企业官网建设流程全解析

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 repo's issue tracker.

也就是说，仓库中各个 AI Skill（技能）在对话中使用的是一套抽象的"标准分诊角色"词汇，而本文件负责把这些角色映射为工单跟踪系统中实际使用的标签字符串。这是一张典型的"词汇桥接表"——它让 Skill 的措辞保持稳定，同时允许底层标签字符串随团队实际用法自由调整。

五个标准分诊角色与标签映射表

以下是docs/agents/triage-labels.md中的完整映射表，左列为 Skill 中的角色名，右列为本仓库工单系统中的实际标签字符串，第三列是其语义：

从源码结构看，当前仓库恰好采用"角色名即标签名"的一一映射，五组字符串完全一致。这并不意味着二者必须相同——正如文档末尾所强调的：

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.md），frontmatter 承载跟踪状态：

--- 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> ---

注意其中两点与分诊标签体系直接相关：

1. labels字段注释显式引用了docs/agents/triage-labels.md，说明 frontmatter 中允许出现的标签值域就是上文映射表中的五个字符串（可以一个或多个）；
2. status（open/in-progress/closed）与labels是两个正交维度：前者描述处理进度，后者描述分诊结论（谁来做、还需什么条件、是否终止）。

笔记正文（Body）为自由格式，包含问题陈述、复现步骤、上下文、验收标准与备注。

通过 Obsidian MCP 读写标签

工单统一存放在个人 Obsidian 的notes/work/strapi/issues/目录下（一单一文件），并通过 Obsidian MCP 工具集完成全部读写操作。docs/agents/issue-tracker.md的 Conventions 一节给出了与各分诊动作一一对应的工具调用：

这条约定的工程价值在于：分诊状态的全部变更都收敛到 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为例，一次完整的分诊落盘流程是：

1. Agent 按 Skill 判定工单规格已完整、可交给无人值守（AFK）Agent 执行；
2. 查表得到右列标签字符串ready-for-agent；
3. 调用 Obsidian MCPupdate_frontmatter，把ready-for-agent加入该工单笔记的labels数组，必要时移除此前的needs-triage；
4. 该工单即可被按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/skills，TARGET_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 specified"（ready-for-agent的语义）正是以领域文档完备为前提的。

五、实战要点小结

• 标签值域：frontmatterlabels数组中只允许出现needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix这五个字符串（或你在映射表右列定制后的等价词）；
• 写入路径：所有标签变更都通过update_frontmatter编辑 frontmatter 数组完成，不写入正文；
• 查询路径：按labels元数据过滤（search_by_metadata）即可得到"所有待 AFK Agent 执行的工单"等分诊视图；
• 正交状态：status（open / 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