qiyu-cli 0.2.2 → 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 +156 -84
- package/dist/commands/api-notes.js +16 -0
- package/dist/commands/api.js +60 -14
- package/dist/commands/auth.js +1 -1
- package/dist/commands/db.js +58 -19
- package/dist/commands/query.js +25 -8
- package/dist/commands/stats.js +22 -4
- package/dist/commands/store-precheck.js +72 -5
- package/dist/commands/store.js +46 -11
- package/dist/commands/sync-notes.js +13 -6
- package/dist/commands/sync-run.js +28 -6
- package/dist/commands/sync.js +56 -12
- package/dist/core/config.js +6 -0
- package/dist/core/edition.js +1 -1
- package/dist/core/http.js +24 -2
- package/dist/core/registry/index.js +10 -0
- package/dist/core/registry/specs.json +2 -2
- package/dist/output.js +11 -1
- package/dist/query/sandbox.js +19 -1
- package/dist/store/duckdb.js +1500 -59
- package/dist/store/object-kinds.js +32 -0
- package/dist/store/retry.js +98 -3
- package/dist/store/schema.js +6 -1
- package/dist/sync/engine.js +209 -39
- package/dist/sync/registry.js +3 -1
- package/dist/sync/tasks/pace.js +27 -0
- package/dist/sync/write-contract.js +32 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -41,7 +41,10 @@ cd qiyu-cli && npm install && npm run build
|
|
|
41
41
|
|
|
42
42
|
> 核心命令(`auth`、`api`)零运行时依赖。`store` / `db` / `query` / `stats` 命令需要
|
|
43
43
|
> `@duckdb/node-api`(可选依赖,缺失时会给出安装指引)——`npm install` 会默认安装它。
|
|
44
|
-
> 该包含平台原生二进制,实测安装体积约 130 MB
|
|
44
|
+
> 该包含平台原生二进制,实测安装体积约 130 MB。
|
|
45
|
+
> `sync` 命令**零常规运行时依赖**:会话导出的加密 zip 解压走 Node 内置 `DecompressionStream`
|
|
46
|
+
> (zip 容器解析与 ZipCrypto 解密是本仓库内的实现);`fflate` 只在测试里用来合成加密 zip
|
|
47
|
+
> 夹具,见 `devDependencies`。
|
|
45
48
|
|
|
46
49
|
### 装完之后:安装 skill(推荐)
|
|
47
50
|
|
|
@@ -97,6 +100,8 @@ qiyu auth whoami
|
|
|
97
100
|
# {"ok":true,"data":{"configured":true,"source":"env","profile":"default","robots":[]}}
|
|
98
101
|
```
|
|
99
102
|
|
|
103
|
+
### 把凭证写进配置文件
|
|
104
|
+
|
|
100
105
|
也可以把凭证**写进配置文件**;之后除非用 `--profile` 指定了非 default 档,否则不必每次 export:
|
|
101
106
|
|
|
102
107
|
```bash
|
|
@@ -129,6 +134,8 @@ shell 历史与 `ps` 输出里)。它把配置写到 `~/.config/qiyu/config.js
|
|
|
129
134
|
空白串(`--db ' '`)不是空串,两者都拒绝,且报错点名**真正给了空白值的那一层**
|
|
130
135
|
(旧文案把三个来源一起指控为「均为空」,明明配了值的 `profiles.<name>.store.path` 也在其列)。
|
|
131
136
|
|
|
137
|
+
### 配置文件结构
|
|
138
|
+
|
|
132
139
|
配置文件的完整结构(**顶层 / profile / store 三层的键名写错会被拒绝,退出码 2**):
|
|
133
140
|
|
|
134
141
|
```json
|
|
@@ -166,23 +173,35 @@ shell 历史与 `ps` 输出里)。它把配置写到 `~/.config/qiyu/config.js
|
|
|
166
173
|
`profiles` 里也不报错)。空串口径:`--profile ''` 是 usage 错误;`QIYU_PROFILE=` 与
|
|
167
174
|
`"defaultProfile": ""` 视为未设置。
|
|
168
175
|
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
176
|
+
### 配置文件权限规则
|
|
177
|
+
|
|
178
|
+
判据只有一条:配置文件**含凭证**且 group/other 有**任何**权限位(如 `0644` 可读、`0622` 只写、
|
|
179
|
+
`0601` 仅 other 可执行)即拒绝读取(判据 `mode & 0o077 !== 0`)。可读时落盘的 appSecret 对同机
|
|
180
|
+
其他用户可读,其余组合也不该放宽。父目录 group/other **可写**(文件可被整体替换)时同样拒绝。
|
|
181
|
+
|
|
182
|
+
**任何读取配置的命令**都会拒绝:`kind: config_insecure`、退出码 1,hint 点名要执行的 `chmod`。三档成因与修法:
|
|
183
|
+
|
|
184
|
+
| 成因 | hint |
|
|
185
|
+
|---|---|
|
|
186
|
+
| 文件权限过宽 | `chmod 600 <文件>` |
|
|
187
|
+
| 文件**读不出来**(`EACCES` / `EPERM`)—— 是权限问题,不是配置内容问题 | `chmod 600 <文件>` |
|
|
188
|
+
| 配置**目录**不可搜索(进不去、连文件都 stat 不到) | `chmod 700 <目录>` |
|
|
189
|
+
|
|
190
|
+
目录挡路时**不能**建议对文件 chmod —— 那个状态下这条命令本身就执行不了,也不会把
|
|
191
|
+
「目录挡路」说成「凭证缺失」。Windows 上「过宽」判据不适用(只看 POSIX 权限位),
|
|
192
|
+
但**读被拒绝**(NTFS ACL)同样报 `config_insecure`,此时 hint 是 `icacls <路径> /reset`
|
|
193
|
+
(恢复继承的 ACL)—— `chmod` 不存在于 Windows。
|
|
194
|
+
|
|
195
|
+
两个例外与边界:
|
|
196
|
+
|
|
197
|
+
- 不含凭证的文件**不阻断**,只在 stderr 警告。
|
|
198
|
+
- `auth login` 是**唯一的例外**:它不拒绝,而是把已有文件重写为 `0600`(马上要写入新的 secret,
|
|
199
|
+
拒绝没有意义),写完自检不合格才报 `config_insecure`。
|
|
200
|
+
- 不读配置的命令(`--version`、`api list`、`skill where`、`sync tasks` 等)一律不受影响。
|
|
201
|
+
|
|
202
|
+
数据库正常关闭后 `.wal` 临时文件会自动消失,请勿手工删除。
|
|
203
|
+
|
|
204
|
+
### `auth whoami` 能看到什么
|
|
186
205
|
|
|
187
206
|
> ⚠️ `whoami` **只检查凭证是否存在**,不校验它是否有效——一个拼错的 AppKey 同样返回
|
|
188
207
|
> `configured: true`。第一次真实调用才是唯一的验证。
|
|
@@ -325,6 +344,13 @@ qiyu --version 包版本 + skill_contract_version
|
|
|
325
344
|
含内部表 `schema_version` / `sync_state` / `sync_gaps`,所以两边数量应当一致);库里
|
|
326
345
|
有而本 CLI **未声明**的表(旧版 CLI 或其它工具建的)不出现在 `tables` 里,而是在
|
|
327
346
|
`meta.warnings` 中点名 —— 数量不等时先读 `warnings` 判成因,不要径直断定「有表缺失」。
|
|
347
|
+
与声明表**同名但不是基表**的对象(view 等)同样不进 `tables`、在 `warnings` 里点名:
|
|
348
|
+
`store status` / `store init` / `db tables` / `sync verify` / `db describe` / `query --table` /
|
|
349
|
+
`stats fields` 都不会去执行它(一条同名 view 的本体若读外部文件或引用已删的表,执行它会让整条
|
|
350
|
+
命令失败;`db describe` 只出声明元数据、`row_count` / `time_range` 为 null,`query --table` 与
|
|
351
|
+
`stats fields` 报 `store_not_initialized` 并给出「换新路径重建库 + `sync run`」的恢复动作)。**大小写也算同名**:DuckDB 标识符大小写不敏感,
|
|
352
|
+
`"TAGS"` view 会被 `"tags"` 解析到并执行。
|
|
353
|
+
|
|
328
354
|
`schema_version` 要跟当前 CLI 的版本(`LATEST_VERSION`)比才有意义,小于它就是
|
|
329
355
|
旧版 CLI 建的库,`store init` 只补建缺失的迁移、不重放已应用的。`store status` 的每次调用都要对
|
|
330
356
|
各表做全表 `COUNT`(行数无缓存),轮询代价与数据量成正比,Agent 不应把它当作高频健康
|
|
@@ -332,27 +358,41 @@ qiyu --version 包版本 + skill_contract_version
|
|
|
332
358
|
|
|
333
359
|
### sync 命令的输出
|
|
334
360
|
|
|
335
|
-
`sync run` 的 stdout 是 `{tasks:[...], truncated:false}
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
`
|
|
340
|
-
|
|
341
|
-
total
|
|
342
|
-
|
|
343
|
-
`resolved_range
|
|
344
|
-
`
|
|
345
|
-
`
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
361
|
+
`sync run` 的 stdout 是 `{tasks:[...], truncated:false}`。每个任务含这些字段:
|
|
362
|
+
|
|
363
|
+
| 字段 | 内容 |
|
|
364
|
+
|---|---|
|
|
365
|
+
| `task` | 任务 id |
|
|
366
|
+
| `status` | `complete` / `partial` / `failed`(逐值见下) |
|
|
367
|
+
| `windows` | `{total, succeeded, failed, skipped, contained?}`,恒有 `total = succeeded + failed + skipped` |
|
|
368
|
+
| `rows` | `{fetched, written}` |
|
|
369
|
+
| `resolved_range` | 本轮请求的 Asia/Shanghai `+08:00` ISO 二元组(含义见 `meta.field_notes`) |
|
|
370
|
+
| `watermark` / `last_synced_at` | UTC `Z` 形态,与 `resolved_range` **写法不同**(见下) |
|
|
371
|
+
| `gaps` | 本轮失败 / 提示的缺口,`gaps[].range` 与 `resolved_range` 同形态 |
|
|
372
|
+
| `notes` | 中文说明数组(恒在,常为空),见下 |
|
|
373
|
+
|
|
374
|
+
**`windows.skipped` 有三种成因**:跳过的**残段窗**数 + **整窗晚于末端上限被丢弃**的窗数 +
|
|
375
|
+
**覆盖窗失败**时其名下被合并、该拉没拉的窗数。
|
|
376
|
+
|
|
377
|
+
**`windows.contained`** 仅在 > 0 时出现:完全落进前一窗**回看重叠区**、被合并的窗数
|
|
378
|
+
(overlapDays > 0 的任务)。**覆盖窗成功**时数据已由那一窗覆盖,所以既不算 skipped、
|
|
379
|
+
也不计入 total;覆盖窗失败时这些窗改记 skipped 并逐窗出进度行。
|
|
380
|
+
物理切出的窗数 = `total + contained`。
|
|
381
|
+
|
|
382
|
+
`notes` 是中文说明数组(恒在,常为空),内容是「有意跳过」、**不是故障**——看到它不代表本轮失败。两个生产来源:
|
|
383
|
+
|
|
384
|
+
- 「请求区间早于接口可得数据的最早边界」(把「区间不可得」与「同步故障」分开);
|
|
385
|
+
- 日对齐任务遇到非上海日界的 `--until`,两档:该日不早于末端上限(调整 `--until` 无用,
|
|
386
|
+
要等上限自然前移再跑增量);或末窗是半个自然日、按残段窗跳过(该日未同步,
|
|
387
|
+
要含该日请把 `--until` 写到次日 0 点)。
|
|
388
|
+
|
|
389
|
+
末段有无被跳过看 `windows.skipped`,不要只凭本数组为空判断。
|
|
350
390
|
|
|
351
391
|
⚠️ **`watermark` / `last_synced_at` 是 UTC `Z` 形态**(引擎写库的原样字符串),与同一行里
|
|
352
392
|
`resolved_range` 的 `+08:00` 形态**写法不同**——两者可以是同一时刻
|
|
353
393
|
(实测 `"…08:53:20.000Z"` 与 `"…16:53:20+08:00"` 是同一瞬间)。直接按字符串比较会得出
|
|
354
394
|
相反结论,先解析成时刻再比。`watermark` 是「数据覆盖到哪」,`last_synced_at` 是
|
|
355
|
-
|
|
395
|
+
「那次提交发生在什么时候」——注意**它按成功窗更新、不按轮**:一轮里有部分窗口失败
|
|
356
396
|
(`sync run` 报 `partial`)时它照样被更新(实测:中窗失败 → `partial` 而它已是末个成功窗
|
|
357
397
|
的提交时刻);它也**可能晚于水位实际前进的时刻**(断链后的成功窗仍刷新它,水位却冻结在
|
|
358
398
|
连续成功末端,实测同一轮里两者相差数分钟)。只有整轮没有任何带水位写入的成功提交
|
|
@@ -371,14 +411,24 @@ total —— 覆盖窗失败时这些窗改记 skipped 并逐窗出进度行;
|
|
|
371
411
|
|
|
372
412
|
| status | 含义 | 该做什么 |
|
|
373
413
|
|---|---|---|
|
|
374
|
-
| `complete` | **没有失败窗口**(`windows.failed = 0`) |
|
|
375
|
-
| `partial` | 至少一个窗口失败 |
|
|
414
|
+
| `complete` | **没有失败窗口**(`windows.failed = 0`) | 正常。⚠️ 不保证「全部窗口都跑了」:`windows.skipped` 可能大于 0(残段窗 / 整窗晚于末端上限两种;覆盖窗失败那种只会出现在 `partial`),判实际覆盖看它 |
|
|
415
|
+
| `partial` | 至少一个窗口失败 | 它**也覆盖「一行都没落」**:全窗失败时 `windows.succeeded = 0`,退出码仍为 1。两个计数字段怎么读见下 |
|
|
376
416
|
| `failed` | 快照任务的失败(本地限频闸门拦截 / 上游取数失败 / 落库失败或行数核对不符) | 快照没有窗口循环,所以不会出现 `partial`;反过来 windowed 任务也**不会**给出 `failed` —— 全窗失败同样是 `partial` |
|
|
377
417
|
|
|
418
|
+
上表两处展开:
|
|
419
|
+
|
|
420
|
+
- **`complete` 时 `windows.skipped > 0` 有两种成因**:跳过的残段窗、整窗晚于末端上限被丢弃。
|
|
421
|
+
第三种成因(覆盖窗失败时其名下被合并的窗转 skipped)必然带 `windows.failed > 0`,
|
|
422
|
+
**只会出现在 `partial`**。
|
|
423
|
+
- **`partial` 的两个计数分开读**:`windows.succeeded` 是成功窗数(空窗也算成功,
|
|
424
|
+
大于 0 不代表有行);`rows.written` 是写入行数(为 0 也可能是「窗口都成功、只是上游没数据」)。
|
|
425
|
+
⚠️ `count_mismatch` / `write_failed` 的失败窗记的是「参与核对的应写行数」——那批行已回滚、
|
|
426
|
+
实际没落库,这两类失败窗存在时它**偏大**。
|
|
427
|
+
|
|
378
428
|
`sync status` 的 `data` 是 `{tasks:[…]}`(图例键即该路径下的字段,如 `tasks[].range_status`),
|
|
379
429
|
每任务输出 `{task, watermark, range_status, last_synced_at, resolved_range,
|
|
380
430
|
gaps, gaps_count, locked}`:`resolved_range` 是上次成功推进的水位区间(形态同 run 的
|
|
381
|
-
`resolved_range`,但
|
|
431
|
+
`resolved_range`,但 `start` 是**水位起点语义**、含可能被跳过的首残段前缀 ——
|
|
382
432
|
本命令不输出 `windows.skipped`,判实际覆盖要看 `sync run` 的 `windows.skipped`),
|
|
383
433
|
`gaps` 是历史缺口逐条 `{range, reason, detail, recorded_at}`。
|
|
384
434
|
|
|
@@ -387,10 +437,20 @@ gaps, gaps_count, locked}`:`resolved_range` 是上次成功推进的水位区
|
|
|
387
437
|
|
|
388
438
|
| range_status | 真实含义 | 常见误读 |
|
|
389
439
|
|---|---|---|
|
|
390
|
-
| `complete` | **水位推进过**(引擎每个成功窗都写它) | ❌ 不是「全窗口成功」:3 窗中窗失败 → run 报 `partial` 而这里仍是 `complete
|
|
391
|
-
| `pending` | **最近一次运行没推进水位**(每轮开跑就置 pending,成功窗才推回 complete) |
|
|
440
|
+
| `complete` | **水位推进过**(引擎每个成功窗都写它) | ❌ 不是「全窗口成功」:3 窗中窗失败 → run 报 `partial` 而这里仍是 `complete`。判数据完整要综合三个判据,见下 |
|
|
441
|
+
| `pending` | **最近一次运行没推进水位**(每轮开跑就置 pending,成功窗才推回 complete) | 有三种误读都要避免,见下 |
|
|
392
442
|
| `null` | 该任务在 `sync_state` 里**没有行** | ❌ 不是「同步失败」:从未跑过,或只跑过被跳过的残段窗 |
|
|
393
443
|
|
|
444
|
+
上表两处展开:
|
|
445
|
+
|
|
446
|
+
- **`complete` 的「判数据完整」三个判据**:**覆盖范围**(`resolved_range`,以及 `sync run` 的
|
|
447
|
+
`windows.skipped` —— 本命令不输出它)、**历史缺口新鲜度**(按 `range` 对照,见下)、
|
|
448
|
+
**空 `gaps` 不等于完整**(`skipped > 0` 时可能 `gaps` 为空但仍有未覆盖段)。
|
|
449
|
+
- **`pending` 的三种误读**:❌ 不是「库里没数据」(首窗失败时后续成功窗照常落库、只是不推水位,
|
|
450
|
+
实测 pending 且表里有 2 行);❌ 不是「从未同步过」(先成功一轮、再跑一轮首窗失败同样回到 pending,
|
|
451
|
+
而 `watermark` 保留上一轮的值);❌ 也不是「正在同步」(并发写者会让本命令退避等待,
|
|
452
|
+
等到后读到的是那一轮的结果)。
|
|
453
|
+
|
|
394
454
|
`locked:true` 表示 `sync_state` 里有**残留**的写者章(上一轮运行被强杀)——它同样是
|
|
395
455
|
「不是正在同步中」:真正持锁的进程会让本命令退避等待(`readOnlyRetryMs`,默认 30 秒),
|
|
396
456
|
等到说明那一轮已结束(返回 `false`),等不到才报 `store_locked`。看到 `true` 说明写锁
|
|
@@ -408,6 +468,7 @@ gaps, gaps_count, locked}`:`resolved_range` 是上次成功推进的水位区
|
|
|
408
468
|
**`expected_from_api` 只对快照任务有意义**(上游 fetch 的行数);windowed 任务不做上游
|
|
409
469
|
全量重拉,该字段恒为 `null`,核对方式是「本地行数 ↔ sync_state 成功状态」的一致性
|
|
410
470
|
(`state_windows_consistent`)——两种任务的核对方式不同,读 drift 前先看任务 kind。
|
|
471
|
+
`local_rows` 在本地同名对象不是基表(view 等)时为 `null`(drift 有 `not_base_table`,见下图例)。
|
|
411
472
|
`sync tasks` 每任务含 `sensitive_columns`——该表标注为敏感的 PII 列清单(会话/工单的
|
|
412
473
|
`payload` 列在列内,它是整行 PII 的完整副本,不要 `SELECT *`)。本阶段**没有**任务的
|
|
413
474
|
启用/停用机制:注册表里的任务总是全部执行(选定任务靠命令行显式列出)。
|
|
@@ -419,11 +480,11 @@ gaps, gaps_count, locked}`:`resolved_range` 是上次成功推进的水位区
|
|
|
419
480
|
|---|---|---|
|
|
420
481
|
| `rate_limit_local` | 本地限频冷却未到点(持久化冷却,跨进程有效) | 等到 `detail` 里的时刻再重跑覆盖该区间;提前重跑必然再失败 |
|
|
421
482
|
| `fetch_failed` | 取数失败(有界重试后仍失败,本窗未写入) | 稍后重跑覆盖该区间 |
|
|
422
|
-
| `write_failed` |
|
|
483
|
+
| `write_failed` | 落库失败(事务已回滚,本窗未写入)。⚠️ 若 `detail` 点名「库里的同名对象不是基表(view 等)」:该表已被同名 view 取代,**重跑必然再失败** | 一般情况检查本地库(锁/磁盘)后重跑;被 view 取代时按 `detail` 里给出的「备份旧库 → 换新路径 `store init` → `sync run`」重建 |
|
|
423
484
|
| `count_mismatch` | 写入意图行数 ≠ API 声明行数(事务已回滚) | 重跑;持续不符报告人类 |
|
|
424
485
|
| `knowledge_row_malformed` | 快照映射时缺键列的行被丢弃(响应形态漂移);含知识库类目树里缺 id 的节点(连同其子树) | 报告人类核对接口形态;快照全删重插下这些行已消失 |
|
|
425
486
|
| `staff_id_list_malformed` | 分两种:`staffIdList` 非数组 → **该组全部成员**未落库(整组跳过);成员 id 为空 → **该成员**未落库(同组其余成员照常落库) | 报告人类核对接口形态;快照全删重插下这些成员已消失 |
|
|
426
|
-
| `row_missing_key` |
|
|
487
|
+
| `row_missing_key` | 映射时行缺主键列(缺键或空串),**该行未落库**;`detail` 是丢弃行数(工单日志另点名整单未拉取数) | 报表 / 工单 / 工单日志:报告人类核对接口形态;行数核对不含这些行,窗口仍可能 complete |
|
|
427
488
|
| `filter_matched_no_staff` | 报表筛选条件未命中任何客服(本窗按 0 行记) | 结合筛选条件判断——它不是「没有数据」的证据 |
|
|
428
489
|
| `export_fixture_unreported` | 导出流未上报窗口声明行,空窗可能真空也可能被截断 | 抽查该窗行数,必要时重跑 |
|
|
429
490
|
| `export_window_mismatch` | 导出声明的窗口宽于请求(重叠行由幂等 upsert 吸收) | 数据不受损,知悉即可 |
|
|
@@ -441,7 +502,10 @@ gaps, gaps_count, locked}`:`resolved_range` 是上次成功推进的水位区
|
|
|
441
502
|
**`drift[].kind` 的全部取值**(`sync verify`):`not_synced`(从未同步 → 先 `sync run`)、
|
|
442
503
|
`state_pending`(上次运行未完成或中断 → 重跑 `sync run` 补全后再 verify)、
|
|
443
504
|
`count_mismatch`(本地行数 ≠ 上游行数,仅快照任务 → 重跑覆盖,持续不符报告人类)、
|
|
444
|
-
`fetch_failed`(上游取数失败,**无法核对 ≠ 一致** → 稍后重试 verify
|
|
505
|
+
`fetch_failed`(上游取数失败,**无法核对 ≠ 一致** → 稍后重试 verify)、
|
|
506
|
+
`not_base_table`(本地同名对象不是基表(view 等),**未做行数核对** —— 执行它的主体会读到
|
|
507
|
+
错误数据或直接失败,此时 local_rows 为 null、快照任务也不发上游请求 → 用 db tables 看
|
|
508
|
+
对象类型;本 CLI 的表已被同名 view 取代时需换新路径重建库再 `sync run`,detail 里给了完整命令)。
|
|
445
509
|
|
|
446
510
|
⚠️ `sync verify` 的 `state_windows_consistent: true` **不等于「数据完整」**,`drift` 为空
|
|
447
511
|
或退出码 0 **同样不能当完整性证据**。对 **windowed 任务**,本命令只核对同步状态记录,而
|
|
@@ -595,6 +659,56 @@ min/max **只能核对一致性、不是量纲证据** —— 量纲不明确时
|
|
|
595
659
|
脱敏边界;payload 不是合法 JSON 的行不计入统计,**含空字符串键 `""` 的行仍计入该行其它字段**
|
|
596
660
|
(只跳过那个键本身),两者都会在 `meta.warnings` 里点名数量。
|
|
597
661
|
|
|
662
|
+
### skill 命令的输出
|
|
663
|
+
|
|
664
|
+
**`skill` 输出的状态取值**(Agent 按值分支;命令输出里每个值都带释义与动作,见
|
|
665
|
+
`meta.field_notes`;本图例与源码枚举由 `tests/skill-field-notes.test.ts` 三方核对):
|
|
666
|
+
|
|
667
|
+
`data.entity.state`(`skill where`)——`ok` 实体目录可用 / `missing` 不存在(= 未安装)/
|
|
668
|
+
`not_a_directory` 路径存在但不是目录(install 不会写它,需人先处理)/
|
|
669
|
+
`unknown` 无法判定(带 `error`,此时 `exists` 为 `null`)—— **`unknown` 不是「不存在」**。
|
|
670
|
+
|
|
671
|
+
`data.links[].state`(`skill where` 与 `skill install`)——`ok` 正确指向本实体 /
|
|
672
|
+
`missing` 链接不存在(**install 只在该 Agent 的 skills 目录已存在时**创建链接,从不创建
|
|
673
|
+
目录;目录不存在时 install 在 `meta.warnings` 里说明,且 `links` 里没有这个 Agent 的条目)/
|
|
674
|
+
`dangling` 链接存在但目标已不在(install 会重建)/
|
|
675
|
+
`foreign` **路径上是别人的东西**(不是指向本实体的符号链接,install 一律跳过,**不要删**)/
|
|
676
|
+
`unknown` 无法判定(带 `error`)——同样**不是「不存在」**。
|
|
677
|
+
|
|
678
|
+
`skill install --dry-run` 的 `data.action` / `data.planned_status`——`install`/`installed`
|
|
679
|
+
首次安装;`update`/`updated` 覆盖正文(`--force`)或只重写落后的清单;`skip`/`skipped`
|
|
680
|
+
**实体正文零写入**(内容一致且清单新鲜,或内容不同但没带 `--force`,原因在 `meta.warnings`)。
|
|
681
|
+
⚠️ 零写入只针对**实体正文**:链接仍会照常建立/修复 —— 实测「删掉链接后重装」返回
|
|
682
|
+
`status: skipped` 且 `links[].state` 回到 `ok`。判断链接发生了什么要看 `links[]`。
|
|
683
|
+
真实安装用 `data.status`(`installed`/`updated`/`skipped`,语义同上);`links[].action`
|
|
684
|
+
是**计划动作**(`keep`/`create`/`rebuild`/`skip`/`unknown`,与 `links[].state` 一一对应),
|
|
685
|
+
只在 `--dry-run` 的输出里存在 —— 真实安装的 `links[]` 条目只有 `state` 与可选 `error`。
|
|
686
|
+
|
|
687
|
+
### api call 的 body 校验
|
|
688
|
+
|
|
689
|
+
body 分级校验:`api call` 的 `--body` 与注册表参数表比对——缺必填拒绝(退出码 2),
|
|
690
|
+
未知字段/类型不符出 `meta.warnings`;`--strict` 可升级、`--no-validate` 可关闭。
|
|
691
|
+
参数表见 `qiyu api schema <id>`(`data.params`、`data.response_shape`)。
|
|
692
|
+
`data.params[]` 的元素字段是 `in`(`query` / `body` / `path` / `header`)、`required`、
|
|
693
|
+
`type`、`description`、`example`,以及条件出现的 `auto`(**只挂在这个数组的元素上**,
|
|
694
|
+
不是 `data` 的顶层键)。
|
|
695
|
+
只依据文档生成的参数表,不构成对服务端行为的保证;**响应体不做校验**;
|
|
696
|
+
校验只对 `body_kind: json` 且有 body 参数表的接口生效,其余原样透传。
|
|
697
|
+
`--strict` 只做本地参数表闭集一致性检查(「严格」≠「正确严格」),误拒时**不要删字段重试**。
|
|
698
|
+
|
|
699
|
+
### 输出格式(`--pretty`)
|
|
700
|
+
|
|
701
|
+
**输出格式**:所有命令默认输出紧凑 JSON(一行、可解析)。`--pretty` 输出缩进 JSON(人类可读)——
|
|
702
|
+
写在**具体子命令之后**(如 `qiyu api list --pretty`)。Agent 不需要它:默认输出已是合法 JSON,
|
|
703
|
+
缩进只是给人看的。用法错误(退出码 2)仍是紧凑 JSON —— 先修参数,再看格式。
|
|
704
|
+
|
|
705
|
+
### `api list` 的输出
|
|
706
|
+
|
|
707
|
+
`api list` 输出的 `data` 是**行数组**(`[{id, title, …}, …]`,不是 `{rows:[…]}` 对象)——
|
|
708
|
+
`meta.field_notes` 的键是**行字段名**(`verified` / `dangerous` / `direction` …),
|
|
709
|
+
唯一的例外是 `request_schema`:它不是字段,而是一条「本 meta 不含参数表,去
|
|
710
|
+
`api schema` 查」的否定声明。`meta.registry_complete` 会如实反映注册表是否已收录全部接口。
|
|
711
|
+
|
|
598
712
|
## 安全
|
|
599
713
|
|
|
600
714
|
- **危险操作硬门禁**:标记为 `dangerous` 的接口在缺少 `--yes` 时,**绝不发出任何请求**:body 合法则返回退出码 4,body 缺必填/非对象则**先**报参数错误(退出码 2),并给出 `confirm_required` / `confirm_arg` / `risk` / `target` 四个字段。
|
|
@@ -651,48 +765,6 @@ Skill 化——`skill install`(复制正文 + 建 Agent 链接,幂等,`--d
|
|
|
651
765
|
`skill where`(只读报告实体目录与各 Agent 链接状态),
|
|
652
766
|
外加 `qiyu --version`(输出包版本与 `skill_contract_version`)。
|
|
653
767
|
|
|
654
|
-
**`skill` 输出的状态取值**(Agent 按值分支;命令输出里每个值都带释义与动作,见
|
|
655
|
-
`meta.field_notes`;本图例与源码枚举由 `tests/skill-field-notes.test.ts` 三方核对):
|
|
656
|
-
|
|
657
|
-
`data.entity.state`(`skill where`)——`ok` 实体目录可用 / `missing` 不存在(= 未安装)/
|
|
658
|
-
`not_a_directory` 路径存在但不是目录(install 不会写它,需人先处理)/
|
|
659
|
-
`unknown` 无法判定(带 `error`,此时 `exists` 为 `null`)—— **`unknown` 不是「不存在」**。
|
|
660
|
-
|
|
661
|
-
`data.links[].state`(`skill where` 与 `skill install`)——`ok` 正确指向本实体 /
|
|
662
|
-
`missing` 链接不存在(**install 只在该 Agent 的 skills 目录已存在时**创建链接,从不创建
|
|
663
|
-
目录;目录不存在时 install 在 `meta.warnings` 里说明,且 `links` 里没有这个 Agent 的条目)/
|
|
664
|
-
`dangling` 链接存在但目标已不在(install 会重建)/
|
|
665
|
-
`foreign` **路径上是别人的东西**(不是指向本实体的符号链接,install 一律跳过,**不要删**)/
|
|
666
|
-
`unknown` 无法判定(带 `error`)——同样**不是「不存在」**。
|
|
667
|
-
|
|
668
|
-
`skill install --dry-run` 的 `data.action` / `data.planned_status`——`install`/`installed`
|
|
669
|
-
首次安装;`update`/`updated` 覆盖正文(`--force`)或只重写落后的清单;`skip`/`skipped`
|
|
670
|
-
**实体正文零写入**(内容一致且清单新鲜,或内容不同但没带 `--force`,原因在 `meta.warnings`)。
|
|
671
|
-
⚠️ 零写入只针对**实体正文**:链接仍会照常建立/修复 —— 实测「删掉链接后重装」返回
|
|
672
|
-
`status: skipped` 且 `links[].state` 回到 `ok`。判断链接发生了什么要看 `links[]`。
|
|
673
|
-
真实安装用 `data.status`(`installed`/`updated`/`skipped`,语义同上);`links[].action`
|
|
674
|
-
是**计划动作**(`keep`/`create`/`rebuild`/`skip`/`unknown`,与 `links[].state` 一一对应),
|
|
675
|
-
只在 `--dry-run` 的输出里存在 —— 真实安装的 `links[]` 条目只有 `state` 与可选 `error`。
|
|
676
|
-
|
|
677
|
-
body 分级校验:`api call` 的 `--body` 与注册表参数表比对——缺必填拒绝(退出码 2),
|
|
678
|
-
未知字段/类型不符出 `meta.warnings`;`--strict` 可升级、`--no-validate` 可关闭。
|
|
679
|
-
参数表见 `qiyu api schema <id>`(`data.params`、`data.response_shape`)。
|
|
680
|
-
`data.params[]` 的元素字段是 `in`(`query` / `body` / `path` / `header`)、`required`、
|
|
681
|
-
`type`、`description`、`example`,以及条件出现的 `auto`(**只挂在这个数组的元素上**,
|
|
682
|
-
不是 `data` 的顶层键)。
|
|
683
|
-
只依据文档生成的参数表,不构成对服务端行为的保证;**响应体不做校验**;
|
|
684
|
-
校验只对 `body_kind: json` 且有 body 参数表的接口生效,其余原样透传。
|
|
685
|
-
`--strict` 只做本地参数表闭集一致性检查(「严格」≠「正确严格」),误拒时**不要删字段重试**。
|
|
686
|
-
|
|
687
|
-
**输出格式**:所有命令默认输出紧凑 JSON(一行、可解析)。`--pretty` 输出缩进 JSON(人类可读)——
|
|
688
|
-
写在**具体子命令之后**(如 `qiyu api list --pretty`)。Agent 不需要它:默认输出已是合法 JSON,
|
|
689
|
-
缩进只是给人看的。用法错误(退出码 2)仍是紧凑 JSON —— 先修参数,再看格式。
|
|
690
|
-
|
|
691
|
-
`api list` 输出的 `data` 是**行数组**(`[{id, title, …}, …]`,不是 `{rows:[…]}` 对象)——
|
|
692
|
-
`meta.field_notes` 的键是**行字段名**(`verified` / `dangerous` / `direction` …),
|
|
693
|
-
唯一的例外是 `request_schema`:它不是字段,而是一条「本 meta 不含参数表,去
|
|
694
|
-
`api schema` 查」的否定声明。`meta.registry_complete` 会如实反映注册表是否已收录全部接口。
|
|
695
|
-
|
|
696
768
|
## 浏览器 / 文档
|
|
697
769
|
|
|
698
770
|
完整的接口语义、字段行为、限频与错误码的实测记录,见
|
|
@@ -48,6 +48,22 @@ export function callFieldNotes() {
|
|
|
48
48
|
+ '⚠️ 只覆盖结构性为空:业务为空(如 ticket.search 查到 0 条返回 {total:0,tickets:[]})'
|
|
49
49
|
+ '不会置位 —— 没有 not_found 不等于有数据',
|
|
50
50
|
warning: '与 not_found 同时出现的一句话说明(固定文案)',
|
|
51
|
+
unverified_endpoint: 'true = 该接口的响应信封形状从未实测(注册表 `verified:false`),'
|
|
52
|
+
+ '本次的 `not_found` 判定、`data` 解包与错误分类都只有文档依据。'
|
|
53
|
+
+ '具体后果:整条 200 响应没有载荷键时,信封未实测的接口不判 not_found —— '
|
|
54
|
+
+ '「空 data 是什么」没人观测过,实测过 `deleteKnowledges` 的空数组是全部删成功,'
|
|
55
|
+
+ '按读接口判据会被报成什么都没删。'
|
|
56
|
+
+ '例外:「message 能解析成 JSON 且结果为空」的宽松分支仍会置位(同时带 warning),'
|
|
57
|
+
+ '它同样只有文档依据。'
|
|
58
|
+
+ '所以收到 not_found 仍然要怀疑,没收到 not_found 不等于有数据。'
|
|
59
|
+
+ '信封形状(A/B/C/D)也是推的,若与文档不符,`data` 可能取错键或落进宽松模式。'
|
|
60
|
+
+ '它不是这次调用失败的信号(调用本身可能完全成功),而是不要依据本次输出的'
|
|
61
|
+
+ '空/非空与字段形状下结论,必要时人工确认结果。'
|
|
62
|
+
+ '成功信封(ok:true)在 meta 里、错误信封(ok:false)在 error 里都有这个键,'
|
|
63
|
+
+ '含义相同,错误时的 kind 与 retryable 同样只有文档依据。'
|
|
64
|
+
+ '键不出现有两种可能:该接口实测过(`verified:true`),或这次没能定位到接口'
|
|
65
|
+
+ '(如未知 id 的用法错误)。前者不代表其余字段没有坑(见 note),后者说明本字段'
|
|
66
|
+
+ '什么都没告诉你 —— 别把「没有这个键」当成「这个接口是实测过的」',
|
|
51
67
|
note: '该接口的已知坑(来自注册表,只在登记了 note 的接口上出现)。'
|
|
52
68
|
+ '⚠️ 它是静态说明、不是本次调用的结果',
|
|
53
69
|
};
|
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';
|
|
@@ -23,7 +23,8 @@ const CALL_FLAGS = [
|
|
|
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
|
{
|
|
@@ -87,7 +88,7 @@ const API_USAGE = `用法:qiyu api <list|call|schema> [参数]
|
|
|
87
88
|
出错时 stdout 是 {"ok":false,"error":{code,kind,retryable,message,hint?}}。
|
|
88
89
|
⚠️ 请按 kind 分支,不要按 code —— code 只是个标签:它可能是服务端的
|
|
89
90
|
数字码(如 14009),也可能是本 CLI 合成的词(usage / network / internal /
|
|
90
|
-
auth_missing / config_insecure / confirm_required / store_locked / store_not_initialized / local_rate_limit / sync_not_run / unknown)。合成词查不到官方错误码表。
|
|
91
|
+
auth_missing / config_insecure / config_invalid / confirm_required / store_locked / store_not_initialized / local_rate_limit / sync_not_run / unknown)。合成词查不到官方错误码表。
|
|
91
92
|
|
|
92
93
|
退出码:0 成功 · 1 业务错误 · 2 用法错误 · 3 网络错误 · 4 需要 --yes
|
|
93
94
|
`;
|
|
@@ -487,8 +488,18 @@ async function schema(argv) {
|
|
|
487
488
|
}
|
|
488
489
|
async function callOne(argv) {
|
|
489
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());
|
|
490
501
|
if (!id) {
|
|
491
|
-
return
|
|
502
|
+
return failCall('用法:qiyu api call <接口id> [--body <JSON>] [--yes] [--no-validate] [--strict]');
|
|
492
503
|
}
|
|
493
504
|
// ⚠️ 接口 id 必须是第一个参数。若第一个 token 是 flag(`--yes`/`--body`/`--bod`…),
|
|
494
505
|
// 用户把 flag 写在了 id 之前 —— 此前它会落到 `byId('--yes')` 报出
|
|
@@ -510,7 +521,7 @@ async function callOne(argv) {
|
|
|
510
521
|
// `api call --pretty --help` 报「接口 id 必须是第一个参数」而不是给帮助 ——
|
|
511
522
|
// 缺 id 是硬错误,help 修不了它(与 `list()` 的「未知/位置参数 → help」同源)。
|
|
512
523
|
if (id.startsWith('-') && id !== '--help' && id !== '-h') {
|
|
513
|
-
return
|
|
524
|
+
return failCall(`用法:接口 id 必须是第一个参数,但你给的是 flag \`${id}\`。\n` +
|
|
514
525
|
'正确写法:qiyu api call <接口id> [--body <JSON>] [--yes] [--no-validate] [--strict]');
|
|
515
526
|
}
|
|
516
527
|
// ⚠️ **参数校验必须全部在 `byId(id)` 之前。** 此前它们是交错在 `byId`/
|
|
@@ -564,7 +575,7 @@ async function callOne(argv) {
|
|
|
564
575
|
// 退出码 2 的语义是"改参数重来",而这里没有任何东西需要改。
|
|
565
576
|
// → 判据是**"重复是否会丢掉一个值"**,不是"是否为布尔 flag"。
|
|
566
577
|
if (i >= 0 && argv.indexOf('--body', i + 1) >= 0) {
|
|
567
|
-
return
|
|
578
|
+
return failCall('用法:--body 只能出现一次');
|
|
568
579
|
}
|
|
569
580
|
// ⚠️ 未知参数必须报错,不能静默忽略。实测:`--bod '{"a":1}'`(拼错一个字母)
|
|
570
581
|
// 会被无声丢掉,请求照常发出、body 为 undefined,服务端返回的却是一个
|
|
@@ -595,7 +606,7 @@ async function callOne(argv) {
|
|
|
595
606
|
// ⚠️ 这一句保持**字面量**:`readme.test.ts:58` 按源文本逐字钉着它(含 `<JSON>` 占位符,
|
|
596
607
|
// 渲染无法无参复现)。`command-tree.test.ts` 有一条断言把这里点名的 flag 与
|
|
597
608
|
// `CALL_FLAGS` 对齐,所以它不会与 spec 漂移。
|
|
598
|
-
return
|
|
609
|
+
return failCall(`未知参数:${describeArgs(unknown)}。可用:--body <JSON>、--yes、--no-validate、--strict、--pretty`);
|
|
599
610
|
}
|
|
600
611
|
// ⚠️ **位置参数同样必须报错** —— 上面那条只筛 `-` 开头的。`api call` 除接口 id
|
|
601
612
|
// 外不接受任何位置参数,而此前它们被无声丢弃(实测 `call ticket.search extra`
|
|
@@ -616,7 +627,7 @@ async function callOne(argv) {
|
|
|
616
627
|
// 星号 —— 与 help 文本同一条规则:输出给谁看,就按谁的格式写。这句强调此前
|
|
617
628
|
// 写成了 `**body 必须用 --body 传入…**`,是 stderr 通道上唯一一处 Markdown。
|
|
618
629
|
// 哨兵在 tests/commands/api.test.ts 的「用法错误的 stderr 也不得出现 Markdown」。
|
|
619
|
-
return
|
|
630
|
+
return failCall(`未知参数:${describeArgs(positional)}。` +
|
|
620
631
|
'接口 id 之后的参数必须写成 --body <JSON> / --yes / --no-validate / --strict —— ' +
|
|
621
632
|
'body 必须用 --body 传入,直接写 JSON 会被忽略(那会发出一个没有 body 的请求)');
|
|
622
633
|
}
|
|
@@ -625,7 +636,7 @@ async function callOne(argv) {
|
|
|
625
636
|
const raw = argv[i + 1];
|
|
626
637
|
if (raw === undefined) {
|
|
627
638
|
// 静默当成 {} 会掩盖用户的输入错误,并可能触发"空 body"那条代码路径
|
|
628
|
-
return
|
|
639
|
+
return failCall('用法:--body 后面缺少 JSON 值');
|
|
629
640
|
}
|
|
630
641
|
try {
|
|
631
642
|
body = JSON.parse(raw);
|
|
@@ -634,7 +645,7 @@ async function callOne(argv) {
|
|
|
634
645
|
// ⚠️ 用 describeArgs 渲染,不裸插值(2026-10-07 修):`--body ''`(如 shell 变量未设置)
|
|
635
646
|
// 会让裸插值产出 `--body 不是合法 JSON:` —— 冒号后什么都没有,退出码 2 的全部信息量归零。
|
|
636
647
|
// 与 `describeArgs` 存在的理由完全同款(见 output.ts 该函数注释)。
|
|
637
|
-
return
|
|
648
|
+
return failCall(`--body 不是合法 JSON:${describeArgs([raw])}`);
|
|
638
649
|
}
|
|
639
650
|
}
|
|
640
651
|
// ⚠️ 次序与 `list()` 逐字一致:**未知/位置参数/值 → help → `--pretty`**(2026-10-08 修)。
|
|
@@ -661,12 +672,14 @@ async function callOne(argv) {
|
|
|
661
672
|
// ⚠️ 命令行已证明合法,现在才谈接口是否存在 / 可调用 / 需确认。
|
|
662
673
|
// 这三者都抛异常,由下方 catch 统一映射退出码(未知 id → usage 2、
|
|
663
674
|
// 不可调用 → usage 2、危险未确认 → needs_confirmation 4)。
|
|
664
|
-
// ⚠️ spec 提升到 try
|
|
675
|
+
// ⚠️ spec 提升到 try 外(已在函数顶部声明):catch 里的 mapThrownToExit 需要它来判断
|
|
665
676
|
// 「限流错误要不要附本地 fallback 建议」(G1)。byId 抛错时它仍是 undefined,
|
|
666
677
|
// 那种错误是 usage,走不到 fallback 分支。
|
|
667
|
-
|
|
678
|
+
/** 门禁分支的未实测标记(在 catch 里读 `spec` 前就算好,见 mapThrownToExit 头注释)。 */
|
|
679
|
+
let needsConfirmUnverified;
|
|
668
680
|
try {
|
|
669
681
|
spec = byId(id);
|
|
682
|
+
needsConfirmUnverified = unverifiedMark(spec);
|
|
670
683
|
assertCallable(spec);
|
|
671
684
|
assertGetHasNoBody(spec, body);
|
|
672
685
|
assertNoValidateStrictConflict(argv);
|
|
@@ -697,7 +710,7 @@ async function callOne(argv) {
|
|
|
697
710
|
// 避免「api 认配置文件、sync 只认环境变量」这种 Agent 看不出来的分叉。
|
|
698
711
|
const credOutcome = resolveCredentialsUsingFile(currentCredentialEnv());
|
|
699
712
|
if (!credOutcome.ok)
|
|
700
|
-
return fail(credOutcome.error);
|
|
713
|
+
return fail({ ...credOutcome.error, ...(mine() ? { unverifiedEndpoint: mine() } : {}) });
|
|
701
714
|
const creds = credOutcome.creds;
|
|
702
715
|
const r = await call(spec, body, { credentials: creds });
|
|
703
716
|
// ⚠️ 「成功但查无此物」必须显式标出来。设计稿 §9.2:0 行是比报错危险得多的
|
|
@@ -724,6 +737,14 @@ async function callOne(argv) {
|
|
|
724
737
|
...(warnings.length ? { warnings } : {}),
|
|
725
738
|
...(r.notFound ? { not_found: true, warning: '接口返回成功但无数据' } : {}),
|
|
726
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 } : {}),
|
|
727
748
|
});
|
|
728
749
|
}
|
|
729
750
|
catch (e) {
|
|
@@ -744,6 +765,7 @@ async function callOne(argv) {
|
|
|
744
765
|
hint: '这是不可逆的写操作。**必须由人类确认**后再执行 —— 不要自动追加 --yes。' +
|
|
745
766
|
'请把该操作及其目标(接口 id 见 target)复述给人类,得到许可后才可重试。',
|
|
746
767
|
confirmRequired: true, target: err.target ?? id,
|
|
768
|
+
...(needsConfirmUnverified ? { unverifiedEndpoint: needsConfirmUnverified } : {}),
|
|
747
769
|
});
|
|
748
770
|
}
|
|
749
771
|
// 已分类的业务/网络错误与其余用法错误共用 mapThrownToExit,避免同族错误两种表现。
|
|
@@ -751,6 +773,28 @@ async function callOne(argv) {
|
|
|
751
773
|
return mapThrownToExit(e, spec);
|
|
752
774
|
}
|
|
753
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
|
+
}
|
|
754
798
|
/** 把 catch 到的异常映射为退出码与输出 —— `callOne` 与 `api schema` **共用**的唯一出口(spec §三 :207)。
|
|
755
799
|
* 两类:① 已分类的业务/网络错误(kind!=='usage')→ 只出 stdout JSON(失败也 classification 直传);
|
|
756
800
|
* ② 其余(未知 id、不可调用、校验硬拒、`--no-validate`/`--strict` 冲突等)→ usage 双通道 + 退出码 2。
|
|
@@ -761,6 +805,7 @@ function mapThrownToExit(e, spec) {
|
|
|
761
805
|
// ⚠️ 用 `Partial<QiyuError>`(src/core/errors.ts:53,`retryAfter` 是 `{seconds,source}` 对象)——
|
|
762
806
|
// 不要写成 `retryAfter: number`(fail() 的入参类型是对象,tsc 会 TS2322 红)。
|
|
763
807
|
const err = e;
|
|
808
|
+
const unverifiedEndpoint = unverifiedMark(spec);
|
|
764
809
|
if (err.kind && err.kind !== 'usage') {
|
|
765
810
|
// —— 限流 → 本地 fallback 建议(G1 交付;设计稿 §9.1 示例里声明过这两个字段)——
|
|
766
811
|
//
|
|
@@ -802,6 +847,7 @@ function mapThrownToExit(e, spec) {
|
|
|
802
847
|
message: err.message ?? String(e), hint, retryAfter: err.retryAfter,
|
|
803
848
|
...(retryStrategy !== undefined ? { retryStrategy } : {}),
|
|
804
849
|
...(fallback !== undefined ? { fallback } : {}),
|
|
850
|
+
...(unverifiedEndpoint !== undefined ? { unverifiedEndpoint } : {}),
|
|
805
851
|
});
|
|
806
852
|
}
|
|
807
853
|
// 用法错误走 `usageFail`(**唯一出口**,2026-11-02 收敛)。
|
|
@@ -812,7 +858,7 @@ function mapThrownToExit(e, spec) {
|
|
|
812
858
|
// 都输出**缩进**的错误信封,而同一 exit 2 的 `api list extra --pretty`(走 usageFail)是紧凑的
|
|
813
859
|
// —— 同一退出码两种报文形态,而 Agent 会拿缩进当「格式化已生效」的证据。
|
|
814
860
|
// 那三条断言之所以没抓到:`tests/commands/api.test.ts` 只钉了走 `usageFail` 的那三条分支。
|
|
815
|
-
return usageFail(e instanceof Error ? e.message : String(e), err.hint);
|
|
861
|
+
return usageFail(e instanceof Error ? e.message : String(e), err.hint, unverifiedEndpoint);
|
|
816
862
|
}
|
|
817
863
|
/** 私有:`--no-validate` 与 `--strict` 同传 → 抛普通 Error(→ 退出码 2)。 */
|
|
818
864
|
export function assertNoValidateStrictConflict(argv) {
|
package/dist/commands/auth.js
CHANGED
|
@@ -40,7 +40,7 @@ auth login 从环境变量读取凭证(不接受 --app-key/--app-secret:命
|
|
|
40
40
|
出错时 stdout 是 {"ok":false,"error":{code,kind,retryable,message,hint?}}。
|
|
41
41
|
⚠️ 请按 kind 分支,不要按 code —— code 只是个标签:它可能是服务端的
|
|
42
42
|
数字码(如 14009),也可能是本 CLI 合成的词(usage / network / internal /
|
|
43
|
-
auth_missing / config_insecure / confirm_required / store_locked / store_not_initialized /
|
|
43
|
+
auth_missing / config_insecure / config_invalid / confirm_required / store_locked / store_not_initialized /
|
|
44
44
|
local_rate_limit / sync_not_run / unknown)。合成词查不到官方错误码表。
|
|
45
45
|
|
|
46
46
|
退出码:0 成功 · 1 业务错误 · 2 用法错误 · 3 网络错误 · 4 需要 --yes
|