Unit Executor 是一个面向研究工作区（Workspace）的原子化执行技能。其首要原则是原子性：一次调用只负责一个 Unit 的一次 Attempt，要么提交一个被接受的 Completion，要么记录一个可诊断的 block，绝不会启动第二个 Unit。
用途
它用于在已有的研究 Workspace 中精确执行一个符合条件的 Unit，适合逐步执行或手动语义执行。当需要按状态、Attempt、Artifact、Manifest 等条件推进单个 Unit 时使用。若需要跨 Unit 自动连续执行，应使用 research-pipeline-runner。
输入
- UNITS.csv 以及被选中的 Unit 行。
- 该行 inputs 字段声明的文件。
- 当 Unit 受 checkpoint 门控时，需要 DECISIONS.md。
输出
- Unit 的 outputs 字段声明的文件。
- 更新后的 UNITS.csv、Run Evidence，以及可选的 STATUS.md 投影。
- 当严格质量检查阻止 Completion 时，输出 output/QUALITY_GATE.md。
执行步骤
-
协调并选择一个 Unit：通过 Pipeline 适配器检查 Workspace，选择请求的 Unit，或选择依赖已 DONE 的第一个 TODO Unit。当遇到 HUMAN checkpoint、未解决的 Decision、打开的 Attempt 或完整性失败而无法选择时停止。完成标准：恰好选中一个符合条件的 Unit，或记录一个阻塞条件并给出具体下一步动作。
-
打开 Attempt：通过适配器开始语义工作，而不是直接编辑状态单元格：
uv run python scripts/pipeline.py mark
--workspace workspaces/<name>
--unit-id <U###>
--status DOING
--note "starting semantic execution"
完成标准：Unit 处于 DOING，且有一个匹配的打开 Attempt 拥有该执行。
-
执行声明的 Skill：读取所选 Unit 的 Skill，以及该分支所需的上下文指针。产出声明的输出，不修改无关的 Workspace 工件。完成标准：每个必需输出都存在，或失败足够具体可提交为 BLOCKED。
-
验证并提交 Completion：评估 Unit 的 acceptance 规则，并在要求时评估严格质量契约。通过适配器提交：
uv run python scripts/pipeline.py mark
--workspace workspaces/<name>
--unit-id <U###>
--status DONE
--note "acceptance checked"
当 acceptance 失败时，使用 BLOCKED 并给出具体原因。不要直接编辑 UNITS.csv；适配器会同步 Attempt、Artifact、Manifest、Decision 和状态投影。完成标准：Completion 为 DONE 并带有 acceptance 与 provenance 证据，或为 BLOCKED 并带有可诊断的 Failure。
- 在一个 Unit 后停止：刷新 Workspace 投影并报告已完成或阻塞的 Unit。不要声称端到端完成，也不要启动下一个符合条件的 Unit。完成标准：本次调用中恰好一个 Unit 改变了执行状态，下一位操作者可以从 Workspace 文件继续。
上下文指针
- UNITS.csv 中被选中的行拥有 dependencies、inputs、outputs、acceptance、checkpoint 和 Skill 身份。
- 被选中的 Skill 拥有语义行为。
- 锁定的 Pipeline 拥有跨 Unit 门控和目标 Artifacts。
- 跨 Unit 自动连续执行请使用 research-pipeline-runner。
脚本与快速开始
uv run python .codex/skills/unit-executor/scripts/run.py
--workspace workspaces/<name>
全部选项
- --workspace <path>：已存在的 Workspace。
- --unit-id <U###>：执行一个特定的符合条件的 Unit。
- --inputs、--outputs、--checkpoint：Pipeline-runner 兼容参数。
- --strict：阻止类似脚手架的输出，并写出质量门报告。
示例
运行恰好一个严格 Unit：
uv run python .codex/skills/unit-executor/scripts/run.py
--workspace workspaces/<name>
--strict
等价的适配器命令：
uv run python scripts/pipeline.py run-one
--workspace workspaces/<name>
--strict
该辅助脚本在 DONE 或 IDLE 时返回 0，在 BLOCKED 或 ERROR 时返回 2。
故障排查
- 当没有可运行的 Unit 时，先检查依赖、checkpoint 批准和打开的 Attempt，再更改状态。
- 当 DONE 的 Unit 缺少输出时，通过适配器重新打开它并附上说明性备注；绝不要只修复 CSV 投影。
适用场景与限制
适用于需要严格控制单步推进、手动语义执行或逐步执行的研究流水线场景。限制在于它一次只处理一个 Unit，不负责跨 Unit 自动连续执行；不直接编辑 UNITS.csv；遇到 HUMAN checkpoint、未解决 Decision、打开 Attempt 或完整性失败时会停止。