From b9d49ed15d0c0665a45918894ab68350dbd89948 Mon Sep 17 00:00:00 2001 From: Tang <1024830255@qq.com> Date: Fri, 27 Mar 2026 14:07:14 +0800 Subject: [PATCH 1/4] docs(i18n-zh-cn): add Chinese translations for README and docs/ --- docs/i18n/zh-cn/README.md | 205 ++++ docs/i18n/zh-cn/cli.md | 936 ++++++++++++++++++ docs/i18n/zh-cn/commands.md | 706 +++++++++++++ docs/i18n/zh-cn/concepts.md | 624 ++++++++++++ docs/i18n/zh-cn/customization.md | 344 +++++++ docs/i18n/zh-cn/getting-started.md | 253 +++++ docs/i18n/zh-cn/installation.md | 81 ++ docs/i18n/zh-cn/migration-guide.md | 597 +++++++++++ docs/i18n/zh-cn/multi-language.md | 117 +++ docs/i18n/zh-cn/opsx.md | 660 ++++++++++++ docs/i18n/zh-cn/supported-tools.md | 107 ++ docs/i18n/zh-cn/workflows.md | 451 +++++++++ .../.openspec.yaml | 2 + .../design.md | 98 ++ .../proposal.md | 25 + .../specs/zh-cn-translations/spec.md | 59 ++ .../tasks.md | 27 + 17 files changed, 5292 insertions(+) create mode 100644 docs/i18n/zh-cn/README.md create mode 100644 docs/i18n/zh-cn/cli.md create mode 100644 docs/i18n/zh-cn/commands.md create mode 100644 docs/i18n/zh-cn/concepts.md create mode 100644 docs/i18n/zh-cn/customization.md create mode 100644 docs/i18n/zh-cn/getting-started.md create mode 100644 docs/i18n/zh-cn/installation.md create mode 100644 docs/i18n/zh-cn/migration-guide.md create mode 100644 docs/i18n/zh-cn/multi-language.md create mode 100644 docs/i18n/zh-cn/opsx.md create mode 100644 docs/i18n/zh-cn/supported-tools.md create mode 100644 docs/i18n/zh-cn/workflows.md create mode 100644 openspec/changes/archive/2026-03-27-add-zh-cn-translations/.openspec.yaml create mode 100644 openspec/changes/archive/2026-03-27-add-zh-cn-translations/design.md create mode 100644 openspec/changes/archive/2026-03-27-add-zh-cn-translations/proposal.md create mode 100644 openspec/changes/archive/2026-03-27-add-zh-cn-translations/specs/zh-cn-translations/spec.md create mode 100644 openspec/changes/archive/2026-03-27-add-zh-cn-translations/tasks.md diff --git a/docs/i18n/zh-cn/README.md b/docs/i18n/zh-cn/README.md new file mode 100644 index 000000000..361922dee --- /dev/null +++ b/docs/i18n/zh-cn/README.md @@ -0,0 +1,205 @@ +> **声明**：本文档由 AI 翻译，使用 `mimo-v2-pro` 进行翻译。 + +

+ + + + OpenSpec logo + + +

+ +

+ CI + npm version + License: MIT + Discord +

+ +
+最受欢迎的规范框架。 + +[![Stars](https://img.shields.io/github/stars/Fission-AI/OpenSpec?style=flat-square&label=Stars)](https://github.com/Fission-AI/OpenSpec/stargazers) +[![Downloads](https://img.shields.io/npm/dm/@fission-ai/openspec?style=flat-square&label=Downloads/mo)](https://www.npmjs.com/package/@fission-ai/openspec) +[![Contributors](https://img.shields.io/github/contributors/Fission-AI/OpenSpec?style=flat-square&label=Contributors)](https://github.com/Fission-AI/OpenSpec/graphs/contributors) + +
+

+我们的理念： + +```text +→ 灵活而非僵化 +→ 迭代而非瀑布 +→ 简洁而非复杂 +→ 为存量项目而生，而非仅限新项目 +→ 从个人项目到企业级均可扩展 +``` + +> [!TIP] +> **新工作流已上线！** 我们用全新的工件引导工作流重构了 OpenSpec。 +> +> 运行 `/opsx:propose "你的想法"` 即可开始。 → [了解更多](opsx.md) + +

+ 关注 @0xTab on X 获取更新 · 加入 OpenSpec Discord 获取帮助和讨论。 +

+ +### 团队 + +在团队中使用 OpenSpec？[发送邮件](mailto:teams@openspec.dev) 加入我们的 Slack 频道。 + + + +## 实际演示 + +```text +你: /opsx:propose add-dark-mode +AI: 已创建 openspec/changes/add-dark-mode/ + ✓ proposal.md — 为什么要做这个变更，变更内容 + ✓ specs/ — 需求和场景 + ✓ design.md — 技术方案 + ✓ tasks.md — 实现清单 + 准备好开始实现了！ + +你: /opsx:apply +AI: 正在实现任务... + ✓ 1.1 添加主题上下文提供者 + ✓ 1.2 创建切换组件 + ✓ 2.1 添加 CSS 变量 + ✓ 2.2 接入 localStorage + 所有任务完成！ + +你: /opsx:archive +AI: 已归档至 openspec/changes/archive/2025-01-23-add-dark-mode/ + 规范已更新。准备下一个功能。 +``` + +
+OpenSpec 仪表板 + +

+ OpenSpec 仪表板预览 +

+ +
+ +## 快速开始 + +**需要 Node.js 20.19.0 或更高版本。** + +全局安装 OpenSpec： + +```bash +npm install -g @fission-ai/openspec@latest +``` + +然后进入你的项目目录并初始化： + +```bash +cd your-project +openspec init +``` + +现在告诉你的 AI：`/opsx:propose <你想构建的内容>` + +如果你想要扩展工作流（`/opsx:new`、`/opsx:continue`、`/opsx:ff`、`/opsx:verify`、`/opsx:sync`、`/opsx:bulk-archive`、`/opsx:onboard`），使用 `openspec config profile` 选择并通过 `openspec update` 应用。 + +> [!NOTE] +> 不确定你的工具是否受支持？[查看完整列表](supported-tools.md) — 我们支持 20+ 种工具且持续增长。 +> +> 同样适用于 pnpm、yarn、bun 和 nix。[查看安装选项](installation.md)。 + +## 文档 + +→ **[快速开始](getting-started.md)**：第一步
+→ **[工作流](workflows.md)**：组合和模式
+→ **[命令](commands.md)**：斜杠命令和技能
+→ **[CLI](cli.md)**：终端参考
+→ **[支持的工具](supported-tools.md)**：工具集成和安装路径
+→ **[概念](concepts.md)**：整体运作方式
+→ **[多语言](multi-language.md)**：多语言支持
+→ **[自定义](customization.md)**：打造你自己的工作流 + + +## 为什么选择 OpenSpec？ + +AI 编程助手很强大，但当需求仅存在于聊天历史中时，它们就变得不可预测。OpenSpec 添加了一个轻量级的规范层，让你在编写任何代码之前就达成共识。 + +- **先达成共识再构建** — 人类和 AI 在代码编写前就规范达成一致 +- **保持有序** — 每个变更都有自己的文件夹，包含 proposal、specs、design 和 tasks +- **灵活工作** — 随时更新任何工件，没有僵化的阶段门控 +- **使用你的工具** — 通过斜杠命令支持 20+ 种 AI 助手 + +### 对比 + +**vs. [Spec Kit](https://github.com/github/spec-kit)**（GitHub）— 全面但笨重。僵化的阶段门控、大量 Markdown、Python 设置。OpenSpec 更轻量，允许自由迭代。 + +**vs. [Kiro](https://kiro.dev)**（AWS）— 强大但你被锁定在他们的 IDE 中，且仅限 Claude 模型。OpenSpec 与你已有的工具配合使用。 + +**vs. 不使用** — 没有规范的 AI 编程意味着模糊的提示和不可预测的结果。OpenSpec 在没有繁琐流程的情况下带来可预测性。 + +## 更新 OpenSpec + +**升级包** + +```bash +npm install -g @fission-ai/openspec@latest +``` + +**刷新 agent 指令** + +在每个项目中运行此命令以重新生成 AI 指导，确保最新的斜杠命令处于激活状态： + +```bash +openspec update +``` + +## 使用说明 + +**模型选择**：OpenSpec 与高推理能力的模型配合使用效果最佳。我们推荐 Opus 4.5 和 GPT 5.2 用于规划和实现。 + +**上下文管理**：OpenSpec 受益于干净的上下文窗口。在开始实现前清除上下文，并在整个会话中保持良好的上下文管理。 + +## 贡献 + +**小修复** — Bug 修复、拼写纠正和小改进可以直接提交 PR。 + +**大变更** — 对于新功能、重大重构或架构变更，请先提交 OpenSpec 变更提案，以便在实现开始前就意图和目标达成一致。 + +撰写提案时，请牢记 OpenSpec 的理念：我们服务于各种用户，涵盖不同的编码 agent、模型和用例。变更应该对所有人都适用。 + +**欢迎 AI 生成的代码** — 只要经过测试和验证。包含 AI 生成代码的 PR 应注明使用的编码 agent 和模型（例如 "Generated with Claude Code using claude-opus-4-5-20251101"）。 + +### 开发 + +- 安装依赖：`pnpm install` +- 构建：`pnpm run build` +- 测试：`pnpm test` +- 本地开发 CLI：`pnpm run dev` 或 `pnpm run dev:cli` +- 约定式提交（单行）：`type(scope): subject` + +## 其他 + +
+遥测 + +OpenSpec 收集匿名使用统计。 + +我们仅收集命令名称和版本以了解使用模式。不收集参数、路径、内容或个人信息。在 CI 中自动禁用。 + +**退出：** `export OPENSPEC_TELEMETRY=0` 或 `export DO_NOT_TRACK=1` + +
+ +
+维护者和顾问 + +请参阅 [MAINTAINERS.md](../../MAINTAINERS.md) 了解核心维护者和顾问的列表，他们帮助指导项目发展。 + +
+ + + +## 许可证 + +MIT diff --git a/docs/i18n/zh-cn/cli.md b/docs/i18n/zh-cn/cli.md new file mode 100644 index 000000000..a0b44bb6c --- /dev/null +++ b/docs/i18n/zh-cn/cli.md @@ -0,0 +1,936 @@ +> **声明**：本文档由 AI 翻译，使用 `mimo-v2-pro` 进行翻译。 + +# CLI 参考 + +OpenSpec CLI (`openspec`) 提供了用于项目设置、验证、状态检查和管理的终端命令。这些命令是对 AI 斜杠命令（如 `/opsx:propose`）的补充，详见 [Commands](commands.md)。 + +## 概览 + +| 类别 | 命令 | 用途 | +|------|------|------| +| **初始化** | `init`、`update` | 在项目中初始化和更新 OpenSpec | +| **浏览** | `list`、`view`、`show` | 探索变更和规格 | +| **验证** | `validate` | 检查变更和规格的问题 | +| **生命周期** | `archive` | 完成变更的归档 | +| **工作流** | `status`、`instructions`、`templates`、`schemas` | 工件驱动的工作流支持 | +| **Schema** | `schema init`、`schema fork`、`schema validate`、`schema which` | 创建和管理工作流 | +| **配置** | `config` | 查看和修改设置 | +| **工具** | `feedback`、`completion` | 反馈和 Shell 集成 | + +--- + +## 人工 vs 代理命令 + +大多数 CLI 命令设计为在终端中供**人工使用**。部分命令也通过 JSON 输出支持**代理/脚本使用**。 + +### 仅人工命令 + +这些命令是交互式的，专为终端使用设计： + +| 命令 | 用途 | +|------|------| +| `openspec init` | 初始化项目（交互式提示） | +| `openspec view` | 交互式仪表盘 | +| `openspec config edit` | 在编辑器中打开配置 | +| `openspec feedback` | 通过 GitHub 提交反馈 | +| `openspec completion install` | 安装 Shell 补全 | + +### 代理兼容命令 + +这些命令支持 `--json` 输出，供 AI 代理和脚本以编程方式使用： + +| 命令 | 人工使用 | 代理使用 | +|------|----------|----------| +| `openspec list` | 浏览变更/规格 | `--json` 获取结构化数据 | +| `openspec show ` | 读取内容 | `--json` 用于解析 | +| `openspec validate` | 检查问题 | `--all --json` 用于批量验证 | +| `openspec status` | 查看工件进度 | `--json` 获取结构化状态 | +| `openspec instructions` | 获取下一步 | `--json` 获取代理指令 | +| `openspec templates` | 查找模板路径 | `--json` 用于路径解析 | +| `openspec schemas` | 列出可用 schema | `--json` 用于 schema 发现 | + +--- + +## 全局选项 + +这些选项适用于所有命令： + +| 选项 | 描述 | +|------|------| +| `--version`、`-V` | 显示版本号 | +| `--no-color` | 禁用彩色输出 | +| `--help`、`-h` | 显示命令帮助 | + +--- + +## 初始化命令 + +### `openspec init` + +在项目中初始化 OpenSpec。创建文件夹结构并配置 AI 工具集成。 + +默认行为使用全局配置默认值：profile `core`、delivery `both`、workflows `propose, explore, apply, archive`。 + +``` +openspec init [path] [options] +``` + +**参数：** + +| 参数 | 必需 | 描述 | +|------|------|------| +| `path` | 否 | 目标目录（默认：当前目录） | + +**选项：** + +| 选项 | 描述 | +|------|------| +| `--tools ` | 非交互式配置 AI 工具。使用 `all`、`none` 或逗号分隔的列表 | +| `--force` | 自动清理旧文件，不提示 | +| `--profile ` | 为此初始化运行覆盖全局 profile（`core` 或 `custom`） | + +`--profile custom` 使用全局配置中当前选定的工作流（`openspec config profile`）。 + +**支持的工具 ID（`--tools`）：** `amazon-q`、`antigravity`、`auggie`、`claude`、`cline`、`codex`、`codebuddy`、`continue`、`costrict`、`crush`、`cursor`、`factory`、`gemini`、`github-copilot`、`iflow`、`kilocode`、`kiro`、`opencode`、`pi`、`qoder`、`qwen`、`roocode`、`trae`、`windsurf` + +**示例：** + +```bash +# 交互式初始化 +openspec init + +# 在指定目录中初始化 +openspec init ./my-project + +# 非交互式：配置 Claude 和 Cursor +openspec init --tools claude,cursor + +# 配置所有支持的工具 +openspec init --tools all + +# 覆盖本次运行的 profile +openspec init --profile core + +# 跳过提示并自动清理旧文件 +openspec init --force +``` + +**创建的内容：** + +``` +openspec/ +├── specs/ # 规格说明（事实来源） +├── changes/ # 提议的变更 +└── config.yaml # 项目配置 + +.claude/skills/ # Claude Code skills（如果选择了 claude） +.cursor/skills/ # Cursor skills（如果选择了 cursor） +.cursor/commands/ # Cursor OPSX 命令（如果 delivery 包含 commands） +...（其他工具配置） +``` + +--- + +### `openspec update` + +升级 CLI 后更新 OpenSpec 指令文件。使用当前全局 profile、选定的工作流和 delivery 模式重新生成 AI 工具配置文件。 + +``` +openspec update [path] [options] +``` + +**参数：** + +| 参数 | 必需 | 描述 | +|------|------|------| +| `path` | 否 | 目标目录（默认：当前目录） | + +**选项：** + +| 选项 | 描述 | +|------|------| +| `--force` | 即使文件是最新的也强制更新 | + +**示例：** + +```bash +# npm 升级后更新指令文件 +npm update @fission-ai/openspec +openspec update +``` + +--- + +## 浏览命令 + +### `openspec list` + +列出项目中的变更或规格。 + +``` +openspec list [options] +``` + +**选项：** + +| 选项 | 描述 | +|------|------| +| `--specs` | 列出规格而非变更 | +| `--changes` | 列出变更（默认） | +| `--sort ` | 按 `recent`（默认）或 `name` 排序 | +| `--json` | 输出为 JSON | + +**示例：** + +```bash +# 列出所有活跃变更 +openspec list + +# 列出所有规格 +openspec list --specs + +# 脚本使用的 JSON 输出 +openspec list --json +``` + +**输出（文本）：** + +``` +Active changes: + add-dark-mode UI theme switching support + fix-login-bug Session timeout handling +``` + +--- + +### `openspec view` + +显示用于浏览规格和变更的交互式仪表盘。 + +``` +openspec view +``` + +打开终端界面，用于导航项目的规格说明和变更。 + +--- + +### `openspec show` + +显示变更或规格的详细信息。 + +``` +openspec show [item-name] [options] +``` + +**参数：** + +| 参数 | 必需 | 描述 | +|------|------|------| +| `item-name` | 否 | 变更或规格名称（省略时提示选择） | + +**选项：** + +| 选项 | 描述 | +|------|------| +| `--type ` | 指定类型：`change` 或 `spec`（无歧义时自动检测） | +| `--json` | 输出为 JSON | +| `--no-interactive` | 禁用提示 | + +**变更专用选项：** + +| 选项 | 描述 | +|------|------| +| `--deltas-only` | 仅显示增量规格（JSON 模式） | + +**规格专用选项：** + +| 选项 | 描述 | +|------|------| +| `--requirements` | 仅显示需求，排除场景（JSON 模式） | +| `--no-scenarios` | 排除场景内容（JSON 模式） | +| `-r`、`--requirement ` | 按 1 起始索引显示特定需求（JSON 模式） | + +**示例：** + +```bash +# 交互式选择 +openspec show + +# 显示特定变更 +openspec show add-dark-mode + +# 显示特定规格 +openspec show auth --type spec + +# 用于解析的 JSON 输出 +openspec show add-dark-mode --json +``` + +--- + +## 验证命令 + +### `openspec validate` + +验证变更和规格的结构问题。 + +``` +openspec validate [item-name] [options] +``` + +**参数：** + +| 参数 | 必需 | 描述 | +|------|------|------| +| `item-name` | 否 | 要验证的特定项目（省略时提示选择） | + +**选项：** + +| 选项 | 描述 | +|------|------| +| `--all` | 验证所有变更和规格 | +| `--changes` | 验证所有变更 | +| `--specs` | 验证所有规格 | +| `--type ` | 名称有歧义时指定类型：`change` 或 `spec` | +| `--strict` | 启用严格验证模式 | +| `--json` | 输出为 JSON | +| `--concurrency ` | 最大并行验证数（默认：6，或 `OPENSPEC_CONCURRENCY` 环境变量） | +| `--no-interactive` | 禁用提示 | + +**示例：** + +```bash +# 交互式验证 +openspec validate + +# 验证特定变更 +openspec validate add-dark-mode + +# 验证所有变更 +openspec validate --changes + +# 验证所有内容并输出 JSON（用于 CI/脚本） +openspec validate --all --json + +# 严格验证并增加并行度 +openspec validate --all --strict --concurrency 12 +``` + +**输出（文本）：** + +``` +Validating add-dark-mode... + ✓ proposal.md valid + ✓ specs/ui/spec.md valid + ⚠ design.md: missing "Technical Approach" section + +1 warning found +``` + +**输出（JSON）：** + +```json +{ + "version": "1.0.0", + "results": { + "changes": [ + { + "name": "add-dark-mode", + "valid": true, + "warnings": ["design.md: missing 'Technical Approach' section"] + } + ] + }, + "summary": { + "total": 1, + "valid": 1, + "invalid": 0 + } +} +``` + +--- + +## 生命周期命令 + +### `openspec archive` + +归档已完成的变更并将增量规格合并到主规格中。 + +``` +openspec archive [change-name] [options] +``` + +**参数：** + +| 参数 | 必需 | 描述 | +|------|------|------| +| `change-name` | 否 | 要归档的变更（省略时提示选择） | + +**选项：** + +| 选项 | 描述 | +|------|------| +| `-y`、`--yes` | 跳过确认提示 | +| `--skip-specs` | 跳过规格更新（用于基础设施/工具/仅文档变更） | +| `--no-validate` | 跳过验证（需要确认） | + +**示例：** + +```bash +# 交互式归档 +openspec archive + +# 归档特定变更 +openspec archive add-dark-mode + +# 无提示归档（CI/脚本） +openspec archive add-dark-mode --yes + +# 归档不影响规格的工具变更 +openspec archive update-ci-config --skip-specs +``` + +**功能说明：** + +1. 验证变更（除非使用 `--no-validate`） +2. 提示确认（除非使用 `--yes`） +3. 将增量规格合并到 `openspec/specs/` +4. 将变更文件夹移动到 `openspec/changes/archive/YYYY-MM-DD-/` + +--- + +## 工作流命令 + +这些命令支持工件驱动的 OPSX 工作流。对于检查进度的人员和确定下一步的代理都非常有用。 + +### `openspec status` + +显示变更的工件完成状态。 + +``` +openspec status [options] +``` + +**选项：** + +| 选项 | 描述 | +|------|------| +| `--change ` | 变更名称（省略时提示选择） | +| `--schema ` | Schema 覆盖（从变更的配置自动检测） | +| `--json` | 输出为 JSON | + +**示例：** + +```bash +# 交互式状态检查 +openspec status + +# 特定变更的状态 +openspec status --change add-dark-mode + +# 代理使用的 JSON +openspec status --change add-dark-mode --json +``` + +**输出（文本）：** + +``` +Change: add-dark-mode +Schema: spec-driven +Progress: 2/4 artifacts complete + +[x] proposal +[ ] design +[x] specs +[-] tasks (blocked by: design) +``` + +**输出（JSON）：** + +```json +{ + "changeName": "add-dark-mode", + "schemaName": "spec-driven", + "isComplete": false, + "applyRequires": ["tasks"], + "artifacts": [ + {"id": "proposal", "outputPath": "proposal.md", "status": "done"}, + {"id": "design", "outputPath": "design.md", "status": "ready"}, + {"id": "specs", "outputPath": "specs/**/*.md", "status": "done"}, + {"id": "tasks", "outputPath": "tasks.md", "status": "blocked", "missingDeps": ["design"]} + ] +} +``` + +--- + +### `openspec instructions` + +获取创建工件或应用任务的丰富指令。AI 代理使用此命令了解接下来要创建的内容。 + +``` +openspec instructions [artifact] [options] +``` + +**参数：** + +| 参数 | 必需 | 描述 | +|------|------|------| +| `artifact` | 否 | 工件 ID：`proposal`、`specs`、`design`、`tasks` 或 `apply` | + +**选项：** + +| 选项 | 描述 | +|------|------| +| `--change ` | 变更名称（非交互模式下必需） | +| `--schema ` | Schema 覆盖 | +| `--json` | 输出为 JSON | + +**特殊情况：** 使用 `apply` 作为工件以获取任务实施指令。 + +**示例：** + +```bash +# 获取下一个工件的指令 +openspec instructions --change add-dark-mode + +# 获取特定工件的指令 +openspec instructions design --change add-dark-mode + +# 获取 apply/实施指令 +openspec instructions apply --change add-dark-mode + +# 代理消费的 JSON +openspec instructions design --change add-dark-mode --json +``` + +**输出包含：** + +- 工件的模板内容 +- 来自配置的项目上下文 +- 依赖工件的内容 +- 来自配置的每工件规则 + +--- + +### `openspec templates` + +显示 schema 中所有工件的已解析模板路径。 + +``` +openspec templates [options] +``` + +**选项：** + +| 选项 | 描述 | +|------|------| +| `--schema ` | 要检查的 schema（默认：`spec-driven`） | +| `--json` | 输出为 JSON | + +**示例：** + +```bash +# 显示默认 schema 的模板路径 +openspec templates + +# 显示自定义 schema 的模板 +openspec templates --schema my-workflow + +# 编程使用的 JSON +openspec templates --json +``` + +**输出（文本）：** + +``` +Schema: spec-driven + +Templates: + proposal → ~/.openspec/schemas/spec-driven/templates/proposal.md + specs → ~/.openspec/schemas/spec-driven/templates/specs.md + design → ~/.openspec/schemas/spec-driven/templates/design.md + tasks → ~/.openspec/schemas/spec-driven/templates/tasks.md +``` + +--- + +### `openspec schemas` + +列出可用的工作流 schema 及其描述和工件流程。 + +``` +openspec schemas [options] +``` + +**选项：** + +| 选项 | 描述 | +|------|------| +| `--json` | 输出为 JSON | + +**示例：** + +```bash +openspec schemas +``` + +**输出：** + +``` +Available schemas: + + spec-driven (package) + The default spec-driven development workflow + Flow: proposal → specs → design → tasks + + my-custom (project) + Custom workflow for this project + Flow: research → proposal → tasks +``` + +--- + +## Schema 命令 + +用于创建和管理自定义工作流 schema 的命令。 + +### `openspec schema init` + +创建新的项目本地 schema。 + +``` +openspec schema init [options] +``` + +**参数：** + +| 参数 | 必需 | 描述 | +|------|------|------| +| `name` | 是 | Schema 名称（kebab-case） | + +**选项：** + +| 选项 | 描述 | +|------|------| +| `--description ` | Schema 描述 | +| `--artifacts ` | 逗号分隔的工件 ID（默认：`proposal,specs,design,tasks`） | +| `--default` | 设置为项目默认 schema | +| `--no-default` | 不提示设置为默认 | +| `--force` | 覆盖已存在的 schema | +| `--json` | 输出为 JSON | + +**示例：** + +```bash +# 交互式 schema 创建 +openspec schema init research-first + +# 非交互式，指定工件 +openspec schema init rapid \ + --description "快速迭代工作流" \ + --artifacts "proposal,tasks" \ + --default +``` + +**创建的内容：** + +``` +openspec/schemas// +├── schema.yaml # Schema 定义 +└── templates/ + ├── proposal.md # 每个工件的模板 + ├── specs.md + ├── design.md + └── tasks.md +``` + +--- + +### `openspec schema fork` + +复制现有 schema 到项目中进行自定义。 + +``` +openspec schema fork [name] [options] +``` + +**参数：** + +| 参数 | 必需 | 描述 | +|------|------|------| +| `source` | 是 | 要复制的 schema | +| `name` | 否 | 新 schema 名称（默认：`-custom`） | + +**选项：** + +| 选项 | 描述 | +|------|------| +| `--force` | 覆盖已存在的目标 | +| `--json` | 输出为 JSON | + +**示例：** + +```bash +# Fork 内置的 spec-driven schema +openspec schema fork spec-driven my-workflow +``` + +--- + +### `openspec schema validate` + +验证 schema 的结构和模板。 + +``` +openspec schema validate [name] [options] +``` + +**参数：** + +| 参数 | 必需 | 描述 | +|------|------|------| +| `name` | 否 | 要验证的 schema（省略时验证所有） | + +**选项：** + +| 选项 | 描述 | +|------|------| +| `--verbose` | 显示详细验证步骤 | +| `--json` | 输出为 JSON | + +**示例：** + +```bash +# 验证特定 schema +openspec schema validate my-workflow + +# 验证所有 schema +openspec schema validate +``` + +--- + +### `openspec schema which` + +显示 schema 的解析来源（对调试优先级很有用）。 + +``` +openspec schema which [name] [options] +``` + +**参数：** + +| 参数 | 必需 | 描述 | +|------|------|------| +| `name` | 否 | Schema 名称 | + +**选项：** + +| 选项 | 描述 | +|------|------| +| `--all` | 列出所有 schema 及其来源 | +| `--json` | 输出为 JSON | + +**示例：** + +```bash +# 检查 schema 的来源 +openspec schema which spec-driven +``` + +**输出：** + +``` +spec-driven resolves from: package + Source: /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven +``` + +**Schema 优先级：** + +1. 项目级：`openspec/schemas//` +2. 用户级：`~/.local/share/openspec/schemas//` +3. 包级：内置 schema + +--- + +## 配置命令 + +### `openspec config` + +查看和修改全局 OpenSpec 配置。 + +``` +openspec config [options] +``` + +**子命令：** + +| 子命令 | 描述 | +|--------|------| +| `path` | 显示配置文件位置 | +| `list` | 显示所有当前设置 | +| `get ` | 获取特定值 | +| `set ` | 设置值 | +| `unset ` | 移除键 | +| `reset` | 重置为默认值 | +| `edit` | 在 `$EDITOR` 中打开 | +| `profile [preset]` | 交互式或通过预设配置工作流 profile | + +**示例：** + +```bash +# 显示配置文件路径 +openspec config path + +# 列出所有设置 +openspec config list + +# 获取特定值 +openspec config get telemetry.enabled + +# 设置值 +openspec config set telemetry.enabled false + +# 显式设置字符串值 +openspec config set user.name "My Name" --string + +# 移除自定义设置 +openspec config unset user.name + +# 重置所有配置 +openspec config reset --all --yes + +# 在编辑器中编辑配置 +openspec config edit + +# 使用基于操作的向导配置 profile +openspec config profile + +# 快速预设：将工作流切换到 core（保留 delivery 模式） +openspec config profile core +``` + +`openspec config profile` 首先显示当前状态摘要，然后让你选择： +- 更改 delivery + 工作流 +- 仅更改 delivery +- 仅更改工作流 +- 保留当前设置（退出） + +如果保留当前设置，不会写入任何更改，也不会显示更新提示。 +如果没有配置更改但当前项目文件与全局 profile/delivery 不同步，OpenSpec 将显示警告并建议运行 `openspec update`。 +按 `Ctrl+C` 也会干净地取消流程（无堆栈跟踪）并以代码 `130` 退出。 +在工作流清单中，`[x]` 表示该工作流在全局配置中已选中。要将这些选择应用到项目文件，请运行 `openspec update`（或在项目中选择"立即将更改应用到此项目？"）。 + +**交互式示例：** + +```bash +# 仅更新 delivery +openspec config profile +# 选择: 仅更改 delivery +# 选择 delivery: Skills only + +# 仅更新工作流 +openspec config profile +# 选择: 仅更改工作流 +# 在清单中切换工作流，然后确认 +``` + +--- + +## 工具命令 + +### `openspec feedback` + +提交关于 OpenSpec 的反馈。创建 GitHub issue。 + +``` +openspec feedback [options] +``` + +**参数：** + +| 参数 | 必需 | 描述 | +|------|------|------| +| `message` | 是 | 反馈消息 | + +**选项：** + +| 选项 | 描述 | +|------|------| +| `--body ` | 详细描述 | + +**要求：** 必须安装并认证 GitHub CLI (`gh`)。 + +**示例：** + +```bash +openspec feedback "添加对自定义工件类型的支持" \ + --body "我希望定义自己的工件类型，而不局限于内置类型。" +``` + +--- + +### `openspec completion` + +管理 OpenSpec CLI 的 Shell 补全。 + +``` +openspec completion [shell] +``` + +**子命令：** + +| 子命令 | 描述 | +|--------|------| +| `generate [shell]` | 输出补全脚本到 stdout | +| `install [shell]` | 为你的 Shell 安装补全 | +| `uninstall [shell]` | 移除已安装的补全 | + +**支持的 Shell：** `bash`、`zsh`、`fish`、`powershell` + +**示例：** + +```bash +# 安装补全（自动检测 Shell） +openspec completion install + +# 为特定 Shell 安装 +openspec completion install zsh + +# 生成脚本以手动安装 +openspec completion generate bash > ~/.bash_completion.d/openspec + +# 卸载 +openspec completion uninstall +``` + +--- + +## 退出码 + +| 代码 | 含义 | +|------|------| +| `0` | 成功 | +| `1` | 错误（验证失败、文件缺失等） | + +--- + +## 环境变量 + +| 变量 | 描述 | +|------|------| +| `OPENSPEC_CONCURRENCY` | 批量验证的默认并发数（默认：6） | +| `EDITOR` 或 `VISUAL` | `openspec config edit` 使用的编辑器 | +| `NO_COLOR` | 设置时禁用彩色输出 | + +--- + +## 相关文档 + +- [Commands](commands.md) - AI 斜杠命令（`/opsx:propose`、`/opsx:apply` 等） +- [Workflows](workflows.md) - 常见模式及何时使用每个命令 +- [Customization](customization.md) - 创建自定义 schema 和模板 +- [Getting Started](getting-started.md) - 首次设置指南 diff --git a/docs/i18n/zh-cn/commands.md b/docs/i18n/zh-cn/commands.md new file mode 100644 index 000000000..33f4fb3a2 --- /dev/null +++ b/docs/i18n/zh-cn/commands.md @@ -0,0 +1,706 @@ +> **声明**：本文档由 AI 翻译，使用 `mimo-v2-pro` 进行翻译。 + +# 命令 + +这是 OpenSpec 斜杠命令的参考文档。这些命令在您的 AI 编码助手的聊天界面中调用（例如，Claude Code、Cursor、Windsurf）。 + +有关工作流程模式以及何时使用每个命令，请参见[工作流程](workflows.md)。有关 CLI 命令，请参见[CLI](cli.md)。 + +## 快速参考 + +### 默认快速路径（`core` 配置文件） + +| 命令 | 用途 | +|------|------| +| `/opsx:propose` | 一步创建变更并生成规划工件 | +| `/opsx:explore` | 在提交变更前思考想法 | +| `/opsx:apply` | 实施变更中的任务 | +| `/opsx:archive` | 归档已完成的变更 | + +### 扩展工作流程命令（自定义工作流程选择） + +| 命令 | 用途 | +|------|------| +| `/opsx:new` | 开始新的变更框架 | +| `/opsx:continue` | 基于依赖关系创建下一个工件 | +| `/opsx:ff` | 快进：一次创建所有规划工件 | +| `/opsx:verify` | 验证实施是否与工件匹配 | +| `/opsx:sync` | 将增量规范合并到主规范 | +| `/opsx:bulk-archive` | 一次归档多个变更 | +| `/opsx:onboard` | 完整工作流程的引导教程 | + +默认全局配置文件是 `core`。要启用扩展工作流程命令，请运行 `openspec config profile`，选择工作流程，然后在您的项目中运行 `openspec update`。 + +--- + +## 命令参考 + +### `/opsx:propose` + +一步创建新变更并生成规划工件。这是 `core` 配置文件中的默认开始命令。 + +**语法：** +```text +/opsx:propose [变更名称或描述] +``` + +**参数：** +| 参数 | 必需 | 描述 | +|------|------|------| +| `变更名称或描述` | 否 | 烤肉串式命名或纯语言变更描述 | + +**功能：** +- 创建 `openspec/changes/<变更名称>/` +- 生成实施前所需的工件（对于 `spec-driven`：提案、规范、设计、任务） +- 当变更准备好进行 `/opsx:apply` 时停止 + +**示例：** +```text +You: /opsx:propose add-dark-mode + +AI: 已创建 openspec/changes/add-dark-mode/ + ✓ proposal.md + ✓ specs/ui/spec.md + ✓ design.md + ✓ tasks.md + 准备好实施。运行 /opsx:apply。 +``` + +**提示：** +- 这是最快的端到端路径 +- 如果您想要逐步工件控制，请启用扩展工作流程并使用 `/opsx:new` + `/opsx:continue` + +--- + +### `/opsx:explore` + +在提交变更前思考想法、调查问题和澄清需求。 + +**语法：** +``` +/opsx:explore [主题] +``` + +**参数：** +| 参数 | 必需 | 描述 | +|------|------|------| +| `主题` | 否 | 您想探索或调查的内容 | + +**功能：** +- 开启探索性对话，无需结构 +- 调查代码库以回答问题 +- 比较选项和方法 +- 创建可视化图表以澄清思路 +- 当洞察力形成时，可以过渡到 `/opsx:propose`（默认）或 `/opsx:new`（扩展工作流程） + +**示例：** +```text +You: /opsx:explore + +AI: 你想探索什么？ + +You: 我们应该如何处理移动应用的身份验证？ + +AI: 让我调查你当前的身份验证配置... + [分析代码库] + + 我看到你正在使用基于会话的 Web 应用身份验证。 + 对于移动端，我们有三个主要选项： + + 1. JWT 令牌（无状态，支持离线） + 2. OAuth2（如果需要第三方登录） + 3. 扩展现有会话（更简单，但需要网络连接） + + 你的 API 已经配置了 CORS。你对哪个方向感兴趣？ + +You: 我们用 JWT。能为此启动一个变更吗？ + +AI: 随时可以。运行 /opsx:propose add-jwt-auth 开始。 +``` + +**提示：** +- 当需求不明确或您需要调查时使用 +- 探索期间不会创建工件 +- 在决定前比较多种方法很有用 +- 可以读取文件和搜索代码库 + +--- + +### `/opsx:new` + +开始新的变更框架。创建变更文件夹并等待您使用 `/opsx:continue` 或 `/opsx:ff` 生成工件。 + +此命令是扩展工作流程集的一部分（不包含在默认 `core` 配置文件中）。 + +**语法：** +``` +/opsx:new [变更名称] [--schema <架构名称>] +``` + +**参数：** +| 参数 | 必需 | 描述 | +|------|------|------| +| `变更名称` | 否 | 变更文件夹的名称（如果未提供则提示输入） | +| `--schema` | 否 | 要使用的工作流程架构（默认：来自配置或 `spec-driven`） | + +**功能：** +- 创建 `openspec/changes/<变更名称>/` 目录 +- 在变更文件夹中创建 `.openspec.yaml` 元数据文件 +- 显示第一个工件模板，准备创建 +- 如果未提供，则提示输入变更名称和架构 + +**创建内容：** +``` +openspec/changes/<变更名称>/ +└── .openspec.yaml # 变更元数据（架构、创建日期） +``` + +**示例：** +``` +You: /opsx:new add-dark-mode + +AI: 已创建 openspec/changes/add-dark-mode/ + 架构：spec-driven + + 准备创建：proposal + 使用 /opsx:continue 创建它，或使用 /opsx:ff 创建所有工件。 +``` + +**提示：** +- 使用描述性名称：`添加功能`、`修复错误`、`重构模块` +- 避免通用名称如 `更新`、`变更`、`进行中` +- 架构也可以在项目配置中设置（`openspec/config.yaml`） + +--- + +### `/opsx:continue` + +创建依赖链中的下一个工件。一次创建一个工件以实现增量进度。 + +**语法：** +``` +/opsx:continue [变更名称] +``` + +**参数：** +| 参数 | 必需 | 描述 | +|------|------|------| +| `变更名称` | 否 | 要继续的变更（如果未提供则从上下文推断） | + +**功能：** +- 查询工件依赖关系图 +- 显示哪些工件已就绪 vs 被阻塞 +- 创建第一个就绪的工件 +- 读取依赖文件以获取上下文 +- 显示创建后哪些内容变为可用 + +**示例：** +``` +You: /opsx:continue + +AI: 变更：add-dark-mode + + 工件状态： + ✓ proposal （完成） + ◆ specs （就绪） + ◆ design （就绪） + ○ tasks （被阻塞 - 依赖：specs） + + 正在创建 specs... + + [读取 proposal.md，基于需求创建规范] + + ✓ 已创建 openspec/changes/add-dark-mode/specs/ui/spec.md + + 现在可创建：tasks + 运行 /opsx:continue 创建下一个工件。 +``` + +**提示：** +- 当您想在继续前审查每个工件时使用 +- 对于需要控制的复杂变更很有用 +- 多个工件可能同时变为就绪 +- 您可以在继续前编辑已创建的工件 + +--- + +### `/opsx:ff` + +快进工件创建。一次创建所有规划工件。 + +**语法：** +``` +/opsx:ff [变更名称] +``` + +**参数：** +| 参数 | 必需 | 描述 | +|------|------|------| +| `变更名称` | 否 | 要快进的变更（如果未提供则从上下文推断） | + +**功能：** +- 按依赖顺序创建所有工件 +- 通过待办事项列表跟踪进度 +- 当所有 `apply-required` 工件完成时停止 +- 在创建下一个工件前读取每个依赖项 + +**示例：** +``` +You: /opsx:ff add-dark-mode + +AI: 正在快进 add-dark-mode... + + ✓ 正在创建 proposal.md + ✓ 正在创建 specs/ui/spec.md + ✓ 正在创建 design.md + ✓ 正在创建 tasks.md + + 所有规划工件完成！ + 准备好实施。运行 /opsx:apply 开始。 +``` + +**提示：** +- 当您对要构建的内容有清晰的图景时使用 +- 对于简单直接的变更比 `/opsx:continue` 更快 +- 您仍然可以在之后编辑工件 +- 适合中小型功能 + +--- + +### `/opsx:apply` + +实施变更中的任务。按照任务列表工作，编写代码并勾选项目。 + +**语法：** +``` +/opsx:apply [变更名称] +``` + +**参数：** +| 参数 | 必需 | 描述 | +|------|------|------| +| `变更名称` | 否 | 要实施的变更（如果未提供则从上下文推断） | + +**功能：** +- 读取 `tasks.md` 并识别未完成的任务 +- 逐一完成任务 +- 按需编写代码、创建文件、运行测试 +- 用复选框 `[x]` 标记任务完成 + +**示例：** +``` +You: /opsx:apply + +AI: 正在实施 add-dark-mode... + + 读取 tasks.md： + - [ ] 1.1 创建 ThemeContext + - [ ] 1.2 添加 CSS 自定义属性 + - [ ] 1.3 实现 localStorage 持久化 + + 正在处理 1.1：创建 ThemeContext... + [创建 src/context/ThemeContext.tsx] + + ✓ 1.1 完成 + + 正在处理 1.2：添加 CSS 自定义属性... + [更新 src/styles/globals.css] + + ✓ 1.2 完成 + ... +``` + +**提示：** +- 如果中断可以从停止处继续 +- 通过指定变更名称用于并行变更 +- 完成状态在 `tasks.md` 复选框中跟踪 + +--- + +### `/opsx:verify` + +验证实施是否与变更工件匹配。检查完整性、正确性和一致性。 + +**语法：** +``` +/opsx:verify [变更名称] +``` + +**参数：** +| 参数 | 必需 | 描述 | +|------|------|------| +| `变更名称` | 否 | 要验证的变更（如果未提供则从上下文推断） | + +**功能：** +- 检查实施质量的三个维度 +- 搜索代码库以查找实施证据 +- 报告分类为 CRITICAL、WARNING 或 SUGGESTION 的问题 +- 不阻止归档，但会显示问题 + +**验证维度：** + +| 维度 | 验证内容 | +|------|----------| +| **完整性** | 所有任务完成，所有需求已实施，场景已覆盖 | +| **正确性** | 实施符合规范意图，边缘情况已处理 | +| **一致性** | 设计决策反映在代码中，模式一致 | + +**示例：** +``` +You: /opsx:verify + +AI: 正在验证 add-dark-mode... + + 完整性 + ✓ tasks.md 中的所有 8 个任务都已勾选 + ✓ 规范中的所有需求都有对应代码 + ⚠ 场景"系统偏好检测"没有测试覆盖 + + 正确性 + ✓ 实施符合规范意图 + ✓ 场景中的边缘情况已处理 + ✓ 错误状态与规范定义匹配 + + 一致性 + ✓ 设计决策反映在代码结构中 + ✓ 命名约定与 design.md 一致 + ⚠ 设计提到"CSS 变量"但实施使用了 Tailwind 类 + + 摘要 + ───────────────────────────── + 严重问题：0 + 警告：2 + 可以归档：是（有警告） + + 建议： + 1. 为系统偏好检测添加测试 + 2. 更新 design.md 以反映 Tailwind 用法，或重构为使用 CSS 变量 +``` + +**提示：** +- 在归档前运行以尽早发现不匹配 +- 警告不阻止归档但指示潜在问题 +- 在提交前审查 AI 工作很有用 +- 可以发现工件与实施之间的偏差 + +--- + +### `/opsx:sync` + +**可选命令。** 将变更中的增量规范合并到主规范。归档会在需要时提示同步，因此您通常不需要手动运行此命令。 + +**语法：** +``` +/opsx:sync [变更名称] +``` + +**参数：** +| 参数 | 必需 | 描述 | +|------|------|------| +| `变更名称` | 否 | 要同步的变更（如果未提供则从上下文推断） | + +**功能：** +- 从变更文件夹读取增量规范 +- 解析 ADDED/MODIFIED/REMOVED/RENAMED 部分 +- 将更改合并到主 `openspec/specs/` 目录 +- 保留增量中未提及的现有内容 +- 不归档变更（保持活动状态） + +**示例：** +```text +You: /opsx:sync + +AI: 正在同步 add-dark-mode 增量规范... + + 读取：openspec/changes/add-dark-mode/specs/ui/spec.md + 目标：openspec/specs/ui/spec.md + + 待应用的变更： + ✓ 新增：主题选择需求（2 个场景） + ✓ 新增：无障碍需求（1 个场景） + + 正在合并... + ✓ openspec/specs/ui/spec.md 已更新 + + 变更保持活动状态。准备好后运行 /opsx:archive 完成归档。 +``` + +**何时手动使用：** + +| 场景 | 使用同步？ | +|------|-----------| +| 长期运行的变更，希望在归档前将规范放入主规范 | 是 | +| 多个并行变更需要更新的基础规范 | 是 | +| 希望单独预览/审查合并 | 是 | +| 快速变更，直接归档 | 否（归档会处理） | + +**提示：** +- 同步是智能的，不是复制粘贴 +- 可以向现有需求添加场景而不会重复 +- 同步后变更保持活动状态（未归档） +- 大多数用户永远不需要直接调用此命令——归档会在需要时提示 + +--- + +### `/opsx:archive` + +归档已完成的变更。最终确定变更并将其移动到归档文件夹。 + +**语法：** +``` +/opsx:archive [变更名称] +``` + +**参数：** +| 参数 | 必需 | 描述 | +|------|------|------| +| `变更名称` | 否 | 要归档的变更（如果未提供则从上下文推断） | + +**功能：** +- 检查工件完成状态 +- 检查任务完成情况（如果未完成则警告） +- 提供同步增量规范（如果尚未同步） +- 将变更文件夹移动到 `openspec/changes/archive/YYYY-MM-DD-<名称>/` +- 保留所有工件用于审计跟踪 + +**示例：** +```text +You: /opsx:archive + +AI: 正在归档 add-dark-mode... + + 工件状态： + ✓ proposal.md 存在 + ✓ specs/ 存在 + ✓ design.md 存在 + ✓ tasks.md 存在（8/8 任务完成） + + 增量规范：尚未同步 + → 立即同步？（推荐） + +You: 是 + +AI: ✓ 已同步规范到 openspec/specs/ui/spec.md + ✓ 已移动到 openspec/changes/archive/2025-01-24-add-dark-mode/ + + 变更已成功归档。 +``` + +**提示：** +- 归档不会因未完成的任务而阻止，但会发出警告 +- 增量规范可以在归档期间或之前同步 +- 归档的变更保留用于历史记录 +- 使用 `/opsx:verify` 首先发现问题 + +--- + +### `/opsx:bulk-archive` + +一次归档多个已完成的变更。处理变更之间的规范冲突。 + +**语法：** +``` +/opsx:bulk-archive [变更名称...] +``` + +**参数：** +| 参数 | 必需 | 描述 | +|------|------|------| +| `变更名称` | 否 | 要归档的特定变更（如果未提供则提示选择） | + +**功能：** +- 列出所有已完成的变更 +- 归档前验证每个变更 +- 检测变更之间的规范冲突 +- 通过检查实际实施内容解决冲突 +- 按时间顺序归档 + +**示例：** +``` +You: /opsx:bulk-archive + +AI: 找到 3 个已完成的变更： + - add-dark-mode（8/8 任务完成） + - fix-login-bug（3/3 任务完成） + - update-footer（2/2 任务完成） + + 正在检查规范冲突... + ⚠ add-dark-mode 和 update-footer 都涉及 specs/ui/ + + 正在检查代码库以解决... + 两个变更都已实施。将按时间顺序合并： + 1. add-dark-mode（1月20日创建） + 2. update-footer（1月22日创建） + + 归档全部 3 个变更？ + +You: 是 + +AI: ✓ 已归档 add-dark-mode + ✓ 已归档 fix-login-bug + ✓ 已归档 update-footer + 规范已合并：add-dark-mode → update-footer +``` + +**提示：** +- 适合并行工作流 +- 冲突解决是智能的（检查代码库） +- 变更按创建顺序归档 +- 覆盖规范内容前会提示 + +--- + +### `/opsx:onboard` + +通过完整 OpenSpec 工作流程的引导式入门。使用您的实际代码库进行交互式教程。 + +**语法：** +``` +/opsx:onboard +``` + +**功能：** +- 通过完整的工作流程周期进行讲解 +- 扫描您的代码库以寻找真正的改进机会 +- 使用真实工件创建实际变更 +- 实施实际工作（小的、安全的更改） +- 归档已完成的变更 +- 在发生时解释每个步骤 + +**阶段：** +1. 欢迎和代码库分析 +2. 寻找改进机会 +3. 创建变更 (`/opsx:new`) +4. 编写提案 +5. 创建规范 +6. 编写设计 +7. 创建任务 +8. 实施任务 (`/opsx:apply`) +9. 验证实施 +10. 归档变更 +11. 摘要和后续步骤 + +**示例：** +``` +You: /opsx:onboard + +AI: 欢迎使用 OpenSpec！ + + 我将使用你的实际代码库引导你完成完整的工作流程。 + 我们将找到一些可以改进的小问题，为其创建一个正式的变更， + 实施它，然后归档它。 + + 让我扫描你的代码库寻找机会... + + [分析代码库] + + 我找到了几个我们可以处理的事项： + 1. 为联系表单添加输入验证 + 2. 改进身份验证流程中的错误消息 + 3. 为异步按钮添加加载状态 + + 你对哪个感兴趣？（或者建议其他内容） +``` + +**提示：** +- 最适合学习工作流程的新用户 +- 使用真实代码，不是玩具示例 +- 创建可以保留或丢弃的真实变更 +- 需要 15-30 分钟完成 + +--- + +## 按 AI 工具的命令语法 + +不同的 AI 工具使用略有不同的命令语法。使用与您的工具匹配的格式： + +| 工具 | 语法示例 | +|------|----------| +| Claude Code | `/opsx:propose`, `/opsx:apply` | +| Cursor | `/opsx-propose`, `/opsx-apply` | +| Windsurf | `/opsx-propose`, `/opsx-apply` | +| Copilot (IDE) | `/opsx-propose`, `/opsx-apply` | +| Trae | 基于技能的调用，如 `/openspec-propose`, `/openspec-apply-change`（不生成 `opsx-*` 命令文件） | + +所有工具的意图相同，但命令的呈现方式可能因集成而异。 + +> **注意：** GitHub Copilot 命令（`.github/prompts/*.prompt.md`）仅在 IDE 扩展中可用（VS Code、JetBrains、Visual Studio）。GitHub Copilot CLI 目前不支持自定义提示文件——有关详细信息和解决方法，请参见[支持的工具](supported-tools.md)。 + +--- + +## 旧版命令 + +这些命令使用较旧的"一次性"工作流程。它们仍然有效，但推荐使用 OPSX 命令。 + +| 命令 | 功能 | +|------|------| +| `/openspec:proposal` | 一次创建所有工件（提案、规范、设计、任务） | +| `/openspec:apply` | 实施变更 | +| `/openspec:archive` | 归档变更 | + +**何时使用旧版命令：** +- 使用旧工作流程的现有项目 +- 简单的变更，不需要增量工件创建 +- 偏好全有或全无的方法 + +**迁移到 OPSX：** +旧版变更可以使用 OPSX 命令继续。工件结构是兼容的。 + +--- + +## 故障排除 + +### "找不到变更" + +命令无法识别要处理的变更。 + +**解决方案：** +- 显式指定变更名称：`/opsx:apply 添加深色模式` +- 检查变更文件夹是否存在：`openspec list` +- 验证您在正确的项目目录中 + +### "没有工件就绪" + +所有工件要么已完成，要么因缺少依赖项而被阻塞。 + +**解决方案：** +- 运行 `openspec status --change <名称>` 查看阻塞原因 +- 检查所需的工件是否存在 +- 首先创建缺失的依赖项工件 + +### "找不到架构" + +指定的架构不存在。 + +**解决方案：** +- 列出可用架构：`openspec schemas` +- 检查架构名称的拼写 +- 如果是自定义架构，请创建：`openspec schema init <名称>` + +### 命令未被识别 + +AI 工具不识别 OpenSpec 命令。 + +**解决方案：** +- 确保 OpenSpec 已初始化：`openspec init` +- 重新生成技能：`openspec update` +- 检查 `.claude/skills/` 目录是否存在（对于 Claude Code） +- 重启您的 AI 工具以加载新技能 + +### 工件生成不正确 + +AI 创建不完整或不正确的工件。 + +**解决方案：** +- 在 `openspec/config.yaml` 中添加项目上下文 +- 为每个工件添加特定指导规则 +- 在变更描述中提供更多详细信息 +- 使用 `/opsx:continue` 代替 `/opsx:ff` 以获得更多控制 + +--- + +## 后续步骤 + +- [工作流程](workflows.md) - 常见模式及何时使用每个命令 +- [CLI](cli.md) - 用于管理和验证的终端命令 +- [自定义](customization.md) - 创建自定义架构和工作流程 diff --git a/docs/i18n/zh-cn/concepts.md b/docs/i18n/zh-cn/concepts.md new file mode 100644 index 000000000..f8a2d88c1 --- /dev/null +++ b/docs/i18n/zh-cn/concepts.md @@ -0,0 +1,624 @@ +> **声明**：本文档由 AI 翻译，使用 `mimo-v2-pro` 进行翻译。 + +# 概念 + +本指南解释了 OpenSpec 背后的核心理念以及它们如何协作。如需实际使用说明，请参阅[快速开始](getting-started.md)和[工作流](workflows.md)。 + +## 理念 + +OpenSpec 围绕四个原则构建： + +``` +灵活而非僵化 — 无阶段门槛，做有意义的事 +迭代而非瀑布 — 边构建边学习，持续改进 +简洁而非复杂 — 轻量级设置，最低限度的流程 +现有项目优先 — 适用于现有代码库，而非仅限于全新项目 +``` + +### 为什么这些原则重要 + +**灵活而非僵化。** 传统的规范系统将你锁定在阶段中：先规划，再实现，然后完成。OpenSpec 更加灵活 — 你可以按照对工作有意义的任何顺序创建工件。 + +**迭代而非瀑布。** 需求会变化，理解会深入。开始时看似合理的方法，在查看代码库后可能不再适用。OpenSpec 接受这一现实。 + +**简洁而非复杂。** 一些规范框架需要大量的设置、严格的格式或重量级的流程。OpenSpec 不会妨碍你。几秒钟即可初始化，立即开始工作，仅在需要时进行自定义。 + +**现有项目优先。** 大多数软件工作不是从零开始构建 — 而是修改现有系统。OpenSpec 的增量式方法使得指定对现有行为的更改变得容易，而非仅仅描述新系统。 + +## 全局概览 + +OpenSpec 将你的工作组织为两个主要区域： + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ openspec/ │ +│ │ +│ ┌─────────────────────┐ ┌──────────────────────────────┐ │ +│ │ specs/ │ │ changes/ │ │ +│ │ │ │ │ │ +│ │ 真实来源 │◄─────│ 提议的修改 │ │ +│ │ 系统当前的行为 │ 合并 │ 每个更改 = 一个文件夹 │ │ +│ │ │ │ 包含工件和增量规范 │ │ +│ │ │ │ │ │ +│ └─────────────────────┘ └──────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +**Specs** 是真实来源 — 它们描述系统当前的行为。 + +**Changes** 是提议的修改 — 它们位于独立的文件夹中，直到你准备合并它们。 + +这种分离是关键。你可以并行处理多个更改而不会冲突。你可以在更改影响主规范之前对其进行审查。当你归档一个更改时，其增量会干净地合并到真实来源中。 + +## 规范（Specs） + +规范使用结构化的需求和场景来描述系统的行为。 + +### 结构 + +``` +openspec/specs/ +├── auth/ +│ └── spec.md # 认证行为 +├── payments/ +│ └── spec.md # 支付处理 +├── notifications/ +│ └── spec.md # 通知系统 +└── ui/ + └── spec.md # UI 行为和主题 +``` + +按领域组织规范 — 对系统有意义的逻辑分组。常见模式： + +- **按功能区域**：`auth/`、`payments/`、`search/` +- **按组件**：`api/`、`frontend/`、`workers/` +- **按限界上下文**：`ordering/`、`fulfillment/`、`inventory/` + +### 规范格式 + +规范包含需求，每个需求都有场景： + +```markdown +# 认证规范 + +## 目的 +应用程序的认证和会话管理。 + +## 需求 + +### Requirement: 用户认证 +系统 SHALL 在成功登录时签发 JWT 令牌。 + +#### Scenario: 有效凭证 +- GIVEN 用户拥有有效凭证 +- WHEN 用户提交登录表单 +- THEN 返回 JWT 令牌 +- AND 用户被重定向到仪表板 + +#### Scenario: 无效凭证 +- GIVEN 无效凭证 +- WHEN 用户提交登录表单 +- THEN 显示错误消息 +- AND 不签发令牌 + +### Requirement: 会话过期 +系统 MUST 在 30 分钟无活动后使会话过期。 + +#### Scenario: 空闲超时 +- GIVEN 已认证的会话 +- WHEN 30 分钟无活动 +- THEN 会话被无效化 +- AND 用户必须重新认证 +``` + +**关键元素：** + +| 元素 | 用途 | +|------|------| +| `## Purpose` | 此规范领域的高层次描述 | +| `### Requirement:` | 系统必须具备的特定行为 | +| `#### Scenario:` | 需求在实际中的具体示例 | +| SHALL/MUST/SHOULD | RFC 2119 关键词，指示需求强度 | + +### 为什么要这样结构化规范 + +**需求是"什么"** — 它们陈述系统应该做什么，而不指定实现方式。 + +**场景是"何时"** — 它们提供可验证的具体示例。好的场景： +- 可测试（你可以为其编写自动化测试） +- 覆盖正常路径和边界情况 +- 使用 Given/When/Then 或类似的结构化格式 + +**RFC 2119 关键词**（SHALL、MUST、SHOULD、MAY）传达意图： +- **MUST/SHALL** — 绝对需求 +- **SHOULD** — 推荐，但存在例外 +- **MAY** — 可选 + +### 规范是什么（和不是什么） + +规范是**行为契约**，而非实现计划。 + +好的规范内容： +- 用户或下游系统依赖的可观察行为 +- 输入、输出和错误条件 +- 外部约束（安全性、隐私、可靠性、兼容性） +- 可测试或可明确验证的场景 + +规范中应避免： +- 内部类名/函数名 +- 库或框架选择 +- 逐步实现细节 +- 详细的执行计划（这些属于 `design.md` 或 `tasks.md`） + +快速检验： +- 如果实现可以在不改变外部可见行为的情况下更改，它可能不属于规范。 + +### 保持轻量：渐进式严谨 + +OpenSpec 旨在避免官僚主义。使用最轻量的级别，同时仍保持更改的可验证性。 + +**精简规范（默认）：** +- 简短的以行为优先的需求 +- 清晰的范围和非目标 +- 一些具体的验收检查 + +**完整规范（用于更高风险）：** +- 跨团队或跨仓库的更改 +- API/契约更改、迁移、安全/隐私问题 +- 歧义可能导致昂贵返工的更改 + +大多数更改应保持在精简模式。 + +### 人类 + Agent 协作 + +在许多团队中，人类探索，Agent 起草工件。预期的循环是： + +1. 人类提供意图、上下文和约束。 +2. Agent 将其转化为以行为优先的需求和场景。 +3. Agent 将实现细节保留在 `design.md` 和 `tasks.md` 中，而非 `spec.md`。 +4. 验证在实现前确认结构和清晰度。 + +这使规范对人类可读，对 Agent 保持一致。 + +## 更改（Changes） + +更改是对系统的提议修改，打包为一个文件夹，包含理解和实现它所需的一切。 + +### 更改结构 + +``` +openspec/changes/add-dark-mode/ +├── proposal.md # 为什么和做什么 +├── design.md # 怎么做（技术方案） +├── tasks.md # 实现清单 +├── .openspec.yaml # 更改元数据（可选） +└── specs/ # 增量规范 + └── ui/ + └── spec.md # ui/spec.md 中的变化 +``` + +每个更改是自包含的。它包含： +- **工件（Artifacts）** — 捕获意图、设计和任务的文档 +- **增量规范（Delta specs）** — 正在添加、修改或删除的内容的规范 +- **元数据（Metadata）** — 此特定更改的可选配置 + +### 为什么更改是文件夹 + +将更改打包为文件夹有几个好处： + +1. **一切集中在一起。** 提案、设计、任务和规范在一个地方。无需在不同位置搜索。 + +2. **并行工作。** 多个更改可以同时存在而不会冲突。在 `add-dark-mode` 工作的同时，`fix-auth-bug` 也可以在进行中。 + +3. **清晰的历史记录。** 归档时，更改会移动到 `changes/archive/`，并保留其完整上下文。你可以回顾并理解不仅是什么变了，还有为什么变。 + +4. **便于审查。** 更改文件夹易于审查 — 打开它，阅读提案，检查设计，查看规范增量。 + +## 工件（Artifacts） + +工件是更改中指导工作的文档。 + +### 工件流程 + +``` +proposal ──────► specs ──────► design ──────► tasks ──────► implement + │ │ │ │ + why what how steps + + scope changes approach to take +``` + +工件相互构建。每个工件为下一个工件提供上下文。 + +### 工件类型 + +#### 提案（`proposal.md`） + +提案捕获高层次的**意图**、**范围**和**方法**。 + +```markdown +# Proposal: 添加深色模式 + +## Intent +用户要求添加深色模式选项，以减少夜间使用时的眼睛疲劳，并匹配系统偏好。 + +## Scope +范围内： +- 设置中的主题切换 +- 系统偏好检测 +- 在 localStorage 中持久化偏好 + +范围外： +- 自定义颜色主题（未来工作） +- 每页主题覆盖 + +## Approach +使用 CSS 自定义属性进行主题化，结合 React Context 进行状态管理。首次加载时检测系统偏好，允许手动覆盖。 +``` + +**何时更新提案：** +- 范围变化（缩小或扩大） +- 意图明确（更好地理解问题） +- 方法根本性转变 + +#### 规范（`specs/` 中的增量规范） + +增量规范描述相对于当前规范的**变化内容**。参见下面的[增量规范](#增量规范)。 + +#### 设计（`design.md`） + +设计捕获**技术方案**和**架构决策**。 + +````markdown +# Design: 添加深色模式 + +## Technical Approach +通过 React Context 管理主题状态以避免属性钻取。CSS 自定义属性实现运行时切换而无需类切换。 + +## Architecture Decisions + +### Decision: Context 优于 Redux +使用 React Context 管理主题状态的原因： +- 简单的二元状态（亮/暗） +- 无复杂的状态转换 +- 避免添加 Redux 依赖 + +### Decision: CSS 自定义属性 +使用 CSS 变量而非 CSS-in-JS 的原因： +- 与现有样式表兼容 +- 无运行时开销 +- 浏览器原生解决方案 + +## Data Flow +``` +ThemeProvider (context) + │ + ▼ +ThemeToggle ◄──► localStorage + │ + ▼ +CSS Variables (applied to :root) +``` + +## File Changes +- `src/contexts/ThemeContext.tsx` (new) +- `src/components/ThemeToggle.tsx` (new) +- `src/styles/globals.css` (modified) +```` + +**何时更新设计：** +- 实现发现方案不可行 +- 发现更好的解决方案 +- 依赖或约束发生变化 + +#### 任务（`tasks.md`） + +任务是**实现清单** — 带复选框的具体步骤。 + +```markdown +# Tasks + +## 1. 主题基础设施 +- [ ] 1.1 创建具有亮/暗状态的 ThemeContext +- [ ] 1.2 添加颜色的 CSS 自定义属性 +- [ ] 1.3 实现 localStorage 持久化 +- [ ] 1.4 添加系统偏好检测 + +## 2. UI 组件 +- [ ] 2.1 创建 ThemeToggle 组件 +- [ ] 2.2 在设置页面添加切换 +- [ ] 2.3 更新 Header 以包含快速切换 + +## 3. 样式 +- [ ] 3.1 定义深色主题调色板 +- [ ] 3.2 更新组件以使用 CSS 变量 +- [ ] 3.3 测试对比度以确保可访问性 +``` + +**任务最佳实践：** +- 将相关任务分组在标题下 +- 使用层次编号（1.1、1.2 等） +- 保持任务足够小，可在一次会话中完成 +- 完成任务后勾选复选框 + +## 增量规范（Delta Specs） + +增量规范是使 OpenSpec 适用于现有项目开发的关键概念。它们描述**变化内容**，而非重述整个规范。 + +### 格式 + +```markdown +# Delta for Auth + +## ADDED Requirements + +### Requirement: 双因素认证 +系统 MUST 支持基于 TOTP 的双因素认证。 + +#### Scenario: 2FA 注册 +- GIVEN 用户未启用 2FA +- WHEN 用户在设置中启用 2FA +- THEN 显示用于身份验证器应用设置的 QR 码 +- AND 用户必须在激活前使用代码验证 + +#### Scenario: 2FA 登录 +- GIVEN 用户已启用 2FA +- WHEN 用户提交有效凭证 +- THEN 呈现 OTP 质询 +- AND 仅在有效 OTP 后完成登录 + +## MODIFIED Requirements + +### Requirement: 会话过期 +系统 MUST 在 15 分钟无活动后使会话过期。 +（之前：30 分钟） + +#### Scenario: 空闲超时 +- GIVEN 已认证的会话 +- WHEN 15 分钟无活动 +- THEN 会话被无效化 + +## REMOVED Requirements + +### Requirement: 记住我 +（已弃用，改用 2FA。用户应在每个会话中重新认证。） +``` + +### 增量部分 + +| 部分 | 含义 | 归档时的操作 | +|------|------|-------------| +| `## ADDED Requirements` | 新行为 | 追加到主规范 | +| `## MODIFIED Requirements` | 修改的行为 | 替换现有需求 | +| `## REMOVED Requirements` | 弃用的行为 | 从主规范中删除 | + +### 为什么使用增量而非完整规范 + +**清晰度。** 增量精确显示变化内容。阅读完整规范，你需要在脑中与当前版本进行对比。 + +**避免冲突。** 两个更改可以触及同一个规范文件而不会冲突，只要它们修改不同的需求。 + +**审查效率。** 审查者看到的是更改，而非未更改的上下文。关注重要的部分。 + +**适用于现有项目。** 大多数工作修改现有行为。增量使修改成为一等公民，而非事后补充。 + +## 模式（Schemas） + +模式定义工作流的工件类型及其依赖关系。 + +### 模式如何工作 + +```yaml +# openspec/schemas/spec-driven/schema.yaml +name: spec-driven +artifacts: + - id: proposal + generates: proposal.md + requires: [] # 无依赖，可以首先创建 + + - id: specs + generates: specs/**/*.md + requires: [proposal] # 需要先有 proposal + + - id: design + generates: design.md + requires: [proposal] # 可以与 specs 并行创建 + + - id: tasks + generates: tasks.md + requires: [specs, design] # 需要 specs 和 design +``` + +**工件形成依赖图：** + +``` + proposal + （根节点） + │ + ┌─────────────┴─────────────┐ + │ │ + ▼ ▼ + specs design + （依赖：proposal） （依赖：proposal） + │ │ + └─────────────┬─────────────┘ + │ + ▼ + tasks + （依赖：specs, design） +``` + +**依赖是启用器，而非门槛。** 它们显示可以创建什么，而非你接下来必须创建什么。如果不需要，可以跳过 design。可以在 design 之前或之后创建 specs — 两者都只依赖于 proposal。 + +### 内置模式 + +**spec-driven**（默认） + +规范驱动开发的标准工作流： + +``` +proposal → specs → design → tasks → implement +``` + +适用于：大多数功能工作，你希望在实现前就规范达成一致。 + +### 自定义模式 + +为你的团队工作流创建自定义模式： + +```bash +# 从头创建 +openspec schema init research-first + +# 或 fork 现有模式 +openspec schema fork spec-driven research-first +``` + +**自定义模式示例：** + +```yaml +# openspec/schemas/research-first/schema.yaml +name: research-first +artifacts: + - id: research + generates: research.md + requires: [] # 先做研究 + + - id: proposal + generates: proposal.md + requires: [research] # 基于研究的提案 + + - id: tasks + generates: tasks.md + requires: [proposal] # 跳过 specs/design，直接进入 tasks +``` + +有关创建和使用自定义模式的完整详细信息，请参阅[自定义](customization.md)。 + +## 归档（Archive） + +归档通过将增量规范合并到主规范中并为历史保留更改来完成更改。 + +### 归档时会发生什么 + +``` +归档前： + +openspec/ +├── specs/ +│ └── auth/ +│ └── spec.md ◄────────────────┐ +└── changes/ │ + └── add-2fa/ │ + ├── proposal.md │ + ├── design.md │ 合并 + ├── tasks.md │ + └── specs/ │ + └── auth/ │ + └── spec.md ─────────┘ + + +归档后： + +openspec/ +├── specs/ +│ └── auth/ +│ └── spec.md # 现在包含 2FA 需求 +└── changes/ + └── archive/ + └── 2025-01-24-add-2fa/ # 为历史保留 + ├── proposal.md + ├── design.md + ├── tasks.md + └── specs/ + └── auth/ + └── spec.md +``` + +### 归档过程 + +1. **合并增量。** 每个增量规范部分（ADDED/MODIFIED/REMOVED）被应用到相应的主规范。 + +2. **移动到归档。** 更改文件夹移动到 `changes/archive/`，带有日期前缀以按时间顺序排列。 + +3. **保留上下文。** 所有工件在归档中保持完整。你可以随时回顾以理解更改的原因。 + +### 为什么归档很重要 + +**干净的状态。** 活跃更改（`changes/`）只显示进行中的工作。已完成的工作移出视野。 + +**审计跟踪。** 归档保留每个更改的完整上下文 — 不仅是什么变了，还有解释为什么的提案、解释如何做的设计以及展示完成工作的任务。 + +**规范演进。** 随着更改被归档，规范有机增长。每次归档都合并其增量，逐步构建全面的规范。 + +## 整体协作方式 + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ OPENSPEC 流程 │ +│ │ +│ ┌────────────────┐ │ +│ │ 1. 开始 │ /opsx:propose (core) 或 /opsx:new (expanded) │ +│ │ 变更 │ │ +│ └───────┬────────┘ │ +│ │ │ +│ ▼ │ +│ ┌────────────────┐ │ +│ │ 2. 创建 │ /opsx:ff 或 /opsx:continue (扩展工作流) │ +│ │ 工件 │ 创建 proposal → specs → design → tasks │ +│ │ │ （基于模式依赖关系） │ +│ └───────┬────────┘ │ +│ │ │ +│ ▼ │ +│ ┌────────────────┐ │ +│ │ 3. 实现 │ /opsx:apply │ +│ │ 任务 │ 执行任务，完成即勾选 │ +│ │ │◄──── 在学习过程中更新工件 │ +│ └───────┬────────┘ │ +│ │ │ +│ ▼ │ +│ ┌────────────────┐ │ +│ │ 4. 验证 │ /opsx:verify（可选） │ +│ │ 工作 │ 检查实现是否符合规范 │ +│ └───────┬────────┘ │ +│ │ │ +│ ▼ │ +│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │ +│ │ 5. 归档 │────►│ 增量规范合并到主规范 │ │ +│ │ 变更 │ │ 变更文件夹移动到 archive/ │ │ +│ └────────────────┘ │ 规范成为更新后的真实来源 │ │ +│ └──────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +**良性循环：** + +1. 规范描述当前行为 +2. 更改提议修改（作为增量） +3. 实现使更改变为现实 +4. 归档将增量合并到规范中 +5. 规范现在描述新行为 +6. 下一个更改基于更新后的规范构建 + +## 术语表 + +| 术语 | 定义 | +|------|------| +| **工件（Artifact）** | 更改中的文档（提案、设计、任务或增量规范） | +| **归档（Archive）** | 完成更改并将其增量合并到主规范的过程 | +| **更改（Change）** | 对系统的提议修改，打包为包含工件的文件夹 | +| **增量规范（Delta spec）** | 描述相对于当前规范的变化（ADDED/MODIFIED/REMOVED）的规范 | +| **领域（Domain）** | 规范的逻辑分组（例如，`auth/`、`payments/`） | +| **需求（Requirement）** | 系统必须具备的特定行为 | +| **场景（Scenario）** | 需求的具体示例，通常采用 Given/When/Then 格式 | +| **模式（Schema）** | 工件类型及其依赖关系的定义 | +| **规范（Spec）** | 描述系统行为的规范，包含需求和场景 | +| **真实来源（Source of truth）** | `openspec/specs/` 目录，包含当前一致认可的行为 | + +## 后续步骤 + +- [快速开始](getting-started.md) - 实际的第一步 +- [工作流](workflows.md) - 常见模式及使用时机 +- [命令](commands.md) - 完整的命令参考 +- [自定义](customization.md) - 创建自定义模式和配置项目 diff --git a/docs/i18n/zh-cn/customization.md b/docs/i18n/zh-cn/customization.md new file mode 100644 index 000000000..3b38f0607 --- /dev/null +++ b/docs/i18n/zh-cn/customization.md @@ -0,0 +1,344 @@ +> **声明**：本文档由 AI 翻译，使用 `mimo-v2-pro` 进行翻译。 + +# 自定义 + +OpenSpec 提供三个层级的自定义： + +| 层级 | 功能 | 适用场景 | +|------|------|----------| +| **项目配置** | 设置默认值、注入上下文/规则 | 大多数团队 | +| **自定义 Schema** | 定义自己的工作流产物 | 拥有独特流程的团队 | +| **全局覆盖** | 跨所有项目共享 Schema | 高级用户 | + +--- + +## 项目配置 + +`openspec/config.yaml` 文件是为团队自定义 OpenSpec 的最简单方式。它可以让你： + +- **设置默认 Schema** - 每个命令无需再加 `--schema` +- **注入项目上下文** - AI 可以看到你的技术栈、约定等 +- **添加针对特定产物的规则** - 为特定产物定义自定义规则 + +### 快速设置 + +```bash +openspec init +``` + +这会引导你交互式地创建配置文件。或者手动创建： + +```yaml +# openspec/config.yaml +schema: spec-driven + +context: | + Tech stack: TypeScript, React, Node.js, PostgreSQL + API style: RESTful, documented in docs/api.md + Testing: Jest + React Testing Library + We value backwards compatibility for all public APIs + +rules: + proposal: + - Include rollback plan + - Identify affected teams + specs: + - Use Given/When/Then format + - Reference existing patterns before inventing new ones +``` + +### 工作原理 + +**默认 Schema：** + +```bash +# 不使用配置 +openspec new change my-feature --schema spec-driven + +# 使用配置 - Schema 自动应用 +openspec new change my-feature +``` + +**上下文和规则注入：** + +当生成任何产物时，你的上下文和规则会被注入到 AI 提示词中： + +```xml + +Tech stack: TypeScript, React, Node.js, PostgreSQL +... + + + +- Include rollback plan +- Identify affected teams + + + +``` + +- **上下文** 会出现在所有产物中 +- **规则** 仅出现在匹配的产物中 + +### Schema 解析顺序 + +当 OpenSpec 需要 Schema 时，按以下顺序查找： + +1. CLI 参数：`--schema ` +2. Change 元数据（change 文件夹中的 `.openspec.yaml`） +3. 项目配置（`openspec/config.yaml`） +4. 默认值（`spec-driven`） + +--- + +## 自定义 Schema + +当项目配置不足以满足需求时，你可以创建自己的 Schema，实现完全自定义的工作流。自定义 Schema 位于项目的 `openspec/schemas/` 目录中，并随代码一起进行版本控制。 + +```text +your-project/ +├── openspec/ +│ ├── config.yaml # 项目配置 +│ ├── schemas/ # 自定义 Schema 存放位置 +│ │ └── my-workflow/ +│ │ ├── schema.yaml +│ │ └── templates/ +│ └── changes/ # 你的 Change +└── src/ +``` + +### 派生现有 Schema + +最快的自定义方式是派生一个内置 Schema： + +```bash +openspec schema fork spec-driven my-workflow +``` + +这会将整个 `spec-driven` Schema 复制到 `openspec/schemas/my-workflow/`，你可以自由编辑。 + +**你将获得：** + +```text +openspec/schemas/my-workflow/ +├── schema.yaml # 工作流定义 +└── templates/ + ├── proposal.md # Proposal 产物模板 + ├── spec.md # Specs 模板 + ├── design.md # Design 模板 + └── tasks.md # Tasks 模板 +``` + +现在你可以编辑 `schema.yaml` 来更改工作流，或编辑模板来改变 AI 生成的内容。 + +### 从零创建 Schema + +对于完全全新的工作流： + +```bash +# 交互式 +openspec schema init research-first + +# 非交互式 +openspec schema init rapid \ + --description "Rapid iteration workflow" \ + --artifacts "proposal,tasks" \ + --default +``` + +### Schema 结构 + +Schema 定义了工作流中的产物及其依赖关系： + +```yaml +# openspec/schemas/my-workflow/schema.yaml +name: my-workflow +version: 1 +description: My team's custom workflow + +artifacts: + - id: proposal + generates: proposal.md + description: Initial proposal document + template: proposal.md + instruction: | + Create a proposal that explains WHY this change is needed. + Focus on the problem, not the solution. + requires: [] + + - id: design + generates: design.md + description: Technical design + template: design.md + instruction: | + Create a design document explaining HOW to implement. + requires: + - proposal # Can't create design until proposal exists + + - id: tasks + generates: tasks.md + description: Implementation checklist + template: tasks.md + requires: + - design + +apply: + requires: [tasks] + tracks: tasks.md +``` + +**关键字段：** + +| 字段 | 用途 | +|------|------| +| `id` | 唯一标识符，用于命令和规则 | +| `generates` | 输出文件名（支持 glob 模式，如 `specs/**/*.md`） | +| `template` | `templates/` 目录中的模板文件 | +| `instruction` | 创建此产物时的 AI 指令 | +| `requires` | 依赖关系 - 必须先存在的产物 | + +### 模板 + +模板是引导 AI 的 Markdown 文件。在创建产物时，模板会被注入到提示词中。 + +```markdown + +## Why + + + +## What Changes + + + +## Impact + + +``` + +模板可以包含： +- AI 应填写的章节标题 +- 带有 AI 指导的 HTML 注释 +- 展示预期结构的示例格式 + +### 验证你的 Schema + +在使用自定义 Schema 之前，先验证它： + +```bash +openspec schema validate my-workflow +``` + +这会检查： +- `schema.yaml` 语法是否正确 +- 所有引用的模板是否存在 +- 是否存在循环依赖 +- Artifact ID 是否有效 + +### 使用你的自定义 Schema + +创建完成后，通过以下方式使用你的 Schema： + +```bash +# 在命令中指定 +openspec new change feature --schema my-workflow + +# 或在 config.yaml 中设为默认 +schema: my-workflow +``` + +### 调试 Schema 解析 + +不确定正在使用哪个 Schema？使用以下命令检查： + +```bash +# 查看特定 Schema 的解析来源 +openspec schema which my-workflow + +# 列出所有可用 Schema +openspec schema which --all +``` + +输出会显示它来自项目、用户目录还是包： + +```text +Schema: my-workflow +Source: project +Path: /path/to/project/openspec/schemas/my-workflow +``` + +--- + +> **注意：** OpenSpec 还支持用户级别的 Schema，位于 `~/.local/share/openspec/schemas/`，可跨项目共享，但建议使用项目级别的 `openspec/schemas/` Schema，因为它们会随代码一起进行版本控制。 + +--- + +## 示例 + +### 快速迭代工作流 + +适用于快速迭代的最小化工作流： + +```yaml +# openspec/schemas/rapid/schema.yaml +name: rapid +version: 1 +description: Fast iteration with minimal overhead + +artifacts: + - id: proposal + generates: proposal.md + description: Quick proposal + template: proposal.md + instruction: | + Create a brief proposal for this change. + Focus on what and why, skip detailed specs. + requires: [] + + - id: tasks + generates: tasks.md + description: Implementation checklist + template: tasks.md + requires: [proposal] + +apply: + requires: [tasks] + tracks: tasks.md +``` + +### 添加 Review 产物 + +派生默认 Schema 并添加审查步骤： + +```bash +openspec schema fork spec-driven with-review +``` + +然后编辑 `schema.yaml` 添加： + +```yaml + - id: review + generates: review.md + description: Pre-implementation review checklist + template: review.md + instruction: | + Create a review checklist based on the design. + Include security, performance, and testing considerations. + requires: + - design + + - id: tasks + # ... existing tasks config ... + requires: + - specs + - design + - review # 现在 tasks 也需要 review +``` + +--- + +## 另请参阅 + +- [CLI 参考：Schema 命令](cli.md#schema-commands) - 完整的命令文档 diff --git a/docs/i18n/zh-cn/getting-started.md b/docs/i18n/zh-cn/getting-started.md new file mode 100644 index 000000000..cb4075cc1 --- /dev/null +++ b/docs/i18n/zh-cn/getting-started.md @@ -0,0 +1,253 @@ +> **声明**：本文档由 AI 翻译，使用 `mimo-v2-pro` 进行翻译。 + +# 快速入门 + +本指南解释了在安装和初始化 OpenSpec 后它的工作原理。安装说明请参阅 [主 README](../README.md#quick-start)。 + +## 工作原理 + +OpenSpec 帮助你和你的 AI 编程助手在编写任何代码之前就构建内容达成一致。 + +**默认快速路径（核心配置文件）：** + +```text +/opsx:propose ──► /opsx:apply ──► /opsx:archive +``` + +**扩展路径（自定义工作流选择）：** + +```text +/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive +``` + +默认全局配置文件是 `core`，包含 `propose`、`explore`、`apply` 和 `archive`。你可以使用 `openspec config profile` 启用扩展工作流命令，然后运行 `openspec update`。 + +## OpenSpec 创建的内容 + +运行 `openspec init` 后，你的项目将具有以下结构： + +``` +openspec/ +├── specs/ # 真相来源（系统的行为描述） +│ └── / +│ └── spec.md +├── changes/ # 提议的更新（每个变更一个文件夹） +│ └── / +│ ├── proposal.md +│ ├── design.md +│ ├── tasks.md +│ └── specs/ # 增量规范（变更内容） +│ └── / +│ └── spec.md +└── config.yaml # 项目配置（可选） +``` + +**两个关键目录：** + +- **`specs/`** - 真相来源。这些规范描述系统当前的行为。按领域组织（例如 `specs/auth/`、`specs/payments/`）。 + +- **`changes/`** - 提议的修改。每个变更都有自己的文件夹，包含所有相关工件。变更完成后，其规范会合并到主 `specs/` 目录。 + +## 理解工件 + +每个变更文件夹包含指导工作的工件： + +| 工件 | 用途 | +|----------|---------| +| `proposal.md` | "为什么"和"什么" - 捕获意图、范围和方法 | +| `specs/` | 显示添加/修改/删除需求的增量规范 | +| `design.md` | "如何" - 技术方法和架构决策 | +| `tasks.md` | 带复选框的实现清单 | + +**工件相互构建：** + +``` +proposal ──► specs ──► design ──► tasks ──► implement + ▲ ▲ ▲ │ + └───────────┴──────────┴────────────────────┘ + 根据学习进行更新 +``` + +你随时可以回过头来改进早期的工件，随着在实现过程中学到更多。 + +## 增量规范的工作原理 + +增量规范是 OpenSpec 中的核心概念。它们显示相对于当前规范的变更内容。 + +### 格式 + +增量规范使用章节来指示变更类型： + +```markdown +# Auth 增量规范 + +## 添加的需求 + +### 需求：双因素认证 +系统必须在登录时要求第二因素验证。 + +#### 场景：需要 OTP +- 给定一个启用了 2FA 的用户 +- 当用户提交有效凭证时 +- 则显示 OTP 验证提示 + +## 修改的需求 + +### 需求：会话超时 +系统应在 30 分钟不活动后使会话过期。 +（之前：60 分钟） + +#### 场景：空闲超时 +- 给定一个已认证的会话 +- 当 30 分钟过去且没有活动时 +- 则会话被失效 + +## 删除的需求 + +### 需求：记住我 +（已弃用，改用 2FA） +``` + +### 归档时发生什么 + +当你归档一个变更时： + +1. **添加的需求** 被附加到主规范 +2. **修改的需求** 替换现有版本 +3. **删除的需求** 从主规范中删除 + +变更文件夹移动到 `openspec/changes/archive/` 以供审计历史记录。 + +## 示例：你的第一个变更 + +让我们通过向应用程序添加暗色模式来演示。 + +### 1. 启动变更（默认方式） + +```text +你：/opsx:propose add-dark-mode + +AI：已创建 openspec/changes/add-dark-mode/ + ✓ proposal.md — 我们为什么要做这个，以及正在改变什么 + ✓ specs/ — 需求和场景 + ✓ design.md — 技术方案 + ✓ tasks.md — 实现清单 + 准备好进行实现！ +``` + +如果你已启用扩展工作流配置文件，也可以分两步完成：先 `/opsx:new`，然后 `/opsx:ff`（或 `/opsx:continue` 逐步进行）。 + +### 2. 创建的内容 + +**proposal.md** - 捕获意图： + +```markdown +# 提案：添加暗色模式 + +## 意图 +用户请求暗色模式选项，以减少夜间使用时的眼部疲劳。 + +## 范围 +- 在设置中添加主题切换 +- 支持系统偏好检测 +- 将偏好持久化到 localStorage + +## 方法 +使用 CSS 自定义属性进行主题化，配合 React 上下文进行状态管理。 +``` + +**specs/ui/spec.md** - 显示新需求的增量规范： + +```markdown +# UI 增量规范 + +## 添加的需求 + +### 需求：主题选择 +系统应允许用户在亮色和暗色主题之间选择。 + +#### 场景：手动切换 +- 给定一个在任何页面上的用户 +- 当用户点击主题切换时 +- 则主题立即切换 +- 且偏好在会话间持久化 + +#### 场景：系统偏好 +- 给定一个没有保存偏好的用户 +- 当应用程序加载时 +- 则使用系统的首选配色方案 +``` + +**tasks.md** - 实现清单： + +```markdown +# 任务 + +## 1. 主题基础设施 +- [ ] 1.1 创建具有亮/暗状态的 ThemeContext +- [ ] 1.2 添加颜色的 CSS 自定义属性 +- [ ] 1.3 实现 localStorage 持久化 + +## 2. UI 组件 +- [ ] 2.1 创建 ThemeToggle 组件 +- [ ] 2.2 添加切换到设置页面 +- [ ] 2.3 更新 Header 以包含快速切换 + +## 3. 样式 +- [ ] 3.1 定义暗色主题调色板 +- [ ] 3.2 更新组件以使用 CSS 变量 +``` + +### 3. 实现 + +``` +你：/opsx:apply + +AI：正在处理任务... + ✓ 1.1 创建了具有亮/暗状态的 ThemeContext + ✓ 1.2 在 globals.css 中添加了 CSS 自定义属性 + ✓ 1.3 实现了 localStorage 持久化 + ✓ 2.1 创建了 ThemeToggle 组件 + ... + 所有任务完成！ +``` + +在实现过程中，如果发现设计需要调整，只需更新工件并继续即可。 + +### 4. 归档 + +``` +你：/opsx:archive + +AI：正在归档 add-dark-mode... + ✓ 已将规范合并到 openspec/specs/ui/spec.md + ✓ 已移动到 openspec/changes/archive/2025-01-24-add-dark-mode/ + 完成！准备好进行下一个功能。 +``` + +你的增量规范现在已成为主规范的一部分，记录了系统的工作方式。 + +## 验证和审查 + +使用 CLI 检查你的变更： + +```bash +# 列出活动变更 +openspec list + +# 查看变更详情 +openspec show add-dark-mode + +# 验证规范格式 +openspec validate add-dark-mode + +# 交互式仪表板 +openspec view +``` + +## 后续步骤 + +- [工作流](workflows.md) - 常见模式及何时使用每个命令 +- [命令](commands.md) - 所有斜杠命令的完整参考 +- [概念](concepts.md) - 更深入地理解规范、变更和模式 +- [自定义](customization.md) - 让 OpenSpec 按你的方式工作 diff --git a/docs/i18n/zh-cn/installation.md b/docs/i18n/zh-cn/installation.md new file mode 100644 index 000000000..3f034a9e7 --- /dev/null +++ b/docs/i18n/zh-cn/installation.md @@ -0,0 +1,81 @@ +> **声明**：本文档由 AI 翻译，使用 `mimo-v2-pro` 进行翻译。 + +# 安装 + +## 前提条件 + +- **Node.js 20.19.0 或更高版本** — 检查你的版本：`node --version` + +## 包管理器 + +### npm + +```bash +npm install -g @fission-ai/openspec@latest +``` + +### pnpm + +```bash +pnpm add -g @fission-ai/openspec@latest +``` + +### yarn + +```bash +yarn global add @fission-ai/openspec@latest +``` + +### bun + +```bash +bun add -g @fission-ai/openspec@latest +``` + +## Nix + +无需安装，直接运行 OpenSpec： + +```bash +nix run github:Fission-AI/OpenSpec -- init +``` + +或者安装到你的 profile： + +```bash +nix profile install github:Fission-AI/OpenSpec +``` + +或者在 `flake.nix` 中添加到你的开发环境： + +```nix +{ + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + openspec.url = "github:Fission-AI/OpenSpec"; + }; + + outputs = { nixpkgs, openspec, ... }: { + devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell { + buildInputs = [ openspec.packages.x86_64-linux.default ]; + }; + }; +} +``` + +## 验证安装 + +```bash +openspec --version +``` + +## 后续步骤 + +安装完成后，在你的项目中初始化 OpenSpec： + +```bash +cd your-project +openspec init +``` + +请参阅 [快速上手](getting-started.md) 获取完整的操作指南。 diff --git a/docs/i18n/zh-cn/migration-guide.md b/docs/i18n/zh-cn/migration-guide.md new file mode 100644 index 000000000..5ad46b87a --- /dev/null +++ b/docs/i18n/zh-cn/migration-guide.md @@ -0,0 +1,597 @@ +> **声明**：本文档由 AI 翻译，使用 `mimo-v2-pro` 进行翻译。 + +# 迁移到 OPSX + +本指南帮助你从旧版 OpenSpec 工作流过渡到 OPSX。迁移过程经过精心设计，力求平滑过渡——你现有的工作会被完整保留，而新系统提供更大的灵活性。 + +## 有哪些变化？ + +OPSX 用灵活的、基于操作的方式取代了旧的阶段锁定工作流。以下是关键变化： + +| 方面 | 旧版 | OPSX | +|------|------|------| +| **命令** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | 默认：`/opsx:propose`, `/opsx:apply`, `/opsx:archive`（扩展工作流命令可选） | +| **工作流** | 一次性创建所有制品 | 增量创建或一次性创建——由你选择 | +| **回退** | 笨拙的阶段门控 | 自然回退——随时更新任何制品 | +| **定制化** | 固定结构 | 基于 Schema，完全可自定义 | +| **配置** | 带标记的 `CLAUDE.md` + `project.md` | 简洁的 `openspec/config.yaml` 配置 | + +**理念变化：** 工作并非线性的。OPSX 不再假装它是线性的。 + +--- + +## 开始之前 + +### 你现有的工作是安全的 + +迁移过程以保留为设计原则： + +- **`openspec/changes/` 中的活跃变更** —— 完全保留。你可以用 OPSX 命令继续它们。 +- **已归档的变更** —— 不受影响。你的历史记录保持完整。 +- **`openspec/specs/` 中的主要规约** —— 不受影响。这些是你的事实来源。 +- **CLAUDE.md、AGENTS.md 等文件中的内容** —— 保留。仅移除 OpenSpec 标记块；你编写的所有内容都会保留。 + +### 会被移除的内容 + +仅移除正在被替换的 OpenSpec 管理的文件： + +| 内容 | 原因 | +|------|------| +| 旧版斜杠命令目录/文件 | 已被新的 skills 系统取代 | +| `openspec/AGENTS.md` | 已过时的工作流触发器 | +| `CLAUDE.md`、`AGENTS.md` 等中的 OpenSpec 标记 | 不再需要 | + +**各工具的旧版命令位置**（示例——你的工具可能不同）： + +- Claude Code: `.claude/commands/openspec/` +- Cursor: `.cursor/commands/openspec-*.md` +- Windsurf: `.windsurf/workflows/openspec-*.md` +- Cline: `.clinerules/workflows/openspec-*.md` +- Roo: `.roo/commands/openspec-*.md` +- GitHub Copilot: `.github/prompts/openspec-*.prompt.md`（仅 IDE 扩展；Copilot CLI 不支持） +- 其他工具（Augment、Continue、Amazon Q 等） + +迁移会检测你配置了哪些工具，并清理它们的旧版文件。 + +移除列表看起来可能很长，但这些都是 OpenSpec 最初创建的文件。你自己的内容永远不会被删除。 + +### 需要你注意的内容 + +有一个文件需要手动迁移： + +**`openspec/project.md`** —— 这个文件不会被自动删除，因为它可能包含你编写的项目上下文。你需要： + +1. 查看其内容 +2. 将有用的上下文移动到 `openspec/config.yaml`（参见下方指引） +3. 准备好后删除该文件 + +**我们做出这个改变的原因：** + +旧的 `project.md` 是被动的——代理可能会读取它，也可能不会，可能读了但忘了。我们发现可靠性参差不齐。 + +新的 `config.yaml` 上下文会**被主动注入到每个 OpenSpec 规划请求中**。这意味着你的项目约定、技术栈和规则在 AI 创建制品时始终存在。可靠性更高。 + +**权衡取舍：** + +由于上下文会注入到每个请求中，你需要保持简洁。专注于真正重要的内容： +- 技术栈和关键约定 +- AI 需要知道的非显而易见的约束 +- 之前经常被忽略的规则 + +不用担心做到完美。我们仍在探索最佳实践，随着实验的深入，也会持续改进上下文注入的方式。 + +--- + +## 执行迁移 + +`openspec init` 和 `openspec update` 都能检测旧版文件并引导你完成相同的清理过程。根据你的实际情况选择使用： + +- 新安装默认使用 `core` profile（`propose`、`explore`、`apply`、`archive`）。 +- 迁移安装会在需要时写入 `custom` profile，以保留你之前安装的工作流。 + +### 使用 `openspec init` + +如果你想添加新工具或重新配置工具设置，运行此命令： + +```bash +openspec init +``` + +init 命令会检测旧版文件并引导你完成清理： + +``` +Upgrading to the new OpenSpec + +OpenSpec now uses agent skills, the emerging standard across coding +agents. This simplifies your setup while keeping everything working +as before. + +Files to remove +No user content to preserve: + • .claude/commands/openspec/ + • openspec/AGENTS.md + +Files to update +OpenSpec markers will be removed, your content preserved: + • CLAUDE.md + • AGENTS.md + +Needs your attention + • openspec/project.md + We won't delete this file. It may contain useful project context. + + The new openspec/config.yaml has a "context:" section for planning + context. This is included in every OpenSpec request and works more + reliably than the old project.md approach. + + Review project.md, move any useful content to config.yaml's context + section, then delete the file when ready. + +? Upgrade and clean up legacy files? (Y/n) +``` + +**选择 yes 后会发生什么：** + +1. 移除旧版斜杠命令目录 +2. 从 `CLAUDE.md`、`AGENTS.md` 等文件中移除 OpenSpec 标记（你的内容保留） +3. 删除 `openspec/AGENTS.md` +4. 在 `.claude/skills/` 中安装新的 skills +5. 创建带有默认 schema 的 `openspec/config.yaml` + +### 使用 `openspec update` + +如果你只想迁移并将现有工具刷新到最新版本，运行此命令： + +```bash +openspec update +``` + +update 命令也会检测和清理旧版制品，然后刷新生成的 skills/命令以匹配你当前的 profile 和配置设置。 + +### 非交互式 / CI 环境 + +用于脚本化迁移： + +```bash +openspec init --force --tools claude +``` + +`--force` 标志跳过提示并自动接受清理。 + +--- + +## 将 project.md 迁移到 config.yaml + +旧的 `openspec/project.md` 是一个自由格式的 Markdown 文件，用于存放项目上下文。新的 `openspec/config.yaml` 是结构化的，并且——关键的是——**会被注入到每个规划请求中**，因此 AI 工作时你的约定始终存在。 + +### 迁移前 (project.md) + +```markdown +# Project Context + +This is a TypeScript monorepo using React and Node.js. +We use Jest for testing and follow strict ESLint rules. +Our API is RESTful and documented in docs/api.md. + +## Conventions + +- All public APIs must maintain backwards compatibility +- New features should include tests +- Use Given/When/Then format for specifications +``` + +### 迁移后 (config.yaml) + +```yaml +schema: spec-driven + +context: | + Tech stack: TypeScript, React, Node.js + Testing: Jest with React Testing Library + API: RESTful, documented in docs/api.md + We maintain backwards compatibility for all public APIs + +rules: + proposal: + - Include rollback plan for risky changes + specs: + - Use Given/When/Then format for scenarios + - Reference existing patterns before inventing new ones + design: + - Include sequence diagrams for complex flows +``` + +### 关键差异 + +| project.md | config.yaml | +|------------|-------------| +| 自由格式的 Markdown | 结构化的 YAML | +| 一大块文本 | 分离的上下文和按制品划分的规则 | +| 使用时机不明确 | 上下文出现在所有制品中；规则仅出现在匹配的制品中 | +| 无 schema 选择 | 显式的 `schema:` 字段设置默认工作流 | + +### 保留什么，丢弃什么 + +迁移时要有选择性。问问自己："AI 在*每个*规划请求中都需要这个吗？" + +**适合放入 `context:` 的内容：** +- 技术栈（语言、框架、数据库） +- 关键架构模式（monorepo、微服务等） +- 非显而易见的约束（"我们不能使用 X 库，因为……"） +- 经常被忽略的关键约定 + +**应移至 `rules:` 的内容：** +- 特定制品的格式要求（"在 specs 中使用 Given/When/Then"） +- 审查标准（"proposal 必须包含回滚计划"） +- 这些仅出现在匹配的制品中，使其他请求更精简 + +**完全省略的内容：** +- AI 已经知道的通用最佳实践 +- 可以精简的冗长说明 +- 不影响当前工作的历史背景 + +### 迁移步骤 + +1. **创建 config.yaml**（如果 init 还未创建）： + ```yaml + schema: spec-driven + ``` + +2. **添加你的上下文**（保持简洁——这些内容会进入每个请求）： + ```yaml + context: | + Your project background goes here. + Focus on what the AI genuinely needs to know. + ``` + +3. **添加按制品划分的规则**（可选）： + ```yaml + rules: + proposal: + - Your proposal-specific guidance + specs: + - Your spec-writing rules + ``` + +4. 将所有有用的内容迁移完成后，**删除 project.md**。 + +**不要过度思考。** 从要点开始，逐步迭代。如果发现 AI 遗漏了重要内容，就添加上去。如果上下文感觉臃肿，就精简它。这是一个活文档。 + +### 需要帮助？使用这个 Prompt + +如果你不确定如何提炼 project.md，可以问你的 AI 助手： + +``` +I'm migrating from OpenSpec's old project.md to the new config.yaml format. + +Here's my current project.md: +[paste your project.md content] + +Please help me create a config.yaml with: +1. A concise `context:` section (this gets injected into every planning request, so keep it tight—focus on tech stack, key constraints, and conventions that often get ignored) +2. `rules:` for specific artifacts if any content is artifact-specific (e.g., "use Given/When/Then" belongs in specs rules, not global context) + +Leave out anything generic that AI models already know. Be ruthless about brevity. +``` + +AI 会帮助你识别哪些是必需的、哪些可以精简。 + +--- + +## 新命令 + +命令可用性取决于 profile： + +**默认 (`core` profile)：** + +| 命令 | 用途 | +|------|------| +| `/opsx:propose` | 一步创建变更并生成规划制品 | +| `/opsx:explore` | 无结构地梳理思路 | +| `/opsx:apply` | 实施 tasks.md 中的任务 | +| `/opsx:archive` | 完成并归档变更 | + +**扩展工作流（自定义选择）：** + +| 命令 | 用途 | +|------|------| +| `/opsx:new` | 开始一个新的变更框架 | +| `/opsx:continue` | 创建下一个制品（一次一个） | +| `/opsx:ff` | 快进——一次性创建规划制品 | +| `/opsx:verify` | 验证实现是否匹配规约 | +| `/opsx:sync` | 预览/规约合并，无需归档 | +| `/opsx:bulk-archive` | 一次性归档多个变更 | +| `/opsx:onboard` | 端到端引导式上手工作流 | + +使用 `openspec config profile` 启用扩展命令，然后运行 `openspec update`。 + +### 旧版命令映射 + +| 旧版 | OPSX 等价命令 | +|------|--------------| +| `/openspec:proposal` | `/opsx:propose`（默认）或 `/opsx:new` 然后 `/opsx:ff`（扩展） | +| `/openspec:apply` | `/opsx:apply` | +| `/openspec:archive` | `/opsx:archive` | + +### 新功能 + +这些功能是扩展工作流命令集的一部分。 + +**细粒度的制品创建：** +``` +/opsx:continue +``` +基于依赖关系一次创建一个制品。当你想要审查每个步骤时使用此命令。 + +**探索模式：** +``` +/opsx:explore +``` +在承诺变更之前，与伙伴一起梳理思路。 + +--- + +## 理解新架构 + +### 从阶段锁定到灵活流动 + +旧版工作流强制线性推进： + +``` +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ PLANNING │ ───► │ IMPLEMENTING │ ───► │ ARCHIVING │ +│ PHASE │ │ PHASE │ │ PHASE │ +└──────────────┘ └──────────────┘ └──────────────┘ + +If you're in implementation and realize the design is wrong? +Too bad. Phase gates don't let you go back easily. +``` + +OPSX 使用操作（actions）而非阶段（phases）： + +``` + ┌───────────────────────────────────────────────┐ + │ ACTIONS (not phases) │ + │ │ + │ new ◄──► continue ◄──► apply ◄──► archive │ + │ │ │ │ │ │ + │ └──────────┴───────────┴─────────────┘ │ + │ any order │ + └───────────────────────────────────────────────┘ +``` + +### 依赖图 + +制品形成一个有向图。依赖关系是使能器，而非门控： + +``` + proposal + (root node) + │ + ┌─────────────┴─────────────┐ + │ │ + ▼ ▼ + specs design + (requires: (requires: + proposal) proposal) + │ │ + └─────────────┬─────────────┘ + │ + ▼ + tasks + (requires: + specs, design) +``` + +当你运行 `/opsx:continue` 时，它会检查哪些已准备好，并提供下一个可创建的制品。你也可以以任意顺序创建多个已准备好的制品。 + +### Skills 与 Commands + +旧版系统使用工具特定的命令文件： + +``` +.claude/commands/openspec/ +├── proposal.md +├── apply.md +└── archive.md +``` + +OPSX 使用新兴的 **skills** 标准： + +``` +.claude/skills/ +├── openspec-explore/SKILL.md +├── openspec-new-change/SKILL.md +├── openspec-continue-change/SKILL.md +├── openspec-apply-change/SKILL.md +└── ... +``` + +Skills 被多种 AI 编程工具识别，并提供更丰富的元数据。 + +--- + +## 继续现有变更 + +你正在进行的变更可以无缝地与 OPSX 命令配合使用。 + +**有来自旧版工作流的活跃变更？** + +``` +/opsx:apply add-my-feature +``` + +OPSX 会读取现有制品，从你中断的地方继续。 + +**想要为现有变更添加更多制品？** + +``` +/opsx:continue add-my-feature +``` + +根据已有内容显示可以创建的下一步制品。 + +**需要查看状态？** + +```bash +openspec status --change add-my-feature +``` + +--- + +## 新的配置系统 + +### config.yaml 结构 + +```yaml +# 必需：新变更的默认 schema +schema: spec-driven + +# 可选：项目上下文（最大 50KB） +# 会被注入到所有制品指令中 +context: | + Your project background, tech stack, + conventions, and constraints. + +# 可选：按制品划分的规则 +# 仅注入到匹配的制品中 +rules: + proposal: + - Include rollback plan + specs: + - Use Given/When/Then format + design: + - Document fallback strategies + tasks: + - Break into 2-hour maximum chunks +``` + +### Schema 解析 + +确定使用哪个 schema 时，OPSX 按以下顺序检查： + +1. **CLI 标志**：`--schema `（最高优先级） +2. **变更元数据**：变更目录中的 `.openspec.yaml` +3. **项目配置**：`openspec/config.yaml` +4. **默认值**：`spec-driven` + +### 可用 Schema + +| Schema | 制品 | 最适合 | +|--------|------|--------| +| `spec-driven` | proposal → specs → design → tasks | 大多数项目 | + +列出所有可用 schema： + +```bash +openspec schemas +``` + +### 自定义 Schema + +创建你自己的工作流： + +```bash +openspec schema init my-workflow +``` + +或 fork 现有 schema： + +```bash +openspec schema fork spec-driven my-workflow +``` + +详情参见 [定制化](customization.md)。 + +--- + +## 故障排除 + +### "在非交互模式下检测到旧版文件" + +你在 CI 或非交互环境中运行。使用： + +```bash +openspec init --force +``` + +### 迁移后命令未出现 + +重启你的 IDE。Skills 在启动时被检测。 + +### "rules 中出现未知的制品 ID" + +检查你的 `rules:` 键是否与 schema 的制品 ID 匹配： + +- **spec-driven**：`proposal`、`specs`、`design`、`tasks` + +运行以下命令查看有效的制品 ID： + +```bash +openspec schemas --json +``` + +### 配置未生效 + +1. 确保文件位于 `openspec/config.yaml`（不是 `.yml`） +2. 验证 YAML 语法 +3. 配置更改立即生效——无需重启 + +### project.md 未迁移 + +系统有意保留 `project.md`，因为它可能包含你的自定义内容。请手动查看它，将有用的部分移到 `config.yaml`，然后删除它。 + +### 想看看哪些内容会被清理？ + +运行 init 并拒绝清理提示——你会看到完整的检测摘要，而不会进行任何更改。 + +--- + +## 快速参考 + +### 迁移后的文件 + +``` +project/ +├── openspec/ +│ ├── specs/ # 不变 +│ ├── changes/ # 不变 +│ │ └── archive/ # 不变 +│ └── config.yaml # 新增：项目配置 +├── .claude/ +│ └── skills/ # 新增：OPSX skills +│ ├── openspec-propose/ # 默认 core profile +│ ├── openspec-explore/ +│ ├── openspec-apply-change/ +│ └── ... # 扩展 profile 添加 new/continue/ff 等 +├── CLAUDE.md # OpenSpec 标记已移除，你的内容已保留 +└── AGENTS.md # OpenSpec 标记已移除，你的内容已保留 +``` + +### 已移除的内容 + +- `.claude/commands/openspec/` —— 已被 `.claude/skills/` 取代 +- `openspec/AGENTS.md` —— 已过时 +- `openspec/project.md` —— 迁移到 `config.yaml`，然后删除 +- `CLAUDE.md`、`AGENTS.md` 等中的 OpenSpec 标记块 + +### 命令速查表 + +```text +/opsx:propose 快速开始（默认 core profile） +/opsx:apply 实施任务 +/opsx:archive 完成并归档 + +# 扩展工作流（如已启用）： +/opsx:new 搭建变更框架 +/opsx:continue 创建下一个制品 +/opsx:ff 一次性创建规划制品 +``` + +--- + +## 获取帮助 + +- **Discord**: [discord.gg/YctCnvvshC](https://discord.gg/YctCnvvshC) +- **GitHub Issues**: [github.com/Fission-AI/OpenSpec/issues](https://github.com/Fission-AI/OpenSpec/issues) +- **文档**: [opsx.md](opsx.md) 获取完整的 OPSX 参考 diff --git a/docs/i18n/zh-cn/multi-language.md b/docs/i18n/zh-cn/multi-language.md new file mode 100644 index 000000000..78ebeb3de --- /dev/null +++ b/docs/i18n/zh-cn/multi-language.md @@ -0,0 +1,117 @@ +> **声明**：本文档由 AI 翻译，使用 `mimo-v2-pro` 进行翻译。 + +# 多语言指南 + +配置 OpenSpec 以生成英文以外语言的产物。 + +## 快速配置 + +在你的 `openspec/config.yaml` 中添加语言指令： + +```yaml +schema: spec-driven + +context: | + Language: Portuguese (pt-BR) + All artifacts must be written in Brazilian Portuguese. + + # Your other project context below... + Tech stack: TypeScript, React, Node.js +``` + +就这样，所有生成的产物现在将使用葡萄牙语。 + +## 语言示例 + +### 葡萄牙语（巴西） + +```yaml +context: | + Language: Portuguese (pt-BR) + All artifacts must be written in Brazilian Portuguese. +``` + +### 西班牙语 + +```yaml +context: | + Idioma: Español + Todos los artefactos deben escribirse en español. +``` + +### 中文（简体） + +```yaml +context: | + 语言：中文（简体） + 所有产出物必须用简体中文撰写。 +``` + +### 日语 + +```yaml +context: | + 言語：日本語 + すべての成果物は日本語で作成してください。 +``` + +### 法语 + +```yaml +context: | + Langue : Français + Tous les artefacts doivent être rédigés en français. +``` + +### 德语 + +```yaml +context: | + Sprache: Deutsch + Alle Artefakte müssen auf Deutsch verfasst werden. +``` + +## 技巧 + +### 处理技术术语 + +决定如何处理技术术语： + +```yaml +context: | + Language: Japanese + Write in Japanese, but: + - Keep technical terms like "API", "REST", "GraphQL" in English + - Code examples and file paths remain in English +``` + +### 与其他上下文结合 + +语言设置可以与你的其他项目上下文一起使用： + +```yaml +schema: spec-driven + +context: | + Language: Portuguese (pt-BR) + All artifacts must be written in Brazilian Portuguese. + + Tech stack: TypeScript, React 18, Node.js 20 + Database: PostgreSQL with Prisma ORM +``` + +## 验证 + +验证你的语言配置是否生效： + +```bash +# Check the instructions - should show your language context +openspec instructions proposal --change my-change + +# Output will include your language context +``` + +## 相关文档 + +- [自定义指南](./customization.md) - 项目配置选项 +- [工作流指南](./workflows.md) - 完整的工作流文档 diff --git a/docs/i18n/zh-cn/opsx.md b/docs/i18n/zh-cn/opsx.md new file mode 100644 index 000000000..021d3e5e7 --- /dev/null +++ b/docs/i18n/zh-cn/opsx.md @@ -0,0 +1,660 @@ +> **声明**：本文档由 AI 翻译，使用 `mimo-v2-pro` 进行翻译。 + +# OPSX 工作流 + +> 欢迎在 [Discord](https://discord.gg/YctCnvvshC) 提供反馈。 + +## 这是什么？ + +OPSX 现在是 OpenSpec 的标准工作流。 + +这是一种用于 OpenSpec 变更的**流畅、迭代工作流**。不再有僵化的阶段——只有你可以随时执行的操作。 + +## 为什么存在这个？ + +旧版 OpenSpec 工作流可以工作，但它被**锁定了**： + +- **指令是硬编码的** —— 埋在 TypeScript 里，你无法更改 +- **全有或全无** —— 一个大命令创建所有东西，无法单独测试各个部分 +- **固定结构** —— 每个人都是相同的工作流，无法自定义 +- **黑盒** —— 当 AI 输出不好时，你无法调整提示词 + +**OPSX 打开了它。** 现在任何人都可以： + +1. **实验指令** —— 编辑模板，看看 AI 是否表现更好 +2. **细粒度测试** —— 独立验证每个制品的指令 +3. **自定义工作流** —— 定义你自己的制品和依赖关系 +4. **快速迭代** —— 更改模板，立即测试，无需重新构建 + +``` +旧版工作流： OPSX： +┌────────────────────────┐ ┌────────────────────────┐ +│ 硬编码在包中 │ │ schema.yaml │◄── 你编辑这个 +│ （无法更改） │ │ templates/*.md │◄── 或这个 +│ ↓ │ │ ↓ │ +│ 等待新版本发布 │ │ 立即生效 │ +│ ↓ │ │ ↓ │ +│ 希望它更好 │ │ 自己测试 │ +└────────────────────────┘ └────────────────────────┘ +``` + +**这是为所有人设计的：** +- **团队** —— 创建符合你实际工作方式的工作流 +- **高级用户** —— 调整提示词以获得更好的 AI 输出 +- **OpenSpec 贡献者** —— 无需发布即可尝试新方法 + +我们都在一起学习什么最有效。OPSX 让我们一起学习。 + +## 用户体验 + +**线性工作流的问题：** +你"在规划阶段"，然后"在实现阶段"，然后"完成"。但实际工作不是这样的。你实现了一些东西，发现设计有问题，需要更新规范，继续实现。线性阶段与实际工作方式相冲突。 + +**OPSX 方法：** +- **操作而非阶段** —— 创建、实现、更新、归档 —— 随时执行任意操作 +- **依赖关系是使能器** —— 它们展示什么是可能的，而不是接下来需要什么 + +``` + proposal ──→ specs ──→ design ──→ tasks ──→ implement +``` + +## 设置 + +```bash +# 确保已安装 openspec —— skills 会自动生成 +openspec init +``` + +这会在 `.claude/skills/`（或等效目录）中创建 AI 编程助手自动检测的 skills。 + +默认情况下，OpenSpec 使用 `core` 工作流配置文件（`propose`、`explore`、`apply`、`archive`）。如果你需要扩展的工作流命令（`new`、`continue`、`ff`、`verify`、`sync`、`bulk-archive`、`onboard`），请使用 `openspec config profile` 进行配置，然后使用 `openspec update` 应用。 + +在设置过程中，系统会提示你创建**项目配置**（`openspec/config.yaml`）。这是可选的，但推荐使用。 + +## 项目配置 + +项目配置允许你设置默认值，并将项目特定的上下文注入到所有制品中。 + +### 创建配置 + +配置在 `openspec init` 期间创建，或手动创建： + +```yaml +# openspec/config.yaml +schema: spec-driven + +context: | + 技术栈：TypeScript, React, Node.js + API 规范：RESTful, JSON 响应 + 测试：Vitest 用于单元测试，Playwright 用于 e2e + 风格：ESLint + Prettier，严格 TypeScript + +rules: + proposal: + - 包含回滚计划 + - 标识受影响的团队 + specs: + - 场景使用 Given/When/Then 格式 + design: + - 复杂流程包含序列图 +``` + +### 配置字段 + +| 字段 | 类型 | 描述 | +|------|------|------| +| `schema` | string | 新变更的默认 schema（例如 `spec-driven`） | +| `context` | string | 注入到所有制品指令中的项目上下文 | +| `rules` | object | 按制品 ID 键控的每个制品规则 | + +### 工作原理 + +**Schema 优先级**（从高到低）： +1. CLI 标志（`--schema `） +2. 变更元数据（变更目录中的 `.openspec.yaml`） +3. 项目配置（`openspec/config.yaml`） +4. 默认值（`spec-driven`） + +**上下文注入：** +- 上下文被添加到每个制品指令的开头 +- 包裹在 `...` 标签中 +- 帮助 AI 理解你项目的规范 + +**规则注入：** +- 规则仅注入到匹配的制品中 +- 包裹在 `...` 标签中 +- 出现在上下文之后、模板之前 + +### 按 Schema 的制品 ID + +**spec-driven**（默认）： +- `proposal` —— 变更提案 +- `specs` —— 规范 +- `design` —— 技术设计 +- `tasks` —— 实现任务 + +### 配置验证 + +- `rules` 中未知的制品 ID 会生成警告 +- Schema 名称会根据可用 schema 进行验证 +- 上下文有 50KB 大小限制 +- 无效的 YAML 会报告行号 + +### 故障排除 + +**"rules 中有未知的制品 ID：X"** +- 检查制品 ID 是否与你的 schema 匹配（参见上面的列表） +- 运行 `openspec schemas --json` 查看每个 schema 的制品 ID + +**配置未被应用：** +- 确保文件位于 `openspec/config.yaml`（不是 `.yml`） +- 使用验证器检查 YAML 语法 +- 配置更改立即生效（无需重启） + +**上下文过大：** +- 上下文限制为 50KB +- 请改为总结或链接到外部文档 + +## 命令 + +| 命令 | 功能 | +|------|------| +| `/opsx:propose` | 一步创建变更并生成规划制品（默认快速路径） | +| `/opsx:explore` | 思考想法、调查问题、澄清需求 | +| `/opsx:new` | 开始一个新的变更脚手架（扩展工作流） | +| `/opsx:continue` | 创建下一个制品（扩展工作流） | +| `/opsx:ff` | 快速前进规划制品（扩展工作流） | +| `/opsx:apply` | 实现任务，根据需要更新制品 | +| `/opsx:verify` | 根据制品验证实现（扩展工作流） | +| `/opsx:sync` | 同步 delta 规范到主规范（扩展工作流，可选） | +| `/opsx:archive` | 完成时归档 | +| `/opsx:bulk-archive` | 归档多个已完成的变更（扩展工作流） | +| `/opsx:onboard` | 端到端变更的引导式演练（扩展工作流） | + +## 使用方法 + +### 探索想法 +``` +/opsx:explore +``` +思考想法、调查问题、比较选项。无需结构化——只是一个思考伙伴。当想法成熟时，过渡到 `/opsx:propose`（默认）或 `/opsx:new`/`/opsx:ff`（扩展）。 + +### 开始新变更 +``` +/opsx:propose +``` +创建变更并生成实现前需要的规划制品。 + +如果你启用了扩展工作流，可以改为使用： + +```text +/opsx:new # 仅创建脚手架 +/opsx:continue # 一次创建一个制品 +/opsx:ff # 一次创建所有规划制品 +``` + +### 创建制品 +``` +/opsx:continue +``` +根据依赖关系显示可创建的内容，然后创建一个制品。重复使用以逐步构建你的变更。 + +``` +/opsx:ff add-dark-mode +``` +一次创建所有规划制品。当你清楚要构建什么时使用。 + +### 实现（流畅部分） +``` +/opsx:apply +``` +处理任务，逐一完成。如果你在处理多个变更，可以运行 `/opsx:apply `；否则它会从对话中推断，如果无法判断会提示你选择。 + +### 完成 +``` +/opsx:archive # 完成时移动到归档（如需要会提示同步规范） +``` + +## 何时更新 vs. 全新开始 + +你始终可以在实现前编辑你的提案或规范。但什么时候细化变成了"这是不同的工作"？ + +### 提案捕获什么 + +提案定义三件事： +1. **意图** —— 你要解决什么问题？ +2. **范围** —— 什么是范围内/范围外？ +3. **方法** —— 你将如何解决？ + +问题是：哪个改变了，改变了多少？ + +### 更新现有变更的情形： + +**相同意图，细化执行** +- 你发现了未考虑的边界情况 +- 方法需要调整但目标不变 +- 实现发现设计略有偏差 + +**范围缩小** +- 你意识到完整范围太大，想先发布 MVP +- "添加深色模式" → "添加深色模式切换（v2 中添加系统偏好）" + +**学习驱动的修正** +- 代码库结构与你想象的不同 +- 依赖项工作方式不符合预期 +- "使用 CSS 变量" → "改为使用 Tailwind 的 dark: 前缀" + +### 开始新变更的情形： + +**意图根本改变** +- 问题本身现在不同了 +- "添加深色模式" → "添加包含自定义颜色、字体、间距的完整主题系统" + +**范围爆炸** +- 变更增长如此之大，本质上是不同的工作 +- 更新后原始提案面目全非 +- "修复登录 bug" → "重写认证系统" + +**原始变更可完成** +- 原始变更可以标记为"完成" +- 新工作独立存在，不是细化 +- 完成"添加深色模式 MVP" → 归档 → 新变更"增强深色模式" + +### 启发式规则 + +``` + ┌─────────────────────────────────────┐ + │ 这是同一项工作吗？ │ + └──────────────┬──────────────────────┘ + │ + ┌──────────────────┼──────────────────┐ + │ │ │ + ▼ ▼ ▼ + 相同意图？ >50% 重叠？ 原始变更能否 + 相同问题？ 相同范围？ 不需要这些 + │ │ 更改就"完成"？ + │ │ │ + ┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐ + │ │ │ │ │ │ + 是 否 是 否 否 是 + │ │ │ │ │ │ + ▼ ▼ ▼ ▼ ▼ ▼ + 更新 新建 更新 新建 更新 新建 +``` + +| 测试 | 更新 | 新变更 | +|------|------|--------| +| **身份** | "同一事物，细化" | "不同的工作" | +| **范围重叠** | >50% 重叠 | <50% 重叠 | +| **完成性** | 没有这些更改无法"完成" | 可以完成原始变更，新工作独立存在 | +| **故事** | 更新链条讲述连贯的故事 | 补丁会比澄清更令人困惑 | + +### 原则 + +> **更新保留上下文。新变更提供清晰度。** +> +> 当你的思考历史有价值时选择更新。 +> 当从头开始比修补更清晰时选择新变更。 + +把它想象成 git 分支： +- 在处理同一功能时持续提交 +- 当是真正的新工作时开始新分支 +- 有时合并部分功能，为阶段 2 重新开始 + +## 有什么不同？ + +| | 旧版（`/openspec:proposal`） | OPSX（`/opsx:*`） | +|---|---|---| +| **结构** | 一个大的提案文档 | 具有依赖关系的离散制品 | +| **工作流** | 线性阶段：规划 → 实现 → 归档 | 流畅操作 —— 随时做任何事 | +| **迭代** | 回退很尴尬 | 边学习边更新制品 | +| **自定义** | 固定结构 | Schema 驱动（定义你自己的制品） | + +**关键洞察：** 工作不是线性的。OPSX 不再假装它是。 + +## 架构深入分析 + +本节解释 OPSX 在底层如何工作，以及它与旧版工作流的比较。 +本节中的示例使用扩展命令集（`new`、`continue` 等）；默认 `core` 用户可以将相同的流程映射到 `propose → apply → archive`。 + +### 理念：阶段 vs 操作 + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 旧版工作流 │ +│ （阶段锁定，全有或全无） │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ 规划阶段 │ ───► │ 实现阶段 │ ───► │ 归档阶段 │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ │ │ │ +│ ▼ ▼ ▼ │ +│ /openspec:proposal /openspec:apply /openspec:archive │ +│ │ +│ • 一次创建所有制品 │ +│ • 实现期间无法返回更新规范 │ +│ • 阶段门强制线性进展 │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ + + +┌─────────────────────────────────────────────────────────────────────────────┐ +│ OPSX 工作流 │ +│ （流畅操作，迭代式） │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌────────────────────────────────────────────┐ │ +│ │ 操作（而非阶段） │ │ +│ │ │ │ +│ │ new ◄──► continue ◄──► apply ◄──► archive │ │ +│ │ │ │ │ │ │ │ +│ │ └──────────┴───────────┴───────────┘ │ │ +│ │ 任意顺序 │ │ +│ └────────────────────────────────────────────┘ │ +│ │ +│ • 一次创建一个制品或快速前进 │ +│ • 实现期间更新规范/设计/任务 │ +│ • 依赖关系启用进展，阶段不存在 │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +### 组件架构 + +**旧版工作流**使用 TypeScript 中的硬编码模板： + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 旧版工作流组件 │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ 硬编码模板（TypeScript 字符串） │ +│ │ │ +│ ▼ │ +│ 工具特定的配置器/适配器 │ +│ │ │ +│ ▼ │ +│ 生成的命令文件（.claude/commands/openspec/*.md） │ +│ │ +│ • 固定结构，无制品感知 │ +│ • 更改需要代码修改 + 重新构建 │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +**OPSX** 使用外部 schema 和依赖图引擎： + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ OPSX 组件 │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Schema 定义（YAML） │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ name: spec-driven │ │ +│ │ artifacts: │ │ +│ │ - id: proposal │ │ +│ │ generates: proposal.md │ │ +│ │ requires: [] ◄── 依赖关系 │ │ +│ │ - id: specs │ │ +│ │ generates: specs/**/*.md ◄── Glob 模式 │ │ +│ │ requires: [proposal] ◄── proposal 后启用 │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ 制品图引擎 │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ • 拓扑排序（依赖排序） │ │ +│ │ • 状态检测（文件系统存在性） │ │ +│ │ • 丰富指令生成（模板 + 上下文） │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ Skill 文件（.claude/skills/openspec-*/SKILL.md） │ +│ │ +│ • 跨编辑器兼容（Claude Code、Cursor、Windsurf） │ +│ • Skills 查询 CLI 获取结构化数据 │ +│ • 通过 schema 文件完全可自定义 │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +### 依赖图模型 + +制品形成有向无环图（DAG）。依赖关系是**使能器**，而非门： + +``` + proposal + （根节点） + │ + ┌─────────────┴─────────────┐ + │ │ + ▼ ▼ + specs design + （requires: （requires: + proposal) proposal) + │ │ + └─────────────┬─────────────┘ + │ + ▼ + tasks + （requires: + specs, design) + │ + ▼ + ┌──────────────┐ + │ APPLY 阶段 │ + │ （requires: │ + │ tasks) │ + └──────────────┘ +``` + +**状态转换：** + +``` + 受阻 ────────────────► 就绪 ────────────────► 完成 + │ │ │ + 缺失依赖 所有依赖 文件存在于 + 已完成 文件系统 +``` + +### 信息流 + +**旧版工作流** —— 代理接收静态指令： + +``` + 用户："/openspec:proposal" + │ + ▼ + ┌─────────────────────────────────────────┐ + │ 静态指令： │ + │ • 创建 proposal.md │ + │ • 创建 tasks.md │ + │ • 创建 design.md │ + │ • 创建 specs//spec.md │ + │ │ + │ 不知道什么已存在或 │ + │ 制品之间的依赖关系 │ + └─────────────────────────────────────────┘ + │ + ▼ + 代理一次性创建所有制品 +``` + +**OPSX** —— 代理查询获取丰富上下文： + +``` + 用户："/opsx:continue" + │ + ▼ + ┌──────────────────────────────────────────────────────────────────────────┐ + │ 步骤 1：查询当前状态 │ + │ ┌────────────────────────────────────────────────────────────────────┐ │ + │ │ $ openspec status --change "add-auth" --json │ │ + │ │ │ │ + │ │ { │ │ + │ │ "artifacts": [ │ │ + │ │ {"id": "proposal", "status": "done"}, │ │ + │ │ {"id": "specs", "status": "ready"}, ◄── 第一个就绪的 │ │ + │ │ {"id": "design", "status": "ready"}, │ │ + │ │ {"id": "tasks", "status": "blocked", "missingDeps": ["specs"]}│ │ + │ │ ] │ │ + │ │ } │ │ + │ └────────────────────────────────────────────────────────────────────┘ │ + │ │ + │ 步骤 2：获取就绪制品的丰富指令 │ + │ ┌────────────────────────────────────────────────────────────────────┐ │ + │ │ $ openspec instructions specs --change "add-auth" --json │ │ + │ │ │ │ + │ │ { │ │ + │ │ "template": "# Specification\n\n## ADDED Requirements...", │ │ + │ │ "dependencies": [{"id": "proposal", "path": "...", "done": true}│ │ + │ │ "unlocks": ["tasks"] │ │ + │ │ } │ │ + │ └────────────────────────────────────────────────────────────────────┘ │ + │ │ + │ 步骤 3：读取依赖 → 创建一个制品 → 显示解锁的内容 │ + └──────────────────────────────────────────────────────────────────────────┘ +``` + +### 迭代模型 + +**旧版工作流** —— 迭代很尴尬： + +``` + ┌─────────┐ ┌─────────┐ ┌─────────┐ + │/proposal│ ──► │ /apply │ ──► │/archive │ + └─────────┘ └─────────┘ └─────────┘ + │ │ + │ ├── "等等，设计有问题" + │ │ + │ ├── 选项： + │ │ • 手动编辑文件（破坏上下文） + │ │ • 放弃并重新开始 + │ │ • 强行推进，稍后修复 + │ │ + │ └── 没有官方"返回"机制 + │ + └── 一次创建所有制品 +``` + +**OPSX** —— 自然迭代： + +``` + /opsx:new ───► /opsx:continue ───► /opsx:apply ───► /opsx:archive + │ │ │ + │ │ ├── "设计有问题" + │ │ │ + │ │ ▼ + │ │ 直接编辑 design.md + │ │ 然后继续！ + │ │ │ + │ │ ▼ + │ │ /opsx:apply 从你 + │ │ 离开的地方继续 + │ │ + │ └── 创建一个制品，显示解锁的内容 + │ + └── 创建变更脚手架，等待指示 +``` + +### 自定义 Schema + +使用 schema 管理命令创建自定义工作流： + +```bash +# 从头创建新 schema（交互式） +openspec schema init my-workflow + +# 或者 fork 现有 schema 作为起点 +openspec schema fork spec-driven my-workflow + +# 验证你的 schema 结构 +openspec schema validate my-workflow + +# 查看 schema 的解析来源（调试时有用） +openspec schema which my-workflow +``` + +Schema 存储在 `openspec/schemas/`（项目本地，版本控制）或 `~/.local/share/openspec/schemas/`（用户全局）。 + +**Schema 结构：** +``` +openspec/schemas/research-first/ +├── schema.yaml +└── templates/ + ├── research.md + ├── proposal.md + └── tasks.md +``` + +**示例 schema.yaml：** +```yaml +name: research-first +artifacts: + - id: research # 在 proposal 之前添加 + generates: research.md + requires: [] + + - id: proposal + generates: proposal.md + requires: [research] # 现在依赖 research + + - id: tasks + generates: tasks.md + requires: [proposal] +``` + +**依赖图：** +``` + research ──► proposal ──► tasks +``` + +### 总结 + +| 方面 | 旧版 | OPSX | +|------|------|------| +| **模板** | 硬编码 TypeScript | 外部 YAML + Markdown | +| **依赖关系** | 无（一次全部创建） | 具有拓扑排序的 DAG | +| **状态** | 基于阶段的心智模型 | 文件系统存在性 | +| **自定义** | 编辑源码，重新构建 | 创建 schema.yaml | +| **迭代** | 阶段锁定 | 流畅，可编辑任何内容 | +| **编辑器支持** | 工具特定的配置器/适配器 | 单一 skills 目录 | + +## Schema + +Schema 定义了存在的制品及其依赖关系。当前可用： + +- **spec-driven**（默认）：proposal → specs → design → tasks + +```bash +# 列出可用 schema +openspec schemas + +# 查看所有 schema 及其解析来源 +openspec schema which --all + +# 交互式创建新 schema +openspec schema init my-workflow + +# Fork 现有 schema 进行自定义 +openspec schema fork spec-driven my-workflow + +# 使用前验证 schema 结构 +openspec schema validate my-workflow +``` + +## 技巧 + +- 使用 `/opsx:explore` 在承诺变更前思考想法 +- 当你知道想要什么时使用 `/opsx:ff`，探索时使用 `/opsx:continue` +- 在 `/opsx:apply` 期间，如果发现问题——修复制品，然后继续 +- 任务通过 `tasks.md` 中的复选框跟踪进度 +- 随时检查状态：`openspec status --change "name"` + +## 反馈 + +这还很粗糙。这是故意的——我们正在学习什么最有效。 + +发现了 bug？有想法？加入我们的 [Discord](https://discord.gg/YctCnvvshC) 或在 [GitHub](https://github.com/Fission-AI/openspec/issues) 上提交 issue。 diff --git a/docs/i18n/zh-cn/supported-tools.md b/docs/i18n/zh-cn/supported-tools.md new file mode 100644 index 000000000..19519de0e --- /dev/null +++ b/docs/i18n/zh-cn/supported-tools.md @@ -0,0 +1,107 @@ +> **声明**：本文档由 AI 翻译，使用 `mimo-v2-pro` 进行翻译。 + +# 支持的工具 + +OpenSpec 与许多 AI 编码助手配合使用。当你运行 `openspec init` 时，OpenSpec 使用你当前的活动配置/工作流选择和交付模式来配置选定的工具。 + +## 工作原理 + +对于每个选定的工具，OpenSpec 可以安装： + +1. **技能**（如果交付包含技能）：`.../skills/openspec-*/SKILL.md` +2. **命令**（如果交付包含命令）：特定于工具的 `opsx-*` 命令文件 + +默认情况下，OpenSpec 使用 `core` 配置，包括： +- `propose` +- `explore` +- `apply` +- `archive` + +你可以通过 `openspec config profile` 启用扩展工作流（`new`、`continue`、`ff`、`verify`、`sync`、`bulk-archive`、`onboard`），然后运行 `openspec update`。 + +## 工具目录参考 + +| 工具 (ID) | 技能路径模式 | 命令路径模式 | +|-----------|---------------------|----------------------| +| Amazon Q Developer (`amazon-q`) | `.amazonq/skills/openspec-*/SKILL.md` | `.amazonq/prompts/opsx-.md` | +| Antigravity (`antigravity`) | `.agent/skills/openspec-*/SKILL.md` | `.agent/workflows/opsx-.md` | +| Auggie (`auggie`) | `.augment/skills/openspec-*/SKILL.md` | `.augment/commands/opsx-.md` | +| Claude Code (`claude`) | `.claude/skills/openspec-*/SKILL.md` | `.claude/commands/opsx/.md` | +| Cline (`cline`) | `.cline/skills/openspec-*/SKILL.md` | `.clinerules/workflows/opsx-.md` | +| CodeBuddy (`codebuddy`) | `.codebuddy/skills/openspec-*/SKILL.md` | `.codebuddy/commands/opsx/.md` | +| Codex (`codex`) | `.codex/skills/openspec-*/SKILL.md` | `$CODEX_HOME/prompts/opsx-.md`\* | +| Continue (`continue`) | `.continue/skills/openspec-*/SKILL.md` | `.continue/prompts/opsx-.prompt` | +| CoStrict (`costrict`) | `.cospec/skills/openspec-*/SKILL.md` | `.cospec/openspec/commands/opsx-.md` | +| Crush (`crush`) | `.crush/skills/openspec-*/SKILL.md` | `.crush/commands/opsx/.md` | +| Cursor (`cursor`) | `.cursor/skills/openspec-*/SKILL.md` | `.cursor/commands/opsx-.md` | +| Factory Droid (`factory`) | `.factory/skills/openspec-*/SKILL.md` | `.factory/commands/opsx-.md` | +| Gemini CLI (`gemini`) | `.gemini/skills/openspec-*/SKILL.md` | `.gemini/commands/opsx/.toml` | +| GitHub Copilot (`github-copilot`) | `.github/skills/openspec-*/SKILL.md` | `.github/prompts/opsx-.prompt.md`\*\* | +| iFlow (`iflow`) | `.iflow/skills/openspec-*/SKILL.md` | `.iflow/commands/opsx-.md` | +| Kilo Code (`kilocode`) | `.kilocode/skills/openspec-*/SKILL.md` | `.kilocode/workflows/opsx-.md` | +| Kiro (`kiro`) | `.kiro/skills/openspec-*/SKILL.md` | `.kiro/prompts/opsx-.prompt.md` | +| OpenCode (`opencode`) | `.opencode/skills/openspec-*/SKILL.md` | `.opencode/commands/opsx-.md` | +| Pi (`pi`) | `.pi/skills/openspec-*/SKILL.md` | `.pi/prompts/opsx-.md` | +| Qoder (`qoder`) | `.qoder/skills/openspec-*/SKILL.md` | `.qoder/commands/opsx/.md` | +| Qwen Code (`qwen`) | `.qwen/skills/openspec-*/SKILL.md` | `.qwen/commands/opsx-.toml` | +| RooCode (`roocode`) | `.roo/skills/openspec-*/SKILL.md` | `.roo/commands/opsx-.md` | +| Trae (`trae`) | `.trae/skills/openspec-*/SKILL.md` | 不生成（无命令适配器；使用基于技能的 `/openspec-*` 调用） | +| Windsurf (`windsurf`) | `.windsurf/skills/openspec-*/SKILL.md` | `.windsurf/workflows/opsx-.md` | + +\* Codex 命令安装在全局 Codex 主目录（`$CODEX_HOME/prompts/`，如果设置的话，否则为 `~/.codex/prompts/`），而不是你的项目目录。 + +\*\* GitHub Copilot 提示文件在 IDE 扩展（VS Code、JetBrains、Visual Studio）中作为自定义斜杠命令被识别。Copilot CLI 目前不直接使用 `.github/prompts/*.prompt.md`。 + +## 非交互式设置 + +对于 CI/CD 或脚本化设置，请使用 `--tools`（和可选的 `--profile`）： + +```bash +# 配置特定工具 +openspec init --tools claude,cursor + +# 配置所有支持的工具 +openspec init --tools all + +# 跳过工具配置 +openspec init --tools none + +# 覆盖此次初始化的配置 +openspec init --profile core +``` + +**可用的工具 ID（`--tools`）：** `amazon-q`、`antigravity`、`auggie`、`claude`、`cline`、`codex`、`codebuddy`、`continue`、`costrict`、`crush`、`cursor`、`factory`、`gemini`、`github-copilot`、`iflow`、`kilocode`、`kiro`、`opencode`、`pi`、`qoder`、`qwen`、`roocode`、`trae`、`windsurf` + +## 依赖于工作流的安装 + +OpenSpec 根据选定的工作流安装工作流产物： + +- **核心配置（默认）：** `propose`、`explore`、`apply`、`archive` +- **自定义选择：** 任意所有工作流 ID 的子集： + `propose`、`explore`、`new`、`continue`、`apply`、`ff`、`sync`、`archive`、`bulk-archive`、`verify`、`onboard` + +换句话说，技能/命令的数量取决于配置和交付方式，而不是固定的。 + +## 生成的技能名称 + +当通过配置/工作流选择时，OpenSpec 生成以下技能： + +- `openspec-propose` +- `openspec-explore` +- `openspec-new-change` +- `openspec-continue-change` +- `openspec-apply-change` +- `openspec-ff-change` +- `openspec-sync-specs` +- `openspec-archive-change` +- `openspec-bulk-archive-change` +- `openspec-verify-change` +- `openspec-onboard` + +关于命令行为，请参阅 [Commands](commands.md)；关于 `init`/`update` 选项，请参阅 [CLI](cli.md)。 + +## 相关 + +- [CLI 参考](cli.md) — 终端命令 +- [Commands](commands.md) — 斜杠命令和技能 +- [入门指南](getting-started.md) — 首次设置 \ No newline at end of file diff --git a/docs/i18n/zh-cn/workflows.md b/docs/i18n/zh-cn/workflows.md new file mode 100644 index 000000000..35f4a2723 --- /dev/null +++ b/docs/i18n/zh-cn/workflows.md @@ -0,0 +1,451 @@ +> **声明**：本文档由 AI 翻译，使用 `mimo-v2-pro` 进行翻译。 + +# 工作流 + +本指南涵盖了 OpenSpec 的常见工作流模式以及每种模式的使用场景。基础设置请参阅[快速开始](getting-started.md)。命令参考请参阅[命令](commands.md)。 + +## 理念：操作，而非阶段 + +传统工作流强制你经历各个阶段：规划，然后实现，然后完成。但实际工作并不适合整齐地装进框里。 + +OPSX 采用了不同的方法： + +```text +传统（阶段锁定）： + + 规划 ────────► 实现 ────────► 完成 + │ │ + │ "无法回退" │ + └────────────────────┘ + +OPSX（流动操作）： + + proposal ──► specs ──► design ──► tasks ──► implement +``` + +**核心原则：** + +- **操作，而非阶段** — 命令是你能执行的操作，而不是你被困在其中的阶段 +- **依赖关系是赋能者** — 它们展示什么是可能的，而不是接下来必须做什么 + +> **自定义：** OPSX 工作流由定义工件序列的模式驱动。详情请参阅[自定义](customization.md)。 + +## 两种模式 + +### 默认快速路径（`core` 配置） + +新安装默认使用 `core`，提供以下命令： +- `/opsx:propose` +- `/opsx:explore` +- `/opsx:apply` +- `/opsx:archive` + +典型流程： + +```text +/opsx:propose ──► /opsx:apply ──► /opsx:archive +``` + +### 扩展/完整工作流（自定义选择） + +如果你需要显式的脚手架和构建命令（`/opsx:new`、`/opsx:continue`、`/opsx:ff`、`/opsx:verify`、`/opsx:sync`、`/opsx:bulk-archive`、`/opsx:onboard`），使用以下命令启用： + +```bash +openspec config profile +openspec update +``` + +## 工作流模式（扩展模式） + +### 快速功能 + +当你清楚要构建什么，只需要执行时： + +```text +/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive +``` + +**示例对话：** + +```text +You: /opsx:new add-logout-button + +AI: 已创建 openspec/changes/add-logout-button/ + 准备创建：proposal + +You: /opsx:ff + +AI: 正在创建所有规划工件... + ✓ proposal.md + ✓ specs/ + ✓ design.md + ✓ tasks.md + 准备进行实现！ + +You: /opsx:apply + +AI: 正在处理任务... + ✓ 已添加退出按钮到页头 + ✓ 已实现会话清除 + ✓ 已添加确认对话框 + 所有任务完成！ + +You: /opsx:archive + +AI: ✓ 已合并 specs + ✓ 已归档变更 +``` + +**适用场景：** 中小型功能、Bug 修复、简单的变更。 + +### 探索式 + +当需求不明确或需要先调查时： + +```text +/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply +``` + +**示例对话：** + +```text +You: /opsx:explore + +AI: 你想要探索什么？ + +You: 我想改善页面加载性能，但不确定瓶颈在哪里。 + +AI: 让我帮你调查... + [分析打包大小，识别慢查询，审查组件渲染模式] + + 我发现了三个主要瓶颈： + 1. 大型未优化的图片 + 2. ProductList 中的同步数据获取 + 3. 上下文变更引起的重新渲染 + + 你想先处理哪个？ + +You: 我们来解决数据获取的问题。 + +You: /opsx:new optimize-product-list-fetching + +AI: 已创建变更。准备创建：proposal + +You: /opsx:continue + +AI: 正在基于我们的探索创建 proposal... + [撰写融入调查发现的 proposal] + + 准备创建：specs, design + 你想先创建哪个？ + +You: /opsx:continue + +AI: 正在创建 specs... +``` + +**适用场景：** 性能优化、调试、架构决策、需求不明确。 + +### 并行变更 + +同时处理多个变更： + +```text +变更 A: /opsx:new ──► /opsx:ff ──► /opsx:apply (进行中) + │ + 上下文切换 + │ +变更 B: /opsx:new ──► /opsx:ff ──────► /opsx:apply +``` + +**示例对话：** + +```text +You: 我在做 add-dark-mode 但被拉去修一个 bug + +You: /opsx:new fix-login-redirect + +AI: 已创建 openspec/changes/fix-login-redirect/ + +You: /opsx:ff + +AI: ✓ 已创建规划工件 + +You: /opsx:apply + +AI: 正在处理 fix-login-redirect... + [实现修复] + 所有任务完成！ + +You: /opsx:archive + +AI: ✓ 已归档 fix-login-redirect + +You: 继续做暗色模式 + +You: /opsx:apply add-dark-mode + +AI: 正在恢复 add-dark-mode... + 从任务 2.3 继续：更新 Header... +``` + +**适用场景：** 并行工作流、紧急打断、团队协作。 + +当有多个已完成的变更时，使用 `/opsx:bulk-archive`： + +```text +You: /opsx:bulk-archive + +AI: 找到 3 个已完成的变更： + - add-dark-mode（所有任务已完成） + - fix-login-redirect（所有任务已完成） + - update-footer（所有任务已完成） + + 正在检查 spec 冲突... + ⚠ add-dark-mode 和 update-footer 都涉及 specs/ui/ + + 正在检查代码库以解决冲突... + 两个变更都已实现。将按时间顺序应用。 + + 归档全部 3 个变更？ + +You: 是 + +AI: ✓ 已归档 add-dark-mode + ✓ 已归档 fix-login-redirect + ✓ 已归档 update-footer + Specs 按顺序合并：add-dark-mode → update-footer +``` + +批量归档会检测多个变更是否涉及相同的 specs，并通过检查实际实现来解决冲突。 + +### 完成变更 + +推荐的完成流程： + +```text +/opsx:apply ──► /opsx:verify ──► /opsx:archive + │ │ + 验证实现 如果需要则提示 + 同步 +``` + +#### Verify：检查你的工作 + +`/opsx:verify` 从三个维度验证实现是否符合你的工件： + +```text +You: /opsx:verify + +AI: 正在验证 add-auth... + + 完整性 + ✓ tasks.md 中所有 12 个任务已勾选 + ✓ specs 中所有需求已有对应代码 + ⚠ 场景"会话超时后未活动"未测试 + + 正确性 + ✓ 实现符合 spec 意图 + ✓ 场景中的边界情况已处理 + ✓ 错误状态符合 spec 定义 + + 一致性 + ✓ 设计决策已反映在代码结构中 + ✓ 命名规范与 design.md 一致 + ⚠ 设计提到"事件驱动"但实现使用了轮询 + + 总结 + ───────────────────────────── + 严重问题：0 + 警告：2 + 可以归档：是（有警告） + + 建议： + 1. 添加会话超时场景的测试 + 2. 考虑重构为设计中的事件驱动方式，或更新 design.md +``` + +**verify 检查的内容：** + +| 维度 | 验证内容 | +|-----------|------------------| +| 完整性 | 所有任务完成、所有需求已实现、场景已覆盖 | +| 正确性 | 实现符合 spec 意图、边界情况已处理 | +| 一致性 | 设计决策反映在代码中、模式一致 | + +Verify 不会阻止归档，但它会提示你可能需要先处理的问题。 + +#### Archive：完成变更 + +`/opsx:archive` 完成变更并将其移动到归档： + +```text +You: /opsx:archive + +AI: 正在归档 add-auth... + + 工件状态： + ✓ proposal.md 已存在 + ✓ specs/ 已存在 + ✓ design.md 已存在 + ✓ tasks.md 已存在（12/12 任务已完成） + + Delta specs：尚未同步到主分支 + → 是否立即同步？ + +You: 是 + +AI: ✓ 已同步 specs 到 openspec/specs/auth/spec.md + ✓ 已移动到 openspec/changes/archive/2025-01-24-add-auth/ + + 变更归档成功。 +``` + +Archive 会在 specs 未同步时提示。它不会阻止未完成任务的归档，但会发出警告。 + +## 何时使用什么 + +### `/opsx:ff` 与 `/opsx:continue` + +| 场景 | 使用 | +|-----------|-----| +| 需求明确，准备好构建 | `/opsx:ff` | +| 探索中，想审查每一步 | `/opsx:continue` | +| 想在创建 specs 前迭代 proposal | `/opsx:continue` | +| 时间紧迫，需要快速推进 | `/opsx:ff` | +| 复杂变更，想要控制 | `/opsx:continue` | + +**经验法则：** 如果你能预先描述完整范围，使用 `/opsx:ff`。如果你是一边做一边想，使用 `/opsx:continue`。 + +### 何时更新 vs 何时重新开始 + +一个常见问题：什么时候可以更新现有变更，什么时候应该创建新变更？ + +**更新现有变更的情况：** + +- 相同意图，细化执行 +- 范围缩小（先 MVP，其余稍后） +- 学习驱动的修正（代码库不是你预期的那样） +- 基于实现发现的设计调整 + +**创建新变更的情况：** + +- 意图根本性改变 +- 范围扩展为完全不同的工作 +- 原始变更可以单独标记为"完成" +- 补丁会造成更多混淆而非澄清 + +```text + ┌─────────────────────────────────────┐ + │ 这是同一项工作吗？ │ + └──────────────┬──────────────────────┘ + │ + ┌──────────────────┼──────────────────┐ + │ │ │ + ▼ ▼ ▼ + Same intent? >50% overlap? Can original + Same problem? Same scope? be "done" without + │ │ these changes? + │ │ │ + ┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐ + │ │ │ │ │ │ + YES NO YES NO NO YES + │ │ │ │ │ │ + ▼ ▼ ▼ ▼ ▼ ▼ + UPDATE NEW UPDATE NEW UPDATE NEW +``` + +**示例："添加暗色模式"** + +- "还需要支持自定义主题" → 新变更（范围扩展） +- "系统偏好检测比预期困难" → 更新（相同意图） +- "先发布开关功能，稍后添加偏好设置" → 更新后归档，然后创建新变更 + +## 最佳实践 + +### 保持变更聚焦 + +每个变更包含一个逻辑工作单元。如果你在做"添加功能 X 并重构 Y"，考虑拆分为两个独立变更。 + +**为什么重要：** +- 更容易审查和理解 +- 更清晰的归档历史 +- 可以独立发布 +- 需要时更容易回滚 + +### 使用 `/opsx:explore` 处理不明确的需求 + +在提交变更之前，先探索问题空间： + +```text +You: /opsx:explore + +AI: 你想要探索什么？ + +You: 我们应该如何处理 API 的速率限制？ + +AI: 让我调查一下你当前的设置和选项... + [研究代码库，考虑模式] + + 我们可以采用三种方案： + 1. 基于中间件（简单，按端点） + 2. 基于 Redis（可扩展，共享状态） + 3. 按用户的令牌桶（公平，复杂） + + 你当前的技术栈适合方案 #1 或 #2。你的规模如何？ +``` + +探索可以在你创建工件之前澄清思路。 + +### 归档前验证 + +使用 `/opsx:verify` 检查实现是否符合工件： + +```text +You: /opsx:verify + +AI: 正在验证 add-dark-mode... + + ✓ tasks.md 中所有任务已勾选 + ✓ specs 中的需求已有对应代码 + ✓ 设计决策已反映在实现中 + + 可以归档了！ +``` + +在关闭变更之前发现不匹配。 + +### 清晰命名变更 + +好的名称让 `openspec list` 更有用： + +```text +推荐: 避免: +add-dark-mode feature-1 +fix-login-redirect update +optimize-product-query changes +implement-2fa wip +``` + +## 命令快速参考 + +完整的命令详情和选项，请参阅[命令](commands.md)。 + +| 命令 | 目的 | 使用场景 | +|---------|---------|-------------| +| `/opsx:propose` | 创建变更 + 规划工件 | 快速默认路径（`core` 配置） | +| `/opsx:explore` | 探索想法 | 需求不明确、调查 | +| `/opsx:new` | 启动变更脚手架 | 扩展模式、显式工件控制 | +| `/opsx:continue` | 创建下一个工件 | 扩展模式、逐步创建工件 | +| `/opsx:ff` | 创建所有规划工件 | 扩展模式、范围明确 | +| `/opsx:apply` | 实现任务 | 准备编写代码 | +| `/opsx:verify` | 验证实现 | 扩展模式、归档前 | +| `/opsx:sync` | 合并 delta specs | 扩展模式、可选 | +| `/opsx:archive` | 完成变更 | 所有工作完成 | +| `/opsx:bulk-archive` | 归档多个变更 | 扩展模式、并行工作 | + +## 下一步 + +- [命令](commands.md) - 包含选项的完整命令参考 +- [概念](concepts.md) - 深入了解 specs、工件和模式 +- [自定义](customization.md) - 创建自定义工作流 diff --git a/openspec/changes/archive/2026-03-27-add-zh-cn-translations/.openspec.yaml b/openspec/changes/archive/2026-03-27-add-zh-cn-translations/.openspec.yaml new file mode 100644 index 000000000..a61e7c112 --- /dev/null +++ b/openspec/changes/archive/2026-03-27-add-zh-cn-translations/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-03-27 diff --git a/openspec/changes/archive/2026-03-27-add-zh-cn-translations/design.md b/openspec/changes/archive/2026-03-27-add-zh-cn-translations/design.md new file mode 100644 index 000000000..8750c95b1 --- /dev/null +++ b/openspec/changes/archive/2026-03-27-add-zh-cn-translations/design.md @@ -0,0 +1,98 @@ +## Context + +OpenSpec 的中文使用者在增长，当前所有文档（`README.md` + `docs/` 下 11 个文件）仅提供英文。需要提供中文翻译以降低中文使用者的学习门槛。 + +**当前状态**： +- 源文档位于项目根目录 `README.md` 和 `docs/` 下 +- 无任何 i18n 基础设施 +- 文档为纯 Markdown，包含代码块、链接、badge 等 + +## Goals / Non-Goals + +**Goals:** +- 将所有英文文档翻译为中文，放置到 `docs/i18n/zh-cn/` 目录 +- 保持 1:1 文件映射，便于维护 +- 翻译时保留命令名、代码、链接等技术内容原文不变 + +**Non-Goals:** +- 不构建自动化翻译工具或 i18n 框架 +- 不翻译其他语言（仅 zh-cn） +- 不修改现有英文文档内容 +- 不在 CLI 中集成语言切换功能 + +## Decisions + +### 1. 目录结构：`docs/i18n/zh-cn/` + +``` +docs/ + i18n/ + zh-cn/ + README.md ← 根 README.md 的翻译 + getting-started.md + workflows.md + commands.md + ... +``` + +**理由**：i18n 目录是社区通用约定，未来扩展其他语言只需添加 `en/`、`ja/` 等子目录。`README.md` 放在 `zh-cn/` 根下作为中文入口。 + +**备选方案**：直接放在 `docs/zh/` 下 — 缺点是与 i18n 惯例不符，且与英文文档混在一起。 + +### 2. 文件命名：与源文件同名 + +每个翻译文件与源文件同名（如 `getting-started.md` → `getting-started.md`），通过目录区分语言。 + +**理由**：简单直观，无需维护映射表。 + +### 3. 翻译规范：保留技术内容原文 + +翻译时以下内容保持原文不变： +- CLI 命令名（如 `openspec init`、`/opsx:propose`） +- 代码块及行内代码 +- 技术专有名词（如 Node.js、TypeScript、Markdown） +- badge 和 HTML 标签 + +### 4. 链接处理：中文文档内链接指向中文路径 + +中文文档中引用其他文档的相对链接，必须重写为指向 `docs/i18n/zh-cn/` 下的对应中文文件。 + +示例： +- `[Getting Started](getting-started.md)` → `[快速开始](getting-started.md)`（同目录，无需改路径） +- `[Commands](../commands.md)` 在根 README 翻译中 → `[命令](commands.md)`（指向 zh-cn 下的同级文件） +- 外部链接（GitHub、Discord 等）保持不变 + +**理由**：中文文档的读者应该在中文文档体系内导航，跳转到英文文档会造成语言割裂。 + +### 5. AI 翻译声明 + +每份中文文档开头添加一段说明，标注该文档由 AI 翻译，并注明使用的模型名称。 + +格式： +```markdown +> **声明**：本文档由 AI 翻译，使用 `model-name` 进行翻译。 +``` + +**理由**：透明告知读者翻译来源，方便读者判断翻译质量，也便于后续人工校对时定位优先级。 + +### 6. 维护方式：手动同步 + +英文文档更新后，人工同步对应的中文翻译。 + +**理由**：当前文档量不大（12 个文件），手动维护成本可控。后续若文档频繁变更可考虑引入翻译检查 CI。 + +## Risks / Trade-offs + +- **[翻译滞后]** 英文文档更新后中文可能未及时同步 → 在中文文档顶部注明基于哪个版本翻译，降低误导风险 +- **[翻译质量]** 翻译可能不够准确或自然 → 保持技术术语原文，减少翻译歧义 +- **[链接失效]** 中文文档间链接必须重写为中文路径，避免跳转到英文文档 → 翻译时逐一检查并修正所有内部链接 + +## Migration Plan + +1. 创建 `docs/i18n/zh-cn/` 目录 +2. 逐文件翻译并写入 +3. 无需回滚方案（纯新增，不影响现有功能） + +## Open Questions + +无。 diff --git a/openspec/changes/archive/2026-03-27-add-zh-cn-translations/proposal.md b/openspec/changes/archive/2026-03-27-add-zh-cn-translations/proposal.md new file mode 100644 index 000000000..64a7ec2e8 --- /dev/null +++ b/openspec/changes/archive/2026-03-27-add-zh-cn-translations/proposal.md @@ -0,0 +1,25 @@ +## Why + +OpenSpec 的中文环境使用者在增加，当前所有文档仅提供英文版本，这对中文使用者理解和上手 OpenSpec 造成了一定障碍。提供中文文档能更好地帮助中文使用者理解 OpenSpec 的概念、工作流和命令用法。 + +## What Changes + +- 将 `README.md` 翻译为中文，放置到 `docs/i18n/zh-cn/README.md` +- 将 `docs/` 下所有文档翻译为中文，放置到 `docs/i18n/zh-cn/` 对应路径 +- 每份中文文档开头添加 AI 翻译声明，注明使用的模型名称 +- 保留原始 Markdown 格式、链接、代码块等结构不变 + +## Capabilities + +### New Capabilities +- `zh-cn-translations`: 中文文档翻译，涵盖 `README.md` 和 `docs/` 下全部 11 个文档文件 + +### Modified Capabilities + +N/A — 本次变更不修改现有功能的需求，仅为已有文档添加中文翻译。 + +## Impact + +- 新增目录 `docs/i18n/zh-cn/` 及其下所有翻译文件 +- 不影响现有英文文档和功能 +- 未来文档更新时需要同步维护翻译版本 diff --git a/openspec/changes/archive/2026-03-27-add-zh-cn-translations/specs/zh-cn-translations/spec.md b/openspec/changes/archive/2026-03-27-add-zh-cn-translations/specs/zh-cn-translations/spec.md new file mode 100644 index 000000000..104ee8825 --- /dev/null +++ b/openspec/changes/archive/2026-03-27-add-zh-cn-translations/specs/zh-cn-translations/spec.md @@ -0,0 +1,59 @@ +## ADDED Requirements + +### Requirement: Chinese translation completeness +All English documentation files SHALL have corresponding Chinese translations under `docs/i18n/zh-cn/`. + +#### Scenario: All source files have translations +- **WHEN** checking `docs/i18n/zh-cn/` against `docs/` and root `README.md` +- **THEN** every source file has a matching translation file with the same filename + +### Requirement: Technical content preservation +Translations SHALL preserve command names, code, links, and technical proper nouns in their original form. + +#### Scenario: Command names remain in English +- **WHEN** translating a document containing CLI commands like `openspec init` or `/opsx:propose` +- **THEN** the command text remains unchanged in the Chinese translation + +#### Scenario: Code blocks remain unchanged +- **WHEN** translating a document containing code blocks or inline code +- **THEN** all code content is preserved exactly as in the source + +#### Scenario: Links remain functional +- **WHEN** translating a document containing hyperlinks or relative paths +- **THEN** link targets are preserved or adjusted to point to the correct Chinese translation paths + +### Requirement: Internal links point to Chinese translations +Internal document links in Chinese translations SHALL point to other Chinese translation files, not to English source files. + +#### Scenario: Cross-document links use Chinese paths +- **WHEN** translating a document that links to another documentation file (e.g., `[Commands](../commands.md)`) +- **THEN** the link target is rewritten to point to the corresponding file under `docs/i18n/zh-cn/` + +#### Scenario: External links remain unchanged +- **WHEN** translating a document that links to external URLs (GitHub, Discord, npm, etc.) +- **THEN** the external URL remains unchanged + +### Requirement: Translation directory structure +Chinese translations SHALL be placed under `docs/i18n/zh-cn/` with filenames matching the source documents. + +#### Scenario: Root README translation location +- **WHEN** translating the root `README.md` +- **THEN** the translation is saved as `docs/i18n/zh-cn/README.md` + +#### Scenario: Docs translation location +- **WHEN** translating a file from `docs/` (e.g., `docs/getting-started.md`) +- **THEN** the translation is saved as `docs/i18n/zh-cn/getting-started.md` + +### Requirement: AI translation disclaimer +Each Chinese translation file SHALL include a disclaimer at the beginning indicating it was translated by AI, with the model name specified. + +#### Scenario: Disclaimer present at file start +- **WHEN** opening any Chinese translation file under `docs/i18n/zh-cn/` +- **THEN** the file begins with a blockquote containing the AI translation notice and model name in backtick-wrapped format + +### Requirement: Source document unchanged +Existing English documentation SHALL NOT be modified by this change. + +#### Scenario: No changes to source files +- **WHEN** completing the translation work +- **THEN** all files under `docs/` and root `README.md` remain identical to their pre-change state diff --git a/openspec/changes/archive/2026-03-27-add-zh-cn-translations/tasks.md b/openspec/changes/archive/2026-03-27-add-zh-cn-translations/tasks.md new file mode 100644 index 000000000..46ed2f1a8 --- /dev/null +++ b/openspec/changes/archive/2026-03-27-add-zh-cn-translations/tasks.md @@ -0,0 +1,27 @@ +## 1. 目录结构 + +- [x] 1.1 创建 `docs/i18n/zh-cn/` 目录 +- [x] 1.2 确定 AI 翻译声明格式：`> **声明**：本文档由 AI 翻译，使用 \`mimo-v2-pro-free\` 进行翻译。` + +## 2. 翻译文档（每个文件开头需包含 AI 翻译声明） + +- [x] 2.1 翻译 `README.md` → `docs/i18n/zh-cn/README.md`，开头添加声明，链接指向中文文档 +- [x] 2.2 翻译 `docs/getting-started.md` → `docs/i18n/zh-cn/getting-started.md`，开头添加声明，链接指向中文文档 +- [x] 2.3 翻译 `docs/workflows.md` → `docs/i18n/zh-cn/workflows.md`，开头添加声明，链接指向中文文档 +- [x] 2.4 翻译 `docs/commands.md` → `docs/i18n/zh-cn/commands.md`，开头添加声明，链接指向中文文档 +- [x] 2.5 翻译 `docs/cli.md` → `docs/i18n/zh-cn/cli.md`，开头添加声明，链接指向中文文档 +- [x] 2.6 翻译 `docs/supported-tools.md` → `docs/i18n/zh-cn/supported-tools.md`，开头添加声明，链接指向中文文档 +- [x] 2.7 翻译 `docs/concepts.md` → `docs/i18n/zh-cn/concepts.md`，开头添加声明，链接指向中文文档 +- [x] 2.8 翻译 `docs/multi-language.md` → `docs/i18n/zh-cn/multi-language.md`，开头添加声明，链接指向中文文档 +- [x] 2.9 翻译 `docs/customization.md` → `docs/i18n/zh-cn/customization.md`，开头添加声明，链接指向中文文档 +- [x] 2.10 翻译 `docs/installation.md` → `docs/i18n/zh-cn/installation.md`，开头添加声明，链接指向中文文档 +- [x] 2.11 翻译 `docs/migration-guide.md` → `docs/i18n/zh-cn/migration-guide.md`，开头添加声明，链接指向中文文档 +- [x] 2.12 翻译 `docs/opsx.md` → `docs/i18n/zh-cn/opsx.md`，开头添加声明，链接指向中文文档 + +## 3. 验证 + +- [x] 3.1 确认所有 12 个源文件均有对应中文翻译 +- [x] 3.2 检查中文文档内部链接均指向 `docs/i18n/zh-cn/` 下的中文文件 +- [x] 3.3 确认命令名、代码块、专有名词保持原文不变 +- [x] 3.4 确认每份中文文档开头均包含 AI 翻译声明 +- [x] 3.5 确认英文源文档未被修改 From c6661a73b79e0e22bb01a54df1bb9293bbf000fa Mon Sep 17 00:00:00 2001 From: Tang <1024830255@qq.com> Date: Fri, 27 Mar 2026 14:27:08 +0800 Subject: [PATCH 2/4] docs(i18n/zh-cn): fix broken relative links to project root assets - README.md: fix paths to assets/, LICENSE, MAINTAINERS.md (add extra ../) - getting-started.md: link to local Chinese README instead of root English version --- docs/i18n/zh-cn/README.md | 10 +++++----- docs/i18n/zh-cn/getting-started.md | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/i18n/zh-cn/README.md b/docs/i18n/zh-cn/README.md index 361922dee..709d942de 100644 --- a/docs/i18n/zh-cn/README.md +++ b/docs/i18n/zh-cn/README.md @@ -3,8 +3,8 @@

- - OpenSpec logo + + OpenSpec logo

@@ -12,7 +12,7 @@

CI npm version - License: MIT + License: MIT Discord

@@ -78,7 +78,7 @@ AI: 已归档至 openspec/changes/archive/2025-01-23-add-dark-mode/ OpenSpec 仪表板

- OpenSpec 仪表板预览 + OpenSpec 仪表板预览

@@ -194,7 +194,7 @@ OpenSpec 收集匿名使用统计。
维护者和顾问 -请参阅 [MAINTAINERS.md](../../MAINTAINERS.md) 了解核心维护者和顾问的列表，他们帮助指导项目发展。 +请参阅 [MAINTAINERS.md](../../../MAINTAINERS.md) 了解核心维护者和顾问的列表，他们帮助指导项目发展。
diff --git a/docs/i18n/zh-cn/getting-started.md b/docs/i18n/zh-cn/getting-started.md index cb4075cc1..57a6c40f7 100644 --- a/docs/i18n/zh-cn/getting-started.md +++ b/docs/i18n/zh-cn/getting-started.md @@ -2,7 +2,7 @@ # 快速入门 -本指南解释了在安装和初始化 OpenSpec 后它的工作原理。安装说明请参阅 [主 README](../README.md#quick-start)。 +本指南解释了在安装和初始化 OpenSpec 后它的工作原理。安装说明请参阅 [主 README](README.md#快速开始)。 ## 工作原理 From 59bfc7318f5c85e0b533f1d00d67bc22fcc3de69 Mon Sep 17 00:00:00 2001 From: Tang <1024830255@qq.com> Date: Fri, 27 Mar 2026 15:11:55 +0800 Subject: [PATCH 3/4] fix(i18n/zh-cn): fix broken relative links to project root assets - fix customization.md to cli.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- docs/i18n/zh-cn/customization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/i18n/zh-cn/customization.md b/docs/i18n/zh-cn/customization.md index 3b38f0607..c5e4ad2bd 100644 --- a/docs/i18n/zh-cn/customization.md +++ b/docs/i18n/zh-cn/customization.md @@ -341,4 +341,4 @@ openspec schema fork spec-driven with-review ## 另请参阅 -- [CLI 参考：Schema 命令](cli.md#schema-commands) - 完整的命令文档 +- [CLI 参考：Schema 命令](cli.md#schema-命令) - 完整的命令文档 From c45580608f14c8698ba78211f280ac0c9004cb21 Mon Sep 17 00:00:00 2001 From: Tang <1024830255@qq.com> Date: Fri, 27 Mar 2026 15:13:49 +0800 Subject: [PATCH 4/4] fix(i18n/zh-cn): Fix the model name in spec/archive Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- .../changes/archive/2026-03-27-add-zh-cn-translations/tasks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openspec/changes/archive/2026-03-27-add-zh-cn-translations/tasks.md b/openspec/changes/archive/2026-03-27-add-zh-cn-translations/tasks.md index 46ed2f1a8..47cac80b7 100644 --- a/openspec/changes/archive/2026-03-27-add-zh-cn-translations/tasks.md +++ b/openspec/changes/archive/2026-03-27-add-zh-cn-translations/tasks.md @@ -1,7 +1,7 @@ ## 1. 目录结构 - [x] 1.1 创建 `docs/i18n/zh-cn/` 目录 -- [x] 1.2 确定 AI 翻译声明格式：`> **声明**：本文档由 AI 翻译，使用 \`mimo-v2-pro-free\` 进行翻译。` +- [x] 1.2 确定 AI 翻译声明格式：`> **声明**：本文档由 AI 翻译，使用 \`mimo-v2-pro\` 进行翻译。` ## 2. 翻译文档（每个文件开头需包含 AI 翻译声明）