docs: complete ai platform demo milestone

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：
+旧版本快照检查：通过 / 不通过
+权限与审计检查：通过 / 不通过
+结论：通过 / 不通过
+备注（禁止粘贴密钥和完整敏感输入）：
+```

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`