5.9 KiB
5.9 KiB
项目级开发约束
以下规则对人工开发者和编码 Agent 均为强制约束：
- 数据库以
docs/00-新数据库基线设计.md为不可变业务基线。 - 允许创建新表，允许在已有表中增加新字段。
- 禁止重命名或删除已有表。
- 禁止重命名、删除、复用已有字段，禁止改变已有字段的类型、可空性和既有业务含义。
- 历史结构无法满足新需求时，使用新增字段、新表、兼容视图或应用双读解决。
- 架构固定使用 MVC+S；Agent 属于 Service 层。
- 业务 Agent 必须继承公共
BaseAgent并由AgentFactory创建，不得绕过公共鉴权、记忆、模型路由、工具、合规、审计和事件流程。 - 当前系统业务功能只针对场内基金模拟交易；场外基金运营流程独立，不得写入场内交易表。
修改数据库文档或迁移前，必须对比基线并证明没有改变任何已有表名和已有字段定义。
📖 接手先读（按此顺序，只读这些就够）
⭐ 第 0 步先读这个：
docs/superpowers/handoff/2026-09-11-交接文档-客服Agent与RAG收尾.md—— 2026-09-11 收尾会话的交接文档：环境口径、本次交付内容与可复现验证证据、 6 个"单测绿但真机挂"的静默故障、8 条已知问题清单、Git 未提交状态。 它是对"当前状态"最准确的一份，读完它再读下面这些。2026-09-11 做过一次文档清理：已删除 5 份编号文档（
04/06/10/13/99）与 10 份过期过程产物。 删除理由与内容去向见docs/superpowers/ARCHIVE-2026-09-11-文档清理归档.md。 下面这 17 份是清理后剩下的，均已核对过内容正确性。
A. 核心 7 份（无论接手哪条线都必读）
| 序 | 文档 | 承载的唯一权威内容 |
|---|---|---|
| 1 | docs/00-新数据库基线设计.md |
不可变业务基线：表/字段业务语义的唯一来源 |
| 2 | docs/05-接口文档.md |
接口唯一权威：信封/错误码/幂等/SSE、§8.3 知识库管理三端点、§8.4 四个只读工具索引与两段式白名单 |
| 3 | docs/01-通用Agent平台开发设计.md |
MVC+S 分层约束、BaseAgent 执行骨架、AgentFactory |
| 4 | docs/02-数据库建表设计.md |
51 张业务表总览 + DDL + §8 幂等与 Outbox 语义 |
| 5 | docs/03-平台端到端流程文档.md |
一次请求从受理→Worker→审计→事件的全链路与降级矩阵 |
| 6 | docs/08-数据库结构审计基线.md |
三个审计工具 + migration_state_check 的职责；"证明未改基线"的证据出处 |
| 7 | docs/07-测试问题修复记录.md |
无替代：P0-1/2/3 鉴权与 Worker 租约闭环、P1-1~P1-5（含 api_request_receipt 事务幂等） |
B. 按角色补充
| 你接手的是 | 再读这些 |
|---|---|
| 客服 Agent + RAG 这条线 | docs/14（接入入口）→ docs/18（RAG 三集合路由方案）→ docs/19（可运行示例）→ docs/09（底座用法与四工具） |
| 整个底座 | 补 docs/20（第一版→当前的破坏性改动 + §5 四条尚未修复的偏差 + "跑验收前先停常驻 Worker"） |
| 只改某个业务域 | docs/00 → docs/05 → docs/02 → docs/14 → docs/19；行情加 docs/12，前端/联调加 docs/17 |
| 看"现在做到哪了" | docs/验收与审计/phase1-acceptance-report.md（Phase 1 七条验收标准的逐条可复现证据）+ 同目录 phase1-acceptance-criteria.md（老师验收标准原文摘录） |
注：完整的过程台账（
progress.md、各 Task 报告、审计报告）在.superpowers/sdd/2026-09-10-客服Agent与RAG-qyqy版/， 但该目录被.gitignore忽略（属工作区过程产物）—— 因此结论性文档已复制到docs/验收与审计/以保证 git 可见。 若要查过程细节再去看.superpowers/；日常接手只需读本文档列出的这些。
C. 同主题的重复文档（读一份即可，避免信息冲突）
| 主题 | 唯一权威 | 重复品（仅历史参考） |
|---|---|---|
| Agent 组员接入 | docs/14 |
docs/11（旧版说明书）、docs/15（详细手册）、docs/16（入门易懂版）—— 三份已各自在开头标注"以 14 为准" |
| 接口说明 | docs/05 |
docs/17（易懂版，自述"不替代 05"） |
D. ⚠️ 不要用来判断"当前进度"
| 文件 | 为什么 |
|---|---|
TODO.md |
自 2026-09-09 起未随 Phase 1 更新：5 处"49 张表"（实为 51 张业务表）、T8.1 客服 Agent 整节未勾选但已交付、多处标"进行中"其实已完成。当前进度一律以 phase1-acceptance-report.md 为准。 |
| 已删除的 5 份 | docs/04（历史评审评分）、docs/06（正文与附录自相矛盾）、docs/10（结论已整体失效）、docs/13（工具清单不完整）、docs/99（已废弃规范） |
E. 环境与命令口径（易错点）
- 解释器固定
.\.venv\Scripts\python.exe。不是conda activate jr_py313、不是D:\conda\envs\jr_py313（旧文档里有这些残留写法，已修正主要几处）。 - 数据库现为 52 张表（含
alembic_version）＝ 51 张业务表。核验命令：.\.venv\Scripts\python.exe tools\audit_schema.py。 - 已注册业务 Agent：
FundQueryDemoAgent、CustomerServiceAgent（见app/service/agent/bootstrap.py）。 - 已注册公共只读工具：
check_suitability、query_fund_quote、query_knowledge、query_customer_profile；工具可用范围 = 代码上限 ∩ 当前 activeconfig_release的发布白名单，缺发布配置则失败关闭。 - 测试基线：
1 failed, 804 passed, 2 skipped（2026-09-11 实测）；唯一失败是tests/unit/repository/test_fund_readonly_contract.py（底座既有缺陷，不要修也不要报）。 - mypy 基线 151 个错（
mypy app）——接手时不要让它变多。