CorvidLabs/spec-sync
GitHub: CorvidLabs/spec-sync
一款将需求文档与源代码进行双向契约校验的规格驱动开发工具，确保文档与代码在 CI 中始终保持一致。
Stars: 5 | Forks: 0
# SpecSync
[](https://github.com/marketplace/actions/spec-sync)
[](https://corvidlabs.github.io/spec-sync/)
[](https://github.com/CorvidLabs/spec-sync/actions/workflows/ci.yml)
[](https://crates.io/crates/specsync)
[](https://crates.io/crates/specsync)
[](LICENSE)
**将需求转化为模块契约，当代码发生偏移时使 CI 失败——同时不丢失修复过程中的决策与证据。**
Rust · 单一二进制文件 · 33 种语言 · 无需 SpecSync API 密钥
[快速开始](#quick-start) · [完整 SDD 生命周期](#full-sdd-lifecycle) · [在线文档](https://corvidlabs.xyz/spec-sync/docs/) · [示例](#executable-examples) · [对比](#how-it-compares)
## 60 秒内完成契约变更
从 `specs/auth/requirements.md` 中的产品意图开始：
```
### REQ-auth-004
The system SHALL let a signed-in user revoke every active session.
```
将其提炼为 `specs/auth/auth.spec.md` 中的持久模块契约：
```
| Name | Kind | Description |
|---|---|---|
| `revoke_all_sessions` | function | Revokes every session owned by the current user. |
```
现在，某位开发者添加了第二个公共导出（public export）却未更新契约：
```
pub fn revoke_all_sessions(user_id: UserId) -> Result { /* ... */ }
pub fn revoke_session(session_id: SessionId) -> Result<(), SessionError> { /* new */ }
```
本地和 CI 中会运行相同的检查：
```
$ specsync check --strict
specs/auth/auth.spec.md
⚠ undocumented export `revoke_session`
1 warning treated as an error in strict mode
```
修复所保留的不仅仅是一份生成的文档：
```
requirements.md why the behavior exists and how success is judged
auth.spec.md the module/API contract checked against code
context.md decisions, constraints, and files the next agent needs
testing.md requirement-to-test evidence
CHG-*/ approved deltas, verification, and the delivery audit trail
```
添加缺失的契约行——或将该导出设为私有（private）——然后重新运行检查。CI 将变回绿色通过状态，同时需求、上下文、证据以及确切的契约变更依然可以在 Git 中进行审查。
[阅读对抗性证明](site/src/content/docs/comparisons/adversarial-proof.md)
## SpecSync 能捕获什么
SpecSync 会双向验证 Markdown 模块规格说明（`*.spec.md`）与源代码之间的一致性。
| 偏移 | 结果 |
|---|---|
| 代码导出了规格说明中未包含的内容 | 警告；在严格模式下会失败 |
| 规格说明记录了代码中缺失的导出 | 错误 |
| 被引用的源文件已被删除 | 错误 |
| 缺少必需的规格说明部分 | 错误 |
| 声明的依赖项不存在 | 错误 |
| 源文件引入了未声明的依赖 | 严格的依赖错误 |
| 文档中记录的数据库表或列缺失 | 错误 |
| schema 列未被记录或类型不匹配 | 警告 |
它还提供了一个经过验证的规格驱动开发（SDD）生命周期、覆盖率门槛、质量评分、依赖分析、跨项目引用、Git 钩子、编辑器集成以及原生代理（agent）工作流。
SpecSync 的核心是确定性的且在本地运行。它不需要托管的 SpecSync 服务、Corvid AI 账户、提供商密钥或嵌入式模型。Claude、Cursor、Codex、Gemini 和其他编程代理通过它们各自的权限使用相同的 CLI 和生命周期。
## 完整 SDD 生命周期
SpecSync 5.0 将交付过程作为版本化的变更工作区进行管理：
```
draft → approved → implementing → verifying → accepted → archived
```
```
specsync change new "Add passkeys" --spec auth --path src/auth.rs --json
specsync change answer CHG-0001-add-passkeys acceptance_criteria \
"A registered passkey authenticates the user" --json
specsync change approve CHG-0001-add-passkeys
specsync change start CHG-0001-add-passkeys
# 实现已批准的 contract 或 semantic delta
specsync check --strict
specsync change verify CHG-0001-add-passkeys
specsync change accept CHG-0001-add-passkeys
# 先 merge；在证明 delivery integration 后再 archive
specsync change archive CHG-0001-add-passkeys
```
批准是由人工进行、可移植的且与摘要绑定的。验证将测试证据绑定到确切的提交和工作树输入上。验收会原子性地更新标准的规格说明和需求。未提交的脏数据编辑会使证据失效，而不是静默地改变已验收的结果。
[阅读工作流指南](site/src/content/docs/workflow.md)或运行[完整生命周期示例](examples/sdd-lifecycle/)。
## 安装
### Cargo
```
cargo install specsync
```
### Homebrew
```
brew install CorvidLabs/tap/spec-sync
```
### GitHub Action
```
- uses: CorvidLabs/spec-sync@v5
with:
strict: 'true'
require-coverage: '100'
```
`@v5` 遵循兼容的 5.x Action 更新。固定 Action 和二进制文件以实现不可变安装：
```
- uses: CorvidLabs/spec-sync@v5.0.0
with:
version: '5.0.0'
```
### 预编译二进制文件
从 [GitHub Releases](https://github.com/CorvidLabs/spec-sync/releases) 下载 macOS、Linux 或 Windows 的二进制文件。
## 快速开始
```
# 初始化配置和已验证的 lifecycle
specsync init
# Scaffold 一个 module contract 和配套文件
specsync add-spec auth
# 在两个方向上验证 contract ↔ code
specsync check --strict
# 测量覆盖率与 spec 质量
specsync coverage
specsync score --all
# 安装原生 coding-agent workflows 和 Git hooks
specsync agents install
specsync hooks install
```
对于现有的 4.x 项目，请使用[配置](site/src/content/docs/configuration.md)和[工作流](site/src/content/docs/workflow.md)指南中描述的引导式迁移与采用流程。
## 规格说明与配套文件
每个模块在其旁边保留一个可执行的契约和集中的上下文：
```
specs/auth/
├── auth.spec.md validated module contract
├── requirements.md stable requirements and acceptance criteria
├── tasks.md active work, roadmap, and test debt
├── context.md architectural decisions and current state
└── testing.md automated, manual, and edge-case evidence
```
| 产物 | 持久职责 |
|---|---|
| `*.spec.md` | 源文件、公共 API、不变量、行为、错误、依赖项以及变更历史 |
| `requirements.md` | 稳定的 `REQ-*` 标识、规范的 SHALL 语句以及验收标准 |
| `tasks.md` | 待办工作；需求不是复选框 |
| `context.md` | 决策、约束、关键文件以及交接状态 |
| `testing.md` | 需求可追溯性、自动化覆盖率、手动 QA 以及对抗性用例 |
| `.specsync/changes/CHG-*` | 拟议的变更增量、批准、验证以及结案证据 |
[阅读完整的规格说明格式](site/src/content/docs/spec-format.md)、[配套文件参考](site/src/content/docs/companion-files.md)和[工作流约定](site/src/content/docs/workflow.md)。
## 文档
| 从这里开始 | 参考与集成 |
|---|---|
| [为什么选择 SpecSync？](site/src/content/docs/why-specsync.md) | [CLI 参考](site/src/content/docs/cli.md) |
| [快速开始](site/src/content/docs/quickstart.md) | [配置](site/src/content/docs/configuration.md) |
| [工作流指南](site/src/content/docs/workflow.md) | [规格说明格式](site/src/content/docs/spec-format.md) |
| [配套文件](site/src/content/docs/companion-files.md) | [语言注册表](site/src/data/languages.json) |
| [架构](site/src/content/docs/architecture.md) | [跨项目引用](site/src/content/docs/cross-project-refs.md) |
| [AI 与编程代理](site/src/content/docs/integrations/ai-agents.md) | [GitHub Action](site/src/content/docs/integrations/github-action.md) |
| [在线文档中心](https://corvidlabs.xyz/spec-sync/docs/) | [VS Code 扩展](site/src/content/docs/integrations/vscode-extension.md) |
## 可执行示例
这些示例会创建临时项目并运行真实的 CLI：
- [完整的 SDD 生命周期](examples/sdd-lifecycle/)
- [五个演进中的产品史诗](examples/sdd-five-epics/)
- [有序的并发变更](examples/sdd-concurrent-changes/)
- [CI 门槛](site/src/content/examples/ci-gate.mdx)
- [多语言项目](site/src/content/examples/polyglot.mdx)
- [Rust 工作区](site/src/content/examples/rust-workspace.mdx)
## 差异对比
SpecSync 可以独立运行，也可以作为规划型工具下方的执行层来强制实施约束：
- [SpecSync vs. Spec Kit](site/src/content/docs/comparisons/spec-kit.md)
- [SpecSync vs. OpenSpec](site/src/content/docs/comparisons/openspec.md)
- [同时使用 SpecSync、Spec Kit 和 OpenSpec](site/src/content/docs/comparisons/using-together.md)
- [对抗性检测与知识保留证明](site/src/content/docs/comparisons/adversarial-proof.md)
## 支持的语言
SpecSync 会自动检测 33 种语言的源文件和公共导出：
TypeScript/JavaScript、Rust、Go、Python、Swift、Kotlin、Java、C#、Dart、PHP、Ruby、YAML、C、C++、Scala、Crystal、Nim、Erlang、Elixir、Perl、Common Lisp、Scheme、Emacs Lisp、Haskell、Lua、R、OCaml、Groovy、F#、Clojure、D、Objective-C、Bash、PowerShell 和 Vala。
请查看 12 种代表性技术栈的[详细语言配置文件](site/src/data/languages.json)，以及涵盖所有 33 个语系的精确支持、导出检测和测试排除规则的[提取器源码](src/exports/)。
## 贡献
欢迎提交贡献。请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，运行相关测试，并保持规格说明与公共行为同步。
安全问题应遵循 [SECURITY.md](SECURITY.md) 中的指引进行处理，而不是提交为公开 issue。
## 许可证
MIT — 详见 [LICENSE](LICENSE)。