@givolt/i3-composer-agent 2.2.0 → 2.2.2

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/tool-selector.cjs

@@ -0,0 +1,164 @@
+'use strict';
+
+const readline = require('node:readline');
+const { orderedAgents, commonIds } = require('./tool-menu.cjs');
+
+// Terminal columns are not JavaScript string lengths: Chinese characters use
+// two cells. Keep every rendered line within the viewport before repainting.
+function cellWidth(character) {
+  const code = character.codePointAt(0);
+  if (/\p{Mark}/u.test(character) || code === 0x200d) return 0;
+  return code >= 0x1100 && (code <= 0x115f || code === 0x2329 || code === 0x232a
+    || (code >= 0x2e80 && code <= 0xa4cf && code !== 0x303f)
+    || (code >= 0xac00 && code <= 0xd7a3) || (code >= 0xf900 && code <= 0xfaff)
+    || (code >= 0xfe10 && code <= 0xfe19) || (code >= 0xfe30 && code <= 0xfe6f)
+    || (code >= 0xff00 && code <= 0xff60) || (code >= 0xffe0 && code <= 0xffe6)
+    || (code >= 0x1f300 && code <= 0x1faff) || (code >= 0x20000 && code <= 0x3fffd)) ? 2 : 1;
+}
+function width(text) { return [...text].reduce((size, character) => size + cellWidth(character), 0); }
+function clip(text, columns) {
+  if (width(text) <= columns) return text;
+  const suffix = columns >= 3 ? '...' : '';
+  let result = '', size = 0;
+  for (const character of text) {
+    size += cellWidth(character);
+    if (size > columns - suffix.length) break;
+    result += character;
+  }
+  return result + suffix;
+}
+function wrap(text, columns) {
+  const lines = [];
+  let line = '', size = 0;
+  for (const character of text) {
+    const cells = cellWidth(character);
+    if (line && size + cells > columns) { lines.push(line); line = ''; size = 0; }
+    line += character; size += cells;
+  }
+  lines.push(line);
+  return lines;
+}
+
+function selectTools(initialSelection, input = process.stdin, output = process.stdout) {
+  const selected = new Set(initialSelection);
+  let view = 'common', cursor = 0, commonCursor = 0, query = '', searching = false, message = '';
+  let frame = [], pageSize = 10, finished = false;
+  const wasRaw = Boolean(input.isRaw), wasFlowing = input.readableFlowing;
+  const choices = () => view === 'common' ? [...orderedAgents.slice(0, commonIds.length), null]
+    : view === 'more' ? orderedAgents.slice(commonIds.length)
+      : orderedAgents.filter(agent => `${agent.label} ${agent.id}`.toLowerCase().includes(query.toLowerCase()));
+  const selectedLabels = () => [...selected].map(id => orderedAgents.find(agent => agent.id === id).label).join('、');
+
+  function clearFrame() {
+    if (!frame.length) return;
+    const columns = output.columns || 80;
+    const rows = frame.reduce((count, line) => count + Math.max(1, Math.ceil(width(line) / columns)), 0);
+    readline.moveCursor(output, 0, -rows);
+    readline.cursorTo(output, 0);
+    readline.clearScreenDown(output);
+    frame = [];
+  }
+  function render() {
+    if (finished) return;
+    const columns = Math.max(1, (output.columns || 80) - 1), rows = output.rows || 24;
+    const entries = choices();
+    cursor = Math.max(0, Math.min(cursor, entries.length - 1));
+    const summary = wrap(`已选（${selected.size}）：${selectedLabels() || '无'}`, columns);
+    const summaryLimit = rows < 16 ? 1 : 3;
+    if (summary.length > summaryLimit) {
+      summary.length = summaryLimit;
+      summary[summaryLimit - 1] = clip(summary[summaryLimit - 1], Math.max(0, columns - 3)) + '...';
+    }
+    const hints = searching
+      ? ['输入关键词实时搜索', 'Enter/↓ 浏览结果 · Esc返回 · Ctrl-C取消']
+      : ['↑↓ 移动/跨页 · 空格勾选 · Enter确认', 'm 更多 · / 搜索 · b/← 返回 · q/Esc取消'];
+    const footer = ['', ...summary, ...hints.flatMap(line => wrap(line, columns)), message];
+    const searchLine = view === 'search' ? [`搜索：${query}${searching ? '|' : ''}`] : [];
+    pageSize = Math.max(1, Math.min(10, rows - footer.length - searchLine.length - 2));
+    const page = Math.floor(cursor / pageSize), pages = Math.max(1, Math.ceil(entries.length / pageSize));
+    const title = view === 'common' ? '选择常用工具（支持多选）：'
+      : `${view === 'more' ? '更多工具' : '搜索结果'}：第 ${page + 1}/${pages} 页，共 ${entries.length} 项`;
+    const lines = [title, ...searchLine];
+    for (let index = page * pageSize; index < Math.min(entries.length, (page + 1) * pageSize); index++) {
+      const agent = entries[index], pointer = index === cursor ? '>' : ' ';
+      lines.push(agent ? `${pointer} [${selected.has(agent.id) ? 'x' : ' '}] ${orderedAgents.indexOf(agent) + 1}. ${agent.label} [${agent.id}]${agent.globalSkillsDir ? '' : '（仅项目）'}`
+        : `${pointer}     更多工具（空格展开）`);
+    }
+    if (!entries.length) lines.push('没有匹配工具；按 / 重新搜索，或 Esc 返回。');
+    clearFrame();
+    frame = [...lines, ...footer].map(line => clip(line, columns));
+    output.write(frame.join('\n') + '\n');
+  }
+
+  return new Promise((resolve, reject) => {
+    function finish(value, error) {
+      if (finished) return;
+      finished = true;
+      input.off('keypress', keypress);
+      input.off('end', cancel);
+      input.off('error', fail);
+      output.off('resize', redraw);
+      process.off('SIGINT', cancel);
+      input.setRawMode(wasRaw);
+      if (!wasFlowing) input.pause();
+      try {
+        clearFrame();
+        output.write('\x1b[?25h');
+        if (value) output.write(`已选择工具：${selectedLabels()}\n`);
+      } catch (outputError) { error ||= outputError; }
+      if (error) reject(error); else resolve(value);
+    }
+    function cancel() { finish(null); }
+    function fail(error) { finish(null, error); }
+    function redraw() { try { render(); } catch (error) { fail(error); } }
+    function openMore() {
+      if (view === 'common') commonCursor = cursor;
+      view = 'more'; cursor = 0; searching = false;
+    }
+    function back() { view = 'common'; cursor = commonCursor; searching = false; query = ''; }
+    function keypress(text, key = {}) {
+      if (finished) return;
+      try {
+        message = '';
+        if (key.ctrl && ['c', 'd'].includes(key.name)) { cancel(); return; }
+        if (searching) {
+          if (key.name === 'escape') back();
+          else if (['return', 'enter', 'down'].includes(key.name)) searching = false;
+          else if (key.name === 'backspace') { query = [...query].slice(0, -1).join(''); cursor = 0; }
+          else if (text && !key.ctrl && !key.meta && !/[\x00-\x1f\x7f]/.test(text)) { query += text; cursor = 0; }
+        } else if (key.name === 'escape') {
+          if (view === 'search') back(); else { cancel(); return; }
+        } else if (text === 'q') { cancel(); return; }
+        else if (['return', 'enter'].includes(key.name)) {
+          if (selected.size) { finish([...selected]); return; }
+          message = '请至少用空格选择一个工具。';
+        } else if (key.name === 'space' || text === ' ') {
+          const entry = choices()[cursor];
+          if (entry) { if (selected.has(entry.id)) selected.delete(entry.id); else selected.add(entry.id); }
+          else if (view === 'common') openMore();
+        } else if (['up', 'down', 'pageup', 'pagedown'].includes(key.name) || ['n', 'p'].includes(text)) {
+          const direction = ['up', 'pageup'].includes(key.name) || text === 'p' ? -1 : 1;
+          const step = ['pageup', 'pagedown'].includes(key.name) || ['n', 'p'].includes(text) ? pageSize : 1;
+          cursor = Math.max(0, Math.min(choices().length - 1, cursor + direction * step));
+        } else if (text === 'm' || (key.name === 'right' && view === 'common')) openMore();
+        else if (text === 'b' || key.name === 'left') back();
+        else if (text === '/') { if (view === 'common') commonCursor = cursor; view = 'search'; query = ''; cursor = 0; searching = true; }
+        render();
+      } catch (error) { fail(error); }
+    }
+    try {
+      readline.emitKeypressEvents(input);
+      input.setRawMode(true);
+      input.on('keypress', keypress);
+      input.once('end', cancel);
+      input.once('error', fail);
+      output.on('resize', redraw);
+      process.once('SIGINT', cancel);
+      output.write('\x1b[?25l');
+      render();
+      input.resume();
+    } catch (error) { fail(error); }
+  });
+}
+
+module.exports = { selectTools };

package/bin/wizard.cjs

@@ -1,8 +1,8 @@
 'use strict';
 
 const readline = require('node:readline');
-const { registry, selectAgents } = require('./install.cjs');
-const { orderedAgents, commonIds } = require('./tool-menu.cjs');
+const { selectAgents } = require('./install.cjs');
+const { selectTools } = require('./tool-selector.cjs');
 
 async function session(action) {
   const terminal = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -23,49 +23,11 @@ async function session(action) {
 }
 async function choose(options, identity) {
   console.log(identity);
+  const agents = await selectTools(selectAgents(options.agents));
+  if (!agents) return null;
+  if (agents.includes('workbuddy')) console.log('WorkBuddy 桌面版建议全局安装，以便技能列表和输入补全发现 Skills；项目安装仍支持命令，技能列表可能不显示。');
   return session(async ask => {
-    const selected = new Set(selectAgents(options.agents));
-    let view = 'common', page = 0, query = '';
     const cancelled = input => input === null || ['q', 'cancel', '取消'].includes(input.toLowerCase());
-    while (true) {
-      const matches = view === 'common' ? orderedAgents.slice(0, commonIds.length)
-        : view === 'search' ? orderedAgents.filter(agent => `${agent.id} ${agent.label}`.toLowerCase().includes(query.toLowerCase()))
-          : orderedAgents.slice(commonIds.length);
-      const pages = Math.max(1, Math.ceil(matches.length / 10));
-      page = Math.max(0, Math.min(page, pages - 1));
-      console.log(view === 'common' ? '\n选择常用工具（支持多选）：'
-        : `\n${view === 'search' ? `搜索“${query}”` : '更多工具'}：第 ${page + 1}/${pages} 页，共 ${matches.length} 项`);
-      for (const agent of view === 'common' ? matches : matches.slice(page * 10, page * 10 + 10)) {
-        console.log(`${orderedAgents.indexOf(agent) + 1}. ${agent.label} [${agent.id}]${selected.has(agent.id) ? ' ✓ 已选' : ''}${agent.globalSkillsDir ? '' : '（仅项目安装）'}`);
-      }
-      if (view === 'common') console.log('7. 更多（m）');
-      else console.log('n 下一页 · p 上一页 · b 返回常用工具');
-      console.log(`已选：${[...selected].join(', ') || '无'}；/关键词 搜索全部 ${registry.agents.length} 个工具；回车或完成确认；-编号/ID 移除选择。`);
-      const input = await ask('输入编号/ID，可用逗号多选（q/取消退出）： ');
-      if (cancelled(input)) return null;
-      if (['', 'done', '完成'].includes(input.toLowerCase())) {
-        if (selected.size) break;
-        console.log('请至少选择一个工具。'); continue;
-      }
-      if (['m', 'more', '更多'].includes(input.toLowerCase()) || (view === 'common' && input === '7')) { view = 'more'; page = 0; continue; }
-      if (['b', 'back', '返回'].includes(input.toLowerCase())) { view = 'common'; page = 0; continue; }
-      if (view !== 'common' && ['n', '下一页'].includes(input.toLowerCase())) { page = Math.min(pages - 1, page + 1); continue; }
-      if (view !== 'common' && ['p', '上一页'].includes(input.toLowerCase())) { page = Math.max(0, page - 1); continue; }
-      if (input.startsWith('/')) { view = 'search'; query = input.slice(1).trim(); page = 0; continue; }
-      try {
-        const values = ['all', '全部'].includes(input.toLowerCase()) ? orderedAgents.map(agent => agent.id) : input.split(/[,，]/);
-        const additions = [], removals = [];
-        for (const value of values) {
-          const remove = value.trim().startsWith('-'), raw = value.trim().replace(/^-/, '');
-          const id = /^\d+$/.test(raw) ? orderedAgents[Number(raw) - 1]?.id || raw : raw;
-          (remove ? removals : additions).push(...selectAgents([id]));
-        }
-        for (const id of additions) selected.add(id);
-        for (const id of removals) selected.delete(id);
-      } catch (error) { console.log(error.message); }
-    }
-    const agents = [...selected];
-    if (agents.includes('workbuddy')) console.log('WorkBuddy 桌面版建议全局安装，以便技能列表和输入补全发现 Skills；项目安装仍支持命令，技能列表可能不显示。');
     let scope = options.scope;
     while (!scope) {
       const input = await ask('安装范围：1. 项目（当前项目），2. 全局（所有项目）[1]（q/取消退出）： ');
@@ -82,10 +44,13 @@ 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(`  评测：${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} 个未修改内容。`);
-  console.log('包含完整技能及共享参考资料。插件 Hook 需按宿主方式注册和启用。');
+  console.log('包含技能、共享资料和完整评测/Hook/脚本配套。安装不执行评测；Hook 需按宿主方式启用。');
   return session(async ask => {
     const answer = await ask('确认安装这些内容？[y/N]： ');
     return answer !== null && ['y', 'yes', '是', '确认'].includes(answer.toLowerCase());

package/docs/codebuddy-setup.md

@@ -11,6 +11,8 @@ npx @givolt/i3-composer-agent --codebuddy
 向导预选 CodeBuddy，可增加其他工具，再选择项目或全局范围。
 项目安装提供 `.codebuddy/skills/`（25 个技能）、`references/`、
 `commands/`（9 个命令）和 `agents/`（4 个角色）。
+同级 `evals/`、`hooks/`、`scripts/`、`docs/`、`references/` 各自通过 `i3-composer-agent/` 分组资料，
+只有一份实际技能、命令和角色，评测与宿主共用。
 全局使用 `~/.codebuddy/` 的相同结构。默认中文说明和回复；技能/命令标识不改名。
 安装成功清理旧内容，失败恢复；设置与自定义命令保留。
 
@@ -37,9 +39,16 @@ CodeBuddy 与 WorkBuddy 项目共用 `.codebuddy/`；同版本追加客户端会
 全局目录彼此独立。WorkBuddy 桌面版建议全局安装，详见 [WorkBuddy 说明](workbuddy-setup.md)。
 升级或同名冲突先查看 `--dry-run`，再确认或使用 `--yes --force`。
 
-## CodeBuddy Code 完整插件
+## 配套检查
 
-终端宿主的插件管理器使用完整目录：
+在业务项目运行 `node .codebuddy/scripts/i3-composer-agent/run-evals.cjs --min-rank1 95`，
+可检查中英文触发，不调用模型；全局安装使用脚本的全局绝对路径。五项校验、行为评测和样例用法见
+[评测说明](../evals/README.md)。Hook 文件已安装，需要按宿主协议单独启用。
+
+## 通过 CodeBuddy Code 插件管理器安装
+
+这是另一种由宿主插件管理器管理的安装方式；已完成原生安装时无需再次执行。
+`--prepare` 只导出文件并显示注册步骤，不自动注册插件或启用 Hook：
 
 ```bash
 npx @givolt/i3-composer-agent --prepare --codebuddy
@@ -55,7 +64,7 @@ npx @givolt/i3-composer-agent --prepare --codebuddy
 按宿主选择范围并启用后新建会话。兼容清单声明 `.claude/commands/` 与 `commands/`。
 插件命令示例为 `/i3-composer-agent:i3-spec`、`/i3-composer-agent:i3-plan`、
 `/i3-composer-agent:i3-build auto` 和 `/i3-composer-agent:i3-ship`。
-完整目录包含 Hook 与共享参考；原生文件安装不自动启用插件 Hook。
+默认安装和导出均包含完整评测、Hook 与脚本；Hook 不自动启用。
 文件落盘、宿主发现和模型实际执行应分别验证。
 
 目录遵循 [配置目录参考](https://www.codebuddy.cn/docs/cli/codebuddy-dir)，可参照

package/docs/codex-setup.md

@@ -6,11 +6,15 @@
 npx @givolt/i3-composer-agent --codex
 ```
 
-项目范围写入 `.agents/skills/`，全局写入 `~/.agents/skills/`，并安装同级 `references/`。
+项目范围写入 `.agents/skills/`，全局写入 `~/.agents/skills/`，并安装同级 `references/i3-composer-agent/`。
 提供全部 25 个 `i3-` 技能，中文选择说明与默认中文回复在每个入口独立生效。
-此模式不安装短生命周期命令，也不自动启用插件 Hook。
+同级 `evals/`、`hooks/`、`scripts/`、`docs/` 各自以 `i3-composer-agent/` 分组资料。
+命令与角色文件也会提供，供按需阅读，其自动发现由宿主决定。
+从项目目录执行 `node .agents/scripts/i3-composer-agent/run-evals.cjs --min-rank1 95`
+检查实际安装技能的中英文触发，不调用模型；五项结构校验详见
+[评测说明](../evals/README.md)。原生调用使用技能 ID，Hook 文件需按宿主能力单独启用。
 
-## 完整插件
+## 通过插件管理器安装
 
 ```bash
 npx @givolt/i3-composer-agent --prepare --codex
@@ -18,7 +22,8 @@ codex plugin marketplace add ./i3-composer-agent
 codex plugin add i3-composer-agent@i3-composer-agent
 ```
 
-准备模式产生持久目录并显示注册命令。注册启用后新建会话，
+准备模式另行导出持久目录并显示注册命令，不自动注册或启用 Hook。
+已完成原生安装时无需再次准备。选择插件安装方式并注册启用后新建会话，
 通过 `/skills`、`$i3-spec-driven-development` 等技能名称，或在聊天中明确指定技能调用。
 插件适配清单指向 `skills/`；共享资料保留相对链接可解析的 `references/` 布局。
 

package/docs/workbuddy-setup.md

@@ -13,13 +13,22 @@ 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/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。
 WorkBuddy 的目录选择使用自己的配置，不借用 `CODEBUDDY_CONFIG_DIR`。
 
+## 配套检查
+
+运行 `node ~/.workbuddy/scripts/i3-composer-agent/run-evals.cjs --min-rank1 95`，检查实际安装技能的中英文触发，
+不会调用模型。项目安装将 `~/.workbuddy/` 换成 `.codebuddy/`。五项校验、行为评测用例、样例和
+脚本用法见 [评测说明](../evals/README.md)。Hook 文件默认提供，启用需适配宿主事件协议。
+
 ## 发现和调用
 
 安装后新建会话，查看 Skills 列表并输入 `/` 查看命令：
@@ -65,8 +74,8 @@ npx @givolt/i3-composer-agent --workbuddy --scope global --dry-run
 npx @givolt/i3-composer-agent --workbuddy --scope global --yes --force
 ```
 
-升级、修改内容和未登记同名冲突需要确认；成功替换后清理旧文件与所属历史备份，失败恢复。
-原生安装提供 Skills、Commands、Agents；完整插件注册另按宿主能力处理。
+升级和已登记文件修改需确认；未归属的资料冲突或不同内容的同名评测结果需要先处理；成功替换后清理旧文件与所属历史备份，失败恢复。
+原生安装同时提供 Skills、Commands、Agents 和完整 evals/hooks/scripts 配套。
 `--prepare --workbuddy` 不支持，原生安装不会启用插件 Hook。
 
 可参照 [任务栏命令说明](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Task-Bar)、

package/evals/README.md

@@ -0,0 +1,95 @@
+# 技能评测与配套脚本
+
+本目录随默认安装、npm 包和插件导出一起提供，评测 i3 Composer Agent 技能的结构、
+触发与行为。评测不在安装时自动执行。它检查技能库自身，不能代替业务项目测试、
+宿主发现验证或真实模型验收。
+
+## 运行位置
+
+原生安装的技能位于宿主基址的 `skills/`；评测资料位于 `evals/i3-composer-agent/`，
+脚本位于 `scripts/i3-composer-agent/`。安装清单记录预期技能和文件，评测只读取这份实际安装内容。
+例如 CodeBuddy 项目基址是 `.codebuddy/`，WorkBuddy 全局基址是 `~/.workbuddy/`。
+下面原生示例从业务项目根目录运行；从其他位置运行时，将脚本路径换成绝对路径即可。
+Node.js 20 或以上，无需额外 npm 依赖；`.cjs` 入口兼容业务项目的 ESM/CommonJS 设置。
+
+## 不调用模型的检查
+
+```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
+node .codebuddy/scripts/i3-composer-agent/run-evals.cjs --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
+```
+
+独立插件的校验还会检查插件清单和三种命令格式的一致性。原生安装不复制这些注册清单，
+不需要在业务项目或宿主基址执行 `npm test`。
+
+触发评测使用词法评分检查正例、负例、描述冲突、用例结构及样例是否齐全。
+中英文各自满足指定门槛；这不能证明模型在实际宿主中一定选择正确技能。
+失败时应调查技能描述或实现，不能为了通过检查降低门槛或删改失败用例。
+
+## 主动运行模型行为评测
+
+先预览，不调用模型、不生成评测结果：
+
+```bash
+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 .codebuddy/scripts/i3-composer-agent/run-evals.cjs --behavioral i3-test-driven-development --locale zh-CN
+```
+
+执行型用例需要 Git，并在临时 Git 项目中复制 `fixtures/` 的真实输入；
+对话型用例评估对话，不要求项目文件。执行器使用 `acceptEdits` 及明确的工具列表，
+可能编辑文件、运行命令、访问网络；各样例还可能需要自身的语言运行环境。
+评分依据执行轨迹或对话与 `expectations`，不会把“声称完成”当成实际执行证据。
+模型输出按不可信数据评分，执行和评分均有限时。临时项目完成后清理。
+
+`--locale en` 运行英文用例，省略该参数运行两种语言。可通过 `I3_EVAL_MODEL`
+和 `I3_EVAL_GRADER_MODEL` 指定执行/评分模型；报告同时记录宿主和模型信息。
+原生结果写入 `evals/i3-composer-agent/results/`；独立插件写入 `evals/results/`。
+结果不会进入发行包和文件替换清单，升级保留；旧配套目录的结果会迁入新位置，同名异内容时停止迁移。
+
+## 插件级评测
+
+插件清单中的 `experimental.evals` 指向随包提供的 `evals/plugin/`。
+原生安装也保留这些用例作为资料；要运行依赖插件清单的命令，需要独立插件导出。
+它包含整体插件的触发/不触发提示和评分规则；支持 `plugin eval` 的 Claude Code
+可从 `--prepare` / `--extract` 的独立插件导出目录主动运行：
+
+```bash
+claude plugin eval . --no-publish
+```
+
+该检查同样会调用模型；具体参数以当前 Claude Code 的帮助为准。
+`--no-publish` 保持结果本地，报告写入 `evals/plugin/results/`。
+用是否触发、回答质量及对照结果一起判断效果；调用一次成功不能代替多次行为验收。
+
+## Hooks
+
+原生的 `hooks/i3-composer-agent/`（独立插件为 `hooks/`）默认交付会话注入、文档缓存、代码块保护脚本及说明。
+安装文件不会自动注册事件。中文回复与普通技能调用不依赖启用 Hook。
+会话注入仅适用于缺少原生技能路由的宿主；已有路由时不要重复注入。
+缓存及保护的当前配置示例针对 Claude Code，详见
+[文档缓存](../hooks/SDD-CACHE.md) 和 [代码块保护](../hooks/SIMPLIFY-IGNORE.md)。
+其他宿主须按各自事件协议适配。脚本需要 Bash、jq 及说明中的 curl/哈希工具；
+Windows PowerShell 本身不提供这些依赖。

package/evals/cases/i3-api-and-interface-design.json

@@ -0,0 +1,45 @@
+{
+  "skill_name": "i3-api-and-interface-design",
+  "trigger": {
+    "positive": [
+      {
+        "prompt": "Design a REST endpoint for creating invoices, including error responses and versioning",
+        "top_k": 3
+      },
+      {
+        "prompt": "What should the public interface of this payments module expose to other teams?",
+        "top_k": 3
+      },
+      {
+        "prompt": "Help me define the contract between the frontend and the orders service",
+        "top_k": 3
+      }
+    ],
+    "negative": [
+      {
+        "prompt": "My unit test is failing with a null pointer exception",
+        "owner": "i3-debugging-and-error-recovery"
+      },
+      {
+        "prompt": "Make this landing page responsive on mobile",
+        "owner": "i3-frontend-ui-engineering"
+      }
+    ]
+  },
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Design the public API for a URL-shortening service: create, resolve, stats. Produce the endpoint contracts.",
+      "expected_output": "Endpoint contracts with methods, paths, request/response shapes, and explicit error semantics",
+      "files": [
+        "i3-api-and-interface-design"
+      ],
+      "expectations": [
+        "Error responses are specified with status codes and a consistent error shape, not just happy paths",
+        "Input validation at the boundary is addressed for user-supplied URLs",
+        "Versioning or compatibility strategy is stated",
+        "The response does not silently invent unstated requirements"
+      ]
+    }
+  ]
+}

package/evals/cases/i3-browser-testing-with-devtools.json

@@ -0,0 +1,44 @@
+{
+  "skill_name": "i3-browser-testing-with-devtools",
+  "trigger": {
+    "positive": [
+      {
+        "prompt": "Use Chrome DevTools to figure out why the checkout button click does nothing",
+        "top_k": 3
+      },
+      {
+        "prompt": "Inspect the network requests the dashboard makes when it first loads",
+        "top_k": 3
+      },
+      {
+        "prompt": "Verify in a real browser that the form submits and the data persists in localStorage",
+        "top_k": 3
+      }
+    ],
+    "negative": [
+      {
+        "prompt": "Write a spec for the new billing feature before we start",
+        "owner": "i3-spec-driven-development"
+      },
+      {
+        "prompt": "Break this PRD into ordered implementation tasks",
+        "owner": "i3-planning-and-task-breakdown"
+      }
+    ]
+  },
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "The signup form renders but submitting it appears to do nothing. Verify the real behavior in the browser and report findings.",
+      "expected_output": "Runtime evidence from the browser: console errors, network activity, DOM state, and a diagnosis",
+      "files": [
+        "i3-browser-testing-with-devtools"
+      ],
+      "expectations": [
+        "Findings are grounded in observed runtime data (console, network, DOM), not static code reading alone",
+        "The report distinguishes what was observed from what is inferred",
+        "A concrete next step or fix hypothesis is provided"
+      ]
+    }
+  ]
+}

package/evals/cases/i3-ci-cd-and-automation.json

@@ -0,0 +1,45 @@
+{
+  "skill_name": "i3-ci-cd-and-automation",
+  "trigger": {
+    "positive": [
+      {
+        "prompt": "Set up a GitHub Actions pipeline that runs the tests on every pull request",
+        "top_k": 3
+      },
+      {
+        "prompt": "Add a deploy stage to the pipeline with a manual approval gate",
+        "top_k": 3
+      },
+      {
+        "prompt": "Automate the quality gates so nothing merges without passing checks",
+        "top_k": 3
+      }
+    ],
+    "negative": [
+      {
+        "prompt": "Refactor this function so it is easier to read",
+        "owner": "i3-code-simplification"
+      },
+      {
+        "prompt": "Add structured logging to the checkout service",
+        "owner": "i3-observability-and-instrumentation"
+      }
+    ]
+  },
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Create a CI pipeline for a Node project: install, lint, test on every PR, and block merge on failure.",
+      "expected_output": "A working workflow definition with correct triggers, steps, and failure behavior",
+      "files": [
+        "i3-ci-cd-and-automation"
+      ],
+      "expectations": [
+        "The workflow triggers on pull requests",
+        "Failure of any quality gate fails the pipeline run",
+        "Steps are ordered logically and cache or setup steps are sane",
+        "No secrets are hardcoded in the workflow"
+      ]
+    }
+  ]
+}

package/evals/cases/i3-code-review-and-quality.json

@@ -0,0 +1,49 @@
+{
+  "skill_name": "i3-code-review-and-quality",
+  "trigger": {
+    "positive": [
+      {
+        "prompt": "Review this pull request before I merge it",
+        "top_k": 3
+      },
+      {
+        "prompt": "Do a quality pass on this diff for correctness and readability",
+        "top_k": 3
+      },
+      {
+        "prompt": "Can you review the changes another model just wrote for me?",
+        "top_k": 3
+      },
+      {
+        "prompt": "Review this diff before I merge it. It adds paging to the orders endpoint.",
+        "top_k": 3
+      }
+    ],
+    "negative": [
+      {
+        "prompt": "Deploy this to production now",
+        "owner": "i3-shipping-and-launch"
+      },
+      {
+        "prompt": "Write a failing test for the bug before fixing it",
+        "owner": "i3-test-driven-development"
+      }
+    ]
+  },
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Review the provided diff that adds a user-search endpoint. Deliver a structured review.",
+      "expected_output": "A multi-axis review with severity-labelled findings and file:line references",
+      "files": [
+        "i3-code-review-and-quality"
+      ],
+      "expectations": [
+        "Findings cover more than one axis (correctness, readability, architecture, security, performance)",
+        "Every finding carries a severity label from the skill's taxonomy",
+        "Security of user input is explicitly considered for the new endpoint",
+        "The review leads with high-leverage findings rather than nits"
+      ]
+    }
+  ]
+}