qiyu-cli 0.2.1 → 0.2.3

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.
Files changed (72) hide show
  1. package/README.md +433 -72
  2. package/dist/cli.js +48 -7
  3. package/dist/commands/api-notes.js +70 -0
  4. package/dist/commands/api.js +169 -49
  5. package/dist/commands/auth.js +151 -29
  6. package/dist/commands/credentials-source.js +30 -5
  7. package/dist/commands/db-notes.js +75 -0
  8. package/dist/commands/db.js +165 -127
  9. package/dist/commands/query-notes.js +58 -0
  10. package/dist/commands/query.js +449 -61
  11. package/dist/commands/skill.js +445 -51
  12. package/dist/commands/spec-types.js +101 -1
  13. package/dist/commands/stats.js +160 -33
  14. package/dist/commands/store-flags.js +18 -0
  15. package/dist/commands/store-notes.js +38 -0
  16. package/dist/commands/store-precheck.js +321 -0
  17. package/dist/commands/store.js +165 -77
  18. package/dist/commands/sync-notes.js +374 -0
  19. package/dist/commands/sync-run.js +180 -47
  20. package/dist/commands/sync.js +232 -127
  21. package/dist/core/config.js +280 -24
  22. package/dist/core/credentials.js +38 -4
  23. package/dist/core/edition.js +1 -1
  24. package/dist/core/envelope.js +73 -9
  25. package/dist/core/errors.js +73 -16
  26. package/dist/core/http.js +175 -54
  27. package/dist/core/ratelimit.js +5 -1
  28. package/dist/core/registry/index.js +36 -2
  29. package/dist/core/registry/params/export.session.check.json +17 -2
  30. package/dist/core/registry/params/export.session.json +24 -2
  31. package/dist/core/registry/params/export.session.one.json +10 -2
  32. package/dist/core/registry/params/export.session.one.message.json +17 -2
  33. package/dist/core/registry/specs.json +65 -43
  34. package/dist/core/shell.js +30 -0
  35. package/dist/core/time.js +1 -1
  36. package/dist/core/validate.js +21 -2
  37. package/dist/output.js +215 -29
  38. package/dist/postinstall.js +14 -5
  39. package/dist/query/errors.js +145 -45
  40. package/dist/query/mask.js +1277 -25
  41. package/dist/query/metric-catalog.js +11 -0
  42. package/dist/query/native-error.js +189 -0
  43. package/dist/query/sandbox.js +148 -25
  44. package/dist/query/table-query.js +36 -5
  45. package/dist/schedule/install.js +136 -13
  46. package/dist/skill/check.js +11 -6
  47. package/dist/skill/detect.js +89 -29
  48. package/dist/skill/install.js +233 -43
  49. package/dist/skill/paths.js +54 -0
  50. package/dist/skill/qiyu/SKILL.md +29 -5
  51. package/dist/skill/qiyu/errors.md +5 -4
  52. package/dist/skill/qiyu/protocols.md +57 -5
  53. package/dist/skill/qiyu/setup.md +6 -2
  54. package/dist/store/config.js +92 -16
  55. package/dist/store/duckdb.js +1551 -64
  56. package/dist/store/object-kinds.js +32 -0
  57. package/dist/store/retry.js +190 -7
  58. package/dist/store/schema.js +32 -4
  59. package/dist/sync/engine.js +439 -77
  60. package/dist/sync/registry.js +6 -0
  61. package/dist/sync/state.js +20 -0
  62. package/dist/sync/tasks/dim.js +23 -14
  63. package/dist/sync/tasks/knowledge.js +50 -8
  64. package/dist/sync/tasks/pace.js +27 -0
  65. package/dist/sync/tasks/pipeline.js +29 -9
  66. package/dist/sync/tasks/reports.js +176 -49
  67. package/dist/sync/tasks/sessions.js +88 -21
  68. package/dist/sync/tasks/tickets.js +59 -8
  69. package/dist/sync/types.js +60 -1
  70. package/dist/sync/windowing.js +0 -22
  71. package/dist/sync/write-contract.js +79 -0
  72. package/package.json +2 -2
@@ -12,7 +12,8 @@
12
12
  // `--installed` 校验已安装那份;`--compare` 两份都校验并报告差异。
13
13
  // 有违规 → `ok(...)` 之后返回 1(与 `sync verify` 同一写法)。
14
14
  // · where —— 纯只读:报告实体路径与各 agent 链接状态,**只报告、不修复、不删除**
15
- // (spec D2)。要修复就让用户重跑 `qiyu skill install`。
15
+ // (spec D2)。要修复就让用户重跑 `qiyu skill install`(正文漂移时
16
+ // 裸 install 是 skipped 零写入,得用 `--force`)。
16
17
  //
17
18
  // 实体定位统一为 `--dir` > `QIYU_SKILL_DIR` > `npm_config_qiyu_skill_dir` > `defaultEntityDir(resolveHome())`
18
19
  // (唯一实现在 `skill/detect.ts` 的 `resolveEntityDirSources`,G3 审查 C3);
@@ -35,12 +36,12 @@ import { TABLES } from '../store/schema.js';
35
36
  import { REPORT_TABLES } from '../query/metric-catalog.js';
36
37
  import { SYNC_TASKS } from '../sync/registry.js';
37
38
  import { COMMAND_TREE } from './tree.js';
38
- import { prettyAfterSubcommand } from './spec-types.js';
39
- import { skillFlagSpecs } from './skill-specs.js';
39
+ import { prettyAfterSubcommand, prettyPositionalProblem } from './spec-types.js';
40
+ import { SKILL_SPECS, skillFlagSpecs } from './skill-specs.js';
40
41
  import { checkSkillDir } from '../skill/check.js';
41
- import { contentHash, installSkill, planInstall } from '../skill/install.js';
42
- import { entityUndeterminedNote, npmRelativeBase, readInstalledManifestInfo, resetSkillDetectionCache, resolveEntityDirSources, resolveSkillSourceDir, } from '../skill/detect.js';
43
- import { AGENT_SKILL_SUBDIRS, agentSkillDirs, agentSkillSubdir, LINK_NAME, linkState, } from '../skill/paths.js';
42
+ import { contentHash, contentHashOfFiles, fileHash, installSkill, listFiles, managedContentHash, planInstall, sameFileSet } from '../skill/install.js';
43
+ import { ENTITY_SOURCES, entityUndeterminedNote, npmRelativeBase, readInstalledManifestInfo, resetSkillDetectionCache, resolveEntityDirSources, resolveSkillSourceDir, } from '../skill/detect.js';
44
+ import { AGENT_SKILL_SUBDIRS, agentSkillDirs, agentSkillSubdir, dirShape, LINK_NAME, LINK_REPORT_STATES, linkState, } from '../skill/paths.js';
44
45
  /**
45
46
  * 已知 agent 名(`--link` 的合法取值)。从 paths.ts 的 `AGENT_SKILL_SUBDIRS` 派生,
46
47
  * 不再本地镜像:`AgentDir['name']` 是类型层的唯一事实源,paths.ts 的
@@ -62,7 +63,9 @@ const SKILL_USAGE = `用法:qiyu skill <子命令> [参数]
62
63
  并给出已安装正文的版本元数据 entity.installed
63
64
  {version, skill_contract_version, compatible} 与
64
65
  CLI 自己的 cli_contract_version —— 判断正文能否配这份
65
- CLI 就看 compatible(实体不可用或清单缺失/损坏时
66
+ CLI 看 compatible,但它只对「正文与安装清单一致」的那份
67
+ 成立:正文被手工改过(或读不动)时 compatible=null
68
+ (判定不了,不是 false);实体不可用或清单缺失/损坏时
66
69
  installed=null(判定不了),不编造)
67
70
 
68
71
  实体目录定位:--dir > QIYU_SKILL_DIR > npm_config_qiyu_skill_dir(postinstall 的安装
@@ -216,7 +219,7 @@ export function resolveEntity(flagDir) {
216
219
  *
217
220
  * npm 生命周期里 cwd 是包根,所以基准取 `INIT_CWD ?? cwd`(与 postinstall 同一条)。
218
221
  */
219
- function startupProbeStatus() {
222
+ function startupProbeStatus(explicitSource) {
220
223
  const env = process.env;
221
224
  const resolved = resolveEntityDirSources({
222
225
  env,
@@ -225,7 +228,7 @@ function startupProbeStatus() {
225
228
  });
226
229
  if (resolved.decided)
227
230
  return { dir: resolved.dir, note: undefined };
228
- return { dir: undefined, note: entityUndeterminedNote(resolved, env) };
231
+ return { dir: undefined, note: entityUndeterminedNote(resolved, env, { explicitSource }) };
229
232
  }
230
233
  function isErrno(err, code) {
231
234
  return typeof err === 'object' && err !== null && err.code === code;
@@ -294,14 +297,227 @@ function notInstalled(entityDir, detail) {
294
297
  hint: '先运行:qiyu skill install(可用 --dir 指定实体目录)',
295
298
  });
296
299
  }
297
- /** 读取 skill 目录失败(权限/目录结构异常):环境问题,按 message 给出可操作归因。 */
300
+ /**
301
+ * 读取 skill 目录失败(权限/路径异常):环境问题,按 message 给出可操作归因。
302
+ *
303
+ * ⚠️ hint 必须只列**真能到达这条分支**的成因(审查 #12):这里捕获的是
304
+ * `readdirSync`/`statSync`/`readFileSync` 的系统错误 —— EACCES/EPERM(目录或正文
305
+ * 不可读)、ENOENT/ENOTDIR(路径不存在或不是目录)、以及其余 I/O 错误。旧的
306
+ * 「名为 *.md 的子目录请改成文件」已随 `collectMarkdownFiles` 改为递归而不再可能
307
+ * 触发(目录会被递归进入,不会被当文件读),留着就是一句点错方向的指引。
308
+ */
298
309
  function checkFailed(entityDir, detail) {
299
310
  return fail({
300
311
  code: 'skill_check_failed', kind: 'unknown', retryable: false,
301
312
  message: `读取 skill 目录失败:${entityDir}(${detail})`,
302
- hint: '请检查目录权限;若目录里有名为 *.md 的子目录,请改成文件或移走',
313
+ hint: '按括号里的系统错误定位:EACCES/EPERM → 检查该目录与其中正文文件的读权限;'
314
+ + 'ENOENT/ENOTDIR → 路径不存在或不是目录,用 --dir 指定正确的 skill 目录;'
315
+ + '其余 I/O 错误看错误信息里的具体路径',
303
316
  });
304
317
  }
318
+ // —— skill install ——
319
+ // ⚠️ 下面五组枚举都是 `skill where` / `skill install` 输出里 Agent 要按值分支的机器值,
320
+ // 此前全仓无释义(README 只写了链接四态的名字,`entity.state` 的 `not_a_directory`、
321
+ // install 的 `action`/`status` 连名字都没有)。`foreign` 尤其危险:它意味着**路径上是
322
+ // 别人的东西**,猜成「坏了要修」就会误删。
323
+ //
324
+ // 图例走**输出自带的 `meta.field_notes`**(与 `api list` 同一形态)而不是只写 README:
325
+ // 安装后的 Agent 手里只有六篇正文、没有 README(包内 `files` 只有 `dist`),
326
+ // SKILL.md 指向 README 会是一条走不通的路。README 同步保留人读版图例;
327
+ // `tests/skill-field-notes.test.ts` 三方核对(枚举 ↔ field_notes ↔ README)。
328
+ /** `entity.state`(`skill where` 的 `data.entity.state`)。 */
329
+ export const ENTITY_STATES = ['ok', 'missing', 'not_a_directory', 'unknown'];
330
+ /** `links[].state`(`skill where` 与 `skill install` 的 `data.links[].state`)。 */
331
+ export { LINK_REPORT_STATES };
332
+ /** `links[].action`(仅 `skill install --dry-run` 的计划)。 */
333
+ export const LINK_PLAN_ACTIONS = ['keep', 'create', 'rebuild', 'skip', 'unknown'];
334
+ /** `skill install --dry-run` 的 `action`。 */
335
+ export const INSTALL_ACTIONS = ['install', 'update', 'skip'];
336
+ /**
337
+ * 状态枚举的图例文本 —— **唯一构造点**:`skill where`/`skill install` 的
338
+ * `meta.field_notes` 直接用它,README 的人读版由测试核对同一组取值。
339
+ * 每加一个枚举值,这里必须同时加一句释义(`Record<枚举, string>` 让漏写编译失败)。
340
+ */
341
+ export const SKILL_STATE_NOTES = {
342
+ entityState: {
343
+ ok: '实体目录可用',
344
+ missing: '实体目录不存在(= 未安装)',
345
+ not_a_directory: '路径存在但不是目录 —— install 不会写它,需先由人处理该路径',
346
+ unknown: '无法判定(见 error 字段)—— 不是「不存在」,不要据此重装或删除',
347
+ },
348
+ linkState: {
349
+ ok: '链接已正确指向本实体,无需动作',
350
+ missing: '链接不存在。install 只在该 Agent 的 skills 目录已存在时创建链接'
351
+ + '(从不创建目录):目录不存在时 install 在 meta.warnings 里说明、links 里也没有'
352
+ + '这个 Agent 的条目 —— 装好 Agent 后重跑 install 才会建链',
353
+ dangling: '链接存在但目标已不在(install 会重建)',
354
+ foreign: '路径上是别人的东西(不是指向本实体的符号链接)—— install 一律跳过,不要删、不要覆盖',
355
+ unknown: '无法判定(见 error 字段)—— 不是「不存在」,不要据此重装或删除',
356
+ },
357
+ linkAction: {
358
+ keep: '已正确指向,计划不做动作',
359
+ create: '计划创建链接(对应 state=missing)',
360
+ rebuild: '计划重建链接(对应 state=dangling)',
361
+ skip: '计划跳过(对应 state=foreign:别人的东西,不动)',
362
+ unknown: '无法判定,计划不做动作',
363
+ },
364
+ installAction: {
365
+ install: '首次安装(写入正文与清单)',
366
+ update: '覆盖正文(--force)或只重写落后的清单',
367
+ skip: '实体内容零写入:内容与包内一致且清单新鲜,或内容不同但没带 --force'
368
+ + '(原因见 meta.warnings)。⚠️ 链接仍会照常建立/修复 —— 零写入只针对实体正文,'
369
+ + '看 links[] 判断链接发生了什么',
370
+ },
371
+ installStatus: {
372
+ installed: '已安装(首次)',
373
+ updated: '已更新(覆盖正文或重写清单)',
374
+ skipped: '实体内容零写入(语义同 action=skip);链接仍会照常建立/修复,看 links[]',
375
+ },
376
+ };
377
+ /** 渲染成 `a = 释义;b = 释义` —— field_notes 的单元格形态(与 `api list` 同款)。 */
378
+ function renderStateNotes(notes) {
379
+ return Object.entries(notes).map(([k, v]) => `${k} = ${v}`).join(';');
380
+ }
381
+ /** `skill where` 的 `meta.field_notes`(导出供测试核对真实渲染路径)。 */
382
+ export function whereFieldNotes() {
383
+ return {
384
+ 'entity.source': `实体目录来源:${ENTITY_SOURCES.join(' > ')}(优先级即顺序)`,
385
+ 'entity.exists': 'true/false = 是否存在;null = 无法判定(与 state=unknown 配套)—— 不是「不存在」',
386
+ 'entity.state': renderStateNotes(SKILL_STATE_NOTES.entityState),
387
+ 'entity.installed': '已安装那份正文的版本元数据;null(整个对象)= 判定不了(实体不可用或清单缺失/损坏),不是「兼容」'
388
+ + '。compatible 只对「正文与清单记录的 content_hash 一致」的那份正文成立:'
389
+ + '正文被手工改过或读不动时为 null(判定不了),不是 false',
390
+ cli_contract_version: '本 CLI 自己的正文契约号。⚠️ 与 entity.installed.skill_contract_version'
391
+ + '(已安装那份的)是两个数:两者相等才说明手上的正文配得上这份 CLI。'
392
+ + '这里报的是 CLI 的,不要当成「已安装版本」',
393
+ 'links[].state': renderStateNotes(SKILL_STATE_NOTES.linkState),
394
+ };
395
+ }
396
+ /**
397
+ * `skill install` 的 `meta.field_notes`(导出供测试核对真实渲染路径)。
398
+ * ⚠️ 按输出形态分开:dry-run 没有 `status`、真实安装没有 `action`/`planned_status` ——
399
+ * 图例只解释**该输出里真实存在**的字段(否则就是「声明了但没人读」的反向形态:
400
+ * 解释一个不存在的键)。
401
+ */
402
+ export function installFieldNotes(mode) {
403
+ const common = {
404
+ entity_source: `实体目录来源:${ENTITY_SOURCES.join(' > ')}(优先级即顺序)`,
405
+ 'links[].state': renderStateNotes(SKILL_STATE_NOTES.linkState),
406
+ // ⚠️ `links[].error` 只在 state=unknown(ELOOP 等探测异常)时出现,此前没释义
407
+ //(2026-11-04 反向 sweep 实测)。它是「这一条链接为什么判不了」的唯一依据。
408
+ 'links[].error': '这条链接探测失败的原因(只在 state=unknown 时出现)。'
409
+ + '⚠️ 有它不代表链接坏了,而是「读不出来」—— install 会跳过这一条、不动它',
410
+ // ⚠️ `dry_run` 是 Agent 要按值分支的机器布尔,此前两个形态都没释义(2026-11-04
411
+ // 反向 sweep 实测)。与 sync install 的同名字段同义 —— 别按「装上没有」读它。
412
+ // `false` 只说明走的是真实安装流程,**不等于这次写入了东西**(内容一致时
413
+ // status=skipped、零写入)—— 是否改动看 status / links[]。
414
+ dry_run: 'true = 只出计划:正文与链接都零写入、零建链(--dry-run)。'
415
+ + 'false = 走真实安装流程。⚠️ 它不回答「这次是否改动了东西」—— 内容一致时 status=skipped、'
416
+ + '零写入(要判断看 status 与 links[]);也不回答「现在装没装」—— dry-run 对已装好的实体也一样只出计划',
417
+ };
418
+ return mode === 'dry-run'
419
+ ? {
420
+ action: renderStateNotes(SKILL_STATE_NOTES.installAction),
421
+ planned_status: renderStateNotes(SKILL_STATE_NOTES.installStatus),
422
+ // `links[].action` 只在 dry-run 的计划里存在:真实安装的 links 条目只有 state
423
+ // 与可选 error(`InstallResult['links']` 的类型如此)——免得解释一个读不到的键。
424
+ 'links[].action': renderStateNotes(SKILL_STATE_NOTES.linkAction),
425
+ ...common,
426
+ }
427
+ : { status: renderStateNotes(SKILL_STATE_NOTES.installStatus), ...common };
428
+ }
429
+ /**
430
+ * `skill check` 的违规规则释义(10 值闭集)。
431
+ *
432
+ * ⚠️ 为什么逐值写:`violations[].rule` 是 Agent 要按值分支的机器值 ——
433
+ * 「命令拼错」「flag 位置错」「正文里写了表名」对应完全不同的修法。
434
+ * `Record<ViolationRule, string>` 让 `check.ts` 加一条规则而不在这里补释义时**编译失败**。
435
+ *
436
+ * 释义必须回答「这条规则为什么红、怎么改」,不能拿另一条规则的例子凑数:
437
+ * `table_name` 的红线是**正文任何位置出现表名**(包括否定句里的举例),不是「表名拼错」;
438
+ * `sql_sequence` 只认同时含独立词 SELECT 与 FROM 的完整序列,DROP TABLE 不是例子;
439
+ * `unknown_positional` 的点名域是命令 spec 声明的闭集(表/任务/接口 id),不是 agent 名。
440
+ */
441
+ export const CHECK_RULE_NOTES = {
442
+ unknown_command: '命令不在本 CLI 的命令树里(拼错,或该命令尚未实现)',
443
+ unknown_flag: 'flag 没登记在该命令的参数表上',
444
+ unknown_positional: '位置参数的字面取值不在该命令 spec 声明的取值域闭集里'
445
+ + '(如 db describe 的表名、sync run 的任务 id、api call 的接口 id),或位置参数数量超过声明',
446
+ rejected_flag: '用了该命令显式拒绝的 flag',
447
+ flag_before_subcommand: 'flag 写在子命令之前(如 qiyu --db x store init)',
448
+ flag_before_positional: 'flag 写在位置参数之前(只对 spec 标记 first 的命令,如 qiyu api call --body … <id>)',
449
+ flag_missing_value: '值位 flag 后面缺少取值',
450
+ table_name: '正文代码面出现了 TABLES 里的表名(出现即违规,哪怕是否定句里的举例)——'
451
+ + '数据侧事实不得硬编码,删掉表名、改成 qiyu db tables 在运行时获取。'
452
+ + '⚠️ 它不查「表名是否仍存在」,查的是「有没有写」',
453
+ sql_sequence: '正文里出现了同时含独立词 SELECT 与 FROM 的完整 SQL 关键字序列'
454
+ + '(逐行或整个围栏块)——删掉完整查询,改用 qiyu query;DROP TABLE 等危险片段不属这条',
455
+ unknown_kind: '正文里的 kind: x 不在 ERROR_KINDS 里',
456
+ };
457
+ /**
458
+ * `skill check` 三种形态的 `meta.field_notes`(导出供测试核对真实渲染路径)。
459
+ * ⚠️ 按形态分开:单基准有 `baseline`,compare 有 `entity_source` / `package` /
460
+ * `installed` / `differences` —— 一份图例解释另一形态不存在的键,就是「声明了但没人读」
461
+ * 的反向形态。
462
+ */
463
+ export function checkFieldNotes(mode) {
464
+ const ruleCell = renderStateNotes(CHECK_RULE_NOTES);
465
+ const common = {
466
+ mode: renderStateNotes({
467
+ package: '只查包内正文(CI 可跑)',
468
+ installed: '只查已安装的正文',
469
+ compare: '两份都查并列出差异',
470
+ }),
471
+ skill_contract_version: 'CLI 自己的正文契约号 —— 检查的是正文对这份 CLI 契约的符合度,'
472
+ + '不是已安装那份的契约号',
473
+ warnings: '无法静态判定的条目详情(与 unverifiable 同源)。没有时不出现',
474
+ };
475
+ /** 退出码释义(三形态各自可能「有结果但退出码 1」)。 */
476
+ const exitCodeNote = {
477
+ exit_code: '本命令的退出码(0 = 无违规且两侧一致,1 = 有问题)。⚠️ 它是 1 时 stdout 仍是 '
478
+ + '`{ok:true,…}` 且没有 `error` 对象 —— 不要按 `error.kind` 分支,先看退出码再看 data。'
479
+ + '也不要用「有没有 error」判断检查是否通过',
480
+ };
481
+ /** 违规 / 无法判定条目的元素释义(`prefix` 是它们在输出里的真实路径)。 */
482
+ const elementDocs = (prefix) => {
483
+ const p = prefix === '' ? '' : `${prefix}.`;
484
+ return {
485
+ [`${p}violations[].line`]: '违规所在行号(1 起算)',
486
+ [`${p}violations[].rule`]: ruleCell,
487
+ [`${p}violations[].detail`]: '给人读的说明(含该行原文片段)',
488
+ [`${p}unverifiable[].line`]: '无法静态判定的条目所在行号',
489
+ [`${p}unverifiable[].detail`]: '无法静态判定的原因。⚠️ 它不是违规,不改变退出码'
490
+ + '(详情同时进 meta.warnings)',
491
+ };
492
+ };
493
+ if (mode !== 'compare') {
494
+ // 单基准:violations / unverifiable 在顶层
495
+ return {
496
+ ...common,
497
+ ...exitCodeNote,
498
+ baseline: mode === 'package'
499
+ ? '被检查的包内正文目录'
500
+ : '被检查的已安装实体目录(--dir 可改)',
501
+ ...elementDocs(''),
502
+ };
503
+ }
504
+ // compare:violations / unverifiable 分别在 package 与 installed 之下 —— 图例键必须
505
+ // 是真实路径(`violations[].x` 在 compare 输出里不存在)。
506
+ return {
507
+ ...common,
508
+ ...exitCodeNote,
509
+ entity_source: `已安装目录的来源:${ENTITY_SOURCES.join(' > ')}(优先级即顺序)`,
510
+ 'package.dir': '包内正文目录',
511
+ ...elementDocs('package'),
512
+ 'installed.dir': '已安装实体目录',
513
+ 'installed.present': 'true = 读到了 SKILL.md 并完成检查。false = 没读到(原因见 installed.error),'
514
+ + '此时 installed.violations / installed.unverifiable 不出现',
515
+ 'installed.error': 'installed.present=false 的原因(目录不存在 / 不可读 / 缺 SKILL.md / 读取失败)',
516
+ ...elementDocs('installed'),
517
+ differences: '两份的差异清单(人类可读字符串)。空数组 = 没发现差异。'
518
+ + '⚠️ 非空时退出码必为 1(每条差异都对应失败成因或违规)',
519
+ };
520
+ }
305
521
  /** 链接四态 → 安装会采取的动作(dry-run 输出用;与 install.ts 的分派表一致)。 */
306
522
  function linkAction(state) {
307
523
  switch (state) {
@@ -452,7 +668,7 @@ async function skillInstall(argv) {
452
668
  force,
453
669
  no_link: noLink,
454
670
  links: planned.links,
455
- }, warnings.length > 0 ? { warnings } : undefined);
671
+ }, { field_notes: installFieldNotes('dry-run'), ...(warnings.length > 0 ? { warnings } : {}) });
456
672
  }
457
673
  let result;
458
674
  try {
@@ -515,7 +731,7 @@ async function skillInstall(argv) {
515
731
  version: PACKAGE_VERSION,
516
732
  status: result.status,
517
733
  links,
518
- }, allWarnings.length > 0 ? { warnings: allWarnings } : undefined);
734
+ }, { field_notes: installFieldNotes('real'), ...(allWarnings.length > 0 ? { warnings: allWarnings } : {}) });
519
735
  }
520
736
  // —— skill check ——
521
737
  /**
@@ -582,8 +798,15 @@ function checkMeta(warnings) {
582
798
  }
583
799
  /** 单基准(包内 / 已安装)的报告与退出码。 */
584
800
  function reportSingle(mode, dir, result) {
585
- const code = ok({ mode, baseline: dir, violations: result.violations, unverifiable: result.warnings }, checkMeta(result.warnings.map((w) => w.detail)));
586
- return result.violations.length > 0 ? 1 : code;
801
+ const exit = result.violations.length > 0 ? 1 : 0;
802
+ const code = ok({ mode, baseline: dir, violations: result.violations, unverifiable: result.warnings }, {
803
+ ...checkMeta(result.warnings.map((w) => w.detail)),
804
+ // C4(2026-11-06):退出码是 Agent 必须与 ok:true 一起读的机器事实,放进 meta
805
+ // 而不是只写在图例里 —— 图例键必须对应真实字段(反向守卫钉着)。
806
+ exit_code: exit,
807
+ field_notes: checkFieldNotes(mode),
808
+ });
809
+ return exit === 1 ? 1 : code;
587
810
  }
588
811
  /** stat 一个路径:ENOENT → 不存在;其余错误如实带出(ENOTDIR/EACCES)。 */
589
812
  function probeDir(dir) {
@@ -676,6 +899,9 @@ async function skillCheck(argv) {
676
899
  const probe = probeDir(entityDir);
677
900
  if (!probe.exists) {
678
901
  differences.push(`已安装目录不存在:${entityDir}`);
902
+ // 与其余三种 present=false 成因保持一致:原因必须机器可读地给出,
903
+ // 不能只藏在中文 differences 字符串里(图例承诺了「原因见 installed.error」)。
904
+ installedData.error = '目录不存在';
679
905
  installedFailed = true;
680
906
  }
681
907
  else if (probe.error !== undefined || !probe.isDir) {
@@ -714,17 +940,57 @@ async function skillCheck(argv) {
714
940
  installedData.unverifiable = outcome.result.warnings;
715
941
  // 内容哈希与违规数:前者回答「两份正文是否一致」,后者回答「判定结果是否一致」。
716
942
  try {
717
- if (contentHash(pkgDir) !== contentHash(entityDir)) {
943
+ // ⚠️ 同 `where` 与 `install` 的受管文件口径(2026-11-06 审查):整目录总哈希会把
944
+ // 用户放进实体的额外文件算成「正文不同」,让 CI 的 `--compare` 无端退 1 并把成因
945
+ // 写成「正文内容不同」。有受管清单时按受管文件逐个比,没有才退回总哈希。
946
+ const cmpInfo = readInstalledManifestInfo(entityDir);
947
+ // ⚠️ 文件集必须一致才可比(Codex PR #69):包在安装之后**新增**文件时,
948
+ // 清单里的仍是旧文件集 —— 只比这组旧路径会得出「一致」,CI 的 `--compare`
949
+ // 退 0,漏报「装的是旧包」。与 `planInstall` 的受管集判据同源(同一形态
950
+ // 在两处出现过,修一处必查另一处)。
951
+ let differs;
952
+ let reason = '包内与已安装的正文内容不同(content_hash 不一致)';
953
+ if (cmpInfo?.files !== undefined && cmpInfo.files.length > 0) {
954
+ const pkgFiles = listFiles(pkgDir);
955
+ const sameSet = sameFileSet(cmpInfo.files, pkgFiles);
956
+ if (!sameSet) {
957
+ differs = true;
958
+ reason = '已安装的文件集与包内不同(包已增删文件)';
959
+ }
960
+ else {
961
+ // ⚠️ 受管条目先筛「实体内的普通文件」再读(Codex PR #69 第五轮):FIFO 会让
962
+ // `readFileSync` 无限阻塞,符号链接会被跟随、可能拿到与包内相同的内容。
963
+ const h = managedContentHash(entityDir, cmpInfo.files);
964
+ if ('hash' in h) {
965
+ differs = h.hash !== contentHashOfFiles(pkgDir, cmpInfo.files);
966
+ }
967
+ else {
968
+ differs = true;
969
+ reason = `已安装的 ${h.rel} 不可比(${h.problem === 'missing' ? '缺失'
970
+ : h.problem === 'not_plain' ? '非普通文件(符号链接/目录/FIFO 等)'
971
+ : '真实路径不在实体目录内'})`;
972
+ }
973
+ }
974
+ }
975
+ else {
976
+ differs = contentHash(pkgDir) !== contentHash(entityDir);
977
+ }
978
+ if (differs) {
718
979
  // 「正文内容不同」计入 bad:`--compare` 的存在意义就是发现「装过旧版、包升级
719
980
  // 改了正文」(spec D2.1 的洞),而它在 CI 里唯一的信号就是退出码。同一
720
981
  // `differences` 数组里的其它成因(目录不存在 / 缺 SKILL.md / 读取失败 / 哈希
721
982
  // 比较失败)一律退 1,唯独内容漂移退 0 = 检测到了却不报(终审 I3)。
722
- differences.push('包内与已安装的正文内容不同(content_hash 不一致)');
983
+ differences.push(reason);
723
984
  installedFailed = true;
724
985
  }
725
986
  }
726
987
  catch (e) {
727
988
  // 审查 M3:无法完成内容比较 = 无法完成比较,退出码必须为 1。
989
+ // ⚠️ 可读性提示(2026-11-06 Codex 第五轮复核):`managedContentHash` 已把
990
+ // 「缺失 / 非普通文件 / 逃出实体」三种形态归成有名字的差异,**读取错误**
991
+ // (EACCES 等)才落到这里 —— 而那种文件通常更早被上面的 `runCheck` 拦成
992
+ // 「已安装目录读取失败」。本分支因此是**竞态兜底**(检查通过之后、比较之前
993
+ // 文件变得不可读),没有能稳定触达它的用例,如实记录而不是假装有覆盖。
728
994
  differences.push(`内容哈希比较失败:${errMsg(e)}`);
729
995
  installedFailed = true;
730
996
  }
@@ -738,6 +1004,9 @@ async function skillCheck(argv) {
738
1004
  ...pkgOutcome.result.warnings.map((w) => `包内:${w.detail}`),
739
1005
  ...installedUnverifiable.map((w) => `已安装:${w.detail}`),
740
1006
  ];
1007
+ const bad = installedFailed
1008
+ || pkgOutcome.result.violations.length > 0
1009
+ || installedViolations > 0;
741
1010
  const code = ok({
742
1011
  mode: 'compare',
743
1012
  entity_source: source,
@@ -748,10 +1017,7 @@ async function skillCheck(argv) {
748
1017
  },
749
1018
  installed: installedData,
750
1019
  differences,
751
- }, checkMeta(warnings));
752
- const bad = installedFailed
753
- || pkgOutcome.result.violations.length > 0
754
- || installedViolations > 0;
1020
+ }, { ...checkMeta(warnings), exit_code: bad ? 1 : 0, field_notes: checkFieldNotes('compare') });
755
1021
  return bad ? 1 : code;
756
1022
  }
757
1023
  /**
@@ -785,6 +1051,26 @@ function probeAgentLinks(home, entityDir) {
785
1051
  continue;
786
1052
  }
787
1053
  const linkPath = join(dir, LINK_NAME);
1054
+ // 形态先走共享判据(审查 #11/#13):`~/.claude/skills` 被**普通文件**占住时
1055
+ // `linkState` 会顺着 `join()` 得 `ENOTDIR` 抛错,此前这里报 unknown+ENOTDIR;
1056
+ // 而真实安装报的是「路径存在但不是目录」。两条命令对同一状态不同答 —— 现在
1057
+ // 两边都用 `dirShape` 得出同一个 `not_a_directory`。悬空符号链接同理(此前
1058
+ // `linkState` 报 dangling,而那条链接指向的是**目录位置**,不是 skill 链接)。
1059
+ let shape;
1060
+ try {
1061
+ shape = dirShape(dir);
1062
+ }
1063
+ catch (e) {
1064
+ links.push({ agent: name, path: linkPath, state: 'unknown', error: errMsg(e) });
1065
+ warnings.push(`${name} 的 skills 目录无法检查(${errMsg(e)}):${dir}`);
1066
+ continue;
1067
+ }
1068
+ if (shape !== 'dir') {
1069
+ // absent 的目录由 probeAgentDirs 过滤掉了;走到这里只剩「存在但不是目录」。
1070
+ links.push({ agent: name, path: linkPath, state: 'unknown', error: '路径存在但不是目录' });
1071
+ warnings.push(`${name} 的 skills 路径存在但不是目录(无法在此建链,需先由人处理该路径):${dir}`);
1072
+ continue;
1073
+ }
788
1074
  try {
789
1075
  links.push({ agent: name, path: linkPath, state: linkState(linkPath, entityDir) });
790
1076
  }
@@ -803,28 +1089,43 @@ async function skillWhere(argv) {
803
1089
  const warnings = [];
804
1090
  // 启动探测的门是否在这台机器/这个进程上关掉了(追加审查 [57]):where 是排查命令,
805
1091
  // 它要说清「为什么别的命令没有 meta.warnings」。显式来源不经过门,此时不会有这条。
806
- const probe = startupProbeStatus();
1092
+ // ⚠️ 本命令自己的显式来源要传进去(S3):`skill where --dir X` 在测试进程里曾同时
1093
+ // 报「没有显式给出 --dir」,与用户刚做的动作矛盾 —— 启动探测确实看不到 flag,
1094
+ // 但文案必须说清那是**启动探测**,而不是本命令。
1095
+ const probe = startupProbeStatus(source === '--dir' || source === 'QIYU_SKILL_DIR' ? source : undefined);
807
1096
  if (probe.note !== undefined)
808
1097
  warnings.push(probe.note);
809
- // 实体状态:只读 stat;ENOENT 是「未安装」,其余异常如实记 unknown。
1098
+ // 实体状态:形态走共享判据 `dirShape`(唯一实现,审查 #9)。三态映射到 EntityState:
1099
+ // · absent → exists:false / missing(真的不存在,= 未安装);
1100
+ // · not_a_directory → exists:true / not_a_directory(**路径存在**但不是目录:普通
1101
+ // 文件,或悬空符号链接 —— statSync 抛 ENOENT 但 lstat 看得到那个条目);
1102
+ // · dir → exists:true / ok。
1103
+ // ⚠️ 此前这里直接用 `statSync` 并把 ENOENT 等同「不存在」,于是**悬空符号链接**被报成
1104
+ // missing 且警告建议 `qiyu skill install` —— 而那条命令在悬空链接上必然退 1(install
1105
+ // 不覆盖链接)。CLI 自荐了一条走不通的路(实测 #9)。收敛后 where 与 install 同答。
1106
+ // 判定不了(ELOOP/EACCES…)仍如实记 exists:null / unknown:`exists:false` 在那些
1107
+ // 情况下可能是一句假话(审查 M6)。
810
1108
  let entity;
811
1109
  let entityUsable = false;
812
1110
  try {
813
- const st = statSync(entityDir);
814
- const isDir = st.isDirectory();
815
- entity = { path: entityDir, source, exists: true, state: isDir ? 'ok' : 'not_a_directory' };
816
- entityUsable = isDir;
1111
+ switch (dirShape(entityDir)) {
1112
+ case 'dir':
1113
+ entity = { path: entityDir, source, exists: true, state: 'ok' };
1114
+ entityUsable = true;
1115
+ break;
1116
+ case 'absent':
1117
+ entity = { path: entityDir, source, exists: false, state: 'missing' };
1118
+ break;
1119
+ case 'not_a_directory':
1120
+ entity = { path: entityDir, source, exists: true, state: 'not_a_directory' };
1121
+ break;
1122
+ }
817
1123
  }
818
1124
  catch (e) {
819
- if (isErrno(e, 'ENOENT')) {
820
- entity = { path: entityDir, source, exists: false, state: 'missing' };
821
- }
822
- else {
823
- // 审查 M6:ELOOP/EACCES 下我们**不知道**路径是否存在——`exists: false` 可能
824
- // 是一句假话。用 null 表示「无法判定」,与 state:'unknown' 配套;见 SKILL_USAGE。
825
- warnings.push(`实体路径无法检查(${errMsg(e)}):${entityDir}`);
826
- entity = { path: entityDir, source, exists: null, state: 'unknown', error: errMsg(e) };
827
- }
1125
+ // 审查 M6:ELOOP/EACCES 下我们**不知道**路径是否存在——`exists: false` 可能
1126
+ // 是一句假话。用 null 表示「无法判定」,与 state:'unknown' 配套;见 SKILL_USAGE。
1127
+ warnings.push(`实体路径无法检查(${errMsg(e)}):${entityDir}`);
1128
+ entity = { path: entityDir, source, exists: null, state: 'unknown', error: errMsg(e) };
828
1129
  }
829
1130
  // 已安装那份的**版本元数据**(2026-10-26 补):`SKILL.md` 教 Agent「用
830
1131
  // `skill_contract_version` 判断手上的正文能否配这份 CLI」,而此前没有任何命令报出
@@ -837,24 +1138,115 @@ async function skillWhere(argv) {
837
1138
  // 则是「这个字段不存在」,两种沉默对 Agent 含义不同,不能混。
838
1139
  // · `compatible` = 三方判定的落点:只有契约号相等才算配套。包版本不同不算
839
1140
  // 不兼容(正文没变就还能用),这正是 SKILL.md 说「别拿包版本号去比」的原因。
1141
+ // · ⚠️ 清单只描述**安装那一刻**的正文(审查 #10):正文被手工改过后清单仍在、
1142
+ // 契约号也不变,只读清单就会拿旧快照给新正文背书,报出 `compatible:true`。
1143
+ // 所以先算实体当前的内容哈希与清单记录的 `content_hash` 比:不一致(或正文读
1144
+ // 不动)→ `compatible:null`(**判定不了**,不是 false:正文改了不等于不配套,
1145
+ // 我们只是没有依据再说它配套)。代价是 `where` 要读一遍正文——它是排查命令,
1146
+ // 不在启动路径上,换来的是这句判定有据可依。
840
1147
  entity.installed = null;
841
1148
  if (entityUsable) {
842
1149
  const info = readInstalledManifestInfo(entityDir);
843
1150
  if (info !== null) {
1151
+ // `bodyVerified`:清单描述的正文就是磁盘上这份吗?只有它为真,清单里的契约号
1152
+ // 才是在描述「手上的正文」——否则那个号属于旧正文,不能拿来报 `兼容/不兼容`。
1153
+ //
1154
+ // ⚠️ 判据是**受管文件**而不是整个实体目录的总哈希(CodeRabbit #60 实测):
1155
+ // `contentHash(entityDir)` 会把用户自己放进实体的额外文件也算进去,而 `--force`
1156
+ // 刻意不删它们(`cleanupPreviousManaged`)——只比总哈希的话,多一个用户文件就会
1157
+ // 永远报「正文被改过」,而我们推的 `--force` 根本修不好(实测:装好后加
1158
+ // `my-notes.md` → compatible:null,--force 之后仍是 null)。所以:
1159
+ // · 受管文件逐个比对(清单 `files` + 逐文件 `file_hashes`);
1160
+ // · 受管文件都一致但总哈希仍不同 → 正文没被改,差异只在额外文件上
1161
+ // (额外文件单独进 warnings,不改变配套结论);
1162
+ // · 旧清单没有 files/file_hashes → 无从核对受管集,退回总哈希(宁严不宽,
1163
+ // 额外文件会被算成「正文被改过」——那种清单本来也判不出正文是不是旧的)。
1164
+ let bodyVerified = false;
1165
+ // `bodyUnreadable` 与「不一致」分开:读不动是环境问题,不是正文漂移。
1166
+ let bodyUnreadable = false;
1167
+ let extraFiles = null;
1168
+ if (info.files !== undefined && info.fileHashes !== undefined) {
1169
+ const managed = new Set(info.files);
1170
+ let managedOk = true;
1171
+ for (const rel of info.files) {
1172
+ let hash = null;
1173
+ try {
1174
+ hash = fileHash(join(entityDir, rel));
1175
+ }
1176
+ catch {
1177
+ // 受管文件缺失/读不动 = 正文不完整,按「被改过」处理。
1178
+ }
1179
+ if (hash === null || hash !== info.fileHashes[rel]) {
1180
+ managedOk = false;
1181
+ break;
1182
+ }
1183
+ }
1184
+ bodyVerified = managedOk;
1185
+ if (managedOk) {
1186
+ try {
1187
+ // 受管文件一致:额外(非受管)文件不影响正文判定,但要说出来。
1188
+ extraFiles = listFiles(entityDir).filter((rel) => !managed.has(rel));
1189
+ }
1190
+ catch {
1191
+ // 列不出目录不影响「正文一致」的结论,额外文件就不报。
1192
+ }
1193
+ }
1194
+ }
1195
+ else {
1196
+ try {
1197
+ bodyVerified = contentHash(entityDir) === info.contentHash;
1198
+ }
1199
+ catch {
1200
+ bodyUnreadable = true;
1201
+ }
1202
+ }
1203
+ const contractMismatch = info.skillContractVersion !== SKILL_CONTRACT_VERSION;
844
1204
  entity.installed = {
845
1205
  version: info.version,
846
1206
  skill_contract_version: info.skillContractVersion,
847
- compatible: info.skillContractVersion === SKILL_CONTRACT_VERSION,
1207
+ compatible: bodyVerified ? !contractMismatch : null,
848
1208
  };
849
- }
850
- if (info !== null && info.skillContractVersion !== SKILL_CONTRACT_VERSION) {
851
- // ⚠️ 必须推 `--force`(2026-10-26 实测):正文一改,实体内容哈希就与包内不同,
852
- // `planInstall` 此时**不带 --force 一律 skipped + 零写入**——照旧文案推
853
- // `qiyu skill install`,用户跑完契约号仍是旧值、警告照旧,等于指了条死路。
854
- // `--force` 是两种形态都收敛的动词:正文确实不同 → 覆盖;正文恰好一致但清单
855
- // 落后 → 走 rewrite-manifest(该分支排在 force 判断之前),同样把号补正。
856
- warnings.push(`已安装的 skill 契约版本为 ${info.skillContractVersion},当前 CLI 是 ${SKILL_CONTRACT_VERSION}`
857
- + ' —— 正文与 CLI 不配套;运行 `qiyu skill install --force` 更新正文');
1209
+ // 清单号与 CLI 不同时,附一句「这个号描述的是哪份正文」——三种实况分开说,
1210
+ // 不让「正文改过」与「确实不配套」共用一句「不配套」(审查 #10 的连带面:
1211
+ // compatible:null 配一句断言不配套的警告,是同一输出里自相矛盾)。
1212
+ const manifestNote = contractMismatch
1213
+ ? `(安装清单记录的契约版本为 ${info.skillContractVersion},当前 CLI 是 ${SKILL_CONTRACT_VERSION})`
1214
+ : '';
1215
+ if (bodyUnreadable) {
1216
+ warnings.push(`已安装正文无法读取,无法确认是否与安装清单一致:${entityDir} —— compatible 因此为 null`
1217
+ + manifestNote);
1218
+ }
1219
+ else if (!bodyVerified) {
1220
+ // 契约号来自清单、清单描述的是旧正文:这时候报 true/false 都是在给改过的
1221
+ // 正文背书。`--force` 是收敛动词(覆盖正文并按当前包装清单)。
1222
+ //
1223
+ // ⚠️ 旧清单(没有受管文件列表)走总哈希,额外文件会让它「不一致」——而那种
1224
+ // 清单根本分不出「正文被改」与「多了个用户文件」。此时**不能只报前一种成因**:
1225
+ // 报错必须点名真正给坏值的来源(或者如实说分不出来)。
1226
+ const legacyNote = info.files === undefined || info.fileHashes === undefined
1227
+ ? '(该清单没有受管文件列表,无法区分「正文被改」与「实体里有额外的自家文件」)'
1228
+ : '';
1229
+ warnings.push('已安装正文与安装清单记录的 content_hash 不一致(正文被手工改过或写入不完整)'
1230
+ + ' —— 契约判定只对清单描述的那份正文成立,compatible 因此为 null;'
1231
+ + '运行 `qiyu skill install --force` 可覆盖为包内正文'
1232
+ + legacyNote
1233
+ + (contractMismatch ? `${manifestNote},但该记录描述的是旧正文,不能据此判断当前正文配不配套` : ''));
1234
+ }
1235
+ else if (contractMismatch) {
1236
+ // ⚠️ 必须推 `--force`(2026-10-26 实测):正文一改,实体内容哈希就与包内不同,
1237
+ // `planInstall` 此时**不带 --force 一律 skipped + 零写入**——照旧文案推
1238
+ // `qiyu skill install`,用户跑完契约号仍是旧值、警告照旧,等于指了条死路。
1239
+ // `--force` 是两种形态都收敛的动词:正文确实不同 → 覆盖;正文恰好一致但清单
1240
+ // 落后 → 走 rewrite-manifest(该分支排在 force 判断之前),同样把号补正。
1241
+ warnings.push(`已安装的 skill 契约版本为 ${info.skillContractVersion},当前 CLI 是 ${SKILL_CONTRACT_VERSION}`
1242
+ + ' —— 正文与 CLI 不配套;运行 `qiyu skill install --force` 更新正文');
1243
+ }
1244
+ // 受管文件都对、只是多了用户自己的文件:只陈述事实,不改变 compatible ——
1245
+ // `--force` 不会删它们(清理阶段刻意保留无法核对的文件),所以这里也**不能**
1246
+ // 顺手推 `--force`(CodeRabbit #60 实测:推了也修不好)。
1247
+ if (bodyVerified && extraFiles !== null && extraFiles.length > 0) {
1248
+ warnings.push(`实体目录里有不在安装清单中的额外文件(不影响正文判定,install 不会删除它们):${extraFiles.join('、')}`);
1249
+ }
858
1250
  }
859
1251
  }
860
1252
  const probed = probeAgentLinks(resolveHome(), entityDir);
@@ -865,7 +1257,7 @@ async function skillWhere(argv) {
865
1257
  // CLI 自己的契约号:与 `entity.installed.skill_contract_version` 并列,让读者能
866
1258
  // 一眼看出「两个数是否相等」,不必再去跑 `--version` 比对。
867
1259
  cli_contract_version: SKILL_CONTRACT_VERSION,
868
- }, warnings.length > 0 ? { warnings } : undefined);
1260
+ }, { field_notes: whereFieldNotes(), ...(warnings.length > 0 ? { warnings } : {}) });
869
1261
  }
870
1262
  // —— 分派 ——
871
1263
  export async function skillCommand(argv) {
@@ -886,15 +1278,17 @@ export async function skillCommand(argv) {
886
1278
  // G1:--pretty 是输出开关,必须写在具体子命令之后(`skill check --pretty`)。
887
1279
  if (sub === '--pretty') {
888
1280
  const unknown = rest.filter((a) => a.startsWith('-') && a !== '--pretty' && a !== '--help' && a !== '-h');
889
- const positional = rest.filter((a) => !a.startsWith('-'));
890
- const extra = [...unknown, ...positional];
891
- if (extra.length > 0) {
892
- return usageFail(`未知参数:${describeArgs(extra)}。--pretty 不接受额外参数`);
1281
+ if (unknown.length > 0) {
1282
+ return usageFail(`未知参数:${describeArgs(unknown)}。--pretty 不接受额外参数`);
893
1283
  }
1284
+ const badPos = prettyPositionalProblem(rest, SKILL_SPECS);
1285
+ if (badPos !== undefined)
1286
+ return usageFail(badPos);
894
1287
  if (rest.includes('--help') || rest.includes('-h')) {
895
1288
  process.stdout.write(SKILL_USAGE);
896
1289
  return 0;
897
1290
  }
1291
+ // ⚠️ 位置参数按「顺序写反」引导(2026-11-07 审查)—— 见 db.ts 同款注释。
898
1292
  return usageFail(prettyAfterSubcommand('skill'));
899
1293
  }
900
1294
  if (sub !== 'install' && sub !== 'check' && sub !== 'where') {