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/commands/query.js
CHANGED
|
@@ -1,17 +1,22 @@
|
|
|
1
|
-
import { suggestNames, thrownToQueryExit, driftFailureFor, emitQueryFailure } from '../query/errors.js';
|
|
2
|
-
import { maskQueryRows } from '../query/mask.js';
|
|
1
|
+
import { suggestNames, thrownToQueryExit, driftFailureFor, emitQueryFailure, missingTableCauses } from '../query/errors.js';
|
|
2
|
+
import { maskQueryRows, withoutLiterals, withoutComments, queryCallArgs, readSqlString, sqlFunctionCalls, skipSqlTrivia, isIdentAt, isIdentCharAt, } from '../query/mask.js';
|
|
3
3
|
import { parseTimeArg, shanghaiIso, msToShanghaiIso, shanghaiYesterdayStart } from '../core/time.js';
|
|
4
4
|
import { TABLES, tableByName } from '../store/schema.js';
|
|
5
|
-
import { buildCoverageQuery, buildMinQuery, buildTableQuery, effectiveBound, validateGroupBy, } from '../query/table-query.js';
|
|
5
|
+
import { buildCoverageQuery, buildDirtyTimeQuery, buildMinQuery, buildTableQuery, effectiveBound, validateGroupBy, } from '../query/table-query.js';
|
|
6
6
|
import { openGuardedSession } from './db.js';
|
|
7
|
-
import {
|
|
8
|
-
import {
|
|
7
|
+
import { queryFieldNotes } from './query-notes.js';
|
|
8
|
+
import { DB_PATH_HELP } from './store-flags.js';
|
|
9
|
+
import { ok, fail, usageFail, sanitizeControlChars, describeArgs, setPretty, syncRunCommand, dbTablesCommand, dbDescribeCommand, syncStatusCommand, queryTableCommand, querySqlCommand, SQL_ARG_REPLACE_NOTE, storeLocationFromFlags, storeLocationOf, } from '../output.js';
|
|
10
|
+
import { GLOBAL_FLAGS, GLOBAL_FLAG_NAMES, helpArgsError, REJECTED_FLAGS, STORE_FLAGS, valueFlagNames } from './spec-types.js';
|
|
9
11
|
/**
|
|
10
12
|
* `query` 的业务 flag。`--group-by` 标 `repeatable`:可重复给(每次吃一个值)。
|
|
11
13
|
* 存储定位三件套直接用 `STORE_FLAGS`(与 `parseStoreFlags` 同一份事实源)。
|
|
12
14
|
*/
|
|
13
15
|
const QUERY_FLAGS = [
|
|
14
|
-
|
|
16
|
+
// ⚠️ `dashValue`:`--sql` 的取值可以以 `--` 开头(SQL 的行注释 `-- …`)。
|
|
17
|
+
// 它同时驱动本文件的值位守卫与帮助模式检查(`spec-types.ts` 的 `helpArgsError`)——
|
|
18
|
+
// 一个字段两个消费者,不各写一份判据。
|
|
19
|
+
{ name: '--sql', kind: 'value', dashValue: true },
|
|
15
20
|
{ name: '--table', kind: 'value' },
|
|
16
21
|
{ name: '--since', kind: 'value' },
|
|
17
22
|
{ name: '--until', kind: 'value' },
|
|
@@ -49,10 +54,12 @@ const USAGE = `用法:qiyu query <查询方式> [参数]
|
|
|
49
54
|
--no-mask 关闭默认脱敏,输出原始 PII(不要写入日志或对外报表)
|
|
50
55
|
--db <path> / --profile <name> / --backend <name>
|
|
51
56
|
存储定位(与 store / sync 命令同族)
|
|
57
|
+
${DB_PATH_HELP}
|
|
52
58
|
|
|
53
|
-
|
|
59
|
+
只接受单条只读查询(DuckDB 判为「只读」的语句都放行:SELECT、DESCRIBE、SHOW、EXPLAIN、
|
|
60
|
+
PRAGMA 查询形态、VALUES、TABLE <表>、FROM <表> 等);写操作、SET/CALL 之类的实例配置、多语句、
|
|
61
|
+
文件与网络访问一律被沙箱拦截。实测放行/拦截清单见 README「只读沙箱」。
|
|
54
62
|
`;
|
|
55
|
-
const KNOWN = new Set(GLOBAL_FLAG_NAMES);
|
|
56
63
|
/**
|
|
57
64
|
* 值位参数(缺值或值以 `--` 开头 → 报缺值,防止把下一个 flag 当取值)。
|
|
58
65
|
* 从 `QUERY_FLAGS` 派生而不是手写:`--db/--profile/--backend` 与 spec 的 `STORE_FLAGS`
|
|
@@ -65,6 +72,8 @@ const VALUE_FLAGS = new Set(valueFlagNames(QUERY_FLAGS));
|
|
|
65
72
|
* 「取值只是以 `--` 开头」(SQL 的行注释,合法输入)。
|
|
66
73
|
*/
|
|
67
74
|
const FLAG_TOKENS = new Set([...VALUE_FLAGS, ...QUERY_FLAGS.map((f) => f.name), ...GLOBAL_FLAG_NAMES]);
|
|
75
|
+
/** 取值允许以 `--` 开头的值位 flag(`FlagSpec.dashValue`,唯一事实源)。 */
|
|
76
|
+
const DASH_VALUE_FLAGS = new Set(QUERY_FLAGS.filter((f) => f.dashValue === true).map((f) => f.name));
|
|
68
77
|
/**
|
|
69
78
|
* 超时上界 = Node 定时器的最大延迟(2^31−1 ms)。超过它 setTimeout 会**溢出成 1ms**
|
|
70
79
|
* 立即触发 —— 用户本想「几乎不限时」却得到「立刻超时」,是静默的语义反转,必须拒绝。
|
|
@@ -77,8 +86,14 @@ const TIMEOUT_MAX_MS = 2_147_483_647;
|
|
|
77
86
|
// ⚠️ 大小写不敏感(契约审查 C-02):DuckDB 标识符不分大小写,`WHERE STARTTIME …`
|
|
78
87
|
// 是合法 SQL;敏感匹配会让 0 行警告静默失效(正是「0 行 ≠ 没有数据」要防的场景)。
|
|
79
88
|
const ZERO_ROW_TIME_RE = /\b(stat_date|work_date|hour_ts|startTime|endTime)\b/i;
|
|
80
|
-
/**
|
|
81
|
-
|
|
89
|
+
/**
|
|
90
|
+
* 0 行警告的后半句(两个通道同源);前半句各自说明触发条件与实际区间。
|
|
91
|
+
* 带本次存储定位:`sync status` 不带 `--db` 会去看默认库的覆盖范围(#45 边界 ②)。
|
|
92
|
+
*/
|
|
93
|
+
function zeroRowHint(loc) {
|
|
94
|
+
return '这不代表没有数据:同步可能未覆盖该区间——用 `' + syncStatusCommand(loc)
|
|
95
|
+
+ '` 查看覆盖范围,或放宽过滤条件';
|
|
96
|
+
}
|
|
82
97
|
/**
|
|
83
98
|
* iso-day 字面量比较警告(端到端场景 F3,`--sql` 通道)。
|
|
84
99
|
*
|
|
@@ -89,18 +104,284 @@ const ZERO_ROW_HINT = '这不代表没有数据:同步可能未覆盖该区间
|
|
|
89
104
|
* `'2026-10-12T16:00:00.000Z' >= '2026-10-13T00:00:00+08:00'` 为 false,整整少一天,
|
|
90
105
|
* 退出码 0、四道自证机制一道都不响。
|
|
91
106
|
*
|
|
92
|
-
* 判据 = SQL 文本同时含 iso-day
|
|
93
|
-
|
|
94
|
-
* 方向安全(多警告):误报只多一句话;UTC `…Z` 形态与 `--table` 通道不受影响。
|
|
107
|
+
* 判据 = SQL 文本同时含 iso-day 列名与「会被字典序比较错的一天」形态的**单引号字面量**
|
|
108
|
+
*(`dayLiteralHint`,下方)。方向安全(多警告):误报只多一条附带修复方法的 warning。
|
|
95
109
|
*/
|
|
96
110
|
// ⚠️ 大小写不敏感,理由同上(`STAT_DATE >= '2026-10-13'` 同样会少一天)。
|
|
97
111
|
const ISO_DAY_COL_RE = /\b(stat_date|work_date)\b/i;
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
112
|
+
/**
|
|
113
|
+
* 单引号字面量的内容里是否有「按字典序比较会少一天」的形态。
|
|
114
|
+
*
|
|
115
|
+
* 列内只存两种合法形态:上海日零点写成 `YYYY-MM-DDT16:00:00.000Z`(UTC 数值),
|
|
116
|
+
* 或整值为 NULL。按字典序比较时,下列字面量都会把前端那一天排除或错位:
|
|
117
|
+
* · `YYYY-MM-DD` / `YYYY-MM-DD 00:00:00` / `…T00:00:00`(任何不带时区或 +08:00 的写法)
|
|
118
|
+
* · `YYYY-MM-DD…Z`(**这是 UTC 时刻,不是上海日**:`'…T00:00:00Z'` 只有上海 08:00 起才算数)
|
|
119
|
+
* · `YYYY-MM-DD…+08:00` 以外的偏移(如 `+0800`、`…-05:00`)
|
|
120
|
+
* · 任何与库内形态**不逐字一致**的写法(空格分隔、前导空白、多/少小数位……)
|
|
121
|
+
* 唯一的合法写法(UTC 16:00Z 且带小数秒,如 `'2026-10-12T16:00:00.000Z'`)放行。
|
|
122
|
+
*
|
|
123
|
+
* 2026-11-09 实测漏报(旧 `DAY_LITERAL_RE` 只认 `YYYY-MM-DD[ 或 T]00:00:00[.0…][+08:00]`):
|
|
124
|
+
* `'2026-11-08T00:00:00Z'`、`'2026-11-09 00:00:00.000Z'`、`'2026-11-08T00:00:00.000Z'`
|
|
125
|
+
* 三种都静默少算一天、零 warning —— 其中 `…Z` 形态正是 CLI 自己 `--sql` 示例里教的写法。
|
|
126
|
+
*/
|
|
127
|
+
// ⚠️ 秒可缺省(CodeRabbit 2026-11-10):`'2026-10-13 00:00'` / `'…T00:00Z'` 同样按字典序
|
|
128
|
+
// 少算一天,要求秒会把它们漏掉(缺秒时 frac/tz 恒为 null → 下面按「不是列内形态」返回 true)。
|
|
129
|
+
// ⚠️ 分隔符只认 `T`(Codex 2026-11-10 第十一轮 P2):库内形态恒为 `…T16:00:00.000Z`,
|
|
130
|
+
// 空格分隔在字典序上排在 `T` 之前 —— 实测 `stat_date <= '2026-10-13 16:00:00.000Z'` 把
|
|
131
|
+
// 边界日整列排除。允许 `[T ]` 会让这种写法被当成「逐字一致」放行、零警告。
|
|
132
|
+
const DAY_VALUE_RE = /^(\d{4}-\d{2}-\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2}))?(?:\.(\d+))?(Z|[+-]\d{2}:?\d{2})?)?/;
|
|
133
|
+
function isMiscomparedDayLiteral(v) {
|
|
134
|
+
// ⚠️ 判据是「日形态**前缀**」,不是完整匹配(Codex 2026-11-10 第七轮 P2):比较发生在
|
|
135
|
+
// VARCHAR 原文上 —— 实测库值 `…16:00:00.000Z` >= `'…16:00:00.000Z '` 为 **false**,
|
|
136
|
+
// 尾随字符把字面量排到库值之后、边界日整列被排除。旧实现先 `trim()` 再完整匹配,
|
|
137
|
+
// 把它当成列内形态放行(零警告);而只去掉 `trim()` 又会因完整匹配失败落到「不像日期」
|
|
138
|
+
// 分支、同样零警告 —— 必须「按前缀认出是日形态」再单独判是否逐字一致。
|
|
139
|
+
// **前导**空白同样警告(Codex 2026-11-10 第十一轮 P2,实测):`<= ' 2026-…Z'` 一行都不剩。
|
|
140
|
+
// 旧注释按 `>=` 单方向实证「不排除任何行」就放行 —— 反过来用就是静默漏报;判据看不到
|
|
141
|
+
// 运算符,只能按方向安全一律算错位。
|
|
142
|
+
if (v !== v.trimStart())
|
|
143
|
+
return DAY_VALUE_RE.test(v.trimStart());
|
|
144
|
+
const m = DAY_VALUE_RE.exec(v);
|
|
145
|
+
if (m === null)
|
|
146
|
+
return false;
|
|
147
|
+
const exact = m[0].length === v.length;
|
|
148
|
+
if (m[2] === undefined)
|
|
149
|
+
return true; // 纯日期
|
|
150
|
+
// ⚠️ 命中了时刻但没给小数秒/时区时,分组是 `null`(不是 `undefined`)—— 两种都按「不是列内形态」
|
|
151
|
+
// 处理;只判 `undefined` 会让这种字面量一路走到最后返回 false(2026-11-10 回归发现)。
|
|
152
|
+
const frac = m[5] ?? null;
|
|
153
|
+
const tz = m[6] ?? null;
|
|
154
|
+
if (frac === null || tz === null)
|
|
155
|
+
return true; // 没有小数秒或没有时区:不可能是列内形态
|
|
156
|
+
// 只有恰好 `.000` 才是列内形态(Codex 2026-11-10 P2):`.123` 这类字面量在字典序上会
|
|
157
|
+
// 排在 `…16:00:00.000Z` 之后、把当天行排除在外,旧判据(≥3 位即放行)会静默漏报。
|
|
158
|
+
if (frac !== '000')
|
|
159
|
+
return true; // 列内形态恒为三位 `.000`(`.123` 在字典序上把当天行排除)
|
|
160
|
+
if (m[2] !== '16' || m[3] !== '00' || m[4] !== '00')
|
|
161
|
+
return true; // 不是 16:00:00 的 UTC 形态
|
|
162
|
+
if (tz !== 'Z')
|
|
163
|
+
return true; // `+08:00`/`+0800` 等一律错位
|
|
164
|
+
return !exact; // 尾随字符:库值是它的严格前缀 → 排除边界日
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* `--sql` 通道的日期字面量警告判据(单一实现点)。
|
|
168
|
+
*
|
|
169
|
+
* 词法复用 `mask.ts` 的同一个状态机(`withoutComments` / `withoutLiterals`,逐位对齐):
|
|
170
|
+
* 列名在「抹掉注释与字面量」的文本上找(注释里的 `-- WHERE stat_date …` 不是真条件;
|
|
171
|
+
* `"stat_date"` 双引号标识符原样保留、仍算列名);字面量在「只抹注释」的文本上按
|
|
172
|
+
* 单引号状态逐个读出(`'it''s'` 是转义、不是两个字面量)。
|
|
173
|
+
*/
|
|
174
|
+
function dayLiteralHint(sql, loc) {
|
|
175
|
+
return dayHintOf(sql, loc)?.text ?? null;
|
|
176
|
+
}
|
|
177
|
+
function dayHintOf(sql, loc) {
|
|
178
|
+
// `query('<内层 SQL>')` 包装(沙箱放行的形态)里真正执行的是**实参内的 SQL**:
|
|
179
|
+
// `withoutLiterals` 会把整个实参抹掉,只看外层就会漏掉内层里的错位日字面量
|
|
180
|
+
//(Codex 2026-11-10 第二轮 P2,实测 `SELECT * FROM query($$…stat_date >= '2026-10-13'$$)`
|
|
181
|
+
// 少算一天却零警告)。递归检查每个实参的内层 SQL(内层还能再套 query())。
|
|
182
|
+
let unexpandable = false;
|
|
183
|
+
for (const inner of queryCallArgs(withoutComments(sql), () => { unexpandable = true; })) {
|
|
184
|
+
const innerHint = dayHintOf(inner, loc);
|
|
185
|
+
if (innerHint?.kind === 'mismatch')
|
|
186
|
+
return innerHint;
|
|
187
|
+
// 里层的「没法检查」只记下:外层可能还有已确认的错位(见本函数头部注释)。
|
|
188
|
+
if (innerHint !== null)
|
|
189
|
+
unexpandable = true;
|
|
190
|
+
}
|
|
191
|
+
// 注释先抹成空白(逐位对齐):注释里写的 `-- WHERE stat_date >= '…'` 不是真条件。
|
|
192
|
+
const code = withoutComments(sql);
|
|
193
|
+
// ⚠️ 不要只判 `withoutLiterals(code)`:列名可能藏在**有执行语义的字符串**里 ——
|
|
194
|
+
// `COLUMNS('stat_date')` / `COLUMNS('stat.*')` 是列选择器(实测
|
|
195
|
+
// `WHERE COLUMNS('stat_date') >= '2026-10-13'` 两天夹具只计一天,Codex 2026-11-10 第六轮 P2),
|
|
196
|
+
// 而 `withoutLiterals` 会把整个串抹掉。也不能放宽到 `code` 原样:普通字面量里的
|
|
197
|
+
// `'stat_date'` 不是列引用,那会让无关日期字面量也报上。
|
|
198
|
+
// ⚠️ 「无法检查」不能盖过**已确认**的错位(CodeRabbit 2026-11-11 第十四轮,实测):
|
|
199
|
+
// 外层 `stat_date >= '2026-10-13'` 是确定的少算一天,同句再带一个拼接实参的 `query()`
|
|
200
|
+
// 时若提前返回「无法检查」,Agent 只看到「没法检查」、不会去改那条真会少算的过滤。
|
|
201
|
+
// 顺序因此是:外层扫描优先;只有外层**什么都没发现**时才退化成声明缺口。
|
|
202
|
+
const unexpandableHint = () => (unexpandable ? { kind: 'unexpandable', text: unexpandableQueryHint(loc) } : null);
|
|
203
|
+
if (!ISO_DAY_COL_RE.test(withoutLiterals(code)) && !hasDayColumnSelector(code)
|
|
204
|
+
&& !hasDayColumnKeyReference(code))
|
|
205
|
+
return unexpandableHint();
|
|
206
|
+
// 在「只抹注释」的文本上找孤立的**开引号**。`withoutComments` 原样保留双引号标识符与
|
|
207
|
+
// 美元引号体,所以这两段必须整体跳过(CodeRabbit 2026-11-10):`SELECT "it's" …` 里的
|
|
208
|
+
// `'` 会被当成开引号、把后面的真实字面量吞进一个假字面量,警告静默丢失。
|
|
209
|
+
for (let i = 0; i < code.length; i++) {
|
|
210
|
+
if (code[i] === '"') {
|
|
211
|
+
// 双引号标识符:`""` 是转义引号(与单引号串同款)
|
|
212
|
+
for (i++; i < code.length; i++) {
|
|
213
|
+
if (code[i] === '"') {
|
|
214
|
+
if (code[i + 1] !== '"')
|
|
215
|
+
break;
|
|
216
|
+
i++;
|
|
217
|
+
}
|
|
218
|
+
}
|
|
219
|
+
continue;
|
|
220
|
+
}
|
|
221
|
+
// 字面量(单引号 / E 串 / 美元引号):体**本身**就可以是日期字面量(`$$2026-10-13$$`
|
|
222
|
+
// 实测与 `'2026-10-13'` 等价,CodeRabbit 2026-11-10 第五轮);解码与读取走 `mask.ts`
|
|
223
|
+
// 的同一实现(`readSqlString`)。标识符边界由它的美元引号判据负责。
|
|
224
|
+
const lit = readSqlString(code, i);
|
|
225
|
+
if (lit !== null) {
|
|
226
|
+
if (isMiscomparedDayLiteral(lit.value))
|
|
227
|
+
return { kind: 'mismatch', text: isoDayLiteralHint(loc) };
|
|
228
|
+
i = lit.end - 1;
|
|
229
|
+
continue;
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
// 有日列引用但字面量都规范 → 外层没有确定结论,仍要声明不可展开的缺口(不得静默)。
|
|
233
|
+
return unexpandableHint();
|
|
234
|
+
}
|
|
235
|
+
/**
|
|
236
|
+
* SQL 里是否有**列选择器**里的字面量指向时间列:`COLUMNS('stat_date')` / `COLUMNS('stat.*')` /
|
|
237
|
+
* `"COLUMNS"('…')`。
|
|
238
|
+
*
|
|
239
|
+
* `COLUMNS(<正则字符串>)` 的串是**执行语义**(选择哪些列),不是普通字面量 —— 实测
|
|
240
|
+
* `WHERE COLUMNS('stat_date') >= '2026-10-13'` 两天夹具只计一天。判据限定在 COLUMNS 的
|
|
241
|
+
* 实参里:任意位置的普通字符串不当列名。参数按 DuckDB 的正则语义解释;非法正则由
|
|
242
|
+
* DuckDB 自己报错,这里不据此报警。
|
|
243
|
+
*/
|
|
244
|
+
function hasDayColumnSelector(code) {
|
|
245
|
+
for (const { open } of sqlFunctionCalls(code, 'columns')) {
|
|
246
|
+
const lit = readSqlString(code, skipSqlTrivia(code, open));
|
|
247
|
+
if (lit === null)
|
|
248
|
+
continue;
|
|
249
|
+
if (ISO_DAY_COL_RE.test(lit.value))
|
|
250
|
+
return true;
|
|
251
|
+
try {
|
|
252
|
+
const rx = new RegExp(lit.value, 'i');
|
|
253
|
+
if (rx.test('stat_date') || rx.test('work_date'))
|
|
254
|
+
return true;
|
|
255
|
+
}
|
|
256
|
+
catch { /* 非法正则:DuckDB 会自己报错,这里不据此报警 */ }
|
|
257
|
+
}
|
|
258
|
+
return false;
|
|
259
|
+
}
|
|
260
|
+
/**
|
|
261
|
+
* 与 `hasDayColumnSelector` 同一问题的另两种写法(Codex 2026-11-10 第八轮 P2,均实测):
|
|
262
|
+
* · `struct_extract(d, 'stat_date')` / `COLUMNS(['stat_date', 'stat.*'])`:列名是**列表**或
|
|
263
|
+
* 其它函数的位置实参里的字符串 —— 函数名与实参不是一一对应,所以按「有时间列名字面量
|
|
264
|
+
* 出现在函数调用的实参括号里」认,而不是给每个函数名各写一条规则;
|
|
265
|
+
* · `d['stat_date']`:下标访问,列名在方括号里。
|
|
266
|
+
*
|
|
267
|
+
* 反面(不认):普通位置的字符串(`SELECT 'stat_date' AS label`)、字面量里的伪代码。
|
|
268
|
+
* 方向性:误认只会多一条带修复方法的日期警告(与 `hasDayColumnSelector` 同一取舍)。
|
|
269
|
+
*/
|
|
270
|
+
function hasDayColumnKeyReference(code) {
|
|
271
|
+
const blank = withoutLiterals(code);
|
|
272
|
+
// ⚠️ 标识符判据必须与 SQL 词法一致(Codex 2026-11-11 第十四轮 P2,实测):DuckDB 接受
|
|
273
|
+
// 任何非 ASCII 非空白字符作未引用标识符(`AS 数据` 合法),`数据['stat_date']` 与
|
|
274
|
+
// `d['stat_date']` 等价、边界日同样被排除;ASCII 正则认不出别名 → 括号都没看 → 零警告。
|
|
275
|
+
// 复用 `mask.ts` 的 isIdentCp(经 `isIdentAt` 前向 / `isIdentCharAt` 前导边界),
|
|
276
|
+
// 标识符规则只许一个实现点。
|
|
277
|
+
const ws = /[ \t\n\r\f\v]/;
|
|
278
|
+
for (let i = 0; i < blank.length; i++) {
|
|
279
|
+
let nameEnd;
|
|
280
|
+
if (blank[i] === '"') {
|
|
281
|
+
// 双引号标识符整段跳过(`""` 是转义引号;未闭合时退到末尾)
|
|
282
|
+
let j = i + 1;
|
|
283
|
+
while (j < blank.length && !(blank[j] === '"' && blank[j + 1] !== '"')) {
|
|
284
|
+
j += blank[j] === '"' && blank[j + 1] === '"' ? 2 : 1;
|
|
285
|
+
}
|
|
286
|
+
nameEnd = Math.min(j + 1, blank.length);
|
|
287
|
+
}
|
|
288
|
+
else if (isIdentAt(blank, i) && !isIdentCharAt(blank, i)) {
|
|
289
|
+
// 未引用标识符的**起点**(前一个字符不是标识符字符)
|
|
290
|
+
let j = i;
|
|
291
|
+
while (j < blank.length && isIdentAt(blank, j))
|
|
292
|
+
j++;
|
|
293
|
+
nameEnd = j;
|
|
294
|
+
}
|
|
295
|
+
else {
|
|
296
|
+
continue;
|
|
297
|
+
}
|
|
298
|
+
let k = nameEnd;
|
|
299
|
+
while (k < blank.length && ws.test(blank[k]))
|
|
300
|
+
k++;
|
|
301
|
+
if (blank[k] !== '(' && blank[k] !== '[') {
|
|
302
|
+
i = nameEnd - 1;
|
|
303
|
+
continue;
|
|
304
|
+
}
|
|
305
|
+
const close = blank[k] === '(' ? ')' : ']';
|
|
306
|
+
const end = matchingParen(blank, k, blank[k], close);
|
|
307
|
+
if (end === -1) {
|
|
308
|
+
i = nameEnd - 1;
|
|
309
|
+
continue;
|
|
310
|
+
}
|
|
311
|
+
// 实参里的每个字符串字面量:本身就是时间列名,或是以时间列名结尾的下标 `d['stat_date']`
|
|
312
|
+
//(下标表达式里的引号紧跟在 `[` 后)。
|
|
313
|
+
// ⚠️ 先跳过完整的双引号标识符再认字面量:`struct_extract("it's", 'stat_date')` 里
|
|
314
|
+
// `"it's"` 内部的撇号不是字符串起始,按字面量读会一路吞到 `'stat_date'` 之后
|
|
315
|
+
//(Codex 2026-11-10 第九轮 P2,实测该写法下库值被排除边界日却无警告)。
|
|
316
|
+
for (let s = k + 1; s < end; s++) {
|
|
317
|
+
if (code[s] === '"') {
|
|
318
|
+
// 双引号标识符整段跳过:`""` 是转义引号;未闭合时退到区间末尾
|
|
319
|
+
let t = s + 1;
|
|
320
|
+
while (t < end && !(code[t] === '"' && code[t + 1] !== '"')) {
|
|
321
|
+
t += code[t] === '"' && code[t + 1] === '"' ? 2 : 1;
|
|
322
|
+
}
|
|
323
|
+
s = t;
|
|
324
|
+
continue;
|
|
325
|
+
}
|
|
326
|
+
const lit = readSqlString(code, s);
|
|
327
|
+
if (lit === null)
|
|
328
|
+
continue;
|
|
329
|
+
if (ISO_DAY_COL_RE.test(lit.value))
|
|
330
|
+
return true;
|
|
331
|
+
s = lit.end - 1;
|
|
332
|
+
}
|
|
333
|
+
i = k; // 从实参内部继续扫(原实现 re.lastIndex = k + 1)
|
|
334
|
+
}
|
|
335
|
+
return false;
|
|
336
|
+
}
|
|
337
|
+
/**
|
|
338
|
+
* 列表 / 函数的括号或下标方括号配对,返回**闭括号之后**的下标;不成对返回 -1。
|
|
339
|
+
*
|
|
340
|
+
* ⚠️ 先把字面量与注释抹成空白再数(`withoutLiterals` 的结果):字符串里的括号不参与配对;
|
|
341
|
+
* 双引号标识符可以是「函数名」(`"f"(…)`)也可含括号(`"a(b"`),所以从**扫描位置**起按
|
|
342
|
+
* 词法推进,而不是简单字符计数。每次循环都前进,绝不空转。
|
|
343
|
+
*/
|
|
344
|
+
function matchingParen(blank, open, openCh, closeCh) {
|
|
345
|
+
let depth = 0;
|
|
346
|
+
for (let i = open; i < blank.length; i++) {
|
|
347
|
+
const ch = blank[i];
|
|
348
|
+
if (ch === '"') {
|
|
349
|
+
// 双引号标识符整段跳过(`""` 是转义引号)
|
|
350
|
+
let j = i + 1;
|
|
351
|
+
for (; j < blank.length; j++) {
|
|
352
|
+
if (blank[j] === '"') {
|
|
353
|
+
if (blank[j + 1] !== '"')
|
|
354
|
+
break;
|
|
355
|
+
j++;
|
|
356
|
+
}
|
|
357
|
+
}
|
|
358
|
+
i = j;
|
|
359
|
+
continue;
|
|
360
|
+
}
|
|
361
|
+
if (ch === openCh)
|
|
362
|
+
depth++;
|
|
363
|
+
else if (ch === closeCh) {
|
|
364
|
+
if (--depth === 0)
|
|
365
|
+
return i + 1;
|
|
366
|
+
}
|
|
367
|
+
}
|
|
368
|
+
return -1;
|
|
369
|
+
}
|
|
370
|
+
/**
|
|
371
|
+
* `query()` 的实参不是单个静态字符串(拼接 / 函数调用):内层 SQL 随时可以拼出
|
|
372
|
+
* `stat_date >= '2026-10-13'` 这类错位日字面量,而静态判据看不见 —— 声明检查边界
|
|
373
|
+
* (Codex 2026-11-10 第六轮 P2 实测 `query('SELECT ' || '1')` 被冒认成内层 `SELECT `)。
|
|
374
|
+
*/
|
|
375
|
+
function unexpandableQueryHint(loc) {
|
|
376
|
+
return 'SQL 的 `query()` 实参不是单个静态字符串(拼接 / 函数调用等):内层 SQL 无法静态展开,'
|
|
377
|
+
+ '其中是否含「少算一天」的日期过滤**无法检查**——请确认内层用的是 UTC 形态'
|
|
378
|
+
+ '(如 \'2026-10-12T16:00:00.000Z\'),或改用 `' + queryTableCommand('<表>', loc) + '`';
|
|
379
|
+
}
|
|
380
|
+
function isoDayLiteralHint(loc) {
|
|
381
|
+
return '该列列内是 UTC `…Z` 形态的字符串(上海日零点 = 前一日 16:00Z),按字典序比较,' +
|
|
382
|
+
'这个日期字面量会**少算或漏掉一天**(`…Z` 是 UTC 时刻,不是上海日)。要在 --sql 里过滤请写 UTC 形态' +
|
|
383
|
+
'(如 \'2026-10-12T16:00:00.000Z\'),或改用 `' + queryTableCommand('<表>', loc) + ' --since/--until`(该通道已处理取整语义)';
|
|
384
|
+
}
|
|
104
385
|
/**
|
|
105
386
|
* 截断警告(两个通道**文案必须分开**)。
|
|
106
387
|
*
|
|
@@ -114,19 +395,24 @@ const ISO_DAY_LITERAL_HINT = '该列列内是 UTC `…Z` 形态的字符串(
|
|
|
114
395
|
* · `--table` 通道:`--since/--until` 对**无时间列的表**会被拒(25 张表里有 10 张没有
|
|
115
396
|
* `timeColumn`)——对这些表只能建议 `--group-by`(任何表都支持)与 `db describe`。
|
|
116
397
|
*/
|
|
117
|
-
function truncationWarning(returned, limit, channel, hasTimeColumn = true) {
|
|
398
|
+
function truncationWarning(returned, limit, channel, hasTimeColumn = true, loc) {
|
|
118
399
|
const head = `结果被 --limit ${limit} 截断,本次只返回 ${returned} 行(不是全部);`
|
|
119
400
|
+ '聚合与「是否存在数据缺口」的判断都不应基于这批不完整的结果——';
|
|
401
|
+
const describe = dbDescribeCommand('<表>', loc);
|
|
120
402
|
if (channel === 'sql') {
|
|
121
|
-
return head + '请在 SQL 里加 WHERE 条件收窄,或用 `
|
|
403
|
+
return head + '请在 SQL 里加 WHERE 条件收窄,或用 `' + describe + '` 看总行数与时间范围';
|
|
122
404
|
}
|
|
123
405
|
return head + (hasTimeColumn
|
|
124
|
-
? '请用 `
|
|
125
|
-
: '请用 `
|
|
406
|
+
? '请用 `' + describe + '` 看总行数与时间范围,或加过滤条件(--since/--until/--group-by)收窄'
|
|
407
|
+
: '请用 `' + describe + '` 看总行数,或用 `--group-by <列>` 聚合成计数收窄'
|
|
126
408
|
+ '(该表没有时间列,不接受 --since/--until)');
|
|
127
409
|
}
|
|
128
410
|
function parseFlags(argv) {
|
|
129
411
|
const out = { noMask: false, groupBy: [], rest: [] };
|
|
412
|
+
// 值位 flag 重复出现必须报错(Codex 2026-11-10 P2):此前只有 `parseStoreFlags` 拒绝,
|
|
413
|
+
// 而本解析器同样直接赋值 —— `query --db a --db b` 静默作用在后一个库上。
|
|
414
|
+
// `--group-by` 例外:它本来就允许重复(spec §六)。
|
|
415
|
+
const seen = new Set();
|
|
130
416
|
for (let i = 0; i < argv.length; i++) {
|
|
131
417
|
const a = argv[i];
|
|
132
418
|
if (VALUE_FLAGS.has(a)) {
|
|
@@ -135,10 +421,16 @@ function parseFlags(argv) {
|
|
|
135
421
|
// 否则 `query --sql --limit 2` 会把 --limit 当成 SQL 文本。
|
|
136
422
|
// ⚠️ `--sql` 只拒绝「恰好是已知 flag」的值:SQL 以 `--` 开头是合法行注释
|
|
137
423
|
// (`--sql '-- 注释\nSELECT 1'` 必须能跑)。路径/名字/数字/时间的合法取值不会以 `--`
|
|
138
|
-
//
|
|
139
|
-
|
|
424
|
+
// 开头,所以其余值位参数仍按前缀拒绝。两条分支由 `FlagSpec.dashValue` 选择
|
|
425
|
+
//(与帮助模式的 `helpArgsError` 同源,2026-11-06 Codex 审查)。
|
|
426
|
+
if (v === undefined || (DASH_VALUE_FLAGS.has(a) ? FLAG_TOKENS.has(v) : v.startsWith('--'))) {
|
|
140
427
|
throw new Error(`${a} 缺少取值`);
|
|
141
428
|
}
|
|
429
|
+
if (a !== '--group-by') {
|
|
430
|
+
if (seen.has(a))
|
|
431
|
+
throw new Error(`${a} 重复出现:只能给一次(不做静默覆盖)`);
|
|
432
|
+
seen.add(a);
|
|
433
|
+
}
|
|
142
434
|
if (a === '--sql')
|
|
143
435
|
out.sql = v;
|
|
144
436
|
else if (a === '--table')
|
|
@@ -240,14 +532,32 @@ function toEpochMs(v, kind) {
|
|
|
240
532
|
return Number.isFinite(n) ? n : null;
|
|
241
533
|
}
|
|
242
534
|
/** 0 行警告(spec §十):说明**实际生效**的区间,没有完整区间时如实说明。 */
|
|
243
|
-
function zeroRowWarning(range, tc, until) {
|
|
535
|
+
function zeroRowWarning(range, tc, until, loc) {
|
|
536
|
+
const tail = zeroRowHint(loc);
|
|
244
537
|
if (range !== null) {
|
|
245
|
-
return `查询在区间 [${shanghaiIso(range[0])}, ${shanghaiIso(range[1])}] 返回 0 行。${
|
|
538
|
+
return `查询在区间 [${shanghaiIso(range[0])}, ${shanghaiIso(range[1])}] 返回 0 行。${tail}`;
|
|
246
539
|
}
|
|
247
540
|
if (tc !== undefined && until !== undefined) {
|
|
248
|
-
return `查询在上限 ${shanghaiIso(effectiveBound(tc.kind, until))}(下界未能解析)返回 0 行。${
|
|
541
|
+
return `查询在上限 ${shanghaiIso(effectiveBound(tc.kind, until))}(下界未能解析)返回 0 行。${tail}`;
|
|
542
|
+
}
|
|
543
|
+
return `查询在给定时间条件下返回 0 行。${tail}`;
|
|
544
|
+
}
|
|
545
|
+
/**
|
|
546
|
+
* 诊断性计数(best-effort):**失败返回 null,绝不把已成功的查询拖红**。
|
|
547
|
+
*
|
|
548
|
+
* ⚠️ 2026-11-05 审查(Codex PR #68 第三轮 P2):脏时间值计数是全表扫描,若它撞上
|
|
549
|
+
* `--timeout`,同步等待会把「主查询与覆盖统计都成功」的整条命令变成失败 —— 数据拿不到,
|
|
550
|
+
* 而这条计数只是为了补一条警告。诊断失败降级为警告,退出码与 rows 不受影响。
|
|
551
|
+
* 导出供单测直接验证成败两条分支(真实超时难以稳定构造)。
|
|
552
|
+
*/
|
|
553
|
+
export async function runDiagnosticCount(session, sql, params, timeoutMs) {
|
|
554
|
+
try {
|
|
555
|
+
const r = await session.run(sql, { params, timeoutMs });
|
|
556
|
+
return Number(r.rows[0]?.n ?? 0);
|
|
557
|
+
}
|
|
558
|
+
catch {
|
|
559
|
+
return null;
|
|
249
560
|
}
|
|
250
|
-
return `查询在给定时间条件下返回 0 行。${ZERO_ROW_HINT}`;
|
|
251
561
|
}
|
|
252
562
|
/**
|
|
253
563
|
* `--table` 的执行路径(spec §六):解析缺省下界 → 主查询 → 覆盖统计 → 脱敏 → 信封。
|
|
@@ -257,6 +567,11 @@ async function runTableQuery(session, input) {
|
|
|
257
567
|
const { table } = input;
|
|
258
568
|
const tc = table.timeColumn;
|
|
259
569
|
const warnings = [];
|
|
570
|
+
// 本次存储定位:所有诊断 hint(db describe / query --table / sync status)都要指回它,
|
|
571
|
+
// 否则照 hint 执行会读默认库(#45 边界 ②)。
|
|
572
|
+
const loc = input.profileFlag === undefined
|
|
573
|
+
? { db: input.dbPath }
|
|
574
|
+
: { db: input.dbPath, profile: input.profileFlag };
|
|
260
575
|
// 只给 --until:先查该表时间列下界(契约 B)。空表 → 不解析,交给纯函数出 warning。
|
|
261
576
|
// 超时预算与主查询同一口径(--timeout 0 = 不限时)。
|
|
262
577
|
let tableMin;
|
|
@@ -299,10 +614,35 @@ async function runTableQuery(session, input) {
|
|
|
299
614
|
if (row.days !== null && row.days !== undefined)
|
|
300
615
|
coveredDays = Number(row.days);
|
|
301
616
|
}
|
|
617
|
+
// 脏时间值不得静默丢掉(2026-11-05 审查修):时间过滤的 WHERE 里同时挂着形态谓词
|
|
618
|
+
//(正确性 F8),脏值行不会出现在 rows、也不进 data_coverage —— 此前没有任何 warning,
|
|
619
|
+
// 而 `db tables` / `db describe` 对同一张表会报「时间列有 N 个值不符合约定形态」。
|
|
620
|
+
// 没有时间过滤时不报(脏值行照常返回,没有被丢弃)。
|
|
621
|
+
if (tc !== undefined) {
|
|
622
|
+
const dirtyQuery = buildDirtyTimeQuery({
|
|
623
|
+
table, since: input.since, until: input.until, tableMin, now: input.now,
|
|
624
|
+
});
|
|
625
|
+
if (dirtyQuery !== null) {
|
|
626
|
+
// ⚠️ 这是**诊断性**计数(全表扫描),不得成为本次查询成功的前置条件(Codex 2026-11-05
|
|
627
|
+
// 第三轮 P2):主查询与覆盖统计都已成功返回,若这次计数撞上 --timeout,整条命令会失败、
|
|
628
|
+
// 已算出的数据也拿不到。失败/超时只降级为一条警告,不改变退出码。
|
|
629
|
+
const n = await runDiagnosticCount(session, dirtyQuery.sql, dirtyQuery.params, input.timeoutMs);
|
|
630
|
+
if (n === null) {
|
|
631
|
+
warnings.push(`表 ${table.name} 的时间列 ${tc.name} 的脏值统计未能完成(诊断查询超时或被中断),`
|
|
632
|
+
+ '本次时间过滤可能排除了不符合约定形态的值 —— 需要确认时请单独查询该列');
|
|
633
|
+
}
|
|
634
|
+
else if (n > 0) {
|
|
635
|
+
warnings.push(`表 ${table.name} 的时间列 ${tc.name} 有 ${n} 个值不符合约定形态`
|
|
636
|
+
+ '(可能来自旧版 CLI、外部工具或库损坏),本次时间过滤已把它们排除在 rows 与 '
|
|
637
|
+
+ 'data_coverage 之外;用 `' + querySqlCommand(loc) + '` 单独查看它们以确认成因('
|
|
638
|
+
+ SQL_ARG_REPLACE_NOTE + ')');
|
|
639
|
+
}
|
|
640
|
+
}
|
|
641
|
+
}
|
|
302
642
|
// 脱敏唯一出口(spec §7.2);--table 通道按列精确命中(mode.kind='table')。
|
|
303
643
|
const masked = maskQueryRows({
|
|
304
644
|
rows: result.rows, columns: result.columns,
|
|
305
|
-
mode: { kind: 'table', table }, noMask: input.noMask,
|
|
645
|
+
mode: { kind: 'table', table }, noMask: input.noMask, loc,
|
|
306
646
|
});
|
|
307
647
|
// 库漂移「声明有而实际无」(场景审查 9):`SELECT *` 只返回库里真实存在的列,
|
|
308
648
|
// 被删掉的列(旧版 CLI/外部工具改过库)会**静默消失**,而 `db tables`/`db describe`
|
|
@@ -313,7 +653,7 @@ async function runTableQuery(session, input) {
|
|
|
313
653
|
: table.columns.map((c) => c.name).filter((n) => !result.columns.includes(n));
|
|
314
654
|
if (missingCols.length > 0) {
|
|
315
655
|
warnings.push(`库中缺列 ${missingCols.join('、')}(表 ${table.name} 的定义里有、实际没有):`
|
|
316
|
-
+ '可能来自旧版 CLI 或库损坏;`
|
|
656
|
+
+ '可能来自旧版 CLI 或库损坏;`' + dbDescribeCommand(table.name, loc) + '` 可核对声明与实况的差异');
|
|
317
657
|
}
|
|
318
658
|
// ⚠️ `COUNT(*)` 经 getRowObjectsJson 是**字符串**(BIGINT)—— 输出必须是 number,
|
|
319
659
|
// 否则 Agent 拿 `"count": "3"` 做算术会静默出错(与 db describe 的 Number() 同款)。
|
|
@@ -322,7 +662,12 @@ async function runTableQuery(session, input) {
|
|
|
322
662
|
: masked.rows;
|
|
323
663
|
// 0 行 ≠ 没有数据(spec §十 / 红线 3):给了时间过滤而 0 行时附可操作提示。
|
|
324
664
|
if (result.rows.length === 0 && (input.since !== undefined || input.until !== undefined)) {
|
|
325
|
-
|
|
665
|
+
// 区间倒置(只给 --until 且早于表 MIN)的成因已由 buildTimeFilter 的警告说清,
|
|
666
|
+
// 且它是**必然** 0 行 —— 再叠一条「同步可能未覆盖该区间」是假归因
|
|
667
|
+
//(同步正常覆盖了这段,只是上限压根没到开始)(2026-11-09 审计)。
|
|
668
|
+
const inverted = plan.resolvedRange !== null && plan.resolvedRange[0] > plan.resolvedRange[1];
|
|
669
|
+
if (!inverted)
|
|
670
|
+
warnings.push(zeroRowWarning(plan.resolvedRange, tc, input.until, loc));
|
|
326
671
|
}
|
|
327
672
|
else if (result.rows.length === 0) {
|
|
328
673
|
// 没给时间过滤也 0 行:spec §十 把「空表」列为 warnings 的触发条件。
|
|
@@ -332,7 +677,7 @@ async function runTableQuery(session, input) {
|
|
|
332
677
|
// 只有「库中缺列」漂移(plan.warnings 只在给了时间过滤时非空,那走上一分支)——
|
|
333
678
|
// 缺列说的是 schema、空表说的是数据,两件独立事实都该说;压掉后者 Agent 会把
|
|
334
679
|
// 「0 行」误读成缺列的副作用。
|
|
335
|
-
warnings.push('该表无数据;先运行 `
|
|
680
|
+
warnings.push('该表无数据;先运行 `' + syncRunCommand(input.dbPath, input.profileFlag) + '`');
|
|
336
681
|
}
|
|
337
682
|
// 窗口内部空洞(端到端场景 F4):iso-day 表 + 完整区间时,比较「区间应覆盖的自然日数」
|
|
338
683
|
// 与「实际有行的自然日数」。MIN/MAX 的 data_coverage 结构上看不见内部缺口 ——
|
|
@@ -352,8 +697,16 @@ async function runTableQuery(session, input) {
|
|
|
352
697
|
// `coveredDays` 来自实际查询区间,缺省上界含今天;而 expectedDays 已排除今天。
|
|
353
698
|
// 今天只要有一行,就会把昨天的真缺口补满 → 零警告(实测:10/13–10/18 + 今天、
|
|
354
699
|
// 缺 10/19,`--since 7d` 输出 warnings: [])。这里按夹紧后的 hi 再算一次。
|
|
700
|
+
// ⚠️ 夹紧后的上界可能**早于下界**(2026-11-09 实测):窗口只有今天一格时
|
|
701
|
+
//(`--since <今天>`,iso-day 下 lo = hi = 今天零点),今天被排除 → hi = 昨天零点 < lo。
|
|
702
|
+
// 此时窗口内一个应覆盖的日子都没有:跳过覆盖重算、不报缺口。此前照样拿夹紧后的上界
|
|
703
|
+
// 跑 `buildCoverageQuery` → 抛「区间无效」用法错误,而本段在 usageFail 的 try 之外,
|
|
704
|
+
// 异常冒到顶层被归成 `internal` +「若反复出现请报告此问题」——正常问法被说成内部故障。
|
|
355
705
|
let daysInWindow = coveredDays;
|
|
356
|
-
if (hi < plan.resolvedRange[
|
|
706
|
+
if (hi < plan.resolvedRange[0]) {
|
|
707
|
+
daysInWindow = 0;
|
|
708
|
+
}
|
|
709
|
+
else if (hi < plan.resolvedRange[1]) {
|
|
357
710
|
const clamped = buildCoverageQuery({ ...input, until: hi });
|
|
358
711
|
const row = (await session.run(clamped.sql, {
|
|
359
712
|
params: clamped.params, timeoutMs: input.timeoutMs,
|
|
@@ -364,13 +717,13 @@ async function runTableQuery(session, input) {
|
|
|
364
717
|
if (daysInWindow < expectedDays) {
|
|
365
718
|
const scope = input.until === undefined ? '(不含今天:当天数据次日才同步)' : '';
|
|
366
719
|
warnings.push(`区间内应有 ${expectedDays} 个自然日${scope},实际只有 ${daysInWindow} 个有数据`
|
|
367
|
-
+ '(窗口内部存在缺口);用 `
|
|
720
|
+
+ '(窗口内部存在缺口);用 `' + syncStatusCommand(loc) + '` 查看缺口详情,或放宽过滤条件');
|
|
368
721
|
}
|
|
369
722
|
}
|
|
370
723
|
// 截断不得静默(同上):`--limit` 生效时 Agent 读到的不是全量。
|
|
371
724
|
// 无时间列的表不能建议 --since/--until(那是条走不通的路),故传入 tc 是否存在。
|
|
372
725
|
if (result.truncated) {
|
|
373
|
-
warnings.push(truncationWarning(rows.length, input.limit, 'table', tc !== undefined));
|
|
726
|
+
warnings.push(truncationWarning(rows.length, input.limit, 'table', tc !== undefined, loc));
|
|
374
727
|
}
|
|
375
728
|
// --no-mask 的风险警告属于「脱敏整体关闭」,进 meta.warnings;mask_warnings 只装
|
|
376
729
|
// 静态缺口警告(没脱敏就没有「脱敏不完整」可言)。spec §7.2。
|
|
@@ -390,6 +743,8 @@ async function runTableQuery(session, input) {
|
|
|
390
743
|
? null
|
|
391
744
|
: [shanghaiIso(plan.resolvedRange[0]), shanghaiIso(plan.resolvedRange[1])],
|
|
392
745
|
data_coverage: dataCoverage,
|
|
746
|
+
// 图例:9 个键逐条释义(两个通道共用一份,分叉写必然漂移)。
|
|
747
|
+
field_notes: queryFieldNotes(),
|
|
393
748
|
});
|
|
394
749
|
}
|
|
395
750
|
export async function queryCommand(argv, deps = {}) {
|
|
@@ -400,9 +755,13 @@ export async function queryCommand(argv, deps = {}) {
|
|
|
400
755
|
if (argv.includes('--help') || argv.includes('-h')) {
|
|
401
756
|
// --help 不吞额外参数;--pretty 豁免(同族惯例)。
|
|
402
757
|
// 措辞不用「未知参数」:`--sql` 是已知参数、只是不能与 --help 同时出现(同一条闸门)。
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
758
|
+
// ⚠️ 判据与其他命令族同源(spec 的完整接受集),不是只看全局 flag:`query --table
|
|
759
|
+
// sessions --help` 是合法的帮助请求,此前被判「--help 不接受额外参数:--table sessions」
|
|
760
|
+
// 退 2。`--sql` 的取值可能以 `--` 开头,但那不影响「未知 flag 判定」—— 取值一律跳过。
|
|
761
|
+
const problem = helpArgsError(argv, QUERY_SPECS.flatMap((sp) => sp.flags), '。--help 不接受额外参数');
|
|
762
|
+
// ⚠️ 渲染走 `describeArgs`(空串/纯空白要显示成 `''`/`' '`),不是 `join(' ')`。
|
|
763
|
+
if (problem !== undefined)
|
|
764
|
+
return usageFail(problem);
|
|
406
765
|
process.stdout.write(USAGE);
|
|
407
766
|
return 0;
|
|
408
767
|
}
|
|
@@ -444,10 +803,12 @@ export async function queryCommand(argv, deps = {}) {
|
|
|
444
803
|
tableDef = tableByName(name);
|
|
445
804
|
if (tableDef === undefined) {
|
|
446
805
|
const candidates = suggestNames(name, TABLES.map((t) => t.name));
|
|
447
|
-
return usageFail(`未知表:${describeArgs([name])}`, candidates.length > 0
|
|
806
|
+
return usageFail(`未知表:${describeArgs([name])}`, candidates.length > 0
|
|
807
|
+
? `候选:${candidates.join('、')}`
|
|
808
|
+
: '用 `' + dbTablesCommand(storeLocationFromFlags(flags)) + '` 查看可用表');
|
|
448
809
|
}
|
|
449
810
|
try {
|
|
450
|
-
validateGroupBy(tableDef, flags.groupBy);
|
|
811
|
+
validateGroupBy(tableDef, flags.groupBy, storeLocationFromFlags(flags));
|
|
451
812
|
sinceMs = resolveTimeFlag(flags.since, '--since', () => nowMs);
|
|
452
813
|
untilMs = resolveTimeFlag(flags.until, '--until', () => nowMs);
|
|
453
814
|
}
|
|
@@ -471,12 +832,18 @@ export async function queryCommand(argv, deps = {}) {
|
|
|
471
832
|
// 配置解析 → 库前置检查 → 打开沙箱 → schema_version 探测:E 族三个命令共用同一条
|
|
472
833
|
// 路径(db.ts 的 openGuardedSession)。合并的理由见那里的注释:探测口径与文案
|
|
473
834
|
// 一旦三处各写一份,Agent 会在不同命令上得到互相矛盾的解释(架构审查 Important #2)。
|
|
835
|
+
// ⚠️ 不传探测超时 hint:本命令**有** --since/--until/--limit/--timeout,探测也用
|
|
836
|
+
// `DEFAULT_TIMEOUT_HINT`(「缩小时间范围或加过滤条件」)才对。传元数据口径会让
|
|
837
|
+
// 探测超时时建议用户改用 `qiyu query --sql` —— 正是他正在跑的命令
|
|
838
|
+
//(CodeRabbit 2026-11-05 第六轮 minor)。
|
|
474
839
|
const opened = await openGuardedSession({
|
|
475
840
|
db: flags.db, profile: flags.profile, backend: flags.backend,
|
|
476
841
|
});
|
|
477
842
|
if ('exit' in opened)
|
|
478
843
|
return opened.exit;
|
|
479
844
|
const session = opened.session;
|
|
845
|
+
// 已解析的存储定位:--sql 通道与错误出口的诊断 hint 都指回它(#45 边界 ②)。
|
|
846
|
+
const openedLoc = storeLocationOf(opened.dbPath, opened.profileFlag);
|
|
480
847
|
try {
|
|
481
848
|
// 库结构校验(缺 schema_version → store_not_initialized)在 openGuardedSession 里
|
|
482
849
|
// 已做(E 族共用,口径见 db.ts 的注释)——这里不重复探测。
|
|
@@ -494,16 +861,15 @@ export async function queryCommand(argv, deps = {}) {
|
|
|
494
861
|
return fail({
|
|
495
862
|
code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
|
|
496
863
|
message: `数据库中缺表:${tableDef.name}(本表在 CLI 的表定义中存在,库里没有)`,
|
|
497
|
-
hint:
|
|
498
|
-
+
|
|
499
|
-
+ '——需重建库(删除库文件后重新 qiyu store init 并重新同步)。'
|
|
500
|
-
+ '用 `qiyu db tables` 查看库中实际有数据的表',
|
|
864
|
+
hint: missingTableCauses(opened.dbPath, opened.profileFlag) + '。用 `'
|
|
865
|
+
+ dbTablesCommand(openedLoc) + '` 查看库中实际有数据的表',
|
|
501
866
|
});
|
|
502
867
|
}
|
|
503
868
|
}
|
|
504
869
|
if (tableDef !== undefined) {
|
|
505
870
|
return await runTableQuery(session, {
|
|
506
|
-
table: tableDef,
|
|
871
|
+
table: tableDef, dbPath: opened.dbPath, profileFlag: opened.profileFlag,
|
|
872
|
+
since: sinceMs, until: untilMs, groupBy: flags.groupBy,
|
|
507
873
|
limit, timeoutMs, noMask: flags.noMask, now: nowMs,
|
|
508
874
|
});
|
|
509
875
|
}
|
|
@@ -514,20 +880,23 @@ export async function queryCommand(argv, deps = {}) {
|
|
|
514
880
|
const masked = maskQueryRows({
|
|
515
881
|
rows: result.rows, columns: result.columns,
|
|
516
882
|
mode: { kind: 'sql', sql: sqlText, tables: TABLES }, noMask: flags.noMask,
|
|
883
|
+
loc: openedLoc,
|
|
517
884
|
});
|
|
518
885
|
// 0 行 ≠ 没有数据(spec §十 / 红线 3):时间过滤查询 0 行时附可操作提示。
|
|
519
886
|
const warnings = [];
|
|
520
887
|
if (result.rows.length === 0 && ZERO_ROW_TIME_RE.test(sqlText)) {
|
|
521
|
-
warnings.push(`查询返回 0 行,且 SQL 引用了业务时间列。${
|
|
522
|
-
}
|
|
523
|
-
// iso-day 列 + 日期形态字面量 → 按字符串比较会少一天(场景 F3)。与 0 行无关:
|
|
524
|
-
// 非 0 行也可能已经悄悄少了一整天,这正是它危险的地方。
|
|
525
|
-
if (ISO_DAY_COL_RE.test(sqlText) && DAY_LITERAL_RE.test(sqlText)) {
|
|
526
|
-
warnings.push(ISO_DAY_LITERAL_HINT);
|
|
888
|
+
warnings.push(`查询返回 0 行,且 SQL 引用了业务时间列。${zeroRowHint(openedLoc)}`);
|
|
527
889
|
}
|
|
890
|
+
// ⚠️ 不要在这里重复判 `ISO_DAY_COL_RE.test(sqlText)`(CR/Codex 2026-11-10 第六轮):
|
|
891
|
+
// 列名可能只在 `COLUMNS('stat.*')` 的选择器串里,外层 gate 会让内层 hint 永远看不到它。
|
|
892
|
+
// 列名判定只在 `dayLiteralHint` 里做(含选择器形态)。
|
|
893
|
+
const dayHint = dayLiteralHint(sqlText, openedLoc);
|
|
894
|
+
if (dayHint !== null)
|
|
895
|
+
warnings.push(dayHint);
|
|
528
896
|
// 截断不得静默:Agent 会把「只看到前 N 行」当成事实(spec §十)。
|
|
529
|
-
if (result.truncated)
|
|
530
|
-
warnings.push(truncationWarning(masked.rows.length, limit, 'sql'));
|
|
897
|
+
if (result.truncated) {
|
|
898
|
+
warnings.push(truncationWarning(masked.rows.length, limit, 'sql', true, openedLoc));
|
|
899
|
+
}
|
|
531
900
|
// --no-mask 的风险警告属于「脱敏整体关闭」,进 meta.warnings;mask_warnings 只装
|
|
532
901
|
// 静态缺口警告(没脱敏就没有「脱敏不完整」可言)。spec §7.2。
|
|
533
902
|
const maskWarnings = flags.noMask ? [] : masked.warnings;
|
|
@@ -544,6 +913,8 @@ export async function queryCommand(argv, deps = {}) {
|
|
|
544
913
|
// --sql 通道无法通用判定请求区间与数据覆盖(spec §十):恒 null,不猜。
|
|
545
914
|
resolved_range: null,
|
|
546
915
|
data_coverage: null,
|
|
916
|
+
// 与 --table 通道同一份图例(键集相同,见 query-notes.ts)。
|
|
917
|
+
field_notes: queryFieldNotes(),
|
|
547
918
|
});
|
|
548
919
|
}
|
|
549
920
|
catch (e) {
|
|
@@ -552,11 +923,11 @@ export async function queryCommand(argv, deps = {}) {
|
|
|
552
923
|
// `flags.noMask` 一路传到出口:转换错误会回显表里的真实值(CodeRabbit 终审 major),
|
|
553
924
|
// 只有显式 --no-mask 才允许原样输出。
|
|
554
925
|
if (tableDef !== undefined) {
|
|
555
|
-
const drift = driftFailureFor(tableDef, e);
|
|
926
|
+
const drift = driftFailureFor(tableDef, e, openedLoc);
|
|
556
927
|
if (drift !== null)
|
|
557
928
|
return emitQueryFailure(drift, flags.noMask);
|
|
558
929
|
}
|
|
559
|
-
return thrownToQueryExit(e, TABLES, flags.noMask);
|
|
930
|
+
return thrownToQueryExit(e, TABLES, flags.noMask, openedLoc);
|
|
560
931
|
}
|
|
561
932
|
finally {
|
|
562
933
|
await session.close();
|