1. 概述在.claude/scripts/中实现 Python 3.12 版 OpenSpec 核心工具统一入口为uv run python .claude/scripts/openspec.py...该工具用于替换.claude/commands/和.claude/skills/中对openspec-cnCLI 的调用。本次实现覆盖当前 commands/skills 实际使用的核心命令listnew changestatusinstructions工具仅支持从当前工作目录向上查找最近的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.pyCLI 启动入口。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.1listuv run python .claude/scripts/openspec.py list[--sort recent|name][--json]行为从当前目录向上查找最近的openspec/。扫描openspec/changes/下的活动变更目录。忽略archive/目录。支持按修改时间或名称排序。JSON 输出包含changes和本地root信息。3.2new changeuv run python .claude/scripts/openspec.py new changename\[--schema NAME]\[--description TEXT]\[--goal TEXT]\[--json]行为change 名称必须使用 lowercase kebab-case。名称必须以小写字母开头。不允许空格、下划线、大写字母、连续连字符或数字开头。创建openspec/changes/name/。创建.openspec.yaml记录 schema 和可选 goal。提供 description 时创建README.md。如果同名 change 已存在则拒绝覆盖。3.3statusuv run python .claude/scripts/openspec.py status\--changeNAME\[--schema NAME]\[--json]行为加载 change 选择的工作流 schema。根据 artifact 输出路径和依赖关系计算状态。artifact 状态包括done对应文件已经存在。ready文件不存在但依赖已经完成。blocked文件不存在且存在未完成依赖。支持普通文件路径和 glob 输出路径例如specs/**/*.md。核心 JSON 字段包括changeNameschemaNameisCompleteapplyRequiresartifactsartifactPathsplanningHomechangeRootactionContextroot3.4instructionsuv run python .claude/scripts/openspec.py instructions[ARTIFACT]\--changeNAME\[--schema NAME]\[--json]普通 artifact 指令包含context项目上下文。rulesartifact 专属规则。templateartifact 模板。instruction创建指导。resolvedOutputPath目标文件路径或模式。dependencies已完成依赖 artifact 的文件路径。如果没有指定 artifact则选择当前第一个readyartifact。Apply 指令uv run python .claude/scripts/openspec.py instructions apply\--changeNAME\--jsonApply 指令额外返回stateblocked缺少实施前置 artifact。ready可以继续实现任务。all_done所有任务已经完成。contextFiles全部 artifact 对应的实际上下文文件。tasks从 Markdown 复选框解析出的任务列表。progress总数、已完成数和剩余数。actionContext读取和写入范围。任务使用以下 Markdown 格式解析- [ ] 未完成任务 - [x] 已完成任务4. Schema 设计4.1 内置spec-drivenSchema默认工作流包含以下 artifactproposal ├── specs └── design └── tasks实际依赖关系proposal无依赖输出proposal.md。specs依赖proposal输出specs/**/*.md。design依赖proposal输出design.md。tasks依赖specs和design输出tasks.md。apply.requirestasks。内置 schema 同时提供 proposal、specs、design 和 tasks 的默认 Markdown 模板。4.2 项目自定义 Schema项目可以通过以下目录定义自定义工作流openspec/schemas/name/ ├── schema.yaml └── templates/ ├── artifact-id.md └── ...示例name:rapiddescription:Rapid workflowartifacts:-id:planoutput:plan.mdinstruction:Write the plan.-id:tasksoutput:tasks.mdrequires:-planinstruction:Write implementation tasks.apply:requires:-tasks加载自定义 schema 时应校验artifacts 列表不能为空。每个 artifact 必须声明id和output。artifact 依赖必须引用已声明的 artifact。artifact 依赖图不能存在循环。apply.requires必须引用已声明的 artifact。5. 项目配置项目配置来源为openspec/config.yaml支持以下字段schema:spec-drivencontext:|Project-specific development context.rules:proposal:-Keep proposals concisetasks:-Every task must be independently verifiableChange 可以在以下文件中覆盖 schemaopenspec/changes/name/.openspec.yaml示例schema:rapidgoal:Deliver a small fix quickly6. 错误处理与输出契约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. 验证命令uvsyncuv run python-mpytest tests/test_openspec_script.py-quv run python-mruff check .claude/scripts tests/test_openspec_script.py uv run python-mruffformat--check.claude/scripts tests/test_openspec_script.py uv run python .claude/scripts/openspec.py list--json10. 范围与假设本工具兼容当前 skills 依赖的核心行为不逐字段复刻完整上游 OpenSpec CLI。当前不实现show、validate、archive、doctor、context、store和完整 schema 管理命令。不依赖 Node.js、npm、网络或系统级 OpenSpec 安装。内置 schema 和模板随 Python 源码版本化。后续命令应复用现有根目录解析、schema 加载、JSON 输出和错误处理能力进行扩展。
