@givolt/i3-composer-agent 2.3.2 → 2.3.3

package/.agents/plugins/marketplace.json

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

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
   "plugins": [
     {
       "name": "i3-composer-agent",
-      "version": "2.3.2",
+      "version": "2.3.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.3.2",
+  "version": "2.3.3",
   "description": "覆盖需求、计划、开发、测试、审查与发布的软件工程技能，默认使用简体中文。",
   "author": {
     "name": "Givolt"

package/.codex-plugin/plugin.json

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

package/README.md

@@ -1,4 +1,4 @@
-# i3 Composer Agent v2.3.2
+# i3 Composer Agent v2.3.3
 
 **Intelligence. Integration. Innovation.**
 
@@ -25,6 +25,8 @@ WorkBuddy 在第 2 项。上下键移动，空格勾选/取消，回车确认；
 搜索、翻页和命令参数预选均保留选择。搜索外 `q`、Esc 或 Ctrl-C 取消。
 确认工具后选择项目/全局范围并确认安装。
 
+可直接输入工具编号，例如 `1` 选择 CodeBuddy，或 `1,2` 多选，再按回车。CodeBuddy 的安装范围、Hooks、启用组、IDE／CLI、路由、UIUX／antDv 及最终确认均支持数字选择。新范围推荐启用 Hooks，已有安装默认保留现状；升级时要启用 Hooks 请明确选“启用”。UIUX／antDv 可选择安装两项、单项或跳过，之后也可补装。
+
 全部目标均安装 26 个技能、共享参考资料，以及完整评测/Hook/脚本配套。
 全部目标同时提供 10 个命令和 4 个 Agent 角色提示。
 CodeBuddy、WorkBuddy、Claude Code 使用原生命令入口；其他工具通过 Skills 机制使用，
@@ -239,3 +241,5 @@ npx @givolt/i3-composer-agent --codebuddy --dir /path/to/plugin --force
 仓库维护用的 AGENTS.md、CLAUDE.md 不复制进业务项目。
 Codex 通过 `$i3-spec-driven-development` 等技能名调用；其原生 `/plan` 是宿主计划模式。
 中文语言策略、工程方法、审批要求与工具限制在各入口独立生效。
+
+原型共享资料统一在项目 prototypes/：新索引 prototypes/index.json，准备范围 prototypes/.preparation/<id>/scope.json。新原生 scope.moduleIds 自动生成 appliesTo；旧索引、输入和实例保持兼容，安装升级不自动迁移。工具及运行缓存使用所选宿主基址；全局浏览器缓存按业务项目身份隔离。详细规则和只读查询／显式迁移命令见 i3-ui-prototype/references/project-layout.md。

package/bin/agent-targets.json

@@ -8,8 +8,10 @@
       "label": "CodeBuddy",
       "projectSkillsDir": ".codebuddy/skills",
       "globalSkillsDir": {
-        "base": "home",
-        "path": ".codebuddy/skills"
+        "base": "env",
+        "env": "CODEBUDDY_CONFIG_DIR",
+        "fallback": ".codebuddy",
+        "path": "skills"
       }
     },
     {

package/bin/i3-composer-agent.cjs

@@ -24,6 +24,7 @@ ${pkg.name}
   npx ${pkg.name} --codebuddy --scope project --yes --prototype-skills uiux,antdv
   npx ${pkg.name} prototype-deps check --host codex --scope project --project <project>
   npx ${pkg.name} prototype-deps install --host workbuddy --scope global --skills uiux,antdv
+  npx ${pkg.name} hooks list --host codebuddy --scope project --project <project>
   npx ${pkg.name} --prepare --claude --dir <directory>
   npx ${pkg.name} --extract --dir <directory>
 
@@ -35,8 +36,15 @@ ${pkg.name}
   --claude           预选 Claude Code
   --scope <scope>    project 项目 / global 全局（也可 --global / --local）
   --project-dir <dir> 项目安装根目录，默认当前目录
-  --prototype-skills <ids> 可选原型依赖：none（默认）、uiux、antdv、uiux,antdv；跟随所选宿主和范围
+  --prototype-skills <ids> 可选原型依赖：none、uiux、antdv、uiux,antdv；向导数字选择，--yes 未指定时跳过
   --migrate-tools     显式迁移有 i3 来源记录的旧独立 antDv 工具；仅项目范围且需选择 antdv
+  --hooks <action>    CodeBuddy 统一 Hooks：keep（非交互默认）/ enable / list / check / disable
+  --hook-groups <ids> session-start,sdd-cache,simplify-ignore,prototype 或 all；启停默认 prototype
+  --codebuddy-skill-routing <mode> hook（明确需要会话注入）/ native（已有原生路由）
+  --prototype-hooks <action> 旧参数保留，仅管理 prototype 组
+  --codebuddy-product <form> 启用时明确 ide 或 cli；CLI 注册后需在 /hooks 审核
+  --codebuddy-transcript-root <dir|auto> 默认自动识别；可选手动原生日志限制，auto 切回自动
+  --codebuddy-version <version> 实际宿主版本，便于核验记录
   --yes              确认明确指定的非交互安装
   --list-agents      列出全部支持的工具目录
   --prepare          另行导出插件目录并显示宿主注册步骤
@@ -48,13 +56,14 @@ ${pkg.name}
   --help             显示帮助
 
 终端向导先显示常用工具，WorkBuddy 在第 2 项；选择“更多”可分页/搜索全部工具。
-上下键移动/跨页，空格勾选/取消，回车确认；列表下实时显示已选，q/Esc 退出。
+输入工具编号（如 1,2）后回车，或上下键移动/跨页、空格勾选、回车确认；q/Esc 退出。
+范围、Hooks、IDE/CLI、可选原型依赖和最终确认使用数字选择，Hook 组支持逗号分隔数字多选。
 CodeBuddy、WorkBuddy、Claude Code 同时安装短命令和 Agent 角色。
 其他工具通过 Skills 调用，短命令支持取决于宿主。
 所有工具默认安装单份 skills、commands、agents；配套资料集中在 i3-composer-agent/。
 评测、脚本和 Hook 读取同一份已安装技能。--prepare 用于另行导出标准插件并按宿主方式注册。
 WorkBuddy 桌面版建议全局安装，便于技能列表和输入补全发现。
-评测需主动运行；Hook 文件已提供，需按宿主事件协议单独启用。
+评测需主动运行；向导可注册 CodeBuddy Hooks，实际生效仍需宿主审核/重载和回调验证。
 --prepare 仅供插件管理器安装方式使用，不自动注册插件或启用 Hook。
 `;
 
@@ -164,6 +173,10 @@ async function main() {
     console.log(JSON.stringify(await dependencies.main(args.slice(1)), null, 2));
     return;
   }
+  if (['hooks','prototype-hooks'].includes(args[0])) {
+    const result=require('../hooks/manage.cjs').main([...args.slice(1),...(args[0]==='prototype-hooks'?['--groups','prototype']:[])]);
+    console.log(JSON.stringify(result,null,2));if(result.status==='failed')process.exitCode=1;return;
+  }
   if (args.some(arg => ['--extract', '--prepare', '--dir'].includes(arg))) { prepare(); return; }
   const installer = require('./install.cjs');
   if (args.length === 1 && args[0] === '--list-agents') {
@@ -174,7 +187,7 @@ async function main() {
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (['--codebuddy', '--workbuddy', '--codex', '--claude'].includes(arg)) options.agents.push(arg.slice(2));
-    else if (['--agents', '--scope', '--project-dir', '--prototype-skills'].includes(arg)) {
+    else if (['--agents', '--scope', '--project-dir', '--prototype-skills','--prototype-hooks','--hooks','--hook-groups','--codebuddy-skill-routing','--codebuddy-product','--codebuddy-transcript-root','--codebuddy-version'].includes(arg)) {
       if (!args[i + 1] || args[i + 1].startsWith('--')) throw new Error(`${arg} 需要指定值。`);
       const value = args[++i];
       if (arg === '--agents') options.agents.push(value);
@@ -183,6 +196,13 @@ async function main() {
         require('../skills/i3-ui-prototype/scripts/optional-skill-install.cjs').selection(value);
         options.prototypeSkills = value;
       }
+      else if (arg === '--prototype-hooks') {if(!['keep','enable','check','disable'].includes(value))throw new Error('原型 Hooks 请选择 keep / enable / check / disable');options.prototypeHooks=value;}
+      else if (arg === '--hooks') {if(!['keep','enable','disable','list','check'].includes(value))throw new Error('Hooks 请选择 keep / enable / disable / list / check');options.hooks=value;}
+      else if (arg === '--hook-groups') {require('../hooks/manage.cjs').selection(value);options.hookGroups=value;}
+      else if (arg === '--codebuddy-skill-routing') {if(!['native','hook'].includes(value))throw new Error('请选择 native 或 hook');options.codebuddySkillRouting=value;}
+      else if (arg === '--codebuddy-product') {if(!['ide','cli'].includes(value))throw new Error('CodeBuddy 形态请选择 ide 或 cli');options.codebuddyProduct=value;}
+      else if (arg === '--codebuddy-transcript-root') options.codebuddyTranscriptRoot=value==='auto'?'auto':path.resolve(value);
+      else if (arg === '--codebuddy-version') options.codebuddyVersion=value;
       else options.projectDir = path.resolve(value);
     } else if (arg === '--global' || arg === '--local') {
       const scope = arg === '--global' ? 'global' : 'project';
@@ -195,6 +215,14 @@ async function main() {
     else throw new Error(`未知选项： ${arg}`);
   }
   options.agents = installer.selectAgents(options.agents);
+  if(options.prototypeHooks!==undefined&&(options.hooks!==undefined||options.hookGroups!==undefined))throw new Error('--prototype-hooks 旧参数不可与 --hooks / --hook-groups 混用');
+  const hookOptions=()=>({action:options.hooks||options.prototypeHooks||'keep',groups:options.hookGroups||(options.prototypeHooks!==undefined?'prototype':undefined),skillRouting:options.codebuddySkillRouting,host:'codebuddy',scope:options.scope,project:options.projectDir,product:options.codebuddyProduct,transcriptRoot:options.codebuddyTranscriptRoot,productVersion:options.codebuddyVersion,agents:options.agents});
+  if(['list','check','disable'].includes(hookOptions().action)) {
+    if(options.agents.length!==1||options.agents[0]!=='codebuddy'||!options.scope)throw new Error('Hooks check / disable 需明确 --codebuddy --scope project|global，不执行安装');
+    const manager=require('../hooks/manage.cjs');
+    const result=['list','check'].includes(hookOptions().action)?manager.check(hookOptions()):manager.configure({...hookOptions(),preview:!!options.dryRun});
+    console.log(JSON.stringify(result,null,2));if(result.status==='failed')process.exitCode=1;return;
+  }
   if (process.stdin.isTTY && process.stdout.isTTY && !options.yes && !options.dryRun) {
     const selection = await require('./wizard.cjs').choose(options, identity);
     if (!selection) { console.log('安装已取消，未修改文件。'); return; }
@@ -203,18 +231,25 @@ async function main() {
     throw new Error('请在交互终端使用向导，或明确指定 --agents <ids> --scope project|global --yes。');
   }
   if (options.migrateTools && (options.scope !== 'project' || !options.prototypeSkills?.split(',').includes('antdv'))) throw new Error('--migrate-tools requires project scope and selected antdv');
+  if(hookOptions().action!=='keep'&&!options.agents.includes('codebuddy'))throw new Error('首期统一 Hooks 仅适配 CodeBuddy');
+  const hookManager=require('../hooks/manage.cjs');
+  const hookChange=options.agents.includes('codebuddy')?hookManager.prepare(hookOptions()):null;
   const plan = installer.planInstallation(options);
   if (options.dryRun) {
     console.log(JSON.stringify({ name, version: pkg.version, mode: plan.mode, scope: plan.scope, agents: plan.agents, targets: plan.targets, conflicts: plan.conflicts, reused: plan.reused,
-      ...(options.prototypeSkills !== undefined ? { optionalPrototypeSkills: options.prototypeSkills, migrateTools: !!options.migrateTools } : {}) }, null, 2));
+      ...(options.prototypeSkills !== undefined ? { optionalPrototypeSkills: options.prototypeSkills, migrateTools: !!options.migrateTools } : {}),...(hookChange?{hooks:hookChange.summary}:{}) }, null, 2));
     return;
   }
   if (!options.yes) {
-    const confirmed = await require('./wizard.cjs').confirm(plan);
+    const confirmed = await require('./wizard.cjs').confirm(plan, { prototypeSkills: options.prototypeSkills, hooks: hookChange?.summary });
     if (!confirmed) { console.log('安装已取消，未修改文件。'); return; }
     options.force = plan.conflicts.length > 0;
   }
   installer.executeInstallation(plan, { force: options.force });
+  if(hookChange?.summary.changed) {
+    try {console.log(JSON.stringify({hooks:hookManager.apply(hookChange)},null,2));}
+    catch(error){throw new Error(`核心文件已安装，Hooks 注册未完成；请保留当前配置并重试或提供错误。${error.message}`);}
+  }
   console.log(identity);
   if (plan.reused.length) console.log(`已复用同版本的 ${plan.reused.length} 个未修改内容。`);
   for (const target of plan.targets) {
@@ -224,12 +259,13 @@ async function main() {
     console.log(`评测资料：${target.evalsDirectory}`);
     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}（尚未启用）`);
+    console.log(`Hooks：${target.hooksDirectory}${target.agents.includes('codebuddy')?'；统一检查：node "'+path.join(target.hooksDirectory,'manage.cjs')+'" check --host codebuddy --scope '+plan.scope+' --project "'+options.projectDir+'"':'；按宿主协议手动配置'}`);
   }
   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('安装完成。评测说明见 i3-composer-agent/evals/README.md；Hook 需按宿主事件协议启用。');
+  console.log('核心安装完成。评测说明见 i3-composer-agent/evals/README.md。');
+  if (hookChange) console.log(hookChange.summary.action === 'enable' ? `Hooks 已注册：${hookChange.summary.enabledGroups.join('、')}。${hookChange.summary.product === 'cli' ? '请在 CodeBuddy Code /hooks 审核并开启新会话。' : '请重载 CodeBuddy 窗口。'}实际触发另行检查。` : 'Hooks 保留现状；文件已提供不代表启用，请使用 hooks check 检查当前状态。');
   if (options.prototypeSkills !== undefined && options.prototypeSkills !== 'none') {
     try {
       // Shared project targets (for example CodeBuddy + WorkBuddy) prepare once.

package/bin/install.cjs

@@ -29,6 +29,7 @@ function globalSkillsDir(agent, home, env) {
   let base = home;
   if (config.base === 'config') base = env.XDG_CONFIG_HOME && path.isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : path.join(home, '.config');
   if (config.base === 'env') base = env[config.env]?.trim() || path.join(home, config.fallback);
+  if (config.env === 'CODEBUDDY_CONFIG_DIR' && (!path.isAbsolute(base) || /[\x00\r\n]/.test(base))) throw new Error('CODEBUDDY_CONFIG_DIR must be an absolute safe directory');
   if (config.alternatives && !fs.existsSync(path.join(home, path.dirname(config.path)))) {
     const alternative = config.alternatives.find(relative => fs.existsSync(path.join(home, path.dirname(relative))));
     if (alternative) return path.join(home, alternative);
@@ -51,7 +52,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: 3, entryPrefix: 'i3-', scope: plan.scope, agents: asset.target.agents,
-    capabilities: { nativeCommands: !!asset.target.nativeCommands, nativeAgents: !!asset.target.nativeCommands, hooks: 'manual' },
+    capabilities: { nativeCommands: !!asset.target.nativeCommands, nativeAgents: !!asset.target.nativeCommands, hooks: asset.target.agents.includes('codebuddy')?'codebuddy-managed':'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';
 }

package/bin/native-layout.cjs

@@ -78,7 +78,7 @@ function renderAsset(buffer, asset) {
     '本目录提供评测、校验、回归测试、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');
+    '`adapters/` 保留其他命令格式和插件清单，供原版一致性校验与回归测试使用，不自动注册或启用插件。CodeBuddy 通过 `hooks/manage.cjs` 统一管理原版三组和新增原型审计，默认不启用；其他宿主仍按各自协议配置。缓存与代码块保护分别详见 [hooks/SDD-CACHE.md](hooks/SDD-CACHE.md) 和 [hooks/SIMPLIFY-IGNORE.md](hooks/SIMPLIFY-IGNORE.md)，CodeBuddy 管理见 [docs/codebuddy-setup.md](docs/codebuddy-setup.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') {

package/bin/tool-selector.cjs

@@ -42,7 +42,7 @@ function wrap(text, columns) {
 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;
+  let frame = [], pageSize = 10, finished = false, numberInput = '';
   const wasRaw = Boolean(input.isRaw), wasFlowing = input.readableFlowing;
   const choices = () => view === 'common' ? [...orderedAgents.slice(0, commonIds.length), null]
     : view === 'more' ? orderedAgents.slice(commonIds.length)
@@ -71,8 +71,8 @@ function selectTools(initialSelection, input = process.stdin, output = process.s
     }
     const hints = searching
       ? ['输入关键词实时搜索', 'Enter/↓ 浏览结果 · Esc返回 · Ctrl-C取消']
-      : ['↑↓ 移动/跨页 · 空格勾选 · Enter确认', 'm 更多 · / 搜索 · b/← 返回 · q/Esc取消'];
-    const footer = ['', ...summary, ...hints.flatMap(line => wrap(line, columns)), message];
+      : ['数字+Enter指定工具 · ↑↓/空格勾选', 'm 更多 · / 搜索 · b/← 返回 · q/Esc取消'];
+    const footer = ['', ...summary, ...hints.flatMap(line => wrap(line, columns)), numberInput ? `编号：${numberInput}（逗号多选，Enter确认）` : 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));
@@ -130,19 +130,36 @@ function selectTools(initialSelection, input = process.stdin, output = process.s
           if (view === 'search') back(); else { cancel(); return; }
         } else if (text === 'q') { cancel(); return; }
         else if (['return', 'enter'].includes(key.name)) {
+          if (numberInput) {
+            if (numberInput === '0') { cancel(); return; }
+            const numbers = numberInput.split(/[,，]/).map(Number);
+            if (numbers.every(number => Number.isInteger(number) && number >= 1 && number <= orderedAgents.length)) {
+              selected.clear();
+              for (const number of numbers) selected.add(orderedAgents[number - 1].id);
+              finish([...selected]); return;
+            }
+            numberInput = ''; message = `请输入 1–${orderedAgents.length} 的编号（逗号多选），0 取消。`;
+            render(); return;
+          }
           if (selected.size) { finish([...selected]); return; }
-          message = '请至少用空格选择一个工具。';
+          message = '请用数字编号或空格选择工具，再按 Enter。';
+        } else if (text && /^[0-9,，]$/.test(text)) {
+          if (numberInput.length < 255) numberInput += text;
+        } else if (key.name === 'backspace') {
+          numberInput = numberInput.slice(0, -1);
         } else if (key.name === 'space' || text === ' ') {
+          if (numberInput) { render(); return; }
           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)) {
+          numberInput = '';
           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; }
+        } else if (text === 'm' || (key.name === 'right' && view === 'common')) { numberInput = ''; openMore(); }
+        else if (text === 'b' || key.name === 'left') { numberInput = ''; back(); }
+        else if (text === '/') { numberInput = ''; if (view === 'common') commonCursor = cursor; view = 'search'; query = ''; cursor = 0; searching = true; }
         render();
       } catch (error) { fail(error); }
     }

package/bin/wizard.cjs

@@ -1,6 +1,8 @@
 'use strict';
 
 const readline = require('node:readline');
+const fs = require('node:fs');
+const path = require('node:path');
 const { selectAgents } = require('./install.cjs');
 const { selectTools } = require('./tool-selector.cjs');
 
@@ -21,25 +23,88 @@ async function session(action) {
   try { return await action(ask); }
   finally { terminal.close(); }
 }
-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 cancelled = input => input === null || ['q', 'cancel', '取消'].includes(input.toLowerCase());
+const cancelled = input => input === null || ['0', 'q', 'cancel', '取消'].includes(input.toLowerCase());
+async function menu(ask, prompt, values, fallback) {
+  while (true) {
+    const answer = await ask(prompt);
+    if (cancelled(answer)) return null;
+    const key = answer || fallback;
+    if (Object.hasOwn(values, key)) return values[key];
+    console.log(`请选择数字 ${Object.keys(values).join('、')}，或 0 取消。`);
+  }
+}
+function existingInstallation(options, scope) {
+  const { base } = require('../hooks/manage.cjs').location({ scope, project: options.projectDir });
+  return ['.i3-composer-agent.json', 'settings.json', 'settings.local.json', 'state/i3-prototype/installation.json', 'state/i3-composer-agent/hooks.json']
+    .some(file => fs.existsSync(path.join(base, file)));
+}
+async function chooseSettings(options, agents, ask, services = {}) {
     let scope = options.scope;
     while (!scope) {
-      const input = await ask('安装范围：1. 项目（当前项目），2. 全局（所有项目）[1]（q/取消退出）： ');
+      const input = await ask('安装范围：1. 项目（当前项目），2. 全局（所有项目）[1]（0/q/取消退出）： ');
       if (cancelled(input)) return null;
       if (['', '1', 'project', '项目'].includes(input)) scope = 'project';
       else if (['2', 'global', '全局'].includes(input)) scope = 'global';
       else console.log('请选择 1（项目）或 2（全局）。');
     }
-    return { agents, scope };
-  });
+    let hooks=options.hooks||options.prototypeHooks||'keep',hookGroups=options.hookGroups||(options.prototypeHooks!==undefined?'prototype':undefined),codebuddyProduct=options.codebuddyProduct,codebuddyTranscriptRoot=options.codebuddyTranscriptRoot,codebuddySkillRouting=options.codebuddySkillRouting;
+    if (agents.includes('codebuddy') && agents.includes('workbuddy') && options.hooks === undefined && options.prototypeHooks === undefined) {
+      console.log('CodeBuddy 与 WorkBuddy 本次共享目录，保留现有 Hooks；需要启用时请在 CodeBuddy 独立范围配置。');
+    } else if (agents.includes('codebuddy')) {
+      if (options.hooks === undefined && options.prototypeHooks === undefined) {
+        const existing = (services.existingInstallation || existingInstallation)(options, scope);
+        const unsupported = process.platform === 'win32';
+        if (unsupported) console.log('Windows Hooks 引用尚未完成宿主验证，默认保留；核心技能仍可安装。');
+        const fallback = existing || unsupported ? '2' : '1';
+        hooks = await menu(ask, `CodeBuddy 统一 Hooks：1. 选择启用${existing || unsupported ? '' : '（首次安装推荐）'}，2. 保留现状${existing ? '（已有配置，推荐）' : ''} [${fallback}]（0 取消）： `, { '1': 'enable', '2': 'keep' }, fallback);
+        if (hooks === null) return null;
+      }
+      if (hooks === 'enable' && !hookGroups) {
+        console.log('Hook 组：1. 原型执行审计；2. Skill 发现与路由；3. 官方文档请求缓存；4. 代码块简化保护；5. 全部。');
+        while (!hookGroups) {
+          const answer = await ask('启用组：输入数字，可多选（例如 1,3,4）[1]（0 取消）： ');
+          if (cancelled(answer)) return null;
+          const numbers = (answer || '1').split(/[,，]/).map(x => x.trim());
+          if (numbers.every(x => ['1', '2', '3', '4'].includes(x))) hookGroups = [...new Set(numbers)].map(x => ({ '1': 'prototype', '2': 'session-start', '3': 'sdd-cache', '4': 'simplify-ignore' })[x]).join(',');
+          else if (numbers.length === 1 && numbers[0] === '5') hookGroups = 'all';
+          else console.log('请选择 1、2、3、4（可逗号多选），或 5（全部）。');
+        }
+      }
+      const chosen=require('../hooks/manage.cjs').selection(hookGroups,hooks);
+      if (hooks === 'enable' && !codebuddyProduct) {
+        codebuddyProduct = await menu(ask, 'CodeBuddy 形态：1. 桌面 IDE，2. CodeBuddy Code CLI [1]（0 取消）： ', { '1': 'ide', '2': 'cli' }, '1');
+        if (codebuddyProduct === null) return null;
+      }
+      if (hooks === 'enable' && chosen.includes('session-start')) {
+        if (!codebuddySkillRouting) {
+          codebuddySkillRouting = await menu(ask, 'Skill 路由：1. 需要 Hook 会话提示，2. 已有原生路由（自动去除 Skill 发现组）[1]（0 取消）： ', { '1': 'hook', '2': 'native' }, '1');
+          if (codebuddySkillRouting === null) return null;
+        }
+        if (codebuddySkillRouting === 'native') {
+          const remaining = chosen.filter(id => id !== 'session-start');
+          hookGroups = remaining.length ? remaining.join(',') : undefined;
+          if (!remaining.length) hooks = 'keep';
+          console.log('已选择原生路由，本次不新增 session-start；其余所选组保留，已有配置不会被移除。');
+        }
+      }
+      if(hooks==='enable'&&chosen.includes('prototype')&&!codebuddyTranscriptRoot)console.log('新启用的原型审计默认从 Hook 自动识别会话日志；升级保留已有手动限制。特殊环境可使用 --codebuddy-transcript-root <目录|auto>。');
+    }
+    let prototypeSkills = options.prototypeSkills;
+    if (prototypeSkills === undefined) {
+      console.log('可选原型依赖：所选项将联网下载官方固定版本，安装到本次宿主范围；已有可用内容复用。');
+      prototypeSkills = await menu(ask, 'UIUX / antDv：1. 两项都安装（推荐），2. 仅 UIUX，3. 仅 antDv，4. 跳过 [1]（0 取消）： ', { '1': 'uiux,antdv', '2': 'uiux', '3': 'antdv', '4': 'none' }, '1');
+      if (prototypeSkills === null) return null;
+    }
+    return { agents, scope, hooks, hookGroups, codebuddyProduct, codebuddyTranscriptRoot, codebuddySkillRouting, prototypeSkills };
+}
+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(ask => chooseSettings(options, agents, ask));
 }
-async function confirm(plan) {
+async function confirm(plan, selection = {}) {
   console.log(`\n安装范围：${plan.scope === 'project' ? '项目' : '全局'}`);
   for (const target of plan.targets) {
     console.log(`  ${target.agents.join(', ')}: ${target.skillsDirectory}`);
@@ -50,10 +115,19 @@ async function confirm(plan) {
   }
   if (plan.conflicts.length) console.log(`将替换 ${plan.conflicts.length} 个已有内容；安装成功后清理旧文件，失败则恢复。`);
   if (plan.reused.length) console.log(`将复用同版本的 ${plan.reused.length} 个未修改内容。`);
-  console.log('包含技能、共享资料和完整评测/Hook/脚本配套。安装不执行评测；Hook 需按宿主方式启用。');
+  if (selection.hooks) {
+    console.log(`CodeBuddy Hooks：${selection.hooks.action === 'enable' ? '启用 ' + selection.hooks.groups.join('、') : '保留现状'}${selection.hooks.product ? '；' + (selection.hooks.product === 'ide' ? '桌面 IDE' : 'CLI') : ''}。`);
+    if (selection.hooks.action === 'enable') console.log(selection.hooks.product === 'cli' ? '注册后仍需在 CodeBuddy Code /hooks 审核并开启新会话。' : '注册后请重载 CodeBuddy 窗口验证实际回调。');
+  }
+  if (selection.prototypeSkills !== undefined) console.log(`可选依赖：${selection.prototypeSkills === 'none' ? '跳过' : selection.prototypeSkills.split(',').map(id => id === 'uiux' ? 'UIUX Pro Max' : 'antDv 官方 Skill 与工具').join('、')}。`);
+  console.log('包含技能、共享资料和完整评测/Hook/脚本配套。安装不执行评测。');
   return session(async ask => {
-    const answer = await ask('确认安装这些内容？[y/N]： ');
-    return answer !== null && ['y', 'yes', '是', '确认'].includes(answer.toLowerCase());
+    while (true) {
+      const answer = await ask('确认安装这些内容：1. 开始安装，0. 取消 [0]： ');
+      if (answer === '' || cancelled(answer) || ['n', 'no', '否'].includes(answer.toLowerCase())) return false;
+      if (['1', 'y', 'yes', '是', '确认'].includes(answer.toLowerCase())) return true;
+      console.log('请选择 1 开始安装，或 0 取消。');
+    }
   });
 }
-module.exports = { choose, confirm };
+module.exports = { choose, chooseSettings, confirm };

package/docs/codebuddy-setup.md

@@ -48,7 +48,7 @@ CodeBuddy 与 WorkBuddy 项目共用 `.codebuddy/`；同版本追加客户端会
 npx @givolt/i3-composer-agent --codebuddy --scope project --yes --prototype-skills uiux,antdv
 ```
 
-值为 none、uiux、antdv 或 uiux,antdv；默认 none。可选工具跟随宿主和项目／全局范围，位于基址下 `tools/i3-prototype/`；旧项目 `.prototype-tools` 保持读取兼容。需要固定本次版本时使用 `npx @givolt/i3-composer-agent@2.3.2`。已安装后可随时单独检测／补装，无需重装 i3：
+值为 none、uiux、antdv 或 uiux,antdv；默认 none。可选工具跟随宿主和项目／全局范围，位于基址下 `tools/i3-prototype/`；旧项目 `.prototype-tools` 保持读取兼容。需要固定本次版本时使用 `npx @givolt/i3-composer-agent@2.3.3`。已安装后可随时单独检测／补装，无需重装 i3：
 
 ```bash
 node .codebuddy/skills/i3-ui-prototype/scripts/prototype-dependencies.cjs check --host codebuddy --scope project --project .
@@ -106,7 +106,30 @@ node .codebuddy/skills/i3-ui-prototype/scripts/native-pilot.cjs preview prototyp
 
 在业务项目运行 `node .codebuddy/i3-composer-agent/scripts/run-evals.js --min-rank1 95`，
 可检查中英文触发，不调用模型；进入 `.codebuddy/i3-composer-agent/` 可运行 `npm test` 和 `node scripts/run-evals.js --locale zh-CN --min-rank1 95`。全局安装使用脚本的全局绝对路径。五项校验、行为评测和样例用法见
-[评测说明](../evals/README.md)。Hook 文件已安装，需要按宿主协议单独启用。
+[评测说明](../evals/README.md)。Hooks 默认只分发，统一管理如下。
+
+## CodeBuddy 统一 Hooks 管理
+
+原版 `session-start`、`sdd-cache`、`simplify-ignore` 与新增 `prototype` 四组统一由安装器及 `.codebuddy/i3-composer-agent/hooks/manage.cjs` 管理。`i3-prototype.cjs` 是新增审计注册入口，委托 Skill 内原有实现；旧 helper 和 `--prototype-hooks` 参数保留。原版脚本保持，包装只处理宿主路径与输入字段。测试/说明文件不注册。
+
+```sh
+# 已安装后只读列举/检查，项目根运行
+node .codebuddy/i3-composer-agent/hooks/manage.cjs list --host codebuddy --scope project --project .
+node .codebuddy/i3-composer-agent/hooks/manage.cjs check --host codebuddy --scope project --project .
+# 单独启用缓存；全部选择用 --groups all 并满足所有组条件
+node .codebuddy/i3-composer-agent/hooks/manage.cjs enable --host codebuddy --scope project --project . --groups sdd-cache --product ide
+node .codebuddy/i3-composer-agent/hooks/manage.cjs disable --host codebuddy --scope project --project . --groups sdd-cache
+```
+
+全局改用 `~/.codebuddy/i3-composer-agent/hooks/manage.cjs` 和 `--scope global`，继续指定测试项目来判断有效来源。发行 CLI 可用 `hooks list|check|enable|disable` 子命令；安装时使用 `--hooks enable --hook-groups <ids>`，默认 keep 保留既有开关。启停不指定组时兼容旧用法仅针对 prototype，list/check 默认全部。
+
+`session-start` 需要明确 `--skill-routing hook`，已有原生路由时不选该组；安装器对应 `--codebuddy-skill-routing hook`。上游三组需要 Bash、jq 和相应 SHA 工具，缓存另需 curl，缺依赖会在启用前拒绝；不自动安装。prototype 需要真实 `--product ide|cli`；项目／全局新启用默认从 Hook 自动识别当前会话日志，可选 `--transcript-root <实际目录|auto>`。已有手动限制保留，首次尚无原生事件显示 awaiting-native-event，不能当成已验收。全局跟随绝对 CODEBUDDY_CONFIG_DIR，默认 ~/.codebuddy；不移动原生日志。原型严格证据规则见 Skill 的 execution-evidence 参考资料。
+
+配置合并到所选范围 `settings.json`，通用归属在 `state/i3-composer-agent/hooks.json`，原型归属保持 `state/i3-prototype/installation.json`。上游适配缓存在 `<host-base>/cache/i3-composer-agent/hooks/<projectKey>/`；全局按项目隔离。已识别的手动原版注册只报告，不自动接管或重复注册。代码块保护运行时会临时替换文件内容，存在未恢复备份时拒绝移除该组，先结束会话恢复。
+
+IDE 项目设置覆盖全局；CLI 合并后按组选择有效来源避免同组重复执行。CLI 变更后在原生 `/hooks` 审核并新建会话，IDE 重载。文件存在、注册、回调观察与业务验收分别显示；原版 triggered 不表示已验证模型行为。首期仍待用户实际宿主验收，Windows Hooks 未验证，默认不启用的核心安装不受此限制。
+
+依据：[CodeBuddy IDE Hooks](https://www.codebuddy.cn/docs/ide/Features/Hooks)、[CodeBuddy CLI Hooks](https://www.codebuddy.cn/docs/cli/hooks)。
 
 ## 通过 CodeBuddy Code 插件管理器安装
 
@@ -133,3 +156,5 @@ npx @givolt/i3-composer-agent --prepare --codebuddy
 目录遵循 [配置目录参考](https://www.codebuddy.cn/docs/cli/codebuddy-dir)，可参照
 [IDE Skills](https://www.codebuddy.cn/docs/ide/Features/Skills) 与
 [自定义命令](https://www.codebuddy.cn/docs/ide/User-guide/Slash-Commands) 检查发现与调用。
+
+原型共享资料统一在项目 prototypes/：新索引 prototypes/index.json，准备范围 prototypes/.preparation/<id>/scope.json。新原生 scope.moduleIds 自动生成 appliesTo；旧索引、输入和实例保持兼容，安装升级不自动迁移。工具及运行缓存使用所选宿主基址；全局浏览器缓存按业务项目身份隔离。详细规则和只读查询／显式迁移命令见 i3-ui-prototype/references/project-layout.md。

package/docs/codex-setup.md

@@ -37,4 +37,6 @@ Codex 已有原生技能路由，勿把元技能全文预加载为常驻上下
 
 ## 可选原型工具
 
-原型辅助工具位于本宿主基址的 `tools/i3-prototype/`，支持项目和全局范围；旧项目 `.prototype-tools` 继续读取兼容。项目安装可使用 `npx @givolt/i3-composer-agent@2.3.2 --codex --scope project --yes --prototype-skills uiux,antdv`；全局安装将 scope 改为 global。可选依赖默认 none，后续也可使用已安装 Skill 的 prototype-dependencies.cjs 单独检测／补装。完整用法见原型 Skill 的 references/optional-skills.md。
+原型辅助工具位于本宿主基址的 `tools/i3-prototype/`，支持项目和全局范围；旧项目 `.prototype-tools` 继续读取兼容。项目安装可使用 `npx @givolt/i3-composer-agent@2.3.3 --codex --scope project --yes --prototype-skills uiux,antdv`；全局安装将 scope 改为 global。可选依赖默认 none，后续也可使用已安装 Skill 的 prototype-dependencies.cjs 单独检测／补装。完整用法见原型 Skill 的 references/optional-skills.md。
+
+原型共享资料统一在项目 prototypes/：新索引 prototypes/index.json，准备范围 prototypes/.preparation/<id>/scope.json。新原生 scope.moduleIds 自动生成 appliesTo；旧索引、输入和实例保持兼容，安装升级不自动迁移。工具及运行缓存使用所选宿主基址；全局浏览器缓存按业务项目身份隔离。详细规则和只读查询／显式迁移命令见 i3-ui-prototype/references/project-layout.md。

package/docs/other-hosts.md

@@ -6,7 +6,7 @@
 
 ## 使用本地分发目录
 
-以下命令使用完整分发包解压目录里的 CLI，适用于本地测试和离线接入。`/absolute/path/to/package` 均替换为实际解压目录；已发布版本也可使用 `npx @givolt/i3-composer-agent@2.3.2` 的对应入口。
+以下命令使用完整分发包解压目录里的 CLI，适用于本地测试和离线接入。`/absolute/path/to/package` 均替换为实际解压目录；已发布版本也可使用 `npx @givolt/i3-composer-agent@2.3.3` 的对应入口。
 
 ### fx
 

package/docs/ui-prototype-native/USAGE.md

@@ -49,12 +49,12 @@ node .codebuddy/skills/i3-ui-prototype/scripts/native-pilot.cjs template-page --
 
 ## 需求范围与创建
 
-主会话根据实际 PRD 整理 .prototype-preparation/assets/scope.json：逐页声明业务标题、referencePage、区域类型、需求原文及来源。列表适用查询、复选、分页、批量与状态反馈；编辑区域适用校验、保存失败保留和重试。豁免须有明确需求依据。不能漏报实际区域来逃避能力。
+主会话根据实际 PRD 整理 schemaVersion=2 的 prototypes/.preparation/assets/scope.json，moduleIds 填实际模块 ID（未关联填 []），索引 appliesTo 自动去重生成：逐页声明业务标题、referencePage、区域类型、需求原文及来源。列表适用查询、复选、分页、批量与状态反馈；编辑区域适用校验、保存失败保留和重试。豁免须有明确需求依据。不能漏报实际区域来逃避能力。
 
 新原型默认提供明亮、暗黑、清新、科技，默认明亮，无编号。列表默认可调分页 10／20／50，默认 10；在 scope 的区域参数中明确覆盖真实需要。旧实例仍按原有固定输入，不追溯修改。
 
 ```sh
-node .codebuddy/skills/i3-ui-prototype/scripts/native-pilot.cjs create --project . --id assets --scope .prototype-preparation/assets/scope.json --host codebuddy
+node .codebuddy/skills/i3-ui-prototype/scripts/native-pilot.cjs create --project . --id assets --scope prototypes/.preparation/assets/scope.json --host codebuddy
 # 仅在明确选择基础模板模式后，增加 --expert-mode template。
 ```
 
@@ -89,3 +89,5 @@ node .codebuddy/skills/i3-ui-prototype/scripts/native-pilot.cjs state prototypes
 新会话先 state 恢复身份、范围、模式、构建与证据，按 nextAction 继续，不重新生成覆盖。已有 v1 HTML 与旧 v2 原生实例按原合同检查，保留原摘要、手改和认可基线；小模板仅保留测试夹具，旧设备框架起点在 legacy-starter，不作为新生成入口。
 
 最终回复给出原型路径、范围、revision、实际模式、已执行检查、证据及未决项。完成本地技术验证仍为 pending-review，人工认可具体 revision／digest 后才能冻结基线；不把骨架、安装通过或自填报告当作业务完成。
+
+共享索引为 prototypes/index.json，旧根索引保持兼容。只安装不创建业务目录；全局 Skill 仍把原型留在业务项目，缓存按宿主与项目隔离。查询、同步、显式迁移和浏览器输出命令见 Skill 的 references/project-layout.md。

package/docs/workbuddy-setup.md

@@ -85,4 +85,6 @@ npx @givolt/i3-composer-agent --workbuddy --scope global --yes --force
 
 ## 可选原型工具
 
-原型辅助工具位于本宿主基址的 `tools/i3-prototype/`，支持项目和全局范围；旧项目 `.prototype-tools` 继续读取兼容。推荐使用 `npx @givolt/i3-composer-agent@2.3.2 --workbuddy --scope global --yes --prototype-skills uiux,antdv`；项目安装将 scope 改为 project。可选依赖默认 none，后续也可使用已安装 Skill 的 prototype-dependencies.cjs 单独检测／补装。完整用法见原型 Skill 的 references/optional-skills.md。
+原型辅助工具位于本宿主基址的 `tools/i3-prototype/`，支持项目和全局范围；旧项目 `.prototype-tools` 继续读取兼容。推荐使用 `npx @givolt/i3-composer-agent@2.3.3 --workbuddy --scope global --yes --prototype-skills uiux,antdv`；项目安装将 scope 改为 project。可选依赖默认 none，后续也可使用已安装 Skill 的 prototype-dependencies.cjs 单独检测／补装。完整用法见原型 Skill 的 references/optional-skills.md。
+
+原型共享资料统一在项目 prototypes/：新索引 prototypes/index.json，准备范围 prototypes/.preparation/<id>/scope.json。新原生 scope.moduleIds 自动生成 appliesTo；旧索引、输入和实例保持兼容，安装升级不自动迁移。工具及运行缓存使用所选宿主基址；全局浏览器缓存按业务项目身份隔离。详细规则和只读查询／显式迁移命令见 i3-ui-prototype/references/project-layout.md。