@givolt/i3-composer-agent 2.1.0 → 2.2.0

package/docs/codebuddy-setup.md

@@ -1,27 +1,20 @@
-# Using i3 Composer Agent with CodeBuddy
+# 在 CodeBuddy 使用 i3 Composer Agent
 
-## Desktop IDE installation
+## 桌面 IDE 安装
 
-Run inside your business project:
+在业务项目运行：
 
 ```bash
 npx @givolt/i3-composer-agent --codebuddy
 ```
 
-The terminal wizard preselects CodeBuddy, still allows multiple tools, and asks
-for project or global scope before installing. Project scope writes these paths:
+向导预选 CodeBuddy，可增加其他工具，再选择项目或全局范围。
+项目安装提供 `.codebuddy/skills/`（25 个技能）、`references/`、
+`commands/`（9 个命令）和 `agents/`（4 个角色）。
+全局使用 `~/.codebuddy/` 的相同结构。默认中文说明和回复；技能/命令标识不改名。
+安装成功清理旧内容，失败恢复；设置与自定义命令保留。
 
-- `.codebuddy/skills/` — all 25 skills with `i3-` IDs.
-- `.codebuddy/references/` — shared checklists used by skill-relative links.
-- `.codebuddy/commands/` — all 9 existing lifecycle workflows.
-- `.codebuddy/agents/` — all 4 persona definitions.
-
-Global scope uses the same layout under `~/.codebuddy/`. Unchanged manifest-owned
-assets from the same version are reused. Modified files, unowned collisions and
-upgrades require confirmed replacement. Previous files are removed after
-successful installation; a failure restores them. Settings are preserved.
-Reload the CodeBuddy window or start a new chat, then inspect
-the Skills list and type `/` to inspect the command menu.
+重新加载窗口或新建会话，检查技能列表与 `/` 命令补全：
 
 ```text
 /i3-spec
@@ -32,66 +25,39 @@ the Skills list and type `/` to inspect the command menu.
 /i3-ship
 ```
 
-The command wrappers reference installed skill IDs without the plugin namespace.
-Their workflow content and approval gates are retained. File installation does
-not itself prove that the IDE has discovered or executed every workflow.
-
-For multiple tools or a noninteractive installation:
+命令直接调用安装的技能 ID，保留 `$ARGUMENTS`、原工程规则和审批边界。
+发布命令按宿主能力并行审查或顺序降级，主会话汇总并提供回滚计划。
 
 ```bash
 npx @givolt/i3-composer-agent --agents codebuddy,codex --scope project --yes
-npx @givolt/i3-composer-agent --agents codebuddy,workbuddy --scope project --yes
-npx @givolt/i3-composer-agent --codebuddy --scope global --yes
+npx @givolt/i3-composer-agent --agents codebuddy,workbuddy --scope global --yes
 ```
 
-CodeBuddy and WorkBuddy share `.codebuddy/` project files. Installing either
-client first and adding the other at the same package version reuses unmodified
-owned files and merges the client IDs. Global WorkBuddy files use
-`~/.workbuddy/`, independently of `~/.codebuddy/`. See [WorkBuddy setup](workbuddy-setup.md).
-
-CodeBuddy documents [IDE skills](https://www.codebuddy.cn/docs/ide/Features/Skills)
-and [IDE custom commands](https://www.codebuddy.cn/docs/ide/User-guide/Slash-Commands).
-The directory layout follows its [configuration directory reference](https://www.codebuddy.cn/docs/cli/codebuddy-dir).
+CodeBuddy 与 WorkBuddy 项目共用 `.codebuddy/`；同版本追加客户端会复用未修改内容。
+全局目录彼此独立。WorkBuddy 桌面版建议全局安装，详见 [WorkBuddy 说明](workbuddy-setup.md)。
+升级或同名冲突先查看 `--dry-run`，再确认或使用 `--yes --force`。
 
-## CodeBuddy Code native plugin registration
+## CodeBuddy Code 完整插件
 
-For the terminal CodeBuddy Code plugin manager, explicitly prepare the full
-plugin instead of native skill installation:
+终端宿主的插件管理器使用完整目录：
 
 ```bash
 npx @givolt/i3-composer-agent --prepare --codebuddy
 ```
 
-In CodeBuddy Code, register the prepared directory and install the plugin:
+在 CodeBuddy Code 中执行 CLI 显示的注册命令，目录不同时使用绝对路径：
 
 ```text
 /plugin marketplace add ./i3-composer-agent
 /plugin install i3-composer-agent@i3-composer-agent
 ```
 
-Use the absolute directory printed by the CLI if CodeBuddy has a different
-working directory. Choose the intended installation scope in CodeBuddy Code's native
-plugin manager. Reload plugins or start a new session after installation.
-
-CodeBuddy Code supports the existing `.claude-plugin/plugin.json` compatibility
-manifest. It declares `.claude/commands/` and `commands/`, preserving the nine
-original lifecycle commands and their workflow content.
-
-```text
-/i3-composer-agent:i3-spec
-/i3-composer-agent:i3-plan
-/i3-composer-agent:i3-build
-/i3-composer-agent:i3-build auto
-/i3-composer-agent:i3-review
-/i3-composer-agent:i3-ship
-```
-
-Skill IDs and command filenames use `i3-`. Persona names, artifact paths,
-and workflow gates retain their upstream behavior. The plugin namespace is
-`i3-composer-agent`.
-
-The prepared plugin includes all skills, personas, commands, hooks and shared
-`references/`. Native skill installation above does not enable plugin hooks.
+按宿主选择范围并启用后新建会话。兼容清单声明 `.claude/commands/` 与 `commands/`。
+插件命令示例为 `/i3-composer-agent:i3-spec`、`/i3-composer-agent:i3-plan`、
+`/i3-composer-agent:i3-build auto` 和 `/i3-composer-agent:i3-ship`。
+完整目录包含 Hook 与共享参考；原生文件安装不自动启用插件 Hook。
+文件落盘、宿主发现和模型实际执行应分别验证。
 
-In this explicit mode the CLI prepares files and prints registration commands. Actual host discovery
-and model execution should be verified after registering the plugin.
+目录遵循 [配置目录参考](https://www.codebuddy.cn/docs/cli/codebuddy-dir)，可参照
+[IDE Skills](https://www.codebuddy.cn/docs/ide/Features/Skills) 与
+[自定义命令](https://www.codebuddy.cn/docs/ide/User-guide/Slash-Commands) 检查发现与调用。

package/docs/codex-setup.md

@@ -1,45 +1,31 @@
-# Using i3 Composer Agent with Codex
+# 在 Codex 使用 i3 Composer Agent
 
-For the multi-tool native skill wizard, run in your project:
+在项目中运行多工具安装向导：
 
 ```bash
 npx @givolt/i3-composer-agent --codex
 ```
 
-Choose project or global scope. Native installation uses `.agents/skills/`
-or `~/.agents/skills/`, plus the sibling `references/` directory. It installs
-the 25 skills with `i3-` IDs. This mode does not add short lifecycle
-slash commands or enable plugin hooks.
+项目范围写入 `.agents/skills/`，全局写入 `~/.agents/skills/`，并安装同级 `references/`。
+提供全部 25 个 `i3-` 技能，中文选择说明与默认中文回复在每个入口独立生效。
+此模式不安装短生命周期命令，也不自动启用插件 Hook。
 
-For complete plugin registration, prepare a persistent bundle explicitly:
+## 完整插件
 
 ```bash
 npx @givolt/i3-composer-agent --prepare --codex
-```
-
-This mode copies a persistent `./i3-composer-agent/` bundle and prints these
-native registration commands. Run them to enable the plugin:
-
-```bash
 codex plugin marketplace add ./i3-composer-agent
 codex plugin add i3-composer-agent@i3-composer-agent
 ```
 
-Start a new Codex session after registration. All 25 skills use
-`i3-` IDs. In CLI/IDE, use `/skills` or `$i3-spec-driven-development`; in chat,
-explicitly request the relevant skill from i3 Composer Agent.
-
-The adapter in `.codex-plugin/plugin.json` points at the unchanged `skills/`
-layout. Shared checklists remain under `references/`, so skill-relative links
-resolve inside the complete plugin bundle.
-
-The short lifecycle commands (`/i3-spec`, `/i3-plan`, `/i3-build`, `/i3-ship`) remain
-available in hosts that load the Claude-compatible command manifest. Codex
-lifecycle-command adaptation is separate from this brand conversion. Native
-Codex `/plan` switches planning mode; it is not the plugin's planning wrapper.
+准备模式产生持久目录并显示注册命令。注册启用后新建会话，
+通过 `/skills`、`$i3-spec-driven-development` 等技能名称，或在聊天中明确指定技能调用。
+插件适配清单指向 `skills/`；共享资料保留相对链接可解析的 `references/` 布局。
 
-Do not preload `i3-using-agent-skills/SKILL.md` into always-on context: Codex routes
-skills natively. The meta-skill can remain installed and explicitly invoked.
+Codex 原生 `/plan` 切换宿主计划模式，不是插件命令包装。
+`/i3-spec`、`/i3-plan`、`/i3-build`、`/i3-ship` 供支持兼容命令清单的宿主使用。
+Codex 短命令适配是独立的宿主能力，不影响技能中文化与品牌标识。
 
-For local source testing, replace `./i3-composer-agent` above with the absolute
-path to the branded checkout. The CLI does not modify existing plugin settings.
+Codex 已有原生技能路由，勿把元技能全文预加载为常驻上下文。
+元技能仍可安装并按需显式调用。CLI 保留已有插件设置；测试本地目录时使用绝对路径。
+文件安装、宿主发现与实际模型工作流分别验证。

package/docs/commandcode-setup.md

@@ -1,5 +1,13 @@
 # Using i3-composer-agent with Command Code
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 [Command Code](https://commandcode.ai) has a native skills system. The built-in `cmd skills` command clones a GitHub repo, recursively discovers every `SKILL.md`, and installs the ones you pick.
 
 The Command Code binary is available as `cmd` (with aliases `cmdc` on Windows and `command-code`). The examples below use `cmd`.

package/docs/copilot-cli-setup.md

@@ -1,5 +1,13 @@
 # Using i3-composer-agent with GitHub Copilot CLI
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 The standalone `copilot` command-line tool installs this repository as a plugin and discovers every skill in `skills/`. For Copilot inside VS Code, see [copilot-setup.md](copilot-setup.md) instead — the setup and the invocation model are different.
 
 ## Install

package/docs/copilot-setup.md

@@ -1,5 +1,13 @@
 # Using i3-composer-agent with GitHub Copilot
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 This guide covers Copilot in VS Code. For the standalone `copilot` command-line tool, see [copilot-cli-setup.md](copilot-cli-setup.md).
 
 **What an install actually gives you:** the skills. Each installed skill becomes a slash command named after its frontmatter `name` — `/i3-spec-driven-development`, `/i3-test-driven-development`, and so on. `npx skills add /path/to/i3-composer-agent` and the manual copy below both install skills only. Neither of those two routes copies this repo's short lifecycle wrappers (`/i3-spec`, `/i3-plan`, `/i3-build`, `/i3-test`, `/i3-review`, `/i3-ship`) — those are Claude Code commands living in `.claude/commands/`. Use the full skill names, or add your own aliases — see [Lifecycle workflows](#lifecycle-workflows).

package/docs/cursor-setup.md

@@ -1,5 +1,13 @@
 # Using i3-composer-agent with Cursor
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 How to wire [i3-composer-agent](../README.md) into **Cursor** using current, supported project context — not legacy monolith files or Kaizen-specific layouts.
 
 ---

package/docs/gemini-cli-setup.md

@@ -1,5 +1,13 @@
 # Using i3-composer-agent with Gemini CLI
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 ## Setup
 
 ### Option 1: Install as Skills (Recommended)

package/docs/getting-started.md

@@ -1,5 +1,13 @@
 # Getting Started with i3-composer-agent
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+安装后新建宿主会话，以任务意图选择技能。规格、计划、实施、验证和发布保持原审批边界，默认中文交互。CodeBuddy/WorkBuddy 原生安装可调用 /i3-spec、/i3-plan、/i3-build、/i3-ship；Codex 使用技能名称。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 i3-composer-agent works with any AI coding agent that accepts Markdown instructions. This guide covers the universal approach. For tool-specific setup, see the dedicated guides.
 
 Want a worked example before setting up your own project? The

package/docs/opencode-setup.md

@@ -1,5 +1,13 @@
 # OpenCode Setup
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 This guide explains how to use i3 Composer Agent with OpenCode. The reusable assets are the markdown skills in the `skills/` directory; the root `AGENTS.md` file in this repository is repo-scoped and should not be copied into other projects.
 
 ## Overview

package/docs/other-hosts.md

@@ -1,5 +1,13 @@
 # Other hosts
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 These hosts install the pack but are not in the README's install section, because no maintainer has run the current release on them. Each entry is one line: the host and its install command. To add one, see [Adding a Host Guide](../CONTRIBUTING.md#adding-a-host-guide).
 
 Skills are plain `SKILL.md` folders, so any agent that reads the i3 Composer Agent layout can load them. See [getting-started.md](getting-started.md).

package/docs/windsurf-setup.md

@@ -1,5 +1,13 @@
 # Using i3-composer-agent with Windsurf
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+按下文完整工程步骤、检查项与验证条件执行。根据任务选择适用步骤，保留证据、风险和退出条件；正文示例中的英文标签在面向用户输出时译为中文。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 ## Setup
 
 ### Project Rules

package/docs/workbuddy-setup.md

@@ -1,51 +1,28 @@
-# Using i3 Composer Agent with WorkBuddy
+# 在 WorkBuddy 使用 i3 Composer Agent
 
-## Native installation
-
-Run inside your project:
-
-```bash
-npx @givolt/i3-composer-agent --workbuddy
-```
-
-The terminal wizard preselects WorkBuddy and lets you add other clients before
-choosing project or global scope. For explicit installation:
+## 推荐全局安装
 
 ```bash
-npx @givolt/i3-composer-agent --workbuddy --scope project --yes
-npx @givolt/i3-composer-agent --agents codebuddy,workbuddy --scope project --yes
+npx @givolt/i3-composer-agent --workbuddy --scope global
 npx @givolt/i3-composer-agent --workbuddy --scope global --yes
+npx @givolt/i3-composer-agent --agents codebuddy,workbuddy --scope global --yes
 ```
 
-| Selected clients | Project files | Global files |
-| --- | --- | --- |
-| CodeBuddy | `.codebuddy/` | `~/.codebuddy/` |
-| WorkBuddy | `.codebuddy/` | `~/.workbuddy/` |
-| CodeBuddy and WorkBuddy | One shared `.codebuddy/` installation | One installation in each client's directory |
-
-WorkBuddy natively discovers project Commands, Skills and personas in
-`.codebuddy/`. If your project already has `.workbuddy/`, i3 preserves its
-contents and adds `.codebuddy/` for the shared native files. Both directories may
-therefore exist in the same workspace.
+向导中 WorkBuddy 位于第 2 项，预选后仍可多选。全局目录：
 
-Project installation includes:
+- `~/.workbuddy/skills/`：25 个 `i3-` 技能，选择说明和默认回复中文。
+- `~/.workbuddy/commands/`：9 个 `/i3-*` 短命令。
+- `~/.workbuddy/agents/`：4 个专业角色。
+- `~/.workbuddy/references/`：共享参考和标准 MIT 许可。
+- `~/.workbuddy/docs/agents.md`：角色说明。
+- `~/.workbuddy/.i3-composer-agent.json`：安装内容所有权及客户端清单。
 
-- `.codebuddy/skills/`: all 25 Skills with their existing `i3-` IDs.
-- `.codebuddy/commands/`: all 9 short `/i3-*` workflows.
-- `.codebuddy/agents/`: all 4 persona prompts.
-- `.codebuddy/references/`: shared references and the standard MIT license.
-- `.codebuddy/docs/agents.md`: persona documentation.
-- `.codebuddy/.i3-composer-agent.json`: managed asset and client records.
+自定义 profile 可设置 `WORKBUDDY_CONFIG_DIR`，安装后打开对应 profile。
+WorkBuddy 的目录选择使用自己的配置，不借用 `CODEBUDDY_CONFIG_DIR`。
 
-Global WorkBuddy installation uses the same layout under `~/.workbuddy/`.
-If you use a separate WorkBuddy profile, set `WORKBUDDY_CONFIG_DIR` to its
-configuration directory when installing. The installer does not borrow
-`CODEBUDDY_CONFIG_DIR` for WorkBuddy. Open the corresponding profile in the host.
+## 发现和调用
 
-## Discovery and invocation
-
-Open the project in WorkBuddy and start a new chat after installation. Type `/`
-to inspect the project Commands, and inspect the Skills list. Examples:
+安装后新建会话，查看 Skills 列表并输入 `/` 查看命令：
 
 ```text
 /i3-spec
@@ -56,37 +33,43 @@ to inspect the project Commands, and inspect the Skills list. Examples:
 /i3-ship
 ```
 
-Commands invoke the installed Skill IDs without a plugin namespace. Native
-Buddy commands refer to `CODEBUDDY.md` and the installed persona directories.
-Shared project commands refer to the current host's user-level persona directory
-so they work for either client. `/i3-ship` uses native subagents when available
-and reads the installed persona prompts sequentially otherwise. Skill content,
-`$ARGUMENTS`, workflow approval gates, and relative reference links are retained.
+命令调用安装的技能 ID，按 `CODEBUDDY.md` 与安装后的角色目录工作。
+`/i3-ship` 支持时使用原生子代理并行审查，不可用时读取三个角色提示顺序执行，
+主会话汇总 GO/NO-GO 与必需回滚计划。保留参数、审批边界和相对参考链接。
+
+## 项目与多客户端
+
+| 选择 | 项目目录 | 全局目录 |
+| --- | --- | --- |
+| CodeBuddy | `.codebuddy/` | `~/.codebuddy/` |
+| WorkBuddy | `.codebuddy/` | `~/.workbuddy/`（推荐） |
+| 两者 | 共用一次 `.codebuddy/` 安装 | 各自独立安装 |
 
-The [WorkBuddy project documentation](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Project)
-describes these native project directories. The [task-bar command documentation](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Task-Bar)
-describes command discovery, and the [CLI command documentation](https://www.codebuddy.cn/docs/cli/slash-commands)
-describes Markdown commands and `$ARGUMENTS`.
+已观察到 WorkBuddy 5.7.7 桌面 Skills 列表扫描 `.workbuddy/skills/`，
+所以项目安装的 `.codebuddy/skills/` 可能不显示，项目命令仍可发现。
+全局安装已由用户测试确认可发现技能。项目原有 `.workbuddy/` 设置保留。
+也可混合选择：
 
-## Adding a second client or upgrading
+```bash
+npx @givolt/i3-composer-agent --codebuddy --scope project --yes
+npx @givolt/i3-composer-agent --workbuddy --scope global --yes
+```
 
-Either client can be installed first. Installing the other at the same package
-version and scope reuses unmodified manifest-owned files and merges the client
-IDs. It does not create a second project copy. Missing files are restored;
-unrelated settings and custom command filenames are preserved.
+## 追加客户端与升级
 
-Review an upgrade or conflict before replacing files:
+同版本/范围的清单所属未修改内容复用，第二个客户端合并到清单，不建立第二份项目副本。
+缺失内容可恢复，设置与自定义命令文件名保留。升级或冲突可先查看：
 
 ```bash
-npx @givolt/i3-composer-agent --workbuddy --scope project --dry-run
-npx @givolt/i3-composer-agent --workbuddy --scope project --yes --force
+npx @givolt/i3-composer-agent --workbuddy --scope global --dry-run
+npx @givolt/i3-composer-agent --workbuddy --scope global --yes --force
 ```
 
-Modified assets, unowned filename collisions and different versions require
-confirmation or `--force`. Successful replacements remove old files and managed
-historical backups. If installation fails, the previous files are restored.
+升级、修改内容和未登记同名冲突需要确认；成功替换后清理旧文件与所属历史备份，失败恢复。
+原生安装提供 Skills、Commands、Agents；完整插件注册另按宿主能力处理。
+`--prepare --workbuddy` 不支持，原生安装不会启用插件 Hook。
 
-Native installation provides Commands, Skills and personas. It does not register
-a WorkBuddy plugin or enable plugin hooks; `--prepare --workbuddy` is unsupported.
-File installation and command discovery are separate from model execution and
-workflow acceptance in the host.
+可参照 [任务栏命令说明](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Task-Bar)、
+[命令格式](https://www.codebuddy.cn/docs/cli/slash-commands) 和
+[项目目录说明](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Project)。
+目录落盘、发现与模型行为分别验收。

package/hooks/SDD-CACHE.md

@@ -1,5 +1,13 @@
 # sdd-cache hook
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+WebFetch 缓存只在 HTTP 304 重验证后复用，没有 TTL；无 ETag/Last-Modified 不缓存。命中退出码 2、其他路径 0。缓存原文和原提问保持不变，人类解释默认中文。依赖 jq、curl 和哈希工具。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 Cross-session citation cache for [`i3-source-driven-development`](../skills/i3-source-driven-development/SKILL.md). Skips redundant `WebFetch` calls without weakening the skill's "verify against current docs" guarantee.
 
 ## Why

package/hooks/SIMPLIFY-IGNORE.md

@@ -1,5 +1,13 @@
 # simplify-ignore hook
 
+<!-- i3:zh-guide:start -->
+## 中文使用说明
+
+simplify-ignore-start/end 标记保护原代码字节；占位符 BLOCK_<hash>、原因、文件路径与缓存协议保持不变。编辑后恢复受保护块，异常恢复保留诊断；此 Hook 的恢复缓存与安装成功后的旧版本清理用途不同。
+
+默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
+<!-- i3:zh-guide:end -->
+
 Block-level protection for `/i3-code-simplify`. Mark code that should never be simplified — the model won't see it.
 
 ## Setup

package/hooks/sdd-cache-pre.sh

@@ -92,12 +92,12 @@ VERIFIED_AT_ISO=$(date -u -r "$FETCHED_AT" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null \
 # (docs contain backticks, $vars, and backslashes in code examples; an
 # unquoted heredoc would treat them as command substitution).
 {
-  printf '[sdd-cache] Cache hit for %s\n\n' "$URL"
-  printf 'Revalidated via HTTP 304; unchanged since %s. Use the cached\n' "$VERIFIED_AT_ISO"
-  printf 'content below as if WebFetch had just returned it.\n\n'
+  printf '[sdd-cache] 缓存命中（Cache hit）：%s\n\n' "$URL"
+  printf '已通过 HTTP 304 重验证（Revalidated），内容自 %s 起未改变。请将下方缓存\n' "$VERIFIED_AT_ISO"
+  printf '视为 WebFetch 返回结果；解释使用中文，缓存原文保持不变。\n\n'
   if [ -n "$ORIGINAL_PROMPT" ]; then
-    printf 'Original WebFetch prompt: "%s". If your angle differs, judge\n' "$ORIGINAL_PROMPT"
-    printf 'whether this reading still covers it.\n\n'
+    printf '原 WebFetch 提问（Original WebFetch prompt）："%s"。若当前问题不同，请判断\n' "$ORIGINAL_PROMPT"
+    printf '这份内容是否仍覆盖当前问题。\n\n'
   fi
   printf -- '----- BEGIN CACHED CONTENT -----\n'
   printf '%s\n' "$CONTENT"

package/hooks/session-start-test.sh

@@ -33,7 +33,7 @@ if (typeof out.additionalContext !== 'string' || !out.additionalContext.trim())
 
 const ctx = out.additionalContext;
 if (hasJq) {
-  if (!ctx.includes('i3-composer-agent loaded.')) {
+  if (!ctx.includes('i3-composer-agent 已加载。')) {
     throw new Error('additionalContext is missing startup preface');
   }
   if (!ctx.includes('# Using i3 Composer Agent')) {

package/hooks/session-start.sh

@@ -16,7 +16,7 @@ SKILLS_DIR="$(dirname "$SCRIPT_DIR")/skills"
 META_SKILL="$SKILLS_DIR/i3-using-agent-skills/SKILL.md"
 
 if ! command -v jq >/dev/null 2>&1; then
-  echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "i3-composer-agent: jq is required for the session-start hook but was not found on PATH. Install jq (e.g. `brew install jq` or `apt-get install jq`) to enable meta-skill injection. Skills remain available individually."}}'
+  echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "i3-composer-agent: 会话启动 Hook 需要 jq（jq is required），但 PATH 中未找到。请安装 jq（如 `brew install jq` 或 `apt-get install jq`）后启用元技能注入；仍可单独调用技能。"}}'
   exit 0
 fi
 
@@ -24,10 +24,10 @@ if [ -f "$META_SKILL" ]; then
   CONTENT=$(cat "$META_SKILL")
   # Use jq to properly escape and construct valid JSON
   jq -cn \
-    --arg context "i3-composer-agent loaded. Use the skill discovery flowchart to find the right skill for your task.
+    --arg context "i3-composer-agent 已加载。请按技能发现流程选择合适的技能，默认使用简体中文回复；用户明确要求其他语言时再切换。
 
 $CONTENT" \
     '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $context}}'
 else
-  echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "i3-composer-agent: i3-using-agent-skills meta-skill not found. Skills may still be available individually."}}'
+  echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "i3-composer-agent: i3-using-agent-skills 元技能未找到（meta-skill not found），仍可尝试单独调用技能。"}}'
 fi

package/hooks/simplify-ignore.sh

@@ -25,7 +25,7 @@ set -euo pipefail
 shopt -u patsub_replacement 2>/dev/null || true
 
 if ! command -v jq >/dev/null 2>&1; then
-  printf '%s\n' "error: missing jq" >&2; exit 1
+  printf '%s\n' "错误：缺少 jq（error: missing jq）" >&2; exit 1
 fi
 
 CACHE="${CLAUDE_PROJECT_DIR:-.}/.claude/.simplify-ignore-cache"
@@ -43,13 +43,13 @@ FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev
   FILE_PATH=""
 }
 if [ -n "$parse_error" ]; then
-  printf 'Warning: %s (input: %.120s)\n' "$parse_error" "$INPUT" >&2
+  printf '警告（Warning）：%s（输入：%.120s）\n' "$parse_error" "$INPUT" >&2
 fi
 
 hash_cmd() {
   if command -v shasum >/dev/null 2>&1; then shasum
   elif command -v sha1sum >/dev/null 2>&1; then sha1sum
-  else printf '%s\n' "error: missing shasum or sha1sum" >&2; exit 1; fi
+  else printf '%s\n' "错误：缺少哈希工具（error: missing shasum or sha1sum）" >&2; exit 1; fi
 }
 file_id() { printf '%s' "$1" | hash_cmd | cut -c1-16; }
 block_hash() { printf '%s' "$1" | hash_cmd | cut -c1-8; }
@@ -139,7 +139,7 @@ ${line}"
 
   # Unclosed block → flush as-is
   if [ $in_block -eq 1 ] && [ -n "$buf" ]; then
-    printf 'Warning: unclosed simplify-ignore-start in %s (block not hidden)\n' "$src" >&2
+    printf '警告：%s 中 simplify-ignore-start 未闭合，未隐藏代码块（Warning: unclosed simplify-ignore-start; block not hidden）\n' "$src" >&2
     printf '%s\n' "$buf" >> "$dest"
   fi
 
@@ -185,7 +185,7 @@ expand_file() {
           # (only trigger if BLOCK_hash is still present AND wasn't in the original block content)
           case "$block_content" in *"BLOCK_${h}"*) ;; *)
             case "$line" in *"BLOCK_${h}"*)
-              printf 'Warning: placeholder BLOCK_%s was modified by model, using fuzzy match\n' "$h" >&2
+              printf '警告：占位符 BLOCK_%s 被模型修改，使用模糊匹配恢复（Warning: placeholder; using fuzzy match）\n' "$h" >&2
               esc_fuzzy=$(escape_glob "${bp}BLOCK_${h}${bs}")
               line="${line//$esc_fuzzy/$block_content}"
               # Last resort: match just the hash token
@@ -214,7 +214,7 @@ expand_file() {
       # Get first line of block to check if it was expanded back
       first_line=$(head -1 "$bf")
       if ! grep -qF "$first_line" "$dest" 2>/dev/null; then
-        printf 'Warning: protected block BLOCK_%s was deleted by model\n' "$bh" >&2
+        printf '警告：受保护代码块 BLOCK_%s 被模型删除（Warning: protected block; deleted by model）\n' "$bh" >&2
       fi
     fi
   done
@@ -258,7 +258,7 @@ if [ -z "$TOOL_NAME" ]; then
         rewritten="$CACHE/${fid}.recovered"
         cat "$orig" > "$rewritten"
         cat "$bak" > "$orig"
-        printf 'Warning: no BLOCK_ placeholder left in %s, restored from backup. Rewrite kept at %s\n' \
+        printf '警告：%s 中没有剩余 BLOCK_ 占位符，已从事务备份恢复，改写内容保留于 %s（Warning: no BLOCK_; restored from backup）\n' \
           "$orig" "$rewritten" >&2
       fi
       rm -f "$bak" "$pathfile" "$CACHE/${fid}".block.* "$CACHE/${fid}".reason.* "$CACHE/${fid}".prefix.* "$CACHE/${fid}".suffix.*
@@ -269,7 +269,7 @@ if [ -z "$TOOL_NAME" ]; then
       mv "$bak" "${orig}.recovered"
       rm -f "$pathfile" "$CACHE/${fid}".block.* "$CACHE/${fid}".reason.* "$CACHE/${fid}".prefix.* "$CACHE/${fid}".suffix.*
       rmdir "$CACHE/${fid}.lock" 2>/dev/null
-      printf 'Warning: %s was moved/deleted. Recovered original to %s.recovered\n' "$orig" "$orig" >&2
+      printf '警告：%s 被移动或删除，已将原文件恢复到 %s.recovered（Warning: moved/deleted; Recovered original）\n' "$orig" "$orig" >&2
     fi
   done
   # Clean orphan locks (created but crash before backup)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@givolt/i3-composer-agent",
-  "description": "i3 Composer Agent: production-grade engineering skills and lifecycle commands for AI coding agents.",
+  "description": "i3 Composer Agent：默认中文的软件工程技能、命令与 Agent，覆盖规格到发布。",
   "license": "MIT",
   "author": "Givolt",
   "contributors": [
@@ -98,7 +98,7 @@
       "LICENSE"
     ]
   },
-  "version": "2.1.0",
+  "version": "2.2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/49780522/i3-composer-agent.git"