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
package/dist/output.js CHANGED
@@ -51,13 +51,154 @@ function write(obj) {
51
51
  export function describeArgs(args) {
52
52
  return args.map((a) => (a.trim() === '' ? `'${a}'` : a)).join('、');
53
53
  }
54
+ /**
55
+ * 渲染「恢复命令必须指向**本次使用的库**」的完整命令(唯一实现,2026-10-30)。
56
+ *
57
+ * 背景(真库实测):hint 里写「请先运行:qiyu store init」时,若本次是用 `--db`/
58
+ * `--profile`/环境变量选了非默认库,逐字执行会作用在**默认库**上:
59
+ * · `db describe tickets --db <空库>` → 照 hint 跑 `qiyu store init` → 建出
60
+ * `~/.qiyu/duckdb/qiyu.duckdb`,原命令再跑仍报同一句(死循环,实测);
61
+ * · `sync install --db <未同步库>` → 照 hint 跑 `qiyu sync run` → 同步默认库,
62
+ * install 仍报 `sync_not_run`。
63
+ * 修法:点名的命令一律带**本次解析出的绝对路径** `--db <path>`。为什么用解析后的
64
+ * 路径而不是回显用户给的 flag:选择可能来自配置文件或环境变量(没有 flag 可回显),
65
+ * 而 `--db` 的优先级高于两者 —— 解析后的路径在任何来源下都精确复现本次目标,
66
+ * 且是绝对路径,换工作目录也成立。
67
+ *
68
+ * `syncRunCommand` 还要回显**档名**(CodeRabbit 2026-10-30 major):`--db` 只固定库文件,
69
+ * 而 `sync run` 还从**解析出的档**读 `store.options.knowledgeRobotIds` 与
70
+ * `profiles.<name>.robots`(robotId 注入面)。实测:同一份 config 下带 `--profile alpha`
71
+ * 解析出 `options={"knowledgeRobotIds":[1000001]}`、robots `["2000002"]`,不带则两者皆空 ——
72
+ * 只回显 `--db` 的 hint 会让知识库任务用错 robot 集合。`store init` 不读 options/robots
73
+ *(只跑迁移),故 `storeInitCommand` 不回显档名。
74
+ *
75
+ * ⚠️ 参数值经 `shellArg` 渲染(Python `shlex.quote` 同一安全集):路径/档名含空白或
76
+ * shell 元字符时用单引号包裹,否则裸渲染保持可读。**为什么必须引号**:hint 是给 Agent
77
+ * 复制执行的命令 —— 未引号的 `--db /tmp/x; touch /tmp/marker; #` 粘进 shell 会真的
78
+ * 执行 `touch`(CodeRabbit 2026-10-30 major)。
79
+ * ⚠️ 引号方言按平台选择(CodeRabbit 2026-10-30 第二条 major,pwsh 实测复现注入):
80
+ * POSIX shell 里单引号内的 `'` 转义为 `'\''`;**PowerShell 的反斜杠不是转义符**,
81
+ * 同一串会让引号提前闭合、后面的 `; touch …` 真的执行 —— win32 改用 PowerShell 方言
82
+ *(`''` 转义内嵌单引号)。win32 的 hint 面向 PowerShell(Windows 现代默认 shell);
83
+ * cmd.exe 不识别单引号、`&` 在引号外仍会切命令,**不要把 win32 的 hint 原样粘进
84
+ * cmd.exe**。这两个边界都如实记录,不假装一种引号能通吃所有 shell。
85
+ */
86
+ export function storeInitCommand(path, profileFlag) {
87
+ // 档名随路径一起带出(口径同 syncRunCommand):store init 也要落
88
+ // profiles.<name>.robots / store.options,重建出的库才是同一组数据。
89
+ return `qiyu store init --db ${shellArg(path)}`
90
+ + (profileFlag === undefined ? '' : ` --profile ${shellArg(profileFlag)}`);
91
+ }
92
+ /**
93
+ * `qiyu sync run` 恢复命令,指向本次解析出的库与档(口径见 `storeInitCommand`)。
94
+ * `profileFlag`:本次**有显式来源**的档名(flag / QIYU_PROFILE / defaultProfile,
95
+ * 由 `resolveStoreConfig().profileFlag` 给出);内置 default 不传 —— 显式
96
+ * `--profile default` 会触发「点名档必须存在」守卫,在 profiles 非空且无 default 档时
97
+ * 反而让恢复命令失败。
98
+ */
99
+ export function syncRunCommand(path, profileFlag) {
100
+ return `qiyu sync run --db ${shellArg(path)}`
101
+ + (profileFlag === undefined ? '' : ` --profile ${shellArg(profileFlag)}`);
102
+ }
103
+ /**
104
+ * 从**尚未解析**的 `--db`/`--profile` 原始取值构造定位(前置闭集校验阶段的用法)。
105
+ * 两者都没给 → `undefined`(渲染不带任何 flag,等价于默认解析)。
106
+ */
107
+ export function storeLocationFromFlags(flags) {
108
+ if (flags.db === undefined && flags.profile === undefined)
109
+ return undefined;
110
+ const loc = {};
111
+ if (flags.db !== undefined)
112
+ loc.db = flags.db;
113
+ if (flags.profile !== undefined)
114
+ loc.profile = flags.profile;
115
+ return loc;
116
+ }
117
+ /** 已解析出的库路径/档名 → 定位(命令层 `opened` 的用法)。 */
118
+ export function storeLocationOf(db, profile) {
119
+ return profile === undefined ? { db } : { db, profile };
120
+ }
121
+ /** `--db <p> [--profile <q>]`(带前导空格);两者都没有时返回空串。 */
122
+ export function storeLocationFlags(loc) {
123
+ if (loc === undefined)
124
+ return '';
125
+ let s = '';
126
+ if (loc.db !== undefined)
127
+ s += ` --db ${shellArg(loc.db)}`;
128
+ if (loc.profile !== undefined)
129
+ s += ` --profile ${shellArg(loc.profile)}`;
130
+ return s;
131
+ }
132
+ /** `qiyu db tables` 诊断命令,指向本次的存储定位(口径见 `StoreLocation`)。 */
133
+ export function dbTablesCommand(loc) {
134
+ return 'qiyu db tables' + storeLocationFlags(loc);
135
+ }
136
+ /**
137
+ * `qiyu db describe <表>` 诊断命令,指向本次的存储定位。
138
+ * `table` 只接受 `TABLES` 里的表名或占位符 `<表>`(代码内常量,不是用户输入)——
139
+ * 表中列名不承载外部输入,故原样渲染;路径/档名走 `shellArg`。
140
+ */
141
+ export function dbDescribeCommand(table, loc) {
142
+ return `qiyu db describe ${table}` + storeLocationFlags(loc);
143
+ }
144
+ /** `qiyu sync status` 诊断命令,指向本次的存储定位(sync 族同样接受三件套)。 */
145
+ export function syncStatusCommand(loc) {
146
+ return 'qiyu sync status' + storeLocationFlags(loc);
147
+ }
148
+ /** `qiyu query --table <表>` 诊断命令,指向本次的存储定位。 */
149
+ export function queryTableCommand(table, loc) {
150
+ return `qiyu query --table ${table}` + storeLocationFlags(loc);
151
+ }
152
+ /**
153
+ * `query --sql` hint 里占位符的**替换契约**(三处 hint 共用这一句,避免文案漂移)。
154
+ *
155
+ * 为什么必须写出来(CodeRabbit 2026-10-30 major):占位符在**引号里**,用户若只把
156
+ * `<SQL>` 这个词换掉、引号留着,SQL 里带单引号时就会把引号提前闭合 ——
157
+ * `--sql 'SELECT '2026-10-01''` 经 shell 解析后 CLI 收到的是 `SELECT 2026-10-01`
158
+ *(可能照跑并给出不同结果,是静默错误而不是报错)。正确做法是**整段(含引号)**
159
+ * 换成按当前 shell 规则引号化好的 SQL 参数。
160
+ */
161
+ export const SQL_ARG_REPLACE_NOTE = "`'<SQL>'` 要整段替换成按你的 shell 规则转义好的 SQL,不要只替换引号里的词";
162
+ /**
163
+ * `qiyu query --sql '<SQL>'` 诊断命令,指向本次的存储定位。
164
+ *
165
+ * ⚠️ 占位符不是装饰(CodeRabbit 2026-10-30 minor):`--sql` 是**取值** flag,
166
+ * 而 `commands/query.ts` 的值位守卫把「取值恰好是已知 flag」判为缺值 —— 渲染成
167
+ * `qiyu query --sql --db <path>` 时,`--db` 会被当成 `--sql` 的值位,逐字执行报
168
+ * 「--sql 缺少取值」并退出 2。**hint 里的命令必须真的能跑**,所以值位先给占位符,
169
+ * 定位 flag 排在它之后。
170
+ * 占位符**必须加引号**:SQL 含空格,`--sql SELECT 1` 在 shell 里会被拆成两个参数
171
+ *(`1` 落成位置参数 → 未知参数退出 2);`<`/`>` 不加引号还会变成重定向。
172
+ * 加引号的代价是替换契约必须一起说清 —— 见 `SQL_ARG_REPLACE_NOTE`,**用到本渲染器
173
+ * 的 hint 必须把它带上**(否则用户可能只替换引号内的词,见那里的静默错误说明)。
174
+ */
175
+ export function querySqlCommand(loc) {
176
+ return "qiyu query --sql '<SQL>'" + storeLocationFlags(loc);
177
+ }
178
+ /**
179
+ * `db tables` / `db describe` / `stats fields` 的超时 hint(2026-11-05 审查修)。
180
+ *
181
+ * 这三个命令的查询是**整表统计**,不接受 `--since`/`--until`/`--limit` —— `query` 那句
182
+ * 「缩小时间范围或加过滤条件」对它们是一条走不通的路。可执行的替代只有:稍后重试,
183
+ * 或改用 `query --sql`(它才有 `--timeout`)。渲染器指向本次的库,占位符替换契约一并带上。
184
+ */
185
+ export function metadataTimeoutHint(loc) {
186
+ return '本命令的统计按整表进行,没有可调的过滤参数;可稍后重试,或改用 `'
187
+ + querySqlCommand(loc) + '` 单独执行同类统计(该通道支持 --timeout 调整超时预算,'
188
+ + '0 = 不限时;' + SQL_ARG_REPLACE_NOTE + ')';
189
+ }
190
+ import { shellArg } from './core/shell.js';
191
+ export { shellArg };
54
192
  /** 把不受信文本(调用方 body 的字段名等)中的终端控制字符抹成占位,防止 stderr 注入 ANSI/OSC 序列。 */
55
193
  export { sanitizeControlChars, sanitizeMessage, stripSqlEcho } from './core/sanitize.js';
56
194
  // usageFail 的出口净化要用(re-export 不建立本地绑定)。
57
195
  import { sanitizeMessage } from './core/sanitize.js';
58
196
  export function ok(data, meta) {
59
197
  // ⚠️ `data` 必须**始终存在**,即便值是 undefined 也写成 null。
60
- // 设计稿 §9.1 的成功形态是 `{ok, data, meta}` —— 三个键都在。
198
+ // 设计稿 §9.1 的成功形态是 `{ok, data, meta}` —— 但只有 `ok`/`data` 恒在:
199
+ // `meta` 是**条件键**(有内容才出现,见下方两个分支与 `tests/output.test.ts`
200
+ // 「未提供 meta 时不输出该键」)。这条注释早前写的是「三个键都在」,与实现相反,
201
+ // 还经 README 传成了对 Agent 的承诺(2026-10-26 修正)。
61
202
  // 若直接 `{ ok: true, data }`,JS 的 JSON.stringify 会把值为 undefined 的键**整个丢掉**,
62
203
  // 于是 `ok(undefined)` 产出 `{"ok":true}`,Agent 无法区分
63
204
  // "这个接口没有载荷"(robot.transfer.config 实测就是这样)与"我解析错了"。
@@ -154,17 +295,47 @@ function exitCodeFor(kind) {
154
295
  export function fail(error) {
155
296
  // 入参驼峰、出参下划线。这一层改写是刻意的:
156
297
  // 内部改字段名不会破坏 Agent 契约,反之亦然。
298
+ //
299
+ // ⚠️ **净化必须在这唯一的错误出口做一次**(2026-11-02 第五轮审查,实测发现缺口):
300
+ // `message` 与 `hint` 里会拼进**调用方给的字节** —— `--db` 路径、表名、DuckDB 原文。
301
+ // 此前 `usageFail` / `failFromTagged` / `emitQueryFailure` 三个出口各自净化,而
302
+ // `fail()` 本体**没有**,于是走它直出的路径(`statGuard` 的库前置检查、
303
+ // `storeNotInitializedHint`、`thrownToExit` 的多数分支)把 C1 控制字符原样写进 stdout。
304
+ // 实测:`store status --db $'/tmp/x\u009b31mBAD.db'` 的 stdout 里出现原始字节
305
+ // `c2 9b 33 31 6d`(CSI 31m,终端里能改色/清屏),而同一路径在 `db describe` 的
306
+ // hint 里是 `·31m`(被净化过)—— **同一输入两种行为**,与本项目反复修的
307
+ // 「同一份规则复制到多处」同族。JSON.stringify **不会**转义 `\u007F-\u009F`
308
+ // (`\u009b` 原样输出),所以这层净化是终端注入的唯一防线。
309
+ //
310
+ // ⚠️ 净化**幂等**:上面三个出口已净化的消息再过一遍 `sanitizeMessage` 不变,
311
+ // 所以这里加一层不会让它们变成双重占位。
312
+ // ⚠️ 只净化**文本字段**:`retry_after` 是数字、`confirm_required` 等是布尔/闭集字面量,
313
+ // 不经过此函数;`target` 是回显给 Agent 的目标名(可能是路径/表名),一并净化。
157
314
  const e = {
158
- code: error.code, kind: error.kind, retryable: error.retryable, message: error.message,
315
+ // ⚠️ `code` 也必须净化(2026-11-07 审查实测):它常是服务端返回的不可信字段
316
+ // (`envelope.ts` 的 `String(o.code ?? 'unknown')`),实测服务端回
317
+ // `code:"\u009b31mX"`(CSI)时原始 C1 控制字节原样进 stdout —— 与本函数上方
318
+ // 「唯一防线」的思路同源,此前只漏了这一个字段。
319
+ code: sanitizeMessage(error.code), kind: error.kind, retryable: error.retryable,
320
+ message: sanitizeMessage(error.message),
159
321
  };
160
322
  if (error.hint)
161
- e.hint = error.hint;
323
+ e.hint = sanitizeMessage(error.hint);
162
324
  if (error.retryAfter)
163
325
  e.retry_after = error.retryAfter;
164
326
  if (error.retryStrategy)
165
327
  e.retry_strategy = error.retryStrategy;
166
328
  if (error.fallback)
167
329
  e.fallback = error.fallback;
330
+ if (error.unverifiedEndpoint) {
331
+ // ⚠️ 键名是 `unverified_endpoint`,语义是「**未**实测」—— 必须取反。
332
+ // 2026-11-13 实测踩过:这里曾直接赋 `verified`,于是已实测接口输出 `true`、
333
+ // 未实测输出 `false`,与成功路径(未实测才给 `true`)正好相反。
334
+ // 错误路径显式给 true/false:已实测的接口也要说 false,Agent 才不用去猜
335
+ // 「键不出现」是什么意思(见 `ErrorInput.unverifiedEndpoint` 的注释)。
336
+ e.unverified_endpoint = !error.unverifiedEndpoint.verified;
337
+ e.endpoint = sanitizeMessage(error.unverifiedEndpoint.id);
338
+ }
168
339
  // ⚠️ 确认字段与退出码必须由**同一个判据**决定,不能是两个独立闸门。
169
340
  // 设计稿 §9.1 要求退出码 4 **必须**携带 `confirm_required`/`confirm_arg`/`risk`/`target`
170
341
  // 且 `retryable: false`。此前 `exitCodeFor(kind)` 与 `if (error.confirmRequired)` 互相独立,
@@ -178,7 +349,7 @@ export function fail(error) {
178
349
  e.confirm_required = true;
179
350
  e.confirm_arg = '--yes';
180
351
  e.risk = 'irreversible';
181
- e.target = error.target ?? '';
352
+ e.target = sanitizeMessage(error.target ?? '');
182
353
  // ⚠️ 硬置为 false,不接受调用方给别的值 —— 让人工确认一个不可逆操作失败后
183
354
  // 自动重试,是最坏的结果(重复执行)。设计稿把这条写成「必须」。
184
355
  e.retryable = false;
@@ -188,6 +359,32 @@ export function fail(error) {
188
359
  write({ ok: false, error: e });
189
360
  return exitCodeFor(error.kind);
190
361
  }
362
+ /**
363
+ * 在**紧凑信封**下走一次 `fail()`(用法错误的唯一渲染口)。
364
+ *
365
+ * ⚠️ 契约(README「输出格式」/ 设计稿 §11.2):`--pretty` 只修饰**成功输出**,
366
+ * 用法错误(退出码 2)永远保持紧凑 —— 理由不是审美,而是「先修参数,再看格式」:
367
+ * 一个带缩进的错误信封恰好出现在「你这条命令根本没跑起来」的时刻,Agent 判断
368
+ * 格式是否生效时会拿它当「格式化已生效」的证据。
369
+ *
370
+ * ⚠️ `prettyOutput = false` 这一步**只在此一处**。此前 `usageFail` 自己写了一遍
371
+ * (只覆盖 `kind:'usage'`),而 `query/errors.ts` 的 `emitQueryFailure` 为保住真实
372
+ * code(`query_error` / `sandbox_blocked`)复刻了 stderr 写法却**没复刻这一句**,
373
+ * 于是 `query --sql 'SELEC 1' --pretty` 输出缩进信封、退出码 2 —— 同一契约两个结果。
374
+ * 复刻一处必然漏另一处,故收敛到这里。
375
+ */
376
+ export function failCompact(error) {
377
+ const prevPretty = prettyOutput;
378
+ prettyOutput = false;
379
+ try {
380
+ return fail(error);
381
+ }
382
+ finally {
383
+ // 还原:用法错误是命令的终点,但同进程内连续多次 `run()`(测试里常见)时,
384
+ // 下一条命令不该因为上一条报了个用法错误就丢掉它的 `--pretty`。
385
+ prettyOutput = prevPretty;
386
+ }
387
+ }
191
388
  /**
192
389
  * 用法错误(退出码 2)的统一出口。
193
390
  *
@@ -223,41 +420,30 @@ export function fail(error) {
223
420
  export function failFromTagged(e) {
224
421
  const err = e;
225
422
  if (err.kind) {
423
+ // ⚠️ 净化必须在出口做(与 usageFail 同一约定):带 kind 的错误也会拼进路径/服务端原文,
424
+ // 此前这条分支直接透传 —— 而调用方换成 failFromTagged 后,原本 usageFail 里的净化就
425
+ // 消失了。sanitizeMessage 保留换行结构,正常文案一字不变。
226
426
  return fail({
227
427
  code: err.code ?? 'unknown', kind: err.kind, retryable: err.retryable ?? false,
228
- message: err.message ?? String(e), hint: err.hint,
428
+ message: sanitizeMessage(err.message ?? String(e)),
429
+ ...(err.hint !== undefined ? { hint: sanitizeMessage(err.hint) } : {}),
229
430
  });
230
431
  }
231
432
  return usageFail(sanitizeMessage(err.message ?? String(e)));
232
433
  }
233
- export function usageFail(message, hint) {
434
+ export function usageFail(message, hint, unverifiedEndpoint) {
234
435
  // ⚠️ stderr 是不受信文本进终端的主通道(security S4):未知参数、未知表名、DuckDB 原文
235
436
  // 都拼进 message,未经净化就能注入 ANSI/OSC 序列。净化必须在**出口**做一次,
236
437
  // 而不是靠每个调用点自觉补 —— 实测 `db describe` / `query --table` 的未知表路径补了、
237
438
  // 而同文件的 `未知参数` / `--help` 多余参数路径没补,两种行为并存正是缺口的来源。
238
439
  const safe = sanitizeMessage(message);
239
440
  process.stderr.write(safe.endsWith('\n') ? safe : safe + '\n');
240
- // ⚠️ 用法错误**永远是紧凑 JSON**,即使 `--pretty` 已开启(CodeRabbit 2026-10-25 实测发现)。
241
- // 契约写在 README「输出格式」与设计稿 §11.2:`--pretty` 只修饰**成功输出**,
242
- // 用法错误(退出码 2)保持紧凑 —— 理由不是审美,而是"先修参数,再看格式":
243
- // 一个带缩进的错误信封恰好出现在"你这条命令根本没跑起来"的时刻,
244
- // 而 Agent 判断格式是否生效时会拿它当"格式化已生效"的证据。
245
- // 此前有多条分支在 `setPretty(true)` **之后**才报用法错误(如 `api schema --pretty`
246
- // 缺 id、`auth login --pretty` 缺环境变量),那些路径输出的就是缩进错误信封。
247
- // 现在在唯一的出口处强制收窄 —— 逐个调用点调整次序既脆弱又会随新分支漂移。
248
- const prevPretty = prettyOutput;
249
- prettyOutput = false;
250
- try {
251
- return fail({
252
- code: 'usage', kind: 'usage', retryable: false,
253
- // message 去尾换行 —— stdout 的 JSON 里不该带控制字符;stderr 的文本保留换行便于阅读。
254
- message: safe.replace(/\n+$/, ''),
255
- ...(hint !== undefined ? { hint: sanitizeMessage(hint) } : {}),
256
- });
257
- }
258
- finally {
259
- // 还原:用法错误是命令的终点,但同进程内连续多次 `run()`(测试里常见)时,
260
- // 下一条命令不该因为上一条报了个用法错误就丢掉它的 `--pretty`。
261
- prettyOutput = prevPretty;
262
- }
441
+ // ⚠️ 用法错误**永远是紧凑 JSON**,即使 `--pretty` 已开启 —— 契约与理由见 `failCompact`。
442
+ return failCompact({
443
+ code: 'usage', kind: 'usage', retryable: false,
444
+ // message 去尾换行 —— stdout 的 JSON 里不该带控制字符;stderr 的文本保留换行便于阅读。
445
+ message: safe.replace(/\n+$/, ''),
446
+ ...(hint !== undefined ? { hint: sanitizeMessage(hint) } : {}),
447
+ ...(unverifiedEndpoint !== undefined ? { unverifiedEndpoint } : {}),
448
+ });
263
449
  }
@@ -95,11 +95,20 @@ export async function runPostinstall(opts) {
95
95
  force: false,
96
96
  ...(entityDir !== undefined ? { entityDir } : {}),
97
97
  });
98
- // 措辞按**实际**结果(审查 B2):计划要写、实际零写入时 status 是 skipped,
99
- // 说「已是最新,跳过」是谎报——此时正文其实没跟上包内版本。
100
- const label = result.status === 'skipped'
101
- ? (result.plannedStatus === 'skipped' ? '已是最新,跳过' : '未完成更新(详见下方提示)')
102
- : `已安装(${result.status})`;
98
+ // 措辞按**实际**结果(审查 B2):
99
+ // · `upToDate`(正文与清单都是包内那份)→ 「已是最新,跳过」;
100
+ // · 其余 `status === 'skipped'` → 「未完成更新」。
101
+ // ⚠️ 判据**不能**写成「`status === 'skipped' && plannedStatus === 'skipped'`」
102
+ // (2026-11-02 审查实测):`planInstall` 的 `skipped` 有四种含义,其中「内容不同且
103
+ // 未加 `--force`」「清单被非普通文件占用」「实体目录列不出来」三种都零写入且**没跟上**,
104
+ // 但 `plannedStatus` 同样是 `'skipped'` —— 旧写法把它们全说成「已是最新」,
105
+ // 紧接着下一行又打印「内容与包内不同,未覆盖」,同一进程两行自相矛盾(实测复现)。
106
+ // 判据现由 `installSkill` 算成 `result.upToDate` 一个字段(见 install.ts 的说明)。
107
+ const label = result.upToDate
108
+ ? '已是最新,跳过'
109
+ : result.status === 'skipped'
110
+ ? '未完成更新(详见下方提示)'
111
+ : `已安装(${result.status})`;
103
112
  note(`skill ${label}:${result.entityDir}`);
104
113
  if (result.warnings.length > 0) {
105
114
  // 零链接(审查 B3 / #58)等提示同样要出现在 npm 自动安装路径上。