@mison/wecom-cleaner 1.3.0 → 1.3.3

package/README.md

@@ -96,10 +96,12 @@
 
 - 启动后按“早/午/晚”三时段检查更新（默认开启）。
 - 版本源优先 npmjs，失败自动回退 GitHub Release。
+- 检查更新会同时校验 Agent skills 是否与主程序版本匹配。
 - 交互模式发现新版本时可直接选择升级方式：
   - npm 升级（默认）
   - GitHub 脚本升级
-- 无交互模式仅提示不阻断任务执行。
+- 程序升级完成后默认联动同步 skills，避免“程序已升级但 skills 仍旧版”。
+- 无交互模式可用 `--sync-skills` 单独修复 skills 版本绑定。
 
 ## 能力边界
 
@@ -154,12 +156,16 @@ npx --yes --package=@mison/wecom-cleaner wecom-cleaner-skill install
 - `--target <dir>`：自定义安装目录（默认 `$CODEX_HOME/skills` 或 `~/.codex/skills`）
 - `--force`：覆盖已存在技能目录
 - `--dry-run`：仅预演，不落盘
+- `status` 子命令：检查 skills 与主程序版本是否匹配
+- `sync` 子命令：等价 `install --force`，用于升级 skills
 
 示例：
 
 ```bash
 npx --yes --package=@mison/wecom-cleaner wecom-cleaner-skill install --force
 npx --yes --package=@mison/wecom-cleaner wecom-cleaner-skill install --target ~/.codex/skills
+npx --yes --package=@mison/wecom-cleaner wecom-cleaner-skill status --json
+npx --yes --package=@mison/wecom-cleaner wecom-cleaner-skill sync
 ```
 
 GitHub 备选方式（无 npm 包依赖）：
@@ -168,10 +174,10 @@ GitHub 备选方式（无 npm 包依赖）：
 curl -fsSL https://raw.githubusercontent.com/MisonL/wecom-cleaner/main/scripts/install-skill.sh | bash
 ```
 
-若需安装指定版本标签（例如 `v1.3.0`）：
+若需安装指定版本标签（例如 `v1.3.3`）：
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/MisonL/wecom-cleaner/main/scripts/install-skill.sh | bash -s -- --ref v1.3.0
+curl -fsSL https://raw.githubusercontent.com/MisonL/wecom-cleaner/main/scripts/install-skill.sh | bash -s -- --ref v1.3.3
 ```
 
 Agent 侧统一任务入口脚本（位于 `skills/wecom-cleaner-agent/scripts/`）：
@@ -204,6 +210,7 @@ Agent 侧统一任务入口脚本（位于 `skills/wecom-cleaner-agent/scripts/`
 - `--doctor`
 - `--check-update`
 - `--upgrade <npm|github-script>`
+- `--sync-skills`
 
 ### 无交互安全规则
 
@@ -238,6 +245,9 @@ wecom-cleaner --space-governance \
 # 回收区治理（按策略执行）
 wecom-cleaner --recycle-maintain --dry-run false --yes
 
+# 年月清理（三阶段协议：预演 -> 执行 -> 复核）
+wecom-cleaner --cleanup-monthly --accounts all --cutoff-month 2024-04 --run-task preview-execute-verify --yes
+
 # 批次恢复（冲突策略：重命名）
 wecom-cleaner --restore-batch 20260226-105009-ffa098 --conflict rename
 
@@ -251,13 +261,18 @@ wecom-cleaner --check-update --output text
 wecom-cleaner --upgrade npm --upgrade-yes
 
 # 执行升级（GitHub 托管脚本方式）
-wecom-cleaner --upgrade github-script --upgrade-version 1.3.1 --upgrade-yes
+wecom-cleaner --upgrade github-script --upgrade-version 1.3.3 --upgrade-yes
+
+# 单独同步 skills（修复版本不匹配）
+wecom-cleaner --sync-skills --skill-sync-method npm --dry-run false
 ```
 
 ### 输出与兼容参数
 
 - `--output json|text`：无交互输出格式，默认 `json`。
 - `--json`：兼容别名，等价于 `--output json`。
+- `--run-task preview|execute|preview-execute-verify`：阶段任务协议（推荐给 Agent）。
+- `--scan-debug off|summary|full`：扫描诊断信息输出等级。
 - `--mode`：兼容参数，建议迁移到动作参数（如 `--cleanup-monthly`）。
 - `--save-config`：将本次全局配置参数写回 `config.json`。
 - `--help` / `-h`：输出命令帮助并退出。
@@ -265,6 +280,9 @@ wecom-cleaner --upgrade github-script --upgrade-version 1.3.1 --upgrade-yes
 - `--upgrade-channel stable|pre`：升级检查通道（稳定版/预发布）。
 - `--upgrade-version <x.y.z>`：指定升级目标版本。
 - `--upgrade-yes`：确认执行升级动作（无此参数将拒绝执行升级）。
+- `--upgrade-sync-skills true|false`：升级后是否联动同步 skills（默认 `true`）。
+- `--skill-sync-method npm|github-script`：skills 同步方式（默认 `npm`）。
+- `--skill-sync-ref <x.y.z>`：skills 同步版本标签（通常与程序版本一致）。
 
 ### 各动作关键统计字段（JSON）
 
@@ -280,6 +298,7 @@ wecom-cleaner --upgrade github-script --upgrade-version 1.3.1 --upgrade-yes
 - `summary.rootPathCount`：涉及的清理根目录数量
 - `summary.accountCount` / `monthCount` / `categoryCount` / `externalRootCount`
 - `summary.cutoffMonth`：截止月份（当使用 `--cutoff-month` 时）
+- `summary.runTaskMode` / `summary.taskDecision`：阶段协议模式与决策（仅 `--run-task`）
 
 `cleanup-monthly` 还会在 `data.report` 中返回可展示明细：
 
@@ -288,6 +307,9 @@ wecom-cleaner --upgrade github-script --upgrade-version 1.3.1 --upgrade-yes
 - `data.report.matched.rootStats`：按根目录统计（条目数、体积）
 - `data.report.matched.topPaths`：按体积 Top 路径样例
 - `data.report.executed.byCategory/byMonth/byRoot`：真实执行落地统计（成功/跳过/失败 + 体积）
+- `data.taskPhases`：阶段执行明细（预演/执行/复核）
+- `data.taskCard`：面向用户的任务卡片聚合结果
+- `data.scanDebug`：扫描诊断（当 `--scan-debug summary|full`）
 
 #### `analysis-only`
 
@@ -334,7 +356,10 @@ wecom-cleaner --upgrade github-script --upgrade-version 1.3.1 --upgrade-yes
 - `summary.currentVersion` / `latestVersion`
 - `summary.source`：`npm` 或 `github`
 - `summary.channel`：`stable` 或 `pre`
+- `summary.skillsStatus` / `summary.skillsMatched`
+- `summary.skillsInstalledVersion` / `summary.skillsBoundAppVersion`
 - `data.update`：检查详情（含 `errors`、`checkReason`、`checkedAt`）
+- `data.skills`：skills 绑定详情（状态、目录、建议）
 
 #### `upgrade`
 
@@ -343,6 +368,17 @@ wecom-cleaner --upgrade github-script --upgrade-version 1.3.1 --upgrade-yes
 - `summary.targetVersion`：目标版本
 - `summary.status`：升级命令退出码
 - `data.upgrade.command`：实际执行命令
+- `summary.skillSyncStatus` / `summary.skillSyncMethod` / `summary.skillSyncTargetVersion`
+- `summary.skillsStatusBefore` / `summary.skillsStatusAfter`
+- `data.skillSync`：skills 同步命令结果
+
+#### `sync-skills`
+
+- `summary.method`：skills 同步方式（`npm` / `github-script`）
+- `summary.status`：`dry_run` / `synced` / `failed` / `mismatch_after_sync`
+- `summary.skillsStatusBefore` / `summary.skillsStatusAfter`
+- `data.before` / `data.after`：同步前后 skills 绑定详情
+- `data.skillSync`：执行命令与退出码
 
 ### 全局参数
 
@@ -355,6 +391,8 @@ wecom-cleaner --upgrade github-script --upgrade-version 1.3.1 --upgrade-yes
 - `--theme <auto|light|dark>`：Logo 主题
 - `--interactive`：即使携带参数也进入交互流程（可配合 `--mode`）
 - `--force`：锁异常场景下强制清理并继续（兜底参数，通常无需）
+- `--run-task preview|execute|preview-execute-verify`：阶段任务协议（推荐无交互自动化调用）
+- `--scan-debug off|summary|full`：附加扫描诊断信息
 
 ### `--theme` 可选值
 
@@ -438,8 +476,8 @@ npm run pack:tgz:dry-run
 
 当前基线（主分支）：
 
-- 单元测试：`100/100` 通过。
-- 覆盖率：`statements 87.63%`，`branches 74.03%`，`functions 92.47%`，`lines 87.63%`。
+- 单元测试：`107/107` 通过。
+- 覆盖率：`statements 87.66%`，`branches 74.38%`，`functions 92.47%`，`lines 87.66%`。
 - 全菜单 smoke：通过（含恢复冲突分支与 doctor JSON 分支）。
 
 ## 测试矩阵
@@ -482,7 +520,7 @@ npm run pack:tgz
 npm run pack:release-assets
 
 # 2) 推送主分支与标签
-VERSION="1.3.0"
+VERSION="1.3.3"
 git push origin main
 git tag "v${VERSION}"
 git push origin "v${VERSION}"

package/docs/IMPLEMENTATION_PLAN.md

@@ -122,7 +122,7 @@
 - 使用 `c8` 输出覆盖率报告。
 - 门禁阈值：`lines/statements >= 75%`，`functions >= 80%`，`branches >= 60%`。
 - 命令：`npm run test:coverage` / `npm run test:coverage:check`。
-- `v1.1.0` 基线：`statements 86.57%`，`branches 73.96%`，`functions 93.25%`，`lines 86.57%`。
+- `v1.3.2` 基线：`statements 87.66%`，`branches 74.38%`，`functions 92.47%`，`lines 87.66%`。
 
 4. 端到端回归
 
@@ -142,17 +142,17 @@ npm run pack:tgz:dry-run
 
 1. 版本与产物
 
-- `package.json` / `package-lock.json`：`1.1.0`
-- `native/manifest.json`：版本与 `baseUrl` 对齐 `v1.1.0`
+- `package.json` / `package-lock.json`：`1.3.2`
+- `native/manifest.json`：版本与 `baseUrl` 对齐当前发布标签
 - 默认打包双架构核心：`darwin-x64` + `darwin-arm64`
 
 2. GitHub Release
 
 ```bash
 git push origin main
-git tag v1.1.0
-git push origin v1.1.0
-gh release create v1.1.0 --title "v1.1.0" --notes-file docs/releases/v1.1.0.md wecom-cleaner-1.1.0.tgz
+git tag v1.3.2
+git push origin v1.3.2
+gh release create v1.3.2 --title "v1.3.2" --notes-file docs/releases/v1.3.2.md wecom-cleaner-1.3.2.tgz
 ```
 
 3. npm 发布

package/docs/NON_INTERACTIVE_SPEC.md

@@ -22,6 +22,7 @@
 - `--doctor`
 - `--check-update`
 - `--upgrade <npm|github-script>`
+- `--sync-skills`
 
 若缺少动作或动作冲突，退出码为 `2`。
 
@@ -34,6 +35,10 @@
 - 默认 `dry-run`（不执行真实删除/恢复）。
 - 真实执行需显式传 `--yes`。
 - 若传 `--dry-run false` 且未传 `--yes`，退出码为 `3`。
+- 可通过 `--run-task` 启用阶段协议：
+  - `preview`：仅预演阶段。
+  - `execute`：仅真实执行阶段（破坏性动作需 `--yes`）。
+  - `preview-execute-verify`：预演 -> 真实执行 -> 同条件复核（预演命中 `0` 时自动跳过执行与复核）。
 
 ## 4. 输出协议
 
@@ -41,6 +46,8 @@
 
 - `--output json|text`（默认 `json`）
 - `--json` 为兼容别名（等价 `--output json`）
+- `--run-task preview|execute|preview-execute-verify`（推荐破坏性动作使用）
+- `--scan-debug off|summary|full`（默认 `off`）
 
 JSON 顶层字段：
 
@@ -53,6 +60,10 @@ JSON 顶层字段：
 - `data`：动作明细数据
 - `meta`：元信息（版本、耗时、引擎、时间戳等）
 - `data.userFacingSummary`：统一的用户侧结果摘要（范围 + 结果 + 关键分布）
+  - `scopeNotes`：扫描边界说明（例如是否纳入“文件存储位置”目录、是否因命中为 0 跳过执行）
+- `data.taskPhases`：阶段协议明细（仅在 `--run-task` 时返回）
+- `data.taskCard`：阶段任务卡片（仅在 `--run-task` 时返回）
+- `data.scanDebug`：扫描诊断信息（仅在 `--scan-debug summary|full` 时返回）
 
 `cleanup_monthly` 常见 `summary` 字段：
 
@@ -173,12 +184,23 @@ JSON 顶层字段：
 - `hasUpdate`
 - `currentVersion` / `latestVersion`
 - `source`
+- `sourceChain`（来源链路说明：先 npm，必要时自动回退 GitHub）
 - `channel`
 - `skippedByUser`
+- `skillsStatus` / `skillsMatched`
+- `skillsInstalledVersion` / `skillsBoundAppVersion`
 
 `check_update` 的 `data`：
 
 - `update`：更新检查详情（`checkedAt`、`checkReason`、`errors`、`upgradeMethods`）
+- `skills`：skills 版本绑定详情（状态、目录、建议）
+
+说明：
+
+- 当 npm 失败但 GitHub 回退成功时，动作整体仍为成功：
+  - `summary.source=github`
+  - `summary.sourceChain` 会说明“npm 失败后回退”
+  - 失败细节进入 `warnings`，不计入 `errors`
 
 `upgrade` 常见 `summary` 字段：
 
@@ -187,11 +209,31 @@ JSON 顶层字段：
 - `targetVersion`
 - `status`
 - `command`
+- `skillSyncEnabled`
+- `skillSyncMethod`
+- `skillSyncStatus`
+- `skillSyncTargetVersion`
+- `skillsStatusBefore` / `skillsStatusAfter`
 
 `upgrade` 的 `data`：
 
 - `upgrade`：升级执行结果（stdout/stderr/exit status）
 - `update`：升级前检查结果（若有）
+- `skills`：升级前后 skills 绑定状态
+- `skillSync`：skills 同步执行结果
+
+`sync_skills` 常见 `summary` 字段：
+
+- `method`：同步方式（`npm` / `github-script`）
+- `dryRun`：是否预演
+- `status`：`dry_run` / `synced` / `failed` / `mismatch_after_sync`
+- `skillsStatusBefore` / `skillsStatusAfter`
+- `skillsMatchedAfter`
+
+`sync_skills` 的 `data`：
+
+- `before` / `after`：同步前后 skills 绑定详情
+- `skillSync`：执行命令与退出码
 
 ## 5. 退出码
 
@@ -215,6 +257,11 @@ JSON 顶层字段：
 - `--upgrade-channel <stable|pre>`：更新通道（稳定版/预发布）
 - `--upgrade-version <x.y.z>`：升级到指定版本
 - `--upgrade-yes`：确认执行升级（无此参数将拒绝执行升级）
+- `--upgrade-sync-skills <true|false>`：升级后是否联动同步 skills（默认 `true`）
+- `--skill-sync-method <npm|github-script>`：skills 同步方式
+- `--skill-sync-ref <x.y.z>`：skills 同步版本标签
+- `--run-task preview|execute|preview-execute-verify`：无交互阶段协议
+- `--scan-debug off|summary|full`：扫描诊断输出等级
 
 ## 7. 动作参数
 
@@ -285,6 +332,18 @@ JSON 顶层字段：
 
 - `npm`：执行 `npm i -g @mison/wecom-cleaner@<version>`
 - `github-script`：执行 GitHub 托管脚本 `scripts/upgrade.sh`
+- 默认会联动同步 skills，可通过 `--upgrade-sync-skills false` 关闭。
+
+### 7.9 `--sync-skills`
+
+- `--skill-sync-method <npm|github-script>`（可选，默认 `npm`）
+- `--skill-sync-ref <x.y.z>`（可选）
+- `--dry-run <true|false>`（可选，默认 `false`）
+
+说明：
+
+- 用于单独修复/升级 Agent skills 版本绑定。
+- `npm` 方式优先使用本地随包 skills；`github-script` 方式按指定版本标签下载。
 
 ## 8. 兼容参数
 

package/docs/TEST_MATRIX.md

@@ -26,6 +26,7 @@
 - `doctor`
 - `check_update`
 - `upgrade`
+- `sync_skills`
 
 ### 维度 C：范围组合
 
@@ -39,6 +40,8 @@
 - dry-run（预演）
 - 真实执行（`--dry-run false --yes`）
 - 真实执行后复核（同条件二次运行）
+- 阶段协议（`--run-task preview|execute|preview-execute-verify`）
+- 扫描诊断（`--scan-debug summary|full`）
 
 ### 维度 E：异常与边界
 
@@ -92,19 +95,23 @@
 
 1. `cleanup_monthly`：`--cutoff-month` + `--output json` + dry-run（有目标 / 无目标）
 2. `cleanup_monthly`：真实执行 + 复核（复核命中应下降或归零）
-3. `space_governance`：`suggested-only` 与 `allow-recent-active` 组合
-4. `restore`：`skip/overwrite/rename` 三冲突策略
-5. `recycle_maintain`：`disabled` / `no_candidate` / `partial_failed`
-6. `doctor`：只读模式不创建状态目录
-7. `check_update`：npm 正常 / npm 失败回退 GitHub / 全部失败
-8. `upgrade`：未确认拒绝、已是最新不执行、执行失败可返回非 0
-9. Agent 报告脚本：成功、无目标、失败三态退出码与卡片完整性
+3. `cleanup_monthly`：`--run-task preview-execute-verify --yes`（阶段字段稳定）
+4. `cleanup_monthly`：`--scan-debug summary/full`（诊断字段稳定）
+5. `space_governance`：`suggested-only` 与 `allow-recent-active` 组合
+6. `restore`：`skip/overwrite/rename` 三冲突策略
+7. `recycle_maintain`：`disabled` / `no_candidate` / `partial_failed`
+8. `doctor`：只读模式不创建状态目录
+9. `check_update`：npm 正常 / npm 失败回退 GitHub / 全部失败
+10. `upgrade`：未确认拒绝、已是最新不执行、执行失败可返回非 0
+11. `sync_skills`：预演/真实同步、版本匹配状态收敛
+12. Agent 报告脚本：成功、无目标、失败三态退出码与卡片完整性
 
 ## 当前门禁（执行顺序）
 
 1. `npm run check`
-2. `npm run test:coverage:check`
-3. `shellcheck skills/wecom-cleaner-agent/scripts/*.sh scripts/upgrade.sh scripts/install-skill.sh scripts/release-gate.sh`
-4. `npm run e2e:smoke`
+2. `npm run check:skills-version`
+3. `npm run test:coverage:check`
+4. `shellcheck skills/wecom-cleaner-agent/scripts/*.sh scripts/upgrade.sh scripts/install-skill.sh scripts/release-gate.sh`
+5. `npm run e2e:smoke`
 
 说明：若新增动作/字段，需先补此文档矩阵与断言，再提交实现。

package/docs/releases/v1.3.1.md

@@ -0,0 +1,31 @@
+# v1.3.1
+
+发布日期：2026-02-27
+
+## 重点更新
+
+- 新增无交互阶段协议 `--run-task`：
+  - `preview`：仅预演
+  - `execute`：仅执行
+  - `preview-execute-verify`：预演 -> 执行 -> 复核
+- 无交互 JSON 新增阶段产物：
+  - `data.taskPhases`：阶段明细（状态、耗时、命中/成功/失败统计）
+  - `data.taskCard`：用户视角任务卡片（范围、结论、分布）
+- 新增扫描诊断参数 `--scan-debug off|summary|full`：用于定位“扫描命中与预期不一致”问题。
+
+## CLI 与 Agent 协同
+
+- `--help` 已补充 `--run-task` 与 `--scan-debug`。
+- skills 文档与命令参考已同步：CLI 回退场景优先使用 `--run-task`，并读取 `taskCard/taskPhases`。
+
+## 测试与质量
+
+- 新增/更新：
+  - `test/config.test.js`：新增 `--run-task` / `--scan-debug` 参数解析覆盖。
+  - `test/cli-non-interactive.test.js`：新增阶段协议与扫描诊断覆盖。
+- 全量测试通过：`npm test`（107/107）。
+
+## 兼容性说明
+
+- 旧的无交互调用方式保持兼容（不传 `--run-task` 时行为不变）。
+- 文本输出保持原有动作卡片，新增阶段流程区块仅在 `--run-task` 时显示。

package/docs/releases/v1.3.2.md

@@ -0,0 +1,38 @@
+# v1.3.2
+
+发布日期：2026-02-27
+
+## 重点更新
+
+- 4 个破坏性 Agent 报告脚本统一改为 `--run-task` 单入口（预演 / 执行 / 复核一致语义）：
+  - `cleanup_monthly_report.sh`
+  - `space_governance_report.sh`
+  - `restore_batch_report.sh`
+  - `recycle_maintain_report.sh`
+- Zig 核心版本号改为构建期自动注入，不再手工写死。
+- `native/manifest.json` 升级到 `v1.3.2`，并同步 `darwin-x64`/`darwin-arm64` 双架构 SHA256。
+
+## 稳定性修复
+
+- 修复 4 个报告脚本在错误分支下的变量展开风险：失败场景稳定返回非 0，避免自动化流程误判成功。
+- 修复 Zig 核心 `--ping` 版本与包版本可能不一致的问题。
+
+## 文档同步
+
+- README、实施计划、技能命令参考、升级脚本示例统一更新到 `v1.3.2`。
+
+## 验证结果
+
+- 发布门禁全通过：`npm run release:gate`
+  - `format:check`
+  - `check`
+  - `test:coverage:check`
+  - `shellcheck(skills)`
+  - `e2e:smoke`
+  - `pack:tgz:dry-run`
+  - `pack:release-assets:dry-run`
+- 覆盖率基线（`test:coverage:check`）：
+  - `statements 87.66%`
+  - `branches 74.38%`
+  - `functions 92.47%`
+  - `lines 87.66%`

package/docs/releases/v1.3.3.md

@@ -0,0 +1,32 @@
+# v1.3.3
+
+发布日期：2026-02-27
+
+## 重点更新
+
+- 新增 skills 版本绑定元数据：`skills/wecom-cleaner-agent/version.json`，将 skills 版本与主程序版本显式绑定。
+- 新增无交互动作 `--sync-skills`，支持独立同步 Agent skills（`npm` / `github-script`）。
+- 新增 `wecom-cleaner-skill status` / `wecom-cleaner-skill sync`，用于检测和修复版本不匹配。
+- 新增 skills 版本门禁：`scripts/check-skills-version.js`，并接入 `npm run check:skills-version` 与 `release:gate`。
+
+## 升级链路改进
+
+- `--check-update` 输出新增 skills 匹配状态与版本字段（`skillsStatus`、`skillsMatched` 等）。
+- `--upgrade` 默认联动同步 skills，并返回同步状态、同步方式与前后匹配状态。
+- 交互模式“检查更新与升级”支持直接触发 skills 同步；头部增加 skills 状态徽章。
+- `scripts/upgrade.sh` 默认升级后同步 skills，可通过 `--sync-skills false` 关闭。
+
+## 发布与资产
+
+- release 资产打包新增 skills 独立附件：`wecom-cleaner-skill-vX.Y.Z.tar.gz`。
+- SHA256 清单命名统一为：`wecom-cleaner-vX.Y.Z-SHA256SUMS.txt`。
+- `scripts/install-skill.sh` 安装完成后输出 skills 版本与绑定版本，便于核验。
+
+## Agent 技能适配
+
+- `wecom-cleaner-agent` 的 `check_update_report` / `upgrade_report` / `doctor_report` 已适配 skills 版本状态与同步反馈。
+- `SKILL.md` 与命令参考文档已同步更新。
+
+## 稳定性结论
+
+- 已通过：`npm run format:check`、`npm run check`、`npm run check:skills-version`、`npm test`（116/116）。

package/native/manifest.json

@@ -1,16 +1,16 @@
 {
   "schemaVersion": 1,
-  "version": "1.3.0",
+  "version": "1.3.3",
   "targets": {
     "darwin-x64": {
       "binaryName": "wecom-cleaner-core",
-      "sha256": "1ea550528055b97e26a76de7d33ca7c445f7dcedf36b21c0cfe1ef7e0f9841bf",
-      "url": "https://github.com/MisonL/wecom-cleaner/releases/download/v1.3.0/wecom-cleaner-core-v1.3.0-darwin-x64"
+      "sha256": "e803a1d480895f3edc2350151611a20390ae01401c179aa3f58b5773fed011a8",
+      "url": "https://github.com/MisonL/wecom-cleaner/releases/download/v1.3.3/wecom-cleaner-core-v1.3.3-darwin-x64"
     },
     "darwin-arm64": {
       "binaryName": "wecom-cleaner-core",
-      "sha256": "2819be9b6108435d94f9a6f5cd0f4e219c335925239366f76fe8a22da023a736",
-      "url": "https://github.com/MisonL/wecom-cleaner/releases/download/v1.3.0/wecom-cleaner-core-v1.3.0-darwin-arm64"
+      "sha256": "0bee4994c39ec66690a1effa2acc4178a581567750577c5caa9ba4e495dd3b1d",
+      "url": "https://github.com/MisonL/wecom-cleaner/releases/download/v1.3.3/wecom-cleaner-core-v1.3.3-darwin-arm64"
     }
   }
 }

package/native/zig/build.sh

@@ -2,6 +2,9 @@
 set -euo pipefail
 
 ROOT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+PACKAGE_VERSION="$(node -p "JSON.parse(require('fs').readFileSync('${ROOT_DIR}/package.json', 'utf8')).version")"
+VERSION_ZIG_PATH="${ROOT_DIR}/native/zig/src/version.zig"
+printf 'pub const APP_VERSION = "%s";\n' "${PACKAGE_VERSION}" > "${VERSION_ZIG_PATH}"
 
 HOST_OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
 HOST_ARCH="$(uname -m)"

package/native/zig/src/main.zig

@@ -1,4 +1,5 @@
 const std = @import("std");
+const version_meta = @import("version.zig");
 
 fn isAbsPath(path: []const u8) bool {
     return std.fs.path.isAbsolute(path);
@@ -57,7 +58,7 @@ fn dirTreeSize(dir: *std.fs.Dir) !u64 {
 }
 
 fn printPing(writer: *std.Io.Writer) !void {
-    try writer.writeAll("{\"ok\":true,\"engine\":\"zig\",\"version\":\"1.3.0\"}\n");
+    try writer.print("{{\"ok\":true,\"engine\":\"zig\",\"version\":\"{s}\"}}\n", .{version_meta.APP_VERSION});
 }
 
 fn runDu(args: []const []const u8, writer: *std.Io.Writer) !void {

package/native/zig/src/version.zig

@@ -0,0 +1 @@
+pub const APP_VERSION = "1.3.3";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mison/wecom-cleaner",
-  "version": "1.3.0",
+  "version": "1.3.3",
   "description": "企业微信本地聊天缓存清理工具（交互式 CLI/TUI）",
   "author": "MisonL",
   "license": "MIT",
@@ -42,6 +42,7 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "check": "node --check src/*.js",
+    "check:skills-version": "node scripts/check-skills-version.js",
     "e2e:smoke": "bash scripts/e2e-smoke.sh",
     "release:gate": "bash scripts/release-gate.sh",
     "prepack": "npm run build:native:release && npm run check",

package/skills/wecom-cleaner-agent/SKILL.md

@@ -16,10 +16,11 @@ description: 用于执行和编排 wecom-cleaner 的无交互 Agent 技能。当
 1. 全程只用无交互命令（禁止直接运行 `wecom-cleaner` 进入 TUI）。
 2. 优先脚本入口，禁止手写三步命令流（除非脚本失败或缺失）。
 3. 破坏性动作（清理/治理/恢复/回收区治理）默认预演；真实执行必须有明确授权。
-4. 升级动作默认只做检查或预演（`--execute false`）；真实升级必须有明确授权。
-5. 若预演命中为 `0`，必须结束并说明“无需执行”，不得继续真实执行。
-6. 最终汇报必须是中文用户视角，先结论再细节，并解释关键指标含义。
-7. 禁止在终端回显完整 JSON；只输出人类可读摘要。
+4. 回退到 CLI 时，破坏性动作必须使用 `--run-task` 协议（`preview` 或 `preview-execute-verify`），禁止手工串联多次命令。
+5. 升级动作默认只做检查或预演（`--execute false`）；真实升级必须有明确授权。
+6. 若预演命中为 `0`，必须结束并说明“无需执行”，不得继续真实执行。
+7. 最终汇报必须是中文用户视角，先结论再细节，并解释关键指标含义。
+8. 禁止在终端回显完整 JSON；只输出人类可读摘要。
 
 ## 动作到脚本映射（必须）
 
@@ -31,12 +32,14 @@ description: 用于执行和编排 wecom-cleaner 的无交互 Agent 技能。当
 - 系统自检：`scripts/doctor_report.sh`
 - 检查更新：`scripts/check_update_report.sh`
 - 程序升级：`scripts/upgrade_report.sh`
+- skills 同步：回退到 `wecom-cleaner --sync-skills --output json`
 
 调用顺序：
 
 1. 先判断用户意图对应哪个动作。
 2. 直接调用对应脚本。
 3. 脚本失败时，才回退到 `wecom-cleaner --<action> --output json` 手工流程。
+4. 回退流程里优先读取 `data.taskCard` 与 `data.taskPhases`，再读取 `summary/data.report` 细节。
 
 ## 脚本调用约定
 
@@ -44,6 +47,9 @@ description: 用于执行和编排 wecom-cleaner 的无交互 Agent 技能。当
 - 用户明确“现在执行/开始清理/确认执行”时才传 `--execute true`。
 - 破坏性动作脚本内部会做：预演 ->（可选）真实执行 ->（可选）复核。
 - 升级脚本默认“检查 + 预演”；只有明确授权才执行真实升级。
+- CLI 回退时：
+  - 仅预演：`--run-task preview`
+  - 已授权执行：`--run-task preview-execute-verify --yes`
 
 推荐参数：
 

package/skills/wecom-cleaner-agent/agents/openai.yaml

@@ -1,5 +1,5 @@
 interface:
   display_name: 'WeCom Cleaner Agent'
   short_description: '面向AI Agent的企业微信缓存清理与恢复无交互执行技能'
-  default_prompt: '请使用 $wecom-cleaner-agent 执行任务：按用户意图自动选择 scripts/ 下对应报告脚本（cleanup/analysis/space/restore/recycle/doctor/check-update/upgrade），优先输出中文用户任务卡片；仅在脚本不可用时回退 wecom-cleaner --output json。'
+  default_prompt: '请使用 $wecom-cleaner-agent 执行任务：按用户意图自动选择 scripts/ 下对应报告脚本（cleanup/analysis/space/restore/recycle/doctor/check-update/upgrade），需要 skills 同步时回退 wecom-cleaner --sync-skills --output json；优先输出中文用户任务卡片；仅在脚本不可用时回退 wecom-cleaner --output json，并在破坏性动作中使用 --run-task（preview 或 preview-execute-verify）读取 data.taskCard/taskPhases。'
   brand_color: '#0EA5E9'