oh-my-pi Coding Agent Advisor 的项目上下文注入context-files 提示块与 AGENTS.md 约束机制解析【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi是 oh-my-pi仓库代号 oh-my-picoding-agent 为只读顾问advisor量身定制的提示注入块它把用户常驻的项目指令文件AGENTS.md、CLAUDE.md 等以与主 agent 完全对称的方式注入顾问的系统提示让顾问在审查时能够拿着用户的“项目宪法”去约束驱动 agent而不是因为看不到约定而提出违背项目的建议。本文将以 context-files.md 模板为核心结合其渲染入口、能力发现管线与主 agent 侧的对称实现完整还原这条“项目上下文 → 顾问系统提示”的链路帮助开发者理解如何利用它构建遵守项目规范的审查型子代理。模板本体一份只有 8 行的约束声明关联文档 context-files.md 是一份 Handlebars 模板全文如下project-context Context files: users standing project instructions (AGENTS.md etc.); binding on driving agent. Enforce; flag drift immediately; NEVER advise against mandates. {{#each contextFiles}} file path{{path}} {{content}} /file {{/each}} /project-context逐行拆解这份模板可以看到它承载了三个层次的语义语义声明行开头一句话定义了这批内容的性质与效力——Context files: users standing project instructions (AGENTS.md etc.)用户常驻项目指令binding on driving agent对驱动 agent 具有约束力随后是三条行为准则Enforce强制执行、flag drift immediately发现偏离立即上报、NEVER advise against mandates绝不建议违背项目强制要求。这行文字先于文件内容出现确保模型在阅读任何文件正文之前就建立起“这些指令是约束、不是参考”的认知框架。{{#each contextFiles}}循环遍历调用方传入的contextFiles数组每个条目渲染为file path{{path}}与{{content}}包裹的块。path给出文件绝对路径让模型知道约定出自哪个文件content则是文件的原始正文。project-context外层包裹与主 agent 侧的repo-rules见下文相呼应为 LLM 提供清晰的 XML 式段落边界避免与提示中的其他指令块混淆。需要强调的是模板本身不负责“找文件”——发现与加载由运行时完成详见后文模板只负责把已经解析好的{path, content}列表渲染成提示文本。渲染入口formatAdvisorContextPrompt 的调用契约模板的唯一渲染入口位于 packages/coding-agent/src/advisor/watchdog.tsexport function formatAdvisorContextPrompt( contextFiles: ReadonlyArray{ path: string; content: string }, ): string | undefined { if (contextFiles.length 0) return undefined; return prompt.render(contextFilesTemplate, { contextFiles }).trim() || undefined; }函数注释点明了设计意图把项目上下文文件AGENTS.md 等渲染成一个块注入顾问advisor的系统提示镜像主 agent 接收它们的方式mirroring how the primary agent receives them。其核心价值在于让只读审查者拿到用户的常驻项目指令从而能够“要求驱动 agent 遵守它们”而不是“因为看不到项目约定而给出违背约定的建议”。几个值得注意的实现细节空数组返回undefined没有上下文文件时不渲染块避免向提示中注入空的占位段落.trim() || undefined模板渲染结果即使非空但全为空白也会被规约为undefined统一的prompt.render与同文件中的formatActiveRepoWatchdogPrompt、formatAdvisorMemoryPrompt使用同一渲染设施三者共同构成顾问系统提示的“记忆/上下文/监视”三件套。同文件的discoverWatchdogFileswatchdog.ts展示了同类发现机制的对照它会沿 cwd 向上、项目.omp目录与用户 agent 目录搜索WATCHDOG.md并对内容做import展开后包装成attention块。也就是说项目常驻约束在顾问侧至少有两个注入通道——project-contextAGENTS.md 等与attentionWATCHDOG.md。发现管线上下文文件如何被找到并装载模板中的数据来自主 agent 同一条发现管线。核心实现是 system-prompt.ts 中的loadProjectContextFilesexport async function loadProjectContextFiles( options: LoadContextFilesOptions {}, ): PromiseArray{ path: string; content: string; depth?: number } { const resolvedCwd options.cwd ?? getProjectDir(); const result await loadCapability(contextFileCapability.id, { cwd: resolvedCwd, disabledExtensions: options.disabledExtensions, }); const files await Promise.all( result.items.map(async item { const contextFile item as ContextFile; return { path: contextFile.path, content: await expandAtImports(contextFile.content, contextFile.path), depth: contextFile.depth, }; }), ); files.sort((a, b) { /* depth 降序离 cwd 越近越靠后越突出 */ }); return dedupeContainedContextFiles(files); }这条管线包含四个关键步骤能力发现capability通过loadCapability(contextFileCapability.id, ...)调用名为context-files的能力。能力定义在 packages/coding-agent/src/capability/context-file.tsContextFile携带path、content、level: user | project、depth与 cwd 的距离0 表示就在 cwd 中等元数据。能力按“作用域”去重——key为user或project:depth即用户级至多一个文件、每个项目目录深度至多一个文件同一深度内更高优先级的 provider 会遮蔽低优先级者这正支撑了 monorepo 中多个祖先层级都存在AGENTS.md的场景。validate确保条目至少具备 path、content 与合法 level。import展开expandAtImports定义于 packages/coding-agent/src/discovery/at-imports.ts把文件内容中的path/to/file引用就地展开且以文件自身所在目录为解析基准——与 Claude Code、Goose 等工具对相对导入的约定保持一致保证从仓库任意深度引用的路径都能正确解析。深度排序按depth降序排列离 cwd 越远越高层的祖先目录越靠前离 cwd 越近越具体、越权威的文件越靠后、越突出避免 LLM 被高层泛化规则占据注意力。段落包含去重dedupeContainedContextFilessystem-prompt.ts做的是精确的段落序列包含检测——只有当一个更权威更靠近 cwd的文件把另一个文件的规范化段落序列作为连续片段完整包含时后者才被剔除仅仅措辞相近或段落交错不会被误删。这保证了 monorepo 中“子目录 AGENTS.md 复制了根目录内容”这种常见冗余能被安全折叠。buildSystemPrompt还提供了contextFiles参数system-prompt.ts支持调用方预加载上下文文件从而跳过发现阶段方便宿主在启动时就并行拉取文件源码中通过withDeadline对contextFilesPromise设置了超时保护避免发现过程拖垮提示构建。主 agent 侧的对称实现 块顾问侧的project-context并非孤立设计它与主 agent 系统提示中的repo-rules块严格对称。见 packages/coding-agent/src/prompts/system/project-prompt.md{{#if contextFiles.length}} repo-rules MUST follow these context files for all tasks: {{#each contextFiles}} file path{{path}} {{content}} /file {{/each}} /repo-rules {{/if}}两份模板共用同一份contextFiles数据同样含file path包裹与{{content}}但语气强度不同维度主 agentproject-prompt.md顾问context-files.md段落标签repo-rulesproject-context约束语气MUST follow these context files for all tasksbinding on driving agent行为要求无条件遵守Enforce; flag drift immediately; NEVER advise against mandates角色执行者直接吸收规则审查者持规则监督执行者主 agent 侧还附带一条防噪音指令project-prompt.md上下文文件已自动加载永远不要再grep/glob去搜AGENTS.md、CLAUDE.md、.cursorrules等文件——相关文件已在上下文中其他都是噪音。这保证了“指令注入”与“工具搜索”两条路径不会互相干扰。“NEVER advise against mandates”的语义与工程价值模板中最具设计分量的一句话是NEVER advise against mandates。结合 advisor/watchdog.ts 的注释可以还原其意图顾问是只读审查者它的职责是审计驱动 agent 的工作是否偏离用户的项目约定如果顾问看不到这些约定它就只能凭通用常识提建议极可能给出与项目强制要求相悖的意见例如项目规定禁止使用某个依赖顾问却建议引入。注入project-context后顾问获得了与驱动 agent 同等的“规则视野”于是Enforce把 AGENTS.md 等视为约束性条款而非背景知识flag drift immediately一旦发现驱动 agent 的行为与约定背离立即上报而不是等会话结束再总结NEVER advise against mandates即使顾问认为某个项目强制要求不合理也绝不能建议违背——这是审查者与执行者之间“同一条宪法”的体现避免两层 agent 出现指令冲突。这一语义与顾问配置体系packages/coding-agent/src/advisor/config.ts 中discoverAdvisorConfigs从WATCHDOG.yml/WATCHDOG.yaml读取顾问定义共同构成了 oh-my-pi 的“带约束的审查制”用户通过 AGENTS.md 表达项目意志顾问通过project-context获得意志驱动 agent 通过repo-rules受意志约束三方共享同一份数据源保证一致性。实战建议结合源码可以给出三条落地建议AGENTS.md 是顾问可见的“硬约束”由于 context-files 能力默认发现AGENTS.md、CLAUDE.md、GEMINI.md等系统指令文件见 context-file.ts 的文件头注释且顾问与主 agent 共享同一发现管线因此写入 AGENTS.md 的强制规范如目录结构约定、禁止使用的 API、提交信息格式会同时约束驱动 agent 与顾问审查。想被顾问强制执行的规则就放进 AGENTS.md而不是散落在聊天里。monorepo 分层规则会被自动去重子目录的AGENTS.md若只是逐段复制了根目录内容加载时会被dedupeContainedContextFiles折叠只有新增/改写的段落才会保留并叠加。因此各层文件应写“增量差异”而非整份复制。利用import复用片段expandAtImports支持以文件所在目录为基准的path/to/file导入可以把跨目录共享的规范拆成独立片段统一引用减少重复维护该机制同时被 WATCHDOG 与顾问 instructions 使用是仓库级提示工程的标准手法。总而言之context-files.md虽仅 8 行却是 oh-my-pi 审查体系与执行体系之间“规则一致性”的枢纽它以模板形式固化了项目上下文的注入协议以binding语义赋予其约束力并通过 capability 发现、import展开、深度排序与段落去重等运行时管线把散落在仓库各层的 AGENTS.md 汇总成顾问与驱动 agent 共同遵循的“项目宪法”。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考