模块 1 · Richards/Ford 映射

别只说「微服务」
架构有四张底牌

说 JinRong「有四个 Agent」只描述了结构（Structure）。完整架构还要写清： 架构特征、 架构决策（不变量）、 设计原则。

四 Agent = 结构；共享底座 = 特征与决策

结构

客户 / 顾问 / 问数 / 风控 分路由；不互调 LLM，走画像表与平台 API。

特征（Top 3）

合规可审计 · 归属隔离 · 可演示可运维（Redis/ready/会话）。

决策

审计只 INSERT；问数仅 SELECT；仅 R-02 可阻断交易；各 Agent 一套 JWT。

原则

同步 HTTP 默认；deny/clarify 不调 LLM；L0 正式测评优先于 L1 措辞。

第一定律： 一切都是 trade-off。例如 fail-open 吊销 vs 更严安全——MEMORY 里已拍板，改前要对表。

数据流：一次客户问话经过谁

🖥前端
🚪chat.py
⚖编排+阀门

点「下一步」——指挥 AI 改 Chat 时，先对号入座在哪一层

MEMORY 禁止项（节选） 
四 Agent 不互调 LLM
audit_log 等审计表（只 INSERT）
各 Agent 自建第二套 JWT/RBAC
风控自动冻户 / 改正式风险等级
白话

这些是不变量：AI 说「加个 Agent 直连另一个 LLM」——先拒绝，除非新 ADR/拍板。

「帮运维 UPDATE 审计表」——违反 G-02，应追加新记录而不是改历史。

答辩说「我们架构是四 Agent 微服务」缺什么？

模块 2 · 第二定律

ADR
Why 比 How 重要

拓扑图只回答「怎么连」。拍板表、spec、测试日志才是本项目的 ADR 等价物——否则同一决策会Groundhog day反复吵。

ADR 五段（书第 19 章 → 本项目写法）

Title

例：1B 数据查询违禁词处理

Context

客服数据类回复不能乱承诺；又不能误转人工。

Decision

We will 回退 fact_text，不自动 transfer（customer+visitor 共用）。

Consequences

用户体验略硬；合规风险下降；需单测 sanitize 路径。

Compliance

pytest + 客服验收用例；改 sanitize_postprocess.py 必跑。

群聊：拍板怎么落到代码

落点 
docs/memory/MEMORY.md  §3 拍板表
docs/superpowers/specs/*.md
docs/memory/tests/**/TEST-LOG-*.md
app/utils/sanitize_postprocess.py
白话

让 AI 写功能前：先问「有没有 ADR/拍板？」没有就补 Context+Decision 再写代码。

Email-driven architecture = 只在聊天里说过，MEMORY 没写——后人必踩坑。

问数 guard 修缺口 A/B，最好同时更新什么？

模块 3 · 决策 vs 原则

不变量、原则
和降级不是一回事

不变量：过不了就拒或走唯一规定路径。 原则：多种写法都合法，但优先选 A。 降级：依赖坏了仍要服务，但不能悄悄突破不变量。

对照表（指挥 AI 时用）

不变量

问数仅 SELECT；审计只 INSERT → 失败时 DENY

原则

Bearer 优先于 debug 头 → review / 文档纠偏

降级

1B fact_text；Redis 会话 fail-open → 能力缩水，规则仍成立

客户线 1B：不是「放行违禁」，是换安全出口

分支 
数据查询 intent + 违禁词
  → finalize: 回退 fact_text
RAG/闲聊 + 违禁
  → COMPLIANCE_REJECT（仍不 auto transfer）
白话

降级 = 仍合规地回答问题，不是 ignore 过滤器。

若 AI 建议「违禁就删 sanitize」——违反不变量，应拒绝。

哪项属于「允许的设计降级」？

假阀门： 问数曾用「SQL 里出现 customer_id 字符串就算有过滤」——探针证明仍可能全表泄露。不变量必须在语义上可测。

模块 4 · Ensure compliance

Fitness function
阀门装在哪一层

书里的「确保合规」不是开更多会——是把规则写进pytest、guard、ready、仓储凭证，让 busy 的开发者也绕不过去。

分层阀门（JinRong）

入口

deps.py / platform auth · JWT + 归属

领域

sanitize_postprocess · analyst deny 不调 LLM

执行前

sql_guard.validate() · 表白名单

仓储

RiskListAccess · ThresholdWriteAccess

基建

Redis connect timeout · GET /api/ready

Flow：问数 deny 探针

🧪pytest
🛡sql_guard

LLM 会「碰巧写对」——fitness function 不能赌模型

ready 
GET /api/ready
  → Redis ping
  → 关键路由存在（close-all / 问数…）
web DevReadyBanner 提示旧后端
白话

运维才显现：后端没重启、Redis 没起——功能像「坏了」；ready 是环境 fitness。

指挥 AI：「加不变量」= 加 guard + 加 test，不是加 README 一句「请勿越权」。

新增「问数禁止查 risk_alert 全表」应优先？

模块 5 · 客户财富 Agent

合规特征
落在 LangGraph 出口

结构：customer_service.py 14 节点 + Tool + Milvus。 特征：无投资建议/收益承诺/自动下单。 阀门：sanitize_postprocess + L0 优先 + C-05/C-11 意图边界。

拍板 → 不变量（节选）

  • C-05：最新净值快照 OK；「实时净值/走势预测」reject
  • C-11：可买/匹配说明 OK；「稳赚推荐」reject
  • L0 优先：槽位与正式测评冲突时听 L0
  • 1B：数据类违禁 → fact_text（见模块 3）
流式 
POST /api/chat/stream
  session_id 续聊 · 落库 insert_turn
  needs_disclaimer 首帧 meta
sanitize 在 finalize 出口
白话

改 prompt 很容易；改出口阀门才保证每条回复过合规。

会话 active/close-all 是运维显现类决策——前后端版本不一致会「删不掉」。

客户问「实时净值涨跌」应？

模块 6 · 数据分析 Agent

数据不变量
在 sql_guard 不在 prompt

结构：独立 analyst_agent（非 chat StateGraph）。 特征：仅 SELECT、域隔离、deny 可审计。 ADR：2026-09-11-query-interpret-split-design.md（问数 vs interpret 拆分）。

Least worst：不追求万能 NL2SQL

模板 + 白名单 16 表 + guard 探针 = 可答辩的最小可靠组合；自由 SQL 靠 prompt 是软设计。

数据推论（书）： 最重要决策常跟「谁能看哪张表、哪一行」有关——TEST-AN-001 修的就是这个。
guard 
sql_guard.validate(sql, role, domain)
  → 表白名单
  → ROW_SCOPED 归属 WHERE
deny/clarify → 不调 LLM 解读
白话

指挥 AI 加表：同时改 guard、模板、MEMORY 白名单说明、探针。

「inject_ownership 定义了但零调用」= 决策写了 enforcement 未接——典型 vitality 债。

假阀门长什么样？

模块 7 · 风控监测 Agent

R-02 与纵深
API 不够还要仓储凭证

结构：service/risk/* + 预警表 + simulate 网关。 不变量：仅 R-02 阻断交易；禁止自动冻户/改正式等级。 运维显现：cron 脚本无 UI、仓储单层防线（TEST-RISK-001 F1）。

Risk storming 在本项目的影子

  • sandbox_risk_test.py · 演示 SOP · FR-8~10 扩展
  • 合规矩阵 F2/F3：production 通道是否可达
  • repo_access.RiskListAccess：列表查询凭证
禁止 
MEMORY: 风控自动冻户
MEMORY: 改正式风险等级
Agent 处置预警（问数仅 SELECT）
R-02 → simulate / suitability 链
白话

新 API 绕过 risk_repository 鉴权 = 纵深缺口；fitness = 矩阵测试 + E2E。

escalation_scan 无 UI = 运维才运行的架构量子外圈。

F1 类问题指什么？

模块 8 · 运维与结构

Service-based 单体
运维才显现的债

本书的 microservices 不是目标——我们是模块化单体 + 清晰 Agent 边界（像 service-based：少量服务域 + 共享 Agent 库）。 Connascence：改 02-mysql-agent专用.sql 可能牵动风控+问数。

四块映射（共用模块）

鉴权 deps ∥ gateway

决策：一套 JWT；模块禁止 import gateway。Fitness：auth pytest。

平台 API

决策：与 Agent 重复时 platform 为准。Dashboard 每次打 MySQL（性能 trade-off）。

顾问 Agent

未完整接入：无独立深编排 · T-20 未做 · Chat 骨架在 · 答辩勿作主 Demo。

前端 web/

决策：四角色路由；TODO 路由守卫。Vitest 22；E2E 未进库。

运维 checklist（演示 ≠ 产品）

①

Redis 6380 · uvicorn 含 close-all · 前端强刷

②

GET /api/ready + DevReadyBanner

③

手跑 escalation_scan / rebuild_alerts（无 UI）

④

Architecture vitality：CHAT/E2E 未跑项见 TODO

「清空会话无效」最常先查？

结业句： 指挥 AI 时带四问——不变量？阀门？fitness？ADR 里 why 写了吗？