OSpec
把模糊需求变成可验证的目标循环：规划、执行、验证，规范与证据全部留在你的仓库里，兼容主流 AI 编码代理。
- Star 数
- ★ 391
- 最近更新
- 1 个月前
- License
- MIT
- 主语言
- JavaScript
- FA 评分
- 50/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 使用 Claude Code 或 Codex 的开发者，希望需求、计划和验证证据留在仓库而非聊天记录中以便审查
- 不适合
- 没有原生 subagent 能力的 IDE 或终端环境，控制器派发会直接失败
- 不愿让 OSpec 写入 .claude/settings.json 等宿主配置的团队
- 只想在聊天里随手改代码、不需要仓库内规格与证据留痕的个人
- 源码审查
- 50/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
OSpec（官方 CLI 包为 @clawplays/ospec-cli，命令为 ospec）是一个面向 AI 编码代理的规范驱动工作流框架。它解决的核心问题是：只存在于聊天记录中的需求难以审查、验收和归档。OSpec 把一次请求落成仓库中的文件——提案、设计、计划、任务、评审与验证证据，使任何助手（Claude Code、Codex/GPT、Gemini、OpenCode 或纯 CLI）都能从上次中断处继续。它提供两条主流程：轻量的 ospec change 快速变更流（proposal → tasks → 实现 → verification → review），以及重型的 ospec goal 工作流，后者带任务图控制器、并行 worker 调度、独立评审门禁与持久化证据。项目以 TypeScript 编写，通过 npm 全局安装，文档语言支持 en-US、zh-CN、ja-JP 和 ar。
运行三步流程：1) ospec init 在项目目录创建协议外壳（根 .skillrc、README.md、.ospec/ 目录，含 changes/active、changes/archived、SKILL.md、for-ai 指导和基线项目文档）；2) ospec change <name> 或 ospec goal <name> 创建并推进变更，读取并生成 proposal.md、tasks.md、design.md、implementation-plan.md、task-graph.json 等工件；ospec execute dispatch/launch/complete 调度原生子代理（Codex 用 spawn_agent，Claude Code 用后台 Task 轮询，Gemini 用 @generalist，OpenCode 用 @mention），ospec loop tick 发出带执行者溯源的评审，ospec execute verify 记录测试证据；3) ospec verify + ospec finalize 验收后归档变更并刷新索引和特性目录。另有 ospec session 生成会话简报、ospec docs obligations 管理文档义务、ospec brainstorm/plan 提供变更前辅助、ospec update 迁移旧项目。
- 使用 Claude Code 或 Codex 的开发者，希望需求、计划和验证证据留在仓库而非聊天记录中以便审查
- 团队需要把一个较大或高风险的重构拆成带评审门禁和并行 worker 的完整 Goal 工作流
- 维护多语言文档（en-US/zh-CN/ja-JP/ar）的项目，想让生成的规范与变更文档保持统一语言
- 项目依赖人类维护的架构/API 文档，希望归档时自动刷新特性目录并强制文档义务（warn 或 strict 模式）
- 多会话或多人接手的项目，需要 ospec session 简报和持久化的任务图状态让新会话直接续做
如何安装或部署这个 Agent？
需 Node.js 18+ 和 npm 8+。运行：npm install -g @clawplays/ospec-cli，然后用 ospec --help 验证安装。
如何使用这个 Agent？
1) 在项目目录运行 ospec init .（可加 --summary、--tech-stack、--architecture、--document-language）；2) 创建变更：ospec change fix-login-timeout . 或启动完整 Goal：ospec goal improve-checkout --target codex --execution-model controller --harness-interactive true --native-subagents supported；3) 部署/测试/QA 通过后运行 ospec verify changes/active/<change-name> 和 ospec finalize changes/active/<change-name> 归档。在 Claude Code 中可用自然语言提示（如“OSpec, initialize this project”）或技能命令（/ospec、/ospec-change、/ospec-goal）。升级后运行 ospec update 刷新托管文件。
这个 Agent 有哪些优点和局限？
- 规范、任务、评审与验证证据以文件形式持久化在仓库中，任何支持的助手都能续接，避免上下文锁死在单一工具的聊天里
- Goal 工作流内置确定性的规划预检、一次独立合并规划评审、分组修复收敛守卫和冲突安全的并行执行，减少无限循环
- 子代理调度采用有界等待（单次轮询 ≤60 秒）、心跳与租约机制，会话丢失后可用 ospec loop recover --force 恢复
- 文档义务与特性目录机制（ospec:feature 定位注释、ospec docs locate/audit）把代码变更与人类维护文档的可追溯性绑定
- 完整 Goal 工作流概念较多（任务图、租约、心跳、令牌预算、allowlist 等），学习与运维成本不低
- 依赖当前 IDE/ harness 提供原生子代理能力：若无原生子代理，可执行调度会阻塞且不会回退到其他代理 CLI
- Claude Code 硬执行 hooks 需一次性运行 ospec session hook --target claude --apply 并写入 .claude/settings.json，属于侵入性配置
- 新嵌套目录布局与旧扁平归档并存，旧项目需要 ospec update 或 ospec layout migrate --to nested 显式迁移
这个 Agent 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| OSpec 当前 | 50 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 391 | 1 个月前 | JavaScript | Codex · Claude Code |
| ZCF - 零配置代码流程 | 51 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 6.1k | 今天 | TypeScript | Codex · Claude Code |
| Smart Ralph | 73 · 存在缺口 | Agent 插件 / 技能免费 + 模型费 | ★ 562 | 1 个月前 | Shell | Codex · Claude Code |
| CoCo Super Intelligence | 69 · 存在缺口 | Agent 插件 / 技能免费 + 模型费 | ★ 785 | 今天 | Python | Codex · Claude Code |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示强制归档需要双重标志、确切名称确认与审计理由，且必需决策会阻塞实现（user_confirmation=2）；发布工作流权限收敛为 contents:read 加 id-token:write 且有版本核对（dependency_security=2，运行时依赖仅 js-yaml/semver）。扣分点：产品会写 .claude/settings.、派生子代理并执行任意 verify 命令，但未提供最小权限说明或权限清单（least_privilege=1）；数据流仅以叙述形式描述，无静态可核对的数据边界（data_flow_transparency=1）；未说明敏感数据（如 diff、验证输出）如何处理（sensitive_data_handling=1）；对外效果（hooks、worktree、子代理派生）描述多但风险边界少（external_effects=1）；hook 声称幂等可逆、update 迁移存在，但无回滚命令或恢复路径文档（rollback=1）；作者与仓库链接存在但发布者未经核实，来源归属仅为自我声明（source_attribution=1）。
失败行为有具体描述：无法提供原生子代理时 dispatch 明确失败、修复循环有收敛保护、重复失败即停止（failure_messages=2）；运行时依赖只有两个成熟库，可用性风险低（dependency_availability=2）。扣分点：README（且被截断）包含大量无法静态验证的行为断言，各文件间无测试或代码佐证其一致性（self_consistency=1）。
目标受众（AI 编码代理用户）与场景（变更/目标工作流）描述清晰，支持四种代理平台与四种文档语言（audience_and_scenarios=2）；明确列出能力边界：60 秒轮询上限、无原生子代理时不回退启动其他 CLI、并发回退值为 3（capability_boundaries=2）；skill 触发词与 CLI 命令区分明确（trigger_precision=2）；Node 18+/npm 8+ 与多平台适配说明充分（environment_fit=2）。整体因缺乏代码级验证各留一档，不给满分。
仓库结构（.ospec/ 布局、归档路径、嵌套布局迁移）在文档中组织良好（information_architecture=2）；安装步骤、验证方式（ospec --help）与 ospec update 说明完整（install_notes=2）；命名别名（ospec new/ospec change、CLI 简写路径）有明确兼容说明（naming_stability=2）；提供大量 CLI 与提示词示例及文档链接（examples_and_faq=2）；LICENSE 文件为标准 MIT（license=3）。扣分点：未见 CHANGELOG 或已知限制清单（known_limitations=1、versioning_changelog=1，虽有 tag-版本核对机制）；发布者为未经验证的第三方，维护责任仅有 issues 链接与作者邮箱（maintenance_responsibility=1）。
输出为仓库内结构化工件（索引、状态、紧凑 JSON、证据包），可直接被后续会话或审计使用（output_usability=2）；相对纯聊天历史的需求管理，提供了可检入仓库的可验证目标循环，边际价值有文档支撑（marginal_value=2）。扣分点：成本收益仅有 token 预算与指标文件的描述，无静态可验证的实际收益数据（cost_benefit=1）。
声明附有文档链接、feature 定位注释与归档可追溯性机制，主张可指向具体文件（claim_traceability=2）；行为断言与执行效果区分清楚，如 'launch 写 launch-plan.md，不自行启动 worker'（fact_inference_separation=2）。扣分点：仅有静态文件，npm 下载数、发布状态、hook 实际行为等无法跨来源核实（cross_source_corroboration=1）。
- 静态审查未执行任何命令：README 中的大量行为断言（hook 阻断、子代理调度、收敛保护）未经运行验证，置信度为低。
- ospec session hook 会修改 .claude/settings. 并注册工具级钩子，使用前应人工审查写入内容并保留备份。
- 产品会执行用户提供的 verify 命令并派生子代理，属于较高权限的代理工作流，建议在隔离或受控环境中首次试用。
- 发布者身份未经企业注册表核实，安装 @clawplays/ospec-cli 前请自行核对 npm provenance 与仓库一致性。
- 未发现 CHANGELOG 与明确已知限制清单，升级（ospec update 涉及文件迁移与重排）前应提交并备份仓库。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
2.1.0 2.1.0 - categorised doc bindings, coverage/bind/retire pipelines, and a generated docs map
发布说明摘录
OSpec 2.1.0 extends the living-documentation engine from docs/features/ to every documentation category. Bindings can now be declared in docs/api/, docs/design/ and docs/project/ with <!-- ospec:doc <slug> code:... --> (same syntax and slug namespace as ospec:feature), and every binding carries a kind inferred from its path. Obligations become kind-aware: api sections follow the behaviour table, design decisions verify as verify_decision (still holds, or mark Superseded), project overviews verify as verify_structure, and planning/product documents stay reference-only. New onb …在 GitHub 查看 ↗ -
2.0.2 2.0.2 - feature-catalog links that actually resolve
发布说明摘录
OSpec 2.0.2 fixes the generated docs/project/feature-catalog.md so its links work: heading anchors keep Unicode (CJK headings no longer anchor to an empty fragment), and hrefs resolve through the project layout (nested-layout projects no longer link through a doubled .ospec/). No breaking changes. After upgrading, run ospec index build in each project — the catalogue regenerates with working links; no re-migration is needed. Fixed …在 GitHub 查看 ↗ -
2.0.1 2.0.1 - localized migration drafts, index freshness, and a js-yaml security bump
发布说明摘录
OSpec 2.0.1 fixes three defects found while migrating real projects to 2.0, and bumps js-yaml past a CPU-exhaustion advisory. No breaking changes; upgrade with npm install -g @clawplays/[email protected] and re-run ospec update in each project to refresh the protocol documents. Fixed - ospec docs migrate --plan now writes its draft-skeleton guidance in the project's documentLanguage (zh-CN, ja-JP, ar, en-US) instead of hardcoded English, following the same rule as the feature catalogue and the obligation copy. The status: draft line and the ospec:migration-draft marker stay mach …在 GitHub 查看 ↗