@givolt/i3-composer-agent 2.3.2 → 2.3.4

package/skills/i3-ui-prototype/SKILL.md

@@ -37,7 +37,7 @@ Skill/Command/Agent 标识、文件路径、命令参数、代码/API 名称、
 
 ### 1. 公共前置：上下文、操作与副作用
 
-所有入口，包括直接 Skill 调用，先读取用户原始要求与最新限制、项目规则、实际文件、技术栈、`.i3-ui-prototypes.json` 指向的原型和交接。没有正式规格时整理最小范围和待确认项，不补造审批权限或把演示规则写成已确认需求。
+所有入口，包括直接 Skill 调用，先读取用户原始要求与最新限制、项目规则、实际文件、技术栈、`prototypes/index.json` 指向的原型和交接；仅有旧 `.i3-ui-prototypes.json` 时兼容读取，不创建第二份活动索引。没有正式规格时整理最小范围和待确认项，不补造审批权限或把演示规则写成已确认需求。共享资料与宿主缓存按 [project-layout.md](references/project-layout.md) 管理。
 
 选择 `analyze`、`create`、`revise`、`inspect` 或 `confirm-baseline`；无参数默认 create，明确分析或只读限制优先。analyze 不初始化、不安装升级、不持久化设计、不更新项目／执行状态，也不为记录分析而写文件。允许经过核对的只读查询；用户明确要求保存分析文档时只执行该项写入授权。inspect 是否落盘服从本次范围。规则见 [workflow-contract.md](references/workflow-contract.md)。
 
@@ -57,6 +57,14 @@ analyze 的交付是需求／能力覆盖、模板与框架选型、交互验收
 
 已有 v2 实例先运行一次 `node <skill-root>/scripts/native-pilot.cjs state <prototype-root>`，从聚合结果恢复身份、固定需求、设计／构建／实际QA、负责人和下一步的精确命令。不要为寻找参数反复遍历全仓库、node_modules或阅读控制器内部实现。这里只读检查，不安装、启动浏览器或更新状态。
 
+CodeBuddy 新建原型采用 A＋B 执行合同，实际接口见 [execution-evidence.md](references/execution-evidence.md)。先只读检查该安装范围的 `prototype-hooks.cjs check`；未启用或来源协议未核实则报告缺项，不能自行改宿主配置或声称严格完成。analyze 和纯读取不进入制作门禁。已有实例没有 `runtime.executionPolicy` 时保留原合同，不隐式追加输入或重建原型。
+
+项目／全局 IDE／CLI 新启用默认从真实 Hook 的 `transcript_path` 自动取得当前会话文件；不让模型搜索／填写日志、不选择最近文件。`transcript.status=awaiting-native-event` 表示尚未观察，不阻止启动已授权任务及 `execution-begin`；进入制作和交付仍必须有可解析的原生证据。已有手动目录限制保持，可由用户显式切回 auto；缺字段、不可读、格式不支持或会话不符时报告未核验，不能用手写记录补齐。
+
+CodeBuddy／WorkBuddy 新 create 前，用 `native-pilot.cjs execution-assertions-template --scope <scope-file>` 取得完整场景，按本次 PRD 与能力参数填充每项预期 JSON 事实，存于该原型 `.preparation` 目录。create 增加 `--host <codebuddy|workbuddy> --execution-policy buddy-ab-v2 --execution-assertions <assertions-file>`；官方 Skill 真实不可用时才显式 `--official-source-fallback`，保留其失败调用定位。随后在实际所选宿主主会话执行 `execution-begin <prototype-root>`，以原生 Skill 工具加载当前上下文需要的前端 Skill 后再写业务界面。旧 codebuddy-ab-v1 及未采用 executionPolicy 的实例保留原合同。其他宿主尚未适配此 Hook 合同，按原流程披露调用核验边界。
+
+`execution-template <prototype-root>` 返回当前身份与已观察到的真实加载引用；以实际查询、实现复核及浏览器结果补齐 `qa/execution-evidence.json`，不能补造调用 ID。构建、record-run、record-devtools-review、finalize 与 `execution-check --stage <stage>` 共用 A；B 在可识别的写入前检查，反馈明确 Skill 名与下一动作，成功补调后重试；Stop 按同缺项两次、当前原生任务总计六次的预算继续纠正，到上限如实报告阻塞，反复 begin 不清零。只读分析、进度、阻塞及用户停止可正常结束。未通过门禁时交付候选和缺项；新收据的 `native-source-correlated` 不代表不可篡改认证或用户认可。
+
 ### 2. 完整内容模板与需求能力
 
 正式内容模板位于 `assets/templates/enterprise-admin/`；双击其 `index.html` 或上层 `assets/templates/index.html` 可离线预览。完整模板是内容、通用布局和交互参考，不是最终框架效果。`reference/` 保留原始来源；可编辑页面片段内嵌在离线 `index.html` 的 `template[data-source]` 中，本地样式修改后刷新生效，不需要服务、依赖安装或重建。小列表 HTML 已退出正式资产和默认生成入口。
@@ -68,29 +76,43 @@ node <skill-root>/scripts/native-pilot.cjs template-page --page models-page
 
 默认只读使用本 Skill 随版本发布的模板及能力定义，在内存中计算当前内容索引，不在业务项目创建 `ui-templates`，也不修改安装目录。模板由维护者在 Skill 源码中修改、校验并随包发布；业务修改直接作用于 `prototypes/<id>/app/`，生成依据及索引固定在 inputs。只按本次页面读取内容，避免把整套模板加载到上下文。完整模板的索引是参考清单，不声称已自动理解全部原始交互。既有模板工作副本和 prepare-template／sync-template 命令仅保留兼容；只有用户明确要求复用某个已有副本时指定 --template-root，不自动选择、覆盖或清理它。
 
-生成前依据 PRD 整理范围文件：已有需求文件只读引用；本次新文件放在允许写入的 `.prototype-preparation/<id>/scope.json`，不提前占用原型目标目录。`scope.json`：逐个声明实际业务页面、参考页面、区域类型、需求原文及来源。管理列表由固定定义要求查询、复选、多页分页、批量操作和状态反馈；编辑区域要求校验、失败保留与重试。参数按实际需求记录；默认列表分页可调为 10／20／50，默认 10。豁免必须指向明确需求及原因，不能通过漏报区域逃避本页真实能力。人工／浏览器复核区域与需求是否一致。
+生成前依据 PRD 整理范围文件：已有需求文件只读引用；本次新文件放在允许写入的 `prototypes/.preparation/<id>/scope.json`，不提前占用原型目标目录。新 scope 使用 schemaVersion=3，逐个声明实际业务页面、参考页面、区域类型、需求原文及来源；moduleIds 填实际 PRD／项目已明确的稳定业务模块 ID，不填文档名、需求全文或代码路径，未明确时填 []。多个 PRD 的模块取本原型范围内并集，需求逐条保留来源与版本、使用唯一 ID；不编造模块或把未关联解释为适用全项目。创建及明确接受输入的修订会从固定 scope.moduleIds 去重生成索引 appliesTo，不手填两份。旧 scope 按原合同保留。管理列表由固定定义要求查询、复选、多页分页、批量操作和状态反馈；编辑区域要求校验、失败保留与重试。参数按实际需求记录；默认列表分页可调为 10／20／50，默认 10。豁免必须指向明确需求及原因，不能通过漏报区域逃避本页真实能力。人工／浏览器复核区域与需求是否一致。
 
 新生成原型默认包含“明亮、暗黑、清新、科技”，默认“明亮”，菜单不加编号。由 application-shell 的固定主题能力和原生 ConfigProvider 实现，主题偏好按实例隔离；不把 HTML 参考样式当成最终主题。旧实例的固定分页、可选主题与 20／23 场景合同仍按原输入检查，不追溯修改。完整字段和示例见 [content-template.md](references/content-template.md)。
 
+先运行 `generation-options` 查看本模板真实支持的风格／布局／密度和页面模式，向客户展示中文名称；已有明确选择直接沿用，未指定时说明模板默认值。风格与四主题分开：风格／布局／密度在生成前固定，四主题在成品上切换。离线选择页的“选择风格、布局与密度”只预览结构，不替代框架效果验收。
+
+```sh
+node <skill-root>/scripts/native-pilot.cjs inventory --template enterprise-admin
+node <skill-root>/scripts/native-pilot.cjs generation-options --template enterprise-admin
+node <skill-root>/scripts/native-pilot.cjs generation-plan --template enterprise-admin --scope <scope.json>
+```
+
+逐页读 `template-page` 返回的真实 HTML 和 `generation-plan` 的参考清单；依据本次业务选择 management-list／tree-list／tree-table／edit-form／form-page／detail／wizard／workflow／permissions／content。模式选定后，其能力不能通过删绑定、关开关或 N/A 删除。普通列表不强加树；分类筛选树和树表须分别声明，导航分组也单独声明。列设置、删除、未保存保护、向导、画布、角色状态等均按合同处理，不能只补树。
+
+每个真实字段和操作填入区域的 fields／actions，保留唯一 ID、类型、需求来源及操作预期；页面上的新按钮不能只给反馈文字冒充业务结果。`pendingDecisions` 中的参考能力须明确采用或附需求依据排除；`pendingReferenceElements` 中每个功能节点（包括已被通用能力涵盖的按钮／字段／事件）须用 referenceDecisions 显式关联生成绑定或附来源排除，允许同类节点以明确 nodeIds 分组。不得用“已采用 interaction”批量视为全部节点已处理。检查真实页面与 PRD，工具只验证已声明内容的一致性，不能自动发现 PRD 中从未声明的遗漏。使用 replan 显式统一更新固定输入，避免手改多份合同不一致。完整格式与取舍、重新固定方法见 [generation-contract.md](references/generation-contract.md)。
+
 ### 3. 原生组件首期：设计与实现
 
 UIUX 和框架官方 Skill 独立可选安装，不随本技能默认复制。create／revise 需要这些能力前，运行 `node <skill-root>/scripts/prototype-dependencies.cjs check --host <host-id> --scope project --project <project-root>` 只读检测当前宿主项目及同宿主全局依赖；仅检查全局时用 `--scope global`；不缓存“跳过安装”，后续补装后重新检测，无需重装本技能。宿主未发现新 Skill 时刷新／新建会话。安装须明确选择，不在 analyze 自动下载安装；命令、固定版本和使用边界见 [optional-skills.md](references/optional-skills.md)。已有实例的模式、源码和验收不因安装依赖而自动变更。
 
 按下文专业接入规则检测 UIUX，professional 不静默降级，template 必须明确选择。只读约束贯穿 provider；查询、采用和效果分别有依据。详细接入见 [expert-adapter.md](references/expert-adapter.md)。
 
-初始化前的 probe／查询不得先占用 `prototypes/<id>`。先 probe，再用下列 create 命令原子初始化，然后在已创建实例的 qa 下保存查询、取舍与验证。如果必须在初始化前保存查询文件，使用独立准备目录（如项目内 `.prototype-preparation/<id>`），初始化后再归入本实例 QA；不要预先创建目标的 qa 目录。
+初始化前的 probe／查询不得先占用 `prototypes/<id>`。先 probe，再用下列 create 命令原子初始化，然后在已创建实例的 qa 下保存查询、取舍与验证。如果必须在初始化前保存查询文件，使用独立准备目录（如项目内 `prototypes/.preparation/<id>`），初始化后再归入本实例 QA；不要预先创建目标的 qa 目录。
 
 加载框架官方 Skill 或对应版本官方文档、类型和源码，先查 API、读示例、再实现。先完成上文工具预检，使用已准备的固定本地 CLI；缺项不因官方 Skill 的安装建议而扩大权限。固定项目依赖锁，记录请求与实际知识版本。映射与官方来源见 [framework-contract.md](references/framework-contract.md)。
 
+antDv Skill 成功加载后，优先使用只读命令 `node <skill-root>/scripts/prototype-dependencies.cjs query --host <host> --scope project --project <project-root> --kind info --component <Component> --version <knowledge-version>`，它解析当前宿主本地 Node／CLI 入口，不依赖全局 `antdv` PATH。也可使用检测返回的绝对 Node 和 CLI 入口执行官方只读查询。query 返回不代表 Skill 调用；组件版本与知识版本分别记录，不足时核对目标包类型／源码。官方 Skill 的 allowed-tools／原生权限若不允许实际入口，按原生权限流程处理，不编辑官方正文绕过。
+
 宿主已发现可调用的官方框架 Skill 时，先通过真实 Skill 工具加载它；读取 SKILL.md 或运行 CLI 查询不能冒充宿主 Skill 调用。只有该 Skill 在当前执行者中不可调用时，才使用版本匹配的官方文档／类型／源码等效渠道，并明确记录官方 Skill 未唤醒及实际资料来源。UIUX 的 Skill 调用、真实查询、建议采纳与效果验证也分别记录，查询成功不自动记 used。
 
 ```sh
-node <skill-root>/scripts/native-pilot.cjs create --project <project-root> --id business-demo --scope <project-root>/.prototype-preparation/business-demo/scope.json --expert-mode professional --provider <uiux-root>
+node <skill-root>/scripts/native-pilot.cjs create --project <project-root> --id business-demo --scope <project-root>/prototypes/.preparation/business-demo/scope.json --expert-mode professional --provider <uiux-root>
 # 仅在用户已明确选择基础生成后：
-node <skill-root>/scripts/native-pilot.cjs create --project <project-root> --id business-demo --scope <project-root>/.prototype-preparation/business-demo/scope.json --expert-mode template
+node <skill-root>/scripts/native-pilot.cjs create --project <project-root> --id business-demo --scope <project-root>/prototypes/.preparation/business-demo/scope.json --expert-mode template
 ```
 
-目标存在则 revise，不重新初始化。Follow the `i3-frontend-ui-engineering` skill，使用真实 Table／Form／Drawer／反馈组件及 ConfigProvider。初始化只产生需求对应的框架骨架和四主题，business.status 为 needs-adaptation；这不是已完成业务。实现固定输入中的实际字段、列表和流程，再核对需求映射、模拟数据并更新 business.status 为 adapted。UIUX 采用规则落实到 design-system、主题和页面；模板样式不锁定生成外观。
+目标存在则 revise，不重新初始化。首次业务 UI 写入前必须通过宿主 Skill 工具成功调用 `i3-frontend-ui-engineering`；不得仅凭当前 Skill 中的摘要直接实现。收到门禁反馈时立即补调、等待成功返回并重试原操作，失败则报告具体阻塞，不能推迟到下次修订。Follow the `i3-frontend-ui-engineering` skill，使用真实 Table／Form／Drawer／反馈组件及 ConfigProvider。初始化只产生需求对应的框架骨架和四主题，business.status 为 needs-adaptation；这不是已完成业务。实现固定输入中的实际字段、列表和流程，逐个填写 `design-system/implementation.json` 的实际组件、源文件／定位符和固定场景，再核对需求映射、模拟数据并更新 business.status 为 adapted。UIUX 采用规则落实到 design-system、主题和页面；模板样式不锁定生成外观。
 
 目标存在但没有 prototype.json 时属于未识别的准备目录，不能当作有效实例执行 revise。先核对来源并保留文件；只有从本次工具记录确认整个目标目录均由当前任务的准备操作产生，才可将该整个目录移到独立准备位置，确保目标路径不存在后重试原子 create。仅移动查询文件仍会留下空目录并阻止 create。来源不明或包含用户已有文件时保留原目录并报告冲突，不得覆盖或清空。
 
@@ -118,7 +140,7 @@ node <skill-root>/scripts/native-pilot.cjs record-run <prototype-root> --report
 
 仅迭代历史设备列表且需要专项证明时，browser 传`--expected-categories '<JSON数组>'`、`--verify-blur-validation`、`--verify-atomic-status`或`--expected-description '<精确文案>'`；仅采用相应规则时启用，不能为了工具预设强迫采用UIUX建议。
 
-覆盖筛选→多选→分页→抽屉→校验失败→提交失败→重试保存→列表同步，另查状态、窄屏、键盘、焦点和控制台。进入与退出使用正常动画；退出结束后再销毁；毛玻璃核对配置、计算样式及真实效果，静态截图不证明动效。
+按选定模式覆盖实际流程；列表与编辑覆盖筛选→多选→分页→抽屉→校验失败→提交失败→重试保存→列表同步，树／树表、列设置、删除、向导、画布等逐项按固定场景验证。新 v3 报告还须逐场景填写 generationObservations，附实际动作／目标／结果、工具调用定位及证据摘要，不能只填写场景 passed。另查状态、窄屏、键盘、焦点和控制台。进入与退出使用正常动画；退出结束后再销毁；毛玻璃核对配置、计算样式及真实效果，静态截图不证明动效。
 
 清空文本后要核对查询／校验实际结果。本轮固定 Chrome DevTools MCP 1.11.0 的空字符串 fill 可仅清 DOM 值而未发送输入事件；遇到此现象记录工具限制。实测替代操作是原生 fill 单个空格后，只读取得实际文本长度与光标位置，确认光标在末尾再按该长度逐次 press_key Backspace，最后核对空值及查询／校验结果。空格可能追加到恢复的旧文本；本轮 headless 的 Meta+A／Control+A 也未全选，不能假定快捷键成功。不要用 evaluate_script 补发事件或修改状态。输入事件问题与宿主参数回调兼容分别记录，fill 返回成功不证明页面状态已更新；版本不同按实际观测判断，详见交互验收合同。