group_fqcd_jr/AGENTS.md

项目级开发约束

以下规则对人工开发者和编码 Agent 均为强制约束：

1. 数据库以 docs/00-新数据库基线设计.md 为不可变业务基线。
2. 允许创建新表，允许在已有表中增加新字段。
3. 禁止重命名或删除已有表。
4. 禁止重命名、删除、复用已有字段，禁止改变已有字段的类型、可空性和既有业务含义。
5. 历史结构无法满足新需求时，使用新增字段、新表、兼容视图或应用双读解决。
6. 架构固定使用 MVC+S；Agent 属于 Service 层。
7. 业务 Agent 必须继承公共 BaseAgent 并由 AgentFactory 创建，不得绕过公共鉴权、记忆、模型路由、工具、合规、审计和事件流程。
8. 当前系统业务功能只针对场内基金模拟交易；场外基金运营流程独立，不得写入场内交易表。

修改数据库文档或迁移前，必须对比基线并证明没有改变任何已有表名和已有字段定义。

---

📖 接手先读（按此顺序，只读这些就够）

⭐ 第 0 步先读这个：docs/superpowers/handoff/2026-09-11-交接文档-客服Agent与RAG收尾.md —— 客服 Agent + RAG 这条线的交接文档（含合并完成后的第二次更新）：环境口径、交付内容与 可复现验证证据、合并后修掉的 3 个真机故障、已知问题清单（逐条标注当前状态）、Git/PR 状态。 当前工作分支是 NL_develop（个人分支 → PR 合回 qyqy_develop），不要再用 6516ccb。 它是对"当前状态"最准确的一份，读完它再读下面这些。

⚠️ 文档现状（2026-09-11 第二次修订）：本文件原先声明"已删除 5 份编号文档"， 那条已作废 —— 经评审，docs/04/06/10/13/99 全部保留（架构师明确要求保留： 删除收益为零，而保留成本同样为零）。它们的内容未被核对过、可能过期， 因此列在下面的 D 类"不要用来判断当前进度"里，只作历史参考。 被删除的只有 10 份过程产物，理由与清单见 docs/superpowers/ARCHIVE-2026-09-11-文档清理归档.md。

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 为准。
docs/04 / 06 / 10 / 13 / 99	内容未核对过、可能过期（自相矛盾 / 结论失效 / 清单不全）。经 2026-09-11 评审保留（不再删除），仅作历史参考。不要用它们判断现状

E. 环境与命令口径（易错点）

• 解释器：本机用 .\.venv\Scripts\python.exe；架构师环境用 D:\conda\envs\jr_py313\python.exe。 两者等价，各用本机可用的那个（.venv 被 .gitignore 忽略、不进仓库，不存在"需要统一"的问题）。
• 数据库现为 69 张表（含 alembic_version）＝ 68 张业务表 = 场内 51 + 场外/推广 17。 后 17 张（offsite_* / promotion_*）不进 docs/00 基线（规则 8：场外基金运营流程独立）， 逐表登记见 docs/28-场外与推广域数据表登记.md。核验命令：python tools/audit_schema.py。
• 已注册业务 Agent：FundQueryDemoAgent、CustomerServiceAgent、RiskAgent、PlatformProbeAgent（见 app/service/agent/bootstrap.py）。
• 已注册公共只读工具：search_knowledge（客服知识检索）、check_suitability、query_customer_profile（画像）、query_fund_quote； 工具可用范围 = 代码上限 ∩ 当前 active config_release 的发布白名单，缺发布配置则失败关闭。
• ⚠️ config_release 是环境数据，不随代码合并：本机 active 版本 id 与架构师环境不同 （本机是我方发布的客服白名单；他那边还有风控的 9 条白名单）。"白名单已发布"必须带环境限定，换环境要重发。 发布脚本 tools/publish_customer_service_config.py（同 key 的继承项必须被本次定义覆盖，否则旧值会被子集校验 422 拦下整次发布）。
• ⚠️ Milvus 集合 schema 也因环境而异：本机是 knowledge_id/snippet（无 visibility）， 架构师环境是 doc_id/content/visibility/chapter…。检索层已改为运行时探测字段名 （app/core/knowledge_schema.py）——不要在任何地方硬编码字段名，那会把另一套环境打挂。
• ⚠️ Docker Desktop 不会常驻：它没运行时 Milvus 不可用（docker CLI 报连不上守护进程）。 跑真机验证前先确认 Docker Desktop 在运行。
• 测试基线：1 failed, 1034 passed, 2 skipped（2026-09-11 实测）；唯一失败是 tests/unit/repository/test_fund_readonly_contract.py（底座既有缺陷，不要修也不要报）。
• mypy：本机 mypy app 报 181 个错，其中 170 个集中在 app/model/ 的模型文件（本机未安装 sqlalchemy2-stubs， SQLAlchemy 的 BIGINT/DATETIME 被判成未类型化函数）；架构师环境报 0 错。 这个数字双方不可比，不要拿它当结论；只需保证"不比自己改动前更多"。