qiyu-cli 0.2.0 → 0.2.1
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 +5 -2
- package/dist/commands/api.js +1 -1
- package/dist/commands/skill.js +49 -4
- package/dist/commands/sync.js +1 -1
- package/dist/core/edition.js +13 -3
- package/dist/skill/detect.js +35 -0
- package/dist/skill/qiyu/SKILL.md +12 -6
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -64,7 +64,9 @@ npm 无法确认可信版本、也就无法 pin 版本,`--allow-scripts` 同
|
|
|
64
64
|
|
|
65
65
|
安装是幂等的:正文一致时不动正文(清单缺失或损坏时会补写 `.qiyu-skill.json`);要覆盖
|
|
66
66
|
你改过的正文得加 `--force`。其他子命令:
|
|
67
|
-
`qiyu skill where` 报告实体目录与各 Agent
|
|
67
|
+
`qiyu skill where` 报告实体目录与各 Agent 的链接状态(只读,不修复),并给出**已安装那份
|
|
68
|
+
正文**的契约号与兼容判定(`data.entity.installed.compatible`,与 `data.cli_contract_version`
|
|
69
|
+
比较;判定不了时为 `null`,不是 `false`);`qiyu skill check`
|
|
68
70
|
校验 skill 引用的命令/表/错误 kind 是否仍存在(有违规退出码 1,CI 可跑;`--compare` 模式下
|
|
69
71
|
两份正文内容不一致、或已安装那份不可用,同样退 1)。
|
|
70
72
|
|
|
@@ -165,7 +167,8 @@ qiyu skill install [--dir <path>] [--link <agent>]... [--no-link] [--force] [--d
|
|
|
165
167
|
qiyu skill check [--installed [--dir <path>] | --compare [--dir <path>]]
|
|
166
168
|
校验 skill 引用的命令/表/错误 kind(有违规退出码 1;
|
|
167
169
|
--compare 下内容不一致也算失败)
|
|
168
|
-
qiyu skill where [--dir <path>] 报告实体目录与各 Agent
|
|
170
|
+
qiyu skill where [--dir <path>] 报告实体目录与各 Agent 链接状态(只读,不修复),
|
|
171
|
+
并报已安装正文的契约号与 compatible 判定
|
|
169
172
|
qiyu --version 包版本 + skill_contract_version
|
|
170
173
|
```
|
|
171
174
|
|
package/dist/commands/api.js
CHANGED
|
@@ -764,7 +764,7 @@ export function assertNoValidateStrictConflict(argv) {
|
|
|
764
764
|
export function assertGetHasNoBody(spec, body) {
|
|
765
765
|
if (spec.method === 'GET' && body !== undefined) {
|
|
766
766
|
throw new Error(`接口 ${spec.id} 是 GET 接口,不接受请求体 —— 去掉 --body。` +
|
|
767
|
-
'⚠️ 本 CLI
|
|
767
|
+
'⚠️ 本 CLI 目前没有 GET 的 query 参数通道(还没有可主动调用的 GET 接口),' +
|
|
768
768
|
'所以现在无法给它带任何参数;这道守卫是为了将来出现可调用 GET 时不静默丢弃 body');
|
|
769
769
|
}
|
|
770
770
|
}
|
package/dist/commands/skill.js
CHANGED
|
@@ -39,7 +39,7 @@ import { prettyAfterSubcommand } from './spec-types.js';
|
|
|
39
39
|
import { skillFlagSpecs } from './skill-specs.js';
|
|
40
40
|
import { checkSkillDir } from '../skill/check.js';
|
|
41
41
|
import { contentHash, installSkill, planInstall } from '../skill/install.js';
|
|
42
|
-
import { entityUndeterminedNote, npmRelativeBase, resetSkillDetectionCache, resolveEntityDirSources, resolveSkillSourceDir, } from '../skill/detect.js';
|
|
42
|
+
import { entityUndeterminedNote, npmRelativeBase, readInstalledManifestInfo, resetSkillDetectionCache, resolveEntityDirSources, resolveSkillSourceDir, } from '../skill/detect.js';
|
|
43
43
|
import { AGENT_SKILL_SUBDIRS, agentSkillDirs, agentSkillSubdir, LINK_NAME, linkState, } from '../skill/paths.js';
|
|
44
44
|
/**
|
|
45
45
|
* 已知 agent 名(`--link` 的合法取值)。从 paths.ts 的 `AGENT_SKILL_SUBDIRS` 派生,
|
|
@@ -58,7 +58,12 @@ const SKILL_USAGE = `用法:qiyu skill <子命令> [参数]
|
|
|
58
58
|
skill where [--dir <path>]
|
|
59
59
|
报告实体目录与各 agent 链接状态(只读,不修复;
|
|
60
60
|
实体路径无法判定时 exists=null,链接无法判定时
|
|
61
|
-
state=unknown(带 error
|
|
61
|
+
state=unknown(带 error)——都不是「不存在」);
|
|
62
|
+
并给出已安装正文的版本元数据 entity.installed
|
|
63
|
+
{version, skill_contract_version, compatible} 与
|
|
64
|
+
CLI 自己的 cli_contract_version —— 判断正文能否配这份
|
|
65
|
+
CLI 就看 compatible(实体不可用或清单缺失/损坏时
|
|
66
|
+
installed=null(判定不了),不编造)
|
|
62
67
|
|
|
63
68
|
实体目录定位:--dir > QIYU_SKILL_DIR > npm_config_qiyu_skill_dir(postinstall 的安装
|
|
64
69
|
通道,含大小写/连字符归一)> ~/.agents/skills/qiyu
|
|
@@ -803,9 +808,12 @@ async function skillWhere(argv) {
|
|
|
803
808
|
warnings.push(probe.note);
|
|
804
809
|
// 实体状态:只读 stat;ENOENT 是「未安装」,其余异常如实记 unknown。
|
|
805
810
|
let entity;
|
|
811
|
+
let entityUsable = false;
|
|
806
812
|
try {
|
|
807
813
|
const st = statSync(entityDir);
|
|
808
|
-
|
|
814
|
+
const isDir = st.isDirectory();
|
|
815
|
+
entity = { path: entityDir, source, exists: true, state: isDir ? 'ok' : 'not_a_directory' };
|
|
816
|
+
entityUsable = isDir;
|
|
809
817
|
}
|
|
810
818
|
catch (e) {
|
|
811
819
|
if (isErrno(e, 'ENOENT')) {
|
|
@@ -818,9 +826,46 @@ async function skillWhere(argv) {
|
|
|
818
826
|
entity = { path: entityDir, source, exists: null, state: 'unknown', error: errMsg(e) };
|
|
819
827
|
}
|
|
820
828
|
}
|
|
829
|
+
// 已安装那份的**版本元数据**(2026-10-26 补):`SKILL.md` 教 Agent「用
|
|
830
|
+
// `skill_contract_version` 判断手上的正文能否配这份 CLI」,而此前没有任何命令报出
|
|
831
|
+
// **已安装那份**的契约号 —— `--version` 与 `check` 的 meta 报的都是 CLI 自己的。
|
|
832
|
+
// 那条承诺因此是空的。这里给出安装时的两个版本号 + 与当前 CLI 是否配套的判定。
|
|
833
|
+
// · `null` = 清单缺失/损坏/读不动/实体本身不可用 —— **不编造**(与 detect 的
|
|
834
|
+
// 'unknown' 同一条纪律)。**键必须始终出现**(2026-10-26 审查):此前只有
|
|
835
|
+
// 实体可用时才设这个键,实体缺失/非目录/检查失败时输出里根本没有它,调用方
|
|
836
|
+
// 拿到的是 undefined —— 而 SKILL.md 把 `null` 定义为「判定不了」,`undefined`
|
|
837
|
+
// 则是「这个字段不存在」,两种沉默对 Agent 含义不同,不能混。
|
|
838
|
+
// · `compatible` = 三方判定的落点:只有契约号相等才算配套。包版本不同不算
|
|
839
|
+
// 不兼容(正文没变就还能用),这正是 SKILL.md 说「别拿包版本号去比」的原因。
|
|
840
|
+
entity.installed = null;
|
|
841
|
+
if (entityUsable) {
|
|
842
|
+
const info = readInstalledManifestInfo(entityDir);
|
|
843
|
+
if (info !== null) {
|
|
844
|
+
entity.installed = {
|
|
845
|
+
version: info.version,
|
|
846
|
+
skill_contract_version: info.skillContractVersion,
|
|
847
|
+
compatible: info.skillContractVersion === SKILL_CONTRACT_VERSION,
|
|
848
|
+
};
|
|
849
|
+
}
|
|
850
|
+
if (info !== null && info.skillContractVersion !== SKILL_CONTRACT_VERSION) {
|
|
851
|
+
// ⚠️ 必须推 `--force`(2026-10-26 实测):正文一改,实体内容哈希就与包内不同,
|
|
852
|
+
// `planInstall` 此时**不带 --force 一律 skipped + 零写入**——照旧文案推
|
|
853
|
+
// `qiyu skill install`,用户跑完契约号仍是旧值、警告照旧,等于指了条死路。
|
|
854
|
+
// `--force` 是两种形态都收敛的动词:正文确实不同 → 覆盖;正文恰好一致但清单
|
|
855
|
+
// 落后 → 走 rewrite-manifest(该分支排在 force 判断之前),同样把号补正。
|
|
856
|
+
warnings.push(`已安装的 skill 契约版本为 ${info.skillContractVersion},当前 CLI 是 ${SKILL_CONTRACT_VERSION}`
|
|
857
|
+
+ ' —— 正文与 CLI 不配套;运行 `qiyu skill install --force` 更新正文');
|
|
858
|
+
}
|
|
859
|
+
}
|
|
821
860
|
const probed = probeAgentLinks(resolveHome(), entityDir);
|
|
822
861
|
warnings.push(...probed.warnings);
|
|
823
|
-
return ok({
|
|
862
|
+
return ok({
|
|
863
|
+
entity,
|
|
864
|
+
links: probed.links,
|
|
865
|
+
// CLI 自己的契约号:与 `entity.installed.skill_contract_version` 并列,让读者能
|
|
866
|
+
// 一眼看出「两个数是否相等」,不必再去跑 `--version` 比对。
|
|
867
|
+
cli_contract_version: SKILL_CONTRACT_VERSION,
|
|
868
|
+
}, warnings.length > 0 ? { warnings } : undefined);
|
|
824
869
|
}
|
|
825
870
|
// —— 分派 ——
|
|
826
871
|
export async function skillCommand(argv) {
|
package/dist/commands/sync.js
CHANGED
|
@@ -126,7 +126,7 @@ const USAGE = `用法:qiyu sync <子命令> [参数]
|
|
|
126
126
|
CRON 为 5 段(分 时 日 月 周),支持 * / 数字 / a-b / a-b/k / */k / 逗号列表。
|
|
127
127
|
存储定位:--db / --profile / --backend(store 命令同族)。
|
|
128
128
|
install 的平台形态:darwin=launchd plist、linux=systemd unit+timer(crontab 兜底)、
|
|
129
|
-
win32=schtasks
|
|
129
|
+
win32=schtasks。安装前置:库已初始化且至少成功同步过一次(sync_state 有
|
|
130
130
|
range_status=complete 或 last_synced_at 非空的行;全败的 run 只留 pending,不算跑通)。
|
|
131
131
|
`;
|
|
132
132
|
const KNOWN = new Set(GLOBAL_FLAG_NAMES);
|
package/dist/core/edition.js
CHANGED
|
@@ -12,7 +12,17 @@
|
|
|
12
12
|
// `scripts/copy-assets.mjs`(Task 13)在 tsc 之后把 dist/core/edition.js 里的
|
|
13
13
|
// '0.0.0-dev' 字面量正则替换为 package.json 的 version。源码里永远保持占位值,
|
|
14
14
|
// 靠测试钉住「构建产物非占位」这一契约。
|
|
15
|
-
/**
|
|
16
|
-
|
|
15
|
+
/**
|
|
16
|
+
* skill 正文契约版本:结构性改变才递增(spec D6)。
|
|
17
|
+
*
|
|
18
|
+
* 变更记录:
|
|
19
|
+
* · 1 —— F 子项目交付时的初版(六篇正文)。
|
|
20
|
+
* · 2 —— 2026-10-26:`SKILL.md` 新增「`qiyu skill where` 报出已安装正文的契约号与
|
|
21
|
+
* `compatible`」这一协议段落。**必须递增**:新正文要求 CLI 输出
|
|
22
|
+
* `data.entity.installed` 与 `data.cli_contract_version`,而 0.2.0 的 CLI 没有这些
|
|
23
|
+
* 字段 —— 若不递增,新正文配旧 CLI 会被 `compatible` 判成「配套」,Agent 照着读
|
|
24
|
+
* 会拿到 `undefined`(正是本字段要防的那种「看起来能用、实际不能用」)。
|
|
25
|
+
*/
|
|
26
|
+
export const SKILL_CONTRACT_VERSION = 2;
|
|
17
27
|
/** 包版本占位值;构建期被 copy-assets.mjs 替换为 package.json 的 version。 */
|
|
18
|
-
export const PACKAGE_VERSION = '0.2.
|
|
28
|
+
export const PACKAGE_VERSION = '0.2.1';
|
package/dist/skill/detect.js
CHANGED
|
@@ -44,6 +44,41 @@ import path from 'node:path';
|
|
|
44
44
|
import { fileURLToPath } from 'node:url';
|
|
45
45
|
import { contentHash, MANIFEST } from './install.js';
|
|
46
46
|
import { defaultEntityDir, readEnvByNormalizedKey } from './paths.js';
|
|
47
|
+
/**
|
|
48
|
+
* 读已安装正文的清单版本信息(`skill where` 用)。
|
|
49
|
+
*
|
|
50
|
+
* ⚠️ **为什么需要它**(2026-10-26 实测发现):`SKILL.md` 教 Agent
|
|
51
|
+
* 「用 `skill_contract_version` 判断手上的正文能否配这份 CLI」,但此前**没有任何命令
|
|
52
|
+
* 报出已安装那份的契约号** —— `qiyu --version` 给的是 CLI 自己的,`skill check
|
|
53
|
+
* --installed` 的 `meta.skill_contract_version` 同样是 CLI 自己的(容易被读成"已安装
|
|
54
|
+
* 那份的"),`skill where` 完全不报。于是那句承诺是**空的**:Agent 手上没有可比的数。
|
|
55
|
+
* 实测佐证:把已安装清单的 `skill_contract_version` 改成 99,上面三条命令的输出
|
|
56
|
+
* 一字不变、`meta.warnings` 也不出现任何提示。
|
|
57
|
+
*
|
|
58
|
+
* 返回 `null` 的情形与 `readManifestStrict` 一致(缺失/损坏/字段不全),另外
|
|
59
|
+
* **读不动**(EACCES 等)也归 `null` —— 本函数是排查命令的辅助,不该因为权限问题
|
|
60
|
+
* 让整条 `skill where` 失败;调用方据此报 `null`(= 无法判定),不编造。
|
|
61
|
+
*
|
|
62
|
+
* 契约号还要求是**非负整数**(2026-10-26 审查):`readManifestStrict` 只做类型检查
|
|
63
|
+
* (`typeof === 'number'`),`1.5` / `-3` 都能溜进来。那些值不可能是任何一版安装器
|
|
64
|
+
* 写出的契约号 —— 是一份**损坏**的清单,正确结论是「判定不了」(null),而不是拿它
|
|
65
|
+
* 去比出一个 `compatible:false`:后者会让 Agent 以为「正文版本旧了,重装即可」,
|
|
66
|
+
* 而真实状态是「清单坏了,重装前先确认没别的问题」。0 放行:合法判定归调用方,
|
|
67
|
+
* 本函数只管「这是不是一个像样的契约号」。
|
|
68
|
+
*/
|
|
69
|
+
export function readInstalledManifestInfo(entityDir) {
|
|
70
|
+
try {
|
|
71
|
+
const m = readManifestStrict(entityDir);
|
|
72
|
+
if (m === null)
|
|
73
|
+
return null;
|
|
74
|
+
if (!Number.isInteger(m.skill_contract_version) || m.skill_contract_version < 0)
|
|
75
|
+
return null;
|
|
76
|
+
return { version: m.version, skillContractVersion: m.skill_contract_version };
|
|
77
|
+
}
|
|
78
|
+
catch {
|
|
79
|
+
return null;
|
|
80
|
+
}
|
|
81
|
+
}
|
|
47
82
|
// 进程内判定:同参只探测一次(spec D2.1 的「零成本」)。缓存**不会随文件系统变化自动
|
|
48
83
|
// 失效**,所以凡是「本进程刚改过实体目录」的路径都必须主动调 `resetSkillDetectionCache()`。
|
|
49
84
|
//
|
package/dist/skill/qiyu/SKILL.md
CHANGED
|
@@ -37,17 +37,23 @@ qiyu sync status
|
|
|
37
37
|
|
|
38
38
|
- **`meta.warnings` 里的 skill 提示**:任何一条成功输出都可能带一句「skill 未安装」或
|
|
39
39
|
「skill 已过期」。它只提示、不改退出码、不改 `data`,也**没有自动改过任何文件**。
|
|
40
|
-
含义是本机装的正文与这份 CLI 不配套;更新方式是 `qiyu skill install`——它会写到本机
|
|
40
|
+
含义是本机装的正文与这份 CLI 不配套;更新方式是 `qiyu skill install --force`——它会写到本机
|
|
41
41
|
的 skill 实体目录与各 Agent 的 skills 目录。**只在人类允许写 home 时执行**,不要自作主张
|
|
42
42
|
改动用户目录;不允许时把这条提示原样转述给人类。
|
|
43
|
-
- **`qiyu --version`**:输出包版本(`data.version`)与 `data.skill_contract_version
|
|
44
|
-
|
|
45
|
-
|
|
43
|
+
- **`qiyu --version`**:输出包版本(`data.version`)与 `data.skill_contract_version`
|
|
44
|
+
(**这份 CLI** 的正文契约号)。
|
|
45
|
+
- **`qiyu skill where`**:报告实体目录与各 Agent 链接状态,并给出**已安装那份正文**的
|
|
46
|
+
版本元数据:`data.entity.installed.skill_contract_version`(装的那份的契约号)、
|
|
47
|
+
`data.cli_contract_version`(本 CLI 的)与 `data.entity.installed.compatible`
|
|
48
|
+
(两者是否相等)。**判断「手上的正文能否配这份 CLI」就看这一个字段**,不要拿包版本号
|
|
49
|
+
去比 —— 包版本不同但契约号相同,正文仍然能用。`installed` 为 `null` = 实体不可用,
|
|
50
|
+
或清单缺失/损坏,判定不了,不要当成「兼容」。
|
|
46
51
|
- **`qiyu skill check`**:正文自身的防漂移校验(命令、表名、错误 `kind`、位置参数取值是否
|
|
47
52
|
仍存在于当前 CLI)。默认校验包内那份;`--installed` 校验已安装的那份,`--compare` 比对
|
|
48
53
|
两份并报告差异。有违规时退出码 1。
|
|
49
|
-
-
|
|
50
|
-
|
|
54
|
+
- **不要手工编辑已安装的正文**:手工改过之后,`qiyu skill install`(不带 `--force`)
|
|
55
|
+
会判定「内容与包内不同」而**跳过不覆盖**,你改的那份会一直留着、也一直与包内不一致。
|
|
56
|
+
要改就改包内(发行包里的)那份,再 `qiyu skill install --force` 覆盖本机那份。
|
|
51
57
|
|
|
52
58
|
## 通道路由决策树
|
|
53
59
|
|