qiyu-cli 0.0.0-stage → 0.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.
Files changed (230) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +464 -2
  3. package/dist/cli.js +248 -0
  4. package/dist/commands/api.js +770 -0
  5. package/dist/commands/auth.js +349 -0
  6. package/dist/commands/credentials-source.js +70 -0
  7. package/dist/commands/db.js +503 -0
  8. package/dist/commands/local-fallback-wiring.js +67 -0
  9. package/dist/commands/local-fallback.js +34 -0
  10. package/dist/commands/query.js +564 -0
  11. package/dist/commands/skill-specs.js +64 -0
  12. package/dist/commands/skill.js +863 -0
  13. package/dist/commands/spec-types.js +145 -0
  14. package/dist/commands/stats.js +299 -0
  15. package/dist/commands/store-flags.js +56 -0
  16. package/dist/commands/store.js +258 -0
  17. package/dist/commands/sync-run.js +479 -0
  18. package/dist/commands/sync.js +757 -0
  19. package/dist/commands/tree.js +27 -0
  20. package/dist/core/config.js +259 -0
  21. package/dist/core/credentials.js +71 -0
  22. package/dist/core/edition.js +18 -0
  23. package/dist/core/envelope.js +201 -0
  24. package/dist/core/errors.js +356 -0
  25. package/dist/core/http.js +348 -0
  26. package/dist/core/ratelimit.js +126 -0
  27. package/dist/core/registry/index.js +212 -0
  28. package/dist/core/registry/params/ai.knowledge.addKnowledge.json +88 -0
  29. package/dist/core/registry/params/ai.knowledge.deleteKnowledges.json +46 -0
  30. package/dist/core/registry/params/ai.knowledge.editChannelAnswer.json +60 -0
  31. package/dist/core/registry/params/ai.knowledge.editKnowledge.json +95 -0
  32. package/dist/core/registry/params/ai.knowledge.editKnowledgeNoSimilars.json +102 -0
  33. package/dist/core/registry/params/ai.knowledge.getCategoryTree.json +39 -0
  34. package/dist/core/registry/params/ai.knowledge.getDetail.json +46 -0
  35. package/dist/core/registry/params/ai.knowledge.search.json +67 -0
  36. package/dist/core/registry/params/ai.statistic.transferHuman.json +60 -0
  37. package/dist/core/registry/params/category.list.json +39 -0
  38. package/dist/core/registry/params/chat.queue.group.query.json +39 -0
  39. package/dist/core/registry/params/crm.modifyOrder.json +48 -0
  40. package/dist/core/registry/params/crm.modifyUser.json +48 -0
  41. package/dist/core/registry/params/crm.syncCrmInfo.json +46 -0
  42. package/dist/core/registry/params/crm.tagChange.json +74 -0
  43. package/dist/core/registry/params/data.overview.ipcc.json +32 -0
  44. package/dist/core/registry/params/data.overview.session.json +53 -0
  45. package/dist/core/registry/params/evaluation.setting.get.json +39 -0
  46. package/dist/core/registry/params/event.applyStaff.json +116 -0
  47. package/dist/core/registry/params/event.evaluate.json +74 -0
  48. package/dist/core/registry/params/event.inviteEvaluate.json +81 -0
  49. package/dist/core/registry/params/event.qcResult.json +166 -0
  50. package/dist/core/registry/params/event.queryQueueStatus.json +39 -0
  51. package/dist/core/registry/params/event.queueEnter.json +40 -0
  52. package/dist/core/registry/params/event.queueLeave.json +46 -0
  53. package/dist/core/registry/params/event.quitQueue.json +39 -0
  54. package/dist/core/registry/params/event.sessionChange.json +95 -0
  55. package/dist/core/registry/params/event.sessionData.json +452 -0
  56. package/dist/core/registry/params/event.sessionEnd.json +117 -0
  57. package/dist/core/registry/params/event.sessionStart.json +109 -0
  58. package/dist/core/registry/params/event.updateUInfo.json +46 -0
  59. package/dist/core/registry/params/export.session.check.json +7 -0
  60. package/dist/core/registry/params/export.session.json +7 -0
  61. package/dist/core/registry/params/export.session.one.json +7 -0
  62. package/dist/core/registry/params/export.session.one.message.json +7 -0
  63. package/dist/core/registry/params/get_call_order.json +50 -0
  64. package/dist/core/registry/params/get_call_user_info.json +36 -0
  65. package/dist/core/registry/params/get_order.json +50 -0
  66. package/dist/core/registry/params/get_token.json +22 -0
  67. package/dist/core/registry/params/get_user_info.json +36 -0
  68. package/dist/core/registry/params/icoutcall.callIntercept.list.json +32 -0
  69. package/dist/core/registry/params/icoutcall.dialogFlow.fuzzySearch.json +53 -0
  70. package/dist/core/registry/params/icoutcall.dialogFlow.getDialogFlowList.json +32 -0
  71. package/dist/core/registry/params/icoutcall.get.customer.json +39 -0
  72. package/dist/core/registry/params/icoutcall.get.jobdetail.json +39 -0
  73. package/dist/core/registry/params/icoutcall.get.jobproperties.json +39 -0
  74. package/dist/core/registry/params/icoutcall.history.seat.json +67 -0
  75. package/dist/core/registry/params/icoutcall.history.team.json +67 -0
  76. package/dist/core/registry/params/icoutcall.job.create.json +53 -0
  77. package/dist/core/registry/params/icoutcall.job.importcustomer.json +46 -0
  78. package/dist/core/registry/params/icoutcall.job.pause.json +39 -0
  79. package/dist/core/registry/params/icoutcall.job.readdcustomer.json +109 -0
  80. package/dist/core/registry/params/icoutcall.job.start.json +39 -0
  81. package/dist/core/registry/params/icoutcall.job.terminate.json +39 -0
  82. package/dist/core/registry/params/icoutcall.phone.getLineList.json +32 -0
  83. package/dist/core/registry/params/ipcc.calltask.add.auto.json +117 -0
  84. package/dist/core/registry/params/ipcc.calltask.add.byCustom.json +96 -0
  85. package/dist/core/registry/params/ipcc.calltask.add.byRelation.json +82 -0
  86. package/dist/core/registry/params/ipcc.calltask.add.toGroup.json +89 -0
  87. package/dist/core/registry/params/ipcc.calltask.add.toStaff.json +89 -0
  88. package/dist/core/registry/params/ipcc.calltask.get.json +47 -0
  89. package/dist/core/registry/params/ipcc.calltaskdetail.add.json +54 -0
  90. package/dist/core/registry/params/ipcc.calltaskdetail.delete.json +40 -0
  91. package/dist/core/registry/params/ipcc.calltaskdetail.get.json +54 -0
  92. package/dist/core/registry/params/ipcc.calltaskdetail.update.json +40 -0
  93. package/dist/core/registry/params/ipcc.customfield.template.get.json +47 -0
  94. package/dist/core/registry/params/ipcc.login.json +47 -0
  95. package/dist/core/registry/params/kefu.add.json +130 -0
  96. package/dist/core/registry/params/kefu.delete.json +39 -0
  97. package/dist/core/registry/params/kefu.update.json +137 -0
  98. package/dist/core/registry/params/kefu.v2.query.json +39 -0
  99. package/dist/core/registry/params/kefuGroup.add.json +39 -0
  100. package/dist/core/registry/params/kefuGroup.delete.json +39 -0
  101. package/dist/core/registry/params/kefuGroup.update.json +46 -0
  102. package/dist/core/registry/params/kefuGroup.updateKefus.json +46 -0
  103. package/dist/core/registry/params/merchant.account.login.json +53 -0
  104. package/dist/core/registry/params/merchant.changePassword.json +46 -0
  105. package/dist/core/registry/params/merchant.create.json +81 -0
  106. package/dist/core/registry/params/merchant.disable.json +39 -0
  107. package/dist/core/registry/params/merchant.enable.json +39 -0
  108. package/dist/core/registry/params/merchant.list.json +46 -0
  109. package/dist/core/registry/params/merchant.query.json +46 -0
  110. package/dist/core/registry/params/merchant.update.json +74 -0
  111. package/dist/core/registry/params/message.send.image.json +53 -0
  112. package/dist/core/registry/params/message.send.json +53 -0
  113. package/dist/core/registry/params/message.send.voice.json +53 -0
  114. package/dist/core/registry/params/message.sendFile.json +39 -0
  115. package/dist/core/registry/params/message.uploadFile.json +39 -0
  116. package/dist/core/registry/params/online.session.category.list.json +39 -0
  117. package/dist/core/registry/params/online.session.customfield.template.json +39 -0
  118. package/dist/core/registry/params/online.session.customfield.update.json +74 -0
  119. package/dist/core/registry/params/order.upload.json +40 -0
  120. package/dist/core/registry/params/push.msg.image.json +74 -0
  121. package/dist/core/registry/params/push.msg.richText.json +74 -0
  122. package/dist/core/registry/params/push.msg.text.json +74 -0
  123. package/dist/core/registry/params/receive.message.json +89 -0
  124. package/dist/core/registry/params/robot.data.getQuestionsByCategoryName.json +67 -0
  125. package/dist/core/registry/params/robot.data.knowledge.json +46 -0
  126. package/dist/core/registry/params/robot.data.kpoint.json +46 -0
  127. package/dist/core/registry/params/robot.data.queryStandardByEffectiveQuestion.json +46 -0
  128. package/dist/core/registry/params/robot.data.queryStandardQuestionList.json +46 -0
  129. package/dist/core/registry/params/robot.evaluation.comment.json +67 -0
  130. package/dist/core/registry/params/robot.evaluation.setting.json +46 -0
  131. package/dist/core/registry/params/robot.session.assist.json +74 -0
  132. package/dist/core/registry/params/robot.session.chat.json +74 -0
  133. package/dist/core/registry/params/robot.session.close.json +53 -0
  134. package/dist/core/registry/params/robot.session.commonQuestions.json +74 -0
  135. package/dist/core/registry/params/robot.session.create.json +81 -0
  136. package/dist/core/registry/params/robot.session.evaluation.json +67 -0
  137. package/dist/core/registry/params/robot.session.msgAssociate.json +46 -0
  138. package/dist/core/registry/params/robot.session.msgEvaluation.json +53 -0
  139. package/dist/core/registry/params/robot.session.msgPredict.json +74 -0
  140. package/dist/core/registry/params/robot.session.transfer.json +36 -0
  141. package/dist/core/registry/params/robot.session.uploadFile.json +32 -0
  142. package/dist/core/registry/params/robot.statistic.summary.json +53 -0
  143. package/dist/core/registry/params/robot.transfer.config.json +15 -0
  144. package/dist/core/registry/params/session.user.profile.json +39 -0
  145. package/dist/core/registry/params/settings.wxTemplates.json +46 -0
  146. package/dist/core/registry/params/smstask.create.json +53 -0
  147. package/dist/core/registry/params/smstask.status.json +39 -0
  148. package/dist/core/registry/params/staff.group.list.new.json +39 -0
  149. package/dist/core/registry/params/staff.group.members.new.json +46 -0
  150. package/dist/core/registry/params/staff.list.new.json +46 -0
  151. package/dist/core/registry/params/staff.login.json +47 -0
  152. package/dist/core/registry/params/statistic.overview.json +61 -0
  153. package/dist/core/registry/params/statistic.performance.json +82 -0
  154. package/dist/core/registry/params/statistic.salaryDetail.json +54 -0
  155. package/dist/core/registry/params/statistic.satisfaction.report.json +68 -0
  156. package/dist/core/registry/params/statistic.staffAttendance.json +75 -0
  157. package/dist/core/registry/params/statistic.staffquality.json +75 -0
  158. package/dist/core/registry/params/statistic.staffworklod.json +68 -0
  159. package/dist/core/registry/params/tag.all.json +32 -0
  160. package/dist/core/registry/params/tag.batchUpdate.json +32 -0
  161. package/dist/core/registry/params/tag.update.json +60 -0
  162. package/dist/core/registry/params/ticket.apply.json +46 -0
  163. package/dist/core/registry/params/ticket.batch.modify.json +53 -0
  164. package/dist/core/registry/params/ticket.create.json +151 -0
  165. package/dist/core/registry/params/ticket.filter.count.json +46 -0
  166. package/dist/core/registry/params/ticket.filter.list.json +46 -0
  167. package/dist/core/registry/params/ticket.finish.json +60 -0
  168. package/dist/core/registry/params/ticket.followers.update.json +60 -0
  169. package/dist/core/registry/params/ticket.list.json +74 -0
  170. package/dist/core/registry/params/ticket.log.json +39 -0
  171. package/dist/core/registry/params/ticket.modify.json +74 -0
  172. package/dist/core/registry/params/ticket.new.detail.json +39 -0
  173. package/dist/core/registry/params/ticket.reminder.json +60 -0
  174. package/dist/core/registry/params/ticket.reopen.json +67 -0
  175. package/dist/core/registry/params/ticket.reply.json +60 -0
  176. package/dist/core/registry/params/ticket.search.json +116 -0
  177. package/dist/core/registry/params/ticket.template.fields.json +39 -0
  178. package/dist/core/registry/params/ticket.template.list.json +39 -0
  179. package/dist/core/registry/params/ticket.transfer.json +74 -0
  180. package/dist/core/registry/params/track.event.set.json +32 -0
  181. package/dist/core/registry/params/wecom.robot.switch.json +43 -0
  182. package/dist/core/registry/params.js +84 -0
  183. package/dist/core/registry/specs.json +2172 -0
  184. package/dist/core/registry/validate.json +11 -0
  185. package/dist/core/registry/validation-overrides.js +98 -0
  186. package/dist/core/sanitize.js +24 -0
  187. package/dist/core/sign.js +21 -0
  188. package/dist/core/time.js +194 -0
  189. package/dist/core/validate.js +140 -0
  190. package/dist/output.js +263 -0
  191. package/dist/postinstall.js +178 -0
  192. package/dist/query/errors.js +395 -0
  193. package/dist/query/mask.js +368 -0
  194. package/dist/query/metric-catalog.js +85 -0
  195. package/dist/query/sandbox.js +544 -0
  196. package/dist/query/table-query.js +297 -0
  197. package/dist/query/time-shape.js +44 -0
  198. package/dist/schedule/install.js +377 -0
  199. package/dist/skill/check.js +429 -0
  200. package/dist/skill/detect.js +336 -0
  201. package/dist/skill/install.js +1202 -0
  202. package/dist/skill/paths.js +343 -0
  203. package/dist/skill/qiyu/SKILL.md +86 -0
  204. package/dist/skill/qiyu/errors.md +55 -0
  205. package/dist/skill/qiyu/forbidden.md +52 -0
  206. package/dist/skill/qiyu/metrics.md +65 -0
  207. package/dist/skill/qiyu/protocols.md +55 -0
  208. package/dist/skill/qiyu/setup.md +50 -0
  209. package/dist/skill/refs.js +379 -0
  210. package/dist/store/config.js +137 -0
  211. package/dist/store/duckdb.js +321 -0
  212. package/dist/store/index.js +18 -0
  213. package/dist/store/retry.js +36 -0
  214. package/dist/store/schema.js +419 -0
  215. package/dist/store/types.js +4 -0
  216. package/dist/sync/day.js +8 -0
  217. package/dist/sync/engine.js +818 -0
  218. package/dist/sync/rate-gate.js +95 -0
  219. package/dist/sync/registry.js +22 -0
  220. package/dist/sync/state.js +114 -0
  221. package/dist/sync/tasks/dim.js +186 -0
  222. package/dist/sync/tasks/knowledge.js +252 -0
  223. package/dist/sync/tasks/pace.js +66 -0
  224. package/dist/sync/tasks/pipeline.js +321 -0
  225. package/dist/sync/tasks/reports.js +448 -0
  226. package/dist/sync/tasks/sessions.js +188 -0
  227. package/dist/sync/tasks/tickets.js +219 -0
  228. package/dist/sync/types.js +1 -0
  229. package/dist/sync/windowing.js +56 -0
  230. package/package.json +52 -4
@@ -0,0 +1,863 @@
1
+ // src/commands/skill.ts —— F 子项目对用户的正式门面:`qiyu skill install/check/where`。
2
+ //
3
+ // 分层豁免(brief 第 6 条):本文件是全仓**唯一**允许 import `skill/` 的 commands 文件 ——
4
+ // 它是 skill 子系统的门面;其余 commands 文件与 core/store/query/sync 一律不得 import
5
+ // `skill/`(Task 14 的分层测试钉住)。
6
+ //
7
+ // 三个子命令的分工(设计稿 D2/D3):
8
+ // · install —— 调 `installSkill` 复制正文 + 建 agent 链接。`--dry-run` 只算计划、不写盘;
9
+ // `--link` 的值是 agent 名(不是路径),点名但目录不存在时**不创建目录**,
10
+ // 只进 warnings(spec D1)。
11
+ // · check —— 默认校验**包内那份**(CI 可跑,不依赖 `~/.agents/skills` 存在);
12
+ // `--installed` 校验已安装那份;`--compare` 两份都校验并报告差异。
13
+ // 有违规 → `ok(...)` 之后返回 1(与 `sync verify` 同一写法)。
14
+ // · where —— 纯只读:报告实体路径与各 agent 链接状态,**只报告、不修复、不删除**
15
+ // (spec D2)。要修复就让用户重跑 `qiyu skill install`。
16
+ //
17
+ // 实体定位统一为 `--dir` > `QIYU_SKILL_DIR` > `npm_config_qiyu_skill_dir` > `defaultEntityDir(resolveHome())`
18
+ // (唯一实现在 `skill/detect.ts` 的 `resolveEntityDirSources`,G3 审查 C3);
19
+ // home 一律经 `resolveHome()`(见该函数注释:测试用 `QIYU_HOME_FOR_TEST` 注入,绝不读写真实 `~`)。
20
+ //
21
+ // `skill where` 的逐 agent 兜异常(brief 硬要求):`linkState` 对自指/成环链接抛 ELOOP,
22
+ // `agentSkillDirs` 在 `~/.claude` 是文件时抛 ENOTDIR(Task 7 实测)。一个坏链接不能让
23
+ // 整条排查命令崩掉——每个 agent 的探测各自 try/catch,异常如实写进该 agent 的
24
+ // `state: 'unknown'` 与 `error`,其余照常报告。`agentSkillDirs` 本身是**整体抛出**的
25
+ // (paths.ts 在第一个坏路径就抛),所以它失败时退化为逐个已知 agent 探测,坏的那个
26
+ // 记 unknown,好的照常——否则「其余照常报告」在 ENOTDIR 下就落空了。
27
+ import { lstatSync, statSync } from 'node:fs';
28
+ import { homedir } from 'node:os';
29
+ import { join } from 'node:path';
30
+ import { describeArgs, fail, ok, setPretty, setSkillWarning, usageFail } from '../output.js';
31
+ import { PACKAGE_VERSION, SKILL_CONTRACT_VERSION } from '../core/edition.js';
32
+ import { ERROR_KINDS } from '../core/errors.js';
33
+ import { allEndpoints } from '../core/registry/index.js';
34
+ import { TABLES } from '../store/schema.js';
35
+ import { REPORT_TABLES } from '../query/metric-catalog.js';
36
+ import { SYNC_TASKS } from '../sync/registry.js';
37
+ import { COMMAND_TREE } from './tree.js';
38
+ import { prettyAfterSubcommand } from './spec-types.js';
39
+ import { skillFlagSpecs } from './skill-specs.js';
40
+ import { checkSkillDir } from '../skill/check.js';
41
+ import { contentHash, installSkill, planInstall } from '../skill/install.js';
42
+ import { entityUndeterminedNote, npmRelativeBase, resetSkillDetectionCache, resolveEntityDirSources, resolveSkillSourceDir, } from '../skill/detect.js';
43
+ import { AGENT_SKILL_SUBDIRS, agentSkillDirs, agentSkillSubdir, LINK_NAME, linkState, } from '../skill/paths.js';
44
+ /**
45
+ * 已知 agent 名(`--link` 的合法取值)。从 paths.ts 的 `AGENT_SKILL_SUBDIRS` 派生,
46
+ * 不再本地镜像:`AgentDir['name']` 是类型层的唯一事实源,paths.ts 的
47
+ * `Record<AgentDir['name'], string>` 保证那里覆盖全部成员(新增 agent 时编译失败)。
48
+ */
49
+ const KNOWN_AGENTS = AGENT_SKILL_SUBDIRS.map((a) => a.name);
50
+ const SKILL_USAGE = `用法:qiyu skill <子命令> [参数]
51
+
52
+ 子命令:
53
+ skill install [--dir <path>] [--link <agent>]... [--no-link] [--force] [--dry-run]
54
+ 安装 skill 正文到实体目录,并链接到已存在的 agent 目录
55
+ skill check [--installed [--dir <path>] | --compare [--dir <path>]]
56
+ 校验 skill 正文引用与 CLI 契约是否一致(有违规退出码 1;
57
+ --compare 下内容不一致、已安装那份不可用同样算失败)
58
+ skill where [--dir <path>]
59
+ 报告实体目录与各 agent 链接状态(只读,不修复;
60
+ 实体路径无法判定时 exists=null,链接无法判定时
61
+ state=unknown(带 error)——都不是「不存在」)
62
+
63
+ 实体目录定位:--dir > QIYU_SKILL_DIR > npm_config_qiyu_skill_dir(postinstall 的安装
64
+ 通道,含大小写/连字符归一)> ~/.agents/skills/qiyu
65
+ (相对路径一律按当前目录解析成绝对路径)
66
+ --link 取值:claude-code、codex(可重复)。点名的 agent 目录不存在时不创建目录,只警告。
67
+ --dry-run 只输出将要做的动作,不写盘。
68
+
69
+ 出错时 stdout 是 {"ok":false,"error":{code,kind,retryable,message,hint?}}。
70
+ ⚠️ 请按 kind 分支,不要按 code —— code 只是个标签。
71
+
72
+ 退出码:0 成功 · 1 业务错误 · 2 用法错误 · 3 网络错误 · 4 需要 --yes
73
+ `;
74
+ /**
75
+ * 解析叶子命令参数。次序与既有命令一致:`--help`/`-h`/`--pretty` 永远收下
76
+ * (它们的裁决在 `prelude` 里按「未知/位置参数 → help → --pretty」进行),
77
+ * 其余 token 必须是本子命令声明的 flag 或值位。
78
+ *
79
+ * 值位拒绝空串与纯空白(`--dir ""` 会让后续 `mkdtemp` 在 cwd 里落暂存目录)——
80
+ * 缺值就是缺值,不能猜。
81
+ */
82
+ function parseFlags(argv, spec) {
83
+ const out = { values: new Map(), lists: new Map(), flags: new Set(), rest: [] };
84
+ for (let i = 0; i < argv.length; i++) {
85
+ const a = argv[i];
86
+ if (a === '--help' || a === '-h' || a === '--pretty') {
87
+ out.flags.add(a);
88
+ continue;
89
+ }
90
+ if (spec.value.includes(a) || spec.repeat.includes(a)) {
91
+ const v = argv[i + 1];
92
+ if (v === undefined || v.startsWith('--') || v.trim() === '') {
93
+ throw new Error(`${a} 缺少取值`);
94
+ }
95
+ if (spec.repeat.includes(a)) {
96
+ const list = out.lists.get(a) ?? [];
97
+ list.push(v);
98
+ out.lists.set(a, list);
99
+ }
100
+ else {
101
+ out.values.set(a, v);
102
+ }
103
+ i++;
104
+ continue;
105
+ }
106
+ if (spec.bool.includes(a)) {
107
+ out.flags.add(a);
108
+ continue;
109
+ }
110
+ if (a.startsWith('-'))
111
+ throw new Error(`未知参数:${a}`);
112
+ out.rest.push(a);
113
+ }
114
+ return out;
115
+ }
116
+ /**
117
+ * 叶子命令的公共裁决(与 `api list` / `sync` 同一条次序):
118
+ * 未知 flag 由 `parseFlags` 先拦;位置参数 → help → `--pretty`。
119
+ * 返回退出码表示已裁决完;返回 null 表示继续执行。
120
+ */
121
+ function prelude(parsed, sub) {
122
+ if (parsed.rest.length > 0) {
123
+ return usageFail(`未知参数:${describeArgs(parsed.rest)}。skill ${sub} 不接受位置参数`);
124
+ }
125
+ if (parsed.flags.has('--help') || parsed.flags.has('-h')) {
126
+ process.stdout.write(SKILL_USAGE);
127
+ return 0;
128
+ }
129
+ // G1:--pretty 已实现 —— 原拒绝点开启缩进输出(次序不变:位置参数 → help → pretty)。
130
+ if (parsed.flags.has('--pretty'))
131
+ setPretty(true);
132
+ return null;
133
+ }
134
+ /** 解析 + 公共裁决;失败时直接返回退出码。 */
135
+ function parseOrFail(argv, spec, sub) {
136
+ let parsed;
137
+ try {
138
+ parsed = parseFlags(argv, spec);
139
+ }
140
+ catch (e) {
141
+ return usageFail(e.message);
142
+ }
143
+ const code = prelude(parsed, sub);
144
+ return code ?? parsed;
145
+ }
146
+ /**
147
+ * 测试注入 home 的环境变量(D1)。**仅供测试注入**,不做路径校验——它只改变 skill
148
+ * 子系统的默认实体目录位置与 agent 目录探测根,**不读任何凭证**。
149
+ *
150
+ * ⚠️ 为什么需要它:`os.homedir()` 在 Windows 上读 `USERPROFILE`、POSIX 上读 `HOME`,
151
+ * 而测试原本只 stub `HOME` —— Windows 上跑测试会真的把 skill 写进用户 home。
152
+ * 用一个显式变量把「测试的 home」与平台环境变量解耦,测试因此不再依赖平台差异。
153
+ *
154
+ * 空串 / 纯空白按未设处理(与 `QIYU_SKILL_DIR` 同一条口径):否则测试里
155
+ * `vi.stubEnv('QIYU_HOME_FOR_TEST', '')` 会把默认实体目录算成相对路径。
156
+ */
157
+ export const HOME_FOR_TEST_ENV = 'QIYU_HOME_FOR_TEST';
158
+ /**
159
+ * skill 子系统在命令层使用的 home。优先级:`QIYU_HOME_FOR_TEST`(非空)?? `os.homedir()`。
160
+ *
161
+ * 收成一个函数的所有调用点都走它(install 的链接探测、where 的 agent 探测、启动探测的
162
+ * 默认实体位、默认实体目录):任何一处漏了,Windows 上就仍会碰真实 home(D1 的变异点)。
163
+ * `env` 可注入只为把「空串视为未设」这条纯规则测得不碰磁盘。
164
+ */
165
+ export function resolveHome(env = process.env) {
166
+ const injected = env[HOME_FOR_TEST_ENV]?.trim();
167
+ if (injected !== undefined && injected !== '')
168
+ return injected;
169
+ return homedir();
170
+ }
171
+ /**
172
+ * 实体定位:`--dir` > `QIYU_SKILL_DIR` > `npm_config_qiyu_skill_dir` > 默认位置。
173
+ *
174
+ * 第三条是 postinstall 的安装通道(spec C5:`npm i -g` 时唯一跨版本可用的自定义位置)。
175
+ * 不认它的话,用 postinstall 装到自定义目录的用户跑 `skill where` / `check --installed`
176
+ * 会对着默认路径报「未安装」,与漂移探测口径分叉(终审 I2 的连带面)。
177
+ *
178
+ * ⚠️ 这里**不再自己写一遍优先级**(G3 审查 C3):三份实现各自漂移过,现在统一调用
179
+ * `detect.resolveEntityDirSources`。相对路径按 `process.cwd()` 解析成绝对路径(C4)——
180
+ * 此前 `--dir rel` 原样返回,install 按进程 cwd 装而 where 按另一处 cwd 比,链接报 dangling。
181
+ * 命令层**不受测试门影响**(用户显式给的位置照常使用);测试门只作用于启动探测
182
+ * (`cli.ts` 的启动探测)与本层的「未确定」情形(见 `skill where` 的报告)。
183
+ *
184
+ * ⚠️ **基准为什么是 `process.cwd()` 而不是 `npmRelativeBase`(INIT_CWD ?? cwd)**:
185
+ * 本层解析的 `--dir` / `QIYU_SKILL_DIR` 都是用户在自己 shell 里敲的,天然以进程 cwd 为基准;
186
+ * 而 npm 生命周期里 `INIT_CWD` 是「用户敲 npm 的目录」,可能与本进程 cwd 不同。若本层也
187
+ * 吃 `INIT_CWD`,`npm test`(恒设 `INIT_CWD` = 仓库根)下任何 chdir 到临时目录的用例都会
188
+ * 被解析回仓库根——相对路径逃出临时 home,正是 C4 要防的那类事故。真实发行形态是 `npx`
189
+ * (cwd 与 INIT_CWD 相同),二者不产生分叉;`npm run` 里带相对 `npm_config_qiyu_skill_dir`
190
+ * 调用 qiyu 属于窄边界,见 G3 报告的「遗留边界」。
191
+ */
192
+ export function resolveEntity(flagDir) {
193
+ const resolved = resolveEntityDirSources({
194
+ flagDir,
195
+ env: process.env,
196
+ baseDir: process.cwd(),
197
+ // D1:默认实体位也以注入的 home 为根(否则 Windows 上无 --dir 的 install 仍写真实 home)。
198
+ home: resolveHome(),
199
+ // 命令层不受测试门影响:`skill where --dir X` 在测试里必须照常报告 X,
200
+ // 且它必须认 npm_config 这条 postinstall 通道(终审 I2)。
201
+ testGate: false,
202
+ });
203
+ if (!resolved.decided)
204
+ throw new Error('实体目录解析失败:既无显式来源也无默认位置');
205
+ return { dir: resolved.dir, source: resolved.source };
206
+ }
207
+ /**
208
+ * 启动探测(`cli.run()` 里那次)的同一条解析:门开着时返回目录,门关着时返回 undefined
209
+ * 并给出原因。`skill where` 用它解释「为什么这次没有未安装/已过期提示」(追加审查 [57]:
210
+ * 门不能静默)。
211
+ *
212
+ * npm 生命周期里 cwd 是包根,所以基准取 `INIT_CWD ?? cwd`(与 postinstall 同一条)。
213
+ */
214
+ function startupProbeStatus() {
215
+ const env = process.env;
216
+ const resolved = resolveEntityDirSources({
217
+ env,
218
+ baseDir: npmRelativeBase(env, () => process.cwd()),
219
+ home: resolveHome(),
220
+ });
221
+ if (resolved.decided)
222
+ return { dir: resolved.dir, note: undefined };
223
+ return { dir: undefined, note: entityUndeterminedNote(resolved, env) };
224
+ }
225
+ function isErrno(err, code) {
226
+ return typeof err === 'object' && err !== null && err.code === code;
227
+ }
228
+ function errMsg(err) {
229
+ return err instanceof Error ? err.message : String(err);
230
+ }
231
+ /**
232
+ * 探测 agent skills 目录(`install --link` 与 `where` 共用,审查 M4)。
233
+ *
234
+ * 正常路径用 `agentSkillDirs(home)`(只返回已存在的目录)。它**整体抛出**
235
+ * (`~/.claude` 是文件 → ENOTDIR;Task 7 实测)时退化为逐个已知 agent 探测:
236
+ * 坏的那个进 `broken`,好的照常返回——否则「点名 codex、但无关的 claude 坏了」
237
+ * 会让整条安装失败,而自动模式在同一环境下是成功的。
238
+ */
239
+ function probeAgentDirs(home) {
240
+ try {
241
+ return {
242
+ dirs: agentSkillDirs(home).map((a) => ({ name: a.name, dir: a.dir })),
243
+ broken: new Map(),
244
+ warnings: [],
245
+ };
246
+ }
247
+ catch (e) {
248
+ const warnings = [`枚举 agent skills 目录失败(${errMsg(e)}),改为逐个 agent 探测`];
249
+ const dirs = [];
250
+ const broken = new Map();
251
+ for (const name of KNOWN_AGENTS) {
252
+ const dir = join(home, agentSkillSubdir(name));
253
+ try {
254
+ lstatSync(dir);
255
+ dirs.push({ name, dir });
256
+ }
257
+ catch (err) {
258
+ if (isErrno(err, 'ENOENT'))
259
+ continue;
260
+ broken.set(name, errMsg(err));
261
+ }
262
+ }
263
+ return { dirs, broken, warnings };
264
+ }
265
+ }
266
+ /** 包内 skill 源目录缺失时的统一错误(安装包不完整,属于 CLI 自身缺陷)。 */
267
+ function sourceMissing() {
268
+ return fail({
269
+ code: 'internal', kind: 'internal', retryable: false,
270
+ // 源目录的解析规则是「与 skill/detect 模块同层」(发布态 dist/skill/qiyu、
271
+ // 源码态 src/skill/qiyu)——文案如实描述**检查位置**,不要写成「两个候选都不存在」。
272
+ message: '找不到包内 skill 源目录(与 skill/detect 同层的 qiyu/ 目录不存在;'
273
+ + '发布态应为 dist/skill/qiyu,源码态应为 src/skill/qiyu)',
274
+ hint: 'CLI 安装包可能不完整,请重装 qiyu-cli 后重试',
275
+ });
276
+ }
277
+ /**
278
+ * 「已安装的 skill 不存在」的业务错误(退出码 1,brief 明确要求)。
279
+ *
280
+ * ⚠️ kind 用 `unknown` 而不是新造一个:`ERROR_KINDS`(core/errors.ts)是错误 kind 的
281
+ * **单一事实源**,本任务不允许改它;`store_not_initialized` 会误导 Agent 去跑
282
+ * `qiyu store init`(那是数据库,不是 skill)。message 与 hint 已把动作说死,
283
+ * `unknown` 在 errors.md 里的语义是「按 message 判断」——这里 message 足够明确。
284
+ */
285
+ function notInstalled(entityDir, detail) {
286
+ return fail({
287
+ code: 'skill_not_installed', kind: 'unknown', retryable: false,
288
+ message: `skill 未安装到 ${entityDir}${detail !== undefined ? `(${detail})` : ''}`,
289
+ hint: '先运行:qiyu skill install(可用 --dir 指定实体目录)',
290
+ });
291
+ }
292
+ /** 读取 skill 目录失败(权限/目录结构异常):环境问题,按 message 给出可操作归因。 */
293
+ function checkFailed(entityDir, detail) {
294
+ return fail({
295
+ code: 'skill_check_failed', kind: 'unknown', retryable: false,
296
+ message: `读取 skill 目录失败:${entityDir}(${detail})`,
297
+ hint: '请检查目录权限;若目录里有名为 *.md 的子目录,请改成文件或移走',
298
+ });
299
+ }
300
+ /** 链接四态 → 安装会采取的动作(dry-run 输出用;与 install.ts 的分派表一致)。 */
301
+ function linkAction(state) {
302
+ switch (state) {
303
+ case 'ok': return 'keep';
304
+ case 'missing': return 'create';
305
+ case 'dangling': return 'rebuild';
306
+ case 'foreign': return 'skip';
307
+ case 'unknown': return 'unknown';
308
+ }
309
+ }
310
+ /** 安装计划 → dry-run 的 action/planned_status(与真实 install 的 status 一一对应)。 */
311
+ function planOutcome(plan) {
312
+ switch (plan.action) {
313
+ case 'write':
314
+ return plan.status === 'installed'
315
+ ? { action: 'install', status: 'installed' }
316
+ : { action: 'update', status: 'updated' };
317
+ case 'rewrite-manifest':
318
+ return { action: 'update', status: 'updated' };
319
+ case 'none':
320
+ return { action: 'skip', status: 'skipped' };
321
+ }
322
+ }
323
+ /**
324
+ * dry-run 的链接计划:只读探测,绝不建链、绝不建目录。
325
+ * `explicitTargets` 非 undefined 时只规划用户点名的 agent(与 installSkill 的
326
+ * `linkDirs` 语义一致);自动模式则与 installSkill 的 linkAgents **同一条退化**:
327
+ * 枚举整体失败时不规划任何链接(逐 agent 退化只用于显式 --link,审查 M4)。
328
+ */
329
+ function planLinks(home, entityDir, explicitTargets, noLink) {
330
+ if (noLink)
331
+ return { links: [], warnings: [] };
332
+ const warnings = [];
333
+ let targets;
334
+ if (explicitTargets !== undefined) {
335
+ targets = explicitTargets;
336
+ }
337
+ else {
338
+ // ⚠️ 自动模式必须与 installSkill 的 linkAgents 自动路径**同一条退化**(复审
339
+ // Minor):`~/.claude` 是文件时枚举整体抛 ENOTDIR,真实安装「本次不建链接」。
340
+ // 若这里改用逐 agent 退化,dry-run 会预告一批真实安装不会发生的链接。
341
+ try {
342
+ targets = agentSkillDirs(home).map((a) => ({ name: a.name, dir: a.dir }));
343
+ }
344
+ catch (e) {
345
+ return { links: [], warnings: [`探测 agent skills 目录失败(${errMsg(e)}),本次不建链接`] };
346
+ }
347
+ }
348
+ const links = [];
349
+ for (const t of targets) {
350
+ const linkPath = join(t.dir, LINK_NAME);
351
+ try {
352
+ const state = linkState(linkPath, entityDir);
353
+ links.push({ agent: t.name, path: linkPath, state, action: linkAction(state) });
354
+ }
355
+ catch (e) {
356
+ // ELOOP(自指/成环)等不落四态:如实记 unknown,不触碰。
357
+ links.push({ agent: t.name, path: linkPath, state: 'unknown', action: 'unknown', error: errMsg(e) });
358
+ warnings.push(`无法判定 ${t.name} 链接状态(${errMsg(e)}),安装时会跳过:${linkPath}`);
359
+ }
360
+ }
361
+ return { links, warnings };
362
+ }
363
+ async function skillInstall(argv) {
364
+ // flag 集从 `SKILL_SPECS` 派生(G3 审查 C1):解析器与 spec 同源,不再有第二份事实源。
365
+ const parsed = parseOrFail(argv, skillFlagSpecs('install'), 'install');
366
+ if (typeof parsed === 'number')
367
+ return parsed;
368
+ const linkNames = [...new Set(parsed.lists.get('--link') ?? [])];
369
+ const noLink = parsed.flags.has('--no-link');
370
+ const force = parsed.flags.has('--force');
371
+ const dryRun = parsed.flags.has('--dry-run');
372
+ // 边界 4(brief):互斥不猜「后者优先」。
373
+ if (linkNames.length > 0 && noLink) {
374
+ return usageFail('--link 与 --no-link 互斥:要么显式指定要链接的 agent,要么完全不建链接');
375
+ }
376
+ // 边界 1(brief):值必须是已知 agent 名,而不是路径。
377
+ const unknownAgents = linkNames.filter((n) => !KNOWN_AGENTS.includes(n));
378
+ if (unknownAgents.length > 0) {
379
+ return usageFail(`未知 agent:${describeArgs(unknownAgents)}。可用 agent:${KNOWN_AGENTS.join('、')}`);
380
+ }
381
+ // 校验过后才收窄成联合类型(校验前是用户输入,不能直接断言)。
382
+ const agentNames = linkNames;
383
+ const home = resolveHome();
384
+ const { dir: entityDir, source } = resolveEntity(parsed.values.get('--dir'));
385
+ const sourceDir = resolveSkillSourceDir();
386
+ if (sourceDir === undefined)
387
+ return sourceMissing();
388
+ const warnings = [];
389
+ // 边界 2(brief):用户显式点名的 agent 目录不存在 → 不创建目录(spec D1),
390
+ // 该 agent 进 warnings,其余照常安装。显式点名意味着**只**链这些 agent。
391
+ //
392
+ // 探测失败按 agent 粒度收敛(审查 M4):`agentSkillDirs` 因无关 agent(如
393
+ // `~/.claude` 是文件 → ENOTDIR)整体抛出时,退化为逐个已知 agent 探测——
394
+ // 点名 codex 就照常链 codex,坏的 claude 只进 warnings,不拖垮整条安装。
395
+ let explicitTargets;
396
+ if (!noLink && agentNames.length > 0) {
397
+ explicitTargets = [];
398
+ const probed = probeAgentDirs(home);
399
+ warnings.push(...probed.warnings);
400
+ for (const name of agentNames) {
401
+ const hit = probed.dirs.find((a) => a.name === name);
402
+ if (hit !== undefined) {
403
+ explicitTargets.push(hit);
404
+ continue;
405
+ }
406
+ const broken = probed.broken.get(name);
407
+ if (broken !== undefined) {
408
+ warnings.push(`${name} 的 skills 目录无法检查(${broken}),跳过`);
409
+ }
410
+ else {
411
+ warnings.push(`${name} 的 skills 目录不存在,跳过(不替用户创建目录)`);
412
+ }
413
+ }
414
+ }
415
+ // 边界 3(brief):未给 --link 且未给 --no-link → 交给 installSkill 自己探测。
416
+ const linkDirs = explicitTargets?.map((t) => t.dir);
417
+ if (dryRun) {
418
+ // ⚠️ 计划必须与真实安装**共用同一判定**(审查 I1):`planInstall` 是 installSkill
419
+ // 内部使用的同一个只读判定函数(比实体内容哈希 / 真空 / 清单落后),不是
420
+ // detectSkillState 的「包是否变过」。四种边界态(用户改正文、空实体、清单被删、
421
+ // 用户新增文件)都有「dry-run action == 真实 install status」的对照用例。
422
+ let plan;
423
+ try {
424
+ plan = planInstall({ entityDir, sourceDir, version: PACKAGE_VERSION, force });
425
+ }
426
+ catch (e) {
427
+ // 计划能预见到的失败(源不可用 / 实体被文件占用)与真实安装同样报错,
428
+ // 不谎报一个会成功的计划。
429
+ return fail({
430
+ code: 'skill_install_failed', kind: 'unknown', retryable: false,
431
+ message: `无法计算安装计划:${errMsg(e)}`,
432
+ hint: '请检查 --dir 目标路径与包内 skill 源目录的可读性;若 --dir 指向的是文件,请改成目录路径',
433
+ });
434
+ }
435
+ const outcome = planOutcome(plan);
436
+ warnings.push(...plan.warnings);
437
+ const planned = planLinks(home, entityDir, explicitTargets, noLink);
438
+ warnings.push(...planned.warnings);
439
+ return ok({
440
+ dry_run: true,
441
+ entity_dir: entityDir,
442
+ entity_source: source,
443
+ source_dir: sourceDir,
444
+ version: PACKAGE_VERSION,
445
+ action: outcome.action,
446
+ planned_status: outcome.status,
447
+ force,
448
+ no_link: noLink,
449
+ links: planned.links,
450
+ }, warnings.length > 0 ? { warnings } : undefined);
451
+ }
452
+ let result;
453
+ try {
454
+ result = await installSkill({
455
+ home, sourceDir, version: PACKAGE_VERSION, force, entityDir,
456
+ ...(linkDirs !== undefined ? { linkDirs } : {}),
457
+ noLink,
458
+ });
459
+ }
460
+ catch (e) {
461
+ // installSkill 只在「源目录不可用 / 实体被文件占用 / 暂存写入失败」三类抛错。
462
+ // kind 用 unknown:这三类都是环境或路径问题,说成 internal 等于谎称 CLI 有缺陷。
463
+ return fail({
464
+ code: 'skill_install_failed', kind: 'unknown', retryable: false,
465
+ message: `skill 安装失败:${errMsg(e)}`,
466
+ hint: '请检查 --dir 目标路径与 agent skills 目录的权限;若 --dir 指向的是文件,请改成目录路径;'
467
+ + '若错误码是 ENOTEMPTY/EEXIST,说明有另一个 qiyu skill install 正在并发安装,稍后重试即可',
468
+ });
469
+ }
470
+ // ⚠️ 安装成功必须清掉启动时探测出的「未安装/已过期」提示(Task 10 审查疑虑 2):
471
+ // cli.run() 在分派前探测、注入进程级提示;同一进程里安装成功后再输出,那条提示已经过时。
472
+ // 这里是**输出层**的残留,与探测缓存是两回事(D5),两个都要清:
473
+ // · setSkillWarning(undefined) —— 清掉已经注入进程的那句文本;
474
+ // · resetSkillDetectionCache() —— 让同进程内**下一次** cli.run() 重新探测。只清文本
475
+ // 不失效缓存的话,先 `--version`(absent)→ install → 再 `--version`,第三条仍会
476
+ // 命中旧的 absent 结论并再次报「skill 未安装」(D5 的实测顺序)。
477
+ setSkillWarning(undefined);
478
+ resetSkillDetectionCache();
479
+ const allWarnings = [...warnings, ...result.warnings];
480
+ // installSkill 对幂等命中返回 skipped 且**无警告**(一个字节都没写)。命令层补一句
481
+ // 「已存在」——brief 要求重复安装时 meta.warnings 能说明发生了什么,否则 Agent 只能
482
+ // 从 status 猜。内容不同的 skipped 自带 --force 警告,不重复。
483
+ if (result.status === 'skipped' && result.warnings.length === 0) {
484
+ allWarnings.push(`skill 已存在且内容一致,未做任何改动:${result.entityDir}`);
485
+ }
486
+ // ⚠️ 审查 [55] 的文案归 `install.ts` 的 `planInstall`(B 组已落地),**命令层不再改写**:
487
+ // 它现在区分两种失败并各给各的出口 ——
488
+ // · `listError`(目录列不出来,如实体目录 chmod 000):rename 进这个目录同样被拒,
489
+ // 如实说「即使 --force 也会以同样的错误失败,先修权限」;
490
+ // · `hashError`(某个文件读不出来):rename 覆盖需要的是**目录**写权限而不是该文件的
491
+ // 读权限,`--force` 确实能修好 —— 仍推荐 `--force`。
492
+ // 命令层此前(G3 单独落地时)把两者统一改写成「不可读,--force 也失败(不要用它试)」,
493
+ // 这在 `hashError` 分支上是**反向误导**(实测 `--force` 退 0、status=updated、文件已换入)。
494
+ // 两层各写一份文案必然漂移,这里删掉改写,只保留 install.ts 那唯一一处。
495
+ // ⚠️ installSkill 的显式 linkDirs 分支用 `agentSkillDirs(home)` 反查 agent 名;
496
+ // 该调用失败(如无关的 `~/.claude` 是文件 → ENOTDIR)时它静默退回「目录路径当
497
+ // agent 标识」。命令层手里有明确的点名映射,这里按链接路径回填可读的 agent 名
498
+ // (审查 M4:点名 codex 时输出也必须写 codex,而不是一串路径)。
499
+ const links = explicitTargets === undefined
500
+ ? result.links
501
+ : result.links.map((link) => {
502
+ const hit = explicitTargets.find((t) => join(t.dir, LINK_NAME) === link.path);
503
+ return hit === undefined ? link : { ...link, agent: hit.name };
504
+ });
505
+ return ok({
506
+ dry_run: false,
507
+ entity_dir: result.entityDir,
508
+ entity_source: source,
509
+ source_dir: sourceDir,
510
+ version: PACKAGE_VERSION,
511
+ status: result.status,
512
+ links,
513
+ }, allWarnings.length > 0 ? { warnings: allWarnings } : undefined);
514
+ }
515
+ // —— skill check ——
516
+ /**
517
+ * 校验上下文:命令树 / 表名 / 错误 kind / 位置参数取值域,全部从各自的权威位置取。
518
+ *
519
+ * 取值域闭集在这里组装而不是让 `skill/check.ts` 去 import:`skill/` 若要自己取
520
+ * `SYNC_TASKS` / `allEndpoints()` / `REPORT_TABLES`,就会把 sync 注册表乃至
521
+ * `core/registry/specs.json` 拉进它的依赖面(`skill check` 因此连带加载注册表)。
522
+ * 命令层本来就是组合根,各份闭集在这里并成一份注入。
523
+ *
524
+ * `domains` 的键是 `Domain` 联合类型(`Record<Domain, …>`):`Domain` 加一个成员而
525
+ * 不在这里补闭集,`tsc` 会直接报缺键——取值域不会悄悄少一份。
526
+ *
527
+ * ⚠️ `endpoint-ids`(全集)与 `callable-endpoint-ids`(`callable: true` 子集)是**两个**域
528
+ * (G3 审查 C2,各按命令的取值域引用):`api schema` 查形状,对不可调用的接口同样合法;
529
+ * `api call` 只能调 callable 的——给 `api call` 用全集会把一条运行时必然 exit 2 的
530
+ * 调用判成合法(假阴性),给 `api schema` 用 callable 子集会把合法的 schema 查询判成
531
+ * `unknown_positional`(假阳性)。两份闭集来自同一个 `allEndpoints()`,不会各抄一份。
532
+ *
533
+ * ⚠️ **惰性构造**(G3 追加审查 [20]):这份上下文只有 `skill check` 用得到,而
534
+ * `skill install` / `skill where` 与契约校验无关——值域闭集(154 条接口 id 等在内存里
535
+ * 现拼出来的数组)不该在模块初始化时就建好。改成首次用到才建、之后复用同一个对象。
536
+ * ⚠️ 如实说明边界:**模块图**没变——本文件仍静态 import `tree.js` 与各注册表
537
+ * (`findSpec` 与各闭集都来自它们)。要把「install/where 不加载命令图」做实,得把
538
+ * `cli.ts` 的分派改成动态 import;而 `cli.js` 本来就静态 import 全部 8 个命令模块
539
+ * (审查 [20] 复核实测:cli.js 子图 58 个模块 = skill.js 的 57 个 + cli.js 本身,
540
+ * diff 为空),对真实 CLI 用户是零收益。这条取舍已写进 G3 报告。
541
+ */
542
+ let checkContextCache;
543
+ /** 校验上下文(首次调用时构造,之后复用同一份——闭集是常量,语义与急切构造相同)。 */
544
+ function checkContext() {
545
+ if (checkContextCache === undefined) {
546
+ const endpoints = allEndpoints();
547
+ checkContextCache = {
548
+ tree: COMMAND_TREE,
549
+ tableNames: TABLES.map((t) => t.name),
550
+ errorKinds: ERROR_KINDS,
551
+ domains: {
552
+ tables: TABLES.map((t) => t.name),
553
+ 'report-tables': REPORT_TABLES,
554
+ 'task-ids': SYNC_TASKS.map((t) => t.id),
555
+ 'endpoint-ids': endpoints.map((e) => e.id),
556
+ 'callable-endpoint-ids': endpoints.filter((e) => e.callable).map((e) => e.id),
557
+ },
558
+ };
559
+ }
560
+ return checkContextCache;
561
+ }
562
+ /** `checkSkillDir` 不吞错(brief 第 2 条):命令层守卫,转成可读错误。 */
563
+ function runCheck(dir) {
564
+ try {
565
+ return { result: checkSkillDir(dir, checkContext()) };
566
+ }
567
+ catch (e) {
568
+ return { error: errMsg(e) };
569
+ }
570
+ }
571
+ /** check 的 meta:契约版本恒在(设计稿 D6);无法静态判定的条目进 warnings。 */
572
+ function checkMeta(warnings) {
573
+ return {
574
+ skill_contract_version: SKILL_CONTRACT_VERSION,
575
+ ...(warnings.length > 0 ? { warnings } : {}),
576
+ };
577
+ }
578
+ /** 单基准(包内 / 已安装)的报告与退出码。 */
579
+ function reportSingle(mode, dir, result) {
580
+ const code = ok({ mode, baseline: dir, violations: result.violations, unverifiable: result.warnings }, checkMeta(result.warnings.map((w) => w.detail)));
581
+ return result.violations.length > 0 ? 1 : code;
582
+ }
583
+ /** stat 一个路径:ENOENT → 不存在;其余错误如实带出(ENOTDIR/EACCES)。 */
584
+ function probeDir(dir) {
585
+ try {
586
+ return { exists: true, isDir: statSync(dir).isDirectory() };
587
+ }
588
+ catch (e) {
589
+ if (isErrno(e, 'ENOENT'))
590
+ return { exists: false, isDir: false };
591
+ return { exists: true, isDir: false, error: errMsg(e) };
592
+ }
593
+ }
594
+ function probeSkillDoc(dir) {
595
+ try {
596
+ return statSync(join(dir, 'SKILL.md')).isFile() ? { kind: 'present' } : { kind: 'missing' };
597
+ }
598
+ catch (e) {
599
+ // ENOENT:目录里确实没有 SKILL.md(真·未安装)。其余错误(EACCES/EPERM/ELOOP…)
600
+ // 是「读不了」,必须如实报环境问题,不能谎报成「没有」。
601
+ if (isErrno(e, 'ENOENT'))
602
+ return { kind: 'missing' };
603
+ return { kind: 'unreadable', error: errMsg(e) };
604
+ }
605
+ }
606
+ async function skillCheck(argv) {
607
+ const parsed = parseOrFail(argv, skillFlagSpecs('check'), 'check');
608
+ if (typeof parsed === 'number')
609
+ return parsed;
610
+ const wantInstalled = parsed.flags.has('--installed');
611
+ const wantCompare = parsed.flags.has('--compare');
612
+ if (wantInstalled && wantCompare) {
613
+ return usageFail('--installed 与 --compare 互斥:一次只能选一种校验基准');
614
+ }
615
+ const flagDir = parsed.values.get('--dir');
616
+ // 审查 M1:默认基准是**包内那份**,`--dir` 改不了它——静默忽略与仓库
617
+ // 「不静默吞参数」的口径不一致。`--dir` 只对已安装侧(--installed/--compare)有意义。
618
+ if (!wantInstalled && !wantCompare && flagDir !== undefined) {
619
+ return usageFail('--dir 只配合 --installed / --compare 使用:默认校验包内那份,不能用 --dir 改');
620
+ }
621
+ const { dir: entityDir, source } = resolveEntity(flagDir);
622
+ // —— 默认:包内那份(CI 可跑) ——
623
+ if (!wantInstalled && !wantCompare) {
624
+ const pkgDir = resolveSkillSourceDir();
625
+ if (pkgDir === undefined)
626
+ return sourceMissing();
627
+ const outcome = runCheck(pkgDir);
628
+ if ('error' in outcome)
629
+ return checkFailed(pkgDir, outcome.error);
630
+ return reportSingle('package', pkgDir, outcome.result);
631
+ }
632
+ // —— --installed:已安装那份 ——
633
+ if (wantInstalled) {
634
+ const probe = probeDir(entityDir);
635
+ if (!probe.exists)
636
+ return notInstalled(entityDir);
637
+ if (probe.error !== undefined)
638
+ return checkFailed(entityDir, probe.error);
639
+ if (!probe.isDir) {
640
+ return fail({
641
+ code: 'skill_not_installed', kind: 'unknown', retryable: false,
642
+ message: `已安装路径不是目录:${entityDir}`,
643
+ hint: '用 --dir 指向 skill 实体目录(默认 ~/.agents/skills/qiyu)',
644
+ });
645
+ }
646
+ // 审查 M2:空目录 / 零 SKILL.md 不是「已安装且通过」。
647
+ // 追加审查 [55]:读不了 ≠ 没有——不可读时走 checkFailed(环境异常),只有确实
648
+ // 没有 SKILL.md 才报「未安装」。变异「退回统一的 hasSkillDoc」→ 对应用例红。
649
+ const doc = probeSkillDoc(entityDir);
650
+ if (doc.kind === 'unreadable')
651
+ return checkFailed(entityDir, doc.error);
652
+ if (doc.kind === 'missing')
653
+ return notInstalled(entityDir, '目录里没有 SKILL.md');
654
+ const outcome = runCheck(entityDir);
655
+ if ('error' in outcome)
656
+ return checkFailed(entityDir, outcome.error);
657
+ return reportSingle('installed', entityDir, outcome.result);
658
+ }
659
+ // —— --compare:两份都比并报告差异 ——
660
+ const pkgDir = resolveSkillSourceDir();
661
+ if (pkgDir === undefined)
662
+ return sourceMissing();
663
+ const pkgOutcome = runCheck(pkgDir);
664
+ if ('error' in pkgOutcome)
665
+ return checkFailed(pkgDir, pkgOutcome.error);
666
+ const differences = [];
667
+ const installedData = { dir: entityDir, present: false };
668
+ let installedUnverifiable = [];
669
+ let installedViolations = 0;
670
+ let installedFailed = false;
671
+ const probe = probeDir(entityDir);
672
+ if (!probe.exists) {
673
+ differences.push(`已安装目录不存在:${entityDir}`);
674
+ installedFailed = true;
675
+ }
676
+ else if (probe.error !== undefined || !probe.isDir) {
677
+ const why = probe.error ?? '不是目录';
678
+ differences.push(`已安装路径不可用:${entityDir}(${why})`);
679
+ installedData.error = why;
680
+ installedFailed = true;
681
+ }
682
+ else {
683
+ // 追加审查 [55]:读不了 ≠ 没有 SKILL.md(同 `--installed` 的判据)。
684
+ const doc = probeSkillDoc(entityDir);
685
+ if (doc.kind === 'unreadable') {
686
+ differences.push(`已安装目录不可读:${entityDir}(${doc.error})`);
687
+ installedData.error = doc.error;
688
+ installedFailed = true;
689
+ }
690
+ else if (doc.kind === 'missing') {
691
+ // 审查 M2:`present` 与 `--installed` 的「已安装」判据必须一致——没有 SKILL.md
692
+ // 的目录不算一份可用的安装,不能判成 present=true + 零违规。
693
+ differences.push(`已安装目录缺少 SKILL.md:${entityDir}`);
694
+ installedData.error = '缺少 SKILL.md';
695
+ installedFailed = true;
696
+ }
697
+ else {
698
+ const outcome = runCheck(entityDir);
699
+ if ('error' in outcome) {
700
+ differences.push(`已安装目录读取失败:${outcome.error}`);
701
+ installedData.error = outcome.error;
702
+ installedFailed = true;
703
+ }
704
+ else {
705
+ installedViolations = outcome.result.violations.length;
706
+ installedUnverifiable = outcome.result.warnings;
707
+ installedData.present = true;
708
+ installedData.violations = outcome.result.violations;
709
+ installedData.unverifiable = outcome.result.warnings;
710
+ // 内容哈希与违规数:前者回答「两份正文是否一致」,后者回答「判定结果是否一致」。
711
+ try {
712
+ if (contentHash(pkgDir) !== contentHash(entityDir)) {
713
+ // 「正文内容不同」计入 bad:`--compare` 的存在意义就是发现「装过旧版、包升级
714
+ // 改了正文」(spec D2.1 的洞),而它在 CI 里唯一的信号就是退出码。同一
715
+ // `differences` 数组里的其它成因(目录不存在 / 缺 SKILL.md / 读取失败 / 哈希
716
+ // 比较失败)一律退 1,唯独内容漂移退 0 = 检测到了却不报(终审 I3)。
717
+ differences.push('包内与已安装的正文内容不同(content_hash 不一致)');
718
+ installedFailed = true;
719
+ }
720
+ }
721
+ catch (e) {
722
+ // 审查 M3:无法完成内容比较 = 无法完成比较,退出码必须为 1。
723
+ differences.push(`内容哈希比较失败:${errMsg(e)}`);
724
+ installedFailed = true;
725
+ }
726
+ if (installedViolations !== pkgOutcome.result.violations.length) {
727
+ differences.push(`违规数不同:包内 ${pkgOutcome.result.violations.length} 处,已安装 ${installedViolations} 处`);
728
+ }
729
+ }
730
+ }
731
+ }
732
+ const warnings = [
733
+ ...pkgOutcome.result.warnings.map((w) => `包内:${w.detail}`),
734
+ ...installedUnverifiable.map((w) => `已安装:${w.detail}`),
735
+ ];
736
+ const code = ok({
737
+ mode: 'compare',
738
+ entity_source: source,
739
+ package: {
740
+ dir: pkgDir,
741
+ violations: pkgOutcome.result.violations,
742
+ unverifiable: pkgOutcome.result.warnings,
743
+ },
744
+ installed: installedData,
745
+ differences,
746
+ }, checkMeta(warnings));
747
+ const bad = installedFailed
748
+ || pkgOutcome.result.violations.length > 0
749
+ || installedViolations > 0;
750
+ return bad ? 1 : code;
751
+ }
752
+ /**
753
+ * 逐 agent 探测链接状态。目录枚举走 `probeAgentDirs`(与 install 共用同一套
754
+ * ENOTDIR 退化逻辑,审查 M4);每个 agent 的 `linkState` 各自 try/catch:
755
+ * 自指/成环链接抛 ELOOP,一个坏链接不能让整条排查命令崩掉(brief 硬要求)。
756
+ *
757
+ * ⚠️ **按 KNOWN_AGENTS 逐个出条目,包括目录不存在的 agent**(规格 D2 / 验收 1:
758
+ * 「对每个 agent 报出 ok/dangling/foreign/missing 之一」)。此前只报告探测到的
759
+ * 目录,未装任何 agent 的机器上 links 是空数组——「没报告」不等于「状态是 missing」,
760
+ * 排查时看不出到底缺哪个。目录不存在 → state:'missing'(链接路径必然也不存在)。
761
+ */
762
+ function probeAgentLinks(home, entityDir) {
763
+ const links = [];
764
+ const probed = probeAgentDirs(home);
765
+ const warnings = [...probed.warnings];
766
+ const dirOf = new Map(probed.dirs.map((d) => [d.name, d.dir]));
767
+ for (const name of KNOWN_AGENTS) {
768
+ const dir = dirOf.get(name);
769
+ if (dir === undefined) {
770
+ const path = join(home, agentSkillSubdir(name), LINK_NAME);
771
+ const error = probed.broken.get(name);
772
+ if (error !== undefined) {
773
+ // 目录本身不可检查(如父级是文件 → ENOTDIR):如实记 unknown,不谎报 missing。
774
+ links.push({ agent: name, path, state: 'unknown', error });
775
+ warnings.push(`${name} 的 skills 目录无法检查(${error}):${join(home, agentSkillSubdir(name))}`);
776
+ }
777
+ else {
778
+ links.push({ agent: name, path, state: 'missing' });
779
+ }
780
+ continue;
781
+ }
782
+ const linkPath = join(dir, LINK_NAME);
783
+ try {
784
+ links.push({ agent: name, path: linkPath, state: linkState(linkPath, entityDir) });
785
+ }
786
+ catch (e) {
787
+ links.push({ agent: name, path: linkPath, state: 'unknown', error: errMsg(e) });
788
+ warnings.push(`${name} 的链接状态无法判定(${errMsg(e)}):${linkPath}`);
789
+ }
790
+ }
791
+ return { links, warnings };
792
+ }
793
+ async function skillWhere(argv) {
794
+ const parsed = parseOrFail(argv, skillFlagSpecs('where'), 'where');
795
+ if (typeof parsed === 'number')
796
+ return parsed;
797
+ const { dir: entityDir, source } = resolveEntity(parsed.values.get('--dir'));
798
+ const warnings = [];
799
+ // 启动探测的门是否在这台机器/这个进程上关掉了(追加审查 [57]):where 是排查命令,
800
+ // 它要说清「为什么别的命令没有 meta.warnings」。显式来源不经过门,此时不会有这条。
801
+ const probe = startupProbeStatus();
802
+ if (probe.note !== undefined)
803
+ warnings.push(probe.note);
804
+ // 实体状态:只读 stat;ENOENT 是「未安装」,其余异常如实记 unknown。
805
+ let entity;
806
+ try {
807
+ const st = statSync(entityDir);
808
+ entity = { path: entityDir, source, exists: true, state: st.isDirectory() ? 'ok' : 'not_a_directory' };
809
+ }
810
+ catch (e) {
811
+ if (isErrno(e, 'ENOENT')) {
812
+ entity = { path: entityDir, source, exists: false, state: 'missing' };
813
+ }
814
+ else {
815
+ // 审查 M6:ELOOP/EACCES 下我们**不知道**路径是否存在——`exists: false` 可能
816
+ // 是一句假话。用 null 表示「无法判定」,与 state:'unknown' 配套;见 SKILL_USAGE。
817
+ warnings.push(`实体路径无法检查(${errMsg(e)}):${entityDir}`);
818
+ entity = { path: entityDir, source, exists: null, state: 'unknown', error: errMsg(e) };
819
+ }
820
+ }
821
+ const probed = probeAgentLinks(resolveHome(), entityDir);
822
+ warnings.push(...probed.warnings);
823
+ return ok({ entity, links: probed.links }, warnings.length > 0 ? { warnings } : undefined);
824
+ }
825
+ // —— 分派 ——
826
+ export async function skillCommand(argv) {
827
+ setPretty(false); // G1:每条命令入口重置输出格式 —— 同一进程内多次 run(测试)不残留上一条命令的开关。
828
+ const [sub, ...rest] = argv;
829
+ // `--help` 不吞额外参数(与 cli.ts / auth.ts 同一条规则);`--pretty` 豁免。
830
+ if (sub === undefined || sub === '--help' || sub === '-h') {
831
+ if (sub === undefined) {
832
+ return usageFail('用法:qiyu skill <install|check|where> [参数](`qiyu skill --help` 查看全部)');
833
+ }
834
+ const extra = rest.filter((a) => a !== '--help' && a !== '-h' && a !== '--pretty');
835
+ if (extra.length > 0) {
836
+ return usageFail(`未知参数:${describeArgs(extra)}。--help 不接受额外参数`);
837
+ }
838
+ process.stdout.write(SKILL_USAGE);
839
+ return 0;
840
+ }
841
+ // G1:--pretty 是输出开关,必须写在具体子命令之后(`skill check --pretty`)。
842
+ if (sub === '--pretty') {
843
+ const unknown = rest.filter((a) => a.startsWith('-') && a !== '--pretty' && a !== '--help' && a !== '-h');
844
+ const positional = rest.filter((a) => !a.startsWith('-'));
845
+ const extra = [...unknown, ...positional];
846
+ if (extra.length > 0) {
847
+ return usageFail(`未知参数:${describeArgs(extra)}。--pretty 不接受额外参数`);
848
+ }
849
+ if (rest.includes('--help') || rest.includes('-h')) {
850
+ process.stdout.write(SKILL_USAGE);
851
+ return 0;
852
+ }
853
+ return usageFail(prettyAfterSubcommand('skill'));
854
+ }
855
+ if (sub !== 'install' && sub !== 'check' && sub !== 'where') {
856
+ return usageFail(`未知子命令:${describeArgs([sub])}\n可用子命令:install、check、where`);
857
+ }
858
+ if (sub === 'install')
859
+ return skillInstall(rest);
860
+ if (sub === 'check')
861
+ return skillCheck(rest);
862
+ return skillWhere(rest);
863
+ }