跳到主要内容

Kanban — 多 Agent 协作档案

想要一份上手指南? 请阅读 Kanban 教程 — 其中包含四个用户故事(个人开发者、集群批量处理、带重试的角色流水线、熔断器),并附有各自的仪表板截图。本页是参考文档;教程则是叙述性讲解。

Kopi Agent Kanban 是一个持久化的任务看板,在你所有的 Kopi Agent 档案之间共享,让多个具名 agent 协同工作,而无需依赖脆弱的进程内 subagent 蜂群。每个任务都是 ~/.kopi/kanban.db 中的一行;每次交接都是任何人都可读写的一行;每个 worker 都是一个完整的 OS 进程,拥有自己的身份。

两种交互界面:模型通过工具操作,你通过 CLI 操作​

看板有两扇前门,背后都是同一个 ~/.kopi/kanban.db:

  • Agent 通过专用的 kanban_* 工具集驱动看板 — kanban_show、kanban_list、kanban_complete、kanban_block、kanban_heartbeat、kanban_comment、kanban_create、kanban_link、kanban_unblock。dispatcher 在生成每个 worker 时,其 schema 中就已包含这些工具;orchestrator 档案也可以显式启用 kanban 工具集。模型通过直接调用工具来读取和分派任务,而不是 通过 shell 调用 kopi kanban。详见下文的 worker 如何与看板交互。
  • 你(以及脚本和 cron)通过 CLI 上的 kopi kanban …、/kanban … 这一 slash 命令,或仪表板来驱动看板。 这些面向人类和自动化 — 也就是背后没有工具调用模型的场景。

两种交互界面都经过同一个 kanban_db 层,因此读取看到的是一致的视图,写入也不会产生偏差。本页其余部分展示 CLI 示例,因为它们易于复制粘贴,但每个 CLI 动词都有模型使用的工具调用等价形式。

以下正是 delegate_task 无法覆盖的工作负载形态:

  • 研究分流 — 并行研究员 + 分析师 + 撰稿人,人在环中。
  • 定时运维 — 每日循环简报,持续数周累积成日志。
  • 数字分身 — 持久化的具名助手(inbox-triage、ops-review),随时间不断积累记忆。
  • 工程流水线 — 拆解 → 在并行 worktree 中实现 → 评审 → 迭代 → 提交 PR。
  • 集群作业 — 由一名专家管理 N 个对象(50 个社交账号、12 个受监控服务)。

完整的 rationale(设计依据)、与 Cline Kanban / Paperclip / NanoClaw / Google Gemini Enterprise 的对比分析,以及八种经典协作模式,请参见仓库中的 docs/kopi-kanban-v1-spec.pdf。

Kanban 与 delegate_task 的对比​

两者看起来相似,但并不是同一个原语。

delegate_taskKanban
形态RPC 调用(fork → join)持久化消息队列 + 状态机
父级阻塞直到子级返回create 之后即发即忘
子级身份匿名 subagent具名档案,带持久化记忆
可恢复性无 — 失败即失败阻塞 → 解除阻塞 → 重新运行;崩溃 → 回收
人在环中不支持可随时评论 / 解除阻塞
每个任务的 agent 数一次调用 = 一个 subagent在任务生命周期内 N 个 agent(重试、评审、后续跟进)
审计轨迹上下文压缩时丢失SQLite 中的持久行,永久保存
协作方式分层(调用方 → 被调用方)对等 — 任何档案都可读写任何任务

一句话区分: delegate_task 是一次函数调用;Kanban 是一个工作队列,其中每次交接都是一行,任何档案(或人类)都能看到并编辑。

在以下情况使用 delegate_task: 父 agent 在继续之前需要一个简短的推理答案,不涉及人类,结果会进入父级的上下文。

在以下情况使用 Kanban: 工作跨越 agent 边界、需要在重启后存活、可能需要人类输入、可能由不同角色接手,或需要在事后可被发现。

两者可以共存:kanban worker 在运行过程中可能在内部调用 delegate_task。

核心概念​

  • Board(看板) — 一个独立的任务队列,拥有自己的 SQLite 数据库、workspaces 目录和 dispatcher 循环。一次安装可以拥有多个 board (例如每个项目、仓库或领域一个);参见下文的 Boards(多项目)。 单项目用户始终留在 default board 上,除了本文档这一节外, 永远不会看到 "board" 这个词。
  • Task(任务) — 一行记录,包含标题、可选正文、一个 assignee(即某个 profile 名称)、状态 (triage | todo | ready | running | blocked | done | archived)、可选的 tenant 命名空间、可选的 idempotency key(用于重试自动化时的去重)。
  • Link(链接) — task_links 行,记录 parent → child 依赖关系。当所有 parent 都为 done 时,dispatcher 会将 todo → ready 提升。
  • Comment(评论) — agent 之间的协议。Agent 和人类都会追加评论;当 worker 被(重新)生成时,它会读取完整的评论线程作为上下文的一部分。
  • Workspace(工作区) — worker 运行所在的目录。共有三种类型:
    • scratch(默认)— 在 ~/.kopi/kanban/workspaces/<id>/(非默认 board 上则是 ~/.kopi/kanban/boards/<slug>/workspaces/<id>/)下的全新临时目录。任务完成时即被删除 — scratch 按设计就是临时性的,因此当 worker(或 kopi kanban complete <id>)将任务标记为完成的那一刻,目录就会被清除。如果你想保留 worker 的输出,请改用 worktree: 或 dir:<path>。首次在某次安装中创建 scratch workspace 时,dispatcher 会记录一条警告,并在该任务上发出一个 tip_scratch_workspace 事件(可通过 kopi kanban show <id> 查看)。
    • dir:<path> — 一个已存在的共享目录(Obsidian vault、邮件操作目录、每个账号各自的文件夹)。必须是绝对路径。 像 dir:../tenants/foo/ 这样的相对路径会在 dispatch 时被拒绝,因为它们会相对于 dispatcher 恰好所在的 CWD 解析,这既含糊不清,也是 confused-deputy 逃逸向量。除此之外,该路径是受信任的 —— 这是你的机器、你的文件系统,worker 以你的 uid 运行。这就是 trusted-local-user 威胁模型;kanban 按设计是单主机的。完成时保留。
    • worktree — 用于编码任务的、位于 .worktrees/<id>/ 下的 git worktree。使用 worktree:<path> 来指定确切的目标路径。Worker 端的 git worktree add 会创建它,并在提供时使用 --branch。完成时保留。
  • Dispatcher(调度器) — 一个长期运行的循环,每隔 N 秒(默认 60)执行:回收过期的 claim、回收崩溃的 worker(PID 已消失但 TTL 尚未过期)、提升就绪的任务、执行原子化 claim、生成已分配的 profile。默认在 gateway 内部运行 (kanban.dispatch_in_gateway: true)。一个 dispatcher 每个 tick 扫描所有 board;生成 worker 时会固定 KOPI_KANBAN_BOARD,使它们看不到其他 board。在同一个任务上连续 kanban.failure_limit 次生成失败后(默认:2 次),dispatcher 会以最后一次错误为原因自动将其置为 blocked —— 防止在 profile 不存在、workspace 无法挂载等任务上反复空转。
  • Tenant(租户) — board 内部的可选字符串命名空间。一支专家 fleet 可以服务多个业务 (--tenant business-a),并通过 workspace 路径和 memory key 前缀实现数据隔离。Tenant 是软过滤器;board 才是硬隔离边界。

Boards(多项目)​

Board 让你把互不相关的工作流 —— 每个项目、仓库或领域一个 —— 拆分到隔离的队列中。新安装只有一个名为 default 的 board(为保持向后兼容,数据库位于 ~/.kopi/kanban.db)。只想要单一工作流的用户完全无需了解 board;该功能是可选启用的。

每个 board 的隔离是绝对的:

  • 每个 board 有独立的 SQLite 数据库 (~/.kopi/kanban/boards/<slug>/kanban.db)。
  • 独立的 workspaces/ 和 logs/ 目录。
  • 为某个任务生成的 worker 只能看到其所属 board 的任务 —— dispatcher 会在子进程 env 中设置 KOPI_KANBAN_BOARD,而 worker 可访问的每个 kanban_* 工具都会读取它。
  • 不允许跨 board 链接任务(保持 schema 简单;如果你确实需要 跨项目引用,请使用自由文本提及并手动按 id 查找)。

通过 CLI 管理 board​

# See what's on disk. Fresh installs show only "default".
kopi kanban boards list

# Create a new board.
kopi kanban boards create atm10-server \
--name "ATM10 Server" \
--description "Minecraft modded server ops" \
--icon 🎮 \
--switch # optional: make it the active board

# Operate on a specific board without switching.
kopi kanban --board atm10-server list
kopi kanban --board atm10-server create "Restart ATM server" --assignee ops

# Change which board is "current" for subsequent calls.
kopi kanban boards switch atm10-server
kopi kanban boards show # who's active right now?

# Rename the display name (the slug is immutable — it's the directory name).
kopi kanban boards rename atm10-server "ATM10 (Prod)"

# Archive (default) — moves the board's dir to boards/_archived/<slug>-<ts>/.
# Recoverable by moving the dir back.
kopi kanban boards rm atm10-server

# Hard delete — `rm -rf` the board dir. No recovery.
kopi kanban boards rm atm10-server --delete

Board 解析顺序(优先级从高到低):

  1. CLI 调用时显式指定的 --board <slug>。
  2. KOPI_KANBAN_BOARD 环境变量(由 dispatcher 在生成 worker 时设置,因此 worker 看不到其他 board)。
  3. ~/.kopi/kanban/current —— 由 kopi kanban boards switch 持久化的 slug。
  4. default。

Slug 会经过校验:仅限小写字母数字 + 连字符 + 下划线,1-64 个 字符,且必须以字母数字开头。大写输入会自动转为小写。 其他任何内容(斜杠、空格、点号、..)都会在 CLI 层被拒绝, 这样路径穿越伎俩就无法给 board 命名。

通过 dashboard 管理 board​

kopi dashboard → Kanban 标签页会在 board 数量超过一个(或任一 board 有任务)时, 立即在顶部显示 board 切换器。单 board 用户只会看到一个小的 + New board 按钮; 在切换器真正派上用场之前它都是隐藏的。

  • Board 下拉菜单 — 选择当前活动的 board。你的选择会保存到 浏览器的 localStorage 中,因此在重新加载后依然有效,同时不会 把 CLI 的 current 指针从你一直开着的终端下挪走。
  • + New board — 打开一个模态框,要求填写 slug、显示名称、 描述和图标。可以选择自动切换到新 board。
  • Archive — 只在非 default 的 board 上显示。确认后, 会把该 board 目录移动到 boards/_archived/。

所有 dashboard API 端点都接受 ?board=<slug> 来限定 board 范围。events WebSocket 在连接时固定到某个 board;在 UI 中切换会针对新 board 打开一条新的 WS 连接。

文件附件​

任务可以携带文件附件 —— PDF、图片、源文档 —— 这样 worker 就能拿到所需的源材料,而无需你把路径粘贴进 正文里再指望它能找到。

  • 上传 —— 在仪表板抽屉中打开任务,使用 Attachments 区域的 Upload file 按钮(一次上传多个文件 也可以)。每次上传上限为 25 MB。
  • 存储 —— 默认看板的文件存放在 <kopi-home>/kanban/attachments/<task_id>/ 下,命名 看板则存放在 <kopi-home>/kanban/boards/<slug>/attachments/<task_id>/。设置 KOPI_KANBAN_ATTACHMENTS_ROOT 可固定到自定义位置。
  • worker 看到的内容 —— 当 dispatcher 把任务交给 worker 时, worker 的上下文中会包含一个 Attachments 区域,列出每个 文件的名称及其绝对路径。worker 拥有完整的文件/终端 工具访问权限,因此可以直接读取附件(read_file,或使用 pdftotext 等 shell 工具)。
  • 下载 / 移除 —— 抽屉中会列出每个附件,附带下载 链接和移除 (×) 控件。移除附件会同时删除 元数据行和磁盘上的文件。
远程终端后端

附件路径在本地终端后端上直接解析,这也是 Kanban worker 的 默认设置。如果你在远程后端(Docker、Modal)上运行 worker, 请把看板的 attachments/ 目录挂载到 sandbox 中,以便 worker 上下文中的绝对路径可以被访问到。

快速开始​

以下命令是你(人类)用来设置看板和创建任务的。任务一旦被分配, dispatcher 就会把所分配的 profile 拉起为 worker,此后由模型通过 kanban_* 工具调用来推动任务,而不是 CLI 命令 —— 参见 worker 如何与看板交互。

# 1. Create the board (you)
kopi kanban init

# 2. Start the gateway (hosts the embedded dispatcher)
kopi gateway start

# 3. Create a task (you — or an orchestrator agent via kanban_create)
kopi kanban create "research AI funding landscape" --assignee researcher

# 4. Watch activity live (you)
kopi kanban watch

# 5. See the board (you)
kopi kanban list
kopi kanban stats

当 dispatcher 接手 t_abcd 并拉起 researcher profile 时, 该 worker 的模型做的第一件事就是调用 kanban_show() 来读取自己的任务。它不会运行 kopi kanban show t_abcd。

Gateway 内嵌的 dispatcher(默认)​

dispatcher 运行在 gateway 进程内部。无需安装任何东西,也没有 独立服务需要管理 —— 只要 gateway 在运行,就绪的任务就会在 下一个 tick(默认 60 秒)被接手。

# config.yaml
kanban:
dispatch_in_gateway: true # default
dispatch_interval_seconds: 60 # default

可通过 KOPI_KANBAN_DISPATCH_IN_GATEWAY=0 在运行时覆盖 config 标志, 便于调试。gateway 的标准监管方式同样适用:直接运行 kopi gateway start,或把 gateway 接入为 systemd 用户单元(参见 gateway 文档)。如果没有正在运行的 gateway,ready 任务会停在原处, 直到 gateway 启动 —— kopi kanban create 会在创建 时就此发出警告。

将 kopi kanban daemon 作为独立进程运行已弃用; 请使用 gateway。如果确实无法运行 gateway(无头主机 策略禁止长驻服务等),--force 逃生舱口会在一个发布周期内 保留旧的独立守护进程,但同时针对同一个 kanban.db 运行 gateway 内嵌的 dispatcher 与独立守护进程会导致认领竞争, 不受支持。

幂等创建(用于自动化 / webhook)​

# First call creates the task. Any subsequent call with the same key
# returns the existing task id instead of duplicating.
kopi kanban create "nightly ops review" \
--assignee ops \
--idempotency-key "nightly-ops-$(date -u +%Y-%m-%d)" \
--json

批量 CLI 动词​

所有生命周期动词都接受多个 id,因此你可以在一条命令中清理一批:

kopi kanban complete t_abc t_def t_hij --result "batch wrap"
kopi kanban archive t_abc t_def t_hij
kopi kanban unblock t_abc t_def
kopi kanban block t_abc "need input" --ids t_def t_hij

worker 如何与看板交互​

worker 不会通过 shell 调用 kopi kanban。 当 dispatcher 生成 worker 时,它会在子进程的 env 中设置 KOPI_KANBAN_TASK=t_abcd,而该 env var 会在模型 schema 中开启一个专用的 kanban 工具集。同一工具集也对在其 toolsets 配置中启用了 kanban 的 orchestrator 配置文件可用。这些工具通过 Python kanban_db 层直接读取和修改看板,与 CLI 的行为一致。运行中的 worker 像调用其他任何工具一样调用它们;它从未见过、也不需要 kopi kanban CLI。

工具用途必需参数
kanban_show读取当前任务(标题、正文、先前的尝试、父任务交接、评论、完整预格式化的 worker_context)。默认使用 env 中的 task id。—
kanban_list列出任务摘要,支持按 assignee、status、tenant、归档可见性以及 limit 进行过滤。供 orchestrator 发现看板上的工作时使用。—
kanban_complete以 summary + metadata 结构化交接来完成任务。summary / result 至少填一个
kanban_block停止工作并按原因路由:kind=dependency(在 todo 中等待,自动恢复),needs_input/capability/transient(上报给人类处理)。同类重复阻塞会自动升级为 triage。reason
kanban_heartbeat在长时间操作期间发送存活信号。纯副作用。—
kanban_comment向任务线程追加一条持久化备注。task_id、body
kanban_create(Orchestrator)以一个 assignee、可选的 parents、skills 等分发为子任务。title、assignee
kanban_link(Orchestrator)事后添加一条 parent_id → child_id 依赖边。parent_id、child_id
kanban_unblock(Orchestrator)将被阻塞的任务移回 ready。task_id

一个典型的 worker 回合如下:

# Model's tool calls, in order:
kanban_show() # no args — uses KOPI_KANBAN_TASK
# (model reads the returned worker_context, does the work via terminal/file tools)
kanban_heartbeat(note="halfway through — 4 of 8 files transformed")
# (more work)
kanban_complete(
summary="migrated limiter.py to token-bucket; added 14 tests, all pass",
metadata={"changed_files": ["limiter.py", "tests/test_limiter.py"], "tests_run": 14},
)

orchestrator worker 则进行分发:

kanban_show()
kanban_create(
title="research ICP funding 2024-2026",
assignee="researcher-a",
body="focus on seed + series A, North America, AI-adjacent",
)
# → returns {"task_id": "t_r1", ...}
kanban_create(title="research ICP funding — EU angle", assignee="researcher-b", body="…")
# → returns {"task_id": "t_r2", ...}
kanban_create(
title="synthesize findings into launch brief",
assignee="writer",
parents=["t_r1", "t_r2"], # promotes to ready when both complete
body="one-pager, 300 words, neutral tone",
)
kanban_complete(summary="decomposed into 2 research tasks + 1 writer; linked dependencies")

"(Orchestrators)" 工具——kanban_list、kanban_create、kanban_link、kanban_unblock,以及作用于外部任务的 kanban_comment——通过同一工具集提供;其约定(编码在自动注入的 kanban guidance 中)是:worker 配置文件不分发、也不路由无关工作,而 orchestrator 配置文件不执行实现类工作。Dispatcher 生成的 worker 在破坏性生命周期操作上仍然限定于自身任务范围,无法修改无关任务。

为什么用工具而不是 shell 调用 kopi kanban​

三个原因:

  1. 后端可移植性。 terminal 工具指向远程后端(Docker / Modal / Singularity / SSH)的 worker,需要在容器内部运行 kopi kanban complete,而那里没有安装 kopi,也未挂载 ~/.kopi/kanban.db。kanban 工具在 agent 自己的 Python 进程中运行,无论 terminal 后端为何都能访问 ~/.kopi/kanban.db。
  2. 没有 shell 引号的脆弱性。 通过 shlex + argparse 传递 --metadata '{"files": [...]}' 是一个潜在的坑。结构化的工具参数完全绕开了它。
  3. 更好的错误信息。 工具结果是模型可以推理的结构化 JSON,而不是它必须去解析的 stderr 字符串。

在普通会话中零 schema 占用。 除非活跃的 profile 为 orchestrator 工作显式启用了 kanban 工具集,否则常规的 kopi chat 会话在其 schema 中没有任何 kanban_* 工具。Dispatcher 生成的任务 worker 获得的是限定于任务范围的工具,因为设置了 KOPI_KANBAN_TASK;orchestrator 配置文件则通过 config 获得更广的路由能力。对于从不接触 kanban 的用户来说,不会有任何工具膨胀。

自动注入的 kanban guidance 会教模型何时该调用哪个工具,以及按什么顺序调用。

推荐的交接证据​

kanban_complete(summary=..., metadata={...}) 刻意保持灵活: summary 是给人看的收尾说明,而 metadata 是 机器可读的交接信息,下游 agent、reviewer 或 dashboard 可以直接复用, 无需从散文中抓取内容。

对于工程和 review 任务,建议使用以下可选的 metadata 结构:

{
"changed_files": ["path/to/file.py"],
"verification": ["pytest tests/kopi_cli/test_kanban_db.py -q"],
"dependencies": ["parent task id or external issue, if any"],
"blocked_reason": null,
"retry_notes": "what failed before, if this was a retry",
"residual_risk": ["what was not tested or still needs human review"]
}

这些 key 是约定,而非 schema 要求。其有用的特性在于 每个 worker 都留下足够的证据,让下一个阅读者能快速回答四个问题:

  1. 改了什么?
  2. 如何验证的?
  3. 如果失败了,什么能解除阻塞或重试它?
  4. 还刻意留下了哪些未解决的风险?

请将密钥、原始日志、token、OAuth 材料以及无关的对话记录排除在 metadata 之外。改为存放指针和摘要。如果某个任务没有文件或 测试,请在 summary 中明确说明,并把实际存在的证据(例如来源 URL、 issue id 或手动 review 步骤)放到 metadata 中。

worker 生命周期​

每个处理 kanban 任务的配置文件都会自动获得 worker 生命周期——它在生成时被注入到 worker 的系统提示中(即 KANBAN_GUIDANCE 块),因此无需安装或配置任何东西。它通过 tool call(而非 CLI 命令)教会 worker 完整的生命周期:

  1. 生成后,调用 kanban_show() 读取标题 + 正文 + 父任务交接 + 先前的尝试 + 完整评论线程。
  2. cd $KOPI_KANBAN_WORKSPACE(通过 terminal 工具)并在那里开展工作。
  3. 在长时间操作期间每隔几分钟调用一次 kanban_heartbeat(note="...")。如果你的工作可能超过 1 小时,请至少每小时调用一次 kanban_heartbeat ——dispatcher 会回收那些运行时间超过 kanban.dispatch_stale_timeout_seconds(默认 4 小时)且最近一小时内没有心跳的任务,假定 worker 已经崩溃且未做清理。回收是良性的(任务会回到 ready 以便重新派发,且不会计入失败计数),但你会丢失当前这次运行的进度。
  4. 用 kanban_complete(summary="...", metadata={...}) 完成,或在卡住时使用 kanban_block(reason="...")。

最后一次 kanban_complete / kanban_block 调用是 worker 协议的一部分。如果 worker 进程在任务仍处于 running 状态时以状态 0 退出, dispatcher 会将其视为协议违规,发出一个 protocol_violation 事件,并在下一个 tick 上自动阻塞该任务, 而不是把它重新生成到同一个循环中。这通常意味着模型只写了一段 纯文本回答就退出了,而没有使用 K 看板工具的界面。

生命周期加上关键的参考细节(workspace 种类、交付物 artifacts、认领已创建的卡片)都会随该 system-prompt 块一起下发,因此无论 worker 在哪个 profile 下运行,都拥有这些内容——无需为每个 profile 单独配置 skill。

将额外的 skill 固定到特定任务​

有时单个任务需要被指派的 profile 默认并不具备的专业上下文——例如需要 translation skill 的翻译任务、需要 github-code-review 的审校任务、需要 security-pr-audit 的安全审计任务。与其每次都去修改被指派者的 profile,不如把这些 skill 直接附加到任务上。

由 orchestrator agent 发起(最常见的情况——一个 agent 把工作分派给另一个),使用 kanban_create 工具的 skills 数组:

kanban_create(
title="translate README to Japanese",
assignee="linguist",
skills=["translation"],
)

kanban_create(
title="audit auth flow",
assignee="reviewer",
skills=["security-pr-audit", "github-code-review"],
)

由人工发起(CLI / 斜杠命令),为每个 skill 重复一次 --skill:

kopi kanban create "translate README to Japanese" \
--assignee linguist \
--skill translation

kopi kanban create "audit auth flow" \
--assignee reviewer \
--skill security-pr-audit \
--skill github-code-review

在 dashboard 中,在内联创建表单的 skills 字段里以逗号分隔输入这些 skill。

dispatcher 会为列出的每个 skill 各发出一个 --skills <name> 标志,因此 worker 启动时会在自动注入的看板指导之上加载所有这些 skill。skill 名称必须与被指派者 profile 上实际已安装的 skill 匹配(运行 kopi skills list 可查看可用项);不存在运行时安装。

目标模式卡片(--goal)​

默认情况下,每个 worker 只有一次机会处理它的卡片——完成工作、调用 kanban_complete/kanban_block、退出。传入 --goal(CLI)或 goal_mode=True(kanban_create 工具 / dashboard),即可改为让该 worker 运行在目标循环中,也就是 /goal 斜杠命令背后的同款 Ralph 风格引擎:每一轮结束后,会有一个辅助 judge 对照卡片的标题 + 正文(视为验收标准)检查 worker 的输出,如果工作尚未完成——且轮次预算仍有剩余——worker 就会在同一会话中继续推进,直到 judge 认可、worker 自行终止任务,或预算耗尽(此时会阻塞该卡片以供人工审查,而不是悄悄退出)。

kopi kanban create "Translate the docs site to French" \
--body "Acceptance: every page translated, no English left, links intact." \
--assignee linguist \
--goal \
--goal-max-turns 15 # optional; default 20

把它用于开放式、多步骤或“一直推进直到 X 成立”的卡片。廉价的一次性工作则不必使用——每轮 judge 的开销并不划算,而且 dispatcher 现有的重试/熔断机制已经能处理临时性的 worker 故障。judge 的水平取决于你写的 goal 文本,所以请把正文写成明确的验收标准。

orchestrator 的行为方式​

**一个行为良好的 orchestrator 不会亲自干活。**它把用户的目标拆解成任务、建立任务间的关联、把每个任务分配给你已设置的某个 profile,然后退居幕后。orchestrator 指导内容——包括抵御诱惑的规则、一个 Step-0 的 profile 发现提示(dispatcher 遇到未知的 assignee 名称时会静默失败,因此 orchestrator 必须把每个卡片都建立在你机器上真实存在的 profile 之上),以及一套围绕 kanban_create / kanban_link / kanban_comment 组织的拆解手册——会自动注入到 worker 的 system prompt 中;无需安装任何东西。

一个典型的 orchestrator 回合(两个并行的研究者把结果交给一位撰写者):

# Goal from user: "draft a launch post on the ICP funding landscape"
kanban_create(title="research ICP funding, NA angle", assignee="researcher-a", body="…") # → t_r1
kanban_create(title="research ICP funding, EU angle", assignee="researcher-b", body="…") # → t_r2
kanban_create(
title="synthesize ICP funding research into launch post draft",
assignee="writer",
parents=["t_r1", "t_r2"], # promoted to 'ready' when both researchers complete
body="one-pager, neutral tone, cite sources inline",
) # → t_w1
# Optional: add cross-cutting deps discovered later without re-creating tasks
kanban_link(parent_id="t_r1", child_id="t_followup")
kanban_complete(
summary="decomposed into 2 parallel research tasks → 1 synthesis task; writer starts when both researchers finish",
)

orchestrator 指导内容会自动随 worker 的 system prompt 一起下发——无需按 profile 安装或同步任何东西。

要获得最佳效果,请搭配一个把工具集限制为看板操作(kanban、gateway、memory)的 profile,这样即使 orchestrator 想做,也根本无法执行实现类任务。

Dashboard(GUI)​

/kanban CLI 与 slash command 足以无界面地运行看板,但可视化看板往往更适合让人参与其中(humans-in-the-loop):分诊、跨 profile 监督、阅读评论串,以及在各列之间拖动卡片。Kopi Agent 将其作为 plugins/kanban/ 处的内置 dashboard 插件提供 —— 既不是核心功能,也不是独立服务 —— 遵循 Extending the Dashboard 中阐述的模式。

使用以下命令打开:

kopi kanban init      # one-time: create kanban.db if not already present
kopi dashboard # "Kanban" tab appears in the nav, after "Skills"

该插件提供哪些能力​

  • 一个 Kanban 标签页,每个状态对应一列:triage、todo、ready、running、blocked、done(打开开关时还有 archived)。
    • triage 是用于放置粗略想法的暂存列。默认情况下(kanban.auto_decompose: true),dispatcher 会对落入此列的任务自动运行分解器(decomposer)。内置 decomposer 使用 auxiliary.kanban_decomposer 模型路径,读取你的 profile roster(含描述),并将任务扇出为一个小型子任务图,路由到最匹配的 specialists。原任务会保持存活,作为每个子任务的父任务,这样当所有子任务完成后,它的 assignee(kanban.orchestrator_profile;未设置时为当前默认 profile)会重新唤醒来判定完成情况。切换页面顶部的 Orchestration: Auto/Manual 胶囊开关(绿色 = Auto,暗灰 = Manual),或直接编辑 config.yaml。两种模式都与 kopi kanban specify 并存 —— 当你不希望扇出时,它仍然可用作单任务的 spec 重写。
  • 卡片显示任务 id、标题、优先级徽章、tenant 标签、已分配的 profile、评论/链接计数、一个进度胶囊(当任务有依赖子任务时显示 N/M 子任务已完成),以及“创建于 N 前”。每张卡片都有一个复选框,用于多选。
  • Running 内按 profile 分道 —— 工具栏复选框可切换 Running 列按 assignee 进行子分组。
  • 通过 WebSocket 实时更新 —— 该插件以较短的轮询间隔跟踪只追加的 task_events 表;任何 profile(CLI、gateway 或另一个 dashboard 标签页)一有动作,看板立即反映变化。重新加载经过防抖处理,因此一连串事件只会触发一次重新获取。
  • 拖放卡片在列之间移动以更改状态。放下时会发送 PATCH /api/plugins/kanban/tasks/:id,它经由 CLI 所使用的同一段 kanban_db 代码路由 —— 三个界面永远不可能出现偏差。移入破坏性状态(done、archived、blocked)时会提示确认。触屏设备使用基于 pointer 的回退方案,因此在平板上也能使用看板。
  • 行内创建 —— 点击任意列标题上的 +,即可输入标题、assignee、优先级,并(可选地)从覆盖所有现有任务的下拉框中选择一个父任务。按 Enter 创建任务,Shift+Enter 在标题字段中插入换行,或按 Escape 取消。从 Triage 列创建时,新任务会自动停放到 triage。
  • 多选与批量操作 —— shift/ctrl 点击卡片,或勾选其复选框,将其加入选择集。顶部会出现批量操作栏,提供批量状态流转、归档和重新分配(通过 profile 下拉框,或“(unassign)”)。破坏性批量操作会先确认。按 id 的部分失败会被报告,而不会中断其余操作。
  • 点击卡片(不按 shift/ctrl)会打开一个侧边抽屉(按 Escape 或点击外部区域关闭),其中包含:
    • 可编辑标题 —— 点击标题即可重命名。
    • 可编辑 assignee / 优先级 —— 点击元信息行即可改写。
    • 可编辑描述 —— 默认进行 markdown 渲染(标题、粗体、斜体、行内代码、围栏代码、http(s) / mailto: 链接、无序列表),并有一个“edit”按钮切换为 textarea。Markdown 渲染由一个极小的、XSS 安全的渲染器完成 —— 所有替换都在 HTML 转义后的输入上执行,只有 http(s) / mailto: 链接会直接通过,且始终设置 target="_blank" + rel="noopener noreferrer"。
    • 依赖编辑器 —— 以 chip 列表展示父任务与子任务,每一项都有一个 × 用于解除关联,另有覆盖其他所有任务的下拉框用于添加新的父任务或子任务。循环依赖的尝试会在服务端被拒绝,并给出清晰提示。
    • 状态操作行(→ triage / → ready / → running / block / unblock / complete / archive),对破坏性流转会显示确认提示。对于 Triage 列中的卡片,该行还提供两个 LLM 驱动的操作:⚗ Decompose 将任务扇出为一个子任务图,并按描述路由到 specialist profiles;✨ Specify 则执行单任务的 spec 重写。当 LLM 判定该任务不适合扇出时,Decompose 会回退到 specify 风格的提升,因此它是严格的超集。两者都可从 CLI(kopi kanban decompose <id> / specify <id> / --all)、任何 gateway 平台(/kanban decompose <id>)访问,也可通过 POST /api/plugins/kanban/tasks/:id/decompose 和 …/specify 以编程方式调用。在 config.yaml 的 auxiliary.kanban_decomposer 和 auxiliary.triage_specifier 下配置模型。
    • 结果区(同样进行 markdown 渲染)、按 Enter 提交的评论串、最近 20 条事件。
  • 工具栏筛选器 —— 自由文本搜索、tenant 下拉框(默认取自 config.yaml 的 dashboard.kanban.default_tenant)、assignee 下拉框、“show archived”开关、“lanes by profile”开关,以及一个 Nudge dispatcher 按钮,这样你就不用等待下一个 60 秒的 tick。

视觉上,目标是熟悉的 Linear / Fusion 布局:深色主题、带计数的列标题、彩色状态圆点、优先级和 tenant 的胶囊 chip。该插件只读取主题 CSS 变量(--color-*、--radius、--font-mono、……),因此会随当前激活的 dashboard 主题自动换肤。

自动与手动编排​

看板有两种方式处理你放入 Triage 列的任务:

Auto(默认) —— kanban.auto_decompose: true。内嵌于 gateway 的 dispatcher 在每个 tick 运行 decomposer,并由 kanban.auto_decompose_per_tick 限制上限(默认每个 tick 3 个任务),这样批量导入的 triage 任务不会让辅助 LLM 突然大量消耗。decomposer 使用内置的 decomposition prompt 加上 auxiliary.kanban_decomposer 模型路径,读取你已安装的 profiles 及其描述,a 并要求 LLM 生成一个 JSON 任务图:需要派生哪些任务、分配给谁、以及哪些任务依赖哪些任务。最初的 triage 任务会成为图中所有叶子节点的父任务,因此它会一直存活,直到整个任务图完成——随后再升级回 ready,让其负责人(kanban.orchestrator_profile,未设置时则为当前默认 profile)判断是否已完成;如果工作尚未结束,还可以继续追加任务。这就是"丢下一句话就走开"的工作流。

手动 — kanban.auto_decompose: false。triage 任务会一直停留在 triage 中,直到你主动操作。点击卡片上的 ⚗ Decompose 按钮、运行 kopi kanban decompose <id>(或 --all),或在聊天中使用 /kanban decompose <id>。这与引入 decomposer 之前的看板行为一致,适合你想完全掌控何时运行什么的场景。

可通过看板页面顶部的 Orchestration: Auto/Manual 药丸按钮在两种模式间切换(翡翠绿 = Auto,灰色 = Manual),也可以直接编辑 config.yaml。两种模式都与 kopi kanban specify 并存——当你不想要扇出(fan-out)时,它仍可作为单任务的 spec 重写来使用。

decomposer 的路由决策依赖于 profile 描述,这是一种按 profile 设置的标注原语,可通过 kopi profile create --description "..."、kopi profile describe <name> --text "..."、kopi profile describe <name> --auto(由 LLM 根据该 profile 已安装的 skills + 模型生成)来设置,也可以在仪表板展开的 Orchestration settings 面板中使用按 profile 的编辑器。没有描述的 profile 仍会出现在名单中——它们依然可按名称路由,只是精确度较低。decomposer 绝不会把子任务落到 assignee=None 上:当 LLM 选中一个未知 profile 时,该子任务会被路由到 kanban.default_assignee(若未设置,则路由到当前默认 profile)。

kanban.orchestrator_profile 不会把该 profile 的 prompt、skills 或自定义逻辑加载到分解调用中。它控制的是扇出之后根任务/编排任务归谁所有。要更改 decomposer 使用的模型/provider,请配置 auxiliary.kanban_decomposer。若想使用某个 profile 的自定义任务拆分逻辑而非内置 decomposer,请切换到 Manual 模式,并让该 profile 显式地创建或分解任务。

配置项(均位于 ~/.kopi/config.yaml 的 kanban: 下):

键默认值用途
auto_decomposetrueDispatcher 每个 tick 自动运行一次 decomposer。
auto_decompose_per_tick3每个 dispatcher tick 内可执行的分解次数上限。超出部分顺延到下一个 tick。
orchestrator_profile""分解后分配给根任务/编排任务的 profile。留空 = 回退到当前默认 profile。
default_assignee""当 LLM 选中未知 profile 时,子任务落脚的位置。留空 = 回退到当前默认 profile。
auto_subscribe_on_createtrue当 worker 在具有持久投递通道(消息网关或 TUI)的会话内调用 kanban_create 时,来源会话会被自动订阅新任务的完成/阻塞事件。投递仍由 dispatcher 驱动——此项仅决定调用方的 chat/key 是否出现在 notify-sub 表中。设为 false 则要求每个任务都显式调用 kanban_notify-subscribe。

以及两个辅助 LLM 槽位:

键用途
auxiliary.kanban_decomposer生成任务图的模型(由 Decompose 调用)。设置 provider/model 可覆盖主聊天模型。
auxiliary.profile_describer自动生成 profile 描述的模型(由 kopi profile describe --auto 调用)。

架构​

GUI 严格来说是一个 read-through-the-DB + write-through-kanban_db 层,本身不含任何领域逻辑:

┌────────────────────────┐      WebSocket (tails task_events)
│ React SPA (plugin) │ ◀──────────────────────────────────┐
│ HTML5 drag-and-drop │ │
└──────────┬─────────────┘ │
│ REST over fetchJSON │
▼ │
┌────────────────────────┐ writes call kanban_db.* │
│ FastAPI router │ directly — same code path │
│ plugins/kanban/ │ the CLI /kanban verbs use │
│ dashboard/plugin_api.py │
└──────────┬─────────────┘ │
│ │
▼ │
┌────────────────────────┐ │
│ ~/.kopi/kanban.db │ ───── append task_events ──────────┘
│ (WAL, shared) │
└────────────────────────┘

REST 接口​

所有路由都挂在 /api/plugins/kanban/ 下,并由仪表板的临时会话 token 保护:

方法路径用途
GET/board?tenant=<name>&include_archived=…按状态列分组的完整看板,外加用于筛选下拉框的 tenants 与 assignees
GET/tasks/:id任务 + 评论 + 事件 + 关联链接
POST/tasks创建(封装 kanban_db.create_task,接受 triage: bool 与 parents: [id, …])
PATCH/tasks/:id状态 / 负责人 / 优先级 / 标题 / 正文 / 结果
POST/tasks/bulk对 ids 中的每个 id 应用同一补丁(状态 / 归档 / 负责人 / 优先级)。单个 id 失败会单独上报,不会中止其余操作
POST/tasks/:id/comments追加一条评论
POST/tasks/:id/specify运行 triage specifier——辅助 LLM 会补全任务正文,并将其从 triage 升级到 todo。返回 {ok, task_id, reason, new_title};在"不在 triage 中"/无 aux client / LLM 出错时,ok=false 会给出可读原因,且返回 200 而非 4xx
POST/tasks/:id/decompose运行看板 decomposer——辅助 LLM 生成任务图,helper 会原子地创建子任务 + 链接根任务 + 翻转 triage → todo。返回 {ok, task_id, reason, fanout, child_ids, new_title}。LLM 出错时同样遵循返回 200 的约定,与 /specify 一致。
GET/profiles列出已安装的 profile 及其描述(供仪表板的 profile 描述编辑器和 orchestrator 选择器使用)。
PATCH/profiles/:name设置或清除某个 profile 的描述(用户撰写——description_auto: false)。返回 {ok, profile, description}。
POST/profiles/:name/describe-auto通过 auxiliary.profile_describer 为某个 profile 生成描述。以 description_auto: true 持久化,以便仪表板显示"待审核"徽标。
GET/orchestration读取看板编排设置(orchestrator_profile、default_assignee、auto_decompose),以及回退处理之后已解析的生效值。
PUT/orchestration更新 config.yaml 中三个编排键的一个或多个。会校验非空的 profile 名称确实存在。
POST/links添加依赖(parent_id → child_id)
DELETE/links?parent_id=…&child_id=…移除依赖
POST/dispatch?max=…&dry_run=…推动 dispatcher——跳过 60 秒等待
GET/config从 config.yaml 读取 dashboard.kanban 偏好设置——default_tenant、lane_by_profile、include_archived_by_default、render_markdown
__C
ODE_352__/events?since=<event_id>task_events 行的实时流

每个 handler 都只是一个薄封装 —— 整个插件约 700 行 Python(router + WebSocket tail + bulk batcher + config reader),不引入任何新的业务逻辑。一个很小的 _conn() 辅助函数会在每次读写时自动初始化 kanban.db,因此无论用户是先打开 dashboard、直接调用 REST API,还是运行 kopi kanban init,全新安装都能正常工作。

Dashboard 配置​

在 ~/.kopi/config.yaml 的 dashboard.kanban 下设置以下任意键,都会改变该标签页的默认值 —— 插件会在加载时通过 GET /config 读取它们:

dashboard:
kanban:
default_tenant: acme # preselects the tenant filter
lane_by_profile: true # default for the "lanes by profile" toggle
include_archived_by_default: false
render_markdown: true # set false for plain <pre> rendering

每个键都是可选的,未设置时使用上面所示的默认值。

安全模型​

dashboard 的 HTTP auth 中间件显式跳过 /api/plugins/ —— plugin 路由按设计不带认证,因为 dashboard 默认只绑定 localhost。这意味着 kanban 的 REST 接口可以从主机上的任意进程访问。

WebSocket 多走了一步:它要求把 dashboard 的临时 session token 作为 ?token=… 查询参数传入(浏览器无法在 upgrade 请求上设置 Authorization),这与浏览器内 PTY bridge 使用的模式一致。

如果你运行 kopi dashboard --host 0.0.0.0,所有 plugin 路由(包括 kanban)都会暴露到网络上。不要在共享主机上这样做。 看板包含任务正文、评论和 workspace 路径;攻击者一旦能访问这些路由,就能读取你的整个协作面,还可以创建 / 重新分配 / 归档任务。

_conn() 中的任务刻意与 profile 无关(这正是协作原语)。即使用 kopi -p <profile> dashboard 打开 dashboard,看板仍会显示主机上任何其他 profile 创建的任务。所有 profile 都由同一用户拥有,但如果多个角色共存,这一点值得了解。

实时更新​

task_events 是一个 append-only 的 SQLite 表,带有一个单调递增的 id。WebSocket 端点会记录每个客户端最后见到的事件 id,并在新行落库时推送它们。当事件成批到达时,前端会重新加载(开销极低的)board 端点 —— 这比尝试根据每种事件类型修补本地状态更简单也更正确。WAL 模式意味着读取循环永远不会阻塞 dispatcher 的 BEGIN IMMEDIATE 认领事务。

扩展​

该插件使用标准的 Kopi Agent dashboard plugin 契约 —— 完整的 manifest 参考、shell slot、页面级 slot 以及 Plugin SDK,请参阅扩展 Dashboard。额外的列、自定义卡片外观、按租户过滤的布局,或完整的 tab.override 替换,都可以在不 fork 该插件的情况下实现。

要禁用而不删除:在 config.yaml 中添加 dashboard.plugins.kanban.enabled: false(或删除 plugins/kanban/dashboard/manifest.json)。

范围边界​

这个 GUI 刻意做得很薄。插件所做的一切都可以通过 CLI 完成;插件只是让人类用起来更顺手。自动分配、预算、治理门禁和组织结构视图仍属于用户空间 —— 一个 router profile、另一个插件,或复用 tools/approval.py —— 正如设计规范中 out-of-scope 一节所列。

CLI 命令参考​

这是你(或脚本、cron、仪表板)用来驱动看板的接口。运行在 dispatcher 内部的 worker 使用 kanban_* 工具接口执行相同的操作——此处的 CLI 和那里的工具都经由 kanban_db 路由,因此这两个接口在设计上天然一致。

kopi kanban init                                     # create kanban.db + print daemon hint
kopi kanban create "<title>" [--body ...] [--assignee <profile>]
[--parent <id>]... [--tenant <name>]
[--workspace scratch|worktree|worktree:<path>|dir:<path>]
[--branch <name>]
[--priority N] [--triage] [--idempotency-key KEY]
[--max-runtime 30m|2h|1d|<seconds>]
[--max-retries N]
[--goal] [--goal-max-turns N]
[--skill <name>]...
[--json]
kopi kanban list [--mine] [--assignee P] [--status S] [--tenant T] [--archived]
[--workflow-template-id <id>] [--current-step-key <key>]
[--sort created|created-desc|priority|priority-desc|status|assignee|title|updated]
[--json]
kopi kanban show <id> [--json]
kopi kanban assign <id> <profile> # or 'none' to unassign
kopi kanban reassign <id>... <profile> # bulk re-assign tasks to a profile
kopi kanban edit <id> [--title ...] [--body ...] # edit task title / body / priority in place
[--priority N]
kopi kanban promote <id>... # move todo/blocked tasks to ready (recovery)
kopi kanban schedule <id> --at <ISO8601> # set/clear a task's scheduled_at start time
kopi kanban diagnostics [--json] # board health snapshot (alias: diag)
kopi kanban link <parent_id> <child_id>
kopi kanban unlink <parent_id> <child_id>
kopi kanban claim <id> [--ttl SECONDS]
kopi kanban comment <id> "<text>" [--author NAME]

# Bulk verbs — accept multiple ids:
kopi kanban complete <id>... [--result "..."]
kopi kanban block <id> "<reason>" [--ids <id>...]
kopi kanban unblock <id>...
kopi kanban archive <id>...

kopi kanban tail <id> # follow a single task's event stream
kopi kanban watch [--assignee P] [--tenant T] # live stream ALL events to the terminal
[--kinds completed,blocked,…] [--interval SECS]
kopi kanban heartbeat <id> [--note "..."] # worker liveness signal for long ops
kopi kanban runs <id> [--json] # attempt history (one row per run)
kopi kanban assignees [--json] # profiles on disk + per-assignee task counts
kopi kanban dispatch [--dry-run] [--max N] # one-shot pass
[--failure-limit N] [--json]
kopi kanban daemon --force # DEPRECATED — standalone dispatcher (use `kopi gateway start` instead)
[--failure-limit N] [--pidfile PATH] [-v]
kopi kanban stats [--json] # per-status + per-assignee counts
kopi kanban log <id> [--tail BYTES] # worker log from ~/.kopi/kanban/logs/
kopi kanban notify-subscribe <id> # gateway bridge hook (used by /kanban in the gateway)
--platform <name> --chat-id <id> [--thread-id <id>] [--user-id <id>]
kopi kanban notify-list [<id>] [--json]
kopi kanban notify-unsubscribe <id>
--platform <name> --chat-id <id> [--thread-id <id>]
kopi kanban context <id> # what a worker sees
kopi kanban specify [<id> | --all] [--tenant T] # flesh out a triage-column idea
[--author NAME] [--json] # into a full spec and promote to todo
kopi kanban gc [--event-retention-days N] # workspaces + old events + old logs
[--log-retention-days N]

所有命令在交互式 CLI 中也可作为斜杠命令(slash command)使用,消息网关中亦然(见下文的 /kanban 斜杠命令)。

--max-retries 是针对 dispatcher 的按任务熔断器(circuit-breaker)覆盖设置。--max-retries 1 在第一次非成功尝试时阻塞该任务,而 --max-retries 3 允许两次重试,并在第三次失败时阻塞。省略它则使用 config.yaml 中的 kanban.failure_limit,再否则使用内置默认值。

并发、调度与子任务晋升配置​

配置键默认值作用
kanban.max_in_progress未设置(无限制)限制同时运行的任务数量。当看板已有 N 个任务在运行时,dispatcher 会跳过继续派生更多任务——适用于运行缓慢的 worker(本地 LLM、资源受限的主机),让它们先完成手头任务,避免堆积后超时。无效或小于 1 的值会记录警告,并按无限制处理。
kanban.max_in_progress_per_profile未设置(无限制)max_in_progress 的按 profile(配置档)变体——限制任何单个 assignee profile 并发运行的任务数量。当某个 profile 运行缓慢或受速率限制、而其他 profile 应继续正常流动时很有用。与看板级的 max_in_progress 并行生效;两者都允许派生时才会继续。
kanban.auto_promote_childrentrue当 decompose_triage_task() 产出的子任务没有任何父级阻塞依赖时,它们会自动晋升为 ready,以便 dispatcher 拾取。设为 false 则需要人工审查——子任务会停留在 todo,直到你手动晋升它们。
kanban.default_workdir未设置看板级的默认工作目录,当 --workspace 和任务本身都未覆盖时,应用于新任务。按任务的 workspace: 仍然优先。
kanban:
max_in_progress: 2
auto_promote_children: false
default_workdir: ~/work/active-project

定时任务启动(scheduled_at)​

在任务上设置 scheduled_at 可将派发延迟到特定时间。dispatcher 会跳过 scheduled_at 在未来某个时间的就绪任务,并在该时间戳之后的第一次 tick 中拾取它们。

kopi kanban create "nightly backup audit" \
--assignee ops --scheduled-at "2026-06-01T03:00:00Z"

重新派生防护​

当一个就绪任务在上一次运行中遇到配额/认证/429 错误(blocker_auth),或在防护窗口内成功完成过一次运行(recent_success),或近期任务评论中包含指向 GitHub PR 的链接(active_pr)时,dispatcher 会拒绝重新派生该任务。这可防止在人工跟进之前,针对同一个 bug 或任务反复引发 worker 风暴。参见事件参考中的 respawn_guarded 行。

拖拽删除与批量删除(仪表板)​

仪表板在看板页面上提供了一个回收站拖放区——将任意卡片拖入其中即可删除该任务(级联删除 task_events、子任务链接和订阅)。确认提示可防止误操作。批量删除也可通过 DELETE /api/plugins/kanban/tasks 配合 JSON 请求体 {"ids": ["t_abc", "t_def", ...]} 访问。

Worker 可见性端点​

仪表板 plugin API 现在为外部监控暴露了以下只读端点(外加一个运行控制动词):

端点返回内容
GET /api/plugins/kanban/workers/active当前已派生的 worker,包含 PID、profile、任务 id、启动时间、最近心跳
GET /api/plugins/kanban/runs/{id}单次运行详情——任务 id、状态、开始/结束时间、退出码、日志路径
POST /api/plugins/kanban/runs/{run_id}/terminate终止一个可回收的运行——停止 worker 并释放任务以便重新派发
GET /api/plugins/kanban/inspect综合 dispatcher 快照——积压量、进行中数量与 max_in_progress 的对比、近期事件

所有这些端点都与看板 plugin API 的其他部分一样,受相同的仪表板 plugin 鉴权限制。

Kanban Swarm 拓扑辅助工具​

kopi kanban swarm 可一次性创建一个持久的 Kanban Swarm v1 图:一张已完成的根/黑板卡片、N 张并行的 worker 卡片、一张以所有 worker 为门控条件的 verifier 卡片,以及一张以 verifier 为门控条件的 synthesizer 卡片。共享的 swarm 上下文(即"黑板")以结构化 JSON 评论的形式存储在根卡片上,任何 worker 都可以读取。

kopi kanban swarm "Design a multi-region failover plan" \
--workers researcher,architect,sre \
--verifier reviewer --synthesizer writer

生成的图会正常派发——worker 并行运行,verifier 在它们全部完成后被唤醒,synthesizer 在 verifier 标记工作无误后被唤醒。

/kanban slash 命令​

每个 kopi kanban <action> 动词也都可以通过 /kanban <action> 访问 —— 无论是在交互式 kopi chat 会话内部,还是从任何网关平台(Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost、邮件、SMS)。两种入口调用的是完全相同的 kopi_cli.kanban.run_slash() 入口点,该入口点复用 kopi kanban 的 argparse 树,因此参数表面、标志位和输出格式在 CLI、/kanban 和 kopi kanban 之间完全一致。你无需离开聊天界面就能操控看板。

/kanban list
/kanban show t_abcd
/kanban create "write launch post" --assignee writer --parent t_research
/kanban comment t_abcd "looks good, ship it"
/kanban unblock t_abcd
/kanban dispatch --max 3
/kanban specify t_abcd # flesh out a triage one-liner into a real spec
/kanban specify --all --tenant engineering # sweep every triage task in one tenant

多词参数的引号处理方式与 shell 中相同 —— run_slash 会使用 shlex.split 解析行的剩余部分,因此 "..." 和 '...' 两种写法都有效。

运行中使用:/kanban 绕过运行中 agent 的守护机制​

当 agent 仍在思考时,网关通常会对 slash 命令和用户消息进行排队 —— 这是为了防止你在第一个回合仍在进行时意外启动第二个回合。/kanban 被明确豁免于此守护机制。 看板存在于 ~/.kopi/kanban.db 中,而非运行中 agent 的状态中,因此读取(list、show、context、tail、watch、stats、runs)和写入(comment、unblock、block、assign、archive、create、link、……)都会立即执行,即使是在回合中途。

这正是这种分离设计的全部意义所在:

  • 某个 worker 阻塞等待另一个协作方 → 你从手机发送 /kanban unblock t_abcd,调度器会在下一个 tick 拾取该协作方。被阻塞的 worker 不会被中断 —— 它只是不再被阻塞。
  • 你发现某张卡片需要人工上下文 → /kanban comment t_xyz "use the 2026 schema, not 2025" 落到任务线程上,该任务的下一次运行会在 kanban_show() 中读到它。
  • 你想了解你的集群在做什么而不停止编排器 → /kanban list --mine 或 /kanban stats 会检查看板,而不触及你的主对话。

在 /kanban create 时自动订阅(仅限网关)​

当你通过网关使用 /kanban create "…" 创建任务时,发起聊天(平台 + 聊天 id + 线程 id)会自动订阅该任务的终态事件(completed、blocked、gave_up、crashed、timed_out)。每个终态事件你都会收到一条消息 —— 在 completed 时还包括 worker 结果摘要的第一行 —— 无需轮询或记住任务 id。

you> /kanban create "transcribe today's podcast" --assignee transcriber
bot> Created t_9fc1a3 (ready, assignee=transcriber)
(subscribed — you'll be notified when t_9fc1a3 completes or blocks)

… ~8 minutes later …

bot> ✓ t_9fc1a3 completed by transcriber
transcribed 42 minutes, saved to podcast/2026-05-04.md

一旦任务达到 done 或 archived,订阅会自动移除自身。如果你使用 --json(机器输出)编写创建脚本,则会跳过自动订阅 —— 其假设是脚本调用方希望通过 /kanban notify-subscribe 显式管理订阅。

消息中的输出截断​

网关平台有实际的消息长度上限。如果 /kanban list、/kanban show 或 /kanban tail 产生的输出超过约 3800 个字符,响应会被截断,并附带 … (truncated; use \kopi kanban …` in your terminal for full output)` 页脚。CLI 入口没有这样的上限。

自动补全​

在交互式 CLI 中,输入 /kanban 并按 Tab 会循环浏览内置子命令列表(list、ls、show、create、assign、link、unlink、claim、comment、complete、block、unblock、archive、tail、dispatch、context、init、gc)。上面 CLI 参考中列出的其余动词(watch、stats、runs、log、assignees、heartbeat、notify-subscribe、notify-list、notify-unsubscribe、daemon)同样可用 —— 只是尚未出现在自动补全提示列表中。

协作模式​

看板无需任何新的原语即可支持以下八种模式:

模式形态示例
P1 扇出(Fan-out)N 个同级,相同角色"并行研究 5 个角度"
P2 流水线(Pipeline)角色链:scout → editor → writer每日简报组装
P3 投票 / 法定人数N 个同级 + 1 个聚合器3 个研究员 → 1 个评审挑选
P4 长期运行日志相同 profile + 共享目录 + cronObsidian 知识库
P5 人工参与(Human-in-the-loop)worker 阻塞 → 用户评论 → 解除阻塞含糊的决策
P6 @mention从散文中内联路由@reviewer look at this
P7 线程范围工作区线程中的 /kanban here按项目划分的网关线程
P8 集群托管一个 profile,N 个对象50 个社交账号
P9 分诊说明符粗略想法 → triage → kopi kanban specify 展开正文 → todo"把这个单行内容变成一个有规格的任务"

每种模式的具体示例,请参见 docs/kopi-kanban-v1-spec.pdf。

多租户使用​

当一个专家集群为多个业务提供服务时,为每个任务打上租户标签:

kopi kanban create "monthly report" \
--assignee researcher \
--tenant business-a \
--workspace dir:~/tenants/business-a/data/

Worker 会收到 $KOPI_TENANT,并通过前缀对其内存写入进行命名空间隔离。看板、调度器和 profile 定义都是共享的;只有数据是按范围隔离的。

网关通知​

当你从网关(Telegram、Discord、Slack 等)运行 /kanban create … 时,发起聊天会自动订阅该新任务。网关的后台通知器每隔几秒轮询一次 task_events,并将每个终态事件(completed、blocked、gave_up、crashed、timed_out)作为一条消息发送到该聊天。已完成的任务还会发送 worker --result 的第一行,让你无需 /kanban show 就能看到结果。

你可以从 CLI 显式管理订阅 —— 当脚本 / cron 任务想要通知一个并非由其发起的聊天时,这很有用:

kopi kanban notify-subscribe t_abcd \
--platform telegram --chat-id 12345678 --thread-id 7
kopi kanban notify-list
kopi kanban notify-unsubscribe t_abcd \
--platform telegram --chat-id 12345678 --thread-id 7

一旦任务达到 done 或 archived,订阅会自动移除自身;无需清理。

Runs(运行记录)—— 每次尝试一行​

任务是逻辑上的工作单元;run 是对它的一次执行尝试。当调度器认领一个就绪任务时,它会在 task_runs 中创建一行,并将 tasks.current_run_id 指向该行。当这次尝试结束时——无论完成、受阻、崩溃、超时、启动失败还是被回收——该 run 行都会以一个 outcome 关闭,任务的指针随即清空。一个尝试过三次的任务会有三行 task_runs。

为什么要用两张表而不是直接修改任务本身:真实世界的复盘需要完整的尝试历史("第二次审核尝试进行到了 approve,第三次合并了"),而且需要一个干净的地方来挂载每次尝试的元数据——改动了哪些文件、运行了哪些测试、审核者记录了哪些发现。这些是 run 的事实,而不是任务的事实。

结构化交接(structured handoff)也保存在 run 中。当 worker 完成任务(通过 kanban_complete(...))时,它可以传递:

  • summary(tool param)/ --summary(CLI)—— 供人阅读的交接说明;记录在 run 上;下游子任务会在其 build_worker_context 中看到它。
  • metadata(tool param)/ --metadata(CLI)—— run 上的自由格式 JSON 字典;子任务会在 summary 旁边看到它的序列化结果。
  • result(tool param)/ --result(CLI)—— 记录在任务行上的简短日志行(历史遗留字段,为向后兼容而保留)。

下游子任务会读取每个父任务最近一次已完成 run 的 summary + metadata。重试的 worker 会读取自己任务上先前的尝试(outcome、summary、error),以免重复一条已经失败的路径。

# What a worker actually does — a tool call, from inside the agent loop:
kanban_complete(
summary="implemented token bucket, keys on user_id with IP fallback, all tests pass",
metadata={"changed_files": ["limiter.py", "tests/test_limiter.py"], "tests_run": 14},
result="rate limiter shipped",
)

当你(人工)需要收尾一个 worker 无法完成的任务时——例如一个被放弃的任务,或者你在 dashboard 上手动标记为完成的任务——同样可以从 CLI 访问这份交接信息:

kopi kanban complete t_abcd \
--result "rate limiter shipped" \
--summary "implemented token bucket, keys on user_id with IP fallback, all tests pass" \
--metadata '{"changed_files": ["limiter.py", "tests/test_limiter.py"], "tests_run": 14}'

# Review the attempt history on a retried task:
kopi kanban runs t_abcd
# # OUTCOME PROFILE ELAPSED STARTED
# 1 blocked worker 12s 2026-04-27 14:02
# → BLOCKED: need decision on rate-limit key
# 2 completed worker 8m 2026-04-27 15:18
# → implemented token bucket, keys on user_id with IP fallback

run 会在 dashboard 上展示(抽屉中的 Run History 部分,每次尝试一行并以颜色区分),也会通过 REST API 暴露(GET /api/plugins/kanban/tasks/:id 返回一个 runs[] 数组)。带 {status: "done", summary, metadata} 的 PATCH /api/plugins/kanban/tasks/:id 会将两者都转发给 kernel,因此 dashboard 的"标记完成"按钮与 CLI 等效。task_events 行会携带它们所属的 run_id,以便 UI 按尝试进行分组;而 completed 事件会在其 payload 中嵌入首行 summary(上限 400 个字符),这样 gateway 通知器无需再进行一次 SQL 查询即可渲染结构化交接信息。

批量关闭的注意事项。 kopi kanban complete a b c --summary X 会被拒绝——结构化交接是针对单次 run 的,因此把同一段 summary 复制粘贴到 N 个任务几乎总是错误的。不带 --summary / --metadata 的批量关闭仍然适用于"我完成了一堆行政任务"这类常见场景。

状态变更导致的 run 回收。 如果你在 dashboard 上把一个运行中的任务从 running 拖走(拖回 ready,或直接拖到 todo),或者归档一个仍在运行的任务,进行中的 run 会以 outcome='reclaimed' 关闭,而不会变成孤儿。当 tasks.current_run_id 为 NULL 时,task_runs 行总是处于终态,反之亦然——这一不变量在 CLI、dashboard、调度器和通知器中都成立。

从未被认领的完成操作的合成 run。 完成或阻塞一个从未被认领的任务(例如人工从 dashboard 上带 summary 地关闭一个 ready 任务,或 CLI 用户运行 kopi kanban complete <ready-task> --summary X)原本会丢失交接信息。现在 kernel 会插入一个零时长的 run 行(started_at == ended_at),携带 summary / metadata / reason,从而使尝试历史保持完整。completed / blocked 事件的 run_id 会指向该行。

抽屉实时刷新。 当 dashboard 的 WebSocket 事件流报告了用户当前正在查看的任务的新事件时,抽屉会自行重新加载(通过一个逐任务的事件计数器,该计数器被传入其 useEffect 依赖列表)。要查看 run 的新行或更新后的结果,不再需要关闭并重新打开抽屉。

前向兼容性​

tasks 上预留了两个可空列用于 v2 的工作流路由:workflow_template_id(该任务所属的模板)和 current_step_key(该模板中当前处于活动状态的步骤)。v1 kernel 在路由时会忽略它们,但允许客户端写入,因此 v2 发布时无需再做 schema 迁移即可加入路由机制。

事件参考​

每次状态转换都会向 task_events 追加一行。每行都带有一个可选的 run_id,因此 UI 可以按 attempt 对事件进行分组。Kind 归为三类,便于过滤(kopi kanban watch --kinds completed,gave_up,timed_out):

生命周期(任务作为逻辑单元发生了什么变化):

KindPayload触发时机
created{assignee, status, parents, tenant}任务已插入。run_id 为 NULL。
promoted—todo → ready,因为所有父任务都已达到 done。run_id 为 NULL。
claimed{lock, expires, run_id}Dispatcher 原子地认领了一个 ready 任务以进行 spawn。
completed{result_len, summary?}Worker 写入了 --result / --summary,且任务达到 done。summary 是首行交接内容(上限 400 字符);完整版本存放在 run 行上。如果对一个从未被认领但带有交接字段的任务调用 complete_task,会合成一个零时长的 run,以便 run_id 仍然指向某个对象。
blocked{reason, kind, recurrences}Worker 或人工将任务置为 blocked。kind 是带类型的阻塞原因(needs_input、capability、transient,或 null 表示通用阻塞);recurrences 是解除阻塞循环的计数器。当对一个从未被认领但带有 --reason 的任务调用时,会合成一个零时长的 run。
dependency_wait{reason, kind}Worker 因 kind=dependency 而阻塞——任务只是在等待另一个任务,因此它会被路由到 todo(受父任务门控、自动提升),而不是 blocked。无需人工介入。
block_loop_detected{reason, kind, recurrences, limit}某个任务因相同原因 BLOCK_RECURRENCE_LIMIT 次(默认 2 次)被解除阻塞后又重新阻塞。它不会再次落到 blocked(在那里 cron 会不断解除其阻塞),而是被路由到 triage 交由人工决策,从而打破"解除阻塞↔重新阻塞"的循环。
unblocked—blocked → ready(如果父任务仍未关闭则是 todo),可通过手动或 /unblock 触发。会重置 dispatcher 的 consecutive_failures,但有意保留 block_recurrences,使循环中断器保留其记忆。run_id 为 NULL。
archived—从默认看板中隐藏。如果任务仍在运行,则携带因副作用被回收的那次 run 的 run_id。

编辑(非状态转换的、由人工驱动的变更):

KindPayload触发时机
assigned{assignee}负责人已变更(包括取消指派)。
edited{fields}标题或正文已更新。
reprioritized{priority}优先级已变更。
status{status}仪表盘拖放直接写入了状态(例如 todo → ready)。当从 running 拖出时,携带被回收的那次 run 的 run_id;否则 run_id 为 NULL。

Worker 遥测(关于执行过程,而非逻辑任务):

KindPayload触发时机
spawned{pid}Dispatcher 成功启动了一个 worker 进程。
heartbeat{note?}Worker 在长时间操作期间调用 kopi kanban heartbeat $TASK 以发放心跳信号。
reclaimed{stale_lock}认领 TTL 到期且未收到完成信号;任务退回 ready。
crashed{pid, claimer}Worker PID 已不再存活,但 TTL 尚未到期。
timed_out{pid, elapsed_seconds, limit_seconds, sigkill}超出 max_runtime_seconds;dispatcher 发送 SIGTERM(5 秒宽限期后发送 SIGKILL)并重新入队。
stale{elapsed_seconds, last_heartbeat_at, heartbeat_age_seconds, timeout_seconds, pid, terminated}任务运行时间超过 kanban.dispatch_stale_timeout_seconds(默认 4 小时)且最后一小时内未收到 kanban_heartbeat。Dispatcher 会向宿主本地的 worker(如有)发送 SIGTERM,并将任务重置为 ready 以便重新调度。不会增加失败计数器(stale 属于 dispatcher 侧的缺失检测,而非 worker 故障)。执行长时间操作的 worker 应至少每小时调用一次 kanban_heartbeat 以避免这种情况。
respawn_guarded{reason}Dispatcher 在本次 tick 中拒绝重新 spawn 这个就绪任务。原因包括:blocker_auth(最近一次失败是配额/认证/429 错误——需等待速率窗口重置)、recent_success(最近一小时内有一次已完成的 run——需等待评审后再重新运行)、active_pr(最近的评论中出现了 GitHub PR URL——之前的 worker 已经打开了 PR)。任务保持在 ready;下一个 tick 将再次获得 spawn 机会。如果底层状况持续存在,正常的 consecutive_failures 熔断器将在 failure_limit 次失败后通过 gave_up 自动阻塞。
spawn_failed{error, failures}一次 spawn 尝试失败(PATH 缺失、工作区无法挂载等)。计数器递增;任务返回 ready 以进行重试。
protocol_violation{pid, claimer, exit_code}Worker 在任务仍为 running 时正常退出,通常是因为它在未调用 kanban_complete 或 kanban_block 的情况下就给出了回答。Dispatcher 同时会发出 gave_up 并立即自动阻塞,而不是重试。
gave_up{failures, effective_limit, limit_source, error}在 N 次连续非成功尝试后熔断器触发。任务带上最后一次错误自动阻塞。有效限制的解析顺序为:任务 max_retries,然后 dispatcher failure_limit / kanban.failure_limit,最后是内置默认值。

kopi kanban tail <id> 会展示单个任务的这些事件。kopi kanban watch 会在整个看板范围内流式输出它们。

不在范围内​

Kanban 特意设计为单宿主。~/.kopi/kanban.db 是一个本地 SQLite 文件,dispatcher 在同一台机器上 spawn worker。不支持跨两台宿主机运行共享看板——没有用于"宿主机 A 上的 worker X、宿主机 B 上的 worker Y"的协调原语,而且崩溃检测路径假设 PID 是宿主本地的。如果你需要多宿主机,请为每台宿主机运行一个独立的看板,并使用 delegate_task / 消息队列来桥接它们。

设计规范​

完整设计——架构、并发正确性、与其他系统的对比、实现计划、风险、未决问题——位于 docs/kopi-kanban-v1-spec.pdf。在提交任何行为变更 PR 之前请先阅读该文档。