group_fqcd_jr/TODO.md

Agent 底座开发 TODO

⚠️ 本文件自 2026-09-09 起未随 Phase 1 交付更新，存在系统性过期，请勿作为当前进度依据。 已知硬错：① 五处「49 张表」→ 现库 52 张（51 张业务表）；② L203「尚未建立 Python 应用代码、Alembic 迁移」→ 实际已有 120 个 .py、8 个迁移；③ T8.1 客服 Agent 整节未勾选但已交付；④ T2.2 / T5.3 标「进行中」其实已完成；⑤ [-] 状态行与子项勾选普遍不一致。当前进度请看 docs/superpowers/sdd/2026-09-10-客服Agent与RAG-qyqy版/phase1-acceptance-report.md。

（此批注由 2026-09-11 只读审计加入；原文未改动。详见 docs/superpowers/ARCHIVE-2026-09-11-文档清理归档.md §3）

版本：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 为问题来源（该报告已于 2026-09-11 随文档清理删除； 其全部 P0/P1 结论已完整承载在 docs/07-测试问题修复记录.md，请改引该文件），按项复测后勾选。

• 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 已同步。数据库结构无变更。
• P0-2 未注册 Agent 受理前拒绝（依 05 返回 404）。 证据：HTTP 未注册类型不写数据库测试 + 3 项 MySQL 受理/并发/HTTP 回归，共 4 passed。 修正并发测试断言为“恰好一个成功运行”，防止全部失败也通过。正式注册入口 bootstrap 与测试注册分离，未接入业务 Agent 不冒充已注册。错误采用 05 的 AGENT_TYPE_NOT_FOUND。
• P0-3 独立 Worker 入口与真实运行闭环。 证据：test_worker_runtime_mysql.py 3 passed；python -m app.worker --help 可执行； 启动、注册、租约、撤权和验收范围见 docs/07-测试问题修复记录.md。新轮询配置已写 .env。
• P1-1 非法 JWT sub 返回 401。 证据：test_security.py 11 passed，包含非数字、负数、零、全角数字、超长和溢出， 有效签名但 sub=abc 的 HTTP 请求为 401 且不调用身份查询。
• P1-2 配置、记忆、合规治理钩子接线。 证据：test_agent_governance.py 9 项 + test_governance_mysql.py 真库召回/禁止词 1 项。 工厂注入治理协议；发布配置快照、按意图工具交集、客户记忆和已审核禁止词实际生效； 引用校验、号码脱敏、合规替换、缺失依赖拒绝执行及治理方法覆盖测试通过。 限制：完整意图模型/工具执行器未完成；未登记工具记录和外部引用拒绝；正则规则失败关闭。
• P1-3 SSE delta 与结果级恢复。 证据：test_agent_run_sse.py 6 passed；待完成连接输出提交后的 delta，终态重连用 replace； 中文/emoji、空正文、唯一事件 ID、未提交不泄露正文及断流恢复均覆盖。05 已同步。
• P1-4 Controller 数据访问下沉。 证据：Controller 不再导入 Model/Repository 或操作 Session；架构 AST 检查 + HTTP/SSE 和真库 Worker 回归共 12 passed；新增 ConversationRepository/ConversationService/ RunQueryService/ConfigApplicationService，连接依赖移至 api/dependencies。
• P1-5 公共、管理、运维接口覆盖及 OpenAPI；业务接口不纳入。 证据：OpenAPI 路由 40 条，覆盖运行、会话、取消、反馈、转人工、记忆、知识、管理资源、 健康和指标；所有底座写接口使用 ApiTransactionService 幂等回执，管理写接口要求 If-Match， 配置/模型/工具上限校验集中在 AdminService。接口动态资源按文档资源编号映射；业务域接口仍由组员负责。
• P2-1 会话实体与澄清轮次。 svc_conversation_session 已按 02 §8.1 新表迁移，ConversationSession/SessionRepository 提供归属、状态、消息计数和带旧值的澄清轮次更新；未修改既有表。
• P2-2 JWT 公钥缓存。 认证依赖使用单例 JwtAuthenticator，公钥只在进程首次请求加载；JWT 轮换需重启/清缓存。
• P2-3 会话归属并发保护。 新会话表存在时受理使用用户+session 行锁、状态和 Agent 一致性校验；旧消息归属仍保留兼容兜底。
• P2-4 废弃 HTTP 文档权威检查。 tools/check_authoritative_docs.py 检查 05 唯一权威文档和历史废弃稿标记。
• P2-5 分层目录文档对齐。 代码实际目录以 app/api/controllers、app/api/views、app/service、app/repository 为准， 本次 AST 检查和 docs/07 已按此记录；不移动源码，避免无意义路径破坏。
• P2-6 表数及 TODO 证据一致性。 02 文档同步为 51 张（含会话补表和 HTTP 回执表），audit_schema 及 Alembic head 已同步。
• P2-7 外键与基线字段完整性核对。 新增表按 02 DDL 建立；既有表以 49 张指纹审计证明字段未变化。外键完整性不通过新增约束 改写既有表，保留由应用 Repository 约束的历史兼容关系；审计范围和限制见 docs/08。

2026-09-09 数据库基线纠偏、空库重建与记忆链路修复

• DB-1 基线联合唯一键纠偏。 根因：tools/generate_baseline_sql.py 只按规则列里的"唯一"字样逐字段生成 UNIQUE KEY， 无法表达文档中的 唯一键 (a, b)。受影响表：fin_market_price、fin_nav_history、 fin_holding、sys_customer_assignment——会导致场内日线与净值每产品只能存一行、 持仓每客户只能有一个产品。修复：生成器支持联合唯一键；迁移 20260909_constraint_fix 删 8 个错误单列唯一键、加 4 个联合唯一键，并做成幂等收敛（空库重建时自动跳过）。 纠偏时四张表均为 0 行。证据：docs/evidence/20260909-before-constraint-fix.sql、四份结构指纹、 约束差异 12 → 0、指纹差异恰好 4 张表。docs/00 未做任何修改。
• DB-2 审计盲区补强。 tools/schema_fingerprint.py 指纹纳入索引/唯一键与外键（此前只对字段做指纹，查不出约束漂移）； 新增 tools/audit_constraints.py 做"文档唯一键 ↔ 库唯一索引 ↔ ORM 列名"三向比对； tools/audit_schema.py 不再硬编码数据库凭据（改读 .env）。
• DB-3 空库重建（方案 A）。 新增基线初始迁移 20260909_baseline_schema（39 张基线表），原链首 20260909_agent_platform_v31 改接其后。空库 alembic upgrade head 建出 51 张业务表，与既有库结构指纹 0 差异； 既有库无需额外操作（版本记录已位于新链上）。
• MEM-1 记忆链路打通。 WorkerRuntime 注册 4 个 handler；消费者改为按 message_id 回查 conversation_message 取权威正文（事件仍只带定位信息，不落正文）；event_id 作为证据幂等键；修复冲突记录自引用 与库列名不符；迁移 20260909_memory_active_key 补生成列与唯一键。 证据：tools/memory_chain_probe.py 全项 PASSED，见 docs/evidence/20260909-memory-chain-acceptance.md。
• MEM-2 ORM 映射漂移归零。47 条不一致全部对齐，tools/audit_constraints.py PASSED。
• FIN-1 场内交易只读层。新增 app/model/fund.py 与 app/repository/fund_query_repository.py： 无任何写方法、返回冻结快照防止回写、客户范围 fail-closed、组合式查询与注册式扩展点。
• MEM-3 记忆抽取 P2（模型严格 JSON、语义 memory_key 词表、事件驱动触发）。 新增 app/service/memory_extraction_service.py 与受控词表 app/service/memory_taxonomy.py； 抽取失败关闭（JSON 非法、键不在词表、置信度越界一律不落库）；触发判定改为显式信号 + 业务事件驱动。 复核中发现并修复信号识别三类缺陷（宽泛"偏好"造成跨键重叠误命中、模式过于字面造成漏命中）， 配 11 个回归测试。P2 还引入过一个真实回归：_execute_claimed 在同一 Session 上先做只读查询触发 autobegin，使 complete_run 抛 "A transaction is already begun on this Session"，已改为独立 Session 查询并补上失败堆栈日志。 证据：tools/memory_chain_probe.py 全项 PASSED，含"抽取模型被真实调用、记忆键来自受控词表、 记忆内容是抽取的结构化值而非用户原文"。
• MEM-4 记忆 P3（召回、episode 聚合、级联失效）。 新增 app/service/memory_recall_service.py、app/service/memory_lifecycle_service.py、 app/model/episode.py、app/worker/episode_worker.py，并补齐 53 个专项单元测试 （召回 17 例、生命周期 10 例、episode 16 例、模型向量化 10 例）。 接线（此前这三个服务零调用点，实为死代码，目标要求的"接线"当时并未达成）： · 召回——PlatformGovernance.recall 改走 MemoryRecallService，bootstrap 组装并注入 recall_factory；Redis 缓存与语义通道均已接入：模型网关新增 OpenAI-compatible /embeddings 能力（ModelEmbeddingService + ModelDispatchService.embed，与文本生成 同族的受控降级），组装层在 Milvus 可达时传入 vector= 与 embed=；缺 embedding 端点时 向量化失败关闭、保留结构化召回并标记 embedding_failed（配置缺口，非功能缺失）； · episode——WorkerRuntime 每 30 轮顺带聚合一次已静默会话片段，实测 inserted=1 persisted_rows=1； · 级联——注册 memory.deletion_requested handler → MemoryLifecycleService.run， 实测 memory_status=invalidated 且审计恰好 1 行。 接线暴露并修复的三个真实缺陷： · EpisodeWorker 只 flush 不提交，接线方漏 commit → 出现"报告插入成功但表里没有行"； · 召回缓存命中时丢失降级状态（写入含 degraded，读取硬编码 False）； · recall_with_decay 中 Decimal * float 抛 TypeError（该路径此前从未被真实数据触发）。

验证汇总：pytest unit+contract 140 passed / integration 19 passed；Ruff 通过；MyPy strict 91 文件通过；tools/audit_schema.py 51 张业务表通过；tools/audit_constraints.py PASSED； 记忆链路探针 PASSED；空库重建与既有库结构 0 差异。

状态只允许使用：

• [ ] 未开始
• [-] 进行中
• [x] 已完成并通过验收
• [!] 阻塞，必须在任务说明中写明原因和需要的决策

任务完成必须同时满足：代码完成、测试通过、文档同步、验收证据已记录。

三、当前基线

2026-09-09 业务域接入评估补课

• P0-A 模型 Adapter、统一模型生成入口。 新增 OpenAI-compatible Adapter、env secret_ref 解析、模型失败统一错误、受控 fallback、 ModelGenerationService 和 BaseAgent.generate_with_model；业务 Agent 不能直连供应商。 验证：模型 Adapter、密钥不泄露、空路由失败关闭和工厂注入测试通过。真实供应商端点仍需环境配置演练。

• P0-B ToolRegistry、ToolExecutor 和 BaseAgent 工具入口。 工具必须只读、声明输入 Schema/权限/角色，按意图白名单执行，失败关闭、超时、脱敏摘要、 来源引用和独立审计均已实现；工厂统一注入，未注入时拒绝执行。专项工具测试已补。

• P0-C 公共适当性校验服务和工具入口。 新增 SuitabilityService、严格输入 DTO 和 suitability_tool_handler；统一执行 C1-C5/R1-R5 风险匹配、测评过期、风险揭示/二次确认/双录规则。通过和拒绝决定均写入 interaction_audit， 不修改交易或产品数据，业务 Agent 只能经 ToolExecutor 调用。专项边界、过期、时区和审计测试通过。

• P1 意图分类公共服务。 新增 IntentClassifier：通过已注入的 ModelGenerationService 生成严格 JSON，校验意图必须属于 AgentDefinition.supported_intents，置信度低于可配置阈值时标记 needs_clarification；格式错误、 未声明意图和空输入失败关闭。专项测试已补，业务 Agent 不得自行复制分类解析逻辑。

• P1 意图分类接入公共执行骨架。 AgentFactory 统一注入 IntentClassifier 和模型端点解析器；BaseAgent.execute() 在业务 handle() 前自动分类，并把结果写入 CoreResult.intent。业务 Agent 禁止覆盖分类、绑定方法， 不再需要自行创建分类器、调用路由或传递端点。骨架接入与防覆盖测试通过。

• 补齐 bootstrap 公共依赖组装入口（截图问题 1）。 get_agent_factory() 统一组装数据库端点驱动的 DatabaseModelGateway → ModelGenerationService， 注册适当性只读工具到 ToolRegistry → ToolExecutor，并注入 AgentFactory；HTTP 与 Worker 共用同一入口。 业务组员不需要、也不允许自行拼接模型和工具链。专项组装测试已补。

• 截图问题 2（可运行示例 Agent）暂不处理，按当前任务范围排除。

• 增加 Agent 注册表骨架契约测试（截图问题 3）。 tests/contract/test_agent_factory_contract.py 扫描注册表，强制每个构造器返回 BaseAgent，且 返回实例的 AgentDefinition 必须与注册定义完全一致；非法构造器会在工厂创建阶段失败。

• 发布业务组员 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 的限制。

• 合并组员使用说明书。 新增 docs/14-Agent组员统一接入说明书.md，作为业务组员唯一推荐入口，整合启动、注册、公共执行链、 模型、意图、工具、适当性、行情、禁止事项和验收命令；09、11 保留作为详细历史参考。

• 发布组员详细开发与代码说明手册。 新增 docs/15-Agent组员详细开发与使用手册.md，补充项目分层、关键源码解释、BaseAgent 执行链、 模型/工具/行情/适当性代码示例、HTTP 恢复、错误处理、测试和交接模板，供组员及其 AI 完整阅读。

• 发布组员入门易懂版说明。 新增 docs/16-Agent组员入门易懂版说明.md，用机场类比和逐步代码示例解释 Agent、Factory、BaseAgent、 工具、行情、适当性、配置、错误和测试，适合首次接入的组员及其 AI 阅读。

• 发布接口文档易懂说明。 新增 docs/17-接口文档易懂说明.md，用请求示例解释 REST/SSE、JWT、幂等、运行、会话、管理、运维接口、 错误处理和 A/B 类业务扩展，明确与《05-接口文档.md》的权威关系。

• 完成 MVC+S 底座设计。

• 完成 BaseAgent、AgentFactory、记忆、Neo4j、配置中心和模型路由设计。

• 完成数据库设计，当前总表数为 49 张。

• 新增 agent_run 作为可恢复运行实体。

• 完成 REST/SSE 接口规范。

• 明确 run_id 与 trace_id 分离。

• 明确记忆提取事件在 complete_run() 同一事务写入 Outbox。

• 将旧版 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() 最终事务一致。
• 场内模拟交易、客服、投顾和风控边界测试通过。
• 所有未完成项、已知限制和迁移风险已写入发布记录。

十四、任务记录模板

每个任务完成后按以下格式补充记录：

任务编号：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 响应都不暴露密钥值。

环境检查验收命令

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）：

• Outbox 发布使用当前 UTC 时间，不复用历史更新时间。
• 空轮询回滚只读事务，释放专用 Session 的事务资源。
• 提交失败执行回滚并传播错误，不再次提交或误计为消费者失败。
• 消费异常仅记录异常类型，不持久化可能含密钥的原始报错。
• 单元测试覆盖成功、空队列、提交失败、消费失败计数、达到上限和无消费者死信，共 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。
• 发布底座使用文档：docs/09-底座使用文档.md。
• 发布公共 Service Protocol、DTO、错误码、事件类型和工具声明规范。
• 发布数据库新增表和字段说明、迁移执行说明及回滚限制。
• 发布记忆召回、Neo4j 查询、模型路由和配置读取的调用示例。
• 发布“允许做什么/禁止做什么”清单：Agent 可查询、分析、生成草案和转人工；不可代客下单、审核方案、处置风险预警或修改交易数据。
• 验收：业务 Agent 开发者只阅读底座开发文档和接口文档，即可完成一个新 Agent 的注册、测试和运行。

D9. 底座专项完成标准

状态：[-] 底座核心已完成；待外部真实模型端点配置和业务 Agent 端到端验收

• 底座核心任务均有代码、测试、文档和验收证据；未验收项已明确记录。
• 公共执行模板不可被业务 Agent 绕过，工厂是唯一创建入口。
• 数据库兼容性检查通过，没有修改已有表名和已有字段定义。
• 长期记忆提取与 complete_run() 事务一致，Neo4j 投影可重试和对账。
• 配置、模型、Prompt、工具和权限支持版本化、审计和回滚基础能力。
• 至少一个客服 Agent、一个投顾 Agent 和一个风控 Agent 在底座上完成端到端验收。

说明：最后一项属于业务 Agent 接入和业务组验收，不纳入本轮底座负责人个人交付；D8 继续暂停。

十六、已完成任务记录

任务编号：DB-1 / DB-2 / DB-3 / MEM-1 / MEM-2 / FIN-1
负责人：底座负责人
完成日期：2026-09-09
实际修改文件：tools/generate_baseline_sql.py、tools/audit_constraints.py（新增）、
  tools/audit_schema.py、tools/schema_fingerprint.py、tools/generate_baseline_migration.py（新增）、
  tools/memory_chain_probe.py（新增）、alembic/versions/20260909_baseline_schema.py（新增）、
  20260909_constraint_fix.py（新增）、20260909_memory_active_key.py（新增）、
  20260909_agent_platform_v31.py、alembic/baseline_generated.sql、app/model/memory.py、
  app/model/configuration.py、app/model/conversation.py、app/model/platform.py、
  app/model/fund.py（新增）、app/service/memory_service.py、app/worker/runtime.py、
  app/worker/memory_extraction_worker.py、app/repository/fund_query_repository.py（新增）、
  docs/02、docs/08、docs/evidence/*
测试命令：python -m pytest -q tests/unit tests/contract；python -m pytest -q tests/integration；
  python -m ruff check app tests tools alembic；python -m mypy app；python tools/audit_schema.py；
  python tools/audit_constraints.py；python tools/memory_chain_probe.py
测试结果：140 passed / 19 passed；Ruff 通过；MyPy strict 通过；51 张业务表审计通过；
  约束审计 PASSED；记忆链路探针 PASSED；空库重建与既有库结构指纹 0 差异。
数据库变更：新增迁移 3 个（基线初始、约束纠偏、记忆生成列）；删除 8 个错误单列唯一键、
  新增 4 个联合唯一键、新增 memory_unit.active_memory_key 生成列与唯一键。
  未重命名或删除任何既有表与既有字段，docs/00 基线文档未修改。
接口变更：无 HTTP 接口变更。
未完成项：记忆 P2（进行中）、记忆 P3（未开始）；真实模型端点仍未配置
  （model_endpoint_config 为 0 行，空端点时会按设计失败关闭，因此零配置环境无法端到端跑通 Agent）。
阻塞与决策：无。

任务编号：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 表；未重命名、删除或修改任何既有表和字段定义。

任务编号：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 张业务表审计通过。
未完成：真实模型端点配置和网络故障演练。

任务编号：D7 / 客户端断流结果级恢复
完成日期：2026-09-09
修改文件：tests/unit/api/test_agent_run_sse.py、TODO.md
已验证：客户端只读取 start 后断开，重新根据同一 run_id 生成完整 replace/done 终态事件；结果恢复不依赖原连接或 Worker 内存。
结果：全量 42 passed；Ruff/MyPy 通过。

任务编号：D7 / Redis 与 Milvus 真实停止恢复演练
完成日期：2026-09-09
目标容器：my-redis、milvus-standalone
停止验证：redis unavailable:ConnectionError；milvus unavailable:MilvusException；neo4j ok。
降级验证：缓存和向量适配器故障单元测试通过。
恢复验证：两个容器重新启动后 redis=True、milvus=ok、neo4j=ok。
结果：真实停止、故障观测、恢复和健康复查完成；未修改业务数据库表。

任务编号：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 停止/恢复演练仍未执行。

任务编号：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 停止/恢复演练仍未执行。

任务编号：D7 / 本机外部依赖健康检查
完成日期：2026-09-09
新增文件：tools/dependency_health_check.py
执行命令：python tools/dependency_health_check.py
结果：redis=True；neo4j=ok；milvus=ok。
说明：仅为连通性检查，不等于故障注入、降级和恢复演练；PyMilvus 输出第三方 API 弃用警告。

任务编号：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；四类配置审计。
> 后续变更（2026-09-10）：**取消双人复核**。单管理员部署下允许创建人自审，数据库约束
> `chk_config_release_separation` 已由迁移 `20260910_drop_review_separation` 撤下。
> 上面这行描述的"创建人不能审核自己"是当时的行为，已不再成立。
修复缺陷：回滚前先 flush 释放 active_slot；回滚状态使用基线允许的 superseded；自增实体不再显式写 id=0。
数据库变更：无。

任务编号：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 通过。

任务编号：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。

任务编号：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 绑定，仍需数据库集成测试。

任务编号：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。

任务编号：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 轮询数据库并受最长连接时间限制。
未完成项：真实客户端断流测试、外部依赖故障演练和性能基线。

任务编号：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。
数据库变更：无；测试数据已清理。

任务编号：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；测试数据完成清理。

任务编号：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；不同消费者不误领事件。
未完成项：死信重放、真实数据库提交失败回滚、并发唯一冲突压力测试。

任务编号：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 迁移、唯一冲突并发测试、死信重放。

任务编号：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 仍在进行中，不增加未经统计的整体百分比。

任务编号：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、缓存失效、完整专项集成测试

任务编号：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 文档生成，已记录生成脚本和审计脚本

任务编号：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 集成测试待补；统一错误映射待补
阻塞与决策：无