@givolt/i3-composer-agent 2.2.2 → 2.3.0

package/.agents/plugins/marketplace.json

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

package/.claude/commands/i3-prototype.md

@@ -0,0 +1,23 @@
+---
+description: "选择模板并生成、评审和迭代交互原型，维护已确认的 UI 基线。"
+# i3-description-source: "description: Create, review and iterate interactive UI prototypes with template selection and approved baselines"
+---
+
+<!-- i3:zh-CN:start -->
+## 中文交互与输出
+
+默认使用简体中文回复，包括追问、选项说明、阶段进度、分析、规格、计划、验收、代码审查与发布报告。只有用户明确要求其他语言时才切换；输入中出现英文术语、代码或引用不构成切换语言的要求。
+下文的工程步骤、审批要求、退出条件和工具约束完整有效。英文示例中的人类可读标题、说明和占位内容在实际输出时应译为中文；保留原有信息与验证标准，不删减方法。
+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 基线。
+<!-- i3:zh-CN:end -->
+
+Invoke the i3-ui-prototype skill.
+
+$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.

package/.claude/commands/i3-review.md

@@ -24,5 +24,5 @@ Review the current changes (staged or recent commits) across all five axes:
 4. **Security** — Input validated? Secrets safe? Auth checked? (Use i3-security-and-hardening skill)
 5. **Performance** — No N+1 queries? No unbounded ops? (Use i3-performance-optimization skill)
 
-Categorize findings as Critical, Important, or Suggestion.
+Categorize findings as Critical, Required, Optional, or Nit.
 Output a structured review with specific file:line references and fix recommendations.

package/.claude/commands/i3-ship.md

@@ -43,7 +43,7 @@ Constraints (from Claude Code's subagent model):
 
 Once all three reports are back, the main agent (not a sub-persona) synthesizes them:
 
-1. **Code Quality** — Aggregate Critical/Important findings from `code-reviewer` and any failing tests, lint, or build output. Resolve duplicates between reviewers.
+1. **Code Quality** — Aggregate Critical/Required findings from `code-reviewer` and any failing tests, lint, or build output. Resolve duplicates between reviewers.
 2. **Security** — Promote any Critical/High `security-auditor` findings to launch blockers. Cross-reference with `code-reviewer`'s security axis.
 3. **Performance** — Pull from `code-reviewer`'s performance axis; cross-check Core Web Vitals if applicable.
 4. **Accessibility** — Verify keyboard nav, screen reader support, contrast (not covered by the three personas — handle directly here, or invoke the accessibility checklist).

package/.claude-plugin/marketplace.json

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

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "i3-composer-agent",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "覆盖需求、计划、开发、测试、审查与发布的软件工程技能，默认使用简体中文。",
   "author": {
     "name": "Givolt"
@@ -12,7 +12,7 @@
   "interface": {
     "displayName": "i3 Composer Agent",
     "shortDescription": "中文软件工程全流程技能",
-    "longDescription": "i3 Composer Agent 提供 25 项工程技能，覆盖需求、计划、实现、测试、审查与发布，默认使用简体中文。",
+    "longDescription": "i3 Composer Agent 提供 26 项工程技能，覆盖需求、计划、实现、测试、审查与发布，默认使用简体中文。",
     "developerName": "Givolt",
     "category": "Productivity",
     "capabilities": [

package/.gemini/commands/i3-prototype.toml

@@ -0,0 +1,23 @@
+description = "选择模板并生成、评审和迭代交互原型，维护已确认的 UI 基线。"
+# i3-description-source: "description = \"Create, review and iterate interactive UI prototypes with template selection and approved baselines\""
+
+prompt = """
+<!-- i3:zh-CN:start -->
+## 中文交互与输出
+
+默认使用简体中文回复，包括追问、选项说明、阶段进度、分析、规格、计划、验收、代码审查与发布报告。只有用户明确要求其他语言时才切换；输入中出现英文术语、代码或引用不构成切换语言的要求。
+下文的工程步骤、审批要求、退出条件和工具约束完整有效。英文示例中的人类可读标题、说明和占位内容在实际输出时应译为中文；保留原有信息与验证标准，不删减方法。
+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 基线。
+<!-- i3:zh-CN:end -->
+
+Invoke the i3-ui-prototype skill.
+
+$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.
+"""

package/.gemini/commands/i3-review.toml

@@ -23,6 +23,6 @@ Review the current changes (staged or recent commits) across all five axes:
 4. **Security** — Input validated? Secrets safe? Auth checked? (Use i3-security-and-hardening skill)
 5. **Performance** — No N+1 queries? No unbounded ops? (Use i3-performance-optimization skill)
 
-Categorize findings as Critical, Important, or Suggestion.
+Categorize findings as Critical, Required, Optional, or Nit.
 Output a structured review with specific file:line references and fix recommendations.
 """

package/.gemini/commands/i3-ship.toml

@@ -40,7 +40,7 @@ Constraints (from Gemini CLI's subagent model):
 
 Once all three reports are back, the main agent (not a sub-persona) synthesizes them:
 
-1. **Code Quality** — Aggregate Critical/Important findings from `code-reviewer` and any failing tests, lint, or build output. Resolve duplicates between reviewers.
+1. **Code Quality** — Aggregate Critical/Required findings from `code-reviewer` and any failing tests, lint, or build output. Resolve duplicates between reviewers.
 2. **Security** — Promote any Critical/High `security-auditor` findings to launch blockers. Cross-reference with `code-reviewer`'s security axis.
 3. **Performance** — Pull from `code-reviewer`'s performance axis; cross-check Core Web Vitals if applicable.
 4. **Accessibility** — Verify keyboard nav, screen reader support, contrast (not covered by the three personas — handle directly here, or invoke the accessibility checklist).

package/README.md

@@ -1,4 +1,4 @@
-# i3 Composer Agent v2.2.2
+# i3 Composer Agent v2.3.0
 
 **Intelligence. Integration. Innovation.**
 
@@ -25,8 +25,8 @@ WorkBuddy 在第 2 项。上下键移动，空格勾选/取消，回车确认；
 搜索、翻页和命令参数预选均保留选择。搜索外 `q`、Esc 或 Ctrl-C 取消。
 确认工具后选择项目/全局范围并确认安装。
 
-全部目标均安装 25 个技能、共享参考资料，以及完整评测/Hook/脚本配套。
-全部目标同时提供 9 个命令和 4 个 Agent 角色提示。
+全部目标均安装 26 个技能、共享参考资料，以及完整评测/Hook/脚本配套。
+全部目标同时提供 10 个命令和 4 个 Agent 角色提示。
 CodeBuddy、WorkBuddy、Claude Code 使用原生命令入口；其他工具通过 Skills 机制使用，
 命令和角色文件可作为资料读取，是否自动发现取决于宿主。
 目录预设来自固定的 [Skills CLI 工具登记](https://github.com/vercel-labs/skills/blob/48dc9e8eb8aa19040e91cb90ba0b642c9cbad57e/src/agents.ts)
@@ -54,7 +54,7 @@ CodeBuddy 和 WorkBuddy 的项目安装共用 `.codebuddy/`，相同目标只安
 同版本、同范围的清单所属未修改内容会复用，新增客户端合并到清单。
 升级、修改过的内容及未登记同名冲突需确认替换；非交互使用 `--force` 前可先看 dry-run。
 安装成功后清理替换掉的旧内容及本安装器所属历史备份，失败则恢复原文件。
-升级按文件归属清理旧副本，保留用户新增文件；旧评测结果迁入新的 evals 分组。
+升级按文件归属清理旧副本，保留用户新增文件；2.2.2 的分散配套资料迁入工具根；2.2.1 的评测结果保留原位。
 同名结果内容不同时会在写入前停止；未归属本包的资料冲突也需先处理，`--force` 不会接管。
 成功后不保留临时备份。`npx -y` 确认 npm 下载；包的 `--yes` 确认安装计划。
 
@@ -63,11 +63,11 @@ CodeBuddy 和 WorkBuddy 的项目安装共用 `.codebuddy/`，相同目标只安
 | 内容 | 默认安装 | 用途 |
 | --- | --- | --- |
 | `skills/`（含技能内部的 `scripts/` 等资源） | 是 | 工程工作流及运行辅助文件 |
-| `references/i3-composer-agent/` | 是 | 技能引用的检查清单与参考资料 |
+| `i3-composer-agent/references/` | 是 | 技能引用的检查清单与参考资料 |
 | `commands/`、`agents/` | 是；发现与调用依宿主支持 | 短命令与专业角色提示 |
-| `hooks/` | 是，文件安装后按宿主方式启用 | 会话注入、文档缓存和代码块保护 |
-| `scripts/` | 是 | 评测运行器、五项校验脚本及其共享库 |
-| `evals/` | 是 | 中英文触发/行为用例、测试项目样例及插件评分规则 |
+| `i3-composer-agent/hooks/` | 是，文件安装后按宿主方式启用 | 会话注入、文档缓存和代码块保护 |
+| `i3-composer-agent/scripts/` | 是 | 评测运行器、五项校验、全部原版脚本回归测试及共享库 |
+| `i3-composer-agent/evals/` | 是 | 中英文触发/行为用例、测试项目样例及插件评分规则 |
 
 以项目安装的 `.codebuddy/` 为例，默认目录为：
 
@@ -76,42 +76,49 @@ CodeBuddy 和 WorkBuddy 的项目安装共用 `.codebuddy/`，相同目标只安
 ├─ skills/                         # 宿主和评测共用的实际技能
 ├─ commands/                       # 一份命令
 ├─ agents/                         # 一份角色提示
-├─ references/i3-composer-agent/
-├─ evals/i3-composer-agent/         # 用例、样例、插件评测与运行结果
-├─ hooks/i3-composer-agent/
-├─ scripts/i3-composer-agent/       # .cjs 入口及 lib/
-├─ docs/i3-composer-agent/
+├─ i3-composer-agent/               # 配套工具根，不是第二份插件
+│  ├─ package.json                 # 独立 CommonJS 配置，提供 npm test
+│  ├─ README.md
+│  ├─ scripts/                     # 全部脚本、原有回归测试及 lib/
+│  ├─ evals/                       # 中英文用例、样例、插件评测及结果
+│  ├─ hooks/
+│  ├─ references/
+│  ├─ docs/
+│  └─ adapters/                    # 其他命令格式和插件清单的校验输入
 └─ .i3-composer-agent.json          # 版本、布局、能力与文件归属清单
 ```
 
-每个宿主基址只有一份技能；公共资料按插件名称分组。技能内部的 scripts/references 保留。
+每个宿主基址只有一份技能；公共资料集中在配套工具根目录。技能内部的 scripts/references 保留。
 WorkBuddy 全局安装将基址换为 `~/.workbuddy/`，Codex 项目安装为 `.agents/`。
 评测、校验和适用的 Hook 读取宿主使用的实际内容，不生成第二份完整插件。
 
-从业务项目目录运行以下检查，不调用模型；也可用脚本绝对路径从任意目录运行：
+进入配套目录后运行以下命令，不调用模型：
 
 ```bash
-node .codebuddy/scripts/i3-composer-agent/validate-skills.cjs
-node .codebuddy/scripts/i3-composer-agent/validate-versions.cjs
-node .codebuddy/scripts/i3-composer-agent/validate-commands.cjs
-node .codebuddy/scripts/i3-composer-agent/validate-reference-links.cjs
-node .codebuddy/scripts/i3-composer-agent/validate-artifact-paths.cjs
-node .codebuddy/scripts/i3-composer-agent/run-evals.cjs --locale zh-CN --min-rank1 95
+cd .codebuddy/i3-composer-agent
+npm test
+node scripts/run-evals.js --locale zh-CN --min-rank1 95
 ```
 
+`npm test` 执行五项校验、中英文确定性评测和全部原版脚本回归测试。
+原版英文案例完整保留，中文案例作为增量，两种语言分别通过门槛。
+脚本也可使用绝对路径从任意目录运行；无需 `npm install`。
+
 模型行为评测需要主动运行并消耗模型额度，详见 [评测说明](evals/README.md)。
 原生脚本按安装清单检查本包内容，支持业务项目的 ESM/CommonJS 设置。
-独立插件导出目录仍可执行 `npm test`；上述检查均不能代替业务项目测试或宿主执行验收。
+配套根与独立插件导出目录均可执行 `npm test`；这些检查均不能代替业务项目测试或宿主执行验收。
 评测结果不进入安装替换清单。安装过程不执行评测，也不自动启用 Hook。
 
 可选 Hook 不影响普通技能和命令的使用，默认中文交互也不依赖 Hook。
 未配置 Hook 时，自动注入、缓存和代码块保护这些增强功能不会运行。
 会话注入仅适合缺少原生技能路由的宿主；已有原生路由时不应重复注入元技能。
-缓存与代码块保护的配置说明位于 `hooks/i3-composer-agent/` 下的 `SDD-CACHE.md`、
+缓存与代码块保护的配置说明位于 `i3-composer-agent/hooks/` 下的 `SDD-CACHE.md`、
 `SIMPLIFY-IGNORE.md`，当前示例针对 Claude Code，其他宿主需适配自己的事件协议。
 脚本依赖 Bash、jq；缓存还需 curl 和哈希工具，代码块保护还需其文档列出的工具。
 Windows PowerShell 本身不会自动提供这些脚本依赖。
 
+`i3-composer-agent/adapters/` 中的其他命令格式与插件清单用于完整回归校验，不自动注册插件。
+
 ## 通过宿主插件管理器安装
 
 默认配套已包含 Skills、Commands、Agents、references、evals、hooks 和 scripts。
@@ -154,6 +161,7 @@ CodeBuddy、WorkBuddy、Claude Code 原生安装使用 `/i3-spec`、`/i3-plan`
 | /i3-composer-agent:i3-code-simplify | 简化代码，降低复杂度，提高可读性与维护性，并保持既有行为不变。 |
 | /i3-composer-agent:i3-constraints | 访谈并定义项目质量门槛，提供合理默认值，写入 CONSTRAINTS.md 并落实约束。 |
 | /i3-composer-agent:i3-plan | 把工作拆成带验收标准、验证步骤和依赖顺序的小任务。 |
+| /i3-composer-agent:i3-prototype | 选择模板并生成、评审和迭代交互原型，维护已确认的 UI 基线。 |
 | /i3-composer-agent:i3-review | 从正确性、可读性、架构、安全和性能五个维度审查代码。 |
 | /i3-composer-agent:i3-ship | 并行调用三个专业角色执行发布前检查，主会话汇总 GO/NO-GO 决策与回滚计划。 |
 | /i3-composer-agent:i3-spec | 先编写结构化规格、目标、范围与验收标准，再进入实现。 |
@@ -162,8 +170,16 @@ CodeBuddy、WorkBuddy、Claude Code 原生安装使用 `/i3-spec`、`/i3-plan`
 
 `/i3-build auto` 按已获批准的任务计划执行完整流程。
 插件调用为 `/i3-composer-agent:i3-build auto`，原审批边界和验证条件仍有效。
+`/i3-review` 在主会话中使用代码审查技能；`/i3-test` 在主会话中使用测试驱动开发技能，
+这两个命令不会自动启动同名专业角色。测试规范的编写与 TDD 执行应按各自任务处理。
 `/i3-ship` 在宿主支持时并行运行三个专业角色；不可用时读取角色提示依次审查，
-由主会话汇总 GO/NO-GO 决策，回滚计划必需，严重问题默认阻止发布。
+由主会话汇总 GO/NO-GO 决策，回滚计划必需。代码审查使用 Critical、Required、Optional、Nit
+四级；Critical 和 Required 问题默认阻止发布，各专业角色仍保留自己的报告字段和判断规则。
+
+`/i3-prototype` 调用 `i3-ui-prototype` 技能，支持先选模板，再按业务需求生成原型。默认采用专业增强模式，
+UI/UX Pro Max 是需要单独安装的外部设计能力，不计入本包的技能数量；未安装时提示安装，
+用户也可明确选择模板模式继续。企业后台模板可用于人工测试，AI 工作台、数字孪生大屏和
+移动端模板仍在规划中。原型验收、后续迭代约束与项目需求需要单独确认；本包尚未实现企业 SOP 自动编排。
 
 ## Skills
 
@@ -192,7 +208,8 @@ CodeBuddy、WorkBuddy、Claude Code 原生安装使用 `/i3-spec`、`/i3-plan`
 | [i3-shipping-and-launch](skills/i3-shipping-and-launch/SKILL.md) | 检查生产发布条件与回滚策略。适用于上线准备、发布清单、监控、分阶段部署和回滚方案，确保风险有依据且可恢复。 |
 | [i3-source-driven-development](skills/i3-source-driven-development/SKILL.md) | 以官方文档和权威来源支撑实现决策。适用于核对框架/库用法、验证方案、查证 API 和避免过时实现，并保留来源证据。 |
 | [i3-spec-driven-development](skills/i3-spec-driven-development/SKILL.md) | 在实现前形成结构化规格。适用于新项目、功能或重大改动、PRD、需求澄清、目标与范围、场景和验收标准，以及将需求拆为独立可测试能力。 |
-| [i3-test-driven-development](skills/i3-test-driven-development/SKILL.md) | 执行测试先行的红绿重构循环。适用于实现逻辑、修复缺陷、修改行为、复现报错及证明改动有效；缺陷修复使用先证明失败的 Prove-It 模式。 |
+| [i3-test-driven-development](skills/i3-test-driven-development/SKILL.md) | 执行测试先行的红绿重构循环。适用于实现逻辑、修复缺陷、修改行为、复现报错及证明改动有效；也用于为函数补测试、修复或修改直接粘贴的代码，即使请求未提到测试；缺陷修复使用先证明失败的 Prove-It 模式。 |
+| [i3-ui-prototype](skills/i3-ui-prototype/SKILL.md) | 根据业务需求选择 UI 模板，生成、评审并迭代交互原型。适用于选择原型模板、制作可操作审查原型、检查原型一致性及维护已确认的原型基线。 |
 | [i3-using-agent-skills](skills/i3-using-agent-skills/SKILL.md) | 发现并调用合适的工程技能。适用于开始会话、判断任务意图、选择技能或工作流；作为元技能协调其他技能的发现和调用。 |
 
 ## Agent 角色

package/agents/code-reviewer.md

@@ -110,5 +110,5 @@ Categorize every finding, using the same severity labels as the `i3-code-review-
 ## Composition
 
 - **Invoke directly when:** the user asks for a review of a specific change, file, or PR.
-- **Invoke via:** `/i3-review` (single-perspective review) or `/i3-ship` (parallel fan-out alongside `security-auditor` and `test-engineer`).
+- **Invoke via:** `/i3-ship` (parallel fan-out alongside `security-auditor` and `test-engineer`). `/i3-review` runs the `i3-code-review-and-quality` skill in the main session and does not spawn this persona.
 - **Do not invoke from another persona.** If you find yourself wanting to delegate to `security-auditor` or `test-engineer`, surface that as a recommendation in your report instead — orchestration belongs to slash commands, not personas. See [docs/agents.md](../docs/agents.md).

package/agents/test-engineer.md

@@ -103,5 +103,5 @@ When analyzing test coverage:
 ## Composition
 
 - **Invoke directly when:** the user asks for test design, coverage analysis, or a Prove-It test for a specific bug.
-- **Invoke via:** `/i3-test` (TDD workflow) or `/i3-ship` (parallel fan-out for coverage gap analysis alongside `code-reviewer` and `security-auditor`).
+- **Invoke via:** `/i3-ship` (parallel fan-out for coverage gap analysis alongside `code-reviewer` and `security-auditor`). `/i3-test` runs the `i3-test-driven-development` skill in the main session and does not spawn this persona.
 - **Do not invoke from another persona.** Recommendations to add tests belong in your report; the user or a slash command decides when to act on them. See [docs/agents.md](../docs/agents.md).

package/bin/i3-composer-agent.cjs

@@ -46,7 +46,7 @@ ${pkg.name}
 上下键移动/跨页，空格勾选/取消，回车确认；列表下实时显示已选，q/Esc 退出。
 CodeBuddy、WorkBuddy、Claude Code 同时安装短命令和 Agent 角色。
 其他工具通过 Skills 调用，短命令支持取决于宿主。
-所有工具默认安装单份 skills、commands、agents；资料按 references/evals/hooks/scripts/docs 分组。
+所有工具默认安装单份 skills、commands、agents；配套资料集中在 i3-composer-agent/。
 评测、脚本和 Hook 读取同一份已安装技能。--prepare 用于另行导出标准插件并按宿主方式注册。
 WorkBuddy 桌面版建议全局安装，便于技能列表和输入补全发现。
 评测需主动运行；Hook 文件已提供，需按宿主事件协议单独启用。
@@ -205,12 +205,13 @@ async function main() {
     if (target.nativeCommands) console.log(`命令：/i3-spec、/i3-plan、/i3-build、/i3-ship（共 ${target.catalog.commands.length} 个工作流）：${target.commandsDirectory}`);
     else console.log(`命令和角色资料已提供；是否自动发现取决于宿主：${target.commandsDirectory}、${target.personasDirectory}`);
     console.log(`评测资料：${target.evalsDirectory}`);
-    console.log(`中文评测：node "${path.join(target.scriptsDirectory, 'run-evals.cjs')}" --locale zh-CN --min-rank1 95`);
+    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}（尚未启用）`);
   }
-  for (const directory of plan.preserved || []) console.log(`旧目录中保留了用户文件：${directory}`);
+  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('安装完成。评测说明见 evals/i3-composer-agent/README.md；Hook 需按宿主事件协议启用。');
+  console.log('安装完成。评测说明见 i3-composer-agent/evals/README.md；Hook 需按宿主事件协议启用。');
 }
 main().catch(error => { console.error(`${name}: ${error.message}`); process.exitCode = 1; });

package/bin/install.cjs

@@ -7,7 +7,7 @@ const crypto = require('node:crypto');
 const registry = require('./agent-targets.json');
 const { cleanupBackups } = require('./cleanup-backups.cjs');
 const { nativeAssets, renderAsset } = require('./native-layout.cjs');
-const { migrationAssets, pruneRetiredDirectories } = require('./native-migration.cjs');
+const { migrationAssets, pruneRetiredDirectories, ownsAsset } = require('./native-migration.cjs');
 const { fingerprint } = require('./asset-fingerprint.cjs');
 const root = path.resolve(__dirname, '..');
 const name = 'i3-composer-agent';
@@ -50,7 +50,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: 2, entryPrefix: 'i3-', scope: plan.scope, agents: asset.target.agents,
+  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' },
     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';
@@ -64,10 +64,10 @@ function planInstallation({ agents, scope, projectDir = process.cwd(), home = os
     const agent = registry.agents.find(item => item.id === id);
     const skillsDirectory = destination(scope === 'project' ? path.resolve(projectDir, agent.projectSkillsDir) : globalSkillsDir(agent, home, env));
     const base = path.dirname(skillsDirectory);
-    if (!targets.has(skillsDirectory)) targets.set(skillsDirectory, { agents: [], skillsDirectory, referencesDirectory: path.join(base, 'references', name),
+    if (!targets.has(skillsDirectory)) targets.set(skillsDirectory, { agents: [], skillsDirectory, toolkitDirectory: path.join(base, name), referencesDirectory: path.join(base, name, 'references'),
       commandsDirectory: path.join(base, 'commands'), personasDirectory: path.join(base, 'agents'),
-      evalsDirectory: path.join(base, 'evals', name), scriptsDirectory: path.join(base, 'scripts', name),
-      hooksDirectory: path.join(base, 'hooks', name), docsDirectory: path.join(base, 'docs', name), base });
+      evalsDirectory: path.join(base, name, 'evals'), scriptsDirectory: path.join(base, name, 'scripts'),
+      hooksDirectory: path.join(base, name, 'hooks'), docsDirectory: path.join(base, name, 'docs'), base });
     const target = targets.get(skillsDirectory);
     target.agents.push(id);
     if (['codebuddy', 'workbuddy', 'claude-code'].includes(id)) {
@@ -83,7 +83,7 @@ function planInstallation({ agents, scope, projectDir = process.cwd(), home = os
     // Earlier Windows installs persisted backslashes. Normalize before lookup
     // and containment checks so owned upgrades work across both manifest forms.
     if (owned) previous.assets = previous.assets.map(relative => typeof relative === 'string' ? relative.replaceAll('\\', '/') : relative);
-    const sameVersion = owned && previous.layoutVersion === 2 && previous.version === version && previous.scope === scope && previous.entryPrefix === 'i3-';
+    const sameVersion = owned && previous.layoutVersion === 3 && previous.version === version && previous.scope === scope && previous.entryPrefix === 'i3-';
     if (owned && previous.scope === scope && Array.isArray(previous.agents)) {
       const applicable = previous.agents.filter(id => {
         const agent = registry.agents.find(item => item.id === id);
@@ -101,9 +101,8 @@ function planInstallation({ agents, scope, projectDir = process.cwd(), home = os
     for (const asset of additions) {
       // A new grouped resource must not take ownership of an unrelated file,
       // even when --force confirms replacement of a previous installation.
-      const previousOwned = owned && previous.assets.some(relative => relative === asset.relative
-        || (previous.layoutVersion !== 2 && asset.relative.startsWith(relative + '/')));
-      asset.protectedResource = /^(references|evals|hooks|scripts|docs)\//.test(asset.relative);
+      const previousOwned = owned && ownsAsset(previous, asset.relative);
+      asset.protectedResource = /^(references|evals|hooks|scripts|docs|i3-composer-agent)\//.test(asset.relative);
       if (exists(asset.destination) && !previousOwned && asset.protectedResource) {
         throw new Error(`未归属本包的同名资源，不能覆盖，请先处理：${asset.destination}`);
       }
@@ -201,7 +200,20 @@ function executeInstallation(plan, { force = false } = {}) {
     }
     pruneRetiredDirectories(plan.assets);
     completed = true;
-    plan.preserved = plan.targets.map(target => path.join(target.base, name)).filter(file => exists(file));
+    const ownedPaths = new Set(plan.assets.filter(asset => asset.kind !== 'legacy').map(asset => asset.destination));
+    plan.preserved = [];
+    function findUserFiles(directory) {
+      if (!exists(directory) || fs.lstatSync(directory).isSymbolicLink()) return;
+      for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        const file = path.join(directory, entry.name);
+        if (entry.isDirectory()) findUserFiles(file);
+        else if (!ownedPaths.has(file) && !file.split(path.sep).includes('results')) plan.preserved.push(file);
+      }
+    }
+    for (const target of plan.targets) {
+      findUserFiles(path.join(target.base, name));
+      for (const category of ['references', 'evals', 'hooks', 'scripts', 'docs']) findUserFiles(path.join(target.base, category, name));
+    }
     return [];
   } catch (error) {
     for (const change of committed.reverse()) {

package/bin/native-command-validation.cjs

@@ -1,27 +1,22 @@
-#!/usr/bin/env node
 'use strict';
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { loadInstallation } = require('./lib/installation.cjs');
-const { frontmatterYamlErrors } = require('./lib/skill-lint.cjs');
+const { frontmatterYamlErrors } = require('./skill-lint.js');
 
-try {
-  const { root, catalog } = loadInstallation();
+function validateAgents({ root, catalog }) {
   let errors = 0;
-  for (const category of ['commands', 'agents']) {
-    for (const name of catalog[category]) {
-      const relative = `${category}/${name}.md`;
+    for (const name of catalog.agents) {
+      const relative = `agents/${name}.md`;
       const text = fs.readFileSync(path.join(root, relative), 'utf8');
       const issues = frontmatterYamlErrors(text);
       const frontmatter = text.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/)?.[1] || '';
       if (!/^description:\s*\S/m.test(frontmatter)) issues.push('缺少 description');
-      if (category === 'agents' && !new RegExp(`^name:\\s*["']?${name}["']?\\s*$`, 'm').test(frontmatter)) issues.push('角色 name 与文件名不一致');
+      if (!new RegExp(`^name:\\s*["']?${name}["']?\\s*$`, 'm').test(frontmatter)) issues.push('角色 name 与文件名不一致');
       if (!text.replace(/^---[\s\S]*?\n---/, '').trim()) issues.push('缺少提示正文');
       console.log(`${issues.length ? '✗' : '✓'} ${relative}`);
       for (const issue of issues) { console.error(`  ${issue}`); errors++; }
     }
-  }
-  console.log(`已检查 ${catalog.commands.length} 个命令、${catalog.agents.length} 个角色；${errors} 个错误。`);
-  process.exitCode = errors ? 1 : 0;
-} catch (error) { console.error(error.message); process.exitCode = 1; }
+  return errors;
+}
+module.exports = { validateAgents };

package/bin/native-layout.cjs

@@ -11,34 +11,54 @@ function replaceOnce(text, before, after, label) {
 }
 
 function nativeScript(text, relative) {
-  const setup = "const INSTALLATION = require('./lib/installation.cjs').loadInstallation();";
-  text = text.replaceAll("require('./lib/skill-lint')", "require('./lib/skill-lint.cjs')");
-  if (relative === 'scripts/lib/skill-lint.js') return text;
+  // Copied upstream test fixtures keep their original repository paths; the
+  // real installed runners always require the installation manifest.
+  const setup = "const INSTALLATION = (require('node:fs').existsSync(require('node:path').join(__dirname, 'lib', 'installation.js')) || require('node:path').basename(require('node:path').resolve(__dirname, '..')) === 'i3-composer-agent') ? require('./lib/installation.js').loadInstallation() : null;";
+  if (relative.startsWith('scripts/lib/') || relative === 'scripts/run-regressions.js') return text;
+  if (relative === 'scripts/validate-versions.js' || relative === 'scripts/validate-versions-test.js') {
+    return replaceOnce(text, 'const manifestPaths = [', setup + "\nconst MANIFEST_ROOT = INSTALLATION ? INSTALLATION.resources.adapters : require('node:path').resolve(__dirname, '..');\nconst manifestPaths = [", relative)
+      .replace('readFileSync(manifestPath, "utf8")', 'readFileSync(require("node:path").join(INSTALLATION && manifestPath === "package.json" ? INSTALLATION.toolkitRoot : MANIFEST_ROOT, manifestPath), "utf8")')
+      .replace('const expectedVersion = readManifestVersion("plugin.json");', 'const expectedVersion = readManifestVersion("plugin.json");\nif (INSTALLATION && expectedVersion !== INSTALLATION.manifest.version) throw new Error("插件版本与实际安装版本不一致");');
+  }
+  if (relative === 'scripts/floor-guard-reference-test.js') {
+    return replaceOnce(text, 'const REFERENCE = path.join(', setup + '\nconst REFERENCE = path.join(', relative)
+      .replace("__dirname, '..', 'skills',", "(INSTALLATION ? INSTALLATION.root : path.resolve(__dirname, '..')), 'skills',");
+  }
+  if (/-test\.js$/.test(relative)) return text;
   if (relative === 'scripts/validate-skills.js') {
-    text = replaceOnce(text, "const SKILLS_DIR = path.resolve(__dirname, '..', 'skills');", `${setup}\nconst SKILLS_DIR = INSTALLATION.skillsDirectory;`, relative);
-    return replaceOnce(text, 'fs.readdirSync(SKILLS_DIR)', 'INSTALLATION.catalog.skills', relative);
+    text = replaceOnce(text, "const SKILLS_DIR = path.resolve(__dirname, '..', 'skills');", setup + "\nconst SKILLS_DIR = INSTALLATION ? INSTALLATION.skillsDirectory : path.resolve(__dirname, '..', 'skills');", relative);
+    text = replaceOnce(text, "const AGENTS_DIR = path.resolve(__dirname, '..', 'agents');", "const AGENTS_DIR = INSTALLATION ? path.join(INSTALLATION.root, 'agents') : path.resolve(__dirname, '..', 'agents');", relative);
+    text = replaceOnce(text, 'fs.readdirSync(AGENTS_DIR)', "(INSTALLATION ? INSTALLATION.catalog.agents.map(name => name + '.md') : fs.readdirSync(AGENTS_DIR))", relative);
+    return replaceOnce(text, 'fs.readdirSync(SKILLS_DIR)', '(INSTALLATION ? INSTALLATION.catalog.skills : fs.readdirSync(SKILLS_DIR))', relative);
   }
   const rootDeclaration = relative === 'scripts/run-evals.js'
     ? "const ROOT = path.join(__dirname, '..');" : "const ROOT = path.resolve(__dirname, '..');";
-  text = replaceOnce(text, rootDeclaration, `${setup}\nconst ROOT = INSTALLATION.root;`, relative);
+  text = replaceOnce(text, rootDeclaration, setup + "\nconst ROOT = INSTALLATION ? INSTALLATION.root : path.resolve(__dirname, '..');", relative);
   if (relative === 'scripts/run-evals.js') {
-    text = text.replaceAll("path.join(ROOT, 'evals',", "path.join(INSTALLATION.resources.evals,")
-      .replaceAll("path.join(ROOT, 'evals/zh-CN/cases')", "path.join(INSTALLATION.resources.evals, 'zh-CN/cases')");
-    return replaceOnce(text, 'fs.readdirSync(SKILLS_DIR)', 'INSTALLATION.catalog.skills', relative);
+    text = text.replaceAll("path.join(ROOT, 'evals',", "path.join(INSTALLATION ? INSTALLATION.resources.evals : path.join(ROOT, 'evals'),")
+      .replaceAll("path.join(ROOT, 'evals/zh-CN/cases')", "path.join(INSTALLATION ? INSTALLATION.resources.evals : path.join(ROOT, 'evals'), 'zh-CN/cases')");
+    return replaceOnce(text, 'fs.readdirSync(SKILLS_DIR)', '(INSTALLATION ? INSTALLATION.catalog.skills : fs.readdirSync(SKILLS_DIR))', relative);
   }
   if (relative === 'scripts/validate-reference-links.js') {
-    text = replaceOnce(text, 'fs.readdirSync(SKILLS_DIR)', 'INSTALLATION.catalog.skills', relative);
-    return replaceOnce(text, 'references\\/[A-Za-z0-9._-]+\\.md', 'references\\/(?:[A-Za-z0-9._-]+\\/)*[A-Za-z0-9._-]+\\.md', relative);
+    text = replaceOnce(text, 'fs.readdirSync(SKILLS_DIR)', '(INSTALLATION ? INSTALLATION.catalog.skills : fs.readdirSync(SKILLS_DIR))', relative);
+    return replaceOnce(text, 'references\\/[A-Za-z0-9._-]+\\.md', '(?:i3-composer-agent\\/)?references\\/(?:[A-Za-z0-9._-]+\\/)*[A-Za-z0-9._-]+\\.md', relative);
+  }
+  if (relative === 'scripts/validate-commands.js') {
+    text = replaceOnce(text, "path.join(ROOT, '.claude', 'commands')", "path.join(ROOT, INSTALLATION ? 'commands' : '.claude/commands')", relative);
+    text = replaceOnce(text, "path.join(ROOT, '.gemini', 'commands')", "path.join(INSTALLATION ? INSTALLATION.resources.adapters : ROOT, '.gemini', 'commands')", relative);
+    text = replaceOnce(text, "path.join(ROOT, 'commands')", "path.join(INSTALLATION ? INSTALLATION.resources.adapters : ROOT, 'commands')", relative);
+    text = replaceOnce(text, 'fs.readdirSync(dir)', "(INSTALLATION ? (ext === '.md' ? INSTALLATION.catalog.commands.map(name => name + '.md') : fs.readdirSync(dir).filter(file => INSTALLATION.catalog.commands.includes(NAME_MAP_REVERSE[path.basename(file, ext)] ?? path.basename(file, ext)))) : fs.readdirSync(dir))", relative);
+    return replaceOnce(text, '  let errors = 0;', "  let errors = INSTALLATION ? require('./lib/validate-agents.js').validateAgents(INSTALLATION) : 0;", relative);
   }
   if (relative === 'scripts/validate-artifact-paths.js') {
     const guarded = text.match(/const GUARDED_FILES = \[[\s\S]*?\n\];/)?.[0];
     if (!guarded) throw new Error(`缺少原生产物检查配置：${relative}`);
-    return text.replace(guarded, `const GUARDED_FILES = [
-  ...INSTALLATION.catalog.commands.map(name => 'commands/' + name + '.md'),
-  'skills/i3-spec-driven-development/SKILL.md',
-  'skills/i3-planning-and-task-breakdown/SKILL.md',
-  ...INSTALLATION.manifest.assets.filter(file => /^docs\\/i3-composer-agent\\/(getting-started|adoption-guide|copilot-setup)\\.md$/.test(file)),
-];`);
+    text = text.replace(guarded, 'const GUARDED_FILES = INSTALLATION ? [\n' +
+      "  ...INSTALLATION.catalog.commands.map(name => 'commands/' + name + '.md'),\n" +
+      "  'skills/i3-spec-driven-development/SKILL.md', 'skills/i3-planning-and-task-breakdown/SKILL.md',\n" +
+      "  ...INSTALLATION.manifest.assets.filter(file => /^(?:i3-composer-agent\\/docs\\/(getting-started|adoption-guide|copilot-setup)\\.md|i3-composer-agent\\/adapters\\/(?:\\.gemini\\/commands|commands)\\/i3-(spec|planning|build)\\.toml)$/.test(file)),\n" +
+      '] : ' + guarded.slice('const GUARDED_FILES = '.length));
+    return text.replace(/^GUARDED_FILES\.push\(.*\);$/m, "if (!INSTALLATION) $&");
   }
   throw new Error(`尚未适配的公共脚本：${relative}`);
 }
@@ -47,6 +67,18 @@ function renderAsset(buffer, asset) {
   const relative = asset.sourceRelative || '';
   if (relative.startsWith('evals/fixtures/')) return buffer;
   let text = buffer.toString('utf8');
+  if (asset.kind === 'toolkit-package') {
+    const pkg = JSON.parse(text);
+    return Buffer.from(JSON.stringify({ name: pkg.name, version: pkg.version, private: true,
+      type: 'commonjs', engines: pkg.engines, scripts: Object.fromEntries(
+        Object.entries(pkg.scripts).filter(([key]) => ['test', 'validate', 'eval', 'test:regression'].includes(key))) }, null, 2) + '\n');
+  }
+  if (asset.kind === 'toolkit-readme') return Buffer.from(
+    '# i3 Composer Agent 配套工具\n\n' +
+    '本目录提供评测、校验、回归测试、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');
   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') {
@@ -71,7 +103,7 @@ function renderAsset(buffer, asset) {
     });
   }
   // Shared references move; skill-local references and executable assets stay.
-  text = text.replace(/((?:\.\.\/){2,})references\/(?!i3-composer-agent\/)/g, `$1references/${name}/`);
+  text = text.replace(/((?:\.\.\/){2,})references\//g, '$1' + name + '/references/');
   // Resolve actual Markdown links through the same source-to-destination map.
   text = text.replace(/(\]\()([^\s)#]+)(#[^\s)]+)?(\))/g, (match, open, link, fragment = '', close) => {
     if (/^(?:[a-z]+:|\/)/i.test(link)) return match;
@@ -81,9 +113,9 @@ function renderAsset(buffer, asset) {
     return open + path.posix.relative(path.posix.dirname(asset.relative), mapped) + fragment + close;
   });
   if (asset.kind === 'command' || asset.kind === 'persona') {
-    text = text.replaceAll('docs/agents.md', `docs/${name}/agents.md`);
+    text = text.replaceAll('docs/agents.md', name + '/docs/agents.md');
   }
-  if (relative.startsWith('hooks/')) text = text.replace(/\bhooks\/(?!i3-composer-agent\/)/g, `hooks/${name}/`);
+  if (relative.startsWith('hooks/')) text = text.replace(/\bhooks\//g, name + '/hooks/');
   return Buffer.from(text);
 }
 
@@ -110,24 +142,28 @@ function nativeAssets(root, target, packageFiles, version) {
   visit('skills', 'skills', 'skill');
   visit('.claude/commands', 'commands', 'command');
   visit('agents', 'agents', 'persona');
-  visit('references', `references/${name}`, 'reference');
-  visit('README.md', `docs/${name}/README.md`, 'docs');
+  visit('references', name + '/references', 'reference');
+  visit('README.md', name + '/docs/README.md', 'docs');
+  visit('README.md', name + '/README.md', 'toolkit-readme');
+  visit('package.json', name + '/package.json', 'toolkit-package');
   for (const file of packageFiles) {
     const category = file.split('/')[0];
     if (!['evals', 'hooks', 'scripts', 'docs'].includes(category)) continue;
-    if (file === 'scripts/validate-commands.js' || file === 'scripts/validate-versions.js') continue;
-    const relative = `${category}/${name}${file.slice(category.length)}`.replace(/\.js$/, category === 'scripts' ? '.cjs' : '.js');
+    const relative = name + '/' + file;
     visit(file, relative, category === 'scripts' ? 'script' : category);
   }
-  visit('bin/native-runtime.cjs', `scripts/${name}/lib/installation.cjs`, 'runtime');
-  visit('bin/native-command-validation.cjs', `scripts/${name}/validate-commands.cjs`, 'native-validator');
-  visit('bin/native-version-validation.cjs', `scripts/${name}/validate-versions.cjs`, 'native-validator');
+  visit('bin/native-runtime.cjs', name + '/scripts/lib/installation.js', 'runtime');
+  visit('bin/native-command-validation.cjs', name + '/scripts/lib/validate-agents.js', 'runtime');
+  for (const file of ['commands', '.gemini/commands', 'plugin.json', '.codex-plugin/plugin.json',
+    '.claude-plugin/plugin.json', '.claude-plugin/marketplace.json', '.agents/plugins/marketplace.json']) {
+    visit(file, name + '/adapters/' + file, 'adapter');
+  }
   target.catalog = {
     skills: fs.readdirSync(path.join(root, 'skills')).filter(id => fs.existsSync(path.join(root, 'skills', id, 'SKILL.md'))).sort(),
     commands: fs.readdirSync(path.join(root, '.claude/commands')).filter(file => file.endsWith('.md')).map(file => file.slice(0, -3)).sort(),
     agents: fs.readdirSync(path.join(root, 'agents')).filter(file => file.endsWith('.md')).map(file => file.slice(0, -3)).sort(),
   };
-  target.resources = Object.fromEntries(['references', 'evals', 'hooks', 'scripts', 'docs'].map(category => [category, `${category}/${name}`]));
+  target.resources = Object.fromEntries(['references', 'evals', 'hooks', 'scripts', 'docs', 'adapters'].map(category => [category, name + '/' + category]));
   for (const asset of assets) { asset.mapping = mapping; asset.base = target.base; }
   return assets;
 }