This release is a pre-release and may not be stable for production use.
phase-barrier
强制编码 Agent（如 Alpha-SWE）遵循标准工程师 SOP 的**阶段门禁（Stage Gate）**框架。
phase-barrier 的核心是阶段门禁的不可绕过性（以 sidecar 与文件系统隔离为信任前提）。
控制面是可选的人机协作层，不改变门禁的核心逻辑；控制面的所有写操作都经过审计和权限检查。
权限、任务写操作与写前 Diff 通过 permissions-init 显式启用，调度器另需配置。
流程：需求 -> spec 设计 -> 测试用例 -> 实现 -> 测试 -> 修复 -> 交付。 每个阶段要求可验证证据（spec 章节 / 测试 AST / 语法检查 / 测试结果 / 覆盖率）， 跳步、偷步、伪造产出会被自动拦截——先有证据，才放行下一步。
为什么需要 phase-barrier？
实测数据
SWE-bench Lite Scale-20（官方评测容器内，同模型同预算，20 实例配对，2026-09）：
| 组别 | resolved | 门禁拦截 | 交付全绿 | 空补丁 | 平均耗时 |
|---|---|---|---|---|---|
| baseline（无门禁） | 18/20（90%） | 0 | — | 0 | 262s |
| gated（阶段门禁） | 20/20（100%） | 78 | 14 | 0 | 462s |
门禁把 baseline 失败的 2 个实例救了回来，0 例拖累；代价是平均耗时约 1.8 倍（n=20，仅同条件对比）。
完整报告与复算命令见 docs/benchmarks/swe-bench-scale20.md，
原始数据在 benchmarks/swebench/results/。
版本线：v1.0.0 冻结公开 API；v1.1.0 引入默认不启用的可选控制面。
标签创建与正式发布须通过安全及 CI 门槛；实际发布状态以远程标签和 Release 为准。
实际版本由 Git tag 决定，状态与兼容性策略见 docs/release.md。
为什么需要 phase-barrier？
编码 Agent 拿到需求后倾向于“直接写代码”，跳过需求分析、设计与测试，造成理解偏差、 缺回归保障、后期难维护。phase-barrier 在 Agent 的工具调用层加一道闸门：
- 不可绕过：校验逻辑独立于 Agent 决策循环；状态文件由 Skill 独占原子写入。
- 证据明确：每个阶段要求具体可验证的产物，拦截时返回可读原因，Agent 可据此修正流程。
- 自动校验：spec 章节检查、测试 AST 统计、语法检查、测试结果解析、覆盖率门禁全部自动完成。
核心特性
- 阶段状态机：需求 -> spec -> 测试 -> 实现 -> 测试 -> 修复 -> 交付，逐级放行、不可跳级。
- 多语言适配：13 种语言适配器——Python / JavaScript（含 TypeScript）/ Java / Kotlin / Scala / Go / Rust / Swift / Ruby / PHP / C#（.NET 别名）/ C++ / Dart。
- 工具拦截：包装
write_file/execute_command；shell 重定向、python -c/node -e等脚本写入同样受控。 - 人机控制面：写前 Diff / 人工复核、只读 Textual TUI、会话权限、SQLite 任务看板、跨会话 Goal 和 sidecar 定时维护（使用指南）。
- 防篡改：HMAC 状态签名、证据清单（SHA-256）、
verify-evidenceGit 基线校验。 - 安全规则包：shell 注入 / 路径穿越 / 硬编码密钥 / 许可证头等内置规则，YAML 一键启用。
- 集成面广：进程内包装、CLI 透明代理、GitHub Action、K8s sidecar（Helm）、Docker 一键体验。
- Agent 框架示例：LangChain / AutoGPT / SWE-agent 开箱即用示例（
docs/integrations.md）。 - 插件机制：语言适配器 / 校验器 / 拦截规则 / 集成插件四类入口点 +
plugin-verify自动验证；打phase-barrier-plugintopic 即被每周自动收录（5 分钟创建你的第一个插件，或从官方模板仓库一键生成）。 - 自洽工程：CI 全矩阵真实工具链、覆盖率门禁（≥90%）、模糊测试与性能 / SWE-bench 基准。
快速开始
Docker 一键体验（无需安装）
docker run --rm -it ghcr.io/xuqing0415/phase-barrier-demo
演示“跳步被拦截 -> 按 SOP 补齐证据 -> 全通到交付”。不想装 Docker 也可以直接看
2.5 分钟演示视频：画面全部来自该演示脚本的真实
运行输出（python scripts/make_demo_video.py --out demo.mp4 可一键复现）。
pip 安装 + 初始化
pip install phase-barrier
python -m anti_shortcut init # 自动检测语言，生成带注释的 config.yaml
python examples/minimal_agent.py # 最小可运行示例：先跳步被拦，再按 SOP 通过
最小接入（进程内包装）
from anti_shortcut import AntiShortcutSkill
skill = AntiShortcutSkill(
workspace=".",
config="anti_shortcut_config.yaml", # 可选
user_request="实现一个计算斐波那契数列的函数",
)
# 包装 Agent 工具表：write_file / execute_command / advance_stage 全部经过门禁
tools = skill.install(agent.tools)
tools["write_file"]("fib.py", impl) # 未完成 spec/测试 -> 抛 PermissionError 并说明原因
tools["advance_stage"](2) # 校验 spec 证据通过后，进入阶段 2（测试用例编写）
可运行示例：examples/minimal_agent.py（拦截 + 正常流程）、
examples/demo.py（完整演示）。详细步骤见 docs/quickstart.md。
命令行门禁（编排器 / CI / 人工复核）
anti-shortcut inspect --workspace . --json # 查看当前阶段
anti-shortcut write --workspace . --path spec.md --content "..." # 经门禁写文件
anti-shortcut exec --workspace . --command "python -m pytest -q" # 经门禁执行测试
anti-shortcut advance --workspace . --to 2 # 推进阶段（校验证据）
使用示例（输出摘要）
[BLOCKED] write_file(fib.py, ...)
-> 当前阶段不允许编写实现代码，请先完成 spec 与测试用例
[OK] write_file(spec.md, ...)
[OK] advance_stage(2)
...
[demo] 完成：交付
文档导航
| 主题 | 文档 |
|---|---|
| 快速开始 | docs/quickstart.md |
| CLI 使用 | docs/usage.md |
| 人机控制面（TUI / Diff / Goal / 任务 / 权限 / 调度） | docs/control-plane.md |
| 配置指南（全字段） | docs/configuration.md |
| 语言适配器 | docs/languages.md |
| 架构与设计 | docs/architecture.md |
| 拦截规则与安全加固 | docs/security-rules.md |
| 红队 Agent（自己打自己，18 类逃逸技术 / CI 常态化，v0.60.0） | docs/red-team.md |
| 形式化不变量（TLA+ 模型检查，v0.58.0） | docs/formal-invariants.md |
| 学习型防线（从案例中学习 + 半自动闭环，v0.60.0） | docs/learning-defense.md |
| 状态与审计（远程推送） | docs/audit-logging.md |
| GitHub Action | docs/github-action.md |
| 编排器钩子 SDK | docs/orchestrator-hooks.md |
| Agent 框架集成（LangChain 等） | docs/integrations.md |
| K8s 部署（Helm） | docs/k8s.md |
| 插件与生态 | docs/plugins.md |
| API 参考 | docs/api.md |
| FAQ | docs/faq.md |
| Roadmap | docs/roadmap.md |
| 发布与供应链安全 | docs/release.md |
| 贡献指南 | CONTRIBUTING.md |
支持的语言与框架
| 语言 | 适配器 | 测试框架 |
|---|---|---|
| Python | PythonAdapter | pytest / unittest |
| JavaScript / TypeScript | JavaScriptAdapter | Jest / Vitest / Playwright / Cypress |
| Java | JavaAdapter | JUnit 4/5 / TestNG / Maven / Gradle |
| Kotlin | KotlinAdapter | JUnit 5 / kotlin.test / Gradle |
| Scala | ScalaAdapter | ScalaTest / MUnit / JUnit / sbt |
| Swift | SwiftAdapter | XCTest / swift-testing（swift test） |
| Go | GoAdapter | testing / testify |
| Rust | RustAdapter | cargo test |
| Ruby | RubyAdapter | RSpec / Minitest |
| PHP | PhpAdapter | PHPUnit |
| C / C++ | CppAdapter | GoogleTest / Catch2 / CTest |
| C# / .NET | CSharpAdapter / DotNetAdapter | xUnit / NUnit / VSTest / dotnet test |
| Dart | DartAdapter | package:test / flutter test |
自动检测规则、自定义适配器与各语言语法检查方式见 docs/languages.md。
社区与支持
- 使用问题 / 功能建议 / Bug：GitHub Issues（内置模板）
- 插件提交与生态索引：docs/plugins.md
- Roadmap：docs/roadmap.md ｜ 更新日志：CHANGELOG.md
- 官方文档站：https://docs.xshayncka.dev/
- 与 alpha-swe 双向关联（编排器钩子 SDK 已合并接入）
License
1 maintainer
Metadata
1 maintainer
Release files for phase-barrier 1.1.0.post1.dev0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| phase_barrier-1.1.0.post1.dev0.tar.gz | 1.5 MB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| phase_barrier-1.1.0.post1.dev0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.7 MB
Release files / phase_barrier-1.1.0.post1.dev0.tar.gz
| Download URL | phase_barrier-1.1.0.post1.dev0.tar.gz |
|---|---|
| Size | 1.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cec6f52691d34a5e7b36ebbbca096d8ce8c126607362defc3dc14734aa986e10
|
|
BLAKE2b-256 checksum How to use checksums |
cc216d8c9434632093398049b7c0f32ef97dd3df051fe8aa069031d6617031a3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logRelease files / phase_barrier-1.1.0.post1.dev0-py3-none-any.whl
| Download URL | phase_barrier-1.1.0.post1.dev0-py3-none-any.whl |
|---|---|
| Size | 266.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6f9b32f0407162d0daac6aa1621a7a67695bca08fcede6ccd29c76ac24f0c7fd
|
|
BLAKE2b-256 checksum How to use checksums |
016123f660a67291fe5b28e6dbad38003e227b5b9a5b74550d299f37d9905fa1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logSecurity for phase-barrier 1.1.0.post1.dev0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for phase_barrier-1.1.0.post1.dev0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
