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/cli.js
CHANGED
|
@@ -7,6 +7,7 @@ import { PACKAGE_VERSION, SKILL_CONTRACT_VERSION } from './core/edition.js';
|
|
|
7
7
|
import { detectSkillState, entityUndeterminedNote, npmRelativeBase, resolveEntityDirSources, resolveSkillSourceDir, skillWarning, } from './skill/detect.js';
|
|
8
8
|
import { apiCommand } from './commands/api.js';
|
|
9
9
|
import { prettyAfterSubcommand } from './commands/spec-types.js';
|
|
10
|
+
import { DB_PATH_HELP } from './commands/store-flags.js';
|
|
10
11
|
import { wireLocalFallback } from './commands/local-fallback-wiring.js';
|
|
11
12
|
import { storeCommand } from './commands/store.js';
|
|
12
13
|
import { syncCommand } from './commands/sync.js';
|
|
@@ -18,6 +19,27 @@ import { skillCommand } from './commands/skill.js';
|
|
|
18
19
|
// 它只 import 各命令模块、不含入口逻辑,将来 `src/skill/check.ts` 从**那里**消费。
|
|
19
20
|
// 本文件 re-export 只是兼容入口(计划原文写的是 `cli.ts` 汇总),免得调用方改路径。
|
|
20
21
|
export { COMMAND_TREE } from './commands/tree.js';
|
|
22
|
+
/**
|
|
23
|
+
* `--version` 的 `meta.field_notes`。
|
|
24
|
+
*
|
|
25
|
+
* ⚠️ 为什么需要:`skill_contract_version` 是 CLI **自己**的正文契约号,而 SKILL.md 教
|
|
26
|
+
* Agent「用它判断手上的正文能否配这份 CLI」—— 手上有两个同名的数(CLI 的、已安装那份的),
|
|
27
|
+
* 不点名就会拿错(2026-10-28 实测:两者可以不等,且 `--version` 不报已安装那份)。
|
|
28
|
+
*/
|
|
29
|
+
export function versionFieldNotes() {
|
|
30
|
+
return {
|
|
31
|
+
version: 'CLI 包版本(npm 包的语义版本号)',
|
|
32
|
+
skill_contract_version: 'CLI 自己的正文契约号 —— 不是已安装那份的。'
|
|
33
|
+
+ '要判断已安装的 skill 正文能否配这份 CLI,拿它与 `skill where` 的 '
|
|
34
|
+
+ 'entity.installed.skill_contract_version 比,相等才配。'
|
|
35
|
+
+ '⚠️ `--version` 既不读安装清单、也不读已安装正文:这个值是 CLI 自己的常量,'
|
|
36
|
+
+ '上文「相等才配」只是拿它与 `skill where` 报出的数比。那个数的可靠性由 `skill where` 兜:'
|
|
37
|
+
+ '它会拿实体当前内容与清单记录的 content_hash 比对,正文被手工改过(或读不动)时'
|
|
38
|
+
+ '`entity.installed.compatible` 报 null(判定不了),不会拿旧清单给改过的正文背书。'
|
|
39
|
+
+ '⚠️ 清单缺失或损坏时整个 entity.installed 是 null(不是它下面某个字段为 null)——'
|
|
40
|
+
+ '先判 entity.installed 非 null 再读,也不要把 null 当 0',
|
|
41
|
+
};
|
|
42
|
+
}
|
|
21
43
|
// —— 限流 fallback 接线(G1 契约小件)——
|
|
22
44
|
// `api call` 的限流错误要附「改用本地查询」建议(retry_strategy/fallback),
|
|
23
45
|
// 而该建议需要 sync 任务注册表与本地库探测;`commands/api.ts` 按分层红线
|
|
@@ -41,6 +63,14 @@ const COMMANDS = {
|
|
|
41
63
|
* ⚠️ 全局约束承诺了「CLI 的 `--help` 一律中文」,所以这里必须实现它,
|
|
42
64
|
* 不能让它落到「未知子命令」分支(实测那会输出「未知子命令:--help」,退出码 2)。
|
|
43
65
|
*/
|
|
66
|
+
/**
|
|
67
|
+
* 分派层三条伪命令(`--help` / `--version` / `--pretty`)共同接受的 token。
|
|
68
|
+
*
|
|
69
|
+
* ⚠️ **一份**清单而不是三份(2026-11-06 审查):此前三条分支各写各的豁免,缺少对方
|
|
70
|
+
* 的 token,于是 `--help --version` / `--pretty --version` 会把另一个合法全局选项
|
|
71
|
+
* 说成「未知参数」——同一命令行换个顺序就换一种结果(`--version --help` 是 0)。
|
|
72
|
+
*/
|
|
73
|
+
const PSEUDO_TOKENS = new Set(['--help', '-h', '--version', '--pretty']);
|
|
44
74
|
const USAGE = `用法:qiyu <子命令> [参数]
|
|
45
75
|
|
|
46
76
|
全局选项:
|
|
@@ -52,7 +82,9 @@ const USAGE = `用法:qiyu <子命令> [参数]
|
|
|
52
82
|
Agent 解析不需要它)
|
|
53
83
|
|
|
54
84
|
子命令:
|
|
55
|
-
auth whoami
|
|
85
|
+
auth whoami 检查凭证是否已配置(只查存在性,不校验有效性)
|
|
86
|
+
auth login [--profile <name>]
|
|
87
|
+
把环境变量里的凭证写入配置文件(新建目录 0700、文件 0600)
|
|
56
88
|
api list [--all] 列出接口(默认只列可主动调用的出站接口)
|
|
57
89
|
api call <id> [--body <JSON>] [--yes] [--no-validate] [--strict]
|
|
58
90
|
调用接口;危险接口必须加 --yes
|
|
@@ -87,12 +119,13 @@ const USAGE = `用法:qiyu <子命令> [参数]
|
|
|
87
119
|
行数上限 / 超时 / 关闭默认脱敏(细节见 qiyu query --help)
|
|
88
120
|
--db <path> / --profile <name> / --backend <name>
|
|
89
121
|
db / query / stats 共用的存储定位(与 store / sync 同族)
|
|
122
|
+
${DB_PATH_HELP}
|
|
90
123
|
|
|
91
124
|
出错时 stdout 是 {"ok":false,"error":{code,kind,retryable,message,hint?}}。
|
|
92
125
|
⚠️ 请按 kind 分支,不要按 code —— code 只是个标签:它可能是服务端的
|
|
93
126
|
数字码(如 14009),也可能是本 CLI 合成的词(usage / network / internal /
|
|
94
|
-
auth_missing / config_insecure / confirm_required / store_locked / store_not_initialized /
|
|
95
|
-
local_rate_limit / query_error / sandbox_blocked / query_timeout / unknown)。
|
|
127
|
+
auth_missing / config_insecure / config_invalid / confirm_required / store_locked / store_not_initialized /
|
|
128
|
+
local_rate_limit / query_error / sandbox_blocked / query_timeout / sync_not_run / unknown)。
|
|
96
129
|
合成词查不到官方错误码表。
|
|
97
130
|
|
|
98
131
|
退出码:0 成功 · 1 业务错误 · 2 用法错误 · 3 网络错误 · 4 需要 --yes
|
|
@@ -137,7 +170,10 @@ export async function run(argv) {
|
|
|
137
170
|
// (与 `api list --help --help` 同答 —— 都不算"额外参数")。
|
|
138
171
|
// ⚠️ `--pretty` 同样豁免(2026-10-08;G1 起已实现为缩进开关):它是**合法 flag**,
|
|
139
172
|
// 不是"额外参数"—— `qiyu --help --pretty` 给帮助(与 `api list --help --pretty` 同答)。
|
|
140
|
-
|
|
173
|
+
// ⚠️ 三条伪命令的豁免清单必须**互相包含**(2026-11-06 审查):此前各写各的,
|
|
174
|
+
// 于是 `--help --version` 退 2 并说 `--version` 是「未知参数」——一个就在这张帮助里
|
|
175
|
+
// 列着的全局选项被自己的 CLI 称作未知,取决于书写顺序(`--version --help` 却是 0)。
|
|
176
|
+
const extra = rest.filter((a) => !PSEUDO_TOKENS.has(a));
|
|
141
177
|
if (extra.length > 0) {
|
|
142
178
|
return usageFail(`未知参数:${describeArgs(extra)}。--help 不接受额外参数`);
|
|
143
179
|
}
|
|
@@ -156,14 +192,14 @@ export async function run(argv) {
|
|
|
156
192
|
// 输出走 `ok()`(而非自己写 stdout):skill 安装态提示要能经 `meta.warnings`
|
|
157
193
|
// 合并进来,且成功信封的形态由 output.ts 一处统一。
|
|
158
194
|
if (sub === '--version') {
|
|
159
|
-
const extra = rest.filter((a) => a
|
|
195
|
+
const extra = rest.filter((a) => !PSEUDO_TOKENS.has(a));
|
|
160
196
|
if (extra.length > 0) {
|
|
161
197
|
return usageFail(`未知参数:${describeArgs(extra)}。--version 不接受额外参数`);
|
|
162
198
|
}
|
|
163
199
|
// G1:--version --pretty → 缩进的版本 JSON(帮助/版本检查是例外:--pretty 有可修饰的对象)
|
|
164
200
|
if (rest.includes('--pretty'))
|
|
165
201
|
setPretty(true);
|
|
166
|
-
return ok({ version: PACKAGE_VERSION, skill_contract_version: SKILL_CONTRACT_VERSION });
|
|
202
|
+
return ok({ version: PACKAGE_VERSION, skill_contract_version: SKILL_CONTRACT_VERSION }, { field_notes: versionFieldNotes() });
|
|
167
203
|
}
|
|
168
204
|
// ⚠️ 分派层的 `--pretty` 必须与叶子层同答(2026-10-08 统一)。此前它落到
|
|
169
205
|
// 「未知子命令:--pretty」—— 而 `--pretty` 是真实存在的输出开关(G1 已实现)
|
|
@@ -174,7 +210,12 @@ export async function run(argv) {
|
|
|
174
210
|
// G1:--pretty 已实现,但它必须写在具体子命令之后(`qiyu api list --pretty`)。
|
|
175
211
|
// 写在顶层时没有任何可修饰的输出(帮助是裸文本、version 是另一条伪命令)。
|
|
176
212
|
if (sub === '--pretty') {
|
|
177
|
-
|
|
213
|
+
// `--version` 是合法全局选项,但它必须写在 `--pretty` **之前**(`qiyu --version
|
|
214
|
+
// --pretty`)—— 报「未知参数:--version」是事实错误(2026-11-06 审查)。
|
|
215
|
+
if (rest.includes('--version')) {
|
|
216
|
+
return usageFail('--version 必须写在 --pretty 之前:`qiyu --version --pretty`');
|
|
217
|
+
}
|
|
218
|
+
const unknown = rest.filter((a) => a.startsWith('-') && !PSEUDO_TOKENS.has(a));
|
|
178
219
|
const positional = rest.filter((a) => !a.startsWith('-'));
|
|
179
220
|
const extra = [...unknown, ...positional];
|
|
180
221
|
if (extra.length > 0) {
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
// src/commands/api-notes.ts
|
|
2
|
+
//
|
|
3
|
+
// `api call` 的 `meta.field_notes` 图例(2026-10-28)。
|
|
4
|
+
//
|
|
5
|
+
// ⚠️ 为什么 `api call` 需要图例:它的 `data` 是**上游载荷**,与其余命令的
|
|
6
|
+
// `data`(CLI 自己的契约)不是一回事 —— 不点破,Agent 会按 `qiyu db tables` 的
|
|
7
|
+
// 形状去读 `ticket.search` 的返回。`meta` 里的 `endpoint` / `not_found` /
|
|
8
|
+
// `warnings` / `note` 也各有坑(尤其 `not_found` 只覆盖**结构性为空**)。
|
|
9
|
+
//
|
|
10
|
+
// ⚠️ 为什么键是 `data`(信封顶层):图例解释的是「读者会读的那个键」,而 `data`
|
|
11
|
+
// 恰恰是最容易被误读的一个 —— 它是本输出里唯一来自上游的键。
|
|
12
|
+
export function callFieldNotes() {
|
|
13
|
+
return {
|
|
14
|
+
data: '上游响应解包后的载荷:本 CLI 按信封形状取出 data / result / staffInfo 等键'
|
|
15
|
+
// ⚠️ 不能说「原样透传、不改写」(2026-11-07 审查实测):形状 M 的载荷在透传前被
|
|
16
|
+
// trim(),形状 C 的畸形 JSON 先经 repairUnquotedIntKeys 修复再解析。
|
|
17
|
+
// ⚠️ 也不能让读者去 `api schema` 查响应字段:它只有请求侧 params 与
|
|
18
|
+
// `response_shape:{kind}`,没有任何响应字段表(2026-11-07 审查)。
|
|
19
|
+
+ '(信封形状 M 会 trim 首尾空白,形状 C 的畸形 JSON 键会先被修复再解析)。'
|
|
20
|
+
+ '⚠️ 本 CLI 没有响应字段表:`qiyu api schema` 只给请求参数与信封种类,'
|
|
21
|
+
+ '各字段的确切含义以七鱼官方文档为准,不要按其他命令 data 的形状推断',
|
|
22
|
+
endpoint: '本次调用的接口 id(把结果与请求对上用)',
|
|
23
|
+
warnings: '⚠️ 这是多来源数组,元素形状不统一:'
|
|
24
|
+
+ '① body 校验的软告警(对象,含 `kind` / `message`),'
|
|
25
|
+
// ⚠️ `field` **不保证**存在(Sourcery 指出):`non_json_body`(body_kind 非 json 时
|
|
26
|
+
// 整条请求级的提示 —— 传输层仍按 JSON.stringify 发 JSON 字节,不是该编码的原文)是**整条请求**级的提示,没有单一字段可归因 —— 它只带 `kind` 与
|
|
27
|
+
// `message`。消费者按 `w.field` 取值会拿到 `undefined`。
|
|
28
|
+
+ '`field` 仅在告警属于某个具体字段时出现(如 `unknown_field` / '
|
|
29
|
+
+ '`type_mismatch` / `alias_normalized`),`non_json_body` 这类整条请求级的提示没有它,'
|
|
30
|
+
+ '② CLI 级的安装态提示(如 skill 未安装)——'
|
|
31
|
+
+ '同一次输出里已有 ① 时它被包成 `{kind:"skill_drift", message}`,否则是裸字符串。'
|
|
32
|
+
+ '故按 `w.kind` 取值前先判元素类型,别假定它一定是对象。'
|
|
33
|
+
+ '⚠️ 键不出现 ≠ body 正确:它只在「没有软告警且没有 CLI 提示」时不出现,'
|
|
34
|
+
+ '--no-validate 只保证不产生 ①(body 未校验),② 照旧出现。'
|
|
35
|
+
+ '⚠️ `missing_required` 永远不会出现在这里 —— 缺必填是硬拒绝(退出码 2、错误信封),'
|
|
36
|
+
+ '不要写「在 warnings 里找 missing_required」的分支。'
|
|
37
|
+
+ '它是本 CLI 的提示,不是上游的业务告警',
|
|
38
|
+
not_found: 'true = 解包后的载荷为空。判据作用在解包后的 payload 上:'
|
|
39
|
+
+ 'data / result 形状下是 {} / []。形状 C 且 message 能解析成 JSON 时,'
|
|
40
|
+
+ '解析出的 {} / [] 同样置位(message 缺失或解析失败是失败,不是 not_found)。'
|
|
41
|
+
+ 'envelope 未登记的宽松模式下,message 能解析成 JSON 且结果为空同样置位。'
|
|
42
|
+
+ '整条 200 响应没有载荷键时,只有信封已实测且不是 D 族(A/B/D-nf)的接口判为查无此物'
|
|
43
|
+
// ⚠️ 形状 C **不在**这个列表里:C 分支对任何响应都会先尝试解析 message,
|
|
44
|
+
// `{code:200}`(无 message)在 C 上直接判失败,根本走不到末尾兜底。
|
|
45
|
+
+ '(形状 C 不在此列:它的无 message 是失败,不是查无此物)'
|
|
46
|
+
+ '(envelope 为 null 不在此断言。形状 M 的空 message 判失败,不判 not_found)。'
|
|
47
|
+
+ 'staffInfo 形状恒不置位。'
|
|
48
|
+
+ '⚠️ 只覆盖结构性为空:业务为空(如 ticket.search 查到 0 条返回 {total:0,tickets:[]})'
|
|
49
|
+
+ '不会置位 —— 没有 not_found 不等于有数据',
|
|
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
|
+
+ '什么都没告诉你 —— 别把「没有这个键」当成「这个接口是实测过的」',
|
|
67
|
+
note: '该接口的已知坑(来自注册表,只在登记了 note 的接口上出现)。'
|
|
68
|
+
+ '⚠️ 它是静态说明、不是本次调用的结果',
|
|
69
|
+
};
|
|
70
|
+
}
|