Agent 框架后端低代码RAG【免费下载链接】yao✨ All your agents and workspaces in one place, on every device you own. Track tasks on a board, accessible from desktop, mobile, browser, or API. Self-hosted.项目地址https://gitcode.com/gh_mirrors/ya/yao点击查看免费下载本文围绕 tools/skills/yao-board/SKILL.md 这一能力型 Skill 文档展开系统讲解 Yao 中看板Kanban Board与任务Task查询工具board_list、task_list的用法、参数约定与调用规范并结合仓库源码剖析其从tai toolCLI → Process → 服务层 SQL 查询的完整链路。读完本文你将掌握如何在沙箱工作区内通过 bash 调用看板与任务查询工具、如何理解并组合task_list的五个过滤参数、如何根据返回的 JSON 结构做二次加工以及这些工具背后在 agent/board 与 agent/task 中的真实实现原理。一、yao-board Skill 是什么yao-board是 Yao 项目在tools/skills/目录下提供的能力型 Skill 之一其定义文件 SKILL.md 的 YAML frontmatter 声明了--- name: yao-board description: Kanban board and task query expert. ALWAYS invoke this skill when the user asks about boards, tasks, task status, or project progress. Do not guess task state — use this skill first. ---从description可以提炼出该 Skill 的设计意图触发时机只要用户询问看板boards、任务tasks、任务状态task status或项目进度project progressAgent 就应当主动调用本 Skill而不是凭记忆猜测任务状态角色定位它是看板与任务查询专家通过两个工具board_list、task_list经 bash 完成查询使用纪律Do not guess task state — use this skill first——这条规则强调任务状态必须以工具返回的 JSON 为准杜绝 Agent 幻觉。1.1 Skill 如何被注入与自动发现在 Yao 的沙箱工作区机制中Skill 并不是靠手动阅读生效的。从 tools/skills.go 可以看到//go:embed skills var SkillsFS embed.FStools/skills/目录下的全部SKILL.md通过go:embed编译进二进制随后被注入到沙箱工作区。系统提示词模板 tools/prompts/system-tools.md.tmpl 中对此有明确说明The system skills (yao-web,yao-process,yao-doc,yao-image,yao-audio,yao-agent,yao-secret,yao-board,yao-workspace, ...) in$HOME/.claude/skills/areauto-discovered— they contain detailed parameter docs and workflow guidance. You do not need to manually read them; they are loaded automatically when your task matches their description.也就是说当 Agent 的任务与某个 Skill 的description匹配时对应 Skill 会被自动加载。在系统工具总表中board_list与task_list都被标注为属于yao-boardSkill见 tools/prompts/system-tools.md.tmpl。1.2 统一的 CLI 调用约定所有 Yao 系统工具都遵循同一条 bash 调用约定见 tools/prompts/system-tools.md.tmpltai tool name --param value [--param2 value2 ...]而 Skill 文档中的示例采用的是将参数打包为单个 JSON 字符串的等价形式tai tool name json两者均可使用本文后续示例统一采用 Skill 文档原生的 JSON 参数形式。二、board_list列出所有看板board_list用于列出当前用户/团队可见的全部看板以及每个看板的列column与任务计数task count。2.1 基本用法Skill 文档给出的最小调用tai tool board_list {}该工具不接受任何输入参数。工具定义文件 tools/board/list_schema.json 印证了这一点{ name: board_list, description: List all kanban boards with columns and task counts, process: tools.board_list, inputSchema: { type: object, properties: {} }, x-process-args: [] }2.2 返回结构board_list的返回体由 agent/board/types.go 中的ListResult与Board、Column结构定义type ListResult struct { Boards []*Board json:boards } type Board struct { BoardID string json:board_id Name string json:name Icon string json:icon,omitempty Color string json:color,omitempty Position int json:position TaskCount int json:task_count Columns []*Column json:columns,omitempty Metadata any json:metadata,omitempty CreatedAt time.Time json:created_at UpdatedAt time.Time json:updated_at } type Column struct { ColumnID string json:column_id BoardID string json:board_id Name string json:name Icon string json:icon,omitempty Color string json:color,omitempty Position int json:position Collapsed bool json:collapsed Metadata any json:metadata,omitempty CreatedAt time.Time json:created_at }典型的返回 JSON 大致形如{ boards: [ { board_id: xxx, name: 开发工作流, icon: material-view_kanban, color: #6366F1, position: 1, task_count: 12, columns: [ { column_id: col-1, name: To Do, position: 0, collapsed: false }, { column_id: col-2, name: In Progress, position: 1, collapsed: false }, { column_id: col-3, name: Done, position: 2, collapsed: false } ], created_at: ..., updated_at: ... } ] }2.3 源码视角数据从哪来从 agent/board/board.go 的List实现可以看到查询链路分为三步查看板以deleted_at IS NULL过滤按position ASC排序查询看板表查列对每个看板调用getColumns(b.BoardID)加载其列数任务用列 ID 集合执行WHERE IN (column_id)deleted_at IS NULL的Count()得到TaskCount填入返回体。同时该方法还受auth.Constraints约束TeamOnly时按团队 ID 过滤CreatorOnly时按创建者过滤这与 Skill 中当前用户可见的语义一致。2.4 看板的来源模板看板通常不是凭空创建的而是从模板生成。仓库内置了两份模板agent/board/templates/kanban-basic.yaml基础看板与 agent/board/templates/dev-workflow.yaml开发工作流。以kanban-basic.yaml为例它定义了四个经典列并附带zh-CN本地化id: kanban-basic name: Basic Kanban icon: material-view_kanban color: #6366F1 columns: - name: To Do icon: material-inbox color: #F59E0B - name: In Progress icon: material-sync color: #3B82F6 - name: In Review icon: material-visibility color: #8B5CF6 - name: Done icon: material-done_all color: #10B981 locales: zh-CN: name: 基础看板 columns: - name: 待办 - name: 进行中 - name: 审核中 - name: 完成模板的 i18n 解析逻辑ResolvedName/ResolvedColumnName定义在 agent/board/types.go优先返回locales中指定语言的名字找不到时回退到默认名。这意味着不同语言环境下同一个看板可以呈现不同的列名。三、task_list带过滤的任务查询task_list是任务查询的主力工具支持按状态、按助手、按看板三种维度过滤并支持分页。3.1 基本用法与参数表Skill 文档给出的示例tai tool task_list {board_id: xxx, run_status: running}完整的参数表摘自 tools/skills/yao-board/SKILL.md 与 tools/task/list_schema.json参数类型必填说明run_statusstring否运行状态过滤pending / running / waiting / completed / failedassistant_idstring否按助手 ID 过滤board_idstring否按看板 ID 过滤pagenumber否页码默认 1page_sizenumber否每页条数默认 50对应的 JSON Schema 定义见 tools/task/list_schema.json其中每个参数的description与上表一一对应x-process-args依次映射到$args.run_status、$args.assistant_id、$args.board_id、$args.page、$args.page_size。3.2 参数解析与默认值agent/task/types.go 中的ListQuery还额外包含archive_status与locale两个字段当前 CLI 工具层暂未暴露属服务层能力type ListQuery struct { RunStatus string json:run_status,omitempty ArchiveStatus string json:archive_status,omitempty AssistantID string json:assistant_id,omitempty BoardID string json:board_id,omitempty Page int json:page,omitempty PageSize int json:page_size,omitempty Locale string json:locale,omitempty }在 agent/task/task.go 的List实现中默认值逻辑为PageSize 0时取 50Page 0时取 1。因此即使不传分页参数也会得到一个最多 50 条、从第 1 页开始的结果集。3.3 返回结构task_list的返回体ListResult见 agent/task/types.gotype ListResult struct { Tasks []*Task json:tasks Total int64 json:total Page int json:page PageSize int json:page_size }单个Task除了基础字段chat_id、column_id、position、pinned、priority、tags、run_status、progress、duration、run_count、created_at等之外还包含通过 JOIN 派生出来的关联字段title、assistant_id、assistant_name、board_id、workspace_name、connector_label以及查询期计算的next_run调度任务的下次运行时间。这让一次task_list调用就能拿到任务在看板列 × 助手 × 工作区三个维度上的完整上下文。3.4 源码视角过滤与联表查询agent/task/task.go 中的List查询是理解各过滤参数语义的关键run_status直接对任务表t.run_status做等值过滤assistant_id通过左连接聊天表c过滤c.assistant_id——注意助手是挂在 chat 上的不是任务表字段board_id通过左连接看板列表col过滤col.board_id——看板归属同样需要 JOIN 才能得到分页offset (page - 1) * page_size配合ORDER BY t.position ASC排序软删除所有查询都带WhereNull(t.deleted_at)权限约束与board_list一致TeamOnly/CreatorOnly约束在任务表上生效。查询完成后还有两步后处理resolveWorkspaceNames解析工作区名称、resolveNextRun计算下次调度时间若传入Locale还会用 i18n 对assistant_name做本地化翻译见 agent/task/task.go。3.5 run_status 的生命周期Skill 文档列出的五种run_status取值pending/running/waiting/completed/failed与执行引擎的生命周期严格对应可以从 agent/task/task.go 中印证新建任务时写入run_status: pending第 262 行且默认priority: none、progress: 0、run_count: 0开始执行时更新为running第 594、627 行引擎执行完成后置为completed出错置为failed需要人工介入时处于waiting特别值得注意的是注释第 289 行run_status不能通过 Update 接口手工修改它完全由执行引擎控制——这正是 Skill 文档强调不要猜测任务状态先调用工具的原因。四、组合查询的实战工作流Skill 文档末尾的 Guidelines 给出了官方推荐的调用流程这也是 Agent 在真实对话中应该遵循的决策路径先用board_list发现看板拿到board_id、列结构及其task_count确定项目进度的载体再用task_list配合过滤定位具体任务按board_id收敛范围按run_status筛选进行中/已阻塞/已完成按assistant_id定位到具体助手负责的任务消费 JSON 输出所有工具输出均为 JSON直接解析即可无需二次猜测。一个典型的汇报项目进度调用序列# 第一步发现看板 tai tool board_list {} # 第二步定位某个看板下所有 running 任务 tai tool task_list {board_id: xxx, run_status: running} # 第三步查看某位助手名下待办任务可结合分页 tai tool task_list {assistant_id: smith.weather, run_status: pending, page: 1, page_size: 20}这套序列恰好对应description中 boards, tasks, task status, project progress 四种查询诉求且每一步的输出 JSON 都能直接用于生成用户可读的进度摘要。五、看板与任务的完整工具族yao-boardSkill 只承载了两个查询工具但看板域在仓库中拥有一套完整的工具族注册于 MCP 清单 tools/mcps/kanban.json{ name: yao-kanban, transport: process, description: Kanban board, task management, and inbox tools, tools: { task_list: tools.task_list, task_create: tools.task_create, task_move: tools.task_move, board_list: tools.board_list, board_create: tools.board_create, inbox_list: tools.inbox_list, inbox_view: tools.inbox_view } }各工具的入口均位于 tools/task 与 tools/board要点如下board_create新建看板必填name可选icon、colorSchema 见 tools/board/create_schema.jsontask_create新建任务必填title、assistant_id、column_id可选chat_id入口在 tools/task/create.go创建后任务即落入pending状态见 agent/task/task.go并通过事件总线广播task.createdtask_move把任务移动到目标列/位置必填chat_id、column_id、position见 tools/task/move.go 与 tools/task/move_schema.jsontask_run运行或恢复任务向任务发送一条消息以启动执行见 tools/task/run.gotask_stop停止任务支持force强制终止见 tools/task/stop.go。这五个写操作与board_list/task_list两个查询操作共同构成查询 → 定位 → 创建 → 移动 → 运行/停止的闭环而yao-boardSkill 承担的是其中先看清楚再动手的入口职责。六、调用链路的源码级串联从一条tai tool task_list {run_status: running}命令到最终 JSON 返回完整的链路可以这样概括CLI 层tai tool解析工具名与参数命中tools.task_listProcess工具入口层 tools/task/list.go 的ListHandler从proc.ArgsMap(0)取出参数字典逐字段类型断言后填充tasksvc.ListQueryrun_status、assistant_id、board_id断言为 stringpage、page_size断言为 float64 后转 int桥接层工具包内的FnList函数指针由 openapi/agent/task对应看板为 openapi/agent/board/tools_bridge.go在init()中注入为服务层实现boardsvc.List/tasksvc.List服务层 agent/task/task.go 执行过滤条件拼装 双查询count 与分页数据 JOIN 派生字段 后处理的完整逻辑agent/board/board.go 执行看板 → 列 → 任务计数的聚合逻辑返回层结果统一序列化为 JSON出错时返回{error: ...}结构见各 Handler 的错误分支。对于看板工具其函数指针注入在 openapi/agent/board/tools_bridge.goboardtools.FnList boardsvc.List、boardtools.FnCreate boardsvc.Create。任务侧同理FnList、FnCreate、FnMove、FnRun、FnStop五个指针由 openapi/agent/task 注入声明见 tools/task/task.go。理解这条链路的价值在于当task_list的过滤结果不符合预期时排查方向是清晰的——先确认参数是否进入ListQuery工具层解析再看对应过滤条件是否命中正确的表字段服务层 JOIN 语义而不是盲目怀疑工具本身。七、使用注意与边界状态以工具返回为准run_status由执行引擎控制、不可手工修改agent/task/task.go任何猜状态的行为都违反 Skill 的description约束看板归属的过滤语义board_id过滤实际作用于列表的board_id因此一个任务必须落在某看板的某列中才会被board_id命中软删除已软删除的看板与任务不会出现在查询结果中deleted_at IS NULL分页上限默认每页 50 条遍历大结果集时请使用page翻页并注意total字段以判断是否还有后续页Skill 自动发现yao-board无需手工读取任务匹配其description时会被自动加载tools/skills.go若要为 Agent 补充工具指引可参考本目录下其他SKILL.md的组织方式如 tools/skills/yao-agent/SKILL.md。综上yao-board虽是一份极简的 Skill 文档但其背后是完整的CLI 工具 → Process → 服务层查询架构。掌握board_list的看板发现、task_list的五参数组合过滤以及它们的数据语义就掌握了在 Yao 中回答一切任务状态与项目进度问题的正确姿势。赞分享Agent 框架后端低代码RAG【免费下载链接】yao✨ All your agents and workspaces in one place, on every device you own. Track tasks on a board, accessible from desktop, mobile, browser, or API. Self-hosted.项目地址https://gitcode.com/gh_mirrors/ya/yao点击查看免费下载相关推荐Homepage 接入 Vikunja任务看板 Widget 配置与源码级原理解析Homepage 接入 Vikunja任务看板 Widget 配置与源码级原理解析 Vikunja 是一款开源的任务管理与待办事项工具而 Homepage前端用 Obsidian Dataview 的 TASK 查询构建任务看板从过滤、排序到分组与源码解析用 Obsidian Dataview 的 TASK 查询构建任务看板从过滤、排序到分组与源码解析 导读 在 Obsidian 中使用 Dataview ht前端知识管理数据分析k-skill-proxy 使用统计看板Promtail Loki Grafana 日志分析栈的部署与查询实战k skill proxy 使用统计看板Promtail Loki Grafana 日志分析栈的部署与查询实战 k skill proxy 是 k s人工智能AI 技能上一篇ColorControl一键掌控显示设备与智能电视的终极解决方案下一篇如何在PC上完美使用PS4手柄DS4Windows游戏控制器映射终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考