1. 从 7.3k Star 说起：这个 Coding Agent Harness 到底在解决什么问题

第一次看到 ZCode 这个项目的时候，我正被手头一堆零散的代码生成任务折磨得够呛。当时团队里每个人都在用不同的方式调模型写代码，有人直接开聊天窗口复制粘贴，有人写了个脚本批量跑 prompt，还有人干脆手动改。结果就是同一个项目里，代码风格五花八门，上下文丢失严重，改到后面连最初的需求是什么都忘了。ZCode 这个项目在 GitHub 上拿到 7.3k Star 的时候，我特意去翻了一遍它的设计文档和 issue 区，发现它想解决的核心问题其实非常明确：给 Coding Agent 提供一个标准化的运行框架，让模型调用、上下文管理、工具执行、结果验证这几个环节能够串起来，而不是各干各的。

所谓 Coding Agent Harness，你可以把它理解成赛马场上的马鞍和缰绳。模型本身是那匹跑得很快的马，但如果没有一套合适的装备，你根本控制不了它往哪跑、跑多快、什么时候停。Harness 这个词在软件工程里本来就有“脚手架”“测试框架”的意思，放到 Coding Agent 这个场景下，它指的是包裹在模型外面的一层运行时环境，负责把用户的意图翻译成模型能理解的指令，再把模型的输出转化成可执行的操作，最后把执行结果反馈回去形成闭环。ZCode 之所以能拿到 7.3k Star，很大程度上是因为它把这层环境做得足够通用，既不像某些项目那样绑死在某一个模型上，也不像另一些项目那样只支持单一的操作系统或编辑器。

我仔细对比过市面上几个类似的方案，发现 ZCode 的定位很巧妙。它没有试图去做一个完整的 IDE，也没有把自己包装成万能的 AI 编程助手，而是老老实实地做中间层。这个中间层向上提供统一的接口给不同的前端调用，向下适配不同的模型提供商和工具链。这种设计思路在分布式架构里很常见，就是通过增加一个抽象层来解耦上下游，只不过 ZCode 把它用在了 Coding Agent 这个场景上。对于我这种经常需要在不同项目之间切换、用不同模型做实验的人来说，这种设计省去了大量重复适配的工作。

适合读这篇内容的人，我大致分了三类。第一类是正在做 AI 编程工具链的工程师，你们可能已经在用 LangChain 或者类似的框架，但发现它们对 Coding Agent 这个特定场景的支持不够细致，想看看别人是怎么处理上下文窗口、工具调用、错误重试这些脏活的。第二类是对 Agent 架构感兴趣但还没动手实践的技术爱好者，你们可能看过不少概念性的文章，但缺少一个具体的、能跑起来的参考实现。第三类是在团队里负责技术选型的人，你们需要评估 ZCode 这类方案能不能嵌入现有的开发流程，它的扩展性和维护成本到底怎么样。不管你是哪一类，接下来的内容都会围绕架构设计、核心模块、实操配置、问题排查这几个维度展开，尽量把我在实际使用和阅读源码过程中积累的经验都倒出来。

2. 架构拆解：ZCode 的分层设计与核心模块

2.1 为什么选择分层架构而不是单体设计

ZCode 的架构图第一次看的时候觉得挺复杂，但拆开之后发现它的分层逻辑非常清晰。最上面是接口层，负责接收来自命令行、编辑器插件或者 API 的请求；中间是调度层，处理任务队列、上下文管理和模型路由；最下面是执行层，对接具体的模型 API、文件系统、终端命令和版本控制工具。这种三层结构在微服务架构里很常见，但 ZCode 把它用在一个本地运行的 Agent Harness 上，好处是每一层都可以独立替换或扩展。

我举个例子来说明这种设计的好处。假设你一开始用的是某个云端模型 API，后来因为成本或者延迟问题想换成另一个提供商的模型，在单体设计里你可能需要改遍所有调用模型的地方，但在 ZCode 的分层架构下，你只需要在模型适配层新增一个 provider 的实现，然后在配置里切换一下就行。调度层和接口层完全不需要改动。这种面向接口编程的思路，在分布式系统里是基本功，但很多 Agent 项目为了快速出效果，往往把模型调用直接写死在业务逻辑里，后期维护起来非常痛苦。

另一个让我觉得设计合理的地方是上下文管理被单独抽成了一个模块。Coding Agent 和普通聊天机器人的最大区别在于，它需要维护一个不断增长的代码上下文，包括当前打开的文件、最近修改的记录、终端输出、错误日志等等。如果把这些东西都塞进模型的 prompt 里，很快就会超出上下文窗口限制。ZCode 的做法是维护一个上下文池，根据任务类型和模型能力动态决定哪些内容需要注入到当前请求中。这个池子里的内容有优先级标记，比如当前正在编辑的文件优先级最高，历史对话记录优先级较低，超过一定轮次就会被压缩或丢弃。

2.2 调度层的任务队列与并发控制

调度层是 ZCode 里我最感兴趣的部分，因为它直接决定了这个 Harness 能同时处理多少任务、响应速度怎么样。ZCode 内部维护了一个任务队列，每个任务包含任务类型、优先级、依赖关系和超时设置。任务类型大致分为几类：代码生成、代码解释、错误修复、重构建议、测试生成。不同类型的任务对模型能力的要求不一样，比如错误修复通常需要更强的推理能力，而代码解释可能用一个小模型就够了。

并发控制这块，ZCode 用的是信号量加优先级队列的组合。默认情况下，同时运行的任务数量是有限制的，这个限制可以在配置文件里调整。我实测下来，在本地跑的时候，并发数设置为 3 到 5 比较合适，再高的话模型 API 的速率限制就会成为瓶颈，而且本地文件系统的读写也会出现竞争。如果你用的是云端模型，并发数可以适当调高，但要注意 API 提供商的 rate limit，不然会频繁触发 429 错误。

提示：并发数不是越高越好。我试过把并发调到 10，结果发现任务完成时间反而变长了，因为大量时间花在了等待 API 响应和重试上。后来降到 4，整体吞吐量反而更稳定。

任务队列的另一个关键设计是依赖管理。有些任务之间有先后关系，比如先生成代码再生成对应的测试，或者先修复错误再重构。ZCode 用了一个简单的有向无环图来管理这些依赖，确保前置任务完成之后才调度后续任务。这个机制在处理大型重构任务的时候特别有用，你可以把一个大任务拆成多个子任务，让它们按照依赖关系自动执行。

2.3 执行层的工具抽象与沙箱机制

执行层是 ZCode 和真实世界交互的地方，它需要调用文件系统、执行终端命令、读写 Git 仓库、甚至启动浏览器做端到端测试。ZCode 把这些能力统一抽象成工具，每个工具都有明确的输入输出定义和权限声明。这种设计借鉴了操作系统里系统调用的思路，Agent 只能通过预定义的工具来操作环境，不能直接访问底层资源。

沙箱机制是执行层里最值得关注的部分。ZCode 默认会在一个受限的环境里执行模型生成的代码，限制包括文件系统访问范围、网络访问权限、进程资源占用等。这个设计非常必要，因为模型生成的代码不一定可靠，有时候会写出死循环或者试图删除重要文件。我刚开始用的时候觉得沙箱限制太多，后来把权限放宽之后，有一次模型生成的脚本差点把我本地的临时文件全删了，从那以后我就老老实实按默认配置来。

工具抽象带来的另一个好处是可测试性。因为每个工具都有明确的接口，你可以很方便地写单元测试来验证工具的行为，也可以用 mock 工具来模拟各种边界情况。ZCode 的测试覆盖率在同类项目里算是比较高的，这跟它的架构设计有直接关系。

3. 核心模块实操：从配置到运行的完整流程

3.1 环境准备与依赖安装

ZCode 的安装过程不算复杂，但有几个地方容易踩坑。首先它依赖 Node.js 环境，版本要求是 18 以上，我建议直接用 20 的 LTS 版本。如果你本地已经装了其他版本的 Node，最好用 nvm 或者 fnm 这类版本管理工具切换一下，避免全局包冲突。安装命令很简单，用 npm 或者 pnpm 都行，但我个人推荐 pnpm，因为 ZCode 的依赖树比较深，pnpm 的硬链接机制能省不少磁盘空间，安装速度也快一些。

# 使用 pnpm 安装 pnpm install -g zcode-cli # 验证安装 zcode --version

安装完成之后，你需要初始化配置文件。ZCode 的配置文件默认放在用户目录下的.zcode文件夹里，里面包含模型配置、工具权限、上下文策略等。初始化命令会引导你完成基本设置，包括选择模型提供商、输入 API Key、设置默认工作目录。这里有个细节要注意：API Key 不要直接写在配置文件里明文存储，ZCode 支持从环境变量读取，我建议用环境变量的方式，避免不小心把 Key 提交到 Git 仓库。

# 设置环境变量 export ZCODE_API_KEY="your-api-key-here" # 初始化配置 zcode init

初始化过程中会问你默认的模型和备用模型。我的建议是至少配置两个模型，一个能力强的用于复杂任务，一个速度快成本低的用于简单任务。ZCode 的调度层会根据任务类型自动选择合适的模型，这个策略可以在配置里调整。

3.2 模型适配层的配置与切换

模型适配层是 ZCode 里最常需要调整的部分，因为不同项目的需求不一样，有时候需要切换模型来对比效果。ZCode 的模型配置采用提供者模式，每个模型提供商对应一个配置文件，里面定义了 API 端点、认证方式、请求格式、响应解析规则等。目前官方支持主流的几家云端模型服务，也支持本地部署的模型通过兼容接口接入。

配置一个模型提供商的基本结构是这样的：

{ "providers": { "provider-name": { "type": "openai-compatible", "baseUrl": "https://api.example.com/v1", "apiKeyEnv": "ZCODE_API_KEY", "models": [ { "id": "model-id", "name": "Display Name", "contextWindow": 128000, "maxOutputTokens": 4096, "capabilities": ["code", "reasoning"] } ] } } }

这里有几个参数需要特别注意。contextWindow决定了模型能处理多长的上下文，这个值直接影响 ZCode 的上下文压缩策略。如果你填得比实际值大，请求可能会被模型拒绝；填得太小，又会导致上下文被过度压缩，影响生成质量。maxOutputTokens控制单次生成的最大长度，对于代码生成任务，我建议设置在 4096 以上，不然稍微复杂一点的函数就写不完。capabilities字段用来标记模型擅长的任务类型，调度层会根据这个字段做路由。

切换模型的时候，你不需要修改代码，只需要在配置里调整默认模型的指向，或者在命令行里用--model参数临时指定。我经常用这个功能来对比不同模型在同一个任务上的表现，比如让模型 A 和模型 B 分别生成同一个函数的实现，然后对比代码质量和执行结果。

3.3 上下文管理的策略与调优

上下文管理是 Coding Agent 最核心也最容易被忽视的部分。ZCode 默认的上下文策略是滑动窗口加优先级淘汰，简单来说就是保留最近 N 轮对话和当前活跃文件的内容，历史记录按照优先级逐步淘汰。这个策略在大多数场景下够用，但如果你处理的是大型代码库，可能需要调整。

ZCode 的上下文配置里有几个关键参数：

我实测下来，maxContextTokens 设置为模型窗口的 70% 到 80% 比较稳妥。留太多浪费，留太少又容易触发模型的截断行为。recentTurns 这个参数要看任务类型，如果是连续性的重构任务，保留更多轮对话有助于模型理解上下文；如果是独立的代码生成任务，10 轮足够了。

还有一个容易被忽略的配置是文件排除规则。ZCode 默认会把工作目录下的所有文件都纳入上下文候选，但有些文件是不需要注入的，比如 node_modules、构建产物、日志文件。你可以在配置里用 glob 模式排除这些目录，这样能显著减少上下文占用，提高响应速度。

{ "context": { "excludePatterns": [ "**/node_modules/**", "**/dist/**", "**/*.log", "**/.git/**" ] } }

3.4 工具权限的精细控制

工具权限控制是 ZCode 安全性的重要保障，也是实际使用中需要仔细配置的部分。ZCode 把工具分为几个权限等级：只读、读写、执行、网络。只读工具包括文件读取、目录列表、代码搜索；读写工具包括文件写入、文件删除、重命名；执行工具包括运行终端命令、启动进程；网络工具包括 HTTP 请求、API 调用。

默认配置下，ZCode 只开启只读和部分读写权限，执行和网络权限需要手动开启。这个默认值我觉得很合理，因为大多数代码生成任务只需要读取现有代码和写入新文件，不需要执行任意命令。如果你确实需要让 Agent 运行测试或者安装依赖，可以针对特定目录或特定命令开启执行权限。

{ "tools": { "fileSystem": { "read": ["**/*"], "write": ["src/**", "tests/**"], "deny": ["**/.env", "**/secrets/**"] }, "terminal": { "enabled": true, "allowedCommands": ["npm test", "npm run build", "git diff"], "timeout": 30000 } } }

注意：allowedCommands 用的是前缀匹配，不是正则匹配。写npm test会允许所有以npm test开头的命令，包括npm test -- --watch。如果你只想允许精确匹配，需要在命令后面加$符号。

我踩过的一个坑是文件写入权限的范围设置。一开始我把 write 设成了**/*，结果模型在重构的时候把配置文件也改了，导致项目跑不起来。后来我把写入范围限制在src和tests目录，配置文件只给读权限，这个问题就再也没出现过。所以权限控制的原则是最小必要，只开当前任务需要的权限，任务完成后再收回来。

4. 实操过程：用 ZCode 完成一个真实的重构任务

4.1 任务定义与前置准备

为了把上面的配置讲清楚，我拿一个真实的小项目来演示。这个项目是一个用 TypeScript 写的工具库，大概有十几个文件，主要功能是处理日期和时间的格式化。代码是半年前写的，现在看起来有几个问题：函数命名不统一，有些用 camelCase 有些用 snake_case；错误处理很随意，有些地方抛异常有些地方返回 null；测试覆盖率只有 40% 左右。我的目标是让 ZCode 帮我完成一次系统性重构，统一命名风格、规范错误处理、补充测试。

在开始之前，我先做了一次 Git 提交，确保当前状态是干净的。这一步很重要，因为 Agent 操作过程中可能会改坏文件，有 Git 记录就能随时回滚。然后我在项目根目录创建了.zcode配置文件，针对这个项目做了定制。

{ "project": { "name": "date-utils", "language": "typescript", "testCommand": "npm test", "buildCommand": "npm run build" }, "context": { "includePatterns": ["src/**/*.ts", "tests/**/*.ts"], "excludePatterns": ["**/node_modules/**", "**/dist/**"] }, "tools": { "fileSystem": { "read": ["**/*"], "write": ["src/**", "tests/**"] }, "terminal": { "enabled": true, "allowedCommands": ["npm test", "npm run build", "npx tsc --noEmit"] } } }

配置里的testCommand和buildCommand是给 Agent 用的，它在修改代码之后会自动运行这些命令来验证结果。这个反馈闭环非常关键，没有它的话，Agent 改完代码就结束了，你根本不知道改得对不对。

4.2 分阶段执行重构任务

我没有让 ZCode 一次性完成所有重构，而是拆成了三个阶段。第一阶段是命名规范化，第二阶段是错误处理统一，第三阶段是测试补充。每个阶段完成后我都会检查一遍，确认没问题再进行下一阶段。这种分阶段的方式比一次性大重构要安全得多，出问题的时候也容易定位。

第一阶段的任务描述我是这样写的：

请扫描 src 目录下的所有 TypeScript 文件，找出所有使用 snake_case 命名的函数和变量，将它们统一改为 camelCase。修改时请注意： 1. 只修改函数名和变量名，不要改动字符串字面量中的内容 2. 如果某个名称被导出，需要同步更新所有引用它的地方 3. 修改完成后运行 npx tsc --noEmit 检查类型错误

ZCode 接到任务后，先读取了 src 目录下的所有文件，然后生成了一个修改计划，列出了需要改动的文件和具体的改动点。我检查了一下计划，发现它漏掉了两个在类型定义文件里的引用，手动补充之后让它继续执行。执行过程中它调用了文件读写工具，逐个修改文件，最后运行了类型检查命令。整个过程大概花了三分钟，比我手动改快多了，而且不会漏掉引用。

第二阶段处理错误处理的时候，我给的指令更具体一些：

请检查 src 目录下所有函数的错误处理逻辑，按照以下规则统一： 1. 所有可能失败的操作（文件读写、解析、网络请求）必须使用 try-catch 包裹 2. catch 块中必须记录错误信息，使用项目现有的 logger 工具 3. 对外暴露的函数在出错时抛出带有明确错误码的异常，不要返回 null 4. 内部辅助函数可以返回 Result 类型，但需要在类型定义中明确

这个任务比第一个复杂，因为涉及到逻辑判断。ZCode 在执行过程中遇到一个它不确定的地方：有一个函数既可能返回 null 也可能抛异常，它不知道应该统一成哪种风格。它把这个文件标记出来，在最后的结果里提示我需要人工确认。这种不确定时主动询问的行为，我觉得是 ZCode 做得比较好的地方，比那些强行猜测然后改错的方案要靠谱。

4.3 验证与回滚机制

每个阶段完成后，ZCode 会自动运行测试命令，把测试结果作为反馈。如果测试失败，它会尝试分析失败原因并修复，最多重试三次。我实测下来，第一次通过率大概在 70% 左右，经过一两次重试之后能到 90% 以上。剩下的 10% 通常是测试本身需要更新，或者模型对业务逻辑的理解有偏差，需要人工介入。

回滚机制方面，ZCode 在执行修改之前会自动创建一个 Git stash 或者临时分支，如果整个任务失败或者你手动取消，可以一键回滚到执行前的状态。这个功能在重构任务里特别有用，我有一次让 Agent 改一个核心模块，结果它把依赖关系搞乱了，测试大面积失败，我直接回滚重来，没有造成任何损失。

# 查看 ZCode 创建的回滚点 zcode history list # 回滚到指定版本 zcode history rollback --id abc123

提示：回滚点默认保留最近 10 次，可以在配置里调整保留数量。如果你做的是大型重构，建议把保留数量调大一些，方便回溯到更早的状态。

5. 常见问题与排查技巧实录

5.1 模型响应超时或截断

这是最常见的问题，尤其是在处理大文件或者复杂任务的时候。表现是模型返回的代码不完整，或者请求直接超时。排查思路分几步：先看上下文是不是太长了，如果注入的 token 数接近模型窗口上限，模型可能会截断输出。解决办法是调整上下文策略，减少注入的文件数量或者降低 fileContextLines。再看maxOutputTokens 是不是设小了，如果生成的内容超过这个限制，会被硬截断。最后检查网络连接和 API 速率限制，如果频繁触发 429，需要降低并发数或者增加重试间隔。

我遇到过一次比较隐蔽的情况：模型返回的代码看起来完整，但运行时报语法错误。后来发现是输出被截断在了字符串中间，因为 maxOutputTokens 刚好卡在了一个尴尬的位置。从那以后我养成了一个习惯，对于代码生成任务，maxOutputTokens 至少设 4096，复杂任务设 8192。

5.2 工具调用失败与权限问题

工具调用失败通常有几个原因：路径不对、权限不足、命令不存在。ZCode 的错误信息还算清晰，会告诉你哪个工具调用失败了、失败原因是什么。但有些情况下错误信息比较模糊，比如“文件写入失败”，可能是路径不存在，也可能是权限不够，还可能是磁盘满了。

我的排查顺序是这样的：先确认路径是否正确，ZCode 用的是相对于项目根目录的路径，如果你写的是绝对路径可能会被沙箱拦截。再检查权限配置，看看目标路径是否在 write 允许的范围内。最后看系统层面的限制，比如文件是否被其他进程占用、磁盘空间是否充足。

5.3 上下文丢失与幻觉问题

Coding Agent 的幻觉问题比聊天机器人更隐蔽，因为它生成的代码看起来往往很合理，但引用了不存在的函数或者变量。ZCode 通过上下文注入来缓解这个问题，把当前文件的完整内容、相关文件的接口定义、类型声明都注入到 prompt 里。但如果上下文管理配置不当，关键信息可能会被淘汰掉，导致模型“忘记”了某些定义。

我的经验是，对于跨文件的重构任务，一定要确保相关文件的接口定义在上下文里。ZCode 有一个relatedFiles配置，可以指定某个文件的相关文件列表，这些文件的内容会被优先保留。比如你在改一个工具函数，它的类型定义在另一个文件里，就把那个文件加到 relatedFiles 里。

{ "context": { "relatedFiles": { "src/utils/date.ts": ["src/types/index.ts", "src/utils/format.ts"] } } }

另一个减少幻觉的技巧是在任务描述里明确引用具体的文件和函数。不要说“修改日期处理函数”，而要说“修改 src/utils/date.ts 里的 formatDate 函数”。越具体的指令，模型越不容易跑偏。

5.4 性能调优与资源占用

ZCode 在运行过程中会占用一定的 CPU 和内存，尤其是在处理大项目的时候。我实测下来，一个中等规模的 TypeScript 项目（大概 50 个文件），ZCode 的内存占用在 300MB 到 500MB 之间，CPU 占用在空闲时接近零，执行任务时会飙到 30% 到 50%。这个资源占用对于开发机来说完全可以接受，但如果你在 CI 环境里跑，可能需要考虑资源限制。

性能调优的几个方向：减少上下文注入量能显著降低内存占用和响应时间；合理设置并发数避免资源竞争；启用缓存避免重复读取相同的文件。ZCode 有一个文件内容缓存，默认开启，对于频繁读取的文件能省不少 IO。

{ "performance": { "maxConcurrency": 4, "fileCache": true, "cacheTTL": 300000 } }

注意：fileCache 的 TTL 默认是 5 分钟，如果你在任务执行过程中手动修改了文件，缓存可能不会立即失效。这种情况下可以手动清除缓存，或者把 TTL 设短一些。

6. 扩展与集成：把 ZCode 嵌入现有工作流

6.1 与编辑器的集成方式

ZCode 提供了命令行接口，也提供了 API 接口，可以很方便地集成到各种编辑器里。我平时用 VS Code 比较多，社区里已经有人做了 ZCode 的 VS Code 扩展，安装之后可以在编辑器里直接调用 ZCode 的功能。扩展的工作原理是通过本地端口和 ZCode 的守护进程通信，把当前打开的文件、光标位置、选中的代码片段作为上下文传给 ZCode。

如果你用的编辑器没有现成的扩展，也可以用 ZCode 的 API 自己写一个。ZCode 的 API 是 HTTP 接口，默认监听本地端口，请求和响应都是 JSON 格式。你可以用任何语言来调用，只要构造好请求体就行。

import requests response = requests.post("http://localhost:3721/api/task", json={ "type": "code-generation", "prompt": "实现一个函数，计算两个日期之间的工作日天数", "context": { "file": "src/utils/date.ts", "language": "typescript" }, "options": { "model": "default", "maxTokens": 2048 } }) print(response.json()["result"])

这种集成方式的好处是灵活，你可以根据自己的需求定制交互界面和上下文注入策略。坏处是需要自己处理错误和重试逻辑，ZCode 的命令行工具已经帮你封装好了这些。

6.2 在 CI 流程中自动运行

把 ZCode 放到 CI 流程里是一个比较进阶的用法，适合那些需要自动化代码审查或者自动修复的场景。比如你可以配置一个 CI 任务，在每次 Pull Request 创建时自动运行 ZCode，让它检查代码风格、发现潜在 bug、甚至自动生成修复建议。

在 CI 环境里运行 ZCode 需要注意几点：API Key 要通过环境变量注入，不要写在配置文件里；并发数要调低，因为 CI 环境的资源有限；超时时间要设长一些，因为 CI 环境的网络可能比较慢。另外，CI 环境通常是无状态的，ZCode 的缓存和回滚点不会保留，每次运行都是全新的状态。

# GitHub Actions 示例 name: ZCode Review on: [pull_request] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm install -g zcode-cli - run: zcode review --diff origin/main...HEAD env: ZCODE_API_KEY: ${{ secrets.ZCODE_API_KEY }}

这个配置会在每次 PR 时运行 ZCode 的 review 命令，它会分析 diff 内容，给出代码质量评估和修改建议。我实测下来，对于中小型 PR，这个流程能在两分钟内完成，给出的建议质量也还不错。

6.3 自定义工具的开发

ZCode 的工具系统是开放的，你可以开发自定义工具来扩展它的能力。比如你的项目用了一个内部的代码生成器，你可以写一个工具让 ZCode 调用它；或者你的项目有特殊的测试框架，你可以写一个工具来运行测试并解析结果。

自定义工具的开发流程大概是这样的：先定义一个工具描述文件，说明工具的输入输出格式和权限要求；然后实现工具的逻辑，可以用 JavaScript 或者 TypeScript 写；最后把工具注册到 ZCode 的配置里。ZCode 会在启动时加载这些工具，模型在需要的时候会调用它们。

// tools/custom-linter.js module.exports = { name: "custom-linter", description: "运行项目自定义的代码检查工具", input: { type: "object", properties: { files: { type: "array", items: { type: "string" } } }, required: ["files"] }, async execute({ files }) { const { execSync } = require("child_process"); const result = execSync(`npx custom-lint ${files.join(" ")}`, { encoding: "utf-8" }); return { output: result }; } };

自定义工具的价值在于把项目特有的知识固化下来，让 Agent 能够利用这些知识做出更准确的判断。比如你的项目有一套内部的 API 规范，你可以写一个工具来检查生成的代码是否符合规范，这样就不需要每次都把规范写在 prompt 里了。

7. 一些踩坑之后的个人体会

用 ZCode 这段时间，我最大的感受是Agent 的能力上限取决于 Harness 的设计质量。同一个模型，在不同的 Harness 里表现可能差很多。ZCode 之所以好用，是因为它在上下文管理、工具抽象、错误处理这几个关键环节上都做了比较细致的设计，而不是简单地把模型包一层就完事。

另一个体会是不要指望 Agent 一次做对所有事情。我现在的习惯是把大任务拆成小任务，每个任务只做一件事，做完验证再继续。这样虽然看起来麻烦，但整体效率反而更高，因为出问题的时候容易定位，回滚的成本也低。ZCode 的任务队列和依赖管理机制天然支持这种工作方式，你可以把多个小任务串起来，让它们按顺序自动执行。

最后分享一个我常用的技巧：在任务描述里加上验收标准。比如“修改完成后运行 npm test，确保所有测试通过”或者“生成的代码必须通过 npx tsc --noEmit 检查”。ZCode 会把验收标准作为任务的一部分，在生成代码后自动运行验证命令，如果不通过会尝试修复。这个技巧能显著提高生成代码的可用性，减少人工检查的工作量。

这个项目后续还可以往几个方向扩展，比如支持更多的模型提供商、增加对更多编程语言的原生支持、提供更细粒度的权限控制。如果你也在做类似的事情，欢迎交流踩坑经验。