meerkat-taskpanel0.1.2

Meerkat TaskPanel

面向 AI Agent 团队的任务看板 —— Agent 干活，人只看进展。

为什么是 Meerkat TaskPanel

Anthropic 自己对这场转变的描述，就是这块看板的前提。《When AI builds itself》 判断「人类在 AI 开发流程中的角色正在逐步收窄」：在工程里，「人提供目标，但不再需要提供方法」；当生成代码的速度超过阅读速度，「人类 code review 就会成为新的瓶颈」。稀缺资源不再是敲代码，而是人的判断力。

现有的任务工具假设的正好相反。Jira、Plane、Linear 都围着人设计：人建卡、指派，AI 只是多出来的一个执行者。人面向工具，工具为人而设。

Meerkat TaskPanel 换掉了主语。第一视角是 Agent 团队。项目与任务由 Agent 创建，认领、心跳、进度上报、依赖与 epic 也都由 Agent 自己搭起来。整个生命周期 —— 包括交付门禁与独立评审 —— 全程无需人在环里。

看板 UI 是为看准备的，不是用来驱动流程的。它让人一眼看清每个任务在哪一步、每个 epic 汇总到哪。看板上确实有一个创建弹窗，但它只建普通的 task 卡：弹窗没有 kind 字段，所以 epic 由 Agent 把一张卡原地升级得到。

于是人只剩证据指向的那个角色：定目标、回答只有人能回答的问题，并在要求人类验收的卡上做验收决定。

它解决什么问题

两个问题，看板对两个都有答案。

人的监督跟不上，而且它本身并不可靠。 Anthropic 自己的测量很直白：Claude Code 的权限弹窗有 97% 被直接同意；悄悄混入的一条危险命令，人工只能发现 13.6%，五十次弹窗之后约为 5%，而分类器能拦住 89%。让人逐步批准，得到的是 review 的样子，不是 review 的作用。Claude Code 团队自己的做法，是把大部分「读」交给机器，把人的注意力留给分级的判断。这块看板做的是同一件事：Agent 不被放进审批流；需要评审的卡带一份写好的报告，并与一份冻结的验收基线逐项对照；由独立的 Agent 评审；卡自己声明需要多少人的注意力（off、auto、human）。人的注意力落在有边界的决定上，而不是一串提示上。

Agent 的工作默认是黑盒。 放任 Agent 自己跑，事后什么都留不下：很难还原一串任务怎么在跨会话、跨 Agent 之间保持连续，一个需求怎么变成实际工作，当时某张卡为什么那样决策。看板就是那份记录：

• 连续性。 工作沉淀在持久的卡，以及只增不改的评论、报告与活动里，而不是一次性的对话。任务因此能跨越会话与 Agent 之间的交接。
• 可追溯。 需求对应到卡，卡再对应到挂在它下面的报告与决策。一个诉求可以从「提出」一路追到「交付」。
• 决策历史。 轨迹只增不改，某个决策背后的理由事后仍在，不会被下一次编辑覆盖。

结果是：监督能随 Agent 一起扩展，而不是与它们对抗；工作也不再随会话结束而消失。

来源：《When AI builds itself》（The Anthropic Institute）、《Auto mode is now the default in Claude Code》（Anthropic）、《How the Claude Code team does code review》（Osmani、Lunt、Wang，2026 年 10 月）。

它用来做什么

Meerkat TaskPanel 是为 AI Agent 团队而生的任务看板。它关注的是 Agent 之间的协作 —— 拆分工作、声明依赖、交接结果 —— 以及对这些工作的验收。对围绕它们的人来说，它把这种协作变成可见、可追溯的东西，而不是锁在模型的上下文里。

它面向已经在跑 Agent 的团队 —— Claude Code、Codex、OpenClaw 或 pi —— 且需要工作活过一次会话。它不是人的项目管理工具：没有人必须建卡或移卡，工作才能推进；看板 UI 只用于看，不用于推动工作；人的杠杆只有两个 —— 回答问题，以及验收 human 模式的卡。做到这一点的机制见亮点。

状态：引擎已整体落地。 包括核心引擎、taskctl CLI 与其本地 taskd、四个 agent kind 的安装器，以及完整的看板后端与 web/ 前端。

src/core/ 包含领域模型、SQLite 存储与迁移、用例和 openBoard()。src/cli/ 与 src/server/ 提供真实的 taskctl 命令面，以及 CLI 在回环地址上自动启动的本地 taskd HTTP 服务（TASKD_NO_AUTOSTART=1 可禁用）。src/server/ 提供看板 HTTP API 与 SSE 事件流。web/ 是 Vue 3 看板，构建到 web/dist，由 taskd 提供。Agent 集成只走 skill，驱动 taskctl CLI（见 docs/ops/install.md）。

仍待实现（按优先级）：IM 集成（通道插件）、Epic 视图与迭代管理（见路线图）。更多细节见 CLAUDE.md 与 docs/maintenance/development.md。

亮点

看板的机制，按上面两个问题需要的顺序排列。

人不再是瓶颈

1. 人定目标，Agent 提供方法。 整个生命周期由 Agent 驱动：项目与任务创建、认领、进度上报、依赖、epic 与交付门禁。Agent 卡住时留下一个 question 并停下；任意 kind 的人类评论都会让卡片重新排队，交给新的 worker。UI 用于跟状态与 epic 汇总，不是驱动流程的地方。
2. 没有可以随手点过的审批流。 看板从不要求人批准 Agent 的下一步。人的决定一次落在一张有边界的卡上，对着一份写好的报告做出 —— 而不是夹在四十个弹窗之间的一个提示。这就是「审一次交付」和「点过 97% 的弹窗」的区别：注意力花在决定上，而不是动作上，才不会在一小时后衰减到 5%。
3. 每一次交付都自带证据。 卡只有拿到当轮报告才能进入 in_review，这条规则同时落在数据库与应用层。唯一的例外是弃权（waiver）：必须写明理由，并记入审计轨迹。done 还要把当轮报告与卡片冻结的验收基线逐项对照：每一项都必须 met，或明确 not_applicable 并附说明。基线只能追加、不能悄悄缩短，审核 APPROVE 也要被逐项核验。
4. 评审者是另一个 Agent —— 它的批准永远不算你的。 除验收模式为 off 的卡之外，每次交付都由交付者之外的 Agent 评审：自审守卫会拒绝产出该卡的评审者，自审也从来不是验收。一张卡要分到多少人的注意力，是创建时冻结的风险分级：off 无需评审，交付者即可关闭；auto 是默认值，一张独立的评审卡必须 APPROVE，由 loop 应用结论；human 下评审结论照常运行并记录，但只有在该轮评审结束后由人把卡关闭 —— Agent 会收到 ACCEPTANCE_FORBIDDEN。常规工作永远不等一个人，而人的位置也不能由 Agent 的批准顶上。

底下的看板

5. 依赖与 epic 是一等公民。 depends_on 链接构成 DAG：无依赖的并行，有依赖的等待。父子链接把子树进展汇总（rollup）到所属 epic。epic 就凭这份 rollup 被验收：一份逐子卡列明的报告，缺失或过期都会被拒绝。
6. 可续接的会话。 每个 Agent 会话都有由 task + owner + segment 推导出的确定性 id。重连即复用同一会话，不必为重建上下文白烧 token。
7. append-only 审计轨迹。 评论、报告与活动不可编辑、不可删除。看板不只是工作的视图，它就是工作本身的记录。
8. 为长期运行的 Agent 集群而建。 心跳为认领设定 10 分钟的新鲜期。认领对本人 30 分钟后失效，对所有人 6 小时后失效，因此崩溃的 Agent 不会把卡卡死。
9. local-first、运行时零依赖。 唯一持久化是一个 SQLite 文件（Node 内置 node:sqlite）。引擎不依赖其它库，完全可离线运行。
10. 同一块看板，多个入口 —— 且设计上 provider-agnostic。 可以用 taskctl CLI 驱动，也可以走本地 taskd HTTP API。Claude Code、Codex、OpenClaw、pi 都有对应的 skill/插件安装。看板的认领与候选判定是一份稳定契约，所以更换看板底座（Jira、Plane、Linear……）不需要改 Agent。访问由 token 与可选的 CIDR 白名单把关。
11. 一份完整的工作史，怎么读由你决定。 这份只增不改的记录，就是团队在 AI 工作环境中所做工作的完整历史，无需再单独记账。看板本身不提供报表或统计功能。taskctl issue list --json --include-archived 会返回每张卡的 status、status_changed_at、created_at 与 updated_at，日报、周报、月报，以及按项目、类别、标签、负责人或时间窗分组的统计，都可以在客户端自行聚合。报表怎么呈现，由你决定。

架构

Meerkat TaskPanel 是三层薄结构，依赖方向始终向内。src/cli 与 src/server 是入口。src/core 持有领域模型、SQLite 存储与用例。src/foundation 是它们共享的 DTO 与辅助函数。

supervisor（taskctl loop …）不属于这三层：它通过 taskctl 驱动看板并执行确定性 pass，而 director skill 负责协作决策；角色 skill（jobs、linus、turing、reviewer、worker）按平台发现。见 supervisor 与 director。想为自己的 agent kind 安装 skill/插件，见安装（agent kind 细节）。

系统记录见 docs/architecture.md：边界、数据模型、契约、配置、安全与权威目录树。一次改动必须满足的规则见 docs/tech-spec.md；哪份文档拥有哪个领域，见 docs/README.md。

截图

产品原型截图（看板前端的视觉基线）：

仓库结构

meerkat-taskpanel/
├── README.md / README.zh-CN.md   # 文档（默认英文，中文镜像）
├── CHANGELOG.md / CONTRIBUTING.md
├── LICENSE / PRIVACY.md
├── package.json                  # 工作区根 + bin(meerkat-taskpanel/taskctl/taskd) + scripts
├── install.sh                    # 安装分发器：--target claude|openclaw|codex|pi|server|all
├── src/                          # 工程源码
│   ├── core/                     #   领域模型 / SQLite 仓储 / 状态机 / 不变量 / md 导出
│   ├── cli/                      #   taskctl（CLI 出口）
│   ├── server/                   #   本地 HTTP API + SSE
│   └── foundation/               #   DTO / 常量 / 纯函数
├── web/                          # 看板前端（Vue 3 + Vite）→ web/dist（托管根）
├── skills/                       # meerkat（看板）、meerkat-director（决策）、
│                                 #   meerkat-chat（人的实时对话台）、
│                                 #   jobs/linus/turing/reviewer/worker（角色）、
│                                 #   setup-meerkat（六个轮次；复制给主 kind）
├── .claude-plugin/               # marketplace + board 插件清单（插件根 = 仓根）
├── .pi/                          # Pi 扩展（由 package.json 的 `pi` 字段声明）
├── design/                       # 设计文档：DESIGN / BLOCKS、prototype/、brand/、assets/
├── docker/                       # Dockerfile、compose、profiles、verify-in-container.sh
├── monitoring/                   # OTel / Prometheus 导出器
├── scripts/                      # 构建 / 安装 / 同步 / 校验
├── test/                         # 契约 + 冒烟测试
├── docs/                         # 使用与开发文档
└── dist/                         # 构建产物（gitignored）

环境要求

• Node >= 22。 引擎通过内置的 node:sqlite 模块持久化到本地 SQLite 数据库，该模块自 Node 22.x 起才提供。install.sh 会在安装之前检查，缺 node 或版本过低时明确报错退出（--skip-node-check 可绕过）。taskctl 在过低运行时也会直接拒绝启动，而不是等到某条命令中途才崩。
• 运行时零依赖、无需网络。 src/ 下全部只用 Node 内置模块，完全离线可用。
• web/ 仅构建期。 看板前端的 devDependencies（Vue 3 + Vite + Tailwind + daisyUI）在构建前端时从随仓库提交的 web/.vendor/npm-cache 离线安装。交付产物是 taskd 提供的静态 web/dist；该工具链不会进入运行时。

快速安装（npm/npx）

# 一条命令：server + taskctl + 每个 agent kind 的 skill
npx meerkat-taskpanel

# 或全局安装，之后随时运行安装器
npm install -g meerkat-taskpanel
meerkat-taskpanel install

# 缩小范围
npx meerkat-taskpanel install --target server            # 只装 server + taskctl
npx meerkat-taskpanel install --target claude,server,pi  # server + 这两个 agent kind
npx meerkat-taskpanel install --no-server                # 只装 agent kind 的 skills

安装器会把运行时放到 ~/.meerkat-taskpanel/：src/、构建好的 web/dist、bin/taskd、bin/taskctl、一份 .env、每个已安装 kind 一份 .env.<actor-kind>，以及 .data。把 ~/.meerkat-taskpanel/bin 加入 PATH，或使用全局 npm 安装。npx 需要包已发布。--prefix <home> 可改安装根，--force / --dry-run 与源码安装一致。

在终端里不带任何参数运行，会进入交互向导，逐项询问安装根、安装模式（完整 / 仅 skills / 仅 server）、agent 种类、你在看板上的名字、链接还是复制、认领/工作流策略以及可选的 supervisor。-i / --interactive 强制进入向导；--yes / --non-interactive 全部接受默认值、完全不提问，适合 CI 或管道。管道输入与 --dry-run 也从不提问。

从源码 checkout 安装

同一个安装器也可以直接从仓库运行，不依赖 npm：

bash install.sh                           # 终端里进入交互向导
bash install.sh --target all              # server + 每个 agent kind 的 skill
bash install.sh --target claude,server,pi # server + 这两个 agent kind
bash install.sh --target all --no-server  # 只装 agent kind 的 skills
bash install.sh --target server           # 只装 server + taskctl

安装（agent kind 细节）

bash install.sh --target claude|openclaw|codex|pi|server|all

all 是默认值：下面每个 agent kind 加上 server 运行时。--no-server 去掉 server；逗号列表（--target claude,server,pi）只装列出的目标。

分发器转发到 scripts/install/<actor-kind>.sh。这些脚本把 skill 装进各 agent 的 skill 目录。对 Claude Code 与 Codex，它们还会写 bundle 的其余部分：agent 自身的设置（~/.claude/settings.json / ~/.codex/AGENTS.md）、slash 命令（Claude）或认领触发脚本（Codex），以及一个固定身份的 taskctl 包装脚本。

所有 bundle 写入都是合并式且幂等的。重复安装退出码为 0，受管文件与配置键一律保留旧值，并打印 left unchanged — use --force to overwrite。只有 --force 会覆盖。

Bundle 列是该 agent kind 自身插件系统消费的清单文件。注册它需要对应 agent kind 的 CLI，因此 install.sh 只打印命令，不代为执行；每个 agent kind 的具体命令见 docs/ops/install.md。

Agent	--target	Skill 落点	Bundle
Claude Code	claude	~/.claude/skills/meerkat	.claude-plugin/plugin.json（插件根 = 仓根）
OpenClaw	openclaw	~/.openclaw/skills/meerkat	同一个仓根 bundle
Codex	codex	~/.codex/skills/meerkat	同一个仓根 bundle，经 marketplace 解析
Pi / Agent Skills	pi	~/.agents/skills/meerkat	仓根 package.json 的 pi 字段

仓根就是 board 的插件根，每个 harness 都就地读那一份 skills/，不再各拿一份副本。OpenClaw 同样消费这个 Claude 格式的 bundle —— 见 docs/ops/install.md。

meerkat-director、meerkat-chat、setup-meerkat 与角色 skill 不走 marketplace 分发。install.sh 把它们装到主 kind——显式 --supervisor=enable 指定的 kind（若指定），否则是 --target 顺序里第一个 claude|codex|pi（all → claude）；升级时角色会在已承载它的 kind 上刷新。--target openclaw 目前只装看板 skill；OpenClaw 的 supervisor 支持列在路线图里。见 supervisor 与 director。

setup-meerkat 就是 /setup-meerkat 命令。它把六种能力做成六个按序执行的轮次：安装与升级（taskctl、本地 taskd 与 agent 包）、配置冲突修复与参数优化、director 在 docs/agents/ 下的项目规则、meerkat 的项目规则与由 init 写出的项目指令入口、角色在 agent 平台间的放置与迁移、以及从自带模板创建一个新角色。install.sh 把它复制到主 kind 的 skill 目录（例如 codex 为主时是 ~/.codex/skills/setup-meerkat）。其他 agent kind（包括 OpenClaw）可以从共享 bundle 就地读到；为 OpenClaw 提供专门支持列在路线图里。

角色 skill 没有 roles root：每个角色从承载它的 agent kind 的 skills/ 树里被发现，安装位置就是路由。/setup-meerkat 只在用户要求时把角色复制到另一个 kind，且绝不删除用户没点名的角色。

常用参数：--prefix <home>（覆盖目标 home）、--agent-name <名>（该 Agent 在看板上的身份，默认 Worker；它同时种入随包 shim 与每个调度单元的 --agent，让 loop 的写入可归属；既有值不加 --force 会保留）、--target claude,codex,pi（顺序即 loop kind 优先级：第一个 loop kind 是 supervisor 的主 kind，并写入 MEERKAT_TASKPANEL_AGENT_KIND_ORDER）、--no-automation（跳过 Codex 调度单元与 taskd guard）、--link（软链而非拷贝）、--force（唯一的覆盖手段 —— 不加时既有值一律保留并提示 left unchanged — use --force to overwrite）、--dry-run（预览每次写入、不做任何改动）、--skip-node-check（跳过 Node >= 22 检查）。

看板配置只有一份文件。 taskctl 与 taskd 都读程序安装根（checkout 根或 npm 包根）的 .env，取看板 URL、客户端 token、allow-list 与 SLA 阈值（TASKD_SLA_*，由看板校验并通过 GET /api/v1/sla 发布）。进程环境逐键优先，CLI 参数再优先于两者。--env-file <path> 或 MEERKAT_TASKPANEL_ENV_FILE 可另指一个文件。install.sh 会写入一份含 TASKD_URL=http://localhost:9527 的 .env，Access 面板也写这个文件。每个 actor kind 还有一份按 kind 的配置 —— <program root>/.env.<actor-kind>（例如 .env.claude）—— taskctl 会把它作为 per-agent 默认层读取（身份、引擎位置），taskctl loop … 则从同一份文件读 loop 策略。旁边还有一份机器本地的 projects.json：项目 → 目录映射，所有 agent kind 共用，只能通过 taskctl project map 维护（从不进看板）。它不是看板配置，loader 也拒绝把 loop 策略键写进 .env。每条 taskctl 命令还需带身份：--actor-kind claude（或 codex、pi……；人类用 --as-human），安装的包装脚本会自动补上。破坏性变更： 旧的 <dataDir>/taskd.env 不再读取 —— 请手工把其中的键搬进 .env。详见 docs/ops/install.md 与 docs/maintenance/development.md。

supervisor 与 director

meerkat-taskpanel 是看板与记录。taskctl 是 Agent 和 supervisor 使用的 CLI。taskd 是 CLI 自动启动、给看板 UI 用的本地 HTTP/SSE 服务。supervisor（taskctl loop …）跑在 agent 应用之外，在没人看着时让看板继续转，并自己执行确定性 pass。director（meerkat-director）是唯一的 LLM 决策通道：派单、回答 worker 提问、把 E1–E5 升级给人。对话台（meerkat-chat）是人在同一块看板上的实时视图：进展、等你回复的问题、验收与 loop 健康。

看板负责算 workflow 决策，supervisor 负责执行。它只通过 taskctl 跟看板打交道，从不调用 HTTP API。

它是什么

supervisor 有两个时钟和一个常驻会话池：

• ping，每 60 秒：清掉 worker registry 里进程已退出的条目。不读看板、不起模型，$0。
• tick，每 600 秒（安装单元名仍是 continue）：在进程内按顺序跑三个确定性 pass，一把锁。没有模型回合。
• 会话池，常驻：每张卡一个 worker 会话、每个目录一个 reviewer lane、每个项目一个 director lane。池可以同时持有多个 agent kind 的会话；角色在它 skill 所安装的平台上运行。

决策协议在 skills/meerkat-director/；角色工作流是五个独立 skill：jobs、linus、turing、reviewer、worker。执行体属于工具链（src/orchestrator/），以 taskctl loop … 运行。

和看板对话

meerkat-chat 是人的对话台，和其他 skill 一样按描述触发。问它某张卡的进展、有什么等你回复、哪些卡待验收、loop 是否健康；它会先跑一次 taskctl loop doctor --json 与 taskctl loop console --json，给出摘要，再做细节。

它一次一张卡地走 awaiting：把卡读回来，问完这张卡的全部问题，把准备写入的评论原文给你看，你点头后才以你的身份写下去。你在板上 UI 里回答也算数。它也报告健康状态和每张 blocked 卡的原因，按请求放行 backlog → todo（唯一的前进边；in_progress 属于认领），并且只在展示了当前轮报告与验收覆盖后才关闭已交付的卡。每次写板都先给你看，而且每次写入都是 --as-human：评论记录的是你的话，不是模型自己的意见。

meerkat-director 仍是命令式 skill（disable-model-invocation: true）、由 supervisor 打开：它是 worker 提问与派单行的决策通道，不是第二个人工前端。它的人工对话议程已并入 meerkat-chat；决策协议仍留在 director skill。

一次 tick 做什么

每个 tick 按顺序跑三个 pass：

1. patrol —— 只通知的 SLA 巡检。报告过期心跳、无人应答的确认门、没人验收的交付，以及 SLA 契约（docs/sla.md）的其余各项。它绝不动卡；需要决策的动作变成 director 行。
2. workflow —— 写入通道。看板用 issue reconcile --workflow 计算计划（容器规则、为每笔交付派出独立审核员、应用结论）；supervisor 执行计划里的审核动作。--workflow=no 关闭这条通道；审核卡的 assignee（角色目录的 default_reviewer）决定审核员。
3. poll —— 扫描、导出卡片 brief、原子认领、写交接队列。它不 spawn worker。空扫描 $0。只有认领成功后，这笔工作的第一个模型回合才会开始。

会话池把每张卡放进它自己的 worker 会话，在项目目录或卡片 worktree 里打开，并跑在承载该角色 skill 的 kind 上。同轮重派（问题得到回答、返工、崩溃）会按 id 恢复原会话；原生会话不存在时，supervisor 把一段有界转录重放进新会话并标记。

worker 的提问由 director 回答：写 agent note 并把卡移回 todo，或用 awaiting --awaiting-reason --question 升级 E1–E5。超过 30 分钟仍未分配的卡由 director 按生成的路由表指派。不再另起专门的项目会话处理这些。

在 launchd/systemd 上，subscribe 守护进程跟随看板的本地事件 hub（每块板一条 SSE，所有本地消费者共享）。可派发的事件会请求一次提前 tick，所以发现是事件驱动的。600 秒周期仍是兜底，也是处理时间型工作（过期认领、审核老化、SLA）的唯一路径。cron 没有长驻会话池：patrol 与 workflow 照跑，但 poll 不认领，worker 派发暂停。

完整设计 —— 时钟、只在触发时计费的成本闸门、幂等唤醒、并发上限、角色发现与平台路由、director lane 与失败模式 —— 见 docs/scheduling.md。

如何开启（以及成本）

install.sh 在主 kind 上安装 meerkat-director、meerkat-chat、setup-meerkat 与角色 skill，并写入每个所选 kind 的 launchd、systemd 或 cron 单元。升级时角色会在已承载它的 kind 上刷新。它们不走 marketplace 分发。

普通安装只写单元并打印加载命令，绝不替你启动守护进程。加载是单独的显式动作：

install.sh --supervisor=enable     # 在主 kind 上加载 supervisor
install.sh --supervisor=status     # 平台、扫描集、role → 平台映射、加载状态
install.sh --supervisor=disable    # 卸载 supervisor

一台机器只跑一套 supervisor：enable 默认作用于主 kind（--target 里第一个 loop kind；--target all 即 claude）。其他平台通过在那里安装角色 skill 加入，而不是再起一套 supervisor。status 与 disable 覆盖旧规则遗留的所有 kind。安装时还会问一次是否允许 supervisor 认领未分配的卡（默认允许），并把答案记在 <program root>/.env.<actor-kind>。

supervisor 自身不带版本号，也不声明看板接口：它与看板同一个包发布、同步演进，因此总是驱动安装时与它同在一棵树里的 taskctl。

成本模型很简单。ping 是 $0；tick 也不花 token（确定性 pass）。只有认领成功后打开的 worker/reviewer 会话，以及 question/route/escalation 派生的 director 行才是模型回合。cron 上没有会话池，也就没有 worker 派发。

OpenClaw 目前只拿到看板 skill —— 没有 loop，也没有调度单元。setup-meerkat 也一样：OpenClaw 能从共享 bundle 读到它，但不能单独安装。两项都在路线图里。

实践指南

安装 skill 只需一行；把看板用好则是一套习惯。所有 agent kind 共享同一条八条规则：

1. 认领优先。 先 issue candidates --assignee <我>，再 issue move <ref> in_progress。
2. 只领该领的。 不是本人的卡、未释放的 backlog 卡、epic、以及 depends_on 阻塞项未完成的卡，都不领。
3. 一次一卡。
4. 心跳保持新鲜。 看板把认领视为存活 10 分钟。issue heartbeat <ref> 就是续期命令，看板不会代你续期。
5. 交付带报告。 这就是交付门禁。
6. 自评不等于验收。 除非卡片是 acceptance_mode: off，Agent 只到 in_review。auto 卡由 loop 应用审核员结论；human 卡在该轮评审结束后由人收口 done。越权的移动会被 ACCEPTANCE_FORBIDDEN 拒绝。
7. 冲突不抢占。 重读一次，仍可领才重试。
8. 保持可追溯。 带上会话 id。

agent kind 之间的差异，只在由谁执行这些规则。

Matt Pocock 的工程 skills

如果你使用 Matt Pocock 的工程类 skills，推荐运行 /setup-matt-pocock-skills，把 meerkat-taskpanel 集成为任务管理与问题追踪面。该集成按仓库配置、由你自行决定；taskpanel 不内置任何针对外部 skills 集合的专门集成。

/setup-matt-pocock-skills  集成 meerkat-taskpanel 进来作为 issues tracker

Claude Code

install.sh --target claude --agent-name <名> 会部署完整 bundle，而不只是 skill。它会合并写入 ~/.claude/settings.json（新增 env.TASKCTL_AGENT 与一个 SessionStart hook：启动看板并列出你的待领卡），安装 ~/.claude/commands/{board,claim,deliver}.md，并随包提供注入 --agent <名> 的 taskctl 包装脚本。

随后用 taskctl 驱动看板，并在每次写入时带上 actor kind 与会话 —— --actor-kind claude --session-id <id> —— 让卡的轨迹指回动手的那段对话。Claude Code 本身没有定时器，所以规则 1 的认领由外部驱动：调度器唤醒一个 claude -p 无头会话（用 --resume <sid> 续接同一会话），你也可以从 SessionStart hook 或 slash 命令手动触发。

Codex

install.sh --target codex --agent-name <名> 会部署完整 bundle。它向 ~/.codex/AGENTS.md 追加 claim-first 片段，写入调度单元（--no-automation 跳过），并随包提供 taskctl 包装脚本。

以同样方式操作看板，并用当前线程作为会话 id —— --actor-kind codex --session-id "$CODEX_THREAD_ID" —— 做会话级归属。Codex 本身没有定时器，所以规则 1 由调度器唤醒 codex exec 回合（或使用 Codex 应用自动化）来驱动，随包的认领触发脚本作为最小后备。

面向 agent 的指南 —— claim-first、状态模型、交付门与看板 workflow —— 在 skill 内：skills/meerkat/SKILL.md。各 agent kind 的安装与触发细节见 docs/ops/install.md。

开发

需要 Node >= 22（node:sqlite 时代）。引擎为运行时零依赖、无需网络 —— src/ 下全部只用 Node 内置模块。唯一例外是 web/（Vue 3 + Vite + Tailwind + daisyUI），其构建期 devDependencies 由镜像从随仓库提交的 web/.vendor/npm-cache 离线安装，产物不会进入运行时。

node --test                          # 运行冒烟 / 契约测试
node scripts/verify/manifests.mjs    # 校验插件清单
node scripts/verify/skill.mjs        # 校验看板 skill 的 SKILL.md frontmatter
node scripts/build.mjs               # 产出 dist/

或一次跑完：

npm run check

想贡献？ 先读 CONTRIBUTING.md —— 它讲清了容器门禁（npm run verify:docker）、PR 流程，以及 CI 强制执行的约定。贡献以 MIT 许可落库。

路线图

按优先级排序；IM 集成是下一项。

能力域	内容	状态
引擎	src/core/ —— 领域模型、SQLite 存储与迁移、状态机、下沉到数据库触发器的各项不变量、openBoard()	已落地
CLI 与本地服务	src/cli/ —— taskctl 命令面，以及 CLI 自动启动的回环 taskd	已落地
安装器	install.sh + scripts/install/<actor-kind>.sh —— claude / openclaw / codex / pi 四个 agent kind 目标，外加 server 运行时；幂等且合并式写入	已落地
md 导出	src/core/storage/md/ —— taskctl export md 为每张卡写一份规范 markdown	已落地
看板 API 与前端	src/server/ —— 完整的看板 HTTP API 及其 SSE 流；web/ —— 构建到 web/dist 的 Vue 3 看板	已落地
supervisor + director	skills/meerkat-director/ 与五个角色 skill —— 外部 supervisor：60 秒 ping、600 秒确定性 tick（SLA 巡检 → workflow → poll）、多 kind 会话池与 director 决策通道；只通过 taskctl 驱动看板	已落地
对话台	skills/meerkat-chat/ —— 人的实时视图：进展、awaiting 问题、待验收、看板健康与异常卡分诊；以 --as-human 原样记录人的话	已落地
IM 集成	把“需要人”的项（awaiting / agent question / 待验收）推到 IM，在 IM 里记录决策与验收，并回答进展查询。引擎只提供插件宿主 + channel-kit；每个平台（飞书、Slack、微信、WhatsApp、Teams、Telegram）是独立适配器包，基于第三方 SDK。见 docs/im-integration.md。	（规划中 —— 优先于下列项）
Epic 视图	epic 层级 / 进展 / rollup 的可视化视图 —— 查看 epic 及其子卡状态的聚合	（规划中）
迭代管理	迭代（sprint）周期管理：任务归入迭代、迭代内进度与容量	（规划中）
OpenClaw 的 supervisor 支持	为 openclaw 目标安装并运行 supervisor（调度单元 + 会话池）。当前 --target openclaw 只装看板 skill；与 OpenClaw 自带 poll/patrol 如何共存仍待设计	（规划中）
OpenClaw 的 setup-meerkat 支持	为 openclaw 目标安装并运行 setup-meerkat。安装器会把它复制到主 loop kind；OpenClaw 仍只能从共享 bundle 读到	（规划中）

本表已弃用 M0–M6 编号：M3（stdio MCP 服务器）是先落地、后被整体移除的 —— 见 迁移记录。

许可证

MIT —— 见 LICENSE。