@bovinphang/frontend-craft 2.9.0 → 3.0.0

package/CONTRIBUTING.zh-CN.md

@@ -1,371 +1,383 @@
-# 贡献指南
-
-> **English:** [CONTRIBUTING.md](CONTRIBUTING.md)
-
-感谢你对 `frontend-craft` 的关注。欢迎通过 Issue、Pull Request、文档修正、runtime 适配、示例补充等方式参与贡献。
-
-## 开发环境
-
-- Node.js >= 22，用于通用安装器与 OpenClaw 包构建。
-- Git。
-- 本地开发前运行 `pnpm install`。
-
-仅修改文档时，重点阅读语言与文档策略以及 Pull Request 自检。修改 skill 或 OpenClaw 时，请在提交 PR 前参考下方对应章节。
-
-快速自检（最小推荐）：
-
-```bash
-pnpm test                         # 通用校验
-pnpm run pack:skills              # Skill 变更
-pnpm run check:skills-publish     # Skill 变更
-pnpm run typecheck:openclaw       # OpenClaw 变更
-```
-
-完整的场景化命令请见后文 npm scripts 与 Pull Request 自检。
-
-## 项目结构
-
-```
-├── agents/          # Agent 定义（Markdown + YAML frontmatter）
-├── bin/             # CLI 入口 (frontend-craft.ts)
-├── commands/        # 自定义命令定义 (fec-init, fec-review, fec-scaffold)
-├── docs/            # 各 runtime 安装文档与多语言 README
-├── hooks/           # Hook 配置 (hooks.json)
-├── scripts/         # 源码运行的维护脚本（构建、打包、发布校验）
-├── skills/          # Skill 定义 (SKILL.md + metadata.json)
-├── src/             # 源代码
-│   ├── hooks/       # runtime hook 源码，打包到 dist/hooks/
-│   ├── install/     # 安装器核心 (CLI、交互式向导、各 runtime 转换器)
-│   └── openclaw/    # OpenClaw runtime TypeScript 源码
-├── templates/       # 模板文件 (Claude/Codex/OpenClaw 配置 + 共享规则)
-├── tests/           # 测试用例
-│   ├── converters/  # 转换器测试
-│   └── install/     # 安装器测试 (CLI、端到端、全 runtime dry-run)
-└── package.json     # 项目配置与脚本
-```
-
-## 本地开发与调试
-
-```bash
-# 1. 安装依赖
-pnpm install
-
-# 2. 构建 dist/bin 与 dist/hooks
-pnpm run build
-
-# 3. 本地安装到指定 runtime（如 claude）
-node dist/bin/frontend-craft.js install claude --local --dry-run  # 先 dry-run 预览
-node dist/bin/frontend-craft.js install claude --local            # 实际安装
-
-# 4. 安装到所有 runtime
-node dist/bin/frontend-craft.js install --all --dry-run
-
-# 5. 列出所有支持的 runtime
-node dist/bin/frontend-craft.js list
-```
-
-`pnpm run build` 会依次运行 `clean`、`typecheck` 和 `scripts/build-dist.ts`。本地使用 `dist/bin/frontend-craft.js` 或打包后的 hook 脚本前，请先运行它。
-
-## 测试指南
-
-测试使用 Node.js 内置 `node:test` + `assert/strict`。
-
-```bash
-# 运行所有测试
-pnpm test
-
-# 运行单个测试文件
-node --import tsx --test tests/install/cli.test.ts
-
-# 运行安装器相关测试
-node --import tsx --test tests/install/*.test.ts
-
-# 运行转换器相关测试
-node --import tsx --test tests/converters/*.test.ts
-
-# 运行全 runtime dry-run 测试
-node --import tsx --test tests/install/all-runtimes-dry.test.ts
-```
-
-测试交互式安装向导时，设置 `FRONTEND_CRAFT_FORCE_INTERACTIVE=1` 环境变量：
-
-```bash
-FRONTEND_CRAFT_FORCE_INTERACTIVE=1 node --import tsx --test tests/install/cli.test.ts
-```
-
-`pnpm test` 会先运行 `pnpm run build`，再通过 `tsx` 执行 `tests/` 下精选的 converter 与 installer 测试。
-
-## OpenClaw 构建流程
-
-OpenClaw runtime 有独立的构建管线：
-
-```bash
-pnpm run build:openclaw          # 使用 esbuild 将 TypeScript 打包到 dist/openclaw/
-pnpm run typecheck:openclaw      # TypeScript 类型检查
-pnpm run check:openclaw-dist     # 验证 dist 完整性
-pnpm run pack:openclaw           # 完整构建 + 验证 + 打包
-```
-
-源码路径：`src/openclaw/`（TypeScript）→ `dist/openclaw/index.js`（打包后的 ESM）。
-TypeScript 配置：`tsconfig.openclaw.json`。
-
-## 独立 Skill 发布包
-
-Skill 的权威源文件位于 `skills/<skill-id>/`。不要手动修改 `skill-packages/` 下的生成产物。
-
-```bash
-pnpm run pack:skills            # 为每个 skill 生成独立发布包
-pnpm run check:skills-publish   # 校验包元数据、索引和引用文件
-pnpm run pack:all               # 构建 + 测试 + OpenClaw 包 + 独立 skill 包
-```
-
-`pnpm run pack:skills` 会生成 `skill-packages/<skill-id>/`，其中包含 `SKILL.md`、该 skill 实际引用的 `references/` 文件、`metadata.json`、`package.json`、`README.md` 和 `LICENSE`。同时会生成 `skill-packages/index.json`，供平台索引或发布自动化使用。
-
-修改 skill 时，请保持这些源文件一致：
-
-- `skills/<skill-id>/SKILL.md` — runtime 使用的权威说明。
-- `skills/metadata.json` — 发布元数据、分类、标签、关键词、目标平台和包版本。
-- `skills/eval_queries.json` — 用于路由质量检查的正向/负向触发样例。
-- 当公开 skill 列表或用户可见行为变化时，同步 `README.md` 和各语言 README 摘要。
-
-## 开发 scripts
-
-包管理器固定为 pnpm 12.4.1，唯一依赖锁文件为 pnpm-lock.yaml。通过 npm 安装 pnpm 需要 Node.js >=22.13；发布插件的运行要求仍为 Node.js >=22.0.0。使用 `pnpm install --frozen-lockfile` 安装依赖。pnpm-workspace.yaml 仅允许 esbuild 构建脚本，其余当前未使用的 SDK/原生初始化显式跳过。
-
-`pnpm lint` 检查代码和中英文内容声明；`pnpm format:check` 只检查变更的源码与配置，不修改文件。`pnpm test` 自动发现 tests 下的所有 *.test.ts，无需手动维护清单。
-
-请把 `package.json` scripts 作为公开的开发入口。
-
-| Script                         | 用途                                                                       |
-| ------------------------------ | -------------------------------------------------------------------------- |
-| `pnpm run lint` | 检查代码和中英文内容声明。 |
-| `pnpm run format:check` | 检查变更源码的格式。 |
-| `pnpm run check:content` | 校验 YAML、名称、引用及本地化结构。 |
-| `pnpm run clean`                | 删除 `dist/`。                                                             |
-| `pnpm run typecheck`            | 运行主项目 TypeScript 检查，并检查 skill 辅助脚本。                        |
-| `pnpm run build`                | 运行 `clean`、`typecheck`，并通过 `scripts/build-dist.ts` 打包 CLI/hooks。 |
-| `pnpm test`                     | 先构建，再通过 `tsx` 运行精选的 `node:test` 测试集。                       |
-| `pnpm run build:openclaw`       | 构建主项目，然后打包 OpenClaw runtime 输出。                               |
-| `pnpm run audit:skills`         | 构建后输出 skill 说明长度与描述重叠度信号。                                |
-| `pnpm run typecheck:openclaw`   | 使用 `tsconfig.openclaw.json` 检查 OpenClaw 类型。                         |
-| `pnpm run check:openclaw-dist`  | 校验生成的 OpenClaw dist 输出。                                            |
-| `pnpm run pack:openclaw`        | 构建、校验并打包 OpenClaw 插件。                                           |
-| `pnpm run pack:skills`          | 先构建，再在 `skill-packages/` 下生成独立 skill 包。                       |
-| `pnpm run check:skills-publish` | 先构建，再校验独立 skill 包元数据与复制文件。                              |
-| `pnpm run pack:all`             | 构建、运行测试、打包 OpenClaw、打包 skills，并校验 skill 产物。             |
-| `pnpm run sync:version`         | 同步发布清单中的 package 版本元数据。                                      |
-| `pnpm run version`              | 运行 `sync:version` 同步版本元数据，不自动暂存文件。                       |
-| `pnpm run prepack`              | 在 `npm pack` 前构建。                                                     |
-| `pnpm run prepublishOnly`       | 在 npm publish 前同步版本并运行测试。                                      |
-
-常见变更类型建议：
-
-- Skill 变更：运行 `pnpm test`、`pnpm run audit:skills`、`pnpm run pack:skills` 和 `pnpm run check:skills-publish`。
-- OpenClaw 变更：运行 `pnpm run typecheck:openclaw` 和 `pnpm run pack:openclaw`。
-- 发布打包：运行 `pnpm run pack:all`；`prepublishOnly` 也会在发布前执行版本同步和测试。
-
-## 源码维护脚本
-
-维护脚本位于 `scripts/`，通过 `tsx` 直接运行源码；它们不会以 `dist/scripts` 形式发布。
-
-| 文件                                       | 用途                           |
-| ------------------------------------------ | ------------------------------ |
-| `scripts/audit-skills.ts`                  | Skill 大小与触发描述重叠度审计 |
-| `scripts/build-dist.ts`                    | CLI 与 runtime hook 打包       |
-| `scripts/clean-dist.mjs`                   | 删除生成的 `dist/` 输出        |
-| `scripts/sync-codex-agents-toml.ts`        | 同步 Codex agents 配置         |
-| `scripts/sync-version.ts`                  | 同步发布版本元数据             |
-| `scripts/pack-skills.ts`                   | 独立 skill 包构建              |
-| `scripts/check-skills-publish.ts`          | 独立 skill 包校验              |
-| `scripts/skill-packaging.ts`               | skill 打包共享辅助函数         |
-| `scripts/openclaw/build.ts`                | OpenClaw esbuild 打包          |
-| `scripts/openclaw/pack-openclaw.ts`        | OpenClaw 打包                  |
-| `scripts/openclaw/verify-openclaw-dist.ts` | 验证 OpenClaw dist 完整性      |
-
-## Runtime Hook 脚本
-
-Hook 脚本位于 `src/hooks/`，发布时会打包到 `dist/hooks/` 供 runtime 使用。维护脚本位于 `scripts/`，通过 `tsx` 直接运行源码，不再发布为 `dist/scripts`。
-
-| 源文件                             | 打包输出                            | 用途           |
-| ---------------------------------- | ----------------------------------- | -------------- |
-| `src/hooks/cleanup-claude-cache.ts` | `dist/hooks/fec-cleanup-claude-cache.js` | 缓存清理 |
-| `src/hooks/run-tests.ts`           | `dist/hooks/fec-run-tests.js`           | 测试运行辅助   |
-| `src/hooks/format-changed-file.ts` | `dist/hooks/fec-format-changed-file.js` | 格式化变更文件 |
-| `src/hooks/security-check.ts`      | `dist/hooks/fec-security-check.js`      | 安全检查       |
-| `src/hooks/notify.ts`              | `dist/hooks/fec-notify.js`              | 通知脚本       |
-| `src/hooks/session-start.ts`       | `dist/hooks/fec-session-start.js`       | 会话初始化     |
-
-## 架构概览
-
-通用安装器的架构如下：
-
-```
-bin/frontend-craft.ts
-  └─ src/install/cli.ts              # CLI 入口（解析命令：install/list/version/uninstall）
-       ├─ src/install/registry.ts    # runtime 注册表（名称 + 安装器映射）
-       ├─ src/install/converters/     # 各 runtime 适配器（claude, codex, cursor, copilot 等）
-       ├─ src/install/interactive.ts # 交互式安装向导（runtime/位置选择）
-       ├─ src/install/runtime-homes.ts # 全局/本地目录约定
-       └─ src/install/types.ts       # 共享 TypeScript 类型
-```
-
-`src/install/converters/` 下的每个 runtime 转换器都实现了 `types.ts` 中定义的 `InstallContext` 接口，将 skills、agents、commands、hooks 和模板写入目标 runtime 的配置目录。
-
-## 分支策略
-
-- `main` — 稳定发布分支。
-- `develop` — 开发分支（如使用）。
-- `feature/<name>` — 新功能。
-- `fix/<name>` — Bug 修复。
-- `docs/<name>` — 文档更新。
-
-## 提交规范
-
-遵循 [Conventional Commits](https://www.conventionalcommits.org/)：
-
-```text
-<type>(<scope>): <description>
-
-[optional body]
-[optional footer]
-```
-
-常见类型：
-
-| Type       | 含义             |
-| ---------- | ---------------- |
-| `feat`     | 新功能           |
-| `fix`      | Bug 修复         |
-| `docs`     | 文档             |
-| `refactor` | 重构             |
-| `test`     | 测试             |
-| `chore`    | 构建、工具或维护 |
-
-示例：
-
-```text
-feat(skills): add e2e testing skill
-fix(hooks): resolve Windows path handling
-docs(readme): update installation steps
-```
-
-## 语言与文档策略
-
-英文是公开项目治理、runtime 文档、发布说明和 GitHub 协作模板的**源语言**。多语言 README 应聚焦用户向摘要，并在贡献者或维护者细节上链接回英文文档。
-
-当 Pull Request 修改公共行为、安装步骤、runtime、agent、skill、command 或 hook 时：
-
-- 优先更新 `README.md` 与 `CHANGELOG.md`（及对应的 [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md) 若需同步中文读者）。
-- 若影响用户，需同步 `README.zh-CN.md`、`docs/zh-TW/README.md`、`docs/ja-JP/README.md` 和 `docs/ko-KR/README.md` 中的用户向摘要。
-- Claude Code Marketplace 的安装与更新说明以 [`docs/runtimes/claude.md`](docs/runtimes/claude.md) 与 [`docs/runtimes/claude.zh-CN.md`](docs/runtimes/claude.zh-CN.md) 为准；修改该流程时请更新这两份文件（根 README 与各语言 README 仅链向它们）。
-- 若同一 PR 无法完成翻译，请创建或链接后续 Issue，并在 PR 描述中说明。
-- 各语言版本中的代码示例、runtime 名称、命令名、文件路径和包名应保持一致。
-
-Issue 与 PR 使用英文最便于全球社区检索与 Review。若你更习惯中文，也欢迎提交；维护者可协助翻译标题和摘要。
-
-## 如何添加 Skill
-
-1. 在 `skills/` 下创建目录，例如 `skills/fec-my-skill/`。
-2. 创建 `SKILL.md`，包含 YAML frontmatter 与简洁说明：
-
-```markdown
----
-name: fec-my-skill
-description: Use when the user needs ...
----
-
-# Skill Title
-
-## When to Use
-
-- ...
-
-## Core Rules
-
-- ...
-```
-
-3. 在 `skills/metadata.json` 中新增条目，包括 `id`、展示名称 `name`、分类 `category`、`tags`、`summary`、发布元数据、`keywords` 和 `platforms`。其中 `version`、`license`、`homepage`、`repository` 应与 `package.json` 保持一致。
-4. 在 `skills/eval_queries.json` 中补充正向和负向触发样例。
-5. 在 `README.md` 的 Skills 表格中新增一行。
-6. 若可见目录结构变化，同步 `README.md` 与各语言 README 的目录树。
-7. 运行 `pnpm test`、`pnpm run pack:skills` 和 `pnpm run check:skills-publish`。
-
-## 如何添加 Agent
-
-1. 创建 `agents/my-agent.md`。
-2. 定义 YAML frontmatter：
-
-```markdown
----
-name: my-agent
-description: Use this agent when ...
-tools: Read, Edit, Write, Glob, Grep, Bash
-model: sonnet
-skills:
-  - relevant-skill
----
-```
-
-3. 在 `README.md` 的 Agents 表格中新增一行。
-4. 当数量或用户向描述变化时，同步 `README.zh-CN.md`、`docs/*/README.md` 与 `.claude-plugin/marketplace.json`。
-
-## 如何添加 Command
-
-1. 创建 `commands/my-command.md`。
-2. 使用 YAML frontmatter 与 Markdown 描述执行步骤。
-3. 在 `README.md` 的 Commands 表格中新增一行，并按需同步多语言用户向摘要。
-
-## 如何添加 Rule 模板
-
-1. 在 `templates/shared/rules/` 下创建 `my-rule.md`。
-2. 在 `commands/fec-init.md` 的复制清单中新增该文件。
-3. 在 `templates/claude/CLAUDE.md` 的规则导入示例中补充（如适用）。
-
-## 多工具安装器
-
-- 入口：`bin/frontend-craft.ts`。
-- 实现目录：`src/install/`（安装器、注册表、路径辅助）。
-- 交互向导与输入解析：`src/install/interactive.ts`（测试可将 `FRONTEND_CRAFT_FORCE_INTERACTIVE` 设为 `1` 以模拟管道输入下的问答）。
-- 新增 runtime 时，在 `src/install/registry.ts` 注册。
-- 在 `src/install/converters/` 下添加 runtime 安装器。
-- 参考 `src/install/runtime-homes.ts` 中的全局目录约定。
-- 在 `tests/install/` 中新增或更新测试。
-
-## 如何添加 Hook
-
-1. 更新 `hooks/hooks.json`。
-2. 如需 runtime hook 脚本，放在 `src/hooks/` 下，并优先使用跨平台 Node.js。
-3. 在 `scripts/build-dist.ts` 中新增对应入口，确保 `pnpm run build` 会将其打包到 `dist/hooks/`。
-4. 在 `hooks/hooks.json` 中，引用内置 hook 入口请使用 **`${CLAUDE_PLUGIN_ROOT}/dist/hooks/<script>.js`**（Claude Code 会在运行时替换根路径；见官方 [Plugins reference](https://code.claude.com/docs/en/plugins-reference)）。本仓库的 Claude 安装器在将 `hooks.json` 写入 `.claude/` 时，也会把 **`${CLAUDE_PLUGIN_ROOT}`** 及旧占位符 **`${FRONTEND_CRAFT_ROOT}`** 展开为绝对路径。
-5. 仓库维护脚本继续放在 `scripts/`，不要在 runtime hook 配置中直接引用它们。
-6. 更新 `README.md` 的 Hooks 表格。
-
-## Pull Request 自检
-
-提交 PR 前请确认：
-
-- [ ] 变更范围清晰，描述明确。
-- [ ] `pnpm test` 通过。
-- [ ] 修改 skill 时，`pnpm run audit:skills`、`pnpm run pack:skills` 与 `pnpm run check:skills-publish` 通过。
-- [ ] 修改 OpenClaw 代码或模板时，`pnpm run typecheck:openclaw` 与 `pnpm run pack:openclaw` 通过。
-- [ ] 用户可见行为变化已更新 `README.md` 与 `CHANGELOG.md`（及 [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md) 如适用）。
-- [ ] 多语言 README 已同步，或已链接后续翻译 Issue。
-- [ ] 新增 runtime、agent、skill、command、hook 或模板时，包含相关测试或 dry-run 覆盖。
-- [ ] 发布打包相关变更已通过 `pnpm run pack:all`，或已由 `prepublishOnly` 发布门禁覆盖。
-- [ ] 涉及安全敏感逻辑时，已按 [SECURITY.zh-CN.md](SECURITY.zh-CN.md) / [SECURITY.md](SECURITY.md) 检查。
-
-## 代码风格
-
-- Markdown 使用稳定标题和清晰表格。
-- Skill 与 Agent 描述保持简洁，因为模型路由依赖这些描述。
-- 自动化脚本优先使用跨平台 Node.js。
-- 除非特定 runtime 明确需要，否则避免依赖某个 shell 的特性。
-
-## 问题反馈
-
-使用 [GitHub Issues](https://github.com/bovinphang/frontend-craft/issues) 提交 Bug 或功能建议。请尽量包含 runtime、操作系统、Node.js 版本、执行命令、预期行为和实际行为。
-
-**安全敏感漏洞**不要提交公开 Issue，请按 [SECURITY.zh-CN.md](SECURITY.zh-CN.md)（或 [SECURITY.md](SECURITY.md)）处理。
-
-修改审核或图表能力时，同步各语言 README 与运行时指南中的范围默认值、自然语言示例、工具前提、QA 边界和覆盖报告要求。参见 [审核范围与技术图交付](docs/zh-CN/review-and-diagram-workflows.md).
+# 贡献指南
+
+> **English:** [CONTRIBUTING.md](CONTRIBUTING.md)
+
+感谢你对 `frontend-craft` 的关注。欢迎通过 Issue、Pull Request、文档修正、runtime 适配、示例补充等方式参与贡献。
+
+## 开发环境
+
+- Node.js >= 22，用于通用安装器与 OpenClaw 包构建。
+- Git。
+- pnpm 12.4.1（在 package.json 中固定）；通过 npm 安装 pnpm 需要 Node.js >=22.13。已发布的插件仍支持 Node.js >=22.0.0。
+- pnpm-lock.yaml 是唯一的依赖锁文件。pnpm-workspace.yaml 允许 esbuild 构建脚本，并显式跳过本项目未使用的可选 SDK/原生依赖安装。
+- Windows 上请通过 Corepack（`corepack enable pnpm`）或 npm 安装 pnpm，不要使用 standalone 安装器；standalone 的 pnpm 10+ 会屏蔽安装固定版本原生二进制的 lifecycle 脚本，留下 Windows 无法执行的 shim。
+- 本地开发前运行 `pnpm install --frozen-lockfile`。
+
+仅修改文档时，重点阅读语言与文档策略以及 Pull Request 自检。修改 skill 或 OpenClaw 时，请在提交 PR 前参考下方对应章节。
+
+快速自检（最小推荐）：
+
+```bash
+pnpm lint                         # ESLint + 内容一致性
+pnpm typecheck                    # TypeScript + Skill 脚本类型检查
+pnpm run check:common             # 公共快照只读校验
+pnpm test                         # 构建 + 全部测试
+pnpm run pack:skills              # Skill 变更
+pnpm run check:skills-publish     # Skill 变更
+pnpm run typecheck:openclaw       # OpenClaw 变更
+```
+
+完整的场景化命令请见后文 npm scripts 与 Pull Request 自检。
+
+## 项目结构
+
+```
+├── agents/          # Agent 定义（Markdown + YAML frontmatter）
+├── bin/             # CLI 入口 (frontend-craft.ts)
+├── commands/        # 自定义命令定义 (fec-init, fec-review, fec-scaffold)
+├── docs/            # 各 runtime 安装文档与多语言 README
+├── hooks/           # Hook 配置 (hooks.json)
+├── scripts/         # 源码运行的维护脚本（构建、打包、发布校验）
+├── skills/          # Skill 定义 (SKILL.md + metadata.json)
+├── src/             # 源代码
+│   ├── hooks/       # runtime hook 源码，打包到 dist/hooks/
+│   ├── install/     # 安装器核心 (CLI、交互式向导、各 runtime 转换器)
+│   └── openclaw/    # OpenClaw runtime TypeScript 源码
+├── templates/       # 模板文件 (Claude/Codex/OpenClaw 配置 + 共享规则)
+├── tests/           # 测试用例
+│   ├── converters/  # 转换器测试
+│   └── install/     # 安装器测试 (CLI、端到端、全 runtime dry-run)
+└── package.json     # 项目配置与脚本
+```
+
+## 本地开发与调试
+
+```bash
+# 1. 安装依赖
+pnpm install
+
+# 2. 构建 dist/bin 与 dist/hooks
+pnpm run build
+
+# 3. 本地安装到指定 runtime（如 claude）
+node dist/bin/frontend-craft.js runtime install claude --local --dry-run  # 先 dry-run 预览
+node dist/bin/frontend-craft.js runtime install claude --local            # 实际安装
+
+# 4. 安装到所有 runtime
+node dist/bin/frontend-craft.js runtime install --all --dry-run
+
+# 5. 列出所有支持的 runtime
+node dist/bin/frontend-craft.js list
+```
+
+`pnpm run build` 会依次运行 `clean`、`typecheck` 和 `scripts/build-dist.ts`。本地使用 `dist/bin/frontend-craft.js` 或打包后的 hook 脚本前，请先运行它。
+
+源码检出不支持 CLI 自身管理。使用 `node dist/bin/frontend-craft.js runtime update --dry-run` 预览包内资源更新；顶层 update/uninstall 应通过隔离的 npm/pnpm 全局安装、假包管理器及临时 HOME 验证。顶层 `--dry-run` 必须保持只读。3.0 命令迁移见 README 迁移表。
+
+## 测试指南
+
+测试使用 Node.js 内置 `node:test` + `assert/strict`。
+
+```bash
+# 运行所有测试
+pnpm test
+
+# 运行单个测试文件
+node --import tsx --test tests/install/cli.test.ts
+
+# 运行安装器相关测试
+node --import tsx --test tests/install/*.test.ts
+
+# 运行转换器相关测试
+node --import tsx --test tests/converters/*.test.ts
+
+# 运行全 runtime dry-run 测试
+node --import tsx --test tests/install/all-runtimes-dry.test.ts
+```
+
+测试交互式安装向导时，设置 `FRONTEND_CRAFT_FORCE_INTERACTIVE=1` 环境变量：
+
+```bash
+FRONTEND_CRAFT_FORCE_INTERACTIVE=1 node --import tsx --test tests/install/cli.test.ts
+```
+
+`pnpm test` 会先运行 `pnpm run build`，再递归发现 `tests/**/*.test.ts`，通过 Node.js `node:test` 串行执行全部测试。已有构建时可使用 `pnpm run test:only`。
+
+## OpenClaw 构建流程
+
+OpenClaw runtime 有独立的构建管线：
+
+```bash
+pnpm run build:openclaw          # 使用 esbuild 将 TypeScript 打包到 dist/openclaw/
+pnpm run typecheck:openclaw      # TypeScript 类型检查
+pnpm run check:openclaw-dist     # 验证 dist 完整性
+pnpm run pack:openclaw           # 完整构建 + 验证 + 打包
+```
+
+源码路径：`src/openclaw/`（TypeScript）→ `dist/openclaw/index.js`（打包后的 ESM）。
+TypeScript 配置：`tsconfig.openclaw.json`。
+
+## 独立 Skill 发布包
+
+Skill 的权威源文件位于 `skills/<skill-id>/`。不要手动修改 `skill-packages/` 下的生成产物。
+
+```bash
+pnpm run pack:skills            # 为每个 skill 生成独立发布包
+pnpm run check:skills-publish   # 校验包元数据、索引和引用文件
+pnpm run pack:all               # 构建 + 测试 + OpenClaw 包 + 独立 skill 包
+```
+
+`pnpm run pack:skills` 会生成 `skill-packages/<skill-id>/`，其中包含 `SKILL.md`、实际引用的 `references/` 及运行所需的 scripts、assets、data、styles 等资源、`metadata.json`、`package.json`、`README.md` 和 `LICENSE`。同时会生成 `skill-packages/index.json`，供平台索引或发布自动化使用。
+
+修改 skill 时，请保持这些源文件一致：
+
+- `skills/<skill-id>/SKILL.md` — runtime 使用的权威说明。
+- `skills/metadata.json` — 发布元数据、分类、标签、关键词、目标平台和包版本。
+- `skills/eval_queries.json` — 用于路由质量检查的正向/负向触发样例。
+- 当公开 skill 列表或用户可见行为变化时，同步 `README.md` 和各语言 README 摘要。
+
+## 开发 scripts
+
+包管理器固定为 pnpm 12.4.1，唯一依赖锁文件为 pnpm-lock.yaml。通过 npm 安装 pnpm 需要 Node.js >=22.13；发布插件的运行要求仍为 Node.js >=22.0.0。使用 `pnpm install --frozen-lockfile` 安装依赖。pnpm-workspace.yaml 仅允许 esbuild 构建脚本，其余当前未使用的 SDK/原生初始化显式跳过。
+
+`pnpm lint` 检查代码和中英文内容声明；`pnpm format:check` 只检查变更的源码与配置，不修改文件。`pnpm test` 自动发现 tests 下的所有 *.test.ts，无需手动维护清单。
+
+请把 `package.json` scripts 作为公开的开发入口。
+
+| Script                         | 用途                                                                       |
+| ------------------------------ | -------------------------------------------------------------------------- |
+| `pnpm run lint` | 检查代码和中英文内容声明。 |
+| `pnpm run format:check` | 检查变更源码的格式。 |
+| `pnpm run check:content` | 校验 YAML、名称、引用及本地化结构。 |
+| `pnpm run clean`                | 删除 `dist/`。                                                             |
+| `pnpm run typecheck`            | 运行主项目 TypeScript 检查，并检查 skill 辅助脚本。                        |
+| `pnpm run build`                | 运行 `clean`、`typecheck`，并通过 `scripts/build-dist.ts` 打包 CLI/hooks。 |
+| `pnpm test`                     | 先构建，再递归发现并执行全部 `node:test` 测试。                       |
+| `pnpm run build:openclaw`       | 构建主项目，然后打包 OpenClaw runtime 输出。                               |
+| `pnpm run audit:skills`         | 构建后输出 skill 说明长度与描述重叠度信号。                                |
+| `pnpm run typecheck:openclaw`   | 使用 `tsconfig.openclaw.json` 检查 OpenClaw 类型。                         |
+| `pnpm run check:openclaw-dist`  | 校验生成的 OpenClaw dist 输出。                                            |
+| `pnpm run pack:openclaw`        | 构建、校验并打包 OpenClaw 插件。                                           |
+| `pnpm run pack:skills`          | 先构建，再在 `skill-packages/` 下生成独立 skill 包。                       |
+| `pnpm run check:skills-publish` | 先构建，再校验独立 skill 包元数据与复制文件。                              |
+| `pnpm run pack:all`             | 构建、运行测试、打包 OpenClaw、打包 skills，并校验 skill 产物。             |
+| `pnpm run sync:version`         | 同步发布清单中的 package 版本元数据。                                      |
+| `pnpm run version`              | 运行 `sync:version` 同步版本元数据，不自动暂存文件。                       |
+| `pnpm run prepack`              | 在 `npm pack` 前构建。                                                     |
+| `pnpm run prepublishOnly`       | 在 npm publish 前同步版本并运行测试。                                      |
+
+常见变更类型建议：
+
+- Skill 变更：运行 `pnpm test`、`pnpm run audit:skills`、`pnpm run pack:skills` 和 `pnpm run check:skills-publish`。
+- OpenClaw 变更：运行 `pnpm run typecheck:openclaw` 和 `pnpm run pack:openclaw`。
+- 发布打包：运行 `pnpm run pack:all`；`prepublishOnly` 也会在发布前执行版本同步和测试。
+
+## 源码维护脚本
+
+维护脚本位于 `scripts/`，通过 `tsx` 直接运行源码；它们不会以 `dist/scripts` 形式发布。
+
+| 文件                                       | 用途                           |
+| ------------------------------------------ | ------------------------------ |
+| `scripts/audit-skills.ts`                  | Skill 大小与触发描述重叠度审计 |
+| `scripts/build-dist.ts`                    | CLI 与 runtime hook 打包       |
+| `scripts/clean-dist.mjs`                   | 删除生成的 `dist/` 输出        |
+| `scripts/sync-codex-agents-toml.ts`        | 同步 Codex agents 配置         |
+| `scripts/sync-version.ts`                  | 同步发布版本元数据             |
+| `scripts/pack-skills.ts`                   | 独立 skill 包构建              |
+| `scripts/check-skills-publish.ts`          | 独立 skill 包校验              |
+| `scripts/skill-packaging.ts`               | skill 打包共享辅助函数         |
+| `scripts/openclaw/build.ts`                | OpenClaw esbuild 打包          |
+| `scripts/openclaw/pack-openclaw.ts`        | OpenClaw 打包                  |
+| `scripts/openclaw/verify-openclaw-dist.ts` | 验证 OpenClaw dist 完整性      |
+
+## Runtime Hook 脚本
+
+Hook 脚本位于 `src/hooks/`，发布时会打包到 `dist/hooks/` 供 runtime 使用。维护脚本位于 `scripts/`，通过 `tsx` 直接运行源码，不再发布为 `dist/scripts`。
+
+| 源文件                             | 打包输出                            | 用途           |
+| ---------------------------------- | ----------------------------------- | -------------- |
+| `src/hooks/cleanup-claude-cache.ts` | `dist/hooks/fec-cleanup-claude-cache.js` | 缓存清理 |
+| `src/hooks/run-tests.ts`           | `dist/hooks/fec-run-tests.js`           | 测试运行辅助   |
+| `src/hooks/format-changed-file.ts` | `dist/hooks/fec-format-changed-file.js` | 格式化变更文件 |
+| `src/hooks/security-check.ts`      | `dist/hooks/fec-security-check.js`      | 安全检查       |
+| `src/hooks/notify.ts`              | `dist/hooks/fec-notify.js`              | 通知脚本       |
+| `src/hooks/session-start.ts`       | `dist/hooks/fec-session-start.js`       | 会话初始化     |
+
+## 架构概览
+
+通用安装器的架构如下：
+
+```
+bin/frontend-craft.ts
+  └─ src/install/cli.ts              # CLI 入口（解析命令：install/list/version/uninstall）
+       ├─ src/install/registry.ts    # runtime 注册表（名称 + 安装器映射）
+       ├─ src/install/converters/     # 各 runtime 适配器（claude, codex, cursor, copilot 等）
+       ├─ src/install/interactive.ts # 交互式安装向导（runtime/位置选择）
+       ├─ src/install/runtime-homes.ts # 全局/本地目录约定
+       └─ src/install/types.ts       # 共享 TypeScript 类型
+```
+
+`src/install/converters/` 下的每个 runtime 转换器都实现了 `types.ts` 中定义的 `InstallContext` 接口，将 skills、agents、commands、hooks 和模板写入目标 runtime 的配置目录。
+
+## 分支策略
+
+- `main` — 稳定发布分支。
+- `develop` — 开发分支（如使用）。
+- `feature/<name>` — 新功能。
+- `fix/<name>` — Bug 修复。
+- `docs/<name>` — 文档更新。
+
+## 提交规范
+
+遵循 [Conventional Commits](https://www.conventionalcommits.org/)：
+
+```text
+<type>(<scope>): <description>
+
+[optional body]
+[optional footer]
+```
+
+常见类型：
+
+| Type       | 含义             |
+| ---------- | ---------------- |
+| `feat`     | 新功能           |
+| `fix`      | Bug 修复         |
+| `docs`     | 文档             |
+| `refactor` | 重构             |
+| `test`     | 测试             |
+| `chore`    | 构建、工具或维护 |
+
+示例：
+
+```text
+feat(skills): add e2e testing skill
+fix(hooks): resolve Windows path handling
+docs(readme): update installation steps
+```
+
+## 语言与文档策略
+
+英文是公开项目治理、runtime 文档、发布说明和 GitHub 协作模板的**源语言**。多语言 README 应聚焦用户向摘要，并在贡献者或维护者细节上链接回英文文档。
+
+当 Pull Request 修改公共行为、安装步骤、runtime、agent、skill、command 或 hook 时：
+
+- 优先更新 `README.md` 与 `CHANGELOG.md`（及对应的 [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md) 若需同步中文读者）。
+- 若影响用户，需同步 `README.zh-CN.md`、`docs/zh-TW/README.md`、`docs/ja-JP/README.md` 和 `docs/ko-KR/README.md` 中的用户向摘要。
+- Claude Code Marketplace 的安装与更新说明以 [`docs/runtimes/claude.md`](docs/runtimes/claude.md) 与 [`docs/runtimes/claude.zh-CN.md`](docs/runtimes/claude.zh-CN.md) 为准；修改该流程时请更新这两份文件（根 README 与各语言 README 仅链向它们）。
+- 若同一 PR 无法完成翻译，请创建或链接后续 Issue，并在 PR 描述中说明。
+- 各语言版本中的代码示例、runtime 名称、命令名、文件路径和包名应保持一致。
+
+Issue 与 PR 使用英文最便于全球社区检索与 Review。若你更习惯中文，也欢迎提交；维护者可协助翻译标题和摘要。
+
+## 如何添加 Skill
+
+1. 在 `skills/` 下创建目录，例如 `skills/fec-my-skill/`。
+2. 创建 `SKILL.md`，包含 YAML frontmatter 与简洁说明：
+
+```markdown
+---
+name: fec-my-skill
+description: Use when the user needs ...
+---
+
+# Skill Title
+
+## When to Use
+
+- ...
+
+## Core Rules
+
+- ...
+```
+
+3. 在 `skills/metadata.json` 中新增条目，包括 `id`、展示名称 `name`、分类 `category`、`tags`、`summary`、发布元数据、`keywords` 和 `platforms`。其中 `version`、`license`、`homepage`、`repository` 应与 `package.json` 保持一致。
+4. 在 `skills/eval_queries.json` 中补充正向和负向触发样例。
+5. 在 `README.md` 的 Skills 表格中新增一行。
+6. 若可见目录结构变化，同步 `README.md` 与各语言 README 的目录树。
+7. 运行 `pnpm test`、`pnpm run pack:skills` 和 `pnpm run check:skills-publish`。
+
+## 如何添加 Agent
+
+1. 创建 `agents/my-agent.md`。
+2. 定义 YAML frontmatter：
+
+```markdown
+---
+name: my-agent
+description: Use this agent when ...
+tools: Read, Edit, Write, Glob, Grep, Bash
+model: sonnet
+skills:
+  - relevant-skill
+---
+```
+
+3. 在 `README.md` 的 Agents 表格中新增一行。
+4. 当数量或用户向描述变化时，同步 `README.zh-CN.md`、`docs/*/README.md` 与 `.claude-plugin/marketplace.json`。
+
+## 如何添加 Command
+
+1. 创建 `commands/my-command.md`。
+2. 使用 YAML frontmatter 与 Markdown 描述执行步骤。
+3. 在 `README.md` 的 Commands 表格中新增一行，并按需同步多语言用户向摘要。
+
+## 如何添加 Rule 模板
+
+1. 在 `templates/shared/rules/` 下创建 `my-rule.md`。
+2. 在 `commands/fec-init.md` 的复制清单中新增该文件。
+3. 在 `templates/claude/CLAUDE.md` 的规则导入示例中补充（如适用）。
+
+## 多工具安装器
+
+- 入口：`bin/frontend-craft.ts`。
+- 实现目录：`src/install/`（安装器、注册表、路径辅助）。
+- 交互向导与输入解析：`src/install/interactive.ts`（测试可将 `FRONTEND_CRAFT_FORCE_INTERACTIVE` 设为 `1` 以模拟管道输入下的问答）。
+- 新增 runtime 时，在 `src/install/registry.ts` 注册。
+- 在 `src/install/converters/` 下添加 runtime 安装器。
+- 参考 `src/install/runtime-homes.ts` 中的全局目录约定。
+- 在 `tests/install/` 中新增或更新测试。
+
+## 如何添加 Hook
+
+1. 更新 `hooks/hooks.json`。
+2. 如需 runtime hook 脚本，放在 `src/hooks/` 下，并优先使用跨平台 Node.js。
+3. 在 `scripts/build-dist.ts` 中新增对应入口，确保 `pnpm run build` 会将其打包到 `dist/hooks/`。
+4. 在 `hooks/hooks.json` 中，引用内置 hook 入口请使用 **`${CLAUDE_PLUGIN_ROOT}/dist/hooks/<script>.js`**（Claude Code 会在运行时替换根路径；见官方 [Plugins reference](https://code.claude.com/docs/en/plugins-reference)）。本仓库的 Claude 安装器在将 CLI 管理的 hook 条目合并到 `.claude/settings.json` 时，也会把 **`${CLAUDE_PLUGIN_ROOT}`** 及旧占位符 **`${FRONTEND_CRAFT_ROOT}`** 展开为绝对路径。
+5. 仓库维护脚本继续放在 `scripts/`，不要在 runtime hook 配置中直接引用它们。
+6. 更新 `README.md` 的 Hooks 表格。
+
+## Pull Request 自检
+
+提交 PR 前请确认：
+
+- [ ] 变更范围清晰，描述明确。
+- [ ] `pnpm test` 通过。
+- [ ] 修改 skill 时，`pnpm run audit:skills`、`pnpm run pack:skills` 与 `pnpm run check:skills-publish` 通过。
+- [ ] 修改 OpenClaw 代码或模板时，`pnpm run typecheck:openclaw` 与 `pnpm run pack:openclaw` 通过。
+- [ ] 用户可见行为变化已更新 `README.md` 与 `CHANGELOG.md`（及 [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md) 如适用）。
+- [ ] 多语言 README 已同步，或已链接后续翻译 Issue。
+- [ ] 新增 runtime、agent、skill、command、hook 或模板时，包含相关测试或 dry-run 覆盖。
+- [ ] 发布打包相关变更已通过 `pnpm run pack:all`，或已由 `prepublishOnly` 发布门禁覆盖。
+- [ ] 涉及安全敏感逻辑时，已按 [SECURITY.zh-CN.md](SECURITY.zh-CN.md) / [SECURITY.md](SECURITY.md) 检查。
+
+## 代码风格
+
+- Markdown 使用稳定标题和清晰表格。
+- Skill 与 Agent 描述保持简洁，因为模型路由依赖这些描述。
+- 自动化脚本优先使用跨平台 Node.js。
+- 除非特定 runtime 明确需要，否则避免依赖某个 shell 的特性。
+
+## 问题反馈
+
+使用 [GitHub Issues](https://github.com/bovinphang/frontend-craft/issues) 提交 Bug 或功能建议。请尽量包含 runtime、操作系统、Node.js 版本、执行命令、预期行为和实际行为。
+
+**安全敏感漏洞**不要提交公开 Issue，请按 [SECURITY.zh-CN.md](SECURITY.zh-CN.md)（或 [SECURITY.md](SECURITY.md)）处理。
+
+修改审核或图表能力时，同步各语言 README 与运行时指南中的范围默认值、自然语言示例、工具前提、QA 边界和覆盖报告要求。参见 [审核范围与技术图交付](docs/zh-CN/review-and-diagram-workflows.md).
+
+## 公共内容维护
+
+`cc-*` Skill 和内嵌公共方法由精确依赖 `@bovinphang/craft-common@2.0.0` 生成，禁止直接修改分发副本。先在 craft-common 修改并准备对应包，再运行 `pnpm run sync:common`，审阅 `common-content.lock.json` 与中英文快照，最后运行 `pnpm run check:common` 和 `pnpm lint`。前端领域 Skill、元数据及中文镜像仍在本仓库维护。完整目录和维护边界见[项目结构](docs/zh-CN/project-structure.md)与[公共能力迁移](docs/zh-CN/common-migration.md)。