技能介绍

Rootloom 是一个本地工程工作流，由 qingye-lab 制作。它的目标可以概括为一句话：把 Codex 的代码改动变成可检查的工程工作（Turn Codex code changes into inspectable engineering work）。

它由两部分组成：一个完整的原生 OpenAI Codex 插件，以及一个独立的 Agent Plugins 可移植预览版。原生插件暴露四个技能，分别用于改动代码、审查改动、维护仓库指引，以及管理可选的安装项；可移植预览版只暴露 Change、Review 与 Project Guidance，不含 Codex 专有的 Hooks 与 Setup。

Rootloom 不是另一个编码代理，也不替代你的编辑器、测试或 CI。Governed 与机器证据类工作仍然只是 Change 的模式，而不是额外的公开工作流。

它的适用边界被刻意收窄：

  • 它是：带完整原生 OpenAI Codex 插件的单代理工程工作流。
  • 它是：面向 Change、Review、Project Guidance 的 Agent Plugins 1.0.0 可移植预览。
  • 它是：本地的、可检查的，运行时只用 Python 标准库。
  • 它不是：规格框架、测试运行器、linter、密钥扫描器、CI 系统，也不替代人工评审。
  • 它不是：用于运行不可信验证命令的沙箱。
  • 它不承诺：在不同编码代理客户端之间提供等价的 Hooks、Setup、权限、证据或模型行为。

规格类工具（如 GitHub Spec Kit 与 OpenSpec）帮助在实现前定义工作；测试、linter、扫描器与 CI 执行各自的检查。Rootloom 处在执行与评审的边界上：为什么这样改、为什么改这里、跑过什么、有什么证据支持「已完成」。

适用场景

  • 修复缺陷，但不想再出现「补在离报错最近的那一行」这类修补错层的问题。
  • 需要一次可追溯的代码改动：小 diff、范围清晰、审查者能看懂。
  • 审查一个 diff、PR、迁移或设计，只要发现与证据，不要补丁。
  • 想让项目的仓库指引（AGENTS.md）固化下来：项目命令或长期不变量应当持久存在。
  • 需要严格的证据记录：把行为声明绑定到真正运行过的命令上。
  • 想在多个项目之间复用同一套工作约定（可选 Setup 与 Autonomy Rules）。

核心能力

四个入口，按任务选择：

↔ 左右滑动查看完整表格
你想让 Codex…使用何时用它
构建、修复、重构、迁移、部署，或采集严格证据$operating-coding-change唯一的实现入口；它路由 Direct、Scoped、Governed、Evidence 与 External Action 模式
审查 diff、PR、迁移或设计，且不做编辑$operating-code-review你要的是发现与证据，不是补丁
播种、刷新、精修或校验仓库的 AGENTS.md$project-guidance项目命令或长期不变量应当持久化
安装、升级、检查或回滚可选的全局 Setup$setup-rootloom你想要跨项目指引或 Autonomy Rules

Rootloom Core 始终提供这四个入口。Change 只在任务需要时加载详细的 governed、external-action、verification 或 Evidence Reference。版本号与序列化产物本身不触发兼容性判定：可再生的内部记录保持 Scoped 且仅限当前版本，而回滚恢复完整的旧版本、历史重放使用与之匹配的运行时。运行时兼容性需要真实切换后消费者的证据。Project Guidance 可以在活跃的仓库指引要求检查时执行校验，但持久的播种、刷新或精修需要用户明确意图；仓库只有在带有精确的独立标记 `` 时才能授权对单个文件的一次精修，仅有文字描述永远不构成写入授权。

它反的是什么（常见失败 与 Rootloom 的应对）：

↔ 左右滑动查看完整表格
常见失败Rootloom 要求 Codex 改做什么
修补离报错最近的那一行找到真正拥有被破坏行为的组件
一直改到某个测试通过声明预期范围，并保留无关改动
只测主流程检查主路径、不变量，以及邻近的替代或失败路径
说「测试通过」却没有有用的记录列出真正运行过的确切命令与各自的结果
把退出码 0 当作完成证明检查范围、仓库状态或已采集的证据之后是否发生了变化
给每个任务都加流程用轻量的日常工作流；只在会改变决策时才选择更深的证据

实际价值很简单：更少改在错误层次上、更小的 diff、更清晰的评审，以及可以检查的完成声明。原文也明确说明：Rootloom 让工作更易被检视，但它不会让模型变得不会出错，也不会把通过的测试变成正确性证明。

证据模式（Evidence Mode）： 多数任务应当停留在常规的编辑-测试路径上。当一个改动需要可复现的本地记录时，显式向 $operating-coding-change 请求 Evidence Mode。可选的证据路径可以绑定：改动前的 Git 与仓库状态；允许与禁止的路径；把行为声明绑定到真正运行过的命令；验证后的第二次仓库采集；以及把机器观测结果与人的语义判断分开记录。它产出本地 bundle，内含采集到的 patch、测试日志与机器可读摘要。这是可检查的评审记录，不是安全证明，也不是不可篡改的审计系统。

「命令通过了」并不足够。 Rootloom 自己的开发过程给出了一个例子：一条验证命令成功退出，但运行过程中创建了一个新的被忽略的 .env 文件，并把它的合成值复制进了一个普通文件。命令通过了，但被评审的仓库状态没有保持不变。验证后的采集捕获到了这个差异，隔离了敏感路径，把变更内容排除在 patch bundle 之外，并让严格评审失败，而不是给出一个通过的完成声明。这个场景与可执行回归记录整理在 The command passed, the review failed。

技术契约要点： 可选的 Evidence 路径用 resources/evidence/analyze_change.py 做建议性分析；analyze_change.py --write-baseline 可以写入仅分析器使用的证据，而 governed intake 用 seal_contract.py 发布精确契约。严格评审使用 --strict；机器消费者应读取 quality_status 与稳定的能力字段 evidence_complete。REVIEW_EVIDENCE_COMPLETE 表示证据链完整，REVIEW_REQUIRED_WITH_REDACTIONS 表示存在实质性删改、无法给出该结论。Direct 与 Scoped 是自包含的常规路径，不加载任何 Reference；Governed 与 Evidence 会在第一次编辑前加载其详细契约，并在必需 Reference 无法加载时停止。仓库状态只有在两次连续的有界采集一致后才被接受，每次采集生命周期由 --max-capture-seconds 约束；包括新发现的被忽略新增项在内的实质性元数据变更，会在常规内容采集之前触发仅元数据的隔离。分类使用 is_sensitive_material_path；Rootloom 不是内容感知的密钥扫描器。Evidence 与 bundle 路径必须位于仓库工作树和解析后的 Git 公共目录之外。可选授权模式有 Single action、Standard 与 Full：Standard 跨任务持续，但每个任务仍需要明确目标与已解析范围；Full 永远不会被推断出来。

产品结构：

Rootloom Core
├── Change: Direct / Scoped / Governed / Evidence
├── Review
├── Project Guidance
├── Setup
├── Optional Autonomy: authorization modes / Command Rules
└── Optional Evidence resources: Analyzer / Baseline / Contract / Seal / Finalizer

Rootloom Memory
└── Separate experimental plugin

可移植预览版的取舍： portable/rootloom/ 是一个独立的 Agent Plugins 1.0.0 包，恰好包含 operating-coding-change、operating-code-review 与 project-guidance。兼容客户端从包根的 plugin.json 与固定的 skills/ 目录发现这些技能。Cursor、VS Code、GitHub Copilot CLI 与 Kiro 使用同一个包，不需要平台清单或重复的技能，只有各自的加载器配置不同；Copilot cloud 仍需要一个已发布、可解析的市场条目，Rootloom 目前尚未提供。Codex 保留其原生包，因为它的受管 Hook、Setup 与接口面是有意做得比 Agent Plugins v1 更大的。该预览版有意省略 Setup、Hooks、Rules、Memory、MCP、OpenAI UI 元数据以及插件级的 Evidence 助手，因此显式的 Evidence 请求会失败关闭（fail closed），而不是伪造一个证据包。不要把原生包与可移植包装进同一个客户端，因为重复技能的优先级没有标准化。

效果预览

Rootloom - OpenAI Codex 可检查工程工作流集合 preview
Rootloom 把风险、缺陷与项目上下文同证据、范围与测试编织在一起，产出经过验证的改动

工作方式

你仍然用自然语言描述任务，Rootloom 改变的是 Codex 处理它的方式：

  1. 编辑之前先读仓库及其本地规则；
  2. 判断风险并界定合理的范围；
  3. 对缺陷，把症状追溯到底层真正拥有该行为的边界；
  4. 做最小的自洽改动；
  5. 验证主路径、所属不变量与一条相邻路径；
  6. 报告真正运行过的命令、它们的结果，以及仍不确定的部分。

大多数工作只需要一次调用：

$operating-coding-change
Fix the reconnect race and verify reconnect, clean disconnect, and cancellation.

一次普通改动的流转如下：

Your request
    ↓
Repository evidence and local guidance
    ↓
Risk + scope
    ↓
Root cause for a defect / intended behavior for a feature
    ↓
Focused change
    ↓
Behavior-based verification
    ↓
Evidence-backed completion report

对于缺陷，Rootloom 会把调查推向一条显式的链条：

symptom → trigger → owning boundary → violated invariant → cause

对于新功能，不存在被发明的「根因」；工作流改为声明预期的行为与归属。验证是从「改了什么」推导出来的，而不是从「哪条测试命令最好跑」推导出来的。

你需要提供

  • 需要 Codex CLI 或支持插件的桌面版，以及 Git 与 Python 3.11+。
  • 用自然语言描述的任务（要修的问题、要实现的行为），以及你希望 Codex 遵守的约束（例如不要改公开 API）。
  • 若要用到跨项目的工作约定，需要显式请求可选的全局 Setup。

你会获得

一次有用的完成报告应当回答四个具体问题：

Cause        Where did the behavior originate, and which invariant was broken?
Change       Which files and behavior changed?
Verification Which commands actually ran, and what did each prove?
Risk         What remains unverified or uncertain?

如果显式请求了 Evidence Mode，还会得到一个本地 bundle，包含采集到的 patch、测试日志和机器可读摘要，作为可检查的评审记录。

使用示例

安装插件（两条命令即可完成）：

codex plugin marketplace add liyanqing90/rootloom
codex plugin add rootloom@rootloom

插件技能在任务开始时被发现，不需要项目配置、守护进程或单独的 Rootloom 命令。随后直接提出任务：

$operating-coding-change
The worker can reconnect after cancellation and create two active sessions.
Find the cause, fix it without changing the public API, and run the relevant tests.

可选的个人 Setup（跨项目工作约定，先给计划再安装）：

$setup-rootloom
Show me the personal preset plan, then install it if there are no conflicts.

Setup 是计划优先、带备份、拒绝冲突、可在文档限定的范围内回滚的。它不会改动你的模型、推理强度、沙箱、审批策略、provider、MCP server、插件或应用。

可选的 Rootloom Memory（Project Memory 不再被 Core 自动发现，只在你需要仓库自有的历史经验时安装）：

codex plugin add rootloom-memory@rootloom

它的 $project-memory 技能保留 rootloom-project-memory-v1，始终是建议性的，绝不覆盖当前源码、测试、schema 或运行时证据。

开发相关命令：

make check-changed BASE=origin/main
make validate
make test
make check
make compatibility-smoke
make telemetry-check

# Preview the website at http://localhost:8000
python3 -m http.server 8000

check-changed 是默认的开发路径：它从已提交、已暂存与未暂存的已跟踪改动中，按受影响的 owner 选择测试，同时排除无关的未跟踪文件；只有当这些未跟踪文件都属于当前任务时才加 INCLUDE_UNTRACKED=1。未知的可执行路径或共享的测试选择基础设施会回退到完整测试套件。