openspec-cn 0.23.0 → 0.23.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +403 -77
  2. package/dist/commands/workflow/instructions.js +2 -2
  3. package/dist/core/templates/skill-templates.js +8 -8
  4. package/package.json +1 -2
package/README.md CHANGED
@@ -1,5 +1,5 @@
1
1
  <p align="center">
2
- <a href="https://github.com/xiangagou163/OpenSpec-cn">
2
+ <a href="https://github.com/Fission-AI/OpenSpec">
3
3
  <picture>
4
4
  <source srcset="assets/openspec_pixel_dark.svg" media="(prefers-color-scheme: dark)">
5
5
  <source srcset="assets/openspec_pixel_light.svg" media="(prefers-color-scheme: light)">
@@ -8,11 +8,11 @@
8
8
  </a>
9
9
 
10
10
  </p>
11
- <p align="center">Spec-driven development for AI coding assistants.</p>
11
+ <p align="center">面向 AI 编码助手的规范驱动开发。</p>
12
12
  <p align="center">
13
- <a href="https://github.com/xiangagou163/OpenSpec-cn/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/xiangagou163/OpenSpec-cn/actions/workflows/ci.yml/badge.svg" /></a>
14
- <a href="https://www.npmjs.com/package/openspec-cn"><img alt="npm version" src="https://img.shields.io/npm/v/openspec-cn?style=flat-square" /></a>
15
- <a href="https://nodejs.org/"><img alt="node version" src="https://img.shields.io/node/v/openspec-cn?style=flat-square" /></a>
13
+ <a href="https://github.com/Fission-AI/OpenSpec/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Fission-AI/OpenSpec/actions/workflows/ci.yml/badge.svg" /></a>
14
+ <a href="https://www.npmjs.com/package/@fission-ai/openspec"><img alt="npm version" src="https://img.shields.io/npm/v/@fission-ai/openspec?style=flat-square" /></a>
15
+ <a href="https://nodejs.org/"><img alt="node version" src="https://img.shields.io/node/v/@fission-ai/openspec?style=flat-square" /></a>
16
16
  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
17
17
  <a href="https://conventionalcommits.org"><img alt="Conventional Commits" src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=flat-square" /></a>
18
18
  <a href="https://discord.gg/YctCnvvshC"><img alt="Discord" src="https://img.shields.io/badge/Discord-Join%20the%20community-5865F2?logo=discord&logoColor=white&style=flat-square" /></a>
@@ -23,131 +23,457 @@
23
23
  </p>
24
24
 
25
25
  <p align="center">
26
- Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates · Join the <a href="https://discord.gg/YctCnvvshC">OpenSpec Discord</a> for help and questions.
26
+ 关注 <a href="https://x.com/0xTab">@0xTab</a> 获取更新 · 进入 <a href="https://discord.gg/YctCnvvshC">OpenSpec Discord</a> 获取帮助与答疑。
27
27
  </p>
28
28
 
29
29
  <p align="center">
30
- <sub>🧪 <strong>New:</strong> <a href="docs/experimental-workflow.md">Experimental Workflow (OPSX)</a> — schema-driven, hackable, fluid. Iterate on workflows without code changes.</sub>
30
+ <sub>🧪 <strong>新功能：</strong> <a href="docs/experimental-workflow.md">实验性工作流（OPSX）</a> — 以 schema 驱动、可定制、可流动。无需改代码即可迭代工作流。</sub>
31
31
  </p>
32
32
 
33
- # OpenSpec-cn
33
+ # OpenSpec
34
34
 
35
- OpenSpec alignments humans and AI coding assistants with spec-driven development so you agree on what to build before any code is written. **No API keys required.**
35
+ OpenSpec 用规范驱动开发对齐人类与 AI 编码助手，让你在写任何代码之前先达成“要做什么”的一致。**无需 API Key。**
36
36
 
37
- ## Why OpenSpec?
37
+ ## 中文本地化
38
38
 
39
- AI coding assistants are powerful but unpredictable when requirements live in chat history. OpenSpec adds a lightweight specification workflow that locks intent before implementation, giving you deterministic, reviewable outputs.
39
+ 此分支已对 OpenSpec 生成的规范与指令做完整中文化。所有必需的 OpenSpec 标记（如 Requirement/Scenario/ADDED/MODIFIED/REMOVED/RENAMED、SHALL/MUST）保持不变，以确保解析器兼容性。
40
40
 
41
- Key outcomes:
42
- - Human and AI stakeholders agree on specs before work begins.
43
- - Structured change folders (proposals, tasks, and spec updates) keep scope explicit and auditable.
44
- - Shared visibility into what's proposed, active, or archived.
45
- - Works with the AI tools you already use: custom slash commands where supported, context rules everywhere else.
41
+ ## 为什么选择 OpenSpec？
46
42
 
47
- ## Installation
43
+ AI 编码助手很强，但当需求只存在于聊天记录时，输出往往不可控。OpenSpec 提供轻量的规范化流程，在实现前锁定意图，从而得到可预测、可审阅的输出。
48
44
 
49
- ```bash
50
- npm install -g openspec-cn
51
- ```
45
+ 关键收益：
46
+ - 人与 AI 在动工前对规范达成一致。
47
+ - 结构化的变更目录（提案、任务、规范更新）让范围清晰可审计。
48
+ - 共享可见性：哪些在提议、哪些在进行、哪些已归档。
49
+ - 与你现有的 AI 工具协作：支持自定义命令的就用命令，不支持的就用上下文规则。
52
50
 
53
- ## How OpenSpec compares (at a glance)
51
+ ## OpenSpec 对比概览
54
52
 
55
- - **Lightweight**: simple workflow, no API keys, minimal setup.
56
- - **Brownfield-first**: works great beyond 0→1. OpenSpec separates the source of truth from proposals: `openspec/specs/` (current truth) and `openspec/changes/` (proposed updates). This keeps diffs explicit and manageable across features.
57
- - **Change tracking**: proposals, tasks, and spec deltas live together; archiving merges the approved updates back into specs.
58
- - **Compared to spec-kit & Kiro**: those shine for brand-new features (0→1). OpenSpec also excels when modifying existing behavior (1→n), especially when updates span multiple specs.
53
+ - **轻量**：流程简单，无需 API Key，最小化配置。
54
+ - **面向存量系统**：0→1 之外也很强。OpenSpec 将“真实规范”与“变更提案”分离：`openspec/specs/`（当前真相）与 `openspec/changes/`（提议更新），使差异清晰且可管理。
55
+ - **变更跟踪**：提案、任务与规范增量共存；归档时把已批准的更新合并回规范。
56
+ - **对比 spec-kit 与 Kiro**：它们更适合 0→1，新特性场景。OpenSpec 在修改既有行为（1→n）、尤其涉及多份规范时表现更佳。
59
57
 
60
- See the full comparison in [How OpenSpec Compares](#how-openspec-compares).
58
+ 完整对比见：[OpenSpec 对比](#how-openspec-compares)。
61
59
 
62
- ## How It Works
60
+ ## 它如何工作
63
61
 
64
62
  ```
65
63
  ┌────────────────────┐
66
- │ Draft Change │
67
- │ Proposal │
64
+ │ 变更草案 │
65
+ │ 提案 │
68
66
  └────────┬───────────┘
69
- │ share intent with your AI
67
+ │ 与 AI 共享意图
70
68
  ▼
71
69
  ┌────────────────────┐
72
- │ Review & Align │
73
- │ (edit specs/tasks) │◀──── feedback loop ──────┐
70
+ │ 评审与对齐 │
71
+ │（编辑规范/任务） │◀──── 反馈循环 ──────┐
74
72
  └────────┬───────────┘ │
75
- │ approved plan │
73
+ │ 已批准的计划 │
76
74
  ▼ │
77
75
  ┌────────────────────┐ │
78
- │ Implement Tasks │──────────────────────────┘
79
- │ (AI writes code) │
76
+ │ 实现任务 │──────────────────────────┘
77
+ │（AI 写代码） │
80
78
  └────────┬───────────┘
81
- │ ship the change
79
+ │ 交付变更
82
80
  ▼
83
81
  ┌────────────────────┐
84
- │ Archive & Update │
85
- │ Specs (source) │
82
+ │ 归档与更新 │
83
+ │ 规范（源） │
86
84
  └────────────────────┘
87
85
 
88
- 1. Draft a change proposal that captures the spec updates you want.
89
- 2. Review the proposal with your AI assistant until everyone agrees.
90
- 3. Implement tasks that reference the agreed specs.
91
- 4. Archive the change to merge the approved updates back into the source-of-truth specs.
86
+ 1. 起草变更提案，描述你希望的规范更新。
87
+ 2. 与 AI 反复审阅，直到达成共识。
88
+ 3. 根据已一致的规范执行任务。
89
+ 4. 归档变更，将已批准的更新合并回“真实规范”。
92
90
  ```
93
91
 
94
- ## Getting Started
92
+ ## 快速开始
95
93
 
96
- ### Supported AI Tools
94
+ ### 支持的 AI 工具
97
95
 
98
96
  <details>
99
- <summary><strong>Native Slash Commands</strong> (click to expand)</summary>
97
+ <summary><strong>原生命令（Slash Commands）</strong>（点击展开）</summary>
100
98
 
101
- These tools have built-in OpenSpec commands. Select the OpenSpec integration when prompted.
99
+ 这些工具内置 OpenSpec 命令，按提示选择 OpenSpec 集成即可。
102
100
 
103
- | Tool | Commands |
101
+ | 工具 | 命令 |
104
102
  |------|----------|
105
103
  | **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` (`.amazonq/prompts/`) |
106
104
  | **Antigravity** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.agent/workflows/`) |
107
- | **Claude Code** | `/opsx:new`, `/opsx:continue`, `/opsx:apply` (`.claude/commands/`) |
108
- | **Cursor** | `/opsx:new`, `/opsx:continue`, `/opsx:apply` (`.cursor/commands/`) |
109
- | **Windsurf** | `/opsx:new`, `/opsx:continue`, `/opsx:apply` (`.windsurf/commands/`) |
105
+ | **Auggie (Augment CLI)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.augment/commands/`) |
106
+ | **Claude Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |
107
+ | **Cline** | 在 `.clinerules/workflows/` 目录下的工作流（`.clinerules/workflows/openspec-*.md`） |
108
+ | **CodeBuddy Code (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.codebuddy/commands/`) — 见 [docs](https://www.codebuddy.ai/cli) |
109
+ | **Codex** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive`（全局：`~/.codex/prompts`，自动安装） |
110
+ | **Continue** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.continue/prompts/`) |
111
+ | **CoStrict** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.cospec/openspec/commands/`) — 见 [docs](https://costrict.ai)|
112
+ | **Crush** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.crush/commands/openspec/`) |
113
+ | **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
114
+ | **Factory Droid** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.factory/commands/`) |
115
+ | **Gemini CLI** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.gemini/commands/openspec/`) |
116
+ | **GitHub Copilot** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.github/prompts/`) |
117
+ | **iFlow (iflow-cli)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.iflow/commands/`) |
118
+ | **Kilo Code** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` (`.kilocode/workflows/`) |
119
+ | **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
120
+ | **Qoder** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.qoder/commands/openspec/`) — 见 [docs](https://qoder.com) |
121
+ | **Qwen Code** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.qwen/commands/`) |
122
+ | **RooCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.roo/commands/`) |
123
+ | **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.windsurf/workflows/`) |
124
+
125
+ Kilo Code 会自动发现团队工作流。将生成文件保存到 `.kilocode/workflows/`，并通过命令面板触发 `/openspec-proposal.md`、`/openspec-apply.md` 或 `/openspec-archive.md`。
110
126
 
111
127
  </details>
112
128
 
113
129
  <details>
114
- <summary><strong>Context Rules</strong> (click to expand)</summary>
130
+ <summary><strong>AGENTS.md 兼容</strong>（点击展开）</summary>
131
+
132
+ 这些工具会自动读取 `openspec/AGENTS.md` 中的工作流说明。如需提醒，可直接要求它们遵循 OpenSpec 工作流。更多信息见 [AGENTS.md 规范](https://agents.md/)。
115
133
 
116
- For tools without custom commands, use OpenSpec via context rules. Copy the appropriate rules from [docs/context-rules/](docs/context-rules/) into your project's rule file (e.g., `.cursorrules`, `.clinerules`).
134
+ | 工具 |
135
+ |-------|
136
+ | Amp • Jules • Others |
117
137
 
118
138
  </details>
119
139
 
120
- ### Quick Start
140
+ ### 安装与初始化
121
141
 
122
- 1. Initialize OpenSpec in your project:
123
- ```bash
124
- openspec init
125
- ```
126
- 2. Start a new change:
127
- ```bash
128
- openspec change new "my-feature"
129
- ```
130
- *This creates `openspec/changes/my-feature/proposal.md`*
131
- 3. Collaborate with your AI to refine the specs and tasks.
132
- 4. Implement the change:
133
- ```bash
134
- openspec change apply "my-feature"
135
- ```
136
- 5. Archive when done:
142
+ #### 前置条件
143
+ - **Node.js >= 20.19.0** - 使用 `node --version` 检查版本
144
+
145
+ #### 第一步：全局安装 CLI
146
+
147
+ **方式 A：使用 npm**
148
+
149
+ ```bash
150
+ npm install -g openspec-cn@latest
151
+ ```
152
+
153
+ 验证安装：
154
+ ```bash
155
+ openspec --version
156
+ ```
157
+
158
+ **方式 B：使用 Nix（NixOS 与 Nix 包管理器）**
159
+
160
+ 无需安装，直接运行 OpenSpec：
161
+ ```bash
162
+ nix run github:Fission-AI/OpenSpec -- init
163
+ ```
164
+
165
+ 或安装到你的 profile：
166
+ ```bash
167
+ nix profile install github:Fission-AI/OpenSpec
168
+ ```
169
+
170
+ 或在 `flake.nix` 中加入开发环境：
171
+ ```nix
172
+ {
173
+ inputs = {
174
+ nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
175
+ openspec.url = "github:Fission-AI/OpenSpec";
176
+ };
177
+
178
+ outputs = { nixpkgs, openspec, ... }: {
179
+ devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
180
+ buildInputs = [ openspec.packages.x86_64-linux.default ];
181
+ };
182
+ };
183
+ }
184
+ ```
185
+
186
+ 验证安装：
187
+ ```bash
188
+ openspec --version
189
+ ```
190
+
191
+ #### 第二步：在项目中初始化 OpenSpec
192
+
193
+ 进入你的项目目录：
194
+ ```bash
195
+ cd my-project
196
+ ```
197
+
198
+ 运行初始化：
199
+ ```bash
200
+ openspec init
201
+ ```
202
+
203
+ **初始化过程中会发生：**
204
+ - 你会被提示选择原生支持的 AI 工具（Claude Code、CodeBuddy、Cursor、OpenCode、Qoder 等）；其他助手使用共享的 `AGENTS.md` 说明
205
+ - OpenSpec 会为你选择的工具自动配置命令，并在项目根目录写入托管的 `AGENTS.md` 交接文件
206
+ - 在项目中创建新的 `openspec/` 目录结构
207
+
208
+ **完成设置后：**
209
+ - 主要 AI 工具可直接触发 `/openspec` 工作流，无需额外配置
210
+ - 运行 `openspec list` 验证设置并查看活跃变更
211
+ - 如果编码助手没有立刻显示命令，请重启。命令在启动时加载，重新启动即可出现。
212
+
213
+ ### 可选：补充项目上下文
214
+
215
+ `openspec init` 完成后，你会看到一段建议提示，用于补充项目上下文：
216
+
217
+ ```text
218
+ Populate your project context:
219
+ "Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions"
220
+ ```
221
+
222
+ 使用 `openspec/project.md` 定义项目级规范、标准、架构模式以及在所有变更中应遵循的准则。
223
+
224
+ ### 创建你的第一个变更
225
+
226
+ 下面是一个完整流程示例，适用于任何 AI 工具。支持命令的工具会自动识别快捷方式。
227
+
228
+ #### 1. 起草提案
229
+ 先让 AI 创建变更提案：
230
+
231
+ ```text
232
+ You: 创建一个 OpenSpec 变更提案，用于新增按角色与团队的个人资料筛选
233
+ （支持命令的工具快捷方式：/openspec:proposal Add profile search filters）
234
+
235
+ AI: 我将为个人资料筛选创建 OpenSpec 变更提案。
236
+ *创建 openspec/changes/add-profile-filters/，包含 proposal.md、tasks.md、spec 增量。*
237
+ ```
238
+
239
+ #### 2. 验证与评审
240
+ 确认变更创建正确并审阅提案：
241
+
242
+ ```bash
243
+ $ openspec list # 确认变更目录存在
244
+ $ openspec validate add-profile-filters # 校验规范格式
245
+ $ openspec show add-profile-filters # 查看提案、任务与规范增量
246
+ ```
247
+
248
+ #### 3. 打磨规范
249
+ 迭代规范直到满足需求：
250
+
251
+ ```text
252
+ You: 能否为角色与团队筛选添加验收标准？
253
+
254
+ AI: 我会在规范增量中加入对应场景。
255
+ *编辑 openspec/changes/add-profile-filters/specs/profile/spec.md 与 tasks.md。*
256
+ ```
257
+
258
+ #### 4. 实现变更
259
+ 规范确认无误后开始实现：
260
+
261
+ ```text
262
+ You: 规范看起来没问题。开始实现这个变更。
263
+ （支持命令的工具快捷方式：/openspec:apply add-profile-filters）
264
+
265
+ AI: 我将执行 add-profile-filters 变更中的任务。
266
+ *实现 openspec/changes/add-profile-filters/tasks.md 中的任务*
267
+ *标记完成：Task 1.1 ✓, Task 1.2 ✓, Task 2.1 ✓...*
268
+ ```
269
+
270
+ #### 5. 归档已完成的变更
271
+ 实现完成后归档变更：
272
+
273
+ ```text
274
+ AI: 任务已全部完成，实现就绪。
275
+
276
+ You: 请归档该变更
277
+ （支持命令的工具快捷方式：/openspec:archive add-profile-filters）
278
+
279
+ AI: 我将归档 add-profile-filters 变更。
280
+ *运行：openspec archive add-profile-filters --yes*
281
+ ✓ 变更归档成功，规范已更新，准备开始下一个功能！
282
+ ```
283
+
284
+ 或在终端自行运行：
285
+ ```bash
286
+ $ openspec archive add-profile-filters --yes # 无提示归档已完成的变更
287
+ ```
288
+
289
+ **注：** 支持命令的工具（Claude Code、CodeBuddy、Cursor、Codex、Qoder、RooCode）可使用这些快捷方式。其他工具可使用自然语言请求“创建 OpenSpec 提案”、“应用 OpenSpec 变更”或“归档变更”。
290
+
291
+ ## 命令参考
292
+
293
+ ```bash
294
+ openspec list # 查看活跃变更目录
295
+ openspec view # 交互式仪表盘查看规范与变更
296
+ openspec show <change> # 查看变更详情（提案、任务、规范更新）
297
+ openspec validate <change> # 校验规范格式与结构
298
+ openspec archive <change> [--yes|-y] # 归档已完成变更（--yes 为无交互）
299
+ ```
300
+
301
+ ## 示例：AI 如何生成 OpenSpec 文件
302
+
303
+ 当你让 AI “添加双因素认证”时，它会生成：
304
+
305
+ ```
306
+ openspec/
307
+ ├── specs/
308
+ │ └── auth/
309
+ │ └── spec.md # 当前认证规范（若存在）
310
+ └── changes/
311
+ └── add-2fa/ # AI 创建整个结构
312
+ ├── proposal.md # 为什么变更、改了什么
313
+ ├── tasks.md # 实现清单
314
+ ├── design.md # 技术决策（可选）
315
+ └── specs/
316
+ └── auth/
317
+ └── spec.md # 增量内容
318
+ ```
319
+
320
+ ### AI 生成的规范（位于 `openspec/specs/auth/spec.md`）：
321
+
322
+ ```markdown
323
+ # 认证规范
324
+
325
+ ## 目的
326
+ 认证与会话管理。
327
+
328
+ ## 需求
329
+ ### Requirement: User Authentication
330
+ 系统 SHALL 在成功登录后签发 JWT。
331
+
332
+ #### Scenario: Valid credentials
333
+ - WHEN 用户提交有效凭证
334
+ - THEN 返回 JWT
335
+ ```
336
+
337
+ ### AI 生成的变更增量（位于 `openspec/changes/add-2fa/specs/auth/spec.md`）：
338
+
339
+ ```markdown
340
+ # Auth 变更增量
341
+
342
+ ## ADDED Requirements
343
+ ### Requirement: Two-Factor Authentication
344
+ 系统 MUST 在登录时要求第二因素。
345
+
346
+ #### Scenario: OTP required
347
+ - WHEN 用户提交有效凭证
348
+ - THEN 需要 OTP 挑战
349
+ ```
350
+
351
+ ### AI 生成的任务（位于 `openspec/changes/add-2fa/tasks.md`）：
352
+
353
+ ```markdown
354
+ ## 1. 数据库准备
355
+ - [ ] 1.1 在 users 表中新增 OTP 密钥列
356
+ - [ ] 1.2 创建 OTP 验证日志表
357
+
358
+ ## 2. 后端实现
359
+ - [ ] 2.1 添加 OTP 生成接口
360
+ - [ ] 2.2 修改登录流程要求 OTP
361
+ - [ ] 2.3 添加 OTP 验证接口
362
+
363
+ ## 3. 前端更新
364
+ - [ ] 3.1 创建 OTP 输入组件
365
+ - [ ] 3.2 更新登录流程 UI
366
+ ```
367
+
368
+ **重要：** 这些文件无需手动创建，AI 会根据你的需求和现有代码库自动生成。
369
+
370
+ ## 理解 OpenSpec 文件
371
+
372
+ ### 增量格式
373
+
374
+ 增量是展示规范如何变化的“补丁”：
375
+
376
+ - **`## ADDED Requirements`** - 新能力
377
+ - **`## MODIFIED Requirements`** - 行为变化（包含完整更新文本）
378
+ - **`## REMOVED Requirements`** - 弃用功能
379
+
380
+ **格式要求：**
381
+ - 使用 `### Requirement: <name>` 作为标题
382
+ - 每条需求至少包含一个 `#### Scenario:` 块
383
+ - 需求文字使用 SHALL/MUST
384
+
385
+ <a id="how-openspec-compares"></a>
386
+ ## OpenSpec 对比
387
+
388
+ ### 对比 spec-kit
389
+ OpenSpec 的双目录模型（`openspec/specs/` 表示当前真相，`openspec/changes/` 表示提议更新）将状态与差异分离。修改既有功能或涉及多个规范时更易扩展。spec-kit 在 0→1 阶段更强，但对跨规范更新与演进特性支持较弱。
390
+
391
+ ### 对比 Kiro.dev
392
+ OpenSpec 将单个功能的所有变更收拢到一个目录（`openspec/changes/feature-name/`），便于同时跟踪规范、任务与设计。Kiro 将更新分散在多个规范目录中，跟踪更难。
393
+
394
+ ### 对比无规范
395
+ 没有规范时，AI 往往基于模糊提示生成代码，容易漏需求或引入不必要功能。OpenSpec 通过在动工前达成行为共识带来可预期性。
396
+
397
+ ## 团队落地
398
+
399
+ 1. **初始化 OpenSpec** – 在仓库中运行 `openspec init`。
400
+ 2. **从新功能开始** – 让 AI 用变更提案记录即将开展的工作。
401
+ 3. **渐进演进** – 每次变更归档为活的规范，持续记录系统。
402
+ 4. **保持灵活** – 队友可用 Claude Code、CodeBuddy、Cursor 或任何兼容 AGENTS.md 的工具，规范保持一致。
403
+
404
+ 当有人切换工具时运行 `openspec update`，让指令与命令绑定保持最新。
405
+
406
+ ## 更新 OpenSpec
407
+
408
+ 1. **升级包**
137
409
  ```bash
138
- openspec change archive "my-feature"
410
+ npm install -g openspec-cn@latest
139
411
  ```
412
+ 2. **刷新代理指令**
413
+ - 在每个项目内运行 `openspec update`，重新生成 AI 指引并确保最新命令生效。
140
414
 
141
- ## Documentation
415
+ ## 实验性功能
416
+
417
+ <details>
418
+ <summary><strong>🧪 OPSX：流动、可迭代的工作流</strong>（仅 Claude Code）</summary>
419
+
420
+ **为什么需要它：**
421
+ - 标准工作流是固定的——你无法调整指令或自定义
422
+ - AI 输出不好时，你无法自行优化提示
423
+ - 所有人用同一套流程，难以匹配团队习惯
424
+
425
+ **有何不同：**
426
+ - **可改造** — 直接编辑模板与 schema，即时测试，无需重建
427
+ - **更细粒度** — 每个工件都有独立指令，可单独测试与微调
428
+ - **可定制** — 自定义工作流、工件与依赖关系
429
+ - **流动** — 没有阶段闸口，随时更新任意工件
430
+
431
+ ```
432
+ 随时可以回到任一步：
433
+
434
+ 提案 ──→ 规范 ──→ 设计 ──→ 任务 ──→ 实现
435
+ ▲ ▲ ▲ │
436
+ └─────────┴────────┴────────────────┘
437
+ ```
142
438
 
143
- Full documentation is available at [openspec.dev](https://openspec.dev) (TBD).
439
+ | 命令 | 作用 |
440
+ |---------|--------------|
441
+ | `/opsx:new` | 创建新变更 |
442
+ | `/opsx:continue` | 创建下一个工件（根据就绪情况） |
443
+ | `/opsx:ff` | 快进（一次性生成全部规划工件） |
444
+ | `/opsx:apply` | 实现任务，必要时同步更新工件 |
445
+ | `/opsx:archive` | 完成后归档 |
144
446
 
145
- - [Core Concepts](docs/core-concepts.md)
146
- - [Workflow Guide](docs/workflow.md)
147
- - [Experimental Artifact Workflow](docs/experimental-workflow.md)
148
- - [Configuration](docs/configuration.md)
149
- - [Troubleshooting](docs/troubleshooting.md)
447
+ **启用：** `openspec experimental`
448
+
449
+ [完整文档 →](docs/experimental-workflow.md)
450
+
451
+ </details>
452
+
453
+ <details>
454
+ <summary><strong>遥测</strong> – OpenSpec 收集匿名使用统计（可退出：<code>OPENSPEC_TELEMETRY=0</code>）</summary>
455
+
456
+ 我们只收集命令名与版本号用于理解使用模式，不含参数、路径、内容或个人信息。CI 中会自动关闭。
457
+
458
+ **退出：** `export OPENSPEC_TELEMETRY=0` 或 `export DO_NOT_TRACK=1`
459
+
460
+ </details>
461
+
462
+ ## 参与贡献
463
+
464
+ - 安装依赖：`pnpm install`
465
+ - 构建：`pnpm run build`
466
+ - 测试：`pnpm test`
467
+ - 本地开发 CLI：`pnpm run dev` 或 `pnpm run dev:cli`
468
+ - 规范化提交（单行）：`type(scope): subject`
469
+
470
+ <details>
471
+ <summary><strong>维护者与顾问</strong></summary>
472
+
473
+ 维护者与顾问名单见 [MAINTAINERS.md](MAINTAINERS.md)。
474
+
475
+ </details>
150
476
 
151
- ## License
477
+ ## 许可证
152
478
 
153
479
  MIT
package/dist/commands/workflow/instructions.js CHANGED
@@ -147,7 +147,7 @@ function parseTasksFile(content) {
147
147
  let taskIndex = 0;
148
148
  for (const line of lines) {
149
149
  // Match checkbox patterns: - [ ] or - [x] or - [X]
150
- const checkboxMatch = line.match(/^[-*]\s*\[([ xX])\]\s*(.+)$/);
150
+ const checkboxMatch = line.match(/^[-*]\s*\[([ xX])\]\s*(.+)\s*$/);
151
151
  if (checkboxMatch) {
152
152
  taskIndex++;
153
153
  const done = checkboxMatch[1].toLowerCase() === 'x';
@@ -228,7 +228,7 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
228
228
  const context = loadChangeContext(projectRoot, changeName, schemaName);
229
229
  const changeDir = path.join(projectRoot, 'openspec', 'changes', changeName);
230
230
  // Get the full schema to access the apply phase configuration
231
- const schema = resolveSchema(context.schemaName);
231
+ const schema = resolveSchema(context.schemaName, projectRoot);
232
232
  const applyConfig = schema.apply;
233
233
  // Determine required artifacts and tracking file from schema
234
234
  // Fallback: if no apply block, require all artifacts
package/dist/core/templates/skill-templates.js CHANGED
@@ -362,7 +362,7 @@ export function getNewChangeSkillTemplate() {
362
362
  - 使用的 schema/工作流及其工件顺序
363
363
  - 当前状态（0/N 工件完成）
364
364
  - 首个工件的模板
365
- - 提示语："Ready to create the first artifact? Just describe what this change is about and I'll draft it, or ask me to continue."
365
+ - 提示语："准备创建第一个工件了吗？直接描述这个变更的内容，我会起草；或让我继续。"
366
366
 
367
367
  **约束**
368
368
  - 不要创建任何工件——只展示指令
@@ -419,7 +419,7 @@ export function getContinueChangeSkillTemplate() {
419
419
  **若所有工件完成（\`isComplete: true\`）**：
420
420
  - 祝贺用户
421
421
  - 展示最终状态（包含所用 schema）
422
- - 建议："All artifacts created! You can now implement this change or archive it."
422
+ - 建议："所有工件已创建！现在可以实现该变更或将其归档。"
423
423
  - 停止
424
424
 
425
425
  ---
@@ -616,7 +616,7 @@ Working on task 4/7: <task description>
616
616
  - [x] Task 2
617
617
  ...
618
618
 
619
- All tasks complete! Ready to archive this change.
619
+ 所有任务已完成！可归档该变更。
620
620
  \`\`\`
621
621
 
622
622
  **暂停时输出（遇到问题）**
@@ -1302,7 +1302,7 @@ export function getOpsxApplyCommandTemplate() {
1302
1302
  - 若仅存在一个活跃变更则自动选择
1303
1303
  - 若有歧义，运行 \`openspec list --json\` 获取变更列表并用 **AskUserQuestion tool** 让用户选择
1304
1304
 
1305
- 始终声明："Using change: <name>" 并说明如何切换（例如 \`/opsx:apply <other>\`）。
1305
+ 始终声明："使用变更：<name>" 并说明如何切换（例如 \`/opsx:apply <other>\`）。
1306
1306
 
1307
1307
  2. **检查状态以了解 schema**
1308
1308
  \`\`\`bash
@@ -1396,7 +1396,7 @@ Working on task 4/7: <task description>
1396
1396
  - [x] Task 2
1397
1397
  ...
1398
1398
 
1399
- All tasks complete! Ready to archive this change.
1399
+ 所有任务已完成！可归档该变更。
1400
1400
  \`\`\`
1401
1401
 
1402
1402
  **暂停时输出（遇到问题）**
@@ -1635,7 +1635,7 @@ export function getArchiveChangeSkillTemplate() {
1635
1635
  **Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
1636
1636
  **Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
1637
1637
 
1638
- All artifacts complete. All tasks complete.
1638
+ 所有工件完成，所有任务完成。
1639
1639
  \`\`\`
1640
1640
 
1641
1641
  **约束**
@@ -2308,7 +2308,7 @@ export function getOpsxArchiveCommandTemplate() {
2308
2308
  **Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
2309
2309
  **Specs:** ✓ Synced to main specs
2310
2310
 
2311
- All artifacts complete. All tasks complete.
2311
+ 所有工件完成，所有任务完成。
2312
2312
  \`\`\`
2313
2313
 
2314
2314
  **成功时输出（无增量规范）**
@@ -2321,7 +2321,7 @@ All artifacts complete. All tasks complete.
2321
2321
  **Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
2322
2322
  **Specs:** No delta specs
2323
2323
 
2324
- All artifacts complete. All tasks complete.
2324
+ 所有工件完成，所有任务完成。
2325
2325
  \`\`\`
2326
2326
 
2327
2327
  **成功时输出（含警告）**
package/package.json CHANGED
@@ -1,10 +1,9 @@
1
1
  {
2
2
  "name": "openspec-cn",
3
- "version": "0.23.0",
3
+ "version": "0.23.1",
4
4
  "description": "AI-native system for spec-driven development (Chinese Edition)",
5
5
  "keywords": [
6
6
  "openspec",
7
- "openspec-cn",
8
7
  "specs",
9
8
  "cli",
10
9
  "ai",