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.
Files changed (72) hide show
  1. package/README.md +433 -72
  2. package/dist/cli.js +48 -7
  3. package/dist/commands/api-notes.js +70 -0
  4. package/dist/commands/api.js +169 -49
  5. package/dist/commands/auth.js +151 -29
  6. package/dist/commands/credentials-source.js +30 -5
  7. package/dist/commands/db-notes.js +75 -0
  8. package/dist/commands/db.js +165 -127
  9. package/dist/commands/query-notes.js +58 -0
  10. package/dist/commands/query.js +449 -61
  11. package/dist/commands/skill.js +445 -51
  12. package/dist/commands/spec-types.js +101 -1
  13. package/dist/commands/stats.js +160 -33
  14. package/dist/commands/store-flags.js +18 -0
  15. package/dist/commands/store-notes.js +38 -0
  16. package/dist/commands/store-precheck.js +321 -0
  17. package/dist/commands/store.js +165 -77
  18. package/dist/commands/sync-notes.js +374 -0
  19. package/dist/commands/sync-run.js +180 -47
  20. package/dist/commands/sync.js +232 -127
  21. package/dist/core/config.js +280 -24
  22. package/dist/core/credentials.js +38 -4
  23. package/dist/core/edition.js +1 -1
  24. package/dist/core/envelope.js +73 -9
  25. package/dist/core/errors.js +73 -16
  26. package/dist/core/http.js +175 -54
  27. package/dist/core/ratelimit.js +5 -1
  28. package/dist/core/registry/index.js +36 -2
  29. package/dist/core/registry/params/export.session.check.json +17 -2
  30. package/dist/core/registry/params/export.session.json +24 -2
  31. package/dist/core/registry/params/export.session.one.json +10 -2
  32. package/dist/core/registry/params/export.session.one.message.json +17 -2
  33. package/dist/core/registry/specs.json +65 -43
  34. package/dist/core/shell.js +30 -0
  35. package/dist/core/time.js +1 -1
  36. package/dist/core/validate.js +21 -2
  37. package/dist/output.js +215 -29
  38. package/dist/postinstall.js +14 -5
  39. package/dist/query/errors.js +145 -45
  40. package/dist/query/mask.js +1277 -25
  41. package/dist/query/metric-catalog.js +11 -0
  42. package/dist/query/native-error.js +189 -0
  43. package/dist/query/sandbox.js +148 -25
  44. package/dist/query/table-query.js +36 -5
  45. package/dist/schedule/install.js +136 -13
  46. package/dist/skill/check.js +11 -6
  47. package/dist/skill/detect.js +89 -29
  48. package/dist/skill/install.js +233 -43
  49. package/dist/skill/paths.js +54 -0
  50. package/dist/skill/qiyu/SKILL.md +29 -5
  51. package/dist/skill/qiyu/errors.md +5 -4
  52. package/dist/skill/qiyu/protocols.md +57 -5
  53. package/dist/skill/qiyu/setup.md +6 -2
  54. package/dist/store/config.js +92 -16
  55. package/dist/store/duckdb.js +1551 -64
  56. package/dist/store/object-kinds.js +32 -0
  57. package/dist/store/retry.js +190 -7
  58. package/dist/store/schema.js +32 -4
  59. package/dist/sync/engine.js +439 -77
  60. package/dist/sync/registry.js +6 -0
  61. package/dist/sync/state.js +20 -0
  62. package/dist/sync/tasks/dim.js +23 -14
  63. package/dist/sync/tasks/knowledge.js +50 -8
  64. package/dist/sync/tasks/pace.js +27 -0
  65. package/dist/sync/tasks/pipeline.js +29 -9
  66. package/dist/sync/tasks/reports.js +176 -49
  67. package/dist/sync/tasks/sessions.js +88 -21
  68. package/dist/sync/tasks/tickets.js +59 -8
  69. package/dist/sync/types.js +60 -1
  70. package/dist/sync/windowing.js +0 -22
  71. package/dist/sync/write-contract.js +79 -0
  72. package/package.json +2 -2
@@ -1,14 +1,19 @@
1
1
  // src/commands/store.ts
2
- import { statSync, lstatSync, mkdirSync } from 'node:fs';
2
+ import { lstatSync, mkdirSync } from 'node:fs';
3
3
  import { dirname } from 'node:path';
4
4
  import { resolveStoreConfig, currentStoreEnv } from '../store/config.js';
5
5
  import { openStore } from '../store/index.js';
6
- import { ok, fail, usageFail, sanitizeControlChars, setPretty } from '../output.js';
7
- import { parseStoreFlags } from './store-flags.js';
8
- import { GLOBAL_FLAGS, GLOBAL_FLAG_NAMES, prettyAfterSubcommand, REJECTED_FLAGS, STORE_FLAGS } from './spec-types.js';
6
+ import { ok, fail, usageFail, failFromTagged, sanitizeControlChars, setPretty, storeInitCommand, syncRunCommand, describeArgs, } from '../output.js';
7
+ import { classifyOpenFailure, openFailureHint } from '../store/retry.js';
8
+ import { DB_PATH_HELP, parseStoreFlags } from './store-flags.js';
9
+ import { SCHEMA_VERSION_COLUMNS_SQL, statGuard, schemaVersionMissing, nonRegularFileHint, undeclaredTables, storeTablesWarnings, OBJECT_KINDS_SQL, nonBaseTables, nonBaseTablesWarning, sameObjectName, } from './store-precheck.js';
10
+ import { TABLES, tableByName } from '../store/schema.js';
11
+ import { storeFieldNotes } from './store-notes.js';
12
+ import { GLOBAL_FLAGS, helpArgsError, prettyAfterSubcommand, prettyPositionalProblem, REJECTED_FLAGS, STORE_FLAGS } from './spec-types.js';
9
13
  /**
10
14
  * 命令契约(F 组 D4):`skill check` 据此判断 skill 正文里的 `qiyu store …` 是否真的存在。
11
- * `flags` 是**完整接受集**(含全局 flag),`--pretty` 同时在 `rejected` 里。
15
+ * `flags` 是**完整接受集**(含全局 flag);`rejected` 直接取 `REJECTED_FLAGS`(当前为空 ——
16
+ * `--pretty` 自 2026-10-24 G1 起已实现,不再是 rejected,见 `spec-types.ts` 顶部)。
12
17
  */
13
18
  export const STORE_SPECS = [
14
19
  {
@@ -32,11 +37,11 @@ const USAGE = `用法:qiyu store <子命令> [参数]
32
37
  store status [--db <path>] [--profile <name>] [--backend <name>]
33
38
  查看数据库状态与各表行数
34
39
 
35
- ⚠️ 存储配置需手工编辑 ~/.config/qiyu/config.json(CLI 不会自动创建)。
36
- 也可用 --db / QIYU_DB_PATH 直接指定库路径。
40
+ ⚠️ 存储配置仍需手工编辑 ~/.config/qiyu/config.json(store 命令本身不写配置;配置文件可能已
41
+ 由 auth login 创建,但只含 credentials 键,不含 store 段)。也可用 --db / QIYU_DB_PATH 直接指定库路径。
42
+ ${DB_PATH_HELP}
37
43
  `;
38
- const KNOWN = new Set(GLOBAL_FLAG_NAMES);
39
- export function thrownToExit(e) {
44
+ export function thrownToExit(e, profileFlag) {
40
45
  const err = e;
41
46
  // usage 类错误(store 层预检抛出,如未知列/缺列/连接已关闭):归 usageFail 双通道、
42
47
  // 退出码 2 —— 这是用法错误不是环境故障(M1 修:此前被下方排除条件挡住后落 internal)。
@@ -51,30 +56,56 @@ export function thrownToExit(e) {
51
56
  // ① DuckDB 拒绝打开非 DuckDB 文件 / 执行期错误 → 环境/数据问题,退出码 1、internal;
52
57
  // ② 其余 → 用法错误,退出码 2(usageFail 双通道)。
53
58
  const msg = err.message ?? String(e);
54
- if (/not a valid DuckDB database/i.test(msg)) {
59
+ // ⚠️ 打开失败的成因分流走 `store/retry.ts` 的 `classifyOpenFailure`(2026-10-31 单一实现点):
60
+ // 判据与 hint 口径必须与 `query/sandbox.ts` 的 `openSandbox`、`sync-run.ts` 的
61
+ // `storeInitFail` 一致 —— 此前三处各写各的,
62
+ // 同一个 `chmod 000` 的文件在 `store status` 与 `query` 上给出**互相矛盾**的 hint
63
+ // (一个说「检查读写权限」、一个说「请确认文件存在且由本 CLI 创建,跑 store init」)。
64
+ // 判据本身的形态要求(DuckDB 原生报文、strerror 在句尾、锚 `$` 不能子串搜)见那里的注释。
65
+ const openFailure = classifyOpenFailure(e);
66
+ if (openFailure !== null) {
55
67
  return fail({ code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
56
- message: `无法打开 ${msg}`, hint: '该路径已存在且不是 DuckDB 数据库,请换 --db 路径' });
57
- }
58
- // ⚠️ open/执行期 errno 分流(R 组 R6):EACCES/EPERM/EROFS 是环境问题不是程序错误,
59
- // 归因必须准(K 组 M3 只做了 lstat/statSync 层,这里补 open 期)。
60
- if (/^(EACCES|EPERM|EROFS)/.test(msg)) {
61
- return fail({ code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
62
- message: `无法打开 ${msg}`, hint: '请检查路径写权限(磁盘只读或目录无写权限都会导致无法打开)' });
68
+ message: `无法打开 ${msg}`, hint: openFailureHint(openFailure) });
63
69
  }
64
70
  // ⚠️ internal 兜底(第四轮 I 组 H1/M8 修):spec §8.2 禁止把 DuckDB 英文原文裸透
65
71
  // 给 Agent —— 必须中文包装 + 底层原文;hint 中性化(status 只读路径也会走到这里,
66
72
  // 不能说「写入」)。
73
+ // ⚠️ hint 不得指向 `qiyu store status`(2026-11-07 审查):本函数是 `store init` 与
74
+ // `store status` **共用**的出口 —— 当失败的命令本身就是 `store status` 时,
75
+ // 「请用 store status 检查数据库状态」是在让 Agent 重跑刚失败的同一条命令(死循环)。
76
+ // 换成两个子命令都成立的诊断动作:换一个 --db 验证库本身是否有问题。
77
+ // ⚠️ 恢复命令必须经渲染器带出(store-hint-selection 的 BARE_HINT 守卫):
78
+ // 重建目标是一个**尚不存在的新路径**,渲染器只接路径 —— 用全仓统一的占位符 `<新路径>`
79
+ // 传入,替换契约(换成真实 .duckdb 路径、不要指回原文件)随 hint 一并写明。
67
80
  return fail({ code: 'internal', kind: 'internal', retryable: false,
68
- message: `存储操作失败(底层:${msg})`, hint: '数据库执行期错误。若持续出现,请用 qiyu store status 检查数据库状态,或用 --db 指向其他数据库文件' });
81
+ message: `存储操作失败(底层:${msg})`, hint: '数据库执行期错误(重跑同一条命令不会改变结果)。'
82
+ + '请先用 --db 指向另一个库验证是否是该库的问题;若只有该库失败,请先备份该文件,再用 '
83
+ + storeInitCommand('<新路径>', profileFlag) + ' 重建(把 <新路径> 整段替换成新的 .duckdb 文件路径,'
84
+ + '不要指回出问题的文件 —— 本地库只是缓存),之后带同一个 --db 跑 '
85
+ + syncRunCommand('<新路径>', profileFlag) + ' 可重新拉取' });
86
+ // ⚠️ `profileFlag` 必须随 hint 带出(CodeRabbit 2026-11-09 minor):`sync run` 从**解析出的
87
+ // 档**读 `store.options.knowledgeRobotIds` 与 `profiles.<name>.robots`(robotId 注入面),
88
+ // 只给 `--db` 的恢复命令会用错 robot 集合且不报错(真库实测:带 `--profile alpha` 解析出
89
+ // [1000001]、不带则为空)。调用点见本文件 storeCommand 两处与 sync.ts 的 openRo。
69
90
  }
70
91
  export async function storeCommand(argv) {
71
92
  setPretty(false); // G1:每条命令入口重置输出格式 —— 同一进程内多次 run(测试)不残留上一条命令的开关。
72
93
  const [sub, ...rest] = argv;
73
- if (sub === undefined || sub === '--help' || sub === '-h') {
74
- // --help 不吞额外参数;--pretty 豁免(B 惯例)
75
- const extra = rest.filter((a) => !KNOWN.has(a));
76
- if (extra.length > 0)
77
- return usageFail(`未知参数:${extra.join(' ')}。--help 不接受额外参数`);
94
+ // ⚠️ 无子命令 = 用法错误(退 2 + stdout JSON),**不是**裸文本帮助(2026-11-07 审查):
95
+ // 此前它和 `--help` 共用一个分支,把 USAGE 写进 stdout 并退 0 —— 而顶层 `run()`、
96
+ // `api` / `auth` / `query` / `skill` 五个命令族对同一形态都给 usageFail(退 2 + JSON)。
97
+ // `cli.ts` 的 USAGE 还明写「`--help` 是**唯一**以裸文本输出的情形」,README 则承诺
98
+ // 「Agent 靠退出码和 stdout 的 JSON 做决定」—— 裸文本让 `qiyu store | jq` 直接 parse error。
99
+ // 原始裁决见计划 2026-09-30 §无参数分支:「无参数是用法错误,不是『用户请求帮助』」。
100
+ if (sub === undefined) {
101
+ return usageFail(`用法:qiyu store <init|status> [参数](\`qiyu store --help\` 查看全部)`, '可用子命令:init、status');
102
+ }
103
+ if (sub === '--help' || sub === '-h') {
104
+ // --help 不吞**未知**参数;已知 flag 与子命令名/取值一律放行(2026-11-06 审查:
105
+ // `store status --db /tmp/x --help` 此前被 `GLOBAL_FLAG_NAMES` 判成「未知参数」退 2)。
106
+ const problem = helpArgsError(rest, STORE_SPECS.flatMap((sp) => sp.flags), '。--help 不接受额外参数');
107
+ if (problem !== undefined)
108
+ return usageFail(problem);
78
109
  process.stdout.write(USAGE);
79
110
  return 0;
80
111
  }
@@ -82,15 +113,17 @@ export async function storeCommand(argv) {
82
113
  // store 级:--pretty 是合法**输出开关**,但它必须写在具体子命令之后(`store init --pretty`)。
83
114
  // 写在这里时没有任何子命令可修饰 —— 给出正确写法,而不是说成"未知子命令"(B 惯例)。
84
115
  if (sub === '--pretty') {
85
- const unknown = rest.filter((a) => a.startsWith('-') && !KNOWN.has(a));
86
- const positional = rest.filter((a) => !a.startsWith('-'));
87
- if (unknown.length + positional.length > 0) {
88
- return usageFail(`未知参数:${[...unknown, ...positional].join(' ')}。--pretty 不接受额外参数`);
89
- }
116
+ const problem = helpArgsError(rest, STORE_SPECS.flatMap((sp) => sp.flags));
117
+ if (problem !== undefined)
118
+ return usageFail(`${problem}。--pretty 不接受额外参数`);
119
+ const badPos = prettyPositionalProblem(rest, STORE_SPECS);
120
+ if (badPos !== undefined)
121
+ return usageFail(badPos);
90
122
  if (rest.includes('--help') || rest.includes('-h')) {
91
123
  process.stdout.write(USAGE);
92
124
  return 0;
93
125
  }
126
+ // ⚠️ 位置参数一律按「顺序写反」引导(2026-11-07 审查)—— 见 db.ts 同款注释。
94
127
  return usageFail(prettyAfterSubcommand('store'));
95
128
  }
96
129
  return usageFail(`未知子命令:${sub}\n可用子命令:init、status`);
@@ -99,9 +132,9 @@ export async function storeCommand(argv) {
99
132
  // ⚠️ 次序不能反:若先过滤「未知 token」再 parseStoreFlags,`store init --db <path>` 的
100
133
  // --db 及其值会被当未知参数误拒(v1 计划的实测缺陷,D/F 组独立发现)。
101
134
  if (rest.includes('--help') || rest.includes('-h')) {
102
- const rawRest = rest.filter((a) => !KNOWN.has(a));
103
- if (rawRest.length > 0)
104
- return usageFail(`未知参数:${rawRest.join(' ')}`);
135
+ const problem = helpArgsError(rest, STORE_SPECS.flatMap((sp) => sp.flags));
136
+ if (problem !== undefined)
137
+ return usageFail(problem);
105
138
  process.stdout.write(USAGE);
106
139
  return 0;
107
140
  }
@@ -117,16 +150,19 @@ export async function storeCommand(argv) {
117
150
  }
118
151
  // parseStoreFlags 之后剩下的 rest 才是真正的未知参数(带值 flag 的值位已被消费)
119
152
  if (flags.rest.length > 0)
120
- return usageFail(`未知参数:${flags.rest.join(' ')}`);
153
+ return usageFail(`未知参数:${describeArgs(flags.rest)}`);
121
154
  let resolved;
122
155
  try {
123
156
  resolved = resolveStoreConfig({ flags: { db: flags.db, profile: flags.profile, backend: flags.backend },
124
157
  env: currentStoreEnv() });
158
+ // ⚠️ failFromTagged(不是 usageFail):配置层会抛带 `kind: config_insecure` 的错误
159
+ // (含凭证且权限过宽 —— 退出码 1、只能由人 chmod)。包成 usageFail 会把它降级成
160
+ // 「改参数重来」退出码 2 并丢掉 hint,与 auth/api 那条路径的说法相反。
125
161
  }
126
162
  catch (e) {
127
- return usageFail(sanitizeControlChars(e.message));
163
+ return failFromTagged(e);
128
164
  }
129
- const { config, configPath, configExists } = resolved;
165
+ const { config, configPath, configExists, profileFlag } = resolved;
130
166
  if (sub === 'init') {
131
167
  // 文件前置检查(spec §7.1 步骤 2;验收 41)
132
168
  // ⚠️ lstat 异常按 errno 分流(K 组 M3):只有 ENOENT 才是「不存在 → DuckDB 会创建」;
@@ -149,15 +185,27 @@ export async function storeCommand(argv) {
149
185
  }
150
186
  }
151
187
  if (st !== undefined && st.isFile() === false && st.isDirectory() === true) {
188
+ // ⚠️ 两处「非普通文件」文案走 `store-precheck.ts` 的 `nonRegularFileHint`(2026-10-31
189
+ // 单一实现点)——此前 init/status 与 db/sync 各写各的,`!isFile()` 这个判据
190
+ // 覆盖了目录 / FIFO / 设备 / 套接字 四种成因,而 status 只按「目录」写死文案,
191
+ // 对 FIFO 说出「你传了个目录」(假话)。init 的结构不并入共享实现(它的
192
+ // lstat/符号链接拒绝/建父目录是写路径特有),但这段文案与 status/db/sync 同源。
152
193
  return fail({ code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
153
- message: `不是普通文件:${config.path}`, hint: '--db 指向的不是普通文件,请改成一个数据库文件路径' });
194
+ message: `不是普通文件:${config.path}`, hint: nonRegularFileHint(true) });
154
195
  }
155
196
  if (st !== undefined && st.isFile() === false && st.isSymbolicLink() === false && st.isDirectory() === false) {
156
197
  // 其它特殊文件(设备/套接字等)同样拒绝
157
198
  return fail({ code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
158
- message: `不是普通文件:${config.path}`, hint: '--db 指向的不是普通文件,请改成一个数据库文件路径' });
199
+ message: `不是普通文件:${config.path}`, hint: nonRegularFileHint(false) });
159
200
  }
160
201
  if (st !== undefined && st.isSymbolicLink() === true) {
202
+ // ⚠️ 这条检查**不是安全边界**(历史审查 PR#4「Symlink checks can be bypassed」复核):
203
+ // `lstat` 与随后 DuckDB 的 `create` 之间仍有 TOCTOU 窗口,能把路径换成链接的进程
204
+ // 同样能直接改写库里内容 —— 那已经是"同一用户权限下的任意文件写",不是本 CLI 能靠
205
+ // 一次 lstat 拦住的威胁。DuckDB 的打开接口没有 `O_NOFOLLOW` 之类的入口,所以这里
206
+ // 只做**防误用**(用户/脚本把 --db 指到链接上时立刻说清楚),并在测试里钉住拒绝行为
207
+ // (tests/commands/store.test.ts 的「--db 是符号链接」用例)。不要把它当成安全承诺写进
208
+ // 文档;真要防篡改,正确做法是给库文件与父目录设权限(0600/0700)。
161
209
  return fail({ code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
162
210
  message: `目标是符号链接:${config.path}`, hint: '--db 目标是符号链接,请给出真实路径' });
163
211
  }
@@ -181,76 +229,116 @@ export async function storeCommand(argv) {
181
229
  store = await openStore(config, 'rw');
182
230
  }
183
231
  catch (e) {
184
- return thrownToExit(e);
232
+ return thrownToExit(e, profileFlag);
185
233
  }
186
234
  try {
187
235
  await store.init();
188
- const tables = await store.tables();
236
+ // ⚠️ 与 `store status` 同口径(2026-11-01):`store.tables()` 给的是**全库**清单
237
+ // (含未声明表),两个命令若一个全给、一个只给声明表,README 承诺的
238
+ // 「两边数量应当一致」就成了假话。未声明的表名进 warnings,不静默丢弃。
239
+ const all = await store.tables();
189
240
  const sv = await store.query('SELECT COALESCE(MAX(version),0) AS v FROM schema_version');
241
+ const declaredNames = TABLES.map((t) => t.name);
242
+ // ⚠️ 同名对象不是基表(view 等)就不算「我们的表」(2026-11-14,PR #74 合并后自查):
243
+ // `store.tables()` 来自 `information_schema`、把 view 也算作表,init 曾把一条 view
244
+ // 列进自己的 tables 清单(实测),而 `store status` / `db tables` 已是「只数基表 +
245
+ // 非基表进 warnings」。三处清单同口径,README 的「两边数量应当一致」才成立。
246
+ // 同样按声明名归位(DuckDB 标识符大小写不敏感:`"TAGS"` view 就是 `tags` 这个名字)。
247
+ const nonBase = nonBaseTables((await store.query(OBJECT_KINDS_SQL)).rows)
248
+ .map((n) => tableByName(n)?.name ?? n);
249
+ const warnings = [
250
+ ...(storeTablesWarnings(all, config.path, profileFlag) ?? []),
251
+ ...(nonBaseTablesWarning(nonBase) ?? []),
252
+ ];
190
253
  return ok({ path: config.path, backend: config.backend, config_path: configPath,
191
254
  config_exists: configExists,
192
255
  schema_version: Number(sv.rows[0]?.v ?? 0),
193
- tables });
256
+ tables: all.filter((n) => declaredNames.some((d) => sameObjectName(d, n)) && !nonBase.includes(n)) }, warnings.length === 0
257
+ ? { field_notes: storeFieldNotes() }
258
+ : { field_notes: storeFieldNotes(), warnings });
194
259
  }
195
260
  catch (e) {
196
- return thrownToExit(e);
261
+ return thrownToExit(e, profileFlag);
197
262
  }
198
263
  finally {
199
264
  await store.close();
200
265
  }
201
266
  }
202
267
  // status
203
- // ⚠️ statSync 异常按 errno 分流(K 组 M6):EACCES 误报「请先运行 init」会把
204
- // 只读路径的权限错误引导向写操作(init),Agent 必然再失败一次 —— 归因必须准。
205
- let st;
206
- try {
207
- st = statSync(config.path);
208
- }
209
- catch (e) {
210
- const code = e.code;
211
- if (code === 'ENOENT') {
212
- return fail({ code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
213
- message: `数据库文件不存在:${config.path}`, hint: '数据库尚未初始化。请先运行:qiyu store init' });
214
- // ⚠️ 修复批 2 裁定:D 交付后本 hint **不改指** `qiyu sync run`(设计稿 §9.5 的
215
- // 「D 交付后改指 sync run」不再采纳)——「初始化存储」的最小命令是 store init,
216
- // 且 sync status/verify 是只读命令,指它们跑一次写操作并非必要。
217
- // 同步侧(sync status/verify/install、sync run 的 storeInitFail)与 C1 同口径。
218
- }
219
- return fail({ code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
220
- message: `无法访问 ${config.path}:${e instanceof Error ? e.message : String(e)}`,
221
- hint: '请检查路径权限(status 是只读命令,不需要写权限)' });
222
- }
223
- if (!st.isFile()) {
224
- // ⚠️ P 组 P-H2:目录成因**不能**引导向 store init(init 也拒绝目录 → 死循环)——
225
- // 独立 hint,与「不存在」成因分形。
226
- return fail({ code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
227
- message: `不是普通文件:${config.path}`,
228
- hint: '--db 指向的是目录而非数据库文件,请给出 .duckdb 数据库文件路径' });
229
- }
268
+ // 库前置检查(ENOENT / 权限 / 非普通文件)走 `store-precheck.ts` 的 `statGuard`
269
+ // ——**唯一实现点**(2026-10-31 收敛)。此前这里自己写了一份,与 db/sync 那两份
270
+ // already 漂移出两种说法:本文件的权限 hint 写「status 是只读命令」、非普通文件写
271
+ // 「指向的是目录」(对 FIFO/设备是假话);db/sync 写「只读命令」「不是普通文件」。
272
+ // ⚠️ 「不存在」成因的裁定保留在此(不进共享实现):D 交付后本 hint **不改指**
273
+ // `qiyu sync run`(设计稿 §9.5 的「D 交付后改指 sync run」不再采纳)——「初始化存储」
274
+ // 的最小命令是 store init,且 sync status/verify 是只读命令,指它们跑一次写操作并非必要。
275
+ // 同步侧(sync status/verify/install、sync run 的 storeInitFail)与 C1 同口径。
276
+ const guarded = statGuard(config.path);
277
+ if (guarded !== null)
278
+ return guarded;
230
279
  let store;
231
280
  try {
232
281
  store = await openStore(config, 'ro');
233
282
  }
234
283
  catch (e) {
235
- return thrownToExit(e);
284
+ return thrownToExit(e, profileFlag);
236
285
  }
237
286
  try {
238
287
  const names = await store.tables();
239
- if (!names.includes('schema_version')) {
240
- return fail({ code: 'store_not_initialized', kind: 'store_not_initialized', retryable: false,
241
- message: `数据库结构不完整(缺表):${config.path}`,
242
- hint: names.length > 0 ? '目标数据库不是本 CLI 创建的,请换 --db 路径' : '请运行:qiyu store init' });
243
- }
288
+ // ⚠️ 成因分形(他人库不引导向 init)在共享实现里,口径与 db/sync 逐字一致。
289
+ // ⚠️ 表名不是身份证明(2026-11-07 审查实测):他人工具的 schema_version 无 version 列时,
290
+ // 旧判据放行,下面的 MAX(version) 抛 Binder Error 落 internal「备份重建」—— 假归因。
291
+ const versionColumns = names.some((n) => sameObjectName('schema_version', n))
292
+ ? (await store.query(SCHEMA_VERSION_COLUMNS_SQL)).rows.map((r) => String(r.column_name))
293
+ : undefined;
294
+ const missing = schemaVersionMissing(config.path, names, versionColumns);
295
+ if (missing !== null)
296
+ return fail(missing);
244
297
  const tables = [];
245
- for (const n of names)
298
+ // ⚠️ 只能对**声明表**(`TABLES`)做 COUNT(2026-11-01 实测修):`store.count()` 内部
299
+ // 走 `assertTable`,库里有未声明的表(旧版 CLI 或其它工具建的)时抛 `usage`
300
+ // (`未知表:xxx`,退出码 2)—— 于是 `store status` 在**库恰好有漂移时整条命令失败**,
301
+ // 连 `schema_version` 都拿不到,而 `db tables` 对同一状态只是把它列进 warnings
302
+ //(README 与 `db tables` 都明确把「库中有而声明无」当作**要警告、不失败**的漂移)。
303
+ // `names` 来自全库 `information_schema`(含未声明表),因此必须按声明集过滤后再 COUNT;
304
+ // 未声明的表名进 warnings(不得静默 —— 与 `db tables` 同口径,README 承诺要报警)。
305
+ const undeclared = new Set(undeclaredTables(names));
306
+ // ⚠️ 只数**基表**(2026-11-14,历史审查 PR#4 复核):`information_schema` 把 view 也算作
307
+ // 表,同名 view 会让 COUNT 执行它的本体(实测 `read_csv_auto` 的 view → IO Error →
308
+ // status 整条退出 1,而「库有漂移只警告」是本命令的承诺)。view/macro 与未声明表一样
309
+ // 进 warnings、不进 tables。
310
+ // ⚠️ 比对大小写不敏感(Codex PR#76 实测):一条 `"TICKETS"` view 会被 `"tickets"` 解析
311
+ // 到并被执行,而元数据里的名字保留原样 —— `Set.has()` 精确比会漏掉它。
312
+ const nonBase = nonBaseTables((await store.query(OBJECT_KINDS_SQL)).rows);
313
+ for (const n of names) {
314
+ if (undeclared.has(n) || nonBase.some((x) => sameObjectName(n, x)))
315
+ continue;
316
+ // ⚠️ 基表的 COUNT 失败**不**降级成警告(Codex PR#74 第三轮 P1):view 已在上面按类型
317
+ // 排除,所以走到这里的都是基表,数不出来就是真错(磁盘 I/O、库损坏、并发删表)——
318
+ // 按 spec §8.2「DuckDB 执行期错误 → internal / 退出码 1」如实失败。
319
+ // 把这类错误说成 warning + 退出码 0,Agent 会以为拿到的 tables 是完整的。
246
320
  tables.push({ name: n, rows: await store.count(n) });
247
- const sv = await store.query('SELECT COALESCE(MAX(version),0) AS v FROM schema_version');
321
+ }
322
+ // ⚠️ `schema_version` 自己是 view 时**不许求值**(CodeRabbit PR#74):列检查(version 列存在)
323
+ // 会放行,这条 MAX(version) 仍会把 view 本体执行一遍 —— 一个 `CAST('x' AS INTEGER)` 就能
324
+ // 让整条 status 退出 1,把「库有漂移只警告」的承诺打穿。按缺失读,交给 warnings 点名。
325
+ const sv = nonBase.some((x) => sameObjectName('schema_version', x))
326
+ ? { rows: [{ v: 0 }] }
327
+ : await store.query('SELECT COALESCE(MAX(version),0) AS v FROM schema_version');
328
+ // ⚠️ 两半漂移都进 warnings,**唯一渲染点**在 `storeTablesWarnings`(2026-11-02 实测修):
329
+ // 此前这里只算「库中有而声明无」,声明表被删时 tables 少了几张却零 warnings ——
330
+ // 同一库上 `db tables` 会警告、`store status` 报 ok 且干净,README 又教 Agent
331
+ // 「数量不等时先读 warnings」,于是 Agent 读到空 warnings 反而确认了「没事」。
332
+ const warnings = storeTablesWarnings(names, config.path, profileFlag);
333
+ const allWarnings = [...(warnings ?? []), ...(nonBaseTablesWarning(nonBase) ?? [])];
248
334
  return ok({ path: config.path, backend: config.backend, config_path: configPath,
249
335
  config_exists: configExists,
250
- schema_version: Number(sv.rows[0]?.v ?? 0), tables });
336
+ schema_version: Number(sv.rows[0]?.v ?? 0), tables }, allWarnings.length === 0
337
+ ? { field_notes: storeFieldNotes() }
338
+ : { field_notes: storeFieldNotes(), warnings: allWarnings });
251
339
  }
252
340
  catch (e) {
253
- return thrownToExit(e);
341
+ return thrownToExit(e, profileFlag);
254
342
  }
255
343
  finally {
256
344
  await store.close();