bound

BOUND

在完成有意义的执行步骤后使用 BOUND，以决定 Agent 应继续、重试、重新规划还是回滚。BOUND 评估已完成的工作；它不决定要编写什么代码。

Agent 集成类型

所有 BOUND Agent 集成都仅基于指令——即 Agent 阅读并遵循的提示词。没有强制执行的集成（没有以编程方式接入 Agent 的事件系统、MCP 服务、规则或生命周期事件）。每种集成都依赖 Agent 自愿遵循指令并根据 BOUND 的决策采取行动。

Agent	文件	类型	机制
Cline	integrations/cline/INSTALL_BOUND.md	仅基于指令	基于提示词；Agent 遵循指令
Codex	integrations/codex/INSTALL_BOUND.md	仅基于指令	基于提示词；Agent 遵循指令
Claude Code	integrations/claude-code/INSTALL_BOUND.md	仅基于指令	基于提示词；Agent 遵循指令
Hermes Agent	integrations/hermes-agent/INSTALL_BOUND.md	仅基于指令	基于提示词；Agent 遵循指令
Kilo Code	integrations/kilo-code/INSTALL_BOUND.md	仅基于指令	基于提示词；Agent 遵循指令
通用	integrations/generic/INSTALL_BOUND.md	仅基于指令	基于提示词；任何 Agent 都可遵循指令

关键区别： 仅基于指令的集成会说明 BOUND 控制循环，并指示 Agent 在每个边界处手动调用 BOUND 的 CLI 或 Python API。Agent 负责根据决策采取行动——BOUND 不会强制执行该操作。强制执行的集成（未来提供）会接入 Agent 的事件系统，在决策到达 Agent 前进行拦截。

集成前先检查

1. 将最新的稳定软件包安装到项目环境中：

   pip install bound-policy
   

2. 检查已安装的 API，不要依赖记忆中的签名：

   python -c "import bound; print(bound.__version__); print(bound.__all__)"
   bound integration-spec
   

3. 确认项目实际使用的测试、lint、类型检查和构建命令。

4. 检查 Agent 实际支持的钩子、模式、指令、命令、任务边界、遥测和检查点。不要臆造原生 BOUND 集成或未文档化的框架机制。

5. 查找现有的 INTEGRATION.md、INTEGRATION_REPORT.md、PLAN.md 和 bound_integration/ 文件。将记录的结果视为需要复现的说法，而非权威证据。

建立执行沿袭记录

对于多步骤工作，请在仓库根目录维护 PLAN.md。小型的一步任务可以使用内联计划。为每个有意义的阶段分配一个稳定 ID，并在适用时定义其目标、可观察的验收检查、风险检查、验证命令、预算、预期产物、负责人和依赖关系。

维护以下沿袭记录：

intent -> plan phase -> StepContract -> execution -> ExecutionEvidence
       -> BOUND evaluation -> control action -> integration report

执行后保留阶段记录。当策略发生实质性变化时，创建派生 ID，例如 PHASE-002-R1；不要重写历史来掩盖重新规划。

选择有意义的边界

在实现并完成验证后、针对特定问题重试后，以及决定是否继续完善同一目标前，调用 BOUND。不要在每个令牌、文件读取、Shell 命令或底层工具调用后都调用它。

每个边界都必须具备可观察的完成标准。如果无法观察到有意义的成功或风险信号，请合并或重新定义步骤。

修改项目之前先报告提案

实现前记录以下标题：

Integration point:
Step boundary:
Available evidence:
Missing evidence:
Control-flow mapping:
Files to modify:

列出确切的验证命令，以及少量可移除的集成文件。对于无法获取的指标，应标记为不可用，而不是估算。

构建契约与证据

将每个阶段映射到一个 StepContract，其中至少包含一个 AcceptanceCheck、可选的 RiskCheck、预期产物和一个 StepBudget。仅收集运行期间观察到的 ExecutionEvidence：命令退出码、检查结果、变更的产物、重试次数、工具调用、 令牌数、运行时长，以及可用时的回滚可用性。

确保契约和证据中的 check_id 值一致。缺少必需检查的证据不算通过。 区分未设置的预算（None）、不可用的测量值和观察到的零。

如果已安装的 evaluate_agent_step(...) 辅助函数在检查其 API 后确认可用，优先使用它。否则调用 BoundWorkflow.evaluate_step(...)，并严格使用：

ACCEPT   -> continue
RETRY    -> retry
REPLAN   -> replan
ROLLBACK -> rollback

绝不要添加第五个操作，也不要复述 BOUND 的评分和决策公式。

已验证证据与溯源（v0.7.0）

BOUND v0.7.0 将证据的报告者与验证者区分开来。Agent 是参与者，而非裁判。

• 提前定义契约，包括溯源要求。 每个 AcceptanceCheck / RiskCheck 都可以声明 accepted_provenance（其接受哪些可信溯源）、on_missing、on_claimed，而风险检查还可以声明 decision_critical（缺失或声称的证据随后会强制将保证级别设为 INSUFFICIENT，并阻止干净的 ACCEPT）。

• 配置允许的收集器；由 BOUND 执行客观验证。 使用 BOUND 收集器（PytestCollector、GitCollector、JUnitCollector、BudgetCollector、ProcessRuntimeCollector、CommandCollector，以及原生的 RuffEvidence、MypyEvidence、CoverageEvidence）来执行由 BOUND 控制的验证。它们会记录 evidence.collected 审计事件，其中包含 VERIFIED/OBSERVED 溯源、收集器名称和版本、产物哈希，以及带时区的时间戳。收集器崩溃或产物过期时，会如实记录为 evidence.collection_failed / INVALID，绝不会算作已验证通过。

• Agent 不能指定 VERIFIED 溯源。 Agent 自行报告的内容始终为 CLAIMED，绝不会是 VERIFIED/OBSERVED。Agent 不得覆盖或隐藏收集器结果。MISSING 表示“未收集”，绝不能静默地记为 0；遥测指标中的 None 表示缺失，而非测得的零。

• 主观标准使用独立评估器（EVALUATED）。 无法独立重新运行的标准（例如 UX 质量）属于 EVALUATED——虽如实，但绝不算作 VERIFIED。

• BOUND 记录 Agent 的报告；Agent 执行控制操作。 BOUND 记录 action.reported（reported_provenance=CLAIMED）；独立钩子可以添加 observed_action 以确认该操作。Agent 执行控制操作。 BOUND 是轻量级工具框架：它会发出 ROLLBACK，并可独立验证由此产生的状态。它可以使用明确的 bound rollback --execute，针对先前已确认的检查点回滚工作区，但必须明确选择启用。

• 保证级别决定候选决策是否可通过。 BOUND 根据决策关键检查的溯源计算 DecisionAssurance（VERIFIED/MIXED/CLAIMED/INSUFFICIENT）。如果候选 ACCEPT 仅由 CLAIMED/MISSING 的关键证据支持，则会降级为契约的 on_missing/on_claimed 操作。查看方式：

  bound inspect <run_id>                  # per-check provenance + candidate vs final + assurance + coverage
  bound inspect <run_id> --only-unverified # only unverified/claimed/missing/invalid evidence
  bound inspect <run_id> --json           # machine-readable: provenance + assurance + coverage
  

持久化数值评估结果

对于每次评估，从返回的 BOUND 对象中读取数值并输出：

BOUND evaluation
Acceptance (A): <4 decimals>
Influence (I): <4 decimals>
Risk (R): <4 decimals>
Cost (C): <4 decimals>
Score (S): <4 decimals>
Threshold (T): <4 decimals>
Decision: <ACCEPT|RETRY|REPLAN|ROLLBACK>
Next action: <continue|retry|replan|rollback>

同时持久化公开的权重、加权分量、重试余量、回滚风险阈值和评分溯源。请阅读 references/integration-report.md，了解所需的报告结构。

验证之前的评分

当存在较早的集成记录时，请将其契约、证据、标准、预算、评分、决策和操作与当前运行进行比较。如果其输入完整，请重建这些输入并再次调用 BOUND。将返回的 A/I/R/C/S/T、决策和操作与记录进行比较。

• 将不完整的历史结果标记为 not reproducible，并列出缺失的数据。
• 当证据或配置发生变化时，将评估标记为 stale。
• 追加新的评估，而不是悄悄覆盖历史记录。
• 将不一致视为一致性检查失败，并在继续之前调查。
• 不要另行实现公式，作为第二个评估器。

根据结果采取行动

• ACCEPT：停止完善此阶段并继续。
• RETRY：保留策略，进行一项有针对性的修正，收集新证据，并在预算范围内重新评估。
• REPLAN：停止当前策略，选择实质上不同的方法，并创建派生的契约 ID。
• ROLLBACK：仅恢复到先前确认安全的检查点，不丢弃无关或预先存在的更改，然后重新规划。如果不存在安全检查点，请说明这一点，并避免采用破坏性近似方案。

记录决策沿袭（v0.7.0）

BOUND v0.7.0 可以将每次评估记录为可复现、仅追加的本地沿袭——contract → evidence → scores → decision → agent outcome——并存储在 .bound/runs/<run_id>/ 下。此功能按运行选择启用，且向后兼容：如果从未启动运行，就不会记录任何内容。使用 BOUND_LINEAGE_DISABLED=1 可禁用此功能。

对于使用 BOUND 评估的任何非简单任务，请遵循以下规则：

1. 每项任务只启动一个运行。

   bound run start "<task>" --metadata phase=PHASE-001
   

   （在 Python 中：with bound.start_run("<task>") as run:。）

2. 使用稳定的步骤／契约 ID。 将同一 ID 从 PLAN.md → StepContract(id=...) → 沿袭贯穿始终。同一步骤重新规划时，追加 -R<N>（PHASE-001 → PHASE-001-R1）；绝不要另起无关的 ID，也不要改写历史记录来掩盖重新规划。

3. 仅在有意义的边界进行评估（实现和验证完成后，而不是每个令牌／文件／命令之后），并将评估记录到运行中：

   bound evaluate --run <run_id> --step PHASE-001 --attempt 1 \
       --action "..." --goal "..." \
       --acceptance A --influence I --risk R --cost C \
       --threshold 0.7 --retry-margin 0.1
   

   这会写入 step_started + evaluation_recorded，并向 JSON 添加一个 lineage 块。

4. 记录你实际采取的后续操作——而不是 BOUND「本应」产生的操作：

   bound outcome --run <run_id> --step PHASE-001 --attempt 1 \
       --decision REPLAN --note "switched strategy to validator + parametrized tests"
   

   如果省略 --next-action 和 --reason-code，它们将根据 --decision（ACCEPT|RETRY|REPLAN|ROLLBACK）推导得出。

5. 任务结束时明确关闭运行：

   bound run finish <run_id> --status completed|interrupted|failed --note "..."
   

   缺少 run_finished 表示运行不完整／崩溃（日志仍可读取）。如果使用了 with bound.start_run(...)，上下文管理器会在退出时自动结束被中断的运行。

6. 报告本地沿袭路径——.bound/runs/<run_id>/（run.json + 仅追加的 events.jsonl）——并展示决策树：

   bound inspect <run_id>
   

规范流程是一个运行、两次尝试：

Attempt 1  →  evidence 1/3 (A=0.3333)  →  REPLAN  → switch strategy
            (new step PHASE-001-R1, attempt 2)
Attempt 2  →  evidence 3/3 (A=1.0000)  →  ACCEPT  → continue to next step

事件日志仅追加：重新规划会发出新的 step_started，其 attempt+1，且契约 ID 带有 -R<N> 后缀；不会改写较早的尝试。绝不会存储提示词、令牌和源代码——只记录契约 ID、评分、阈值、决策、原因代码以及你的后续操作／备注。完整数据模型和 API 请参阅 docs/lineage.md。

验证集成

添加端到端测试，构建真实契约、收集真实的观测证据、调用 BOUND、断言四种决策之一，并断言精确的控制流映射。除非证据确实满足契约，否则不要将 ACCEPT 写死。

在使用方仓库中，所有接线逻辑都应保持精简，并置于 src/bound/ 之外。绝不要伪造证据、重复实现策略逻辑，或使用 LLM 作为最终裁决者。