自研 ZCode 插件的源码在这里改,~/.zcode/plugins/ 是运行时读的安装副本。两份并存意味着一个陷阱:改了源码没重装,跑的还是旧代码 —— 而报错会指向你刚改好的那个文件,排查全跑偏。这个工作区用 deploy.mjs + audit-plugins.mjs 把这件事钉死。

zcode/
  deploy.mjs            源码 → ~/.zcode/plugins,备份 + 测试 + 审计
  audit-plugins.mjs     源码 vs 安装副本 漂移检测 + 文档/语法检查
  tests/tools.test.mjs  上面两个工具自己的测试(含"能不能真发现漂移")
  package.json          一键入口
  zcode-env-sync/       插件:团队环境同步(导出/导入/校验/清理/诊断)
  zcode-thinking-mode/  插件:思考档位切换(查看/切换/默认值/自检)

常用命令

npm run deploy:dry        # 预演:会改哪些文件,不落盘
npm run deploy            # 备份 → 同步 → 跑测试 → 审计
npm run audit             # 只看源码与安装副本是否一致
npm run audit:drift       # 只要漂移结论,跳过文档/语法检查
npm run test:all          # 三个项目全测(工具 24 + env-sync 63 + thinking 28)

只想部署一个插件:

node deploy.mjs zcode-thinking-mode
node deploy.mjs zcode-thinking-mode --no-test     # 只同步
node deploy.mjs --no-deploy                       # 只测+审计,不动文件

漂移检测

$ npm run audit
### zcode-env-sync  v0.3.0
  ✗ 副本与源码有差异:
      内容不同:scripts/export.mjs
      → 重装:cp -r ".../zcode-env-sync/." ".../zcode/plugins/zcode-env-sync/"

判定口径:

情况	判定
源码有、副本没有(新增文件没部署)	✗ 失败
两边都有但内容不同	✗ 失败
版本号不一致	✗ 失败
源码已删、副本还在(`scripts/` `commands/` 等源码管理位置)	✗ 失败 —— 幽灵代码仍会被加载
根目录 / 自定义子目录的本机文件(`local-state.json` 等)	⚠ 只提示 —— 这是有意的本地产物
命令文档缺 `description` / 引用脚本不存在 / 脚本语法错	✗ 失败

残留判定只认源码管理的位置(scripts/、commands/、.zcode-plugin/,以及根目录的 .md 与 package.json)。不按扩展名一刀切 —— 否则根目录的 local-state.json 会被报成 "残留代码建议删除",把一个只读审计工具变成删数据的推手。

为什么 deploy 只增改不删

副本里可能有你有意放的本机文件(local-state.json、本机专用配置)。整目录替换会把它们一起抹掉,所以 deploy 逐文件写,只在有差异时动对应文件。

源码删掉的文件会留成幽灵代码继续被加载 —— deploy 会检测出来并打印 rm 命令, 但不自动删:删除不可逆,备份虽有,但"删了才发现还想留"的代价比多敲一行高。

部署后生效

插件、命令、hooks 都在启动时读取,重启 ZCode 生效。当前会话里想立刻验证,直接跑脚本本体:

node ~/.zcode/plugins/zcode-thinking-mode/scripts/thinking.mjs doctor
node ~/.zcode/plugins/zcode-env-sync/scripts/doctor.mjs

每个插件的文档

zcode-env-sync/README.md —— 快照结构、路径占位符、密钥束、七条命令
zcode-thinking-mode/README.md —— 双写原理、默认值文件、自检