DeepSeek-Reasonix · 中文源码精读教程

DeepSeek-Reasonix · 中文源码精读教程

契约驱动:以 SPEC 工程契约为纲领,拆解一个 DeepSeek 原生调优的 AI coding agent

这本教程讲什么

这是一份带读源码的 DeepSeek-Reasonix(简称 Reasonix)精读教程。

Reasonix 是一款 DeepSeek 原生调优的终端 AI coding agent——Claude Code / Gemini CLI 的同类产品,MIT 协议,作者以中国开发者为主的社区(esengine 等),版本 1.20.0。它不是 DeepSeek 官方模型仓库,而是一个第三方构建的、以 DeepSeek 为首选 provider 的通用 coding agent 框架;任何 OpenAI 兼容端点都可作为配置项接入。

Reasonix 的核心定位是**"由配置与插件驱动的极薄 harness"——单一静态 Go 二进制(CGO_ENABLED=0),围绕 DeepSeek 的前缀缓存(prefix cache) 调优,以压低长会话的 token 成本。它最独特的工程贡献是"prefix-cache 友好的上下文维护"**:系统提示前缀必须字节稳定以保持缓存命中,旧工具输出先 snip/prune 再 compaction,新信息"ride the turn tail"追加到尾部而非破坏前缀。

💡 核心心法:Reasonix 自带一份 docs/SPEC.md 工程契约,开篇明义——"This document is the contract — code follows it. Change the contract first, then the code."(这份文档是契约,代码跟随它。先改契约,再改代码。)本教程以这份契约为纲领,契约先行,代码跟随——每章从 SPEC 的一条设计原则或核心抽象切入,讲清"契约怎么规定、代码怎么实现、有什么边界"。

本教程采用契约驱动式:自顶向下,从 SPEC §1 六条设计原则出发,经过配置体系、Provider/Tool 双接口注册表、Agent 会话主循环、prefix-cache 上下文维护(全书高潮★)、MCP+Extension 两层扩展、三前端共用单 Controller、子代理编排与安全,一直讲到 IM 机器人/SSH 远程/桌面全栈/发布。每章标注"对应的契约条款",保持契约主线连贯。

一张图看懂契约架构

SPEC 是一切的源头——设计原则约束布局,布局定义依赖方向,依赖方向承载核心抽象,核心抽象组装成 Agent,Agent 围绕缓存优化,缓存友好靠 Controller 统一三前端,扩展体系挂在接口上。

十章契约驱动路径

第 1 章 Reasonix 全貌与"薄 harness"哲学 ── SPEC §1 六条设计原则
第 2 章 配置体系:TOML 驱动一切 ── SPEC §2 Layout + 四级覆盖
第 3 章 Provider 接口与注册表 ── SPEC §3.1 Provider + Factory
第 4 章 Tool 接口与内置工具 ── SPEC §3.2 Tool + TOOL_CONTRACT
第 5 章 Agent 会话与主循环 ── Session + permission + checkpoint
第 6 章 ★ Prefix-cache 友好的上下文维护 ── REASONIX.md Cache-first
第 7 章 MCP 插件与 Extension Protocol ── EXTENSION_PROTOCOL
第 8 章 三前端共用单 Controller ── transport-agnostic Controller
第 9 章 子代理编排与安全 ── fleet + sandbox + guardian
第 10 章 IM/SSH/桌面全栈/发布 ── BOT_GUIDE + Remote + production
​

第 6 章 prefix-cache 上下文维护(★)是全书高潮——这是 Reasonix 区别于其他 coding agent 的灵魂。

章节目录

第 1 章 Reasonix 全貌与"薄 harness"哲学
Reasonix 是什么;SPEC §1 六条设计原则(配置+插件驱动核心/单静态二进制 CGO_ENABLED=0/精简依赖/两层扩展/接口优先注册表/演进不过度工程);与 Claude Code 对比;"薄 harness"哲学——核心只懂接口,具体模型和工具靠注册表按名解析。

第 2 章 配置体系:TOML 驱动一切
SPEC §2 Layout 依赖方向无环(cli→{agent,plugin,config}→{tool,provider});config 四级覆盖(flag>project>user>defaults);reasonix.example.toml 260 行精读(DeepSeek 预设/双模型 executor+planner/定价/工具启用)。

第 3 章 Provider 接口与注册表
SPEC §3.1 Provider interface(Name/Stream)+ Factory + Register/init() 自注册;openai 兼容实现;DeepSeek 预设;双模型协作(executor+planner 分别缓存稳定会话);任何 OpenAI 兼容端点只是配置项不是代码。

第 4 章 Tool 接口与内置工具
SPEC §3.2 Tool interface + Registry;内置工具(bash 用 mvdan.cc/sh 解析/edit/read/grep/glob/codeindex 用 tree-sitter 五语言语法树);TOOL_CONTRACT.md 工具契约;工具参数 JSON Schema 校验;工具批准模式(TOOL_APPROVAL_MODES)。

第 5 章 Agent 会话与主循环
internal/agent Session 生命周期 + harness loop;permission Policy(allow/ask/deny→Decision);checkpoint 检查点回放;repair 自动修复;REASONIX.md 项目记忆注入系统提示。

第 6 章 ★ Prefix-cache 友好的上下文维护
全书高潮:REASONIX.md "Cache-first" 契约——系统提示前缀(base prompt+tools+memory)必须字节稳定;boot 系统提示装配;control.Compose "ride the turn tail"(新信息追加尾部不破坏前缀);compact 上下文压缩;snip/prune 旧工具输出先裁剪再摘要;cache_shape 缓存形态;Context Engine v2 分层记忆检索(SESSION_MEMORY_RETRIEVAL)。

第 7 章 MCP 插件与 Extension Protocol
两层扩展:internal/plugin MCP stdio JSON-RPC 客户端(adapts remote tools);internal/extension Extension Protocol v1 sidecar(拦截运行时事件/提供 Provider/结构化 UI);Plugin Manifest v1 版本化插件包;sdk/go 第三方 Go 编写 sidecar;EXTENSION_PROTOCOL.md。

第 8 章 三前端共用单 Controller
REASONIX.md "One transport-agnostic control.Controller";internal/control 传输无关 Controller(所有前端共享);TUI(Charm bubbletea/lipgloss);HTTP/SSE serve(internal/serve);Wails 桌面(desktop/)。行为加到 Controller 而非前端,三者自动继承。

第 9 章 子代理编排与安全
internal/agent fleet/coordinator 多 agent 协作编排;SUBAGENT_PROFILES.md 子代理配置;sandbox 沙箱;guardian 守护/审查;planmode 计划模式;分支(branch)与缓存形态。

第 10 章 IM 机器人/SSH 远程/桌面全栈/发布
internal/bot IM 机器人(飞书 feishu/QQ/微信 weixin,BOT_GUIDE.md);internal/remote SSH Remote-SSH(forward 端口转发/sftpfs SFTP 文件层/bootstrap 远端 serve);desktop Wails+React 19+8 套主题;workers Cloudflare Workers(accounts/forum/crash-report);GoReleaser 六平台交叉编译+SignPath 签名;production_checklist;全书回顾。

适合读者

本教程适合对 AI coding agent 架构、Go 工程设计、LLM 推理优化(缓存)、插件体系、多前端架构感兴趣的开发者:

• 想理解 Claude Code / Gemini CLI 这类 coding agent 内部实现的开发者
• 对 Go"接口优先 + 注册表模式 + 依赖方向无环"工程设计感兴趣的 Go 工程师
• 对"prefix-cache 友好的上下文维护"这个 LLM 系统优化感兴趣的研究者
• 想学习 MCP 协议集成、插件 sidecar 通信、IM 机器人集成的实战派
• 想构建自己的 AI coding agent 或扩展现有 agent 的架构师

前置知识:

• Go 基础(能读懂 interface/struct/init()/channel/context)
• LLM 基本概念(prompt/completion/token/缓存,不必熟练)
• 可选:React 基础(第8/10章桌面部分会用)

关于源码版本

本教程对照的源码来自 DeepSeek-Reasonix-main-v2(MIT 协议,Reasonix Contributors),版本 1.20.0(2026-08-05)。核心 Go 代码位于 internal/(约 16.5 万行,40+ 包),桌面应用 desktop/(Go 后端 11.1 万 + React 前端 12.6 万),CLI 入口 cmd/,Go SDK sdk/go/,Cloudflare Workers workers/。工程契约见 docs/SPEC.md,项目记忆见 REASONIX.md。