Provable rails for unattended AI engineering —— 为 AI 无人值守编程铺设可证明的轨道。
ProofRail 让 AI 在无人值守下安全地改代码、跑验证、出证据：每一步都可验证、可回滚、可审计， 人的审批始终保留在关键节点。
- 首错即停 + 哈希绑定产物 + 原子提交回滚的“可证明写入”模型
- 相同失败指纹预算与有效修复证据判定的“防 AI 无限循环”机制
- 编辑边界矩阵与停机门禁的“AI 权限最小化”模型
- 隔离候选事务（candidate 不污染正式定义）的自愈安全模型
S1 实施中（2026-09-11）：核心切片已推进至 T027 前置能力，完成证据、快照、进程/租约守卫、托管变更集与事务应用、产品生命周期，以及无 IDE CLI 基线（init/validate/config explain/preview/approvals/interactions/cost report/secret/ai check/run/report）。
当前仍不是正式发行包：run 只支持 noop-only 任务链；遇到 code/build/verify 步骤会 fail-close 并返回非零退出码。
preview 已支持离线只读静态预览（no-AI），不会执行命令、网络探测、模型调用或凭据读取。
export 已具备库级实现（internal/snapshot/export.go 与 internal/evidence/delivery.go），CLI 入口仍在后续切片。
approvals 已提供授权账本查看与撤销（list/revoke），撤销按 stopDisposition 接线受控停机并持久化待审批队列（重启可见）；离线、零模型调用。
effects/diagnostics 已具备库级副作用分类与恢复诊断（internal/gates/effects.go、internal/evidence/diagnostics.go）：S1 拒绝外部写，未知副作用只对账不重投，诊断只读脱敏；CLI 入口仍在后续切片。
interactions 已提供追加式交互账本的待办重建、结构化答复和无 ANSI 聚焦终端界面；Engine 仅在 request/response、当前绑定与等待态一致且状态事件持久化后归还控制权。真实 Agent session 续跑仍待 T027，完整统一 TUI 仍属后续切片。
ai check 已提供显式单请求的 agent-runner-cli live availability probe；它不自动执行、不跨 profile/模型/通道回退，也不证明 AgentRunner enforcement 或 AT-23。
项目建议书与历史设计来源见 docs/RFC-proofrail-unattended-ai-engineering-product.md；分域权威见 docs/DOCUMENTATION_PLAN.md。
从 docs/DOCUMENTATION_PLAN.md 阅读文档导航与低成本模型流程； 执行顺序见 docs/DEV_PLAN.md，就绪缺口见 docs/ADR_REGISTER.md。 独立产品端到端叙事见 docs/BUSINESS_WORKFLOWS.md；尚未冻结的安装发行方案见 docs/INSTALLATION_PLAN.md。
产品完整性评审已补充无副作用预览、已接受结果导出、授权撤销、外部副作用边界、成本预留结算和备份/停用流程；见 docs/PRODUCT_REQUIREMENTS.md §8。各项实现状态以 docs/DEV_PLAN.md 为准；文件回滚不保证撤销外部操作。
当前界面是 Windows Terminal、PowerShell 或 VS Code 集成终端中的逐行 CLI，不是图形窗口或完整 TUI。发布候选的软硬件要求、下载核验和五步上手见 Windows 便携 ZIP 安装指南。核心离线 CLI 不要求 VS Code。目标正式 AI 执行使用 AgentRunner/CLI Agent；另规划基于 SessionBridge visible 的受监督黑箱候选，可更快复用现有可见 Agent，但只保证归还后的产物检查，不保证工具、网络、费用或外部副作用。两条产品闭环当前均未交付。
prfrail init --workspace .
prfrail validate --chain ./proofrail.chain.json
prfrail config explain --chain ./proofrail.chain.json
prfrail preview --chain ./proofrail.chain.json
# 仅在明确授权一次真实模型请求后执行：
prfrail ai check --chain ./proofrail.chain.json --channel agent-runner-cli --copilot C:/path/to/copilot.exe --workspace . --max-requests 1 --out ./tmp/ai-availability.json --json
prfrail ai verify --chain ./proofrail.chain.json --record ./tmp/ai-availability.json --channel agent-runner-cli --max-age 10m --max-requests 1 --json
prfrail approvals list --ledger ./authorization-ledger.jsonl
prfrail interactions list --ledger ./operator-interactions.jsonl
prfrail interactions tui --ledger ./operator-interactions.jsonl --actor-id operator-one
prfrail run --chain ./proofrail.chain.json --run-id run-demo
prfrail report --run-dir ./tmp/prfrail-runs/run-demo
说明：run 目前仅执行 noop-only 任务链；interactions tui 是 T025 的聚焦终端收件箱，不是完整统一 TUI，serve/完整 TUI 仍在后续切片。ai verify 可重复指定 --prior-record <path>，离线拒绝同一 probe ID 的历史分叉；相同记录重放保持幂等。后续黑箱模式须先展示降级保证和责任边界。SessionBridge visible 投递不等于完成，正式流程也不依赖 @sbr-review。
go build ./...
go vet ./...
go test ./...
| 阶段 | 目标 | 关键交付 |
|---|---|---|
| S0 规格化 | 领域模型与协议定稿 | 文档包、JSON Schema、威胁模型、ADR |
| S1 核心任务链 | 可运行的 MVP | Chain Engine、checker、gate runner、adapter、快照/评审/恢复、TUI |
| S2 平台与语言扩展 | 走向通用 | 多 harness、Linux 支持、Web 控制台、模型策略 |
| S3 高级能力 | 产品化完整闭环 | 生成钩子场景 B、多编辑器、多语言文档 |
| 场景 | 写法 |
|---|---|
| 正式品牌、标题、对外文档 | ProofRail |
| 紧凑视觉标识 | PrfRail |
| 仓库、CLI、包名、模块前缀 | prfrail |
| 中文文档 | 证轨 |
MIT（见 LICENSE）。
ProofRail enables AI to safely modify code, run validations, and produce evidence in unattended mode: every step is verifiable, reversible, and auditable, while human approval always remains at critical checkpoints.
- "Provable write" model: fail-fast on first error + hash-bound artifacts + atomic commit/rollback
- Anti-infinite-loop mechanism: identical failure-fingerprint budgets + valid-fix-evidence determination
- Least-privilege AI model: edit boundary matrix + halt gates
- Self-healing security model: isolated candidate transactions (candidate never contaminates formal definitions)
S1 implementation in progress (2026-09-11): prerequisite work now reaches T027, covering evidence, snapshots, process/lease guards, managed change sets, transactional apply, product lifecycle, and a no-IDE CLI baseline (init/validate/config explain/preview/approvals/interactions/cost report/secret/ai check/run/report).
This is still not a production release package: run currently supports noop-only chains and fail-closes with a non-zero exit for executable code/build/verify steps.
preview now supports a no-AI offline read-only static report with zero command/network/model/credential execution.
export is now implemented at library level (internal/snapshot/export.go + internal/evidence/delivery.go); a dedicated CLI entrypoint remains in later slices.
approvals now provides an authorization ledger view and revocation (list/revoke) with controlled-stop wiring per stopDisposition and a restart-visible pending inbox; offline and model-free.
effects/diagnostics now provide library-level side-effect classification and recovery diagnosis (internal/gates/effects.go, internal/evidence/diagnostics.go): S1 denies external writes, unknown effects reconcile instead of blind retry, and diagnosis is read-only and redacted; CLI entrypoints remain in later slices.
interactions now rebuilds pending items from an append-only ledger, records structured responses, and provides a focused ANSI-free terminal UI. The Engine returns control only after request/response, current binding, waiting state, and durable state events agree. Real Agent-session continuation remains T027 work, and the complete unified TUI remains a later slice.
ai check now provides an explicit single-request agent-runner-cli live availability probe. It never runs automatically, falls back across profiles/models/channels, or proves AgentRunner enforcement or AT-23.
Project proposal and historical design source: docs/RFC-proofrail-unattended-ai-engineering-product.md. Domain authorities: docs/DOCUMENTATION_PLAN_EN.md.
Start with docs/DOCUMENTATION_PLAN_EN.md for navigation and the low-cost model workflow; see docs/DEV_PLAN_EN.md for tasks and docs/ADR_REGISTER_EN.md for readiness gaps. See docs/BUSINESS_WORKFLOWS_EN.md for the independent end-to-end product narrative and docs/INSTALLATION_PLAN_EN.md for unresolved installation and distribution decisions.
Product review adds side-effect-free preview, accepted-result export, revocation, external-effect boundaries, cost reservation/settlement and backup/retirement flows. See docs/PRODUCT_REQUIREMENTS_EN.md section 8 and docs/DEV_PLAN_EN.md for each capability's implementation status. File rollback cannot guarantee undoing external effects.
The current interface is a line-oriented CLI in Windows Terminal, PowerShell, or the VS Code integrated terminal, not a graphical window or complete TUI. See the Windows portable ZIP installation guide for candidate hardware/software requirements, download verification, and the five-step quick start. Core offline mode needs no VS Code. Target formal AI execution uses AgentRunner/CLI Agent; a separate SessionBridge-visible supervised black-box candidate mode is planned for faster reuse of an existing visible Agent, but warrants post-return artifacts only, not tools, network, cost, or external effects. Neither product loop is delivered yet.
prfrail init --workspace .
prfrail validate --chain ./proofrail.chain.json
prfrail config explain --chain ./proofrail.chain.json
prfrail preview --chain ./proofrail.chain.json
# Run only after explicit authorization for one live model request:
prfrail ai check --chain ./proofrail.chain.json --channel agent-runner-cli --copilot C:/path/to/copilot.exe --workspace . --max-requests 1 --out ./tmp/ai-availability.json --json
prfrail ai verify --chain ./proofrail.chain.json --record ./tmp/ai-availability.json --channel agent-runner-cli --max-age 10m --max-requests 1 --json
prfrail approvals list --ledger ./authorization-ledger.jsonl
prfrail interactions list --ledger ./operator-interactions.jsonl
prfrail interactions tui --ledger ./operator-interactions.jsonl --actor-id operator-one
prfrail run --chain ./proofrail.chain.json --run-id run-demo
prfrail report --run-dir ./tmp/prfrail-runs/run-demo
Notes: run currently executes noop-only chains. interactions tui is T025's focused terminal inbox, not the complete unified TUI; serve and the complete TUI remain later slices. ai verify accepts repeatable --prior-record <path> inputs, rejects historical forks for one probe ID offline, and treats identical record replay as idempotent. The later black-box mode must show its reduced assurance and responsibility boundary before selection. SessionBridge visible delivery is not completion, and the formal path does not depend on @sbr-review.
go build ./...
go vet ./...
go test ./...
| Phase | Goal | Key deliverables |
|---|---|---|
| S0 Spec | Finalize domain model and protocols | Docs package, JSON Schema, threat model, ADR |
| S1 Core chain | Runnable MVP | Chain Engine, checker, gate runner, adapter, snapshot/review/recover, TUI |
| S2 Platform & language extension | Go general | Multiple harnesses, Linux support, web console, model policies |
| S3 Advanced capabilities | Full productized loop | Generated hook scenario B, multiple editors, multilingual docs |
| Context | Spelling |
|---|---|
| Official brand, titles, external docs | ProofRail |
| Compact visual identity | PrfRail |
| Repo, CLI, package, module prefix | prfrail |
| Chinese docs | 证轨 |
MIT (see LICENSE).