docs: 显式化三档 agent 接入分层（MCP 直查 / CLI 管线 / artifact 交付）+ 场景化 cookbook

[2233admin]

背景

本项目核心两问（作为后续功能/文档取舍基准）：

1. 能不能让 AI 快速理解代码
2. 能不能让 AI 写代码时少写没必要的东西

评估了 TdxQuant（通达信量化平台文档：https://help.tdx.com.cn/quant/docs/markdown/mindoc-1cfsjkbf8f3is/ ）的工程设计，结论：架构层无可搬——领域不同（行情/交易数据面 vs 代码情报），且其强项本仓已有更严格等价物（"服务端预清洗即用数据" ↔ Repowise verified 索引；"先回测后实盘" ↔ preview-only edit plan / worktree blast radius #58 #86；响应信封元数据 ↔ MCP _meta freshness）。

唯一值得内化的是它的接入分层设计：TdxQuant 给 AI 平台三档接入（TQ-Python 写代码 / TQ-Local 免代码直取数据 / Lambda 提交远端系统执行），显式承认"agent 不该总写代码"。本仓事实上存在同构三档，但从未按分层讲清：

档位	本仓对应	服务的核心
免代码直查	repowise MCP（get_answer / get_context / get_symbol …）	快速理解代码：不跑管线、不读全文件
跑管线	code-intel CLI（audit / blast-radius / repin …）	全量分析、结构门禁
重交付	artifact handoff（audit report、retirement packet）	跨 agent / 跨会话交接

要做

1. skills/code-intel-pipeline/SKILL.md 与 README 增加"接入分层"一节：哪档回答哪类问题；何时禁止升档（MCP 能答就不 Read 全文件、不无谓重跑管线）。
2. 场景化 recipe 页（cookbook）：先覆盖三个最小场景——改代码前 / PR review / 清理扫除——每个给出工具调用序列。CLAUDE.md 的 "Compose them" 段落是现成雏形。
3. 每条 recipe 显式标注"这一步省掉了什么"（少读了什么、少写了什么），直接对齐上面核心两问。

不做

• 本地 HTTP JSON-RPC 常驻端口（TdxQuant 127.0.0.1:17709 式）：无鉴权本地端口与 sentrux gate / execution policy / capability inventory 的安全姿态冲突，MCP 已覆盖同一需求且带权限模型。
• 常量/契约单页字典（TdxQuant "常量枚举"页式）：暂缓，契约目前集中在 docs/*.md，散度不够不值得建生成器。

验收

• 新 agent 只读"接入分层"一节 + cookbook 即可正确选档。
• 典型误用（MCP 可答却全文件 Read、能直查却重跑管线）在 recipe 中被点名为反例。

[2233admin]

顺序与形态约束回填(来自文档计划审视)

1. 先真后增:docs: README/SKILL.md 不提 run execute / artifact query / change risk——CI 级全链路只活在 --help --all（冷启动 F1） #112(F1)/docs: README『输出在哪里』文件树与实际 content-addressed objects/sha256 布局不符（冷启动 F3） #113(F3)是入口文档在说假话,先修它们,再写本条 cookbook——否则新 recipe 建立在假入口上。
2. 形态:每条 recipe = 可执行命令 + eval 断言(eval: 北极星度量基准——正确率/token/diff 冗余度，管线 vs 裸读，模型无关回归门 #93 第 6 条已建此链接),不写散文。无断言背书的 recipe 出生即是下一批待砍库存(lifecycle: 规范阅后即焚——一次性 spec 自动归档 + 活契约绑测试 + stale-spec 门禁 #104 一次性类)。