docs: complete ai platform demo milestone
This commit is contained in:
hailin
57
docs/development/ai-platform-demo-acceptance.md
Normal file
57
docs/development/ai-platform-demo-acceptance.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# AI 平台配置演示版验收
|
||||
|
||||
更新日期：2026-07-14
|
||||
|
||||
## 验收状态
|
||||
|
||||
| 检查项 | 状态 | 证据 |
|
||||
|---|---|---|
|
||||
| 后端自动化 | 已通过 | 71 项 pytest；Ruff、迁移漂移与 Django system check 通过 |
|
||||
| 全新数据库迁移 | 已通过 | 测试配置下从空库应用全部迁移 |
|
||||
| 前端自动化 | 已通过 | 11 项 Vitest；ESLint、类型检查与生产构建通过 |
|
||||
| 真实模型三步运行 | 待执行 | 凭证仅允许管理员在本地录入，不进入仓库 |
|
||||
|
||||
真实模型三步运行通过前，本演示版只能描述为“实现完成、真实渠道验收待完成”。
|
||||
|
||||
## 前置条件
|
||||
|
||||
- 使用桌面端浏览器和系统管理员账号。
|
||||
- `.env` 已设置独立的 `AI_CREDENTIAL_ENCRYPTION_KEY`。
|
||||
- PostgreSQL、Redis、Django、Celery worker、Celery Beat 和前端均已启动。
|
||||
- 已准备一个允许聊天补全、能够输出 JSON 的 OpenAI-compatible 文本模型渠道。
|
||||
|
||||
## 固定端到端脚本
|
||||
|
||||
1. 管理员登录空白环境，确认 AI 能力菜单包含 Agent、运行记录、Skill 和模型渠道。
|
||||
2. 打开 `#/modelhub/providers`，创建渠道并在密码输入框录入真实凭证；保存后确认页面只显示末四位脱敏值。
|
||||
3. 创建文本模型配置并执行连通测试，等待状态变为“成功”；记录测试 UUID、Token 是否由渠道提供以及耗时。
|
||||
4. 在后端执行 `python manage.py seed_ai_demo --deployment-id <模型配置 ID>`，确认生成三个已发布 Skill 和一个技术支持分析 Agent 草稿。
|
||||
5. 打开 `#/skills`，进入每个 Skill，校验并格式化输入/输出 Schema；编辑草稿后发布。
|
||||
6. 打开 `#/agents`，检查三个有序步骤及其输入映射，按需调整模型参数，并以示例输入运行草稿沙箱。
|
||||
7. 在运行详情确认执行脊柱包含“问题结构化、排查建议、客户回复草稿”，最终输出等于最后一步输出；检查每步版本、输入输出、调用尝试、Token、耗时和配置快照。
|
||||
8. 发布 Agent，再运行已发布版本；确认运行记录不再标记沙箱。
|
||||
9. 修改配置并创建新版本，回看旧运行，确认旧运行仍显示原 Agent、Skill、模型和参数快照。
|
||||
10. 创建一个不具备 `model.manage`、`skill.manage`、`agent.manage`、`agent.use`、`agent.run.view` 的账号，确认入口隐藏，直接请求相应 API 返回 403。
|
||||
11. 查看操作审计，确认存在渠道、模型测试、Skill/Agent 发布回滚、运行启动/结束和取消记录；确认审计中不存在明文密钥、完整 Prompt、完整输入或完整模型响应。
|
||||
|
||||
## 失败路径抽查
|
||||
|
||||
- 将测试渠道凭证替换为无效值，确认鉴权失败立即终止且不重试。
|
||||
- 使用可控兼容服务返回一次 429 或 5xx，确认只退避重试一次。
|
||||
- 让模型首次返回不符合 Schema 的内容，确认出现一次 `structure_repair`；第二次仍无效时运行失败且后续步骤不执行。
|
||||
- 对排队任务执行取消，确认立即变为 `cancelled`；对运行中任务取消，确认当前模型请求返回后不再开始下一步。
|
||||
|
||||
## 验收记录模板
|
||||
|
||||
```text
|
||||
日期：
|
||||
执行人：
|
||||
渠道名称 / 模型名：
|
||||
模型测试 UUID：
|
||||
草稿运行 UUID：
|
||||
发布运行 UUID：
|
||||
旧版本快照检查：通过 / 不通过
|
||||
权限与审计检查：通过 / 不通过
|
||||
结论：通过 / 不通过
|
||||
备注（禁止粘贴密钥和完整敏感输入）：
|
||||
```
|
||||
@@ -8,12 +8,27 @@
|
||||
|
||||
## First Run
|
||||
|
||||
```bash
|
||||
copy .env.example .env
|
||||
```powershell
|
||||
Copy-Item .env.example .env
|
||||
python -c "import base64,secrets; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())"
|
||||
```
|
||||
|
||||
将输出写入 `.env` 的 `AI_CREDENTIAL_ENCRYPTION_KEY`。该值缺失时，系统会拒绝保存模型渠道凭证；已经保存凭证后不要随意更换主密钥。
|
||||
|
||||
完整应用（PostgreSQL、Redis、MinIO、Django、Celery worker、Celery Beat、React）：
|
||||
|
||||
```powershell
|
||||
cd infra
|
||||
docker compose --env-file ../.env up --build
|
||||
```
|
||||
|
||||
只启动本地基础设施、在宿主机运行前后端时：
|
||||
|
||||
```powershell
|
||||
cd infra
|
||||
docker compose -f docker-compose.local.yml --env-file ../.env up -d
|
||||
```
|
||||
|
||||
首次启动时，backend 容器会自动等待 PostgreSQL、执行数据库迁移，并初始化企业后台治理数据。
|
||||
|
||||
Backend:
|
||||
@@ -44,10 +59,28 @@ pytest -v
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run test:run
|
||||
npm run lint
|
||||
npm run typecheck
|
||||
npm run build
|
||||
```
|
||||
|
||||
## AI Platform Demo
|
||||
|
||||
1. 使用管理员账号打开 `#/modelhub/providers`，创建 OpenAI-compatible 渠道和文本模型，并执行异步连通测试。
|
||||
2. 取得模型配置 ID 后创建预置草稿：
|
||||
|
||||
```powershell
|
||||
cd backend
|
||||
python manage.py seed_ai_demo --deployment-id 1
|
||||
```
|
||||
|
||||
3. 在 `#/skills` 检查、编辑并发布三个 Skill。
|
||||
4. 在 `#/agents` 编辑技术支持分析 Agent 的模型、步骤和输入映射，先运行草稿沙箱，再发布并运行正式版本。
|
||||
5. 在 `#/agent-runs` 查看执行脊柱、每步输入输出、调用尝试、Token、耗时和配置快照。
|
||||
|
||||
完整验收步骤见 [AI 平台配置演示版验收](ai-platform-demo-acceptance.md)。
|
||||
|
||||
## Stage 1 API Smoke Tests
|
||||
|
||||
- Tickets: `GET http://localhost:8000/api/tickets`
|
||||
|
||||
@@ -490,17 +490,16 @@ AI 不单独占据主要工作流：建单辅助出现在创建工单页，支
|
||||
|
||||
## 16. 立即执行的下一迭代
|
||||
|
||||
下一迭代先完成 Phase 0，再实施研发管理员使用的 AI 平台配置演示里程碑。该演示只包含模型、Agent 和 Skill，不启动 MCP，也不计为业务闭环完成。
|
||||
当前迭代已完成 AI 平台配置演示版的代码与自动化检查，正在等待管理员在本地提供真实渠道凭证并执行固定端到端验收。该演示只包含模型、Agent 和 Skill，不启动 MCP，也不计为业务闭环完成。
|
||||
|
||||
建议任务顺序：
|
||||
当前收尾与下一阶段任务顺序：
|
||||
|
||||
1. 将当前工作树中的产品概念实验、依赖升级和文档删除整理成可审查的变更集。
|
||||
2. 建立 `docs/product/capability-status.md`，逐项标注真实、演示、缺失和债务。
|
||||
3. 写出 `TicketResolution`、`AgentArtifact`、知识版本和引用快照的数据决策记录。
|
||||
4. 禁止新增代码读取或写入 `Ticket.ai_solution`，设计兼容迁移。
|
||||
5. 为工单创建、状态流转、方案采纳和知识检索补最小跨端回归。
|
||||
6. 固化全新数据库迁移、后端测试、前端测试/类型检查/Lint/构建命令。
|
||||
7. 完成 AI 平台配置演示里程碑后，更新能力状态并编写 Phase 1 可信建单闭环的实施计划。
|
||||
1. 使用本地真实凭证执行 AI 平台固定端到端验收，记录渠道、模型和运行编号，不记录密钥。
|
||||
2. 验证无 AI 权限账号的菜单隐藏、后端拒绝和审计脱敏。
|
||||
3. 真实验收通过后关闭 Demo Milestone，并为 Phase 1 编写“可信建单闭环设计”。
|
||||
4. 写出 `TicketResolution`、`AgentArtifact`、知识版本和引用快照的数据决策记录。
|
||||
5. 禁止新增代码读取或写入 `Ticket.ai_solution`，设计兼容迁移。
|
||||
6. 为工单创建、状态流转、方案采纳和知识检索补最小跨端回归。
|
||||
|
||||
AI 平台配置演示只验证真实运行底座，不建设通用 Agent 平台。其后下一份实施文档必须是“可信建单闭环设计”。
|
||||
|
||||
|
||||
@@ -16,26 +16,26 @@
|
||||
| 领域 | 能力 | 状态 | 说明 |
|
||||
|---|---|---|---|
|
||||
| 企业治理 | 登录、用户、用户组、角色、菜单权限 | 真实 | Django 权限与菜单 API 已实现 |
|
||||
| 企业治理 | 操作审计 | 真实 | 已覆盖部分治理和工单操作，AI 审计待补 |
|
||||
| 企业治理 | 操作审计 | 真实 | 已覆盖治理、工单以及 AI 渠道、版本和运行操作；敏感运行正文不进入普通审计 |
|
||||
| 工单 | 创建、查询、编辑、分类状态流转、评论、导出 | 真实 | 后端与前端均使用真实 API |
|
||||
| 工单 | 附件 | 债务 | 当前仅记录附件元数据和存储路径，尚无真实对象上传 |
|
||||
| 工单 | AI 建议 | 债务 | `Ticket.ai_solution` 位于业务主表，后续停止新增依赖 |
|
||||
| 解决方案 | 维护、关联、采纳并关闭工单 | 真实 | 已有 API、事件和使用次数统计 |
|
||||
| 知识 | 知识库、条目、文档文本、切片和检索 | 真实 | 基础 CRUD 与检索 API 可运行 |
|
||||
| 知识 | 向量检索 | 演示 | 使用 JSON 哈希向量和应用内排序，不是 pgvector/真实 Embedding |
|
||||
| AI 平台 | 模型渠道和真实模型测试 | 缺失 | 本次演示里程碑实施 |
|
||||
| AI 平台 | Skill 草稿、发布、Schema 和回滚 | 缺失 | 本次演示里程碑实施 |
|
||||
| AI 平台 | Agent 版本、有序执行和运行轨迹 | 缺失 | 本次演示里程碑实施 |
|
||||
| AI 平台 | 模型渠道和真实模型测试 | 真实 | OpenAI-compatible 适配器、凭证加密/脱敏、异步测试和一次瞬时重试已实现；真实渠道凭证验收待本地执行 |
|
||||
| AI 平台 | Skill 草稿、发布、Schema 和回滚 | 真实 | 受限模板、JSON Schema、不可变发布版本、克隆草稿和按版本回滚已实现 |
|
||||
| AI 平台 | Agent 版本、有序执行和运行轨迹 | 真实 | 草稿沙箱、发布校验、Celery 有序执行、失败终止、结构修复、取消、快照和运行详情已实现 |
|
||||
| AI 平台 | MCP | 缺失 | 不在本次演示范围 |
|
||||
| 前端 | 工单工作台概念方案 | 演示 | 保留在 `/concept` 设计实验室，不计为真实功能 |
|
||||
| 部署 | PostgreSQL、Redis、MinIO 本地基础设施 | 真实 | `infra/docker-compose.local.yml` |
|
||||
| 部署 | Celery worker | 债务 | 配置存在但尚无真实任务，本次演示里程碑补齐 |
|
||||
| 部署 | Celery worker 与 Beat | 真实 | 模型测试、Agent 运行与每日留存清理使用 Celery；本地完整编排包含 Redis worker 和 Beat |
|
||||
|
||||
## 当前质量基线
|
||||
|
||||
- 后端测试：43 项通过。
|
||||
- 前端测试：6 项通过。
|
||||
- 前端 TypeScript 类型检查和生产构建通过。
|
||||
- 前端生产包存在体积告警，后续管理页面接入时需要按路由拆分评估。
|
||||
- 后端测试：71 项通过；Ruff、迁移检查、Django system check 和全新数据库迁移通过。
|
||||
- 前端测试：11 项通过；ESLint、TypeScript 类型检查和生产构建通过。
|
||||
- 前端生产入口包约 626 KB，存在 Vite 体积告警；后续按路由懒加载拆包。
|
||||
- 真实模型渠道的三步端到端脚本尚未执行，因为凭证必须由管理员在本地提供；在该步骤通过前，不声明演示里程碑验收完成。
|
||||
|
||||
能力状态只依据已验证代码更新。页面存在、类型定义存在或 Mock 可交互，不视为真实能力。
|
||||
|
||||
Reference in New Issue
Block a user