zcode-tooling/zcode-env-sync/commands/sync-doctor.md

description

description
自诊断 —— 一次查完所有前置条件,定位同步为什么不能用

用 Bash(Windows 用 git-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