feat: zcode thinking-mode 0.3.0（state历史+rollback+分写+校验收紧+34用例全绿+文档）

2026-09-21 09:47:20 +08:00
commit 6ed5dda847
41 changed files with 6213 additions and 0 deletions
@@ -0,0 +1,83 @@
+# 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) —— 双写原理、默认值文件、自检