概览
metaboard
README / ZH
插件文档
MetaBoard
给编码以外的工作，留下可检视的执行轨迹。
English | 简体中文
编码 agent 有一样别的工具几乎都没有的东西：一份可回溯、可检视的记录，说明这件事究竟是怎么做成的。 每一次检索、每一次工具调用、每一次重试都是一条结构化事件——因为执行器自己会掉出来， 不是靠谁记得去记一笔。
内容创作没有这份记录。看板能告诉你一篇稿子从 todo 挪到了 in_review，
但告诉不了你大纲是从哪二十篇同题材里提炼的、第二次改稿花了多久、编辑打回时具体说了什么。
而这些恰恰是数据不好时你要回头查的东西。
MetaBoard 把 agent 轨迹带到非编码业务上，首个业务域是内容生产。
当前状态
第一阶段——独立 dsh 插件的形态——已经实现，并且在真实会话上验证过；
docs/phase-1-acceptance.md 是记录。当前分支在此之上
加了命令行、项目、留言流、会话绑定的认领，测试套件全程保持全绿。
还有两项验收没有走完，都因为需要一个真实的 dsh 会话才能跑：完整走一遍全流程， 以及两个会话并发认领同一个工作项。认领冲突这部分有单元测试覆盖，还没有在真实运行时上验过。
想找现在就能装的东西，过段时间再来。对「执行轨迹如何脱离软件领域」这个问题感兴趣，可以往下读。
想法
MetaBoard 是 DeepSeek Harness（dsh）的插件。
它复用 dsh 里真正难写、也真正与领域无关的那一部分——会话节点装配器，替换掉与编码绑定的那一层。
装配器把原始事件流变成物化的业务对象：每个注册的 Definition 从单个事件里抽出稳定业务 ID， 在匹配到的事件上折叠状态，产出视图节点。旧一页历史加载进来时，只有答案发生变化的 Context 会被重放。 这套增量重放是长轨迹能保持流畅的原因，也是最不该自己重写一遍的部分。
这套机制里没有任何一处知道 token、工具 schema 或 TTFT。那些在上面一层， 在轨迹 UI 自己的 Definition 里。换掉那一层，同一个引擎渲染的就是另一个领域。
内容轨迹长什么样
竖向顺序是时间。蓝色的边是看板表达不了的东西:这一稿来自哪几条素材、这一版改的是哪一稿。 它们不是推断出来的——每个工具在自己的结果里就记下了。
选中一行打开完整载荷：检索到的素材、稿件全文、它从哪几条来、花了多久。
怎么做的
MetaBoard 是一个普通的、仓库外的 npm 包，两半：
host 半注册内容生产工具。每次调用产生核心的 tool/call 和 tool/result 事件，
领域载荷挂在 tool/result.meta 上——那是 dsh 本来就提供的、工具私有、核心不透明、
持久化保存的 JSON 通道。
client 半注册自己的会话 Definition 和一个视图标签页。Definition 只认领 MetaBoard 自己的调用， 把它们装配成领域对象再渲染。
不 fork，不改宿主，不加新事件类型。
最后这条不是审美偏好，是测出来的边界，而且它塑造了整个设计。
命令与工具
MetaBoard 有两个入口：人直接用的命令行，和 agent 在会话里调的 dsh 工具。两边写的是同一份 工作项日志——谁建的都能被另一边立项、留言、打回。
命令行
| 命令 | 作用 |
|---|---|
metaboard new <标题> [--project <pid>] |
记一个想法，落在「待立项」——agent 碰不到，直到被批准。 |
metaboard approve <id> |
立项：允许 agent 认领并开始做。 |
metaboard ls [--project <pid>] [--all] |
看板：只显示已立项的流水线，按状态分组。--all 连待立项、完成、取消一起列。 |
metaboard show <id> |
这个工作项的完整时间线：看板动作与 dsh 会话事件并成一条线。 |
metaboard status <id> <状态> |
把工作项挪到任意状态。 |
metaboard comment <id> <正文> |
留一句话——要求、疑问、说明。 |
metaboard return <id> <理由> |
打回：等你确认 → 处理中，理由记进留言。 |
metaboard rename <id> <新标题> |
改标题。 |
metaboard archive <id> |
归档。归档只是从看板隐藏，历史仍在。 |
metaboard set-project <id> <pid|-> |
归属到某个项目，- 取消归属。 |
metaboard project new <名字> [--path <绝对目录>] |
建一个项目。--path 把一个绝对目录存进项目记录——目前没有任何地方会反过来用它，把当前目录解析回项目。 |
metaboard project ls |
列出项目。 |
metaboard project rename <pid> <新名字> |
改项目名。 |
metaboard project archive <pid> |
归档项目。归属它的工作项不受影响。 |
metaboard doctor |
检查工作项日志、项目日志、dsh 会话存储三边读不读得到。 |
agent 正在做的工作项带着一个认领：第一个往它上面写的那个会话。认领还在的时候，别的
对话写它一律被拒——两个会话同时写同一个工作项就是这样被拦住的。metaboard show <id>
会印出认领在谁手里。任意 metaboard status <id> <状态> 都会解除认领，会话中途死掉时就靠
这一条把活儿收回来。
dsh 工具
| 工具 | 作用 |
|---|---|
metaboard_work_create |
记一个新工作项，可以在建项时就指定项目。落在待立项——记录一个需求不是授权去做它。 |
metaboard_research |
把已经检索到的素材逐字记下来。 |
metaboard_draft |
把已经写好的草稿逐字记下来。 |
metaboard_revise |
把改稿和依据的意见逐字记下来。 |
metaboard_review |
把一次人工评审的结论记进轨迹。 |
metaboard_work_read |
读一个工作项的标题、状态、项目归属和留言流。读不需要授权。 |
metaboard_report |
把 agent 自己做了什么写进同一条留言流，可以选择顺带把工作项交回去等待确认。 |
已经验证过什么
在写产品代码之前，先直接对着上游代码库把可行性边界探了一遍——测试写进真实的 JSONL 日志， 再用全新挂载的栈读回来。六条命题，全部确认：
| # | 命题 | 结果 |
|---|---|---|
| 1 | Session.append 能否让插件把自己的事件标成可忽略 |
不能。 公开写入 API 打不了这个标记 |
| 2 | 含插件自定义事件类型的日志会怎样 | 整份拒收——SessionFormatUnsupportedError，不是跳过那一行 |
| 3 | 同一条事件带上可忽略标记呢 | 完整读回，一字不差。存储层支持，只是写入侧没开口 |
| 4 | 50KB 的 tool/result.meta 经真实文件往返 |
能。没被 spill，没被截断 |
| 5 | 插件直接 append 的 user/message 能否往返 |
能——不需要模型参与 |
| 6 | 插件事件类型会不会进模型上下文 | 不会。它不是 surface 事件类型 |
第 2 条是 MetaBoard 不定义自己事件类型的原因。第 4、5 条是它不需要定义的原因。
第 3 条记录了一个存在于存储层、但在写入 API 上被有意关闭的口子——
上游文档写明 Session.append 会「在第一个使用者出现时」补上这个入口。
设计
完整设计文档暂时不在这个仓库里。要紧的几个决定：
数据落点只看一个问题——它是事件还是状态。
| 类别 | 例子 | 落点 |
|---|---|---|
| 事件，模型发起 | 检索到的素材、稿件全文、改稿 diff | tool/result.meta |
| 事件，人发起 | 编辑打回、临时指令 | user/message（plugin 来源） |
| 状态 | 选题状态、负责人、看板位置、播放量 | MetaBoard 自有存储 |
Context 身份是一次调用，不是一个选题。 一次调用一个 Context，
让 live append 保持 O(1)，也让 prepend 不会让整个选题的历史失效。
选题 ID 放在节点载荷里，分组在快照装配时做。
失败的调用也必须写信封。 tool/result 的载荷里不带工具名——只有 tool/call 带——
而匹配时不能查历史。信封是唯一的认领依据。工具失败时省掉它，账本上就留下一行永远显示
「运行中」的记录，重新加载也不会好，因为日志里存的就是这个。
引用在渲染时解析，不走依赖 reader。 走 reader 会记下窗口缺口依赖， 每次往回翻都触发链式重放。而引用指向的目标其值从不改变，只是有时还没加载。 渲染一个未解析的引用，代价是它灰一下；另一条路的代价是每条长轨迹的滚动性能。
路线
第一阶段 · 可行性切片。 三个工具、两个 Definition、一个标签页、一张最简行表。 没有检视面板、没有时间轴、没有看板、没有存储层。及格线：层级装得出来、引用解析得出来、 50KB 载荷重开还在、失败的调用渲染成一行完整的失败记录而不是卡住的行。
第二阶段 · 工作项。 看板视图、自有存储、跨会话汇总、平台数据接入。
第三阶段 · 其他领域。 数据落点规则和信封不是内容生产专用的。 法务审查、研究综述、设计迭代是同一个形状：一个多步过程，中间产物比最终状态更值得看。
来源与致谢
MetaBoard 来自两个项目：
- deepseek-ai/deepseek-harness—— 装配器、事件流、轨迹账本，这份设计从中学习。MIT。
- chuspeeism/dashi-taskboard—— 本地优先的任务看板，带工作流图和第三方发布节点。它把字段级审计和 AI 会话记录分成两套的做法， 让中间缺的那一层变得明显。
MetaBoard 与这两个项目均无隶属关系。
许可
MIT