openspec-cn 0.23.0

package/schemas/spec-driven/schema.yaml

@@ -0,0 +1,148 @@
+name: spec-driven
+version: 1
+description: 默认 OpenSpec 工作流 - proposal → specs → design → tasks
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: 概述变更的初始提案文档
+    template: proposal.md
+    instruction: |
+      创建提案文档，说明本次变更为何需要。
+
+      Sections:
+      - **Why**: 用 1-2 句话描述问题或机会。它解决什么问题？为何现在？
+      - **What Changes**: 变更清单（项目符号）。明确说明新增能力、修改或移除的内容。破坏性变更用 **BREAKING** 标记。
+      - **Capabilities**: 标明将创建或修改哪些规范：
+        - **New Capabilities**: 列出引入的新能力。每项生成 `specs/<name>/spec.md`。使用 kebab-case 命名（例如 `user-auth`、`data-export`）。
+        - **Modified Capabilities**: 列出 REQUIREMENTS 有变化的既有能力。仅在规范层面的行为变化时包含（不含纯实现细节）。每项需要一个增量规范文件。参考 `openspec/specs/` 中已有名称。若无需求变化则留空。
+      - **Impact**: 影响到的代码、API、依赖或系统。
+
+      IMPORTANT: Capabilities 部分至关重要，它建立了
+      proposal 与 specs 阶段的契约。在填写前先研究现有规范。
+      这里列出的每个能力都需要对应的规范文件。
+
+      保持简洁（1-2 页）。聚焦“为什么”，而非“如何实现”——
+      实现细节应放在 design.md。
+
+      这是基础文档——specs、design 与 tasks 都建立在它之上。
+    requires: []
+
+  - id: specs
+    generates: "specs/**/*.md"
+    description: 变更的详细规范
+    template: spec.md
+    instruction: |
+      创建规范文件，定义系统应做什么（WHAT）。
+
+      每个能力/功能领域创建一个规范文件：`specs/<name>/spec.md`。
+
+      增量操作（使用 ## 标题）：
+      - **ADDED Requirements**: New capabilities
+      - **MODIFIED Requirements**: Changed behavior - MUST include full updated content
+      - **REMOVED Requirements**: Deprecated features - MUST include **Reason** and **Migration**
+      - **RENAMED Requirements**: Name changes only - use FROM:/TO: format
+
+      需求格式：
+      - 每条需求：`### Requirement: <name>`，后接描述
+      - 规范性需求使用 SHALL/MUST（避免 should/may）
+      - 每个场景：`#### Scenario: <name>`，使用 WHEN/THEN 格式
+      - **CRITICAL**: 场景必须使用 4 个井号（`####`）。使用 3 个井号或列表会静默失败。
+      - 每条需求必须至少包含一个场景。
+
+      MODIFIED 需求流程：
+      1. 在 openspec/specs/<capability>/spec.md 中定位现有需求
+      2. 复制完整需求块（从 `### Requirement:` 到所有场景）
+      3. 粘贴到 `## MODIFIED Requirements` 下并编辑为新行为
+      4. 确保标题文本完全一致（忽略空白）
+
+      常见误区：用 MODIFIED 只写部分内容会在归档时丢失细节。
+      如果只是新增关注点而不改变现有行为，请改用 ADDED。
+
+      Example:
+      ```
+      ## ADDED Requirements
+
+      ### Requirement: User can export data
+      The system SHALL allow users to export their data in CSV format.
+
+      #### Scenario: Successful export
+      - **WHEN** user clicks "Export" button
+      - **THEN** system downloads a CSV file with all user data
+
+      ## REMOVED Requirements
+
+      ### Requirement: Legacy export
+      **Reason**: Replaced by new export system
+      **Migration**: Use new export endpoint at /api/v2/export
+      ```
+
+      规范应可测试——每个场景都是潜在测试用例。
+    requires:
+      - proposal
+
+  - id: design
+    generates: design.md
+    description: 包含实现细节的技术设计文档
+    template: design.md
+    instruction: |
+      创建设计文档，说明如何实现本次变更（HOW）。
+
+      何时需要 design.md（满足任一项才创建）：
+      - 跨模块/跨服务变更或新的架构模式
+      - 新的外部依赖或显著的数据模型变更
+      - 安全、性能或迁移复杂度较高
+      - 存在需要先做技术决策的歧义
+
+      Sections:
+      - **Context**: 背景、现状、约束与相关方
+      - **Goals / Non-Goals**: 设计要达成的目标与明确排除的范围
+      - **Decisions**: 关键技术选择及其理由（为何选 X 而非 Y）。每项决策需包含考虑过的替代方案。
+      - **Risks / Trade-offs**: 已知限制与可能出错之处。格式：[风险] → 缓解措施
+      - **Migration Plan**: 上线步骤与回滚策略（如适用）
+      - **Open Questions**: 待解决的决策或未知点
+
+      聚焦架构与方案，而非逐行实现细节。
+      动机参考 proposal，需求参考 specs。
+
+      优秀的设计文档应解释技术决策背后的“why”。
+    requires:
+      - proposal
+
+  - id: tasks
+    generates: tasks.md
+    description: 从规格与设计中拆解出的实现任务
+    template: tasks.md
+    instruction: |
+      创建任务列表，拆解实现工作。
+
+      Guidelines:
+      - 使用 ## 编号标题分组相关任务
+      - 每项任务为复选框：- [ ] X.Y 任务描述
+      - 任务应足够小，便于一次会话内完成
+      - 按依赖顺序排列任务（先做哪些）
+
+      Example:
+      ```
+      ## 1. Setup
+
+      - [ ] 1.1 Create new module structure
+      - [ ] 1.2 Add dependencies to package.json
+
+      ## 2. Core Implementation
+
+      - [ ] 2.1 Implement data export function
+      - [ ] 2.2 Add CSV formatting utilities
+      ```
+
+      依据 specs 确定要做什么，依据 design 确定如何做。
+      每项任务应可验证——完成与否清晰可判断。
+    requires:
+      - specs
+      - design
+
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  instruction: |
+    阅读上下文文件，逐项完成待办任务，完成后立即标记。
+    若遇到阻塞或需要澄清，暂停并说明情况。

package/schemas/spec-driven/templates/design.md

@@ -0,0 +1,19 @@
+## Context
+
+<!-- 背景与现状 -->
+
+## Goals / Non-Goals
+
+**Goals:**
+<!-- 该设计要达成的目标 -->
+
+**Non-Goals:**
+<!-- 明确不在范围内的内容 -->
+
+## Decisions
+
+<!-- 关键设计决策与理由 -->
+
+## Risks / Trade-offs
+
+<!-- 已知风险与权衡 -->

package/schemas/spec-driven/templates/proposal.md

@@ -0,0 +1,23 @@
+## Why
+
+<!-- 说明本次变更的动机。它解决什么问题？为何现在要做？ -->
+
+## What Changes
+
+<!-- 描述将发生的变化。明确说明新增能力、修改或移除的内容。 -->
+
+## Capabilities
+
+### New Capabilities
+<!-- 引入的新能力。将 <name> 替换为 kebab-case 标识符（例如 user-auth、data-export、api-rate-limiting）。每项都会生成 specs/<name>/spec.md -->
+- `<name>`: <此能力涵盖内容的简要说明>
+
+### Modified Capabilities
+<!-- 需求发生变化的既有能力（不仅是实现变化）。
+     仅在规范层面的行为发生变化时列出。每项都需要一个增量规范文件。
+     使用 openspec/specs/ 中已有的规范名称。若无需求变化则留空。 -->
+- `<existing-name>`: <变更的需求是什么>
+
+## Impact
+
+<!-- 影响到的代码、API、依赖或系统 -->

package/schemas/spec-driven/templates/spec.md

@@ -0,0 +1,8 @@
+## ADDED Requirements
+
+### Requirement: <!-- 需求名称 -->
+<!-- 需求描述 -->
+
+#### Scenario: <!-- 场景名称 -->
+- **WHEN** <!-- 条件 -->
+- **THEN** <!-- 预期结果 -->

package/schemas/spec-driven/templates/tasks.md

@@ -0,0 +1,9 @@
+## 1. <!-- 任务分组名称 -->
+
+- [ ] 1.1 <!-- 任务描述 -->
+- [ ] 1.2 <!-- 任务描述 -->
+
+## 2. <!-- 任务分组名称 -->
+
+- [ ] 2.1 <!-- 任务描述 -->
+- [ ] 2.2 <!-- 任务描述 -->

package/schemas/tdd/schema.yaml

@@ -0,0 +1,213 @@
+name: tdd
+version: 1
+description: 测试驱动开发工作流 - tests → implementation → docs
+artifacts:
+  - id: spec
+    generates: spec.md
+    description: 定义需求的功能规范
+    template: spec.md
+    instruction: |
+      创建功能规范，定义要构建的内容（WHAT）。
+
+      Sections:
+      - **Feature**: 功能名称与高层描述（目的与用户价值）
+      - **Requirements**: 具体需求列表，规范性表述使用 SHALL/MUST
+      - **Acceptance Criteria**: 采用 WHEN/THEN 格式的可测试标准
+
+      需求格式：
+      - 每条需求应具体且可测试
+      - 验收标准使用 `#### Scenario: <name>` 并采用 WHEN/THEN 格式
+      - 明确列出边界情况与错误场景
+      - 每条需求必须至少包含一个场景
+
+      Example:
+      ```
+      ## Feature: User Authentication
+
+      Users can securely log into the application.
+
+      ## Requirements
+
+      ### Requirement: Password validation
+      The system SHALL validate passwords meet minimum security requirements.
+
+      #### Scenario: Valid password accepted
+      - **WHEN** password has 8+ chars, uppercase, lowercase, and number
+      - **THEN** password is accepted
+
+      #### Scenario: Weak password rejected
+      - **WHEN** password is less than 8 characters
+      - **THEN** system displays "Password too short" error
+      ```
+
+      此规范驱动测试编写——每个场景都会成为一个测试用例。
+    requires: []
+
+  - id: tests
+    generates: "tests/*.test.ts"
+    description: 在实现前编写的测试文件
+    template: test.md
+    instruction: |
+      在实现前编写测试（TDD 红阶段）。
+
+      文件命名：
+      - 测试文件命名为 `tests/<feature>.test.ts`
+      - 每个功能/能力对应一个测试文件
+      - 使用与规范一致的描述性名称
+
+      测试结构：
+      - 使用 Given/When/Then 格式，与规范场景保持一致
+      - 相关测试使用 `describe()` 分组
+      - 规范中的每个场景至少对应一个 `it()` 测试
+
+      覆盖要求：
+      - 覆盖规范中的每条需求
+      - 包含正常路径（成功案例）
+      - 包含边界情况（临界条件）
+      - 包含错误场景（非法输入、失败）
+      - 初始测试应失败（尚未实现）
+
+      Example:
+      ```typescript
+      describe('Password validation', () => {
+        it('accepts valid password with all requirements', () => {
+          // GIVEN a password meeting all requirements
+          const password = 'SecurePass1';
+          // WHEN validating
+          const result = validatePassword(password);
+          // THEN it should be accepted
+          expect(result.valid).toBe(true);
+        });
+
+        it('rejects password shorter than 8 characters', () => {
+          // GIVEN a short password
+          const password = 'Short1';
+          // WHEN validating
+          const result = validatePassword(password);
+          // THEN it should be rejected with message
+          expect(result.valid).toBe(false);
+          expect(result.error).toBe('Password too short');
+        });
+      });
+      ```
+
+      严格遵循规范需求——测试用于验证规范。
+    requires:
+      - spec
+
+  - id: implementation
+    generates: "src/*.ts"
+    description: 让测试通过的实现代码
+    template: implementation.md
+    instruction: |
+      实现功能以让测试通过（TDD 绿阶段）。
+
+      TDD 工作流：
+      1. 运行测试，确认失败（红）
+      2. 编写最少代码让一个测试通过
+      3. 运行测试，确认通过（绿）
+      4. 需要时重构，同时保持测试通过
+      5. 对下一个失败测试重复
+
+      实现准则：
+      - 为通过测试写最少代码——不多不少
+      - 频繁运行测试以验证进度
+      - 函数保持小而专注
+      - 使用清晰、可读的名称
+
+      代码组织：
+      - 在 `src/<feature>.ts` 中创建源文件
+      - 清晰导出公共 API
+      - 实现细节保持私有
+      - 为公共函数添加 JSDoc 注释
+
+      Example structure:
+      ```typescript
+      /**
+       * Validates a password meets security requirements.
+       * @param password - The password to validate
+       * @returns Validation result with valid flag and optional error
+       */
+      export function validatePassword(password: string): ValidationResult {
+        if (password.length < 8) {
+          return { valid: false, error: 'Password too short' };
+        }
+        // ... additional checks
+        return { valid: true };
+      }
+      ```
+
+      不要过度设计——只实现测试要求的内容。
+    requires:
+      - tests
+
+  - id: docs
+    generates: "docs/*.md"
+    description: 已实现功能的文档
+    template: docs.md
+    instruction: |
+      为已实现的功能编写文档。
+
+      Sections:
+      - **Overview**: 功能说明与存在原因（1-2 段）
+      - **Getting Started**: 可立即使用的快速上手指南
+      - **Examples**: 展示常见用例的代码示例
+      - **Reference**: 详细 API 文档与配置选项
+
+      Guidelines:
+      - 面向用户，而非开发者
+      - 从最常见用例开始
+      - 提供可复制粘贴的代码示例
+      - 记录所有配置项及其默认值
+      - 说明限制、边界情况与注意事项
+      - 链接相关功能或规范
+
+      Example structure:
+      ```markdown
+      ## Overview
+
+      Password validation ensures user passwords meet security requirements
+      before account creation or password changes.
+
+      ## Getting Started
+
+      Import and use the validation function:
+
+      ```typescript
+      import { validatePassword } from './password';
+
+      const result = validatePassword('MySecurePass1');
+      if (!result.valid) {
+        console.error(result.error);
+      }
+      ```
+
+      ## Examples
+
+      ### Basic validation
+      ...
+
+      ### Custom error handling
+      ...
+
+      ## Reference
+
+      ### validatePassword(password)
+
+      | Parameter | Type | Description |
+      |-----------|------|-------------|
+      | password | string | The password to validate |
+
+      **Returns**: `{ valid: boolean, error?: string }`
+      ```
+
+      需求参考规范，细节参考实现。
+    requires:
+      - implementation
+
+apply:
+  requires: [tests]
+  tracks: null
+  instruction: |
+    运行测试查看失败项。编写最少代码逐一通过。
+    重构时保持测试通过。

package/schemas/tdd/templates/docs.md

@@ -0,0 +1,15 @@
+## Overview
+
+<!-- 功能概述 -->
+
+## Getting Started
+
+<!-- 快速上手指南 -->
+
+## Examples
+
+<!-- 代码示例 -->
+
+## Reference
+
+<!-- API 参考或补充细节 -->

package/schemas/tdd/templates/implementation.md

@@ -0,0 +1,11 @@
+## Implementation Notes
+
+<!-- 技术实现细节 -->
+
+## API
+
+<!-- 公共 API 文档 -->
+
+## Usage
+
+<!-- 使用示例 -->

package/schemas/tdd/templates/spec.md

@@ -0,0 +1,11 @@
+## Feature: <!-- 功能名称 -->
+
+<!-- 功能描述 -->
+
+## Requirements
+
+<!-- 需求列表 -->
+
+## Acceptance Criteria
+
+<!-- 验收标准列表 -->

package/schemas/tdd/templates/test.md

@@ -0,0 +1,11 @@
+## Test Plan
+
+<!-- 描述测试策略 -->
+
+## Test Cases
+
+### <!-- 测试用例名称 -->
+
+- **Given:** <!-- 前置条件 -->
+- **When:** <!-- 操作 -->
+- **Then:** <!-- 预期结果 -->

package/scripts/postinstall.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall script for auto-installing shell completions
+ *
+ * This script runs automatically after npm install unless:
+ * - CI=true environment variable is set
+ * - OPENSPEC_NO_COMPLETIONS=1 environment variable is set
+ * - dist/ directory doesn't exist (dev setup scenario)
+ *
+ * The script never fails npm install - all errors are caught and handled gracefully.
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Check if we should skip installation
+ */
+function shouldSkipInstallation() {
+  // Skip in CI environments
+  if (process.env.CI === 'true' || process.env.CI === '1') {
+    return { skip: true, reason: 'CI environment detected' };
+  }
+
+  // Skip if user opted out
+  if (process.env.OPENSPEC_NO_COMPLETIONS === '1') {
+    return { skip: true, reason: 'OPENSPEC_NO_COMPLETIONS=1 set' };
+  }
+
+  return { skip: false };
+}
+
+/**
+ * Check if dist/ directory exists
+ */
+async function distExists() {
+  const distPath = path.join(__dirname, '..', 'dist');
+  try {
+    const stat = await fs.stat(distPath);
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect the user's shell
+ */
+async function detectShell() {
+  try {
+    const { detectShell } = await import('../dist/utils/shell-detection.js');
+    const result = detectShell();
+    return result.shell;
+  } catch (error) {
+    // Fail silently if detection module doesn't exist
+    return undefined;
+  }
+}
+
+/**
+ * Install completions for the detected shell
+ */
+async function installCompletions(shell) {
+  try {
+    const { CompletionFactory } = await import('../dist/core/completions/factory.js');
+    const { COMMAND_REGISTRY } = await import('../dist/core/completions/command-registry.js');
+
+    // Check if shell is supported
+    if (!CompletionFactory.isSupported(shell)) {
+      console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+      return;
+    }
+
+    // Generate completion script
+    const generator = CompletionFactory.createGenerator(shell);
+    const script = generator.generate(COMMAND_REGISTRY);
+
+    // Install completion script
+    const installer = CompletionFactory.createInstaller(shell);
+    const result = await installer.install(script);
+
+    if (result.success) {
+      // Show success message based on installation type
+      if (result.isOhMyZsh) {
+        console.log(`✓ Shell completions installed`);
+        console.log(`  Restart shell: exec zsh`);
+      } else if (result.zshrcConfigured) {
+        console.log(`✓ Shell completions installed and configured`);
+        console.log(`  Restart shell: exec zsh`);
+      } else {
+        console.log(`✓ Shell completions installed to ~/.zsh/completions/`);
+        console.log(`  Add to ~/.zshrc: fpath=(~/.zsh/completions $fpath)`);
+        console.log(`  Then: exec zsh`);
+      }
+    } else {
+      // Installation failed, show tip for manual install
+      console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+    }
+  } catch (error) {
+    // Fail gracefully - show tip for manual install
+    console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+  }
+}
+
+/**
+ * Main function
+ */
+async function main() {
+  try {
+    // Check if we should skip
+    const skipCheck = shouldSkipInstallation();
+    if (skipCheck.skip) {
+      // Silent skip - no output
+      return;
+    }
+
+    // Check if dist/ exists (skip silently if not - expected during dev setup)
+    if (!(await distExists())) {
+      return;
+    }
+
+    // Detect shell
+    const shell = await detectShell();
+    if (!shell) {
+      console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+      return;
+    }
+
+    // Install completions
+    await installCompletions(shell);
+  } catch (error) {
+    // Fail gracefully - never break npm install
+    // Show tip for manual install
+    console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+  }
+}
+
+// Run main and handle any unhandled errors
+main().catch(() => {
+  // Silent failure - never break npm install
+  process.exit(0);
+});