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 状态。 主集成分支是 qyqy_develop（ZSY 的客服接入线已由 PR #7 合入，见 docs/36）； 客服/RAG 那条线的个人分支是 NL_develop（个人分支 → PR 合回 qyqy_develop），不要再用 6516ccb。 它是对"当前状态"最准确的一份，读完它再读下面这些。

🖥️ 前端（2026-09-14 修订）：正式前端在 app/static/portal/，由 app/main.py 挂载， 通过 /portal/ 访问（/ 与 /portal/ 都 307 跳到 /portal/guest/home/）。 实际是 6 个角色目录（原写"四套页面"已过期，漏了投顾与运营两个）：

目录	角色	子页面
guest/	访客（免登录）	home/、products/、product-detail/
customer/	客户	login/、dashboard/、orders/、transactions/、holdings/、cash-ledger/、profit-loss/、risk-questionnaire/
employee-console/	平台管理员	login/、workspace/
employee-risk/	风控专员	dashboard/
employee-advisor/	投顾	dashboard/
employee-operations/	运营（场外／推广／NL2SQL）	dashboard/、nl2sql/、offsite/、promotion/

⚠️ employee-advisor/ 与 employee-console/ 是两个不同角色，不是改名关系，别合并。 访客公开产品页已由 app/api/controllers/public_platform.py 的 /products 等端点供数， 不再是 common/mock-data.js。端点表集中在 common/api-client.js，改接口调用请改那一份。 启动：python -m uvicorn app.main:app --port 8000（注意模块级变量是 app，不是 application）。 tools/portal.py（8101）只是跨角色联调工具，不是产品前端，不要再往它加功能。

🚀 一键启动与演示（2026-09-13 起）：不想敲命令就直接双击桌面的 启动金融Agent平台.bat（仓库里也有一份 启动平台.bat）。它按序做六件事： 找解释器 → 检查 MySQL/Redis/Milvus → 刷新行情 → 起 API 与 Agent Worker 两个窗口 → 等 API 真正应答 → 自动开浏览器。重复双击是安全的（API 按端口、Worker 按进程判断， 不会起第二份）；参数可透传，如 启动平台.bat -Port 8100、-NoBrowser、-SkipPriceSync。 bat 由 python tools/make_launcher_bat.py 生成（改完 start.ps1 或想换路径就重跑它， 桌面与仓库两份一起更新）—— 不要手写那个 bat，它必须同时满足 GBK 编码 + CRLF 换行 + 无 BOM， 缺任何一条 cmd 都会解析错乱（LF 换行会把 echo 的说明文字当命令执行， 实测报 AT 命令已弃用、']' 不是内部或外部命令）。 也可以直接用脚本：powershell -ExecutionPolicy Bypass -File start.ps1。 演示数据一键准备：python tools/seed_demo_data.py（10 步，顺序有依赖，见脚本内表格）； 演示流程（8 个场景照读版 + 排障表 + 账号速查）见 docs/44-演示流程.md； 交付自检（两条线互补，都跑一遍）： python tools/e2e_smoke_test.py（业务链路冒烟：登录→下单→成交、风控扫描→处置闭环、客服问答与转人工工单处置闭环，6 条线 44 项，--read-only 不动数据）； python tools/portal_api_check.py（接口契约体检：按前端的方式调每个端点，核对状态码、信封形状与字段是否与前端期望一致，41 项；--write 加测写操作、--dangerous 再加测会改生效配置的操作）。 ⚠️ start.ps1 必须保存为 UTF-8 with BOM：Windows PowerShell 5.1 在缺 BOM 时按系统 ANSI（简中为 GBK）解析，中文注释直接抛 Unexpected token '[璀﹀憡]' 这类语法错误。 用 edit/write 类工具改完务必补回 BOM（只加字节、别重写换行： d=open(p,'rb').read(); open(p,'wb').write(b'\xef\xbb\xbf'+d)）。 ⚠️ 解释器探测必须实测「能 import 依赖」，不能只看 --version 成功： 曾经因此选中一个 Python 3.10 环境（本项目用 datetime.UTC，3.11+ 才有，且依赖 asyncmy）， 报错却发生在行情刷新那一步，看起来像"行情源坏了"。现在的门槛是 版本 ≥ 3.11 + import fastapi, sqlalchemy, asyncmy, pydantic 通过。 另注：... 2>&1 | Select-Object -First 1 会掐断上游 native 进程、把 $LASTEXITCODE 弄脏， 在探测循环里用它会把每个候选都判成"无法执行" —— 先接住输出再取行。 ⚠️ 行情有效期只有 15 分钟（app/service/trade_service.py 的 MAX_QUOTE_AGE）， 超时后**所有委托一律 503「行情已过期」**且无自动刷新 —— 这是演示最容易翻的一环。 补刷用 python tools/sync_market_prices.py，立即生效、无需重启服务。

⚠️ 文档现状（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 张表"（实为 89 张业务表）、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 忽略、不进仓库，不存在"需要统一"的问题）。

• 数据库现为 90 张表（含 alembic_version）＝ 89 张业务表 = 场内 51 + 场外/推广 17 + 投顾 21。 后 38 张（offsite_* / promotion_* / advisor_*）不进 docs/00 基线（规则 8）： 场外/推广那 17 张逐表登记见 docs/28-场外与推广域数据表登记.md； 投顾那 21 张的登记文档待补（按同样口径另立一份）。 核验命令：python tools/audit_schema.py（若报 unexpected 先分清是"库里多表"还是"迁移没进来"）。

• ⚠️ 画像有两个存储，别只找 MySQL：值在 MySQL（fin_customer_profile / profile_snapshots / fin_risk_assessment / user_facts，唯一真相），关系在 Neo4j（Customer 节点 + Tag/Product 等，单向、幂等、可重建的派生视图）。图不一致时一律以 MySQL 为准 （python tools/reconcile_graph.py <customer_id> [--repair]）。设计细节见 docs/23（已与代码对齐）。

• 已注册业务 Agent（7 个，见 app/service/agent/implementations/ 与 app/service/agent/）： FundQueryDemoAgent、CustomerServiceAgent、RiskAgent、PlatformProbeAgent、 AdvisorAgent、OffsiteFundAgent、PromotionMaterialAgent。

• 已注册公共只读工具：search_knowledge（客服知识检索）、check_suitability、query_customer_profile（画像）、query_fund_quote； query_knowledge 是 search_knowledge 的别名（同一 handler，为兼容一期发布配置与旧客户端保留，见 bootstrap.py）； 其余业务线工具（风控、投顾、NL2SQL）按各自 Agent 白名单注册，全部在 bootstrap.py 的 get_agent_factory() 里。 工具可用范围 = 代码上限 ∩ 当前 active config_release 的发布白名单，缺发布配置则失败关闭。

• ⚠️ RBAC 权限码的定义源是 tools/seed_test_rbac.py 的 PERMISSIONS（9001-9065 号段，共 65 条）： 那个脚本是 DELETE 重建语义（DELETE FROM sys_permission WHERE id BETWEEN 9001 AND 9099）， 没并进它的权限码重建一次就没了，表现是"接口突然 403"而没有任何报错线索。 tools/grant_*.py 只补种子里缺的，且 id 必须与种子逐条一致 —— 一致性由 python tools/check_rbac_seed_consistency.py 及其单测守着 （2026-09-12 曾因两套 id→code 映射并存，让 advisor 在种子重建后静默拿到语义错误的权限）。 号段演进（改这里之前先看这段）： 9001-9017 一期公共；9018-9034 客服二期/投顾；9041-9046 产品治理与候选审核 （9035-9040 与 4041-4046 从未建过，9041 是把冲突的 9020-9035 挪走的修正结果，见 docs/36）； 9047-9050 风控告警四个；9051-9056 推广／NL2SQL／探针； 9057-9059 投顾客户范围三项；9060-9065 账户与交易看板六项（2026-09-12 后追加，AGENTS.md 旧写的「9046」已过期）； 9066-9068 投顾代客三项（*:customer 变体，服务层按 customer_id == context.user_id 动态拼出来， 对账工具抓不到字面量，曾是"投顾一操作客户就整片 403"的根因）； 9069 客服转人工工单处置 handover:write（2026-09-14 补：此前只有 handover:read， 状态机 pending→assigned→processing→resolved→closed 一个动作都没有入口，40 张单子全停在 pending； 用 tools/grant_handover_write_permission.py 幂等补齐，只授给 admin）。 另注：sys_user 已改为「存在则更新、不存在才插入」，故重跑种子不会再弄丢演示密码。

• ⚠️ config_release 是环境数据，不随代码合并：本机 active 版本 id 与架构师环境不同 （本机是我方发布的客服白名单；他那边还有风控的白名单）。"白名单已发布"必须带环境限定，换环境要重发。 ⚠️ 常被误读的一点：「架构师环境有风控的 9 条白名单」说的是那台环境 config_release 里的 9 个 agent_tools 配置项，不是代码里的常量——别去仓库里找"9 条"这个对象 （本机发布脚本 tools/publish_risk_agent_config.py 只发 4 条：3 工具 + general 空）。 发布脚本 tools/publish_customer_service_config.py：同 key 的继承项必须被本次定义覆盖， 否则旧值会被子集校验 422 拦下整次发布；继承范围必须覆盖全部三张受管表 —— 它此前只搬 platform_config_item，把 customer_service_chitchat 提示词静默漏在了旧版本里 （Agent 侧有代码默认值兜底，所以功能看着正常、零告警）。现已改用 ConfigReleaseService.effective_snapshot() 并在激活后硬校验条数，不符即失败退出。 另：知识类意图要同时发 search_knowledge（登录客户走）与 query_knowledge （访客令牌只有 knowledge:query），缺哪一条对应人群就一问即失败。

• ⚠️ Milvus 集合 schema 也因环境而异：本机是 knowledge_id/snippet（无 visibility）， 架构师环境是 doc_id/content/visibility/chapter…。检索层已改为运行时探测字段名 （app/core/knowledge_schema.py）——不要在任何地方硬编码字段名，那会把另一套环境打挂。

• ⚠️ 客服/风控对话必须有常驻 Worker：python -m app.worker。Agent 请求是 「受理 202 → Worker 领单 → 落结果」三段式；没有 Worker 时 agent_run 会一直停在 status='queued'、worker_id 为空，而前端只显示"客服响应超时 / 客服繁忙"—— 看起来像链路慢，实际是没人处理（2026-09-13 访客浮窗"回答超时"就是栽在这里）。 排查第一步：查 agent_run 最新那行是不是 queued。反过来，跑验收脚本前又要 先停掉它，否则会抢队列（见 docs/20）。 本机实测（Worker 在跑 + deepseek-flash）：访客一问端到端 4.1–4.8 秒， 其中受理只占 0.05 秒，其余是一次意图分类加一次 embedding 检索。

• ⚠️ Docker Desktop 不会常驻：它没运行时 Milvus 不可用（docker CLI 报连不上守护进程）。 跑真机验证前先确认 Docker Desktop 在运行。

• ⚠️ memory_sync_outbox 的取值必须是小写英文（milvus/neo4j、upsert、 pending/failed/processed/dead）。docs/00 §6.4.6 那一栏曾写作大写 MILVUS/NEO4J、UPSERT + 中文 待处理，与全仓实现从未对齐，照它写会静默失效： 消费端按 handlers.get(target_store) 分派、且只领 status in {"pending","failed"}， 大写 + 中文两个条件都不满足 ⇒ 事件任何消费者都领不到、永久滞留且不报错 （唯一键 (event_uuid, target_store) 对大小写无约束，MySQL 也不报错）。 取值口径以主干既有读取方为准（projection_reconciliation_service.py、 graph_projection_worker.py），不是文档。详见 docs/37-记忆投影链路实现说明.md。

• ⚠️ 一张表只能有一个 ORM 类：app/model/ 下曾出现两个类都映射 profile_snapshots （profile.py 与 risk_questionnaire.py），各自单独导入都没事，同时导入即抛 InvalidRequestError: Table 'profile_snapshots' is already defined for this MetaData instance —— Worker 既要重建画像又要处理投顾问卷，因此真的被打挂过（库里 memory_sync_outbox 留下 last_error='InvalidRequestError' 的行）。2026-09-12 已修为 re-export，见 docs/37 §6.2。 新增模型前先搜一遍 __tablename__ 有没有被占用。

• ⚠️ 记忆可读范围只有一个判定口径：app/core/memory_scope.py（2026-09-14 收敛）。 此前三处各自判断且口径不一：governance.recall() 把 int(context.user_id) 当客户号、 BaseAgent.recall_memory() 要求"每条记忆的 customer_id == context.user_id"、 review_output() 的引用校验只认同一条件。后果有两个，方向相反但都致命： ① 员工身份（风控／投顾／运营／管理员／system）恒空；② 越权陷阱 —— 员工号与客户号同号段（演示数据里客户 9001-9020、员工 9002/9020 并存）， int(user_id) 撞上真实客户号就会读到陌生客户的长期记忆并注入提示词，且不报错。 现口径：客户身份只读自己；员工身份只读 sys_customer_assignment 分配给自己的客户 （context.customer_ids，由 IdentityRepository.load_context() 读入），归属未维护即 失败关闭并在日志点名原因；归属客户按客户号升序、单次上限 MAX_RECALL_CUSTOMERS=10。 改召回、改引用校验、改范围守卫，三处必须一起走这个模块（单测 tests/unit/core/test_memory_scope.py + tests/unit/service/test_agent_governance.py 守着）。 遗留：风控扫描上下文是 user_id="0"/roles=("system",) 且无归属行，因此仍读不到记忆 —— 根因是召回发生在 handle() 之前、上下文里没有"本次目标客户"，见 docs/演示用/记忆召回恒空-根因与修复-2026-09-14.md §5.4。

• ⚠️ 长期记忆的 Milvus 集合名是一个代码级常量，不是配置项： app/infrastructure/milvus_profile_projection.py 的 PROFILE_COLLECTION （user_long_term_memory_v1），写（投影）／读（bootstrap.get_vector_memory_adapter）／ 删（projection_cleanup_service）三侧共用。曾经读/删两侧读的是 settings.milvus_collection （.env 里 jr_memory，该集合从未被创建）：MilvusClient 构造不校验集合存在， 于是适配器"构造成功"但每次 search 抛异常被吞成 degraded ⇒ 语义召回恒 milvus_unavailable；清理则走 vector_collection_absent 分支 ⇒ 报成功却一个向量都没删。 已删除 Settings.milvus_collection 并把三侧锁到同一常量（Settings 的 extra="ignore" 让环境里残留的 MILVUS_COLLECTION 被安全忽略）。 回归守卫：tests/unit/infrastructure/test_memory_vector_collection_consistency.py —— 这类缺陷之所以能活下来，就是因为两侧单测全绿而接缝没人守。

• 测试基线（2026-09-13 合并组员前端提交之后实测）： mypy app → 249 个文件 0 错； pytest tests/unit tests/contract → 1376 passed, 2 skipped, 0 failed； pytest tests/integration → 104 passed； python tools/audit_schema.py → 89 张业务表。 ⚠️ 用例数会随开发增减，判断健康看"0 failed"而不是看绝对值。 2026-09-14 复测（记忆链路修复后）：pytest tests/unit tests/contract → 1445 passed, 2 skipped, 1 failed；mypy app → 255 个文件，3 个错 （均在组员新提交的文件里，与本次改动无关：agent_persistence_service.py:82 的 Any 未导入、run_query_service.py:79 实参类型不匹配、promotion_renderer.py:84 元组长度不匹配）；ruff check app tests tools alembic hq.py → 16 个错，同样全在 组员新文件里（promotion_renderer.py 行长/zip(strict=)、run_query_service.py 导入未排序、tools/probe_memory_state.py 无占位符 f-string 等）。 唯一失败用例是 tests/unit/api/test_portal_frontend.py::test_advisor_workspace_registers_documented_operation_endpoints —— 组员正在改投顾页面（该页已被整体替换成自包含静态页，不再走 api-client.js/app-shell.js），故未擅自改动，交付前需与组员确认这页是否 还应注册 docs/05 的端点表。 说明：agent_persistence_service.py:82 的 Any 未导入只是局部变量注解， 运行时不求值（已实测不会 NameError），属静态检查级问题。 另：tests/unit/service/test_offsite_document_recognition_adapter.py 有 2 个用例在某些环境 会失败 —— 它们断言请求体里是中文原文，而 httpx 会把中文序列化成 \uXXXX，属环境相关， 不要"修"实现；真要修应改为断言 json.loads(body) 后的字段值。

• mypy：mypy app → Success: no issues found in 249 source files（0 错）。 ⚠️ 曾在本机报 184 个错，已查明是环境版本旧，与代码质量无关 —— 复现矩阵：

  SQLAlchemy	mypy	报错数
  2.0.34（本机旧）	1.14.1	173
  2.0.34	1.20.2	173
  2.0.52	1.14.1	6
  2.0.52	1.20.2	0（当前）

  ⇒ 主因是 SQLAlchemy 的补丁版本（旧补丁版类型标注不完整，BIGINT/DATETIME 被判成未类型化 函数，app/model/*.py 每个列定义报一条）。出现"一边上百个错、另一边 0 错"时先对版本， 别当代码质量问题；根因是某一侧的虚拟环境没满足 pyproject.toml 的 sqlalchemy>=2.0,<3 / mypy>=1.14,<2。 不要装 sqlalchemy2-stubs —— 那是给 SQLAlchemy 1.4 用的，2.0 自带 py.typed， 装上会按 1.4 API 核对 2.0 代码、换一批新错（mapped_column / DeclarativeBase 不存在）。 pyproject.toml 的 sqlalchemy>=2.0,<3 允许范围内补丁版差异会造成量级差异； 若门禁数字要求稳定，需把 SQLAlchemy 钉到具体补丁版（属公共约定，改前先问）。

• ⚠️ MILVUS_LOCAL_URI 配了就会"看着正常、查的是另一个库"：一旦在 .env 里设置它， 健康检查与部分检索链路会指向本地 Milvus Lite 文件。团队/生产环境请保持该变量为空。 对应的 milvus-lite 属本地开发依赖，应放在 pyproject.toml 的 optional-dependencies，不要进主 dependencies。

• 集成测试前置（不跑这两步，tests/integration 会有 13 个登录/RBAC 用例因 401 而红， 容易被误判成代码缺陷）：先 python tools/seed_test_rbac.py（角色/权限/演示账号）， 再 python tools/set_user_password.py（演示口令，非幂等：重复执行等于重设密码）。 接口联调清单见 docs/32-平台侧交接与联调准备.md；主干 PR #7 合并的逐项证据见 docs/36-PR7合并记录与权限号段修正.md。