qiyu-cli 0.2.0 → 0.2.2

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 (70) hide show
  1. package/README.md +349 -57
  2. package/dist/cli.js +48 -7
  3. package/dist/commands/api-notes.js +54 -0
  4. package/dist/commands/api.js +113 -39
  5. package/dist/commands/auth.js +150 -28
  6. package/dist/commands/credentials-source.js +30 -5
  7. package/dist/commands/db-notes.js +75 -0
  8. package/dist/commands/db.js +112 -113
  9. package/dist/commands/query-notes.js +58 -0
  10. package/dist/commands/query.js +427 -56
  11. package/dist/commands/skill.js +477 -38
  12. package/dist/commands/spec-types.js +101 -1
  13. package/dist/commands/stats.js +139 -30
  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 +254 -0
  17. package/dist/commands/store.js +128 -75
  18. package/dist/commands/sync-notes.js +367 -0
  19. package/dist/commands/sync-run.js +155 -44
  20. package/dist/commands/sync.js +182 -121
  21. package/dist/core/config.js +274 -24
  22. package/dist/core/credentials.js +38 -4
  23. package/dist/core/edition.js +13 -3
  24. package/dist/core/envelope.js +73 -9
  25. package/dist/core/errors.js +73 -16
  26. package/dist/core/http.js +151 -52
  27. package/dist/core/ratelimit.js +5 -1
  28. package/dist/core/registry/index.js +26 -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 +64 -42
  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 +204 -28
  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 +129 -24
  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 +122 -27
  48. package/dist/skill/install.js +233 -43
  49. package/dist/skill/paths.js +54 -0
  50. package/dist/skill/qiyu/SKILL.md +38 -8
  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 +51 -5
  56. package/dist/store/retry.js +92 -4
  57. package/dist/store/schema.js +26 -3
  58. package/dist/sync/engine.js +257 -65
  59. package/dist/sync/registry.js +4 -0
  60. package/dist/sync/state.js +20 -0
  61. package/dist/sync/tasks/dim.js +23 -14
  62. package/dist/sync/tasks/knowledge.js +50 -8
  63. package/dist/sync/tasks/pipeline.js +29 -9
  64. package/dist/sync/tasks/reports.js +176 -49
  65. package/dist/sync/tasks/sessions.js +88 -21
  66. package/dist/sync/tasks/tickets.js +59 -8
  67. package/dist/sync/types.js +60 -1
  68. package/dist/sync/windowing.js +0 -22
  69. package/dist/sync/write-contract.js +47 -0
  70. package/package.json +1 -1
@@ -32,9 +32,11 @@ export const ERROR_KINDS = [
32
32
  // `--yes` 门禁拒绝时的 kind —— `api.ts` 的 `fail()` 产出它,
33
33
  // 对应 `code: 'confirm_required'`(危险接口未加 --yes),退出码 4
34
34
  'needs_confirmation',
35
- // 存储层(C1):数据库被写进程持锁(读者退避超限 / 写者立即)—— 退出码 1,可重试
35
+ // 存储层(C1):数据库被其他进程持有(读者退避超限 / 写者立即)。注意持有者**不一定
36
+ // 是写进程** —— DuckDB 的只读会话同样挡住写者(2026-11-05 审查实测)—— 退出码 1,可重试
36
37
  'store_locked',
37
- // 存储层(C1):库不存在 / 缺表 / 依赖缺失 / 非 DuckDB 文件 / 他人库 —— 退出码 1
38
+ // 存储层(C1):库不存在 / 缺表 / 依赖缺失 / 非 DuckDB 文件 / 文件已损坏 / 他人库
39
+ // —— 退出码 1
38
40
  'store_not_initialized',
39
41
  // 查询层(E):只读查询超时(conn.interrupt 生效)—— 退出码 1;
40
42
  // `output.ts` 的 `exitCodeFor` 不设分支,落 default(EXIT.BUSINESS)
@@ -47,6 +49,14 @@ export const ERROR_KINDS = [
47
49
  // 可被整体替换)—— 退出码 1,重试无用,必须由人执行 chmod 收紧密码。
48
50
  // ⚠️ 与 `auth_missing` 的区别:那是「没配」,这是「配了但落在不安全的位置」。
49
51
  'config_insecure',
52
+ // 配置层(2026-11-09 审计):配置文件的**内容**读不出来(畸形 JSON / 未知键 /
53
+ // 路径不是普通文件)—— 退出码 1,改参数修不好,必须先修文件。
54
+ // ⚠️ **权限拒绝不属于这里**:那是 `config_insecure`(`permissionReadError` / auth 的
55
+ // insecure 分支),修法是 chmod/icacls,不是改文件内容(CodeRabbit 2026-11-11 第十四轮:
56
+ // 旧注释把「权限拒绝」列在本 kind 的成因里,照着它分流会挑错 kind)。此前 `auth login`
57
+ // 把读失败报成 `kind: usage`(退出码 2),而退出码 2 的语义是「改参数重来」:换环境变量
58
+ // 不会修好损坏的 JSON(`auth whoami` 对同一状态是降级为 warning、退出 0)。
59
+ 'config_invalid',
50
60
  ];
51
61
  /** 抹掉服务端泄漏的内部实现细节。必须在任何 message 透出前调用。 */
52
62
  export function redactInternal(message) {
@@ -116,22 +126,30 @@ export function classify(code, rawMessage) {
116
126
  if (has(message, 'Too many running task'))
117
127
  return rate();
118
128
  // —— 14501 有两种含义,必须先按 message 区分(设计稿 §6.2)——
119
- // 跨度问题 → 调用方切片重试;对齐问题 → 必须把 endTime 对齐到自然日边界。
129
+ // 跨度问题 → 调用方切片重试;endTime 越界(晚于今天 0:00)→ 必须用纯历史日期。
120
130
  // 两者错误码相同、修复方式完全不同;一律当"跨度"会让 Agent 反复重试无效操作。
121
131
  if (String(code) === '14501') {
122
132
  if (has(message, 'endTime is invalid'))
123
133
  return { ...base, kind: 'window_misaligned', retryable: false,
124
- hint: 'endTime 必须对齐到自然日边界(不得晚于今天 00:00)' };
125
- if (has(message, 'is invalid'))
134
+ // ⚠️ 必须是「早于」而不是「不晚于」:实测 `endTime = 今天 0:00` 本身不稳定
135
+ // (有时 200 有时被拒,设计稿 §6.2),贴着等号的写法会把这条不稳定边界
136
+ // 当成安全上界教给 Agent。纯历史日期是唯一可靠做法。
137
+ hint: 'endTime 必须早于今天 00:00(用纯历史日期,不要包含今天的数据)' };
138
+ if (has(message, 'is invalid')) {
139
+ // ⚠️ 报文**不一定**带数字(2026-11-07 审查实测):`classify('14501','x is invalid')`
140
+ // 也命中本分支,而 hint 却让 Agent 去找一个不存在的数字。按报文实际形态分支。
141
+ const num = /(?:>|>=|超过|大于)\s*(\d+)/.exec(message)?.[1];
126
142
  return { ...base, kind: 'window_too_large', retryable: false,
127
143
  // ⚠️ 不要写"core 会重切" —— 本计划没有自动切片(见「已知缺口」),
128
144
  // 那样 Agent 会等一个永远不发生的重试。主用户是 Agent,hint 必须是它能执行的动作。
129
- //
130
- // 报文里带着服务端自己的上限(`> 31 is invalid` / `> 365 is invalid`),
131
- // 所以这里直接把那个数字指出来 —— 比让 Agent 去查注册表更可靠,
132
- // 因为 `maxWindowDays` 只有已实测的接口才有。
133
- hint: '时间跨度超出该接口上限。报文里的数字就是上限天数(如 `> 31` 即 31 天),' +
134
- '请按它切片后重试;`qiyu api list` 里带 max_window_days 的接口也标了上限' };
145
+ hint: num !== undefined
146
+ // 报文里带着服务端自己的上限(`> 31 is invalid` / `> 365 is invalid`),
147
+ // 直接把那个数字指出来 —— 比让 Agent 去查注册表更可靠。
148
+ ? `时间跨度超出该接口上限。报文里的数字就是上限天数(文中为 ${num}),` +
149
+ '请按它切片后重试;`qiyu api list` 里带 max_window_days 的接口也标了上限'
150
+ : '时间跨度超出该接口上限。报文里**不带**数字,' +
151
+ '请按 `qiyu api list` 里该接口的 max_window_days 切片后重试' };
152
+ }
135
153
  return { ...base, kind: 'unknown', retryable: false };
136
154
  }
137
155
  // —— 14004 与 14500 一样是多义码(设计稿 §4.3 明确要求分发表)——
@@ -154,6 +172,28 @@ export function classify(code, rawMessage) {
154
172
  // 而那正是静默少取约 58 天的路径。上限只有一个权威来源:注册表。
155
173
  hint: '时间跨度超出该接口上限。报文里不带数字,' +
156
174
  '请按 `qiyu api list` 里该接口的 max_window_days 切片后重试' };
175
+ if (has(message, 'appId not bind'))
176
+ // 实测(settings.wxTemplates 每次返回 `14004 appId not bind`):这是**账号没绑定
177
+ // 公众号**,不是请求参数问题。此前落到兜底 `param('核对字段名与类型')` —— Agent
178
+ // 会反复核对字段并重试,而真实动作是去后台绑定。错误出口必须点名真正的成因。
179
+ return { ...base, kind: 'module_offline', retryable: false,
180
+ hint: '该账号未绑定公众号(appId not bind)—— 不是字段或类型错误,改参数与重试都无效;' +
181
+ '请先在七鱼后台完成公众号绑定' };
182
+ if (message.toLowerCase().includes('timestamp interval limit'))
183
+ // 实测(2026-11-08 真实凭证,export.session):跨度**恰等于** maxWindowDays ×
184
+ // 86400000 毫秒(6 天 = 144.0h)也报本错 —— 518400000ms 拒绝、518399999ms 通过。
185
+ // 此前落到兜底 param(「核对字段名与类型」):成因完全指错,Agent 会反复核对
186
+ // 字段并原样重试。与「≤ 上界即可」的报表族不同,这个接口的边界是**开**的 ——
187
+ // 只说"缩小窗口"会让 Agent 切回恰好 N 天再撞一次,必须写出「严格小于」。
188
+ // ⚠️ 不得把成因说死(CodeRabbit 2026-11-08 minor):设计稿 §7.5 实测
189
+ // `start>end` / `start==end` / 窗口超限**三成因共用这个码且不可区分** ——
190
+ // 只写「跨度超限」时,start>=end 的用户会照着切片再撞一次。
191
+ return { ...base, kind: 'window_too_large', retryable: false,
192
+ hint: '最常见成因:时间跨度超出该接口上限 —— 且**恰好等于**注册表上界也会被拒' +
193
+ '(export.session 实测:跨度恰为 max_window_days×86400000 毫秒报本错,' +
194
+ '减 1 毫秒即通过)。请按「严格小于 max_window_days 天」的跨度切片后重试;' +
195
+ '⚠️ 同一报文也用于 start >= end(设计稿 §7.5:三成因共码、无法从报文区分)' +
196
+ '—— 若切片后仍报同一错误,先核对 start 严格小于 end' };
157
197
  return param('服务端拒绝了参数,请核对字段名与类型');
158
198
  }
159
199
  switch (String(code)) {
@@ -174,11 +214,23 @@ export function classify(code, rawMessage) {
174
214
  // ⚠️ 这里只列**实测出现过**的四个 5xx(500/502/503/504)+ 429;设计稿 §5.3 的措辞
175
215
  // 是「5xx/429」,但 501(未实现)/505(版本不支持)本身非瞬时,纳入重试反而有害。
176
216
  // 故本集合是"实测子集",不是"5xx 全集" —— 执行者若要扩到 501/505,须先确证它们是瞬时的。
177
- // ⚠️ 这组状态码必须与 http.ts 里 `res.json()` 失败分支的 `transient` 集合**逐字一致**
178
- // (两处都是 429/500/502/503/504)—— 否则同一个 500 会因代理返回 HTML 还是 Spring JSON
179
- // 被判成 internal 或 network,取决于代理行为,不是调用方能解释的差异。
180
- // 401/403 同理,两处都归 `auth`。
217
+ // ⚠️ **429 与 5xx 必须分开**(2026-11-04 修)。两者都是"没有正常业务响应",但副作用
218
+ // 语义**相反**:5xx(尤其 502/504)可能已经在服务端执行过业务逻辑;429 是"请求太频繁"
219
+ // —— 服务端在执行业务逻辑**之前**就拒绝了,肯定没有副作用。旧实现把 5xx/429 归成同一
220
+ // 个 `network`,危险接口的 429 会收到「请求可能已被服务端执行,重发会再执行一次」——
221
+ // 把一次确定未执行的限流劝阻成"先确认状态",方向反了;且 Agent 拿不到 retry_after,
222
+ // 只能瞎退避。归 `rate_limit` 后由 `call()` 统一附 retry_after 与来源说明。
223
+ // ⚠️ 与 http.ts 的 HTML 载体现已**刻意不同**:那里 429 走 rate_limit、5xx 走 network。
224
+ // 同一次 429/5xx 无论载体是 HTML 还是 Spring JSON,都必须落到同一个 kind ——
225
+ // 两处集合的**语义**一致即可,不要为了"逐字一致"把 429 塞回 5xx 组。
181
226
  case '429':
227
+ // ⚠️ 不要承诺「一定未执行」(CodeRabbit PR #65 指出):429 的标准语义是"限流拒绝",
228
+ // 但网关/代理可能在**转发之后**合成 429,此时上游是否执行过无法从响应判断。
229
+ // 对危险接口保留"先只读确认"的动作指引,不给"重发安全"的保证。
230
+ return { ...base, kind: 'rate_limit', retryable: true,
231
+ hint: '服务端限流(HTTP 429)—— 通常表示请求在执行业务逻辑之前被拒绝,' +
232
+ '但网关也可能在转发后合成 429:危险接口请先用只读接口确认当前状态再重试;' +
233
+ '读接口按 retry_after 等待后重试' };
182
234
  case '500':
183
235
  case '502':
184
236
  case '503':
@@ -192,7 +244,12 @@ export function classify(code, rawMessage) {
192
244
  case '14001':
193
245
  return { ...base, kind: 'auth', retryable: false, hint: '请检查 QIYU_APP_KEY 是否正确' };
194
246
  case '14002':
195
- return { ...base, kind: 'auth', retryable: false, hint: '签名不匹配,这是 CLI 的内部缺陷' };
247
+ // ⚠️ 不能断言「唯一成因是 CLI 自身」:checksum = SHA1(appSecret + md5(body) + time)
248
+ // (sign.ts),所以 **appSecret 配错**同样返回 14002(2026-11-07 审查)。此前
249
+ // 文案只说内部缺陷,Agent 会直接报 bug 而不去核对 QIYU_APP_SECRET。
250
+ return { ...base, kind: 'auth', retryable: false,
251
+ hint: '签名不匹配 —— 先核对 QIYU_APP_SECRET 是否为本应用的真实值'
252
+ + '(appSecret 参与 checksum 计算,配错同样报 14002);确认无误再按 CLI 缺陷上报' };
196
253
  case '14003':
197
254
  // core 层会**先用新时间戳重签重试一次**,正常情况下 Agent 不会看到这个错误。
198
255
  // ⚠️ 但 Agent 能看到它,就说明重签也没救回来 —— 那是**本机时钟真的偏移了**
package/dist/core/http.js CHANGED
@@ -2,7 +2,7 @@
2
2
  import { signedQuery } from './sign.js';
3
3
  import { classify } from './errors.js';
4
4
  import { normalize } from './envelope.js';
5
- import { TokenBucket, limitFor } from './ratelimit.js';
5
+ import { TokenBucket, limitFor, registeredRateLimit } from './ratelimit.js';
6
6
  import { redact } from './credentials.js';
7
7
  const BASE = 'https://qiyukf.com';
8
8
  /**
@@ -32,6 +32,83 @@ function bucketKey(spec) {
32
32
  function limitForSpec(spec) {
33
33
  return limitFor(spec.id);
34
34
  }
35
+ /**
36
+ * 解析 HTTP `Retry-After`(RFC 9110):秒数或 HTTP 日期两种形态;非法/缺失返回 undefined。
37
+ * 日期形态按注入时钟折算成秒(向上取整、不小于 0)——不要把"过去的时间"折成负数。
38
+ */
39
+ function parseRetryAfterSeconds(header, nowMs) {
40
+ if (!header)
41
+ return undefined;
42
+ const t = header.trim();
43
+ // delay-seconds 语法是 1*DIGIT,但 0 秒等于「立刻重试」——在 429 语境下必然再吃限流,
44
+ // 与 malformed 一样退回兜底(0 无法给出有意义的等待建议)。
45
+ if (/^\d+$/.test(t)) {
46
+ const n = Number(t);
47
+ return Number.isFinite(n) && n > 0 ? n : undefined;
48
+ }
49
+ // ⚠️ 不能直接 `Date.parse` 任何非数字串(CodeRabbit PR #65 第三轮):V8 的宽松日期解析
50
+ // 接受 `1.5`(→ 2001 年)、`-1`(→ 2001 年)这类非 HTTP-date 值,折算成"过去"后
51
+ // 被 max(0) 压成 0 秒 —— Agent 会立刻重试、再吃限流。HTTP-date 必然含英文星期/月份名,
52
+ // 用它做形态门(RFC 9110 的三种格式都满足)。
53
+ if (!/[A-Za-z]/.test(t))
54
+ return undefined;
55
+ const at = Date.parse(t);
56
+ if (Number.isNaN(at))
57
+ return undefined;
58
+ // ⚠️ 日期分支也必须要求**正数**(CodeRabbit PR #65 第四轮):过去的时间(或
59
+ // `May 1` 这种被宽松解析到过去的值)会算出 ≤0 —— 与秒数分支的 0 秒一样是
60
+ // "立刻重试",必须退回兜底而不是报 0。
61
+ const secs = Math.ceil((at - nowMs) / 1000);
62
+ return secs > 0 ? secs : undefined;
63
+ }
64
+ /**
65
+ * 限流错误的统一装饰:`retry_after` + 来源说明 + 三态 hint。
66
+ * 所有 `kind=rate_limit` 的出口(服务端业务码、HTTP 429 的两种载体)都必须经过这里 ——
67
+ * 否则同一类限流会因载体不同给出不同的等待建议(实测:HTTP 429 曾直接抛出,
68
+ * 从不附 retry_after)。本地令牌桶的 `local_rate_limit` 自带精确等待,不经过这里。
69
+ */
70
+ function decorateRateLimit(err, spec, serverSeconds) {
71
+ // ⚠️ 服务端 `Retry-After` 头优先于本地限频表(CodeRabbit PR #65):429 同时带
72
+ // `Retry-After: 3600` 时,限频表的 20/30 秒会诱导 Agent 提前重试、继续吃限流。
73
+ if (serverSeconds !== undefined) {
74
+ err.retryAfter = { seconds: serverSeconds, source: 'header' };
75
+ err.hint = `服务端通过 Retry-After 指定了等待 ${serverSeconds} 秒(最可信的来源,优先于本地限频表)。` +
76
+ (err.hint ? ` 原分类提示:${err.hint}` : '');
77
+ return err;
78
+ }
79
+ const limit = limitForSpec(spec);
80
+ // ⚠️ **必须标出这个数字的来源**(2026-10-05 修):设计稿 §11.2 D 的分流协议按
81
+ // `retry_after > 60` 二分(`> 60` → 不要 sleep,去查本地库),而**兜底值恰好就是 60**、
82
+ // 实测值里也真的有 60(ipcc 报表)—— 同一个数字承载不同的来源与可信度。
83
+ // ⚠️ 直接用**限频表自己的 `source`**,不要压成一个布尔:表里 6 行是 `'doc'`
84
+ // (文档值、从未实测),压成 `measured: true` 会把它们谎报成实测。
85
+ err.retryAfter = limit
86
+ ? { seconds: limit.windowSeconds, source: limit.source }
87
+ : { seconds: 60, source: 'fallback' };
88
+ // ⚠️ **三态**(2026-11-04 修):`limitFor` 把「未登记」与「显式 null(实测过、确实
89
+ // 没有限频)」压成同一个 null。旧 hint 一律说「未登记在本地限频表」—— 对显式 null 的
90
+ // 5 个接口(`export.session.check` 等)与 `api schema` 的 `rate_limit` 图例
91
+ // (「null = 实测过,确实没有限频」)直接矛盾:Agent 被告知"没测过",schema 刚说"测过"。
92
+ const registered = registeredRateLimit(spec.id);
93
+ if (registered === undefined) {
94
+ err.hint = '该接口未登记在本地限频表,下面的等待秒数是**保守兜底值、不是实测冷却**,' +
95
+ '可能短于服务端真实冷却(睡完仍可能再吃限频)。真实配额见接口文档。' +
96
+ (err.hint ? ` 原分类提示:${err.hint}` : '');
97
+ }
98
+ else if (registered === null) {
99
+ err.hint = '本表对该接口的实测结论是「没有限频」(不是没测过),但服务端本次确实限流 —— ' +
100
+ '以服务端为准;下面的等待秒数是保守兜底值、不是该接口的实测冷却。' +
101
+ (err.hint ? ` 原分类提示:${err.hint}` : '');
102
+ }
103
+ else if (limit?.source === 'doc') {
104
+ // ⚠️ `doc` 来源也必须说清(2026-10-07 补):秒数抄自厂商文档、**从未实测过**。
105
+ // 此前它与 `observed` 走同一段代码、hint 一字不差,等于把文档值当实测值报给 Agent。
106
+ err.hint = '下面的等待秒数取自**厂商文档、未对本租户实测**,' +
107
+ '真实冷却可能不同(睡完仍可能再吃限频)。' +
108
+ (err.hint ? ` 原分类提示:${err.hint}` : '');
109
+ }
110
+ return err;
111
+ }
35
112
  function bucketFor(spec) {
36
113
  const key = bucketKey(spec);
37
114
  let b = buckets.get(key);
@@ -104,6 +181,21 @@ function networkError(e, creds) {
104
181
  function isLocalRequestError(e) {
105
182
  return e instanceof TypeError && !e.cause;
106
183
  }
184
+ /**
185
+ * 危险接口遇到**网络类**故障时给 Agent 的 hint —— **唯一渲染点**。
186
+ *
187
+ * ⚠️ 三处载体必须共用这一句(2026-11-02 修):`fetch` 抛错、响应体读取失败、
188
+ * HTTP 5xx/429 的两种载体(网关 HTML / Spring JSON)。此前只有前两处写了对危险接口的
189
+ * 收窄说明,5xx 两处仍报「网关瞬时故障,请退避后重试」—— 同一个 `message.send`
190
+ * 在「连接断了」时被告知"可能已执行,先确认状态",在「网关 502」时被告知"退避重试",
191
+ * 而两者**同样可能已经执行**(502/504 恰恰是"上游收到请求后失败"的典型形态)。
192
+ * Agent 照后一句重试,就是一次确认变成两次执行。
193
+ * ⚠️ 逐字复制这条文案到新分支也算缺陷:新分支应当只调用本常量。
194
+ */
195
+ const DANGEROUS_NETWORK_HINT = '危险接口的网络故障**不会被自动重试** —— 请求可能已被服务端执行,重发会再执行一次。' +
196
+ '请先用只读接口确认当前状态,再决定是否重新调用';
197
+ /** 一次网络重试的退避(与 14003 重签重试**不共用**预算,见 call() 里的两个计数器)。 */
198
+ const networkBackoffMs = (attempt) => 300 * 2 ** attempt;
107
199
  /** 发起一次已签名调用。业务错误以分类后的异常抛出。 */
108
200
  export async function call(spec, body, opts) {
109
201
  const now = opts.now ?? (() => Date.now());
@@ -182,14 +274,11 @@ export async function call(spec, body, opts) {
182
274
  // 判定放在**抛出之前**:给 Agent 一个可重试的 network 错误,
183
275
  // 由它自己决定要不要再确认一次 —— 而不是 CLI 替它做这个决定。
184
276
  if (spec.dangerous) {
185
- throw Object.assign(new Error(err.message), err, {
186
- hint: '危险接口的网络故障**不会被自动重试** —— 请求可能已被服务端执行,' +
187
- '重发会再执行一次。请先用只读接口确认当前状态,再决定是否重新调用',
188
- });
277
+ throw Object.assign(new Error(err.message), err, { hint: DANGEROUS_NETWORK_HINT });
189
278
  }
190
279
  if (opts.noRetry || networkAttempts >= 2)
191
280
  throw Object.assign(new Error(err.message), err);
192
- await sleep(300 * 2 ** networkAttempts);
281
+ await sleep(networkBackoffMs(networkAttempts));
193
282
  networkAttempts++;
194
283
  continue;
195
284
  }
@@ -217,14 +306,11 @@ export async function call(spec, body, opts) {
217
306
  // 与 fetch 抛错那条分支保持同一套语义:危险接口不自动重发,
218
307
  // 读接口退避重试(预算与 fetch 失败共用 `networkAttempts`)。
219
308
  if (spec.dangerous) {
220
- throw Object.assign(new Error(err.message), err, {
221
- hint: '危险接口的网络故障**不会被自动重试** —— 请求可能已被服务端执行,' +
222
- '重发会再执行一次。请先用只读接口确认当前状态,再决定是否重新调用',
223
- });
309
+ throw Object.assign(new Error(err.message), err, { hint: DANGEROUS_NETWORK_HINT });
224
310
  }
225
311
  if (opts.noRetry || networkAttempts >= 2)
226
312
  throw Object.assign(new Error(err.message), err);
227
- await sleep(300 * 2 ** networkAttempts);
313
+ await sleep(networkBackoffMs(networkAttempts));
228
314
  networkAttempts++;
229
315
  continue;
230
316
  }
@@ -252,8 +338,38 @@ export async function call(spec, body, opts) {
252
338
  throw Object.assign(new Error(`请求被拒绝(HTTP ${status},返回的不是 JSON)`), { code: String(status), kind: 'auth', retryable: false,
253
339
  hint: `请求被拒绝(HTTP ${status})—— 凭证或权限问题,重试无用` });
254
340
  }
255
- const transient = status === 429 || status === 500 || status === 502 ||
341
+ // ⚠️ 429 先于 transient 处理(2026-11-04 修):429 是"请求太频繁",服务端在执行业务
342
+ // 逻辑之前就拒绝了,**没有副作用** —— 与 5xx(可能已执行)的语义相反。若留在这组
343
+ // transient 里,危险接口的 429 会收到 DANGEROUS_NETWORK_HINT("可能已被执行,重发会
344
+ // 再执行一次"),把确定未执行的限流劝阻成"先确认状态";且立即退避重试也不符合
345
+ // 限流语义(要按服务端冷却等)。这里抛 kind:rate_limit 并立即经 decorateRateLimit
346
+ // 附上 retry_after 与来源说明(与 Spring JSON 载体走同一条装饰路径);
347
+ // 不进入下面的自动重试预算 —— 立即重试只会继续吃限流。
348
+ if (status === 429) {
349
+ const e = Object.assign(new Error('响应不是合法 JSON(HTTP 429)—— 服务端限流'), { code: '429', kind: 'rate_limit', retryable: true,
350
+ hint: '服务端限流(HTTP 429)—— 通常表示请求在执行业务逻辑之前被拒绝,' +
351
+ '但网关也可能在转发后合成 429:危险接口请先用只读接口确认当前状态再重试;' +
352
+ '读接口按 retry_after 等待后重试' });
353
+ throw decorateRateLimit(e, spec, parseRetryAfterSeconds(res.headers.get('retry-after'), now()));
354
+ }
355
+ const transient = status === 500 || status === 502 ||
256
356
  status === 503 || status === 504;
357
+ // ⚠️ 危险接口的 5xx 同样可能已经执行(502/504 是"上游收到请求后失败"的典型形态),
358
+ // hint 必须与 fetch-throw / body-read 两支的收窄同源(DANGEROUS_NETWORK_HINT)——
359
+ // 此前这里对 message.send 仍说「请退避后重试」,Agent 照做就是二次执行。
360
+ if (transient && spec.dangerous) {
361
+ throw Object.assign(new Error(`网关/服务端故障(HTTP ${status})—— ` + DANGEROUS_NETWORK_HINT), { code: String(status), kind: 'network', retryable: true, hint: DANGEROUS_NETWORK_HINT });
362
+ }
363
+ // ⚠️ 瞬时 5xx 也必须走 core 的重试预算(2026-11-02 修):此前只有 fetch 抛错与
364
+ // body 读取失败两支会重试,5xx 直接抛出 —— 而 `sync/engine.ts` 的 `isTransient`
365
+ // 正是以「core 已重试 2 次」为前提**不**再重试网络类错误。实测:一次网关 502
366
+ // 只发 1 个请求就把整个窗口打成 fetch_failed gap,那次 502 成了"不可恢复"。
367
+ // 现在四支的预算一致(同一 `networkAttempts`)。
368
+ if (transient && !opts.noRetry && networkAttempts < 2) {
369
+ await sleep(networkBackoffMs(networkAttempts));
370
+ networkAttempts++;
371
+ continue;
372
+ }
257
373
  throw Object.assign(new Error(`响应不是合法 JSON(HTTP ${status})` +
258
374
  (transient ? '。这通常是网关/代理的瞬时故障,可退避重试' : '')),
259
375
  // 瞬时故障归为 `network`(退出码 3),与 fetch 抛错同一类 ——
@@ -292,48 +408,31 @@ export async function call(spec, body, opts) {
292
408
  }
293
409
  if (!norm.ok) {
294
410
  const err = classify(norm.code, norm.messageText);
411
+ // ⚠️ 危险接口 + 网络类失败(Spring 错误体里的 429/5xx 会经 classify 归成 network)
412
+ // 必须与另外三支同口径收窄(2026-11-02 修):Spring JSON 与网关 HTML 是**同一次
413
+ // 故障的两种载体**,此前只有 HTML 载体被收窄,Spring 载体的 `message.send` 仍收到
414
+ // 「服务端/网关瞬时故障,请退避后重试」—— Agent 照着重试就是二次执行。
415
+ // 只改 hint/文案,`retryable` 仍为 true(由 Agent 决定是否重新确认,与其它三支一致)。
416
+ // ⚠️ message 必须放在**最后**并过 `redact`(CodeRabbit PR #58):`Object.assign`
417
+ // 右覆盖左,写成 `Object.assign(new Error(文案), err)` 会让 `err.message`(含原始
418
+ // 凭证回显)把文案和脱敏结果一起冲掉 —— 与下面通用出口同一条坑。
419
+ if (spec.dangerous && err.kind === 'network') {
420
+ throw Object.assign(new Error(), err, {
421
+ message: redact(err.message, creds), hint: DANGEROUS_NETWORK_HINT,
422
+ });
423
+ }
295
424
  // 冷却秒数由**限频表**决定,不由分派器猜 —— 实测冷却随接口变化
296
- const limit = limitForSpec(spec);
297
425
  if (err.kind === 'rate_limit') {
298
- // ⚠️ **必须标出这个数字的来源**(2026-10-05 修)。
299
- // 此前是裸的 `{ seconds: N }`,Agent 分不出来:设计稿 §11.2 D 的分流协议
300
- // 按 `retry_after > 60` 二分(`> 60` → 不要 sleep,去查本地库),而**兜底值
301
- // 恰好就是 60**、实测值里也真的有 60(ipcc 报表)—— 同一个数字承载不同的
302
- // 来源与可信度,Agent 无从判断该不该信。
303
- // ⚠️ 直接用**限频表自己的 `source`**,不要压成一个布尔:表里 6 行是
304
- // `'doc'`(文档值、从未实测),压成 `measured: true` 会把它们谎报成实测。
305
- err.retryAfter = limit
306
- ? { seconds: limit.windowSeconds, source: limit.source }
307
- // 接口没登记限频、但服务端确实报了限流 —— 此时**必须**给个保守兜底,
308
- // 否则 Agent 收到限流却拿不到任何等待建议,只能立刻重试、继续吃 14009。
309
- //
310
- // ⚠️ **兜底值恰好等于设计稿 §11.2 D 的分流阈值(`retry_after > 60`),这是刻意的。**
311
- // 该协议说:`> 60` → 「**不要 sleep**;改为查询本地数据库」。
312
- // 本计划**没有 `store/`**(见「已知缺口」),所以"查询本地数据库"这条动作
313
- // 对本计划的 Agent **不可执行** —— 那等于把 Agent 指向一个不存在的能力。
314
- // 落在 `<= 60` 这一侧(可以 sleep)才是当前唯一可执行的下一步。
315
- // → **不要**为了让"未登记接口也走不要 sleep 分支"而把这个值改成 61:
316
- // 那会把 Agent 送去查一个本计划没有的数据库。等有 `store/` 之后再改,
317
- // 届时这个兜底值才有第二种正确取法。
318
- : { seconds: 60, source: 'fallback' };
319
- // ⚠️ 兜底时**必须**说清它不是实测值,并指明真正的配额要去哪查 ——
320
- // 否则 Agent 睡满 60 秒就重试,很可能再吃一次 14009。
321
- if (!limit) {
322
- err.hint = '该接口未登记在本地限频表,下面的等待秒数是**保守兜底值、不是实测冷却**,' +
323
- '可能短于服务端真实冷却(睡完仍可能再吃限频)。真实配额见接口文档。' +
324
- (err.hint ? ` 原分类提示:${err.hint}` : '');
325
- }
326
- else if (limit.source === 'doc') {
327
- // ⚠️ `doc` 来源也必须说清(2026-10-07 补)。限频表里 6 行是 `source: 'doc'`
328
- // —— 秒数抄自厂商文档、**从未实测过**。此前它与 `observed` 走同一段代码、
329
- // hint 一字不差,等于把文档值当实测值报给 Agent —— 与 `source` 存在的
330
- // 唯一目的(让 Agent 分辨该不该信)相反。
331
- // `source` 字段本身对 Agent 零解释(见「已知缺口」登记),所以 hint 是
332
- // 唯一能传达这件事的渠道 —— 与 `fallback` 那条同一条理由。
333
- err.hint = '下面的等待秒数取自**厂商文档、未对本租户实测**,' +
334
- '真实冷却可能不同(睡完仍可能再吃限频)。' +
335
- (err.hint ? ` 原分类提示:${err.hint}` : '');
336
- }
426
+ decorateRateLimit(err, spec, parseRetryAfterSeconds(res.headers.get('retry-after'), now()));
427
+ }
428
+ // ⚠️ 瞬时 5xx(Spring JSON 载体)也走 core 的重试预算,与上面四条网络分支
429
+ // 共用 `networkAttempts` —— 同一个 502 不该因为"代理回 HTML 还是 Spring JSON"
430
+ // 而一个重试、一个不重试。危险接口已在上面的分支提前抛出不重试。
431
+ // 429 不在其中:它归 rate_limit(未执行、需按冷却等待),不自动重试。
432
+ if (err.kind === 'network' && !opts.noRetry && networkAttempts < 2) {
433
+ await sleep(networkBackoffMs(networkAttempts));
434
+ networkAttempts++;
435
+ continue;
337
436
  }
338
437
  // ⚠️ message 必须放在**最后** —— Object.assign 是右覆盖左,
339
438
  // 若写成 Object.assign(new Error(redact(...)), err),err.message 会把
@@ -24,7 +24,11 @@ export const RATE_LIMITS = {
24
24
  'data.overview.session': { limit: 1, windowSeconds: 30, source: 'observed', scope: 'endpoint' },
25
25
  // 呼叫坐席/团队历史:实测约 20 秒冷却,超限返回 14402(设计稿 §4.3)
26
26
  'icoutcall.history.seat': { limit: 1, windowSeconds: 20, source: 'observed', scope: 'endpoint' },
27
- 'icoutcall.history.team': { limit: 1, windowSeconds: 20, source: 'observed', scope: 'endpoint' },
27
+ // ⚠️ team 的行来自文档值,不是对 team 路径实测的(2026-11-04 修):此前的 20 秒登记
28
+ // 与 seat 共用路径,"观测"实际打在 seat 上。设计稿把 team 的冷却记为「间隔 ≥5 分钟」——
29
+ // 那是文档值,实测数据只有 seat 的 20 秒。team 尚未实测,按**文档值**填 300 秒
30
+ // (source:'doc'),避免拿"未实测的 20 秒"当实测定去诱导 Agent 在真实冷却前重试。
31
+ 'icoutcall.history.team': { limit: 1, windowSeconds: 300, source: 'doc', scope: 'endpoint' },
28
32
  // 报表域:ipcc 是 10 次/60 秒滚动窗口(与其余报表的 30 秒不同)
29
33
  'data.overview.ipcc': { limit: 10, windowSeconds: 60, source: 'observed', scope: 'endpoint' },
30
34
  // 知识库取数接口实测也是 14009,且冷却长达数分钟(不是 30 秒)
@@ -127,7 +127,7 @@ export function loadSpecs(raw) {
127
127
  // message 里的 JSON 字符串**当成载荷原样返回**,Agent 拿到的是一段字符串
128
128
  // 而不是解析后的对象 —— 而它无从知道这是因为注册表拼错了字。
129
129
  // 与 dangerous 同理:枚举值必须在加载时校验,不能靠运行时兜底。
130
- const ENVELOPES = new Set(['A', 'B', 'C', 'D', 'D-nf']);
130
+ const ENVELOPES = new Set(['A', 'B', 'C', 'D', 'D-nf', 'M']);
131
131
  if (o.envelope !== null && !ENVELOPES.has(o.envelope)) {
132
132
  throw new Error(`specs.json[${o.id}] 的 envelope 取值非法:${JSON.stringify(o.envelope)}。` +
133
133
  `合法值为 ${[...ENVELOPES].join('/')} 或 null(未实测)。`);
@@ -161,6 +161,29 @@ export function loadSpecs(raw) {
161
161
  throw new Error(`specs.json[${o.id}] 的 auth 取值非法:${JSON.stringify(o.auth)}。` +
162
162
  '合法值为 checksum / eventType / none。');
163
163
  }
164
+ // ⚠️ **不变量:可调用 ⇒ auth 必须是 checksum**(2026-10-30 加)。
165
+ //
166
+ // `call()` 对**所有**出站请求无条件签名(`http.ts` 里没有 `auth` 分支),所以
167
+ // 一条 `callable: true` + `auth !== 'checksum'` 的记录,其 `auth` 值与实际
168
+ // 发出的请求**互相矛盾** —— Agent 若依据 `api schema` 里这个值判断「调它不用签名」,
169
+ // 会得到一个与真实契约不符的结论(契约诚实性缺陷:声明了但没人读、且与行为相反)。
170
+ //
171
+ // 当前实测(2026-10-30):154 条里 136 条 `checksum|callable`、7 条 `none|noncallable`、
172
+ // 2 条 `checksum|noncallable`、9 条 `eventType|noncallable` —— **没有**任何
173
+ // `callable && auth!=='checksum'`。所以这条不变量今天恒真,它守的是**将来**:
174
+ // 一旦有人接入一个「不需要签名」的出站接口并标 callable,加载期立刻炸,
175
+ // 逼他要么在 `call()` 里补上不签名分支、要么把 auth 改对,**不允许**带着
176
+ // 矛盾的声明上线。
177
+ //
178
+ // 这里**刻意不**在 `http.ts` 加 `if (spec.auth === 'none') 不签名` 的分支 ——
179
+ // 那会是一条当前不可达的死分支(没有可调用的 none 接口),是等价变异。等真有
180
+ // 这样的接口时,这条不变量会先炸,开发者据此再补分支,而不是现在就凭空写。
181
+ if (o.callable === true && o.auth !== 'checksum') {
182
+ throw new Error(`specs.json[${o.id}] 标记为可调用,但 auth 是 ${JSON.stringify(o.auth)}。` +
183
+ 'call() 对所有出站请求无条件签名,可调用接口的 auth 必须是 checksum —— ' +
184
+ '这一对矛盾说明「声明」与「实际请求」不一致,不允许上线。' +
185
+ '(若确有免签名接口,先给 call() 加不签名分支,再放开这条不变量。)');
186
+ }
164
187
  return o;
165
188
  });
166
189
  }
@@ -179,7 +202,8 @@ export function byId(id) {
179
202
  // ⚠️ 本文件在任务 6、output.ts 在任务 9,**无法 import describeArgs** —— 手写同一规则;
180
203
  // 将来若调整 describeArgs 的渲染,记得这里有一份副本(同 cli.ts 任务 1 的手写 JSON)。
181
204
  const shown = id.trim() === '' ? `'${id}'` : id;
182
- throw new Error(`未知接口:${shown}。可用 \`qiyu api list\` 查看全部接口 id。`);
205
+ throw new Error(`未知接口:${shown}。可用 \`qiyu api list --all\` 查看全部接口 id` +
206
+ '(默认列表只含可主动调用的接口;入站接口与不可调用项要加 --all 才显示)');
183
207
  }
184
208
  return spec;
185
209
  }
@@ -1,7 +1,22 @@
1
1
  {
2
- "params": [],
2
+ "params": [
3
+ {
4
+ "name": "key",
5
+ "in": "body",
6
+ "required": true,
7
+ "type": "string",
8
+ "description": "create 返回的任务 key"
9
+ },
10
+ {
11
+ "name": "code",
12
+ "in": "body",
13
+ "required": false,
14
+ "type": "string",
15
+ "description": "(可选,实测不校验)"
16
+ }
17
+ ],
3
18
  "responseShape": {
4
19
  "kind": "none"
5
20
  },
6
- "bodyKind": "none"
21
+ "bodyKind": "json"
7
22
  }
@@ -1,7 +1,29 @@
1
1
  {
2
- "params": [],
2
+ "params": [
3
+ {
4
+ "name": "start",
5
+ "in": "body",
6
+ "required": true,
7
+ "type": "integer",
8
+ "description": "窗口起点(毫秒时间戳,含)"
9
+ },
10
+ {
11
+ "name": "end",
12
+ "in": "body",
13
+ "required": true,
14
+ "type": "integer",
15
+ "description": "窗口终点(毫秒时间戳,不含)"
16
+ },
17
+ {
18
+ "name": "code",
19
+ "in": "body",
20
+ "required": false,
21
+ "type": "string",
22
+ "description": "(可选,实测不校验;不传误导性参数)"
23
+ }
24
+ ],
3
25
  "responseShape": {
4
26
  "kind": "none"
5
27
  },
6
- "bodyKind": "none"
28
+ "bodyKind": "json"
7
29
  }
@@ -1,7 +1,15 @@
1
1
  {
2
- "params": [],
2
+ "params": [
3
+ {
4
+ "name": "sessionId",
5
+ "in": "body",
6
+ "required": true,
7
+ "type": "string",
8
+ "description": "会话 id(单条查询,无需 code)"
9
+ }
10
+ ],
3
11
  "responseShape": {
4
12
  "kind": "none"
5
13
  },
6
- "bodyKind": "none"
14
+ "bodyKind": "json"
7
15
  }
@@ -1,7 +1,22 @@
1
1
  {
2
- "params": [],
2
+ "params": [
3
+ {
4
+ "name": "sessionId",
5
+ "in": "body",
6
+ "required": true,
7
+ "type": "string",
8
+ "description": "会话 id"
9
+ },
10
+ {
11
+ "name": "mTypes",
12
+ "in": "body",
13
+ "required": true,
14
+ "type": "string",
15
+ "description": "消息类型,逗号分隔字符串(传数组 → 14500)"
16
+ }
17
+ ],
3
18
  "responseShape": {
4
19
  "kind": "none"
5
20
  },
6
- "bodyKind": "none"
21
+ "bodyKind": "json"
7
22
  }