1. 概述

在 .claude/scripts/ 中实现 Python 3.12 版 OpenSpec 核心工具，统一入口为：

uv run python .claude/scripts/openspec.py ...

该工具用于替换 .claude/commands/ 和 .claude/skills/ 中对 openspec-cn CLI 的调用。

本次实现覆盖当前 commands/skills 实际使用的核心命令：

• list
• new change
• status
• instructions

工具仅支持从当前工作目录向上查找最近的 openspec/ 目录，不支持 OpenSpec 的全局 Store 注册和 --store 参数。

实现应保持现有提示依赖的核心 JSON 字段兼容，并采用模块化结构，为后续扩展其他 OpenSpec 命令保留空间。

2. 实现设计

2.1 代码结构

在 .claude/scripts/ 下提供单一可执行入口，并将具体职责拆分到内部 Python 包：

.claude/scripts/
├── openspec.py
└── openspec_py/
    ├── __init__.py
    ├── cli.py
    ├── models.py
    ├── schema.py
    └── service.py

各模块职责如下：

• openspec.py：CLI 启动入口。
• cli.py：参数解析、命令分发、文本及 JSON 输出。
• models.py：工作流 schema、artifact、项目配置和根目录数据模型。
• schema.py：内置 schema、项目自定义 schema 和配置加载。
• service.py：根目录发现、变更管理、状态计算和指令生成。

2.2 Python 编码规范

• 使用 Python 3.12。
• 使用 uv 管理运行环境和依赖。
• 使用标准库 argparse 实现 CLI，不额外引入 CLI 框架。
• 使用 pathlib 处理路径。
• 使用 dataclasses 表达内部模型。
• 使用完整类型标注。
• 使用 PyYAML 解析项目配置、change metadata 和自定义 schema。
• 遵循仓库现有 Ruff lint 和 format 配置。
• JSON 输出使用 UTF-8，并保留中文字符。

3. 命令行为

3.1 list

uv run python .claude/scripts/openspec.py list [--sort recent|name] [--json]

行为：

• 从当前目录向上查找最近的 openspec/。
• 扫描 openspec/changes/ 下的活动变更目录。
• 忽略 archive/ 目录。
• 支持按修改时间或名称排序。
• JSON 输出包含 changes 和本地 root 信息。

3.2 new change

uv run python .claude/scripts/openspec.py new change <name> \
  [--schema NAME] \
  [--description TEXT] \
  [--goal TEXT] \
  [--json]

行为：

• change 名称必须使用 lowercase kebab-case。
• 名称必须以小写字母开头。
• 不允许空格、下划线、大写字母、连续连字符或数字开头。
• 创建 openspec/changes/<name>/。
• 创建 .openspec.yaml，记录 schema 和可选 goal。
• 提供 description 时创建 README.md。
• 如果同名 change 已存在，则拒绝覆盖。

3.3 status

uv run python .claude/scripts/openspec.py status \
  --change NAME \
  [--schema NAME] \
  [--json]

行为：

• 加载 change 选择的工作流 schema。
• 根据 artifact 输出路径和依赖关系计算状态。
• artifact 状态包括：
  • done：对应文件已经存在。
  • ready：文件不存在，但依赖已经完成。
  • blocked：文件不存在，且存在未完成依赖。
• 支持普通文件路径和 glob 输出路径，例如 specs/**/*.md。

核心 JSON 字段包括：

• changeName
• schemaName
• isComplete
• applyRequires
• artifacts
• artifactPaths
• planningHome
• changeRoot
• actionContext
• root

3.4 instructions

uv run python .claude/scripts/openspec.py instructions [ARTIFACT] \
  --change NAME \
  [--schema NAME] \
  [--json]

普通 artifact 指令包含：

• context：项目上下文。
• rules：artifact 专属规则。
• template：artifact 模板。
• instruction：创建指导。
• resolvedOutputPath：目标文件路径或模式。
• dependencies：已完成依赖 artifact 的文件路径。

如果没有指定 artifact，则选择当前第一个 ready artifact。

Apply 指令

uv run python .claude/scripts/openspec.py instructions apply \
  --change NAME \
  --json

Apply 指令额外返回：

• state
  • blocked：缺少实施前置 artifact。
  • ready：可以继续实现任务。
  • all_done：所有任务已经完成。
• contextFiles：全部 artifact 对应的实际上下文文件。
• tasks：从 Markdown 复选框解析出的任务列表。
• progress：总数、已完成数和剩余数。
• actionContext：读取和写入范围。

任务使用以下 Markdown 格式解析：

- [ ] 未完成任务
- [x] 已完成任务

4. Schema 设计

4.1 内置 spec-driven Schema

默认工作流包含以下 artifact：

proposal
   ├── specs
   └── design
          └── tasks

实际依赖关系：

• proposal：无依赖，输出 proposal.md。
• specs：依赖 proposal，输出 specs/**/*.md。
• design：依赖 proposal，输出 design.md。
• tasks：依赖 specs 和 design，输出 tasks.md。
• apply.requires：tasks。

内置 schema 同时提供 proposal、specs、design 和 tasks 的默认 Markdown 模板。

4.2 项目自定义 Schema

项目可以通过以下目录定义自定义工作流：

openspec/schemas/<name>/
├── schema.yaml
└── templates/
    ├── <artifact-id>.md
    └── ...

示例：

name: rapid
description: Rapid workflow

artifacts:
  - id: plan
    output: plan.md
    instruction: Write the plan.

  - id: tasks
    output: tasks.md
    requires:
      - plan
    instruction: Write implementation tasks.

apply:
  requires:
    - tasks

加载自定义 schema 时应校验：

• artifacts 列表不能为空。
• 每个 artifact 必须声明 id 和 output。
• artifact 依赖必须引用已声明的 artifact。
• artifact 依赖图不能存在循环。
• apply.requires 必须引用已声明的 artifact。

5. 项目配置

项目配置来源为：

openspec/config.yaml

支持以下字段：

schema: spec-driven

context: |
  Project-specific development context.

rules:
  proposal:
    - Keep proposals concise
  tasks:
    - Every task must be independently verifiable

Change 可以在以下文件中覆盖 schema：

openspec/changes/<name>/.openspec.yaml

示例：

schema: rapid
goal: Deliver a small fix quickly

6. 错误处理与输出契约

6.1 JSON 模式

使用 --json 时：

• stdout 只输出一个完整 JSON 文档。
• 不向 stderr 输出普通诊断信息。
• 失败时使用非零退出码。
• 错误输出包含稳定的 status 数组。

示例：

{
  "status": [
    {
      "level": "error",
      "code": "FileNotFoundError",
      "message": "Unknown change: add-auth"
    }
  ]
}

6.2 文本模式

未使用 --json 时：

• 正常结果输出到 stdout。
• 错误信息输出到 stderr。
• 失败时返回非零退出码。

7. Commands 和 Skills 迁移

需要更新以下目录中的 Markdown 文件：

.claude/commands/opsx/
.claude/skills/openspec-*/

迁移规则：

• 将所有 openspec-cn 调用替换为 Python CLI。
• 将 compatibility 更新为需要 Python 3.12 和 uv。
• 删除 Store 发现、Store ID 和 --store 相关说明。
• 明确工具仅发现最近的本地 openspec/ 根目录。
• archive 和 sync 仍由 Agent 按 Markdown 工作流直接操作文件，仅使用 Python CLI 获取 list/status 信息。

8. 测试计划

8.1 根目录发现

• 当前目录包含 openspec/。
• 祖先目录包含 openspec/。
• 找不到 openspec/ 时返回稳定错误。

8.2 Change 管理

• 创建合法 change。
• 拒绝非法名称。
• 拒绝覆盖已有 change。
• 正确写入 schema、goal 和 description。
• 正确列出并排序活动 change。

8.3 状态计算

• 空 change 的 ready/blocked 状态。
• 部分 artifact 已完成。
• 所有 apply 前置 artifact 已完成。
• glob 型 specs 路径识别。
• 缺失依赖和未知 schema 错误。

8.4 Instructions

• 返回模板、context 和 rules。
• 返回依赖 artifact 文件路径。
• 自动选择第一个 ready artifact。
• Apply 状态覆盖 blocked、ready 和 all_done。
• 正确解析任务复选框和进度。

8.5 自定义 Schema

• 加载有效项目 schema。
• 拒绝未知依赖。
• 拒绝循环依赖。
• 拒绝无效 apply.requires。

8.6 Prompt 迁移检查

• .claude/commands/ 和 .claude/skills/ 中不再出现 openspec-cn。
• 不再出现 store list 或 --store。
• 所有调用统一使用仓库内 Python CLI。

9. 验证命令

uv sync
uv run python -m pytest tests/test_openspec_script.py -q
uv run python -m ruff check .claude/scripts tests/test_openspec_script.py
uv run python -m ruff format --check .claude/scripts tests/test_openspec_script.py
uv run python .claude/scripts/openspec.py list --json

10. 范围与假设

• 本工具兼容当前 skills 依赖的核心行为，不逐字段复刻完整上游 OpenSpec CLI。
• 当前不实现 show、validate、archive、doctor、context、store 和完整 schema 管理命令。
• 不依赖 Node.js、npm、网络或系统级 OpenSpec 安装。
• 内置 schema 和模板随 Python 源码版本化。
• 后续命令应复用现有根目录解析、schema 加载、JSON 输出和错误处理能力进行扩展。