diff --git a/.env.example b/.env.example index 294d96f..fa30f57 100644 --- a/.env.example +++ b/.env.example @@ -15,7 +15,7 @@ POSTGRES_PORT=5432 CELERY_BROKER_URL=redis://redis:6379/0 CELERY_RESULT_BACKEND=redis://redis:6379/1 -AI_CREDENTIAL_ENCRYPTION_KEY=t8XuQv9e8WDoFv7RXT4-zdw1hQChGFKtr7E6ccRZAzU= +AI_CREDENTIAL_ENCRYPTION_KEY= AI_RUN_RETENTION_DAYS=90 MINIO_ROOT_USER=minio diff --git a/README.md b/README.md index e56acbf..ff12464 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ The product centers on support tickets and business knowledge, with configurable ## Current Status -Active implementation. The project has a runnable Django + React baseline with enterprise governance, shadcn-based frontend foundation, Docker Compose local startup, category-driven ticket workflows, reusable solution adoption for fast ticket closure, and a knowledge base and retrieval baseline. +Active implementation. The project has a runnable Django + React baseline with enterprise governance, ticket and knowledge workflows, plus an administrator-facing AI configuration demo: encrypted OpenAI-compatible model channels, versioned Skills and Agents, Celery execution, cancellation, retention, and structured run traces. A real-provider end-to-end acceptance still requires a locally supplied credential. Key docs: @@ -14,6 +14,7 @@ Key docs: - [Capability status](docs/product/capability-status.md) - [Design discussion log](docs/communication/2026-06-30-ai-ticket-platform-discussion-log.md) - [Local setup](docs/development/local-setup.md) +- [AI platform demo acceptance](docs/development/ai-platform-demo-acceptance.md) - [Frontend design system](docs/frontend/design-system.md) ## Target Stack diff --git a/docs/development/ai-platform-demo-acceptance.md b/docs/development/ai-platform-demo-acceptance.md new file mode 100644 index 0000000..4b265a4 --- /dev/null +++ b/docs/development/ai-platform-demo-acceptance.md @@ -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： +旧版本快照检查：通过 / 不通过 +权限与审计检查：通过 / 不通过 +结论：通过 / 不通过 +备注（禁止粘贴密钥和完整敏感输入）： +``` diff --git a/docs/development/local-setup.md b/docs/development/local-setup.md index d2a40ba..637f5a1 100644 --- a/docs/development/local-setup.md +++ b/docs/development/local-setup.md @@ -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` diff --git a/docs/product/blueprint.md b/docs/product/blueprint.md index 90ae3ef..7480e34 100644 --- a/docs/product/blueprint.md +++ b/docs/product/blueprint.md @@ -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 平台。其后下一份实施文档必须是“可信建单闭环设计”。 diff --git a/docs/product/capability-status.md b/docs/product/capability-status.md index 44ef539..2a83f7e 100644 --- a/docs/product/capability-status.md +++ b/docs/product/capability-status.md @@ -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 可交互，不视为真实能力。