@givolt/i3-composer-agent 2.1.1 → 2.2.1

package/README.md

@@ -1,39 +1,40 @@
-# i3 Composer Agent v2.1.1
+# i3 Composer Agent v2.2.1
 
 **Intelligence. Integration. Innovation.**
 
-The npm package is `@givolt/i3-composer-agent`; the plugin and marketplace ID is
-`i3-composer-agent`. Commands and Skill IDs use the `i3-` prefix.
+面向中文环境的软件工程工作流：需求、规格、计划、开发、测试、审查与发布。
+包名为 `@givolt/i3-composer-agent`，插件/市场标识为 `i3-composer-agent`。
+Skill 和命令使用 `i3-` 前缀。默认简体中文交互；用户明确要求时可切换语言。
+代码标识、路径、参数、工具协议和机器状态保持原样。
 
-## Install with the wizard
+## 通过向导安装
 
-Run in the project where you want to use the skills:
+在要使用技能的项目中运行：
 
 ```bash
 npx @givolt/i3-composer-agent
-# Preselect a tool; the wizard still allows multiple selections:
 npx @givolt/i3-composer-agent --codebuddy
-# WorkBuddy desktop: use global scope for Skills discovery:
 npx @givolt/i3-composer-agent --workbuddy --scope global
 ```
 
-The interactive terminal wizard offers multiple tools, project or global scope,
-an installation summary, and confirmation. It offers 80 directory
-presets: the pinned [Vercel Skills CLI registry](https://github.com/vercel-labs/skills/blob/48dc9e8eb8aa19040e91cb90ba0b642c9cbad57e/src/agents.ts)
-plus a native WorkBuddy preset.
-Choose by tool ID or comma-separated menu numbers. Use `--list-agents` to list
-the choices. Directory presets are not an execution test of every host.
+首屏依次为 CodeBuddy、WorkBuddy、Codex、Claude Code、Cursor、Gemini CLI，
+WorkBuddy 在第 2 项。上下键移动，空格勾选/取消，回车确认；列表原地刷新，
+下方实时显示已选工具。移到“更多”按空格或直接按 `m` 打开其他工具。
+更多列表上下移动可跨页，`n`/`p` 或 PageDown/PageUp 整页翻页，`b`/左键返回常用。
+按 `/` 输入关键词实时搜索全部 80 个工具；回车或下键结束输入，再用空格选择。
+搜索、翻页和命令参数预选均保留选择。搜索外 `q`、Esc 或 Ctrl-C 取消。
+确认工具后选择项目/全局范围并确认安装。
 
-Every selected tool receives all 25 skills and shared references.
-CodeBuddy, WorkBuddy and Claude Code also receive 9 short command workflows
-and 4 Agent role definitions. Other tools use their native skill support;
-short lifecycle commands depend on the host. Shared destinations are installed
-once. A standard MIT license accompanies the shared references.
-Reload the IDE window or start a new session after installation. See
-[CodeBuddy setup](docs/codebuddy-setup.md), [WorkBuddy setup](docs/workbuddy-setup.md)
-and [Codex setup](docs/codex-setup.md).
+全部目标均安装 25 个技能、共享参考资料，以及完整评测/Hook/脚本配套。
+CodeBuddy、WorkBuddy、Claude Code 另安装 9 个短命令和 4 个 Agent 角色。
+其他工具通过其原生 Skills 机制使用；短命令支持取决于宿主。
+目录预设来自固定的 [Skills CLI 工具登记](https://github.com/vercel-labs/skills/blob/48dc9e8eb8aa19040e91cb90ba0b642c9cbad57e/src/agents.ts)
+并增加 WorkBuddy。目录预设验证与每个宿主的实际执行验收分别记录。
 
-For an explicit installation without prompts:
+安装后重新加载 IDE 或新建会话。详见 [CodeBuddy](docs/codebuddy-setup.md)、
+[WorkBuddy](docs/workbuddy-setup.md) 和 [Codex](docs/codex-setup.md) 安装说明。
+
+无需交互时，明确选择工具和范围：
 
 ```bash
 npx @givolt/i3-composer-agent --agents codebuddy,codex --scope project --yes
@@ -43,36 +44,57 @@ npx @givolt/i3-composer-agent --claude --scope global --yes
 npx @givolt/i3-composer-agent --codebuddy --scope project --dry-run
 ```
 
-CodeBuddy and WorkBuddy share one project installation under `.codebuddy/`.
-Existing `.workbuddy/` project settings are preserved. Global installations use
-separate `~/.codebuddy/` and `~/.workbuddy/` directories.
-
-**WorkBuddy desktop: global installation is recommended.** In WorkBuddy 5.7.7,
-project Commands are discoverable, but the desktop Skills list scans
-`.workbuddy/skills/` rather than the shared `.codebuddy/skills/` destination.
-Use `--workbuddy --scope global` for Skills list and input completion.
-For both clients, you can install CodeBuddy at project scope and WorkBuddy at
-global scope, or install both globally. See [WorkBuddy setup](docs/workbuddy-setup.md).
-
-Unchanged manifest-owned assets from the same version and scope are reused;
-adding a client merges its ID into the shared installation manifest. Modified
-files, unowned collisions and version upgrades require confirmation; use
-`--force` with noninteractive installs after reviewing the dry run.
-After successful installation, replaced files and installer-owned historical
-backups are removed. A failed installation restores the previous files.
-`npx -y` accepts npm's package download prompt; the package's own `--yes` flag
-accepts the explicit installation plan.
-
-Earlier native installations migrate their unprefixed Skill and command paths
-when those paths belong to this package's previous installation manifest.
-The migration removes owned legacy paths after successful installation. Use
-`/i3-spec` in CodeBuddy or WorkBuddy, or `$i3-spec-driven-development`
-in Codex after upgrading.
-
-## Prepare the complete plugin
-
-For native plugin registration, including plugin hooks, explicitly prepare a
-persistent `./i3-composer-agent/` bundle:
+CodeBuddy 和 WorkBuddy 的项目安装共用 `.codebuddy/`，相同目标只安装一次，
+保留已有 `.workbuddy/` 项目设置。全局分别使用 `~/.codebuddy/` 和 `~/.workbuddy/`。
+**WorkBuddy 桌面版建议全局安装**：已观察到 5.7.7 的技能列表扫描 `.workbuddy/skills/`，
+共用的项目 `.codebuddy/skills/` 可能不显示，但项目命令仍可发现。
+可让 CodeBuddy 项目安装、WorkBuddy 全局安装，或让两者都全局安装。
+
+同版本、同范围的清单所属未修改内容会复用，新增客户端合并到清单。
+升级、修改过的内容及未登记同名冲突需确认替换；非交互使用 `--force` 前可先看 dry-run。
+安装成功后清理替换掉的旧内容及本安装器所属历史备份，失败则恢复原文件。
+迁移只清理旧清单所属的无前缀 Skill/命令路径，保留自定义内容。
+标准 MIT 许可随共享参考资料安装。`npx -y` 确认 npm 下载；包的 `--yes` 确认安装计划。
+
+## 安装内容与可选功能
+
+| 内容 | 默认安装 | 用途 |
+| --- | --- | --- |
+| `skills/`（含技能内部的 `scripts/` 等资源） | 是 | 工程工作流及运行辅助文件 |
+| `references/` | 是 | 技能引用的检查清单与参考资料 |
+| `commands/`、`agents/` | CodeBuddy、WorkBuddy、Claude Code | 短命令与专业角色 |
+| `hooks/` | 是，文件安装后按宿主方式启用 | 会话注入、文档缓存和代码块保护 |
+| `scripts/` | 是 | 评测运行器、五项校验脚本及其共享库 |
+| `evals/` | 是 | 中英文触发/行为用例、测试项目样例及插件评分规则 |
+
+完整配套默认放在宿主目录下的 `i3-composer-agent/`，例如
+`.codebuddy/i3-composer-agent/` 或 `~/.workbuddy/i3-composer-agent/`。
+其中保留对应的技能、命令、角色、参考资料与清单，供评测、校验和 Hook 的相对路径使用；
+宿主调用入口继续安装在其原生目录。该配套与技能一起升级、复用和失败恢复。
+
+从配套目录运行以下检查，不调用模型：
+
+```bash
+npm test
+node scripts/run-evals.js --locale zh-CN --min-rank1 95
+```
+
+模型行为评测需要主动运行并消耗模型额度，详见 [评测说明](evals/README.md)。
+本包的 `npm test` 检查随包技能的结构和中英文触发，不是业务项目测试或宿主执行验收。
+评测结果不进入安装替换清单。安装过程不执行评测，也不自动启用 Hook。
+
+可选 Hook 不影响普通技能和命令的使用，默认中文交互也不依赖 Hook。
+未配置 Hook 时，自动注入、缓存和代码块保护这些增强功能不会运行。
+会话注入仅适合缺少原生技能路由的宿主；已有原生路由时不应重复注入元技能。
+缓存与代码块保护的配置说明分别在配套目录的 `hooks/SDD-CACHE.md`、
+`hooks/SIMPLIFY-IGNORE.md`，当前示例针对 Claude Code，其他宿主需适配自己的事件协议。
+脚本依赖 Bash、jq；缓存还需 curl 和哈希工具，代码块保护还需其文档列出的工具。
+Windows PowerShell 本身不会自动提供这些脚本依赖。
+
+## 通过宿主插件管理器安装
+
+默认配套已包含 Skills、Commands、Agents、references、evals、hooks 和 scripts。
+若希望另行导出目录，交给宿主插件管理器管理：
 
 ```bash
 npx @givolt/i3-composer-agent --prepare --codebuddy
@@ -80,80 +102,88 @@ npx @givolt/i3-composer-agent --prepare --codex
 npx @givolt/i3-composer-agent --prepare --claude
 ```
 
-The bundle includes skills, commands, personas, hooks and references. Run the
-registration commands printed by the CLI in the intended host. This preparation
-mode does not install native skills or choose the host plugin manager's scope.
-
-CodeBuddy Code (terminal) / Claude Code:
+`--prepare` 只准备 `./i3-composer-agent/` 运行文件并输出宿主注册命令，
+不会把插件自动注册到宿主，也不会启用可选 Hook。普通技能安装完成后无需再执行它。
+需要让宿主插件管理器统一发现和管理插件时，再按下面步骤注册：
+在 CodeBuddy Code（终端）或 Claude Code 中执行：
 
 ```text
 /plugin marketplace add ./i3-composer-agent
 /plugin install i3-composer-agent@i3-composer-agent
 ```
 
-Codex:
+Codex 中执行：
 
 ```bash
 codex plugin marketplace add ./i3-composer-agent
 codex plugin add i3-composer-agent@i3-composer-agent
 ```
 
-Start a new session after enabling the plugin. Codex uses the branded Skill
-names, such as `$i3-spec-driven-development`; lifecycle slash-command adaptation
-is maintained separately.
+按宿主管理器选择安装范围，启用后新建会话。原生文件安装与插件注册是两种入口。
+本包没有默认 Hook 注册配置；插件启用后，可选 Hook 仍需按上面的用途和宿主要求单独配置。
 
-## Commands
+## 命令
 
-Native CodeBuddy, WorkBuddy and Claude Code installations use short filenames such as
-`/i3-spec`, `/i3-plan`, `/i3-build` and `/i3-ship`. Hosts supporting Claude-compatible plugin
-commands load the same workflows under the plugin namespace:
+CodeBuddy、WorkBuddy、Claude Code 原生安装使用 `/i3-spec`、`/i3-plan`、
+`/i3-build`、`/i3-ship` 等短命令。支持兼容插件命令的宿主使用插件命名空间：
 
-| Command | Description |
+| 命令 | 中文说明 |
 | --- | --- |
-| /i3-composer-agent:i3-build | Implement tasks incrementally — build, test, verify, commit. Add "auto" to run the whole plan in one approved pass. |
-| /i3-composer-agent:i3-code-simplify | Simplify code for clarity and maintainability — reduce complexity without changing behavior |
-| /i3-composer-agent:i3-constraints | Define and enforce this project's quality bar — interview, sane defaults, CONSTRAINTS.md |
-| /i3-composer-agent:i3-plan | Break work into small verifiable tasks with acceptance criteria and dependency ordering |
-| /i3-composer-agent:i3-review | Conduct a five-axis code review — correctness, readability, architecture, security, performance |
-| /i3-composer-agent:i3-ship | Run the pre-launch checklist via parallel fan-out to specialist personas, then synthesize a go/no-go decision |
-| /i3-composer-agent:i3-spec | Start spec-driven development — write a structured specification before writing code |
-| /i3-composer-agent:i3-test | Run TDD workflow — write failing tests, implement, verify. For bugs, use the Prove-It pattern. |
-| /i3-composer-agent:i3-webperf | Run a web performance audit via the web-performance-auditor persona |
-
-`/i3-build auto` runs the existing approved-plan workflow in native installations;
-plugin installations use `/i3-composer-agent:i3-build auto`.
+| /i3-composer-agent:i3-build | 按任务增量实现、构建、测试、验证并提交；添加 auto 可按已获批准的完整计划执行。 |
+| /i3-composer-agent:i3-code-simplify | 简化代码，降低复杂度，提高可读性与维护性，并保持既有行为不变。 |
+| /i3-composer-agent:i3-constraints | 访谈并定义项目质量门槛，提供合理默认值，写入 CONSTRAINTS.md 并落实约束。 |
+| /i3-composer-agent:i3-plan | 把工作拆成带验收标准、验证步骤和依赖顺序的小任务。 |
+| /i3-composer-agent:i3-review | 从正确性、可读性、架构、安全和性能五个维度审查代码。 |
+| /i3-composer-agent:i3-ship | 并行调用三个专业角色执行发布前检查，主会话汇总 GO/NO-GO 决策与回滚计划。 |
+| /i3-composer-agent:i3-spec | 先编写结构化规格、目标、范围与验收标准，再进入实现。 |
+| /i3-composer-agent:i3-test | 执行 TDD：先编写失败测试，再实现和验证；缺陷使用 Prove-It 模式复现。 |
+| /i3-composer-agent:i3-webperf | 调用 web-performance-auditor 角色审查网页性能与 Core Web Vitals。 |
+
+`/i3-build auto` 按已获批准的任务计划执行完整流程。
+插件调用为 `/i3-composer-agent:i3-build auto`，原审批边界和验证条件仍有效。
+`/i3-ship` 在宿主支持时并行运行三个专业角色；不可用时读取角色提示依次审查，
+由主会话汇总 GO/NO-GO 决策，回滚计划必需，严重问题默认阻止发布。
 
 ## Skills
 
-| Skill | Description |
+| 技能 | 中文说明 |
 | --- | --- |
-| [i3-api-and-interface-design](skills/i3-api-and-interface-design/SKILL.md) | Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend. |
-| [i3-browser-testing-with-devtools](skills/i3-browser-testing-with-devtools/SKILL.md) | Tests in real browsers via Chrome DevTools MCP. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data. Requires the chrome-devtools MCP server to be configured. |
-| [i3-ci-cd-and-automation](skills/i3-ci-cd-and-automation/SKILL.md) | Automates CI/CD pipeline setup. Use when setting up or modifying build and deployment pipelines. Use when you need to automate quality gates, configure test runners in CI, or establish deployment strategies. |
-| [i3-code-review-and-quality](skills/i3-code-review-and-quality/SKILL.md) | Conducts multi-axis code review. Use before merging any change. Use when reviewing code written by yourself, another agent, or a human. Use when you need to assess code quality across multiple dimensions before it enters the main branch. Use when asked to review a diff or a pull request, even when the diff is pasted inline. |
-| [i3-code-simplification](skills/i3-code-simplification/SKILL.md) | Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity. |
-| [i3-constraint-driven-development](skills/i3-constraint-driven-development/SKILL.md) | Establishes a project's quality bar as a written contract and stops agents quietly lowering it. Interviews the user on which dimensions matter, supplies sane default thresholds when they have no number in mind, records everything in CONSTRAINTS.md, and watches the diff for a weakened bar — new @ts-ignore or eslint-disable suppressions, skipped or deleted tests, assertions stripped out, unimplemented stubs, thresholds edited down. Use when no quality bar is written down, when the user says "set up constraints" or "define our standards", when the user wants dimensions they care about — accessibility, web performance, coverage — set up as enforced constraints, when an agent keeps silencing checks or skipping tests to get to green, when you need a coverage or performance threshold and don't know what number to pick, or when an agent writes more code than anyone will read. |
-| [i3-context-engineering](skills/i3-context-engineering/SKILL.md) | Optimizes agent context setup. Use when starting a new session, when agent output quality degrades, when switching between tasks, or when you need to configure rules files and context for a project. |
-| [i3-debugging-and-error-recovery](skills/i3-debugging-and-error-recovery/SKILL.md) | Guides systematic root-cause debugging. Use when tests fail, builds break, something that worked yesterday broke, behavior doesn't match expectations, or you encounter any unexpected error. Use when you need to figure out what broke and why — a systematic approach to finding and fixing the root cause rather than guessing. |
-| [i3-deprecation-and-migration](skills/i3-deprecation-and-migration/SKILL.md) | Manages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. |
-| [i3-documentation-and-adrs](skills/i3-documentation-and-adrs/SKILL.md) | Records decisions and documentation. Use when you need to document an architecture decision (ADR) or the reasoning behind a design choice, when changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase. |
-| [i3-doubt-driven-development](skills/i3-doubt-driven-development/SKILL.md) | Subjects every non-trivial decision to a fresh-context adversarial review before it stands. Use when you want every assumption cross-examined before proceeding, when stress-testing a plan for hidden failure modes, when correctness matters more than speed, when working in unfamiliar code, when stakes are high (production auth, security-sensitive logic, a high-stakes migration, irreversible operations), or any time a confident output would be cheaper to verify now than to debug later. |
-| [i3-frontend-ui-engineering](skills/i3-frontend-ui-engineering/SKILL.md) | Builds production-quality, accessible, responsive user-facing UIs. Use when building or modifying interfaces and pages, creating components, implementing layouts, meeting WCAG accessibility requirements, managing state, or when the output needs to look and feel production-quality rather than AI-generated. |
-| [i3-git-workflow-and-versioning](skills/i3-git-workflow-and-versioning/SKILL.md) | Structures git workflow practices. Use when making any code change. Use when committing, branching, resolving conflicts, splitting uncommitted work in a messy working tree into clean atomic commits, opening or reviewing a pull request (PR), pushing to a remote, or when you need to organize work across multiple parallel streams. Use when cutting a release, choosing a semantic version bump, tagging, or writing a changelog. |
-| [i3-idea-refine](skills/i3-idea-refine/SKILL.md) | Refines raw ideas into sharp, actionable concepts through structured divergent and convergent thinking. Use when an idea is still vague, when you need to stress-test assumptions before committing to a plan, or when you want to expand options before converging on one. Triggers on "ideate", "refine this idea", or "stress-test my plan". |
-| [i3-incremental-implementation](skills/i3-incremental-implementation/SKILL.md) | Delivers changes incrementally in thin, verifiable slices. Use when implementing any feature or change that touches more than one file, or when picking up the next task from a plan. Use when rolling a change out behind a feature flag, when you're about to write a large amount of code at once, or when a task feels too big to land in one step. |
-| [i3-interview-me](skills/i3-interview-me/SKILL.md) | Extracts what the user actually wants instead of what they think they should want. Achieves this through one-question-at-a-time interview until ~95% confidence about the underlying intent. Use when an ask is underspecified ("build me X" without "for whom" or "why now"), when the user explicitly invokes ("interview me", "grill me", "are we sure?", "stress-test my thinking"), or when you catch yourself silently filling in ambiguous requirements before any plan, spec, or code exists. |
-| [i3-observability-and-instrumentation](skills/i3-observability-and-instrumentation/SKILL.md) | Instruments code so production behavior is visible and diagnosable. Use when adding logging, metrics, tracing, or alerting. Use when shipping any feature that runs in production and you need evidence it works. Use when production issues are reported but you can't tell what happened from the available data. |
-| [i3-performance-optimization](skills/i3-performance-optimization/SKILL.md) | Optimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. |
-| [i3-planning-and-task-breakdown](skills/i3-planning-and-task-breakdown/SKILL.md) | Breaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. |
-| [i3-security-and-hardening](skills/i3-security-and-hardening/SKILL.md) | Hardens code against vulnerabilities. Use when auditing an input handler for vulnerabilities, when handling user input, authentication, data storage, or external integrations, or when checking a login flow is safe against the OWASP Top Ten. Use when building any feature that accepts untrusted data, manages user sessions, or interacts with third-party services. Use when auditing dependencies for known vulnerabilities, triaging package-manager audit findings, or assessing supply-chain risk in a new package. Use when personal data or privacy compliance (GDPR, CCPA) is involved. |
-| [i3-shipping-and-launch](skills/i3-shipping-and-launch/SKILL.md) | Prepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. |
-| [i3-source-driven-development](skills/i3-source-driven-development/SKILL.md) | Grounds every implementation decision in official documentation. Use when you want to verify an approach against the official docs before implementing it, or when you want authoritative, source-cited code free from outdated patterns. Use when building with any framework or library where correctness matters. |
-| [i3-spec-driven-development](skills/i3-spec-driven-development/SKILL.md) | Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when drafting a PRD or requirements document with objectives and scope, or when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying. |
-| [i3-test-driven-development](skills/i3-test-driven-development/SKILL.md) | Drives development with tests using the red-green-refactor loop. Use when implementing any logic, fixing any bug, or changing any behavior. Use when you need to prove that code works, when a bug report arrives, or when you're about to modify existing functionality. |
-| [i3-using-agent-skills](skills/i3-using-agent-skills/SKILL.md) | Discovers and invokes agent skills. Use when starting a session, or when you need to decide which skill or workflow applies to the piece of work at hand. This is the meta-skill that governs how all other skills are discovered and invoked. |
-
-## Bundle options
+| [i3-api-and-interface-design](skills/i3-api-and-interface-design/SKILL.md) | 设计稳定的 API、模块接口和类型契约。适用于 REST/GraphQL 端点、模块边界、前后端接口及公共 API 设计。 |
+| [i3-browser-testing-with-devtools](skills/i3-browser-testing-with-devtools/SKILL.md) | 通过 Chrome DevTools MCP 在真实浏览器测试。适用于网页开发或排错、检查 DOM、控制台错误、网络请求、性能及视觉结果；需要配置 chrome-devtools MCP。 |
+| [i3-ci-cd-and-automation](skills/i3-ci-cd-and-automation/SKILL.md) | 配置 CI/CD 构建与部署流水线。适用于每次 PR 自动执行 lint 和测试、失败阻止合并，配置持续集成质量门禁与部署策略。 |
+| [i3-code-review-and-quality](skills/i3-code-review-and-quality/SKILL.md) | 按正确性、可读性、架构、安全与性能审查代码。适用于合并前审查自己、其他代理或人工编写的改动，包括 diff、PR 和内联代码评审。 |
+| [i3-code-simplification](skills/i3-code-simplification/SKILL.md) | 在保持行为不变的前提下简化代码。适用于简化现有代码结构、重构复杂逻辑、保留全部现有行为，并提高可读性、维护性与可扩展性。 |
+| [i3-constraint-driven-development](skills/i3-constraint-driven-development/SKILL.md) | 把项目质量标准写入 CONSTRAINTS.md 并落实为约束。适用于制定无障碍、性能、覆盖率等门槛，选择合理默认值，防止跳过测试、削弱断言、压低阈值、屏蔽错误或以空实现通过检查。 |
+| [i3-context-engineering](skills/i3-context-engineering/SKILL.md) | 优化代理上下文与项目规则。适用于新会话、输出质量下降、任务切换，以及配置项目规则文件、上下文和提示。 |
+| [i3-debugging-and-error-recovery](skills/i3-debugging-and-error-recovery/SKILL.md) | 系统复现故障、定位根因并验证修复。适用于测试失败、构建损坏、运行崩溃、功能回归、异常报错或行为不符合预期。 |
+| [i3-deprecation-and-migration](skills/i3-deprecation-and-migration/SKILL.md) | 管理废弃与迁移。适用于替换旧系统、API 或功能、迁移用户、生产数据库无停机扩展/收缩，以及决定维护或退役现有代码。 |
+| [i3-documentation-and-adrs](skills/i3-documentation-and-adrs/SKILL.md) | 记录文档、架构决策与设计理由。适用于编写 ADR、公共 API 发生变化时补充文档、交付功能，以及保存后续工程师和代理理解设计取舍所需的背景。 |
+| [i3-doubt-driven-development](skills/i3-doubt-driven-development/SKILL.md) | 对非平凡决策进行独立的对抗式审查。适用于核查假设、压力测试计划、寻找隐藏失败模式、陌生代码、安全敏感功能、生产认证或高风险不可逆迁移。 |
+| [i3-frontend-ui-engineering](skills/i3-frontend-ui-engineering/SKILL.md) | 实现可访问、响应式、具有生产质量的前端界面。适用于页面/组件开发、布局、状态管理、WCAG 无障碍、交互与视觉质量改进。 |
+| [i3-git-workflow-and-versioning](skills/i3-git-workflow-and-versioning/SKILL.md) | 组织 Git 分支、提交、冲突处理、PR 与版本发布。适用于任何代码改动、拆分工作区改动、并行开发、推送、合并、语义化版本、标签及变更日志。 |
+| [i3-idea-refine](skills/i3-idea-refine/SKILL.md) | 通过发散与收敛思考完善模糊想法。适用于创意探索、细化方案、验证假设、压力测试计划，以及确定方向前比较更多选项。 |
+| [i3-incremental-implementation](skills/i3-incremental-implementation/SKILL.md) | 把改动拆成小而完整、可验证的实现切片。适用于涉及多个文件的功能、领取计划中的下一任务、特性开关发布，以及避免一次落地过大的改动。 |
+| [i3-interview-me](skills/i3-interview-me/SKILL.md) | 通过一次一个问题的访谈或采访明确真实意图，直到约 95% 把握并确信理解用户想要什么。适用于需求不充分、缺少目标用户或目的、用户要求访谈/质询，或在提出方案、规格与计划前发现关键需求仍在猜测。 |
+| [i3-observability-and-instrumentation](skills/i3-observability-and-instrumentation/SKILL.md) | 为生产行为增加日志、指标、链路追踪与告警。适用于新增可观测性、交付生产功能并提供运行证据，以及无法从已有数据定位生产故障。 |
+| [i3-performance-optimization](skills/i3-performance-optimization/SKILL.md) | 优化前端、后端、查询和数据库性能。适用于性能指标、回归、Core Web Vitals、慢加载、N+1 查询或性能剖析发现瓶颈。 |
+| [i3-planning-and-task-breakdown](skills/i3-planning-and-task-breakdown/SKILL.md) | 把规格和明确需求拆成有顺序的任务。适用于实施计划、验收条件、验证步骤、依赖排序、范围估算，以及大任务或并行工作安排。 |
+| [i3-security-and-hardening](skills/i3-security-and-hardening/SKILL.md) | 分析漏洞、威胁与安全加固。适用于不可信输入、webhook URL 服务端请求与 SSRF 防护、认证授权、会话、数据存储、外部集成、OWASP Top Ten、依赖 CVE、供应链、个人数据与隐私合规。 |
+| [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-using-agent-skills](skills/i3-using-agent-skills/SKILL.md) | 发现并调用合适的工程技能。适用于开始会话、判断任务意图、选择技能或工作流；作为元技能协调其他技能的发现和调用。 |
+
+## Agent 角色
+
+| 角色 | 中文说明 |
+| --- | --- |
+| [code-reviewer](agents/code-reviewer.md) | 高级代码审查角色，评估正确性、可读性、架构、安全和性能。适用于合并前完整代码评审，并输出有严重程度和证据的问题报告。 |
+| [security-auditor](agents/security-auditor.md) | 安全工程角色，分析漏洞、威胁模型与安全编码。适用于安全审查、认证授权、威胁分析和加固建议，并输出审计报告。 |
+| [test-engineer](agents/test-engineer.md) | 质量工程角色，设计测试策略、编写测试并分析覆盖率。适用于测试套件设计、现有代码测试、边界/错误/并发路径与测试质量评估。 |
+| [web-performance-auditor](agents/web-performance-auditor.md) | 网页性能角色，分析 Core Web Vitals、加载、渲染与网络。适用于性能审计、CWV 分析和识别结构性性能反模式。 |
+
+## 导出与升级
 
 ```bash
 npx @givolt/i3-composer-agent --extract --dir /path/to/plugin
@@ -161,6 +191,8 @@ npx @givolt/i3-composer-agent --codebuddy --dir /path/to/plugin --dry-run
 npx @givolt/i3-composer-agent --codebuddy --dir /path/to/plugin --force
 ```
 
-Explicit `--dir` retains the plugin preparation behavior. Successful replacement
-removes the previous bundle and this plugin's historical backups. Repository-scoped
-AGENTS.md and CLAUDE.md are not copied into business projects.
+明确 `--dir` 保持完整插件准备行为。成功替换后清理旧插件和所属历史备份。
+升级时重新运行安装命令并确认替换，完成后重新加载宿主。
+仓库维护用的 AGENTS.md、CLAUDE.md 不复制进业务项目。
+Codex 通过 `$i3-spec-driven-development` 等技能名调用；其原生 `/plan` 是宿主计划模式。
+中文语言策略、工程方法、审批要求与工具限制在各入口独立生效。

package/agents/code-reviewer.md

@@ -1,8 +1,20 @@
 ---
 name: code-reviewer
-description: Senior code reviewer that evaluates changes across five dimensions — correctness, readability, architecture, security, and performance. Use for thorough code review before merge.
+description: "高级代码审查角色，评估正确性、可读性、架构、安全和性能。适用于合并前完整代码评审，并输出有严重程度和证据的问题报告。"
+# i3-description-source: "description: Senior code reviewer that evaluates changes across five dimensions — correctness, readability, architecture, security, and performance. Use for thorough code review before merge."
 ---
 
+<!-- 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 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
+
+适用说明：高级代码审查角色，评估正确性、可读性、架构、安全和性能。适用于合并前完整代码评审，并输出有严重程度和证据的问题报告。
+<!-- i3:zh-CN:end -->
+
 # Senior Code Reviewer
 
 You are an experienced Staff Engineer conducting a thorough code review. Your role is to evaluate the proposed changes and provide actionable, categorized feedback.

package/agents/security-auditor.md

@@ -1,8 +1,20 @@
 ---
 name: security-auditor
-description: Security engineer focused on vulnerability detection, threat modeling, and secure coding practices. Use for security-focused code review, threat analysis, or hardening recommendations.
+description: "安全工程角色，分析漏洞、威胁模型与安全编码。适用于安全审查、认证授权、威胁分析和加固建议，并输出审计报告。"
+# i3-description-source: "description: Security engineer focused on vulnerability detection, threat modeling, and secure coding practices. Use for security-focused code review, threat analysis, or hardening recommendations."
 ---
 
+<!-- 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 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
+
+适用说明：安全工程角色，分析漏洞、威胁模型与安全编码。适用于安全审查、认证授权、威胁分析和加固建议，并输出审计报告。
+<!-- i3:zh-CN:end -->
+
 # Security Auditor
 
 You are an experienced Security Engineer conducting a security review. Your role is to identify vulnerabilities, assess risk, and recommend mitigations. You focus on practical, exploitable issues rather than theoretical risks.

package/agents/test-engineer.md

@@ -1,8 +1,20 @@
 ---
 name: test-engineer
-description: QA engineer specialized in test strategy, test writing, and coverage analysis. Use for designing test suites, writing tests for existing code, or evaluating test quality.
+description: "质量工程角色，设计测试策略、编写测试并分析覆盖率。适用于测试套件设计、现有代码测试、边界/错误/并发路径与测试质量评估。"
+# i3-description-source: "description: QA engineer specialized in test strategy, test writing, and coverage analysis. Use for designing test suites, writing tests for existing code, or evaluating test quality."
 ---
 
+<!-- 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 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
+
+适用说明：质量工程角色，设计测试策略、编写测试并分析覆盖率。适用于测试套件设计、现有代码测试、边界/错误/并发路径与测试质量评估。
+<!-- i3:zh-CN:end -->
+
 # Test Engineer
 
 You are an experienced QA Engineer focused on test strategy and quality assurance. Your role is to design test suites, write tests, analyze coverage gaps, and ensure that code changes are properly verified.

package/agents/web-performance-auditor.md

@@ -1,8 +1,20 @@
 ---
 name: web-performance-auditor
-description: Web performance engineer focused on Core Web Vitals, loading, rendering, and network optimization. Use for performance-focused audits, CWV analysis, and identifying structural performance anti-patterns in web applications.
+description: "网页性能角色，分析 Core Web Vitals、加载、渲染与网络。适用于性能审计、CWV 分析和识别结构性性能反模式。"
+# i3-description-source: "description: Web performance engineer focused on Core Web Vitals, loading, rendering, and network optimization. Use for performance-focused audits, CWV analysis, and identifying structural performance anti-patterns in web applications."
 ---
 
+<!-- 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 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
+
+适用说明：网页性能角色，分析 Core Web Vitals、加载、渲染与网络。适用于性能审计、CWV 分析和识别结构性性能反模式。
+<!-- i3:zh-CN:end -->
+
 # Web Performance Auditor
 
 You are an experienced Web Performance Engineer conducting a performance audit. Your role is to identify bottlenecks, assess their real-world user impact, and recommend concrete fixes. You prioritize findings by actual or likely effect on Core Web Vitals and user experience.

package/bin/asset-fingerprint.cjs

@@ -21,6 +21,7 @@ function fingerprint(file, asset) {
     if (stat.isDirectory()) {
       for (const entry of fs.readdirSync(current).sort()) {
         if (asset && entry === '.DS_Store') continue;
+        if (asset?.kind === 'support' && ['results', 'node_modules', '.git'].includes(entry)) continue;
         if (!visit(path.join(current, entry), path.join(relative, entry))) return false;
       }
     } else {