@givolt/i3-composer-agent 2.3.1 → 2.3.3

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/commands/i3-prototype.toml

@@ -1,5 +1,5 @@
-description = "选择模板并生成、评审和迭代交互原型，维护已确认的 UI 基线。"
-# i3-description-source: "description = \"Create, review and iterate interactive UI prototypes with template selection and approved baselines\""
+description = "在主会话中分析、创建、检查与迭代 UI 交互原型。"
+# i3-description-source: "description = \"Create, analyze, inspect and iterate UI prototypes in the main session\""
 
 prompt = """
 <!-- i3:zh-CN:start -->
@@ -10,14 +10,12 @@ prompt = """
 Skill/Command/Agent 标识、文件路径、命令参数、代码/API 名称、工具调用参数、JSON 键/类型/枚举、机器状态、测试期望字面量及引用原文保持原样。生成文档正文用中文，SPEC.md、tasks/plan.md、tasks/todo.md、CONSTRAINTS.md 等约定路径不改名。
 严重程度按原规则判断，面向用户可写“严重（Critical）”“必须修复（Required）”“小问题（Nit）”“可选（Optional）”“建议考虑（Consider）”“仅供参考（FYI）”；High/Medium/Low、APPROVE/REQUEST CHANGES 和 GO/NO-GO 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
 
-适用说明：选择模板并生成、评审和迭代交互原型，维护已确认的 UI 基线。
+适用说明：在主会话中分析、创建、检查与迭代 UI 交互原型。
 <!-- i3:zh-CN:end -->
 
-Invoke the i3-ui-prototype skill.
+Use the i3-ui-prototype skill in the main session for the user's request below. Follow its shared preflight, operation boundaries and applicable runtime workflow.
 
 $ARGUMENTS
 
-With no arguments, use create. Supported operations: create, revise, inspect, confirm-baseline.
-Default to professional enhancement mode. Detect UI/UX Pro Max in the current host; if unavailable, offer installation or explicit template mode. Never silently downgrade.
-Use the skill workflow for template selection, business mapping, professional advice, real browser verification and version-specific human confirmation. Preserve approved snapshots during iteration.
+With no arguments use create; explicit analysis or read-only limits take precedence. Preserve the user's scope, manual edits, fixed inputs and approved baselines. Use supporting engineering, framework, design and browser skills as the working skill requires; keep its workflow and evidence requirements there.
 """

package/docs/codebuddy-setup.md

@@ -9,7 +9,7 @@ npx @givolt/i3-composer-agent --codebuddy
 ```
 
 向导预选 CodeBuddy，可增加其他工具，再选择项目或全局范围。
-项目安装提供 `.codebuddy/skills/`（26 个技能）、`references/`、
+项目安装提供 `.codebuddy/skills/`（26 个技能）、
 `commands/`（10 个命令）和 `agents/`（4 个角色）。
 同级 `i3-composer-agent/` 是配套工具根，集中提供 `package.json`、`evals/`、`hooks/`、`scripts/`、`docs/`、`references/` 和校验输入 `adapters/`，
 只有一份实际技能、命令和角色，评测与宿主共用。
@@ -25,9 +25,10 @@ npx @givolt/i3-composer-agent --codebuddy
 /i3-build auto
 /i3-review
 /i3-ship
+/i3-prototype
 ```
 
-命令直接调用安装的技能 ID，保留 `$ARGUMENTS`、原工程规则和审批边界。
+命令保留 `$ARGUMENTS`、原工程规则和审批边界。原型命令由主会话使用 `i3-ui-prototype`，其他命令沿用各自流程。
 发布命令按宿主能力并行审查或顺序降级，主会话汇总并提供回滚计划。
 
 ```bash
@@ -39,11 +40,96 @@ CodeBuddy 与 WorkBuddy 项目共用 `.codebuddy/`；同版本追加客户端会
 全局目录彼此独立。WorkBuddy 桌面版建议全局安装，详见 [WorkBuddy 说明](workbuddy-setup.md)。
 升级或同名冲突先查看 `--dry-run`，再确认或使用 `--yes --force`。
 
+## 原型官方依赖可选安装
+
+默认安装仅包含 i3 自身技能，UIUX Pro Max 与 antDv 官方 Skill 可不安装。CodeBuddy 项目安装可明确选择：
+
+```bash
+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.3`。已安装后可随时单独检测／补装，无需重装 i3：
+
+```bash
+node .codebuddy/skills/i3-ui-prototype/scripts/prototype-dependencies.cjs check --host codebuddy --scope project --project .
+node .codebuddy/skills/i3-ui-prototype/scripts/prototype-dependencies.cjs install --host codebuddy --scope project --project . --skills uiux,antdv
+```
+
+检测只读，不下载安装。安装需要网络，固定官方版本并保留原名与来源，已有可用安装复用；已有不可用目录保留并提示修复，不自动覆盖、全局升级或安装 Python。UIUX 专业模式缺项时提示，用户明确选择基础模式后仍可生成并保留同样功能验收；antDv Skill 缺失可按官方版本资料渠道实施。后续安装不改变已有实例模式或旧验收，CodeBuddy 必要时重载窗口／新建会话。目录与检测通过不等于宿主实际调用。
+
+## 主会话原型流程与使用入口
+
+原型由主会话使用 `.codebuddy/skills/i3-ui-prototype/`，按同一方法完成需求理解、设计、制作、修订与验证。Skill 保存模板、能力、框架和验收规则；按任务需要复用前端工程方法、官方框架知识、UIUX Pro Max 和浏览器测试能力。HTML 是内容参考，生成结果采用真实框架组件。
+
+模板编辑、构建、证据登记和后续修改的完整命令见[首期使用与续接](ui-prototype-native/USAGE.md)。
+
+自然语言可以这样提出任务：
+
+> 根据资产清单需求，参考完整 enterprise-admin 内容模板，用 Vue 3＋antDv-next 生成交互原型。保留筛选、多选、分页和编辑抽屉，验证失败重试、开合动效和遮罩模糊。请使用 UIUX Pro Max 优化体验，交付待评审候选。
+
+或明确使用命令：
+
+```text
+/i3-prototype analyze 先检查需求与内容模板，不修改任何文件
+/i3-prototype create 参考完整 enterprise-admin 模板，用 Vue 3＋antDv-next 生成资产清单原型
+```
+
+自然语言、`/i3-prototype`、已加载的 `i3-using-agent-skills` 和直接使用 `i3-ui-prototype` 都进入同一主会话流程。`i3-using-agent-skills` 按普通技能发现选择工作 Skill；命令只提供快捷入口。普通安装不注册原型专责角色，也不安装常驻原型分派规则。命令菜单、Skill 被读取和真实执行分别验证；CodeBuddy IDE 与 CodeBuddy Code CLI 的证据不能互相替代。
+
+直接使用方法也是正式入口：说“请当前会话使用 i3-ui-prototype 技能，只读分析这个原型”。主会话交付自然语言分析、候选与真实证据，不以父子 Agent JSON 或回传标记为前置。只读分析不写入；原型基线认可需真实用户认可，后续工程仍按现有规格、计划和实现流程交接。
+
+升级只退出清单归属明确且内容匹配已知原型增量的旧角色和旧入口规则。旧入口经过用户修改或来源未知时保留原文件并停止安装，提示人工检查；`--force` 不绕过此保护。同名用户自建 Agent 保留并报告。这样可以在升级前明确处理仍可能生效的旧常驻规则。
+
+默认只读使用 Skill 内置模板，模板由维护者在 Skill 源码中修改并随包发布；业务项目不默认生成 ui-templates。生成的真实组件工程在 `prototypes/<id>/app/`，业务修改直接作用于该工程，生成依据固定在 inputs。已有模板副本仅在明确指定 --template-root 时复用并保留手工修改。按实际 PRD 固定页面、区域和适用能力；旧原型按原合同继续读取，不自动迁移。professional 默认使用真实 UIUX 查询；明确选择 template 时仍完成同样功能验收，不声称使用了 UIUX。
+
+框架官方 antdv Skill 是独立知识来源，按本次版本和授权接入，不随本包安装而自动全局安装或升级 CLI。首期固定库 1.5.3；已探测的 CLI 0.0.0-beta.1 没有该知识文件，显式回退查询 1.5.2 只能作参考，再核对 1.5.3 包内类型／源码。错误文本或退出码 0、仅打印 Parsed args 的 lint，均不能作为查询或验收通过。
+
+工具前置使用依赖检测返回的实际 Node 入口，也兼容已有 `.prototype-tools/node_modules` 布局或宿主明确的绝对入口；缺失时只读分析报告未决项，不以 npm exec／npx 下载或补缓存。工具准备须有明确选择，写范围仅指定工具目录，不含业务内容或 SDK。analyze 只交覆盖、选型、验收计划和缺口，不套用创建阶段的 UIUX 采纳、构建或浏览器门禁。
+
+本轮新原生流程还要求执行者真实调用 `i3-browser-testing-with-devtools` Skill，并使用 Chrome DevTools MCP 对当前构建取得 DOM／计算样式、截图、console、network、可访问性和性能观测。只读取 Skill 文件或运行 Playwright 脚本都不等于调用该 Skill；Playwright 保留为原型专项补充。缺可调用 Skill 或 MCP 时整链不 complete，按已授权范围准备宿主工具后再验；analyze 不启动或安装浏览器。具体工具接入以实际宿主暴露为准，不能从其他会话或维护 smoke 推断当前执行环境可用。旧实例按固定合同保留，其他宿主等效结果单列。
+
+新完整模板原生流程默认包含明亮、暗黑、清新、科技，首次默认明亮，菜单无编号；生成工程用原生框架主题，验证四预设、刷新记忆、实例隔离及业务状态保留。旧实例继续按原有固定合同，不隐式增加能力；步骤见首期指南。
+
+## 原型本地检查与预览
+
+以下使用项目安装路径，原型目录替换为实际值。首次构建允许安装依赖时使用 --install；后续复用依赖构建。预览命令持续运行并输出本地 URL。
+
+```bash
+node .codebuddy/skills/i3-ui-prototype/scripts/native-pilot.cjs inspect prototypes/device-list
+node .codebuddy/skills/i3-ui-prototype/scripts/native-pilot.cjs build prototypes/device-list --install
+node .codebuddy/skills/i3-ui-prototype/scripts/native-pilot.cjs preview prototypes/device-list
+```
+
+真实浏览器执行场景后，使用 inspect --acceptance 核对当前候选、实际构建和证据引用。检查通过仍待用户评审。只读分析不执行以上写入构建步骤，也不安装、持久化设计或更新原型状态。
+
 ## 配套检查
 
 在业务项目运行 `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 插件管理器安装
 
@@ -70,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

@@ -34,3 +34,9 @@ Codex 短命令适配是独立的宿主能力，不影响技能中文化与品
 Codex 已有原生技能路由，勿把元技能全文预加载为常驻上下文。
 元技能仍可安装并按需显式调用。CLI 保留已有插件设置；测试本地目录时使用绝对路径。
 文件安装、宿主发现与实际模型工作流分别验证。
+
+## 可选原型工具
+
+原型辅助工具位于本宿主基址的 `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.1` 的对应入口。
+以下命令使用完整分发包解压目录里的 CLI，适用于本地测试和离线接入。`/absolute/path/to/package` 均替换为实际解压目录；已发布版本也可使用 `npx @givolt/i3-composer-agent@2.3.3` 的对应入口。
 
 ### fx
 

package/docs/ui-prototype-native/MAIN-SESSION-REPORT.md

@@ -0,0 +1,66 @@
+# 主会话原型改造验证报告
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+日期：2026-10-17。源码分支：feature/prototype-native-pilot。首期为CodeBuddy＋admin-list小模板＋Vue 3/antDv-next设备流程。实施及样例技术验收完成，补充复核后的当前收据已完成；用户视觉/业务评审仍为pending-review。正式main与上游保全基线未变，未合并或发布。
+
+## 已完成改造
+
+取消prototype-specialist专责Agent、常驻分派规则及父子JSON强制；自然语言、using、/i3-prototype、直接Skill均由主会话执行。using以原版aeac41d4为基线，只增加普通原型分支和Quick Reference行；移除两行后SHA256为30787ef2c77bf1a4729fffed0f6523ba6fcbe81bdc436b36371b78c21394d3c3。三宿主命令格式仍是薄入口，不承担企业调度。
+
+企业SOP在外层组织PRD、设计取舍、制作、技术验证、人工认可与工程交接；原型Skill按需复用前端、官方框架、UIUX和浏览器方法。业务/技术规格、任务tracker及正式发布仍依上游方法，不增加企业审批库或专属Agent。
+
+HTML继续可离线修改，是内容和能力输入。生成原型采用真实ConfigProvider/Table/Form/Drawer等组件；本次需求明确绑定“明亮、暗黑、清新、科技”，首次默认明亮，页面内切换，不重挂应用或丢失筛选/页码/选择/未保存输入。旧HTML及未绑定主题的固定实例不自动加入主题、不重写摘要。模板内容和最终框架效果分别验证。
+
+已有安装按清单归属＋已审原字节指纹安全退出旧角色/规则；修改过、来源不明的受管退出资产会阻断，force不绕过；用户文件保留。维护宿主工具不自动成为上游/全局Hook。
+
+## 主要实证
+
+证据根：工作区artifacts/verification/prototype-main-session-20261017/。
+
+| 范围 | 实际结果 | 证据 |
+|---|---|---|
+| 源码与分发 | 全回归528/528、零跳过；实际打包/安装各340/340；最终冻结复验以相邻JSON/log为准 | source-final-guidance.*、source-delivery-final.*、candidate-3-*-test.*、delivery-package/ |
+| 退出与升级 | 真实旧tgz→新tgz项目/global角色5→4，用户规则保留；16项迁移保护通过 | installation/real-upgrade-RESULT.json |
+| 离线HTML | 实际断网file://修改、展示、同步提取，3本地请求、0外部请求/console错误，未起服务 | offline-html-check/ |
+| CLI四入口 | 真实Skill调用、完整分析回传，无Agent；734文件前后同一，SDK/工具/缓存未变 | ENTRY-MATRIX.json、probe-*/ |
+| CodeBuddy IDE入口 | 实际识别/展开命令、UseSkill及主会话中文回传，732安装文件比较无异常差异 | ide-command/ |
+| 全新业务冷生成 | 100工具/22MCP，无Agent，processComplete=true；官方/前端/browser Skill及真实UIUX查询/设计/构建；7/7单测、类型与构建通过 | cold-main-session-v2/、cold-v2-preflight.json |
+| 完整原型专项 | 23/23、零console错误/警告，同一candidate/build，含四主题/状态/偏好/隔离、Drawer动效/毛玻璃/焦点、窄屏/键盘和故障对照 | cold-project-v2/prototypes/main-devices/qa/runs/chrome-1792253902290/ |
+| UIUX实际Skill复查 | Skill(ui-ux-pro-max)真实加载，31工具，零文件/缓存变更；采纳/拒绝与效果分别核对，无阻断 | uiux-final-review/ |
+| 真实交互DevTools补录 | 实际browser Skill，44次MCP/51工具，trace含13 click/1 input，六类观测与操作后console/network已保存；48轮上限后无最终模型回复，未算该轮自动完成 | devtools-interaction-supplement/ |
+| 独立输入/焦点诊断 | 实际固定MCP原生Backspace恢复21；空名保存拒绝、错误/焦点/抽屉/列表均正确，console0 | mcp-empty-fill-diagnostic/run-006/ |
+| 审定与交付 | 原始事件审计、修正登记后build/browser/devtoolsReview/delivery均current，nextAction=return-result；passed、pending-review | FINAL-COLD-AUDIT.json、audited-state-final.json、实例qa/delivery.json |
+| 兼容保护 | 337摘要/模式未变、原先REPORT/TASKS字节前缀保留；旧v1/v2固定合同不追随新模板 | protected-current.json |
+
+当前原型：main-devices/r001，candidateDigest=793e0a1eee86bad6e9a081548840cc6408aded05347fa8485f050611f71f1954；buildId=b-193a4dfa2f1be867ceb1，buildDigest=193a4dfa2f1be867ceb103690bdc451ceabcbee0ef29875d388fc420c88f637c。
+
+## 发现、修复与证据纠正
+
+真实冷运行发现原生分页内部隐藏链接仍能获得焦点。中央starter只将page项渲染为不可聚焦span，保留外层LI及鼠标/键盘；新固定快照启用paginationFocusGuard，旧快照缺字段维持原合同。AX普通鼠标可复现、故障负例能失败、修复后的23项与零候选warning均有实证。
+
+CodeBuddy2.168.2初层fill参数scalar与后层完整对象换ID格式，维护宿主已做极窄兼容（固定managed1.11.0、非只读、精确PreToolUse和fill），19/19及独立审查通过，实际新补录也无auditDenied。不能据此建立通用跨层deny绑定保证；实际文件边界另由OS策略及差异证明，不扩大写目录，不改上游Hook/全局配置。
+
+独立审计发现初版模型报告的时区错误、调用ID占位、MCP网络摘要和冷缓存措辞不实，性能trace只覆盖reload。原始字节与原最终回复保留，未接受其自评结论。当前报告从真实UTC/call_*生成；MCP仅确认URL/状态，真实响应字节SHA来自独立Playwright观测。UIUX原生成有provider查询但没有Skill调用，真实Skill复查由后续只读阶段完成，不改写历史。
+
+补录的完整五分钟交互trace解压70,406,491字节，登记器64MiB边界正确拒绝。原件未改；以明确标注来源、摘要和窗口的前120秒连续原事件导出登记（34,338,470字节、7 click/1 input），不改上限、不筛事件类别、不宣称该片段就是完整录制。索引在实例qa/devtools/audited/trace-excerpt-index.json。
+
+另独立复现固定MCP1.11.0的空fill直接清DOM而未发input/change：查询/校验仍读旧绑定。正常键盘/Playwright为空可正确工作。真实MCP以当前文本和末尾光标为准逐次Backspace验证通过；Meta+A/Control+A未全选、空格可能追加旧值等失败保留。自有Skill已补实测指引，上游浏览器Skill/MCP/组件库不改。该工具事件问题与宿主scalar参数兼容分别记录。诊断run-004在抛弃的独立profile中误做一次非空保存已披露；通过run-006无成功保存，应用文件、共享模型profile、旧QA均未变。
+
+第一次源码/机械浏览器失败、第一次冷生成120轮未完、维护者误期待revise自动刷新快照而停止的阶段、补录48轮上限、客户端参数/解析错误、64MiB拒绝均保留。revise只接受已整理输入摘要，不自动迁移framework；旧实例未手补新字段。
+
+## 结论边界
+
+首期样例经过实际主会话制作、专项回归及补充复核后具备待评审交付条件。不能扩展为所有模型/宿主/页面或单轮无人复核都可靠。短种子未触发长文本ellipsis的专门视觉用例，未声称该效果已经实测。技术验证不代替人类认可，不执行confirm-baseline。
+
+四CLI入口和IDE入口来自C1；C2的using/三命令字节相同，C2完成新业务冷生成。其后仅自有输入事件指引与维护文档修订；最终包与C2实现/模板/框架/浏览器执行器/入口的字节比较、精确包摘要和最终打包/安装结果以delivery-package/及FINAL-PACKAGE.json为准，不冒认最终说明版本另跑了一次完整冷生成。
+
+只读CLI的工具限制、OS写保护及零缓存结论不外推到任意IDE/全工具配置；IDE实际界面请求保留无害残留前缀，项目根重定位只归一确切安装路径，不对用户级会话日志宣称零写入。可写冷生成使用独立npm缓存产生正常依赖缓存/日志；SDK与固定工具未改。
+
+本次改造提交保留在试点分支，未安装覆盖用户现有全局环境、未合并、未发布。最终可预览当前候选，仍需用户针对明确revision/digest进行业务和视觉评审。

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

@@ -0,0 +1,93 @@
+# 原型制作与续接
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+当前默认内容模板为完整企业管理后台，生成目标为 Vue3＋antDv-next。HTML 参考可以离线编辑；生成的框架工程需要安装依赖、构建并启动预览。安装方式见 [CodeBuddy 说明](../codebuddy-setup.md)。
+
+## 在 CodeBuddy 发起
+
+```text
+/i3-prototype analyze 根据 PRD 分析原型范围和模板适用能力，先不写入或安装
+/i3-prototype create 根据 PRD，参考完整 enterprise-admin 模板，生成 Vue3＋antDv-next 原型，ID 为 assets
+```
+
+自然语言、命令、using 选择及直接调用 Skill 均由主会话执行，无原型专责 Agent。using 按普通发现逻辑选择原型 Skill；原型流程按阶段复用前端、官方框架、UIUX 和浏览器能力，避免一次加载全部模板、依赖源码及历史日志。
+
+只读分析交付覆盖、选型、验收计划及缺口，不创建原型、安装依赖、启动浏览器或保存用户级记忆。创建／修订的写入限于本次项目与明确范围，长期记忆、全局配置及其他项目另需明确授权。
+
+## 可选官方 Skill 与后续检测
+
+从业务项目根运行：
+
+```sh
+node .codebuddy/skills/i3-ui-prototype/scripts/prototype-dependencies.cjs check --project .
+# 以下仅在明确选择安装后执行，可单独选 uiux 或 antdv：
+node .codebuddy/skills/i3-ui-prototype/scripts/prototype-dependencies.cjs install --project . --skills uiux,antdv
+```
+
+i3 默认不安装这两项依赖，跳过不永久禁用。后续补装后重新检测即可，无需重装 i3；必要时重载 CodeBuddy 窗口或新建会话让宿主发现。已有可用全局 UIUX 可复用，已有第三方技能和工具不覆盖。缺 Python 仅报告，不安装系统运行环境。官方正文、许可、版本和来源保留，详情见已安装 Skill 的 references/optional-skills.md。
+
+UIUX 专业模式为默认，缺少可用查询资源会提示，不静默降级；用户明确选择基础模板模式后仍完成同样业务功能、四主题和验收。安装依赖不会自动改变既有原型的模式、源码或证据。检测不代表真实宿主调用；CodeBuddy 仍须通过其 Skill 工具实际加载。
+
+antDv 官方 Skill 和组件库是独立部分：未安装 Skill 时可使用对应版本官方文档／类型／源码，记录实际渠道；生成工程仍需 antDv-next 库。新工具目录为对应宿主基址下的 tools/i3-prototype/antdv-cli，支持项目和全局安装；旧 .prototype-tools/antdv-cli 保留读取兼容；只读检测返回可执行的 Node 入口，也识别既有 .prototype-tools/node_modules 布局。固定 CLI 0.0.0-beta.1 的 1.5.2 知识仅作参考，目标组件库 1.5.3 仍核对实际类型／源码。不自动升级 CLI，不以 Error 文本、exit 0 或占位 lint 代替成功。
+
+## 内置模板与业务原型
+
+```sh
+node .codebuddy/skills/i3-ui-prototype/scripts/native-pilot.cjs template-page --page models-page
+```
+
+默认只读使用 Skill 安装目录 assets/templates/enterprise-admin 中随版本发布的完整模板，业务项目不生成 ui-templates。可双击内置 index.html 离线查看；模板内容由维护者在 Skill 源码中修改、校验并随包发布，业务使用期间不修改安装目录。索引在内存只读计算，随生成时的模板、范围与能力快照固定到 inputs。业务修改直接落在 prototypes/<id>/app/，Skill 升级不隐式改写已有原型。
+
+只读取本次相关页面。完整索引提供参考页面、路由和资源清单，不表示自动理解或实现全部旧业务。已有 ui-templates 副本保留，不自动读取、覆盖或删除；明确需要其手工内容时，先显式 sync-template 该副本，再在 create 时传 --template-root <已有目录>。旧 prepare-template 命令继续用于兼容，不是新流程必需步骤。
+
+## 需求范围与创建
+
+主会话根据实际 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 prototypes/.preparation/assets/scope.json --host codebuddy
+# 仅在明确选择基础模板模式后，增加 --expert-mode template。
+```
+
+必须提供有来源的 scope，不再自动回退设备演示需求。目标存在时先读取 state，按修订流程保留已有手改，不重新 create。初始化仅提供需求对应的原生框架骨架和主题，business.status 为 needs-adaptation；主会话继续实现实际业务页面、字段、模拟数据和交互后才可验收。
+
+## 实现、构建与真实验收
+
+按需使用 i3-frontend-ui-engineering、可调用的 antDv 官方 Skill、UIUX 查询和取舍。官方 Skill 可调用时先实际加载；无法调用时记录官方资料等效渠道。UIUX 的加载、真实查询、建议采用与效果验证分别有依据。
+
+```sh
+node .codebuddy/skills/i3-ui-prototype/scripts/native-pilot.cjs state prototypes/assets
+node .codebuddy/skills/i3-ui-prototype/scripts/native-pilot.cjs build prototypes/assets --install
+node .codebuddy/skills/i3-ui-prototype/scripts/native-pilot.cjs preview prototypes/assets
+```
+
+首次且允许安装工程依赖时用 --install，之后复用已安装依赖。业务流程覆盖查询、多选、分页、编辑抽屉、校验失败、提交失败、重试保存及列表同步；另验抽屉进入／退出、模糊遮罩、四主题保留状态、窄屏、键盘与焦点恢复。
+
+主会话实际加载 i3-browser-testing-with-devtools，通过 Chrome DevTools MCP 对当前构建检查 DOM／计算样式、截图、console、network、可访问性及性能。缺少工具时保留未验证；读取 Skill、只有截图或运行补充脚本不能冒充该链路通过。浏览器使用项目 localhost 和隔离测试环境。
+
+按 inputs/acceptance.json 的本次业务场景实测，保存真实报告，再登记：
+
+```sh
+node .codebuddy/skills/i3-ui-prototype/scripts/native-pilot.cjs record-run prototypes/assets --report /absolute/path/actual-business-report.json
+node .codebuddy/skills/i3-ui-prototype/scripts/native-pilot.cjs record-devtools-review prototypes/assets --report /absolute/path/actual-devtools-report.json
+node .codebuddy/skills/i3-ui-prototype/scripts/native-pilot.cjs state prototypes/assets
+```
+
+从 state 取得当前准确的 finalize／revise 命令；不要复用修改前摘要。结构校验及报告导入不证明真实 Skill 调用，仍须核对原始宿主调用记录。源码或固定输入变化后重建并重验受影响场景。native-pilot 的历史 browser 子命令仅服务旧设备合同，不适用于新完整模板业务。
+
+## 续接、兼容与交付
+
+新会话先 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

@@ -82,3 +82,9 @@ npx @givolt/i3-composer-agent --workbuddy --scope global --yes --force
 [命令格式](https://www.codebuddy.cn/docs/cli/slash-commands) 和
 [项目目录说明](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Project)。
 目录落盘、发现与模型行为分别验收。
+
+## 可选原型工具
+
+原型辅助工具位于本宿主基址的 `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。

package/evals/cases/i3-frontend-ui-engineering.json

@@ -31,6 +31,10 @@
       {
         "prompt": "Tag and publish the release",
         "owner": "i3-git-workflow-and-versioning"
+      },
+      {
+        "prompt": "Generate a reviewable interactive UI prototype from business requirements",
+        "owner": "i3-ui-prototype"
       }
     ]
   },
@@ -47,6 +51,18 @@
         "ARIA roles or semantic elements are used correctly",
         "Component state is managed deliberately rather than ad hoc"
       ]
+    },
+    {
+      "id": 2,
+      "kind": "dialogue",
+      "prompt": "An approved production design now needs a reusable accessible Vue form component. Separately, a product owner wants an interactive review prototype from an editable HTML reference. Explain the owner of each request and how frontend implementation guidance can support prototype work. Do not implement anything.",
+      "expected_output": "Production frontend ownership and prototype support are distinguished without duplicating or replacing either workflow",
+      "expectations": [
+        "Production component implementation remains in the frontend implementation method and the existing engineering workflow",
+        "The review-prototype request belongs to the prototype workflow in the main session, where frontend guidance can support actual interface implementation",
+        "Frontend guidance does not require creating a prototype, installing a dedicated prototype role or changing its general method",
+        "Prototype-specific version, baseline and acceptance ownership stays with the prototype workflow; no runtime work or human approval is invented"
+      ]
     }
   ]
 }