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.
- package/README.md +433 -72
- package/dist/cli.js +48 -7
- package/dist/commands/api-notes.js +70 -0
- package/dist/commands/api.js +169 -49
- package/dist/commands/auth.js +151 -29
- package/dist/commands/credentials-source.js +30 -5
- package/dist/commands/db-notes.js +75 -0
- package/dist/commands/db.js +165 -127
- package/dist/commands/query-notes.js +58 -0
- package/dist/commands/query.js +449 -61
- package/dist/commands/skill.js +445 -51
- package/dist/commands/spec-types.js +101 -1
- package/dist/commands/stats.js +160 -33
- package/dist/commands/store-flags.js +18 -0
- package/dist/commands/store-notes.js +38 -0
- package/dist/commands/store-precheck.js +321 -0
- package/dist/commands/store.js +165 -77
- package/dist/commands/sync-notes.js +374 -0
- package/dist/commands/sync-run.js +180 -47
- package/dist/commands/sync.js +232 -127
- package/dist/core/config.js +280 -24
- package/dist/core/credentials.js +38 -4
- package/dist/core/edition.js +1 -1
- package/dist/core/envelope.js +73 -9
- package/dist/core/errors.js +73 -16
- package/dist/core/http.js +175 -54
- package/dist/core/ratelimit.js +5 -1
- package/dist/core/registry/index.js +36 -2
- package/dist/core/registry/params/export.session.check.json +17 -2
- package/dist/core/registry/params/export.session.json +24 -2
- package/dist/core/registry/params/export.session.one.json +10 -2
- package/dist/core/registry/params/export.session.one.message.json +17 -2
- package/dist/core/registry/specs.json +65 -43
- package/dist/core/shell.js +30 -0
- package/dist/core/time.js +1 -1
- package/dist/core/validate.js +21 -2
- package/dist/output.js +215 -29
- package/dist/postinstall.js +14 -5
- package/dist/query/errors.js +145 -45
- package/dist/query/mask.js +1277 -25
- package/dist/query/metric-catalog.js +11 -0
- package/dist/query/native-error.js +189 -0
- package/dist/query/sandbox.js +148 -25
- package/dist/query/table-query.js +36 -5
- package/dist/schedule/install.js +136 -13
- package/dist/skill/check.js +11 -6
- package/dist/skill/detect.js +89 -29
- package/dist/skill/install.js +233 -43
- package/dist/skill/paths.js +54 -0
- package/dist/skill/qiyu/SKILL.md +29 -5
- package/dist/skill/qiyu/errors.md +5 -4
- package/dist/skill/qiyu/protocols.md +57 -5
- package/dist/skill/qiyu/setup.md +6 -2
- package/dist/store/config.js +92 -16
- package/dist/store/duckdb.js +1551 -64
- package/dist/store/object-kinds.js +32 -0
- package/dist/store/retry.js +190 -7
- package/dist/store/schema.js +32 -4
- package/dist/sync/engine.js +439 -77
- package/dist/sync/registry.js +6 -0
- package/dist/sync/state.js +20 -0
- package/dist/sync/tasks/dim.js +23 -14
- package/dist/sync/tasks/knowledge.js +50 -8
- package/dist/sync/tasks/pace.js +27 -0
- package/dist/sync/tasks/pipeline.js +29 -9
- package/dist/sync/tasks/reports.js +176 -49
- package/dist/sync/tasks/sessions.js +88 -21
- package/dist/sync/tasks/tickets.js +59 -8
- package/dist/sync/types.js +60 -1
- package/dist/sync/windowing.js +0 -22
- package/dist/sync/write-contract.js +79 -0
- package/package.json +2 -2
package/dist/commands/api.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
// src/commands/api.ts
|
|
2
|
-
import { allEndpoints, byId, assertCallable, assertConfirmed } from '../core/registry/index.js';
|
|
2
|
+
import { allEndpoints, byId, byIdOrUndefined, assertCallable, assertConfirmed } from '../core/registry/index.js';
|
|
3
3
|
import { resolveCredentialsUsingFile, currentCredentialEnv } from './credentials-source.js';
|
|
4
4
|
import { call } from '../core/http.js';
|
|
5
5
|
import { registeredRateLimit } from '../core/ratelimit.js';
|
|
@@ -7,9 +7,9 @@ import { loadValidationOverrides } from '../core/registry/validation-overrides.j
|
|
|
7
7
|
import { loadParams } from '../core/registry/params.js';
|
|
8
8
|
import { effectiveBodyParams, normalizeAliases, validateBody } from '../core/validate.js';
|
|
9
9
|
import { ok, fail, usageFail, describeArgs, setPretty, EXIT } from '../output.js';
|
|
10
|
-
import { sanitizeMessage } from '../core/sanitize.js';
|
|
11
10
|
import { localFallbackFor } from './local-fallback.js';
|
|
12
|
-
import {
|
|
11
|
+
import { callFieldNotes } from './api-notes.js';
|
|
12
|
+
import { GLOBAL_FLAGS, prettyAfterSubcommand, prettyPositionalProblem, REJECTED_FLAGS, renderFlagNames } from './spec-types.js';
|
|
13
13
|
/** `api list` 的业务 flag(`flags` 里还要再并上全局 flag)。 */
|
|
14
14
|
const LIST_FLAGS = [{ name: '--all', kind: 'bool' }];
|
|
15
15
|
/** `api call` 的业务 flag;顺序即「可用:」文案的顺序。 */
|
|
@@ -19,11 +19,12 @@ const CALL_FLAGS = [
|
|
|
19
19
|
{ name: '--no-validate', kind: 'bool' },
|
|
20
20
|
{ name: '--strict', kind: 'bool' },
|
|
21
21
|
];
|
|
22
|
-
/** `api schema` 没有业务 flag——只有全局 flag
|
|
22
|
+
/** `api schema` 没有业务 flag——只有全局 flag(`--pretty` 是可用的输出开关)。 */
|
|
23
23
|
const SCHEMA_FLAGS = [];
|
|
24
24
|
/**
|
|
25
25
|
* 命令契约(F 组 D4):`skill check` 据此判断 skill 正文里的 `qiyu api …` 是否真的存在。
|
|
26
|
-
* `flags` 是**完整接受集**(含全局 flag
|
|
26
|
+
* `flags` 是**完整接受集**(含全局 flag);`rejected` 直接取 `REJECTED_FLAGS`(当前为空 ——
|
|
27
|
+
* `--pretty` 自 2026-10-24 G1 起已实现,不再是 rejected,见 `spec-types.ts` 顶部)。
|
|
27
28
|
*/
|
|
28
29
|
export const API_SPECS = [
|
|
29
30
|
{
|
|
@@ -59,13 +60,19 @@ const LIST_KNOWN = new Set([...GLOBAL_FLAGS, ...LIST_FLAGS].map((f) => f.name));
|
|
|
59
60
|
const CALL_KNOWN = new Set([...GLOBAL_FLAGS, ...CALL_FLAGS].map((f) => f.name));
|
|
60
61
|
const SCHEMA_KNOWN = new Set([...GLOBAL_FLAGS, ...SCHEMA_FLAGS].map((f) => f.name));
|
|
61
62
|
/**
|
|
62
|
-
* 「可用:…」文案里的 flag 清单。`api list`
|
|
63
|
+
* 「可用:…」文案里的 flag 清单。`api list` 从常量渲染即可。
|
|
64
|
+
*
|
|
65
|
+
* ⚠️ 三条命令都必须列 `--pretty`(2026-11-06 审查):同一个拼错(`--prety`)此前得到
|
|
66
|
+
* 三种答案——`api list` 说「可用:--all」、`api call` 说「…--strict」、`api schema`
|
|
67
|
+
* 说「可用:--pretty」,而三条**都接受** `--pretty`。文案是给 Agent 的纠错依据,
|
|
68
|
+
* 漏列等于让它继续拼错。
|
|
63
69
|
* ⚠️ `api call` / `api schema` 的文案保持**字面量**:`readme.test.ts:58` 按**源文本**
|
|
64
70
|
* 钉着 `可用:--body <JSON>、--yes、--no-validate、--strict`,改成渲染会让它变红;
|
|
65
|
-
* 而两处的运行时文案又被 `api.test.ts`
|
|
71
|
+
* 而两处的运行时文案又被 `api.test.ts` 钉着。事实源仍是上面的 `FlagSpec` 常量
|
|
66
72
|
* ——`command-tree.test.ts` 有一条断言把文案里点名的 flag 与 spec 的接受集对齐。
|
|
67
73
|
*/
|
|
68
|
-
const
|
|
74
|
+
const PRETTY_FLAG = GLOBAL_FLAGS.find((f) => f.name === '--pretty');
|
|
75
|
+
const LIST_AVAILABLE = renderFlagNames([...LIST_FLAGS, PRETTY_FLAG]);
|
|
69
76
|
const API_USAGE = `用法:qiyu api <list|call|schema> [参数]
|
|
70
77
|
|
|
71
78
|
qiyu api list [--all] 列出接口
|
|
@@ -75,13 +82,13 @@ const API_USAGE = `用法:qiyu api <list|call|schema> [参数]
|
|
|
75
82
|
--all 连同不可主动调用的接口一起列出
|
|
76
83
|
--body 请求体(JSON 字面量)。省略与传 {} 是两条不同的服务端路径
|
|
77
84
|
--yes 危险接口(写/破坏性操作)必须显式确认
|
|
78
|
-
--no-validate 关闭 body
|
|
85
|
+
--no-validate 关闭 body 校验与别名改写(CLI 级安装提示照旧出现在 warnings;危险门禁不受影响)
|
|
79
86
|
--strict 把「未知字段/类型不符」的提示升级为拒绝
|
|
80
87
|
|
|
81
88
|
出错时 stdout 是 {"ok":false,"error":{code,kind,retryable,message,hint?}}。
|
|
82
89
|
⚠️ 请按 kind 分支,不要按 code —— code 只是个标签:它可能是服务端的
|
|
83
90
|
数字码(如 14009),也可能是本 CLI 合成的词(usage / network / internal /
|
|
84
|
-
auth_missing / config_insecure / confirm_required / store_locked / store_not_initialized / local_rate_limit / unknown)。合成词查不到官方错误码表。
|
|
91
|
+
auth_missing / config_insecure / config_invalid / confirm_required / store_locked / store_not_initialized / local_rate_limit / sync_not_run / unknown)。合成词查不到官方错误码表。
|
|
85
92
|
|
|
86
93
|
退出码:0 成功 · 1 业务错误 · 2 用法错误 · 3 网络错误 · 4 需要 --yes
|
|
87
94
|
`;
|
|
@@ -113,15 +120,19 @@ export async function apiCommand(argv) {
|
|
|
113
120
|
// 子命令之后(`api list --pretty`)。次序保持 **未知/位置 → help → pretty 指引**。
|
|
114
121
|
if (sub === '--pretty') {
|
|
115
122
|
const unknown = argv.slice(1).filter((a) => a.startsWith('-') && a !== '--pretty' && a !== '--help' && a !== '-h');
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
if (extra.length > 0) {
|
|
119
|
-
return usageFail(`未知参数:${describeArgs(extra)}。--pretty 不接受额外参数`);
|
|
123
|
+
if (unknown.length > 0) {
|
|
124
|
+
return usageFail(`未知参数:${describeArgs(unknown)}。--pretty 不接受额外参数`);
|
|
120
125
|
}
|
|
126
|
+
// ⚠️ 位置参数里的拼错子命令名必须在 help 之前拒绝(Codex 2026-11-08 第四轮 P2)——
|
|
127
|
+
// `api --pretty typo --help` 曾经把 typo 静默吞掉、help 退 0。
|
|
128
|
+
const badPos = prettyPositionalProblem(argv.slice(1), API_SPECS);
|
|
129
|
+
if (badPos !== undefined)
|
|
130
|
+
return usageFail(badPos);
|
|
121
131
|
if (argv.includes('--help') || argv.includes('-h')) {
|
|
122
132
|
process.stdout.write(API_USAGE);
|
|
123
133
|
return EXIT.OK;
|
|
124
134
|
}
|
|
135
|
+
// ⚠️ 位置参数按「顺序写反」引导(2026-11-07 审查)—— 见 db.ts 同款注释。
|
|
125
136
|
return usageFail(prettyAfterSubcommand('api'));
|
|
126
137
|
}
|
|
127
138
|
if (sub === 'list')
|
|
@@ -272,16 +283,29 @@ function list(argv) {
|
|
|
272
283
|
// 旧文「false = 仅有文档依据」——但 settings.wxTemplates 实测时真调用过
|
|
273
284
|
// (每次都 14004 appId not bind,错误模式有实测片段,只是成功路径没走通)。
|
|
274
285
|
// 全局只当**索引**:true/false 各自测到/没测到什么,以该行 note 为准。
|
|
275
|
-
verified: 'true =
|
|
276
|
-
'
|
|
286
|
+
verified: 'true = 该接口被真实观测过(不是「成功路径一定走通过」:验证了什么以该行 ' +
|
|
287
|
+
'note 为准 —— 可能是成功响应,也可能只是错误形态或不可调用状态,如 receive.message);' +
|
|
288
|
+
'没有 note 时只能按最弱含义理解「至少接触过真实服务」,不要假定成功路径已验证。' +
|
|
289
|
+
'false = 成功路径未实测(可能只有错误响应或纯文档依据)。具体范围只在该行有 note 时才有说明',
|
|
277
290
|
dangerous: 'true = 危险操作,调用时需 --yes',
|
|
278
291
|
// ⚠️ direction 也必须解释 —— 它是 Agent 判断「我方能调它」还是「它回调我方」
|
|
279
292
|
// 的唯一依据。只输出 `outbound`/`inbound` 两个英文词,Agent 无从知道哪个
|
|
280
|
-
// 是"我可以主动调用",可能对着 inbound 的接口去拼 URL
|
|
281
|
-
//
|
|
282
|
-
//
|
|
283
|
-
|
|
284
|
-
|
|
293
|
+
// 是"我可以主动调用",可能对着 inbound 的接口去拼 URL。与 verified/dangerous
|
|
294
|
+
// 同一条标准:只输出不解释 = 没输出。
|
|
295
|
+
//
|
|
296
|
+
// ⚠️⚠️ 措辞**不能**说「inbound 的 path 是占位符 `/`」(2026-11-02 审查实测):
|
|
297
|
+
// 那是全称断言,而 17 条 inbound 里 9 条是 `/`、**5 条有真实路径**
|
|
298
|
+
// (`get_token` `/get_token`、`get_order` `/get_order`、`get_user_info`
|
|
299
|
+
// `/get_user_info`、`get_call_order` `/get_call_order`、`get_call_user_info`
|
|
300
|
+
// `/get_call_user_info`,全部 `callable: false`)、3 条是 `null`(路径未收录)。
|
|
301
|
+
// 旧措辞会让 Agent 拿「path 是不是 `/`」当 inbound 的判据:看到 `/get_token`
|
|
302
|
+
// 就以为它可主动调用 —— 而它同样不可调用(这几条是**厂商推送给本方、由本方提供
|
|
303
|
+
// 的地址**,方向是入站)。真正的判据只有 `callable` 与 `direction` 两个字段。
|
|
304
|
+
direction: 'outbound = 本方主动调用它;inbound = 对方向本方推送(**一律不可主动调用**,'
|
|
305
|
+
+ '以 direction 与 callable 为准)。⚠️ inbound 的 path **不保证**是占位符 `/`:'
|
|
306
|
+
+ '多数(9/17)是占位符,另有若干是真实路径(如 `/get_token`)——那是厂商推送给'
|
|
307
|
+
+ '本方时用的地址,`direction: inbound` 的那些即便有真实路径也不可主动调用;'
|
|
308
|
+
+ '另有 3 条是 `null`(路径未收录,见 path 说明)。',
|
|
285
309
|
callable: 'false = 结构上不可主动调用(如 inbound 推送);Agent 只能查、不能调',
|
|
286
310
|
// ⚠️ **`path` 的两种"不可用"必须区分**(2026-10-05 加)。`api list --all` 会输出
|
|
287
311
|
// `path: null` 的行(`wecom.robot.switch` 的文档页 paths 键是中文散文、解析不出路径)。
|
|
@@ -292,8 +316,10 @@ function list(argv) {
|
|
|
292
316
|
// ② 认为该接口"方向未知"从而不去用它 —— 而它其实只是**路径未收录**。
|
|
293
317
|
// 必须点明:`null` = 路径未收录(数据缺口),不是"方向未知"也不是"不存在"。
|
|
294
318
|
path: '本行 path 的两种不可用形态含义不同:' +
|
|
295
|
-
'`null` =
|
|
296
|
-
'
|
|
319
|
+
'`null` = **路径未收录**(文档页未提供可用路径,是数据缺口;不代表接口不存在)。' +
|
|
320
|
+
'⚠️ 本注册表里 null 路径**必然伴随 callable=false**(加载器强制:callable 但无路径' +
|
|
321
|
+
'会直接拒绝加载,避免拼出 `…/null?appKey=`),即结构上不可主动调用;' +
|
|
322
|
+
'direction 仍可为 outbound —— 方向描述协议流向,不是可调用性;' +
|
|
297
323
|
'`"/"` = **入站推送的占位符**(path 是占位符不是真实路径,见 direction 说明)。' +
|
|
298
324
|
'两种情况都**不可**据此拼 URL 调用。',
|
|
299
325
|
// ⚠️ `max_window_days` 的语义必须解释 —— 它是最容易被误读的字段。
|
|
@@ -301,8 +327,10 @@ function list(argv) {
|
|
|
301
327
|
// 而字段只存一个数字。若不说明"按精确比较理解",Agent 会按向下取整
|
|
302
328
|
// 切到"31 天零 23 小时",然后在精确比较的接口(robot.statistic.summary)
|
|
303
329
|
// 上撞 14004 —— 而它无从知道是自己把上界理解松了。
|
|
304
|
-
max_window_days: '
|
|
330
|
+
max_window_days: '时间跨度上界(天),**按毫秒精确比较**:`end - start` 不得超过 `max_window_days * 86400000`。' +
|
|
305
331
|
'不要按"向下取整"切到 N 天零若干小时 —— 部分接口(robot.statistic.summary)会拒绝。' +
|
|
332
|
+
'⚠️ 边界开闭**随接口而变**:报表族实测恰好等于上界可接受;export.session 实测**恰好等于也会被拒**' +
|
|
333
|
+
'(14004 Timestamp interval limit,上界减 1ms 通过)—— 对它必须严格小于。拿不准时留出余量。' +
|
|
306
334
|
'未输出该键的接口没有已知上限',
|
|
307
335
|
// ⚠️ category 的**来源与稳定度**都必须说清:它是 Apifox 文档目录路径,
|
|
308
336
|
// 不是厂商 API 契约的一部分。不说清,Agent 会把它当稳定枚举去写分支逻辑
|
|
@@ -323,22 +351,29 @@ function list(argv) {
|
|
|
323
351
|
'⚠️ `--strict` 把「未知字段/类型不符」升级为拒绝,但那是「本地参数表闭集一致性」检查,' +
|
|
324
352
|
'**不是对服务端行为的保证**——参数表漏记时它会误拒合法字段,此时**不要删字段重试**。' +
|
|
325
353
|
'⚠️ 传错的字段可能被服务端以 **14004** 拒绝,也可能被**静默忽略**——**别把「返回成功」当作「字段写对了」**。',
|
|
354
|
+
// ⚠️ 这四个是 **meta 键**(不在行里),此前完全裸奔(2026-11-04 反向 sweep 实测):
|
|
355
|
+
// Agent 读 `registry_complete` 判断「能不能假定清单全」、读 `rows` 判断「拿到几条」,
|
|
356
|
+
// 而 `rows` 是**过滤后**的条数 —— 不与注册表总数相等是设计如此,不是数据缺口。
|
|
357
|
+
rows: '本次输出的行数(= data.length。缺省只列可主动调用的出站接口,所以不等于注册表总数)',
|
|
358
|
+
filter: '本次的过滤口径:`可主动调用`(缺省)= 只含 callable 且 outbound 的接口;`全部` = 带 --all,含入站与不可调用。不要拿缺省行数当注册表总量',
|
|
359
|
+
registry_complete: 'true = 本地注册表已收录全部接口(154 条);false = 尚未收录完整,未列出的接口不等于不存在',
|
|
360
|
+
registry_note: '上面那个布尔的人读说明(与 registry_complete 同源,同时输出不会自相矛盾)',
|
|
326
361
|
},
|
|
327
362
|
});
|
|
328
363
|
}
|
|
329
364
|
const SCHEMA_USAGE = `用法:qiyu api schema <接口id> [--pretty]\n\n 查看某接口的请求参数表(params)与响应形状(response_shape)。\n\n--pretty 输出缩进 JSON(人类可读;Agent 解析不需要它,默认紧凑输出已是合法 JSON)\n`;
|
|
330
365
|
async function schema(argv) {
|
|
331
366
|
const unknown = argv.filter((a) => a.startsWith('-') && !SCHEMA_KNOWN.has(a));
|
|
332
|
-
// ⚠️ 文案逐字保留 `可用:--pretty
|
|
333
|
-
//
|
|
367
|
+
// ⚠️ 文案逐字保留 `可用:--pretty`:`--help`/`-h` 是帮助开关、不进「可用参数」清单,
|
|
368
|
+
// `--pretty` 是唯一非业务的接受项(三条 api 子命令的清单口径一致,2026-11-06 审查)。
|
|
334
369
|
if (unknown.length > 0)
|
|
335
370
|
return usageFail(`未知参数:${describeArgs(unknown)}。可用:--pretty`);
|
|
336
371
|
const positional = argv.filter((a) => !a.startsWith('-'));
|
|
337
372
|
const help = argv.includes('--help') || argv.includes('-h');
|
|
338
|
-
// 3a/3b:help 优先于「缺 id」与「位置参数 > 1
|
|
373
|
+
// 3a/3b:help 优先于「缺 id」与「位置参数 > 1」。⚠️ 帮助请求不再校验位置参数
|
|
374
|
+
// (2026-11-06 审查):`api schema ticket.search --help` 是常规写法,此前被判
|
|
375
|
+
// 「未知参数:ticket.search」退 2 —— 而它正是用户想看帮助的那个 id。
|
|
339
376
|
if (help) {
|
|
340
|
-
if (positional.length > 0)
|
|
341
|
-
return usageFail(`未知参数:${describeArgs(positional)}。--help 不接受额外参数`);
|
|
342
377
|
process.stdout.write(SCHEMA_USAGE);
|
|
343
378
|
return EXIT.OK;
|
|
344
379
|
}
|
|
@@ -398,13 +433,51 @@ async function schema(argv) {
|
|
|
398
433
|
'⚠️ 限频桶是**进程内**的,跨 `qiyu api call` 不共享状态 —— 本表只用于告诉调用方' +
|
|
399
434
|
'「撞上限流后该等多久」,不承诺 CLI 会替你排队',
|
|
400
435
|
has_body_schema: 'true = 本接口有可比对的 body 参数表(body_kind 为 json 且 body 参数数 > 0);不代表本次请求已校验,也不代表其余 bodyKind。本次校验结果见 api call 的 meta.warnings',
|
|
401
|
-
body_kind: '只有 json 会被 api call
|
|
402
|
-
|
|
436
|
+
body_kind: '只有 json 会被 api call 比对字段;其余(none/xml/multipart/text/form)不做字段校验。' +
|
|
437
|
+
'⚠️ 但传输层**恒为 JSON**:请求体一律 `JSON.stringify`、Content-Type 恒 `application/json` —— ' +
|
|
438
|
+
'`--body` 必须是合法 JSON,xml/multipart/text 的原始字节(如 `<xml>...</xml>`)无法通过本 CLI 表达。' +
|
|
439
|
+
'需要此类编码的接口经 api call 实际不可用;传 JSON 对象给它们只会发出 JSON 字节,' +
|
|
440
|
+
'别把「返回成功」当成「字段按接口文档生效了」',
|
|
441
|
+
'params[].auto': 'true = 仅对 callable 且 auth 为 checksum 的接口,CLI 自填鉴权 query 参数(appKey/time/checksum);入站/eventType 接口由回调方提供,不标 auto,调用方不要也不能通过 --body 传',
|
|
442
|
+
// ⚠️ params[] 的元素键此前只解释了 `auto`,其余六个全裸奔(2026-11-04 反向 sweep 实测)。
|
|
443
|
+
// ⚠️⚠️ 2026-11-04 自查修正:`in` 的初版写成「该参数放哪里:path = 进路径占位符、
|
|
444
|
+
// header = 进请求头」,读起来像调用方有这四个通道 —— 而 api call 的 URL 是
|
|
445
|
+
// `${BASE}${spec.path}?${q}`(不做路径占位符替换),headers 只有硬编码的
|
|
446
|
+
// Content-Type。这正是本仓库在 http.ts 自己的注释里警告过的「不要写到不存在的
|
|
447
|
+
// 通道上」。只有 `in=body` 是调用方经 --body 亲手传的通道;query 鉴权三件套由
|
|
448
|
+
// CLI 自填;path/header 没有人工通道。同样的话不要再说回「放哪里」。
|
|
449
|
+
'params[].in': '参数在「上游协议」里的位置(文档口径,不等于本 CLI 给了你对应通道)。'
|
|
450
|
+
+ '`body` = 请求体 —— 唯一能由 `--body` 传的位置;`query` = URL 查询串 —— 本 CLI 只自填鉴权三件套(标 auto),'
|
|
451
|
+
+ '非鉴权的 query 参数只出现在不可主动调用的入站接口上;`path` = 路径占位符 —— 本 CLI 不做占位符替换,'
|
|
452
|
+
+ '带 path 参数的接口也都不可主动调用;`header` = 请求头 —— 现注册表里只有 content-type,由 CLI 固定发送。'
|
|
453
|
+
+ '⚠️ 不要把非 body 参数塞进 --body —— 只有该接口有 JSON body 参数表(has_body_schema=true)'
|
|
454
|
+
+ '且未加 --no-validate 时才会得到 unknown_field 提示;其余情形它照样随请求发出(不做字段检查;'
|
|
455
|
+
+ '整条 body 仍会被 JSON.stringify 重写为紧凑 JSON,不是逐字节原样)、服务端大概率忽略'
|
|
456
|
+
+ '(别把「返回成功」当成「字段生效了」)',
|
|
457
|
+
'params[].type': '参数类型(string/integer/array/object/boolean/number)。⚠️ 只有该接口 `body_kind=json`、'
|
|
458
|
+
+ '`in=body` 且本次传入的字段会被 api call 比对:类型不符是软告警(integer 要求整数,1.5 也判不符),'
|
|
459
|
+
+ '--strict 下升级为拒绝;非 body 参数与非 json body_kind 都不做类型校验',
|
|
460
|
+
'params[].required': '上游文档声明必填。⚠️ 本 CLI 只对 **`body_kind=json` 且 `in=body`** 的必填做校验:'
|
|
461
|
+
+ '缺了拒绝(退出码 2;--no-validate 时不校验)。非 json bodyKind(xml/multipart/text/form)**不做任何必填检查**,'
|
|
462
|
+
+ '缺字段照样发出。'
|
|
463
|
+
+ 'query 的鉴权三件套(required=true)与 header 的 content-type 由 CLI 自填、不用你传 —— '
|
|
464
|
+
+ '⚠️ 这只对 callable 且 `auth=checksum` 的接口成立;入站接口的 required=true 鉴权字段没有任何自动填充,'
|
|
465
|
+
+ '本 CLI 也没有它们的传参通道。path 参数只出现在不可主动调用的接口上。'
|
|
466
|
+
+ '⚠️ false 有两种含义:普通可选;或它在某个 one_of 组里(组内任一存在即可,不是「可省」)—— 看 one_of 判断',
|
|
467
|
+
'params[].name': '参数名。⚠️ 只有 `in=body` 的字段能作为 `--body` 的键传入:'
|
|
468
|
+
+ 'in=query 的鉴权三件套由 CLI 自填,in=path 只出现在不可主动调用的接口上,in=header 由 CLI 固定发送 —— 本 CLI 没有这三者的传参通道',
|
|
469
|
+
'params[].description': '参数的文档说明(来自厂商文档,原样透出,不做校验)',
|
|
470
|
+
'params[].example': '文档给的示例值。⚠️ 含 `{{appKey}}` 这类模板占位符的不是字面值:'
|
|
471
|
+
+ '鉴权三件套的占位符由 CLI 自填(别塞进 --body);其余含占位符的示例只出现在不可主动调用的入站接口上',
|
|
403
472
|
dangerous: 'true = 危险操作,调用时需 --yes,否则退出码 4。必须由人类确认,不要自动追加 --yes',
|
|
404
473
|
callable: 'false = 结构上不可主动调用(如 inbound 推送);Agent 只能查、不能调',
|
|
405
474
|
path: 'null = 路径未收录(数据缺口);"/" = 入站占位符。两者都不可据此拼 URL',
|
|
406
475
|
response_shape: '仅供参照,不做校验',
|
|
407
476
|
one_of: 'one_of 数组每项是一组「组内任一存在即可满足」的字段,全缺会被拒绝(退出码 2);组内字段的 required 已因此降为 false —— false 是「二选一」的意思,不是「两个都可省」',
|
|
477
|
+
// meta 的两个键(2026-11-04 反向 sweep 实测此前裸奔):`endpoint` 回显查询的
|
|
478
|
+
// 是哪个接口(与 data.id 同值);`note` 是注册表里的静态说明(同 api call 的 note)。
|
|
479
|
+
endpoint: '本次查询的接口 id(回显输入,用来把结果与请求对上)',
|
|
480
|
+
note: '该接口在注册表里登记的已知坑(只在登记了 note 的接口上出现)。⚠️ 它是静态说明,不是本次请求的结果',
|
|
408
481
|
},
|
|
409
482
|
});
|
|
410
483
|
}
|
|
@@ -415,8 +488,18 @@ async function schema(argv) {
|
|
|
415
488
|
}
|
|
416
489
|
async function callOne(argv) {
|
|
417
490
|
const [id] = argv;
|
|
491
|
+
// ⚠️ 本函数的**每一条**错误出口都要带 `unverified_endpoint`(CodeRabbit 2026-11-13),
|
|
492
|
+
// 包括 `byId()` 之前就返回的用法错误 —— 那时 `spec` 还是 undefined,
|
|
493
|
+
// 但 `id` 本身能查注册表(`byId` 只读内存里的注册表,不联网、不抛副作用)。
|
|
494
|
+
// 图例写着「键不出现 = 该接口实测过」,若 `api call ticket.finish --body '{'` 的
|
|
495
|
+
// 用法错误不带它,Agent 会反过来推断「这个接口是实测过的」—— 又是一句与事实相反的话。
|
|
496
|
+
let spec;
|
|
497
|
+
// ⚠️ 用闭包而不是当场求值:`spec` 在下方 `byId()` 才赋值,当场读会撞 TDZ。
|
|
498
|
+
// `spec` 一旦解析成功就以它为准,否则退回按 id 查(`byId()` 之前的出口)。
|
|
499
|
+
const mine = () => spec ? unverifiedMark(spec) : unverifiedMark(byIdOrUndefined(id));
|
|
500
|
+
const failCall = (msg) => usageFail(msg, undefined, mine());
|
|
418
501
|
if (!id) {
|
|
419
|
-
return
|
|
502
|
+
return failCall('用法:qiyu api call <接口id> [--body <JSON>] [--yes] [--no-validate] [--strict]');
|
|
420
503
|
}
|
|
421
504
|
// ⚠️ 接口 id 必须是第一个参数。若第一个 token 是 flag(`--yes`/`--body`/`--bod`…),
|
|
422
505
|
// 用户把 flag 写在了 id 之前 —— 此前它会落到 `byId('--yes')` 报出
|
|
@@ -438,7 +521,7 @@ async function callOne(argv) {
|
|
|
438
521
|
// `api call --pretty --help` 报「接口 id 必须是第一个参数」而不是给帮助 ——
|
|
439
522
|
// 缺 id 是硬错误,help 修不了它(与 `list()` 的「未知/位置参数 → help」同源)。
|
|
440
523
|
if (id.startsWith('-') && id !== '--help' && id !== '-h') {
|
|
441
|
-
return
|
|
524
|
+
return failCall(`用法:接口 id 必须是第一个参数,但你给的是 flag \`${id}\`。\n` +
|
|
442
525
|
'正确写法:qiyu api call <接口id> [--body <JSON>] [--yes] [--no-validate] [--strict]');
|
|
443
526
|
}
|
|
444
527
|
// ⚠️ **参数校验必须全部在 `byId(id)` 之前。** 此前它们是交错在 `byId`/
|
|
@@ -492,7 +575,7 @@ async function callOne(argv) {
|
|
|
492
575
|
// 退出码 2 的语义是"改参数重来",而这里没有任何东西需要改。
|
|
493
576
|
// → 判据是**"重复是否会丢掉一个值"**,不是"是否为布尔 flag"。
|
|
494
577
|
if (i >= 0 && argv.indexOf('--body', i + 1) >= 0) {
|
|
495
|
-
return
|
|
578
|
+
return failCall('用法:--body 只能出现一次');
|
|
496
579
|
}
|
|
497
580
|
// ⚠️ 未知参数必须报错,不能静默忽略。实测:`--bod '{"a":1}'`(拼错一个字母)
|
|
498
581
|
// 会被无声丢掉,请求照常发出、body 为 undefined,服务端返回的却是一个
|
|
@@ -523,7 +606,7 @@ async function callOne(argv) {
|
|
|
523
606
|
// ⚠️ 这一句保持**字面量**:`readme.test.ts:58` 按源文本逐字钉着它(含 `<JSON>` 占位符,
|
|
524
607
|
// 渲染无法无参复现)。`command-tree.test.ts` 有一条断言把这里点名的 flag 与
|
|
525
608
|
// `CALL_FLAGS` 对齐,所以它不会与 spec 漂移。
|
|
526
|
-
return
|
|
609
|
+
return failCall(`未知参数:${describeArgs(unknown)}。可用:--body <JSON>、--yes、--no-validate、--strict、--pretty`);
|
|
527
610
|
}
|
|
528
611
|
// ⚠️ **位置参数同样必须报错** —— 上面那条只筛 `-` 开头的。`api call` 除接口 id
|
|
529
612
|
// 外不接受任何位置参数,而此前它们被无声丢弃(实测 `call ticket.search extra`
|
|
@@ -544,7 +627,7 @@ async function callOne(argv) {
|
|
|
544
627
|
// 星号 —— 与 help 文本同一条规则:输出给谁看,就按谁的格式写。这句强调此前
|
|
545
628
|
// 写成了 `**body 必须用 --body 传入…**`,是 stderr 通道上唯一一处 Markdown。
|
|
546
629
|
// 哨兵在 tests/commands/api.test.ts 的「用法错误的 stderr 也不得出现 Markdown」。
|
|
547
|
-
return
|
|
630
|
+
return failCall(`未知参数:${describeArgs(positional)}。` +
|
|
548
631
|
'接口 id 之后的参数必须写成 --body <JSON> / --yes / --no-validate / --strict —— ' +
|
|
549
632
|
'body 必须用 --body 传入,直接写 JSON 会被忽略(那会发出一个没有 body 的请求)');
|
|
550
633
|
}
|
|
@@ -553,7 +636,7 @@ async function callOne(argv) {
|
|
|
553
636
|
const raw = argv[i + 1];
|
|
554
637
|
if (raw === undefined) {
|
|
555
638
|
// 静默当成 {} 会掩盖用户的输入错误,并可能触发"空 body"那条代码路径
|
|
556
|
-
return
|
|
639
|
+
return failCall('用法:--body 后面缺少 JSON 值');
|
|
557
640
|
}
|
|
558
641
|
try {
|
|
559
642
|
body = JSON.parse(raw);
|
|
@@ -562,7 +645,7 @@ async function callOne(argv) {
|
|
|
562
645
|
// ⚠️ 用 describeArgs 渲染,不裸插值(2026-10-07 修):`--body ''`(如 shell 变量未设置)
|
|
563
646
|
// 会让裸插值产出 `--body 不是合法 JSON:` —— 冒号后什么都没有,退出码 2 的全部信息量归零。
|
|
564
647
|
// 与 `describeArgs` 存在的理由完全同款(见 output.ts 该函数注释)。
|
|
565
|
-
return
|
|
648
|
+
return failCall(`--body 不是合法 JSON:${describeArgs([raw])}`);
|
|
566
649
|
}
|
|
567
650
|
}
|
|
568
651
|
// ⚠️ 次序与 `list()` 逐字一致:**未知/位置参数/值 → help → `--pretty`**(2026-10-08 修)。
|
|
@@ -589,12 +672,14 @@ async function callOne(argv) {
|
|
|
589
672
|
// ⚠️ 命令行已证明合法,现在才谈接口是否存在 / 可调用 / 需确认。
|
|
590
673
|
// 这三者都抛异常,由下方 catch 统一映射退出码(未知 id → usage 2、
|
|
591
674
|
// 不可调用 → usage 2、危险未确认 → needs_confirmation 4)。
|
|
592
|
-
// ⚠️ spec 提升到 try
|
|
675
|
+
// ⚠️ spec 提升到 try 外(已在函数顶部声明):catch 里的 mapThrownToExit 需要它来判断
|
|
593
676
|
// 「限流错误要不要附本地 fallback 建议」(G1)。byId 抛错时它仍是 undefined,
|
|
594
677
|
// 那种错误是 usage,走不到 fallback 分支。
|
|
595
|
-
|
|
678
|
+
/** 门禁分支的未实测标记(在 catch 里读 `spec` 前就算好,见 mapThrownToExit 头注释)。 */
|
|
679
|
+
let needsConfirmUnverified;
|
|
596
680
|
try {
|
|
597
681
|
spec = byId(id);
|
|
682
|
+
needsConfirmUnverified = unverifiedMark(spec);
|
|
598
683
|
assertCallable(spec);
|
|
599
684
|
assertGetHasNoBody(spec, body);
|
|
600
685
|
assertNoValidateStrictConflict(argv);
|
|
@@ -625,7 +710,7 @@ async function callOne(argv) {
|
|
|
625
710
|
// 避免「api 认配置文件、sync 只认环境变量」这种 Agent 看不出来的分叉。
|
|
626
711
|
const credOutcome = resolveCredentialsUsingFile(currentCredentialEnv());
|
|
627
712
|
if (!credOutcome.ok)
|
|
628
|
-
return fail(credOutcome.error);
|
|
713
|
+
return fail({ ...credOutcome.error, ...(mine() ? { unverifiedEndpoint: mine() } : {}) });
|
|
629
714
|
const creds = credOutcome.creds;
|
|
630
715
|
const r = await call(spec, body, { credentials: creds });
|
|
631
716
|
// ⚠️ 「成功但查无此物」必须显式标出来。设计稿 §9.2:0 行是比报错危险得多的
|
|
@@ -647,10 +732,19 @@ async function callOne(argv) {
|
|
|
647
732
|
// 该接口的 note 恰恰逐字写明了这个坑,而它就在注册表里,只差没被读。
|
|
648
733
|
// 只给有 note 的接口输出(`api list` 已是这个口径),保持两处一致。
|
|
649
734
|
return ok(r.payload, {
|
|
735
|
+
field_notes: callFieldNotes(),
|
|
650
736
|
endpoint: spec.id,
|
|
651
737
|
...(warnings.length ? { warnings } : {}),
|
|
652
738
|
...(r.notFound ? { not_found: true, warning: '接口返回成功但无数据' } : {}),
|
|
653
739
|
...(spec.note ? { note: spec.note } : {}),
|
|
740
|
+
// ⚠️ `verified === false` 必须在**调用时**说,不能只写在 `api list` 里
|
|
741
|
+
// (2026-11-13 审计):注册表 154 条里 74 条危险接口有 73 条未实测信封,
|
|
742
|
+
// 而 `verified` 此前只在 `api list` 输出、`callOne` 从不读 —— Agent 不先
|
|
743
|
+
// 跑 `api list --all` 就完全不知道「这个接口的响应信封只是按文档推的」。
|
|
744
|
+
// 后果具体:信封未实测时 `not_found` 判定与 `data` 语义可能不适用
|
|
745
|
+
// (`envelope.ts` 记着 `deleteKnowledges` 把「全部删成功」报成 `not_found` 的事故)。
|
|
746
|
+
// 只在**未实测**时输出,已实测的接口不带此键(避免变成对所有人的噪音)。
|
|
747
|
+
...(unverifiedOf(spec) ? { unverified_endpoint: true } : {}),
|
|
654
748
|
});
|
|
655
749
|
}
|
|
656
750
|
catch (e) {
|
|
@@ -671,6 +765,7 @@ async function callOne(argv) {
|
|
|
671
765
|
hint: '这是不可逆的写操作。**必须由人类确认**后再执行 —— 不要自动追加 --yes。' +
|
|
672
766
|
'请把该操作及其目标(接口 id 见 target)复述给人类,得到许可后才可重试。',
|
|
673
767
|
confirmRequired: true, target: err.target ?? id,
|
|
768
|
+
...(needsConfirmUnverified ? { unverifiedEndpoint: needsConfirmUnverified } : {}),
|
|
674
769
|
});
|
|
675
770
|
}
|
|
676
771
|
// 已分类的业务/网络错误与其余用法错误共用 mapThrownToExit,避免同族错误两种表现。
|
|
@@ -678,6 +773,28 @@ async function callOne(argv) {
|
|
|
678
773
|
return mapThrownToExit(e, spec);
|
|
679
774
|
}
|
|
680
775
|
}
|
|
776
|
+
/**
|
|
777
|
+
* 未实测信封的唯一判据(成功路径与三条错误出口共用同一实现,Codex 2026-11-13 P2)。
|
|
778
|
+
*
|
|
779
|
+
* ⚠️ 只在 `verified === false` 时输出:`spec` 为 undefined(未知 id)时无从谈起。
|
|
780
|
+
* 错误路径也要带:`unverified_endpoint` 的图例明说「错误分类只有文档依据」——
|
|
781
|
+
* 若错误分支沉默,Agent 会把未实测接口的错误分类当成确定结论。
|
|
782
|
+
*/
|
|
783
|
+
function unverifiedOf(spec) {
|
|
784
|
+
return spec?.verified === false ? { id: spec.id } : undefined;
|
|
785
|
+
}
|
|
786
|
+
/**
|
|
787
|
+
* 错误出口专用的"接口已定位"判据:只要定位到了接口,**无论实测与否都显式给出**
|
|
788
|
+
* `unverified_endpoint: true | false`。
|
|
789
|
+
*
|
|
790
|
+
* ⚠️ 为什么错误路径与成功路径口径不同(Codex 2026-11-13 P2):图例写「键不出现有两种可能」,
|
|
791
|
+
* 但对**已定位**的接口,Agent 需要的是确定答案而不是"可能"。成功路径保持只对未实测接口
|
|
792
|
+
* 输出(避免对所有人变成噪音),错误路径则两者都给出 —— 已实测时输出 `false`,
|
|
793
|
+
* 让「错误分类只有文档依据」这句话的适用范围不含糊。
|
|
794
|
+
*/
|
|
795
|
+
function unverifiedMark(spec) {
|
|
796
|
+
return spec ? { id: spec.id, verified: spec.verified === true } : undefined;
|
|
797
|
+
}
|
|
681
798
|
/** 把 catch 到的异常映射为退出码与输出 —— `callOne` 与 `api schema` **共用**的唯一出口(spec §三 :207)。
|
|
682
799
|
* 两类:① 已分类的业务/网络错误(kind!=='usage')→ 只出 stdout JSON(失败也 classification 直传);
|
|
683
800
|
* ② 其余(未知 id、不可调用、校验硬拒、`--no-validate`/`--strict` 冲突等)→ usage 双通道 + 退出码 2。
|
|
@@ -688,6 +805,7 @@ function mapThrownToExit(e, spec) {
|
|
|
688
805
|
// ⚠️ 用 `Partial<QiyuError>`(src/core/errors.ts:53,`retryAfter` 是 `{seconds,source}` 对象)——
|
|
689
806
|
// 不要写成 `retryAfter: number`(fail() 的入参类型是对象,tsc 会 TS2322 红)。
|
|
690
807
|
const err = e;
|
|
808
|
+
const unverifiedEndpoint = unverifiedMark(spec);
|
|
691
809
|
if (err.kind && err.kind !== 'usage') {
|
|
692
810
|
// —— 限流 → 本地 fallback 建议(G1 交付;设计稿 §9.1 示例里声明过这两个字段)——
|
|
693
811
|
//
|
|
@@ -729,16 +847,18 @@ function mapThrownToExit(e, spec) {
|
|
|
729
847
|
message: err.message ?? String(e), hint, retryAfter: err.retryAfter,
|
|
730
848
|
...(retryStrategy !== undefined ? { retryStrategy } : {}),
|
|
731
849
|
...(fallback !== undefined ? { fallback } : {}),
|
|
850
|
+
...(unverifiedEndpoint !== undefined ? { unverifiedEndpoint } : {}),
|
|
732
851
|
});
|
|
733
852
|
}
|
|
734
|
-
//
|
|
735
|
-
// ⚠️
|
|
736
|
-
//
|
|
737
|
-
//
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
853
|
+
// 用法错误走 `usageFail`(**唯一出口**,2026-11-02 收敛)。
|
|
854
|
+
// ⚠️ 这里曾是**手写的第三个出口**:自己净化、自己写 stderr、自己调 `fail()` ——
|
|
855
|
+
// 前两项与 `usageFail` 逐字重复(架构审查 F3 曾为此补过一次),第三项漏了它最重要的一条
|
|
856
|
+
// 契约:**用法错误永远是紧凑 JSON,即使 `--pretty` 已开启**(README「输出格式」/
|
|
857
|
+
// 设计稿 §11.2)。实测:`api call nosuchid --pretty` 与 `api call ticket.search --body '[]' --pretty`
|
|
858
|
+
// 都输出**缩进**的错误信封,而同一 exit 2 的 `api list extra --pretty`(走 usageFail)是紧凑的
|
|
859
|
+
// —— 同一退出码两种报文形态,而 Agent 会拿缩进当「格式化已生效」的证据。
|
|
860
|
+
// 那三条断言之所以没抓到:`tests/commands/api.test.ts` 只钉了走 `usageFail` 的那三条分支。
|
|
861
|
+
return usageFail(e instanceof Error ? e.message : String(e), err.hint, unverifiedEndpoint);
|
|
742
862
|
}
|
|
743
863
|
/** 私有:`--no-validate` 与 `--strict` 同传 → 抛普通 Error(→ 退出码 2)。 */
|
|
744
864
|
export function assertNoValidateStrictConflict(argv) {
|