qiyu-cli 0.2.1 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +433 -72
  2. package/dist/cli.js +48 -7
  3. package/dist/commands/api-notes.js +70 -0
  4. package/dist/commands/api.js +169 -49
  5. package/dist/commands/auth.js +151 -29
  6. package/dist/commands/credentials-source.js +30 -5
  7. package/dist/commands/db-notes.js +75 -0
  8. package/dist/commands/db.js +165 -127
  9. package/dist/commands/query-notes.js +58 -0
  10. package/dist/commands/query.js +449 -61
  11. package/dist/commands/skill.js +445 -51
  12. package/dist/commands/spec-types.js +101 -1
  13. package/dist/commands/stats.js +160 -33
  14. package/dist/commands/store-flags.js +18 -0
  15. package/dist/commands/store-notes.js +38 -0
  16. package/dist/commands/store-precheck.js +321 -0
  17. package/dist/commands/store.js +165 -77
  18. package/dist/commands/sync-notes.js +374 -0
  19. package/dist/commands/sync-run.js +180 -47
  20. package/dist/commands/sync.js +232 -127
  21. package/dist/core/config.js +280 -24
  22. package/dist/core/credentials.js +38 -4
  23. package/dist/core/edition.js +1 -1
  24. package/dist/core/envelope.js +73 -9
  25. package/dist/core/errors.js +73 -16
  26. package/dist/core/http.js +175 -54
  27. package/dist/core/ratelimit.js +5 -1
  28. package/dist/core/registry/index.js +36 -2
  29. package/dist/core/registry/params/export.session.check.json +17 -2
  30. package/dist/core/registry/params/export.session.json +24 -2
  31. package/dist/core/registry/params/export.session.one.json +10 -2
  32. package/dist/core/registry/params/export.session.one.message.json +17 -2
  33. package/dist/core/registry/specs.json +65 -43
  34. package/dist/core/shell.js +30 -0
  35. package/dist/core/time.js +1 -1
  36. package/dist/core/validate.js +21 -2
  37. package/dist/output.js +215 -29
  38. package/dist/postinstall.js +14 -5
  39. package/dist/query/errors.js +145 -45
  40. package/dist/query/mask.js +1277 -25
  41. package/dist/query/metric-catalog.js +11 -0
  42. package/dist/query/native-error.js +189 -0
  43. package/dist/query/sandbox.js +148 -25
  44. package/dist/query/table-query.js +36 -5
  45. package/dist/schedule/install.js +136 -13
  46. package/dist/skill/check.js +11 -6
  47. package/dist/skill/detect.js +89 -29
  48. package/dist/skill/install.js +233 -43
  49. package/dist/skill/paths.js +54 -0
  50. package/dist/skill/qiyu/SKILL.md +29 -5
  51. package/dist/skill/qiyu/errors.md +5 -4
  52. package/dist/skill/qiyu/protocols.md +57 -5
  53. package/dist/skill/qiyu/setup.md +6 -2
  54. package/dist/store/config.js +92 -16
  55. package/dist/store/duckdb.js +1551 -64
  56. package/dist/store/object-kinds.js +32 -0
  57. package/dist/store/retry.js +190 -7
  58. package/dist/store/schema.js +32 -4
  59. package/dist/sync/engine.js +439 -77
  60. package/dist/sync/registry.js +6 -0
  61. package/dist/sync/state.js +20 -0
  62. package/dist/sync/tasks/dim.js +23 -14
  63. package/dist/sync/tasks/knowledge.js +50 -8
  64. package/dist/sync/tasks/pace.js +27 -0
  65. package/dist/sync/tasks/pipeline.js +29 -9
  66. package/dist/sync/tasks/reports.js +176 -49
  67. package/dist/sync/tasks/sessions.js +88 -21
  68. package/dist/sync/tasks/tickets.js +59 -8
  69. package/dist/sync/types.js +60 -1
  70. package/dist/sync/windowing.js +0 -22
  71. package/dist/sync/write-contract.js +79 -0
  72. package/package.json +2 -2
@@ -48,7 +48,11 @@
48
48
  // · foreign → 不覆盖,记 'foreign' + 警告「已被占用」。
49
49
  // 链接阶段任何异常——建链失败、linkState 抛 ELOOP(自指循环链接不落四态,Task 7
50
50
  // 实测)、agent 目录不可检查(ENOTDIR/EACCES)——都收敛进 warnings,不让整个安装
51
- // 失败。ELOOP 这类「判定不了」的路径按 foreign 处理:不触碰、只报告,最保守的归类。
51
+ // 失败。⚠️ 这些「判定不了」的路径记 **unknown**(报告域见 `paths.ts` 的
52
+ // `LINK_REPORT_STATES`),不是 `foreign`:`foreign` 的含义是「路径上是别人的东西、
53
+ // 别删别覆盖」,而 ELOOP 恰恰是我们连它是什么都说不出来(审查 #13:同一条自环链接
54
+ // `where` 报 unknown、真实安装报 foreign,两条命令对同一状态不同答)。
55
+ // 动作不变——不触碰、只报告。
52
56
  //
53
57
  // 内容比较用 `contentHash`:对目录下所有普通文件按**相对路径('/' 分隔)升序**,依次
54
58
  // update「路径 + 换行 + 换行归一化后的内容」,SHA-256。定界符是必要的——没有它
@@ -62,7 +66,7 @@ import { createHash } from 'node:crypto';
62
66
  import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
63
67
  import path from 'node:path';
64
68
  import { SKILL_CONTRACT_VERSION } from '../core/edition.js';
65
- import { agentSkillDirs, agentsMissingSkillDir, createSkillLink, defaultEntityDir, LINK_NAME, linkState, linkTarget, MANIFEST, normalizeNewlines, } from './paths.js';
69
+ import { agentSkillDirs, agentsMissingSkillDir, createSkillLink, defaultEntityDir, dirShape, LINK_NAME, linkState, linkTarget, MANIFEST, normalizeNewlines, } from './paths.js';
66
70
  /**
67
71
  * 安装清单文件名(D6:事实源已收敛到 `paths.ts`,这里 re-export 只为保持既有 import
68
72
  * 路径兼容——`detect.ts` 与两个测试文件仍从本模块取它)。
@@ -126,6 +130,12 @@ function isOurMarker(p) {
126
130
  function isStagingName(name, entityBase) {
127
131
  return name.startsWith(`${entityBase}${STAGING_SUFFIX}`) && name.length > entityBase.length + STAGING_SUFFIX.length;
128
132
  }
133
+ /**
134
+ * 安装结果的 `status` 全部取值(真实安装的 `status` 与 dry-run 的 `planned_status` 同源)。
135
+ * Agent 按值分支(skip = 零写入),所以每个值都必须在 README 图例里有释义
136
+ * (`tests/skill-field-notes.test.ts` 双向核对)。
137
+ */
138
+ export const INSTALL_STATUSES = ['installed', 'updated', 'skipped'];
129
139
  /**
130
140
  * 对目录下所有普通文件算内容哈希:按相对路径('/' 分隔)升序,依次 update
131
141
  * 「路径 + '\n' + 换行归一化后的内容」。
@@ -137,8 +147,70 @@ function isStagingName(name, entityBase) {
137
147
  * (安装路径在 I4 处显式捕获)。
138
148
  */
139
149
  export function contentHash(dir) {
150
+ return hashFileSet(listFiles(dir), dir);
151
+ }
152
+ /**
153
+ * 只对**指定相对路径集合**算内容哈希(清单 `files` 的核对用,CodeRabbit #60)。
154
+ *
155
+ * 与 `contentHash` 同一算法(相对路径升序、路径 + '\n' 定界、换行归一化),只是文件集
156
+ * 由调用方给 —— 于是「实体里多了一个用户自己的文件」不会污染结果。调用方负责保证
157
+ * `rels` 都来自受信任的清单(`readInstalledManifestInfo` / `readManifest`)。
158
+ */
159
+ export function contentHashOfFiles(dir, rels) {
160
+ return hashFileSet([...rels].sort(), dir);
161
+ }
162
+ /**
163
+ * 对**实体目录里的受管文件集**算内容哈希,且先验证每个条目是「实体目录内的普通文件」。
164
+ *
165
+ * ⚠️ 不能直接把清单里的相对路径交给 `contentHashOfFiles` 去 `readFileSync`(Codex PR #69
166
+ * 第五轮实测):清单里的一条被 FIFO 占住时 `readFileSync` **无限阻塞**(打开读端等写端),
167
+ * `skill install` 与 `skill check --compare` 都会挂死;被换成指向目录外的符号链接时,
168
+ * 读取会**跟随链接**拿到与包内相同的内容 → 误判「正文一致」,而入口文件必须是实体内的
169
+ * 普通文件(skill spec「`SKILL.md` … 不能是符号链接」)。旧的整目录哈希走 `listFiles`(只收普通文件),天然躲开了
170
+ * 这两种形态 —— 换成受管集哈希后必须把这道筛选补回来。
171
+ *
172
+ * 读取**内容**时的 I/O 错误(EACCES 等)仍然抛给调用方(--force 能修好),这里只拦
173
+ * 「不可比」的形态:缺失 / 非普通文件 / 真实路径逃出实体目录。
174
+ */
175
+ export function managedContentHash(dir, rels) {
176
+ for (const rel of rels) {
177
+ const abs = joinRel(dir, rel);
178
+ const parents = verifyPlainParents(dir, rel);
179
+ if (parents === 'unsafe')
180
+ return { problem: 'escapes', rel };
181
+ let st;
182
+ try {
183
+ st = lstatSync(abs);
184
+ }
185
+ catch (err) {
186
+ if (isErrno(err, 'ENOENT'))
187
+ return { problem: 'missing', rel };
188
+ throw err;
189
+ }
190
+ if (!st.isFile())
191
+ return { problem: 'not_plain', rel }; // FIFO / 目录 / 符号链接:不读
192
+ if (!isRealpathContained(dir, abs))
193
+ return { problem: 'escapes', rel };
194
+ }
195
+ return { hash: contentHashOfFiles(dir, rels) };
196
+ }
197
+ /**
198
+ * 两份文件清单是否是**同一个集合**(唯一判据,2026-11-06 Codex 第四轮)。
199
+ *
200
+ * ⚠️ 不能写成「长度相等 + 逐个在包内」:清单被手工编辑或损坏时可能**含重复条目**
201
+ * 并漏掉另一个文件(把 `errors.md` 换成第二个 `SKILL.md`)—— 长度恰好相等、每个条目
202
+ * 也都在包内,两处比对都会误判「一致」:`skill check --compare` 退 0,
203
+ * `planInstall` 还会走 rewrite-manifest 分支、`--force` 也跳过修复。
204
+ * 重复条目本身说明清单不可信,一律判「不同」。
205
+ */
206
+ export function sameFileSet(a, b) {
207
+ const sa = new Set(a);
208
+ const sb = new Set(b);
209
+ return sa.size === a.length && sa.size === sb.size && [...sa].every((f) => sb.has(f));
210
+ }
211
+ function hashFileSet(rels, dir) {
140
212
  const hash = createHash('sha256');
141
- for (const rel of listFiles(dir)) {
213
+ for (const rel of rels) {
142
214
  // 路径后补 '\n' 定界:没有它,「文件 a + 内容 bc」与「文件 ab + 内容 c」
143
215
  // 会拼出同一字节流(测试钉住)。文件名不含换行时定界无歧义。
144
216
  hash.update(rel + '\n');
@@ -147,7 +219,7 @@ export function contentHash(dir) {
147
219
  return hash.digest('hex');
148
220
  }
149
221
  /** 递归列出目录下普通文件的相对路径('/' 分隔),升序排序;根部清单除外。 */
150
- function listFiles(dir) {
222
+ export function listFiles(dir) {
151
223
  const out = [];
152
224
  const walk = (abs, rel) => {
153
225
  for (const ent of readdirSync(abs, { withFileTypes: true })) {
@@ -294,11 +366,43 @@ function copyTree(src, dest, isRoot = true) {
294
366
  copyFileSync(from, to);
295
367
  }
296
368
  }
369
+ /**
370
+ * 「必须存在且是普通文件」的类型断言(`readPlainTextFile` 的判据本体,2026-11-06 Codex 第六轮)。
371
+ *
372
+ * ⚠️ 直接用 `readFileSync` 打开一个**没有写端的 FIFO 会无限阻塞**(读端等写端),
373
+ * 而这是同步调用 —— vitest 的 `testTimeout`、`try/catch` 都拦不住,命令会硬挂死。
374
+ * 实体目录里的一条被 FIFO 占住(清单 `.qiyu-skill.json` 或受管正文)就是这种形态。
375
+ * 先 `statSync` 判类型再读:非普通文件(FIFO / 目录 / 设备)立刻抛 `EINVAL` 类错误,
376
+ * 由调用方按自己的策略处理(多数是「不可用 / 不可比」)。
377
+ *
378
+ * ENOENT 等 `statSync` 自身的错误原样抛出 —— 调用方需要区分「不存在」与「存在但不可读」。
379
+ */
380
+ export function assertPlainFile(abs) {
381
+ // ⚠️ 用 `statSync`(**跟随符号链接**)而不是 `lstatSync`:清单路径上的符号链接是既有
382
+ // 形态,断链要照旧读成 ENOENT(→ 「清单缺失」→ stale,提示照给),指向文件的链接
383
+ // 照旧读得到。要挡的只是**读取会阻塞或必定失败**的形态:FIFO(打开读端等写端)、
384
+ // 目录、设备节点 —— `statSync` 对它们在类型上就能判出来,不必真去读。
385
+ const st = statSync(abs);
386
+ if (!st.isFile()) {
387
+ throw Object.assign(new Error(`不是普通文件(目录/FIFO/设备等):${abs}`), { code: 'EINVAL' });
388
+ }
389
+ }
390
+ /** 按 utf8 读一个必须是普通文件的路径(清单等文本场景)。 */
391
+ export function readPlainTextFile(abs) {
392
+ assertPlainFile(abs);
393
+ return readFileSync(abs, 'utf8');
394
+ }
297
395
  /**
298
396
  * 单个文件的内容哈希:换行归一化后的 sha256(与 `contentHash` 里的逐文件口径一致)。
299
397
  * 清单用它记录「本工具当时写下的内容」,供下一次 --force 清理时核对(审查 #59)。
398
+ *
399
+ * ⚠️ 读前先验类型(`assertPlainFile`):这个函数会被 `where` 直接用在实体文件上,
400
+ * FIFO 会挂死(Codex PR #69 第六轮)。调用方(清理 / 写入)都已自行筛过普通文件,
401
+ * 这里再筛一次是**兜底**,不改变既有行为。
300
402
  */
301
- function fileHash(abs) {
403
+ export function fileHash(abs) {
404
+ // 二进制读(与旧实现一致),但读前先验类型 —— 见上面 `assertPlainFile` 的理由。
405
+ assertPlainFile(abs);
302
406
  return createHash('sha256').update(normalizeNewlines(readFileSync(abs))).digest('hex');
303
407
  }
304
408
  /**
@@ -344,9 +448,11 @@ function writeManifest(dir, version, contentHashValue, files) {
344
448
  * (`file_hashes` 为 undefined = 「无从核对」,清理时保守不删任何文件),不接受
345
449
  * 部分采用——半份可用的哈希表比没有更容易让后续维护者误以为「已经核对过了」。
346
450
  */
347
- function readManifestSafe(entityDir) {
451
+ export function readManifestSafe(entityDir) {
348
452
  try {
349
- const raw = JSON.parse(readFileSync(path.join(entityDir, MANIFEST), 'utf8'));
453
+ // 走 `readPlainTextFile`:清单被 FIFO 占住时不得阻塞(Codex PR #69 第六轮),
454
+ // 非普通文件 → 抛 EINVAL → 落到本函数的 catch → null(= 「清单不可用」)。
455
+ const raw = JSON.parse(readPlainTextFile(path.join(entityDir, MANIFEST)));
350
456
  if (typeof raw.version === 'string'
351
457
  && typeof raw.skill_contract_version === 'number'
352
458
  && typeof raw.content_hash === 'string'
@@ -377,16 +483,15 @@ function isStringRecord(v) {
377
483
  return false;
378
484
  return Object.values(v).every((x) => typeof x === 'string');
379
485
  }
380
- /** 判定路径是否存在且是目录;不存在或不是目录返回 false,其余错误照常抛。 */
486
+ /**
487
+ * 路径是否是**真实目录**(顺着符号链接走;不存在或不是目录返回 false,其余错误照常抛)。
488
+ *
489
+ * 判据已下沉到 `paths.ts` 的 `dirShape`(唯一实现,审查 #9/#11):本函数只是它的
490
+ * 布尔投影,供「是目录才继续」的调用点用;需要区分「不存在」与「存在但不是目录」
491
+ * 的调用点(`planInstall`)直接看 `dirShape` 的三态。
492
+ */
381
493
  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
- }
494
+ return dirShape(p) === 'dir';
390
495
  }
391
496
  /** 实体目录根部是否存在清单文件(不论内容是否可读——存在就是「有上一版」)。 */
392
497
  function manifestExists(entityDir) {
@@ -869,19 +974,20 @@ export function planInstall(opts) {
869
974
  throw new Error(`skill 源目录不可读:${sourceDir}(${errMsg(err)})`);
870
975
  }
871
976
  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}`);
977
+ // 实体路径的三态收敛到 `dirShape`(唯一判据,审查 #9/#11):此前这里用与 `where`
978
+ // 各写一份的 `isDirectory`,对**悬空符号链接**占住实体路径的形态给出互相矛盾的结论
979
+ // ——`where` 用 statSync 得 ENOENT 报 missing 并建议 `qiyu skill install`,而这里
980
+ // 用 lstatSync 判「存在但不是目录」退 1:CLI 自荐的修复动作**必然失败**(实测)。
981
+ // 现在两处都按「路径存在(链接本身是存在的条目)、但不是可写目录」处理:install 拒绝
982
+ // 写它并说清要先由人处理,`where` 报 `not_a_directory`(图例已写明 install 不会写它)。
983
+ const shape = dirShape(entityDir);
984
+ if (shape === 'not_a_directory') {
985
+ throw new Error(`实体路径已存在但不是目录:${entityDir}`
986
+ // 悬空符号链接是最常见的那种「存在但不是目录」:用户把实体放在大盘/网盘上、
987
+ // 盘没挂上,或链接指向已被删的旧位置。说清动作,否则用户不知道从哪下手。
988
+ + '(若这是一条符号链接,请先修正它的指向或删掉它——install 不覆盖这条链接)');
989
+ }
990
+ if (shape === 'absent') {
885
991
  return { ...base, status: 'installed', action: 'write', warnings };
886
992
  }
887
993
  // —— 分类(审查 I4:分类读取可能因 EACCES 等抛错;失败按「内容不同」处理,
@@ -894,8 +1000,27 @@ export function planInstall(opts) {
894
1000
  // 是目录写权限而不是该文件的读权限,--force 仍能修好(审查 I4 的既有用例)。
895
1001
  let vacuous = false;
896
1002
  let targetHash = null;
1003
+ let sourceComparableHash = null;
897
1004
  let listError = null;
898
1005
  let hashError = null;
1006
+ // 受管文件集与包内不一致(包升级增/删了文件)—— 单独记账,用于给准原因。
1007
+ let fileSetDiffers = false;
1008
+ // 受管条目「不可比」(缺失 / 非普通文件 / 逃出实体目录)—— 与「文件集不同」分开归因。
1009
+ let managedProblem = null;
1010
+ // ⚠️ 「正文是否被改过」的判据基准是**受管文件集**(上一版清单的 `files`),不是整目录
1011
+ // 总哈希(2026-11-06 审查实测):用户往实体目录里放任何自己的文件(`where` 明确说
1012
+ // 「不影响正文判定」)都会让总哈希不同 → 这里报「可能被手工修改」并推 `--force`,
1013
+ // 而 `--force` 刻意保留额外文件 → 下一次原样再报,**永远不收敛**;照提示跑 `--force`
1014
+ // 还会把用户真的手工改动覆盖掉。`where` 早就是受管文件口径(CodeRabbit #60),
1015
+ // 这里与它统一。
1016
+ let prevManifest;
1017
+ try {
1018
+ prevManifest = readManifestSafe(entityDir);
1019
+ }
1020
+ catch {
1021
+ prevManifest = null;
1022
+ }
1023
+ const managedRels = prevManifest?.files;
899
1024
  try {
900
1025
  vacuous = isVacuous(entityDir);
901
1026
  }
@@ -904,7 +1029,30 @@ export function planInstall(opts) {
904
1029
  }
905
1030
  if (listError === null && !vacuous) {
906
1031
  try {
907
- targetHash = contentHash(entityDir);
1032
+ if (managedRels !== undefined && managedRels.length > 0) {
1033
+ // ⚠️ 文件集必须**完全一致**才可比(2026-11-06 自查):只比「清单里的文件」会把
1034
+ // 「包升级新增了一个文件」误判成「正文一致」—— 随后走 rewrite-manifest 分支,
1035
+ // 只重写清单、不复制新文件,status 却报 updated:实体里根本没有那个文件。
1036
+ // 集合不同的成因是**包变了**,不是用户改动,所以原因文案也要分开。
1037
+ // 判据走 `sameFileSet`(同时拒绝重复条目),与 `check --compare` 同源。
1038
+ fileSetDiffers = !sameFileSet(managedRels, sourceFiles);
1039
+ if (!fileSetDiffers) {
1040
+ // 受管条目可能是 FIFO / 符号链接等「不可比」形态 —— 由 `managedContentHash`
1041
+ // 先筛(旧实现读 FIFO 会无限阻塞、跟符号链接会误判一致,Codex PR #69 第五轮)。
1042
+ const h = managedContentHash(entityDir, managedRels);
1043
+ if ('hash' in h) {
1044
+ targetHash = h.hash;
1045
+ sourceComparableHash = contentHashOfFiles(sourceDir, managedRels);
1046
+ }
1047
+ else {
1048
+ managedProblem = h;
1049
+ }
1050
+ }
1051
+ }
1052
+ else {
1053
+ targetHash = contentHash(entityDir);
1054
+ sourceComparableHash = sourceHash;
1055
+ }
908
1056
  }
909
1057
  catch (err) {
910
1058
  hashError = err;
@@ -918,7 +1066,7 @@ export function planInstall(opts) {
918
1066
  ...prevOf(prev),
919
1067
  };
920
1068
  }
921
- if (targetHash === sourceHash) {
1069
+ if (targetHash !== null && sourceComparableHash !== null && targetHash === sourceComparableHash) {
922
1070
  const m = readManifestSafe(entityDir);
923
1071
  if (m !== null
924
1072
  && m.version === version
@@ -952,9 +1100,18 @@ export function planInstall(opts) {
952
1100
  ...prevOf(prev),
953
1101
  };
954
1102
  }
955
- const reason = hashError !== null
956
- ? `读取实体目录内容失败(${errMsg(hashError)})`
957
- : '实体目录内容与包内不同(可能被手工修改)';
1103
+ const managedProblemText = managedProblem === null ? '' : {
1104
+ missing: '受管文件缺失(可能被手工删除)',
1105
+ not_plain: '受管文件被替换成了非普通文件(符号链接/目录/FIFO 等)',
1106
+ escapes: '受管文件的真实路径不在实体目录内',
1107
+ }[managedProblem.problem];
1108
+ const reason = fileSetDiffers
1109
+ ? '包内的受管文件集与上次安装不同(包升级增/删了文件),未能逐文件比对'
1110
+ : managedProblem !== null
1111
+ ? `上一版安装的 ${managedProblem.rel} 不可比(${managedProblemText}),未能判定正文是否一致`
1112
+ : hashError !== null
1113
+ ? `读取实体目录内容失败(${errMsg(hashError)})`
1114
+ : '实体目录内容与包内不同(可能被手工修改)';
958
1115
  warnings.push(`${reason},未覆盖;确认后可用 --force 覆盖:${entityDir}`);
959
1116
  return { ...base, status: 'skipped', action: 'none', warnings };
960
1117
  }
@@ -984,6 +1141,13 @@ export async function installSkill(opts) {
984
1141
  const plan = planInstall({ entityDir, sourceDir, version, force });
985
1142
  const warnings = [...plan.warnings];
986
1143
  let status = plan.status;
1144
+ /**
1145
+ * 并发收敛标记(Sourcery 2026-11-02):另一个进程先装好了**与包内一致**的实体,
1146
+ * 本进程零写入 —— 此时 `status` 仍如实记为 `'skipped'`(本进程确实什么都没写),
1147
+ * 但**最终状态**其实是最新的。`upToDate` 描述的是后者,所以要带上这个标记,
1148
+ * 否则 postinstall 会对一个已经装好的实体报「未完成更新」。
1149
+ */
1150
+ let convergedByConcurrent = false;
987
1151
  if (plan.action === 'write') {
988
1152
  const outcome = writeInstalled(entityDir, sourceDir, plan.sourceFiles, version, plan.sourceHash, warnings, { files: plan.prevFiles, hashes: plan.prevFileHashes });
989
1153
  if (outcome.concurrent === true) {
@@ -1013,6 +1177,9 @@ export async function installSkill(opts) {
1013
1177
  const manifestBlocked = replan.warnings.some((w) => w.includes('清单已被非普通文件占用'));
1014
1178
  const sameContent = replan.warnings.length === 0
1015
1179
  && (replan.action === 'none' || replan.action === 'rewrite-manifest');
1180
+ // 只有 `action === 'none'` 且**无警告**才是真正收敛(正文与清单都是包内那份);
1181
+ // `rewrite-manifest` 说明清单还落后,那不算「最新」。
1182
+ convergedByConcurrent = replan.warnings.length === 0 && replan.action === 'none';
1016
1183
  warnings.push(replan.action === 'rewrite-manifest'
1017
1184
  ? `另一个并发安装已完成,实体内容与包内一致,仅安装清单落后;重跑一次 qiyu skill install 即会补写清单(无需 --force):${entityDir}`
1018
1185
  : manifestBlocked
@@ -1037,7 +1204,13 @@ export async function installSkill(opts) {
1037
1204
  const links = [];
1038
1205
  if (!noLink)
1039
1206
  await linkAgents(opts, entityDir, links, warnings, status, plan.status);
1040
- return { entityDir, status, plannedStatus: plan.status, links, warnings };
1207
+ // 幂等判据 = 计划态 skipped **且** 计划本身一句话都没说(plan.warnings 为空)——
1208
+ // 链接阶段的警告(未发现 Agent 目录等)不算,它们与「正文是否最新」无关。
1209
+ return {
1210
+ entityDir, status, plannedStatus: plan.status, links, warnings,
1211
+ upToDate: (status === 'skipped' && plan.status === 'skipped' && plan.warnings.length === 0)
1212
+ || convergedByConcurrent,
1213
+ };
1041
1214
  }
1042
1215
  /** 对每个 agent 目录按 linkState 四态分派建链,结果与失败原因都写进 links/warnings。 */
1043
1216
  async function linkAgents(opts, entityDir, links, warnings, status, plannedStatus) {
@@ -1079,33 +1252,50 @@ async function linkAgents(opts, entityDir, links, warnings, status, plannedStatu
1079
1252
  warnNoAgentLinked(home, status === 'skipped' && plannedStatus === 'skipped' && warnings.length === 0, warnings);
1080
1253
  }
1081
1254
  for (const { dir, agent } of dirs) {
1082
- let dirOk;
1255
+ // 目录形态用共享判据(审查 #11):此前用布尔 `isDirectory`,把「agent 装了、
1256
+ // 但 skills 路径被一个**普通文件**占住」也说成「目录不存在」(事实错误——
1257
+ // 路径明明存在),且 links 记 missing,而 `where` 对同一路径报 unknown+ENOTDIR。
1258
+ let shape;
1083
1259
  try {
1084
- dirOk = isDirectory(dir);
1260
+ shape = dirShape(dir);
1085
1261
  }
1086
1262
  catch (err) {
1087
1263
  // 审查 M1:agent 目录不可检查(EACCES 等)时收敛进 warnings,不让安装失败。
1264
+ // ⚠️ state 记 `unknown`(不是 missing):dirShape 抛出的 ELOOP/EACCES 下
1265
+ // 路径**存在**——只是判定不了形态(CodeRabbit #60)。missing 含义是「不存在」。
1088
1266
  warnings.push(`检查 ${agent} 的 skills 目录失败(${errMsg(err)}),跳过建链:${dir}`);
1089
- links.push({ agent, path: path.join(dir, LINK_NAME), state: 'missing' });
1267
+ links.push({ agent, path: path.join(dir, LINK_NAME), state: 'unknown', error: errMsg(err) });
1090
1268
  continue;
1091
1269
  }
1092
- if (!dirOk) {
1270
+ if (shape === 'absent') {
1093
1271
  // 不替用户创建 agent 目录(spec D1)。显式点名的目录不存在要说出来;
1094
1272
  // links 里补 missing 条目,Task 11 逐 agent 展示状态时不缺行(审查 M3)。
1095
1273
  warnings.push(`${agent} 的 skills 目录不存在,跳过建链:${dir}`);
1096
1274
  links.push({ agent, path: path.join(dir, LINK_NAME), state: 'missing' });
1097
1275
  continue;
1098
1276
  }
1277
+ if (shape === 'not_a_directory') {
1278
+ // 路径**存在**但不是目录(普通文件、悬空符号链接…)。说「不存在」是事实错误,
1279
+ // 而且它不能像「不存在」那样 mkdir 一下就好——那条路已被一个非目录占住。
1280
+ // 状态记 unknown 而非 missing:`where` 对同路径报的是 unknown(ENOTDIR 判不了),
1281
+ // 两个命令必须同答(#13 的同一纪律)。
1282
+ warnings.push(`${agent} 的 skills 路径存在但不是目录(无法在此建链,需先由人处理该路径):${dir}`);
1283
+ links.push({ agent, path: path.join(dir, LINK_NAME), state: 'unknown', error: '路径存在但不是目录' });
1284
+ continue;
1285
+ }
1099
1286
  const linkPath = path.join(dir, LINK_NAME);
1100
1287
  let state;
1101
1288
  try {
1102
1289
  state = linkState(linkPath, entityDir);
1103
1290
  }
1104
1291
  catch (err) {
1105
- // ELOOP(自指/成环链接)等不落四态(Task 7 实测)。判定不了的路径按 foreign
1106
- // 处理:不触碰、只报告——这是四态里最保守的归类。
1107
- warnings.push(`无法判定 ${agent} 链接状态(${errMsg(err)}),按占用处理、不触碰:${linkPath}`);
1108
- links.push({ agent, path: linkPath, state: 'foreign' });
1292
+ // ELOOP(自指/成环链接)等不落四态(Task 7 实测)。动作是「不触碰、只报告」,
1293
+ // 但**报告值必须是 unknown,不是 foreign**:foreign 在 Agent 图例里的含义是
1294
+ // 「路径上是别人的东西」——判定不了时这是编造(2026-11-03 实测:同一条自环
1295
+ // 链接 `where` 报 unknown、install 报 foreign)。unknown 的释义正是
1296
+ // 「无法判定,不是『不存在』,不要据此重装或删除」,与动作一致。
1297
+ warnings.push(`无法判定 ${agent} 链接状态(${errMsg(err)}),不触碰:${linkPath}`);
1298
+ links.push({ agent, path: linkPath, state: 'unknown', error: errMsg(err) });
1109
1299
  continue;
1110
1300
  }
1111
1301
  if (state === 'ok') {
@@ -151,6 +151,21 @@ function realpathOrSelf(p) {
151
151
  return p;
152
152
  }
153
153
  }
154
+ /**
155
+ * **可判定**的链接四态 —— `linkState()` 的返回域。ELOOP(自指/成环)等判定不了的情况
156
+ * 不在其中,`linkState` 会照常抛,由调用方收敛。
157
+ */
158
+ export const LINK_STATES = ['ok', 'dangling', 'foreign', 'missing'];
159
+ /**
160
+ * `links[].state` 的**报告域**(`skill where` 与 `skill install` 共用,5 值):
161
+ * 四态 + `unknown`(无法判定 ≠ 不存在)。两个命令必须用**同一个域**——
162
+ * 此前 `where` 用 5 值、`install` 用 4 值,同一条自环链接 `where` 报 `unknown`、
163
+ * `install` 报 `foreign`(2026-11-03 实测),同一份输出里两个 `links[].state`
164
+ * 图例说的却是同一套话(`tests/skill-field-notes.test.ts` 三方核对也因此覆盖不到
165
+ * install 侧的真实值域)。收敛到这里后,两处都是这 5 个值。
166
+ * 每个值都必须在 `meta.field_notes`(README 同步)有释义与动作。
167
+ */
168
+ export const LINK_REPORT_STATES = [...LINK_STATES, 'unknown'];
154
169
  /**
155
170
  * 判定 `linkPath` 相对 `entityDir` 的状态。
156
171
  *
@@ -205,6 +220,45 @@ export function linkState(linkPath, entityDir) {
205
220
  function hasInode(st) {
206
221
  return typeof st.ino === 'number' && st.ino !== 0 && typeof st.dev === 'number';
207
222
  }
223
+ /**
224
+ * 路径的目录形态 —— **唯一判据**(2026-11-03 审查 #9/#11)。
225
+ *
226
+ * 此前「这个路径是不是一个可用的目录」有三份各自为政的 `statSync` 判据
227
+ * (`install.ts` 的 `isDirectory`、`commands/skill.ts` 的 `skill where` 实体探测、
228
+ * `detect.ts` 的启动探测),对同一条路径给出互相矛盾的结论:
229
+ * · 实体路径是**悬空符号链接** → `where` 报 `exists:false / missing` 并建议
230
+ * `qiyu skill install`,而 install 退 1「实体路径已存在但不是目录」——
231
+ * CLI 自荐的修复动作必然失败(实测);
232
+ * · agent 的 skills 路径是**普通文件** → install 说「目录不存在」(事实错误,
233
+ * 路径明明存在),`where` 对同一路径报 `unknown`+ENOTDIR。
234
+ * 收敛到一个函数后,三处对同一路径必然同答。
235
+ *
236
+ * 三态与判据(**只看真实文件系统的形态**,不猜意图):
237
+ * · `absent` —— 路径不存在。判据不只是 `statSync` 抛 ENOENT:还要 `lstatSync`
238
+ * 也拿不到(ENOENT 时 lstat 也失败),否则那是**悬空符号链接**(见下)。
239
+ * · `not_a_directory` —— 路径**存在**但不是目录:普通文件/设备,或是一条
240
+ * 解析不到目标的符号链接(`statSync` 抛 ENOENT,但 `lstatSync` 看得到它)。
241
+ * 消费方据此说「路径存在但不是目录,需先由人处理」,**不能**说「不存在」。
242
+ * · `dir` —— 真实目录(**顺着**符号链接判定:实体目录本身是指向别处的符号链接
243
+ * 是合法安装形态,见 `probe()` 的注释)。
244
+ *
245
+ * **其余错误照常抛**(ENOTDIR=父级是文件、EACCES、ELOOP…):那些是「判定不了」,
246
+ * 由调用方按各自语境收敛(install 进 warnings 记 unknown、detect 归 unknown),
247
+ * 本函数不替它们编一个形态。与 `linkState` 的四态是同一条纪律——判不了就抛。
248
+ */
249
+ export function dirShape(p) {
250
+ try {
251
+ return statSync(p).isDirectory() ? 'dir' : 'not_a_directory';
252
+ }
253
+ catch (err) {
254
+ if (!isEnoent(err))
255
+ throw err;
256
+ // 解析不到:区分「根本不存在」与「悬空符号链接占着这个位置」。后者是**存在**的
257
+ // 一个条目(lstat 看得到),只是解析不到目标——它对 install 是「不能写的占用物」,
258
+ // 对 `where` 是「路径存在但不是目录」,对启动探测是「判定不了」。
259
+ return lstatOrNull(p) !== null ? 'not_a_directory' : 'absent';
260
+ }
261
+ }
208
262
  /**
209
263
  * 平台决策的纯函数:给定链接路径、目标与平台,返回实际要传给 `symlink` 的参数。
210
264
  *
@@ -24,6 +24,12 @@ qiyu sync status
24
24
 
25
25
  - 有哪些表、行数、粒度、时间范围、PII 标注:`qiyu db tables`
26
26
  - 单表的列定义:`qiyu db describe <表>`
27
+ (⚠️ 要分清**声明**与**实测**:`columns` / `pii_columns` / `time_column` / `grain` /
28
+ `primary_key` 来自本 CLI 的表定义,是声明——表被删或列被删时照旧输出,差异只在
29
+ `meta.warnings` 里。`row_count` 与 `time_range` 则是**实测**(真去库里查)。另外
30
+ `db describe` 有列级字段,`db tables` 只有表级字段(`grain` / `time_range` /
31
+ `pii_columns`)——别去后者找列清单。`db tables` 的清单也只含库里真实存在的表。
32
+ 逐键释义见输出的 `meta.field_notes`。)
27
33
  - 报表指标的单位、本地观测分布、哨兵值:`qiyu stats fields <报表表>`
28
34
  - 接口清单与参数表:`qiyu api list`、`qiyu api schema <接口id>`
29
35
  - 同步任务清单:`qiyu sync tasks`
@@ -40,16 +46,30 @@ qiyu sync status
40
46
  含义是本机装的正文与这份 CLI 不配套;更新方式是 `qiyu skill install --force`——它会写到本机
41
47
  的 skill 实体目录与各 Agent 的 skills 目录。**只在人类允许写 home 时执行**,不要自作主张
42
48
  改动用户目录;不允许时把这条提示原样转述给人类。
49
+ 提示里同时给出裸 `qiyu skill install` 与 `--force` 时(清单缺失/损坏),按这个次序做:
50
+ **先跑裸 `qiyu skill install`**;返回 `status: "skipped"` 且 `meta.warnings` 说「内容与包内不同」
51
+ 就说明正文被手工改过——此时**先问人类**,得到允许再用 `--force` 覆盖(那会丢掉手工改动)。
52
+ 提示里只有 `--force` 时(版本不一致 / 正文漂移):**正文可能被手工改过**,`--force`
53
+ 会丢掉那些改动——先问人类是否允许覆盖,得到允许再执行。
54
+ 若 install 的 `meta.warnings` 说清单路径被非普通文件占用,**先清理那个占用**(那是人该做的事):
55
+ 两个动词都写不进清单;正文被改过时 `--force` 还会只覆盖正文、留下「状态 updated 但提示仍在」的
56
+ 半截结果,正文与包内一致时连 `--force` 也零写入(status 报 `skipped`)。
43
57
  - **`qiyu --version`**:输出包版本(`data.version`)与 `data.skill_contract_version`
44
58
  (**这份 CLI** 的正文契约号)。
45
59
  - **`qiyu skill where`**:报告实体目录与各 Agent 链接状态,并给出**已安装那份正文**的
46
60
  版本元数据:`data.entity.installed.skill_contract_version`(装的那份的契约号)、
47
61
  `data.cli_contract_version`(本 CLI 的)与 `data.entity.installed.compatible`
48
- (两者是否相等)。**判断「手上的正文能否配这份 CLI」就看这一个字段**,不要拿包版本号
49
- 去比 —— 包版本不同但契约号相同,正文仍然能用。`installed` 为 `null` = 实体不可用,
50
- 或清单缺失/损坏,判定不了,不要当成「兼容」。
51
- - **`qiyu skill check`**:正文自身的防漂移校验(命令、表名、错误 `kind`、位置参数取值是否
52
- 仍存在于当前 CLI)。默认校验包内那份;`--installed` 校验已安装的那份,`--compare` 比对
62
+ (两者是否相等)。判断「手上的正文能否配这份 CLI」看 `compatible`,但先看它是不是
63
+ `null`:**这个判定只对「已安装正文与安装清单记录的一致」的那份成立** —— 正文被手工
64
+ 改过(或读不动)时清单仍指着旧正文,`compatible` 报 `null`(判定不了),不会拿旧清单
65
+ 给改过的正文背书。不要拿包版本号去比 —— 包版本不同但契约号相同,正文仍然能用。
66
+ `installed` 为 `null` = 实体不可用,或清单缺失/损坏,判定不了,不要当成「兼容」。
67
+ `links[].state` 的 `foreign` 表示**那个路径上是别人的东西**(不是本 CLI 建的链接)——
68
+ install 会跳过它,**不要删、不要覆盖**;`unknown` 是「判定不了」,不是「不存在」。
69
+ 各状态的完整含义见该命令输出里的 `meta.field_notes`(每个值都带释义与动作)。
70
+ - **`qiyu skill check`**:正文自身的防漂移校验(命令、flag、错误 `kind` 与位置参数取值是否
71
+ 符合当前 CLI 契约;正文里**出现表名或完整 SQL 序列**也算违规——这类事实必须运行时获取)。
72
+ 默认校验包内那份;`--installed` 校验已安装的那份,`--compare` 比对
53
73
  两份并报告差异。有违规时退出码 1。
54
74
  - **不要手工编辑已安装的正文**:手工改过之后,`qiyu skill install`(不带 `--force`)
55
75
  会判定「内容与包内不同」而**跳过不覆盖**,你改的那份会一直留着、也一直与包内不一致。
@@ -82,6 +102,10 @@ qiyu sync status
82
102
  `{"ok":false,"error":…}`;日志与进度走 stderr,不要把 stderr 当数据。
83
103
  - 出错时按 `error.kind` 分支,不要按 `code`(见 errors.md)。
84
104
  - 退出码:`0` 成功 · `1` 业务错误 · `2` 用法错误 · `3` 网络错误 · `4` 需要人工确认。
105
+ - ⚠️ 退出码 `1` 但 stdout 仍是 `{ok:true,data:…}`(**没有** `error`)的五种情况:
106
+ `sync run` 全窗失败、`sync verify` 的 `drift` 非空、`sync install`/`sync uninstall --yes`
107
+ 有命令执行失败、`skill check` 有违规、`skill check --compare` 两侧不一致。这时按 `data`
108
+ 读问题,不要去找 `error.kind`。
85
109
 
86
110
  ## 其余五份协议(按需阅读)
87
111
 
@@ -11,14 +11,15 @@
11
11
  | 信号 | 动作 |
12
12
  |---|---|
13
13
  | `kind: auth_missing` | 凭证未配置(环境变量与配置文件都没有)。按 hint 设置 `QIYU_APP_KEY`/`QIYU_APP_SECRET` 或让人类跑 `qiyu auth login`;原命令重试无用 |
14
- | `kind: config_insecure` | 配置文件**含凭证**但权限过宽(group/other 可读到 appSecret)。重试无用——转告人类执行 hint 里点名的 `chmod` 后重跑 |
14
+ | `kind: config_insecure` | 配置文件的**权限**问题,重试无用:①文件含凭证但权限过宽(group/other 有任何权限位,可读时可读到 appSecret);②文件因权限拒绝**读不出来**(POSIX:`EACCES`/`EPERM`,hint 是 `chmod 600` 文件;Windows:NTFS ACL 拒绝,hint 是 `icacls <路径> /reset`);③配置**目录**不可搜索/不可进入(POSIX hint 是 `chmod 700` 目录,Windows 同样是 `icacls … /reset`)。都转告人类执行 hint 里点名的命令后重跑;**不是**凭证缺失,不要改去 `auth login` |
15
+ | `kind: config_invalid` | 配置文件**内容**读不出来(畸形 JSON / 不认识的键 / 路径不是普通文件),退出码 1。改参数、重试都修不好:按 hint 先修好或移走该文件,再重跑;`auth login` 此时**没有**写入任何内容 |
15
16
  | `kind: auth` | 凭证被服务端拒绝(key 错、IP 不在白名单、接口无权限)。按 hint 修配置;重试无用 |
16
17
  | `kind: bad_time` | 时间戳超期。CLI 已自动重签重试过;仍失败说明本机时钟真的偏了——校准系统时间 |
17
18
  | `kind: param` | 参数错误。按 message 与 hint 修正;重试无用 |
18
19
  | `kind: usage` | 调用方式有误(退出码 2)。改命令或参数重来;原样重试毫无意义 |
19
20
  | `kind: rate_limit` | 限流。看 `retry_after`:`source` 为 `fallback` 表示该秒数是保守兜底、不是实测冷却(睡完可能再吃一次限流);秒数超过 60 就不要干等——转本地查询通道先做别的分析,稍后再回来。若错误里带 `retry_strategy: switch_to_local` 与 `fallback` 命令,说明**该接口在同步任务里有本地表映射、且配置指向的库文件存在**——CLI 只检查了这两件事,**没有打开库、没有确认那张表真的存在**(把库路径指向别的文件时这条建议照样会出现),所以先跑 `qiyu db tables` 确认表在清单里。即便在,那也只是**整表数据源,不是这次请求的等价替代**:它不会带上你 body 里的筛选条件(时间窗/状态/关键字等),要自己补 WHERE(`--sql` 或 `--since`/`--until`);表存在也不等于已同步或覆盖你要的时间窗,先按 `hint` 用 `qiyu db tables` / `qiyu sync status` 确认行数与水位再采信 |
20
21
  | `kind: window_too_large` | 时间跨度超限。上限天数看报文里的数字(如「> 31」即 31 天),或查 `qiyu api list` 输出里该接口的 `max_window_days`;按它切片、分批请求 |
21
- | `kind: window_misaligned` | 时间边界没对齐自然日(结束边界不得晚于今天零点)。切片修不好——把边界对齐到自然日再试 |
22
+ | `kind: window_misaligned` | `endTime` 越界:必须**早于**今天 00:00(用纯历史日期,不要包含今天的数据)。切片修不好——把窗口挪到纯历史日期再试。⚠️ 边界值 `endTime = 今天 0:00` 本身实测不稳定(有时 200 有时被拒),别贴着它取值 |
22
23
  | `kind: module_offline` | 模块未开通。永久失败,找人类开通,不要重试 |
23
24
  | `kind: not_in_queue` | 业务状态,不是故障。按业务语义处理,不重试 |
24
25
  | `kind: pending` | 异步任务未完成(如会话导出轮询)。这是正常中间态——稍后再次轮询,不要判成失败 |
@@ -27,8 +28,8 @@
27
28
  | `kind: network` | 网络层故障(退出码 3)。检查网络后退避重试 |
28
29
  | `kind: unknown` | 未分类错误。按 message 判断,不要盲目重试 |
29
30
  | `kind: needs_confirmation` | 危险操作等待确认(退出码 4)。**停下**,向人类复述该操作及其目标;**绝不自动追加 `--yes`** |
30
- | `kind: store_locked` | 本地库正被写进程持锁(例如同步进行中)。退避后重试;期间可以先用已有数据做分析 |
31
- | `kind: store_not_initialized` | 本地库不可用(不存在 / 缺表 / 不是本 CLI 的库 / 依赖未安装)。**按 `hint` 行动**:只有 hint 指向 `qiyu store init` 时才跑它,再跑 `qiyu sync run`;其余成因换 `--db` 路径或按 hint 安装依赖,原样重跑 `store init` 无效 |
31
+ | `kind: store_locked` | 本地库正被其他进程持有(同步进行中,或另一个只读会话;DuckDB 的读者共享锁同样会挡住写者)。退避后重试;期间可以先用已有数据做分析 |
32
+ | `kind: store_not_initialized` | 本地库不可用(不存在 / 缺表 / 不是本 CLI 的库 / 文件已损坏 / 依赖未安装)。**按 `hint` 行动**:只有 hint 指向 `qiyu store init` 时才跑它,再跑 `qiyu sync run`;**文件已损坏**时 hint 要求先备份该文件、再用 `--db` 指向新路径重建(对损坏文件原地跑 `store init` 修不好);其余成因换 `--db` 路径或按 hint 安装依赖,原样重跑 `store init` 无效 |
32
33
  | `kind: query_timeout` | 查询超时。缩小时间窗口、减少分组列或降低 `--limit` 后重试 |
33
34
  | `kind: sync_not_run` | 还没有成功同步过。这个 kind **只由 `sync install` 的前置探测产出**(`sync status` 不产出它,水位全为 null 时按 `SKILL.md` 的开场协议处理):先跑一次 `qiyu sync run` 让至少一个任务真正同步成功,再装调度 |
34
35