CatPaw：AI 编程跨会话工作流

面向 coding agent 的 local-first 工作流运行时，用 Work、Proof 和 Approval 管理跨会话协作与可验证交付。

项目地址：https://github.com/shiqkuangsan/catpaw ｜ MIT 开源协议 ｜ 当前源码版本：3.4.3（main，2026-08-29）

这是什么

CatPaw 是面向 coding agent 的 local-first 可靠执行运行时（runtime）。它位于用户、AI Agent 和项目工作记录之间，负责把一次任务从理解推进到交付，并用文件系统保存跨会话仍有价值的事实。

它不是 IDE、模型提供商、prompt 包或完整的任务管理器。它解决的是 AI 编程中经常出现的协作问题：

  • 新会话找不到上次的目标、决策和下一步
  • Agent 声称“完成”，但验证证据和剩余缺口不清楚
  • 多 Agent 修改同一份文件，所有权和合并边界模糊
  • commit、push、deploy 或其它不可逆动作没有明确的授权边界

CatPaw 不替 Agent 决定所有事情，而是把交付结果、可检查证据和用户授权边界显式化，让工作可以继续、复盘和交接。

当前工作模型

CatPaw 3.4 将用户需要理解的模型收敛为三个并列概念：

概念作用
Work要交付的结果、当前进度和下一步 Next；需要跨会话时写入项目工作板
Proof支撑判断的可检查事实、复现结果、独立审查和剩余缺口
Approval只有用户可以提供的新增权限或风险接受；不会被 Agent 输出或 Proof 自动授予

对外可见的流程是：

Understand -> Execute -> Check -> Finish

每个 Work 都会先经过一次轻量的 Understand readiness pass。没有会改变交付的歧义时，CatPaw 保持简短并继续执行；如果歧义可能改变结果、范围、验收、数据或权限边界，或涉及外部与不可逆选择，Agent 会先展示当前理解、已核对事实或假设、当前真正需要用户决定的问题，以及这些决定解锁的第一个交付切片。它不会因此增加一个强制的 Clarify 阶段或新的 artifact。

内部仍使用 schema 2、Direct / Tracked / Gated 等路由元数据，但这些是运行时实现细节，不要求用户学习或手动选择。

最新功能更新

以下内容按仓库 main 的源码版本和 src/runtime/CHANGELOG.md 整理；源码版本不等同于 GitHub Release 页面上的标签。

版本日期主要更新
3.4.32026-08-29对所有 Work 启用 Understand readiness；只追问会改变交付的决策或只能由用户提供的阻塞事实，并让当前理解和首个可交付切片可观察
3.4.22026-08-26将 decision frontier、根因调试循环、双轴审查、限时 prototype、上下文切换和 expand -> migrate -> contract 等方法并入现有运行时权威
3.4.12026-08-16为多系统或多关注点 Work 增加按需的浅层 scope tree、依赖边和 Confirmed / Proposed / Open 局部注记；不新增树状 artifact
3.4.02026-08-14公开模型统一为 Work / Proof / Approval；增加 status、Work、Proof、intent 和 transport 等 CLI 门面，并保留 3.x 兼容入口
3.3.02026-08-13允许明确授权的 Builder 在独占 worktree 和非保护分支上创建一个本地 slice commit；Primary Agent 必须独立审查后才能采纳
3.2.02026-08-13增加基于风险的 Agent dispatch 合约、bounded Task Envelope 和 explore / build / check 意图；只并行处理没有共享可变范围或顺序依赖的工作
3.0.0–3.0.52026-07完成 hybrid runtime、schema 1 到 schema 2 的显式迁移、运行时激活校验和旧工作板导入加固

这些更新的共同原则是：增加可观察性和验证能力，但不把内部角色、阶段或调度细节扩张成用户必须维护的新系统。

Agent 协作

三种 bounded intent

CatPaw 用意图描述一次 Agent 应负责的结果，而不是定义人格、模型或权限：

Intent责任
explore建立事实、边界、选项和设计
build实现或集成一个精确、隔离的范围
check审查缺陷或验证验收

Primary Agent 决定使用哪些 Agent、模型和 transport，以及串行还是并行，并负责最终候选的接受。一个 Agent 可以组合多个意图，但改变意图名称不会产生新的权限，也不会让同一个 Agent 的自审查变成独立 Proof。

实质性委派使用一次性的 bounded contract，至少说明结果、事实、读写范围、约束、输出格式、验证方式、依赖关系、停止条件和允许的动作。不同 Agent 不得同时写同一份可变表面；需要并行时，应使用隔离 worktree 或等价的隔离状态。

本地提交与外部会话

3.3.0 起，Builder 只有在 Primary Agent 明确给出独占 worktree、非保护分支、精确写入范围、干净基线、验证和凭据扫描要求，并标记允许本地 slice commit 时，才可以创建本地提交。该提交只是交接候选，不代表已经集成；push、PR、deploy、保护分支更新、改写历史和破坏性清理仍需用户明确授权。

CatPaw 管理两个 reciprocal、只读的外部 transport：cc（Claude Code）和 cx（Codex）。transport status 只报告进程、退出码和终端输出等可观察事实；空 stdout、进程稳定或退出成功都不能单独证明任务完成。

跨会话记忆与目录边界

CatPaw 将源码、构建包、已安装 runtime 和项目工作板视为四个独立表面：

source -> dist -> installed -> project board

项目工作板位于项目根目录的 .catpaw/，schema 2 的常见结构如下：

.catpaw/
├── index.md              # 活跃工作概览
├── milestones/           # 可选的阶段目标
├── work/                 # Work Item
├── plans/                # Work 的持久计划
└── evidence/             # typed Proof，按主题或 Work 组织
    └── topics/

Work 映射为 Work Item 和 Plan，Proof 映射为 typed Evidence（research、review、test、provider、reflection 等类型），而 Approval 仍是用户授权边界，不是新的 artifact。旧版 todos/ 等目录可以通过显式 migration 导入；迁移会保留带 checksum 的 legacy/schema-1/ 归档，不会把源码仓库的 docs/、scripts/ 或测试目录复制进已安装 runtime。

CLI 与日常使用

安装后的命令可用 catpaw --help、catpaw <command> --help 和 catpaw --version 发现。推荐的日常入口是：

catpaw status
catpaw board init|status|doctor|migrate
catpaw work start|show|update|finish|cancel
catpaw milestone start|show|add|finish|cancel
catpaw proof add|list|show
catpaw intent list|show
catpaw transport check|open|send|status|read|close

Mutation 默认是 dry-run，只有显式 --apply 才写入。proof add 支持内联文本、文件和 stdin，避免把长篇 Proof 塞进命令参数。intent 是只读的合约发现入口；board 保留初始化、诊断和迁移等维护能力；transport 用于高级的 cc / cx 会话。

3.x 的 board status、work close、milestone close、evidence add、agent ... 和 --mode tracked|gated 仍作为兼容输入保留，但新文档应优先使用上面的公开命令和概念。

源码检出时，入口是 node src/runtime/bin/catpaw.mjs；安装后入口是 node ~/.catpaw/bin/catpaw.mjs。文档中的 catpaw 只是这个入口的简写，CatPaw 不会自动修改系统 PATH。

安装与升级

克隆、构建和验证源码包：

git clone https://github.com/shiqkuangsan/catpaw.git
cd catpaw
node scripts/build-runtime.mjs
node scripts/verify-runtime.mjs

构建只生成 dist/runtime/，不会自动写入 ~/.catpaw/，也不会修改全局或项目 adapter、注册表或项目工作板。需要安装或升级时，按仓库的 AI-INSTALL.md 和 Runtime Maintenance 单独执行，并先查看 dry-run 的文件变更和保留规则。

首次在项目启用工作板：

catpaw board init --apply

如果项目已有旧版 todos/，先运行 catpaw board migrate 查看完整映射和阻塞项；确认无误后再使用 --apply。runtime 激活、host adapter 合并、项目注册和 schema 迁移是彼此独立的动作，不会因为其中一步完成而自动触发其它动作。

适用范围与限制

CatPaw 特别适合跨多天、跨会话或需要清晰交接与验证证据的 coding-agent 工作。一次性的 typo、小脚本和明确的局部修复可以直接在当前会话完成，不必为了形式创建工作板。

它依赖本地文件系统保存状态，Proof 是可检查的支持事实而不是加密签名；最终完成判断仍需要 Agent 或用户按实际证据复核。CatPaw 负责协调、记忆和授权边界，不替代具体的编译器、测试框架、浏览器工具或部署平台。

相关资料