ZCode 上手指南

cc 都用上了，不如再认识一下 ZCode。它和"问 AI"是两种完全不同的玩法。

1. ZCode 到底是什么

一句话：ZCode 是一个会自己动手干活的编程智能体（Agent），而不是一个只会在对话框里回你文字的 AI。

两者的区别很关键：

• 聊天机器人：你问，它答。代码要你自己复制走，文件要自己存，命令要自己敲。它只是个嘴。
• 智能体（Agent）：你下指令，它自己读文件、改代码、跑命令、看报错、再修，循环往复，直到把事干完。

所以用 ZCode 的正确姿势，不是"帮我写一段 xxx"，而是"帮我把首页加上分类筛选"。它会自己去翻代码、动手改、验证，你只管审结果。

2. 第一次上手

打开一个项目（比如本站这种 Next.js 仓库），直接用大白话告诉它你想干嘛就行：

"把「最近值得一读」加个分类筛选，别让深度学习的文章全堆在顶部，顺便优化下搜索框。"

然后你会看到它这样工作：

1. 自己去找相关文件：它会搜代码、读文件，搞清楚现在是怎么实现的。
2. 动手改：直接编辑文件（你能在界面上看到改动）。
3. 该跑命令就跑：装依赖、跑类型检查、起本地预览，它会自己执行。
4. 检查结果：报错了它会自己看、自己修，不需要你把错误信息复制给它。

每一步要不要执行，都由你授权。你可以放权让它自己干，也可以盯着每一步确认。

3. 怎么下需求才好使

ZCode 的能力强弱，很大程度取决于你需求下得清不清楚。Rubbish in, rubbish out 这条铁律在智能体上只会更狠——因为它会照着你的描述真刀真枪地改代码。

下需求的好习惯：

• 说意图，而不是说步骤。说"加个分类筛选"比说"在第 245 行加个 select 标签"更好。它自己会决定加在哪、怎么加，你只描述目标。
• 给约束。"别动深度学习的文章顺序，只是在首页交错排列"——把边界划清楚，它就不会乱发挥。
• 让它先出计划。复杂任务，让它先列计划、等你确认再动手（见下面的"计划模式"）。
• 不满意就让它改。智能体的强项是迭代，改个十遍很正常，它会保留之前的上下文。

4. 几个让效率翻倍的功能

计划模式（Plan Mode）

遇到大改动（重构、加功能、改架构），让它先进计划模式：先调研、出方案、列步骤，你拍板了再写代码。能省掉大量返工。这是和"上来就改"最大的区别——动手之前先对齐。

技能（Skill）

ZCode 内置了一堆技能：写文档、做 PDF、搞图表、浏览器自动化、学术写作……要用的时候它会自动调用，你也可以用 /技能名 直接喊。等于给它装了各种专业插件。想加自己的技能也行（有专门的 skill-creator）。

子智能体（Subagent）

一个任务太杂、需要翻很多文件时，它会派子智能体去并行干活、做调研，主线程只看结论。这样不会把主上下文塞满，效率更高。

MCP（外接工具）

MCP 是个协议，能让 ZCode 接上外部工具，比如数据库、设计软件、内部 API。接上之后，它就像多长了几只手，能直接操作这些系统。

后台任务

跑 dev server、跑长测试这种要一直挂着的事，可以让它在后台跑，不挡着你干别的。

5. 权限和安全

ZCode 在你的电脑上干活，所以它有权限这一层：

• 每次读文件、跑命令、上网，你可以设不同的授权力度——从"每步都问我"到"放手让它干"。
• 它拒绝某个操作（比如删东西、发到外网）是默认的安全姿态，需要你确认。
• 改代码前它会先看目标，发现实际情况和你说的对不上，会先告诉你而不是闷头改。

一句话：你始终是拍板的人。能力越大，授权越要你心里有数。

6. 常见误区

• 别微操。不要一句一句指挥它敲键盘，那样反而更慢。把整个目标给它，让它自己规划。
• 要给上下文。它看不到你脑子里的东西，相关背景、约束、参考都告诉它。
• 一定要 review。它会改代码、会跑命令，但它会犯错。尤其涉及删除、发布这种不可逆的操作，自己过一眼再放行。
• 长对话注意精简。聊太长上下文会变重，必要时开新会话，把关键结论带过去。

7. 小结

用 ZCode 的心法就一句：把它当搭档，而不是当嘴替。下清楚目标、给好约束、用好计划模式、最后自己把关。习惯了这个工作方式，你会发现一个人能顶一个小团队。

想搞懂它嘴里那些 Skill、Tool、Loop、Harness 到底都是啥，看下一篇《ZCode 名词速查》。