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.
- package/README.md +349 -57
- package/dist/cli.js +48 -7
- package/dist/commands/api-notes.js +54 -0
- package/dist/commands/api.js +113 -39
- package/dist/commands/auth.js +150 -28
- package/dist/commands/credentials-source.js +30 -5
- package/dist/commands/db-notes.js +75 -0
- package/dist/commands/db.js +112 -113
- package/dist/commands/query-notes.js +58 -0
- package/dist/commands/query.js +427 -56
- package/dist/commands/skill.js +477 -38
- package/dist/commands/spec-types.js +101 -1
- package/dist/commands/stats.js +139 -30
- package/dist/commands/store-flags.js +18 -0
- package/dist/commands/store-notes.js +38 -0
- package/dist/commands/store-precheck.js +254 -0
- package/dist/commands/store.js +128 -75
- package/dist/commands/sync-notes.js +367 -0
- package/dist/commands/sync-run.js +155 -44
- package/dist/commands/sync.js +182 -121
- package/dist/core/config.js +274 -24
- package/dist/core/credentials.js +38 -4
- package/dist/core/edition.js +13 -3
- package/dist/core/envelope.js +73 -9
- package/dist/core/errors.js +73 -16
- package/dist/core/http.js +151 -52
- package/dist/core/ratelimit.js +5 -1
- package/dist/core/registry/index.js +26 -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 +64 -42
- 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 +204 -28
- 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 +129 -24
- 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 +122 -27
- package/dist/skill/install.js +233 -43
- package/dist/skill/paths.js +54 -0
- package/dist/skill/qiyu/SKILL.md +38 -8
- 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 +51 -5
- package/dist/store/retry.js +92 -4
- package/dist/store/schema.js +26 -3
- package/dist/sync/engine.js +257 -65
- package/dist/sync/registry.js +4 -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/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 +47 -0
- package/package.json +1 -1
package/dist/output.js
CHANGED
|
@@ -51,13 +51,154 @@ function write(obj) {
|
|
|
51
51
|
export function describeArgs(args) {
|
|
52
52
|
return args.map((a) => (a.trim() === '' ? `'${a}'` : a)).join('、');
|
|
53
53
|
}
|
|
54
|
+
/**
|
|
55
|
+
* 渲染「恢复命令必须指向**本次使用的库**」的完整命令(唯一实现,2026-10-30)。
|
|
56
|
+
*
|
|
57
|
+
* 背景(真库实测):hint 里写「请先运行:qiyu store init」时,若本次是用 `--db`/
|
|
58
|
+
* `--profile`/环境变量选了非默认库,逐字执行会作用在**默认库**上:
|
|
59
|
+
* · `db describe tickets --db <空库>` → 照 hint 跑 `qiyu store init` → 建出
|
|
60
|
+
* `~/.qiyu/duckdb/qiyu.duckdb`,原命令再跑仍报同一句(死循环,实测);
|
|
61
|
+
* · `sync install --db <未同步库>` → 照 hint 跑 `qiyu sync run` → 同步默认库,
|
|
62
|
+
* install 仍报 `sync_not_run`。
|
|
63
|
+
* 修法:点名的命令一律带**本次解析出的绝对路径** `--db <path>`。为什么用解析后的
|
|
64
|
+
* 路径而不是回显用户给的 flag:选择可能来自配置文件或环境变量(没有 flag 可回显),
|
|
65
|
+
* 而 `--db` 的优先级高于两者 —— 解析后的路径在任何来源下都精确复现本次目标,
|
|
66
|
+
* 且是绝对路径,换工作目录也成立。
|
|
67
|
+
*
|
|
68
|
+
* `syncRunCommand` 还要回显**档名**(CodeRabbit 2026-10-30 major):`--db` 只固定库文件,
|
|
69
|
+
* 而 `sync run` 还从**解析出的档**读 `store.options.knowledgeRobotIds` 与
|
|
70
|
+
* `profiles.<name>.robots`(robotId 注入面)。实测:同一份 config 下带 `--profile alpha`
|
|
71
|
+
* 解析出 `options={"knowledgeRobotIds":[1000001]}`、robots `["2000002"]`,不带则两者皆空 ——
|
|
72
|
+
* 只回显 `--db` 的 hint 会让知识库任务用错 robot 集合。`store init` 不读 options/robots
|
|
73
|
+
*(只跑迁移),故 `storeInitCommand` 不回显档名。
|
|
74
|
+
*
|
|
75
|
+
* ⚠️ 参数值经 `shellArg` 渲染(Python `shlex.quote` 同一安全集):路径/档名含空白或
|
|
76
|
+
* shell 元字符时用单引号包裹,否则裸渲染保持可读。**为什么必须引号**:hint 是给 Agent
|
|
77
|
+
* 复制执行的命令 —— 未引号的 `--db /tmp/x; touch /tmp/marker; #` 粘进 shell 会真的
|
|
78
|
+
* 执行 `touch`(CodeRabbit 2026-10-30 major)。
|
|
79
|
+
* ⚠️ 引号方言按平台选择(CodeRabbit 2026-10-30 第二条 major,pwsh 实测复现注入):
|
|
80
|
+
* POSIX shell 里单引号内的 `'` 转义为 `'\''`;**PowerShell 的反斜杠不是转义符**,
|
|
81
|
+
* 同一串会让引号提前闭合、后面的 `; touch …` 真的执行 —— win32 改用 PowerShell 方言
|
|
82
|
+
*(`''` 转义内嵌单引号)。win32 的 hint 面向 PowerShell(Windows 现代默认 shell);
|
|
83
|
+
* cmd.exe 不识别单引号、`&` 在引号外仍会切命令,**不要把 win32 的 hint 原样粘进
|
|
84
|
+
* cmd.exe**。这两个边界都如实记录,不假装一种引号能通吃所有 shell。
|
|
85
|
+
*/
|
|
86
|
+
export function storeInitCommand(path, profileFlag) {
|
|
87
|
+
// 档名随路径一起带出(口径同 syncRunCommand):store init 也要落
|
|
88
|
+
// profiles.<name>.robots / store.options,重建出的库才是同一组数据。
|
|
89
|
+
return `qiyu store init --db ${shellArg(path)}`
|
|
90
|
+
+ (profileFlag === undefined ? '' : ` --profile ${shellArg(profileFlag)}`);
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* `qiyu sync run` 恢复命令,指向本次解析出的库与档(口径见 `storeInitCommand`)。
|
|
94
|
+
* `profileFlag`:本次**有显式来源**的档名(flag / QIYU_PROFILE / defaultProfile,
|
|
95
|
+
* 由 `resolveStoreConfig().profileFlag` 给出);内置 default 不传 —— 显式
|
|
96
|
+
* `--profile default` 会触发「点名档必须存在」守卫,在 profiles 非空且无 default 档时
|
|
97
|
+
* 反而让恢复命令失败。
|
|
98
|
+
*/
|
|
99
|
+
export function syncRunCommand(path, profileFlag) {
|
|
100
|
+
return `qiyu sync run --db ${shellArg(path)}`
|
|
101
|
+
+ (profileFlag === undefined ? '' : ` --profile ${shellArg(profileFlag)}`);
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* 从**尚未解析**的 `--db`/`--profile` 原始取值构造定位(前置闭集校验阶段的用法)。
|
|
105
|
+
* 两者都没给 → `undefined`(渲染不带任何 flag,等价于默认解析)。
|
|
106
|
+
*/
|
|
107
|
+
export function storeLocationFromFlags(flags) {
|
|
108
|
+
if (flags.db === undefined && flags.profile === undefined)
|
|
109
|
+
return undefined;
|
|
110
|
+
const loc = {};
|
|
111
|
+
if (flags.db !== undefined)
|
|
112
|
+
loc.db = flags.db;
|
|
113
|
+
if (flags.profile !== undefined)
|
|
114
|
+
loc.profile = flags.profile;
|
|
115
|
+
return loc;
|
|
116
|
+
}
|
|
117
|
+
/** 已解析出的库路径/档名 → 定位(命令层 `opened` 的用法)。 */
|
|
118
|
+
export function storeLocationOf(db, profile) {
|
|
119
|
+
return profile === undefined ? { db } : { db, profile };
|
|
120
|
+
}
|
|
121
|
+
/** `--db <p> [--profile <q>]`(带前导空格);两者都没有时返回空串。 */
|
|
122
|
+
export function storeLocationFlags(loc) {
|
|
123
|
+
if (loc === undefined)
|
|
124
|
+
return '';
|
|
125
|
+
let s = '';
|
|
126
|
+
if (loc.db !== undefined)
|
|
127
|
+
s += ` --db ${shellArg(loc.db)}`;
|
|
128
|
+
if (loc.profile !== undefined)
|
|
129
|
+
s += ` --profile ${shellArg(loc.profile)}`;
|
|
130
|
+
return s;
|
|
131
|
+
}
|
|
132
|
+
/** `qiyu db tables` 诊断命令,指向本次的存储定位(口径见 `StoreLocation`)。 */
|
|
133
|
+
export function dbTablesCommand(loc) {
|
|
134
|
+
return 'qiyu db tables' + storeLocationFlags(loc);
|
|
135
|
+
}
|
|
136
|
+
/**
|
|
137
|
+
* `qiyu db describe <表>` 诊断命令,指向本次的存储定位。
|
|
138
|
+
* `table` 只接受 `TABLES` 里的表名或占位符 `<表>`(代码内常量,不是用户输入)——
|
|
139
|
+
* 表中列名不承载外部输入,故原样渲染;路径/档名走 `shellArg`。
|
|
140
|
+
*/
|
|
141
|
+
export function dbDescribeCommand(table, loc) {
|
|
142
|
+
return `qiyu db describe ${table}` + storeLocationFlags(loc);
|
|
143
|
+
}
|
|
144
|
+
/** `qiyu sync status` 诊断命令,指向本次的存储定位(sync 族同样接受三件套)。 */
|
|
145
|
+
export function syncStatusCommand(loc) {
|
|
146
|
+
return 'qiyu sync status' + storeLocationFlags(loc);
|
|
147
|
+
}
|
|
148
|
+
/** `qiyu query --table <表>` 诊断命令,指向本次的存储定位。 */
|
|
149
|
+
export function queryTableCommand(table, loc) {
|
|
150
|
+
return `qiyu query --table ${table}` + storeLocationFlags(loc);
|
|
151
|
+
}
|
|
152
|
+
/**
|
|
153
|
+
* `query --sql` hint 里占位符的**替换契约**(三处 hint 共用这一句,避免文案漂移)。
|
|
154
|
+
*
|
|
155
|
+
* 为什么必须写出来(CodeRabbit 2026-10-30 major):占位符在**引号里**,用户若只把
|
|
156
|
+
* `<SQL>` 这个词换掉、引号留着,SQL 里带单引号时就会把引号提前闭合 ——
|
|
157
|
+
* `--sql 'SELECT '2026-10-01''` 经 shell 解析后 CLI 收到的是 `SELECT 2026-10-01`
|
|
158
|
+
*(可能照跑并给出不同结果,是静默错误而不是报错)。正确做法是**整段(含引号)**
|
|
159
|
+
* 换成按当前 shell 规则引号化好的 SQL 参数。
|
|
160
|
+
*/
|
|
161
|
+
export const SQL_ARG_REPLACE_NOTE = "`'<SQL>'` 要整段替换成按你的 shell 规则转义好的 SQL,不要只替换引号里的词";
|
|
162
|
+
/**
|
|
163
|
+
* `qiyu query --sql '<SQL>'` 诊断命令,指向本次的存储定位。
|
|
164
|
+
*
|
|
165
|
+
* ⚠️ 占位符不是装饰(CodeRabbit 2026-10-30 minor):`--sql` 是**取值** flag,
|
|
166
|
+
* 而 `commands/query.ts` 的值位守卫把「取值恰好是已知 flag」判为缺值 —— 渲染成
|
|
167
|
+
* `qiyu query --sql --db <path>` 时,`--db` 会被当成 `--sql` 的值位,逐字执行报
|
|
168
|
+
* 「--sql 缺少取值」并退出 2。**hint 里的命令必须真的能跑**,所以值位先给占位符,
|
|
169
|
+
* 定位 flag 排在它之后。
|
|
170
|
+
* 占位符**必须加引号**:SQL 含空格,`--sql SELECT 1` 在 shell 里会被拆成两个参数
|
|
171
|
+
*(`1` 落成位置参数 → 未知参数退出 2);`<`/`>` 不加引号还会变成重定向。
|
|
172
|
+
* 加引号的代价是替换契约必须一起说清 —— 见 `SQL_ARG_REPLACE_NOTE`,**用到本渲染器
|
|
173
|
+
* 的 hint 必须把它带上**(否则用户可能只替换引号内的词,见那里的静默错误说明)。
|
|
174
|
+
*/
|
|
175
|
+
export function querySqlCommand(loc) {
|
|
176
|
+
return "qiyu query --sql '<SQL>'" + storeLocationFlags(loc);
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* `db tables` / `db describe` / `stats fields` 的超时 hint(2026-11-05 审查修)。
|
|
180
|
+
*
|
|
181
|
+
* 这三个命令的查询是**整表统计**,不接受 `--since`/`--until`/`--limit` —— `query` 那句
|
|
182
|
+
* 「缩小时间范围或加过滤条件」对它们是一条走不通的路。可执行的替代只有:稍后重试,
|
|
183
|
+
* 或改用 `query --sql`(它才有 `--timeout`)。渲染器指向本次的库,占位符替换契约一并带上。
|
|
184
|
+
*/
|
|
185
|
+
export function metadataTimeoutHint(loc) {
|
|
186
|
+
return '本命令的统计按整表进行,没有可调的过滤参数;可稍后重试,或改用 `'
|
|
187
|
+
+ querySqlCommand(loc) + '` 单独执行同类统计(该通道支持 --timeout 调整超时预算,'
|
|
188
|
+
+ '0 = 不限时;' + SQL_ARG_REPLACE_NOTE + ')';
|
|
189
|
+
}
|
|
190
|
+
import { shellArg } from './core/shell.js';
|
|
191
|
+
export { shellArg };
|
|
54
192
|
/** 把不受信文本(调用方 body 的字段名等)中的终端控制字符抹成占位,防止 stderr 注入 ANSI/OSC 序列。 */
|
|
55
193
|
export { sanitizeControlChars, sanitizeMessage, stripSqlEcho } from './core/sanitize.js';
|
|
56
194
|
// usageFail 的出口净化要用(re-export 不建立本地绑定)。
|
|
57
195
|
import { sanitizeMessage } from './core/sanitize.js';
|
|
58
196
|
export function ok(data, meta) {
|
|
59
197
|
// ⚠️ `data` 必须**始终存在**,即便值是 undefined 也写成 null。
|
|
60
|
-
// 设计稿 §9.1 的成功形态是 `{ok, data, meta}` ——
|
|
198
|
+
// 设计稿 §9.1 的成功形态是 `{ok, data, meta}` —— 但只有 `ok`/`data` 恒在:
|
|
199
|
+
// `meta` 是**条件键**(有内容才出现,见下方两个分支与 `tests/output.test.ts`
|
|
200
|
+
// 「未提供 meta 时不输出该键」)。这条注释早前写的是「三个键都在」,与实现相反,
|
|
201
|
+
// 还经 README 传成了对 Agent 的承诺(2026-10-26 修正)。
|
|
61
202
|
// 若直接 `{ ok: true, data }`,JS 的 JSON.stringify 会把值为 undefined 的键**整个丢掉**,
|
|
62
203
|
// 于是 `ok(undefined)` 产出 `{"ok":true}`,Agent 无法区分
|
|
63
204
|
// "这个接口没有载荷"(robot.transfer.config 实测就是这样)与"我解析错了"。
|
|
@@ -154,11 +295,32 @@ function exitCodeFor(kind) {
|
|
|
154
295
|
export function fail(error) {
|
|
155
296
|
// 入参驼峰、出参下划线。这一层改写是刻意的:
|
|
156
297
|
// 内部改字段名不会破坏 Agent 契约,反之亦然。
|
|
298
|
+
//
|
|
299
|
+
// ⚠️ **净化必须在这唯一的错误出口做一次**(2026-11-02 第五轮审查,实测发现缺口):
|
|
300
|
+
// `message` 与 `hint` 里会拼进**调用方给的字节** —— `--db` 路径、表名、DuckDB 原文。
|
|
301
|
+
// 此前 `usageFail` / `failFromTagged` / `emitQueryFailure` 三个出口各自净化,而
|
|
302
|
+
// `fail()` 本体**没有**,于是走它直出的路径(`statGuard` 的库前置检查、
|
|
303
|
+
// `storeNotInitializedHint`、`thrownToExit` 的多数分支)把 C1 控制字符原样写进 stdout。
|
|
304
|
+
// 实测:`store status --db $'/tmp/x\u009b31mBAD.db'` 的 stdout 里出现原始字节
|
|
305
|
+
// `c2 9b 33 31 6d`(CSI 31m,终端里能改色/清屏),而同一路径在 `db describe` 的
|
|
306
|
+
// hint 里是 `·31m`(被净化过)—— **同一输入两种行为**,与本项目反复修的
|
|
307
|
+
// 「同一份规则复制到多处」同族。JSON.stringify **不会**转义 `\u007F-\u009F`
|
|
308
|
+
// (`\u009b` 原样输出),所以这层净化是终端注入的唯一防线。
|
|
309
|
+
//
|
|
310
|
+
// ⚠️ 净化**幂等**:上面三个出口已净化的消息再过一遍 `sanitizeMessage` 不变,
|
|
311
|
+
// 所以这里加一层不会让它们变成双重占位。
|
|
312
|
+
// ⚠️ 只净化**文本字段**:`retry_after` 是数字、`confirm_required` 等是布尔/闭集字面量,
|
|
313
|
+
// 不经过此函数;`target` 是回显给 Agent 的目标名(可能是路径/表名),一并净化。
|
|
157
314
|
const e = {
|
|
158
|
-
|
|
315
|
+
// ⚠️ `code` 也必须净化(2026-11-07 审查实测):它常是服务端返回的不可信字段
|
|
316
|
+
// (`envelope.ts` 的 `String(o.code ?? 'unknown')`),实测服务端回
|
|
317
|
+
// `code:"\u009b31mX"`(CSI)时原始 C1 控制字节原样进 stdout —— 与本函数上方
|
|
318
|
+
// 「唯一防线」的思路同源,此前只漏了这一个字段。
|
|
319
|
+
code: sanitizeMessage(error.code), kind: error.kind, retryable: error.retryable,
|
|
320
|
+
message: sanitizeMessage(error.message),
|
|
159
321
|
};
|
|
160
322
|
if (error.hint)
|
|
161
|
-
e.hint = error.hint;
|
|
323
|
+
e.hint = sanitizeMessage(error.hint);
|
|
162
324
|
if (error.retryAfter)
|
|
163
325
|
e.retry_after = error.retryAfter;
|
|
164
326
|
if (error.retryStrategy)
|
|
@@ -178,7 +340,7 @@ export function fail(error) {
|
|
|
178
340
|
e.confirm_required = true;
|
|
179
341
|
e.confirm_arg = '--yes';
|
|
180
342
|
e.risk = 'irreversible';
|
|
181
|
-
e.target = error.target ?? '';
|
|
343
|
+
e.target = sanitizeMessage(error.target ?? '');
|
|
182
344
|
// ⚠️ 硬置为 false,不接受调用方给别的值 —— 让人工确认一个不可逆操作失败后
|
|
183
345
|
// 自动重试,是最坏的结果(重复执行)。设计稿把这条写成「必须」。
|
|
184
346
|
e.retryable = false;
|
|
@@ -188,6 +350,32 @@ export function fail(error) {
|
|
|
188
350
|
write({ ok: false, error: e });
|
|
189
351
|
return exitCodeFor(error.kind);
|
|
190
352
|
}
|
|
353
|
+
/**
|
|
354
|
+
* 在**紧凑信封**下走一次 `fail()`(用法错误的唯一渲染口)。
|
|
355
|
+
*
|
|
356
|
+
* ⚠️ 契约(README「输出格式」/ 设计稿 §11.2):`--pretty` 只修饰**成功输出**,
|
|
357
|
+
* 用法错误(退出码 2)永远保持紧凑 —— 理由不是审美,而是「先修参数,再看格式」:
|
|
358
|
+
* 一个带缩进的错误信封恰好出现在「你这条命令根本没跑起来」的时刻,Agent 判断
|
|
359
|
+
* 格式是否生效时会拿它当「格式化已生效」的证据。
|
|
360
|
+
*
|
|
361
|
+
* ⚠️ `prettyOutput = false` 这一步**只在此一处**。此前 `usageFail` 自己写了一遍
|
|
362
|
+
* (只覆盖 `kind:'usage'`),而 `query/errors.ts` 的 `emitQueryFailure` 为保住真实
|
|
363
|
+
* code(`query_error` / `sandbox_blocked`)复刻了 stderr 写法却**没复刻这一句**,
|
|
364
|
+
* 于是 `query --sql 'SELEC 1' --pretty` 输出缩进信封、退出码 2 —— 同一契约两个结果。
|
|
365
|
+
* 复刻一处必然漏另一处,故收敛到这里。
|
|
366
|
+
*/
|
|
367
|
+
export function failCompact(error) {
|
|
368
|
+
const prevPretty = prettyOutput;
|
|
369
|
+
prettyOutput = false;
|
|
370
|
+
try {
|
|
371
|
+
return fail(error);
|
|
372
|
+
}
|
|
373
|
+
finally {
|
|
374
|
+
// 还原:用法错误是命令的终点,但同进程内连续多次 `run()`(测试里常见)时,
|
|
375
|
+
// 下一条命令不该因为上一条报了个用法错误就丢掉它的 `--pretty`。
|
|
376
|
+
prettyOutput = prevPretty;
|
|
377
|
+
}
|
|
378
|
+
}
|
|
191
379
|
/**
|
|
192
380
|
* 用法错误(退出码 2)的统一出口。
|
|
193
381
|
*
|
|
@@ -223,9 +411,13 @@ export function fail(error) {
|
|
|
223
411
|
export function failFromTagged(e) {
|
|
224
412
|
const err = e;
|
|
225
413
|
if (err.kind) {
|
|
414
|
+
// ⚠️ 净化必须在出口做(与 usageFail 同一约定):带 kind 的错误也会拼进路径/服务端原文,
|
|
415
|
+
// 此前这条分支直接透传 —— 而调用方换成 failFromTagged 后,原本 usageFail 里的净化就
|
|
416
|
+
// 消失了。sanitizeMessage 保留换行结构,正常文案一字不变。
|
|
226
417
|
return fail({
|
|
227
418
|
code: err.code ?? 'unknown', kind: err.kind, retryable: err.retryable ?? false,
|
|
228
|
-
message: err.message ?? String(e),
|
|
419
|
+
message: sanitizeMessage(err.message ?? String(e)),
|
|
420
|
+
...(err.hint !== undefined ? { hint: sanitizeMessage(err.hint) } : {}),
|
|
229
421
|
});
|
|
230
422
|
}
|
|
231
423
|
return usageFail(sanitizeMessage(err.message ?? String(e)));
|
|
@@ -237,27 +429,11 @@ export function usageFail(message, hint) {
|
|
|
237
429
|
// 而同文件的 `未知参数` / `--help` 多余参数路径没补,两种行为并存正是缺口的来源。
|
|
238
430
|
const safe = sanitizeMessage(message);
|
|
239
431
|
process.stderr.write(safe.endsWith('\n') ? safe : safe + '\n');
|
|
240
|
-
// ⚠️ 用法错误**永远是紧凑 JSON**,即使 `--pretty`
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
// 现在在唯一的出口处强制收窄 —— 逐个调用点调整次序既脆弱又会随新分支漂移。
|
|
248
|
-
const prevPretty = prettyOutput;
|
|
249
|
-
prettyOutput = false;
|
|
250
|
-
try {
|
|
251
|
-
return fail({
|
|
252
|
-
code: 'usage', kind: 'usage', retryable: false,
|
|
253
|
-
// message 去尾换行 —— stdout 的 JSON 里不该带控制字符;stderr 的文本保留换行便于阅读。
|
|
254
|
-
message: safe.replace(/\n+$/, ''),
|
|
255
|
-
...(hint !== undefined ? { hint: sanitizeMessage(hint) } : {}),
|
|
256
|
-
});
|
|
257
|
-
}
|
|
258
|
-
finally {
|
|
259
|
-
// 还原:用法错误是命令的终点,但同进程内连续多次 `run()`(测试里常见)时,
|
|
260
|
-
// 下一条命令不该因为上一条报了个用法错误就丢掉它的 `--pretty`。
|
|
261
|
-
prettyOutput = prevPretty;
|
|
262
|
-
}
|
|
432
|
+
// ⚠️ 用法错误**永远是紧凑 JSON**,即使 `--pretty` 已开启 —— 契约与理由见 `failCompact`。
|
|
433
|
+
return failCompact({
|
|
434
|
+
code: 'usage', kind: 'usage', retryable: false,
|
|
435
|
+
// message 去尾换行 —— stdout 的 JSON 里不该带控制字符;stderr 的文本保留换行便于阅读。
|
|
436
|
+
message: safe.replace(/\n+$/, ''),
|
|
437
|
+
...(hint !== undefined ? { hint: sanitizeMessage(hint) } : {}),
|
|
438
|
+
});
|
|
263
439
|
}
|
package/dist/postinstall.js
CHANGED
|
@@ -95,11 +95,20 @@ export async function runPostinstall(opts) {
|
|
|
95
95
|
force: false,
|
|
96
96
|
...(entityDir !== undefined ? { entityDir } : {}),
|
|
97
97
|
});
|
|
98
|
-
// 措辞按**实际**结果(审查 B2
|
|
99
|
-
//
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
98
|
+
// 措辞按**实际**结果(审查 B2):
|
|
99
|
+
// · `upToDate`(正文与清单都是包内那份)→ 「已是最新,跳过」;
|
|
100
|
+
// · 其余 `status === 'skipped'` → 「未完成更新」。
|
|
101
|
+
// ⚠️ 判据**不能**写成「`status === 'skipped' && plannedStatus === 'skipped'`」
|
|
102
|
+
// (2026-11-02 审查实测):`planInstall` 的 `skipped` 有四种含义,其中「内容不同且
|
|
103
|
+
// 未加 `--force`」「清单被非普通文件占用」「实体目录列不出来」三种都零写入且**没跟上**,
|
|
104
|
+
// 但 `plannedStatus` 同样是 `'skipped'` —— 旧写法把它们全说成「已是最新」,
|
|
105
|
+
// 紧接着下一行又打印「内容与包内不同,未覆盖」,同一进程两行自相矛盾(实测复现)。
|
|
106
|
+
// 判据现由 `installSkill` 算成 `result.upToDate` 一个字段(见 install.ts 的说明)。
|
|
107
|
+
const label = result.upToDate
|
|
108
|
+
? '已是最新,跳过'
|
|
109
|
+
: result.status === 'skipped'
|
|
110
|
+
? '未完成更新(详见下方提示)'
|
|
111
|
+
: `已安装(${result.status})`;
|
|
103
112
|
note(`skill ${label}:${result.entityDir}`);
|
|
104
113
|
if (result.warnings.length > 0) {
|
|
105
114
|
// 零链接(审查 B3 / #58)等提示同样要出现在 npm 自动安装路径上。
|
package/dist/query/errors.js
CHANGED
|
@@ -17,7 +17,18 @@
|
|
|
17
17
|
//
|
|
18
18
|
// ⚠️ 分层约束(spec §5.1):不 import `sync/`、`commands/`。`output.ts` 是 CLI 输出层
|
|
19
19
|
// (信封与退出码),不是命令层,可以 import。
|
|
20
|
-
import { fail, sanitizeMessage, stripSqlEcho } from '../output.js';
|
|
20
|
+
import { fail, failCompact, sanitizeMessage, stripSqlEcho, storeInitCommand, syncRunCommand, dbTablesCommand, dbDescribeCommand, querySqlCommand, SQL_ARG_REPLACE_NOTE } from '../output.js';
|
|
21
|
+
import { isLayer2Blocked, duckDbSaysMissingName, isOutOfMemory, isBinderOrCatalogError, isParserError, withoutSqlEcho, stripOomSolutions, } from './native-error.js';
|
|
22
|
+
/**
|
|
23
|
+
* OOM 的可操作 hint(2026-11-05:两处出口共用一份,避免同一成因两种说法)。
|
|
24
|
+
*
|
|
25
|
+
* ⚠️ 不能照抄 DuckDB 报文里的「Possible solutions」:那三条 SET 在只读沙箱里**必然失败**
|
|
26
|
+
* (`lock_configuration=true`,实测报 `configuration has been locked`)—— 建议一串
|
|
27
|
+
* 跑不动的命令比不给建议更糟。给的是本通道真能做的动作。
|
|
28
|
+
*/
|
|
29
|
+
export const OOM_HINT = '缩小时间范围、加过滤条件或减少排序/分组的列再试。'
|
|
30
|
+
+ '⚠️ 只读沙箱锁定了配置,DuckDB 报错里建议的 SET memory_limit / threads 等在这里会以 '
|
|
31
|
+
+ 'configuration has been locked 失败,不要照做';
|
|
21
32
|
/** 候选上限(spec §十一 / brief):超过即截断并加「等」。 */
|
|
22
33
|
const CANDIDATE_LIMIT = 5;
|
|
23
34
|
/** 编辑距离上限:只接受「打错一两个字符」的输入,再远就不是同一个名字了。 */
|
|
@@ -147,12 +158,62 @@ function candidateHint(candidates) {
|
|
|
147
158
|
// DuckDB 的错误消息会**回显 SQL 原文**(`LINE 1: …`),Parser Error 的报错里若恰好含
|
|
148
159
|
// `Referenced column "x" not found` 字样,无锚的正则会把「语法错」误判成「列不存在」。
|
|
149
160
|
// 实测:`SELECT 1 WHERE x = Referenced column "zzz" not found` → 原文是 Parser Error。
|
|
161
|
+
//
|
|
162
|
+
// ⚠️⚠️ **只锚类别前缀还不够**(2026-11-01 审查实测,与 PR #54 的报文回声污染同一形态):
|
|
163
|
+
// 回显区与列值都是**用户写的文本**,里面可以逐字含类别前缀。实测两个假归因:
|
|
164
|
+
// · `Parser Error: …` 的 `LINE 1:` 回显里写 ``SELEC'Binder Error: Referenced table "sessons" not found!'``
|
|
165
|
+
// → 纯**语法错**被报成「表 sessons 不存在」+ 候选 `sessions`(Agent 会去改它没写过的表名);
|
|
166
|
+
// · `SELECT … LIMIT '<值>'` 在 **prepare 期**常量折叠,`Conversion Error: Could not convert
|
|
167
|
+
// string 'Catalog Error: Table with name zzz does not exist!' to INT64 …` —— 值里的类别前缀
|
|
168
|
+
// 让 `TABLE_NAME_RE` 命中,**类型转换错误**被报成「表 zzz 不存在」。
|
|
169
|
+
// 判据因此收进 `native-error.ts` 的 `duckDbSaysMissingName`(**唯一实现点**):先剥 SQL 回显,
|
|
170
|
+
// 再要求 DuckDB **自己那句话在开头** —— 真报文的类别前缀就在报文开头(探针逐字核对:
|
|
171
|
+
// `Catalog Error: Table with name sessons does not exist!`),唯一带包装的是 Parser
|
|
172
|
+
//(`Failed to extract statements: Parser Error:`),而它不在本判据要认的类别里。
|
|
150
173
|
const TABLE_NAME_RE = /Catalog Error: Table with name ([^\s]+) does not exist/;
|
|
151
174
|
const TABLE_REF_RE = /Binder Error: Referenced table "([^"]+)" not found/;
|
|
152
175
|
const COLUMN_NAMED_RE = /Binder Error: Table "[^"]+" does not have a column named "([^"]+)"/;
|
|
153
176
|
const COLUMN_NAME_RE = /Binder Error: Referenced column "([^"]+)" (?:was )?not found/;
|
|
177
|
+
/** 四条的**唯一判定入口**:DuckDB 自己说「表/列不存在」才算(回显/列值里的仿冒串不算)。 */
|
|
178
|
+
function matchMissingName(msg, patterns) {
|
|
179
|
+
for (const p of patterns) {
|
|
180
|
+
const m = duckDbSaysMissingName(msg, p);
|
|
181
|
+
if (m !== null)
|
|
182
|
+
return m;
|
|
183
|
+
}
|
|
184
|
+
return null;
|
|
185
|
+
}
|
|
186
|
+
/**
|
|
187
|
+
* 「声明有而库中无」的成因与对策(**唯一实现**:db tables 的 warning、db describe 的
|
|
188
|
+
* warning、query --table 与 stats fields 的 hint 四个出口共用——同一事实四处拷贝必然漂移,
|
|
189
|
+
* 而 `db describe` 曾经独立写成「未同步或未建库」,两个成因都到不了该分支)。
|
|
190
|
+
*
|
|
191
|
+
* ⚠️ 成因口径经实测收窄(2026-10-29),「未同步」「未建库」两条都到不了这里:
|
|
192
|
+
* · 「未同步」不产生缺表:`store init` 的迁移一次建全部声明表,从未同步的库 25 张声明表
|
|
193
|
+
* 全在(row_count=0,无缺表警告);`sync run` 自身也先调 `store.init()`(sync-run.ts)。
|
|
194
|
+
* · 「未建库」到不了这个分支:`openGuardedSession` 先要求 `schema_version` 存在——库文件
|
|
195
|
+
* 不存在或零表时早已是 `store_not_initialized`(实测)。
|
|
196
|
+
* 能到达的只有两种:① 旧版 CLI 建的库,部分迁移没跑完(store init 会重放
|
|
197
|
+
* `version > MAX(version)` 的迁移,可补建);② 迁移已完成后表被删/损坏(store init
|
|
198
|
+
* 返回 ok 但**不会**重建该表——迁移已跳过;重新同步只会 Catalog Error
|
|
199
|
+
* `Table with name … does not exist`,实测)。
|
|
200
|
+
* 故文案不得承诺「store init 一定能修」,也不得把 Agent 指向「先同步一次」。
|
|
201
|
+
* ⚠️ 「重建库」是**破坏性**动作(CodeRabbit 2026-10-29 major):库中可能有 `db tables`
|
|
202
|
+
* 警告过的「未声明表」,也可能有超出 API 回补窗口的本地历史——删除库文件后,重建 +
|
|
203
|
+
* 重新同步都拿不回来。文案必须要求先备份再删除。
|
|
204
|
+
* ⚠️ 命令必须**指向本次的库**(2026-10-30 真库实测):这些 hint 出现在
|
|
205
|
+
* `--db <自定义路径>` 的输出里,裸 `qiyu store init` 会建**默认库**、原命令仍缺表。
|
|
206
|
+
* 渲染走 `storeInitCommand(path)` / `syncRunCommand(path)`(output.ts 的唯一实现)。
|
|
207
|
+
*/
|
|
208
|
+
export function missingTableCauses(path, profileFlag) {
|
|
209
|
+
return '若为建库未完成(迁移未跑完),运行 ' + storeInitCommand(path) + ' 可补建缺失的迁移;'
|
|
210
|
+
+ '若迁移已完成而表被删或损坏,store init 不会重建该表,重新同步也只会写入失败(缺表)'
|
|
211
|
+
+ '——需重建库:先备份库文件,再删除并重新 ' + storeInitCommand(path) + '、'
|
|
212
|
+
+ syncRunCommand(path, profileFlag)
|
|
213
|
+
+ '(未声明表与超出 API 回补窗口的本地历史无法靠重建恢复,删除前先确认)';
|
|
214
|
+
}
|
|
154
215
|
/** 表不存在的中文消息 + 候选 hint(原生分支与 cause 补算分支共用,裁决 R9)。 */
|
|
155
|
-
function tableNotFound(name, msg, tables) {
|
|
216
|
+
function tableNotFound(name, msg, tables, loc) {
|
|
156
217
|
const candidates = mergeCandidates(
|
|
157
218
|
// 多要一个:只有知道「还有第 6 个」才能决定 hint 末尾加不加「等」。
|
|
158
219
|
suggestNames(name, tables.map((t) => t.name), CANDIDATE_LIMIT + 1),
|
|
@@ -162,11 +223,11 @@ function tableNotFound(name, msg, tables) {
|
|
|
162
223
|
suggestNames(name, nativeCandidates(msg), CANDIDATE_LIMIT + 1));
|
|
163
224
|
return {
|
|
164
225
|
message: `表 ${name} 不存在`,
|
|
165
|
-
hint: candidates.length > 0 ? candidateHint(candidates) : '用 `
|
|
226
|
+
hint: candidates.length > 0 ? candidateHint(candidates) : '用 `' + dbTablesCommand(loc) + '` 查看可用表',
|
|
166
227
|
};
|
|
167
228
|
}
|
|
168
229
|
/** 列不存在的中文消息 + 候选 hint(候选池 = 全部表的全部列名:SQL 不告诉我们 FROM 哪张表)。 */
|
|
169
|
-
function columnNotFound(name, msg, tables) {
|
|
230
|
+
function columnNotFound(name, msg, tables, loc) {
|
|
170
231
|
const allColumns = [...new Set(tables.flatMap((t) => t.columns.map((c) => c.name)))];
|
|
171
232
|
const candidates = mergeCandidates(suggestNames(name, allColumns, CANDIDATE_LIMIT + 1),
|
|
172
233
|
// 同 tableNotFound:原生候选须过相关性闸门(正确性 P2)。
|
|
@@ -175,32 +236,34 @@ function columnNotFound(name, msg, tables) {
|
|
|
175
236
|
message: `列 ${name} 不存在`,
|
|
176
237
|
hint: candidates.length > 0
|
|
177
238
|
? candidateHint(candidates)
|
|
178
|
-
: '用 `
|
|
239
|
+
: '用 `' + dbDescribeCommand('<表>', loc) + '` 查看列清单',
|
|
179
240
|
};
|
|
180
241
|
}
|
|
181
242
|
/**
|
|
182
243
|
* 原文 → 表/列不存在的 { message, hint }(四种形态统一入口)。
|
|
183
244
|
* 不是表/列不存在时返回 null —— 调用方自行决定后续分派。
|
|
184
245
|
*/
|
|
185
|
-
function missingNameFailure(msg, tables) {
|
|
186
|
-
const byTableName =
|
|
246
|
+
function missingNameFailure(msg, tables, loc) {
|
|
247
|
+
const byTableName = matchMissingName(msg, [TABLE_NAME_RE, TABLE_REF_RE]);
|
|
187
248
|
if (byTableName)
|
|
188
|
-
return tableNotFound(byTableName[1], msg, tables);
|
|
189
|
-
const byColumn =
|
|
249
|
+
return tableNotFound(byTableName[1], msg, tables, loc);
|
|
250
|
+
const byColumn = matchMissingName(msg, [COLUMN_NAMED_RE, COLUMN_NAME_RE]);
|
|
190
251
|
if (byColumn)
|
|
191
|
-
return columnNotFound(byColumn[1], msg, tables);
|
|
252
|
+
return columnNotFound(byColumn[1], msg, tables, loc);
|
|
192
253
|
return null;
|
|
193
254
|
}
|
|
194
255
|
/**
|
|
195
256
|
* 原生错误 → QueryFailure(spec §十一 分派表)。
|
|
196
257
|
*
|
|
197
258
|
* 分派顺序有意义:先透传已分类错误,再按原文形态分流。
|
|
198
|
-
* ⚠️ layer2 的判定与 sandbox
|
|
199
|
-
*
|
|
200
|
-
*
|
|
259
|
+
* ⚠️ layer2 的判定与 sandbox **同源**(`query/native-error.ts` 的 `isLayer2Blocked`,
|
|
260
|
+
* 2026-11-01 单一实现点;此前两处各写一份逐字相同的正则):锚类别前缀
|
|
261
|
+
* `Permission Error:` + 特征句,并在判定前剥掉 SQL 回显 —— 只认「配置禁用了文件系统」
|
|
262
|
+
* 的措辞,**不认裸 `Permission Error`**(读库文件本身的 OS 权限错误也带这个前缀,
|
|
263
|
+
* 误报成「已被只读沙箱拦截」会把环境问题说成用法问题)。
|
|
201
264
|
* `retryable` 一律 false:这些都是确定性错误,重试同一个查询只会得到同样的结果。
|
|
202
265
|
*/
|
|
203
|
-
export function classifyDuckDbError(e, tables) {
|
|
266
|
+
export function classifyDuckDbError(e, tables, loc) {
|
|
204
267
|
// ① 已分类错误原样透传(sandbox 的分工:它分类,这里不重新分类)。
|
|
205
268
|
// ⚠️ 唯一例外(裁决 R9):sandbox 在 prepare 期把原生 Catalog/Binder 错误包成
|
|
206
269
|
// `usage`/`query_error` 并把原文挂在 `cause` 上 —— kind/code 仍以 sandbox 为准,
|
|
@@ -220,44 +283,53 @@ export function classifyDuckDbError(e, tables) {
|
|
|
220
283
|
const causeMsg = errorText(classified.cause);
|
|
221
284
|
// 表/列不存在只对 usage 补算(sandbox 的 prepare 期包装;Minor #6 守卫)。
|
|
222
285
|
if (classified.kind === 'usage') {
|
|
223
|
-
const refined = missingNameFailure(causeMsg, tables);
|
|
286
|
+
const refined = missingNameFailure(causeMsg, tables, loc);
|
|
224
287
|
if (refined) {
|
|
225
288
|
f.message = refined.message;
|
|
226
289
|
f.hint = refined.hint;
|
|
227
290
|
}
|
|
228
291
|
}
|
|
229
292
|
// R11:sandbox 的执行期 catch 把 OOM 包成 internal 且(修复后)挂 cause ——
|
|
230
|
-
// message 保持 sandbox 原文,只补可操作 hint
|
|
231
|
-
|
|
232
|
-
|
|
293
|
+
// message 保持 sandbox 原文,只补可操作 hint。⚠️ 原文里那段「Possible solutions」
|
|
294
|
+
// 的 SET 在只读沙箱里必然失败(见 `stripOomSolutions` 与 `OOM_HINT`),必须剥掉。
|
|
295
|
+
if (classified.kind === 'internal' && isOutOfMemory(causeMsg)) {
|
|
296
|
+
f.message = stripOomSolutions(f.message);
|
|
297
|
+
f.hint = OOM_HINT;
|
|
233
298
|
}
|
|
234
299
|
}
|
|
235
300
|
return f;
|
|
236
301
|
}
|
|
237
302
|
const msg = errorText(e);
|
|
238
|
-
// ② layer2 拦截(文件/网络):spec §十一 行 4
|
|
239
|
-
//
|
|
240
|
-
|
|
241
|
-
if (/file system operations are disabled|Cannot access file/i.test(msg)) {
|
|
303
|
+
// ② layer2 拦截(文件/网络):spec §十一 行 4。判据与 sandbox 同源
|
|
304
|
+
// (`native-error.ts` 的 `isLayer2Blocked`,单一实现点;形态与边界见那里)。
|
|
305
|
+
if (isLayer2Blocked(msg)) {
|
|
242
306
|
return {
|
|
243
307
|
kind: 'usage', code: 'sandbox_blocked', retryable: false,
|
|
244
308
|
message: '该语句尝试访问文件或网络,已被只读沙箱拦截',
|
|
245
309
|
};
|
|
246
310
|
}
|
|
247
311
|
// ③ 表/列不存在:spec §十一 行 5(四种原生形态统一走 missingNameFailure)。
|
|
248
|
-
const missing = missingNameFailure(msg, tables);
|
|
312
|
+
const missing = missingNameFailure(msg, tables, loc);
|
|
249
313
|
if (missing) {
|
|
250
314
|
return { kind: 'usage', code: 'query_error', retryable: false, ...missing };
|
|
251
315
|
}
|
|
252
316
|
// ④ SQL 语法错:spec §十一 行 6 —— 中文包装 + 底层原文(原文自带位置信息,保留全部行)。
|
|
253
|
-
|
|
317
|
+
// 判据走唯一实现点(锚开头 + 剥回显):子串判会被列值里那句 `Parser Error` 伪造,
|
|
318
|
+
// 把类型转换错误说成语法错(修法完全不同:改数据 vs 改 SQL)。
|
|
319
|
+
if (isParserError(msg)) {
|
|
254
320
|
return {
|
|
255
321
|
kind: 'usage', code: 'query_error', retryable: false,
|
|
256
322
|
message: `SQL 语法错误:${msg}`,
|
|
257
323
|
};
|
|
258
324
|
}
|
|
259
325
|
// ⑤ 未绑参:spec §十一 行 6(「SQL 语法错 / 未绑参」同归 usage/query_error)。
|
|
260
|
-
|
|
326
|
+
// ⚠️ 实测两件事:① 真报文前缀是 `Invalid Input Error: Expected 1 parameters, but none were
|
|
327
|
+
// supplied`(探针:`conn.run('SELECT ?')`);prepared 路径抛的是另一句
|
|
328
|
+
// `Values were not provided for the following prepared statement parameters`。本 CLI 的
|
|
329
|
+
// 沙箱在 layer1-③ 用 `parameterCount !== params.length` **提前拦下**,所以这一支在
|
|
330
|
+
// 用户 SQL 路径上不可达,是防御支;② 即便如此也**锚开头 + 剥回显** —— 子串判同样可被
|
|
331
|
+
// 回显里那句字面量伪造(与 ③⑥⑦ 同族),假归因不会因为分支不可达就变得无害。
|
|
332
|
+
if (/^\s*Invalid Input Error:\s*Expected \d+ parameters/i.test(withoutSqlEcho(msg))) {
|
|
261
333
|
return {
|
|
262
334
|
kind: 'usage', code: 'query_error', retryable: false,
|
|
263
335
|
message: `SQL 参数个数不匹配:${msg}`,
|
|
@@ -265,8 +337,9 @@ export function classifyDuckDbError(e, tables) {
|
|
|
265
337
|
};
|
|
266
338
|
}
|
|
267
339
|
// ⑥ 其余 Binder / Catalog 错误(函数不存在、类型不匹配等):同样是 SQL 写错了。
|
|
268
|
-
//
|
|
269
|
-
|
|
340
|
+
// 判据走唯一实现点(锚开头 + 剥回显,容忍 `Failed to extract statements: ` 包装):
|
|
341
|
+
// 子串判会被列值/回显里的 `Catalog Error:` 伪造,把类型转换错误说成 SQL 写错。
|
|
342
|
+
if (isBinderOrCatalogError(msg)) {
|
|
270
343
|
return {
|
|
271
344
|
kind: 'usage', code: 'query_error', retryable: false,
|
|
272
345
|
message: `SQL 无法执行:${msg}`,
|
|
@@ -274,11 +347,13 @@ export function classifyDuckDbError(e, tables) {
|
|
|
274
347
|
};
|
|
275
348
|
}
|
|
276
349
|
// ⑦ 内存不足:环境问题,不是 SQL 写错 —— internal + 可操作 hint。
|
|
277
|
-
|
|
350
|
+
// 判据走唯一实现点:子串判会被列值里的 `Out of Memory Error` 伪造,给类型转换错误
|
|
351
|
+
// 补一条「缩小时间范围」的假修法。
|
|
352
|
+
if (isOutOfMemory(msg)) {
|
|
278
353
|
return {
|
|
279
354
|
kind: 'internal', code: 'internal', retryable: false,
|
|
280
|
-
message: `查询内存不足(${msg})`,
|
|
281
|
-
hint:
|
|
355
|
+
message: `查询内存不足(${stripOomSolutions(msg)})`,
|
|
356
|
+
hint: OOM_HINT,
|
|
282
357
|
};
|
|
283
358
|
}
|
|
284
359
|
// ⑧ 其余执行期错误 → internal,中文包装 + 底层原文(不裸透,spec §十一 末行)。
|
|
@@ -296,12 +371,14 @@ export function classifyDuckDbError(e, tables) {
|
|
|
296
371
|
* spec §十一 分派表的 code 列(`query_error` / `sandbox_blocked`)——而命令层测试
|
|
297
372
|
* (plan Task 8「多语句 / COPY / ATTACH → sandbox_blocked」)正是按 code 断言的。
|
|
298
373
|
* ⚠️ **这是有意偏离 `usageFail`,不是遗漏**(controller 裁决 R9 concern #2 确认保留):
|
|
299
|
-
* 故这里复刻 usageFail 的 stderr 写法,stdout
|
|
300
|
-
*
|
|
301
|
-
* `
|
|
374
|
+
* 故这里复刻 usageFail 的 stderr 写法,stdout 交回 `output.ts` 的出口渲染,保留真实 code。
|
|
375
|
+
* ⚠️ 紧凑信封**必须复用 `failCompact`**(2026-11-02 实测修):此前这里只复刻了 stderr
|
|
376
|
+
* 写法、直接调 `fail()`,于是 `query --sql 'SELEC 1' --pretty` 输出**缩进**错误信封、
|
|
377
|
+
* 退出码 2 —— 与 `usageFail` 承诺的「用法错误永远紧凑」相反。复刻一半比不复刻更危险:
|
|
378
|
+
* 两处看着都在「照同一份契约做」,行为却不同。
|
|
302
379
|
*/
|
|
303
|
-
export function thrownToQueryExit(e, tables, noMask = false) {
|
|
304
|
-
return emitQueryFailure(classifyDuckDbError(e, tables), noMask);
|
|
380
|
+
export function thrownToQueryExit(e, tables, noMask = false, loc) {
|
|
381
|
+
return emitQueryFailure(classifyDuckDbError(e, tables, loc), noMask);
|
|
305
382
|
}
|
|
306
383
|
/**
|
|
307
384
|
* 已分类失败的唯一出口(`thrownToQueryExit` 与 `--table` 漂移识别共用)。
|
|
@@ -351,10 +428,11 @@ export function emitQueryFailure(f, noMask = false) {
|
|
|
351
428
|
};
|
|
352
429
|
const message = clean(f.message);
|
|
353
430
|
const hint = f.hint === undefined ? undefined : clean(f.hint);
|
|
431
|
+
const render = f.kind === 'usage' ? failCompact : fail;
|
|
354
432
|
if (f.kind === 'usage') {
|
|
355
433
|
process.stderr.write(message.endsWith('\n') ? message : message + '\n');
|
|
356
434
|
}
|
|
357
|
-
return
|
|
435
|
+
return render({
|
|
358
436
|
code: f.code, kind: f.kind, retryable: f.retryable,
|
|
359
437
|
message: message.replace(/\n+$/, ''),
|
|
360
438
|
...(hint !== undefined ? { hint } : {}),
|
|
@@ -371,24 +449,46 @@ export function emitQueryFailure(f, noMask = false) {
|
|
|
371
449
|
* 判据收紧到「缺失名确实属于该表的声明」才认作漂移 —— 否则可能把真实的代码 bug
|
|
372
450
|
*(生成的 SQL 里写错了列名)掩盖成环境问题。不属于时返回 null,交回原生分派。
|
|
373
451
|
*/
|
|
374
|
-
export function driftFailureFor(table, e) {
|
|
375
|
-
|
|
376
|
-
|
|
452
|
+
export function driftFailureFor(table, e, loc) {
|
|
453
|
+
// ⚠️ 判据要吃**原生原文**:sandbox 把 prepare 期的原生错误包成 `SQL 无法执行:…` 并把原文
|
|
454
|
+
// 挂在 `cause` 上(裁决 R9),而 2026-11-01 起表/列判据要求「DuckDB 自己那句话在报文
|
|
455
|
+
// 开头」—— 拿包装后的中文串去判会**永远不命中**(本用例实测:删列后 hint 退化成
|
|
456
|
+
// 「用 db describe <表> 查看列清单」,把用户支使去改一个它没写过的东西,正是本函数要防的)。
|
|
457
|
+
const msg = errorText(e?.cause ?? e);
|
|
458
|
+
const byTable = matchMissingName(msg, [TABLE_NAME_RE, TABLE_REF_RE]);
|
|
377
459
|
if (byTable !== null && byTable[1] === table.name) {
|
|
378
460
|
return {
|
|
379
461
|
code: 'query_error', kind: 'usage', retryable: false,
|
|
380
462
|
message: `表 ${table.name} 在库中不存在——与 TABLES 声明漂移(表被删或建库不完整)`,
|
|
381
|
-
hint:
|
|
382
|
-
+ '并考虑重新同步或重建库(`
|
|
463
|
+
hint: '这不是你的查询写错了:本命令的 SQL 由 CLI 生成。用 `' + dbDescribeCommand(table.name, loc) + '` 核对,'
|
|
464
|
+
+ '并考虑重新同步或重建库(`'
|
|
465
|
+
+ (loc?.db !== undefined ? storeInitCommand(loc.db) : 'qiyu store init')
|
|
466
|
+
+ '` 只补未执行的迁移,不重建已删的表)',
|
|
383
467
|
};
|
|
384
468
|
}
|
|
385
|
-
const byColumn =
|
|
469
|
+
const byColumn = matchMissingName(msg, [COLUMN_NAMED_RE, COLUMN_NAME_RE]);
|
|
386
470
|
if (byColumn !== null && table.columns.some((c) => c.name === byColumn[1])) {
|
|
471
|
+
const missing = byColumn[1];
|
|
472
|
+
// 被删的恰好是**时间列**时,hint 只指 db describe 等于没有出路(2026-11-09 审计实测):
|
|
473
|
+
// 本命令的 WHERE/SELECT 由代码按声明生成,只要时间列不在库里,任何 --since/--until
|
|
474
|
+
// 查询都会以同一条错误失败,--group-by 也绕不过 SELECT 列表里的该列。所以必须说明
|
|
475
|
+
// 「修好之前哪些用法不可用」,并给出真能跑的替代(--sql 不行——它同样在 SELECT * 时撞列,
|
|
476
|
+
// 但可以显式列只取保留下来的列)。
|
|
477
|
+
const timeCol = table.timeColumn;
|
|
478
|
+
const isTimeCol = timeCol !== undefined && timeCol.name === missing;
|
|
479
|
+
const hint = isTimeCol
|
|
480
|
+
? '这不是你的查询写错了:本命令的 SQL 由 CLI 生成,列名来自 TABLES 声明。'
|
|
481
|
+
+ `时间列 ${missing} 恢复前,本命令对该表的 --since/--until(以及默认的整表查询)都会失败;`
|
|
482
|
+
+ '用 `' + querySqlCommand(loc) + '` 显式列出其余列(不选 ' + missing + ')可先把已有数据读出来('
|
|
483
|
+
+ SQL_ARG_REPLACE_NOTE + '),'
|
|
484
|
+
+ '根因修复用 `' + dbDescribeCommand(table.name, loc) + '` 核对漂移后重新同步或重建库'
|
|
485
|
+
: '这不是你的查询写错了:本命令的 SQL 由 CLI 生成,列名来自 TABLES 声明。'
|
|
486
|
+
+ '用 `' + dbDescribeCommand(table.name, loc) + '` 查看实际列集与漂移警告,'
|
|
487
|
+
+ '并按提示重新同步或重建库';
|
|
387
488
|
return {
|
|
388
489
|
code: 'query_error', kind: 'usage', retryable: false,
|
|
389
|
-
message: `列 ${
|
|
390
|
-
hint
|
|
391
|
-
+ `用 \`qiyu db describe ${table.name}\` 查看实际列集与漂移警告`,
|
|
490
|
+
message: `列 ${missing} 在库中不存在(表 ${table.name})——库与 TABLES 声明漂移`,
|
|
491
|
+
hint,
|
|
392
492
|
};
|
|
393
493
|
}
|
|
394
494
|
return null;
|