@mison/wecom-cleaner 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -65,7 +65,7 @@
65
65
 
66
66
  - 支持默认路径、手动配置路径、自动探测路径。
67
67
  - 自动探测采用“结构 + 缓存特征”联合识别(如 `*/WXWork Files/Caches` + 企业微信缓存类别/月目录信号),不依赖目录名且降低误判。
68
- - 自动探测结果默认不预选,需用户确认后纳入处理。
68
+ - 自动探测结果默认预选,执行前可手动取消;同时保留确认提示,避免误纳入无关目录。
69
69
 
70
70
  3. 删除与恢复链路
71
71
 
@@ -164,6 +164,15 @@ curl -fsSL https://raw.githubusercontent.com/MisonL/wecom-cleaner/main/scripts/i
164
164
  curl -fsSL https://raw.githubusercontent.com/MisonL/wecom-cleaner/main/scripts/install-skill.sh | bash -s -- --ref v1.1.0
165
165
  ```
166
166
 
167
+ Agent 侧统一任务入口脚本(位于 `skills/wecom-cleaner-agent/scripts/`):
168
+
169
+ - `cleanup_monthly_report.sh`:年月清理任务卡片(预演/执行/复核)
170
+ - `analysis_report.sh`:会话分析(只读)任务卡片
171
+ - `space_governance_report.sh`:全量空间治理任务卡片
172
+ - `restore_batch_report.sh`:批次恢复任务卡片
173
+ - `recycle_maintain_report.sh`:回收区治理任务卡片
174
+ - `doctor_report.sh`:系统自检任务卡片
175
+
167
176
  ## 常用参数
168
177
 
169
178
  运行方式:
@@ -228,6 +237,69 @@ wecom-cleaner --doctor
228
237
  - `--json`:兼容别名,等价于 `--output json`。
229
238
  - `--mode`:兼容参数,建议迁移到动作参数(如 `--cleanup-monthly`)。
230
239
  - `--save-config`:将本次全局配置参数写回 `config.json`。
240
+ - `--help` / `-h`:输出命令帮助并退出。
241
+ - `--version` / `-v`:输出版本号并退出。
242
+
243
+ ### 各动作关键统计字段(JSON)
244
+
245
+ #### `cleanup-monthly`
246
+
247
+ - `summary.matchedTargets`:命中目标数
248
+ - `summary.matchedBytes`:命中目标总字节
249
+ - `summary.hasWork` / `summary.noTarget`:是否存在可执行目标
250
+ - `summary.successCount` / `skippedCount` / `failedCount`
251
+ - `summary.reclaimedBytes`:预计或实际释放字节
252
+ - `summary.batchId`:真实执行批次号(dry-run 为预演批次)
253
+ - `summary.matchedMonthStart` / `matchedMonthEnd`:本次命中的月份区间
254
+ - `summary.rootPathCount`:涉及的清理根目录数量
255
+ - `summary.accountCount` / `monthCount` / `categoryCount` / `externalRootCount`
256
+ - `summary.cutoffMonth`:截止月份(当使用 `--cutoff-month` 时)
257
+
258
+ `cleanup-monthly` 还会在 `data.report` 中返回可展示明细:
259
+
260
+ - `data.report.matched.categoryStats`:按类别统计(条目数、体积)
261
+ - `data.report.matched.monthStats`:按月份统计(条目数、体积)
262
+ - `data.report.matched.rootStats`:按根目录统计(条目数、体积)
263
+ - `data.report.matched.topPaths`:按体积 Top 路径样例
264
+ - `data.report.executed.byCategory/byMonth/byRoot`:真实执行落地统计(成功/跳过/失败 + 体积)
265
+
266
+ #### `analysis-only`
267
+
268
+ - `summary.targetCount` / `totalBytes`:命中目录数与总体积
269
+ - `summary.accountCount` / `matchedAccountCount` / `categoryCount` / `monthBucketCount`:维度汇总(范围账号数 vs 实际命中账号数)
270
+ - `data.accountsSummary` / `categoriesSummary` / `monthsSummary`:分布统计
271
+ - `data.report.matched`:统一的类别/月份/根目录/路径样例统计结构
272
+
273
+ #### `space-governance`
274
+
275
+ - `summary.matchedTargets` / `matchedBytes`
276
+ - `summary.successCount` / `skippedCount` / `failedCount` / `reclaimedBytes`
277
+ - `summary.tierCount` / `targetTypeCount` / `rootPathCount`
278
+ - `data.report.matched.byTier/byTargetType/byAccount/byRoot/topPaths`
279
+ - `data.report.executed.byCategory/byMonth/byRoot/topPaths`(真实执行时)
280
+
281
+ #### `restore-batch`
282
+
283
+ - `summary.batchId` / `entryCount` / `matchedBytes`
284
+ - `summary.successCount` / `skippedCount` / `failedCount` / `restoredBytes`
285
+ - `summary.scopeCount` / `categoryCount` / `rootPathCount`
286
+ - `data.report.matched.byScope/byCategory/byMonth/byRoot/topEntries`
287
+ - `data.report.executed.byScope/byCategory/byMonth/byRoot/topEntries`(真实执行时)
288
+
289
+ #### `recycle-maintain`
290
+
291
+ - `summary.candidateCount` / `selectedByAge` / `selectedBySize`
292
+ - `summary.deletedBatches` / `deletedBytes` / `failedBatches`
293
+ - `summary.remainingBatches` / `remainingBytes`
294
+ - `data.report.before` / `after` / `thresholdBytes` / `overThreshold`
295
+ - `data.report.selectedCandidates` / `operations`
296
+
297
+ #### `doctor`
298
+
299
+ - `summary.overall` / `pass` / `warn` / `fail`
300
+ - `data.checks`:逐项体检结论(pass/warn/fail)
301
+ - `data.metrics`:账号数、回收区占用、外部存储等关键指标
302
+ - `data.runtime`:运行时环境信息
231
303
 
232
304
  ### 全局参数
233
305
 
@@ -236,7 +308,7 @@ wecom-cleaner --doctor
236
308
  - `--external-storage-root <path[,path...]>`:手动文件存储目录(配置层)
237
309
  - `--external-storage-auto-detect <true|false>`:外部存储自动探测总开关
238
310
  - `--external-roots <path[,path...]>`:本次动作临时覆盖的文件存储目录
239
- - `--external-roots-source <preset|configured|auto|all>`:按来源筛选探测目录(默认 `preset`)
311
+ - `--external-roots-source <preset|configured|auto|all>`:按来源筛选探测目录(默认 `all`,优先减少漏扫;可按需收窄)
240
312
  - `--theme <auto|light|dark>`:Logo 主题
241
313
  - `--interactive`:即使携带参数也进入交互流程(可配合 `--mode`)
242
314
  - `--force`:锁异常场景下强制清理并继续(兜底参数,通常无需)
@@ -319,10 +391,10 @@ npm run e2e:smoke -- --keep
319
391
  npm run pack:tgz:dry-run
320
392
  ```
321
393
 
322
- 当前基线(`v1.1.0`):
394
+ 当前基线(主分支):
323
395
 
324
- - 单元测试:`68/68` 通过。
325
- - 覆盖率:`statements 86.57%`,`branches 73.96%`,`functions 93.25%`,`lines 86.57%`。
396
+ - 单元测试:`78/78` 通过。
397
+ - 覆盖率:`statements 88.28%`,`branches 74.44%`,`functions 94.89%`,`lines 88.28%`。
326
398
  - 全菜单 smoke:通过(含恢复冲突分支与 doctor JSON 分支)。
327
399
 
328
400
  ## 发布与打包
@@ -337,6 +409,8 @@ npm run pack:tgz:dry-run
337
409
  - `native/bin/darwin-x64/wecom-cleaner-core`
338
410
  - `native/bin/darwin-arm64/wecom-cleaner-core`
339
411
 
412
+ 说明:`native/bin/` 为构建产物目录,不纳入 Git 版本管理。
413
+
340
414
  本地交付包(无作用域前缀)建议:
341
415
 
342
416
  ```bash
@@ -354,17 +428,21 @@ npm run test:coverage:check
354
428
  npm run format:check
355
429
  npm run e2e:smoke
356
430
  npm run pack:tgz
431
+ npm run pack:release-assets
357
432
 
358
433
  # 2) 推送主分支与标签
359
434
  git push origin main
360
- git tag v1.1.0
361
- git push origin v1.1.0
362
-
363
- # 3) 发布 GitHub Release(附 tgz 包)
364
- gh release create v1.1.0 \
365
- --title "v1.1.0" \
366
- --notes-file docs/releases/v1.1.0.md \
367
- wecom-cleaner-1.1.0.tgz
435
+ git tag v1.2.0
436
+ git push origin v1.2.0
437
+
438
+ # 3) 发布 GitHub Release(附 npm 包 + 双架构核心附件)
439
+ gh release create v1.2.0 \
440
+ --title "v1.2.0" \
441
+ --notes-file docs/releases/v1.2.0.md \
442
+ wecom-cleaner-1.2.0.tgz \
443
+ dist/release/wecom-cleaner-core-v1.2.0-darwin-x64 \
444
+ dist/release/wecom-cleaner-core-v1.2.0-darwin-arm64 \
445
+ dist/release/wecom-cleaner-core-v1.2.0-SHA256SUMS.txt
368
446
 
369
447
  # 4) 发布 npm
370
448
  npm publish --access public
@@ -7,6 +7,8 @@
7
7
  - `wecom-cleaner`(不带参数):进入交互模式(TUI)。
8
8
  - `wecom-cleaner ...args`(带参数):进入无交互模式。
9
9
  - `wecom-cleaner ...args --interactive`:即使带参数也强制进入交互模式(常用于本地调试/脚本回放)。
10
+ - `wecom-cleaner --help` / `wecom-cleaner -h`:输出命令帮助并退出(`0`)。
11
+ - `wecom-cleaner --version` / `wecom-cleaner -v`:输出版本号并退出(`0`)。
10
12
 
11
13
  ## 2. 动作选择(必填且互斥)
12
14
 
@@ -33,7 +35,7 @@
33
35
 
34
36
  ## 4. 输出协议
35
37
 
36
- 无交互默认输出 JSON,可通过 `--output text` 切换文本。
38
+ 无交互默认输出 JSON,可通过 `--output text` 切换文本任务卡片(中文结论 + 范围 + 统计 + 风险提示)。
37
39
 
38
40
  - `--output json|text`(默认 `json`)
39
41
  - `--json` 为兼容别名(等价 `--output json`)
@@ -49,6 +51,119 @@ JSON 顶层字段:
49
51
  - `data`:动作明细数据
50
52
  - `meta`:元信息(版本、耗时、引擎、时间戳等)
51
53
 
54
+ `cleanup_monthly` 常见 `summary` 字段:
55
+
56
+ - `batchId`
57
+ - `hasWork`
58
+ - `noTarget`
59
+ - `matchedTargets`
60
+ - `matchedBytes`
61
+ - `successCount`
62
+ - `skippedCount`
63
+ - `failedCount`
64
+ - `reclaimedBytes`
65
+ - `accountCount`
66
+ - `monthCount`
67
+ - `categoryCount`
68
+ - `externalRootCount`
69
+ - `cutoffMonth`
70
+ - `matchedMonthStart`
71
+ - `matchedMonthEnd`
72
+ - `rootPathCount`
73
+
74
+ `cleanup_monthly` 的 `data.report`:
75
+
76
+ - `matched`:
77
+ - `totalTargets` / `totalBytes`
78
+ - `monthRange` / `matchedMonths`
79
+ - `categoryStats` / `monthStats` / `accountStats` / `rootStats`
80
+ - `topPaths`(按体积排序)
81
+ - `executed`:
82
+ - `byStatus`
83
+ - `byCategory` / `byMonth` / `byRoot`
84
+ - `topPaths`(按体积排序)
85
+
86
+ `analysis_only` 常见 `summary` 字段:
87
+
88
+ - `targetCount`
89
+ - `totalBytes`
90
+ - `accountCount`
91
+ - `matchedAccountCount`
92
+ - `categoryCount`
93
+ - `monthBucketCount`
94
+
95
+ `analysis_only` 的 `data.report`:
96
+
97
+ - `matched`:
98
+ - `totalTargets` / `totalBytes`
99
+ - `monthRange` / `matchedMonths`
100
+ - `categoryStats` / `monthStats` / `accountStats` / `rootStats`
101
+ - `topPaths`
102
+
103
+ `space_governance` 常见 `summary` 字段:
104
+
105
+ - `matchedTargets` / `matchedBytes`
106
+ - `successCount` / `skippedCount` / `failedCount` / `reclaimedBytes`
107
+ - `tierCount` / `targetTypeCount` / `rootPathCount`
108
+ - `allowRecentActive`
109
+
110
+ `space_governance` 的 `data.report`:
111
+
112
+ - `matched`:
113
+ - `totalTargets` / `totalBytes`
114
+ - `byTier` / `byTargetType` / `byAccount` / `byRoot`
115
+ - `topPaths`
116
+ - `executed`:
117
+ - `byStatus`
118
+ - `byCategory` / `byMonth` / `byRoot`
119
+ - `topPaths`
120
+
121
+ `restore` 常见 `summary` 字段:
122
+
123
+ - `batchId`
124
+ - `successCount` / `skippedCount` / `failedCount`
125
+ - `restoredBytes`
126
+ - `conflictStrategy`
127
+ - `entryCount` / `matchedBytes`
128
+ - `scopeCount` / `categoryCount` / `rootPathCount`
129
+
130
+ `restore` 的 `data.report`:
131
+
132
+ - `matched`:
133
+ - `totalEntries` / `totalBytes`
134
+ - `byScope` / `byCategory` / `byMonth` / `byRoot`
135
+ - `topEntries`
136
+ - `executed`:
137
+ - `byStatus`
138
+ - `byScope` / `byCategory` / `byMonth` / `byRoot`
139
+ - `topEntries`
140
+
141
+ `recycle_maintain` 常见 `summary` 字段:
142
+
143
+ - `status`
144
+ - `candidateCount`
145
+ - `selectedByAge` / `selectedBySize`
146
+ - `deletedBatches` / `deletedBytes` / `failedBatches`
147
+ - `remainingBatches` / `remainingBytes`
148
+
149
+ `recycle_maintain` 的 `data.report`:
150
+
151
+ - `before` / `after`
152
+ - `thresholdBytes` / `overThreshold`
153
+ - `selectedCandidates`
154
+ - `operations`
155
+
156
+ `doctor` 常见 `summary` 字段:
157
+
158
+ - `overall`
159
+ - `pass` / `warn` / `fail`
160
+
161
+ `doctor` 的 `data`:
162
+
163
+ - `checks`:体检项列表(pass/warn/fail)
164
+ - `metrics`:关键计数与容量
165
+ - `runtime`:平台与运行时信息
166
+
52
167
  ## 5. 退出码
53
168
 
54
169
  - `0`:执行成功(含 dry-run 成功)
@@ -63,7 +178,7 @@ JSON 顶层字段:
63
178
  - `--external-storage-root <path[,path...]>`:配置层手动文件存储目录
64
179
  - `--external-storage-auto-detect <true|false>`:自动探测开关
65
180
  - `--external-roots <path[,path...]>`:动作层临时覆盖文件存储目录
66
- - `--external-roots-source <preset|configured|auto|all>`:按来源筛选探测目录(默认 `preset`)
181
+ - `--external-roots-source <preset|configured|auto|all>`:按来源筛选探测目录(默认 `all`)
67
182
  - `--theme <auto|light|dark>`
68
183
  - `--interactive`:强制交互模式(与无交互动作参数互斥使用时,优先按交互模式执行)
69
184
  - `--force`:锁异常场景下强制清理并继续(兜底参数)
@@ -84,6 +199,10 @@ JSON 顶层字段:
84
199
  - `--accounts <all|current|id1,id2...>`
85
200
  - `--categories <all|key1,key2...>`
86
201
 
202
+ 说明:
203
+
204
+ - `analysis-only` 默认按 `external-roots-source=all` 读取外部目录来源(只读动作,避免漏扫)。
205
+
87
206
  ### 7.3 `--space-governance`
88
207
 
89
208
  - `--accounts <all|current|id1,id2...>`
@@ -93,6 +212,11 @@ JSON 顶层字段:
93
212
  - `--allow-recent-active <true|false>`
94
213
  - `--dry-run <true|false>`
95
214
 
215
+ 说明:
216
+
217
+ - `cleanup-monthly` / `space-governance` 默认 `external-roots-source=all`,优先减少漏扫。
218
+ - 若需更保守范围,可显式设置 `--external-roots-source preset`(仅默认+手动配置来源)。
219
+
96
220
  ### 7.4 `--restore-batch <batchId>`
97
221
 
98
222
  - `--conflict <skip|overwrite|rename>`(默认 `skip`)
@@ -0,0 +1,33 @@
1
+ # v1.2.0 发布说明
2
+
3
+ 发布日期:2026-02-26
4
+
5
+ ## 亮点
6
+
7
+ - 无交互 `--output text` 升级为中文任务卡片:
8
+ - 任务结论
9
+ - 处理范围(账号/月份/类别/路径)
10
+ - 结果统计(命中、释放、成功/跳过/失败、批次)
11
+ - 分类与月份分布
12
+ - 风险与运行状态
13
+ - `wecom-cleaner-agent` 升级为“脚本优先”执行模式,新增 6 个报告脚本,面向 Agent 输出更可读。
14
+ - 发布流程支持 GitHub Release 独立双架构核心附件(macOS x64 / arm64)。
15
+
16
+ ## 重要变更
17
+
18
+ - 非交互 `cleanup-monthly` / `space-governance` 默认外部目录来源改为 `all`(减少漏扫)。
19
+ - 交互模式外部目录默认预选自动探测路径,执行前可取消。
20
+ - `native/bin/` 改为构建产物目录,不再纳入 Git 版本管理。
21
+
22
+ ## 修复
23
+
24
+ - 修复 Zig 核心对目录体积的误统计问题(此前可能导致容量明显偏小)。
25
+ - 增强清理/恢复/回收区治理结果的分布统计能力,便于用户复核。
26
+
27
+ ## 资产
28
+
29
+ - npm 包:`wecom-cleaner-1.2.0.tgz`
30
+ - GitHub Release 附件:
31
+ - `wecom-cleaner-core-v1.2.0-darwin-x64`
32
+ - `wecom-cleaner-core-v1.2.0-darwin-arm64`
33
+ - `wecom-cleaner-core-v1.2.0-SHA256SUMS.txt`
@@ -1,15 +1,16 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "version": "1.1.0",
4
- "baseUrl": "https://raw.githubusercontent.com/MisonL/wecom-cleaner/v1.1.0/native/bin",
3
+ "version": "1.2.0",
5
4
  "targets": {
6
5
  "darwin-x64": {
7
6
  "binaryName": "wecom-cleaner-core",
8
- "sha256": "d6bc4b2a7b96010889fc11502fe6d76d6f8d395e6df12c44dfc79aa58b17d53c"
7
+ "sha256": "c703a8bdb6df39df776c6a3ab28b3553916d487cf7c38612989566b4ecea34c9",
8
+ "url": "https://github.com/MisonL/wecom-cleaner/releases/download/v1.2.0/wecom-cleaner-core-v1.2.0-darwin-x64"
9
9
  },
10
10
  "darwin-arm64": {
11
11
  "binaryName": "wecom-cleaner-core",
12
- "sha256": "f3babdfe69e83c2d0b99fe1ad525ea836e4f413c01ae2f31b569e35f2ba955f8"
12
+ "sha256": "8d0a15efcb70a266e15c752212f15570c006a931681249d6cd41a1c438941f72",
13
+ "url": "https://github.com/MisonL/wecom-cleaner/releases/download/v1.2.0/wecom-cleaner-core-v1.2.0-darwin-arm64"
13
14
  }
14
15
  }
15
16
  }
@@ -6,12 +6,13 @@ fn isAbsPath(path: []const u8) bool {
6
6
 
7
7
  fn pathSize(path: []const u8) !u64 {
8
8
  const cwd = std.fs.cwd();
9
-
10
9
  const file_res = if (isAbsPath(path)) std.fs.openFileAbsolute(path, .{}) else cwd.openFile(path, .{});
11
10
  if (file_res) |file| {
12
11
  defer file.close();
13
12
  const st = try file.stat();
14
- return st.size;
13
+ if (st.kind != .directory) {
14
+ return st.size;
15
+ }
15
16
  } else |err| {
16
17
  if (err != error.IsDir) {
17
18
  return err;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mison/wecom-cleaner",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "企业微信本地聊天缓存清理工具(交互式 CLI/TUI)",
5
5
  "author": "MisonL",
6
6
  "license": "MIT",
@@ -46,6 +46,8 @@
46
46
  "prepack": "npm run build:native:release && npm run check",
47
47
  "pack:tgz": "node scripts/pack-tgz.js",
48
48
  "pack:tgz:dry-run": "node scripts/pack-tgz.js --dry-run",
49
+ "pack:release-assets": "node scripts/pack-release-assets.js",
50
+ "pack:release-assets:dry-run": "node scripts/pack-release-assets.js --dry-run",
49
51
  "skill:install": "node src/skill-cli.js install",
50
52
  "skill:path": "node src/skill-cli.js path"
51
53
  },
@@ -1,72 +1,72 @@
1
1
  ---
2
2
  name: wecom-cleaner-agent
3
- description: 用于执行和编排 wecom-cleaner 的无交互 Agent 技能。当任务涉及企业微信缓存盘点、年月清理、全量空间治理、批次恢复、回收区治理或系统自检,并要求 JSON 输出解析与 dry-run 安全门槛时触发。
3
+ description: 用于执行和编排 wecom-cleaner 的无交互 Agent 技能。当任务涉及企业微信缓存盘点、年月清理、全量空间治理、批次恢复、回收区治理或系统自检,并要求高效执行与结构化反馈时触发。
4
4
  ---
5
5
 
6
6
  # wecom-cleaner-agent
7
7
 
8
- ## 何时触发
8
+ ## 目标
9
9
 
10
- - 用户要清理企业微信本地缓存,且希望由 Agent 自动执行。
11
- - 用户要走无交互 CLI,返回可机读 JSON 结果。
12
- - 用户要执行以下任一能力:盘点、年月清理、全量治理、批次恢复、回收区治理、系统自检。
10
+ - 用最少命令完成目标动作。
11
+ - 默认安全(先预演,再按授权执行真实动作)。
12
+ - 输出“用户可读任务卡片”,避免技术键值堆砌。
13
13
 
14
- ## 默认执行策略
14
+ ## 强制规则
15
15
 
16
- 1. 优先无交互模式,不进入 TUI
17
- 2. 先执行 `--doctor --output json` 做只读体检。
18
- 3. 每次调用必须且只能提供一个动作参数。
19
- 4. 破坏性动作先 dry-run,再根据用户确认决定真实执行。
20
- 5. 每次执行都使用 `--output json`,按字段解析结果并汇报。
16
+ 1. 全程只用无交互命令(禁止直接运行 `wecom-cleaner` 进入 TUI)。
17
+ 2. 优先脚本入口,禁止手写三步命令流(除非脚本失败或缺失)。
18
+ 3. 破坏性动作(清理/治理/恢复/回收区治理)默认预演;真实执行必须有明确授权。
19
+ 4. 若预演命中为 `0`,必须结束并说明“无需执行”,不得继续真实执行。
20
+ 5. 最终汇报必须是中文用户视角,先结论再细节,并解释关键指标含义。
21
+ 6. 禁止在终端回显完整 JSON;只输出人类可读摘要。
21
22
 
22
- ## 动作契约
23
+ ## 动作到脚本映射(必须)
23
24
 
24
- 无交互模式只能选一个动作:
25
+ - 年月清理:`scripts/cleanup_monthly_report.sh`
26
+ - 会话分析(只读):`scripts/analysis_report.sh`
27
+ - 全量空间治理:`scripts/space_governance_report.sh`
28
+ - 恢复已删除批次:`scripts/restore_batch_report.sh`
29
+ - 回收区治理:`scripts/recycle_maintain_report.sh`
30
+ - 系统自检:`scripts/doctor_report.sh`
25
31
 
26
- - `--cleanup-monthly`
27
- - `--analysis-only`
28
- - `--space-governance`
29
- - `--restore-batch <batchId>`
30
- - `--recycle-maintain`
31
- - `--doctor`
32
+ 调用顺序:
32
33
 
33
- 退出码约定:
34
+ 1. 先判断用户意图对应哪个动作。
35
+ 2. 直接调用对应脚本。
36
+ 3. 脚本失败时,才回退到 `wecom-cleaner --<action> --output json` 手工流程。
34
37
 
35
- - `0` 成功
36
- - `1` 业务失败或运行失败
37
- - `2` 参数错误或动作冲突
38
- - `3` 请求真实执行但缺少 `--yes`
38
+ ## 脚本调用约定
39
39
 
40
- ## 安全门槛
40
+ - 默认 `--execute false`(仅预演)。
41
+ - 用户明确“现在执行/开始清理/确认执行”时才传 `--execute true`。
42
+ - 破坏性动作脚本内部会做:预演 ->(可选)真实执行 ->(可选)复核。
41
43
 
42
- - 未获明确授权前,不执行真实删除或真实恢复。
43
- - `cleanup-monthly`、`space-governance`、`restore-batch`、`recycle-maintain` 默认保持 dry-run。
44
- - 真实执行必须同时满足:
45
- - 用户明确同意
46
- - 命令显式携带 `--dry-run false --yes`
47
- - 已确认处理范围(账号、月份/目标、类别、目录来源)
44
+ 推荐参数:
48
45
 
49
- ## 输出解析规则
46
+ - `--root <path>`:显式指定 Profile 根目录(在多环境时强烈建议)。
47
+ - `--state-root <path>`:显式指定状态目录(便于审计与回放)。
48
+ - `--accounts all|current|id1,id2`:明确账号范围。
49
+ - `--external-roots-source all`:优先纳入自动探测目录,避免漏扫用户自定义文件存储位置。
50
50
 
51
- - 必须使用 `--output json`。
52
- - 重点字段:
53
- - `ok`:是否成功
54
- - `action`:执行动作
55
- - `dryRun`:是否预演
56
- - `summary`:核心统计
57
- - `warnings`:兼容或降级提示
58
- - `errors`:错误详情(`code/message/path`)
59
- - `meta`:版本、耗时、引擎
60
- - 判定逻辑:
61
- - `ok=true`:输出关键统计并进入下一步
62
- - `ok=false`:先汇总 `errors`,再给出修复后重试策略
63
- - `warnings` 包含引擎回退时:标记为非阻塞风险并继续
51
+ ## 最终汇报规范(对用户)
64
52
 
65
- ## 交互模式原则
53
+ 每次都要给“任务卡片”风格输出,至少包含:
66
54
 
67
- - 默认不使用 `--interactive`。
68
- - 仅当用户明确要求交互演示或人工选择时,才进入交互模式。
55
+ 1. 结果结论:是否完成、是否真实执行、是否无需执行。
56
+ 2. 用户范围:账号范围、数据范围(月份/类别/批次/策略)。
57
+ 3. 关键统计:命中数量、预计/实际释放(或恢复)空间、成功/跳过/失败、批次号。
58
+ 4. 分布明细:按类别、按月份、按路径(Top 路径样例)。
59
+ 5. 安全状态:引擎、耗时、告警数、错误数。
60
+ 6. 指标释义:解释“命中目标、预计释放、批次号、复核剩余”等含义。
61
+
62
+ ## 异常处理
63
+
64
+ - 参数错误(退出码 `2`):说明缺失参数并给出可执行示例。
65
+ - 缺少确认(退出码 `3`):提示需加 `--execute true`(脚本)或 `--dry-run false --yes`(CLI)。
66
+ - 业务失败(退出码 `1`):提取 `errors.code/message`,给出下一步排查建议。
67
+ - 若发现 `warnings` 或 `errors` 非空,结论里必须明确标注。
69
68
 
70
69
  ## 参考资料
71
70
 
72
- - 常用命令模板:`references/commands.md`
71
+ - 命令参考:`references/commands.md`
72
+ - 脚本目录:`scripts/`
@@ -1,5 +1,5 @@
1
1
  interface:
2
2
  display_name: 'WeCom Cleaner Agent'
3
3
  short_description: '面向AI Agent的企业微信缓存清理与恢复无交互执行技能'
4
- default_prompt: '请使用 $wecom-cleaner-agent 对企业微信缓存执行一次先 dry-run 再确认执行的无交互清理流程。'
4
+ default_prompt: '请使用 $wecom-cleaner-agent 执行任务:按用户意图自动选择 scripts/ 下对应报告脚本(cleanup/analysis/space/restore/recycle/doctor),优先输出中文用户任务卡片;仅在脚本不可用时回退 wecom-cleaner --output json。'
5
5
  brand_color: '#0EA5E9'