一条成本焦虑
长成架构宪法

痛点与洞察：成本焦虑撞上现成的省钱机制

1.1 先回答「为什么」

读 Reasonix 的源码之前，先读它的 README。中文 README 开篇没有讲“我们的 Agent 多聪明”，而是先把产品位钉在成本上（README.zh-CN.md:42-43）：

面向终端的 DeepSeek 原生 AI coding agent。
由配置与插件驱动的极薄 harness——单一静态 Go 二进制，围绕 DeepSeek 的前缀缓存调优，长会话也能把 token 成本压低。

这不是营销话术，而是整套架构的出发点：

1. 痛点：长会话里 token 成本随轮次线性增长；DeepSeek 的定价让“一直聊下去”变贵。
2. 现成机制：DeepSeek 自动做前缀缓存——只要请求前缀字节稳定，命中的部分就能打折。
3. 洞察：省钱的钥匙不是“少调用模型”，而是“让前缀一直命中”。于是 cache 从「优化项」升格为「架构约束」。

flowchart LR
    P["痛点：长会话 token 成本高"] --> I["洞察：DeepSeek 自动前缀缓存<br/>前缀稳定 = 命中 = 省钱"]
    I --> C["约束：系统前缀必须字节稳定"]
    C --> D["推论：易变内容外移 turn tail<br/>工具 schema 稳定 · 压缩明码标价 · miss 可诊断"]

1.2 三个可验证的工程主张

1.3 这条约束被写成了「宪法」，而不是注释

仓库自己的 standing instructions（REASONIX.md:14-16）：

- Cache-first: the system-prompt prefix (base prompt + tools + memory) must stay
  byte-stable across turns so DeepSeek's automatic prefix cache stays warm. Never
  mutate it mid-session — ride the turn tail instead (see `control.Compose`).

甚至 PR 模板强制要求 Cache-impact / Cache-guard 元数据（REASONIX.md:64-71）。
本系列里只有 Hermes 的「前缀缓存神圣」能对上劲；Reasonix 的差别是把它焊进了 Go 运行时诊断 + CI 脚本，让“不许打破缓存”成为可执行的协作纪律。

产品位与动机证据：README / REASONIX / SPEC 里的原话

2.1 动机证据表

2.2 产品经理视角：它在卖什么体验

🧠 一句话：别家在优化「工具调用多聪明」；Reasonix 在优化「同一次会话里，前缀到底能不能一直命中缓存」——并把这件事当成不能违约的产品契约。

仓库地图与技术栈：数字形状与依赖方向

3.1 数字化的项目形状（基线 627b051）

docs/SPEC.md 给出的布局契约：

cmd/reasonix/main.go          # 入口；blank-import providers + builtin tools
internal/
  cli/                        # 子命令、装配、退出码
  control/                    # 传输无关 Controller（所有前端的背后）
  agent/                      # Session + harness 循环 + compact + cache shape
  provider/                   # Provider 接口 + openai/anthropic/responses
  tool/ + tool/builtin/       # Tool 接口 + init() 自注册
  permission/                 # allow / ask / deny + bash 分解
  sandbox/                    # OS 沙箱封装
  memory/ · instruction/      # 背景事实 vs standing instructions
  plugin/ · mcp* / capability # MCP / 能力代理
  checkpoint/ · evidence/     # 变更回滚与交付证据
  acp/ · bot/ · desktop*      # 编辑器协议、机器人、桌面

依赖方向（docs/SPEC.md:54-56）：cli → {agent, plugin, config} → {tool, provider}；父包不 import 自注册子包。

3.2 技术栈

入口极薄（cmd/reasonix/main.go）：

// Blank imports wire compile-time built-ins into their registries.
_ "reasonix/internal/provider/anthropic"
_ "reasonix/internal/provider/openai"
_ "reasonix/internal/provider/responses"
_ "reasonix/internal/tool/builtin"

3.3 与 Claude Code / Hermes / Codex 的关系

若只记一句：Reasonix = Hermes 的 cache 哲学 × Codex 的工程硬度 × Claude Code 的终端 coding 品类，焊在 DeepSeek 的自动前缀缓存上。

开发者思维导图：从「前缀必须稳定」到十项设计

这一章是整篇的“地图”：先看开发者脑子里那根主轴，再进代码。下面十项都能从「前缀必须字节稳定」推出；每一项也都有明确的代价。

Cache-first 宪法：稳定前缀 vs turn tail

5.1 两条轨道

Controller.Compose（control/input.go:137-212）把这件事写进注释（input.go:181-183）：

Memory added mid-session rides the turn (never the cached system prefix),
so it takes effect now without invalidating the prompt cache. It folds into
the system prefix on the next session, where it costs nothing per turn.

装配顺序（概念上）：

flowchart TB
    IN["用户 text"] --> G{"有 running goal?"}
    G -->|是| GB["activeGoalBlock + autoResearch"]
    G -->|否| P
    GB --> P{"planMode?"}
    P -->|是| PM["PlanModeMarker"]
    P -->|否| L
    PM --> L["response/reasoning language 包装"]
    L --> M["drainPending → memory-update"]
    M --> J["background-jobs note"]
    J --> H["hook context"]
    H --> R["memory.recall Block（真实 user turn）"]
    R --> OUT["交给 Agent.Run"]

这与 Open Design「按缓存频率分带装配 system prompt」、Hermes「记忆写盘立即生效、下个会话才进提示词」是同一哲学族。Reasonix 的独特处是：把 miss 诊断成结构化事件，而不是只靠文档告诫。

5.2 PrefixShape：为什么 miss？

// PrefixShape hashes the portions of the request prefix that influence
// provider-side prompt-cache reuse. Comparing snapshots across turns
// lets us explain *why* a cache miss happened.
type PrefixShape struct {
	SystemHash        string
	ToolsHash         string
	PrefixHash        string
	LogRewriteVersion int
	ToolSchemaTokens  int
}

CaptureShape 会对 tool schema 排序后再哈希（normalizeToolSchemas），避免“顺序抖动”假 miss。CompareShape 给出 system / tools / log_rewrite 原因列表，并带上 usage 里的 cache hit/miss tokens。

发往 provider 前还会剥掉会打冷缓存的 UI 元数据：LocalOnly 显示记录不进 ModelMessages（provider.go 的 LocalOnly 标记），墙钟与取消半截流都不会污染前缀。

5.3 与 MCP 动态工具的张力

动态 mcp__* 工具一旦进主 Registry，就会改 tools 哈希 → 冷缓存。Reasonix 的解法（docs/TOOL_CONTRACT.md:45-96）：

• Delivery / Planner / 多数 sub-agent：暴露固定名代理工具 use_capability（list / inspect / call / decline）；
• 按需连 MCP 不改变该代理的 provider-visible schema；
• Balanced 的 Executor 刻意保留直接 mcp__*（接受可能的前缀变化）——这是有意识的产品取舍，不是疏漏。

🧠 承重墙：Cache-first 不是「尽量少改 prompt」，而是「哪些变化允许付 cache miss 的税」被显式分类：steer 付税、memory-update 不碰 prefix、MCP 库存变化用代理隔离。

双模型为何必须分 session

6.1 动机

想要“先规划后执行”的成本/质量平衡，但模型切换会破坏前缀。

6.2 约束与选择

docs/SPEC.md:238-240 把话挑明：

switching models inside one shared conversation would break the prefix and tank cache hits, so we don't.

配置了 planner_model 时，Planner 与 Executor 各有独立 session（agent/coordinator.go）：两套前缀各自 cache-stable，会话永不混写。这与 UI 上的 Plan Mode（turn-tail marker）不是同一层。

6.3 代价

• 双份前缀、双份工具面，首轮成本更高；
• 规划期发现的能力必须在 handoff 后仍可直接 call（use_capability 的固定代理正好承担这件事）；
• 路由更复杂：executor_only | plan_and_execute | plan_for_approval | plan_only（planner_route.go）。

主循环：Agent.Run → runToolLoop

7.1 生命周期入口

Agent.Run 自己说得很清楚（注释始于 agent.go:1310，函数体 1319-1378）：

1. 解析本轮 maxSteps（可被 context 覆盖）；
2. 开 workspace lease / steer 队列 / background evidence 提交 defer；
3. interceptAgentStart（extension 可 abort）；
4. beginRunTurn 初始化状态；
5. return a.runToolLoop(ctx, state)。

没有神秘的「框架基类」——就是显式状态机，策略拆在 beginRunTurn / handleFinalResponse / handleToolRound。

7.2 runToolLoop：一轮里发生什么

核心循环在 run_loop.go:274-355：

sequenceDiagram
    participant U as User / Controller
    participant A as Agent.runToolLoop
    participant P as Provider.Stream
    participant T as executeOne(s)

    U->>A: Run(input)
    loop step = 0..maxSteps
        A->>A: consumeSteer?（写入 session，可接受一次 cache miss）
        A->>A: CaptureShape(system+tools)
        A->>P: streamWithMissingReasoningRecovery
        P-->>A: text + reasoning + tool_calls + usage
        A->>A: CompareShape → cache diagnostics
        alt 无 tool_calls
            A->>A: handleFinalResponse（含 maybeCompact）
        else 有 tool_calls
            A->>T: handleToolRound → 并行只读 / 串行写入
            T-->>A: tool results 写入 session
        end
    end
    A-->>U: maxStepsPause 或 error 或 nil

几个味道很重的细节：

7.3 装配入口：boot.Build → 同一 Runner

boot.Build（internal/boot）一次性冻结 system prefix（output style、环境探针快照、memory、skill 索引），再把可选 planner_model 包成 Coordinator。

7.4 单工具执行管线

executeOne（execute_one.go:65-101）是固定五段：

1. parseToolCall — Resolve、歧义 MCP 名、重复成功/失败 loop guard、stale-anchor 编辑拦截；bash 可按参数降级为只读（permission.BashCommandIsReadOnly）；
2. interceptToolBefore — extension 可改写调用；
3. resolveToolPolicy — 权限门禁；
4. prepareToolExecution — 预览、mutation 记账、parent write 锁；
5. finishToolExecution — 真正执行 + 回执。

只读工具可并行，写入串行——与 Claude Code / OpenAI4S 的「只读波次」同族，但落地在 Go 的 mutation observer / evidence ledger 上。

Compose：把易变内容赶进 turn tail

8.1 动机

系统前缀要字节稳定，但 goal、plan、语言偏好、记忆更新、检索结果每轮都可能变。

8.2 约束

凡是不稳定、不必要时不出现的内容，都不能进 cache-stable prefix。

8.3 被否方案

• “把所有动态内容都拼进 system prompt”：省事但每轮冷缓存，直接违背宪法；
• “动态内容完全不进上下文”：goal/plan/记忆更新无法即时生效。

8.4 选择

control.Compose（control/input.go:137-212）在真实 user turn 前按固定顺序装配：activeGoalBlock → PlanModeMarker → 语言包装 → <memory-update> → background-jobs → hook context → memory.recall Block。

8.5 代价

• 每轮多一次装配与剥离（StripComposePrefixes）；
• 若前端/扩展绕过 Compose 直接发消息，缓存宪法会被破坏——所以所有前端都走同一 Controller。

压缩三阶梯：soft → snip → summary（明码标价的缓存重置）

compact.go:20-37 把策略钉死：

设计要点：

• 触发用比例，保留用绝对 token 预算——大窗口不会过度压缩，小窗口也不会卡在阈值附近反复 compact；
• Summary 用结构化标题（Standing facts / Goal / Decisions / Files / Commands / Errors / Pending），包在 <compaction-summary> 里；
• Ablation 开关可关掉 cache 友好策略做对照实验（internal/ablation）；
• Compact 会 bump LogRewriteVersion → CompareShape 会标 log_rewrite——诚实承认这是 cache 重置点。

与 Raven「无损归档」、Claude Code「摘要丢弃」相比：Reasonix 明确站在 「先廉价 snip，再付一次 summary 的 cache 税」 这一边。

工具 ABI：builtin + MCP + use_capability 固定代理

10.1 Compile-time builtins（契约表）

docs/TOOL_CONTRACT.md 由测试守护（TestBuiltinToolContractDocumentation），与运行时 registry 同源。核心面：

实现侧全部 init() { tool.RegisterBuiltin(...) }（如 builtin/readfile.go:27）。

10.2 全量 boot 表面 vs Economy

默认 full-token boot 还挂 session / memory / skill / subagent / LSP / install / slash 等：ask、task/fleet/parallel_tasks、memory/remember/forget、run_skill、LSP 四件套、explore/research/review/security_review 等（docs/TOOL_CONTRACT.md）。

Delivery 另加：

• use_capability：稳定 MCP 代理；
• review_report：中高风险变更的结构化 review；
• Host 侧 evidence：verification / diff / files / manual，无证据的 complete_step 直接拒绝。

Economy 刻意只暴露瘦面（约 ask/bash/read_file/write_file/edit_file/后台三件套 + connect_tool_source），其余按需挂载——用「一次看不全工具」换 token 与前缀稳定。

10.3 Tool 接口味道

工具带 ReadOnly、预览（Previewer）、图像、PlanMode 分类等能力位——权限与并行调度读的是这些位，而不是靠模型「自觉」。Checkpoint 只跟踪带 Previewer 的编辑工具（见第 12 章）。

权限、沙箱、工作区围栏：应用层规则 × OS 围栏

11.1 Permission Policy + Ask / Auto / Yolo

permission.Policy（permission.go）：

• 规则形态对齐 Claude Code：Tool / Tool(glob) / legacy Tool=literal（ParseRule）；
• Decide(toolName, readOnly, args)；bash 走分段分解（DecomposeBashCommand）；
• BashCommandIsReadOnly：把「schema 上可写的 bash」在具体 argv 上降成只读（影响并行、mutation、evidence）；
• BashSubjectRequiresExplicitApproval：间接执行、危险 git 等强制显式批准。

产品审批模式（docs/TOOL_APPROVAL_MODES.md）与 collaboration mode（normal/plan/goal）正交：

另有 internal/guardian：独立安全评审子会话（带 denial circuit breaker）——不能代替记忆写入的用户确认。Hooks（internal/hook）提供 PreToolUse/PostToolUse/PostToolUseFailure，并做 Claude 工具名兼容映射。

11.2 Sandbox + confine

builtin/bash.go 把命令包进 sandbox.Command：

enforce 但无后端时 fail closed（不裸跑）。escape 走 sandbox.EscapeApprover。MCP stdio 默认不继承 Bash sandbox（internal/plugin/plugin.go 的产品默认是 host 进程，注释写明原因）。

SECURITY.md 把边界写清楚：workspace 围栏、权限、沙箱、密钥、HTTP serve 的 localhost/CORS、桌面/bot 隔离、updater 校验——以及什么不算漏洞。

11.3 Checkpoint / Rewind

对齐 Claude Code Esc-Esc / /rewind 叙事（docs/CHECKPOINTS.md）：

• 机制：文件快照（非 git）；sidecar <session-id>.ckpt/；
• 跟踪范围：带 Previewer 的编辑工具（write_file / edit_file / multi_edit）；
• 不跟踪：bash 副作用；move_file 尚未实现 Previewer；
• API：Controller.Checkpoints / Rewind / PrepareRewind+CommitRewind（含 coverage confirmation）；
• 明确不做：git-backed rollback（文档标 out of scope）。

Checkpoint / Delivery / Goal：交付证据与完成协议

12.1 正交三轴

docs/GOAL_ENFORCEMENT.zh-CN.md 开篇：

Goal 是唯一的跨 turn 调度器，Delivery 是纯质量门禁，工具权限与沙箱不受 Goal 开关影响。

模型通过 update_goal(continue|complete|blocked) 申报意图；宿主用结构化 ReadinessResult（agent.go:1497+）决定是否真完成。宣称 complete 但缺证据 → 开启下一轮，而不是信模型嘴硬。

12.2 complete_step

内置工具描述写得很凶（TOOL_CONTRACT.md）：completion 必须带 evidence；host 代为推进 todo。这与 grok-build Goal Mode、MiMo「不信任自我报告」同谱——Reasonix 用 host-observed receipts 落地。

12.3 协作 Profile

（docs/COLLABORATION_MODES.zh-CN.md）

control.Controller：一张脸接所有前端

13.1 设计铁律

REASONIX.md:11-13：

One transport-agnostic control.Controller sits behind every frontend (chat TUI, HTTP/SSE serve, Wails desktop). Add behavior to the controller, not a frontend, so all three inherit it.

实际还有 ACP / bot 等入口。统一装配：boot.Build → Controller → agent.Runner（或 Coordinator）。

13.2 一次用户消息的路径

flowchart LR
    TUI["chat_tui"] --> SUB["Submit / Send"]
    HTTP["serve HTTP/SSE"] --> SUB
    DESK["Wails desktop"] --> SUB
    ACP["ACP"] --> SUB
    SUB --> ADM["admitGuardedTurn<br/>防重入 / park"]
    ADM --> COMP["Compose(turn tail)"]
    COMP --> RUN["Coordinator? → Agent.Run"]
    RUN --> EVT["event.Sink<br/>reasoning/text/tool/notice"]
    EVT --> TUI
    EVT --> HTTP
    EVT --> DESK

关键 API 族（controller.go）：Send / Submit / SubmitHTTP / SubmitDisplay / RunTurn / Goal 循环变体；runGuarded 做 turn admission，避免双开跑飞。

13.3 为什么 Controller 会变成 6k 行巨文件？

因为它吞下了：会话恢复、checkpoint、memory slash、MCP 生命周期、capability、steer fallback、yolo/plan、attachments、goal usage……所有前端共享的产品行为。代价是文件巨大；收益是「修一处，TUI/桌面/HTTP 一起对」。本系列里 OpenAI4S 的 gateway.py、Codex 的 turn.rs 同属「巨心脏」形态。

记忆、指令、扩展、桌面/ACP

14.1 Context Engine v2：指令 ≠ 记忆

docs/SESSION_MEMORY_RETRIEVAL.md 的中心法则：

• Standing instructions（REASONIX.md / AGENTS.md / CLAUDE.md + .local + 祖先目录 + 全局）：必须出现在相关 turn；进 cache-stable prefix；
• Background memory：可过时的事实；BM25 auto-recall（默认 defaultAutoRecallLimit=4、defaultAutoRecallChars=2400）进 turn tail；索引在下个会话才并入 prefix；
• #note / /remember 写指令文件；remember 工具写背景事实——不要混用；
• 安全写入：部分 scope create-only；其余需确认——Auto/Yolo/Guardian 不能绕过；
• 指令解析：更深目录覆盖更广；同目录 .local 胜出；@path 导入限 5 层且禁止逃逸。

14.2 三层扩展：MCP · Plugin Package · Extension Protocol v1

MCP 与 Extension 是不同层：前者接工具/资源，后者接宿主生命周期拦截。Full-trust Extension 是独立攻击面，也是「Open Design 式公开合约」在 Reasonix 里的最硬落地（docs/EXTENSION_PROTOCOL.md）。

14.3 Subagent profiles

Skill frontmatter runAs: subagent（docs/SUBAGENT_PROFILES.md）：内置 explore / research / review / security_review；CLI reasonix subagent …；调用走 /<profile> 或 task/fleet + write_paths 并行写隔离。默认并发 max_subagent_concurrency=6、max_parallel_writers=3。Claude 插件 agents/*.md 可映射为 /<plugin>:agent:<name>。

14.4 桌面与 ACP

• Desktop（desktop/）：嵌套 Wails 模块（保持父模块 CGO_ENABLED=0）；React+TS webview ↔ 同一 Controller（无 HTTP hop）；
• ACP（internal/acp，docs/ACP.md）：reasonix acp [--profile …]；NDJSON JSON-RPC；loadSession + embeddedContext；能力广告 无 image/audio；MCP http: true、sse: false；vendor 扩展含 _reasonix.io/session/steer；
• VS Code 扩展 SivanLiu.reasonix-agent 拉起本机 reasonix acp；
• Remote-SSH / workbench：基线 PR #7368 reconnect hardening——产品已从本地 TUI 长到远程工作台。

十项决策五段式复盘

横向对比（编程 Agent 桌）

诚实边界

• 巨文件成本：controller.go / chat_tui.go / agent.go 均数千行，新人 onboarding 陡；
• DeepSeek 优先税：reasoning 恢复、cache 假设对其他网关不一定成立（有兼容路径，但产品心智仍偏 DeepSeek）；
• Executor 直接 MCP：Balanced Executor 仍可能因 MCP 库存变化冷缓存——文档已承认；
• Windows Bash OS sandbox：产品固定 unconfined；文件工具仍有 confinement；
• Checkpoint 覆盖面：不跟踪 bash 副作用；无 git-backed；move_file preview 未完成；
• Extension full trust：安装即最高权限——能力强，威胁模型需用户理解；
• MCP long tail：OAuth、list_changed、部分 scopes 等仍 deferred（docs/SPEC.md:877）；
• ACP 能力广告：无 image/audio；agent 侧 MCP SSE 收窄；
• 旧分支：v1 仅关键修复；分析/二次开发应对齐 main-v2。

源码导览索引与本地复现

本地复现：

cd "参考项目/DeepSeek-Reasonix"
git fetch origin main-v2
git checkout main-v2
git reset --hard 627b051
# 可选：跑契约测试（需本机 Go）
# go test ./internal/tool -run TestBuiltinToolContractDocumentation

附录 A · 与本系列「Agent 工程模式目录」的对照

附录 B · 一句话收束

Reasonix 不是「又一个 Go 写的 Claude Code 仿制品」。
它把 DeepSeek 的自动前缀缓存，从费用边角料提升为架构中轴：Compose 分流、Shape 诊断、Capability 代理、PR 元数据、Delivery 证据——全部绕着「别把缓存打冷」转。若你在本系列里已经理解 Hermes 的 cache 神圣与 Open Design 的分带装配，读 Reasonix 就是看同一种哲学在 Go 单二进制 coding agent 里被执行到什么硬度。

附录 C · 开发者动机还原：从「成本焦虑」到「架构宪法」

第 1、2、4 章已经把动机链展开；这里保留一张浓缩对照表，方便回看。

分析基线：参考项目/DeepSeek-Reasonix @ 627b051（main-v2）。
系列位置：编程 Agent 样本；与 Hermes（cache）、Codex（沙箱正交）、Claude Code（品类）最近邻。

附录 A · 与本系列「Agent 工程模式目录」的对照

附录 B · 一句话收束

Reasonix 不是「又一个 Go 写的 Claude Code 仿制品」。
它把 DeepSeek 的自动前缀缓存，从费用边角料提升为架构中轴：Compose 分流、Shape 诊断、Capability 代理、PR 元数据、Delivery 证据——全部绕着「别把缓存打冷」转。若你在本系列里已经理解 Hermes 的 cache 神圣与 Open Design 的分带装配，读 Reasonix 就是看同一种哲学在 Go 单二进制 coding agent 里被执行到什么硬度。

附录 C · 开发者动机还原：从「成本焦虑」到「架构宪法」

第 1、2、4 章已经把动机链展开；这里保留一张浓缩对照表，方便回看。

分析基线：参考项目/DeepSeek-Reasonix @ 627b051（main-v2）。
系列位置：编程 Agent 样本；与 Hermes（cache）、Codex（沙箱正交）、Claude Code（品类）最近邻。