内容
# Sembl
[](https://pypi.org/project/sembl/)
[](https://pypi.org/project/sembl/)
[](LICENSE)
**用于 AI 编程代理的确定性责任网关。**
Sembl 检查 AI 编程代理**实际更改**的内容是否符合变更预期范围——它可以触及哪些文件，哪些文件不能触及，以及 diff 大小可能达到多少——以及它是否对触及或测试的内容撒谎。它在代理**之后**和人类**之前**批准运行，并返回单一判决：**PASS / WARN / BLOCK**。
```text
声明范围 + 代理的实际 diff -> sembl verify -> PASS / WARN / BLOCK
```
检查是**确定性**的（循环中没有 LLM），**执行器中立**的（Cursor、Claude Code、Codex、Aider、OpenCode — Sembl 绝不会看到代理），并且**免费在 CI 中运行**。相同的输入，相同的判决，每次都是如此。
[网站](https://sembl.vercel.app) | [PyPI](https://pypi.org/project/sembl/) | [问题](https://github.com/speedvibecode/sembl/issues)
> Sembl 是**网关**。如果您想要整个流程——spec → bounds → executor → gate → merge，每个阶段都可互换，每个制品都经过记录——那就是 **[sembl-stack](https://github.com/speedvibecode/sembl-stack)** （[站点](https://sembl-stack.vercel.app)），它在核心运行此网关。
## 为什么
AI 代理是强大的执行者。差距不再是编写代码——而是**在不阅读每一行代码的情况下信任代理所做的事情**。随着代理变得更加自主，人类审查减少，您需要一个可重复的、机械的检查，以确保更改保持在其声明的范围内，并且没有伪造其结果。
Sembl **执行以下操作**：确定性地捕获 diff 中的客观、可检查的问题——超出范围的编辑、禁止区域的编辑、代理**声称**更改但实际上未更改的文件，以及“测试通过”的声明但无证据。
Sembl **不执行以下操作**：它不使代理更智能，也不判断代码质量或可维护性。那是审查者的工作，LLM 审查者也同样擅长——因此这不是 Sembl 的主张。Sembl 的优势很窄也很诚实：**确定性，零成本和可审计性**——一个可以在 CI 中运行的网关，每次都给出相同的答案，并且没有人可以反驳。
## 工作原理
1. **声明变更范围**——可以编辑的文件、不能触及的区域，以及（可选）大小预算。使用您已经使用的工具生成（参见 [声明范围](#declaring-bounds-bring-your-own)）。
2. **您的代理执行工作。**
3. **`sembl verify`** 将实际的 git diff 与范围进行比较，并返回 PASS / WARN / BLOCK。 使用 `--report`，它还会交叉检查代理自己的成功报告，并标记伪造的文件声明和无证据的测试通过。
```powershell
pip install sembl
# 在您的代理编辑存储库之后：
sembl verify --wo-file bounds.json --report agent-report.json
```
```text
sembl verify — BLOCK
已更改的文件 7
范围（超出范围） infra/deploy.yaml
禁止命中 无
伪造声明 src/payments/refund.ts
验证证据 缺失：pytest
变更与预算 7 个文件 > 6
原因 • 伪造声明（报告但未更改）：src/payments/refund.ts
• 超出范围的编辑：infra/deploy.yaml
```
退出代码：`PASS=0`，`WARN=0`（或 `--strict` 为 `1`），`BLOCK=1`。添加 `--json` 以获取 CI 中机器可读的输出。
## 声明范围（自带）
`verify` 读取一个小的、便携的合约。**只有四个字段很重要**——任何可以发出它们的工具都可以驱动网关：
```json
{
"editable_paths": ["src/auth/"],
"forbidden_areas": ["migrations/", "infra/"],
"churn_budget": { "max_files": 6, "max_lines": 200 }
}
```
您可以随意生成它：
- **从规划工具（推荐）。** `sembl bounds` 将上游工具已经编写的内容转换为边界文件：
```bash
sembl bounds --spec-kit specs/001-feature --out bounds.json # GitHub Spec Kit
sembl bounds --from kiro|tessl|agents-md|cursor-rules # 其他预设
sembl bounds --config adapter.json # 自定义（声明式）
```
Spec Kit 的 `tasks.md` （和其他工具的制品）已经命名了每个任务的**确切文件路径**——这些可以直接映射到 `editable_paths`。使用规划器来决定*要构建什么*；使用 Sembl 来验证代理*是否停留在这些行中*。添加新工具只需一个配置项，而不是代码——请参见
[`docs/integrations.md`](docs/integrations.md)。
- **手动。** 自己编写这四个字段。这是一个普通的 JSON 文件。
- **`sembl generate` （测试版，可选）。** Sembl 还可以生成一个更完整的 Work Order JSON，`verify` 直接读取 - 请参见
[测试版：工作订单生成](#beta-work-order-generation)。这是可选的，并且可以互换使用上述工具。
## `verify` 检查的内容（全部确定性）
| 检查 | 信号 | 判决 |
|-------|--------|---------|
| **范围** | 已更改的文件超出 `editable_paths` | 超出范围（严格模式下 BLOCK，否则 WARN） |
| **禁止** | 已更改的文件位于 `forbidden_areas` 内 | **BLOCK** |
| **伪造** | 报告声称文件已更改，但 diff 未显示 | **BLOCK** |
| **验证证据** | 报告称测试/检查通过，但无退出代码或输出支持 | WARN |
| **变更** | diff 超出 `max_files` / `max_lines` | WARN |
测试始终允许与范围内编辑一起进行。判决汇总为 BLOCK（硬合同违约），WARN（软信号）或 PASS（干净）。 `--strict` 使 WARN 在 CI 网关中成为失败的退出代码。
执行器报告（ `--report` 文件）是 JSON 执行器或您的控制工具生成的；Sembl 绝不会信任它——它只用它来捕获与实际 diff 的**矛盾**。识别常见形状（`files_modified`、`changes[]`、`tests_passed`、`checks[]` 列表等）。
## 在 CI 中进行网关
`verify`可以直接评估 PR 的 diff——无需工作树检出——因此它作为一个硬网关进入 CI。用 `--diff` （或 `--diff -` 表示 stdin）为其提供补丁：
```bash
git diff origin/main...HEAD | sembl verify --wo-file bounds.json --diff - --strict
```
或在每个拉取请求上使用 GitHub Action（参见
[`examples/github-workflow.yml`](examples/github-workflow.yml)):
```yaml
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- uses: speedvibecode/sembl@v0.2.0
with:
bounds: bounds.json
strict: "false" # 默认情况下为 advisory；为硬范围网关设置为 true
```
## 集成
`verify` 自动发现存储库根目录下的 `bounds.json` （然后是 `.sembl/bounds.json`），因此大多数集成都运行零参数。每一个都只是相同命令的触发器。完整配方： [`docs/integrations.md`](docs/integrations.md).
- **GitHub Action** — 网关每个 PR（上文）。
- **pre-commit** — 网关本地提交。钩子运行 `verify --staged`，因此它准确评估正在进行的提交——未暂存的工作树噪音永远不会泄漏到判决中：
```yaml
- repo: https://github.com/speedvibecode/sembl
rev: v0.2.0
hooks: [{ id: sembl-verify }]
```
- **代理控制工具** — 在代理停止编辑时运行 verify。Claude Code（`Stop` 钩子），Aider（ `--test-cmd`），OpenCode（编辑后钩子），或可以运行 shell 命令的任何控制工具。请参见 [`examples/`](examples/)。
- **MCP** — 让代理（或监督子代理的编排器）调用网关而无需 shell：它移交 diff + 已声明的内容，并获得 PASS/WARN/BLOCK 判决。通用情况为 *main-agent-verifies-sub-agent*。零安装 - 将其粘贴到您的 MCP 客户端（`.mcp.json`，Cursor，Windsurf，...）：
```json
{
"mcpServers": {
"sembl": { "command": "uvx", "args": ["--from", "sembl[mcp]", "sembl-mcp"] }
}
}
```
或 `pip install "sembl[mcp]"` 并运行 `sembl-mcp`。工具：`gate_pr`（一个调用 - 选择基准参考，差异分支，发现边界，返回判决），`verify_change`，`bounds_from_spec`，`list_presets`，`doctor`，以及测试版 `clarify_task` / `generate_work_order`（完整的 CLI 接口）。IDE 设置在
[`docs/ide-quickstart.md`](docs/ide-quickstart.md)；示例配置在
[`examples/mcp/`](examples/mcp/)；配方在 [`docs/integrations.md`](docs/integrations.md)。
## 安装
```powershell
pip install sembl
# 作为独立工具
uv tool install sembl
```
从源代码：
```powershell
git clone https://github.com/speedvibecode/sembl
cd sembl
uv pip install -e .
```
## 状态与诚实
Sembl 经历了一个漫长的生成优先阶段。我们测试了其核心前提——编译丰富的前置合约使得代理产生*更好的*结果——而**我们的结果并不支持它**：一个一线任务与一个有能力的代理的八部分工作订单一样好。因此，我们停止了声称。
测试中幸存下来的是什么，以及 Sembl 现在是什么：
- **`verify` — 责任网关。这是产品。** 对实际 diff 进行确定性检查；由测试套件覆盖。
- **`generate` / `clarify` / 图形上下文 — 测试版，可选，未经验证为结果改善者。** 保留是因为它们是生成边界文件的一种便捷方式，但如果您已经使用 GitHub Spec Kit / Tessl / Kiro，**请改用它**并将其输出提供给 `verify`。
我们对 Sembl **没有**提高代理产出的说法。它的声明很窄也很真实：一个可重复的、执行器中立的、免费的检查，检查更改是否在声明的范围内，并且没有伪造其结果。
---
## 测试版：工作订单生成
> **可选且未经验证。** 本节中的所有内容都是 Sembl 较旧的生成部分的半成品。
> 它生成一个“工作订单”——一个作用域合约 + 执行器提示 + 一个 `work-order.json`，`verify` 可以直接读取。
> 它与 GitHub Spec Kit 和类似工具可互换；如果您已经有规范/规划步骤，请仅在需要时使用它。
```powershell
# 核心（生成使用 LLM 提供程序）
pip install sembl
# 带有可选图形上下文（Graphify + code-review-graph）
pip install "sembl[graph-pipeline]"
```
设置一个提供者密钥，然后生成：
```powershell
$env:OPENAI_API_KEY="..." # 或 ANTHROPIC_API_KEY / GEMINI_API_KEY / NVIDIA_API_KEY / OPENROUTER_API_KEY
sembl generate --repo C:\path\to\repo --task "修复失败的登录重定向测试" --provider openai
```
提供者：`openai`，`anthropic`，`gemini`，`nvidia`，`openrouter`，`tokenrouter`，本地 `ollama` 和 `claude-cli`。输出位于
`.sembl/work-orders/wo-...{slug}/` 作为 `work-order.md`，`executor-prompt.md`，
`validation-plan.md` 和 `work-order.json` （`verify --wo-file` 读取的文件）。
其他测试命令：
```powershell
sembl clarify --repo . --task "..." # 判断任务是否足以确定范围（退出 2 如果阻止）
sembl doctor --repo . # 检查可选图形子系统（工具，图形，密钥，修复）
sembl show # 显示最新的工作订单
sembl list # 列出此存储库中的工作订单
sembl validate # 旧的 PASS/FAIL 表单 verify（保留向后兼容）
```
### 可选图形上下文
`generate` 可以使用 [Graphify](https://pypi.org/project/graphify/) 和 code-review-graph 将范围建立在存储库结构上。它是尽力而为的，不在关键路径上；运行 `sembl doctor` 查看已安装的内容以及如何修复间隙，并使用 `--graph-mode auto|required|off` 进行控制。
## 本地测试
```powershell
.venv\Scripts\python.exe -m pytest tests\ -q
python -m compileall -q sembl tests
```
## 发布
发布使用 GitHub Actions 和 Trusted Publishing（OIDC）；不存储 API 令牌。`.github/workflows/release.yml` 在您发布 GitHub Release 时发布到 PyPI，其标签（`v<version>`）与 `pyproject.toml` 和
`sembl/__init__.py` 匹配。参见 `VERSIONING.md`。
---
模型编写代码。 **Sembl 使变更负责。**
