SuperAPI AI 工具集

kanban

通用与其它

查看项目

更新于 10-22 20:09

技能介绍

kanban 是一个由文件支撑的看板工作器,所有工单、评论和活动时间线都保存在一个看板文件(<data_path>/board.json)中。每张工单都有一个内部 uuid 和一个人类可读 key(如 KAN-7,大小写不敏感),二者在任何需要定位工单的地方均可使用。列、优先级、key 前缀和完成列属于配置项,可通过 kanban::config::info 查看当前生效值;默认看板列为 backlog、todo、in_progress、in_review、done。

用途:适用于功能正在规划、分派给其他代理档案或评审,且计划需要比聊天会话存续更久的场景;也适用于被分派到某张工单后认领、汇报并交接给评审者,或需要在某张工单有人类或其他代理评论时做出反应而不轮询,以及在控制台会话旁展示看板或工单。

主要能力:工单支持标题、描述、状态、优先级、负责人、标签、pills 徽章、actor 等字段;最多有一个父任务(子任务)、一个项目和一个发布,三者相互独立。父任务进度只统计处于 done_status 列的子任务,canceled_status 列的子任务不计入。工单不会被代理删除:完成的工单移动到 in_review 或 done,软删除由人工在控制台工单页面执行(磁盘行保留并设置 deleted_at)。写入需要 actor,评论需要 author,应传入自己的代理档案 id,因为评论过滤正是按该字符串匹配。此外还支持项目与发布的列表和管理、标签转换为项目或发布、代理档案列表等。

函数概览:kanban::config::info 返回解析后的设置(看板文件路径、列、done_status、canceled_status、优先级、key 前缀、代理文件夹);kanban::board::get 返回各列及工单摘要,以及 done_status、项目和发布及其计数,可用 statuses、updated_since、limit、compact 缩小读取范围,用 parent_id、project_id、release_id 过滤;kanban::ticket::create 创建工单;kanban::ticket::get 按 uuid 或 key 获取单张工单及其评论、活动、父任务、子任务和进度;kanban::ticket::list 按列、负责人、更新时间、父任务、项目或发布筛选工单摘要;kanban::ticket::links 返回某工单提及的工单以及提及它的工单;kanban::ticket::update 修改字段,支持 add_labels/remove_labels 避免并发覆盖;kanban::ticket::move 移动工单到某列某位置;kanban::ticket::delete/restore 为软删除与恢复(人工操作);kanban::comment::create 创建评论或回复(回复仅一层);kanban::comment::list 按作者、排除作者、仅根评论或时间过滤;kanban::activity::list 返回工单时间线;kanban::agent::list 返回可分配的代理档案及 id;kanban::project::list 和 kanban::release::list 返回项目与发布信息;项目与发布的创建、更新、归档、恢复、发布、重开、删除等为人工操作;kanban::label::convert 将携带某标签的工单转为项目或发布(人工操作)。子任务只有一层:父任务必须存活且自身无父任务,有存活子任务的工单不能再获得父任务。附加或解除会在两张工单上写活动记录。子任务不继承父任务的项目或发布,需要显式传入。项目或发布可按 id 或名称定位;已归档项目拒绝新工单,已发布发布仍接受工单。

使用方式:在聊天中可用 @kanban(id="<uuid>") 提及工单,消息会带上 <mentions> 块和已预验证的 kanban::ticket::get 调用;回复中指向工单时写入函数返回的 id 即可渲染为工单 pill。评论应作为决策与交接日志,而非执行轨迹:仅在有实质范围/验收决策、新可行动阻塞或人类问题、带证据的评审拒绝、或整合后的最终交接时评论;不要发布每次工具调用、分派、阶段起止、成功检查或内部重试。发布前先读已有评论,去重并整合同轮事实。

反应式触发器:当某张工单有人评论时,可注册 kanban:comment 触发器和/或省略 function_id 的代理会话以被唤醒;ticket_id 或 parent_id 必填,parent_id 会为父任务及其任一子任务的评论触发。author、exclude_author、root_only 可进一步收窄;"ticket": "summary" 会投递看板卡片字段而非整张工单及线程。变更会触发触发器,读取不会。kanban:change 是看板级触发器,在 ticket.created、ticket.updated、ticket.moved、ticket.deleted、ticket.restored、comment.created 等事件时触发,仅按工单和事件名过滤,可带 parent_id 和 release_id。绑定方式为注册处理器(或省略 function_id 以唤醒代理会话),再通过 engine::register_trigger 注册触发器,示例配置包含 trigger_type、config、once 和 lifecycle(max_fires、expires_in_ms)。注意该工作器只向自身进程内映射中的绑定投递,因此常驻唤醒应配合对 kanban::comment::list 的 cron 检查。载荷形状可对触发器类型调用 get function info 获取。

限制:不是通用任务队列或持久作业存储,必须执行的工作应使用 queue,需规划与评审的工作才使用看板;kanban:change 没有作者过滤,需要排除自己发布的评论时应使用 kanban:comment 的 exclude_author;删除与恢复是人工操作,代理只移动工单;创建、交付或归档项目与发布、以及将标签转换为项目或发布属于控制台操作,唯一例外是 deepwork 编排器创建其运行的项目;代理档案通过 iii-directory 解析(以配置的 agents 文件夹为后备),该工作器不创建档案。