9. 排障与下一步

来源：ZCode

这一课不再添加项目功能。你会用固定顺序定位问题，并完成一次课程收口检查。遇到故障时，从可观察状态开始，不要立刻重装、换模型或授权完全访问。

通用诊断顺序

先回答六个问题：

1. 当前打开的是哪个工作区？
2. 当前任务从什么时候开始，是否读取了最新 AGENTS.md？
3. 模型是否已连接、供应商是否启用？
4. 当前是哪个执行模式，是否有等待处理的确认？
5. Agent 实际用了哪些文件、命令或浏览器标签？
6. 文件、Git Diff、页面和下载结果分别提供了什么证据？

这个顺序能把“ZCode 不工作”缩小成具体层次：项目状态、模型连接、权限、工具调用或实现结果。

安装或启动问题

症状：安装包打不开或启动后立即退出

• **可能原因：**安装包架构不匹配、系统安全策略拦截、Linux AppImage 缺少权限或依赖。
• **检查：**回到官方安装页确认系统和架构；Linux 从终端启动一次，读取首个错误；Windows 查看安全软件记录。
• **处理：**重新下载匹配的官方安装包；AppImage 先添加执行权限。涉及关闭安全防护或解除系统隔离时，先确认来源和影响，不照抄陌生命令。

官方安装与平台排障

模型连接问题

症状：连接一直 Loading，或输入后没有模型可选

• **可能原因：**网络无法访问服务、账号没有可用模型权限、供应商未启用。
• **检查：**打开“设置 → 模型设置”，确认账号连接、供应商开关和实际返回的模型列表。
• **处理：**先修复连接或账号权限，不要凭记忆手填模型名。官方 FAQ 将网络环境和账号权限列为持续 Loading 的优先检查项。常见问题解答

症状：有 Coding Plan 或余额，但请求没有走预期额度

• **可能原因：**把 Coding Plan 专用端点与开放平台通用端点混用。
• **检查：**确认凭据属于编程套餐还是资源包 / 充值余额。
• **处理：**BigModel Coding Plan 当前使用 /api/coding/paas/v4，通用余额使用 /api/paas/v4；不确定时改用 BigModel 账号授权，让 ZCode 自动选择通道。不要把 API Key 发进聊天。

症状：终端能调用模型，ZCode 仍未配置

• **原因：**终端环境变量和 ZCode 桌面端模型设置是独立入口。
• **处理：**在 ZCode 的欢迎页或“管理模型”中单独连接。终端可用不代表桌面端自动继承。

工作区和项目规则问题

症状：Agent 分析了错误项目或看到了无关文件

• **检查：**查看工作区名称和文件树根目录，不要只看任务标题。
• **处理：**停止当前操作，打开正确文件夹后新建项目任务。不要把用户主目录、整个“文档”目录作为工作区。

症状：Agent 没有遵守刚写的 AGENTS.md

• **可能原因：**文件不在工作区根目录、文件名不正确，或当前任务早于文件创建。
• **检查：**确认路径是 <工作区>/AGENTS.md。
• **处理：**新建项目任务；必要时用 @AGENTS.md 引用并要求复述关键规则。不要用项目 Memory 代替需要评审和共享的规则文件。

权限与执行问题

症状：任务一直停着不动

• **可能原因：**正在等待文件、命令、网络操作或计划审批。
• **检查：**查看当前任务输入区和侧边栏的等待状态，阅读具体路径和命令。
• **处理：**符合范围则只允许本次；路径或影响不明确则拒绝并纠正。不要为了消除提示直接切换完全访问。

症状：确认太多，任务被频繁打断

• **检查：**任务是否已明确限制在低风险练习工作区，操作是否重复且可恢复。
• **处理：**常规文件迭代可切换“自动编辑”；涉及删除、系统配置、外部提交或陌生脚本时继续使用“变更前确认”。减少确认次数不等于扩大工作区范围。

浏览器与页面问题

症状：浏览器控制已开启，Agent 仍不能操作

• **可能原因：**开关只对新任务生效，当前会话是在开启前创建的；或者你期待它直接控制手动打开的标签。
• **处理：**新建任务，让 Agent 打开自己的标签；需要它接管手动标签时显式认领。浏览器面板仅桌面端提供。

症状：Agent 说已修复，页面仍显示旧结果

• **检查：**确认浏览器打开的是当前工作区的 index.html；刷新页面；查看控制台第一条错误；比较文件时间和 Git Diff。
• **处理：**把具体 URL、复现步骤、预期与实际结果交给 Agent。不要只说“还是不行”。

症状：刷新后数据、筛选或完成状态异常

• **检查：**分别检查 focus-board.tasks 的写入和读取；确认筛选只控制显示，没有重写完整数组。
• **处理：**用最短复现步骤建立基线，再限制 Agent 只检查 app.js 的保存、恢复和筛选路径。

Git 与目标模式问题

症状：git commit 提示缺少身份

• **原因：**当前 Git 环境没有提交者名称或邮箱。
• **处理：**在练习仓库中使用第 6 课的 git config --local 设置；除非你明确希望所有项目共用，否则不必改全局配置。

症状：无法设置 /goal

• **可能原因：**当前处于计划模式，或者另一个任务仍在执行。
• **处理：**等待当前轮结束或停止它，再切换到自动编辑、变更前确认或完全访问后设置目标。目标模式和计划模式不能同时运行。

症状：目标运行很多轮仍不完成

• **检查：**目标是否有客观终点；是否有未完成待办；是否在重复同一失败；是否达到用量上限。
• **处理：**用 /goal pause 保留状态，缩小目标或补充验收证据后恢复。不要把“继续努力”当成新的验收标准。

什么时候提交官方反馈

如果问题可以稳定复现，且已经排除错误工作区、网络、账号、权限和项目代码，准备以下信息：

• 操作系统与版本；
• ZCode 版本；
• 模型通道；
• 最短复现步骤；
• 期望表现与实际表现；
• 必要的截图和脱敏日志。

macOS 可从菜单栏“ZCode → 关于 ZCode”查看版本，Windows / Linux 可从标题栏“帮助 → 关于 ZCode”查看。应用右上角反馈入口可以提交问题或导出日志；日志和截图中仍要自行检查敏感项目内容。用户反馈与支持

课程完成检查

回到自己的 focus-board，确认你能够独立完成这些动作：

• 指出工作区、任务、工具和执行模式各自控制什么；
• 打开一个项目任务，并用 @ 引用必要文件；
• 解释一次修改为何选择计划模式、变更前确认或自动编辑；
• 查看真实文件、浏览器结果、任务 Review 和 Git Diff；
• 复现缺陷后要求最小修复并完成回归；
• 设置一个带验收证据的 /goal，必要时暂停和恢复；
• 说出密钥、工作区范围、删除操作和外部副作用的安全边界。

如果其中某一项还只能照着步骤机械完成，回到对应课程再做一次不同的小改动，比继续浏览功能列表更有效。

接下来学什么

按真实需求选下一步，不需要把所有扩展都学一遍：

需求	适合继续了解
从手机继续查看和控制桌面任务	Remote Control
从飞书或微信触发已有工作区任务	Bot Channel
连接 SSH 主机或本地 Docker 容器	远程开发
保存一段短而固定的重复提示词	Command
固化包含脚本、模板和参考资料的工作方法	Skill
接入外部服务和工具	MCP
成套分发技能、命令、子智能体和 MCP	Plugin

课程到这里结束。你得到的不是一份 ZCode 菜单说明书，而是一条可以迁移到真实项目的工作路径：限定范围、提供上下文、选择权限、观察执行、独立验证、审查差异，再决定是否继续。