@givolt/i3-composer-agent 2.3.0 → 2.3.2

package/skills/i3-ui-prototype/assets/templates/enterprise-admin/template.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "kind": "content-reference",
+  "id": "enterprise-admin",
+  "version": "1.0.0",
+  "entry": "index.html",
+  "definition": "capability-definition.json",
+  "title": "完整企业管理后台内容模板"
+}

package/skills/i3-ui-prototype/assets/templates/gallery/index.html

@@ -2,7 +2,7 @@
 <html lang="zh-CN">
 <head>
 <meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
-<title>选择原型类型 · i3 Composer</title><link rel="icon" href="data:,">
+<title>选择原型类型 · i3-Composer</title><link rel="icon" href="data:,">
 <style>
 *{box-sizing:border-box}html{height:100%}body{height:100vh;height:100dvh;display:flex;flex-direction:column;margin:0;background:#f5f5f5;color:#262626;font:14px/1.5 -apple-system,BlinkMacSystemFont,"PingFang SC","Microsoft YaHei",sans-serif}header{flex:none;padding:20px 24px 16px;background:#fff;border-bottom:1px solid #e8e8e8}h1{font-size:22px;margin:0 0 4px}p{margin:0;color:#595959}.options{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:12px;margin:16px 0}.option{text-align:left;border:1px solid #d9d9d9;border-radius:8px;padding:12px 14px;background:#fff;color:inherit;font:inherit;cursor:pointer}.option strong{display:block;font-size:16px;margin-bottom:4px}.option span{display:block;font-size:13px;color:#595959}.option[aria-pressed=true]{border-color:#1677ff;background:#f0f7ff}.option:disabled{cursor:default;background:#fafafa;color:#8c8c8c}.option:disabled span{color:#8c8c8c}.option:focus-visible,a:focus-visible{outline:3px solid #1677ff;outline-offset:3px}.summary{display:flex;align-items:center;justify-content:space-between;gap:16px;flex-wrap:wrap}.summary a{color:#0958d9;text-decoration:none;white-space:nowrap}.summary a:hover{text-decoration:underline}iframe{display:block;flex:1 0 240px;width:100%;min-height:240px;border:0;background:#fff}.error{color:#cf1322}
 @media(max-width:900px){header{padding:16px}.options{grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}.option{padding:10px}.option strong{font-size:14px}.summary{gap:8px}}
@@ -10,16 +10,16 @@
 </style>
 </head>
 <body>
-<header><h1>选择原型类型</h1><p>先确定界面结构，再结合业务需求生成原型。已有项目优先沿用已确认的设计。</p>
+<header><h1>选择原型类型</h1><p>双击即可离线预览完整内容模板；修改后刷新。生成原型时再结合需求与目标框架实现。</p>
 <div class="options" aria-label="原型类型"></div>
 <div class="summary"><p id="summary" role="status">正在读取模板…</p><a id="open" target="_blank" rel="noopener">打开完整演示 ↗</a></div>
 </header>
 <iframe title="企业管理后台完整交互演示"></iframe>
-<script type="module">
+<script src="../catalog.js"></script>
+<script>
 const assetRoot=new URL('../',location.href),frame=document.querySelector('iframe'),summary=document.querySelector('#summary');
 try{
- const response=await fetch(new URL('catalog.json',assetRoot));if(!response.ok)throw new Error('无法读取模板目录');
- const catalog=await response.json();let selected=false;
+ const catalog=I3_TEMPLATE_CATALOG;let selected=false;
  for(const entry of catalog.templates){
   const button=document.createElement('button');button.className='option';button.type='button';
   const title=document.createElement('strong');title.textContent=entry.name;button.append(title);
@@ -29,7 +29,7 @@ try{
    const url=new URL(entry.preview,assetRoot);if(url.origin!==location.origin)throw new Error('模板入口必须来自本地资源');
    document.querySelectorAll('.option').forEach(item=>item.setAttribute('aria-pressed',String(item===button)));
    frame.src=url.href;frame.title=entry.name+'完整交互演示';document.querySelector('#open').href=url.href;
-   summary.textContent=entry.name+' · '+entry.version+' · 来源：'+entry.source+'。保留完整示例，当前等待人工评审。';
+   summary.textContent=(entry.brand?entry.brand+' · ':'')+entry.name+' · '+entry.version+'。保留完整示例，当前等待人工评审。';
   });
   document.querySelector('.options').append(button);
   if(!selected&&!button.disabled){button.click();selected=true}

package/skills/i3-ui-prototype/assets/templates/index.html

@@ -0,0 +1,3 @@
+<!doctype html>
+<html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="refresh" content="0;url=gallery/index.html"><title>i3-Composer 内容模板</title></head>
+<body><p><a href="gallery/index.html">打开完整内容模板选择页</a></p></body></html>

package/skills/i3-ui-prototype/assets/templates/serve-gallery.cjs

@@ -2,6 +2,7 @@
 const http = require('node:http');
 const fs = require('node:fs');
 const path = require('node:path');
+const { brandRuntimeResource } = require('../../scripts/enterprise-template.cjs');
 const root = path.resolve(__dirname);
 const types = { '.html': 'text/html', '.mjs': 'text/javascript', '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.webp': 'image/webp' };
 const server = http.createServer((req, res) => {
@@ -11,6 +12,12 @@ const server = http.createServer((req, res) => {
   const file = path.resolve(root, '.' + relative);
   if (!file.startsWith(root + path.sep) || !fs.existsSync(file) || !fs.statSync(file).isFile() || !fs.realpathSync(file).startsWith(root + path.sep)) { res.writeHead(404).end(); return; }
   res.writeHead(200, { 'Content-Type': (types[path.extname(file)] || 'application/octet-stream') + '; charset=utf-8', 'Cache-Control': 'no-store' });
+  const enterpriseReference = path.join(root, 'enterprise-admin/reference');
+  if (file.startsWith(enterpriseReference + path.sep) && /\.(?:html|js|mjs)$/.test(file)) {
+    const relative = path.relative(enterpriseReference, file).split(path.sep).join('/');
+    res.end(brandRuntimeResource(relative, fs.readFileSync(file, 'utf8')));
+    return;
+  }
   fs.createReadStream(file).pipe(res);
 });
 server.listen(Number(process.argv[2] || 0), '127.0.0.1', () => process.stdout.write(`模板预览：http://127.0.0.1:${server.address().port}/\n`));

package/skills/i3-ui-prototype/references/artifact-contract.md

@@ -8,6 +8,31 @@
 默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
 <!-- i3:zh-guide:end -->
 
+## v2 原生组件实例
+
+schemaVersion=2、artifactKind=framework-prototype、runtime={kind:vue-antdv-next,version:"1"} 使用 native-pilot 合同；template、framework 保存 id、version、digest，expertMode 保留 professional／template。项目清单定位实例，安装包最新定义不替代实例固定输入。
+
+新流程只读使用 Skill 内随版本发布的模板，不默认生成项目 `ui-templates`；模板维护在 Skill 源码完成，业务修改直接落在实例工程。已有模板工作副本可通过 --template-root 显式复用并保留原文件。实例 `inputs/` 固定模板、范围、能力定义和 binding、框架映射及必需场景；`app/` 是真实组件工程，`mocks/` 为可复现状态，`design-system/` 保存正式规则。`requirements-map.json` 连接范围和实现。完整模板固定为参考输入，scope.pages／regions 规定实际业务范围；未知新增交互与任意 N/A 须处理。runtime.contentReference=true 时还记录 business.status；needs-adaptation 的骨架不能通过业务验收，状态变更进入候选身份。详见 [content-template.md](content-template.md)。旧 v2 输入没有该标识时保持原合同。
+
+| 身份 | 包含 |
+| --- | --- |
+| inputDigest | 固定模板、需求范围、能力绑定、框架和必需验收 |
+| candidateDigest | 固定输入＋源码、资源、正式设计、模拟数据、构建配置与锁文件 |
+| buildDigest | 实际产物文件及摘要 |
+| run | 引用候选和构建，保存真实操作、结果和证据 |
+
+node_modules、缓存、执行状态、QA 证据不进入候选摘要。正式场景定义不能因位于 QA 名下而被排除。构建身份由构建阶段形成，不回写候选源码造成循环。
+
+`builds/<build-id>/` 保存固定产物，`qa/runs/<run-id>/` 保存执行证据；`execution.json` 是可变运行记录，不承担候选身份。HANDOFF 保留已完成范围、待确认及恢复入口；实际恢复以文件／摘要为准。用户手改保留并使旧证据失效。
+
+浏览器打开的入口与实际加载资源要匹配构建，不能只读网页内声明的摘要。运行前后候选一致，否则本轮无效；未实际执行不标通过。构建、源码和输入绑定后才能交付已验证候选。
+
+新基线必须覆盖固定输入、候选源码和设计合同，并引用与该版本匹配的验收及人类确认；QA 证据作为可审计附件，不倒算影响候选摘要。使用 `native-pilot.cjs confirm-baseline <root> --confirmation <file>`，人类确认文件包含 revision、digest、reviewer、statement、source。compare-baseline 检查当前差异及基线完整性；不得通过修改 legacy JSON 假装 v2 已冻结。
+
+## Legacy v1 与原摘要
+
+以下合同保留既有实例解释，不能补写 v2 字段、重新计算旧摘要或迁移已确认快照。新执行者需要先判运行层，再选择脚本。
+
 项目 `.i3-ui-prototypes.json` 的 prototypes 列出 id、相对目录和 appliesTo。初始 appliesTo 为空，按实际业务补充模块范围；工程任务选择适用原型，不能把所有基线强加到无关模块。
 
 原型目录含 prototype.json、requirements-map.json、design-system/MASTER.md 与 tokens.json、app、mocks、qa、reviews、baselines、baseline.json、HANDOFF.md。企业后台生成 EASEL 完整参考示例，兼容旧模板生成通用演示；用于新业务时代理必须适配实际业务。企业后台还保留 design-system/source.json、runtime 与 purpose，记录来源、实例数据隔离及用途。模板来源与许可在技能资源中保留。生成实例 app/qa 是来源历史记录；本轮验收证据必须写入根目录 qa，不能复用历史通过状态。

package/skills/i3-ui-prototype/references/content-template.md

@@ -0,0 +1,76 @@
+# 完整内容模板与原生框架生成
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+## 目录与修改方式
+
+```text
+i3-ui-prototype/
+├── assets/templates/index.html                 离线选择入口
+├── assets/templates/enterprise-admin/
+│   ├── index.html                              完整内容模板，双击打开
+│   ├── offline.js                              已构建的本地经典脚本
+│   ├── template.json / capability-definition.json
+│   ├── usability.css / offline-build.json
+│   └── reference/                              不可变来源、样式与本地资源
+├── assets/capabilities/management.json          通用能力定义的维护来源
+├── assets/frameworks/vue-antdv-next/
+│   ├── starter/                                新业务的框架骨架与四主题
+│   └── legacy-starter/                         旧固定设备合同的兼容起点
+└── scripts/、references/、SKILL.md
+```
+
+内容模板只有完整企业后台作为当前可用类型，其余类型仍为 planned。正式 Skill 内不再含 `authoring/admin-list`；历史小 HTML 仅在配套工具的测试夹具中，用来验证已有输入兼容。`legacy-starter` 是旧原生框架合同的兼容代码，不是新内容模板或默认生成入口。
+
+默认直接只读使用 Skill 内随包发布的完整模板及能力定义，不复制到业务项目 `ui-templates/`，不在生成业务原型时修改安装目录。内容索引按实际已安装资源在内存中计算，实例 inputs 固定该索引及模板、范围快照，避免品牌／宿主适配后缓存摘要过期。模板由维护者在 Skill 源码中修改、校验并随版本发布；`index.html` 的 HTML／CSS 仍可离线修改查看。业务项目直接修改 `prototypes/<id>/app/`。
+
+既有 `ui-templates/enterprise-admin/` 和 prepare-template／sync-template 命令保留兼容。只有用户明确选择某个已有副本时，使用 --template-root 指向它；其手工修改保留，不自动迁移、覆盖或清理。同步该副本后，template-page 可显式传目录查看；省略目录时只读查看 Skill 内置模板。
+
+离线 HTML 是内容参考。Vue／antDv-next 工程使用真实组件，仍需要项目依赖和开发／构建预览；不能承诺框架源码也能直接以 file:// 打开。
+
+## 需求与通用能力
+
+完整参考含多种页面，不能默认把所有参考业务生成到新项目。先根据实际 PRD 声明页面与区域。新整理的 scope 放在本次允许写入的 `.prototype-preparation/<id>/scope.json`；已有范围文件只读引用，不改项目其他文件或提前创建原型目标目录。示例仅解释格式：
+
+```json
+{
+  "schemaVersion": 1,
+  "title": "资产管理原型",
+  "pages": [{
+    "id": "assets", "title": "资产台账", "referencePage": "models-page",
+    "regions": [
+      {"id": "list", "mode": "management-list"},
+      {"id": "editor", "mode": "edit-form"}
+    ]
+  }],
+  "requirements": [{
+    "id": "ASSET-01", "text": "按业务字段查询、选择和修改资产", "pages": ["assets"],
+    "source": {"type": "prd", "reference": "PRD.md#ASSET-01", "statement": "此处保留真实需求原文"}
+  }],
+  "exemptions": []
+}
+```
+
+`referencePage` 取本次选定模板索引的页面 ID；`template-page` 只读返回所选页面 HTML。显式引用旧副本时包含其已同步修改。业务 page/region ID 保持稳定；不能把示例 PRD 来源冒充实际需求。
+
+区域类型为 `management-list`、`edit-form`、`content`；只声明本次真实页面。默认列表需要查询、复选、分页、批量和反馈；编辑需要表单与反馈。默认分页为 adjustable，默认 10、选项 10／20／50，至少三页默认容量测试数据；可在区域的 `parameters.pagination` 明确覆盖。固定分页须写 mode=fixed、fixedPageSize 和 minimumTestPages，不能混入可调参数。按真实需要在区域的 `parameters.<capabilityId>` 覆盖其他参数。
+
+新流程额外固定 `app-shell/appearance/theme`，包含明亮／暗黑／清新／科技且默认明亮。原型 Skill 检查区域声明是否对应实际需求；检查器重算各区域的必需能力、参数与验收。定义检查不自动证明页面实现。
+
+## 创建与验收
+
+```sh
+node <skill-root>/scripts/native-pilot.cjs create --project <project-root> --id assets --scope <project-root>/.prototype-preparation/assets/scope.json --expert-mode professional --provider <uiux-root>
+```
+
+缺实际 scope 拒绝创建，不回退固定设备演示。初始化保存完整模板快照、scope、能力定义和绑定、框架版本、验收及需求映射，产生 Vue／antDv-next 骨架和四主题。主会话继续使用前端技能、官方框架知识和 UIUX 取舍实现业务。骨架是 `business.status=needs-adaptation`，state 下一步为 implement-business，不能作为已完成原型验收；完成实际页面后更新 adapted 并重新取得当前摘要。
+
+按 `inputs/acceptance.json` 的业务和框架场景执行真实浏览器操作，保存候选／构建身份、加载资源字节、截图、状态、焦点及错误证据，通过 record-run 导入；Chrome DevTools Skill 的六类观测另按现有合同登记。历史 `browser` 自动脚本只适用于设备列表固定合同，会拒绝新业务；不能用它的通过结果替代业务测试。报告结构及证据文件通过仍需原始工具记录证明真实执行。
+
+四主题必须覆盖真实 Table、Form、Drawer 及浮层，切换保留业务状态，刷新恢复偏好，实例隔离，并检查可访问性、窄屏和减少动效。新骨架默认具备切换机制；业务组件实现后仍需重新验证整页。已存在的 v1／v2 不自动迁移或追加新场景，按原固定输入继续迭代。

package/skills/i3-ui-prototype/references/enterprise-admin.md

@@ -8,14 +8,20 @@
 默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
 <!-- i3:zh-guide:end -->
 
-企业后台的来源是工作区的 EASEL v0.14 HTML 审查成果。模板完整保留 326 个来源文件：运行页面、控件、样式、图标、规则测试、来源、许可及历史验收材料。原 history/easel-history 目录不修改。
+企业后台模板统一使用 i3-Composer 品牌，来源是工作区的 EASEL v0.14 HTML 审查成果。模板完整保留 326 个来源文件：运行页面、控件、样式、图标、规则测试、来源、许可及历史验收材料。原 history/easel-history 目录不修改。
+
+## 离线入口
+
+正式模板双击 `assets/templates/enterprise-admin/index.html` 打开，选择页入口为 `assets/templates/index.html`。可编辑 HTML 片段内嵌在 index.html，本地样式与资源跟随目录；内容／样式修改后刷新即可。离线脚本只替换模块与 fetch 加载方式，原始 reference/ 逐文件保留。新建 HTML 审查实例同样双击 app/index.html；历史模块实例仍沿用原合同和可选静态服务。
+
+完整内容模板也作为原生框架生成的参考，需求页面与通用能力选择见 [content-template.md](content-template.md)。HTML 不是被废弃的旧模板，小 HTML 试点才退出默认入口。
 
 ## 完整示例与新业务
 
 - 用户要审查原来的整套后台时，使用 enterprise-admin 和 purpose=template-review，保留示例菜单与业务，便于和原版对照。
 - 用户要根据新业务做原型时，使用默认 business-prototype，先明确模块、字段、角色、状态和需求映射，修改原型副本中的相关文件；未适配状态 needs-adaptation 不能通过业务验收。
-- 审查完整示例不代表批准其全部 EASEL 业务，也不代表其他项目已完成业务适配。
-- 模板根 origin.json 保存全部来源文件的 SHA-256。reference/ 是完整来源快照，品牌转换不改写其中内容。实例仅进行明确的启动、设计 token 和本地数据命名空间接入。
+- 审查完整示例不代表批准其全部示例业务，也不代表其他项目已完成业务适配。
+- 模板根 origin.json 保存全部来源文件的 SHA-256。reference/ 是完整来源快照，品牌转换不改写其中内容。预览响应与新生成实例共用品牌适配，页面标题、导航、示例项目及授权说明统一显示 i3-Composer；生成副本同时接入启动、设计 token 和本地数据命名空间。
 - 资源库中的 5 个 Markdown 文件按技能命名规范存放为小写名称，原名到存放路径记录在 origin.storagePaths；内容不变，生成实例时还原原文件名，原文链接继续有效。既有验证器保持原有规则。
 - design-system/source.json 记录本实例的局部接入及用途。app/qa 保存的是来源历史记录，当前验收使用原型根 qa/。
 

package/skills/i3-ui-prototype/references/entry-contract.md

@@ -0,0 +1,71 @@
+# 入口与执行合同
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+本合同供自然语言、`/i3-prototype`、已加载的 `i3-using-agent-skills` 和直接 `i3-ui-prototype` 调用共用。主会话读取工作 Skill 并执行公共前置，命令和元技能只提供发现入口，详细流程留在工作 Skill。
+
+## 发现与执行
+
+| 入口 | 规则 |
+| --- | --- |
+| 自然语言制作、修改、分析或评审原型 | 主会话使用 `i3-ui-prototype` |
+| `/i3-prototype` | 主会话使用同一工作 Skill |
+| 已加载元技能 | 按普通原型路由使用同一工作 Skill |
+| 直接 `i3-ui-prototype` Skill | 当前主会话直接执行公共前置 |
+
+各入口不要求专责 Agent、常驻分派规则或父子回传。工作 Skill 不绕回命令或元技能。其他工程工作流已有的委派机制保持原有边界；任务若另有明确协作要求，按实际能力和授权处理，并保留一个源码／合同修改负责人。
+
+品牌发行的命令和 Skill 名称由发行映射决定。不要猜测宿主支持 `/i3-ui-prototype`、`$i3-ui-prototype` 或其他语法；以实际注册和验证结果为准。安装成功、文件存在或词法排名不证明宿主已经加载或执行 Skill。
+
+## 公共前置
+
+1. 保留用户原始要求及最新限制，读取项目规则、实际文件和原型清单。
+2. 识别 `analyze`、`create`、`revise`、`inspect` 或 `confirm-baseline`。无参数默认 create；明确分析或“不改代码／不写文件”优先。
+3. 核对项目位置、原型标识及版本、输入来源、模板工作副本、目标框架、设计要求、已确认决定与问题。恢复写任务前核对 revision 和 candidate digest，保留用户手改及已认可基线。
+4. 核对当前主会话实际可用的官方资料、UIUX、文件和浏览器能力。按本次操作使用工作 Skill 的对应方法，不把计划或声明写成已完成执行。
+
+讨论 Skill、方案或“先分析”进入 analyze，不因出现“原型”而创建业务工程。生产页面实现和普通排错沿用对应工程流程。用户可持续用自然语言推进，无需重复请求已经给出的创建、修改、检查或主题启用授权。
+
+工具先以当前宿主和范围运行只读依赖检测，使用返回的固定实际 Node 入口。新工具位于宿主基址的 `tools/i3-prototype/`，旧项目 `.prototype-tools` 继续只读兼容。analyze 中缺失或不能执行时报告缺口，使用已有只读资料，不使用 npm exec／npx 自动安装或补缓存。工具准备授权仅覆盖明确目录，不扩展到业务文件、SDK、宿主设置或全局配置。
+
+## 按操作使用能力
+
+- analyze 的交付是需求／能力覆盖、模板与框架选型、交互验收计划和缺口。结论足够后交付，不逐组件实施，不执行制作阶段的 UIUX 采纳、构建或浏览器门禁。
+- create／revise 的界面实现使用 `i3-frontend-ui-engineering`；框架适配使用当前可调用的官方 Skill，或版本匹配的官方文档、类型和源码；专业模式按 `expert-adapter` 使用 UI/UX Pro Max。
+- 需要真实浏览器验收时使用 `i3-browser-testing-with-devtools`，适用观测及专项回归由 `interaction-acceptance` 定义。Skill 加载、真实查询、建议采用、构建和实际浏览器执行分别留证。
+
+只读限制贯穿下游技能和工具：不初始化、安装升级、持久化设计、更新执行状态或为结果格式写文件。用户单独要求保存分析文档时只执行该项写入。不写临时传输文件或探测可写目录。
+
+能力覆盖须核对绑定参数。PRD 要求可调页大小而 HTML 只有 `fixedPageSize: 10` 时，应报告部分覆盖及可写阶段所需适配；固定值不是默认值。分析完整交付不等于需求已经全部实现，后续实现计划也不构成额外审批门槛。
+
+## 交付与证据
+
+最后一次工具结果之后，用简短自然语言交付实际完成范围、结论、证据位置、缺项和下一项必要动作。分析留在会话；已有实例检查返回实际读取的身份。无须统一父子 JSON、`PROTOTYPE_RESULT_V1` 标记或 `validate-result.cjs` 前置校验。该工具可保留用于特定维护检查，其结构成功不证明业务完成、真实 QA 或宿主调用。
+
+原生 create／revise 仍按工作流程完成业务适配、设计取舍、构建、全部适用的真实验收和 finalize。交付前只读核对 state 中 `delivery.current`、revision、candidateDigest 与实际 `qa/delivery.json` 收据一致。旧构建、旧 QA 或过期收据不能作为当前成功证据。
+
+本轮 CodeBuddy 新原生流程仍要求主会话实际调用 `i3-browser-testing-with-devtools`，通过 Chrome DevTools MCP 取得当前候选／构建的 DOM／计算样式、截图、console、network、可访问性和性能观测，并执行原型 Playwright 专项补充回归。缺 Skill、MCP 或必需观测时整链未完成。脚本收据和 state 不证明真实调用；原始宿主记录与实际观测另核。其他宿主结果及旧 v1／已有 v2 的固定合同按事实单列，不隐式扩展历史验收。
+
+通过本地验证的候选保持 pending-review。只有真实用户对同一 revision／digest 的明确认可，且适用验收仍当前有效，才能确认基线。原型认可不自动批准工程 Plan、生产开发或发布。Legacy HTML 保留原摘要与运行合同。
+
+缺少证据、执行中断或结果不完整时报告实际完成和未完成部分，不补造成功结论。文件承担连续性，新会话从固定输入、版本及交接恢复，不依赖旧会话或 Agent ID。
+
+## 入口验收
+
+分别记录自然语言、命令、已加载元技能、直接 Skill、只读分析和连续修改的实际表现。记录宿主产品及版本、安装方式、模型、Skill 加载、实际工具与最终交付；CLI 不代替 IDE 证据，词法排序不代替宿主执行。
+
+| 测试 | 输入要点 | 证据 |
+| --- | --- | --- |
+| 自然语言 | 给业务简述、内容模板与框架要求，先只读分析 | 主会话 Skill 执行、公共前置、零项目写入 |
+| 命令 | `/i3-prototype analyze` 加项目和输入位置 | 命令解析、同一 Skill 和只读结果 |
+| 直接 Skill | 当前会话直接使用 `i3-ui-prototype`，保持只读 | Skill 加载与公共前置 |
+| 元技能 | 加载 `i3-using-agent-skills` 后提交原型任务 | 普通原型路由及工作 Skill 实际执行 |
+| 连续修改 | 创建后提出一次小修改，再从文件恢复 | 原型身份保持，手改和旧基线未覆盖 |
+
+只读项对项目树、清单、原型和安装状态做前后比较；已授权分析文档单独说明。执行日志可保存在测试项目之外，宿主自身会话日志与项目写入分开报告。每条入口均核对最后的自然语言交付；写流程核对当前收据，分析核对需求与固定参数冲突是否如实保留。模型、权限和是否全新会话按实际记录，不用上一轮结果证明本轮。

package/skills/i3-ui-prototype/references/expert-adapter.md

@@ -8,23 +8,35 @@
 默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
 <!-- i3:zh-guide:end -->
 
-专业增强模式对应 professional，模板模式对应 template。依赖在用户实际执行的宿主中检测；推荐先使用宿主暴露的技能根，再使用明确 --host 指定的项目和全局目录。Codex 插件安装应由宿主提供的实际路径传给 --provider，不假设固定缓存版本。
+专业增强模式对应 professional，基础生成模式沿用 template 标识；两者框架和功能验收一致。依赖在用户实际执行的宿主中检测：项目级 i3-ui-prototype 可使用同宿主全局 UI/UX Pro Max，无需重复复制。
+
+## 操作范围优先
+
+analyze 和明确只读请求不安装升级、不使用持久化参数、不更新 provider／原型状态、不为查询记录写项目文件。使用核对过的只读查询，结果保留会话；要求保存分析文档时按指定范围写入。官方技能的安装、升级、--persist 或 --force 建议不能扩大本次范围。
+
+analyze 不为未创建候选执行 professional 准入或逐项采纳门禁；只在选型判断确需时查询抽象设计问题，足以形成覆盖／选型／验收计划／缺口后回传。以下完整 provider 探测、实际建议处理与效果验证用于 create／revise，不能机械套为只读分析前置。查询工具缺失时报告，不用 npm exec／npx 自动安装或补缓存。
+
+优先将宿主暴露的实际技能根传给 --provider；明确指定路径时只检查该副本。自动检测传 --host 与 --project，按项目 Skill、全局 Skill、当前宿主已安装且启用的插件顺序检查，不可用副本不会遮蔽后续可用副本。Codex 通过原生 `codex plugin list --marketplace ui-ux-pro-max-skill --json` 核对启用状态与确切安装版本；Claude Code、WorkBuddy 和 CodeBuddy 通过各自 installed_plugins.json 与 enabledPlugins 核对。插件入口按 manifest 定位，不遍历缓存选最高版本，也不读取另一宿主的安装。Cursor、Gemini 保留普通 Skill 目录检测；未覆盖的插件安装方式使用宿主提供的 --provider 路径。
+
+检测输出包含 source、searched、attempts 与 diagnostics。未传宿主/路径返回 needs-context；插件发现失败或安装记录冲突时补充实际路径；停用返回 disabled；文件缺失或真实查询失败返回 unusable。上述情况分别定位、启用或修复，不要求重复安装。自动发现所需 CLI 不可用时，不将其当作“未安装”的证据。
 
 检测 SKILL.md、Python 查询模块与数据库，执行只读 UX 探测。安装版本/资源摘要和当前查询记录保存为来源；探测成功只说明可执行，不意味着业务建议已经采用。
 
-缺失依赖时显示：当前环境不能使用 UI/UX Pro Max，可安装并验证，或选择模板模式继续；也可先整理需求和比较模板。默认不降级。用户已经选择安装或模板模式时沿用选择，不重复请求相同许可。
+确认未安装时提供安装入口，依照本次授权处理；也可明确选择 template 或先分析。默认不降级，沿用已有选择，不重复请求许可。委派执行者须验证实际查询能力，不能用父会话的可用判断代替查询。
 
 按维护方 [官方安装说明](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill#installation) 选择当前宿主适用入口。对于未实测的宿主只说明已验证方法和限制，不猜测安装路径。选择安装后应安装完整技能，包括 Python 脚本、数据库与必要引用，重新检测可用性。不能只复制 SKILL.md。不自动安装 Python 或其他系统运行环境。
 
 使用已安装专业技能的指令和查询机制，向数据库传递抽象设计问题，不传私有业务数据。整体设计建议用 --design-system；专项交互用 --domain；实际技术栈支持时另查 --stack。HTML 模板不等于 html-tailwind，不为了查询参数而更换原型技术。
 
 ```sh
+node <skill-root>/scripts/check-design-provider.cjs --host codex --project <project-root>
+# 宿主提供实际路径时：
 node <skill-root>/scripts/check-design-provider.cjs --provider <uiux-root> --query "error summary validation" --domain ux
 ```
 
-对产品类型、页面结构和结果身份核对。返回失配时按专业技能契约重试一次，仍失配就拒绝；专业建议未匹配不等于可以补造业务流程。专业 provider 无可采用结果时记录 no-match 与采用的模板/工程依据，必要时由用户决定是否切换模式。
+对产品类型、页面结构和结果身份核对。失配按专业技能契约重试一次，仍失配就拒绝；建议未匹配不等于补造业务。无可采用结果记录 no-match 与模板／工程依据。真实查询零采用仍可完成 professional 复核，不因此要求切模式。
 
-qa/design-advice.json 采用以下记录结构：
+legacy 的 qa/design-advice.json 采用以下记录结构：
 
 ```json
 {
@@ -37,6 +49,28 @@ qa/design-advice.json 采用以下记录结构：
 }
 ```
 
-decision 可使用 adopted、adjusted、rejected；采用或调整的建议应写入设计契约和验收。初始化为 pending；没有记录实际查询和采用证据时不能声称 used。原始 --persist 结果只可写独立建议候选位置，不覆盖已认可的 MASTER 或使用未授权 --force。
+decision 可使用 adopted、adjusted、rejected；无匹配记录真实查询及结果、理由。采用或调整写入设计合同和验收。初始化 pending；查询成功不自动变成 used，效果未验证不报告已验证。
+
+分别保存 provider 身份与可用性、实际查询／相关返回、匹配与取舍、实施位置、浏览器验证。可在兼容 records 中追加这些字段，不用填假的采用记录通过守卫。验收允许有依据的零采用，冻结保持真实状态，不自动写 used。已冻结旧快照不重算。
+
+## 原生 v2 记录
+
+原生实例的正式设计决定进入候选摘要，原始查询和验证日志为执行证据；不能仅修改 QA 记录改变应验收设计。legacy 保持其原摘要范围。仅在可写操作中，将 --persist 结果写到独立建议候选位置，不覆盖已认可 MASTER 或使用未授权 --force。
+
+v2 的 qa/design-advice.json 保留初始化所得的真实 provider（availability、root、source、version、digest），增加实际查询及处理记录。例如以下结构中的摘要和结果必须来自本次真实查询，不能照抄占位值：
+
+```json
+{
+  "schemaVersion": 2,
+  "provider": {"availability":"available","root":"实际技能根","source":"project-skill","version":"实际版本","digest":"实际provider摘要"},
+  "queries": [{"query":"error summary validation","source":"实际查询结果的路径","resultDigest":"返回文件的SHA256"}],
+  "status":"reviewed",
+  "records": [{"query":"error summary validation","resultIdentity":"Error Placement","decision":"adjusted","rationale":"保留原生字段旁错误，并在校验失败后聚焦无效字段","implementation":"app/src/components/DeviceEditor.vue","verificationScenario":"devices/device-editor/edit/validation","verification":"待浏览器验证：失败提交后错误位于字段旁，焦点定位无效字段"}]
+}
+```
+
+将 records 中的设计决定同步到 design-system/decisions.json：`{"schemaVersion":1,"reviewStatus":"reviewed","records":[同一组设计决定]}`，并把适用规则写入 MASTER.md。query、结果身份、取舍、理由、实施文件和验收场景必须一致；改变正式决定会改变候选摘要，因此先整理决定，再构建和验收。采用／调整必须指向存在的候选源码文件，以及本轮验收的 journey ID。构建前的 verification 写待验证条件，不能把预期写成已经通过；浏览器完成后在 QA 中补充实际结果和证据，正式设计保留预期。recordRun 仍要求所指场景在本轮实际通过，才记录 used。
+
+零采用时 records 仍保存每项真实拒绝或 no-match 的理由与复核结论，不能留空表示完成。查询无匹配应包含缩窄重试的实际结果。全部 no-match 可使用 status/reviewStatus=no-match；有拒绝时使用 reviewed。没有实施变更的记录不需伪造 implementation 或 verificationScenario。只有验收通过后才记录 used／reviewed／no-match，冻结不会把零采用改成 used。
 
 渲染后的专业复核围绕实际发现的问题查询，再由浏览器检查修复。专业数据库提供建议，不自动证明可用性、无障碍认证或用户认可。

package/skills/i3-ui-prototype/references/framework-contract.md

@@ -0,0 +1,76 @@
+# 目标框架合同
+
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
+首期只有一个原生目标 `vue-antdv-next`。内容模板与框架分别选择；HTML 提供内容和能力，starter 提供最小技术起点。用户指定的框架和设计要求不能被专业建议替换。
+
+## 固定技术与知识
+
+- 固定 Vue、antDv-next、Vite、TypeScript、包管理器和依赖锁，实际版本保存在 profile 及实例输入。
+- 宿主发现可调用的官方框架 Skill 时，优先通过真实 Skill 工具加载，再查询 API、阅读示例并实现。读取 SKILL.md 和 CLI 查询分别只是文件读取与工具执行，不能记录成宿主 Skill 唤醒。当前执行者无法调用该 Skill 时才走对应版本官方文档／类型／源码等效渠道，明确记录未唤醒与实际来源。
+- 记录来源修订、真实 Skill 调用证据、查询工具版本、请求知识版本及实际返回版本。官方 Skill 已加载也不自动证明其查询可用或业务完成。
+- 先使用 prototype-dependencies 的只读检测核对 CLI 版本及实际 Node 入口；新工具放在对应宿主基址的 `tools/i3-prototype/antdv-cli`；支持项目和全局范围，并保留独立旧 `.prototype-tools/antdv-cli` 和已有 `.prototype-tools/node_modules` 布局，也可使用宿主明确提供的固定绝对入口。不要反复扫描 node_modules。可选安装见 [optional-skills.md](optional-skills.md)。
+- analyze 严禁 npm exec／npx 及任何自动安装、升级、补缓存的路径；即使缓存可能已存在，也不借该命令猜测。入口缺失或不可执行时报告未决项，使用已有只读资料。
+- 可写操作同样使用已准备的本地固定 CLI。只有用户已授权工具准备时才向明确工具目录安装固定版本；该写范围不包含业务项目文件、已安装 SDK、宿主设置或未选择的全局目录。生成工程的依赖安装另按 build --install 授权。
+- 返回版本回退时核对目标版本类型／源码。工具不可用可使用对应版本官方资料并记录真实渠道；不能把退回版本当成完全匹配。
+- 不因查询参数或 UIUX 示例改成 Tailwind、React 或额外 ProTable。新增依赖仅由本次需求和技术选择决定。
+
+官方资料：
+
+- [面向 Agent 的说明](https://github.com/antdv-next/antdv-next/blob/main/docs/src/pages/docs/vue/for-agents.zh-CN.md)
+- [官方 Skill](https://github.com/antdv-next/cli/blob/main/skills/antdv/SKILL.md)
+- [组件源码及文档](https://github.com/antdv-next/antdv-next)
+
+实际工具能否执行和静态文档宣称支持分别核对。官方查询不能替代类型检查、构建和真实浏览器；不以尚未实现的 lint 功能作为门禁。
+
+## 首期已核对的官方渠道
+
+官方 Skill 固定提交 `2b0dc514ee48bc130048724a5c5a0a76ec632aa1`，SKILL.md 摘要 `07e40bc93a598cdcee0037b2f199422cc046c6dc831a856ffcf85bab7376a19f`。既有试验为独立准备的 `.codebuddy/skills/antdv`；2.3.2 支持用户明确选择后准备同一官方内容，不默认捆绑安装。维护工具读取与执行查询不等同于 CodeBuddy 模型实际加载 Skill。只有真实宿主调用记录才更新该层状态。
+
+实际查询使用固定 `@antdv-next/cli@0.0.0-beta.1`，无全局安装或升级。请求知识 1.5.3 的 info 返回 Error 文本且 exit 0；list 明确失败。缓存文件只提供至 1.5.2，因此显式回退 --ver 1.5.2 查询三组件 info、命名 demo、token 和 Drawer semantic；分别记录请求和实际版本。API 属性已与包内 v1.5.2.json 比较，不能宣称精确匹配目标库 1.5.3。
+
+design.md 返回通用设计语言；未指定名称的 demo 列表忽略 JSON 格式，命名 demo 才给出 JSON；lint 只打印 Parsed args。检查结构及内容，不单凭 exit 0。mask demo 的默认模糊描述与目标包源码不同，仍以固定 1.5.3 类型／源码和真实效果为准。
+
+工具准备完成后的固定只读查询形式；以下路径以业务项目为当前目录，宿主给定绝对入口时直接替换。只读分析只查询足以决定选型的 API，不运行创建阶段的设计／采纳门禁：
+
+```sh
+node <检测返回的antdv-entry> info Table --ver 1.5.2 --format json
+node <检测返回的antdv-entry> demo Table row-selection --ver 1.5.2 --format json
+node <检测返回的antdv-entry> token Drawer --ver 1.5.2 --format json
+```
+
+保留原始 stdout／stderr、退出码、JSON 解析结果及来源摘要。CLI 能力或知识升级时先独立验证，再形成新的框架输入，不改旧候选固定来源。首期具体结果见 profile 与框架 readme，验收报告引用维护验证产物。
+
+## 能力与组件
+
+| 能力 | 框架方向 | 应用责任 |
+| --- | --- | --- |
+| 管理列表 | Table | 记录身份、筛选、排序及空／失败状态 |
+| 当前页多选 | Table rowSelection | 选中数、半选、翻页／筛选清空、批量对象 |
+| 分页 | Table pagination | 当前页、页大小、总数及可见数据一致 |
+| 编辑校验 | Form、Input、Select | 业务规则、提交状态、失败保留、重试更新 |
+| 编辑抽屉 | Drawer | 开合状态、退出完成后卸载、焦点和滚动恢复 |
+| 结果反馈 | 框架反馈组件 | 成功／失败对应真实本地操作结果 |
+| 主题 | ConfigProvider／Token | 固定设计规则；新流程默认四主题与实例偏好，旧输入按其固定绑定 |
+
+原生组件存在不等于应用行为完成。新项目使用完整企业后台内容参考及显式 scope.pages／regions，初始化不再投影固定设备业务。默认四主题已进入 application-shell 必需集合；分页参数由 scope 的区域参数固定，缺省为 adjustable 的 10／20／50、默认 10。数据按本次 PRD 实现，默认容量至少覆盖三页，不能只画分页条或用提示代替保存。
+
+具体结构、命令及适配职责见 [content-template.md](content-template.md)。在真实原生 ConfigProvider 中配置 algorithm／语义 token，自有外壳与浮层同步；主题偏好使用实例的 `${storageNamespace}:ui-theme:v1`，切换保留业务状态，非法偏好或存储拒绝安全回退明亮。系统减少动效设置仍有效。
+
+只有迭代已有设备列表固定输入时读取 [legacy-native.md](legacy-native.md)：原 fixedPageSize、可选主题和 20／23 场景不被新全局合同覆盖。默认新流程不会生成该小模板。
+
+## 抽屉与模糊
+
+明确 Drawer 方向、尺寸、关闭方式、输入丢弃策略及焦点。控制 open 状态，退出动效完成后才销毁内容；避免父级 v-if 提前切断退出。
+
+遮罩模糊显式配置，不依赖未经核对的默认值；核对固定版本 API、实际 CSS、计算样式和呈现。类名存在但滤镜失效应被发现。正常模式检查进入退出；减少动效偏好下仍应能正常操作。
+
+## 适配边界
+
+starter 是可运行的演示起点，Agent 仍按 PRD 和固定能力合同适配业务。框架内置行为、应用组合逻辑和演示假设分别记录。框架配置、能力映射及必需场景随实例固定，全局 profile 更新不重释旧候选。