# ZCode 自研插件工作区

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

## 目录

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

## 常用命令

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

只想部署一个插件:

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

## 漂移检测

```bash
$ 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 生效**。
当前会话里想立刻验证,直接跑脚本本体:

```bash
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-env-sync/README.md) —— 快照结构、路径占位符、密钥束、七条命令
- [zcode-thinking-mode/README.md](zcode-thinking-mode/README.md) —— 双写原理、默认值文件、自检