734 lines
35 KiB
Markdown
734 lines
35 KiB
Markdown
# Plan: Admin Console — Enterprise Department-Scoped Management
|
||
|
||
**Date**: 2026-06-21
|
||
**Status**: completed
|
||
**Type**: feat
|
||
**Origin**: `docs/brainstorms/2026-06-21-admin-console-requirements.md`
|
||
**Branch**: `feat/admin-console`
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
为 Fischer AgentKit 构建统一企业管理端，嵌入主应用 `/admin` 路由组。核心模型：单企业部署 + 部门级权限隔离 + 能力按部门绑定 + 用户多部门归属（权限并集）。MVP 覆盖 4 个领域：部门与用户管理、LLM 配置管理、Skill 与 KB 管理、用量仪表盘与配额。Web UI + CLI 双通道共享 service 层。
|
||
|
||
## Problem Frame
|
||
|
||
当前 AgentKit 没有统一管理端：admin 端点只有 4 个（session 管理），无 user CRUD；LLM 配置只在 `agentkit.yaml`；KB/Skill 无部门隔离；用量不分用户。管理工作流是"零散脚本不成体系"。
|
||
|
||
实际场景：单企业部署，按部门（人事/研发/财务）划分权限，部门绑定专属 skill/KB/工具，用户可多部门（权限并集）。
|
||
|
||
## Requirements (from origin doc)
|
||
|
||
- **R1**: 部门 CRUD + 部门能力绑定（skill/KB/工具权限/LLM 配额）
|
||
- **R2**: 用户 CRUD + 多部门归属（`user_departments` 多对多）+ 密码重置 + 禁用/启用
|
||
- **R3**: LLM 配置运行时管理（Provider/Model/API Key CRUD + fallback 链 + 按部门配额）
|
||
- **R4**: Skill 启停/编辑/导入 + 按部门绑定
|
||
- **R5**: KB 文档 CRUD + 按部门隔离
|
||
- **R6**: 用量仪表盘（按部门/用户/时间）+ 配额硬拒绝（429）
|
||
- **R7**: CLI `agentkit admin <domain> <action>` 镜像 Web UI
|
||
- **R8**: 部门隔离安全测试（人事部用户无法访问研发部资源，除非同时属于两个部门）
|
||
- **SC1**: 超管可在 Web UI 或 CLI 完成全部管理操作，无需手动编辑 YAML 或操作数据库
|
||
- **SC2**: 部门隔离通过安全测试
|
||
- **SC3**: LLM 配置运行时修改立即生效
|
||
- **SC4**: 用量仪表盘数据延迟 < 1 分钟
|
||
- **SC5**: 配额超限返回 429
|
||
- **SC6**: CLI 与 Web UI 操作结果一致
|
||
|
||
## Key Technical Decisions
|
||
|
||
### KTD1: 角色模型简化为两级（MVP）
|
||
|
||
**决策**：MVP 只有超级管理员（admin）和普通用户（member）两种角色，不实现部门管理员。
|
||
|
||
**理由**：用户明确选择"MVP 只有超管和普通用户"。部门管理员涉及跨部门权限委托、本部门资源管理边界等复杂逻辑，放到第二期。
|
||
|
||
**影响**：现有 `permissions.py` 的 3 级 RBAC（member/operator/admin）保持不变，`operator` 角色保留但 MVP 不主动使用。所有 admin 端点用现有 `_require_admin`（`USER_MANAGE` 权限）守卫。
|
||
|
||
### KTD2: 部门隔离用 `department_id` 列 + `user_departments` 多对多表
|
||
|
||
**决策**：
|
||
- 新增 `departments` 表（id, name, description, is_active, created_at）
|
||
- 新增 `user_departments` 多对多表（user_id, department_id, created_at）
|
||
- 资源表（skills 绑定、kb_documents、llm_usage）加 `department_id` 列（NULL 表示全局共享）
|
||
- `DepartmentContextMiddleware` 从 JWT 读取 user_id，查询 `user_departments`，注入 `request.state.department_ids`（列表）
|
||
- Repository 层强制 `WHERE department_id IN (?, ?, NULL)` 过滤（NULL 表示全局资源，所有部门可见）
|
||
|
||
**理由**：用户明确选择"共享数据库 + department_id 列"。多对多表支持用户多部门归属。NULL `department_id` 表示全局共享资源（如默认 LLM 配置），避免每个部门都重复配置。
|
||
|
||
**风险**：middleware 完整性是关键——任何遗漏 `department_id` 过滤的查询都是数据泄露。通过 repository 层强制参数缓解，但需要安全测试覆盖（R8）。
|
||
|
||
### KTD3: LLM 配置保持 YAML + 写回文件（MVP）
|
||
|
||
**决策**：LLM 配置继续以 `agentkit.yaml` 为权威源。运行时修改通过 `PUT /settings/llm` 写回 YAML 文件，依赖现有 `ServerConfig.watch_config()` 文件监听触发热重载。
|
||
|
||
**理由**：用户明确选择"保持 YAML + 写回文件"。完全迁移到数据库工作量大，且现有文件监听热重载机制已可用。
|
||
|
||
**影响**：
|
||
- 不新增 `llm_providers` / `llm_models` / `llm_api_keys` 数据库表
|
||
- 按部门配额存储在数据库（`department_quotas` 表），不存 YAML
|
||
- API Key 在 YAML 中存储（现有方式），按部门配额在 DB 中
|
||
|
||
**风险**：并发修改 YAML 文件可能冲突。MVP 用文件锁（`fcntl.flock`）缓解，第二期考虑迁移到 DB。
|
||
|
||
### KTD4: 用量跟踪加 `user_id` + `department_id` 字段
|
||
|
||
**决策**：
|
||
- 修改 `UsageRecord` dataclass，新增 `user_id` 和 `department_id` 字段
|
||
- 修改 `InMemoryUsageStore` 和 `RedisUsageStore`，存储和查询时包含新字段
|
||
- LLM Gateway 调用时，从请求上下文获取 `user_id` 和 `department_id`，传入 `UsageTracker`
|
||
- 新增 `GET /admin/usage` 端点，按部门/用户/时间维度聚合查询
|
||
|
||
**理由**：当前 `UsageRecord` 只有 `agent_name`，无法按用户/部门统计。必须加字段才能满足 R6。
|
||
|
||
**影响**：`UsageRecord` 是 dataclass，加字段向后兼容（旧记录的 `user_id`/`department_id` 为 None）。Redis Hash 结构需要扩展 key 包含 `user_id` 和 `department_id`。
|
||
|
||
### KTD5: CLI/Web 共享 service 层
|
||
|
||
**决策**：所有管理操作封装在 `src/agentkit/server/admin/` 下的 service 模块（如 `user_service.py`、`department_service.py`、`llm_config_service.py`）。Web UI 路由和 CLI 命令都调用这些 service。
|
||
|
||
**理由**：用户明确要求"CLI/Web 一致性"。共享 service 层避免双份业务逻辑。
|
||
|
||
**影响**：CLI 需要通过 HTTP 调用 server（`agentkit admin` 命令实际是调用 `/api/v1/admin/*` 端点），而不是直接操作数据库。这保证了一致性，但要求 CLI 有 server URL 配置。
|
||
|
||
### KTD6: 前端 `AdminLayout` 独立路由树
|
||
|
||
**决策**：前端新增 `AdminLayout.vue`（左侧导航 + 内容区），所有 admin 页面作为子路由。路由结构：
|
||
```
|
||
/admin → AdminLayout
|
||
/admin/dashboard → AdminDashboard（概览）
|
||
/admin/departments → DepartmentsView（部门管理）
|
||
/admin/users → UsersView（用户管理，扩展现有）
|
||
/admin/llm → LlmConfigView（LLM 配置）
|
||
/admin/skills → SkillsView（Skill 管理）
|
||
/admin/kb → KbManagementView（KB 管理）
|
||
/admin/usage → UsageDashboardView（用量仪表盘）
|
||
```
|
||
|
||
**理由**：独立路由树便于未来拆分到独立前端应用。左侧导航统一入口，解决"散落各处"问题。
|
||
|
||
## High-Level Technical Design
|
||
|
||
### 数据模型 ERD
|
||
|
||
```mermaid
|
||
erDiagram
|
||
departments ||--o{ user_departments : has
|
||
users ||--o{ user_departments : belongs_to
|
||
departments ||--o{ department_skill_bindings : binds
|
||
skills ||--o{ department_skill_bindings : bound_to
|
||
departments ||--o{ department_kb_bindings : binds
|
||
kb_sources ||--o{ department_kb_bindings : bound_to
|
||
departments ||--o{ department_quotas : has
|
||
users ||--o{ llm_usage : generates
|
||
departments ||--o{ llm_usage : belongs_to
|
||
|
||
departments {
|
||
string id PK
|
||
string name
|
||
string description
|
||
bool is_active
|
||
datetime created_at
|
||
}
|
||
user_departments {
|
||
string user_id FK
|
||
string department_id FK
|
||
datetime created_at
|
||
}
|
||
department_skill_bindings {
|
||
string id PK
|
||
string department_id FK
|
||
string skill_name
|
||
datetime created_at
|
||
}
|
||
department_kb_bindings {
|
||
string id PK
|
||
string department_id FK
|
||
string kb_source_id
|
||
datetime created_at
|
||
}
|
||
department_quotas {
|
||
string id PK
|
||
string department_id FK
|
||
string quota_type
|
||
string limit_value
|
||
string period
|
||
datetime updated_at
|
||
}
|
||
llm_usage {
|
||
string id PK
|
||
string user_id FK
|
||
string department_id FK
|
||
string model
|
||
int prompt_tokens
|
||
int completion_tokens
|
||
int total_tokens
|
||
float cost
|
||
datetime timestamp
|
||
}
|
||
```
|
||
|
||
### 请求隔离流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client
|
||
participant AuthMiddleware
|
||
participant DepartmentMiddleware
|
||
participant Route
|
||
participant Service
|
||
participant Repository
|
||
|
||
Client->>AuthMiddleware: Request + JWT
|
||
AuthMiddleware->>AuthMiddleware: Verify JWT, extract user_id
|
||
AuthMiddleware->>DepartmentMiddleware: request.user_id
|
||
DepartmentMiddleware->>DepartmentMiddleware: Query user_departments
|
||
DepartmentMiddleware->>DepartmentMiddleware: Set request.state.department_ids
|
||
DepartmentMiddleware->>Route: Forward with department context
|
||
Route->>Service: Call service method
|
||
Service->>Repository: Pass department_ids
|
||
Repository->>Repository: WHERE department_id IN (?, ?, NULL)
|
||
Repository-->>Service: Filtered results
|
||
Service-->>Route: Response
|
||
Route-->>Client: Response
|
||
```
|
||
|
||
## Implementation Units
|
||
|
||
### U1. 数据库 schema 扩展——部门表 + 多对多 + 资源表 department_id
|
||
|
||
**Goal**: 新增 `departments`、`user_departments`、`department_skill_bindings`、`department_kb_bindings`、`department_quotas` 表，并为 `llm_usage` 加 `user_id`/`department_id` 字段。
|
||
|
||
**Requirements**: R1, R2, R4, R5, R6
|
||
|
||
**Dependencies**: 无（基础单元）
|
||
|
||
**Files**:
|
||
- `src/agentkit/server/auth/models.py` — 新增表 DDL + ORM 模型，bump `_SCHEMA_VERSION` 到 3
|
||
- `src/agentkit/server/admin/__init__.py` — 新建 admin 模块
|
||
- `src/agentkit/server/admin/models.py` — admin 相关 Pydantic 模型（Department, UserDepartment, etc.）
|
||
- `tests/unit/admin/test_models.py` — 表创建 + CRUD 测试
|
||
|
||
**Approach**:
|
||
- 在 `models.py` 的 `_SCHEMA_SQL` 中追加 5 个新表的 CREATE TABLE IF NOT EXISTS
|
||
- 新增 `_migrate_v2_to_v3()` 迁移函数，gated on `auth_meta` marker `schema_v3_departments`
|
||
- `departments` 表：id (UUID), name (UNIQUE), description, is_active, created_at
|
||
- `user_departments` 表：user_id, department_id, created_at, PRIMARY KEY (user_id, department_id)
|
||
- `department_skill_bindings` 表：id, department_id, skill_name, created_at, UNIQUE (department_id, skill_name)
|
||
- `department_kb_bindings` 表：id, department_id, kb_source_id, created_at, UNIQUE (department_id, kb_source_id)
|
||
- `department_quotas` 表：id, department_id, quota_type (token_limit/cost_limit/model_whitelist), limit_value (JSON), period (daily/monthly), updated_at
|
||
- `llm_usage` 不是 SQL 表（是 Redis），所以 `user_id`/`department_id` 加在 `UsageRecord` dataclass 上（见 U8）
|
||
|
||
**Patterns to follow**: 现有 `models.py` 的 `_SCHEMA_SQL` + `_migrate_v2_to_v3` 模式（参考 `_backfill_user_sessions`）
|
||
|
||
**Test scenarios**:
|
||
- Happy path: `init_auth_db()` 创建新表，`auth_meta` 记录 schema_v3_departments
|
||
- Edge case: 重复调用 `init_auth_db()` 不报错（幂等）
|
||
- Edge case: 已有 v2 数据库升级到 v3，新表创建成功，现有数据不丢失
|
||
- Integration: `departments` 表插入 + 查询，`user_departments` 多对多关系正确
|
||
|
||
**Verification**: `pytest tests/unit/admin/test_models.py -v` 通过；手动检查 `data/auth.db` 新表存在
|
||
|
||
---
|
||
|
||
### U2. 部门 CRUD service + API 端点
|
||
|
||
**Goal**: 实现部门的创建、列表、编辑、禁用/启用、删除，以及部门能力绑定（skill/KB）管理。
|
||
|
||
**Requirements**: R1, R4, R5
|
||
|
||
**Dependencies**: U1
|
||
|
||
**Files**:
|
||
- `src/agentkit/server/admin/department_service.py` — DepartmentService 类（CRUD + 能力绑定）
|
||
- `src/agentkit/server/routes/admin.py` — 新建独立 admin_router 模块（从 auth.py 迁出 session 端点 + 新增 department 端点）
|
||
- `src/agentkit/server/app.py` — 挂载新 admin_router
|
||
- `tests/unit/admin/test_department_service.py` — service 单元测试
|
||
- `tests/integration/admin/test_department_routes.py` — API 集成测试
|
||
|
||
**Approach**:
|
||
- `DepartmentService` 方法：`create_department`, `list_departments`, `get_department`, `update_department`, `disable_department`, `delete_department`, `bind_skill`, `unbind_skill`, `list_department_skills`, `bind_kb`, `unbind_kb`, `list_department_kbs`
|
||
- 删除部门时检查是否有用户归属，有则拒绝（或强制 cascade 删除 user_departments）
|
||
- 禁用部门时（`is_active=0`），该部门用户仍可登录但无法访问部门资源
|
||
- API 端点：
|
||
- `POST /api/v1/admin/departments` — 创建
|
||
- `GET /api/v1/admin/departments` — 列表
|
||
- `GET /api/v1/admin/departments/{id}` — 详情
|
||
- `PATCH /api/v1/admin/departments/{id}` — 编辑
|
||
- `DELETE /api/v1/admin/departments/{id}` — 删除
|
||
- `POST /api/v1/admin/departments/{id}/skills/{name}` — 绑定 skill
|
||
- `DELETE /api/v1/admin/departments/{id}/skills/{name}` — 解绑 skill
|
||
- `POST /api/v1/admin/departments/{id}/kb/{source_id}` — 绑定 KB
|
||
- `DELETE /api/v1/admin/departments/{id}/kb/{source_id}` — 解绑 KB
|
||
- 所有端点用 `_require_admin` 守卫
|
||
|
||
**Patterns to follow**: `kb_management.py` 的 APIRouter + Pydantic 模型 + Depends 模式
|
||
|
||
**Test scenarios**:
|
||
- Happy path: 创建部门 → 列表返回 → 编辑名称 → 禁用 → 启用 → 删除
|
||
- Happy path: 绑定 skill → 列表返回绑定的 skill → 解绑
|
||
- Edge case: 创建重名部门 → 409 Conflict
|
||
- Edge case: 删除有用户归属的部门 → 400 Bad Request
|
||
- Error path: 非管理员访问 → 403
|
||
- Error path: 不存在的部门 ID → 404
|
||
- Integration: 部门禁用后，该部门用户访问部门资源 → 403
|
||
|
||
**Verification**: `pytest tests/unit/admin/test_department_service.py tests/integration/admin/test_department_routes.py -v` 通过
|
||
|
||
---
|
||
|
||
### U3. 用户 CRUD service + API 端点 + 密码重置
|
||
|
||
**Goal**: 实现用户创建、列表、编辑、禁用/启用、删除、密码重置、多部门归属管理。
|
||
|
||
**Requirements**: R2
|
||
|
||
**Dependencies**: U1, U2
|
||
|
||
**Files**:
|
||
- `src/agentkit/server/admin/user_service.py` — UserService 类
|
||
- `src/agentkit/server/routes/admin.py` — 新增 user 端点（扩展 U2 的 admin_router）
|
||
- `src/agentkit/server/auth/providers/local.py` — 新增 `create_user` 方法
|
||
- `tests/unit/admin/test_user_service.py`
|
||
- `tests/integration/admin/test_user_routes.py`
|
||
|
||
**Approach**:
|
||
- `LocalAuthProvider.create_user(username, email, password, role)` — bcrypt hash + INSERT INTO users
|
||
- `UserService` 方法：`create_user`, `list_users`, `get_user`, `update_user`, `disable_user`, `enable_user`, `delete_user`, `reset_password`, `assign_department`, `remove_department`, `list_user_departments`
|
||
- API 端点：
|
||
- `POST /api/v1/admin/users` — 创建用户
|
||
- `GET /api/v1/admin/users` — 列表（支持 department_id 过滤）
|
||
- `GET /api/v1/admin/users/{id}` — 详情（含部门归属）
|
||
- `PATCH /api/v1/admin/users/{id}` — 编辑（role, is_active, is_terminal_authorized）
|
||
- `DELETE /api/v1/admin/users/{id}` — 删除（软删除：is_active=0）
|
||
- `POST /api/v1/admin/users/{id}/reset-password` — 重置密码
|
||
- `POST /api/v1/admin/users/{id}/departments/{dept_id}` — 分配部门
|
||
- `DELETE /api/v1/admin/users/{id}/departments/{dept_id}` — 移除部门归属
|
||
- 创建用户时可选指定部门列表
|
||
- 密码重置用 bcrypt hash 新密码，更新 `password_hash`，并 revoke 该用户所有会话（`revoke_all_for_user`）
|
||
|
||
**Patterns to follow**: 现有 `auth.py` 的 `_resolve_db_path` + `aiosqlite` 模式
|
||
|
||
**Test scenarios**:
|
||
- Happy path: 创建用户 → 列表返回 → 分配部门 → 用户详情含部门 → 重置密码 → 旧会话失效
|
||
- Happy path: 用户多部门归属 → 两个部门都返回该用户
|
||
- Edge case: 创建重名用户 → 409
|
||
- Edge case: 删除自己 → 400
|
||
- Edge case: 移除用户最后一个部门 → 允许（用户变为无部门全局用户）
|
||
- Error path: 非管理员访问 → 403
|
||
- Error path: 重置密码后旧 token 仍可用 → 失败（会话已 revoke）
|
||
- Integration: 创建用户后用新用户登录 → 成功
|
||
|
||
**Verification**: `pytest tests/unit/admin/test_user_service.py tests/integration/admin/test_user_routes.py -v` 通过
|
||
|
||
---
|
||
|
||
### U4. DepartmentContextMiddleware + repository 层隔离
|
||
|
||
**Goal**: 实现请求级别的部门上下文注入，确保所有资源查询按部门过滤。
|
||
|
||
**Requirements**: R8, SC2
|
||
|
||
**Dependencies**: U1, U2, U3
|
||
|
||
**Files**:
|
||
- `src/agentkit/server/admin/middleware.py` — DepartmentContextMiddleware
|
||
- `src/agentkit/server/admin/context.py` — DepartmentContext dataclass + get_department_context() 依赖
|
||
- `src/agentkit/server/app.py` — 注册 middleware（在 AuthMiddleware 之后）
|
||
- `src/agentkit/server/routes/skills.py` — 修改 skill 查询，按 department_ids 过滤
|
||
- `src/agentkit/server/routes/kb_management.py` — 修改 KB 查询，按 department_ids 过滤
|
||
- `tests/integration/admin/test_department_isolation.py` — 隔离安全测试
|
||
|
||
**Approach**:
|
||
- `DepartmentContextMiddleware`：
|
||
1. 从 `request.state.user` 获取 user_id（AuthMiddleware 已注入）
|
||
2. 查询 `user_departments` 获取 department_ids
|
||
3. 注入 `request.state.department_ids`（列表，可能为空表示全局用户）
|
||
4. 白名单路径（/auth/*, /docs, /health）跳过
|
||
- `get_department_context()` 依赖：从 request.state 读取 department_ids，返回 DepartmentContext
|
||
- Skill 查询修改：`GET /skills` 返回全局 skill + 用户部门绑定的 skill
|
||
- KB 查询修改：`GET /kb-management/sources` 返回全局 KB + 用户部门绑定的 KB
|
||
- Admin 端点（`/admin/*`）跳过部门过滤（超管可看所有）
|
||
|
||
**Patterns to follow**: 现有 `AuthMiddleware` 的 BaseHTTPMiddleware 模式
|
||
|
||
**Test scenarios**:
|
||
- Happy path: 用户属于部门 A → GET /skills 返回全局 skill + 部门 A 绑定的 skill
|
||
- Happy path: 用户属于部门 A 和 B → GET /skills 返回全局 + A + B 的 skill
|
||
- Happy path: 用户无部门 → GET /skills 只返回全局 skill
|
||
- Security: 用户 A（仅部门 A）访问部门 B 绑定的 skill → 404 或不在列表中
|
||
- Security: 用户 A 尝试通过 API 直接访问部门 B 的 KB 文档 → 403/404
|
||
- Security: Admin 用户访问任意部门资源 → 成功（跳过过滤）
|
||
- Integration: 用户从部门 A 移除后 → 立即无法访问部门 A 的 skill
|
||
|
||
**Verification**: `pytest tests/integration/admin/test_department_isolation.py -v` 通过；安全测试覆盖所有资源类型
|
||
|
||
---
|
||
|
||
### U5. LLM 配置管理端点（YAML 写回 + 按部门配额）
|
||
|
||
**Goal**: 实现 LLM Provider/Model/API Key 的运行时 CRUD，写回 `agentkit.yaml`，支持按部门配额。
|
||
|
||
**Requirements**: R3, SC3
|
||
|
||
**Dependencies**: U1, U2
|
||
|
||
**Files**:
|
||
- `src/agentkit/server/admin/llm_config_service.py` — LlmConfigService 类
|
||
- `src/agentkit/server/routes/admin.py` — 新增 LLM 配置端点
|
||
- `src/agentkit/server/routes/settings.py` — 复用/扩展现有 `GET/PUT /settings/llm`
|
||
- `tests/unit/admin/test_llm_config_service.py`
|
||
- `tests/integration/admin/test_llm_config_routes.py`
|
||
|
||
**Approach**:
|
||
- `LlmConfigService` 方法：
|
||
- `list_providers()`, `get_provider(name)`, `create_provider(name, config)`, `update_provider(name, config)`, `delete_provider(name)`
|
||
- `list_models(provider)`, `add_model(provider, model, config)`, `update_model()`, `delete_model()`
|
||
- `list_api_keys()` — 返回 provider 名 + key 前缀（不返回完整 key）
|
||
- `set_api_key(provider, key)` — 写入 YAML（`${ENV_VAR}` 替换保持）
|
||
- `get_fallbacks()`, `set_fallbacks(model, chain)`
|
||
- `set_department_quota(dept_id, quota_type, limit, period)`, `get_department_quota(dept_id)`
|
||
- 写回 YAML 用 `yaml.dump` + `fcntl.flock` 文件锁
|
||
- 现有 `watch_config()` 监听文件变化触发热重载，无需额外通知
|
||
- API 端点：
|
||
- `GET /api/v1/admin/llm/providers` — 列表
|
||
- `POST /api/v1/admin/llm/providers` — 创建
|
||
- `PATCH /api/v1/admin/llm/providers/{name}` — 编辑
|
||
- `DELETE /api/v1/admin/llm/providers/{name}` — 删除
|
||
- `POST /api/v1/admin/llm/providers/{name}/api-key` — 设置 API Key
|
||
- `GET /api/v1/admin/llm/fallbacks` — fallback 链
|
||
- `PUT /api/v1/admin/llm/fallbacks/{model}` — 设置 fallback
|
||
- `GET /api/v1/admin/departments/{id}/quotas` — 部门配额
|
||
- `PUT /api/v1/admin/departments/{id}/quotas` — 设置配额
|
||
|
||
**Patterns to follow**: 现有 `settings.py` 的 `GET/PUT /settings/llm` 模式
|
||
|
||
**Test scenarios**:
|
||
- Happy path: 添加 provider → YAML 文件更新 → 热重载触发 → 新 provider 可用
|
||
- Happy path: 修改 API Key → YAML 更新 → 旧 key 失效
|
||
- Happy path: 设置 fallback 链 → model A 失败时自动切换到 model B
|
||
- Happy path: 设置部门配额 → 部门用户超限 → 429
|
||
- Edge case: YAML 文件被外部修改 → watch_config 触发重载 → 配置同步
|
||
- Edge case: 并发修改 → 文件锁保护 → 后写者覆盖
|
||
- Error path: 无效 provider 配置 → 400
|
||
- Error path: 删除正在使用的 provider → 400
|
||
|
||
**Verification**: `pytest tests/unit/admin/test_llm_config_service.py tests/integration/admin/test_llm_config_routes.py -v` 通过；手动验证 YAML 修改后热重载
|
||
|
||
---
|
||
|
||
### U6. Skill 与 KB 管理端点（启停 + 部门绑定）
|
||
|
||
**Goal**: 实现 Skill 启停/编辑/导入的 admin 端点，KB 文档管理 admin 端点，按部门绑定。
|
||
|
||
**Requirements**: R4, R5
|
||
|
||
**Dependencies**: U1, U2, U4
|
||
|
||
**Files**:
|
||
- `src/agentkit/server/admin/skill_service.py` — SkillService 类（启停/编辑/导入）
|
||
- `src/agentkit/server/admin/kb_service.py` — KbService 类（文档管理）
|
||
- `src/agentkit/server/routes/admin.py` — 新增 skill/kb 端点
|
||
- `src/agentkit/server/routes/skill_management.py` — 实现 reload 端点（当前是 stub）
|
||
- `tests/unit/admin/test_skill_service.py`
|
||
- `tests/integration/admin/test_skill_kb_routes.py`
|
||
|
||
**Approach**:
|
||
- `SkillService` 方法：`enable_skill(name)`, `disable_skill(name)`, `update_skill_config(name, config)`, `import_skill(yaml_content)`, `reload_skill(name)`
|
||
- 启停通过在 skill registry 中标记 `enabled=False`，查询时过滤
|
||
- `KbService` 方法：`list_documents(department_id)`, `upload_document(file, department_id)`, `delete_document(id)`, `sync_source(id)`, `rebuild_index(id)`
|
||
- KB 文档加 `department_id` 列（在 KB store 中，当前是内存存储，需要持久化或加 metadata）
|
||
- API 端点：
|
||
- `POST /api/v1/admin/skills/{name}/enable` — 启用
|
||
- `POST /api/v1/admin/skills/{name}/disable` — 禁用
|
||
- `PATCH /api/v1/admin/skills/{name}` — 编辑配置
|
||
- `POST /api/v1/admin/skills/import` — YAML 导入
|
||
- `POST /api/v1/admin/skills/{name}/reload` — 重载
|
||
- `GET /api/v1/admin/kb/documents` — 列表（支持 department_id 过滤）
|
||
- `POST /api/v1/admin/kb/documents` — 上传（指定 department_id）
|
||
- `DELETE /api/v1/admin/kb/documents/{id}` — 删除
|
||
- `POST /api/v1/admin/kb/sources/{id}/sync` — 同步
|
||
- `POST /api/v1/admin/kb/sources/{id}/rebuild` — 重建索引
|
||
|
||
**Patterns to follow**: 现有 `skills.py` 的 install/unregister 模式
|
||
|
||
**Test scenarios**:
|
||
- Happy path: 禁用 skill → GET /skills 不返回该 skill → 用户无法使用
|
||
- Happy path: 启用 skill → 恢复可用
|
||
- Happy path: 导入 skill YAML → 注册成功 → 可用
|
||
- Happy path: 上传 KB 文档到部门 A → 部门 A 用户可搜索 → 部门 B 用户不可见
|
||
- Edge case: 禁用不存在的 skill → 404
|
||
- Edge case: 导入无效 YAML → 400
|
||
- Security: 部门 A 用户尝试访问部门 B 的 KB 文档 → 404
|
||
- Integration: 禁用 skill 后，正在使用该 skill 的会话 → 优雅降级或错误提示
|
||
|
||
**Verification**: `pytest tests/unit/admin/test_skill_service.py tests/integration/admin/test_skill_kb_routes.py -v` 通过
|
||
|
||
---
|
||
|
||
### U7. 用量仪表盘 + 配额执行
|
||
|
||
**Goal**: 实现按部门/用户/时间的用量查询，配额检查在 LLM 调用时执行（超限返回 429）。
|
||
|
||
**Requirements**: R6, SC4, SC5
|
||
|
||
**Dependencies**: U1, U2, U5
|
||
|
||
**Files**:
|
||
- `src/agentkit/llm/providers/usage_store.py` — 修改 `UsageRecord` + store 实现
|
||
- `src/agentkit/llm/gateway.py` — 调用时传入 user_id/department_id，调用前检查配额
|
||
- `src/agentkit/server/admin/usage_service.py` — UsageService 类（聚合查询）
|
||
- `src/agentkit/server/admin/quota_service.py` — QuotaService 类（配额检查）
|
||
- `src/agentkit/server/routes/admin.py` — 新增 usage 端点
|
||
- `tests/unit/admin/test_usage_service.py`
|
||
- `tests/unit/admin/test_quota_service.py`
|
||
- `tests/integration/admin/test_usage_routes.py`
|
||
|
||
**Approach**:
|
||
- `UsageRecord` 加 `user_id: str | None`, `department_id: str | None`
|
||
- `RedisUsageStore` Hash key 扩展：`agentkit:usage:{date}:{user_id}:{department_id}`
|
||
- `LLMGateway.complete()` 调用前：
|
||
1. 获取当前 user_id + department_ids
|
||
2. 对每个 department_id 检查配额（token/cost，daily/monthly）
|
||
3. 超限 → raise `QuotaExceededError` → 路由层返回 429
|
||
4. 调用后记录 usage（含 user_id + department_id）
|
||
- `UsageService` 方法：`get_usage_summary(department_id, user_id, start, end)`, `get_usage_timeseries(department_id, user_id, start, end, interval)`, `get_usage_by_model(department_id, user_id, start, end)`, `get_top_users(department_id, limit)`, `export_usage(department_id, format)`
|
||
- API 端点：
|
||
- `GET /api/v1/admin/usage/summary?department_id=&user_id=&start=&end=` — 汇总
|
||
- `GET /api/v1/admin/usage/timeseries?...&interval=hour/day` — 时间序列
|
||
- `GET /api/v1/admin/usage/by-model?...` — 按 model 分桶
|
||
- `GET /api/v1/admin/usage/top-users?department_id=&limit=` — 用户排行
|
||
- `GET /api/v1/admin/usage/export?format=csv/json` — 导出
|
||
|
||
**Patterns to follow**: 现有 `llm.py` 的 `GET /llm/usage` 模式
|
||
|
||
**Test scenarios**:
|
||
- Happy path: 用户调用 LLM → usage 记录含 user_id + department_id
|
||
- Happy path: 查询部门 A 用量 → 返回部门 A 的聚合数据
|
||
- Happy path: 查询用户 X 用量 → 返回用户 X 的数据
|
||
- Happy path: 导出 CSV → 格式正确
|
||
- Quota: 部门 A token 配额 1000 → 第 1001 token → 429
|
||
- Quota: 用户月成本上限 $10 → 第 $11 → 429
|
||
- Quota: 多部门用户，部门 A 超限但部门 B 未超 → 拒绝（取最严约束）
|
||
- Edge case: 无 usage 数据 → 返回空结果
|
||
- Edge case: 跨天查询 → 按天聚合
|
||
- Error path: 非管理员访问 → 403
|
||
|
||
**Verification**: `pytest tests/unit/admin/test_usage_service.py tests/unit/admin/test_quota_service.py tests/integration/admin/test_usage_routes.py -v` 通过
|
||
|
||
---
|
||
|
||
### U8. CLI admin 命令组
|
||
|
||
**Goal**: 实现 `agentkit admin <domain> <action>` 命令组，通过 HTTP 调用 server API。
|
||
|
||
**Requirements**: R7, SC6
|
||
|
||
**Dependencies**: U2, U3, U5, U6, U7
|
||
|
||
**Files**:
|
||
- `src/agentkit/cli/admin.py` — admin Typer sub-app
|
||
- `src/agentkit/cli/main.py` — 注册 admin sub-app
|
||
- `src/agentkit/cli/admin_client.py` — AdminHttpClient（封装 HTTP 调用）
|
||
- `tests/unit/cli/test_admin_commands.py`
|
||
|
||
**Approach**:
|
||
- `AdminHttpClient`：从 `agentkit.yaml` 或环境变量读取 server URL + admin API key
|
||
- 命令结构：
|
||
```
|
||
agentkit admin department list/create/update/delete/bind-skill/unbind-skill/bind-kb/unbind-kb
|
||
agentkit admin user list/create/update/delete/reset-password/assign-department/remove-department
|
||
agentkit admin llm list-providers/add-provider/update-provider/delete-provider/set-api-key/set-fallback/set-quota
|
||
agentkit admin skill list/enable/disable/import/reload
|
||
agentkit admin kb list-documents/upload/delete/sync/rebuild
|
||
agentkit admin usage summary/timeseries/by-model/top-users/export
|
||
```
|
||
- 所有命令输出用 Rich 表格/JSON 格式
|
||
- `--json` 标志输出原始 JSON（便于脚本处理）
|
||
- 认证：用 `agentkit pair` 生成的 API key（已有机制），或 admin 用户名密码登录获取 JWT
|
||
|
||
**Patterns to follow**: 现有 `cli/task.py` 的 Typer sub-app + Rich 输出模式
|
||
|
||
**Test scenarios**:
|
||
- Happy path: `agentkit admin department list` → 返回部门列表（Rich 表格）
|
||
- Happy path: `agentkit admin user create --username alice --email alice@corp.com` → 创建用户
|
||
- Happy path: `agentkit admin llm add-provider --name openai --api-key $KEY` → 添加 provider
|
||
- Happy path: `agentkit admin usage summary --department hr --start 2026-06-01 --end 2026-06-30` → 用量汇总
|
||
- Happy path: `--json` 标志 → 输出有效 JSON
|
||
- Edge case: server 不可达 → 友好错误提示
|
||
- Edge case: API key 无效 → 401 提示
|
||
- Edge case: 创建重名用户 → 显示 409 错误
|
||
|
||
**Verification**: `pytest tests/unit/cli/test_admin_commands.py -v` 通过；手动验证 CLI 与 Web UI 操作结果一致
|
||
|
||
---
|
||
|
||
### U9. 前端 AdminLayout + 管理页面
|
||
|
||
**Goal**: 实现前端管理界面，包括 AdminLayout、7 个管理页面、API 客户端扩展。
|
||
|
||
**Requirements**: SC1, SC6
|
||
|
||
**Dependencies**: U2, U3, U5, U6, U7
|
||
|
||
**Files**:
|
||
- `src/agentkit/server/frontend/src/layouts/AdminLayout.vue` — 左侧导航 + 内容区
|
||
- `src/agentkit/server/frontend/src/views/admin/DashboardView.vue` — 概览
|
||
- `src/agentkit/server/frontend/src/views/admin/DepartmentsView.vue` — 部门管理
|
||
- `src/agentkit/server/frontend/src/views/admin/UsersView.vue` — 扩展现有（加 CRUD）
|
||
- `src/agentkit/server/frontend/src/views/admin/LlmConfigView.vue` — LLM 配置
|
||
- `src/agentkit/server/frontend/src/views/admin/SkillsView.vue` — Skill 管理
|
||
- `src/agentkit/server/frontend/src/views/admin/KbManagementView.vue` — KB 管理
|
||
- `src/agentkit/server/frontend/src/views/admin/UsageDashboardView.vue` — 用量仪表盘
|
||
- `src/agentkit/server/frontend/src/api/admin.ts` — 扩展 AdminApiClient
|
||
- `src/agentkit/server/frontend/src/router/index.ts` — 更新路由结构
|
||
- `src/agentkit/server/frontend/src/components/layout/TopNav.vue` — 更新 admin 入口
|
||
|
||
**Approach**:
|
||
- `AdminLayout`：左侧导航（7 个菜单项）+ 顶部用户信息 + 内容区 `<router-view />`
|
||
- 路由结构改为嵌套：
|
||
```ts
|
||
{
|
||
path: '/admin',
|
||
component: AdminLayout,
|
||
meta: { requiresAdmin: true },
|
||
children: [
|
||
{ path: '', redirect: '/admin/dashboard' },
|
||
{ path: 'dashboard', component: DashboardView },
|
||
{ path: 'departments', component: DepartmentsView },
|
||
{ path: 'users', component: UsersView },
|
||
{ path: 'llm', component: LlmConfigView },
|
||
{ path: 'skills', component: SkillsView },
|
||
{ path: 'kb', component: KbManagementView },
|
||
{ path: 'usage', component: UsageDashboardView },
|
||
]
|
||
}
|
||
```
|
||
- `AdminApiClient` 扩展：department/user/llm/skill/kb/usage 方法
|
||
- 各页面用 Ant Design Vue 组件（Table, Form, Modal, Card, Chart）
|
||
- 用量仪表盘用 ECharts 或 Ant Design Charts
|
||
|
||
**Patterns to follow**: 现有 `UsersView.vue` 的双标签页 + `UserSessionsPanel` 模式
|
||
|
||
**Test scenarios**:
|
||
- Happy path: admin 用户访问 /admin → 重定向到 /admin/dashboard
|
||
- Happy path: 部门管理页 → 创建/编辑/删除部门 → 列表更新
|
||
- Happy path: 用户管理页 → 创建用户 → 分配部门 → 列表更新
|
||
- Happy path: LLM 配置页 → 添加 provider → 列表更新 → 热重载提示
|
||
- Happy path: 用量仪表盘 → 选择部门和时间范围 → 图表显示
|
||
- Edge case: 非管理员访问 /admin → 重定向到 /agent/chat
|
||
- Edge case: 网络错误 → 友好错误提示
|
||
- Edge case: 表单验证错误 → 字段级错误提示
|
||
|
||
**Verification**: `npm run typecheck` 通过；手动验证各页面功能
|
||
|
||
---
|
||
|
||
### U10. 集成测试 + 安全测试
|
||
|
||
**Goal**: 端到端集成测试 + 部门隔离安全测试，验证 SC1-SC6。
|
||
|
||
**Requirements**: R8, SC1-SC6
|
||
|
||
**Dependencies**: U1-U9
|
||
|
||
**Files**:
|
||
- `tests/integration/admin/test_e2e_admin_flow.py` — 端到端流程测试
|
||
- `tests/integration/admin/test_security_isolation.py` — 部门隔离安全测试
|
||
- `tests/integration/admin/test_quota_enforcement.py` — 配额执行测试
|
||
|
||
**Approach**:
|
||
- E2E 流程测试：
|
||
1. 创建部门（人事、研发）
|
||
2. 创建用户并分配部门
|
||
3. 绑定 skill/KB 到部门
|
||
4. 配置 LLM provider + 部门配额
|
||
5. 用普通用户登录 → 验证只能访问所属部门资源
|
||
6. 查看用量仪表盘 → 数据正确
|
||
7. CLI 执行相同操作 → 结果一致
|
||
- 安全测试：
|
||
1. 人事部用户尝试访问研发部 skill → 404
|
||
2. 人事部用户尝试访问研发部 KB 文档 → 404
|
||
3. 人事部用户尝试访问研发部用量 → 403
|
||
4. 用户从部门移除后 → 立即无法访问该部门资源
|
||
5. 部门禁用后 → 该部门用户无法访问部门资源
|
||
6. JWT 篡改 department_ids → middleware 重新查询，不信任 JWT
|
||
- 配额测试：
|
||
1. 设置部门 token 配额 1000
|
||
2. 用户调用 LLM 直到 1000 token
|
||
3. 第 1001 token → 429
|
||
4. 重置配额 → 可继续调用
|
||
|
||
**Test scenarios**: 见上述 Approach
|
||
|
||
**Verification**: `pytest tests/integration/admin/ -v` 通过；安全测试 100% 覆盖
|
||
|
||
---
|
||
|
||
## Scope Boundaries
|
||
|
||
### In Scope
|
||
|
||
- 部门 CRUD + 能力绑定
|
||
- 用户 CRUD + 多部门归属 + 密码重置
|
||
- LLM 配置 YAML 写回 + 按部门配额
|
||
- Skill 启停/编辑/导入 + 部门绑定
|
||
- KB 文档管理 + 部门隔离
|
||
- 用量仪表盘 + 配额硬拒绝
|
||
- CLI admin 命令组
|
||
- 前端 AdminLayout + 7 个管理页面
|
||
- 部门隔离安全测试
|
||
|
||
### Deferred to Follow-Up Work
|
||
|
||
- 部门管理员角色（第二期）
|
||
- LLM 配置迁移到数据库（第二期）
|
||
- 审计日志（第二期）
|
||
- SLA 监控（第二期）
|
||
- SSO/SAML 集成（第二期）
|
||
- 独立管理应用部署（架构已预留，第二期实现）
|
||
- 配额软降级（第二期）
|
||
- 用量告警 Webhook/邮件（第二期，MVP 只做日志）
|
||
|
||
### Outside This Product's Identity
|
||
|
||
- SaaS 多租户（外部多客户、租户计费）
|
||
- 物理隔离的独立数据库
|
||
- 计费系统集成（实际扣款）
|
||
|
||
## Risks & Dependencies
|
||
|
||
### Risks
|
||
|
||
1. **部门隔离 middleware 完整性**（高）—— 任何遗漏 `department_id` 过滤的查询都是数据泄露。缓解：repository 层强制参数 + 安全测试覆盖（U10）。
|
||
2. **LLM 配置 YAML 并发修改**（中）—— 多人同时修改 YAML 可能冲突。缓解：`fcntl.flock` 文件锁。第二期迁移到 DB。
|
||
3. **用量跟踪 Redis Hash key 扩展**（中）—— 修改 key 结构可能影响现有数据。缓解：版本化 key（`agentkit:usage:v2:{date}:{user_id}:{dept_id}`），旧 key 保留。
|
||
4. **KB 内存存储持久化**（中）—— 当前 KB 是内存存储，加 `department_id` 需要持久化或 metadata 扩展。缓解：MVP 用 metadata dict 存储 department_id，第二期迁移到 DB。
|
||
5. **CLI 认证机制**（低）—— CLI 需要 server URL + API key 配置。缓解：复用 `agentkit pair` 机制。
|
||
|
||
### Dependencies
|
||
|
||
- 现有 JWT 认证 + RBAC 权限模型
|
||
- 现有 `agentkit.yaml` 文件监听热重载机制
|
||
- 现有 `agentkit` CLI 框架（Typer）
|
||
- 现有 Ant Design Vue 组件库
|
||
|
||
## Phased Delivery
|
||
|
||
| 批次 | 实施单元 | 交付物 |
|
||
|------|----------|--------|
|
||
| 批次 1 | U1, U2, U3, U4 | 部门与用户管理 + 隔离 middleware |
|
||
| 批次 2 | U5 | LLM 配置管理 |
|
||
| 批次 3 | U6 | Skill 与 KB 管理 |
|
||
| 批次 4 | U7 | 用量仪表盘 + 配额 |
|
||
| 批次 5 | U8, U9, U10 | CLI + 前端 + 集成测试 |
|
||
|
||
每批次独立可交付、可测试、可合并。
|
||
|
||
## Open Questions (Resolved)
|
||
|
||
- ~~KB 内存存储如何加 `department_id`？~~ → **已明确**：MVP 用 metadata dict 存储 department_id，不持久化（重启丢失绑定关系，可接受）。第二期迁移到 SQLite。
|
||
- ~~CLI 认证用 API key 还是用户名密码？~~ → **已明确**：API key，复用 `agentkit pair` 机制。CLI 配置文件存储 server_url + api_key。
|
||
- ~~用量仪表盘图表库选 ECharts 还是 Ant Design Charts？~~ → **已明确**：Ant Design Charts，与现有 UI 一致。
|
||
- ~~部门删除策略：拒绝删除有用户的部门，还是 cascade 删除 user_departments？~~ → **已明确**：拒绝删除，强制管理员先移除用户。
|