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,30 @@
+---
+description: 自诊断 —— 一次查完所有前置条件,定位同步为什么不能用
+---
+
+用 Bash(Windows 用 git-bash)运行诊断脚本(只读,不改任何东西):
+
+```bash
+export ZCODE_SYNC_PASSPHRASE='团队口令'   # 给了才能验证"latest 能否解密"
+SYNC_PLUGIN="${ZCODE_SYNC_PLUGIN:-$(find ~/.zcode/plugins -maxdepth 3 -name doctor.mjs -path '*env-sync*' 2>/dev/null | head -1)}"
+node "$SYNC_PLUGIN"
+```
+
+二十多项检查(条数随环境变化),每项给 `✓ ok` / `⚠ warn` / `✗ fail`,失败项附**可执行的修复建议**:
+
+- 运行时:Node 版本、git 是否可用
+- 凭据:同步口令是否设置且够长、Gitea token 是否读到
+- 仓库:工作区是否已克隆、`origin` 是否内嵌凭据(会明文留在 `.git/config`)、
+  换行符锁定(`.gitattributes: * -text` + `core.autocrlf=false`,否则 hash 会漂移)、
+  `HEAD` 与 `origin/main` 是否一致、有无未提交改动
+- 快照:总数与总体积、manifest 是否损坏、`latest` 指向是否有效、**当前口令能否解开 latest**
+- 环境:启用插件数、自研插件、本插件版本、MCP server 数、模型 provider(几个带密钥)、备份目录
+
+退出码:有 `fail` 时为 1。
+
+用法场景:**用户说"同步不工作/导入失败/推送失败/status 报版本不同"时,先跑这个**,
+再把报告里的 `fail` 项与修复建议照实告诉用户,不要自己猜。
+
+**把脚本输出原样展示给用户**。
+
+用户附加要求:$ARGUMENTS
@@ -0,0 +1,32 @@
+---
+description: 导出本机 ZCode 环境快照并推送到 Gitea 私仓(root/zcode-env-sync)
+---
+
+用 Bash(Windows 用 git-bash)运行导出脚本。口令必须先设置(团队线下约定,**不要进仓**):
+
+```bash
+export ZCODE_SYNC_PASSPHRASE='团队口令'
+SYNC_PLUGIN="${ZCODE_SYNC_PLUGIN:-$(find ~/.zcode/plugins -maxdepth 3 -name export.mjs -path '*env-sync*' 2>/dev/null | head -1)}"
+node "$SYNC_PLUGIN" $ARGUMENTS
+```
+
+`SYNC_PLUGIN` 从本机插件目录自动定位,不写死路径(快照要跨机器还原,
+写死路径到了别的机器就是废的)。也可以直接设 `ZCODE_SYNC_PLUGIN=/绝对/路径/export.mjs`。
+
+可选参数(环境变量):
+
+- `ZCODE_SYNC_REPO=root/zcode-env-sync` 私仓坐标
+- `ZCODE_SYNC_HOST=https://gitea.mymoyu.top` 托管地址
+- `ZCODE_SYNC_WORK=~/.zcode-env-sync` 本地工作区(含 repo clone 与备份)
+- `ZCODE_SYNC_WITH_MODELS=1` 连带同步模型 provider(默认关;开启时**只写脱敏版**,
+  真密钥走加密束) —— 覆盖默认 4 项
+- `ZCODE_SYNC_NO_PUSH=1` 只落本地不推远端(离线排查用)
+- `ZCODE_SYNC_ALLOW_SECRETS='$.路径'` 逗号分隔,放行已知误报的密钥扫描
+- `ZCODE_SYNC_ALLOW_PATH_LEAK=1` 放行路径残留自检(确认无害时才用)
+
+导出过程自带两道闸门,命中即中断且**不推送**:明文区出现真密钥值、明文区残留本机路径。
+
+**把脚本输出原样展示给用户**,包含快照名、推送结果、各项统计。
+失败时把报错和缺什么说清楚,不要自己编快照名。
+
+用户附加要求:$ARGUMENTS
@@ -0,0 +1,32 @@
+---
+description: 从 Gitea 私仓拉快照还原到本机(先自动备份)
+---
+
+用 Bash(Windows 用 git-bash)运行导入脚本。口令必须先设置(解密密钥束用):
+
+```bash
+export ZCODE_SYNC_PASSPHRASE='团队口令'
+SYNC_PLUGIN="${ZCODE_SYNC_PLUGIN:-$(find ~/.zcode/plugins -maxdepth 3 -name import.mjs -path '*env-sync*' 2>/dev/null | head -1)}"
+node "$SYNC_PLUGIN" [快照名] $ARGUMENTS
+```
+
+`SYNC_PLUGIN` 从本机插件目录自动定位,不写死路径。
+也可以直接设 `ZCODE_SYNC_PLUGIN=/绝对/路径/import.mjs`。
+
+- 快照名缺省用远端 `latest.json` 指向的最新快照
+- 可用快照名形如 `主机名-20260911-153000`,先 `/sync-status` 看远端有哪些
+- 还原前自动备份被覆盖文件到 `~/.zcode-env-sync/backup/<时间>/`,报告里给出实际路径
+- 官方插件只报告差异(缺几项、分别是什么),**不自动安装**,去插件市场对照启用后重启
+- 机器特有路径(host/port/command)可写 `~/.zcode-env-sync/overrides.json`(不进仓),导入自动合并
+- 每人身份不同(token 各用各的)时加 `ZCODE_SYNC_SKIP_SECRETS='DSH_SECRETS/gitea-token.txt'`,
+  只同步连接配置不盖 token;模型密钥同理用 `MODELS/<provider>/<key>` 格式
+- 模型 provider 只报告不覆盖本机 `v2/config.json`(里面有活的 apiKey);
+  确需应用要显式开 `ZCODE_SYNC_WITH_MODELS=1`,此时:脱敏结构合并(只增不减)、
+  密钥按 `MODELS/<provider>/<key>` 回填(只填空位,本机已有密钥默认跳过保护;
+  确需覆盖再加 `ZCODE_SYNC_OVERWRITE_MODEL_SECRETS=1`);选中态(当前用哪个模型)
+  默认不动,加 `ZCODE_SYNC_APPLY_MODEL_SELECTION=1` 才应用
+- `ZCODE_SYNC_APPLY_OFFICIAL=0` 可跳过官方插件差异报告
+
+**把脚本输出原样展示给用户**。失败时把报错和缺什么说清楚。
+
+用户附加要求:$ARGUMENTS
@@ -0,0 +1,19 @@
+---
+description: 列出远端全部快照(只读),含体积/内容概要与 latest 标记
+---
+
+用 Bash(Windows 用 git-bash)运行状态脚本加 `--list`(只读,不改本机,不需要口令):
+
+```bash
+SYNC_PLUGIN="${ZCODE_SYNC_PLUGIN:-$(find ~/.zcode/plugins -maxdepth 3 -name status.mjs -path '*env-sync*' 2>/dev/null | head -1)}"
+node "$SYNC_PLUGIN" --list
+```
+
+输出每个快照的:名字、来源主机与时间、体积、官方启用数/自研插件(含版本)/MCP 数/密钥数/模型 provider 数。
+`*` 标出 `latest.json` 指向的那个 —— `/sync-import` 不带参数时用的就是它。
+
+用户问"有哪些快照/能回到哪个版本"时用这条;要看**本机与最新快照的差异**用 `/sync-status`(不带 `--list`)。
+
+**把脚本输出原样展示给用户**。
+
+用户附加要求:$ARGUMENTS
@@ -0,0 +1,27 @@
+---
+description: 清理远端旧快照(默认只预演,加 --apply 才真删)
+---
+
+用 Bash(Windows 用 git-bash)运行清理脚本:
+
+```bash
+SYNC_PLUGIN="${ZCODE_SYNC_PLUGIN:-$(find ~/.zcode/plugins -maxdepth 3 -name prune.mjs -path '*env-sync*' 2>/dev/null | head -1)}"
+node "$SYNC_PLUGIN" [--keep N] [--apply] [--exclude <快照名>]
+```
+
+**默认只预演(dry-run),不删任何东西**;要真删必须显式加 `--apply`。
+
+- `--keep N` 保留最近 N 个(默认 10,也可用 `ZCODE_SYNC_KEEP` 设)
+- `--exclude <快照名>` 额外钉住某个快照(可重复);`--exclude=X` 亦可
+- 永远不动:`latest.json` 指向的那个、最新的那个、你钉住的那些
+- 删完若 `latest.json` 指向被删的快照,会自动重指到一个还活着的
+- `ZCODE_SYNC_NO_PUSH=1` 只本地删不推远端(排查用)
+
+**先跑一次不带 `--apply` 的,把预演结果给用户确认**(会列出删哪几个、各多大、共释放多少),
+用户确认后再加 `--apply` 重跑。不要不问就删。
+
+清理会真的删掉远端历史,**这是不可逆的**;用户若没明确说"删",就只跑预演并告诉他加上 `--apply` 才会删。
+
+**把脚本输出原样展示给用户**。
+
+用户附加要求:$ARGUMENTS
@@ -0,0 +1,20 @@
+---
+description: 对比本机与远端最新快照差异(只读)
+---
+
+用 Bash(Windows 用 git-bash)运行状态脚本(只读,不改本机,不需要口令):
+
+```bash
+SYNC_PLUGIN="${ZCODE_SYNC_PLUGIN:-$(find ~/.zcode/plugins -maxdepth 3 -name status.mjs -path '*env-sync*' 2>/dev/null | head -1)}"
+node "$SYNC_PLUGIN" $ARGUMENTS
+```
+
+`SYNC_PLUGIN` 从本机插件目录自动定位,不写死路径。
+
+输出各项对比:官方插件启用差异、自研插件版本差异、MCP server 名差异、密钥束清单差异。
+若快照带模型 provider,还会有一行 provider 差异(只比 id/模型清单)。
+密钥只比清单 hash,不读值、不解密。
+
+**把脚本输出原样展示给用户**。
+
+用户附加要求:$ARGUMENTS
@@ -0,0 +1,31 @@
+---
+description: 校验快照完整性(hash/密钥束/占位符),导入前确认没坏
+---
+
+用 Bash(Windows 用 git-bash)运行校验脚本:
+
+```bash
+export ZCODE_SYNC_PASSPHRASE='团队口令'        # 要解密密钥束就得给
+SYNC_PLUGIN="${ZCODE_SYNC_PLUGIN:-$(find ~/.zcode/plugins -maxdepth 3 -name verify.mjs -path '*env-sync*' 2>/dev/null | head -1)}"
+node "$SYNC_PLUGIN" [快照名] [--all] [--strict] [--quiet]
+```
+
+参数:
+
+- 不带参数 → 校验 `latest.json` 指向的快照
+- `[快照名]` → 校验指定快照
+- `--all` → 扫全部快照,逐个标出「结构OK / 可解密 / 口令不符」。**团队仓里混着不同口令导出的快照时用这个**——它会告诉你当前口令能用的是哪几个,并给出 `/sync-import <可用快照名>`
+- `--strict` → 有警告也算失败(退出码 1);等价于 `ZCODE_SYNC_VERIFY_STRICT=1`
+- `--quiet` → 只打汇总,不列通过明细
+
+校验内容:必备文件是否齐全、自研插件目录 hash 与 manifest 是否一致、密钥束能否用当前口令解密、
+密钥清单 hash 是否对得上、配置区有没有残留未占位符化的绝对路径、manifest 自洽性。
+
+**只比哈希、不落地、不打印任何密钥值**。退出码:有致命错误为 1。
+
+导入前跑一次最稳;`/sync-import` 失败(尤其"解密失败")时也先跑这个定位。
+`--all` 与 `--strict` 会让脚本退出码非 0,那是**校验结果**,不是脚本坏了 —— 照报告里的建议做。
+
+**把脚本输出原样展示给用户**。
+
+用户附加要求:$ARGUMENTS