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,1202 @@
1
+ // src/skill/install.ts —— `qiyu skill install` 的核心:把包内 skill 正文复制到实体目录、
2
+ // 按链接四态分派建立 agent 链接、写安装清单 `.qiyu-skill.json`。本文件是整个 skill
3
+ // 子项目里**唯一会写用户 home 目录**的代码,行为原则只有一条:**绝不静默覆盖用户改动**。
4
+ //
5
+ // 写入安全性(审查 C1/C2/I1 的落地形态——暂存 + 校验 + 逐文件 rename 换入):
6
+ // · 先暂存:正文与清单先复制进暂存目录 `<entity>.tmp-XXXXXX`(`mkdtempSync`
7
+ // 生成),复制完做哈希校验。暂存阶段任何失败都清掉暂存并抛错,实体一个字节
8
+ // 不变——不存在「删了旧文件之后复制才失败」的中间态。
9
+ // · 暂存位与实体**同设备**:暂存目录落在实体目录**真实落点**的父目录
10
+ // (`realpath(entityDir)` 的 dirname)。实体目录本身可能是指向网盘/大盘的
11
+ // 符号链接(detect 明确认可这种形态),按字面路径建暂存会落在 home 所在卷
12
+ // 上,换入时跨卷 EXDEV、每个文件都写失败却报「已更新」(2026-10-22 审查 B2
13
+ // 实测)。设备判断万一仍不一致时,`renameSync` 捕获 EXDEV 降级为
14
+ // 「复制 → 删源」并**如实警告**。
15
+ // · 后换入:暂存成功后才动实体,逐文件 `rename` 换入:目标是普通文件 → 原子替换
16
+ // (POSIX rename 语义,没有先删后写的窗口);缺失 → 换入;符号链接/目录/设备
17
+ // → 一律不写、如实警告。rename 会替换符号链接本身、copy 会**写穿**符号链接
18
+ // (2026-10-21 审查 WT1/WT2/WT3 实测),所以实体里与包内同名的任何非普通文件
19
+ // 都按「用户占用」处理。父目录链同样逐级验证——目录符号链接会让 rename 写进
20
+ // 实体之外(同样的写穿,换了个入口)。
21
+ // · 清单最后换入:中途失败时实体里还是旧清单,重跑 --force 即收敛(已换入的文件
22
+ // 会被再次原子替换,幂等)。
23
+ //
24
+ // 决策表:
25
+ // · 实体不存在 → 暂存后一次性 rename 换入,status='installed';
26
+ // · 实体「真空」(除根部清单外无任何条目;符号链接/子目录都算用户内容,审查 C1)
27
+ // → 没有用户内容可保护,换入,status='installed';
28
+ // · 正文哈希一致、清单一致 → status='skipped'(幂等,一个字节不写);
29
+ // · 正文哈希一致、清单落后/损坏 → 只重写清单(清单损坏视为落后,不视为用户改动,
30
+ // 审查 M2),status='updated';
31
+ // · 哈希不同或**无法计算**(EACCES 等,审查 I4)、无 --force → 什么都不写,
32
+ // status='skipped' + 警告提 --force;
33
+ // · 同上但有 --force → 暂存 → 换入 → 清理「上一版有、本版没有」的受管文件
34
+ // (审查 I2 采纳的更优方案:以上一版清单界定,而不是删一切包外文件;清单不可
35
+ // 识别则不清理、只警告;用户新增内容一律保留并警告),status='updated'。
36
+ // · **status 反映实际写盘结果**(2026-10-22 审查 B2):计划说要写、实际一个文件
37
+ // 都没写进去时,status 退回 'skipped' 并附明确警告——「报 updated 但实体零变化」
38
+ // 是对 Agent 的谎报。
39
+ //
40
+ // 链接按 `linkState` 四态分派(**不能直接 createSkillLink**:symlink 已存在时它抛
41
+ // EEXIST,2026-10-20 Task 7 实测):
42
+ // · ok → 不碰,记 state='ok';
43
+ // · missing → createSkillLink,成功后**复核** linkState,非 ok 不得报 ok
44
+ // (审查 B1:agent 目录本身是符号链接时,链接可能建到解析不到的地方),
45
+ // 记 'ok';
46
+ // · dangling → 先 unlink 再 createSkillLink(重建),成功记 'ok';重建会删掉
47
+ // 用户自己建的那条链接,**必须警告并记下原链接内容**(审查 Minor);
48
+ // · foreign → 不覆盖,记 'foreign' + 警告「已被占用」。
49
+ // 链接阶段任何异常——建链失败、linkState 抛 ELOOP(自指循环链接不落四态,Task 7
50
+ // 实测)、agent 目录不可检查(ENOTDIR/EACCES)——都收敛进 warnings,不让整个安装
51
+ // 失败。ELOOP 这类「判定不了」的路径按 foreign 处理:不触碰、只报告,最保守的归类。
52
+ //
53
+ // 内容比较用 `contentHash`:对目录下所有普通文件按**相对路径('/' 分隔)升序**,依次
54
+ // update「路径 + 换行 + 换行归一化后的内容」,SHA-256。定界符是必要的——没有它
55
+ // 「文件 a 内容 bc」与「文件 ab 内容 c」会拼出同一字节流(测试钉住)。`.qiyu-skill.json`
56
+ // 不参与哈希:否则 installed_at 每次安装都变,目标永远被判「内容不同」。源目录里的
57
+ // 符号链接既不复制也不参与哈希(复制与哈希同口径),因此不会造成幂等漂移。
58
+ //
59
+ // 分层:`skill/` 叶子层,只 import `node:*` 与 `core/`;不 import `commands/`。
60
+ // 测试通过 opts 注入 home,本文件不读真实环境。
61
+ import { createHash } from 'node:crypto';
62
+ import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
63
+ import path from 'node:path';
64
+ import { SKILL_CONTRACT_VERSION } from '../core/edition.js';
65
+ import { agentSkillDirs, agentsMissingSkillDir, createSkillLink, defaultEntityDir, LINK_NAME, linkState, linkTarget, MANIFEST, normalizeNewlines, } from './paths.js';
66
+ /**
67
+ * 安装清单文件名(D6:事实源已收敛到 `paths.ts`,这里 re-export 只为保持既有 import
68
+ * 路径兼容——`detect.ts` 与两个测试文件仍从本模块取它)。
69
+ */
70
+ export { MANIFEST };
71
+ /** 暂存目录前缀:`<entity>.tmp-`(`mkdtempSync` 在其后追加唯一随机后缀)。 */
72
+ const STAGING_SUFFIX = '.tmp-';
73
+ /**
74
+ * 暂存目录的**独占标记**(终审 F3):清理崩溃残留时只认带这个标记的目录。
75
+ *
76
+ * 为什么名字形状不够:`isStagingName` 只能判「前缀 + 长度」,用户自己的
77
+ * `qiyu.tmp-backup/` 恰好符合(`backup` 正好也是 6 位字母数字,收紧到 mkdtemp 的
78
+ * 后缀形态也挡不住)。而 `mkdtemp` 的随机后缀与用户名字无法从名字上区分,所以用
79
+ * 一个**只有本模块会写**的标记做判据。
80
+ *
81
+ * ⚠️ 标记是暂存目录**旁边**的一个文件(`<staging>.marker`),不是目录**里面**的文件
82
+ * (复审 N2):放在里面会有一条可达污染路径——源目录里若恰好有同名文件,`copyTree`
83
+ * 会把它带进来、覆盖正文,且首次安装换入前 `unlink` 会把那篇源文件**静默丢掉**,
84
+ * 实体从此永远与源哈希不一致。放到外面后标记彻底离开被拷贝/换入的树。
85
+ *
86
+ * 兼容性:旧版本留下的残留没有标记,从此不会被自动清理(宁留不删,与本轮 [59] 的
87
+ * 「宁留不删」同一取向)。暂存目录被 `finally` 清掉时标记一并删除。
88
+ */
89
+ const STAGING_MARKER_SUFFIX = '.marker';
90
+ /**
91
+ * 标记文件的**内容**:写入与孤儿清理的校验同源(复审 N1)。
92
+ * 它同时是「这个标记确实由本模块写下」的判据——只认名字会误删用户的同名普通文件。
93
+ */
94
+ export const STAGING_MARKER_CONTENT = 'qiyu skill install 的暂存目录;崩溃残留清理只认带此标记的目录\n';
95
+ /** 某个暂存目录对应的标记文件路径。 */
96
+ function stagingMarkerPath(staging) {
97
+ return `${staging}${STAGING_MARKER_SUFFIX}`;
98
+ }
99
+ /**
100
+ * 该路径是否是一个**由本模块写下**的标记(普通文件 + 内容逐字匹配)。
101
+ *
102
+ * 判据为什么是**内容**而不只是名字(复审 N1/W5):名字形状挡不住用户的
103
+ * `qiyu.tmp-*.marker`,只认名字会把用户数据当残留删掉;标记内容是本模块写死的固定串,
104
+ * 要误删得先伪造它 —— 比「名字撞上」难得多,所以不引入 pid 校验之类更重的机制。
105
+ *
106
+ * ⚠️ 先看大小再读(复审 N5):这条路径在 `postinstall` 的自动安装里也会跑,对任意同名
107
+ * 文件做整文件读取会让一个 300MB 的同名文件拖慢安装(实测 538ms / RSS +600MB)。
108
+ * 我们的标记只有一行,4096 字节的余量足够,超出即不是我们的。
109
+ */
110
+ function isOurMarker(p) {
111
+ try {
112
+ const st = lstatSync(p);
113
+ if (!st.isFile() || st.size > 4096)
114
+ return false;
115
+ return readFileSync(p, 'utf8') === STAGING_MARKER_CONTENT;
116
+ }
117
+ catch {
118
+ return false;
119
+ }
120
+ }
121
+ /**
122
+ * 判断一个目录项名是否是本模块的暂存目录名(`<实体名>.tmp-<随机后缀>`)。
123
+ * 消费方是安装开始时的残留清理——**名字形状只是第一道筛**,真正的判据是
124
+ * `stagingMarkerPath()` 指的旁挂标记(见其注释:用户目录可能恰好同名)。
125
+ */
126
+ function isStagingName(name, entityBase) {
127
+ return name.startsWith(`${entityBase}${STAGING_SUFFIX}`) && name.length > entityBase.length + STAGING_SUFFIX.length;
128
+ }
129
+ /**
130
+ * 对目录下所有普通文件算内容哈希:按相对路径('/' 分隔)升序,依次 update
131
+ * 「路径 + '\n' + 换行归一化后的内容」。
132
+ *
133
+ * 根部的 `.qiyu-skill.json` 不参与(清单是安装元数据,不是正文);子目录里同名的
134
+ * 文件仍参与——只有根部那份是清单。符号链接等非常规条目忽略(不受管内容)。
135
+ *
136
+ * 读取失败(EACCES/ELOOP 等)照常抛出:本函数只负责算,是否容错由调用方决定
137
+ * (安装路径在 I4 处显式捕获)。
138
+ */
139
+ export function contentHash(dir) {
140
+ const hash = createHash('sha256');
141
+ for (const rel of listFiles(dir)) {
142
+ // 路径后补 '\n' 定界:没有它,「文件 a + 内容 bc」与「文件 ab + 内容 c」
143
+ // 会拼出同一字节流(测试钉住)。文件名不含换行时定界无歧义。
144
+ hash.update(rel + '\n');
145
+ hash.update(normalizeNewlines(readFileSync(joinRel(dir, rel))));
146
+ }
147
+ return hash.digest('hex');
148
+ }
149
+ /** 递归列出目录下普通文件的相对路径('/' 分隔),升序排序;根部清单除外。 */
150
+ function listFiles(dir) {
151
+ const out = [];
152
+ const walk = (abs, rel) => {
153
+ for (const ent of readdirSync(abs, { withFileTypes: true })) {
154
+ const childRel = rel === '' ? ent.name : `${rel}/${ent.name}`;
155
+ if (rel === '' && ent.name === MANIFEST)
156
+ continue;
157
+ const kind = direntKind(abs, ent);
158
+ if (kind === 'dir')
159
+ walk(path.join(abs, ent.name), childRel);
160
+ else if (kind === 'file')
161
+ out.push(childRel);
162
+ // 'other'(符号链接等非常规条目):不属于受管正文,忽略(复制同样跳过,
163
+ // 两侧口径一致;源里的符号链接既不复制也不参与哈希,因此不会造成幂等漂移)。
164
+ }
165
+ };
166
+ walk(dir, '');
167
+ return out.sort();
168
+ }
169
+ /**
170
+ * `Dirent` 的类型归类。`withFileTypes` 在 d_type=`DT_UNKNOWN` 的文件系统
171
+ * (CIFS 挂载、部分 XFS 等)上给出的是「既不是文件也不是目录也不是符号链接」的
172
+ * 空壳,Node 不会替我们补 stat(2026-10-22 审查 #40)。此时补一次 `lstatSync`
173
+ * 再归类——否则非空的网络盘实体会被 `contentHash` 判成空集,与本地源永远不一致,
174
+ * 安装永远 skipped、「--force 也收敛不了」。
175
+ *
176
+ * 补 stat 之后仍不是普通文件/目录(FIFO、设备、符号链接)→ `'other'`,照旧忽略。
177
+ * 条目在 readdir 与 lstat 之间消失(ENOENT)→ 按 `'other'` 忽略(它已不在)。
178
+ */
179
+ function direntKind(abs, ent) {
180
+ if (ent.isDirectory())
181
+ return 'dir';
182
+ if (ent.isFile())
183
+ return 'file';
184
+ if (ent.isSymbolicLink())
185
+ return 'other';
186
+ try {
187
+ const st = lstatSync(path.join(abs, ent.name));
188
+ if (st.isDirectory())
189
+ return 'dir';
190
+ if (st.isFile())
191
+ return 'file';
192
+ }
193
+ catch (err) {
194
+ if (!isErrno(err, 'ENOENT'))
195
+ throw err;
196
+ }
197
+ return 'other';
198
+ }
199
+ /**
200
+ * 相对路径的**统一分隔符口径**(2026-10-22 审查 #37):清单 `files` 里的两种分隔符
201
+ * 都当分隔符处理。只认 `/` 时,Windows 上 `..\\..\\evil` 会被当成一整段普通名字
202
+ * 穿过字符串层与父链层,三层防线退化为只剩 realpath 一层。
203
+ */
204
+ const REL_SEP_RE = /[\\/]/;
205
+ /**
206
+ * 把相对路径('/' 或 '\\' 分隔)还原为平台路径。
207
+ *
208
+ * 两种分隔符都按分隔符处理(审查 #37):清单是外部数据,`..\\..\\evil` 这种
209
+ * Windows 写法必须在每一层防御里都被当成多段路径看待,否则前三层防线在 Windows
210
+ * 上形同虚设。我们自己写出的清单一律用 '/'(`listFiles` 的口径),所以这只影响
211
+ * 被篡改的清单——那种情况下「解析到实体目录内的另一个文件」正是我们要拦的。
212
+ */
213
+ function joinRel(root, rel) {
214
+ return path.join(root, ...rel.split(REL_SEP_RE));
215
+ }
216
+ /**
217
+ * `rel` 是否是一个**合法的、限定在实体目录内**的相对路径(审查 N1)。
218
+ *
219
+ * 清单 `files` 是**不可信输入**(用户可以编辑它、也可能被篡改),删除前必须当外部
220
+ * 数据校验:绝对路径、盘符、`..` 段、空段(`a//b`)、`.` 段一律拒绝。只做字符串
221
+ * 层面判定;符号链接父链造成的逃逸由 `verifyPlainParents` + `realpath` 复核兜住。
222
+ *
223
+ * 分隔符 `/` 与 `\` 都认(审查 #37):判定要与平台无关——一份在 Linux 上写的清单
224
+ * 被带到 Windows(或反过来)时,两者的含义必须一致、防线层数不缩水。
225
+ */
226
+ function isContainedRel(rel) {
227
+ if (rel === '' || path.isAbsolute(rel) || path.win32.isAbsolute(rel) || /^[A-Za-z]:/.test(rel))
228
+ return false;
229
+ return rel.split(REL_SEP_RE).every((part) => part !== '' && part !== '.' && part !== '..');
230
+ }
231
+ /**
232
+ * 只读版的父链验证:`rel` 的每个父组件在 `base` 下都必须存在且是**真实目录**
233
+ * (不是符号链接/文件)。与 `ensurePlainParents` 同一套判定,但**不创建**任何目录
234
+ * ——删除路径绝不能有副作用。任一父组件缺失(返回 'missing')或不是真实目录
235
+ * (返回 false)即不可删除。
236
+ */
237
+ function verifyPlainParents(base, rel) {
238
+ let cur = base;
239
+ for (const part of rel.split(REL_SEP_RE).slice(0, -1)) {
240
+ cur = path.join(cur, part);
241
+ let st;
242
+ try {
243
+ st = lstatSync(cur);
244
+ }
245
+ catch (err) {
246
+ if (isErrno(err, 'ENOENT'))
247
+ return 'missing';
248
+ return 'unsafe';
249
+ }
250
+ if (!st.isDirectory())
251
+ return 'unsafe';
252
+ }
253
+ return 'ok';
254
+ }
255
+ /**
256
+ * `abs` 解析后是否仍在 `entityDir` 之内(两边都过 `realpath`,消掉符号链接与 `..`)。
257
+ * 与父链验证互为双保险:父链判定的是「路径字符串逐级看是真实目录」,本函数判定
258
+ * 的是「真实文件系统上最终落在哪里」。任一环节不确定(realpath 抛错)都按不安全处理。
259
+ */
260
+ function isRealpathContained(entityDir, abs) {
261
+ try {
262
+ const root = realpathSync(entityDir).toString();
263
+ const target = realpathSync(abs).toString();
264
+ const prefix = root.endsWith(path.sep) ? root : root + path.sep;
265
+ return target === root || target.startsWith(prefix);
266
+ }
267
+ catch {
268
+ return false;
269
+ }
270
+ }
271
+ /**
272
+ * 实体目录是否「真空」:除根部清单外**没有任何条目**。符号链接、子目录都算内容——
273
+ * 用户把自己的笔记/私有片段以符号链接挂进实体目录是合理用法,不能当空目录删
274
+ * (审查 C1,2026-10-21 实测:只含符号链接的实体被判空,链接被无警告删除)。
275
+ */
276
+ function isVacuous(entityDir) {
277
+ return readdirSync(entityDir).filter((n) => n !== MANIFEST).length === 0;
278
+ }
279
+ /**
280
+ * 递归复制源目录到目标目录(不转换换行:复制是逐字节的)。根部 `.qiyu-skill.json`
281
+ * 不复制——清单由安装逻辑自己写,源里即使有一份也不该被带进目标。源里的符号链接
282
+ * 不复制(与 `listFiles` 同口径:不受管内容,不参与哈希)。
283
+ */
284
+ function copyTree(src, dest, isRoot = true) {
285
+ mkdirSync(dest, { recursive: true });
286
+ for (const ent of readdirSync(src, { withFileTypes: true })) {
287
+ if (isRoot && ent.name === MANIFEST)
288
+ continue;
289
+ const from = path.join(src, ent.name);
290
+ const to = path.join(dest, ent.name);
291
+ if (ent.isDirectory())
292
+ copyTree(from, to, false);
293
+ else if (ent.isFile())
294
+ copyFileSync(from, to);
295
+ }
296
+ }
297
+ /**
298
+ * 单个文件的内容哈希:换行归一化后的 sha256(与 `contentHash` 里的逐文件口径一致)。
299
+ * 清单用它记录「本工具当时写下的内容」,供下一次 --force 清理时核对(审查 #59)。
300
+ */
301
+ function fileHash(abs) {
302
+ return createHash('sha256').update(normalizeNewlines(readFileSync(abs))).digest('hex');
303
+ }
304
+ /**
305
+ * 写安装清单(覆盖)。`installed_at` 用 ISO 8601,便于人读与机器解析。
306
+ *
307
+ * `file_hashes`(审查 #59):与 `files` 一一对应的**逐文件内容哈希**。清单里的
308
+ * `files` 是「哪些文件是我们写的」的唯一依据,而它是一份可以被就地编辑的 JSON——
309
+ * 往 `files` 里追加一条用户自己的文件名,下一次 `--force` 就会把它当「上一版遗留」
310
+ * 删掉,且警告还说「移除了上一版安装的文件」(实测)。清理时改为只删「当前哈希与
311
+ * `file_hashes` 记录一致」的文件,其余一律保留并警告。
312
+ *
313
+ * ⚠️ 这不是完整性保护:`file_hashes` 与 `files` 在同一个文件里,能改 `files` 的
314
+ * 进程也能补一份对得上的哈希(本机没有密钥/签名可用)。它挡住的是两类**现实**场景:
315
+ * ① 备份恢复/同步工具/人工编辑让 `files` 多出条目(不会连哈希一起伪造);
316
+ * ② 用户在上一版之后改过那个文件(哈希必然不符)。
317
+ */
318
+ function writeManifest(dir, version, contentHashValue, files) {
319
+ const hashes = {};
320
+ for (const rel of files)
321
+ hashes[rel] = fileHash(joinRel(dir, rel));
322
+ const manifest = {
323
+ version,
324
+ skill_contract_version: SKILL_CONTRACT_VERSION,
325
+ content_hash: contentHashValue,
326
+ installed_at: new Date().toISOString(),
327
+ files,
328
+ file_hashes: hashes,
329
+ };
330
+ writeFileSync(path.join(dir, MANIFEST), JSON.stringify(manifest, null, 2) + '\n');
331
+ }
332
+ /**
333
+ * 读清单;缺失、JSON 损坏或字段不全都返回 null(安装逻辑据此判断「需要重写」)。
334
+ *
335
+ * 清单损坏/缺失一律**视为清单落后**(重写即可),不视为用户改动——它不是正文,
336
+ * 用户没有理由手工编辑它;把它当用户改动会让安装永远卡在 skipped(审查 M2)。
337
+ *
338
+ * `files` 是**不可信输入**(用户可编辑、也可能被篡改):解析时先过 `isContainedRel`,
339
+ * 非法条目(绝对路径 / 含 `..` / 空段)直接丢弃。非法条目意味着清单被动过手脚,
340
+ * 整份清单按「落后」处理(返回 null)比只丢几个条目更安全——否则一份被篡改的清单
341
+ * 仍会被当作「上一版的准确记录」,清理范围就建立在不可信数据上(审查 N1)。
342
+ *
343
+ * `file_hashes` 同样是不可信输入,但判定方向相反:**形状不对就整份丢字段**
344
+ * (`file_hashes` 为 undefined = 「无从核对」,清理时保守不删任何文件),不接受
345
+ * 部分采用——半份可用的哈希表比没有更容易让后续维护者误以为「已经核对过了」。
346
+ */
347
+ function readManifestSafe(entityDir) {
348
+ try {
349
+ const raw = JSON.parse(readFileSync(path.join(entityDir, MANIFEST), 'utf8'));
350
+ if (typeof raw.version === 'string'
351
+ && typeof raw.skill_contract_version === 'number'
352
+ && typeof raw.content_hash === 'string'
353
+ && typeof raw.installed_at === 'string') {
354
+ let files;
355
+ if (Array.isArray(raw.files)) {
356
+ if (!raw.files.every((f) => typeof f === 'string' && isContainedRel(f)))
357
+ return null;
358
+ files = raw.files;
359
+ }
360
+ let fileHashes;
361
+ if (raw.file_hashes !== undefined) {
362
+ if (!isStringRecord(raw.file_hashes))
363
+ return null;
364
+ fileHashes = raw.file_hashes;
365
+ }
366
+ return { ...raw, files, file_hashes: fileHashes };
367
+ }
368
+ return null;
369
+ }
370
+ catch {
371
+ return null;
372
+ }
373
+ }
374
+ /** `v` 是否是「键值都为字符串」的普通对象(数组/嵌套值一律拒绝)。 */
375
+ function isStringRecord(v) {
376
+ if (typeof v !== 'object' || v === null || Array.isArray(v))
377
+ return false;
378
+ return Object.values(v).every((x) => typeof x === 'string');
379
+ }
380
+ /** 判定路径是否存在且是目录;不存在或不是目录返回 false,其余错误照常抛。 */
381
+ function isDirectory(p) {
382
+ try {
383
+ return statSync(p).isDirectory();
384
+ }
385
+ catch (err) {
386
+ if (isErrno(err, 'ENOENT'))
387
+ return false;
388
+ throw err;
389
+ }
390
+ }
391
+ /** 实体目录根部是否存在清单文件(不论内容是否可读——存在就是「有上一版」)。 */
392
+ function manifestExists(entityDir) {
393
+ try {
394
+ lstatSync(path.join(entityDir, MANIFEST));
395
+ return true;
396
+ }
397
+ catch {
398
+ return false;
399
+ }
400
+ }
401
+ function isErrno(err, code) {
402
+ return typeof err === 'object' && err !== null && err.code === code;
403
+ }
404
+ function errMsg(err) {
405
+ return err instanceof Error ? err.message : String(err);
406
+ }
407
+ /**
408
+ * 保证 `rel` 的父目录链在 `base` 下都是**真实目录**(不是符号链接/文件)。
409
+ * 缺的目录建出来;遇到非目录返回 false——目录符号链接会让后续 rename 写进实体
410
+ * 之外(与 C2 同一类写穿,只是换了入口)。
411
+ */
412
+ function ensurePlainParents(base, rel, warnings) {
413
+ let cur = base;
414
+ for (const part of rel.split('/').slice(0, -1)) {
415
+ cur = path.join(cur, part);
416
+ let st;
417
+ try {
418
+ st = lstatSync(cur);
419
+ }
420
+ catch (err) {
421
+ if (isErrno(err, 'ENOENT')) {
422
+ mkdirSync(cur);
423
+ continue;
424
+ }
425
+ warnings.push(`检查目录 ${cur} 失败(${errMsg(err)}),未写入 ${rel}`);
426
+ return false;
427
+ }
428
+ if (!st.isDirectory()) {
429
+ warnings.push(`实体目录中 ${path.relative(base, cur)} 不是真实目录(符号链接/文件),未写入 ${rel}`);
430
+ return false;
431
+ }
432
+ }
433
+ return true;
434
+ }
435
+ /**
436
+ * 把暂存目录里的文件逐个换入实体。目标不存在 → 换入;目标是普通文件 →
437
+ * **原子替换**(POSIX rename 语义,没有先删后写的窗口);目标是符号链接/目录/设备
438
+ * → 一律不写并警告——`rename` 会替换链接本身、`copyFile` 会写穿链接(审查 C2
439
+ * WT1/WT2/WT3 实测),两种形态都会伤到用户数据,统一按「用户占用」处理。
440
+ *
441
+ * 单文件失败只警告,不中断(其余文件照常换入)。返回各计数;调用方据此决定要不要
442
+ * 换清单,以及 status 该报什么(审查 B2:**status 必须反映实际写盘结果**):
443
+ * · `complete`(写了本包全部文件)→ 换清单;
444
+ * · `written === 0` → 一个文件都没写进去,status 不得报 updated;
445
+ * · 0 < `written` < 总数 → 部分写入,如实警告。
446
+ *
447
+ * 换入方式见 `moveFile`:同设备时 rename,EXDEV 时降级为复制 + 删源并记一条警告。
448
+ */
449
+ function swapIn(staging, entityDir, rels, warnings) {
450
+ let written = 0;
451
+ for (const rel of rels) {
452
+ if (!ensurePlainParents(entityDir, rel, warnings))
453
+ continue;
454
+ const to = joinRel(entityDir, rel);
455
+ if (!isSafeWriteTarget(to, `目标 ${rel} `, warnings))
456
+ continue;
457
+ try {
458
+ moveFile(joinRel(staging, rel), to, warnings);
459
+ written++;
460
+ }
461
+ catch (err) {
462
+ warnings.push(`写入 ${rel} 失败(${errMsg(err)}):${to}`);
463
+ }
464
+ }
465
+ return { complete: written === rels.length, written, total: rels.length };
466
+ }
467
+ /**
468
+ * 把 `from` 换到 `to`:先 `renameSync`;遇到 `EXDEV`(跨设备)降级为
469
+ * 「`copyFileSync` 复制 → 删源」。
470
+ *
471
+ * EXDEV 的现实来源(2026-10-22 审查 B2 实测):「实体目录是指向网盘/大盘的符号
472
+ * 链接」是 detect 明确认可的安装形态,但暂存目录若建在**符号链接的字面父目录**
473
+ * 上,两者可能不在同一设备。暂存改落 `realpath(entityDir)` 的父目录已消除主因
474
+ * (见 `stagingBaseDir`),本降级是第二道保险——卷的挂载点与路径推断未必一致。
475
+ *
476
+ * 降级窗口的语义:`copyFileSync` 覆盖目标时先截断再写入,不再是原子替换——这是
477
+ * 跨设备时唯一可用的手段,但**必须说出来**(warning 记下受影响的文件):用户据此
478
+ * 知道这次更新不是原子的。用户内容仍受 `isSafeWriteTarget` + 父链验证保护。
479
+ */
480
+ function moveFile(from, to, warnings) {
481
+ try {
482
+ renameSync(from, to);
483
+ }
484
+ catch (err) {
485
+ if (!isErrno(err, 'EXDEV'))
486
+ throw err;
487
+ copyFileSync(from, to);
488
+ unlinkSync(from);
489
+ warnings.push(`暂存目录与实体不在同一设备(EXDEV),已降级为「复制 → 删除源」换入(非原子):${to}`);
490
+ }
491
+ }
492
+ /**
493
+ * 清理「上一版安装过、本版不再有」的受管文件(审查 I2 采纳的方案:以清单里的
494
+ * `files` 界定,而不是删一切包外文件)。用户新增的文件一律保留并警告;上一版
495
+ * 受管文件若已被用户换成符号链接/目录,也不动。
496
+ *
497
+ * 旧清单没有 `files`(本任务之前的安装)→ 无法识别上一版,**不删任何东西**,
498
+ * 只把包外文件列进警告。
499
+ *
500
+ * **内容核对层(审查 #59)**:`files` 只是一份可以被编辑的 JSON,「清单里写着它」
501
+ * 不等于「它是我们写的」。删除前还要对得上 `file_hashes` 里记录的哈希:
502
+ * · 有 `file_hashes`、且该条目的当前哈希与记录一致 → 是本工具写下的、未被改过,删除;
503
+ * · 有 `file_hashes`、但该条目没有记录 / 哈希不一致 → 不是本工具写的内容(清单被
504
+ * 篡改,或用户改过),保留并警告;
505
+ * · 旧清单没有 `file_hashes` → 无从核对,**不删**,只警告(宁留不删)。
506
+ * 这一层同样挡不住「连哈希一起伪造」——清单在实体目录里、与正文同权限,本机没有
507
+ * 密钥可用;它挡的是现实中的误伤来源(见 `writeManifest` 注释)。
508
+ */
509
+ function cleanupPreviousManaged(entityDir, prevFiles, prevHashes, newFiles, warnings) {
510
+ const keep = new Set(newFiles);
511
+ if (prevFiles === undefined) {
512
+ const extra = listFiles(entityDir).filter((f) => !keep.has(f));
513
+ if (extra.length > 0) {
514
+ warnings.push(`实体目录中存在不在包内的文件(无法确认是否为上一版遗留,均未删除):${extra.join('、')}`);
515
+ }
516
+ return;
517
+ }
518
+ const prev = new Set(prevFiles);
519
+ const removed = [];
520
+ const unverifiable = [];
521
+ for (const rel of prevFiles) {
522
+ if (keep.has(rel))
523
+ continue;
524
+ // —— 纵深防御(审查 N1):清单是外部数据,删除前逐层复核 ——
525
+ // ① 字符串层:必须是实体内的相对路径(readManifestSafe 已过滤,这里再拦一次)。
526
+ if (!isContainedRel(rel)) {
527
+ warnings.push(`清单 files 含非法路径(绝对路径或路径逃逸),拒绝删除:${rel}`);
528
+ continue;
529
+ }
530
+ const abs = joinRel(entityDir, rel);
531
+ // ② 父链层:lstat/unlink 的父组件会顺着符号链接解析——references 是指向个人
532
+ // 目录的链接时,unlink 会删到实体之外。父链必须全是真实目录;父链缺失说明
533
+ // 文件早已不存在,静默跳过。
534
+ const parents = verifyPlainParents(entityDir, rel);
535
+ if (parents === 'missing')
536
+ continue;
537
+ if (parents === 'unsafe') {
538
+ warnings.push(`上一版安装的 ${rel} 所在路径含符号链接或非目录组件,拒绝删除(可能指向实体之外)`);
539
+ continue;
540
+ }
541
+ let st;
542
+ try {
543
+ st = lstatSync(abs);
544
+ }
545
+ catch (err) {
546
+ if (isErrno(err, 'ENOENT') || isErrno(err, 'ENOTDIR'))
547
+ continue;
548
+ warnings.push(`检查 ${rel} 失败(${errMsg(err)}),未删除`);
549
+ continue;
550
+ }
551
+ if (!st.isFile()) {
552
+ warnings.push(`上一版安装的 ${rel} 已被用户替换为非普通文件,保留不动:${abs}`);
553
+ continue;
554
+ }
555
+ // ③ 终点层:解析后的真实位置必须仍在实体目录之内(与父链检查互为双保险)。
556
+ if (!isRealpathContained(entityDir, abs)) {
557
+ warnings.push(`上一版安装的 ${rel} 解析后不在实体目录内,拒绝删除:${abs}`);
558
+ continue;
559
+ }
560
+ // ④ 内容核对层(审查 #59):清单里写着「这是我们写的」还不够——还要对得上
561
+ // 清单记录的哈希。对不上(用户改过 / 清单被改过)→ 不删。
562
+ const recorded = prevHashes?.[rel];
563
+ if (recorded === undefined) {
564
+ unverifiable.push(rel);
565
+ continue;
566
+ }
567
+ let current;
568
+ try {
569
+ current = fileHash(abs);
570
+ }
571
+ catch (err) {
572
+ warnings.push(`读取上一版文件 ${rel} 计算哈希失败(${errMsg(err)}),未删除`);
573
+ continue;
574
+ }
575
+ if (current !== recorded) {
576
+ unverifiable.push(rel);
577
+ continue;
578
+ }
579
+ try {
580
+ unlinkSync(abs);
581
+ removed.push(rel);
582
+ }
583
+ catch (err) {
584
+ warnings.push(`删除上一版文件 ${rel} 失败(${errMsg(err)})`);
585
+ }
586
+ }
587
+ if (removed.length > 0) {
588
+ // 删除用户可见的文件必须说出来:--force 是「覆盖」授权,删除仍要如实报告。
589
+ warnings.push(`移除了上一版安装、本版不再包含的文件:${removed.join('、')}`);
590
+ }
591
+ if (unverifiable.length > 0) {
592
+ // 清单说它是我们写的、内容却对不上(用户改过,或清单被改过)——不删,并说明。
593
+ warnings.push(`以下文件在上一版清单中登记、但内容与记录不符(可能已被用户修改或清单被改动),已保留不动:${unverifiable.join('、')}`);
594
+ }
595
+ const extra = listFiles(entityDir).filter((f) => !keep.has(f) && !prev.has(f));
596
+ if (extra.length > 0) {
597
+ warnings.push(`保留了实体目录中不在包内的文件(可能是用户新增):${extra.join('、')}`);
598
+ }
599
+ }
600
+ /**
601
+ * 最终写入路径的安全门(审查 C2):缺失或普通文件 → 可写(rename 原子替换/覆盖);
602
+ * 符号链接/目录/设备 → 一律不写,警告并说明原因。`copyFile` 会写穿符号链接、
603
+ * `rename` 会替换链接本身——实体里与包内路径重合的任何非普通文件都按「用户占用」
604
+ * 处理,无论是否有 --force。
605
+ *
606
+ * 判定与文案拆成 `writeTargetWarning`:`planInstall` 需要**只读预判**清单是否可写
607
+ * (dry-run 与真实安装共用同一判据,Task 11 审查 I1),但预判时不能产生警告。
608
+ */
609
+ function writeTargetWarning(p, what) {
610
+ let st;
611
+ try {
612
+ st = lstatSync(p);
613
+ }
614
+ catch (err) {
615
+ if (isErrno(err, 'ENOENT'))
616
+ return null;
617
+ return `检查${what} ${p} 失败(${errMsg(err)}),未写入`;
618
+ }
619
+ if (!st.isFile()) {
620
+ return `${what}已被非普通文件占用(符号链接/目录等),不覆盖、保留用户内容:${p}`;
621
+ }
622
+ return null;
623
+ }
624
+ function isSafeWriteTarget(p, what, warnings) {
625
+ const warning = writeTargetWarning(p, what);
626
+ if (warning === null)
627
+ return true;
628
+ warnings.push(warning);
629
+ return false;
630
+ }
631
+ /**
632
+ * 确定要安装后的写盘路径(审查 I1/I3 的落地):先在实体旁的暂存目录完成
633
+ * 「复制 + 哈希校验 + 写清单」,全部成功之后才动实体——暂存阶段任何失败都清掉
634
+ * 暂存并抛错,实体一个字节不变;不存在「先删旧文件、复制才失败」的中间态。
635
+ *
636
+ * 暂存位用 `mkdtempSync`(`<entity>.tmp-XXXXXX`)而不是固定 pid 后缀:防御性
637
+ * `rmSync` 面对同名**真实目录**(用户恰好放了这么个目录)时会把里面的用户文件
638
+ * 一起递归删掉(复审 N2 实测);`mkdtemp` 保证路径必然是本次新建的空目录,
639
+ * 「同名目录」这个面从根上消失。同父目录 ⇒ 同设备,rename 必然可行。
640
+ *
641
+ * 首次安装(实体不存在):整个暂存目录一次性 `rename` 换入(同设备,原子)。
642
+ * 覆盖安装:逐文件 `rename` 换入(每个文件原子),清单**最后**换入——中途失败时
643
+ * 实体里还是旧清单,重跑 --force 即收敛;清单换入失败也只警告(正文已就位,
644
+ * 下次安装会再补清单)。
645
+ */
646
+ function writeInstalled(entityDir, sourceDir, sourceFiles, version, sourceHash, warnings, prev) {
647
+ // 清单此刻是否存在(复审 Minor:「保持上一版」的措辞只在真有上一版清单时成立;
648
+ // 首次安装中途被占用根本没写过清单,措辞要区分开)。必须在动实体**之前**判断。
649
+ const hadPrevManifest = manifestExists(entityDir);
650
+ // 暂存位与实体同设备(审查 B2):落在实体**真实落点**的父目录下。实体目录本身
651
+ // 不存在时 realpath 会失败——退回「逐级向上找最近一个存在的祖先再 realpath」,
652
+ // 这样即便父目录本身是符号链接,也能落在那条链的真实卷上。
653
+ const stagingBase = stagingBaseDir(entityDir);
654
+ let staging;
655
+ try {
656
+ mkdirSync(stagingBase, { recursive: true });
657
+ // 崩溃残留(审查 Minor #4):SIGKILL 打断的安装会留下 `qiyu.tmp-XXXXXX`,
658
+ // 里面还带着正文。在**新建本次暂存位之前**清理同前缀的旧目录——本次的暂存位
659
+ // 尚未创建,不存在「误删自己」的窗口。只认 `<实体名>.tmp-` 这个形状。
660
+ cleanupStaleStaging(stagingBase, path.basename(entityDir), warnings);
661
+ staging = mkdtempSync(path.join(stagingBase, `${path.basename(entityDir)}${STAGING_SUFFIX}`));
662
+ copyTree(sourceDir, staging);
663
+ if (contentHash(staging) !== sourceHash) {
664
+ throw new Error('暂存内容与源不一致(防御性校验失败)');
665
+ }
666
+ // 标记写在暂存目录**旁边**(不是里面):它因此不参与 contentHash、不会被
667
+ // copyTree 的源撞名覆盖、也不会被换入实体(复审 N2)。崩溃残留(含正文、尚未
668
+ // 换入)带标记,下次安装可安全清理(终审 F3)。
669
+ writeFileSync(stagingMarkerPath(staging), STAGING_MARKER_CONTENT);
670
+ writeManifest(staging, version, sourceHash, sourceFiles);
671
+ }
672
+ catch (err) {
673
+ if (staging !== undefined) {
674
+ rmSync(staging, { recursive: true, force: true });
675
+ rmSync(stagingMarkerPath(staging), { force: true });
676
+ }
677
+ throw new Error(`安装中断:暂存目录写入失败(${errMsg(err)}),实体目录未被改动:${entityDir}`);
678
+ }
679
+ try {
680
+ let entityExists;
681
+ try {
682
+ lstatSync(entityDir);
683
+ entityExists = true;
684
+ }
685
+ catch (err) {
686
+ if (!isErrno(err, 'ENOENT'))
687
+ throw err;
688
+ entityExists = false;
689
+ }
690
+ if (!entityExists) {
691
+ mkdirSync(path.dirname(entityDir), { recursive: true });
692
+ try {
693
+ renameSync(staging, entityDir);
694
+ return { complete: true, written: sourceFiles.length, total: sourceFiles.length, manifestKept: false };
695
+ }
696
+ catch (err) {
697
+ // 并发(gap 8):另一进程在「判实体不存在」与「rename 换入」之间把实体目录
698
+ // 建了出来(且非空),rename 不能覆盖非空目录 → ENOTEMPTY。这不是失败——
699
+ // 实体现在可能已经是对的;由调用方按**实际状态**决算(`concurrent: true`)。
700
+ if (!isErrno(err, 'ENOTEMPTY') && !isErrno(err, 'EEXIST'))
701
+ throw err;
702
+ warnings.push('检测到另一个 qiyu skill install 正在并发安装(首次换入撞 ENOTEMPTY),按实体实际状态收敛');
703
+ return { complete: false, written: 0, total: sourceFiles.length, manifestKept: false, concurrent: true };
704
+ }
705
+ }
706
+ const swap = swapIn(staging, entityDir, sourceFiles, warnings);
707
+ // 清理只在「确实写进了东西」时跑:一个文件都没写进去(例如整盘只读、每次
708
+ // rename 都 EXDEV 且复制也失败)时删上一版遗留只会让实体更空,且与那份
709
+ // 「什么都没更新」的真实结果不相称。
710
+ if (swap.written > 0) {
711
+ cleanupPreviousManaged(entityDir, prev?.files, prev?.hashes, sourceFiles, warnings);
712
+ }
713
+ if (!swap.complete) {
714
+ // 有文件没能换入(被占用/失败):清单不换入,如实反映「实际装上的仍是旧内容」。
715
+ // 下一次安装因此会报内容不同并提示 --force;用户清掉占用后重跑即可收敛。
716
+ const detail = swap.written === 0
717
+ ? `本次一个文件都没有写进去(${swap.total} 个文件全部失败)`
718
+ : `本次未能完整写入(${swap.total} 个文件中成功 ${swap.written} 个)`;
719
+ warnings.push(hadPrevManifest
720
+ ? `${detail},安装清单保持上一版`
721
+ : `${detail},安装清单未写入;清掉占用后重跑安装即可补全`);
722
+ return { complete: false, written: swap.written, total: swap.total, manifestKept: hadPrevManifest };
723
+ }
724
+ if (isSafeWriteTarget(path.join(entityDir, MANIFEST), '清单', warnings)) {
725
+ moveFile(path.join(staging, MANIFEST), path.join(entityDir, MANIFEST), warnings);
726
+ }
727
+ return { complete: true, written: swap.written, total: swap.total, manifestKept: false };
728
+ }
729
+ finally {
730
+ rmSync(staging, { recursive: true, force: true });
731
+ // 旁挂标记也要一并清掉,否则每次安装都会在 skills 目录里留一个垃圾文件。
732
+ rmSync(stagingMarkerPath(staging), { force: true });
733
+ }
734
+ }
735
+ /**
736
+ * 暂存目录的落点:实体目录**真实落点**的父目录,保证暂存与实体在同一设备上
737
+ * (审查 B2——`renameSync` 跨设备抛 EXDEV,而旧实现假定「同父目录 ⇒ 同设备」,
738
+ * 对「实体目录是指向网盘/大盘的符号链接」这种 detect 明确认可的形态并不成立)。
739
+ *
740
+ * 实体目录本身可能还不存在(首次安装):逐级向上找到最近一个存在的祖先,
741
+ * 对它 realpath 后再拼回缺失的那几段。
742
+ */
743
+ function stagingBaseDir(entityDir) {
744
+ const abs = path.resolve(entityDir);
745
+ const parts = abs.split(path.sep);
746
+ for (let i = parts.length; i > 0; i--) {
747
+ const candidate = parts.slice(0, i).join(path.sep) || path.sep;
748
+ try {
749
+ const real = realpathSync(candidate).toString();
750
+ return path.dirname(path.join(real, ...parts.slice(i)));
751
+ }
752
+ catch {
753
+ continue;
754
+ }
755
+ }
756
+ return path.dirname(abs);
757
+ }
758
+ /**
759
+ * 清理 SIGKILL 残留的暂存目录(审查 Minor #4):只删 `stagingBase` 下名字形如
760
+ * `<entityBase>.tmp-XXXXXX` 的**目录**。删不掉只警告,不让安装失败。
761
+ *
762
+ * ⚠️ **不能无差别删**(2026-10-22 并发实测):两个 install 同时跑时,B 会把 A 正在写的
763
+ * 暂存目录当成「上次中断的残留」删掉,于是 A 的 `copyTree` 撞 `ENOENT`、或哈希校验报
764
+ * 「暂存内容与源不一致」——6 个并发进程 3 轮跑出 13 次失败,其中一半是这种**自伤**
765
+ * (变异验证:禁用本函数后 `copyfile ENOENT` 与「暂存内容与源不一致」全部消失,只剩
766
+ * 真正的 ENOTEMPTY 竞态)。
767
+ *
768
+ * 判据改为**按年龄**:只有最后修改时间早于 `STALE_STAGING_MIN_AGE_MS` 的才算残留。
769
+ * 活着的并发安装会持续往里写文件,mtime 始终是新的,因此不会被误删;而 SIGKILL 留下的
770
+ * 那份不会再被任何进程触碰,过了阈值就必然可清。
771
+ *
772
+ * 为什么不用 pid 文件 / 锁:需要额外写一个「谁在用」的契约,而进程崩溃时那个文件本身
773
+ * 也可能残留,判定问题只是被挪了一层。年龄阈值是同一个判断的最简形式。
774
+ */
775
+ const STALE_STAGING_MIN_AGE_MS = 10 * 60_000;
776
+ function cleanupStaleStaging(stagingBase, entityBase, warnings, now = Date.now()) {
777
+ let entries;
778
+ try {
779
+ entries = readdirSync(stagingBase, { withFileTypes: true });
780
+ }
781
+ catch {
782
+ return; // 目录还不存在等:本次新建时自然会建出来。
783
+ }
784
+ for (const ent of entries) {
785
+ // 旁挂标记本身也满足 `isStagingName` 的前缀(`<staging>.marker`)—— 复审 W1:
786
+ // 不排除它就会在清理后对它再 lstat,得到一条假的「清理残留暂存目录失败(ENOENT)」。
787
+ if (ent.name.endsWith(STAGING_MARKER_SUFFIX))
788
+ continue;
789
+ if (!isStagingName(ent.name, entityBase))
790
+ continue;
791
+ const abs = path.join(stagingBase, ent.name);
792
+ try {
793
+ const st = lstatSync(abs);
794
+ if (!st.isDirectory())
795
+ continue;
796
+ // 独占标记(终审 F3):没有标记的同名目录**不是**本模块的暂存位——可能是用户
797
+ // 自己建的 `qiyu.tmp-backup/`。宁留不删,也不给一条「已清理残留」的错误归因。
798
+ // 标记是**旁挂文件**(复审 N2),所以用户目录里就算有个同名文件也不算数。
799
+ if (!isOurMarker(stagingMarkerPath(abs)))
800
+ continue;
801
+ // 年轻 = 可能有别的 install 正在写它。留到下次再清(`--force` 也救不了误删)。
802
+ if (now - st.mtimeMs < STALE_STAGING_MIN_AGE_MS)
803
+ continue;
804
+ rmSync(abs, { recursive: true, force: true });
805
+ rmSync(stagingMarkerPath(abs), { force: true });
806
+ warnings.push(`清理了上次安装中断时残留的暂存目录:${abs}`);
807
+ }
808
+ catch (err) {
809
+ warnings.push(`清理残留暂存目录失败(${errMsg(err)}):${abs}`);
810
+ }
811
+ }
812
+ // 孤儿标记(复审 W2):SIGKILL 若落在 `finally` 的两条 rmSync 之间,目录已删、标记
813
+ // 还在。这类标记没有对应目录,永远清不掉,会永久留在 skills 目录里。按年龄一并清。
814
+ //
815
+ // ⚠️ 判据是**内容**而不是名字(复审 N1):只看名字的话,用户自己的普通文件
816
+ // `<实体>.tmp-*.marker` 会被静默删除(且不给任何警告)。标记内容是本模块写死的固定串,
817
+ // 它才是「这确实是我写的」的判据——这也是 W5(用户目录 + 同名标记)能再窄一层的同一
818
+ // 思路:伪造固定串才可能误删,比「名字撞上」难得多,故不再引入 pid 校验之类的机制。
819
+ for (const ent of entries) {
820
+ if (!ent.name.endsWith(STAGING_MARKER_SUFFIX))
821
+ continue;
822
+ const abs = path.join(stagingBase, ent.name);
823
+ const stagingDir = abs.slice(0, -STAGING_MARKER_SUFFIX.length);
824
+ if (isStagingName(path.basename(stagingDir), entityBase) === false)
825
+ continue;
826
+ if (existsSync(stagingDir))
827
+ continue; // 目录还在:由上面的循环处理
828
+ try {
829
+ const st = lstatSync(abs);
830
+ if (!st.isFile())
831
+ continue; // 符号链接/目录/设备:不是我们的
832
+ if (now - st.mtimeMs < STALE_STAGING_MIN_AGE_MS)
833
+ continue;
834
+ // 与第一循环**同一个谓词**(复审 N1:内联复制会静默漂移,「逐字相等」的强度
835
+ // 就没人保证了)。
836
+ if (!isOurMarker(abs))
837
+ continue;
838
+ rmSync(abs, { force: true });
839
+ }
840
+ catch {
841
+ // 读不出来 / 并发删掉了等:无副作用,不必打扰用户。
842
+ }
843
+ }
844
+ }
845
+ export function planInstall(opts) {
846
+ const { entityDir, sourceDir, version, force } = opts;
847
+ const warnings = [];
848
+ // —— 源目录校验 ——
849
+ let srcIsDir;
850
+ try {
851
+ srcIsDir = statSync(sourceDir).isDirectory();
852
+ }
853
+ catch (err) {
854
+ if (isErrno(err, 'ENOENT'))
855
+ throw new Error(`skill 源目录不存在:${sourceDir}`);
856
+ throw err;
857
+ }
858
+ if (!srcIsDir)
859
+ throw new Error(`skill 源目录不是目录:${sourceDir}`);
860
+ let sourceFiles;
861
+ let sourceHash;
862
+ try {
863
+ sourceFiles = listFiles(sourceDir);
864
+ sourceHash = contentHash(sourceDir);
865
+ }
866
+ catch (err) {
867
+ // 源目录存在但内容不可读(权限等):源是包内内容,读不了就是硬错误,
868
+ // 但给出比裸 EACCES 更能定位问题的文案。
869
+ throw new Error(`skill 源目录不可读:${sourceDir}(${errMsg(err)})`);
870
+ }
871
+ const base = { entityDir, sourceFiles, sourceHash };
872
+ if (!isDirectory(entityDir)) {
873
+ let exists = true;
874
+ try {
875
+ lstatSync(entityDir);
876
+ }
877
+ catch (err) {
878
+ if (isErrno(err, 'ENOENT'))
879
+ exists = false;
880
+ else
881
+ throw err;
882
+ }
883
+ if (exists)
884
+ throw new Error(`实体路径已存在但不是目录:${entityDir}`);
885
+ return { ...base, status: 'installed', action: 'write', warnings };
886
+ }
887
+ // —— 分类(审查 I4:分类读取可能因 EACCES 等抛错;失败按「内容不同」处理,
888
+ // 让 --force 仍然可用、无 force 则跳过 + 警告,不把用户卡死) ——
889
+ // 「目录列不出来」与「目录里的某个文件读不出来」是**两种**失败:
890
+ // · listError(列目录失败,如实体目录 chmod 000):换入要往这个目录里 rename,
891
+ // 同样会被拒——--force 也救不了,实装必然失败。计划如实说「读不到,不覆盖」,
892
+ // 不给一个必然落空的 updated 承诺(审查 #53)。
893
+ // · hashError(某个文件读不出来,如 SKILL.md chmod 000):rename 覆盖它需要的
894
+ // 是目录写权限而不是该文件的读权限,--force 仍能修好(审查 I4 的既有用例)。
895
+ let vacuous = false;
896
+ let targetHash = null;
897
+ let listError = null;
898
+ let hashError = null;
899
+ try {
900
+ vacuous = isVacuous(entityDir);
901
+ }
902
+ catch (err) {
903
+ listError = err;
904
+ }
905
+ if (listError === null && !vacuous) {
906
+ try {
907
+ targetHash = contentHash(entityDir);
908
+ }
909
+ catch (err) {
910
+ hashError = err;
911
+ }
912
+ }
913
+ if (vacuous) {
914
+ // 真空(审查 C1 判据:除根部清单外无任何条目)——没有用户内容可保护,按首次安装换入。
915
+ const prev = readManifestSafe(entityDir);
916
+ return {
917
+ ...base, status: 'installed', action: 'write', warnings,
918
+ ...prevOf(prev),
919
+ };
920
+ }
921
+ if (targetHash === sourceHash) {
922
+ const m = readManifestSafe(entityDir);
923
+ if (m !== null
924
+ && m.version === version
925
+ && m.skill_contract_version === SKILL_CONTRACT_VERSION
926
+ && m.content_hash === sourceHash) {
927
+ return { ...base, status: 'skipped', action: 'none', warnings }; // 幂等:一个字节都不写
928
+ }
929
+ // 审查 M2:清单损坏/字段缺失/旧格式视为「落后」,不视为用户改动——它不是
930
+ // 正文,损坏不构成保护对象;正文哈希一致已证明正文未被改动。只重写清单
931
+ // (否则 Task 10 的漂移探测会永远报 stale)。
932
+ const manifestWarning = writeTargetWarning(path.join(entityDir, MANIFEST), '清单');
933
+ if (manifestWarning !== null) {
934
+ // 清单被占用:正文一致,用户处理占用后重跑即可。
935
+ return { ...base, status: 'skipped', action: 'none', warnings: [manifestWarning] };
936
+ }
937
+ return { ...base, status: 'updated', action: 'rewrite-manifest', warnings };
938
+ }
939
+ // 实体目录列不出来(chmod 000 等):连「里面有什么」都判定不了,而换入本身也需要
940
+ // 该目录的写权限(`rename` 进一个不可遍历的目录同样被拒)。**有 --force 也不能**
941
+ // 承诺 updated —— 此前 dry-run --force 预告 updated、真实 --force 退 1 的分叉
942
+ // (审查 #53)就出在 force 分支无视了这个错误。
943
+ if (listError !== null) {
944
+ warnings.push(`读取实体目录失败(${errMsg(listError)}),无法确认内容与写盘可行性,未覆盖;`
945
+ + `请先修复该目录的可读/可写权限再重跑(即使 --force 也会以同样的错误失败):${entityDir}`);
946
+ return { ...base, status: 'skipped', action: 'none', warnings };
947
+ }
948
+ if (force) {
949
+ const prev = readManifestSafe(entityDir);
950
+ return {
951
+ ...base, status: 'updated', action: 'write', warnings,
952
+ ...prevOf(prev),
953
+ };
954
+ }
955
+ const reason = hashError !== null
956
+ ? `读取实体目录内容失败(${errMsg(hashError)})`
957
+ : '实体目录内容与包内不同(可能被手工修改)';
958
+ warnings.push(`${reason},未覆盖;确认后可用 --force 覆盖:${entityDir}`);
959
+ return { ...base, status: 'skipped', action: 'none', warnings };
960
+ }
961
+ /** 计划里带上上一版清单的清理依据(`files` + 逐文件哈希 `file_hashes`)。 */
962
+ function prevOf(prev) {
963
+ if (prev === null)
964
+ return {};
965
+ const out = {};
966
+ if (prev.files !== undefined)
967
+ out.prevFiles = prev.files;
968
+ if (prev.file_hashes !== undefined)
969
+ out.prevFileHashes = prev.file_hashes;
970
+ return out;
971
+ }
972
+ /**
973
+ * 安装 skill。流程见文件头决策表。链接阶段的任何异常都进 warnings,不向上抛;
974
+ * 只有「源目录不可用」「实体路径被文件占用」「暂存写入失败」这类无法继续的情况
975
+ * 才抛错(调用方 Task 11 会转成 internal 错误信封)。
976
+ *
977
+ * 判定本身在 `planInstall`(只读);本函数只负责按计划执行写操作,并把**实际**
978
+ * 写盘结果翻译成 status(审查 B2:计划说要写但实际零写入时,status 退回 skipped
979
+ * 并警告——`data.status` 是 Agent 读的那一个字段,「报 updated、实体零变化」等于谎报)。
980
+ */
981
+ export async function installSkill(opts) {
982
+ const { home, sourceDir, version, force, noLink = false } = opts;
983
+ const entityDir = opts.entityDir ?? defaultEntityDir(home);
984
+ const plan = planInstall({ entityDir, sourceDir, version, force });
985
+ const warnings = [...plan.warnings];
986
+ let status = plan.status;
987
+ if (plan.action === 'write') {
988
+ const outcome = writeInstalled(entityDir, sourceDir, plan.sourceFiles, version, plan.sourceHash, warnings, { files: plan.prevFiles, hashes: plan.prevFileHashes });
989
+ if (outcome.concurrent === true) {
990
+ // 并发(gap 8):另一个进程先建出了实体,本进程**一个文件都没写**。
991
+ // 所以 status 恒为 skipped —— 此前这里用 `replan.status` 覆盖它,而 `skipped`
992
+ // 在 planInstall 里有**四种**含义(幂等一致 / 内容不同且未加 force / 清单被占用 /
993
+ // 目录列不出),于是内容不同时会谎报「一致」,--force 下更会把零写入报成 updated
994
+ // (终审 F1:重新引入了 B2 刚消灭的那类谎报)。
995
+ //
996
+ // 「正文一致」的判据必须**同时**满足「没有要写正文的动作」与「没有任何警告」
997
+ // (复审 F1 残留:只看 `action` 会把「内容不同且未加 force」这类 `action === 'none'`
998
+ // **带警告**的形态误说成「一致」;只认 `action === 'none'` 又会把「正文一致、仅清单
999
+ // 落后」误说成「仍不同(计划要求 --force)」——而那种情况不需要 --force,重跑即可):
1000
+ // · `action === 'none'` 且无警告 → 幂等,正文与清单都一致;
1001
+ // · `action === 'rewrite-manifest'` → 正文哈希一致、只是清单落后(该分支的
1002
+ // warnings 必为空:planInstall 走到它时还没 push 过任何警告);
1003
+ // · 其余(`action === 'none'` 带警告:内容不同且未加 force / 清单被占用 /
1004
+ // 实体目录列不出)才是「仍不同」。
1005
+ const replan = planInstall({ entityDir, sourceDir, version, force });
1006
+ status = 'skipped';
1007
+ // ⚠️ `action === 'none'` **带警告**还有两种完全不同的情形(复审 W3):
1008
+ // · 内容不同且未加 force → 提示加 --force 是正确的;
1009
+ // · 清单被目录/符号链接占用(正文逐字节一致)→ `--force` **无效**(planInstall
1010
+ // 在 force 分支之前就拦下了),劝用户加 --force 是错的建议。
1011
+ // 判据用警告文案里的关键词区分(planInstall 的这两条文案是稳定的),而不是再算一遍
1012
+ // 内容哈希——那会与 planInstall 形成第二事实源。
1013
+ const manifestBlocked = replan.warnings.some((w) => w.includes('清单已被非普通文件占用'));
1014
+ const sameContent = replan.warnings.length === 0
1015
+ && (replan.action === 'none' || replan.action === 'rewrite-manifest');
1016
+ warnings.push(replan.action === 'rewrite-manifest'
1017
+ ? `另一个并发安装已完成,实体内容与包内一致,仅安装清单落后;重跑一次 qiyu skill install 即会补写清单(无需 --force):${entityDir}`
1018
+ : manifestBlocked
1019
+ ? `另一个并发安装已完成,实体内容与包内一致,但安装清单被非普通文件占用;`
1020
+ + `先处理该占用再重跑 qiyu skill install(--force 对此无效):${entityDir}`
1021
+ : sameContent
1022
+ ? `另一个并发安装已完成,实体内容与包内一致:${entityDir}`
1023
+ : `另一个并发安装已完成,但实体内容与包内仍不同:${replan.warnings[0] ?? '计划要求 --force'}。`
1024
+ + `按上面那条警告的指引处理后再重跑 qiyu skill install(「内容被手工修改」或`
1025
+ + `某个文件读不出这两类,--force 有效;整个目录列不出来时 --force 同样失败)`);
1026
+ }
1027
+ else if (!outcome.complete && outcome.written === 0) {
1028
+ // 零写入:status 必须反映事实。`installed` 也一样退——实体可能只是个空壳。
1029
+ status = 'skipped';
1030
+ warnings.push(`实体目录内容与包内仍不一致(本次零写入),status 按实际结果记为 skipped;修复上述问题后重跑安装即可收敛`);
1031
+ }
1032
+ }
1033
+ else if (plan.action === 'rewrite-manifest') {
1034
+ writeManifest(entityDir, version, plan.sourceHash, plan.sourceFiles);
1035
+ }
1036
+ // —— 链接:按四态分派;任何失败都收敛进 warnings ——
1037
+ const links = [];
1038
+ if (!noLink)
1039
+ await linkAgents(opts, entityDir, links, warnings, status, plan.status);
1040
+ return { entityDir, status, plannedStatus: plan.status, links, warnings };
1041
+ }
1042
+ /** 对每个 agent 目录按 linkState 四态分派建链,结果与失败原因都写进 links/warnings。 */
1043
+ async function linkAgents(opts, entityDir, links, warnings, status, plannedStatus) {
1044
+ const { home, linkDirs } = opts;
1045
+ // 目录 → agent 名映射:默认探测直接用探测结果的 name;显式 linkDirs 查映射表,
1046
+ // 查不到(自定义目录)就把目录路径本身当 agent 标识,保证 links[].agent 可追溯。
1047
+ let dirs;
1048
+ if (linkDirs !== undefined) {
1049
+ const nameOf = new Map();
1050
+ try {
1051
+ for (const a of agentSkillDirs(home))
1052
+ nameOf.set(a.dir, a.name);
1053
+ }
1054
+ catch {
1055
+ // 映射失败只影响 links[].agent 的可读性,不影响建链,静默退回目录路径。
1056
+ }
1057
+ dirs = linkDirs.map((dir) => ({ dir, agent: nameOf.get(dir) ?? dir }));
1058
+ }
1059
+ else {
1060
+ try {
1061
+ dirs = agentSkillDirs(home).map((a) => ({ dir: a.dir, agent: a.name }));
1062
+ }
1063
+ catch (err) {
1064
+ // ~/.claude 是文件时 lstat 抛 ENOTDIR(Task 7 实测):收敛,不让整个安装失败。
1065
+ // 审查 B3:这也是「装了 Agent 却零链接」的一种,探测失败的原因已经在这句话里。
1066
+ warnings.push(`探测 agent skills 目录失败(${errMsg(err)}),本次不建链接`);
1067
+ return;
1068
+ }
1069
+ }
1070
+ // 自动模式下一条都没链上(审查 B3 / #58):`agentSkillDirs` 只返回**已存在**的
1071
+ // 目录,所以「装了 Agent 但没 skills 子目录」和「这台机器根本没装 Agent」在这里
1072
+ // 都表现为 dirs 为空。用户拿到的是「安装成功」,而 skill 不会被任何 Agent 加载。
1073
+ //
1074
+ // 不替用户创建目录(spec D1),但要说出来。`idempotent`(本次既没写盘也没别的
1075
+ // 警告)时把「已存在」也写进这条:命令层只在 result.warnings 为空时补那句
1076
+ // 「已存在且内容一致」,这里补上它就不会被吞掉——幂等重跑同样要告诉用户
1077
+ // 「没建链、skill 不会被加载」。
1078
+ if (linkDirs === undefined && dirs.length === 0) {
1079
+ warnNoAgentLinked(home, status === 'skipped' && plannedStatus === 'skipped' && warnings.length === 0, warnings);
1080
+ }
1081
+ for (const { dir, agent } of dirs) {
1082
+ let dirOk;
1083
+ try {
1084
+ dirOk = isDirectory(dir);
1085
+ }
1086
+ catch (err) {
1087
+ // 审查 M1:agent 目录不可检查(EACCES 等)时收敛进 warnings,不让安装失败。
1088
+ warnings.push(`检查 ${agent} 的 skills 目录失败(${errMsg(err)}),跳过建链:${dir}`);
1089
+ links.push({ agent, path: path.join(dir, LINK_NAME), state: 'missing' });
1090
+ continue;
1091
+ }
1092
+ if (!dirOk) {
1093
+ // 不替用户创建 agent 目录(spec D1)。显式点名的目录不存在要说出来;
1094
+ // links 里补 missing 条目,Task 11 逐 agent 展示状态时不缺行(审查 M3)。
1095
+ warnings.push(`${agent} 的 skills 目录不存在,跳过建链:${dir}`);
1096
+ links.push({ agent, path: path.join(dir, LINK_NAME), state: 'missing' });
1097
+ continue;
1098
+ }
1099
+ const linkPath = path.join(dir, LINK_NAME);
1100
+ let state;
1101
+ try {
1102
+ state = linkState(linkPath, entityDir);
1103
+ }
1104
+ catch (err) {
1105
+ // ELOOP(自指/成环链接)等不落四态(Task 7 实测)。判定不了的路径按 foreign
1106
+ // 处理:不触碰、只报告——这是四态里最保守的归类。
1107
+ warnings.push(`无法判定 ${agent} 链接状态(${errMsg(err)}),按占用处理、不触碰:${linkPath}`);
1108
+ links.push({ agent, path: linkPath, state: 'foreign' });
1109
+ continue;
1110
+ }
1111
+ if (state === 'ok') {
1112
+ links.push({ agent, path: linkPath, state });
1113
+ }
1114
+ else if (state === 'foreign') {
1115
+ warnings.push(`${agent} 的链接路径已被占用(不是指向本 skill 的链接),不覆盖:${linkPath}`);
1116
+ links.push({ agent, path: linkPath, state });
1117
+ }
1118
+ else {
1119
+ // missing / dangling:建链;dangling 必须先删(createSkillLink 遇已存在路径抛 EEXIST)。
1120
+ //
1121
+ // 重建 dangling 会**删掉用户自己建的那条链接**(审查 Minor #3:目标暂时不存在
1122
+ // 的自建链接也会落进 dangling)。删除用户数据必须说出来:把原链接内容记进警告,
1123
+ // 用户据此可以自行恢复。
1124
+ let previousTarget = null;
1125
+ try {
1126
+ if (state === 'dangling') {
1127
+ previousTarget = readlinkSync(linkPath, { encoding: 'utf8' });
1128
+ unlinkSync(linkPath);
1129
+ }
1130
+ const target = linkTarget(dir, entityDir);
1131
+ await createSkillLink(linkPath, target);
1132
+ if (previousTarget !== null) {
1133
+ warnings.push(`已重建 ${agent} 的悬空链接(原链接 → ${previousTarget},现为 → ${target}):${linkPath}`);
1134
+ }
1135
+ // 事后复核(审查 B1 双保险):建链“成功”不等于“agent 能解析到实体”——
1136
+ // agent 目录本身是符号链接时,相对路径若按错误的前缀算就会指向不存在的位置。
1137
+ // 复核不是 ok 就**如实**记 dangling,不得报 ok。
1138
+ const after = linkState(linkPath, entityDir);
1139
+ if (after === 'ok') {
1140
+ links.push({ agent, path: linkPath, state: 'ok' });
1141
+ }
1142
+ else {
1143
+ let resolved = null;
1144
+ try {
1145
+ resolved = readlinkSync(linkPath, { encoding: 'utf8' });
1146
+ }
1147
+ catch { /* 读回失败不影响结论 */ }
1148
+ warnings.push(`${agent} 的链接已创建但复核状态为 ${after}——Agent 很可能加载不到本 skill`
1149
+ + `(链接内容 ${resolved ?? '?'},实体 ${entityDir};若 agent skills 目录本身是符号链接请检查其落点):${linkPath}`);
1150
+ links.push({ agent, path: linkPath, state: after });
1151
+ }
1152
+ }
1153
+ catch (err) {
1154
+ const reason = previousTarget !== null ? `(原链接 → ${previousTarget} 已被移除)` : '';
1155
+ warnings.push(`${agent} 建链失败${reason}(${errMsg(err)}):${linkPath}`);
1156
+ // 如实报告失败后的真实状态(dangling 已删但建失败 → missing;删失败 → 仍 dangling)。
1157
+ links.push({ agent, path: linkPath, state: recheckState(linkPath, entityDir, state) });
1158
+ }
1159
+ }
1160
+ }
1161
+ }
1162
+ /**
1163
+ * 零链接时的如实提示(审查 B3 / #58):skill 装好了,但没有任何 Agent 会加载它。
1164
+ *
1165
+ * 分两种情况:
1166
+ * · 装了 Agent 根目录(`~/.claude`、`~/.codex`)但缺 skills 子目录 → 用户 mkdir
1167
+ * 一下再重跑 `qiyu skill install` 就能建链;
1168
+ * · 连 Agent 根目录都没有 → 这台机器上没装 Agent,属正常状态,也说一声(否则
1169
+ * 「装好了」的提示会让人以为 skill 已经能用了)。
1170
+ *
1171
+ * **不替用户创建目录**(spec D1):只提示,不 mkdir。
1172
+ *
1173
+ * `idempotent`(本次一个字节都没写、也没有别的警告)时,句首补上「已存在且内容
1174
+ * 一致、未做任何改动」——命令层只在 `result.warnings` 为空时才补这句,这里补上
1175
+ * 就不会被吞掉:幂等重跑同样要告诉用户「没建链、skill 不会被加载」。
1176
+ */
1177
+ function warnNoAgentLinked(home, idempotent, warnings) {
1178
+ let missing;
1179
+ try {
1180
+ missing = agentsMissingSkillDir(home).map((a) => a.dir);
1181
+ }
1182
+ catch {
1183
+ missing = [];
1184
+ }
1185
+ const prefix = idempotent ? 'skill 已存在且内容一致,未做任何改动;' : '';
1186
+ if (missing.length > 0) {
1187
+ warnings.push(`${prefix}已装 Agent 但缺少 skills 子目录,本次未建链:${missing.join('、')};`
1188
+ + `创建这些目录后重跑 \`qiyu skill install\` 即可建链(skill 不会被任何 Agent 加载)`);
1189
+ return;
1190
+ }
1191
+ warnings.push(`${prefix}未发现任何 Agent skills 目录(~/.claude/skills、~/.codex/skills),`
1192
+ + '本次未建链:skill 不会被任何 Agent 加载;装好 Agent 后重跑 `qiyu skill install` 即可建链');
1193
+ }
1194
+ /** 建链失败后重新判定状态;判定本身再抛(ELOOP 等)就退回尝试前的状态。 */
1195
+ function recheckState(linkPath, entityDir, fallback) {
1196
+ try {
1197
+ return linkState(linkPath, entityDir);
1198
+ }
1199
+ catch {
1200
+ return fallback;
1201
+ }
1202
+ }