ZCode Chat
在 VS Code 侧栏里和 ZCode 智能体对话。本扩展不单独登录、不保存自己的密钥，只复用本机 ZCode 桌面应用 的账号、模型和会话。
对话时不必开着桌面窗口。更换项目、重新登录或登录过期后，在桌面端完成操作，再在扩展里选「重新读取登录」。
适配范围
本扩展只跟 当前最新的 ZCode 桌面端 一起用（已在 3.12.3 验证）。更早的桌面版本不支持。
桌面端大版本更新后，协议可能变化，需要换用对应的本扩展版本。不要把本扩展配到旧桌面，也不要在未更新扩展的情况下指望兼容更新后的桌面。
本地适配可能有问题。遇到对不上的地方，用其他智能体查一下、改一下即可。
正常运行需要什么
缺任何一条，侧栏都不会稳定显示「已连接」：
| # |
条件 |
如何确认 |
| 1 |
VS Code 1.85 或更高，已安装本扩展并 Reload Window |
帮助 → 关于 |
| 2 |
本机可执行 Node.js |
终端执行 node -v；不行则在设置里填 zcode.nodePath |
| 3 |
已安装 最新 ZCode 桌面端（3.12.3 或同代），且能找到 zcode.cjs |
见下方探测路径 |
| 4 |
桌面端 已经登录过 |
存在 ~/.zcode/v2/setting.json 和 ~/.zcode/v2/credentials.json |
| 5 |
当前桌面选择里有 还能用的模型凭据（个人或团队项目，且有额度） |
桌面端能正常开一个新对话 |
扩展实际启动的是：
node <zcode.cjs> app-server
不要把 Electron 主程序（名为 zcode / ZCode 的那个）填进 zcode.binaryPath。
安装
命令面板：Extensions: Install from VSIX… → 选 zcode-desktop-chat-0.1.0.vsix → Developer: Reload Window。
code --install-extension zcode-desktop-chat-0.1.0.vsix --force
Windows 若从开始菜单打开的 VS Code 里 node 不在 PATH，先在系统终端确认 node -v，再把可执行文件路径填到 zcode.nodePath。
使用
- 活动栏 ZCode 图标，或
Ctrl+Shift+Z（macOS：Cmd+Shift+Z）。
- 输入框右上角「已连接」后即可发送。
Enter 发送，Shift+Enter 换行。
- 发出去后发送键变为终止。生成中再输入文字，变为插入（排队）和立即插入。排队中的消息可以修改、删除或立即发送。
- 输入框下方切换模型、权限模式（变更前确认 / 自动编辑 / 计划 / 完全访问）、推理强度。
- 点左上角会话名可改名，回车保存。时钟图标打开历史：切换或归档；已归档的可以删除。
- 本扩展里的会话会出现在桌面端同一工作区的列表中。请先打开一个文件夹再聊，否则工作区会落到用户主目录，和桌面端对不齐。
输入框上方是当前文件芯片；有选区时带行号。点芯片可对模型隐藏（变灰）。引用格式与桌面端相同，例如 [main.ts](./src/main.ts#L12-L34)。
编辑器右键：
- ZCode: Add Selection to Chat — 钉住选区
- ZCode: Add Current File to Chat — 钉住文件
智能体改了文件后，工具卡片上可以打开文件或查看 diff。
登录与模型
| 操作 |
模型 |
鉴权 |
| 打开已有会话 |
沿用该会话当时的供应商和模型 |
用桌面端当前登录里、同一供应商的凭据 |
| 新建会话 |
桌面端当前默认供应商和模型 |
同样用当前桌面登录 |
| 桌面端切换个人 / 团队项目 |
已有会话的模型不变 |
扩展重新读取桌面选择 |
个人额度用尽会出现余额不足。在桌面端切到仍有额度的项目，再在扩展里「重新读取登录」。
设置
VS Code 设置里搜索 ZCode：
| 设置 |
默认 |
说明 |
zcode.binaryPath |
空（自动探测） |
zcode.cjs 的绝对路径 |
zcode.nodePath |
空（用 node） |
Node 可执行文件的绝对路径 |
zcode.workspacePath |
空（当前窗口第一个文件夹） |
发给智能体的工作区根目录 |
zcode.model |
空（跟桌面默认） |
覆盖项，格式 providerId/modelId |
相关命令：ZCode: Show Log、ZCode: Open Chat。
本机文件
路径在 Windows 下把 ~ 换成 %USERPROFILE%。
| 路径 |
作用 |
~/.zcode/v2/setting.json |
桌面当前是个人还是团队、默认模型 |
~/.zcode/v2/credentials.json |
登录凭据（加密）。扩展只读，不把密钥打进 vsix |
~/.zcode/v2/tasks-index.sqlite |
桌面侧栏会话索引（含归档） |
~/.zcode/cli/db/db.sqlite |
会话正文 |
zcode.cjs |
与桌面同源的 app-server 入口 |
zcode.cjs 探测顺序
- 设置
zcode.binaryPath（若已填）
- macOS：
/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs，以及 ~/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs
- Windows：
%LOCALAPPDATA%\Programs\ZCode\resources\glm\zcode.cjs
- Linux：
/opt/ZCode/resources/glm/zcode.cjs、/usr/lib/zcode/resources/glm/zcode.cjs、~/.local/share/ZCode/resources/glm/zcode.cjs
排查
先打开 ZCode: Show Log（输出面板频道名 ZCode），再对照下面的提示。聊天错误卡片上的「重试 / 打开日志 / 重新读取登录 / 选择模型」与这些情况对应。
本机自检
在系统终端执行（不要用扩展自己的终端，以免 PATH 不一致）：
node -v
code --version
Linux / macOS：
test -f /opt/ZCode/resources/glm/zcode.cjs && echo "cjs: /opt/ZCode/resources/glm/zcode.cjs"
ls -l ~/.zcode/v2/setting.json ~/.zcode/v2/credentials.json
macOS 可再查 /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs。Windows 可再查 %LOCALAPPDATA%\Programs\ZCode\resources\glm\zcode.cjs。
能找到 zcode.cjs 时，可手动试启动（应保持前台运行、不要当日常用法）：
node /opt/ZCode/resources/glm/zcode.cjs app-server
node: not found / 无法将 node 项识别为 cmdlet → 装 Node 或填 zcode.nodePath。
Cannot find module / 文件不存在 → 桌面未安装或 zcode.binaryPath 填错。
界面提示对照
| 看到的内容 |
常见原因 |
处理 |
| 一直「连接中」或「读取登录…」然后失败 |
找不到 node、找不到 zcode.cjs、app-server 起不来 |
自检 node -v 和 zcode.cjs；看日志里 Starting app-server 的 cmd / args |
ZCode credentials not found |
没有 ~/.zcode/v2/credentials.json |
打开桌面端登录后再 Reload |
ZCode desktop data not found |
没有 ~/.zcode/v2 |
先安装并登录桌面端 |
Could not reuse the BigModel team plan / coding-plan login |
桌面 OAuth 过期，或当前选的项目换了 |
桌面端保持登录并选对项目，扩展里「重新读取登录」 |
Provider … has no usable API key |
选中的供应商在当前登录里没有密钥 |
桌面端切回有密钥的项目，或换模型 |
ZCode startup failed / ZCode process exited |
子进程立刻退出 |
日志 stderr；确认 binaryPath 指向 .cjs 且用 node 启动 |
无法定位 CLI ZCode Built-in Provider Config |
桌面更新后 app-server 找不到内置模型配置 |
确认桌面已打开过一次；扩展会带上 ZCODE_BUILTIN_PROVIDER_* 环境变量。若仍失败，检查 /opt/ZCode/resources/config/provider/zcode-builtin.json（macOS 在 ZCode.app/Contents/Resources/config/provider/） |
Unrecognized key / Method not found / not in the workspace model registry |
桌面端版本和本扩展不匹配 |
把 ZCode 桌面升到当前最新，并安装对应的本扩展 vsix |
余额不足 / 类似额度错误 |
当前桌面选择的套餐没额度 |
桌面端换有额度的项目，再「重新读取登录」 |
| 历史里归档会话跑到「活动」 |
读不了桌面的 tasks-index.sqlite（少见） |
看日志里 sqlite / archive；VS Code 过旧时能力会降级，一般仍能聊 |
| 已连接但工作区里看不到刚才的会话 |
当前窗口文件夹和桌面打开的不是同一路径 |
用「打开文件夹」打开同一个项目；不要依赖 zcode.workspacePath 除非有意覆盖 |
日志里成功启动时会出现类似：
Starting app-server { cmd: 'node', args: [ '…/zcode.cjs', 'app-server' ], cwd: '…' }
cmd 必须是 node（或你填的 zcode.nodePath），args[0] 必须是存在的 zcode.cjs。
需要请人协助时
把下面几项一并给出（不要发送 credentials.json 原文或任何 API Key）：
- 操作系统和 VS Code 版本（
code --version）
node -v 的完整输出，或「VS Code 里找不到 node」- 是否已安装桌面端、能否在桌面里正常聊天
- 侧栏完整提示原文（可截图）
- ZCode: Show Log 里从启动到报错的一段（可打码家目录用户名）
从源码构建
npm install
npm run build
npx vsce package --no-dependencies --allow-missing-repository --no-rewrite-relative-links
