Strapi AI Agent 工单分诊体系五角色 Triage 标签映射与 Frontmatter 落地机制【免费下载链接】strapi Strapi is the leading open-source headless CMS. It’s 100% JavaScript/TypeScript, fully customizable, and developer-first.项目地址: https://gitcode.com/GitHub_Trending/st/strapi本篇基于 Strapi 仓库中的docs/agents/triage-labels.md及其姊妹文档docs/agents/issue-tracker.md讲解 Strapi 仓库为 AI Agent 工作流设计的工单分诊triage标签体系五个标准分诊角色如何映射到实际的标签字符串、标签如何存储在 Obsidian 工单笔记的 frontmatter 中以及 Skill 在分诊流程中如何引用这些角色。读完本文你可以完整理解并复用这套角色 → 标签 → frontmatter的三级分诊机制并将其嵌入自己的 Agent 化工单流程中。一、Triage 标签体系解决什么问题docs/agents/triage-labels.md开篇即定义了这套体系的角色定位The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repos issue tracker.也就是说仓库中各个 AI Skill技能在对话中使用的是一套抽象的标准分诊角色词汇而本文件负责把这些角色映射为工单跟踪系统中实际使用的标签字符串。这是一张典型的词汇桥接表——它让 Skill 的措辞保持稳定同时允许底层标签字符串随团队实际用法自由调整。五个标准分诊角色与标签映射表以下是docs/agents/triage-labels.md中的完整映射表左列为 Skill 中的角色名右列为本仓库工单系统中的实际标签字符串第三列是其语义Label in mattpocock/skillsLabel in our trackerMeaningneeds-triageneeds-triageMaintainer needs to evaluate this issue需要维护者评估该工单needs-infoneeds-infoWaiting on reporter for more information等待报告者补充信息ready-for-agentready-for-agentFully specified, ready for an AFK agent规格完整可交给无人值守 Agent 处理ready-for-humanready-for-humanRequires human implementation需要人工实现wontfixwontfixWill not be actioned不再跟进从源码结构看当前仓库恰好采用角色名即标签名的一一映射五组字符串完全一致。这并不意味着二者必须相同——正如文档末尾所强调的Edit the right-hand column to match whatever vocabulary you actually use.即右列tracker 实际标签是可定制项。例如当团队把工单迁移到 Linear 并改用不同命名习惯如agent:ready、human时只需修改右列Skill 侧的五角色词汇保持不变。二、标签的存储载体Obsidian 工单笔记与 Frontmatter标签存放在哪里docs/agents/triage-labels.md明确指出Labels are stored in thelabels:frontmatter array of each issue note undernotes/work/strapi/issues/即每个工单是一个 Markdown 笔记文件标签以labels:frontmatter 数组的形式存储在该文件的 YAML 头部。这一约定与docs/agents/issue-tracker.md中的 Note shape 规范完全对应。工单笔记的完整结构docs/agents/issue-tracker.md给出了工单笔记的文件命名与 frontmatter 规范文件名采用slug.md形式示例为cm-403-redirect-loop.mdfrontmatter 承载跟踪状态--- title: short description type: issue status: open | in-progress | closed labels: [needs-triage] # one or more of the triage roles — see docs/agents/triage-labels.md created: YYYY-MM-DD linear: Linear issue URL, once promoted ---注意其中两点与分诊标签体系直接相关labels字段注释显式引用了docs/agents/triage-labels.md说明 frontmatter 中允许出现的标签值域就是上文映射表中的五个字符串可以一个或多个statusopen/in-progress/closed与labels是两个正交维度前者描述处理进度后者描述分诊结论谁来做、还需什么条件、是否终止。笔记正文Body为自由格式包含问题陈述、复现步骤、上下文、验收标准与备注。通过 Obsidian MCP 读写标签工单统一存放在个人 Obsidian 的notes/work/strapi/issues/目录下一单一文件并通过 Obsidian MCP 工具集完成全部读写操作。docs/agents/issue-tracker.md的 Conventions 一节给出了与各分诊动作一一对应的工具调用分诊动作MCP 工具说明创建工单write_note在notes/work/strapi/issues/下新建带上述 frontmatter 的文件读取工单read_note/search_notes按标题/永久链接读取或按关键词检索列出/查询工单list_directory/search_notes/search_by_metadata可按status与labels元数据过滤追加评论patch_note向正文追加内容应用/移除分诊标签update_frontmatter编辑labelsfrontmatter 数组映射关系以docs/agents/triage-labels.md为准关闭工单update_frontmatter将status置为closed这条约定的工程价值在于分诊状态的全部变更都收敛到 frontmatter 的结构化编辑上正文只承载叙述性内容。由于labels是机器可解析的 YAML 数组Agent 可以用search_by_metadata直接按标签如ready-for-agent批量拉取待办工单而不需要解析自然语言正文。三、Skill 如何引用分诊角色使用规则与示例docs/agents/triage-labels.md给出了 Skill 与标签系统之间的唯一使用规则When a skill mentions a role (e.g. apply the AFK-ready triage label), use the corresponding label string from this table.即当某个 Skill 的指令中提到一个角色例如应用 AFK-ready 分诊标签时执行端必须查上表取右列对应的标签字符串写入 frontmatter。以ready-for-agent为例一次完整的分诊落盘流程是Agent 按 Skill 判定工单规格已完整、可交给无人值守AFKAgent 执行查表得到右列标签字符串ready-for-agent调用 Obsidian MCPupdate_frontmatter把ready-for-agent加入该工单笔记的labels数组必要时移除此前的needs-triage该工单即可被按labels元数据过滤的查询取出所有ready-for-agent工单命中并进入 Agent 执行队列。这套角色 → 查表 → 写 frontmatter的路径使得分诊决策在 Skill 层是语义化的Agent 只需理解AFK-ready这个概念在存储层是确定性的字符串值域被映射表锁定。标签词汇的本地化定制文档最后一行是本体系面向复用者的开放接口Edit the right-hand column to match whatever vocabulary you actually use.把右列改为你实际使用的标签词即可。由于 Skill 只依赖左列的五个角色名tracker 侧标签改名不会波及 Skill 措辞反过来只要映射表与 frontmatter 中实际写入的字符串保持同步任何团队都可以让同一套五角色分诊语义适配自己的工单系统词汇。四、辅助机制标签体系所处的 Agent 工作流全景为了理解这套分诊标签在 Strapi 仓库中的运转环境有必要结合仓库中已确认的 Agent 工具链说明其上下游本节为原文档之外的补充佐证。1. 双轨工单跟踪Obsidian 个人轨 Linear 公司轨docs/agents/issue-tracker.md确立了个人轨先行的原则Issues and PRDs for this repo are trackedpersonally in Obsidian first, and only promoted to the companyLinearworkspace when explicitly asked.分诊标签主要活跃在个人轨Obsidian 笔记。只有当用户明确要求升级时才会用 Linear MCP 的save_issue工具标题与正文取自 Obsidian 笔记创建公司侧工单并把返回的 Linear URL 回写到笔记的linear:frontmatter同时保持 Obsidian 笔记作为工作副本。这意味着ready-for-agent、wontfix等分诊状态首先反映在本地笔记上公司轨只承载经过显式升级的记录。2. Skill 的单一事实源与多工具同步分诊标签由 Skill 引用而 Skill 的分发由仓库的 AI 工具链管理。AGENTS.md 的 Skills directories 一节说明.ai/skills/是已提交 Skill 的规范来源每个含SKILL.md的子目录即一个 Skill当前仓库中已提交的是 .ai/skills/git-conventions/SKILL.md.agents/skills/、.claude/skills/、.cursor/skills/三个 AI 工具的 well-known 位置由yarn ai:sync维护为符号链接目标增删 Skill 后运行yarn ai:sync保持三端一致yarn ai:unlink仅移除.ai来源的链接yarn ai:status给出只读的 linked / missing / conflict / stale 报告。从源码结构看该同步逻辑实现在 scripts/ai-tooling/links.ts 中SOURCE_PATH固定为.ai/skillsTARGET_PATHS为上述三个目录sync函数按条目状态机absent/ours/foreign-link/real决定新建、重建、跳过或清理链接listSourceSkills只识别含SKILL.md的子目录。相应行为由 scripts/ai-tooling/tests/links.test.ts 中的用例覆盖路径归一、POSIX/win32 大小写差异、链接分类等。分诊标签文档正是这类 Skill 的共享词汇表——Skill 定义在.ai/skills/而标签词汇的定义收敛在docs/agents/下二者解耦。3. 领域文档的协同消费同目录的 docs/agents/domain.md 规定了 Skill 探索代码库前应先读取的领域文档根目录CONTEXT-MAP.md、各 package 的CONTEXT.md、docs/adr/下的架构决策。分诊过程中ready-for-agent的判定往往依赖这些上下文是否足以支撑无人值守实现——从文档体系的设计意图看Fully specifiedready-for-agent的语义正是以领域文档完备为前提的。五、实战要点小结标签值域frontmatterlabels数组中只允许出现needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix这五个字符串或你在映射表右列定制后的等价词写入路径所有标签变更都通过update_frontmatter编辑 frontmatter 数组完成不写入正文查询路径按labels元数据过滤search_by_metadata即可得到所有待 AFK Agent 执行的工单等分诊视图正交状态statusopen / in-progress / closed记录进度labels记录分诊结论两者独立维护升级动作分诊标签留在个人轨仅在显式要求时用 Linear MCP 创建公司侧工单并回写linear:链接。这套机制的核心设计是把分诊语义五个角色稳定、标签词汇映射表右列可定制、存储实现Obsidian frontmatter可替换三层解耦使 AI Skill 的措辞、团队的实际标签习惯与底层工单系统各自独立演进又始终通过 docs/agents/triage-labels.md 这张映射表保持一致。【免费下载链接】strapi Strapi is the leading open-source headless CMS. It’s 100% JavaScript/TypeScript, fully customizable, and developer-first.项目地址: https://gitcode.com/GitHub_Trending/st/strapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考