喂指令与可观测 — 带内的约定,不是线协议
1. 这条分支是什么
前 4 条分支都是 agent 运行时对外的线协议(怎么调工具、怎么对话、怎么画 UI、怎么付钱)。这条分支补的是另一面:
人/仓库/站点怎么把意图喂给 agent(指令、能力包、优先级、可读内容),以及系统怎么观测 agent 的行为(标准化遥测)。它们多为约定与契约,不是握手式线协议。
第一性原理:agent 要可控、可信、可运维,需要两类约定——输入侧(谁的指令算数、能力怎么打包、站点怎么自报内容)和输出侧(行为怎么被一致地记录与观测)。本分支把这两侧的标准都收在一起。
2. 分支内有哪几种做法(流派)
喂指令与可观测
├── 输入侧:给 agent 喂指令/能力/内容
│ ├── 仓库级指令 ........ AGENTS.md(就近文件生效,跨 harness 约定)
│ ├── 能力打包 .......... Agent Skills(SKILL.md 文件夹 + 渐进披露 + 校验器)
│ ├── 指令优先级 ........ OpenAI Model Spec(platform>developer>user>tool)
│ └── 站点自报内容 ...... llms.txt(站点给 LLM 一份可读清单)
└── 输出侧:观测 agent 行为
└── OTel GenAI ........ LLM/agent/tool 调用的标准 span/属性/metric
3. 对比矩阵
| 库 | 是约定还是规范 | 标准化什么 | 谁消费 | 约束在哪 | 成熟度 | 代码锚点 |
|---|---|---|---|---|---|---|
| agents-md | 跨 harness 约定 | 仓库级 agent 指令文件;monorepo 就近文件优先 | 编码 agent(harness 自动加载,各家支持不一) | 几乎全在 README 散文,无 schema | LF AAIF(2025-12 捐赠) | agents-md/README.md(格式)、根 AGENTS.md(自举示例) |
| agent-skills-spec | 开放格式规范 | SKILL.md frontmatter(name/description/allowed-tools)+ 渐进披露 + 目录约定 | 任何加载 skill 的 agent | 约束几乎全在 frontmatter,正文刻意宽松 | 有参考校验器 | agent-skills-spec/docs/specification.mdx:27(name/description 约束)、skills-ref/ |
| openai-model-spec | OpenAI 模型策略 | 指令优先级(platform>developer>user>tool);可指令 vs 硬规则 | OpenAI 模型;思路可借鉴 | 单文件散文 + 范例 | 单文档,跟 CHANGELOG diff | openai-model-spec/model_spec.md(按标题跳读) |
| llms-txt | 站点约定 | /llms.txt:H1 + 摘要 blockquote + 链接分节 + .md 孪生页 | 抓站点的 LLM/agent | H1 是唯一必需段;参考解析器定边界 | 约定,仓库锁定即真相 | llms-txt/nbs/index.qmd:42(H1 必需);llms_txt/(参考解析器) |
| otel-genai-semconv | 遥测语义规范 | GenAI 的 span/属性/metric/event 名(LLM/agent/tool 调用) | 观测后端 + instrumentation 库 | YAML 属性注册表生成文档 | upstream 仍 unstable;属性名钉 commit | otel-genai-semconv/docs/gen-ai/gen-ai-spans.md、gen-ai-metrics.md、model/gen-ai/(YAML);MCP 专页已迁至独立仓 semantic-conventions-genai,本仓 mcp.md 现为重定向桩 |
4. 模式与权衡
- “约定”极轻但无强制力,“规范”有结构但更重。 AGENTS.md/llms.txt 是约定——agent 去固定路径取文件即可,无握手无校验,各 harness 支持参差;Agent Skills/OTel 是有结构的规范——前者有校验器、后者有 YAML 注册表。按“你要不要可校验/可协商”选。
- AGENTS.md vs llms.txt:指令 vs 内容。 AGENTS.md 是“给 agent 的操作指令”(怎么在这仓库干活);llms.txt 是“给 LLM 的可读内容”(这站点有什么)。别混。
- Agent Skills 的约束只在 frontmatter。 正文刻意宽松——别凭空发明正文的结构要求;要校验就用
skills-ref。 - Model Spec 是 OpenAI 的策略,借思路别照搬。 指令分层(root vs delegated)的思想通用、值得借鉴;但具体行为规则是 OpenAI 模型专属,不要当普适规则导入。
- OTel GenAI 是输出侧唯一项。 它把 ①–④ 分支里发生的 LLM/tool/agent 调用变成可观测 span/metric(
docs/gen-ai/gen-ai-spans.md、gen-ai-metrics.md),是观测与本货架其余协议的接缝。注意: 早期本仓的 MCP 专页(docs/gen-ai/mcp.md)已迁至独立仓semantic-conventions-genai,本仓该文件现为「Moved / no longer maintained」重定向桩——接 MCP 调用属性时引上游独立仓,勿引本仓mcp.md。
5. 趋势
- 指令侧在收敛与治理化:AGENTS.md 入 LF AAIF,Agent Skills 出参考校验器——从“各家私有约定”走向“可校验的开放格式”。
- 观测侧 OTel GenAI 仍 unstable;GenAI semconv 近期整体迁仓到
semantic-conventions-genai(含 MCP、各 provider 专页),适配器钉属性名到 lock commit,并核对引用是否指向迁移后的仓。
6. 代表作 + 深入
- 首读(指令):
agents-md(README 即全部约定)+agent-skills-spec(docs/specification.mdx的 frontmatter 表)。 (TODO: 待各子库 doc) - 优先级思想:
openai-model-spec。 (TODO: 待子库 doc) - 站点内容:
llms-txt。 (TODO: 待子库 doc) - 观测:
otel-genai-semconv(docs/gen-ai/的 spans/metrics;MCP 专页见迁移后的semantic-conventions-genai)。 (TODO: 待子库 doc)