zcode-patch-cli

一个使用 JavaScript AST 自动发现并修补 ZCode app-server bundle 的命令行工具。

它只处理用户指定的：

resources/glm/zcode.cjs

不会修改 app.asar，不会启动 ZCode，也不会读取或记录 prompt、API key、Authorization header 或模型响应。

环境要求

• Windows、macOS 或 Linux；
• Node.js 18 或更高版本；
• 执行落盘写入前先完全退出 ZCode。

npx 使用

默认是只读预览，不会写入文件：

npx --yes [email protected] `
  --bundle 'D:\DeveloperTools\ZCode\resources\glm\zcode.cjs'

确认报告中的 status 为 ready 后，显式使用 --apply：

npx --yes [email protected] `
  --bundle 'D:\DeveloperTools\ZCode\resources\glm\zcode.cjs' `
  --apply

发布后也可以使用不带版本号的命令：

npx --yes zcode-patch-cli --help

建议在生产环境固定版本号，避免未来规则变化造成意外行为。

目标选择

按优先级支持：

--bundle <path>
--install-dir <path>
--exe <path>
ZCODE_BUNDLE
ZCODE_INSTALL_DIR
ZCODE_EXE
默认安装路径

示例：

npx --yes [email protected] `
  --install-dir 'D:\DeveloperTools\ZCode'

也可以使用环境变量：

$env:ZCODE_BUNDLE = 'D:\DeveloperTools\ZCode\resources\glm\zcode.cjs'
npx --yes [email protected]

目标路径必须是实际的 zcode.cjs 文件；工具不会自动修改其他文件。

配置

默认策略和规则随包提供：

reasoning-policy.json
patch-rules.json

可以通过命令行或环境变量覆盖：

npx --yes [email protected] `
  --policy 'C:\config\reasoning-policy.json' `
  --rules 'C:\config\patch-rules.json'

对应环境变量为：

ZCODE_REASONING_POLICY
ZCODE_PATCH_RULES

操作模式

预览

以下命令都只读：

npx --yes [email protected] --inspect --bundle 'C:\path\zcode.cjs'
npx --yes [email protected] --dry-run --bundle 'C:\path\zcode.cjs'

默认不带模式参数时也是预览。

写入

npx --yes [email protected] --apply --bundle 'C:\path\zcode.cjs'

默认备份为：

C:\path\zcode.cjs.bak

如果备份已经存在，工具会拒绝覆盖：

npx --yes [email protected] `
  --apply `
  --overwrite-backup `
  --bundle 'C:\path\zcode.cjs'

也可以指定备份位置：

npx --yes [email protected] `
  --apply `
  --backup 'C:\backup\zcode-original.cjs' `
  --bundle 'C:\path\zcode.cjs'

--no-backup 会跳过备份，不建议常规使用：

npx --yes [email protected] `
  --apply --no-backup `
  --bundle 'C:\path\zcode.cjs'

恢复

恢复默认先预览：

npx --yes [email protected] `
  --restore 'C:\path\zcode.cjs.bak' `
  --bundle 'C:\path\zcode.cjs'

确认后实际恢复：

npx --yes [email protected] `
  --restore 'C:\path\zcode.cjs.bak' `
  --apply `
  --bundle 'C:\path\zcode.cjs'

补丁行为

工具使用 AST 查找满足以下结构的唯一候选：

• 条件返回对象包含 level；
• 同一对象包含 providerOptions；
• providerOptions 使用 providerOptionsByLevel[level]；
• 同一能力对象访问 .enabled 和 .levels；
• 候选评分达到规则阈值。

目标表达式会变为：

providerOptionsByLevel?.[level] ?? __zcodeReasoningFallback(level)

已有当前 helper 或旧版 zCfgEffort(level) 时不会重复注入。候选不唯一、语法解析失败、helper 名称冲突或目标文件在检查后发生变化时，工具会拒绝写入。

安全说明

• 写入前要求关闭 ZCode；
• 默认只读预览；
• --apply 才会写文件；
• 默认创建 .bak 备份；
• 写入前后进行 JavaScript 语法解析；
• 使用 SHA-256 检查目标是否在检查期间发生变化；
• 使用同目录临时文件进行原子替换；
• 不修改 app.asar；
• 不修改环境变量、快捷方式或 ZCode 进程；
• 不自动下载或安装 Node.js。

如果报告状态为 ambiguous、not-found、parse-error、helper-conflict 或 validation-failed，不要强行覆盖目标文件，应保留原文件并针对新版本增加规则。

开发测试

npm install
npm test

测试文件和 fixtures 只用于开发，不会被 npm files 白名单发布。

发布前检查

npm test
npm pack --dry-run

确认 tarball 只包含运行时 CLI、AST 模块、安装发现模块、两个 JSON 配置和 README 后，再按需执行 npm publish。