Antrail 将模型建议限制在显式状态机、路径策略和硬预算之内。默认模式保持 Phase A
只读仓库分析；--mode patch 在精确审批后应用受控补丁；--mode patch-verify
进一步执行审批冻结的注册验证命令，并从 Runtime 事实生成可审计报告。
Important
当前版本为早期开发版 0.2.0。CLI 支持 DeepSeek、Qwen、Kimi、GLM、MiniMax
和 MiMo 真实模型，也保留离线结构化响应脚本用于确定性运行与评测。真实调用可能
产生 API 费用。
- 控制权属于 Runtime：模型只能提出结构化建议，不能直接修改状态、预算或工具注册表。
- 默认只读：未指定模式时仅执行受控调查，不获得写预算。
- 审批后写入：Patch 模式绑定计划、文件快照、补丁摘要和人工审批，拒绝隐式批准。
- 验证也需审批：Patch Verify 模式绑定固定 argv、cwd、超时、后端与验证摘要。
- 路径策略统一生效：仓库边界、敏感路径、受保护路径和符号链接均在读取前检查。
- 资源有硬上限：模型调用、工具调用、读取字符和总时间由 Runtime 结算。
- 报告可追溯：读取文件、Git、工具和生命周期事实均从已记录事件投影。
- 结果可复现：脚本 Adapter 和临时 Git 场景支持无网络、确定性的自动化测试。
Antrail 当前适合作为“先调查、再审阅、再决定是否写入”的受控执行层：
- 快速理解陌生仓库：识别语言、源码目录、测试目录、Git 基线和项目配置。
- 定位实现与测试：通过有界搜索和文件读取查找某个行为对应的代码证据。
- 变更前设计：为小功能或可复现缺陷生成包含文件、步骤、风险和证据的候选计划。
- 安全评测：使用固定响应脚本复现预算耗尽、策略拒绝和结构错误等边界情况。
- 审计集成：让上层系统消费稳定终态、预算用量和不含正文的事件摘要。
- 小范围文本变更：对普通源码或测试文件展示精确补丁后，由用户批准全部或安全子集。
| 维度 | 常见直接执行模式 | Antrail Phase F |
|---|---|---|
| 模型权限 | 模型可能直接选择并调用工具 | 模型只提出通过 schema 校验的结构化建议 |
| 状态所有权 | 编排框架或模型输出可能改变状态 | 仅 RuntimeController 可以迁移状态 |
| 文件能力 | 通常同时具备读取与写入 | 默认只读；显式 Patch 模式仍需 exact patch 审批 |
| 资源限制 | 依赖提示词或循环上限 | 模型、工具、字符和时间使用硬预算 |
| 报告来源 | 可能依赖模型自行总结 | 从连续 Runtime 事件确定性投影 |
| 失败行为 | 可能继续重试或降级执行 | 进入稳定、可审计的终止状态 |
flowchart LR
CLI[CLI / 自然语言任务] --> B[Bootstrap]
B --> R[Route]
R --> D[Discover]
D -->|有限循环| D
D --> P[Plan]
P -->|read-only| A[Answer]
P -->|patch| V[Policy Review]
V --> Q[Approval]
Q --> E[Execute]
A --> O[Report]
E --> O
C[Runtime Controller<br/>状态 · 预算 · 事件] -.控制.-> B
C -.控制.-> R
C -.控制.-> D
C -.控制.-> P
C -.控制.-> A
C -.控制.-> V
C -.控制.-> Q
C -.控制.-> E
C -.控制.-> O
D --> T[只读工具]
G[RepositoryAccessPolicy] -.校验.-> T
默认路径为 BOOTSTRAP → ROUTE → DISCOVER → PLAN → ANSWER → REPORT → COMPLETED；
Patch 路径从 PLAN 进入 POLICY_REVIEW → APPROVAL → EXECUTE → REPORT。任何策略拒绝、
预算耗尽或结构化响应失败都会进入明确的终止状态，而不是绕过 Runtime 继续执行。
- Python 3.12 或更高版本
- Git
- uv
git clone https://github.com/Hmanbo/antrail.git
cd antrail
uv sync --all-groups检查当前 Git 仓库与 Antrail 状态目录的边界：
uv run antrail workspace .该命令只输出工作区 JSON，不会创建状态目录或修改目标仓库。
在进程环境中设置 DeepSeek API Key。不要把凭证写入项目配置或提交到 Git：
$env:DEEPSEEK_API_KEY = "<your-api-key>"export DEEPSEEK_API_KEY="<your-api-key>"使用当前官方默认模型 deepseek-v4-flash：
uv run antrail run "解释这个仓库的结构" \
--provider deepseek \
--repository .也可以显式选择 deepseek-v4-pro：
uv run antrail run "定位配置预算的实现并给出修改计划" \
--provider deepseek \
--model deepseek-v4-pro \
--repository .DeepSeek 调用使用 JSON Output、非流式响应和显式非思考模式。模型只能提出结构化的 route、只读调查动作、候选计划和最终分析回答；工具是否执行仍由 Runtime、Policy 和 硬预算决定。
目标仓库必须显式声明候选写范围和正写预算，例如：
version: 1
paths:
writable: [src/]
budgets:
write_operations: 4随后选择 Patch 模式：
uv run antrail run "只修改 src/app.py 中指定的返回值" `
--mode patch `
--provider deepseek `
--repository $TargetRepo `
--state-root $StateRoot交互式终端默认使用 human 输出，实时展示 Runtime 已确认的阶段、模型公开提交的路由说明、
问题理解和计划步骤。它不会展示 provider 原始响应或隐藏推理。审批点默认展示冻结的
unified diff；可输入 a 批准、s 按编号选择文件、r 修订、x 拒绝、c 取消，或
d 再次查看 exact patch 与验证详情。CLI 会从当前冻结请求自动绑定 request_id、
patch_digest 和可选的
verification_digest，但不会自动批准。
脚本和 CI 应显式使用 --format json。JSON 模式继续要求提交完整结构化响应，例如：
{"action":"approve","request_id":"request-1","patch_digest":"<当前 patch_digest>"}approve_subset、revise、reject 和 cancel 的格式见
Phase B 审批式补丁。默认持久模式可以通过 task ID 在新进程
重显和提交同一审批；--ephemeral 的审批仍只在当前进程有效。批准后仍会重新检查路径、
文件类型、快照、dry-run 和预算。
run 和 resume 都接受 --format human|json。未显式选择时，stdout 与 stderr 均连接
TTY 才使用 human；任一输出被重定向时保持 JSON，避免破坏管道。
任务参数可以包含自然段、列表和制表符；NUL 等非文本控制字符仍会在启动前被拒绝。
目标仓库还需注册至少一条命令，并提供正验证预算：
version: 1
paths:
writable: [src/]
commands:
unit:
argv: [uv, run, pytest, -q]
timeout_seconds: 120
risk: R1
budgets:
write_operations: 4
verification_commands: 2uv run antrail run "修改 src/app.py 并运行单元测试" `
--mode patch-verify `
--provider deepseek `
--repository $TargetRepo `
--state-root $StateRoot审批请求会展示完整 argv、相对 cwd、timeout、有效风险、host_process_v1 后端和
verification_digest；human 快捷批准自动绑定两个摘要，JSON 批准必须同时回显它们。
非交互模式只展示请求并暂停，绝不执行。只有显式增加
--repair-on-verification-failure，失败诊断才可能经裁剪和净化后交给当前 provider，
且修复补丁必须重新审批，最多一轮。完整流程见补丁验证操作指南。
Phase A 的 run 命令需要一个有限 JSON 数组，按顺序提供 route、discover、plan 和
answer 的结构化响应。
展开查看最小 responses.json
[
{
"task_type": "analysis",
"primary_workflow": "read_only",
"selected_skills": [],
"confidence": 0.9,
"clarification_required": false,
"clarification_questions": [],
"risk_level": "R0",
"rationale": "进入只读分析"
},
{
"action": "finish_discovery",
"reason": "项目画像足以形成计划"
},
{
"problem_understanding": "分析仓库结构",
"in_scope": ["汇总只读事实"],
"out_of_scope": ["修改仓库"],
"expected_files": ["README.md"],
"steps": [
{
"step_id": "summarize",
"description": "汇总项目画像",
"depends_on": [],
"evidence_refs": []
}
],
"verification_command_ids": [],
"risks": ["未读取全部源码"],
"user_decisions": [],
"evidence_refs": []
},
{
"answer": "这是一个受控的只读仓库分析 Runtime。",
"findings": [
{
"finding_id": "repository-root",
"statement": "调查确认了 Git 仓库根目录。",
"confidence": "high",
"evidence_refs": ["git:repository-root"]
}
],
"recommendations": ["按候选计划继续人工审阅"],
"limitations": ["当前阶段未执行项目验证命令"],
"evidence_refs": ["git:repository-root"]
}
]uv run antrail run "分析这个仓库" \
--repository . \
--script responses.json命令输出 JSON 格式的项目画像、路由、候选计划、最终分析 result、工具统计、预算
余量、最终事实 report 和终止状态。result 是模型根据已校验证据对用户问题的回答；
plan 是未执行的候选步骤；report 是 Runtime 确定性投影的审计事实。提前终止时
result 为 null，CLI 仍会从图停止时的 Runtime 状态投影 report。
典型输出中的安全摘要如下；文件正文、搜索预览和 Git diff 内容不会进入 CLI 报告：
{
"current_stage": "completed",
"result": {
"source": "llm",
"answer": "这是一个受控的只读仓库分析 Runtime。",
"findings": [],
"recommendations": [],
"limitations": ["当前阶段未执行项目验证命令"],
"evidence_refs": ["git:repository-root"],
"verification_status": "not_run"
},
"loaded_files": [],
"tools": {
"names": [],
"results": {
"completed": 0,
"denied": 0,
"failed": 0
}
},
"budgets": {
"write_operations": {
"limit": 0,
"used": 0,
"remaining": 0
}
},
"report": {
"report_state": "completed",
"lifecycle": [
"bootstrap",
"route",
"discover",
"plan",
"answer",
"report",
"completed"
],
"terminal": {
"state": "completed",
"reason_code": "graph.completed",
"explanation": "只读分析已完成"
}
},
"terminal": {
"state": "completed",
"reason_code": "graph.completed",
"explanation": "只读分析已完成"
},
"error_code": null
}只读模式不会在目标仓库中创建结果或报告文件。默认 run 会在仓库外的状态目录创建任务
数据库，并在第一次模型调用前把 task ID 写入 stderr；使用 --ephemeral 可保留纯进程内
模式。stdout 的原有字段保持兼容，并增加 persistence 摘要。
| 命令 | 用途 | 关键参数 |
|---|---|---|
antrail workspace [repository] |
解析 Git 根目录、状态目录与配置路径 | --state-root |
antrail run <task> |
默认创建持久任务并执行只读或审批式补丁流程 | --mode、--provider、--state-root、--task-id、--ephemeral、--ui、--format |
antrail resume <task-id> |
重显或提交持久审批，终态时幂等返回报告 | --response、--response-json、--script、--repository、--format |
antrail status <task-id> |
查看脱敏生命周期、游标、operation 和完整性摘要 | --state-root、--json |
antrail inspect <task-id> |
检查事件、完整性或显式展示待审批 patch | --events、--integrity、--approval |
antrail ui <task-id> |
在本机启动只读 Runtime Inspector | --state-root、--port |
antrail cancel <task-id> |
幂等取消，不执行 Git 清理或回滚 | --state-root |
antrail task-report <task-id> |
从持久事件重放、验证或写出报告 | --verify、--output |
antrail eval validate <suite> |
只读校验 suite、scenario、fixture、脚本和摘要闭包 | --evaluation-root |
antrail eval run <suite> |
顺序执行冻结 trial plan，并写入全新公开 output | --cell、--provider、--model、--repeat、--output |
antrail eval summarize <run-directory> |
不重跑产品，离线重建并核验聚合报告 | — |
antrail eval baseline <report> |
从完整通过报告生成不可覆盖的 baseline 候选 | --output |
antrail eval compare <baseline> <report> |
核对兼容性、安全 gate 和数值回归 | — |
--provider 默认为 scripted，此时必须提供 --script 且不会访问网络。选择
deepseek 时不能提供脚本，默认模型为 deepseek-v4-flash。
需要持续观察任务时，可以启动不依赖前端构建或独立后端的开发辅助页面：
uv run antrail ui <task-id> --state-root <state-root>页面固定监听 127.0.0.1:8765，通过有界轮询展示已提交的生命周期、预算、计划、
审批/变更、验证和最近事件。它不提供任务管理、审批或写入能力，详见
本地 Runtime Inspector。
需要从任务启动阶段实时观察时，直接在 run 上增加 --ui：
uv run antrail run "分析这个仓库" --provider deepseek --repository . --ui任务创建后 CLI 会立即在 stderr 输出 Inspector URL。运行结束后页面继续保留，终端会
提示按回车键；按下回车后停止本机服务并退出命令，Ctrl+C 仍可用于中断。
任务成功完成时 run 返回退出码 0；进入 blocked、failed 或 budget exhausted 等终态时
返回 1；命令参数或启动输入无效时由 CLI 返回 2。
评测 output、fixture 工作树与任务 state 始终分离。eval run --output 只接受不存在的新目录；
eval baseline --output 也不覆盖现有文件。比较命令返回 0 表示通过、2 表示兼容但回归、
3 表示身份不兼容。完整数据协议、目录布局和安全边界见
Phase E 评测数据协议。
目标仓库可以提供 .antrail/config.yaml。最小配置只需声明 schema 版本：
version: 1一个更实用的只读分析配置可以声明项目范围、敏感路径和候选验证命令：
version: 1
project:
name: example-project
root: .
paths:
ignored:
- "**/.venv/**"
- "**/node_modules/**"
sensitive:
- "**/.env"
- "**/*secret*"
commands:
unit_tests:
cwd: .
argv: [uv, run, pytest, -q]
timeout_seconds: 120
risk: R1注册命令不等于允许执行。默认只读模式会把写操作与验证命令预算固定为零；Patch 模式只读取配置的写预算，验证命令预算仍固定为零；只有显式 Patch Verify 模式会加载 验证预算，并且仍需计划选择和用户审批。
默认 scripted provider 不访问网络。选择 --provider deepseek 时，Antrail 会向
DeepSeek API 发送完成当前步骤所需的有界上下文，可能包括：
- 用户任务、结构化 schema 与项目画像；
- 文件读取结果、搜索预览和其他只读工具结果；
- Patch 模式中经过策略复核的目标文件内容与编辑上下文；
- 启用有限修复时经过裁剪和净化的验证诊断。
“源码正文不进入事件、报告或 checkpoint”不代表源码从未发送给所选模型 provider。 外部 provider 如何处理和保留请求数据受其服务条款与隐私政策约束。请只对你有权发送给 该 provider 的仓库使用真实模型，并在运行前通过 protected/sensitive 路径配置进一步 限制范围。当前版本不包含独立遥测通道；API Key 仅从进程环境读取，不应写入项目文件。
当前版本明确不包含以下能力：
- 运行任意 Shell；
- 隔离不可信项目代码的容器或 OS 沙箱；
- 删除、重命名、复制、mode、binary 或链接写入；
- 后台服务、远程队列或多机恢复；
- 多 Agent 协作；
- 在事件、报告或 checkpoint 中保存敏感正文。
.antrail/config.yaml 中的路径、命令和预算只是候选配置，不能降低 Runtime 的内置
限制。完整字段说明参见项目配置。
| 主题 | 说明 |
|---|---|
| Phase B 验收 | 审批式补丁场景矩阵、双平台 CI 与阶段边界 |
| Phase B 审批式补丁 | CLI 审批 JSON、生命周期与进程内恢复限制 |
| Phase C 验收 | 45 项完成门槛、双平台 CI 与阶段边界 |
| Phase D 验收 | 跨进程 crash matrix、双平台 CI 与最终验收结论 |
| Phase E 验收 | 20 项 Graduation 门槛、确定性门禁与真实 Provider Pilot 证据 |
| Phase F 验收 | 架构边界、v0.1.0 兼容、重构前 baseline 与真实比较证据 |
| 当前变更治理特征 | 补丁生命周期、持久恢复边界与现有治理语义的测试映射 |
| Phase E 评测数据协议 | 稳定 v1 DTO、身份摘要、指标分母与安全门禁 |
| 确定性评测集合 | 冻结 fixture、scripted 核心场景与本地/CI 运行约束 |
| 真实 Provider Pilot | DeepSeek 手工运行、费用上界、公开证据与保留边界 |
| Phase A 验收 | 场景矩阵、CI 约束与阶段边界 |
| 只读运行图 | 生命周期、节点职责与 CLI 输出 |
| Runtime Kernel | 状态所有权、预算、事件与 checkpoint |
| Bootstrap | 启动顺序、失败语义与只读保证 |
| 访问策略 | 仓库路径、敏感内容与符号链接策略 |
| 补丁提案 | unified diff 解析、事实复核与无写入 dry-run |
| 补丁审批 | 不可变审批载荷、子集批准与进程内暂停恢复 |
| 补丁执行 | 执行前复核、固定 Git apply 与实际变化审计 |
| 补丁副作用恢复 | 持久 operation、崩溃对账与最多一次应用语义 |
| 验证命令与调用恢复 | 最多一次 spawn、残留进程核验与调用预算对账 |
| 验证进程 Runner | 最小环境、有界双流输出与跨平台进程树控制 |
| 验证工作树审计 | Git 快照、副作用分类与只读审计边界 |
| VERIFY 节点与命令审计 | 审批摘要复核、验证预算、顺序执行与 fail-fast 聚合 |
| EVALUATE 节点与单次修复 | 确定性失败路由、受限模型诊断与重新审批边界 |
| 补丁验证操作指南 | patch-verify 配置、审批、报告、终态与 host process 风险 |
| 事件投影 TaskReport | 版本化报告、事件重放与缓存验证 |
| 持久任务 CLI | 默认持久运行、恢复、查询、取消和报告命令 |
| 交互式 CLI 验收 | human/JSON、实时事件、审批与恢复安全证据 |
| 本地 Runtime Inspector | 本机只读任务页面、数据来源与安全边界 |
| 可观测性架构 | 权威数据、只读投影、敏感信息与实时演进边界 |
| 只读工具 | Dispatcher 与工具结果契约 |
| LLM Gateway | Adapter、结构化 schema 与错误恢复 |
| 项目画像 | 推断事实与证据来源 |
| 项目清单 | 枚举边界、截断与确定性 |
| 工作区 | 仓库目录与外部状态目录隔离 |
| 发布检查清单 | 版本同步、全量验证、产物审计、tag 与 Release 流程 |
| 变更日志 | 未发布变更与版本发布记录 |
antrail/
├── src/antrail/
│ ├── cli.py # 运行、恢复与持久任务管理命令入口
│ ├── inspector/ # 本地只读任务快照与包内静态页面
│ ├── config/ # 项目配置加载和命令注册
│ ├── workspace/ # Git 仓库与状态目录边界
│ ├── git/ # 分支、HEAD 和工作区基线
│ ├── inventory/ # 有界、确定性的目录清单
│ ├── profile/ # 带证据来源的项目画像
│ ├── policy/ # 路径访问与敏感内容策略
│ ├── patches/ # 补丁模型、parser、dry-run 与批准后执行
│ ├── approval/ # 审批载荷、批准范围与进程内 Session
│ ├── evaluation/ # 版本化评测、产品进程、oracle、指标与比较
│ ├── runtime/ # 生命周期、预算、事件和 checkpoint
│ ├── llm/ # Adapter、Gateway 与结构化 schema
│ ├── tools/ # 只读工具及统一 Dispatcher
│ ├── nodes/ # 模型节点与 Policy Review 节点
│ ├── read_only_graph.py # LangGraph 只读流程组装
│ └── patch_graph.py # 审批式补丁流程组装
├── evals/ # 版本化 fixture、scenario 与 deterministic suite
├── tests/
│ ├── unit/ # 组件契约与边界测试
│ ├── integration/ # 跨模块与 CLI 测试
│ ├── scenarios/ # 临时 Git 仓库端到端验收
│ └── acceptance/ # 真实子进程恢复与 CLI 验收
└── docs/ # 设计边界与验收文档
uv lock --check
uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest -q
uv run antrail eval validate evals/suites/deterministic-v1.yaml
uv buildCI 在 Python 3.12 的 Windows 与 Linux 环境执行全量测试；Linux job 另外执行锁文件检查、 Ruff、格式检查、mypy、deterministic evaluation gate 和构建。该评测 gate 不访问网络或 读取 provider secret，任一安全失败都会使 CI 失败。Linux 环境必须实际通过符号链接安全 测试。
当前 Windows 本地验收基线为 1581 passed, 15 skipped。跳过项是 POSIX 专属进程组测试
或 Windows 在缺少符号链接权限时的平台能力测试；Linux CI 会执行对应的 POSIX 和强制
符号链接用例。
| 终态 | 含义 |
|---|---|
completed |
报告已生成；只读任务完成，或批准补丁已应用 |
blocked |
需要补充信息，或受策略/工具结果阻塞 |
cancelled |
Runtime 收到明确取消请求 |
failed |
schema、注册表、节点或内部契约失败 |
budget_exhausted |
模型、工具、读取字符或总时间预算耗尽 |
终态一旦写入便不能继续迁移。CLI 同时输出稳定 reason_code，调用方不需要解析平台异常
文本来判断失败类型。
- Phase A — 只读 Runtime（已完成）：受控调查、候选计划与事实报告。
- Phase B — 审批式补丁（已完成）：在显式授权后生成并应用受限变更。
- Phase C — 验证闭环（已完成）：执行审批绑定的注册命令并进行最多一次有界修复。
- Phase D — 报告与恢复（已完成）：持久恢复、产品图装配、lease heartbeat、终态 artifact 清理和真实产品路径的组合验收均已完成，详见 Phase D 验收。
- Phase E — 可执行评测（已完成）：版本化 suite、真实产品路径、确定性 oracle、 指标与 baseline 比较、双平台核心路径测试、scripted gate 和首份真实 Provider Pilot 均已完成，详见 Phase E 验收。
- Phase F — 架构收敛（已完成）：CLI、Application、Persistence、Runtime、Graph、 Evaluation 与 Inspector 的职责边界已收敛，并通过 v0.1.0 特征样本、双平台门禁和 重构前 deterministic baseline 比较，详见 Phase F 验收。
什么时候需要提供 --script？
默认 scripted provider 必须提供有限响应脚本，它不访问网络，适合确定性测试和 CI。
使用 --provider deepseek 时不提供脚本，而是从 DEEPSEEK_API_KEY 建立真实客户端。
配置了 writable 路径或验证命令后会执行吗？
默认不会。只读模式始终把写入和验证预算固定为零。--mode patch 只允许审批后写入，
仍不会执行验证命令。只有显式 --mode patch-verify、配置正写入与验证预算、计划选择
注册命令，并提交同时绑定 patch 与 verification 摘要的审批 JSON 后，才会运行命令。
Antrail 会读取 .env、凭证或私钥吗？
不会。内置 protected 规则与项目 sensitive pattern 会在工具执行前拒绝这些路径，拒绝 事件也不会包含敏感正文。
Inventory 被截断后还会继续分析吗？
可以，但 inventory_complete 会保持为 false，截断原因会进入项目画像和模型上下文，
避免把不完整清单误报成完整事实。
欢迎通过 Issue 讨论缺陷、设计和使用场景，或提交范围清晰、测试完备的 Pull Request。 提交前请运行上方的完整验证命令，并确保变更不削弱默认只读、审批绑定和审计能力。 安全漏洞请按照安全政策私密报告，不要创建公开 Issue。
提交代码前请阅读贡献指南和行为准则； 使用问题与维护范围见支持政策。
Antrail 采用 Apache License 2.0 许可。