尧图网站建设 
Dograh 的 AGENTS.md 层级审查技能一套面向 AI 协作文档漂移审计的实操方法【免费下载链接】dograhOpen source voice AI platform. Self-hosted alternative to Vapi and Retell. On Prem, BYOK across Speech to Speech or LLM/STT/TTS, with a visual workflow builder, MCP native and telephony support.项目地址: https://gitcode.com/GitHub_Trending/do/dograhDograh 仓库使用一套按目录层级分布的AGENTS.md文档来向 AI 编码代理和人类贡献者传递各子系统的上下文与扩展规则而文档与现实代码之间的漂移drift会直接误导代理的行为。本文基于仓库内的技能定义文件 .agents/skills/review-agents-md/SKILL.md完整拆解其先审计、后修改的审查流程、层级归属测试parent-fit / child-fit / no-drift 等、Dograh 项目特定的审查启发式以及配套的清单脚本与 seam 参考文件读完你可以掌握一套可复用于任何多AGENTS.md仓库的文档漂移审计方法并能理解 Dograh 后端路由聚合、telephony/integrations 双注册表为何是该技能重点校验的对象。技能的定位与接口review-agents-md是 Dograh 仓库.agents/skills/目录下的一个代理技能。其 frontmatter 定义了三要素name: review-agents-md description: Audit Dograh AGENTS.md files for drift against the live repo and for bad scope boundaries between parent and child docs. Use when the user asks to review existing AGENTS files, identify stale guidance, decide whether a subtree needs its own AGENTS.md, or update the AGENTS.md hierarchy under the repo root, api/, or ui/.它明确了四个典型触发场景审查现有 AGENTS 文件、识别过期指引、判断某个子树是否需要独立的AGENTS.md、更新仓库根 /api//ui/下的文档层级。技能的默认行为是审计优先Audit first除非用户明确要求打补丁否则只报告漂移、覆盖缺失和错误的归属边界不动文档。同目录下的 .agents/skills/review-agents-md/agents/openai.yaml 进一步给出了面向 OpenAI 代理的界面元数据default_prompt为一句话Use $review-agents-md to audit AGENTS.md files for drift, missing coverage, and wrong scope boundaries.说明该技能被设计为可直接以$review-agents-md引用的原子能力。核心原则仓库即事实来源Freshness Rule技能开篇确立了全部审计行为的基准以当前代码和当前目录结构为准任何AGENTS.md、README.md或技能自身的参考文件都不得凌驾于其上文字描述与代码不一致时将文字报告为过期stale如果技能自己的参考文件与仓库不符信任仓库并明确指出这处漂移。这条原则之所以重要是因为 Dograh 是一个后端域较多、扩展点较多的项目AGENTS.md一旦写死具体文件清单就会迅速过期。仓库内的真实例子是 references/dograh-seams.md 中记录的已知漂移案例api/services/telephony/README.md曾描述扁平的twilio_provider.py之类的旧文件布局、指向旧的组织配置存储形态而实际运行时代码早已迁移到providers/name/提供者包 注册表驱动的解析方式。因此该参考文件明确规定不要在 seam 文件里固化当前AGENTS.md清单必须用rg --files -g AGENTS.md .动态发现任何内嵌清单都视为漂移风险并应删除。审计工作流Workflow技能把工作流划分为 0–7 共八个步骤以下按顺序展开并给出在 Dograh 仓库上的可验证落点。步骤 0先刷新 seam 参考再使用它references/dograh-seams.md是快速起步地图而非事实来源所以在依赖它之前必须先刷新若环境支持子代理subagents为这次维护恰好派生一个子代理指令其检查实时仓库把它的补丁集限定为 .agents/skills/review-agents-md/references/dograh-seams.md且仅当 .agents/skills/review-agents-md/scripts/inventory_agents_md.py 这个助手脚本本身需要仓库特定的修复时才允许动它明确告诉子代理不要递归进入同样的 seam 刷新流程——这是一次单层维护而不是无限自我审计循环也不要让它此时审查或修改任何仓库AGENTS.md子代理返回后主流程快速过一遍它的 diff再在主审计中使用dograh-seams.md。技能给出了可直接使用的提示词模板Review and refresh .agents/skills/review-agents-md/references/dograh-seams.md against the live Dograh repo. Patch only that file, and patch .agents/skills/review-agents-md/scripts/inventory_agents_md.py only if needed. Do not recurse into another seam-refresh pass. Do not review or edit any AGENTS.md files yet.若子代理不可用则在本地执行同样的 seam 刷新后再继续。步骤 1盘点当前层级首先在仓库根运行助手脚本python .agents/skills/review-agents-md/scripts/inventory_agents_md.py它输出四部分内容所有发现的AGENTS.md、每个子AGENTS.md的归属边界、每个 scope 的直接子目录、可能值得拥有独立AGENTS.md的大而未覆盖子树。需要时用直接的文件发现交叉验证rg --files -g AGENTS.md . find api ui -name AGENTS.md | sort在 Dograh 仓库上实际执行当前层级为 8 个文件仓库根 AGENTS.md、api/AGENTS.md、api/services/integrations/AGENTS.md、api/services/telephony/AGENTS.md、api/services/telephony/providers/AGENTS.md、ui/AGENTS.md、docs/AGENTS.md、scripts/AGENTS.md。脚本的实际输出同时标出了若干热点候选例如根层级的evals/27 个代码文件、18 个嵌套目录与sdk/41 个代码文件没有本地AGENTS.mdapi/services/下则有 3 个更深层AGENTS.md——这些只是候选不是结论脚本末尾的 Notes 明确写着这是启发式清单不是自动决策引擎。步骤 2自上而下阅读再判断细节阅读顺序固定为仓库根AGENTS.mdapi/AGENTS.mdui/AGENTS.md以上各树内更深层的AGENTS.md每读一个文件在笔记中写一行归属声明回答三件事它拥有哪个子树、它应该包含哪些共享规则、哪些更深层文档应该接管实现细节。这对应技能的核心立场——AGENTS.md是导航与边界文档不是实现手册。步骤 3对照实时代码逐一核验核验对象是目录树、路由聚合器、注册点和扩展缝seam而不是文字里提到的文件名。技能列出了 Dograh 值得尽早检查的文件清单这些点在本仓库中均可直接验证文档声明的锚点源码事实REST 路由聚合在api/routes/main.pyapi/routes/main.py 中from api.services.integrations import all_routers随后逐个router.include_router(...)挂接 telephony、superuser、workflow、campaign 等路由集成包路由经all_routers()挂载api/app.py 中api_router.include_router(main_router)后将整个 REST 树挂到/api/v1前缀下集成包注册/运行时编排api/services/integrations/registry.py 提供register_package(IntegrationPackageSpec)、create_runtime_sessions(...)、run_completion_handlers(...)包发现基于模块扫描api/services/integrations/loader.py 使用pkgutil.iter_modules(package.__path__)动态发现集成包Telephony 注册表驱动api/services/telephony/registry.py 定义了ProviderSpec、register(spec)、get(name)、all_specs()各提供者包在自身__init__.py中自注册当需要快速定位这些缝时再阅读 dograh-seams.md。该参考文件按根层锚点 / 后端锚点 / 前端锚点 / 已知漂移 / 热点启发式组织其中几个对审计最关键的论断包括工作流执行不是一个文件夹图/DTO/节点数据在api/services/workflow/实时管线执行在api/services/pipecat/通话后的 QA、已注册集成与 webhook 执行在api/tasks/run_integrations.py。若api/AGENTS.md暗示工作流执行只在一处应视为可疑区分两种 MCPDograh 自托管的 MCP API 挂在api/mcp_server/由api/app.py挂载 stateless FastMCP 应用而客户在 workflow 里配置的 MCP 工具会话在api/services/workflow/mcp_tool_session.py二者不可混淆路由-服务-数据库边界当前后端并不强制 route → service → db 的调用链所有 ORM 会话与事务细节必须留在api/db/包内其他运行时代码包直接构造 SQLAlchemy 查询属于边界违规租户隔离从已认证上下文推导 organization是不可谈判的第二条边界前端锚点页面在ui/src/app/生成式 API 客户端在ui/src/client/由ui/openapi-ts.config.ts配置、经 ui 包的generate-client脚本重新生成AuthProvider在拉取/api/config/auth后才在 Stack 与本地包装器之间选择因此auth 是编译期静态的这类文档表述属于可疑。步骤 4套用层级测试对每个 scope 应用六项测试这是技能的方法论核心测试判定标准parent-fit父文档解释它的直接子系统、共享不变量和导航child-fit更深层文档拥有本地的扩展契约、模块级 gotcha、文件级模式no-duplication父文档不复述本应属于子文档的详细实现指引downward-pointing文档把贡献者指向下一个相关子目录或更深层AGENTS.md而不是试图自己解释整棵子树no-gaps某个大或扩展密集的子树若规则无法被父文档用几行干净地解释则标记缺失的子级AGENTS.mdno-drift文件树、命令、扩展点和架构声明仍然与代码一致步骤 5Dograh 特定审查启发式针对四个关键文件技能给出了各自的预期轮廓根AGENTS.md应停留在高层级——描述顶层项目形态、共享技术栈、共享本地开发预期提及对贡献者重要的顶层应用与支持目录不应记录后端内部扩展契约或前端组件内部。若某个对贡献者实质重要的顶层目录未被根文档覆盖报告missing-parent-coverage。api/AGENTS.md应把贡献者带过后端各域而不是完整记录每个本地契约。需指到路由、服务、数据库访问、schemas、任务、测试与安全不变量所在处需准确描述工作流执行的分布api/services/workflow/、api/services/pipecat/、api/tasks/run_integrations.py三处需把 telephony 描述为一个重量级子系统而非一个路由文件应提及集成可扩展性并把包级规则让渡给api/services/integrations/AGENTS.md。若api/services/telephony/或api/services/workflow/复杂到父文档变得含糊或超载报告missing-child-agents。api/services/integrations/AGENTS.md拥有集成包契约——包注册、节点模型/规格模式、运行时收集、完成处理、可选路由、导入纪律与测试预期。必须与活的注册表/加载器路径一致即register_packagepkgutil发现的动态路径而不是描述中央手动接线这种已不存在的模式除非通用框架本身变了否则不应要求新集成去编辑workflow/dto.py、run_pipeline.py或路由聚合。ui/AGENTS.md应在不记录单个功能内部细节的前提下导览前端——描述ui/src/app/的 App Router 布局、指向ui/src/components/的可复用组件、提及ui/src/client/的生成式客户端用法、提及ui/src/lib/auth/的认证就绪约束不应描述已删除的文件夹或过期的技术栈细节。步骤 6给发现分类每个发现归入五类之一stale文字提到的文件、命令、流程或架构已与仓库不符missing-parent-coverage父 scope 遗漏了它应当为读者定向的重要子系统missing-child-agents某个深层子树很可能需要自己的AGENTS.mdwrong-level内容放错了父/子层级extra-detail父文档对其所在层级而言过于实现细节化。步骤 7报告格式先按严重程度列出发现格式固定为path: category - problem - what should own or replace it技能给出的三个示例直接展示三类典型问题api/AGENTS.md: missing-child-agents - telephony is a large extension surface with provider registration, transport, routes, and config rules but has no local AGENTS.md - add api/services/telephony/AGENTS.md and keep api/AGENTS.md at navigation level api/services/integrations/AGENTS.md: stale - says central DTO edits are required for new integrations, but registry-based discovery handles node resolution - update the doc to describe the registry path only ui/AGENTS.md: wrong-level - describes individual workflow-builder component behavior instead of frontend navigation rules - move that detail to a deeper doc or remove it在发现列表之后附未决问题或假设仅在用户要求修复或明显希望下一步修复时才附可选的补丁计划。清单脚本 inventory_agents_md.py 的实现要点.agents/skills/review-agents-md/scripts/inventory_agents_md.py 是上述流程的自动化底座读懂它的判定逻辑有助于正确解读输出发现discoverydiscover_agents()从给定 roots默认.做os.walk跳过IGNORE_DIRS中列出的构建/缓存目录.git、node_modules、__pycache__、.venv、dist等及所有点开头目录收集全部AGENTS.md归属边界child AGENTSdirect_child_agents()只返回最近的后代AGENTS.md——如果某个更深的AGENTS.md已经被中间某层子 scope 拥有祖先层就不重复列出避免把所有权层级显示得比实际更扁平热点hotspot一个子目录被列为热点候选需同时满足三个条件——自身没有AGENTS.md、代码文件数.py/.ts/.tsx/.js/.jsx/.mjs/.cjs达到--hotspot-threshold默认12、且没有任何更深层AGENTS.mdnested_hotspots()进一步支持伞形目录下的二级热点用于识别形如ui/src/下再细分app/、components/、lib/的情况。脚本支持roots位置参数与--hotspot-threshold选项可只扫描某个子树自我约束main()结尾固定打印三条 Notes——启发式清单不是决策引擎、热点只是更深层AGENTS.md的候选、报告漂移前必须对照实时代码验证架构声明。这套实现正好呼应 Freshness Rule脚本负责发现与计数判定该不该有独立文档永远交给步骤 2–7 的人工/代理审查。编辑规则只有用户要求修复时才动笔当用户明确要求修复文档时技能给出一组克制性的编辑纪律只打补丁能恢复干净层级的最小AGENTS.md集合仅当子树拥有独特的本地规则或扩展契约时才新增AGENTS.md父文档保持短小、导航性子文档拥有本地实现规则避免把同一份指引复制到父子两个文件写导航指引时优先用文件夹而非文件除非某个文件是唯一的真实接缝新增子级AGENTS.md时从最短有用契约起步避免教程式行文始终向下指路——把读者指向下一个相关子目录或子级AGENTS.md草稿一旦显得刻意或过度解释就再次压缩。常用命令速查技能末尾沉淀的验证命令集覆盖盘点—定位—核验扩展缝三层python .agents/skills/review-agents-md/scripts/inventory_agents_md.py # 层级盘点 rg --files -g AGENTS.md . # 全仓发现 find api ui -name AGENTS.md | sort # 前后端两棵树 find api/services -maxdepth 2 -type d | sort # 后端服务子树 find ui/src -maxdepth 2 -type d | sort # 前端子树 rg -n include_router|all_routers api/routes/main.py api/services/integrations # 路由聚合缝 rg -n register\(|ProviderSpec|register_package|create_runtime_sessions|run_completion \ api/services/telephony api/services/integrations # 双注册表扩展缝最后两条 ripgrep 针对的正是 Dograh 的两个核心扩展机制telephony 的ProviderSpec/register()注册链见 api/services/telephony/registry.py与集成包的register_package/create_runtime_sessions/run_completion编排见 api/services/integrations/registry.py。任何声称新增集成/新增电话服务商需要中央接线的文档文字都可以用这两条命令在十秒内证伪。总结这套方法的可迁移价值review-agents-md本质上把AI 协作文档的维护变成了与代码同等严格的工程活动仓库是唯一事实来源、审计先于编辑、层级归属用六项测试裁决、发现用五类标签归档、报告用统一三元组格式输出并且用一层先刷新地图再看地图的子代理流程防止参考文件自身腐烂。对 Dograh 这类多AGENTS.md、多注册式扩展点路由聚合、telephony 注册表、集成包注册表、MCP 工具的仓库它给出的不是一份静态检查清单而是一套可反复执行、输出可对比的审查程序——这正是多代理协作仓库里文档不腐化的关键机制。【免费下载链接】dograhOpen source voice AI platform. Self-hosted alternative to Vapi and Retell. On Prem, BYOK across Speech to Speech or LLM/STT/TTS, with a visual workflow builder, MCP native and telephony support.项目地址: https://gitcode.com/GitHub_Trending/do/dograh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Dograh 的 AGENTS.md 层级审查技能：一套面向 AI 协作文档漂移审计的实操方法
Dograh 的 AGENTS.md 层级审查技能一套面向 AI 协作文档漂移审计的实操方法【免费下载链接】dograhOpen source voice AI platform. Self-hosted alternative to Vapi and Retell. On Prem, BYOK across Speech to Speech or LLM/STT/TTS, with a visual workflow builder, MCP native and telephony support.项目地址: https://gitcode.com/GitHub_Trending/do/dograhDograh 仓库使用一套按目录层级分布的AGENTS.md文档来向 AI 编码代理和人类贡献者传递各子系统的上下文与扩展规则而文档与现实代码之间的漂移drift会直接误导代理的行为。本文基于仓库内的技能定义文件 .agents/skills/review-agents-md/SKILL.md完整拆解其先审计、后修改的审查流程、层级归属测试parent-fit / child-fit / no-drift 等、Dograh 项目特定的审查启发式以及配套的清单脚本与 seam 参考文件读完你可以掌握一套可复用于任何多AGENTS.md仓库的文档漂移审计方法并能理解 Dograh 后端路由聚合、telephony/integrations 双注册表为何是该技能重点校验的对象。技能的定位与接口review-agents-md是 Dograh 仓库.agents/skills/目录下的一个代理技能。其 frontmatter 定义了三要素name: review-agents-md description: Audit Dograh AGENTS.md files for drift against the live repo and for bad scope boundaries between parent and child docs. Use when the user asks to review existing AGENTS files, identify stale guidance, decide whether a subtree needs its own AGENTS.md, or update the AGENTS.md hierarchy under the repo root, api/, or ui/.它明确了四个典型触发场景审查现有 AGENTS 文件、识别过期指引、判断某个子树是否需要独立的AGENTS.md、更新仓库根 /api//ui/下的文档层级。技能的默认行为是审计优先Audit first除非用户明确要求打补丁否则只报告漂移、覆盖缺失和错误的归属边界不动文档。同目录下的 .agents/skills/review-agents-md/agents/openai.yaml 进一步给出了面向 OpenAI 代理的界面元数据default_prompt为一句话Use $review-agents-md to audit AGENTS.md files for drift, missing coverage, and wrong scope boundaries.说明该技能被设计为可直接以$review-agents-md引用的原子能力。核心原则仓库即事实来源Freshness Rule技能开篇确立了全部审计行为的基准以当前代码和当前目录结构为准任何AGENTS.md、README.md或技能自身的参考文件都不得凌驾于其上文字描述与代码不一致时将文字报告为过期stale如果技能自己的参考文件与仓库不符信任仓库并明确指出这处漂移。这条原则之所以重要是因为 Dograh 是一个后端域较多、扩展点较多的项目AGENTS.md一旦写死具体文件清单就会迅速过期。仓库内的真实例子是 references/dograh-seams.md 中记录的已知漂移案例api/services/telephony/README.md曾描述扁平的twilio_provider.py之类的旧文件布局、指向旧的组织配置存储形态而实际运行时代码早已迁移到providers/name/提供者包 注册表驱动的解析方式。因此该参考文件明确规定不要在 seam 文件里固化当前AGENTS.md清单必须用rg --files -g AGENTS.md .动态发现任何内嵌清单都视为漂移风险并应删除。审计工作流Workflow技能把工作流划分为 0–7 共八个步骤以下按顺序展开并给出在 Dograh 仓库上的可验证落点。步骤 0先刷新 seam 参考再使用它references/dograh-seams.md是快速起步地图而非事实来源所以在依赖它之前必须先刷新若环境支持子代理subagents为这次维护恰好派生一个子代理指令其检查实时仓库把它的补丁集限定为 .agents/skills/review-agents-md/references/dograh-seams.md且仅当 .agents/skills/review-agents-md/scripts/inventory_agents_md.py 这个助手脚本本身需要仓库特定的修复时才允许动它明确告诉子代理不要递归进入同样的 seam 刷新流程——这是一次单层维护而不是无限自我审计循环也不要让它此时审查或修改任何仓库AGENTS.md子代理返回后主流程快速过一遍它的 diff再在主审计中使用dograh-seams.md。技能给出了可直接使用的提示词模板Review and refresh .agents/skills/review-agents-md/references/dograh-seams.md against the live Dograh repo. Patch only that file, and patch .agents/skills/review-agents-md/scripts/inventory_agents_md.py only if needed. Do not recurse into another seam-refresh pass. Do not review or edit any AGENTS.md files yet.若子代理不可用则在本地执行同样的 seam 刷新后再继续。步骤 1盘点当前层级首先在仓库根运行助手脚本python .agents/skills/review-agents-md/scripts/inventory_agents_md.py它输出四部分内容所有发现的AGENTS.md、每个子AGENTS.md的归属边界、每个 scope 的直接子目录、可能值得拥有独立AGENTS.md的大而未覆盖子树。需要时用直接的文件发现交叉验证rg --files -g AGENTS.md . find api ui -name AGENTS.md | sort在 Dograh 仓库上实际执行当前层级为 8 个文件仓库根 AGENTS.md、api/AGENTS.md、api/services/integrations/AGENTS.md、api/services/telephony/AGENTS.md、api/services/telephony/providers/AGENTS.md、ui/AGENTS.md、docs/AGENTS.md、scripts/AGENTS.md。脚本的实际输出同时标出了若干热点候选例如根层级的evals/27 个代码文件、18 个嵌套目录与sdk/41 个代码文件没有本地AGENTS.mdapi/services/下则有 3 个更深层AGENTS.md——这些只是候选不是结论脚本末尾的 Notes 明确写着这是启发式清单不是自动决策引擎。步骤 2自上而下阅读再判断细节阅读顺序固定为仓库根AGENTS.mdapi/AGENTS.mdui/AGENTS.md以上各树内更深层的AGENTS.md每读一个文件在笔记中写一行归属声明回答三件事它拥有哪个子树、它应该包含哪些共享规则、哪些更深层文档应该接管实现细节。这对应技能的核心立场——AGENTS.md是导航与边界文档不是实现手册。步骤 3对照实时代码逐一核验核验对象是目录树、路由聚合器、注册点和扩展缝seam而不是文字里提到的文件名。技能列出了 Dograh 值得尽早检查的文件清单这些点在本仓库中均可直接验证文档声明的锚点源码事实REST 路由聚合在api/routes/main.pyapi/routes/main.py 中from api.services.integrations import all_routers随后逐个router.include_router(...)挂接 telephony、superuser、workflow、campaign 等路由集成包路由经all_routers()挂载api/app.py 中api_router.include_router(main_router)后将整个 REST 树挂到/api/v1前缀下集成包注册/运行时编排api/services/integrations/registry.py 提供register_package(IntegrationPackageSpec)、create_runtime_sessions(...)、run_completion_handlers(...)包发现基于模块扫描api/services/integrations/loader.py 使用pkgutil.iter_modules(package.__path__)动态发现集成包Telephony 注册表驱动api/services/telephony/registry.py 定义了ProviderSpec、register(spec)、get(name)、all_specs()各提供者包在自身__init__.py中自注册当需要快速定位这些缝时再阅读 dograh-seams.md。该参考文件按根层锚点 / 后端锚点 / 前端锚点 / 已知漂移 / 热点启发式组织其中几个对审计最关键的论断包括工作流执行不是一个文件夹图/DTO/节点数据在api/services/workflow/实时管线执行在api/services/pipecat/通话后的 QA、已注册集成与 webhook 执行在api/tasks/run_integrations.py。若api/AGENTS.md暗示工作流执行只在一处应视为可疑区分两种 MCPDograh 自托管的 MCP API 挂在api/mcp_server/由api/app.py挂载 stateless FastMCP 应用而客户在 workflow 里配置的 MCP 工具会话在api/services/workflow/mcp_tool_session.py二者不可混淆路由-服务-数据库边界当前后端并不强制 route → service → db 的调用链所有 ORM 会话与事务细节必须留在api/db/包内其他运行时代码包直接构造 SQLAlchemy 查询属于边界违规租户隔离从已认证上下文推导 organization是不可谈判的第二条边界前端锚点页面在ui/src/app/生成式 API 客户端在ui/src/client/由ui/openapi-ts.config.ts配置、经 ui 包的generate-client脚本重新生成AuthProvider在拉取/api/config/auth后才在 Stack 与本地包装器之间选择因此auth 是编译期静态的这类文档表述属于可疑。步骤 4套用层级测试对每个 scope 应用六项测试这是技能的方法论核心测试判定标准parent-fit父文档解释它的直接子系统、共享不变量和导航child-fit更深层文档拥有本地的扩展契约、模块级 gotcha、文件级模式no-duplication父文档不复述本应属于子文档的详细实现指引downward-pointing文档把贡献者指向下一个相关子目录或更深层AGENTS.md而不是试图自己解释整棵子树no-gaps某个大或扩展密集的子树若规则无法被父文档用几行干净地解释则标记缺失的子级AGENTS.mdno-drift文件树、命令、扩展点和架构声明仍然与代码一致步骤 5Dograh 特定审查启发式针对四个关键文件技能给出了各自的预期轮廓根AGENTS.md应停留在高层级——描述顶层项目形态、共享技术栈、共享本地开发预期提及对贡献者重要的顶层应用与支持目录不应记录后端内部扩展契约或前端组件内部。若某个对贡献者实质重要的顶层目录未被根文档覆盖报告missing-parent-coverage。api/AGENTS.md应把贡献者带过后端各域而不是完整记录每个本地契约。需指到路由、服务、数据库访问、schemas、任务、测试与安全不变量所在处需准确描述工作流执行的分布api/services/workflow/、api/services/pipecat/、api/tasks/run_integrations.py三处需把 telephony 描述为一个重量级子系统而非一个路由文件应提及集成可扩展性并把包级规则让渡给api/services/integrations/AGENTS.md。若api/services/telephony/或api/services/workflow/复杂到父文档变得含糊或超载报告missing-child-agents。api/services/integrations/AGENTS.md拥有集成包契约——包注册、节点模型/规格模式、运行时收集、完成处理、可选路由、导入纪律与测试预期。必须与活的注册表/加载器路径一致即register_packagepkgutil发现的动态路径而不是描述中央手动接线这种已不存在的模式除非通用框架本身变了否则不应要求新集成去编辑workflow/dto.py、run_pipeline.py或路由聚合。ui/AGENTS.md应在不记录单个功能内部细节的前提下导览前端——描述ui/src/app/的 App Router 布局、指向ui/src/components/的可复用组件、提及ui/src/client/的生成式客户端用法、提及ui/src/lib/auth/的认证就绪约束不应描述已删除的文件夹或过期的技术栈细节。步骤 6给发现分类每个发现归入五类之一stale文字提到的文件、命令、流程或架构已与仓库不符missing-parent-coverage父 scope 遗漏了它应当为读者定向的重要子系统missing-child-agents某个深层子树很可能需要自己的AGENTS.mdwrong-level内容放错了父/子层级extra-detail父文档对其所在层级而言过于实现细节化。步骤 7报告格式先按严重程度列出发现格式固定为path: category - problem - what should own or replace it技能给出的三个示例直接展示三类典型问题api/AGENTS.md: missing-child-agents - telephony is a large extension surface with provider registration, transport, routes, and config rules but has no local AGENTS.md - add api/services/telephony/AGENTS.md and keep api/AGENTS.md at navigation level api/services/integrations/AGENTS.md: stale - says central DTO edits are required for new integrations, but registry-based discovery handles node resolution - update the doc to describe the registry path only ui/AGENTS.md: wrong-level - describes individual workflow-builder component behavior instead of frontend navigation rules - move that detail to a deeper doc or remove it在发现列表之后附未决问题或假设仅在用户要求修复或明显希望下一步修复时才附可选的补丁计划。清单脚本 inventory_agents_md.py 的实现要点.agents/skills/review-agents-md/scripts/inventory_agents_md.py 是上述流程的自动化底座读懂它的判定逻辑有助于正确解读输出发现discoverydiscover_agents()从给定 roots默认.做os.walk跳过IGNORE_DIRS中列出的构建/缓存目录.git、node_modules、__pycache__、.venv、dist等及所有点开头目录收集全部AGENTS.md归属边界child AGENTSdirect_child_agents()只返回最近的后代AGENTS.md——如果某个更深的AGENTS.md已经被中间某层子 scope 拥有祖先层就不重复列出避免把所有权层级显示得比实际更扁平热点hotspot一个子目录被列为热点候选需同时满足三个条件——自身没有AGENTS.md、代码文件数.py/.ts/.tsx/.js/.jsx/.mjs/.cjs达到--hotspot-threshold默认12、且没有任何更深层AGENTS.mdnested_hotspots()进一步支持伞形目录下的二级热点用于识别形如ui/src/下再细分app/、components/、lib/的情况。脚本支持roots位置参数与--hotspot-threshold选项可只扫描某个子树自我约束main()结尾固定打印三条 Notes——启发式清单不是决策引擎、热点只是更深层AGENTS.md的候选、报告漂移前必须对照实时代码验证架构声明。这套实现正好呼应 Freshness Rule脚本负责发现与计数判定该不该有独立文档永远交给步骤 2–7 的人工/代理审查。编辑规则只有用户要求修复时才动笔当用户明确要求修复文档时技能给出一组克制性的编辑纪律只打补丁能恢复干净层级的最小AGENTS.md集合仅当子树拥有独特的本地规则或扩展契约时才新增AGENTS.md父文档保持短小、导航性子文档拥有本地实现规则避免把同一份指引复制到父子两个文件写导航指引时优先用文件夹而非文件除非某个文件是唯一的真实接缝新增子级AGENTS.md时从最短有用契约起步避免教程式行文始终向下指路——把读者指向下一个相关子目录或子级AGENTS.md草稿一旦显得刻意或过度解释就再次压缩。常用命令速查技能末尾沉淀的验证命令集覆盖盘点—定位—核验扩展缝三层python .agents/skills/review-agents-md/scripts/inventory_agents_md.py # 层级盘点 rg --files -g AGENTS.md . # 全仓发现 find api ui -name AGENTS.md | sort # 前后端两棵树 find api/services -maxdepth 2 -type d | sort # 后端服务子树 find ui/src -maxdepth 2 -type d | sort # 前端子树 rg -n include_router|all_routers api/routes/main.py api/services/integrations # 路由聚合缝 rg -n register\(|ProviderSpec|register_package|create_runtime_sessions|run_completion \ api/services/telephony api/services/integrations # 双注册表扩展缝最后两条 ripgrep 针对的正是 Dograh 的两个核心扩展机制telephony 的ProviderSpec/register()注册链见 api/services/telephony/registry.py与集成包的register_package/create_runtime_sessions/run_completion编排见 api/services/integrations/registry.py。任何声称新增集成/新增电话服务商需要中央接线的文档文字都可以用这两条命令在十秒内证伪。总结这套方法的可迁移价值review-agents-md本质上把AI 协作文档的维护变成了与代码同等严格的工程活动仓库是唯一事实来源、审计先于编辑、层级归属用六项测试裁决、发现用五类标签归档、报告用统一三元组格式输出并且用一层先刷新地图再看地图的子代理流程防止参考文件自身腐烂。对 Dograh 这类多AGENTS.md、多注册式扩展点路由聚合、telephony 注册表、集成包注册表、MCP 工具的仓库它给出的不是一份静态检查清单而是一套可反复执行、输出可对比的审查程序——这正是多代理协作仓库里文档不腐化的关键机制。【免费下载链接】dograhOpen source voice AI platform. Self-hosted alternative to Vapi and Retell. On Prem, BYOK across Speech to Speech or LLM/STT/TTS, with a visual workflow builder, MCP native and telephony support.项目地址: https://gitcode.com/GitHub_Trending/do/dograh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考