基础篇
进阶篇
高频篇
精选篇
手写篇
面经篇
AI 篇
原理篇
每日一题
小程序题库
  • 知识卡片碎片时间过考点
  • 场景篇按分类整理的大前端场景考点
  • 历年面经按年份追踪真实考点
  • 算法题库NEW在线编码即时判题
  • 专项自测100 题快速查漏
  • 前端基础
    • HTTP从报文一路讲到 HTTPS
    • 浏览器渲染、事件循环、进程
    • 计算机基础Linux、网络、操作系统
  • 进阶专项
    • 设计模式23 种模式怎么用
    • 前端系统进阶学习大型项目工程化
    • 前端综合文章长期沉淀的实践文
  • 工程与工具
    • Node学习指南从环境搭建到服务端
    • NPM工作流script、依赖与发布
    • Docker容器化部署上手
    • Canvas图形与动画实战
  • 路线与导图
    • 思维导图知识点全景图
    • 学习路线按图索骥不跑偏
  • 动态
    • 公众号动态公众号历史文章
    • 博客动态站长的技术博客
    • 开发者导航常用工具与文档站
    • AI 热点每日 AI 资讯与动向
AI 工作台
旧版
AIHT
内容
精选全部 AI 动态热点榜AI 日报收藏
分类
模型行业编程产品技术观点开源
更多
Agent 接入
返回首页开发者导航
AIHT
精选 / 资讯详情
5.0
关注
AI SCORE
技术实践2026-08-01 20:03

Agent配置:AGENTS.md可移植性与结构化文件的分工

dev.to · AI#Agent工程#配置管理
Editor brief · 编辑速览

讨论APC框架中AGENTS.md根文件与.apc/agents/目录的职责划分,前者负责发现兼容性,后者承载结构化细节。

文章思维导图
Knowledge map
拖拽缩放
Full translation

完整中文译文

结构化 Agent 文件应该拥有细节。AGENTS.md 应该保持便携性。

APC 最有效的做法是同时完成两项工作而不混淆它们。

第一项工作:为每个工具提供一个显而易见的项目入口点。那就是仓库根目录下的 AGENTS.md。

第二项工作:为 APC 感知工具提供一个更清洁的位置来存储结构化细节。那就是 .apc/project.json 旁边的 .apc/agents/<slug>.md。

这种分离之所以重要,是因为兼容性和结构是不同的问题。

在 AGENTS.md 的 APC 配套规范中,根文件被定义为面向兼容性的 agent 发现契约。它位于项目根目录,紧邻 .apc/,许多工具已经知道如何找到和读取它。同一规范还指出,当同一 slug 的 .apc/agents/<slug>.md 存在时,该结构化文件应被视为权威的结构化定义。

这就是正确的边界。

如果你试图把所有细节都放进 AGENTS.md,根契约就会变得很庞杂。冗长的描述、自定义字段、内存覆盖、技能列表和格式边界情况全都挤到了每个运行时必须最先扫描的那个文件中。便携式发现变得更难,正好因为"简单入口点"开始表现得像一个数据库。

如果你走另一个极端、完全放弃 AGENTS.md,便携性会更差。许多工具能够上溯仓库寻找一个熟悉的根文件。但较少工具会在第一天就知道你的内部结构化布局。

APC 通过保持两个层级来避免这种权衡。

一个轻量级的根契约看起来可以是这样的:

# Agents

## reviewer
- **Role**: Code review
- **Model**: gpt-5
- **Skills**: documentation
- **Description**: Reviews risks, tests, and regressions.

这足以用于发现、路由和对项目的初步理解。

然后更丰富的定义可以放在 APC 感知工具期望的地方:

.apc/
  project.json
  agents/
    reviewer.md

这也匹配 APX 使用项目的方式。

APX 在运行时将 AGENTS.md 作为项目指导读入。在 buildProjectAgentsBlock 中,它加载根文件,必要时截断,然后作为"项目指导 (AGENTS.md)"注入到 prompt 中。这是一个关于预期大小和目的的强烈暗示:有用的启动规则,而不是持续增长的 agent 内部转储。

APX 还有一个专门的 AGENTS.md 部分解析器。它查找一个 # Agents 标题,读取每个 ## <slug> 块,并提取角色、模型、技能和描述等项目符号字段。这个解析器存在是因为根契约需要保持可预测和便携。

所以实际规则很简单:

在 AGENTS.md 中放置跨工具发现信息。

在 .apc/agents/ 中放置结构化的逐 agent 细节。

将运行时会话、对话和私有状态都排除在两者之外;APX 将这些存储在 ~/.apx/ 下。

这为 APC 提供了一个持久的便携层,为 APX 提供了一个干净的日常使用运行时层。

AGENTS.md 保持对人类和广泛兼容工具的可读性。.apc/agents 保持对更丰富的 APC 原生结构的可用性。APX 随后可以连接两者,而不会将其中任何一个变成错误类型的存储。

便携式项目通常因为重载每个人都触及的第一个文件而失败。APC 通过保持索引精简、将细节放在结构应该在的位置而走得更远。

Original source

本文由 AI 翻译整理,来源 dev.to · AI,原文版权归原作者所有。

阅读原文
上一篇
大规模人脸识别系统的同意架构与算法公平性
下一篇
Herdr:编码Agent的终端复用与并行管理方案

资讯速览

dev.to · AI · 2026-08-01 20:03

AI 评分 5.0 / 10

相关标签

#Agent工程#配置管理

继续阅读

  • 从代码生成器到生产Agent:工程化三大支柱
  • 大规模人脸识别系统的同意架构与算法公平性
  • Herdr:编码Agent的终端复用与并行管理方案
  • Hugging Face热门论文速览:Agent、长期记忆、World Model
  • MCP扩展IDE:为Copilot集成实时B2B情报数据