workboard Plugin
详细说明 workboard 内建 plugin 如何通过 runtime HTTP 暴露结构化工作快照，以及它为什么更偏观测面和控制面能力
workboard Plugin
workboard 是当前内建 plugin 里最典型的 HTTP 注入型样本。
它不像 skill、web、asr、tts 那样主要靠 action 提供能力，而是更偏：
- 运行时状态暴露
- 结构化快照输出
- 控制面 / UI 消费
它到底做什么
workboard 的职责可以概括成一句话：
- 把 agent 当前和最近的工作状态，以结构化快照的形式暴露给外部界面
它当前最核心的能力是 runtime HTTP 路由：
GET /api/workboard/snapshot
为什么它很重要
因为它说明了一件很关键的事：
- plugin 不一定非要靠
runAction(...)才算“被使用”
有些 plugin 的主要消费者并不是 agent 自己，而是：
- Console
- UI
- 状态面板
- 控制面代理
workboard 正是这种形态。
它使用了哪些 plugin 能力
workboard 当前用到的是：
availabilityhttp.runtime
它没有使用：
actionssetupusagesystemhooks
这说明它的职责非常聚焦：提供一个可控、可鉴权、可观测的 HTTP 能力面。
典型运行流
一个典型的 workboard 请求大致这样运行：
- 外部界面向
/api/workboard/snapshot发起GET - runtime 先按 plugin 声明的鉴权策略判断是否允许访问
workboard检查自身 availability- 如果当前不可用，返回
503 - 如果可用，从快照存储读取当前状态
- 返回结构化 JSON
这里最关键的不是路由本身，而是：
- 路由归属 plugin
- 鉴权策略由 plugin 声明
- availability 也和 plugin 生命周期对齐
鉴权要求
workboard 当前对外暴露的快照接口需要：
- 已认证访问
- 权限
agent.read
这说明它不是一个面向匿名访问的公共状态页，而是一个受控的运行时观测面。
典型场景
场景一：Console 想显示“agent 现在在干什么”
最典型做法就是轮询或按需请求：
GET /api/workboard/snapshot
然后把结果渲染成工作面板。
场景二：你在做一个控制台代理层，想统一读取 agent 运行快照
workboard 提供的是结构化 JSON，而不是零散日志文本，这很适合作为控制面数据源。
场景三：你在做插件文档或架构设计，想参考 HTTP 型 plugin
当前 workboard 就是最直接的参考实现。
在 SDK 里怎么理解它
对于 workboard，最重要的不是“怎么 runAction”，而是“它如何把 HTTP 路由安全地挂进 runtime”。
也就是说，这个 plugin 的主要消费方式更接近：
- 外部 HTTP 客户端访问
而不是：
- 本地 SDK 显式动作调用
它暴露的接口
当前最核心的接口是：
GET /api/workboard/snapshot成功时返回的是结构化快照响应。
如果 plugin 当前不可用，通常会返回：
503
如果内部读取快照出错，通常会返回：
500
为什么它不需要 action
这是理解 workboard 的关键点。
它的目标不是提供“用户手动点一下就执行一个业务动作”的接口，而是提供一个可持续被界面读取的状态面。
在这种场景里：
- HTTP route 比 action 更自然
因为：
- 消费方本来就是 UI / 代理 / 控制台
- 它们最习惯读 HTTP JSON 接口
它和 Plugin HTTP 文档的关系
如果你想真正理解 workboard，推荐搭配看：
因为 workboard 正是该机制在当前代码里的标准样本。
它和 runtime ownership 的边界
workboard 不是一个“独立后台任务 runtime owner”，而是一个：
- runtime 快照暴露插件
它不负责“做工作”，而更负责“把正在做的工作状态暴露出来”。
这类需求天然更适合 plugin HTTP 注入，而不是单独扩展出一套独立通信面。
需要注意的边界
它是观测面，不是业务执行面
不要把它理解成一个业务动作中心。
它依赖受控权限
如果访问方没有 agent.read 权限，这个接口就不应该被放开。
availability 会影响接口行为
即使路由存在，只要 plugin 当前被禁用或不可用，也不意味着请求一定成功。
什么时候优先参考它
当你要设计这些能力时，优先参考 workboard：
- plugin HTTP 注入
- 运行时状态快照
- UI / Console 观测面
- 鉴权受控的状态接口