841 lines
52 KiB
Markdown
841 lines
52 KiB
Markdown
# Agent 底座开发 TODO
|
||
|
||
> 版本：v1.0
|
||
> 更新日期：2026-09-09
|
||
> 适用对象：底座负责人、业务 Agent 开发人员、编码 Agent、测试和运维人员
|
||
> 规范依据：`AGENTS.md`、`docs/01-通用Agent平台开发设计.md`、`docs/02-数据库建表设计.md`、`docs/03-平台端到端流程文档.md`、`docs/05-接口文档.md`
|
||
|
||
## 一、使用规则
|
||
|
||
- 每个任务开始前，先阅读对应设计文档和本 TODO 的前置依赖。
|
||
- 任务完成后必须补充测试、验收结果和实际修改文件。
|
||
- 未通过当前任务验收，不得开始依赖该任务的后续任务。
|
||
- 不得把未确定项留给编码 Agent 猜测；发现设计缺口必须停止并提交决策。
|
||
- 所有接口变化必须同步 `docs/05-接口文档.md`、OpenAPI 和接口测试。
|
||
- 所有数据库变化必须先对照 `docs/00-新数据库基线设计.md`，确认没有修改已有表名和已有字段定义。
|
||
- 业务 Agent 不得绕过 `AgentFactory`、`BaseAgent`、统一鉴权、记忆、模型、工具、合规、审计和事件流程。
|
||
- 当前业务范围只包括场内基金模拟交易；场外运营必须独立建表、独立接口。
|
||
|
||
## 二、任务状态
|
||
|
||
### 2026-09-09 测试报告修复（当前验收优先于下方历史记录）
|
||
|
||
此前 D9“底座核心已完成”结论撤回：缺少鉴权、Worker 启动和治理接线的端到端证据。
|
||
以下修复以 `docs/06-底座代码测试报告.md` 为问题来源，按项复测后勾选。
|
||
|
||
- [x] P0-1 RBAC、入口、工厂和受理鉴权；补平台管理入口权限。
|
||
证据：`test_agent_authorization.py` 8 项；`test_identity_mysql.py` 真实 MySQL
|
||
有效角色、权限、客户归属、过期撤权、禁用账号及客户端伪造覆盖；41 项单测通过。
|
||
变更：identity_repository/identity_service/authorization_service、Factory/BaseAgent、
|
||
受理和鉴权依赖；05 §4.2 已同步。数据库结构无变更。
|
||
- [x] P0-2 未注册 Agent 受理前拒绝（依 05 返回 404）。
|
||
证据：HTTP 未注册类型不写数据库测试 + 3 项 MySQL 受理/并发/HTTP 回归，共 4 passed。
|
||
修正并发测试断言为“恰好一个成功运行”，防止全部失败也通过。正式注册入口 bootstrap
|
||
与测试注册分离，未接入业务 Agent 不冒充已注册。错误采用 05 的 AGENT_TYPE_NOT_FOUND。
|
||
- [x] P0-3 独立 Worker 入口与真实运行闭环。
|
||
证据：`test_worker_runtime_mysql.py` 3 passed；`python -m app.worker --help` 可执行；
|
||
启动、注册、租约、撤权和验收范围见 `docs/07-测试问题修复记录.md`。新轮询配置已写 .env。
|
||
- [x] P1-1 非法 JWT sub 返回 401。
|
||
证据：test_security.py 11 passed，包含非数字、负数、零、全角数字、超长和溢出，
|
||
有效签名但 sub=abc 的 HTTP 请求为 401 且不调用身份查询。
|
||
- [x] P1-2 配置、记忆、合规治理钩子接线。
|
||
证据：`test_agent_governance.py` 9 项 + `test_governance_mysql.py` 真库召回/禁止词 1 项。
|
||
工厂注入治理协议；发布配置快照、按意图工具交集、客户记忆和已审核禁止词实际生效；
|
||
引用校验、号码脱敏、合规替换、缺失依赖拒绝执行及治理方法覆盖测试通过。
|
||
限制：完整意图模型/工具执行器未完成；未登记工具记录和外部引用拒绝；正则规则失败关闭。
|
||
- [x] P1-3 SSE delta 与结果级恢复。
|
||
证据：test_agent_run_sse.py 6 passed；待完成连接输出提交后的 delta，终态重连用 replace；
|
||
中文/emoji、空正文、唯一事件 ID、未提交不泄露正文及断流恢复均覆盖。05 已同步。
|
||
- [x] P1-4 Controller 数据访问下沉。
|
||
证据：Controller 不再导入 Model/Repository 或操作 Session；架构 AST 检查 + HTTP/SSE
|
||
和真库 Worker 回归共 12 passed；新增 ConversationRepository/ConversationService/
|
||
RunQueryService/ConfigApplicationService，连接依赖移至 api/dependencies。
|
||
- [x] P1-5 公共、管理、运维接口覆盖及 OpenAPI；业务接口不纳入。
|
||
证据：OpenAPI 路由 40 条，覆盖运行、会话、取消、反馈、转人工、记忆、知识、管理资源、
|
||
健康和指标；所有底座写接口使用 ApiTransactionService 幂等回执，管理写接口要求 If-Match，
|
||
配置/模型/工具上限校验集中在 AdminService。接口动态资源按文档资源编号映射；业务域接口仍由组员负责。
|
||
- [x] P2-1 会话实体与澄清轮次。
|
||
`svc_conversation_session` 已按 02 §8.1 新表迁移，ConversationSession/SessionRepository
|
||
提供归属、状态、消息计数和带旧值的澄清轮次更新；未修改既有表。
|
||
- [x] P2-2 JWT 公钥缓存。
|
||
认证依赖使用单例 JwtAuthenticator，公钥只在进程首次请求加载；JWT 轮换需重启/清缓存。
|
||
- [x] P2-3 会话归属并发保护。
|
||
新会话表存在时受理使用用户+session 行锁、状态和 Agent 一致性校验；旧消息归属仍保留兼容兜底。
|
||
- [x] P2-4 废弃 HTTP 文档权威检查。
|
||
`tools/check_authoritative_docs.py` 检查 05 唯一权威文档和历史废弃稿标记。
|
||
- [x] P2-5 分层目录文档对齐。
|
||
代码实际目录以 `app/api/controllers`、`app/api/views`、`app/service`、`app/repository` 为准，
|
||
本次 AST 检查和 docs/07 已按此记录；不移动源码，避免无意义路径破坏。
|
||
- [x] P2-6 表数及 TODO 证据一致性。
|
||
02 文档同步为 51 张（含会话补表和 HTTP 回执表），audit_schema 及 Alembic head 已同步。
|
||
- [x] P2-7 外键与基线字段完整性核对。
|
||
新增表按 02 DDL 建立；既有表以 49 张指纹审计证明字段未变化。外键完整性不通过新增约束
|
||
改写既有表，保留由应用 Repository 约束的历史兼容关系；审计范围和限制见 docs/08。
|
||
|
||
状态只允许使用：
|
||
|
||
- `[ ]` 未开始
|
||
- `[-]` 进行中
|
||
- `[x]` 已完成并通过验收
|
||
- `[!]` 阻塞，必须在任务说明中写明原因和需要的决策
|
||
|
||
任务完成必须同时满足：代码完成、测试通过、文档同步、验收证据已记录。
|
||
|
||
## 三、当前基线
|
||
|
||
### 2026-09-09 业务域接入评估补课
|
||
|
||
- [x] P0-A 模型 Adapter、统一模型生成入口。
|
||
新增 OpenAI-compatible Adapter、env secret_ref 解析、模型失败统一错误、受控 fallback、
|
||
ModelGenerationService 和 BaseAgent.generate_with_model；业务 Agent 不能直连供应商。
|
||
验证：模型 Adapter、密钥不泄露、空路由失败关闭和工厂注入测试通过。真实供应商端点仍需环境配置演练。
|
||
- [x] P0-B ToolRegistry、ToolExecutor 和 BaseAgent 工具入口。
|
||
工具必须只读、声明输入 Schema/权限/角色，按意图白名单执行，失败关闭、超时、脱敏摘要、
|
||
来源引用和独立审计均已实现；工厂统一注入，未注入时拒绝执行。专项工具测试已补。
|
||
- [x] P0-C 公共适当性校验服务和工具入口。
|
||
新增 `SuitabilityService`、严格输入 DTO 和 `suitability_tool_handler`；统一执行 C1-C5/R1-R5
|
||
风险匹配、测评过期、风险揭示/二次确认/双录规则。通过和拒绝决定均写入 `interaction_audit`，
|
||
不修改交易或产品数据，业务 Agent 只能经 ToolExecutor 调用。专项边界、过期、时区和审计测试通过。
|
||
- [x] P1 意图分类公共服务。
|
||
新增 `IntentClassifier`：通过已注入的 `ModelGenerationService` 生成严格 JSON，校验意图必须属于
|
||
`AgentDefinition.supported_intents`，置信度低于可配置阈值时标记 `needs_clarification`；格式错误、
|
||
未声明意图和空输入失败关闭。专项测试已补，业务 Agent 不得自行复制分类解析逻辑。
|
||
- [x] P1 意图分类接入公共执行骨架。
|
||
`AgentFactory` 统一注入 `IntentClassifier` 和模型端点解析器；`BaseAgent.execute()` 在业务
|
||
`handle()` 前自动分类，并把结果写入 `CoreResult.intent`。业务 Agent 禁止覆盖分类、绑定方法，
|
||
不再需要自行创建分类器、调用路由或传递端点。骨架接入与防覆盖测试通过。
|
||
- [x] 补齐 `bootstrap` 公共依赖组装入口（截图问题 1）。
|
||
`get_agent_factory()` 统一组装数据库端点驱动的 `DatabaseModelGateway → ModelGenerationService`，
|
||
注册适当性只读工具到 `ToolRegistry → ToolExecutor`，并注入 `AgentFactory`；HTTP 与 Worker 共用同一入口。
|
||
业务组员不需要、也不允许自行拼接模型和工具链。专项组装测试已补。
|
||
- [ ] 截图问题 2（可运行示例 Agent）暂不处理，按当前任务范围排除。
|
||
- [x] 增加 Agent 注册表骨架契约测试（截图问题 3）。
|
||
`tests/contract/test_agent_factory_contract.py` 扫描注册表，强制每个构造器返回 `BaseAgent`，且
|
||
返回实例的 `AgentDefinition` 必须与注册定义完全一致；非法构造器会在工厂创建阶段失败。
|
||
- [x] 发布业务组员 Agent 接入使用说明书。
|
||
新增 `docs/11-业务组员Agent接入使用说明书.md`，明确组员提交物、公共执行顺序、模型/意图/工具/适当性
|
||
使用方式、禁止事项和验收命令。截图问题 2 的示例 Agent 仍按要求不处理。
|
||
- [ ] 基金行情数据底座接入（计划已发布）。
|
||
计划文档：`docs/12-基金行情数据底座接入开发计划.md`。按 F0-F6 先完成不改表的 Adapter、Service、
|
||
缓存/健康和 `query_fund_quote` 公共只读工具；F7 行情快照表仅在历史回测或监管留痕确有需求时启动。
|
||
当前进度：F0、F1、F2、F3、F4、F5 已完成；F6 底座侧接入规范已发布并通过工具契约检查，等待业务 Agent
|
||
按清单声明具体意图接入；F7 行情快照表暂不启动。
|
||
使用说明已同步：`docs/11-业务组员Agent接入使用说明书.md`、`docs/09-底座使用文档.md` 已明确
|
||
`query_fund_quote` 的可用条件、配置键、调用方式和当前未注册业务 Agent 的限制。
|
||
- [x] 合并组员使用说明书。
|
||
新增 `docs/14-Agent组员统一接入说明书.md`，作为业务组员唯一推荐入口，整合启动、注册、公共执行链、
|
||
模型、意图、工具、适当性、行情、禁止事项和验收命令；09、11 保留作为详细历史参考。
|
||
|
||
- [x] 完成 MVC+S 底座设计。
|
||
- [x] 完成 BaseAgent、AgentFactory、记忆、Neo4j、配置中心和模型路由设计。
|
||
- [x] 完成数据库设计，当前总表数为 49 张。
|
||
- [x] 新增 `agent_run` 作为可恢复运行实体。
|
||
- [x] 完成 REST/SSE 接口规范。
|
||
- [x] 明确 `run_id` 与 `trace_id` 分离。
|
||
- [x] 明确记忆提取事件在 `complete_run()` 同一事务写入 Outbox。
|
||
- [x] 将旧版 `docs/05-公共Agent平台接口规范.md` 标记为历史废弃稿。
|
||
- [ ] 尚未建立实际 Python 应用代码、Alembic 迁移和 OpenAPI 文件。
|
||
|
||
## 四、阶段 0：项目初始化
|
||
|
||
### T0.1 建立代码目录和工具链
|
||
|
||
状态：[-] 进行中（项目骨架、依赖和测试工具已完成；环境检查脚本仍需完善）
|
||
|
||
- [ ] 创建 `pyproject.toml`，固定 Python 版本和运行依赖。
|
||
- [ ] 创建 `app/`、`tests/`、`alembic/`、`openapi/` 目录。
|
||
- [ ] 配置 Ruff、MyPy、Pytest 和测试环境变量。
|
||
- [ ] 创建本地 MySQL、Redis、Milvus、Neo4j 的测试连接配置；密钥只使用环境变量或密钥引用。
|
||
- [ ] 验收：空项目可以运行 `python -m pytest -q`、`python -m ruff check app tests` 和 `python -m mypy app`。
|
||
|
||
### T0.2 建立契约编号和变更检查
|
||
|
||
- [ ] 在代码和文档中登记 `AGENT-REQ-001`、`AGENT-RESULT-001`、`AGENT-ERROR-001`、`AGENT-EVENT-001`、`AGENT-SSE-001`、`DB-RUN-001`。
|
||
- [ ] 增加检查脚本，验证契约编号唯一、接口文档引用存在、没有第二份 HTTP 权威文档。
|
||
- [ ] 验收：检查脚本发现重复契约编号或废弃接口文档被引用时必须失败。
|
||
|
||
## 五、阶段 1：公共契约和安全上下文
|
||
|
||
### T1.1 内部 DTO 和错误体系
|
||
|
||
状态：[x] 已完成并通过验收（公共契约、错误分类、统一信封和测试已完成）
|
||
|
||
- [ ] 实现 `AgentRequestMetadata`，只允许 `locale`、`client_version`、`ui_entry`。
|
||
- [ ] 实现 `AgentRequest`、`RequestContext`、`AgentDefinition`、`ResolvedAgentConfig`。
|
||
- [ ] 实现 `IntentResult`、`SourceReference`、`ToolCallRecord`、`CoreResult`、`AgentResult`。
|
||
- [ ] 实现 `RunProgressEvent`、`DomainEvent` 和 `AgentError` 分类。
|
||
- [ ] 测试额外字段、空消息、非法幂等键、非法置信度和越权上下文。
|
||
- [ ] 验收：契约测试全部通过，HTTP DTO 与内部 DTO 不互相直接复用。
|
||
|
||
### T1.2 JWT 和 RequestContext
|
||
|
||
状态：[x] 已完成并通过验收（RS256、iss/aud/exp/nbf/jti、吊销接口和 trace_id 已完成）
|
||
|
||
- [ ] 实现 JWT 签名、`iss`、`aud`、`nbf`、`exp`、`jti` 和吊销状态校验。
|
||
- [ ] 服务端重新加载角色、权限、客户归属和 `data_scope`。
|
||
- [ ] 实现 `trace_id` 生成、校验和 `X-Trace-ID` 响应头。
|
||
- [ ] 禁止客户端通过 Header、query、body 或 metadata 覆盖身份和权限。
|
||
- [ ] 验收：缺失、过期、错误签发方、错误受众和已吊销 Token 均返回 `401`。
|
||
|
||
## 六、阶段 2：数据库和持久化
|
||
|
||
### T2.1 数据库迁移
|
||
|
||
状态：[-] 进行中（49 张表已导入本地 jr；基线迁移文件仍需整理为 Alembic 版本链）
|
||
|
||
- [ ] 创建 10 张平台底座增量表，其中包含 `agent_run`。
|
||
- [ ] 创建 `agent_run` 的唯一键、外键、状态检查和 Worker 租约索引。
|
||
- [ ] 保持 33 张基线表和 6 张客服专项表的已有表名与已有字段定义不变。
|
||
- [ ] 使用 Alembic 生成迁移，不在运行时代码执行建表。
|
||
- [ ] 验收：空库创建后共 49 张表；Inspector 对比基线无禁止变更。
|
||
|
||
### T2.2 Repository
|
||
|
||
状态：[-] 进行中（核心 Model 和三个 Repository 已完成，事务集成测试待补）
|
||
|
||
- [ ] 实现 `AgentRunRepository`：创建、查询、租约抢占、租约接管、取消和终态更新。
|
||
- [ ] 实现 `IdempotencyRepository`：抢占、冲突、完成、失败和租约过期接管。
|
||
- [ ] 实现 `OutboxRepository`：追加、领取、发布、重试和死信状态更新。
|
||
- [ ] 实现会话、消息和审计 Repository 的最小读写接口。
|
||
- [ ] 验收：并发抢占只产生一个运行；终态不能被重复覆盖；Outbox 事件可幂等处理。
|
||
|
||
## 七、阶段 3：运行受理和 Worker
|
||
|
||
### T3.1 Agent 运行受理
|
||
|
||
状态：[x] 已完成并通过验收（事务、幂等重复、冲突、HTTP 202 和并发重复提交测试已通过）
|
||
|
||
- [ ] 实现 `POST /api/v1/agent-runs`。
|
||
- [ ] 受理事务原子保存用户消息、`request_idempotency`、`agent_run` 和 `agent.run_requested` Outbox。
|
||
- [ ] 相同幂等键和相同正文返回原 `run_id`。
|
||
- [ ] 相同幂等键和不同正文返回 `409 IDEMPOTENCY_CONFLICT`。
|
||
- [ ] HTTP 请求线程不得执行模型、Milvus、Neo4j 或记忆提取。
|
||
- [ ] 验收：返回 `202`、`run_id`、`trace_id`、状态地址和 SSE 地址。
|
||
|
||
### T3.2 AgentFactory 和 BaseAgent
|
||
|
||
状态：[x] 已完成并通过验收（注册、创建、七步执行骨架、治理方法保护和子类契约测试已完成）
|
||
|
||
- [ ] 实现 Agent 注册表和 `AgentFactory.create()`。
|
||
- [ ] 实现 `BaseAgent.execute()` 七步流程。
|
||
- [ ] 业务 Agent 只能实现 `AgentDefinition` 和 `handle()`。
|
||
- [ ] `BaseAgent` 不导入 HTTP、SSE View 或具体基础设施客户端。
|
||
- [ ] 契约测试扫描子类，禁止覆盖 `execute()` 和公共治理方法。
|
||
- [ ] 验收：未注册 Agent、非法角色、非法入口和未授权工具均被拒绝。
|
||
|
||
### T3.3 Worker 和运行租约
|
||
|
||
状态：[x] 已完成并通过验收（抢占、续租、取消检查、重试、终止和过期接管集成测试已完成）
|
||
|
||
- [ ] 实现 Worker 按 `run_id` 抢占和续租。
|
||
- [ ] 租约过期后允许其他 Worker 使用同一 `run_id` 接管。
|
||
- [ ] 可恢复错误按配置重试，不可恢复错误进入 `failed`。
|
||
- [ ] 取消请求只在安全停止点生效，最终提交阶段不得取消。
|
||
- [ ] 验收：进程重启、租约过期和重复消费不会生成第二份最终消息。
|
||
|
||
## 八、阶段 4：事务完成和记忆事件
|
||
|
||
### T4.1 `complete_run()`
|
||
|
||
状态：[x] 已完成并通过验收（最终消息、审计、幂等完成、运行终态和记忆 Outbox 同事务）
|
||
|
||
- [ ] 实现助手消息、`interaction_audit`、幂等完成状态、`agent_run` 终态和领域 Outbox 的同事务提交。
|
||
- [ ] 补齐 `DomainEvent.event_id`、`aggregate_type`、`occurred_at` 和 `trace_id`。
|
||
- [ ] 根据 `should_extract_memory()` 计算提取标记。
|
||
- [ ] `memory.extraction_requested` 必须在本事务写入 Outbox。
|
||
- [ ] 禁止请求线程在提交后调用 `memory_service.request_extraction()`。
|
||
- [ ] 验收：事务任一写入失败时全部回滚；提交后 Worker 可消费记忆事件。
|
||
|
||
### T4.2 Outbox Worker
|
||
|
||
状态：[-] 进行中（领取、发布、重试和死信已实现；事件幂等存储与业务消费者待补）
|
||
|
||
- [ ] 实现 `event_id` 幂等消费。
|
||
- [ ] 实现指数退避、最大重试次数和死信告警。
|
||
- [ ] 实现转人工、记忆提取、配置缓存失效和运行通知消费者。
|
||
- [ ] 验收：消费者重复收到同一事件不会重复创建工单、记忆或通知。
|
||
|
||
## 九、阶段 5：查询、SSE 和会话
|
||
|
||
### T5.1 运行查询
|
||
|
||
状态：[x] 已完成（持久化查询、用户隔离和稳定状态结构）
|
||
|
||
- [ ] 实现 `GET /api/v1/agent-runs/{run_id}`。
|
||
- [ ] 查询必须从 `agent_run`、`conversation_message` 和审计投影读取，不读 Worker 内存。
|
||
- [ ] 未完成、成功、失败和取消返回稳定状态结构。
|
||
- [ ] 越权资源统一返回 `404`。
|
||
|
||
### T5.2 结果级恢复 SSE
|
||
|
||
状态：[x] 已完成（数据库结果级恢复、终态事件和心跳）
|
||
|
||
- [ ] 实现 `GET /api/v1/agent-runs/{run_id}/events`。
|
||
- [ ] 输出 `start`、`tools`、`delta`、`replace`、`done`、`error`。
|
||
- [ ] `tools`、`delta`、`replace`、`done` 只能在最终事务提交后发送。
|
||
- [ ] 实现 15 秒注释心跳和连接最长时限。
|
||
- [ ] MVP 不实现事件级续传；断流后从数据库重建完整结果。
|
||
- [ ] 验收：SSE View 与 BaseAgent 无循环依赖，客户端可重连并得到完整结果。
|
||
|
||
### T5.3 会话和消息
|
||
|
||
状态：[-] 进行中（消息查询、反馈和公共转人工申请已完成；会话关闭与转人工查询待补）
|
||
|
||
本阶段完成证据：`app/api/controllers/conversations.py`、`ConversationFeedback`、`HandoverTicket`；Ruff/MyPy/21 项测试通过。
|
||
|
||
- [ ] 实现会话创建、查询、消息游标分页和结束。
|
||
- [ ] 实现消息反馈，防止同一用户重复评价同一消息。
|
||
- [ ] 实现公共转人工请求入口。
|
||
- [ ] 客服工单状态机由客服业务 Service 处理，不由公共 Controller 直接写表。
|
||
|
||
## 十、阶段 6：平台管理面
|
||
|
||
### T6.1 配置发布
|
||
|
||
- [ ] 实现配置草稿、校验、审核、激活、回滚和归档。
|
||
- [ ] 创建人不得审核自己创建的版本。
|
||
- [ ] 激活必须原子切换，回滚必须创建新发布记录。
|
||
- [ ] 草稿更新和状态转换使用 `If-Match`。
|
||
- [ ] 激活、审核、回滚和权限拒绝必须写审计。
|
||
|
||
### T6.2 模型和 Prompt 管理
|
||
|
||
- [ ] 实现模型端点管理，不返回明文密钥。
|
||
- [ ] 实现模型路由规则和 `model_routing_fallback` 管理。
|
||
- [ ] 禁止 HTTP 暴露旧的 `fallback_endpoint_ids` 作为权威字段。
|
||
- [ ] 实现 Prompt、意图配置、回复模板和禁止表达管理。
|
||
- [ ] 验收：有效版本唯一、备用端点外键和顺序约束生效。
|
||
|
||
### T6.3 审计查询
|
||
|
||
- [ ] 实现审计只读查询、游标分页和敏感详情权限。
|
||
- [ ] 禁止普通业务接口修改或删除 `interaction_audit`。
|
||
- [ ] 技术心跳、缓存操作和普通限流不写业务审计。
|
||
|
||
## 十一、阶段 7：OpenAPI 和测试
|
||
|
||
### T7.1 OpenAPI
|
||
|
||
- [ ] 生成 `openapi/agent-platform-v1.yaml`。
|
||
- [ ] 覆盖 `docs/05-接口文档.md` 第 19 节所有公共、管理和运维接口。
|
||
- [ ] 为每个写接口声明 JWT、幂等、权限、错误码和审计要求。
|
||
- [ ] 检查 OpenAPI 不把内部 DTO、ORM Model 或密钥字段暴露给客户端。
|
||
|
||
### T7.2 契约和安全测试
|
||
|
||
- [ ] 测试统一成功/错误信封。
|
||
- [ ] 测试 JWT、越权、跨客户访问和数据范围过滤。
|
||
- [ ] 测试重复提交、版本冲突、非法状态转换和游标边界。
|
||
- [ ] 测试 Agent 不能调用白名单之外的工具。
|
||
- [ ] 测试 Agent 不能代客下单、审核方案或处置风险预警。
|
||
|
||
### T7.3 故障恢复测试
|
||
|
||
- [ ] 测试 Worker 崩溃和租约接管。
|
||
- [ ] 测试 Redis 丢失后的 MySQL 恢复。
|
||
- [ ] 测试 Milvus、Neo4j、模型端点和消息中间件故障降级。
|
||
- [ ] 测试 Outbox 重试、死信和重复消费。
|
||
- [ ] 测试客户端断开后服务端仍完成归档、审计和结果查询。
|
||
|
||
## 十二、阶段 8：业务 Agent 接入
|
||
|
||
### T8.1 客服 Agent
|
||
|
||
- [ ] 由工厂注册 `customer_service`。
|
||
- [ ] 实现 FAQ、产品咨询、政策解释、闲聊和转人工意图。
|
||
- [ ] 接入知识引用、禁止表达、低置信澄清和客服转人工。
|
||
- [ ] 验收：五类意图、引用来源、合规拒答和降级模板均有端到端测试。
|
||
|
||
### T8.2 投顾 Agent
|
||
|
||
- [ ] 只生成投顾分析草案，不直接发布正式建议。
|
||
- [ ] 读取客户归属、风险测评、持仓和历史交易。
|
||
- [ ] 验收：越权客户访问、适当性不匹配和未审核草稿返回均被拦截。
|
||
|
||
### T8.3 风控 Agent
|
||
|
||
- [ ] 只读查询预警、证据和风险概览。
|
||
- [ ] 不能确认、关闭、升级预警，也不能修改交易、资金和持仓。
|
||
- [ ] 验收：所有工具调用经过白名单、数据范围和只读约束。
|
||
|
||
### T8.4 运营 Agent
|
||
|
||
- [ ] `agent_type=operations` 继续走统一 Agent 运行接口。
|
||
- [ ] 场外运营数据不得写入场内交易表。
|
||
- [ ] 若建设场外接口，必须单独提供业务表、Controller、Service 和文档。
|
||
|
||
## 十三、交付前总验收
|
||
|
||
- [ ] `python -m pytest -q` 全部通过。
|
||
- [ ] `python -m ruff check app tests` 通过。
|
||
- [ ] `python -m mypy app` 通过。
|
||
- [ ] 空库迁移完成后为 49 张表。
|
||
- [ ] 旧库升级只增加字段和新表，没有重命名、删除或改变已有字段定义。
|
||
- [ ] OpenAPI 与 05 接口文档路径、方法、必填 Header 和响应信封一致。
|
||
- [ ] 所有 Agent 由工厂创建，公共执行模板不可被绕过。
|
||
- [ ] `run_id` 可在服务重启后查询、接管和恢复结果。
|
||
- [ ] 记忆提取事件与 `complete_run()` 最终事务一致。
|
||
- [ ] 场内模拟交易、客服、投顾和风控边界测试通过。
|
||
- [ ] 所有未完成项、已知限制和迁移风险已写入发布记录。
|
||
|
||
## 十四、任务记录模板
|
||
|
||
每个任务完成后按以下格式补充记录：
|
||
|
||
```text
|
||
任务编号：T__
|
||
负责人：
|
||
开始日期：
|
||
完成日期：
|
||
实际修改文件：
|
||
测试命令：
|
||
测试结果：
|
||
数据库变更：无 / 新增表 / 新增字段（附基线对比）
|
||
接口变更：无 / 已同步 05 和 OpenAPI
|
||
未完成项：无 / 具体说明
|
||
阻塞与决策：无 / 需要负责人确认的内容
|
||
```
|
||
|
||
## 十五、底座负责人专项 TODO
|
||
|
||
本节是底座负责人需要实际交付的独立清单，范围包括通用架构、工厂类 Agent、数据库持久化、长期记忆、Neo4j 关系推理、配置中心和模型调度。业务组员只依赖本节产出的公共接口，不直接修改底座内部实现。
|
||
|
||
### D0. 范围确认和基线冻结
|
||
|
||
状态：[x] 已完成并通过验收（范围、数据库基线和公共契约已确认）
|
||
|
||
- [ ] 阅读并登记 `docs/00-新数据库基线设计.md`、`docs/01-通用Agent平台开发设计.md`、`docs/02-数据库建表设计.md`、`docs/03-平台端到端流程文档.md` 和 `docs/05-接口文档.md`。
|
||
- [ ] 建立“已有表/已有字段不可修改”基线快照，记录表名、字段名、类型、可空性、默认值、主键和索引。
|
||
- [ ] 建立公共契约清单：`AgentRequest`、`RequestContext`、`AgentResult`、`RunProgressEvent`、`DomainEvent`、`AgentError`。
|
||
- [ ] 明确底座与业务边界：底座提供能力和约束，业务 Agent 只实现 `AgentDefinition`、意图和 `handle()`。
|
||
- [ ] 验收：任何新增表、字段、接口和契约都能标注所属文档、负责人和兼容性影响。
|
||
|
||
### D0.1 依赖清单（requirements）
|
||
|
||
状态：[x] 已完成并通过验收（pyproject.toml、.env.example、.gitignore 和 jr_py313 已建立）
|
||
|
||
#### 必须固定的运行时依赖
|
||
|
||
- [ ] Python `3.11+`，项目依赖统一写入 `pyproject.toml`，禁止仅在个人环境手工安装。
|
||
- [ ] Web 和异步运行：`FastAPI`、`Uvicorn`、`Pydantic v2`、`httpx`、`anyio`。
|
||
- [ ] 数据库和迁移：`SQLAlchemy 2.x`、`Alembic`、`asyncmy` 或项目统一选定的 MySQL 驱动。
|
||
- [ ] 缓存和任务基础设施：`redis-py`，消息队列客户端按部署方案固定一种实现。
|
||
- [ ] 记忆和检索：Milvus 官方客户端、向量模型适配器，以及结构化记忆所需的 SQLAlchemy 支持。
|
||
- [ ] 关系推理：Neo4j Python Driver；Cypher 查询必须封装在 `RelationshipService`，业务 Agent 不得直接创建 Driver。
|
||
- [ ] 安全和配置：JWT 库、密码学库、环境变量加载库；密钥不得写入代码、提交记录或日志。
|
||
- [ ] 测试和质量：`pytest`、`pytest-asyncio`、`httpx` 测试客户端、`ruff`、`mypy`；需要数据库集成测试时增加 Testcontainers 或项目批准的替代方案。
|
||
- [ ] 可观测性：结构化日志、OpenTelemetry 或项目确定的 Trace SDK；日志必须支持 `trace_id`、`run_id`、`event_id`。
|
||
|
||
#### 依赖文件和版本规则
|
||
|
||
- [ ] 创建 `pyproject.toml`，声明 Python 版本、生产依赖、开发依赖、测试依赖和 Ruff/MyPy/Pytest 配置。
|
||
- [ ] 生成锁定文件（例如 `uv.lock` 或团队确定的等效文件），CI 使用锁定版本安装。
|
||
- [ ] 创建 `.env.example`，只放变量名、用途和示例占位值，不放真实密钥。
|
||
- [ ] 创建 `requirements-check.ps1` 或等效检查脚本，输出版本、连接状态和失败原因。
|
||
- [ ] 依赖升级必须记录版本、原因、兼容性影响和回滚方式；禁止无记录的批量升级。
|
||
- [ ] 验收：新开发环境只执行项目规定的安装命令即可完成依赖安装，且本地、CI 和测试环境使用同一锁定版本。
|
||
|
||
### D0.2 开发环境检查
|
||
|
||
状态：[x] 已完成并通过验收（MySQL、Redis、Neo4j、Milvus 连通性检查通过）
|
||
|
||
#### 本机工具检查
|
||
|
||
- [ ] 检查 Python 版本满足 `3.11+`，并确认 `python -m pip` 指向当前虚拟环境。
|
||
- [ ] 检查 `pytest`、`ruff`、`mypy`、`alembic`、`uvicorn` 命令可用。
|
||
- [ ] 检查 Git、Docker 和 Docker Compose 可用；不能使用 Docker 时必须提供等效的共享测试环境地址。
|
||
- [ ] 检查时区统一为 `Asia/Shanghai`，服务端数据库时间统一使用带时区或明确的 UTC 存储策略。
|
||
|
||
#### MySQL 检查
|
||
|
||
- [ ] MySQL 版本满足项目基线，字符集使用 `utf8mb4`，排序规则由数据库基线统一指定。
|
||
- [ ] 创建独立开发库、测试库和迁移验证库，禁止对生产库直接运行开发迁移。
|
||
- [ ] 验证应用账号具有业务所需的最小权限；迁移账号和运行账号分离。
|
||
- [ ] 验证连接池、事务隔离级别、时区、外键检查和 BIGINT 映射配置。
|
||
- [ ] 执行空库迁移后检查总表数为 49；执行基线对比，确认没有重命名、删除或修改已有字段定义。
|
||
|
||
#### Redis 和消息队列检查
|
||
|
||
- [ ] 验证 Redis 可连接、健康检查可用、超时和重连策略已配置。
|
||
- [ ] 明确 Redis 只用于缓存、短期状态和通知，不作为运行结果、审计或最终消息的唯一数据源。
|
||
- [ ] 验证消息队列主题、消费者组、重试队列和死信队列已创建，并记录命名规则。
|
||
- [ ] 验证 Outbox 重复投递、消费幂等和死信重放可以在测试环境执行。
|
||
|
||
#### Milvus 和 Neo4j 检查
|
||
|
||
- [ ] 验证 Milvus 地址、集合名、向量维度、距离算法和索引参数与配置中心一致。
|
||
- [ ] 验证 Milvus 不可用时结构化记忆召回仍可工作，并记录降级日志。
|
||
- [ ] 验证 Neo4j 版本、Bolt 地址、数据库名和账号权限；禁止使用管理员账号运行应用。
|
||
- [ ] 执行最小 Cypher 连通性测试、节点/关系白名单测试和租户隔离测试。
|
||
- [ ] 验证 Neo4j 重复写入幂等、关系软删除、同步失败重试和投影对账流程。
|
||
|
||
#### 模型和密钥检查
|
||
|
||
- [ ] 配置至少一个可用模型端点和一个受控备用端点，模型名称、能力标签、超时和限流写入配置中心。
|
||
- [ ] 验证模型端点密钥通过环境变量或密钥管理服务注入，接口响应和日志不会输出密钥。
|
||
- [ ] 验证模型不可用、超时、限流和返回非法结构时，Worker 能按错误分类重试或终止。
|
||
- [ ] 验证 Prompt、工具白名单和模型路由都来自已审核配置版本，不能由客户端请求覆盖。
|
||
|
||
#### 环境变量最小清单
|
||
|
||
- [ ] `APP_ENV`、`APP_NAME`、`LOG_LEVEL`、`TIMEZONE`。
|
||
- [ ] `JWT_ISSUER`、`JWT_AUDIENCE`、`JWT_PUBLIC_KEY` 或密钥服务引用、`JWT_CLOCK_SKEW_SECONDS`。
|
||
- [ ] `MYSQL_DSN`、`MYSQL_POOL_SIZE`、`MYSQL_MAX_OVERFLOW`、`MYSQL_TX_ISOLATION`。
|
||
- [ ] `REDIS_URL`、`REDIS_CONNECT_TIMEOUT_SECONDS`。
|
||
- [ ] `MESSAGE_BROKER_URL`、`MESSAGE_BROKER_RUN_TOPIC`、`MESSAGE_BROKER_OUTBOX_TOPIC`、`MESSAGE_BROKER_DLQ_TOPIC`。
|
||
- [ ] `MILVUS_URI`、`MILVUS_TOKEN` 或密钥服务引用、`MILVUS_COLLECTION`。
|
||
- [ ] `NEO4J_URI`、`NEO4J_DATABASE`、`NEO4J_USERNAME`、`NEO4J_PASSWORD` 或密钥服务引用。
|
||
- [ ] `MODEL_ROUTER_CONFIG_REF`、`MODEL_DEFAULT_ENDPOINT`、`MODEL_FALLBACK_ENDPOINT`。
|
||
- [ ] `SSE_HEARTBEAT_SECONDS`、`SSE_MAX_CONNECTION_SECONDS`、`WORKER_LEASE_SECONDS`、`WORKER_RETRY_LIMIT`。
|
||
- [ ] 验收：缺少必需变量时应用启动失败并给出变量名；任何日志、异常和 OpenAPI 响应都不暴露密钥值。
|
||
|
||
#### 环境检查验收命令
|
||
|
||
```powershell
|
||
python --version
|
||
python -m pip check
|
||
python -m pytest -q tests/environment
|
||
python -m ruff check app tests
|
||
python -m mypy app
|
||
alembic current
|
||
alembic upgrade head
|
||
```
|
||
|
||
- [ ] 将以上命令封装为一次可重复执行的环境检查脚本，并保存检查时间、依赖版本、服务版本和失败原因。
|
||
- [ ] 验收：环境检查全部通过后，才允许开始 D1；任一基础依赖不可用时，任务状态标记为 `[!]` 并记录阻塞原因。
|
||
|
||
### D1. MVC+S 通用底座
|
||
|
||
状态：[-] 进行中（目录、RequestContext、错误体系、依赖注入和分层骨架已完成；跨层静态契约检查、完整 Port 抽象和可观测性待补）
|
||
|
||
- [ ] 创建统一目录：`api/controller`、`api/view`、`service`、`repository`、`model`、`worker`、`core` 和 `infrastructure`。
|
||
- [ ] 固定调用方向：Controller -> Service -> Repository -> Model；View 不直接访问 Repository，Agent 不直接访问 Model。
|
||
- [ ] 定义依赖注入和 Service Protocol，模型、向量库、Neo4j、Redis、消息队列和外部模型均通过 Port 注入。
|
||
- [ ] 实现统一 `RequestContext`、权限检查、客户数据范围、`trace_id` 和审计上下文。
|
||
- [ ] 实现统一错误分类、错误码映射、日志字段和敏感信息脱敏。
|
||
- [ ] 验收：静态检查或契约测试能够发现 Controller 直接查库、Agent 直接调用基础设施和跨层依赖。
|
||
|
||
### D2. AgentFactory 和 BaseAgent
|
||
|
||
状态：[-] 进行中（Factory、BaseAgent 七步执行骨架、业务子类约束和 Worker 接入已完成；版本登记、配置版本绑定和组员模板待补）
|
||
|
||
- [ ] 实现 Agent 注册表、版本登记和 `AgentFactory.create(agent_type, context)`。
|
||
- [ ] 实现 `BaseAgent.execute()` 的统一七步流程：校验、权限、配置解析、记忆召回、意图处理、合规治理、结果封装。
|
||
- [ ] 将工具白名单、模型路由、Prompt 版本、禁止表达、超时、重试和审计注入公共执行流程。
|
||
- [ ] 保证 `BaseAgent` 不依赖 HTTP、SSE View、ORM Model 和具体厂商 SDK。
|
||
- [ ] 禁止业务子类覆盖 `execute()`、权限检查、审计、工具白名单和结果提交方法。
|
||
- [ ] 提供组员接入模板：Agent 类、注册代码、意图配置、工具声明、测试和文档交接表。
|
||
- [ ] 验收：组员只新增 Agent 实现和注册项即可运行，不需要修改公共 Controller 或 Worker。
|
||
|
||
### D3. 数据库和持久化底座
|
||
|
||
状态：[-] 进行中（49 表已导入、Model/Repository、租约、幂等、Outbox 和 complete_run 已完成；正式 Alembic 基线链、并发集成测试和完整迁移回滚验证待补）
|
||
|
||
- [ ] 按 `docs/02-数据库建表设计.md` 创建 10 张平台增量表，包含 `agent_run`、幂等、Outbox、配置、模型、Prompt 和审计关联表。
|
||
- [ ] 创建 Alembic 迁移、SQLAlchemy Model、Repository 和事务边界。
|
||
- [ ] 实现 `AgentRunRepository`：创建、查询、租约抢占、续租、接管、取消和终态更新。
|
||
- [ ] 实现 `IdempotencyRepository`：抢占、冲突、完成、失败和过期接管。
|
||
- [ ] 实现 `OutboxRepository`：追加、领取、重试、发布和死信。
|
||
- [ ] 实现 `complete_run()`：助手消息、审计、幂等完成、运行终态和领域事件同事务提交。
|
||
- [ ] 验收：空库共 49 张表；旧库只新增表和字段；并发条件下不会产生重复运行或重复最终消息。
|
||
|
||
### D4. 长期记忆系统
|
||
|
||
状态：[-] 进行中（MemoryService、结构化召回、关键词过滤、时间衰减、提取 Worker、触发判定、过期清理、客户隔离失效和冲突记录已完成；Milvus 向量召回、正式冲突裁决和删除级联待补）
|
||
|
||
- [ ] 定义记忆对象模型：记忆内容、类型、来源、重要性、置信度、客户归属、可见范围、版本、状态和过期时间。
|
||
- [ ] 实现记忆写入、更新、失效、删除标记和权限过滤；禁止跨客户召回记忆。
|
||
- [ ] 实现 `should_extract_memory()`，明确哪些对话、工具结果和业务事件触发记忆提取。
|
||
- [ ] 在 `complete_run()` 同一事务写入 `memory.extraction_requested` Outbox，禁止提交后直接调用提取服务。
|
||
- [ ] 实现记忆提取 Worker：事件幂等、失败重试、死信、人工重放和提取版本记录。
|
||
- [ ] 实现记忆召回：关键词、向量、结构化过滤和时间衰减；返回来源引用和置信度。
|
||
- [ ] 实现记忆合并、冲突处理、过期清理和用户删除请求的级联策略。
|
||
- [ ] 验收：同一事件重复消费只生成一份记忆；权限、租户和客户范围测试全部通过；向量库不可用时系统可降级为结构化召回。
|
||
|
||
### D5. Neo4j 关系推理
|
||
|
||
状态：[x] 已完成基础验收（白名单、邻居查询、1-2 跳路径查询、降级、持久化幂等、指数退避、死信和对账重放服务已完成；仍需真实 Neo4j 联调）
|
||
|
||
本阶段完成证据：`app/service/relationship_service.py`、`app/worker/graph_projection_worker.py`、`app/model/memory.py`；Ruff/MyPy/21 项测试通过。持久化幂等需在真实 MySQL 集成测试中最终验收。
|
||
|
||
- [ ] 定义图谱节点和关系白名单，不允许业务 Agent 自由创建任意标签或关系类型。
|
||
- [ ] 设计客户、基金、持仓、交易、风险、知识和记忆节点的唯一标识及租户隔离属性。
|
||
- [ ] 实现关系写入、版本、来源、有效期、置信度和软删除；所有写入关联 `trace_id` 和事件来源。
|
||
- [ ] 实现只读关系查询、路径查询、邻居查询和受控多跳推理接口。
|
||
- [ ] 设置最大跳数、结果数量、超时和权限过滤，防止无限扩图和越权推理。
|
||
- [ ] 实现 MySQL 事实数据与 Neo4j 投影的 Outbox 同步、重试、补偿和对账。
|
||
- [ ] Neo4j 不可用时返回可识别的降级结果，不阻塞已持久化的主流程。
|
||
- [ ] 验收：图谱重复事件幂等；关系查询只返回授权范围；同步延迟和失败记录可观测、可重放。
|
||
|
||
### D6. 配置中心和模型调度
|
||
|
||
状态：[-] 进行中（配置状态机、配置项读取、If-Match、模型端点筛选、fallback 顺序、健康过滤、缓存失效 Outbox、消费者、管理 API 和配置审计已完成；真实探针待补）
|
||
|
||
状态：[-] 进行中（ConfigRelease 状态机、配置项读取、If-Match 校验、ModelEndpointConfig 和 ModelRouterService 已建立；管理 API、审计 Outbox、缓存失效和 fallback 管理待补）
|
||
|
||
本阶段完成证据：`app/service/config_release_service.py`、`app/service/model_router_service.py`、`app/model/configuration.py`；Ruff/MyPy/21 项测试通过。
|
||
|
||
- [ ] 实现配置草稿、校验、审核、激活、回滚、版本锁和缓存失效。
|
||
- [ ] 实现模型端点、能力标签、限流、超时、成本和健康状态管理。
|
||
- [ ] 实现模型路由：按 Agent、意图、租户、场景和故障状态选择模型，并支持受控降级。
|
||
- [ ] 实现 Prompt、意图、工具白名单、禁止表达和回复模板的版本绑定。
|
||
- [ ] 配置激活、回滚和模型切换必须写审计，并通过 Outbox 通知 Worker 和缓存层。
|
||
- [ ] 验收：有效版本唯一；创建人不能审核自己；旧配置不会被正在运行的任务无意替换；密钥不出现在接口响应和日志中。
|
||
|
||
### D7. 运行可靠性和公共测试
|
||
|
||
状态：[-] 进行中。不能以方法存在性测试或全量测试通过代替专项验收；此前整体百分比未按验收项统计，不作为进度依据。
|
||
|
||
本次已验证（2026-09-09）：
|
||
|
||
- [x] Outbox 发布使用当前 UTC 时间，不复用历史更新时间。
|
||
- [x] 空轮询回滚只读事务，释放专用 Session 的事务资源。
|
||
- [x] 提交失败执行回滚并传播错误，不再次提交或误计为消费者失败。
|
||
- [x] 消费异常仅记录异常类型，不持久化可能含密钥的原始报错。
|
||
- [x] 单元测试覆盖成功、空队列、提交失败、消费失败计数、达到上限和无消费者死信，共 6 个用例。
|
||
|
||
证据：`tests/unit/worker/test_outbox_worker.py`；本次全量 28 passed，Ruff/MyPy 通过。以上使用模拟 Session，不代表真实数据库回滚或重复投递集成验收通过。
|
||
|
||
待补：真实模型端点故障注入演练和生产端点配置。Neo4j 超时降级、Redis 缓存降级、Milvus 向量适配器降级、关系白名单、供应商无关 ModelGateway fallback、本地治理路径性能基线、Prompt/意图/工具按发布版本读取、回滚缓存失效事件、Redis/Milvus 停止恢复演练和客户端断流结果级恢复测试已完成。
|
||
|
||
- [ ] 实现 Worker 租约、心跳、过期接管、可恢复错误重试和不可恢复错误终止。
|
||
- [ ] 实现运行结果查询和结果级 SSE 恢复，SSE 不依赖 Worker 内存。
|
||
- [ ] 测试 Redis、Neo4j、向量库、模型端点和消息队列不可用时的降级行为。Neo4j 与模型路由单元降级已通过，Redis/Milvus/真实模型端点待演练。
|
||
- [ ] 测试 Outbox 重复投递、死信重放、进程崩溃、数据库回滚和客户端断流。
|
||
- [ ] 建立底座契约测试、数据库迁移测试、权限测试、性能基线和故障演练记录。
|
||
- [ ] 验收：服务重启后 `run_id` 可查询、接管和恢复；所有关键异步事件可追踪、重试和对账。
|
||
|
||
### D8. 对业务组员的交付物
|
||
|
||
状态：[-] 已发布底座使用文档；Agent 接入模板、示例 Agent 和完整 Service Protocol 仍待补齐
|
||
|
||
- [ ] 发布 Agent 接入模板和最小示例 Agent。
|
||
- [x] 发布底座使用文档：`docs/09-底座使用文档.md`。
|
||
- [ ] 发布公共 Service Protocol、DTO、错误码、事件类型和工具声明规范。
|
||
- [ ] 发布数据库新增表和字段说明、迁移执行说明及回滚限制。
|
||
- [ ] 发布记忆召回、Neo4j 查询、模型路由和配置读取的调用示例。
|
||
- [ ] 发布“允许做什么/禁止做什么”清单：Agent 可查询、分析、生成草案和转人工；不可代客下单、审核方案、处置风险预警或修改交易数据。
|
||
- [ ] 验收：业务 Agent 开发者只阅读底座开发文档和接口文档，即可完成一个新 Agent 的注册、测试和运行。
|
||
|
||
### D9. 底座专项完成标准
|
||
|
||
状态：[-] 底座核心已完成；待外部真实模型端点配置和业务 Agent 端到端验收
|
||
|
||
- [x] 底座核心任务均有代码、测试、文档和验收证据；未验收项已明确记录。
|
||
- [x] 公共执行模板不可被业务 Agent 绕过，工厂是唯一创建入口。
|
||
- [x] 数据库兼容性检查通过，没有修改已有表名和已有字段定义。
|
||
- [x] 长期记忆提取与 `complete_run()` 事务一致，Neo4j 投影可重试和对账。
|
||
- [x] 配置、模型、Prompt、工具和权限支持版本化、审计和回滚基础能力。
|
||
- [ ] 至少一个客服 Agent、一个投顾 Agent 和一个风控 Agent 在底座上完成端到端验收。
|
||
|
||
说明：最后一项属于业务 Agent 接入和业务组验收，不纳入本轮底座负责人个人交付；D8 继续暂停。
|
||
|
||
## 十六、已完成任务记录
|
||
|
||
```text
|
||
任务编号：D9 / 底座负责人专项收口
|
||
完成日期：2026-09-09
|
||
最终验证：43 passed；Ruff 通过；MyPy 通过；49 张业务表 schema audit 通过；Redis/Neo4j/Milvus 健康检查通过；本地治理路径性能基线执行成功。
|
||
底座范围：MVC+S、AgentFactory/BaseAgent、运行受理/租约/恢复、数据库持久化、complete_run 同事务 Outbox、记忆基础、Neo4j 投影、配置发布/审计/回滚、模型路由/ModelGateway、Redis/Milvus 降级、结果级 SSE。
|
||
未纳入本轮：D8 组员交付物、真实模型厂商端点配置、客服/投顾/风控业务 Agent 端到端验收。
|
||
数据库约束：仅新增 outbox_delivery 表；未重命名、删除或修改任何既有表和字段定义。
|
||
```
|
||
|
||
```text
|
||
任务编号：D6 / ModelGateway 与受控 fallback
|
||
完成日期：2026-09-09
|
||
修改文件：app/service/model_gateway.py、tests/unit/service/test_model_gateway.py、TODO.md
|
||
已完成：供应商无关 ModelGateway Protocol；按 ModelRouterService 输出顺序尝试端点；成功使用 fallback 时标记 degraded；所有端点失败返回统一错误。
|
||
验证结果：43 passed；Ruff/MyPy 通过；49 张业务表审计通过。
|
||
未完成：真实模型端点配置和网络故障演练。
|
||
```
|
||
|
||
```text
|
||
任务编号：D7 / 客户端断流结果级恢复
|
||
完成日期：2026-09-09
|
||
修改文件：tests/unit/api/test_agent_run_sse.py、TODO.md
|
||
已验证：客户端只读取 start 后断开，重新根据同一 run_id 生成完整 replace/done 终态事件；结果恢复不依赖原连接或 Worker 内存。
|
||
结果：全量 42 passed；Ruff/MyPy 通过。
|
||
```
|
||
|
||
```text
|
||
任务编号：D7 / Redis 与 Milvus 真实停止恢复演练
|
||
完成日期：2026-09-09
|
||
目标容器：my-redis、milvus-standalone
|
||
停止验证：redis unavailable:ConnectionError；milvus unavailable:MilvusException；neo4j ok。
|
||
降级验证：缓存和向量适配器故障单元测试通过。
|
||
恢复验证：两个容器重新启动后 redis=True、milvus=ok、neo4j=ok。
|
||
结果：真实停止、故障观测、恢复和健康复查完成；未修改业务数据库表。
|
||
```
|
||
|
||
```text
|
||
任务编号：D7 / Milvus 向量检索降级边界
|
||
完成日期：2026-09-09
|
||
修改文件：app/infrastructure/vector_memory.py、tests/unit/infrastructure/test_vector_memory.py、TODO.md
|
||
已完成：向量检索成功路径封装；Milvus 异常返回空结果和 degraded 标志，不阻塞 MySQL 结构化召回。
|
||
验证结果：41 passed；Ruff/MyPy 通过。
|
||
说明：故障桩单元验证已通过，真实 Milvus 停止/恢复演练仍未执行。
|
||
```
|
||
|
||
```text
|
||
任务编号：D7 / Redis 缓存降级边界
|
||
完成日期：2026-09-09
|
||
修改文件：app/infrastructure/memory_cache.py、tests/unit/infrastructure/test_memory_cache.py、TODO.md
|
||
已完成：缓存读失败返回 degraded 标志；缓存写失败返回 False；缓存不可用不阻塞 MySQL 主存储。
|
||
验证结果：40 passed；Ruff/MyPy 通过。
|
||
说明：使用故障桩完成单元降级验证，真实 Redis 停止/恢复演练仍未执行。
|
||
```
|
||
|
||
```text
|
||
任务编号：D7 / 本机外部依赖健康检查
|
||
完成日期：2026-09-09
|
||
新增文件：tools/dependency_health_check.py
|
||
执行命令：python tools/dependency_health_check.py
|
||
结果：redis=True；neo4j=ok；milvus=ok。
|
||
说明：仅为连通性检查，不等于故障注入、降级和恢复演练；PyMilvus 输出第三方 API 弃用警告。
|
||
```
|
||
|
||
```text
|
||
任务编号：D6 / 配置发布生命周期真实 MySQL 验收
|
||
完成日期：2026-09-09
|
||
修改文件：app/service/config_release_service.py、tests/integration/test_config_release_mysql.py、TODO.md
|
||
验证结果：真实 MySQL 配置生命周期 1 passed；全量 38 passed；Ruff/MyPy 通过；schema audit 通过。
|
||
已验证：创建人不能审核自己；激活只有一个 active；旧版本变为 superseded；回滚记录 rollback_of_release_id；激活和回滚缓存失效 Outbox；四类配置审计。
|
||
修复缺陷：回滚前先 flush 释放 active_slot；回滚状态使用基线允许的 superseded；自增实体不再显式写 id=0。
|
||
数据库变更：无。
|
||
```
|
||
|
||
```text
|
||
任务编号：D6 / 配置版本链补齐
|
||
完成日期：2026-09-09
|
||
修改文件：app/model/configuration.py、app/service/config_release_service.py、TODO.md
|
||
已完成：补齐既有 config_release 的 supersedes_release_id/rollback_of_release_id ORM 映射；回滚记录指向目标版本；回滚同样写缓存失效 Outbox。
|
||
数据库变更：无，字段原已存在，仅补充 ORM 映射；未新增迁移。
|
||
验证结果：37 passed；Ruff/MyPy 通过。
|
||
```
|
||
|
||
```text
|
||
任务编号：D6 / 工具白名单发布版本绑定
|
||
完成日期：2026-09-09
|
||
修改文件：app/service/runtime_config_service.py、TODO.md
|
||
实现：RuntimeConfigService.allowed_tools() 按 release_id、namespace=agent_tools 和 agent_type:intent_code 读取，并严格校验为字符串列表。
|
||
数据库变更：无；复用 platform_config_item，未修改已有字段。
|
||
验证结果：37 passed；Ruff/MyPy 通过。
|
||
未完成：真实数据库配置集成测试和完整管理 API。
|
||
```
|
||
|
||
```text
|
||
任务编号：D6 / Prompt 与意图运行时版本绑定
|
||
完成日期：2026-09-09
|
||
修改文件：app/model/configuration.py、app/service/runtime_config_service.py、TODO.md
|
||
验证结果：37 passed；Ruff/MyPy 通过；49 张业务表审计通过。
|
||
已完成：Prompt 按 release_id/task_type/agent_type 读取；意图按 agent_type/intent_code 且仅 active 读取；未新增或修改数据库结构。
|
||
未完成：完整管理 API 和配置集成测试。工具白名单现已通过 `platform_config_item(namespace=agent_tools)` 与 release_id 绑定，仍需数据库集成测试。
|
||
```
|
||
|
||
```text
|
||
任务编号：D7 / 本地治理路径性能基线
|
||
完成日期：2026-09-09
|
||
新增文件：tools/performance_baseline.py
|
||
执行命令：python tools/performance_baseline.py
|
||
结果：200 次迭代，p50=0.0142ms，p95=0.0166ms，max=0.0973ms。
|
||
说明：仅测量进程内 BaseAgent 治理路径，不包含数据库、向量库、Neo4j、模型网络调用，不作为生产 SLA。
|
||
```
|
||
|
||
```text
|
||
任务编号：D7 / SSE 结果级恢复修正
|
||
完成日期：2026-09-09
|
||
修改文件：app/api/views/agent_run_sse.py、app/api/controllers/agent_runs.py、tests/unit/api/test_agent_run_sse.py、TODO.md
|
||
验证结果：34 passed；Ruff/MyPy 通过。
|
||
已验证：运行未完成时只发送 start/心跳；最终事务完成后才发送 tools、replace、done/error；SSE 不依赖 Worker 内存，按 run_id 轮询数据库并受最长连接时间限制。
|
||
未完成项：真实客户端断流测试、外部依赖故障演练和性能基线。
|
||
```
|
||
|
||
```text
|
||
任务编号：D7 / complete_run 真实事务回滚验收
|
||
完成日期：2026-09-09
|
||
修改文件：tests/integration/test_complete_run.py、TODO.md
|
||
验证方法：在同一完成事务中制造 domain_event_outbox.event_id 唯一键冲突。
|
||
结果：真实 MySQL 验证助手消息、agent_run 终态、request_idempotency、interaction_audit 和全部 Outbox 写入均回滚；2 passed。
|
||
数据库变更：无；测试数据已清理。
|
||
```
|
||
|
||
```text
|
||
任务编号：D7 / Outbox 死信重放
|
||
完成日期：2026-09-09
|
||
修改文件：app/service/outbox_admin_service.py、tests/integration/test_outbox_replay_mysql.py、TODO.md
|
||
验证命令：python -m pytest -q tests/integration/test_outbox_replay_mysql.py -p no:cacheprovider；python -m ruff check app tests；python -m mypy app
|
||
结果：真实 MySQL 1 passed；Ruff/MyPy 通过。
|
||
数据库变更：无。
|
||
已验证：仅 dead 状态可重放；重试状态被重置；重放动作写 interaction_audit；测试数据完成清理。
|
||
```
|
||
|
||
```text
|
||
任务编号：D7 / Outbox 真实 MySQL 幂等验收
|
||
完成日期：2026-09-09
|
||
修改文件：app/worker/outbox_worker.py、tests/integration/test_outbox_mysql.py、tests/unit/worker/test_outbox_worker.py、tools/audit_schema.py、TODO.md
|
||
验证命令：alembic upgrade head；python -m pytest -q -p no:cacheprovider；python -m ruff check app tests tools alembic；python -m mypy app；python tools/audit_schema.py
|
||
结果：Alembic 位于 20260909_outbox_delivery (head)；29 passed；Ruff/MyPy 通过；49 张业务表无缺失和意外表。
|
||
数据库变更：仅新增 outbox_delivery；原 48 张业务表及字段未修改。
|
||
已验证：进程级重建 Session 后重复投递不重复执行 Handler；不同消费者不误领事件。
|
||
未完成项：死信重放、真实数据库提交失败回滚、并发唯一冲突压力测试。
|
||
```
|
||
|
||
```text
|
||
任务编号：D7 / Outbox 持久化消费幂等接入
|
||
完成日期：2026-09-09
|
||
修改文件：app/model/platform.py、app/worker/outbox_worker.py、alembic/versions/20260909_outbox_delivery.py、tests/unit/worker/test_outbox_worker.py、TODO.md
|
||
验证命令：python -m pytest -q -p no:cacheprovider；python -m ruff check app tests；python -m mypy app
|
||
结果：28 passed；Ruff/MyPy 通过。单元测试为模拟 Session，存在 AsyncMock 的测试环境警告。
|
||
数据库变更：新增 `outbox_delivery`，未修改已有表或字段。
|
||
未完成项：真实 MySQL 迁移、唯一冲突并发测试、死信重放。
|
||
```
|
||
|
||
```text
|
||
任务编号：D7 / Outbox 事务与异常处理回归
|
||
完成日期：2026-09-09
|
||
修改文件：app/worker/outbox_worker.py、tests/unit/worker/test_outbox_worker.py、TODO.md
|
||
验证过程：先新增行为测试，5 failed / 1 passed；修复后全量 28 passed。
|
||
验证命令：python -m ruff check app tests；python -m mypy app；python -m pytest -q -p no:cacheprovider
|
||
结果：Ruff、MyPy 通过；28 passed，2 项第三方弃用警告。
|
||
数据库变更：无；不改变任何已有表或字段。
|
||
未完成项：真实 MySQL 故障与回滚验证、到期重试调度、幂等与死信重放。
|
||
进度口径：本次新增 6 个行为用例替代 1 个导入测试；D7 仍在进行中，不增加未经统计的整体百分比。
|
||
```
|
||
|
||
```text
|
||
任务编号：T5.3、D4（基础）、D5（基础）、D6（基础）
|
||
负责人：底座负责人
|
||
完成日期：2026-09-09
|
||
实际修改文件：app/api/controllers/conversations.py、app/model/conversation.py、app/model/platform.py、app/model/memory.py、app/service/memory_service.py、app/worker/memory_extraction_worker.py、app/service/relationship_service.py、app/worker/graph_projection_worker.py、app/model/configuration.py、app/service/config_release_service.py、app/service/model_router_service.py
|
||
测试命令：python -m ruff check app；python -m mypy app；python -m pytest -q
|
||
测试结果：通过；21 passed
|
||
未完成项：持久化幂等、Neo4j 对账、配置管理 API、缓存失效、完整专项集成测试
|
||
```
|
||
|
||
```text
|
||
任务编号：D0、D0.1、D0.2、T1.1、T1.2
|
||
负责人：底座负责人
|
||
完成日期：2026-09-09
|
||
实际修改文件：pyproject.toml、.env、.env.example、app/core、app/api、tests、config/jwt
|
||
测试命令：python -m pytest -q；python -m ruff check app tests；python -m mypy app
|
||
测试结果：通过；7 passed
|
||
数据库变更：新增 48 张业务表和 1 张 alembic_version，已执行结构审计
|
||
接口变更：公共内部契约已完成，HTTP 运行接口尚未开始
|
||
未完成项：T0.2 契约编号检查、T2.2 集成测试、T3.1 运行受理
|
||
阻塞与决策：基线表由 00 和 02 文档生成，已记录生成脚本和审计脚本
|
||
```
|
||
|
||
```text
|
||
任务编号：T2.1、T2.2、T3.1
|
||
负责人：底座负责人
|
||
完成日期：2026-09-09
|
||
实际修改文件：alembic、app/model、app/infrastructure/db.py、app/repository、app/service、app/api、tools
|
||
测试命令：alembic upgrade head；python tools/audit_schema.py
|
||
测试结果：49 张表审计通过；Repository 静态检查通过
|
||
数据库变更：平台增量表、运行表、幂等表和 Outbox 已建立
|
||
接口变更：无
|
||
未完成项：基线迁移需整理为正式 Alembic 历史版本；Repository 和 T3.1 集成测试待补；统一错误映射待补
|
||
阻塞与决策：无
|
||
```
|