qiyu-cli 0.2.1 → 0.2.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +433 -72
- package/dist/cli.js +48 -7
- package/dist/commands/api-notes.js +70 -0
- package/dist/commands/api.js +169 -49
- package/dist/commands/auth.js +151 -29
- package/dist/commands/credentials-source.js +30 -5
- package/dist/commands/db-notes.js +75 -0
- package/dist/commands/db.js +165 -127
- package/dist/commands/query-notes.js +58 -0
- package/dist/commands/query.js +449 -61
- package/dist/commands/skill.js +445 -51
- package/dist/commands/spec-types.js +101 -1
- package/dist/commands/stats.js +160 -33
- package/dist/commands/store-flags.js +18 -0
- package/dist/commands/store-notes.js +38 -0
- package/dist/commands/store-precheck.js +321 -0
- package/dist/commands/store.js +165 -77
- package/dist/commands/sync-notes.js +374 -0
- package/dist/commands/sync-run.js +180 -47
- package/dist/commands/sync.js +232 -127
- package/dist/core/config.js +280 -24
- package/dist/core/credentials.js +38 -4
- package/dist/core/edition.js +1 -1
- package/dist/core/envelope.js +73 -9
- package/dist/core/errors.js +73 -16
- package/dist/core/http.js +175 -54
- package/dist/core/ratelimit.js +5 -1
- package/dist/core/registry/index.js +36 -2
- package/dist/core/registry/params/export.session.check.json +17 -2
- package/dist/core/registry/params/export.session.json +24 -2
- package/dist/core/registry/params/export.session.one.json +10 -2
- package/dist/core/registry/params/export.session.one.message.json +17 -2
- package/dist/core/registry/specs.json +65 -43
- package/dist/core/shell.js +30 -0
- package/dist/core/time.js +1 -1
- package/dist/core/validate.js +21 -2
- package/dist/output.js +215 -29
- package/dist/postinstall.js +14 -5
- package/dist/query/errors.js +145 -45
- package/dist/query/mask.js +1277 -25
- package/dist/query/metric-catalog.js +11 -0
- package/dist/query/native-error.js +189 -0
- package/dist/query/sandbox.js +148 -25
- package/dist/query/table-query.js +36 -5
- package/dist/schedule/install.js +136 -13
- package/dist/skill/check.js +11 -6
- package/dist/skill/detect.js +89 -29
- package/dist/skill/install.js +233 -43
- package/dist/skill/paths.js +54 -0
- package/dist/skill/qiyu/SKILL.md +29 -5
- package/dist/skill/qiyu/errors.md +5 -4
- package/dist/skill/qiyu/protocols.md +57 -5
- package/dist/skill/qiyu/setup.md +6 -2
- package/dist/store/config.js +92 -16
- package/dist/store/duckdb.js +1551 -64
- package/dist/store/object-kinds.js +32 -0
- package/dist/store/retry.js +190 -7
- package/dist/store/schema.js +32 -4
- package/dist/sync/engine.js +439 -77
- package/dist/sync/registry.js +6 -0
- package/dist/sync/state.js +20 -0
- package/dist/sync/tasks/dim.js +23 -14
- package/dist/sync/tasks/knowledge.js +50 -8
- package/dist/sync/tasks/pace.js +27 -0
- package/dist/sync/tasks/pipeline.js +29 -9
- package/dist/sync/tasks/reports.js +176 -49
- package/dist/sync/tasks/sessions.js +88 -21
- package/dist/sync/tasks/tickets.js +59 -8
- package/dist/sync/types.js +60 -1
- package/dist/sync/windowing.js +0 -22
- package/dist/sync/write-contract.js +79 -0
- package/package.json +2 -2
package/dist/schedule/install.js
CHANGED
|
@@ -12,6 +12,7 @@
|
|
|
12
12
|
// 子集外显式失败并指引手工创建。
|
|
13
13
|
import { execFileSync } from 'node:child_process';
|
|
14
14
|
import { existsSync } from 'node:fs';
|
|
15
|
+
import { describeArgs, shellArg } from '../output.js';
|
|
15
16
|
/** 平台检测的显式失败形态(usage):未知平台不猜测、不静默回退。 */
|
|
16
17
|
export function detectPlatform() {
|
|
17
18
|
const p = process.platform;
|
|
@@ -99,11 +100,34 @@ function parseField(src, def) {
|
|
|
99
100
|
const wildcard = sorted.length === def.max - def.min + 1;
|
|
100
101
|
return { values: sorted, wildcard };
|
|
101
102
|
}
|
|
103
|
+
/**
|
|
104
|
+
* 分隔符只接受空格与 Tab。
|
|
105
|
+
*
|
|
106
|
+
* ⚠️ `trim()` 与 `split(/\s+/)` 都会把 CR / LF / 垂直制表 / 不换行空格(U+00A0)/
|
|
107
|
+
* 行分隔符(U+2028)当成空白放过 —— 解析能通过,但**同一个原文字符串**会原样进入
|
|
108
|
+
* 逐行格式的产物(crontab 兜底行、`schedule` 回显):实测 `0 0 *\r* *` 解析成合法
|
|
109
|
+
* 5 段,产出的兜底行里是一个字面的 CR(cron 的字段分隔只认空格/Tab,整行失效);
|
|
110
|
+
* `0 0 * * *\n` 更会把一条条目劈成两条物理行。与 `assertSchedulable` 同族:
|
|
111
|
+
* 不可表达的输入显式拒绝,不替用户清洗(清洗会改变「用户到底装了什么」的事实)。
|
|
112
|
+
*/
|
|
113
|
+
function assertPlainSeparators(expr) {
|
|
114
|
+
const bad = /[^\S \t]/.exec(expr);
|
|
115
|
+
if (!bad)
|
|
116
|
+
return;
|
|
117
|
+
const ch = bad[0];
|
|
118
|
+
const cp = ch.codePointAt(0).toString(16).toUpperCase().padStart(4, '0');
|
|
119
|
+
throw usageError(`无法解析的 cron 表达式:含不允许的空白字符 U+${cp}(${JSON.stringify(ch)}),`
|
|
120
|
+
+ '分隔符只接受空格与 Tab —— 换行/回车等字符会原样进入逐行的调度条目(crontab 兜底行、'
|
|
121
|
+
+ `schedule 回显),把一条计划拆成两条或让整行失效:${JSON.stringify(expr)}`);
|
|
122
|
+
}
|
|
102
123
|
/** 解析 5 段 cron;解析失败抛 usage(契约诚实性:绝不静默装错时刻的计划)。 */
|
|
103
124
|
export function parseCron(expr) {
|
|
125
|
+
assertPlainSeparators(expr);
|
|
104
126
|
const parts = expr.trim().split(/\s+/);
|
|
105
127
|
if (parts.length !== 5) {
|
|
106
|
-
|
|
128
|
+
// ⚠️ describeArgs 渲染取值:`--schedule ''` 此前报「实际 1 段:」冒号后空白,
|
|
129
|
+
// 看不出表达式到底是什么(2026-10-29,与 sync run 的取值渲染同族)。
|
|
130
|
+
throw usageError(`无法解析的 cron 表达式:必须是 5 段(分 时 日 月 周),实际 ${parts.length} 段:${describeArgs([expr])}`);
|
|
107
131
|
}
|
|
108
132
|
const [minute, hour, day, month, weekday] = parts.map((p, i) => parseField(p, FIELDS[i]));
|
|
109
133
|
return { minute: minute, hour: hour, day: day, month: month, weekday: weekday };
|
|
@@ -129,7 +153,47 @@ export const SCHTASKS_TASK_NAME = 'qiyu-cli-sync';
|
|
|
129
153
|
function runArgs(exec, storeArgs = []) {
|
|
130
154
|
return [...exec, 'sync', 'run', ...storeArgs];
|
|
131
155
|
}
|
|
132
|
-
/**
|
|
156
|
+
/**
|
|
157
|
+
* systemd unit 行里的参数渲染:先按 systemd 的**字面量规则**转义,再做引号。
|
|
158
|
+
*
|
|
159
|
+
* ⚠️ `ExecStart=` 不是 shell,但它在交给程序之前自己会做三轮替换(官方文档原文):
|
|
160
|
+
* ① `\` 是 C 转义(systemd.syntax(7)「Each command line is unquoted using the rules
|
|
161
|
+
* described in Quoting…」「In particular, any backslashes should be doubled」;
|
|
162
|
+
* 该表把 `\\` 映射成字面 `\`,且**引号内外都解析**——文档没有为单/双引号分别规定)
|
|
163
|
+
* → 字面 `\` 必须写 `\\`,否则 `\b` 会被解成退格、行尾 `\` 还会**续行**;
|
|
164
|
+
* ② `%` 是指令说明符(systemd.service(5)「The command line accepts "%" specifiers as
|
|
165
|
+
* described in systemd.unit(5)」)→ 字面 `%` 必须写 `%%`;
|
|
166
|
+
* ③ `$` 会做环境变量替换(systemd.service(5)「to pass a literal dollar sign, use "$$"」)。
|
|
167
|
+
*
|
|
168
|
+
* 所以 `--db /tmp/a%b.db` 会被替换成 boot id、`--db /tmp/$HOME/q.db` 会被展开成别处、
|
|
169
|
+
* `--db 'C:\x\q.db'` 会被吃掉反斜杠 —— 与 crontab 的 `%` 是同一族缺陷的不同载体
|
|
170
|
+
* (本轮 Sourcery 只点了 crontab,这里把三种字面字符一并收)。良性值(不含
|
|
171
|
+
* `\`/`%`/`$`)逐字不变,故既有条目形态零漂移。
|
|
172
|
+
*
|
|
173
|
+
* ⚠️ 未覆盖边界:本机是 darwin,无 systemd 可端到端实测;上述三条转义依据官方文档,
|
|
174
|
+
* 未在真实 unit 上验证「引号内 `$$`/`%%` 是否同样折叠」。转义只影响含这三个字符的值
|
|
175
|
+
* (此前这些值本来就必错),不含它们时是恒等变换。
|
|
176
|
+
*/
|
|
177
|
+
function systemdArg(v) {
|
|
178
|
+
// ⚠️ 必须用**函数式替换**:替换串里的 `$` 有特殊含义(`$$` → 字面 `$`、`$&` 等),
|
|
179
|
+
// 写 `v.replace(/\$/g, '$$')` 实测产出**一个** `$`(转义被自身吃掉)。函数返回值
|
|
180
|
+
// 不做这种解析。
|
|
181
|
+
const escaped = v.replace(/\\/g, () => '\\\\').replace(/%/g, () => '%%').replace(/\$/g, () => '$$');
|
|
182
|
+
// ⚠️ 引号不能走 `shellQuote`(2026-11-07 审查实测):它只在含空白/双引号时才加双引号,
|
|
183
|
+
// `--profile o'brien` 于是把裸 `'` 原样写进 ExecStart —— 而 systemd.service(5) 的
|
|
184
|
+
// 命令行解析把 `'` 当**引号符**,整条命令会被错误切分。同一参数在 crontab 兜底行里
|
|
185
|
+
// 却经 `shellArg(v,'linux')` 正确转义 —— 两个载体对同一值给出不同结果。
|
|
186
|
+
// 规则:含空白 / 双引号 / 单引号时用双引号包裹,并把 `"` 转义
|
|
187
|
+
// (反斜杠已在上一步双写,systemd 在双引号内外都按同一规则处理反斜杠)。
|
|
188
|
+
const quoted = /[\s"']/.test(escaped)
|
|
189
|
+
? `"${escaped.replace(/"/g, () => '\\"')}"`
|
|
190
|
+
: escaped;
|
|
191
|
+
// ④ systemd.service(5):「An argument solely consisting of ";" must be escaped, i.e.
|
|
192
|
+
// specified as "\;"」—— 裸 `;` 是**命令分隔符**,会把一条 ExecStart 劈成两条命令
|
|
193
|
+
//(`sync install --db ';'` 这种值罕见,但静默执行别的东西比报错更糟)。文档只对
|
|
194
|
+
// 「整体就是一个 `;`」的参数规定这条,`a;b` 这类值不受影响。
|
|
195
|
+
return quoted === ';' ? '\\;' : quoted;
|
|
196
|
+
}
|
|
133
197
|
function launchdKey(key, f) {
|
|
134
198
|
const value = f.values.length === 1
|
|
135
199
|
? `<integer>${f.values[0]}</integer>`
|
|
@@ -155,8 +219,10 @@ function launchdCalendarXml(spec) {
|
|
|
155
219
|
if (dayR)
|
|
156
220
|
dicts.push(base(launchdKey('Day', spec.day)));
|
|
157
221
|
if (wdR) {
|
|
158
|
-
//
|
|
159
|
-
|
|
222
|
+
// ⚠️ launchd 的 Weekday 与 cron **同一套编号**(man launchd.plist:0 和 7 都是
|
|
223
|
+
// 周日、1 是周一),不是 1 起算 —— 此前这里 `v + 1` 把所有任务整体后移了一天
|
|
224
|
+
// (cron 周一 → 周日执行)。多值 → 键内数组(launchd 键内 OR)。
|
|
225
|
+
const wd = { values: [...spec.weekday.values], wildcard: false };
|
|
160
226
|
dicts.push(base(launchdKey('Weekday', wd)));
|
|
161
227
|
}
|
|
162
228
|
if (dicts.length === 0)
|
|
@@ -220,7 +286,12 @@ function schtasksScheduleArgs(spec) {
|
|
|
220
286
|
const dateRestricted = !spec.day.wildcard || !spec.month.wildcard;
|
|
221
287
|
if (dateRestricted && !spec.day.wildcard && spec.month.wildcard
|
|
222
288
|
&& spec.weekday.wildcard && spec.minute.values.length === 1 && spec.hour.values.length === 1) {
|
|
223
|
-
|
|
289
|
+
// ⚠️ `/SC MONTHLY /D` 只接受**一个**日期(schtasks 文档:「you can specify only one day
|
|
290
|
+
// in the schedule」)——`0 0 1,15 * *` 直接 join 成 `/D 1,15` 会产出一个注定失败的
|
|
291
|
+
// 计划(dry-run 就先给了它)。多日显式落 unmappable,不赌真实 schtasks 的容忍度。
|
|
292
|
+
if (spec.day.values.length !== 1)
|
|
293
|
+
throw unmappable();
|
|
294
|
+
return ['/SC', 'MONTHLY', '/D', String(spec.day.values[0]), '/ST', time];
|
|
224
295
|
}
|
|
225
296
|
if (!spec.weekday.wildcard && spec.day.wildcard && spec.month.wildcard
|
|
226
297
|
&& spec.minute.values.length === 1 && spec.hour.values.length === 1) {
|
|
@@ -245,8 +316,12 @@ function schtasksScheduleArgs(spec) {
|
|
|
245
316
|
throw unmappable();
|
|
246
317
|
if (!spec.minute.wildcard && spec.hour.wildcard) {
|
|
247
318
|
const step = progressionStep(spec.minute.values, 59);
|
|
319
|
+
// ⚠️ `/ST` 必须给:schtasks 的 `/ST` 缺省值是「本机当前时刻」,而 `/SC MINUTE /MO N`
|
|
320
|
+
// 是「从起始时刻起每 N 分钟」——不给 /ST 的话 `*/30` 会被装成「安装那一刻 + 30 分的
|
|
321
|
+
// 相位」(14:07 安装 → :07/:37),而 cron 是 :00/:30。与上面 HOURLY 支同理(它补了
|
|
322
|
+
// /ST 锚相位),也与本模块红线「绝不静默装出错误时刻的计划」冲突。
|
|
248
323
|
if (step !== null)
|
|
249
|
-
return ['/SC', 'MINUTE', '/MO', String(step)];
|
|
324
|
+
return ['/SC', 'MINUTE', '/MO', String(step), '/ST', `00:${pad2(spec.minute.values[0])}`];
|
|
250
325
|
throw unmappable();
|
|
251
326
|
}
|
|
252
327
|
if (!spec.minute.wildcard && !spec.hour.wildcard
|
|
@@ -260,8 +335,52 @@ function unmappable() {
|
|
|
260
335
|
return usageError('无法把该 cron 映射为 schtasks 计划(支持:每 N 分钟 / 每 N 小时 / 每日 / 每周 / 每月的固定时刻)。'
|
|
261
336
|
+ '请在 Windows 任务计划程序中手工创建,或换一个可映射的时刻');
|
|
262
337
|
}
|
|
338
|
+
/**
|
|
339
|
+
* crontab 兜底行:**给人手工复制执行的 POSIX shell 行**(cron 以 `/bin/sh -c` 执行它)。
|
|
340
|
+
*
|
|
341
|
+
* 两层转义、顺序不能反(crontab(5) 原文核实):
|
|
342
|
+
* ① 先 `shellArg`(shlex.quote 同一安全集,POSIX 单引号方言)—— 挡 `$()`/空白/引号;
|
|
343
|
+
* ② 再把 `%` 转义成 `\%` —— **cron 在交给 sh 之前**就处理 `%`:原文「The entire command
|
|
344
|
+
* portion of the line, up to a newline or % character, will be executed … Percent-signs (%),
|
|
345
|
+
* unless escaped with backslash (\), will be changed into newline characters, and all data
|
|
346
|
+
* after the first % will be sent to the command as standard input」。所以单引号挡不住它 ——
|
|
347
|
+
* `--db /tmp/a%b.db` 会让 cron 执行 `--db /tmp/a`、把 `b.db` 当 stdin,**静默跑错库**。
|
|
348
|
+
* 实测(2026-11-02):修前该值裸着印在兜底行里。
|
|
349
|
+
*
|
|
350
|
+
* ⚠️ 未覆盖边界:值里**同时**含 `\` 与 `%` 时不保证(cron 对 `\\` 的处理本机无法实测,
|
|
351
|
+
* 只核实了文档写明的 `\%` 一条规则)。这类路径极罕见,如实记在这里、不假装已覆盖。
|
|
352
|
+
* ⚠️ 换行/回车由两个守卫各管一半:**run 参数**走 `assertSchedulable`(三个平台一致),
|
|
353
|
+
* **--schedule 原文**走 `assertPlainSeparators`(它在 `parseCron` 里,先于任何产物生成)。
|
|
354
|
+
*
|
|
355
|
+
* `shellQuote`(本文件)保留给**不经 shell 也不做替换**的消费方:launchd 的 plist 走
|
|
356
|
+
* `xmlEscape`;schtasks 的 `/TR` 存的是任务动作,由 Task Scheduler 直接 CreateProcess
|
|
357
|
+
* (不经 cmd.exe,`$`/`%` 不展开 —— 依据其执行模型推断,本机 darwin 未能实测)。
|
|
358
|
+
* ExecStart 另有 `systemdArg`(systemd 自己的引号与 `%%`/`$$` 转义;**单引号也参与**
|
|
359
|
+
* —— 见该函数注释)。
|
|
360
|
+
*/
|
|
361
|
+
function crontabArg(v) {
|
|
362
|
+
return shellArg(v, 'linux').replace(/%/g, '\\%');
|
|
363
|
+
}
|
|
263
364
|
function crontabLine(schedule, exec, storeArgs = []) {
|
|
264
|
-
return `${schedule} ${runArgs(exec, storeArgs).map(
|
|
365
|
+
return `${schedule} ${runArgs(exec, storeArgs).map(crontabArg).join(' ')}`;
|
|
366
|
+
}
|
|
367
|
+
/**
|
|
368
|
+
* 调度条目放不下 CR/LF —— 显式拒绝,绝不装出一条含义不同的条目。
|
|
369
|
+
*
|
|
370
|
+
* 三种载体里 systemd unit 与 crontab 行都是**逐行格式**:值里的换行会把一条条目劈成
|
|
371
|
+
* 两条(实测 crontab 兜底行:`--db '/tmp/a\n0 0 * * * touch /tmp/x\nb.db'` 变成三个物理
|
|
372
|
+
* 行,中间那行是一条**真的 cron 计划**)。系统调度器装出来的东西会以安装者身份执行,
|
|
373
|
+
* 所以这里按「不可表达」处理而不是替用户猜测/清洗。launchd 的 plist 技术上能承载换行,
|
|
374
|
+
* 但同一份参数在三平台的形态应当一致(且这种路径无实际意义),故三平台统一拒绝。
|
|
375
|
+
*/
|
|
376
|
+
function assertSchedulable(run) {
|
|
377
|
+
for (const v of run) {
|
|
378
|
+
if (/[\r\n]/.test(v)) {
|
|
379
|
+
throw usageError(`调度条目的参数不能含换行或回车(${describeArgs([v])}):`
|
|
380
|
+
+ 'systemd unit 与 crontab 行是逐行格式,换行会把一条条目拆成两条、'
|
|
381
|
+
+ '后半段会成为一条独立的计划。请改用不含换行的路径');
|
|
382
|
+
}
|
|
383
|
+
}
|
|
265
384
|
}
|
|
266
385
|
/**
|
|
267
386
|
* 生成安装计划(纯函数,不写 fs)。
|
|
@@ -273,6 +392,7 @@ function crontabLine(schedule, exec, storeArgs = []) {
|
|
|
273
392
|
export function planInstall(platform, schedule, opts) {
|
|
274
393
|
const spec = parseCron(schedule);
|
|
275
394
|
const run = runArgs(opts.exec, opts.storeArgs ?? []);
|
|
395
|
+
assertSchedulable(run);
|
|
276
396
|
if (platform === 'darwin') {
|
|
277
397
|
const dir = `${opts.home}/Library/LaunchAgents`;
|
|
278
398
|
const path = `${dir}/${LAUNCHD_LABEL}.plist`;
|
|
@@ -303,7 +423,7 @@ export function planInstall(platform, schedule, opts) {
|
|
|
303
423
|
const dir = `${opts.home}/.config/systemd/user`;
|
|
304
424
|
const servicePath = `${dir}/${SYSTEMD_NAMES.service}`;
|
|
305
425
|
const timerPath = `${dir}/${SYSTEMD_NAMES.timer}`;
|
|
306
|
-
const execLine = run.map(
|
|
426
|
+
const execLine = run.map(systemdArg).join(' ');
|
|
307
427
|
const onCalendar = systemdOnCalendar(spec);
|
|
308
428
|
const service = `[Unit]
|
|
309
429
|
Description=七鱼数据同步(qiyu sync run)
|
|
@@ -354,6 +474,7 @@ export function planUninstall(platform, opts) {
|
|
|
354
474
|
return {
|
|
355
475
|
platform, remove: [{ path, exists: exists(path) }],
|
|
356
476
|
commands: [['launchctl', 'unload', path]],
|
|
477
|
+
postRemoveCommands: [],
|
|
357
478
|
notes: ['卸载次序:先 launchctl unload(停止已加载的代理),文件随后删除。'],
|
|
358
479
|
};
|
|
359
480
|
}
|
|
@@ -362,16 +483,18 @@ export function planUninstall(platform, opts) {
|
|
|
362
483
|
const paths = [`${dir}/${SYSTEMD_NAMES.service}`, `${dir}/${SYSTEMD_NAMES.timer}`];
|
|
363
484
|
return {
|
|
364
485
|
platform, remove: paths.map((path) => ({ path, exists: exists(path) })),
|
|
365
|
-
commands: [
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
486
|
+
commands: [['systemctl', '--user', 'disable', '--now', SYSTEMD_NAMES.timer]],
|
|
487
|
+
// ⚠️ daemon-reload 必须在**删完文件之后**:先 reload 只会重新加载即将被删的 unit,
|
|
488
|
+
// 删完之后没有命令再让 systemd 忘掉它(旧定时器条目会留在内存里直到下次 reload)。
|
|
489
|
+
// 注意不要写成 `disable --now` 之后的第二键 —— 命令层是「跑完 commands 再删文件」。
|
|
490
|
+
postRemoveCommands: [['systemctl', '--user', 'daemon-reload']],
|
|
491
|
+
notes: ['卸载次序:先 disable --now(停定时器),再删除 unit 文件,最后 daemon-reload。'],
|
|
370
492
|
};
|
|
371
493
|
}
|
|
372
494
|
return {
|
|
373
495
|
platform, remove: [],
|
|
374
496
|
commands: [['schtasks', '/Delete', '/TN', SCHTASKS_TASK_NAME, '/F']],
|
|
497
|
+
postRemoveCommands: [],
|
|
375
498
|
notes: ['Windows:卸载即执行 schtasks /Delete(--yes 时执行)。'],
|
|
376
499
|
};
|
|
377
500
|
}
|
package/dist/skill/check.js
CHANGED
|
@@ -2,7 +2,8 @@
|
|
|
2
2
|
// (命令树 / 表名 / 错误 kind / 位置参数取值域)比对,产出三档判定(设计稿 D3):
|
|
3
3
|
//
|
|
4
4
|
// · violations:引用不存在的命令 / flag / kind / 位置参数取值;flag 写错了位置;正文
|
|
5
|
-
// 出现表名;出现完整 SQL 序列;推荐了被显式拒绝的 flag
|
|
5
|
+
// 出现表名;出现完整 SQL 序列;推荐了被显式拒绝的 flag(`rejected` 清单当前为空,
|
|
6
|
+
// 2026-10-24 前 `--pretty` 曾是唯一成员,G1 实现后清空、规则保留)。
|
|
6
7
|
// · warnings:无法静态判定的引用(含管道 / 选择 / 复合命令符号等),不阻塞,但要指认位置。
|
|
7
8
|
// · 两者皆空:通过。
|
|
8
9
|
//
|
|
@@ -71,8 +72,10 @@ function dropFlagsAndValues(tokens, flagAt) {
|
|
|
71
72
|
* 判定顺序(同一行内多条违规的产出顺序):
|
|
72
73
|
* 1. 命令路径:`findSpec` 最长前缀匹配,未命中 → `unknown_command`;
|
|
73
74
|
* 2. flag 接受集:**先查 `spec.rejected`**,再查 `spec.flags` 的完整接受集。顺序是硬要求 ——
|
|
74
|
-
*
|
|
75
|
-
*
|
|
75
|
+
* 一个 flag 可能同时在两者里(`--pretty` 曾是这种情形:在 `GLOBAL_FLAGS` 里、又在
|
|
76
|
+
* `REJECTED_FLAGS` 里),反过来先查 `flags` 会把它判成合法,`rejected_flag` 永远报不出来。
|
|
77
|
+
* 2026-10-24(G1)起 `--pretty` 已实现、不再是 rejected,故当前 `REJECTED_FLAGS` 为空;
|
|
78
|
+
* **次序规则保留**,将来再出现「已知但显式拒绝」的 flag 时按同一次序判。
|
|
76
79
|
* 3. flag 的位置:落在命令路径之内 → `flag_before_subcommand`;落在「第一个位置参数」槽位
|
|
77
80
|
* → `flag_before_positional`;值位 flag 缺取值 → `flag_missing_value`;
|
|
78
81
|
* 4. 位置参数取值域:命令词之后的字面 token 逐个按 `spec.positionals[i].domain` 查注入的
|
|
@@ -113,7 +116,8 @@ function checkCommand(cmd, ctx, violations) {
|
|
|
113
116
|
// 2:flag 接受集。
|
|
114
117
|
for (const flag of cmd.flags) {
|
|
115
118
|
if (spec.rejected.includes(flag.name)) {
|
|
116
|
-
// ⚠️ 必须先于 accepted
|
|
119
|
+
// ⚠️ 必须先于 accepted 判断:一个 flag 可能同时在两者里(`--pretty` 曾是这种情形,
|
|
120
|
+
// G1 实现后已不在 `rejected` 里;次序规则保留)。
|
|
117
121
|
violations.push({
|
|
118
122
|
line: cmd.line,
|
|
119
123
|
rule: 'rejected_flag',
|
|
@@ -229,8 +233,9 @@ function checkCommand(cmd, ctx, violations) {
|
|
|
229
233
|
* 判定顺序(violations 最终按行稳定排序,便于按出现位置阅读):
|
|
230
234
|
* 1. 命令路径:`findSpec` 最长前缀匹配,未命中 → `unknown_command`;
|
|
231
235
|
* 2. flag:**先查 `spec.rejected`**,再查 `spec.flags` 的完整接受集。顺序是硬要求 ——
|
|
232
|
-
*
|
|
233
|
-
*
|
|
236
|
+
* 一个 flag 可能同时在两者里(`--pretty` 曾是这种情形,G1 实现后不再是),反过来先查
|
|
237
|
+
* `flags` 会把它判成合法,`rejected_flag` 永远报不出来。次序规则与空清单的现状见
|
|
238
|
+
* `checkCommand` 的注释。
|
|
234
239
|
* 3. flag 的位置与缺值(见 checkCommand 的注释);
|
|
235
240
|
* 4. 位置参数取值域:命令词之后的字面 token 逐个按 `spec.positionals[i].domain` 查注入的
|
|
236
241
|
* 闭集;不在闭集 → `unknown_positional`,位置参数个数超过 spec 声明同样违规;
|
package/dist/skill/detect.js
CHANGED
|
@@ -11,8 +11,10 @@
|
|
|
11
11
|
// 版本相同仅内容漂移 → 「内容与包内当前版本不一致(版本 <v>)」;
|
|
12
12
|
// 版本未知 → 「无法确认已安装 skill 的版本(安装清单缺失或损坏)」;
|
|
13
13
|
// 前两支以「运行 `qiyu skill install --force` 更新」收尾——内容与包内
|
|
14
|
-
// 不同,不带 `--force`
|
|
15
|
-
//
|
|
14
|
+
// 不同,不带 `--force` 只会跳过;第三支**两个动词都给出**并各自注明条件
|
|
15
|
+
// (清单没了就判不出正文是否漂移:一致时裸 install 补写清单即收敛,
|
|
16
|
+
// 漂移时只有 `--force` 收敛 —— 2026-10-27 实测,此前只推裸 install,
|
|
17
|
+
// 漂移那一半用户跑完提示原样还在);
|
|
16
18
|
// · current / unknown → 不提示(unknown = 判定不了,宁可闭嘴也不打扰)。
|
|
17
19
|
//
|
|
18
20
|
// **只提示、绝不改退出码、绝不改 data、绝不自动改文件**——自动覆盖用户可能改过的
|
|
@@ -38,12 +40,13 @@
|
|
|
38
40
|
// 分层:`skill/` 叶子层,只 import `node:*`、`core/` 与 `skill/` 内部;`output.ts`
|
|
39
41
|
// **不得** import 本文件(Task 14 分层红线钉住)——提示文案经
|
|
40
42
|
// `output.setSkillWarning()` 注入,探测与输出解耦。
|
|
41
|
-
import {
|
|
43
|
+
import { statSync } from 'node:fs';
|
|
42
44
|
import { homedir } from 'node:os';
|
|
43
45
|
import path from 'node:path';
|
|
44
46
|
import { fileURLToPath } from 'node:url';
|
|
45
|
-
import { contentHash, MANIFEST } from './install.js';
|
|
46
|
-
import { defaultEntityDir, readEnvByNormalizedKey } from './paths.js';
|
|
47
|
+
import { contentHash, MANIFEST, readManifestSafe, readPlainTextFile } from './install.js';
|
|
48
|
+
import { defaultEntityDir, dirShape, readEnvByNormalizedKey } from './paths.js';
|
|
49
|
+
import { nonEmptyValue } from '../core/config.js';
|
|
47
50
|
/**
|
|
48
51
|
* 读已安装正文的清单版本信息(`skill where` 用)。
|
|
49
52
|
*
|
|
@@ -68,12 +71,22 @@ import { defaultEntityDir, readEnvByNormalizedKey } from './paths.js';
|
|
|
68
71
|
*/
|
|
69
72
|
export function readInstalledManifestInfo(entityDir) {
|
|
70
73
|
try {
|
|
71
|
-
|
|
74
|
+
// ⚠️ 用 `readManifestSafe`(与安装/清理同一个解析器),不是本文件里探测用的
|
|
75
|
+
// `readManifestStrict`:后者刻意只取四个核心字段、丢掉 files/file_hashes,而
|
|
76
|
+
// `where` 核对正文需要受管文件清单(CodeRabbit #60)。两者对「缺失/损坏」都返回
|
|
77
|
+
// null,差别只在是否带出扩展字段。
|
|
78
|
+
const m = readManifestSafe(entityDir);
|
|
72
79
|
if (m === null)
|
|
73
80
|
return null;
|
|
74
81
|
if (!Number.isInteger(m.skill_contract_version) || m.skill_contract_version < 0)
|
|
75
82
|
return null;
|
|
76
|
-
return {
|
|
83
|
+
return {
|
|
84
|
+
version: m.version,
|
|
85
|
+
skillContractVersion: m.skill_contract_version,
|
|
86
|
+
contentHash: m.content_hash,
|
|
87
|
+
files: m.files,
|
|
88
|
+
fileHashes: m.file_hashes,
|
|
89
|
+
};
|
|
77
90
|
}
|
|
78
91
|
catch {
|
|
79
92
|
return null;
|
|
@@ -120,19 +133,17 @@ export function detectSkillState(entityDir, sourceDir, currentVersion) {
|
|
|
120
133
|
/** 真正的探测逻辑(无缓存)。任何异常都收敛成 unknown。 */
|
|
121
134
|
function probe(entityDir, sourceDir, currentVersion) {
|
|
122
135
|
try {
|
|
123
|
-
//
|
|
124
|
-
//
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
if (!isDir)
|
|
135
|
-
return { kind: 'unknown' }; // 路径被文件占用:不是未安装,也不能谎报 stale
|
|
136
|
+
// 实体路径的形态走共享判据(`paths.ts` 的 `dirShape`,审查 #9):此前这里直接
|
|
137
|
+
// `statSync` 并把 ENOENT 认成 absent —— 但**悬空符号链接**(实体在网盘/大盘上、
|
|
138
|
+
// 盘没挂上)也抛 ENOENT,于是启动探测注入「skill 未安装;运行 `qiyu skill install`」,
|
|
139
|
+
// 而那条命令在悬空链接上必然退 1(无法覆盖链接)。CLI 自荐了一条走不通的路。
|
|
140
|
+
// `dirShape` 区分三态:absent(真不存在,提示成立)、not_a_directory(存在但不是
|
|
141
|
+
// 目录,含悬空链接 → 判定不了,宁可闭嘴)、dir(继续读清单)。
|
|
142
|
+
const shape = dirShape(entityDir);
|
|
143
|
+
if (shape === 'absent')
|
|
144
|
+
return { kind: 'absent' };
|
|
145
|
+
if (shape === 'not_a_directory')
|
|
146
|
+
return { kind: 'unknown' }; // 存在但不是目录:不是「未安装」,也不谎报 stale
|
|
136
147
|
// 只读清单、不读实体正文(spec D2.1 的「零成本」)。readManifestStrict 对
|
|
137
148
|
// 缺失/损坏/字段不全统一返回 null。
|
|
138
149
|
const manifest = readManifestStrict(entityDir);
|
|
@@ -168,7 +179,10 @@ function probe(entityDir, sourceDir, currentVersion) {
|
|
|
168
179
|
function readManifestStrict(entityDir) {
|
|
169
180
|
let text;
|
|
170
181
|
try {
|
|
171
|
-
|
|
182
|
+
// ⚠️ 走 `readPlainTextFile`(先验普通文件):清单被 FIFO 占住时 `readFileSync` 会
|
|
183
|
+
// 无限阻塞(Codex PR #69 第六轮)。非普通文件抛 EINVAL —— 与 EACCES 同路,
|
|
184
|
+
// 落到下面的 rethrow(= 状态 unknown,静默),语义与「清单看不了」一致。
|
|
185
|
+
text = readPlainTextFile(path.join(entityDir, MANIFEST));
|
|
172
186
|
}
|
|
173
187
|
catch (err) {
|
|
174
188
|
if (isErrno(err, 'ENOENT'))
|
|
@@ -217,10 +231,27 @@ export function skillWarning(state, ctx) {
|
|
|
217
231
|
// · 版本相同、仅内容哈希漂移 → 版本号相同,说「版本不一致」自相矛盾;
|
|
218
232
|
// · 版本不同 → 说清「安装于 X,当前 Y」。
|
|
219
233
|
if (state.installedVersion === 'unknown') {
|
|
220
|
-
//
|
|
221
|
-
//
|
|
222
|
-
//
|
|
223
|
-
|
|
234
|
+
// ⚠️ 这一支**判不出正文是否被手工改过**(清单没了,而探测刻意不读正文,D2.1 的
|
|
235
|
+
// 「零成本」),于是裸 `qiyu skill install` 只覆盖其中一种成因:
|
|
236
|
+
// · 正文与包内一致(且清单路径可写)→ planInstall 走 rewrite-manifest,只补写
|
|
237
|
+
// 清单,收敛;
|
|
238
|
+
// · 正文被手工改过 → 「内容不同且无 --force」→ skipped + 零写入,**提示原样还在**。
|
|
239
|
+
// 2026-10-27 实测(清单损坏 + 正文改过 → 跑裸 install → 提示不消失;跑 --force → 消失)。
|
|
240
|
+
// 纪律:提示里的动词必须覆盖该状态的**所有**成因,所以两个动词连同各自的成立条件
|
|
241
|
+
// 一起给出 —— 只推裸 install 就是让漂移那一半用户白跑一趟。
|
|
242
|
+
//
|
|
243
|
+
// 「清单可写」也是条件之一(`writeTargetWarning`)。注意它**不是**两个动词同样
|
|
244
|
+
// 挡住的:2026-10-27 实测(悬空符号链接占住清单路径)——
|
|
245
|
+
// · 正文一致:裸 install 与 --force 都 skipped,实体零变化;
|
|
246
|
+
// · 正文漂移:--force 报 status=updated 且**正文已被换掉**,但清单写不进去,
|
|
247
|
+
// 探测仍报 stale、提示不会消失(CodeRabbit 指出的部分写入)。
|
|
248
|
+
// 所以文案不能说「两个命令都不会覆盖」——那只对清单成立,对正文不成立。
|
|
249
|
+
return '无法确认已安装 skill 的版本(安装清单缺失或损坏);运行 `qiyu skill install` 补写清单'
|
|
250
|
+
+ '——正文与包内一致时即收敛;正文被手工改过时它会跳过不覆盖、提示不会消失,'
|
|
251
|
+
+ '那种情况用 `qiyu skill install --force` 覆盖。'
|
|
252
|
+
+ '若清单路径被非普通文件(符号链接/目录)占用,清单写不进去、提示不会消失:'
|
|
253
|
+
+ '正文被手工改过时 `--force` 只覆盖正文(状态报 updated),正文与包内一致时'
|
|
254
|
+
+ '连 `--force` 也零写入(status 报 skipped);无论哪种,先清理该占用再跑';
|
|
224
255
|
}
|
|
225
256
|
if (ctx?.currentVersion !== undefined && state.installedVersion === ctx.currentVersion) {
|
|
226
257
|
return `已安装的 skill 内容与包内当前版本不一致(版本 ${state.installedVersion});运行 \`qiyu skill install --force\` 更新`;
|
|
@@ -230,6 +261,16 @@ export function skillWarning(state, ctx) {
|
|
|
230
261
|
}
|
|
231
262
|
return undefined;
|
|
232
263
|
}
|
|
264
|
+
/**
|
|
265
|
+
* 实体目录的来源(`skill where` / `install` 输出里的 `entity.source` 即此字符串)。
|
|
266
|
+
*
|
|
267
|
+
* 四个取值与解析优先级一一对应:`--dir` > `QIYU_SKILL_DIR` > `npm_config_qiyu_skill_dir`
|
|
268
|
+
* > 默认位置(`~/.agents/skills/qiyu`)。`npm_config_qiyu_skill_dir` 是 postinstall 的
|
|
269
|
+
* 安装通道(spec C5),命令层与探测层都必须认识它——否则「装到自定义目录」之后每条命令
|
|
270
|
+
* 都误报「未安装」并建议再装一份(终审 I2)。
|
|
271
|
+
*/
|
|
272
|
+
/** 实体目录来源(优先级即数组顺序)—— 输出里的 `entity.source`/`entity_source` 取值。 */
|
|
273
|
+
export const ENTITY_SOURCES = ['--dir', 'QIYU_SKILL_DIR', 'npm_config_qiyu_skill_dir', 'default'];
|
|
233
274
|
/**
|
|
234
275
|
* npm 相对路径的唯一基准(G3 审查 C3):`INIT_CWD ?? cwd`。
|
|
235
276
|
*
|
|
@@ -301,8 +342,10 @@ export function resolveEntityDirSources(opts) {
|
|
|
301
342
|
const flagDir = opts.flagDir?.trim();
|
|
302
343
|
if (flagDir !== undefined && flagDir !== '')
|
|
303
344
|
return resolve(flagDir, '--dir');
|
|
304
|
-
|
|
305
|
-
|
|
345
|
+
// 空串口径与全仓同源(core/config.ts 的 nonEmptyValue 是唯一实现);本处额外先 trim
|
|
346
|
+
// —— `QIYU_SKILL_DIR=' '` 也是「没填」,而路径不能是空白串。
|
|
347
|
+
const explicit = nonEmptyValue(opts.env.QIYU_SKILL_DIR?.trim());
|
|
348
|
+
if (explicit !== undefined)
|
|
306
349
|
return resolve(explicit, 'QIYU_SKILL_DIR');
|
|
307
350
|
if (opts.testGate !== false) {
|
|
308
351
|
if (readEnvByNormalizedKey(opts.env, DISABLE_PROBE_ENV) !== undefined) {
|
|
@@ -317,10 +360,27 @@ export function resolveEntityDirSources(opts) {
|
|
|
317
360
|
return resolve(fromNpm, 'npm_config_qiyu_skill_dir');
|
|
318
361
|
return resolve(defaultEntityDir(opts.home ?? homedir()), 'default');
|
|
319
362
|
}
|
|
320
|
-
/**
|
|
321
|
-
|
|
363
|
+
/**
|
|
364
|
+
* 实体未确定时给用户看的一句话(已确定返回 undefined)。
|
|
365
|
+
*
|
|
366
|
+
* `opts.explicitSource`(2026-11-06 审查 S3):调用方(`skill where`)**本命令**已经从
|
|
367
|
+
* `--dir`/`QIYU_SKILL_DIR` 定位到了实体,而启动探测看不到命令行参数。此时原文案
|
|
368
|
+
* 「且没有显式给出 --dir 或 QIYU_SKILL_DIR … 要定位实体请显式给出 --dir」与用户刚做的
|
|
369
|
+
* 动作**自相矛盾**(他还真给了)。这条分支改成:说清未定位的是**启动探测**、因此本次
|
|
370
|
+
* 没有「未安装/已过期」提示,并点名本命令实体来自哪里、不受影响。
|
|
371
|
+
*/
|
|
372
|
+
export function entityUndeterminedNote(resolution, env = process.env, opts = {}) {
|
|
322
373
|
if (resolution.decided)
|
|
323
374
|
return undefined;
|
|
375
|
+
const explicit = opts.explicitSource;
|
|
376
|
+
if (explicit !== undefined) {
|
|
377
|
+
const why = resolution.reason === 'env'
|
|
378
|
+
? `启动探测已被 ${DISABLE_PROBE_ENV} 显式关闭`
|
|
379
|
+
: `当前进程像 Node 测试(NODE_ENV=${env.NODE_ENV ?? ''},VITEST=${env.VITEST ?? ''})`;
|
|
380
|
+
return `skill 启动探测未定位实体目录:${why} —— 启动探测不读命令行参数,`
|
|
381
|
+
+ '所以本次不会有「未安装/已过期」提示。⚠️ 本命令的实体来自 '
|
|
382
|
+
+ `${explicit},不受影响`;
|
|
383
|
+
}
|
|
324
384
|
if (resolution.reason === 'env') {
|
|
325
385
|
return `skill 实体目录未确定:探测已被 ${DISABLE_PROBE_ENV} 显式关闭;需要时显式给出 --dir 或 QIYU_SKILL_DIR`;
|
|
326
386
|
}
|