@givolt/i3-composer-agent 2.2.1 → 2.2.2

package/bin/native-runtime.cjs

@@ -0,0 +1,57 @@
+'use strict';
+
+// Installed as scripts/i3-composer-agent/lib/installation.cjs. Resolve from
+// this file, never the caller's working directory or the host's package.json.
+const fs = require('node:fs');
+const path = require('node:path');
+const EXPECTED_VERSION = '__I3_INSTALL_VERSION__';
+const root = path.resolve(__dirname, '../../..');
+const manifestPath = path.join(root, '.i3-composer-agent.json');
+
+function resolveOwned(relative) {
+  if (typeof relative !== 'string' || relative.includes('\\') || relative.includes(':')
+      || relative.includes('\0') || relative.split('/').some(part => ['', '.', '..'].includes(part))) {
+    throw new Error(`安装清单路径无效：${relative}`);
+  }
+  let file = root;
+  for (const part of relative.split('/')) {
+    file = path.join(file, part);
+    if (!fs.existsSync(file)) throw new Error(`安装内容缺失：${relative}`);
+    if (fs.lstatSync(file).isSymbolicLink()) throw new Error(`安装内容不能通过符号链接替代：${relative}`);
+  }
+  if (!fs.statSync(file).isFile()) throw new Error(`安装文件无效：${relative}`);
+  return file;
+}
+
+function loadInstallation() {
+  let manifest;
+  try { manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); }
+  catch (error) { throw new Error(`无法读取安装清单 ${manifestPath}：${error.message}`); }
+  if (manifest.name !== 'i3-composer-agent' || manifest.layoutVersion !== 2
+      || manifest.version !== EXPECTED_VERSION || !Array.isArray(manifest.assets) || !manifest.assets.length) {
+    throw new Error(`安装清单的名称、布局或版本不匹配：${manifestPath}`);
+  }
+  const assets = new Set(manifest.assets);
+  for (const [category, suffix] of [['skills', '/SKILL.md'], ['commands', '.md'], ['agents', '.md']]) {
+    const names = manifest.catalog?.[category];
+    if (!Array.isArray(names) || !names.length || new Set(names).size !== names.length) {
+      throw new Error(`安装清单缺少有效的 ${category} 目录项：${manifestPath}`);
+    }
+    for (const name of names) {
+      if (typeof name !== 'string' || !/^[a-z0-9][a-z0-9-]*$/.test(name)
+          || !assets.has(`${category}/${name}${suffix}`)) throw new Error(`安装清单目录项无效：${category}/${name}`);
+    }
+  }
+  for (const relative of assets) resolveOwned(relative);
+  const resources = {};
+  for (const category of ['references', 'evals', 'hooks', 'scripts', 'docs']) {
+    const relative = `${category}/i3-composer-agent`;
+    if (manifest.resources?.[category] !== relative || ![...assets].some(file => file.startsWith(relative + '/'))) {
+      throw new Error(`安装清单缺少资源：${category}`);
+    }
+    resources[category] = path.join(root, relative);
+  }
+  return { root, manifest, catalog: manifest.catalog, resources, skillsDirectory: path.join(root, 'skills') };
+}
+
+module.exports = { loadInstallation };

package/bin/native-version-validation.cjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+'use strict';
+
+try {
+  const { loadInstallation } = require('./lib/installation.cjs');
+  const { manifest } = loadInstallation();
+  console.log(`安装版本 ${manifest.version}，布局 ${manifest.layoutVersion}；${manifest.assets.length} 个登记文件均存在。`);
+} catch (error) { console.error(error.message); process.exitCode = 1; }

package/bin/wizard.cjs

@@ -44,7 +44,9 @@ async function confirm(plan) {
   for (const target of plan.targets) {
     console.log(`  ${target.agents.join(', ')}: ${target.skillsDirectory}`);
     if (target.commandsDirectory) console.log(`  命令：${target.commandsDirectory}`);
-    console.log(`  完整配套（evals、hooks、scripts）：${target.supportDirectory}`);
+    console.log(`  评测：${target.evalsDirectory}`);
+    console.log(`  脚本：${target.scriptsDirectory}`);
+    console.log(`  Hook：${target.hooksDirectory}`);
   }
   if (plan.conflicts.length) console.log(`将替换 ${plan.conflicts.length} 个已有内容；安装成功后清理旧文件，失败则恢复。`);
   if (plan.reused.length) console.log(`将复用同版本的 ${plan.reused.length} 个未修改内容。`);

package/docs/codebuddy-setup.md

@@ -11,7 +11,8 @@ npx @givolt/i3-composer-agent --codebuddy
 向导预选 CodeBuddy，可增加其他工具，再选择项目或全局范围。
 项目安装提供 `.codebuddy/skills/`（25 个技能）、`references/`、
 `commands/`（9 个命令）和 `agents/`（4 个角色）。
-同级 `i3-composer-agent/` 默认提供完整的 `evals/`、`hooks/`、`scripts/` 和依赖资料。
+同级 `evals/`、`hooks/`、`scripts/`、`docs/`、`references/` 各自通过 `i3-composer-agent/` 分组资料，
+只有一份实际技能、命令和角色，评测与宿主共用。
 全局使用 `~/.codebuddy/` 的相同结构。默认中文说明和回复；技能/命令标识不改名。
 安装成功清理旧内容，失败恢复；设置与自定义命令保留。
 
@@ -40,8 +41,8 @@ CodeBuddy 与 WorkBuddy 项目共用 `.codebuddy/`；同版本追加客户端会
 
 ## 配套检查
 
-进入 `.codebuddy/i3-composer-agent/`（全局安装使用对应全局路径）运行 `npm test`，
-可检查技能格式及中英文触发，不调用模型。行为评测、样例和脚本用法见
+在业务项目运行 `node .codebuddy/scripts/i3-composer-agent/run-evals.cjs --min-rank1 95`，
+可检查中英文触发，不调用模型；全局安装使用脚本的全局绝对路径。五项校验、行为评测和样例用法见
 [评测说明](../evals/README.md)。Hook 文件已安装，需要按宿主协议单独启用。
 
 ## 通过 CodeBuddy Code 插件管理器安装

package/docs/codex-setup.md

@@ -6,10 +6,12 @@
 npx @givolt/i3-composer-agent --codex
 ```
 
-项目范围写入 `.agents/skills/`，全局写入 `~/.agents/skills/`，并安装同级 `references/`。
+项目范围写入 `.agents/skills/`，全局写入 `~/.agents/skills/`，并安装同级 `references/i3-composer-agent/`。
 提供全部 25 个 `i3-` 技能，中文选择说明与默认中文回复在每个入口独立生效。
-同级 `i3-composer-agent/` 默认提供完整评测、Hook、脚本及依赖资料。
-进入该配套目录执行 `npm test` 可进行结构和中英文触发检查，不调用模型；详见
+同级 `evals/`、`hooks/`、`scripts/`、`docs/` 各自以 `i3-composer-agent/` 分组资料。
+命令与角色文件也会提供，供按需阅读，其自动发现由宿主决定。
+从项目目录执行 `node .agents/scripts/i3-composer-agent/run-evals.cjs --min-rank1 95`
+检查实际安装技能的中英文触发，不调用模型；五项结构校验详见
 [评测说明](../evals/README.md)。原生调用使用技能 ID，Hook 文件需按宿主能力单独启用。
 
 ## 通过插件管理器安装

package/docs/workbuddy-setup.md

@@ -13,9 +13,11 @@ npx @givolt/i3-composer-agent --agents codebuddy,workbuddy --scope global --yes
 - `~/.workbuddy/skills/`：25 个 `i3-` 技能，选择说明和默认回复中文。
 - `~/.workbuddy/commands/`：9 个 `/i3-*` 短命令。
 - `~/.workbuddy/agents/`：4 个专业角色。
-- `~/.workbuddy/references/`：共享参考和标准 MIT 许可。
-- `~/.workbuddy/docs/agents.md`：角色说明。
-- `~/.workbuddy/i3-composer-agent/`：完整评测、Hook、脚本及依赖资料。
+- `~/.workbuddy/references/i3-composer-agent/`：共享参考。
+- `~/.workbuddy/docs/i3-composer-agent/agents.md`：角色说明。
+- `~/.workbuddy/evals/i3-composer-agent/`：中英文用例、样例与评测结果。
+- `~/.workbuddy/hooks/i3-composer-agent/`：Hook 文件与说明。
+- `~/.workbuddy/scripts/i3-composer-agent/`：评测、校验与依赖库。
 - `~/.workbuddy/.i3-composer-agent.json`：安装内容所有权及客户端清单。
 
 自定义 profile 可设置 `WORKBUDDY_CONFIG_DIR`，安装后打开对应 profile。
@@ -23,8 +25,8 @@ WorkBuddy 的目录选择使用自己的配置，不借用 `CODEBUDDY_CONFIG_DIR
 
 ## 配套检查
 
-进入 `~/.workbuddy/i3-composer-agent/` 运行 `npm test`，检查技能格式及中英文触发，
-不会调用模型。项目安装对应 `.codebuddy/i3-composer-agent/`。行为评测用例、样例和
+运行 `node ~/.workbuddy/scripts/i3-composer-agent/run-evals.cjs --min-rank1 95`，检查实际安装技能的中英文触发，
+不会调用模型。项目安装将 `~/.workbuddy/` 换成 `.codebuddy/`。五项校验、行为评测用例、样例和
 脚本用法见 [评测说明](../evals/README.md)。Hook 文件默认提供，启用需适配宿主事件协议。
 
 ## 发现和调用
@@ -72,7 +74,7 @@ npx @givolt/i3-composer-agent --workbuddy --scope global --dry-run
 npx @givolt/i3-composer-agent --workbuddy --scope global --yes --force
 ```
 
-升级、修改内容和未登记同名冲突需要确认；成功替换后清理旧文件与所属历史备份，失败恢复。
+升级和已登记文件修改需确认；未归属的资料冲突或不同内容的同名评测结果需要先处理；成功替换后清理旧文件与所属历史备份，失败恢复。
 原生安装同时提供 Skills、Commands、Agents 和完整 evals/hooks/scripts 配套。
 `--prepare --workbuddy` 不支持，原生安装不会启用插件 Hook。
 

package/evals/README.md

@@ -6,32 +6,39 @@
 
 ## 运行位置
 
-原生安装的完整配套目录是宿主目录下的 `i3-composer-agent/`。
-例如 CodeBuddy 项目安装为 `.codebuddy/i3-composer-agent/`，
-WorkBuddy 全局安装为 `~/.workbuddy/i3-composer-agent/`。
-先进入该目录；若使用 `--prepare` / `--extract`，进入指定的导出目录。
-配套目录保留技能、命令、角色、参考资料和插件清单，保证校验及 Hook 的相对路径可解析。
-宿主实际使用的原生入口仍位于它自己的 `skills/`、`commands/`、`agents/`。
+原生安装的技能位于宿主基址的 `skills/`；评测资料位于 `evals/i3-composer-agent/`，
+脚本位于 `scripts/i3-composer-agent/`。安装清单记录预期技能和文件，评测只读取这份实际安装内容。
+例如 CodeBuddy 项目基址是 `.codebuddy/`，WorkBuddy 全局基址是 `~/.workbuddy/`。
+下面原生示例从业务项目根目录运行；从其他位置运行时，将脚本路径换成绝对路径即可。
+Node.js 20 或以上，无需额外 npm 依赖；`.cjs` 入口兼容业务项目的 ESM/CommonJS 设置。
 
 ## 不调用模型的检查
 
-需要 Node.js 20 或以上，无需额外 npm 依赖。
-
 ```bash
-# 技能格式、清单版本、三种命令格式一致性、引用与产物路径
-npm run validate
+node .codebuddy/scripts/i3-composer-agent/validate-skills.cjs
+node .codebuddy/scripts/i3-composer-agent/validate-versions.cjs
+node .codebuddy/scripts/i3-composer-agent/validate-commands.cjs
+node .codebuddy/scripts/i3-composer-agent/validate-reference-links.cjs
+node .codebuddy/scripts/i3-composer-agent/validate-artifact-paths.cjs
+node .codebuddy/scripts/i3-composer-agent/run-evals.cjs --locale zh-CN --min-rank1 95
+node .codebuddy/scripts/i3-composer-agent/run-evals.cjs --locale en --min-rank1 95
+```
 
-# 中英文分别检查；省略 --locale 时检查两种语言
-node scripts/run-evals.js --locale zh-CN --min-rank1 95
-node scripts/run-evals.js --locale en --min-rank1 95
+五项校验分别检查技能格式、安装版本及登记文件、实际命令和角色格式、引用锚点、规格/计划产物路径。
+缺少安装清单、已登记技能或必需资源会报错；其他插件和用户新增技能不进入本包的评测目录项。
+`cases/` 保留英文用例，`zh-CN/cases/` 提供中文用例，`fixtures/` 是行为评测的真实输入，
+`plugin/` 保留插件评测提示与评分标准。`skill-impact.md` 记录因评测未通过而放弃的技能改动。
 
-# 一次运行结构检查和中英文触发评测
+若使用 `--prepare` / `--extract` 的独立插件，进入导出目录运行原有入口：
+
+```bash
 npm test
+npm run validate
+node scripts/run-evals.js --locale zh-CN --min-rank1 95
 ```
 
-`scripts/` 包含 `run-evals.js`、五个 `validate-*.js` 和它们依赖的 `lib/skill-lint.js`。
-`evals/cases/` 保留英文用例，`evals/zh-CN/cases/` 提供中文用例，
-`evals/fixtures/` 是执行型评测使用的测试项目样例，`evals/plugin/` 是插件级评测用例。
+独立插件的校验还会检查插件清单和三种命令格式的一致性。原生安装不复制这些注册清单，
+不需要在业务项目或宿主基址执行 `npm test`。
 
 触发评测使用词法评分检查正例、负例、描述冲突、用例结构及样例是否齐全。
 中英文各自满足指定门槛；这不能证明模型在实际宿主中一定选择正确技能。
@@ -42,13 +49,13 @@ npm test
 先预览，不调用模型、不生成评测结果：
 
 ```bash
-node scripts/run-evals.js --behavioral i3-test-driven-development --locale zh-CN --dry-run
+node .codebuddy/scripts/i3-composer-agent/run-evals.cjs --behavioral i3-test-driven-development --locale zh-CN --dry-run
 ```
 
 确认需要后，移除 `--dry-run` 才会调用已登录的 Claude Code，并消耗该账户的模型额度：
 
 ```bash
-node scripts/run-evals.js --behavioral i3-test-driven-development --locale zh-CN
+node .codebuddy/scripts/i3-composer-agent/run-evals.cjs --behavioral i3-test-driven-development --locale zh-CN
 ```
 
 执行型用例需要 Git，并在临时 Git 项目中复制 `fixtures/` 的真实输入；
@@ -59,13 +66,15 @@ node scripts/run-evals.js --behavioral i3-test-driven-development --locale zh-CN
 
 `--locale en` 运行英文用例，省略该参数运行两种语言。可通过 `I3_EVAL_MODEL`
 和 `I3_EVAL_GRADER_MODEL` 指定执行/评分模型；报告同时记录宿主和模型信息。
-结果写入 `evals/results/`，不会进入发行包，也不属于安装器的替换清单。
+原生结果写入 `evals/i3-composer-agent/results/`；独立插件写入 `evals/results/`。
+结果不会进入发行包和文件替换清单，升级保留；旧配套目录的结果会迁入新位置，同名异内容时停止迁移。
 
 ## 插件级评测
 
 插件清单中的 `experimental.evals` 指向随包提供的 `evals/plugin/`。
+原生安装也保留这些用例作为资料；要运行依赖插件清单的命令，需要独立插件导出。
 它包含整体插件的触发/不触发提示和评分规则；支持 `plugin eval` 的 Claude Code
-可从配套目录主动运行：
+可从 `--prepare` / `--extract` 的独立插件导出目录主动运行：
 
 ```bash
 claude plugin eval . --no-publish
@@ -77,7 +86,7 @@ claude plugin eval . --no-publish
 
 ## Hooks
 
-`hooks/` 默认交付会话注入、文档缓存、代码块保护脚本及说明。
+原生的 `hooks/i3-composer-agent/`（独立插件为 `hooks/`）默认交付会话注入、文档缓存、代码块保护脚本及说明。
 安装文件不会自动注册事件。中文回复与普通技能调用不依赖启用 Hook。
 会话注入仅适用于缺少原生技能路由的宿主；已有路由时不要重复注入。
 缓存及保护的当前配置示例针对 Claude Code，详见

package/evals/skill-impact.md

@@ -0,0 +1,6 @@
+# Rejected Skill Changes
+
+This append-only ledger records skill and description changes rejected on eval evidence so contributors can review prior attempts before proposing overlapping work. Add one concise row per rejected proposal; do not record accepted changes here.
+
+| Date | Affected skill | Attempted change | Rank-1 score (before → after) | Rejected PR and outcome |
+|---|---|---|---:|---|

package/package.json

@@ -113,6 +113,7 @@
     "evals/plugin/code-review-stays-quiet/graders/not-fired.md",
     "evals/plugin/code-review-stays-quiet/graders/tdd-fired.md",
     "evals/plugin/code-review-stays-quiet/prompt.md",
+    "evals/skill-impact.md",
     "evals/zh-CN/cases/i3-api-and-interface-design.json",
     "evals/zh-CN/cases/i3-browser-testing-with-devtools.json",
     "evals/zh-CN/cases/i3-ci-cd-and-automation.json",
@@ -274,6 +275,7 @@
       "evals/plugin/code-review-stays-quiet/graders/not-fired.md",
       "evals/plugin/code-review-stays-quiet/graders/tdd-fired.md",
       "evals/plugin/code-review-stays-quiet/prompt.md",
+      "evals/skill-impact.md",
       "evals/zh-CN/cases/i3-api-and-interface-design.json",
       "evals/zh-CN/cases/i3-browser-testing-with-devtools.json",
       "evals/zh-CN/cases/i3-ci-cd-and-automation.json",
@@ -327,7 +329,7 @@
       "LICENSE"
     ]
   },
-  "version": "2.2.1",
+  "version": "2.2.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/49780522/i3-composer-agent.git"

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "i3-composer-agent",
-  "version": "2.2.1",
+  "version": "2.2.2",
   "description": "覆盖需求、计划、开发、测试、审查与发布的软件工程技能，默认使用简体中文。",
   "homepage": "https://github.com/49780522/i3-composer-agent",
   "repository": "https://github.com/49780522/i3-composer-agent"