@givolt/i3-composer-agent 2.2.2 → 2.2.3

package/.agents/plugins/marketplace.json

@@ -6,7 +6,7 @@
   "plugins": [
     {
       "name": "i3-composer-agent",
-      "version": "2.2.2",
+      "version": "2.2.3",
       "description": "覆盖需求、计划、开发、测试、审查与发布的软件工程技能，默认使用简体中文。",
       "source": {
         "source": "local",

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/.codex-plugin/plugin.json

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

package/README.md

@@ -1,4 +1,4 @@
-# i3 Composer Agent v2.2.2
+# i3 Composer Agent v2.2.3
 
 **Intelligence. Integration. Innovation.**
 
@@ -54,7 +54,7 @@ CodeBuddy 和 WorkBuddy 的项目安装共用 `.codebuddy/`，相同目标只安
 同版本、同范围的清单所属未修改内容会复用，新增客户端合并到清单。
 升级、修改过的内容及未登记同名冲突需确认替换；非交互使用 `--force` 前可先看 dry-run。
 安装成功后清理替换掉的旧内容及本安装器所属历史备份，失败则恢复原文件。
-升级按文件归属清理旧副本，保留用户新增文件；旧评测结果迁入新的 evals 分组。
+升级按文件归属清理旧副本，保留用户新增文件；2.2.2 的分散配套资料迁入工具根；2.2.1 的评测结果保留原位。
 同名结果内容不同时会在写入前停止；未归属本包的资料冲突也需先处理，`--force` 不会接管。
 成功后不保留临时备份。`npx -y` 确认 npm 下载；包的 `--yes` 确认安装计划。
 
@@ -63,11 +63,11 @@ CodeBuddy 和 WorkBuddy 的项目安装共用 `.codebuddy/`，相同目标只安
 | 内容 | 默认安装 | 用途 |
 | --- | --- | --- |
 | `skills/`（含技能内部的 `scripts/` 等资源） | 是 | 工程工作流及运行辅助文件 |
-| `references/i3-composer-agent/` | 是 | 技能引用的检查清单与参考资料 |
+| `i3-composer-agent/references/` | 是 | 技能引用的检查清单与参考资料 |
 | `commands/`、`agents/` | 是；发现与调用依宿主支持 | 短命令与专业角色提示 |
-| `hooks/` | 是，文件安装后按宿主方式启用 | 会话注入、文档缓存和代码块保护 |
-| `scripts/` | 是 | 评测运行器、五项校验脚本及其共享库 |
-| `evals/` | 是 | 中英文触发/行为用例、测试项目样例及插件评分规则 |
+| `i3-composer-agent/hooks/` | 是，文件安装后按宿主方式启用 | 会话注入、文档缓存和代码块保护 |
+| `i3-composer-agent/scripts/` | 是 | 评测运行器、五项校验、全部原版脚本回归测试及共享库 |
+| `i3-composer-agent/evals/` | 是 | 中英文触发/行为用例、测试项目样例及插件评分规则 |
 
 以项目安装的 `.codebuddy/` 为例，默认目录为：
 
@@ -76,42 +76,49 @@ CodeBuddy 和 WorkBuddy 的项目安装共用 `.codebuddy/`，相同目标只安
 ├─ skills/                         # 宿主和评测共用的实际技能
 ├─ commands/                       # 一份命令
 ├─ agents/                         # 一份角色提示
-├─ references/i3-composer-agent/
-├─ evals/i3-composer-agent/         # 用例、样例、插件评测与运行结果
-├─ hooks/i3-composer-agent/
-├─ scripts/i3-composer-agent/       # .cjs 入口及 lib/
-├─ docs/i3-composer-agent/
+├─ i3-composer-agent/               # 配套工具根，不是第二份插件
+│  ├─ package.json                 # 独立 CommonJS 配置，提供 npm test
+│  ├─ README.md
+│  ├─ scripts/                     # 全部脚本、原有回归测试及 lib/
+│  ├─ evals/                       # 中英文用例、样例、插件评测及结果
+│  ├─ hooks/
+│  ├─ references/
+│  ├─ docs/
+│  └─ adapters/                    # 其他命令格式和插件清单的校验输入
 └─ .i3-composer-agent.json          # 版本、布局、能力与文件归属清单
 ```
 
-每个宿主基址只有一份技能；公共资料按插件名称分组。技能内部的 scripts/references 保留。
+每个宿主基址只有一份技能；公共资料集中在配套工具根目录。技能内部的 scripts/references 保留。
 WorkBuddy 全局安装将基址换为 `~/.workbuddy/`，Codex 项目安装为 `.agents/`。
 评测、校验和适用的 Hook 读取宿主使用的实际内容，不生成第二份完整插件。
 
-从业务项目目录运行以下检查，不调用模型；也可用脚本绝对路径从任意目录运行：
+进入配套目录后运行以下命令，不调用模型：
 
 ```bash
-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
+cd .codebuddy/i3-composer-agent
+npm test
+node scripts/run-evals.js --locale zh-CN --min-rank1 95
 ```
 
+`npm test` 执行五项校验、中英文确定性评测和全部原版脚本回归测试。
+原版英文案例完整保留，中文案例作为增量，两种语言分别通过门槛。
+脚本也可使用绝对路径从任意目录运行；无需 `npm install`。
+
 模型行为评测需要主动运行并消耗模型额度，详见 [评测说明](evals/README.md)。
 原生脚本按安装清单检查本包内容，支持业务项目的 ESM/CommonJS 设置。
-独立插件导出目录仍可执行 `npm test`；上述检查均不能代替业务项目测试或宿主执行验收。
+配套根与独立插件导出目录均可执行 `npm test`；这些检查均不能代替业务项目测试或宿主执行验收。
 评测结果不进入安装替换清单。安装过程不执行评测，也不自动启用 Hook。
 
 可选 Hook 不影响普通技能和命令的使用，默认中文交互也不依赖 Hook。
 未配置 Hook 时，自动注入、缓存和代码块保护这些增强功能不会运行。
 会话注入仅适合缺少原生技能路由的宿主；已有原生路由时不应重复注入元技能。
-缓存与代码块保护的配置说明位于 `hooks/i3-composer-agent/` 下的 `SDD-CACHE.md`、
+缓存与代码块保护的配置说明位于 `i3-composer-agent/hooks/` 下的 `SDD-CACHE.md`、
 `SIMPLIFY-IGNORE.md`，当前示例针对 Claude Code，其他宿主需适配自己的事件协议。
 脚本依赖 Bash、jq；缓存还需 curl 和哈希工具，代码块保护还需其文档列出的工具。
 Windows PowerShell 本身不会自动提供这些脚本依赖。
 
+`i3-composer-agent/adapters/` 中的其他命令格式与插件清单用于完整回归校验，不自动注册插件。
+
 ## 通过宿主插件管理器安装
 
 默认配套已包含 Skills、Commands、Agents、references、evals、hooks 和 scripts。

package/bin/i3-composer-agent.cjs

@@ -46,7 +46,7 @@ ${pkg.name}
 上下键移动/跨页，空格勾选/取消，回车确认；列表下实时显示已选，q/Esc 退出。
 CodeBuddy、WorkBuddy、Claude Code 同时安装短命令和 Agent 角色。
 其他工具通过 Skills 调用，短命令支持取决于宿主。
-所有工具默认安装单份 skills、commands、agents；资料按 references/evals/hooks/scripts/docs 分组。
+所有工具默认安装单份 skills、commands、agents；配套资料集中在 i3-composer-agent/。
 评测、脚本和 Hook 读取同一份已安装技能。--prepare 用于另行导出标准插件并按宿主方式注册。
 WorkBuddy 桌面版建议全局安装，便于技能列表和输入补全发现。
 评测需主动运行；Hook 文件已提供，需按宿主事件协议单独启用。
@@ -205,12 +205,13 @@ async function main() {
     if (target.nativeCommands) console.log(`命令：/i3-spec、/i3-plan、/i3-build、/i3-ship（共 ${target.catalog.commands.length} 个工作流）：${target.commandsDirectory}`);
     else console.log(`命令和角色资料已提供；是否自动发现取决于宿主：${target.commandsDirectory}、${target.personasDirectory}`);
     console.log(`评测资料：${target.evalsDirectory}`);
-    console.log(`中文评测：node "${path.join(target.scriptsDirectory, 'run-evals.cjs')}" --locale zh-CN --min-rank1 95`);
+    console.log(`完整校验：进入 "${target.toolkitDirectory}" 后运行 npm test`);
+    console.log(`中文评测：node "${path.join(target.scriptsDirectory, 'run-evals.js')}" --locale zh-CN --min-rank1 95`);
     console.log(`Hook：${target.hooksDirectory}（尚未启用）`);
   }
-  for (const directory of plan.preserved || []) console.log(`旧目录中保留了用户文件：${directory}`);
+  for (const file of plan.preserved || []) console.log(`保留了用户文件：${file}`);
   console.log('请重新加载 IDE 窗口或新建宿主会话以发现安装内容。');
   if (plan.agents.some(id => !['codebuddy', 'workbuddy', 'claude-code'].includes(id))) console.log('这些工具通过技能 ID 调用；生命周期短命令支持取决于宿主。');
-  console.log('安装完成。评测说明见 evals/i3-composer-agent/README.md；Hook 需按宿主事件协议启用。');
+  console.log('安装完成。评测说明见 i3-composer-agent/evals/README.md；Hook 需按宿主事件协议启用。');
 }
 main().catch(error => { console.error(`${name}: ${error.message}`); process.exitCode = 1; });

package/bin/install.cjs

@@ -7,7 +7,7 @@ const crypto = require('node:crypto');
 const registry = require('./agent-targets.json');
 const { cleanupBackups } = require('./cleanup-backups.cjs');
 const { nativeAssets, renderAsset } = require('./native-layout.cjs');
-const { migrationAssets, pruneRetiredDirectories } = require('./native-migration.cjs');
+const { migrationAssets, pruneRetiredDirectories, ownsAsset } = require('./native-migration.cjs');
 const { fingerprint } = require('./asset-fingerprint.cjs');
 const root = path.resolve(__dirname, '..');
 const name = 'i3-composer-agent';
@@ -50,7 +50,7 @@ function checkDestination(file) {
 }
 function assetPath(base, file) { return path.relative(base, file).split(path.sep).join('/'); }
 function manifestContent(plan, asset) {
-  return JSON.stringify({ name, version, layoutVersion: 2, entryPrefix: 'i3-', scope: plan.scope, agents: asset.target.agents,
+  return JSON.stringify({ name, version, layoutVersion: 3, entryPrefix: 'i3-', scope: plan.scope, agents: asset.target.agents,
     capabilities: { nativeCommands: !!asset.target.nativeCommands, nativeAgents: !!asset.target.nativeCommands, hooks: 'manual' },
     catalog: asset.target.catalog, resources: asset.target.resources,
     assets: plan.assets.filter(item => item.base === asset.base && !['legacy', 'result'].includes(item.kind)).map(item => assetPath(asset.base, item.destination)) }, null, 2) + '\n';
@@ -64,10 +64,10 @@ function planInstallation({ agents, scope, projectDir = process.cwd(), home = os
     const agent = registry.agents.find(item => item.id === id);
     const skillsDirectory = destination(scope === 'project' ? path.resolve(projectDir, agent.projectSkillsDir) : globalSkillsDir(agent, home, env));
     const base = path.dirname(skillsDirectory);
-    if (!targets.has(skillsDirectory)) targets.set(skillsDirectory, { agents: [], skillsDirectory, referencesDirectory: path.join(base, 'references', name),
+    if (!targets.has(skillsDirectory)) targets.set(skillsDirectory, { agents: [], skillsDirectory, toolkitDirectory: path.join(base, name), referencesDirectory: path.join(base, name, 'references'),
       commandsDirectory: path.join(base, 'commands'), personasDirectory: path.join(base, 'agents'),
-      evalsDirectory: path.join(base, 'evals', name), scriptsDirectory: path.join(base, 'scripts', name),
-      hooksDirectory: path.join(base, 'hooks', name), docsDirectory: path.join(base, 'docs', name), base });
+      evalsDirectory: path.join(base, name, 'evals'), scriptsDirectory: path.join(base, name, 'scripts'),
+      hooksDirectory: path.join(base, name, 'hooks'), docsDirectory: path.join(base, name, 'docs'), base });
     const target = targets.get(skillsDirectory);
     target.agents.push(id);
     if (['codebuddy', 'workbuddy', 'claude-code'].includes(id)) {
@@ -83,7 +83,7 @@ function planInstallation({ agents, scope, projectDir = process.cwd(), home = os
     // Earlier Windows installs persisted backslashes. Normalize before lookup
     // and containment checks so owned upgrades work across both manifest forms.
     if (owned) previous.assets = previous.assets.map(relative => typeof relative === 'string' ? relative.replaceAll('\\', '/') : relative);
-    const sameVersion = owned && previous.layoutVersion === 2 && previous.version === version && previous.scope === scope && previous.entryPrefix === 'i3-';
+    const sameVersion = owned && previous.layoutVersion === 3 && previous.version === version && previous.scope === scope && previous.entryPrefix === 'i3-';
     if (owned && previous.scope === scope && Array.isArray(previous.agents)) {
       const applicable = previous.agents.filter(id => {
         const agent = registry.agents.find(item => item.id === id);
@@ -101,9 +101,8 @@ function planInstallation({ agents, scope, projectDir = process.cwd(), home = os
     for (const asset of additions) {
       // A new grouped resource must not take ownership of an unrelated file,
       // even when --force confirms replacement of a previous installation.
-      const previousOwned = owned && previous.assets.some(relative => relative === asset.relative
-        || (previous.layoutVersion !== 2 && asset.relative.startsWith(relative + '/')));
-      asset.protectedResource = /^(references|evals|hooks|scripts|docs)\//.test(asset.relative);
+      const previousOwned = owned && ownsAsset(previous, asset.relative);
+      asset.protectedResource = /^(references|evals|hooks|scripts|docs|i3-composer-agent)\//.test(asset.relative);
       if (exists(asset.destination) && !previousOwned && asset.protectedResource) {
         throw new Error(`未归属本包的同名资源，不能覆盖，请先处理：${asset.destination}`);
       }
@@ -201,7 +200,20 @@ function executeInstallation(plan, { force = false } = {}) {
     }
     pruneRetiredDirectories(plan.assets);
     completed = true;
-    plan.preserved = plan.targets.map(target => path.join(target.base, name)).filter(file => exists(file));
+    const ownedPaths = new Set(plan.assets.filter(asset => asset.kind !== 'legacy').map(asset => asset.destination));
+    plan.preserved = [];
+    function findUserFiles(directory) {
+      if (!exists(directory) || fs.lstatSync(directory).isSymbolicLink()) return;
+      for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        const file = path.join(directory, entry.name);
+        if (entry.isDirectory()) findUserFiles(file);
+        else if (!ownedPaths.has(file) && !file.split(path.sep).includes('results')) plan.preserved.push(file);
+      }
+    }
+    for (const target of plan.targets) {
+      findUserFiles(path.join(target.base, name));
+      for (const category of ['references', 'evals', 'hooks', 'scripts', 'docs']) findUserFiles(path.join(target.base, category, name));
+    }
     return [];
   } catch (error) {
     for (const change of committed.reverse()) {

package/bin/native-command-validation.cjs

@@ -1,27 +1,22 @@
-#!/usr/bin/env node
 'use strict';
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { loadInstallation } = require('./lib/installation.cjs');
-const { frontmatterYamlErrors } = require('./lib/skill-lint.cjs');
+const { frontmatterYamlErrors } = require('./skill-lint.js');
 
-try {
-  const { root, catalog } = loadInstallation();
+function validateAgents({ root, catalog }) {
   let errors = 0;
-  for (const category of ['commands', 'agents']) {
-    for (const name of catalog[category]) {
-      const relative = `${category}/${name}.md`;
+    for (const name of catalog.agents) {
+      const relative = `agents/${name}.md`;
       const text = fs.readFileSync(path.join(root, relative), 'utf8');
       const issues = frontmatterYamlErrors(text);
       const frontmatter = text.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/)?.[1] || '';
       if (!/^description:\s*\S/m.test(frontmatter)) issues.push('缺少 description');
-      if (category === 'agents' && !new RegExp(`^name:\\s*["']?${name}["']?\\s*$`, 'm').test(frontmatter)) issues.push('角色 name 与文件名不一致');
+      if (!new RegExp(`^name:\\s*["']?${name}["']?\\s*$`, 'm').test(frontmatter)) issues.push('角色 name 与文件名不一致');
       if (!text.replace(/^---[\s\S]*?\n---/, '').trim()) issues.push('缺少提示正文');
       console.log(`${issues.length ? '✗' : '✓'} ${relative}`);
       for (const issue of issues) { console.error(`  ${issue}`); errors++; }
     }
-  }
-  console.log(`已检查 ${catalog.commands.length} 个命令、${catalog.agents.length} 个角色；${errors} 个错误。`);
-  process.exitCode = errors ? 1 : 0;
-} catch (error) { console.error(error.message); process.exitCode = 1; }
+  return errors;
+}
+module.exports = { validateAgents };

package/bin/native-layout.cjs

@@ -11,34 +11,52 @@ function replaceOnce(text, before, after, label) {
 }
 
 function nativeScript(text, relative) {
-  const setup = "const INSTALLATION = require('./lib/installation.cjs').loadInstallation();";
-  text = text.replaceAll("require('./lib/skill-lint')", "require('./lib/skill-lint.cjs')");
-  if (relative === 'scripts/lib/skill-lint.js') return text;
+  // Copied upstream test fixtures keep their original repository paths; the
+  // real installed runners always require the installation manifest.
+  const setup = "const INSTALLATION = (require('node:fs').existsSync(require('node:path').join(__dirname, 'lib', 'installation.js')) || require('node:path').basename(require('node:path').resolve(__dirname, '..')) === 'i3-composer-agent') ? require('./lib/installation.js').loadInstallation() : null;";
+  if (relative.startsWith('scripts/lib/') || relative === 'scripts/run-regressions.js') return text;
+  if (relative === 'scripts/validate-versions.js' || relative === 'scripts/validate-versions-test.js') {
+    return replaceOnce(text, 'const manifestPaths = [', setup + "\nconst MANIFEST_ROOT = INSTALLATION ? INSTALLATION.resources.adapters : require('node:path').resolve(__dirname, '..');\nconst manifestPaths = [", relative)
+      .replace('readFileSync(manifestPath, "utf8")', 'readFileSync(require("node:path").join(INSTALLATION && manifestPath === "package.json" ? INSTALLATION.toolkitRoot : MANIFEST_ROOT, manifestPath), "utf8")')
+      .replace('const expectedVersion = readManifestVersion("plugin.json");', 'const expectedVersion = readManifestVersion("plugin.json");\nif (INSTALLATION && expectedVersion !== INSTALLATION.manifest.version) throw new Error("插件版本与实际安装版本不一致");');
+  }
+  if (relative === 'scripts/floor-guard-reference-test.js') {
+    return replaceOnce(text, 'const REFERENCE = path.join(', setup + '\nconst REFERENCE = path.join(', relative)
+      .replace("__dirname, '..', 'skills',", "(INSTALLATION ? INSTALLATION.root : path.resolve(__dirname, '..')), 'skills',");
+  }
+  if (/-test\.js$/.test(relative)) return text;
   if (relative === 'scripts/validate-skills.js') {
-    text = replaceOnce(text, "const SKILLS_DIR = path.resolve(__dirname, '..', 'skills');", `${setup}\nconst SKILLS_DIR = INSTALLATION.skillsDirectory;`, relative);
-    return replaceOnce(text, 'fs.readdirSync(SKILLS_DIR)', 'INSTALLATION.catalog.skills', relative);
+    text = replaceOnce(text, "const SKILLS_DIR = path.resolve(__dirname, '..', 'skills');", setup + "\nconst SKILLS_DIR = INSTALLATION ? INSTALLATION.skillsDirectory : path.resolve(__dirname, '..', 'skills');", relative);
+    return replaceOnce(text, 'fs.readdirSync(SKILLS_DIR)', '(INSTALLATION ? INSTALLATION.catalog.skills : fs.readdirSync(SKILLS_DIR))', relative);
   }
   const rootDeclaration = relative === 'scripts/run-evals.js'
     ? "const ROOT = path.join(__dirname, '..');" : "const ROOT = path.resolve(__dirname, '..');";
-  text = replaceOnce(text, rootDeclaration, `${setup}\nconst ROOT = INSTALLATION.root;`, relative);
+  text = replaceOnce(text, rootDeclaration, setup + "\nconst ROOT = INSTALLATION ? INSTALLATION.root : path.resolve(__dirname, '..');", relative);
   if (relative === 'scripts/run-evals.js') {
-    text = text.replaceAll("path.join(ROOT, 'evals',", "path.join(INSTALLATION.resources.evals,")
-      .replaceAll("path.join(ROOT, 'evals/zh-CN/cases')", "path.join(INSTALLATION.resources.evals, 'zh-CN/cases')");
-    return replaceOnce(text, 'fs.readdirSync(SKILLS_DIR)', 'INSTALLATION.catalog.skills', relative);
+    text = text.replaceAll("path.join(ROOT, 'evals',", "path.join(INSTALLATION ? INSTALLATION.resources.evals : path.join(ROOT, 'evals'),")
+      .replaceAll("path.join(ROOT, 'evals/zh-CN/cases')", "path.join(INSTALLATION ? INSTALLATION.resources.evals : path.join(ROOT, 'evals'), 'zh-CN/cases')");
+    return replaceOnce(text, 'fs.readdirSync(SKILLS_DIR)', '(INSTALLATION ? INSTALLATION.catalog.skills : fs.readdirSync(SKILLS_DIR))', relative);
   }
   if (relative === 'scripts/validate-reference-links.js') {
-    text = replaceOnce(text, 'fs.readdirSync(SKILLS_DIR)', 'INSTALLATION.catalog.skills', relative);
-    return replaceOnce(text, 'references\\/[A-Za-z0-9._-]+\\.md', 'references\\/(?:[A-Za-z0-9._-]+\\/)*[A-Za-z0-9._-]+\\.md', relative);
+    text = replaceOnce(text, 'fs.readdirSync(SKILLS_DIR)', '(INSTALLATION ? INSTALLATION.catalog.skills : fs.readdirSync(SKILLS_DIR))', relative);
+    return replaceOnce(text, 'references\\/[A-Za-z0-9._-]+\\.md', '(?:i3-composer-agent\\/)?references\\/(?:[A-Za-z0-9._-]+\\/)*[A-Za-z0-9._-]+\\.md', relative);
+  }
+  if (relative === 'scripts/validate-commands.js') {
+    text = replaceOnce(text, "path.join(ROOT, '.claude', 'commands')", "path.join(ROOT, INSTALLATION ? 'commands' : '.claude/commands')", relative);
+    text = replaceOnce(text, "path.join(ROOT, '.gemini', 'commands')", "path.join(INSTALLATION ? INSTALLATION.resources.adapters : ROOT, '.gemini', 'commands')", relative);
+    text = replaceOnce(text, "path.join(ROOT, 'commands')", "path.join(INSTALLATION ? INSTALLATION.resources.adapters : ROOT, 'commands')", relative);
+    text = replaceOnce(text, 'fs.readdirSync(dir)', "(INSTALLATION ? (ext === '.md' ? INSTALLATION.catalog.commands.map(name => name + '.md') : fs.readdirSync(dir).filter(file => INSTALLATION.catalog.commands.includes(NAME_MAP_REVERSE[path.basename(file, ext)] ?? path.basename(file, ext)))) : fs.readdirSync(dir))", relative);
+    return replaceOnce(text, '  let errors = 0;', "  let errors = INSTALLATION ? require('./lib/validate-agents.js').validateAgents(INSTALLATION) : 0;", relative);
   }
   if (relative === 'scripts/validate-artifact-paths.js') {
     const guarded = text.match(/const GUARDED_FILES = \[[\s\S]*?\n\];/)?.[0];
     if (!guarded) throw new Error(`缺少原生产物检查配置：${relative}`);
-    return text.replace(guarded, `const GUARDED_FILES = [
-  ...INSTALLATION.catalog.commands.map(name => 'commands/' + name + '.md'),
-  'skills/i3-spec-driven-development/SKILL.md',
-  'skills/i3-planning-and-task-breakdown/SKILL.md',
-  ...INSTALLATION.manifest.assets.filter(file => /^docs\\/i3-composer-agent\\/(getting-started|adoption-guide|copilot-setup)\\.md$/.test(file)),
-];`);
+    text = text.replace(guarded, 'const GUARDED_FILES = INSTALLATION ? [\n' +
+      "  ...INSTALLATION.catalog.commands.map(name => 'commands/' + name + '.md'),\n" +
+      "  'skills/i3-spec-driven-development/SKILL.md', 'skills/i3-planning-and-task-breakdown/SKILL.md',\n" +
+      "  ...INSTALLATION.manifest.assets.filter(file => /^(?:i3-composer-agent\\/docs\\/(getting-started|adoption-guide|copilot-setup)\\.md|i3-composer-agent\\/adapters\\/(?:\\.gemini\\/commands|commands)\\/i3-(spec|planning|build)\\.toml)$/.test(file)),\n" +
+      '] : ' + guarded.slice('const GUARDED_FILES = '.length));
+    return text.replace(/^GUARDED_FILES\.push\(.*\);$/m, "if (!INSTALLATION) $&");
   }
   throw new Error(`尚未适配的公共脚本：${relative}`);
 }
@@ -47,6 +65,18 @@ function renderAsset(buffer, asset) {
   const relative = asset.sourceRelative || '';
   if (relative.startsWith('evals/fixtures/')) return buffer;
   let text = buffer.toString('utf8');
+  if (asset.kind === 'toolkit-package') {
+    const pkg = JSON.parse(text);
+    return Buffer.from(JSON.stringify({ name: pkg.name, version: pkg.version, private: true,
+      type: 'commonjs', engines: pkg.engines, scripts: Object.fromEntries(
+        Object.entries(pkg.scripts).filter(([key]) => ['test', 'validate', 'eval', 'test:regression'].includes(key))) }, null, 2) + '\n');
+  }
+  if (asset.kind === 'toolkit-readme') return Buffer.from(
+    '# i3 Composer Agent 配套工具\n\n' +
+    '本目录提供评测、校验、回归测试、Hook、共享参考资料和使用指南。技能、命令和 Agent 位于上一级的对应目录，只有一份；这里的评测读取宿主实际安装的内容。\n\n' +
+    '进入本目录后运行：\n\n```bash\nnpm test\nnode scripts/run-evals.js --locale zh-CN --min-rank1 95\n```\n\n' +
+    '`npm test` 执行内容校验、中英文确定性评测及全部脚本回归测试，不需要 npm install。模型行为评测需要另行配置执行宿主；详见 [evals/README.md](evals/README.md)。\n\n' +
+    '`adapters/` 保留其他命令格式和插件清单，供原版一致性校验与回归测试使用，不自动注册或启用插件。Hook 需按宿主支持的事件单独启用；缓存与代码块保护分别详见 [hooks/SDD-CACHE.md](hooks/SDD-CACHE.md) 和 [hooks/SIMPLIFY-IGNORE.md](hooks/SIMPLIFY-IGNORE.md)。\n');
   if (asset.kind === 'runtime') return Buffer.from(text.replace('__I3_INSTALL_VERSION__', asset.version));
   if (asset.kind === 'script') return Buffer.from(nativeScript(text, relative));
   if (relative === 'hooks/session-start.sh') {
@@ -71,7 +101,7 @@ function renderAsset(buffer, asset) {
     });
   }
   // Shared references move; skill-local references and executable assets stay.
-  text = text.replace(/((?:\.\.\/){2,})references\/(?!i3-composer-agent\/)/g, `$1references/${name}/`);
+  text = text.replace(/((?:\.\.\/){2,})references\//g, '$1' + name + '/references/');
   // Resolve actual Markdown links through the same source-to-destination map.
   text = text.replace(/(\]\()([^\s)#]+)(#[^\s)]+)?(\))/g, (match, open, link, fragment = '', close) => {
     if (/^(?:[a-z]+:|\/)/i.test(link)) return match;
@@ -81,9 +111,9 @@ function renderAsset(buffer, asset) {
     return open + path.posix.relative(path.posix.dirname(asset.relative), mapped) + fragment + close;
   });
   if (asset.kind === 'command' || asset.kind === 'persona') {
-    text = text.replaceAll('docs/agents.md', `docs/${name}/agents.md`);
+    text = text.replaceAll('docs/agents.md', name + '/docs/agents.md');
   }
-  if (relative.startsWith('hooks/')) text = text.replace(/\bhooks\/(?!i3-composer-agent\/)/g, `hooks/${name}/`);
+  if (relative.startsWith('hooks/')) text = text.replace(/\bhooks\//g, name + '/hooks/');
   return Buffer.from(text);
 }
 
@@ -110,24 +140,28 @@ function nativeAssets(root, target, packageFiles, version) {
   visit('skills', 'skills', 'skill');
   visit('.claude/commands', 'commands', 'command');
   visit('agents', 'agents', 'persona');
-  visit('references', `references/${name}`, 'reference');
-  visit('README.md', `docs/${name}/README.md`, 'docs');
+  visit('references', name + '/references', 'reference');
+  visit('README.md', name + '/docs/README.md', 'docs');
+  visit('README.md', name + '/README.md', 'toolkit-readme');
+  visit('package.json', name + '/package.json', 'toolkit-package');
   for (const file of packageFiles) {
     const category = file.split('/')[0];
     if (!['evals', 'hooks', 'scripts', 'docs'].includes(category)) continue;
-    if (file === 'scripts/validate-commands.js' || file === 'scripts/validate-versions.js') continue;
-    const relative = `${category}/${name}${file.slice(category.length)}`.replace(/\.js$/, category === 'scripts' ? '.cjs' : '.js');
+    const relative = name + '/' + file;
     visit(file, relative, category === 'scripts' ? 'script' : category);
   }
-  visit('bin/native-runtime.cjs', `scripts/${name}/lib/installation.cjs`, 'runtime');
-  visit('bin/native-command-validation.cjs', `scripts/${name}/validate-commands.cjs`, 'native-validator');
-  visit('bin/native-version-validation.cjs', `scripts/${name}/validate-versions.cjs`, 'native-validator');
+  visit('bin/native-runtime.cjs', name + '/scripts/lib/installation.js', 'runtime');
+  visit('bin/native-command-validation.cjs', name + '/scripts/lib/validate-agents.js', 'runtime');
+  for (const file of ['commands', '.gemini/commands', 'plugin.json', '.codex-plugin/plugin.json',
+    '.claude-plugin/plugin.json', '.claude-plugin/marketplace.json', '.agents/plugins/marketplace.json']) {
+    visit(file, name + '/adapters/' + file, 'adapter');
+  }
   target.catalog = {
     skills: fs.readdirSync(path.join(root, 'skills')).filter(id => fs.existsSync(path.join(root, 'skills', id, 'SKILL.md'))).sort(),
     commands: fs.readdirSync(path.join(root, '.claude/commands')).filter(file => file.endsWith('.md')).map(file => file.slice(0, -3)).sort(),
     agents: fs.readdirSync(path.join(root, 'agents')).filter(file => file.endsWith('.md')).map(file => file.slice(0, -3)).sort(),
   };
-  target.resources = Object.fromEntries(['references', 'evals', 'hooks', 'scripts', 'docs'].map(category => [category, `${category}/${name}`]));
+  target.resources = Object.fromEntries(['references', 'evals', 'hooks', 'scripts', 'docs', 'adapters'].map(category => [category, name + '/' + category]));
   for (const asset of assets) { asset.mapping = mapping; asset.base = target.base; }
   return assets;
 }

package/bin/native-migration.cjs

@@ -5,6 +5,12 @@ const path = require('node:path');
 const { fingerprint } = require('./asset-fingerprint.cjs');
 const inventory = require('./legacy-native-files.json').files;
 const name = 'i3-composer-agent';
+const publishedFiles = new Set(inventory);
+
+function ownsAsset(previous, relative) {
+  return previous.assets.some(file => file === relative
+    || (!(previous.layoutVersion >= 2) && publishedFiles.has(relative) && relative.startsWith(file + '/')));
+}
 
 function allowed(relative) {
   return typeof relative === 'string' && !relative.includes('\0') && !relative.includes(':') && !relative.includes('\\')
@@ -41,7 +47,7 @@ function migrationAssets(target, previous, current) {
     const file = fileAt(base, relative);
     if (!file) continue;
     if (fs.statSync(file).isFile()) oldFiles.add(relative);
-    else if (previous.layoutVersion !== 2) {
+    else if (!(previous.layoutVersion >= 2)) {
       // Old manifests registered directories, not their contents. Expand only
       // paths in the published inventory, never the current filesystem tree.
       for (const known of inventory) if (known.startsWith(relative + '/')) oldFiles.add(known);
@@ -51,8 +57,8 @@ function migrationAssets(target, previous, current) {
 
   // Evaluation output is user data, not an installed package asset. Move it
   // transactionally, including plugin and locale-specific result folders.
-  if (previous.assets.some(file => typeof file === 'string' && file.startsWith(`${name}/`))) {
-    const oldEvals = path.join(base, name, 'evals');
+  if (previous.layoutVersion === 2) {
+    const oldEvals = path.join(base, 'evals', name);
     function visit(directory, relative = '') {
       if (!fs.existsSync(directory)) return;
       for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
@@ -61,7 +67,7 @@ function migrationAssets(target, previous, current) {
         if (entry.isSymbolicLink()) continue;
         if (entry.isDirectory()) visit(source, subpath);
         else if (entry.isFile() && subpath.split('/').includes('results')) {
-          const destinationRelative = `evals/${name}/${subpath}`;
+          const destinationRelative = `${name}/evals/${subpath}`;
           const destination = path.join(base, destinationRelative);
           let reusable = false;
           if (fs.existsSync(destination)) {
@@ -70,11 +76,11 @@ function migrationAssets(target, previous, current) {
           }
           assets.push({ base, source, destination, relative: destinationRelative, kind: 'result', reusable,
             expectedFingerprint: fingerprint(source) });
-          retire(`${name}/evals/${subpath}`);
+          retire(`evals/${name}/${subpath}`);
         }
       }
     }
-    if (fileAt(base, `${name}/evals`)) visit(oldEvals);
+    if (fileAt(base, `evals/${name}`)) visit(oldEvals);
   }
   return assets;
 }
@@ -90,4 +96,4 @@ function pruneRetiredDirectories(assets) {
   }
 }
 
-module.exports = { migrationAssets, pruneRetiredDirectories };
+module.exports = { migrationAssets, pruneRetiredDirectories, ownsAsset };

package/bin/native-runtime.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-// Installed as scripts/i3-composer-agent/lib/installation.cjs. Resolve from
+// Installed as i3-composer-agent/scripts/lib/installation.js. 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');
@@ -27,7 +27,7 @@ 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
+  if (manifest.name !== 'i3-composer-agent' || manifest.layoutVersion !== 3
       || manifest.version !== EXPECTED_VERSION || !Array.isArray(manifest.assets) || !manifest.assets.length) {
     throw new Error(`安装清单的名称、布局或版本不匹配：${manifestPath}`);
   }
@@ -44,14 +44,19 @@ function loadInstallation() {
   }
   for (const relative of assets) resolveOwned(relative);
   const resources = {};
-  for (const category of ['references', 'evals', 'hooks', 'scripts', 'docs']) {
-    const relative = `${category}/i3-composer-agent`;
+  for (const category of ['references', 'evals', 'hooks', 'scripts', 'docs', 'adapters']) {
+    const relative = 'i3-composer-agent/' + category;
     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') };
+  const toolkitRoot = path.join(root, 'i3-composer-agent');
+  const pkg = JSON.parse(fs.readFileSync(path.join(toolkitRoot, 'package.json'), 'utf8'));
+  if (pkg.name !== '@givolt/i3-composer-agent' || pkg.type !== 'commonjs' || pkg.version !== EXPECTED_VERSION) {
+    throw new Error('配套 package.json 的名称、模块格式或版本与安装不一致');
+  }
+  return { root, toolkitRoot, manifest, catalog: manifest.catalog, resources, skillsDirectory: path.join(root, 'skills') };
 }
 
 module.exports = { loadInstallation };

package/docs/advanced-per-agent-configuration.md

@@ -0,0 +1,78 @@
+# Advanced per-agent configuration
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+Skills in this repository are intentionally portable. Every `SKILL.md` keeps its frontmatter limited to the fields the [Agent Skills specification](https://agentskills.io) defines, so the same file works across Claude Code, Cursor, Gemini CLI, Antigravity, and any other spec-conformant client.
+
+Several agents also support extra runtime controls: model routing, tool restrictions, turn limits, execution isolation. These controls are valuable, but they are vendor-specific and do not belong in the shared, portable frontmatter. This document explains which controls each agent supports, where they belong, and how to apply them as an opt-in without breaking portability.
+
+This is the canonical reference for per-agent configuration, and it supersedes the earlier approach of adding vendor fields to top-level `SKILL.md` frontmatter. Fields such as `kind`, `model`, `temperature`, `max_turns`, `tools`, and `context` must not appear at the top level of a skill. They belong under `metadata` or in a separate per-agent adapter file, as described below.
+
+## Principles
+
+1. **Keep `SKILL.md` portable.** The Agent Skills specification reserves top-level frontmatter for `name`, `description`, `license`, `compatibility`, `metadata`, and the experimental `allowed-tools`. Vendor or client-specific properties belong under `metadata`, not at the top level.
+2. **Unknown top-level fields are not guaranteed to be ignored.** Many parsers only read `name` and `description` and silently drop the rest, but a strict spec-conformant validator or client may flag or reject unrecognized top-level keys. Putting vendor fields under `metadata` keeps the file conformant everywhere.
+3. **Opt-in, not global.** Runtime controls should be something a user adds for their own agent and workflow, not a default baked into every skill in the repository.
+4. **Prefer generation over hand-editing.** Where a configuration is repetitive and mechanical, generate it from a single source of truth instead of maintaining copies by hand. See [Automating with scripts](#automating-with-scripts).
+
+## Where vendor fields belong
+
+| Field type | Example | Correct home |
+|---|---|---|
+| Spec fields | `name`, `description`, `license`, `compatibility` | Top-level frontmatter in `SKILL.md` |
+| Vendor metadata | model hints, routing tags | Under the `metadata` key in `SKILL.md` |
+| Runtime orchestration | subagent definitions, turn limits, tool allowlists | A separate per-agent adapter file (see each agent below) |
+
+## Claude Code
+
+Claude Code reads `name` and `description` for discovery. Custom commands and skills share the same frontmatter, so the `context` and `allowed-tools` fields below work in both `.claude/commands/*.md` and `.claude/skills/*/SKILL.md`.
+
+- **`context: fork`** runs a command or skill in an isolated subagent context instead of the active conversation. This gives context isolation, repeatable execution from a clean state, execution tokens spent in the fork rather than the main session, and a cleaner handoff where only the result surfaces back. An optional **`agent`** field selects which subagent type runs the fork (for example `agent: Plan`); it defaults to `general-purpose`.
+- **`allowed-tools`** pre-approves tools; it does not restrict them. Listed tools run without a permission prompt for the turn that invokes the command or skill, and the grant clears on your next message. Nothing is removed from the tool pool.
+- **`disallowed-tools`** is the field that actually restricts: it removes the listed tools from the available pool while the skill is active, which is what least-privilege needs for passive stages such as review or audit. The restriction also clears on your next message. Note it is a Claude Code field and not one of the specification's six, so it belongs in a local copy or an adapter file; in a published `SKILL.md` it fails packaging with an unexpected-key error.
+
+These are Claude Code conventions. Keep the shared, published `SKILL.md` limited to spec fields; apply these runtime controls in your own local command or skill copies instead.
+
+## Gemini CLI and Antigravity
+
+Gemini CLI and Antigravity discover skills the same way: they match `name` and `description`, then load the full skill on demand. Runtime orchestration lives in a separate resource, not in the skill frontmatter.
+
+- **Subagent definitions** live in `.gemini/agents/*.md`, which are distinct from skills. Their schema is `kind` (`local` or `remote`), `model`, `temperature`, `max_turns`, and `tools`. Note that this is a subagent schema, not a skill schema: the two should not be merged into one `SKILL.md`.
+- **Model routing** can send lighter tasks (formatting, documentation, git operations) to a faster model and reserve a stronger model for cognitively demanding work (debugging, security auditing, interface design).
+- **Tool restrictions** enforce least-privilege per subagent, which also trims unused tool schemas from the prompt.
+- **Turn limits** (`max_turns`) cap execution to avoid runaway correction loops.
+
+### Model guidance
+
+Google recommends omitting `temperature` for Gemini 3.x models and using `thinking_level` instead. Do not hardcode `temperature` on skills or subagents routed to 3.x models; prefer `thinking_level` and revisit this guidance as the models evolve.
+
+```yaml
+# .gemini/agents/security-auditor.md
+---
+kind: local
+model: gemini-3-pro
+thinking_level: high   # not: temperature: 0.1
+tools: [read_file, grep]
+max_turns: 10
+---
+```
+
+## Automating with scripts
+
+Maintaining per-agent metadata by hand across every skill is repetitive, drifts out of sync, and is easy to get wrong. A better approach is to keep a single source of truth and generate the agent-specific output:
+
+- A generator reads a per-skill configuration map (which model, tool allowlist, turn limit, and isolation each skill should use for a given agent).
+- For metadata-style fields, it injects them under the `metadata` key of each `SKILL.md`, keeping the file spec-conformant.
+- For orchestration-style fields, it emits the separate adapter files an agent expects, for example `.gemini/agents/*.md` subagent definitions, leaving `SKILL.md` untouched.
+
+Generation also lets the tooling validate **semantics, not just shape**: confirm that a model name is a known model, that a tool name is a real tool, that `max_turns` is a positive integer, and that `temperature` (where still applicable) is a valid number in range. Shape-only checks let invalid values such as `parseInt("1.5")` or `parseFloat("0.2oops")` slip through.
+
+## Status
+
+It is the single reference for per-agent configuration: it keeps the shared skills portable while documenting the advanced controls each agent offers as an opt-in. The script-based automation described above is a proposal pending agreement before any implementation.