前言
关于 coding agent，有个普遍的误解：以为门槛在"让它动起来"。
调个模型接口、把几个工具塞进提示词，半天就能跑通一个能读写文件、执行命令的 demo。动起来这一步，早就不值钱了。
真正值钱、也真正难的，是动起来之后：上下文说着说着就爆了；模型对着报错硬说成功了；读个配置文件顺手把密钥发上云；跑着跑着陷进死循环烧光 token。这些不是"调一调"能解决的，它们是 agent 区别于聊天机器人的那道分水岭------能不能跨过去，全看工程治理。
DeepSeeker-Code 是我填这些坑的一次完整实践：跑在本机、DeepSeek 驱动的 coding agent，VS Code 插件、终端 CLI、HTTP 服务三个入口共用一个大脑。已经开源：github.com/xknk/deepSe...。
这篇不聊功能清单，只聊我在这道分水岭上做的几个关键取舍------为什么这么选，赚到了什么，又牺牲了什么。说到底，一个 agent 好不好，就是由这些取舍决定的。
一、三端一脑：一份引擎，喂饱三个入口
VS Code、终端、HTTP，三个入口怎么安排，是最早的纠结。
常规做法是把核心拆成一个 npm 包，三个入口各自依赖它。我没这么干，而是把引擎（我叫它 core）直接焊进了三个入口的产物里，用 esbuild 打包、tsconfig 路径别名引用。它不是被依赖进去的，是被编译进去的。
为什么这么干？core 还在天天改。一旦拆成独立包，三个入口就会各自锁一个版本，很快出现插件修了 bug、CLI 还在犯的割裂，用户也得纠结"哪个壳配哪个版本"。内联就没这问题，三端永远是同一份代码，改一处全生效。再加上共享同一个本地数据目录，同一个项目的会话在三端之间能无缝接上。
当然有代价：core 没法被别人当库引用了，构建链也复杂不少。这是拿可复用性换一致性。
它独特在哪？多数多入口产品都爱标榜"核心库加多个壳"的优雅解耦。我反着来，承认这东西还在野蛮生长，干脆选了强耦合，换三端铁定一致的踏实。
二、给 DeepSeek 量体裁衣：不做"模型无关"的通用 agent
很多 agent 框架爱强调一个词：模型无关。意思是换个模型也能跑。我没追这个，我这套治理逻辑是照着 DeepSeek 的脾气调的。
上下文压缩这种事，通用框架按教科书比例来就行。但 DeepSeek 有自己的脾气：本地估 token 和真实 token 有固定偏差，它还有隐式前缀缓存，命中能省一大笔。按通用假设来会怎样？要么压缩总慢半拍，以为还安全其实快爆了，最后靠接口报错兜底；要么该吃缓存红利的时候，一个压缩把缓存全打穿。
所以我做了两件事：拿每轮的真实 token 用量去校准本地估算；压缩时机看缓存命中率的脸色，命中率高就推迟压缩接着吃红利，低才早点压。
赚到了什么？长任务跑得稳，token 花在刀刃上。
代价也明确：换个模型，就得重新摸它的脾气、重新调一遍。这套东西跟 DeepSeek 绑得挺死。
独特在哪？别人都奔着"换个模型也能跑"的通融去，我偏只对 DeepSeek 负责。用通用性换针对性，对本地工具来说，我觉得划算。
三、不信任它的自报告：把"防模型犯傻"做成一等公民
跟模型打交道久了会认清一个事实：它会骗你，也会犯傻。
跑命令明明报错了，它可能选择性无视，回头告诉你"成功了"；它会陷进同一个调用来回横跳，把 token 烧光也不收手。
我的理念是：别指望模型自己老实，工程层必须兜底。
所以工具协议里有个字段叫 verifyResult，工具底层自己分析这次的输出，硬判成功还是失败。一旦判失败，我会在喂给模型的结果里强行插一句"系统判定：执行失败，别盲目乐观，老老实实看报错"。再加上死循环熔断、轮数自收敛和兜底上限，都是同一个路子。
赚到了什么？不用人盯着的自动化，才敢真的放手。模型最常犯的那几类傻，被硬拦在了协议层。
代价是：每个工具都得单独写判定逻辑，维护成本不低；硬编码判定偶尔也在边界上犯难，一个 warning 算不算失败，得斟酌。
独特在哪？多数框架的工具就是一个执行函数，跑完拉倒，信不信模型随你。我把"防模型犯错"提到了协议层，当成每个工具定义时就得想清楚的一等公民。
四、人和模型是两类观众：别用一份输出两头不讨好
这条最想单独说。一个工具跑完，产出给谁看？
答案是既给人看，也给模型看。但他俩要的东西完全不一样。最俗的例子：跑个 npm install，终端能刷出两千行下载进度。用户想看那个动画，模型只想知道一句"装好了 45 个包"。两千行原样喂给模型，它的注意力被噪音淹没；只喂一句结论，用户又看不到过程，干巴巴。
所以工具可以把输出分成两路：一路给人，生动、流式、有动画；一路给模型，干净、简短、只要结论。
赚到了什么？模型脑子清醒，用户该看的也没少。一份输出两头不讨好的尴尬没了。
代价是：输出嘈杂的工具，得多写一道分流；那些输出本就干净的简单工具，这层就是多余负担。
独特在哪？多数 agent 是一锅端，拿到啥既给人看又喂模型，两头凑合。我把终端呈现和上下文喂料显式拆开了。
五、两道边界：云端大脑的数据安全，和单人本地的克制
最后说两道边界，一道数据，一道产品。
第一道，数据。 DeepSeek 是云端模型，意味着 agent 读的每个文件、跑的每条命令的结果，都得发出去。那它读到你的 .env、读到数据库密码怎么办？我的处理是脱敏：含密钥的内容发往云端之前，按规则换成星号。本地该怎么用怎么用，云端只见打码。
实话实说，这是治标。数据终究出了本机，不如纯本地模型彻底；脱敏规则也得维护，漏了新型密钥、误伤了正常内容，都是可能的坑。但它至少拔掉了"用云端大脑干本地活"这个形态最尖的那根刺。
第二道，产品。 我从一开始就给它定了性：单人本地工具。不做公网部署，不做多租户，不做 SaaS，也不背 OS 级沙箱那套服务端的包袱。HTTP 服务只开在 127.0.0.1，当个本地的程序化入口。
为什么这么克制？产品形态决定门槛。单人本地，"让用户敢放手用"比"多租户隔离"重要得多。省下来的复杂度，我全投到了 agent 本身的体验上------审批、脱敏、Undo 回退，都围着"敢不敢让它放手干"这一个目标做。
代价也摆在明面上：它天然不支持团队协作，安全上限就是单机水平。这是主动取舍，也是实打实的局限。想拿它搭团队平台的，趁早别看。
结语
做完这玩意儿，我越来越觉得：agent 这东西，门槛不在"能跑起来"，在"跑起来之后好不好用、敢不敢用"。
调个接口、塞几个工具进提示词，半天就能让它动起来。可上下文说着说着爆了、模型对着报错睁眼说瞎话、读个配置文件把密码发上云、跑着跑着死循环烧 token，这些才是真正吃功夫的地方。
而填这些坑，说到底全是在做取舍：拿通用性换针对性，拿可复用性换一致性，拿开发量换可靠性。每个设计都有它的代价，我只是选择老老实实接受这些代价，换我最想要的那点东西。
项目已经开源：github.com/xknk/deepSe...。要是对国产模型驱动的本地 coding agent 感兴趣，或者想看看 agentic 架构在工程上怎么落地，欢迎来看看，也欢迎提 issue。觉得有点意思，点个 star 就是对我最大的鼓励。
总结
- 三端一脑：一份引擎内联进三个入口，牺牲可复用性，换三端永远一致、会话无缝互续；
- 为 DeepSeek 量体：治理逻辑照着 DeepSeek 真实特性调，牺牲通用性，换长任务稳定、token 花在刀刃；
- 不信任模型自报告：把防幻觉、防死循环做成工具协议一等公民，牺牲开发量，换敢放手自动化的可靠；
- 人和模型两类观众：工具输出显式分两路，牺牲简单工具的简洁，换模型清醒、用户也尽兴；
- 两道边界：云端大脑做数据脱敏（治标但拔了最尖的刺），单人本地做产品克制（不背服务端包袱，也不支持团队协作）。