qiyu-cli 0.0.0-stage → 0.2.1

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 +467 -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 +908 -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 +28 -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 +371 -0
  201. package/dist/skill/install.js +1202 -0
  202. package/dist/skill/paths.js +343 -0
  203. package/dist/skill/qiyu/SKILL.md +92 -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,371 @@
1
+ // src/skill/detect.ts —— 安装态探测与首次运行提示(设计稿 D2.1)。
2
+ //
3
+ // 背景漏洞(spec D2.1):用户装过旧版 skill → 包升级改了命令 → 已安装的那份还在
4
+ // 教 Agent 用死命令,而没有任何东西报警。补法是**任何 `qiyu` 命令启动时做一次
5
+ // 零成本探测**(只读 `.qiyu-skill.json` 清单,不读全部正文),据结果往
6
+ // `meta.warnings` 加**一条**提示:
7
+ //
8
+ // · absent → 「skill 未安装到 <实体目录>;运行 `qiyu skill install`」;
9
+ // · stale → 三个成因三支文案(实现见 `skillWarning`):
10
+ // 版本不同 → 「与当前 CLI 版本不一致(安装于 <旧>,当前 <新>)」;
11
+ // 版本相同仅内容漂移 → 「内容与包内当前版本不一致(版本 <v>)」;
12
+ // 版本未知 → 「无法确认已安装 skill 的版本(安装清单缺失或损坏)」;
13
+ // 前两支以「运行 `qiyu skill install --force` 更新」收尾——内容与包内
14
+ // 不同,不带 `--force` 只会跳过;第三支推**不带 `--force`** 的
15
+ // `qiyu skill install`(正文与包内一致时它只补写清单);
16
+ // · current / unknown → 不提示(unknown = 判定不了,宁可闭嘴也不打扰)。
17
+ //
18
+ // **只提示、绝不改退出码、绝不改 data、绝不自动改文件**——自动覆盖用户可能改过的
19
+ // 正文是局部破坏(spec D2.1)。探测失败(权限、路径异常)静默归为 unknown,不影响
20
+ // 命令本身。
21
+ //
22
+ // 探测结果**按参数元组(entityDir + sourceDir + currentVersion 拼接)缓存在进程内**:
23
+ // 同参重复调用复用,不重复 stat;换参(如测试换 tmp 目录)重新探测。缓存键必须含
24
+ // 全部三个参数——测试在同进程内换 tmp 目录跑,只按实体目录做键就会命中错结果。
25
+ //
26
+ // 测试环境(`NODE_ENV === 'test'` 或 vitest 的 `VITEST=true`)的 `resolveEntityDirSources()`:
27
+ // 实体目录**不是**由 `--dir` / `QIYU_SKILL_DIR` 显式指定时返回 undefined、跳过真实路径
28
+ // 探测;`npm_config_qiyu_skill_dir` 排在测试门**之后**读取(G3 审查 [21]:宿主环境里的
29
+ // `npm_config_*` 不得泄进测试)。理由有二(全局约束 + brief Step 5):
30
+ // ① **测试绝不读写真实 `~`**——探测会 stat 用户 home 下的实体目录;
31
+ // ② **探测结果不得依赖开发者机器装没装过 skill**——否则同一份测试在本机装过的
32
+ // 人那里全量多出 meta.warnings、没装过的人不出现,`toEqual({...})` 断言两种
33
+ // 命运。修门(跳过探测)而不是放宽断言。
34
+ // 另有显式开关 `QIYU_DISABLE_SKILL_PROBE`(在 `resolveEntityDirSources` 的测试门里读);
35
+ // 被抑制时 `entityUndeterminedNote()` 给出可解释的文案——`skill where` 与 `--version` 的
36
+ // meta.warnings 都据此如实报告,不静默。
37
+ //
38
+ // 分层:`skill/` 叶子层,只 import `node:*`、`core/` 与 `skill/` 内部;`output.ts`
39
+ // **不得** import 本文件(Task 14 分层红线钉住)——提示文案经
40
+ // `output.setSkillWarning()` 注入,探测与输出解耦。
41
+ import { readFileSync, statSync } from 'node:fs';
42
+ import { homedir } from 'node:os';
43
+ import path from 'node:path';
44
+ import { fileURLToPath } from 'node:url';
45
+ import { contentHash, MANIFEST } from './install.js';
46
+ import { defaultEntityDir, readEnvByNormalizedKey } from './paths.js';
47
+ /**
48
+ * 读已安装正文的清单版本信息(`skill where` 用)。
49
+ *
50
+ * ⚠️ **为什么需要它**(2026-10-26 实测发现):`SKILL.md` 教 Agent
51
+ * 「用 `skill_contract_version` 判断手上的正文能否配这份 CLI」,但此前**没有任何命令
52
+ * 报出已安装那份的契约号** —— `qiyu --version` 给的是 CLI 自己的,`skill check
53
+ * --installed` 的 `meta.skill_contract_version` 同样是 CLI 自己的(容易被读成"已安装
54
+ * 那份的"),`skill where` 完全不报。于是那句承诺是**空的**:Agent 手上没有可比的数。
55
+ * 实测佐证:把已安装清单的 `skill_contract_version` 改成 99,上面三条命令的输出
56
+ * 一字不变、`meta.warnings` 也不出现任何提示。
57
+ *
58
+ * 返回 `null` 的情形与 `readManifestStrict` 一致(缺失/损坏/字段不全),另外
59
+ * **读不动**(EACCES 等)也归 `null` —— 本函数是排查命令的辅助,不该因为权限问题
60
+ * 让整条 `skill where` 失败;调用方据此报 `null`(= 无法判定),不编造。
61
+ *
62
+ * 契约号还要求是**非负整数**(2026-10-26 审查):`readManifestStrict` 只做类型检查
63
+ * (`typeof === 'number'`),`1.5` / `-3` 都能溜进来。那些值不可能是任何一版安装器
64
+ * 写出的契约号 —— 是一份**损坏**的清单,正确结论是「判定不了」(null),而不是拿它
65
+ * 去比出一个 `compatible:false`:后者会让 Agent 以为「正文版本旧了,重装即可」,
66
+ * 而真实状态是「清单坏了,重装前先确认没别的问题」。0 放行:合法判定归调用方,
67
+ * 本函数只管「这是不是一个像样的契约号」。
68
+ */
69
+ export function readInstalledManifestInfo(entityDir) {
70
+ try {
71
+ const m = readManifestStrict(entityDir);
72
+ if (m === null)
73
+ return null;
74
+ if (!Number.isInteger(m.skill_contract_version) || m.skill_contract_version < 0)
75
+ return null;
76
+ return { version: m.version, skillContractVersion: m.skill_contract_version };
77
+ }
78
+ catch {
79
+ return null;
80
+ }
81
+ }
82
+ // 进程内判定:同参只探测一次(spec D2.1 的「零成本」)。缓存**不会随文件系统变化自动
83
+ // 失效**,所以凡是「本进程刚改过实体目录」的路径都必须主动调 `resetSkillDetectionCache()`。
84
+ //
85
+ // ⚠️ 已知的生产形态是「CLI 每个命令一个新进程,缓存天然只活一次命令」,但 `cli.run()`
86
+ // 在同一进程里被多次调用是**真实存在的形态**(测试与嵌入式用法):先 `--version`(探测
87
+ // 出 absent 并缓存)、再 `skill install` 装好实体、再 `--version` —— 不失效的话第三条仍
88
+ // 报「skill 未安装」(2026-10-22 review G4 的 D5)。因此 `skill install` 成功路径显式
89
+ // 失效,`resetSkillDetectionCache()` 是**正式的生产入口**,不再只是测试开关。
90
+ const cache = new Map();
91
+ /**
92
+ * 纯探测:三个参数全部由调用方给(实体目录、包内 skill 源目录、当前 CLI 版本),
93
+ * 本函数不读 `process.env`、不猜路径。内部按参数元组缓存——一个进程内同一组参数
94
+ * 只探测一次(spec D2.1:零成本、不重复 stat)。
95
+ *
96
+ * 判定顺序:
97
+ * 1. 实体目录 stat:ENOENT → absent;存在但不是目录(路径被文件占用)→ unknown
98
+ * (不是「未安装」,也不能谎报 stale,宁可闭嘴);其余错误 → unknown;
99
+ * 2. 读清单:缺失、JSON 损坏、字段不全(类型不对)→ stale + installedVersion='unknown'
100
+ * (正文在而清单没了,最可能是旧版安装或手工清理,按「需要更新」提示是对的);
101
+ * 清单**读不动**(EACCES 等)则不是「缺失」,重抛进第 5 条 → unknown;
102
+ * 3. 版本不同 → stale(带清单里的版本);
103
+ * 4. 版本一致 → 比较清单 content_hash 与**包内**源目录的内容哈希(与安装同一套
104
+ * `contentHash` 算法,CRLF 归一化、排除清单自身):一致 → current,不同 → stale。
105
+ * 源码态下 PACKAGE_VERSION 恒为占位值,版本号区分不了包的新旧——哈希比较是
106
+ * 发现「包变了、装的那份没跟上」的唯一判据;
107
+ * 5. 以上任何一步抛错(EACCES、ELOOP……)→ unknown,**绝不向上抛**——探测失败
108
+ * 不允许影响命令本身。
109
+ */
110
+ export function detectSkillState(entityDir, sourceDir, currentVersion) {
111
+ // 键用 NUL 分隔(路径里不可能出现 NUL,杜绝 'a'+'bc' 与 'ab'+'c' 拼出同键)。
112
+ const key = `${entityDir}\u0000${sourceDir}\u0000${currentVersion}`;
113
+ const hit = cache.get(key);
114
+ if (hit !== undefined)
115
+ return hit;
116
+ const state = probe(entityDir, sourceDir, currentVersion);
117
+ cache.set(key, state);
118
+ return state;
119
+ }
120
+ /** 真正的探测逻辑(无缓存)。任何异常都收敛成 unknown。 */
121
+ function probe(entityDir, sourceDir, currentVersion) {
122
+ try {
123
+ // statSync 会顺着符号链接走——实体目录本身是指向别处的符号链接是合法安装
124
+ // 形态(用户可能把实体放在大盘/网盘上),按最终指向判定。
125
+ let isDir;
126
+ try {
127
+ isDir = statSync(entityDir).isDirectory();
128
+ }
129
+ catch (err) {
130
+ if (isErrno(err, 'ENOENT'))
131
+ return { kind: 'absent' };
132
+ throw err;
133
+ }
134
+ if (!isDir)
135
+ return { kind: 'unknown' }; // 路径被文件占用:不是未安装,也不能谎报 stale
136
+ // 只读清单、不读实体正文(spec D2.1 的「零成本」)。readManifestStrict 对
137
+ // 缺失/损坏/字段不全统一返回 null。
138
+ const manifest = readManifestStrict(entityDir);
139
+ if (manifest === null)
140
+ return { kind: 'stale', installedVersion: 'unknown' };
141
+ if (manifest.version !== currentVersion) {
142
+ return { kind: 'stale', installedVersion: manifest.version };
143
+ }
144
+ // 版本一致,再比内容哈希:清单记录的是「上次安装时的包内哈希」。
145
+ const sourceHash = contentHash(sourceDir);
146
+ return manifest.content_hash === sourceHash
147
+ ? { kind: 'current' }
148
+ : { kind: 'stale', installedVersion: manifest.version };
149
+ }
150
+ catch {
151
+ // contentHash 对源目录不可读会抛(Task 9 的 I4 只在安装路径上容错,detect
152
+ // 侧自己兜)。探测失败一律 unknown:宁可闭嘴也不打扰,绝不让提示搞挂命令。
153
+ return { kind: 'unknown' };
154
+ }
155
+ }
156
+ /**
157
+ * 读清单,要求四个核心字段(version / skill_contract_version / content_hash /
158
+ * installed_at)类型齐全才返回,否则 null。判据与 `install.ts` 的 `readManifestSafe`
159
+ * 一致,但**只读前四个字段、忽略 `files`**——那是 Task 9 为 --force 清理加的扩展,
160
+ * 探测不消费它;探测是只读旁路,也没有删除决策可被它污染。
161
+ *
162
+ * 错误分界(brief 判定矩阵的两条不同结论):
163
+ * · 文件不存在 / JSON 损坏 / 字段不全 → 返回 null(= stale,版本记 'unknown');
164
+ * · 文件**读不动**(EACCES 等,如实体目录 chmod 000)→ 原样重抛(= unknown)。
165
+ * 「清单没了」与「清单看不了」是两种安装态:前者能确定装过但内容不明,
166
+ * 后者连「装没装」都判定不了——按 brief,后者静默。
167
+ */
168
+ function readManifestStrict(entityDir) {
169
+ let text;
170
+ try {
171
+ text = readFileSync(path.join(entityDir, MANIFEST), 'utf8');
172
+ }
173
+ catch (err) {
174
+ if (isErrno(err, 'ENOENT'))
175
+ return null;
176
+ throw err;
177
+ }
178
+ try {
179
+ const raw = JSON.parse(text);
180
+ if (typeof raw.version === 'string'
181
+ && typeof raw.skill_contract_version === 'number'
182
+ && typeof raw.content_hash === 'string'
183
+ && typeof raw.installed_at === 'string') {
184
+ // 显式只取四个字段:files 即使是数组也不带出来(brief:忽略 files)。
185
+ return {
186
+ version: raw.version,
187
+ skill_contract_version: raw.skill_contract_version,
188
+ content_hash: raw.content_hash,
189
+ installed_at: raw.installed_at,
190
+ };
191
+ }
192
+ return null;
193
+ }
194
+ catch {
195
+ return null;
196
+ }
197
+ }
198
+ /**
199
+ * 把安装态翻译成一句 meta.warnings 文案。
200
+ *
201
+ * `ctx` 是 brief 签名之外的**可选**上下文(缺省时文案退化为不含路径/版本的通用
202
+ * 说法,单参调用与 brief 接口完全兼容):
203
+ * · entityDir —— absent 提示里点名实体位置;
204
+ * · currentVersion —— stale 提示里点名当前版本(调用方传 PACKAGE_VERSION)。
205
+ *
206
+ * current / unknown 返回 undefined(不提示)。文案必须**可执行**:告诉 Agent
207
+ * 下一条命令是什么(`qiyu skill install` / `--force`),而不是只说「不一致」。
208
+ */
209
+ export function skillWarning(state, ctx) {
210
+ if (state.kind === 'absent') {
211
+ const where = ctx?.entityDir !== undefined ? `到 ${ctx.entityDir}` : '';
212
+ return `skill 未安装${where};运行 \`qiyu skill install\` 安装`;
213
+ }
214
+ if (state.kind === 'stale') {
215
+ // 三种 stale 来源,文案必须各自准确——不能把「内容漂移」说成「版本不一致」:
216
+ // · 清单缺失/损坏 → 连安装版本都不可知;
217
+ // · 版本相同、仅内容哈希漂移 → 版本号相同,说「版本不一致」自相矛盾;
218
+ // · 版本不同 → 说清「安装于 X,当前 Y」。
219
+ if (state.installedVersion === 'unknown') {
220
+ // 清单缺失/损坏但正文与包内一致 → `planInstall` 返回 rewrite-manifest:不带
221
+ // `--force` 的 `qiyu skill install` 就只补写清单、一个正文字节不动(brief D7)。
222
+ // 推 `--force` 会让用户以为要覆盖正文——那是另一支(内容漂移/版本不一致)才需要。
223
+ return '无法确认已安装 skill 的版本(安装清单缺失或损坏);运行 `qiyu skill install` 更新';
224
+ }
225
+ if (ctx?.currentVersion !== undefined && state.installedVersion === ctx.currentVersion) {
226
+ return `已安装的 skill 内容与包内当前版本不一致(版本 ${state.installedVersion});运行 \`qiyu skill install --force\` 更新`;
227
+ }
228
+ const current = ctx?.currentVersion !== undefined ? `,当前 ${ctx.currentVersion}` : '';
229
+ return `已安装的 skill 与当前 CLI 版本不一致(安装于 ${state.installedVersion}${current});运行 \`qiyu skill install --force\` 更新`;
230
+ }
231
+ return undefined;
232
+ }
233
+ /**
234
+ * npm 相对路径的唯一基准(G3 审查 C3):`INIT_CWD ?? cwd`。
235
+ *
236
+ * npm 生命周期脚本的 cwd 是**包根**(`node_modules/qiyu-cli`),用户执行 install 的目录
237
+ * 是 `INIT_CWD`(spec C6:npm/pnpm/yarn/bun 唯一都提供的变量)。三处解析(postinstall、
238
+ * 命令层、启动探测)统一按这一条基准走,「装到哪里」与「去哪里找」因此是同一个目录——
239
+ * 此前 detect/commands 用 cwd、postinstall 用 INIT_CWD,相对路径下两者必然分叉。
240
+ *
241
+ * `cwd()` 由调用方注入(生产传 `() => process.cwd()`),本函数不直接读进程状态。
242
+ */
243
+ export function npmRelativeBase(env, cwd) {
244
+ const init = env.INIT_CWD?.trim();
245
+ if (init !== undefined && init !== '')
246
+ return init;
247
+ return cwd();
248
+ }
249
+ /** 显式关闭启动探测的环境变量(用户 / 嵌入式调用方可用)。 */
250
+ export const DISABLE_PROBE_ENV = 'QIYU_DISABLE_SKILL_PROBE';
251
+ /**
252
+ * 「进程像 Node 测试」——`NODE_ENV=test` **或** vitest 恒设的 `VITEST=true`。
253
+ *
254
+ * 两个都认的理由:只认 `NODE_ENV` 时,宿主把 `NODE_ENV` 改成别的值就能让本仓库的测试
255
+ * 去读宿主路径(审查 [21] 的同一类风险:`.npmrc` 里的 `qiyu-skill-dir` 经 `npm_config_*`
256
+ * 注入所有子进程);只认 `VITEST` 时,裸 `node --test` 之类的运行器又不受控。
257
+ * 两个都认 = 覆盖面最广、误伤最小。
258
+ */
259
+ export function looksLikeNodeTest(env) {
260
+ return env.NODE_ENV === 'test' || env.VITEST === 'true';
261
+ }
262
+ /**
263
+ * 实体目录解析——**全仓唯一实现**(G3 审查 C3/C4)。
264
+ *
265
+ * 优先顺序:`--dir` > `QIYU_SKILL_DIR` > **[测试门]** > `npm_config_qiyu_skill_dir` > 默认。
266
+ *
267
+ * **所有来源的相对路径一律按 `baseDir` 解析成绝对路径**(C4):此前 `--dir rel` 与
268
+ * `QIYU_SKILL_DIR=rel` 原样返回,`skill install` 按进程 cwd 装、`skill where` 按另一个
269
+ * cwd 比,链接状态因此报 dangling。绝对化之后三条通路对同一条相对写法得到同一个目录。
270
+ *
271
+ * **测试门**(追加审查 [21]/[57]):
272
+ * · `QIYU_DISABLE_SKILL_PROBE` 置真 → 关闭(**显式**开关:调用方主动要求不探测)。
273
+ * · 进程像 Node 测试(`NODE_ENV=test` / `VITEST=true`)→ 关闭**隐式**来源:
274
+ * `npm_config_qiyu_skill_dir` 与默认位置都不再读,返回 `decided: false` + 原因。
275
+ * 显式来源(`--dir` / `QIYU_SKILL_DIR`)在门之前,照常生效——测试正是靠它注入临时目录。
276
+ * 理由有二:测试绝不读写真实 `~`(全局硬约束);宿主 `.npmrc` 里的 `qiyu-skill-dir`
277
+ * 会经 `npm_config_*` 注入**所有**子进程,不得泄进测试、把漂移提示写进模块级
278
+ * `pendingSkillWarning` 污染同文件后续断言(审查 [21] 实测 4 条红)。
279
+ *
280
+ * ⚠️ 与审查 [57] 的偏差(如实记录,不静默):[57] 要求「`NODE_ENV=test` 本身不再作为
281
+ * 关闭条件,只认显式开关」。本仓库**没有 vitest setup 文件**,且大量用例直接依赖
282
+ * 「`NODE_ENV=test` → 探测被门挡掉」这条既有语义(`tests/skill/detect.test.ts`、
283
+ * `tests/cli.test.ts` 各有用例逐条钉住),改成纯显式开关是一次全量测试改造,超出 G3 的
284
+ * 授权范围。按 brief 允许的第二条路走:门保留,但**留下可解释痕迹**——
285
+ * `entityUndeterminedNote()` 给出「为什么没定位到实体目录」的文案,`skill where` 如实报告,
286
+ * 且显式开关 `QIYU_DISABLE_SKILL_PROBE` 始终可用。
287
+ *
288
+ * 本函数**纯字符串**,不碰磁盘;`home` 只用于默认位置(`defaultEntityDir(home)`),
289
+ * 显式来源不经过 home——因此绝不会把相对路径解析成真实 home 下的路径。
290
+ *
291
+ * 三个调用方(`commands/skill.ts` 的 `resolveEntity`、`cli.ts` 的启动探测、`postinstall.ts`)
292
+ * 都走这里;加第四种来源时只改这一处。
293
+ */
294
+ export function resolveEntityDirSources(opts) {
295
+ const base = opts.baseDir ?? process.cwd();
296
+ const resolve = (raw, source) => ({
297
+ dir: path.resolve(base, raw),
298
+ source,
299
+ decided: true,
300
+ });
301
+ const flagDir = opts.flagDir?.trim();
302
+ if (flagDir !== undefined && flagDir !== '')
303
+ return resolve(flagDir, '--dir');
304
+ const explicit = opts.env.QIYU_SKILL_DIR?.trim();
305
+ if (explicit !== undefined && explicit !== '')
306
+ return resolve(explicit, 'QIYU_SKILL_DIR');
307
+ if (opts.testGate !== false) {
308
+ if (readEnvByNormalizedKey(opts.env, DISABLE_PROBE_ENV) !== undefined) {
309
+ return { dir: undefined, source: undefined, decided: false, reason: 'env' };
310
+ }
311
+ if (looksLikeNodeTest(opts.env)) {
312
+ return { dir: undefined, source: undefined, decided: false, reason: 'node-test' };
313
+ }
314
+ }
315
+ const fromNpm = readEnvByNormalizedKey(opts.env, 'npm_config_qiyu_skill_dir');
316
+ if (fromNpm !== undefined)
317
+ return resolve(fromNpm, 'npm_config_qiyu_skill_dir');
318
+ return resolve(defaultEntityDir(opts.home ?? homedir()), 'default');
319
+ }
320
+ /** 实体未确定时给用户看的一句话(已确定返回 undefined)。 */
321
+ export function entityUndeterminedNote(resolution, env = process.env) {
322
+ if (resolution.decided)
323
+ return undefined;
324
+ if (resolution.reason === 'env') {
325
+ return `skill 实体目录未确定:探测已被 ${DISABLE_PROBE_ENV} 显式关闭;需要时显式给出 --dir 或 QIYU_SKILL_DIR`;
326
+ }
327
+ return 'skill 实体目录未确定:当前进程像 Node 测试(NODE_ENV='
328
+ + `${env.NODE_ENV ?? ''},VITEST=${env.VITEST ?? ''}),且没有显式给出 --dir 或 QIYU_SKILL_DIR`
329
+ + '——不读宿主 npm_config_qiyu_skill_dir、也不碰真实 home。'
330
+ + '要定位实体请显式给出 --dir 或 QIYU_SKILL_DIR';
331
+ }
332
+ /**
333
+ * 包内 skill 源目录解析:**与本模块同层**的 `qiyu/` 目录。
334
+ *
335
+ * 本文件在源码态是 `src/skill/detect.ts`、发布态是 `dist/skill/detect.js` ——
336
+ * 两种形态下正文都在同层的 `qiyu/`(构建期由 `copy-assets.mjs` 复制进
337
+ * `dist/skill/qiyu/`)。因此不需要在包根下猜路径。
338
+ *
339
+ * ⚠️ **不能先查 `<包根>/dist/skill/qiyu`**(CodeRabbit 审查):仓库的 `prepare` 挂在
340
+ * `npm run build` 上,任何 `npm install` / `npm ci` 都会产出 `dist/`。先查 dist 会让
341
+ * 源码态(vitest / tsx / 本地开发)读到**构建期的旧副本**而不是刚改的 `src/` 正文:
342
+ * `skill check` 对旧文本报零违规、启动探测哈希到旧值、`skill install` 装出旧副本。
343
+ * 同层目录不存在(如被裁剪的运行环境)返回 undefined **不抛**——探测是旁路,
344
+ * 源找不到就整个静默跳过。
345
+ */
346
+ export function resolveSkillSourceDir() {
347
+ const dir = path.join(path.dirname(fileURLToPath(import.meta.url)), 'qiyu');
348
+ return isRealDirectory(dir) ? dir : undefined;
349
+ }
350
+ /** 路径存在且是目录(顺符号链接);其余一律 false,不抛。 */
351
+ function isRealDirectory(p) {
352
+ try {
353
+ return statSync(p).isDirectory();
354
+ }
355
+ catch {
356
+ return false;
357
+ }
358
+ }
359
+ /**
360
+ * 清进程内探测缓存。
361
+ *
362
+ * **生产入口**(D5):`skill install` 成功后会改变实体目录内容,同进程内后续的
363
+ * `cli.run()` 必须重新探测,否则 `meta.warnings` 仍报「skill 未安装」(缓存按参数元组
364
+ * 命中旧结论)。测试同样用它隔离用例(换 tmp 目录装好实体后不调用就会命中旧结果)。
365
+ */
366
+ export function resetSkillDetectionCache() {
367
+ cache.clear();
368
+ }
369
+ function isErrno(err, code) {
370
+ return typeof err === 'object' && err !== null && err.code === code;
371
+ }