在 VS Code 里结对：ZCode 的结对编程工作流搭建

在 VS Code 里结对ZCode 的结对编程工作流搭建【免费下载链接】ZCodeZCode 是 AI 编程工作台提供桌面应用、浏览器界面和终端 Agent。本仓库包含客户端、后端服务、共享 UI以及 Agent CLI 与运行时源码。项目地址: https://gitcode.com/zai-org/ZCode当 AI 编程助手从补全一行代码进化到自主改完一个仓库开发者面临的新问题不再是它能不能写代码而是我如何让它动手、又不让它乱动手。ZCode 给出的答案是一套可以精细分级的协作协议从只读的 plan 模式到需要逐次审批的 build 模式再到跳过确认的 yolo 模式——开发者可以像给结对伙伴交代分工一样把你只管提方案和你去动手改两种角色切给 AI而自己保留最终的审批权。ZCode 是智谱 AI 推出的开源 AI 编程工作台仓库同时承载桌面应用、浏览器界面和终端 Agent 三种形态。本文基于仓库源码apps/zcode-cli/ 与 packages/拆解如何在 VS Code 生态中搭建一套人审代码、AI 动手的结对工作流先讲清 CLI 与 IDE 工作台的形态差异再落到协作模式、权限审批、以及可以把结对协议固化成配置的 Hooks 与子代理机制。CLI 与 VS Code同一套运行时两种协作姿势很多实测文章把 ZCode 简单归类为终端 Agent这其实只讲对了一半。仓库根目录的 README.md 写得很明确ZCode 是 AI 编程工作台提供桌面应用、浏览器界面和终端 Agent而 Agent CLI 与运行时源码位于 apps/zcode-cli/。命令行发行包统一用zcode命令启动无参数进入 TUI第一个参数为--web时启动 Web 界面其他参数交给现有 Agent CLI 处理。也就是说同一套 Agent 内核被三种界面共享——TUI 只是它的一个皮肤Web 工作台是另一个Electron 桌面端又叠了一层 Host/Renderer 架构。这种内核一套、界面多端的设计让协作方式的选择键盘流、浏览器、还是 VS Code 侧边栏与执行内核解耦。在 VS Code 集成这件事上仓库给出了具体的协作触点。先看编辑器探测层packages/shared/src/platform.ts 定义了EditorInfo其中编辑器标识明确包含vscode这类取值再看工作区编辑器选择逻辑 packages/ui/src/lib/workspaceEditorSelection.ts对于 SSH 远程工作区只允许用vscode/vscode-insiders打开远端路径对于 WSL 工作区额外放行 Windows 资源管理器走 UNC 映射。这背后的工程判断是SSH 工作区路径只存在于远端本地的 Finder/Explorer/Terminal 无法消费/root/...这类路径只有 VS Code Remote-SSH 才能真正打开它。于是协作姿势就清晰了ZCode 的 Agent 负责在项目里读代码、执行命令、改文件这是它的运行时能力而 VS Code 负责给人类提供熟悉的编辑器上下文——看 diff、改建议、审代码。二者通过工作区文件搜索、编辑器打开、远程连接这些边界工具衔接而不是粗暴地让 Agent 去模拟一个 IDE。协作模式设置从 plan 到 yolo 的权限光谱结对编程的第一要务是约定这一轮谁来主导。ZCode 把这件事建模成了协作模式CollaborationMode定义在 apps/zcode-cli/packages/contracts/src/interfaces/session.port.tsexport type CollaborationMode plan | build | edit | yolo | auto;在 CLI 里通过/mode命令切换。命令处理器 apps/zcode-cli/packages/cli/src/command-center/handlers/mode.ts 的实现很直白不带参数时回显当前模式与可用列表plan, build, edit, yolo带参数时切换到目标模式。真正有信息量的是 apps/zcode-cli/packages/core/src/permission/service.ts 里checkPermission的分支顺序它把模式语义落成了可执行的决策规则yolo 模式直接放行注释原话是 Yolo mode bypasses permission prompts——适合你明确信任 AI 且改动风险可控的场景plan 模式checkPlanMode只放行只读且非破坏性的工具mode.plan.readOnly和非破坏性 MCP 工具其余一律拒绝mode.plan.nonReadOnly——AI 在这个模式下只能调研、规划、提问不能动文件edit 模式对文件编辑类工具直接放行其余回落到 build 语义build 模式默认按风险分级决定是否弹审批——critical风险的工具必须显式确认mode.build.criticalRiskhigh风险默认需要确认除非配置了自动放行低风险的会话内状态更新直接放行任何有副作用的工具都要问人。风险等级RiskLevel同样定义在 session.port.tslow | medium | high | critical。也就是说让 AI 动手不是一句空话而是被拆成了可配置、可分级、可追溯的决策链。对结对场景最有价值的组合是先用/mode plan让 AI 只读地读代码、出方案、列改动点人审完方案后/mode edit或/mode build放它动手遇到拿不准的高风险操作审批弹窗会把它拦下来等你拍板。这恰好对应人负责方向与裁决AI 负责执行与细节的分工协议。审批与分工人审代码、AI 动手的落点模式只是门槛真正的人审发生在审批环节。ZCode 把审批设计成了异步的 Permission Brokerapps/zcode-cli/packages/core/src/permission/broker.ts 定义了PermissionBrokerPort客户端TUI、Web、桌面各自实现自己的审批 UIManualPermissionBroker维护一张pending请求表支持超时与取消DenyPermissionBroker则在没有审批客户端时默认拒绝——宁可拒绝也不裸奔。审批请求携带了什么看 apps/zcode-cli/packages/contracts/src/interfaces/permission.port.tstoolName、riskLevel、input、mode、suggestedPermissionUpdates。这意味着弹窗里不仅能展示AI 想跑什么命令、改哪个文件还能顺带提议这次允许之后是否把它记成规则。审批的记忆能力分两层。一层是会话级PermissionService内部维护sessionRules注释明确说明Always allow in this session的授权只活在当前会话内存里/new或重启即失效防止一次大意的放行变成永久的后门。另一层是项目级持久规则PermissionRuleset由allow / deny / ask三组规则组成规则内容支持通配符匹配matchesRuleContent里prefix:*前缀匹配和*通配符转正则匹配的输入字段覆盖command、url、file_path、path、pattern、patch_text等——项目可以预先把只允许改动src/目录禁止执行rm -rf类命令这类结对边界写死。再往下是人审代码的最后一公里。Write工具的输出契约定义在 apps/zcode-cli/packages/contracts/src/tools/write.ts除了常规的写入结果还会返回structuredPatch结构化 diff hunk与可选的gitDiff含文件名、增删行数、patch 正文并且有一个专门的字段/** * True when the user edited the proposed content in the permission dialog before accepting */ userModified?: boolean;这意味着 ZCode 的审批对话框不只是同意/拒绝二选一人类可以在对话框里直接改写 AI 提议的内容改完再放行工具会如实标记userModified。这就是人审代码、AI 动手在实现层面的完整闭环——AI 产出改动草案人既是审批者也是最终内容的编辑者每一次人工介入都被记录进会话。配合 TUI 的审批面板apps/zcode-cli/packages/tui/src/app-approval-panel.tsx提供审批决策与授权范围选择以及/rewind、/fork、/compact等会话控制命令见 apps/zcode-cli/packages/cli/src/command-center/slash-command-types.ts结对双方人和 Agent随时可以回到过去的某个决策点重来——这比传统结对编程改错了只能手动回滚要优雅得多。把结对协议固化进仓库Hooks、子代理与 MCP如果每次结对都要口头重申规则协议早晚会漂移。ZCode 提供了把分工协议写进配置的机制首当其冲的是 Hooks。事件清单定义在 packages/shared/src/hooks.tsSessionStart | UserPromptSubmit | PreToolUse | PermissionRequest | PostToolUse | PostToolUseFailure | Stop其中PreToolUse钩子可以 deny / ask / allow、替换工具输入或附加模型可见上下文PermissionRequest在工具需要审批时触发可以代为批准、拒绝或修改待处理的输入。CLI 文档apps/zcode-cli/README.md给出了可直接落地的 JSON 配置对Bash|Write|Edit这类有副作用的工具挂PreToolUse钩子用退出码2表示显式阻断。举个典型用法团队约定任何会话都不允许执行破坏性 shell 命令就可以用一段钩子输出permissionDecision: deny让规则跟着仓库配置走而不是依赖每个人的自觉。第二层是子代理Subagent。apps/zcode-cli/packages/core/src/subagent/profile.ts 定义了AgentProfile其中有一个专门的AgentPermissionModeauto | plan。也就是说你可以给某个子代理预设权限姿态——一个只读的调研型子代理负责读代码出方案plan一个执行型子代理负责动手auto主 Agent 负责编排二者。这种不同角色不同权限的设计本质上就是把结对编程里导航者driver与驾驶员navigator的角色划分搬进了 Agent 拓扑。第三层是 MCP 与插件生态。ZCode 的 CLI 配置支持stdio/http/sse三类 MCP 服务器工具以mcp__server__tool的形式注册进会话并配套/mcp list、/mcp status、/mcp connect等管理命令插件 manifestapps/zcode-cli/README.md 的 Plugin Manifest 一节允许一个插件同时贡献skills、commands和mcpServers。仓库自带的 bundled skillsapps/zcode-cli/packages/bundled-skills/skills/dynamic-workflows/展示了把整套工作流封装成 Skill 的写法——结对协议本身也可以沉淀成一个 SKILL.md让 AI 每次开工前先读一遍分工章程。小结把 ZCode 当作结对伙伴时它的价值不在于自动到什么程度而在于把人与 AI 的分工变成了可配置、可审计、可编程的协议协作模式决定 AI 的权限光谱权限规则与风险分级决定哪些操作要人拍板Hooks 与子代理把约定固化进仓库Write工具的结构化 diff 与userModified标记则保证每一次人类介入都有迹可循。社区评测中反复出现的网络请求可审计讨论在源码里同样能找到对应所有工具调用、审批决策与会话事件都以结构化事件流沉淀在会话投影里。搭建结对工作流的要点其实就一句话——先想清楚哪些决策必须留给人再把其余的一切放心地交给 Agent。【免费下载链接】ZCodeZCode 是 AI 编程工作台提供桌面应用、浏览器界面和终端 Agent。本仓库包含客户端、后端服务、共享 UI以及 Agent CLI 与运行时源码。项目地址: https://gitcode.com/zai-org/ZCode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考