ZCode 入门教程：从打开项目到完成一次 Java 代码修改

AI 编程工具真正有用的地方，是帮助开发者把"理解项目、定位问题、修改代码、验证结果"连起来。

这篇教程以 Java 项目为例，介绍一套适合初次使用的流程：先让 ZCode 读懂项目，再完成一个范围明确的修改，最后检查结果。

一、安装 ZCode

打开 zcode.z.ai/cn ，在"全部下载"中选择适合电脑的安装包：

系统	选择方式
Windows	按处理器架构选择 64 位或 ARM64
macOS	按芯片选择 Apple Silicon 或 Intel
Linux	按架构与发行版选择安装包，目前标注为 Beta

安装后启动客户端，按当前界面的引导完成账号和模型访问配置。

本文不提供未经确认的设置菜单路径。若客户端要求填写 API Key，应使用它所指向的服务平台生成的凭证，不要直接套用其他编程工具的接口配置，也不要把密钥写入项目源码。

二、准备一个可以正常运行的项目

第一次使用，建议选择一个自己熟悉的小型项目。

熟悉业务有一个实际好处：你能判断 AI 的分析是否正确，而不是只能接受它的解释。

对于 Maven 项目，先在本地终端检查：

lua 复制代码

java -version
mvn -version
git status

这些命令分别用于确认 Java 环境、Maven 环境以及当前代码变更状态。

如果项目使用 Maven Wrapper，可以按操作系统运行：

bash 复制代码

# Windows PowerShell
.\mvnw.cmd -version

# macOS / Linux
./mvnw -version

JDK 版本应与项目要求一致。还要记住：IDEA 能正常启动项目，不一定意味着命令行环境也已配置好。

在开始修改前，保存已有工作，并考虑创建独立分支：

r 复制代码

git switch -c experiment/zcode-first-task

以上是通用项目准备步骤，不是 ZCode 专用命令。

三、打开项目，先做只读分析

在 ZCode 中使用工作区入口选择项目目录。对于多模块 Maven 项目，通常应选择包含父级 pom.xml 的根目录，而不是只打开某个 Java 文件所在的文件夹。

第一个任务可以直接使用下面的提示词：

markdown 复制代码

请只读分析当前 Java 项目，不修改文件、不安装依赖。

请说明：
1. 项目的技术栈和主要模块。
2. 应用启动入口。
3. Controller、Service、数据访问层的组织方式。
4. 测试代码的位置及已有测试运行方式。

为结论标注文件路径。
无法从代码确认的内容，请明确说明，不要猜测。
不要输出配置中的密钥、密码等敏感值。

好的分析结果应当能带你找到代码。

例如，"项目采用分层架构"过于笼统；指出具体 Controller、Service 和 Mapper 文件，才便于继续阅读和核对。

这一阶段重点检查：

它是否选对了模块和启动入口。
是否把测试配置误认为生产配置。
是否区分了实际代码与推测。
有没有忽略父级配置或公共模块。

四、追踪一条真实业务链路

了解项目结构后，继续分析一个具体接口。

复制代码

请追踪用户查询接口的完整调用链。

从 HTTP 路由开始，依次定位：
Controller → Service → 数据访问层 → 数据库查询。

说明参数校验、异常处理和返回值转换的位置。
为每个环节标注文件路径与方法名。
如果存在缓存或远程调用，也请标出。

先只读分析，不修改代码。

如果需要架构图，可以追加：

复制代码

请根据已经确认的调用关系生成 Mermaid 图。
不要补充代码中没有证据的服务或组件。

这里要注意：静态代码分析不能自动证明运行时的全部行为。动态代理、配置开关和消息消费等路径，可能还需要结合日志或运行结果确认。

分析完成后，你应该能够自己沿着路径找到相关代码。这也是判断结果是否可靠的一个简单标准。

五、完成第一次小范围修改

第一个修改任务应尽量小，例如补充参数校验、修复一个边界条件，或者为已有行为增加测试。

不要一开始就要求"重构整个项目"。

假设项目中有一个手机号脱敏方法，可以这样布置任务：

markdown 复制代码

请先找到项目现有的手机号脱敏实现和相关测试，再按以下规则修改：

- 输入 null 时返回空字符串。
- 输入长度不是 11 时，保持原样。
- 输入长度为 11 时，保留前 3 位和后 4 位，中间替换为 ****。

要求：
- 沿用现有代码风格和测试框架。
- 不新增依赖，不重构无关代码。
- 如果发现现有行为与这些要求冲突，先说明影响。
- 补充对应测试，并运行相关测试。

完成后列出修改文件、实际执行的测试命令和结果。

这里的业务规则只是示例，使用时应替换成项目的真实要求。

明确的输入输出，可以直接转成验收用例：

输入	期望输出
`null`	`""`
`""`	`""`
`"12345"`	`"12345"`
`"13812345678"`	`"138****5678"`

这样，你和 ZCode 判断"完成"的依据是一致的。

六、审查改动，再决定是否保留

任务结束后，不要只阅读总结，还要检查文件差异。

可以在 Git 工具或终端查看：

bash 复制代码

git diff --stat
git diff

主要检查三件事：

修改范围是否合理。 一个小方法的调整，不应无缘无故修改大量配置和依赖文件。

行为是否符合约定。 重点检查空值、非法输入、兼容性以及已有调用方的预期。

验证是否真实完成。 写出了测试、运行了测试、测试通过，是三个不同状态。

可以继续要求：

diff 复制代码

请复核本次修改，说明：

- 新增测试覆盖了哪些行为。
- 实际运行了哪些命令。
- 是否存在失败或未执行的检查。
- 是否影响现有调用方。

不要把未运行的测试描述为通过。

对于简单 Maven 项目，常见的指定测试命令是：

ini 复制代码

mvn -Dtest=PhoneMaskTest test

PhoneMaskTest 是示例名称，需要替换为项目实际测试类。多模块项目则应根据模块结构和已有构建方式调整命令。

七、复杂任务如何拆分？

ZCode 官网介绍了通过 Goal 管理长程任务，并持续进行规划、执行和验证。

使用这类能力时，先写清楚终点，再定义阶段验收条件。

例如"增加订单导出功能"，可以拆成：

阶段	预期交付
分析	找到现有查询逻辑、权限规则和导出约定
方案	明确字段、数据量限制和异常处理方式
实现	完成必要代码，保持修改范围可审查
验证	检查正常导出、空结果、权限和大数据量场景

可以这样描述任务：

复制代码

目标：为订单列表增加导出功能。

先分析现有查询条件、权限控制和导出组件。
输出实现方案与影响范围，暂时不修改代码。

方案确认后，再按阶段实现。
每个阶段说明改动和验证结果。
不要部署，不要连接生产数据库。

是否启用多智能体，应取决于任务能否清晰拆分。任务很小时，增加执行者并不必然减少总耗时。

八、遇到问题时怎么排查？

现象	优先检查
找不到相关代码	工作区是否选对、是否打开了完整项目
分析内容太泛	是否指定了接口、模块和证据要求
Java 命令无法运行	JDK 安装、环境变量及版本是否匹配
IDE 能运行，命令行失败	两者使用的 JDK、Maven 和配置是否一致
修改范围过大	是否明确了允许修改的文件与禁止事项
测试未通过	区分代码问题、依赖下载问题和环境问题
模型请求失败	根据错误检查登录、凭证、额度和服务状态

处理错误时，可以把错误信息和相关上下文交给 ZCode，但应隐去密钥和密码。

提示词可以写得很直接：

复制代码

这是刚才运行失败的错误信息。

请先分析失败原因，区分代码问题与环境问题。
给出证据和最小修复方案。
不要重复执行相同的失败命令，也不要扩大修改范围。

结语

第一次使用 ZCode，不必急着让它开发一个完整系统。

打开一个熟悉的 Java 项目，让它分析一条接口链路，再完成一个有明确验收标准的小改动，就足以建立对工具的判断。

真正值得培养的使用习惯是：把任务说清楚，让结论有依据，让修改可审查，让结果经过验证。