[Feature] 受控采纳仓库内 AGENTS.md 等 Agent 指令：只读基线分支版本、按目录分层合并注入，默认仍屏蔽

Abierto
  • ¿Algo no está bien?
#341 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
8/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
docker, git, go
Área
backend, security

Línea de trabajo

Start with internal/runtime/sandbox_process.go (rootProjectAgentPaths, discoverProjectAgentPaths) and internal/runtime/git_isolation.go (UsesProjectAgentConfigIsolation) to see how agent instruction files are masked today. The proposal adds a trusted_base mode that reads AGENTS.md from a base commit with git show and merges it by directory; the masking in the Docker paths and internal/scriptview/scriptview.go must stay unchanged. Done means the default off behaviour is unchanged, the base-commit version is injected, and the workspace copy stays masked across seatbelt, bwrap and docker.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

背景与借鉴来源

仓库内放一份写给 Agent 的说明（构建/测试命令、目录约定、PR 规范），已经是主流 AI coding agent 的通用做法：

  • AGENTS.md 开放格式（https://github.com/agentsmd/agents.md，约 2.5 万 star）：定位是「写给 Agent 的 README」，Codex、Jules、Cursor、Copilot coding agent、Gemini CLI 等都支持。
  • openai/codex（https://github.com/openai/codex，约 13.5 万 star，2026-11-12 仍有提交）：自动从仓库根到 cwd 逐级合并 AGENTS.md，子目录离得越近优先级越高；AGENTS.override.md 可以覆盖；用 project_doc_max_bytes（默认 32 KiB）限制注入大小。
  • GitHub Copilot coding agent：读取 .github/copilot-instructions.md、AGENTS.md、CLAUDE.md，还有带 applyTo glob 的 .github/instructions/*.instructions.md（按改动路径选择性注入）。
  • OpenHands（https://github.com/OpenHands/OpenHands，约 9.3 万 star）的 .openhands/microagents/repo.md、cline/cline（约 7.2 万 star）的 .clinerules、anthropics/claude-code（约 15.5 万 star）的分层 CLAUDE.md、google-gemini/gemini-cli（约 10.9 万 star）的 GEMINI.md：做法都一样，仓库自带的规范跟着代码走、一起版本化。

这些项目的共同结论是：团队约定写在仓库里、和代码一起评审，比在平台上另外维护一份更不容易过期，也是 Agent 一次就跑对测试/lint 命令的主要依据。

LoopForge 现状与不足

LoopForge 在沙箱运行时无条件屏蔽仓库里的所有 Agent 指令文件：

  • internal/runtime/sandbox_process.go：rootProjectAgentPaths / projectAgentFileNames 列出了 AGENTS.md、AGENTS.override.md、CLAUDE.md、CLAUDE.local.md、CODEBUDDY.md、.agents/、.codex/、.claude/、.codebuddy/、.mcp.json。discoverProjectAgentPaths 会递归找出所有层级的这类文件，seatbelt/bwrap 沙箱用它做遮蔽；注释写的是「AgentFlow definitions are the only source of instructions」。
  • internal/runtime/sandbox_docker.go（dockerAgentConfigMasks）和 internal/runtime/sandbox_script_docker.go（currentAgentMasks）在 Docker 沙箱里同样把这些路径挂成遮蔽层。
  • internal/runtime/git_isolation.go：UsesProjectAgentConfigIsolation 对 seatbelt/bwrap/docker 一律返回 true，并把这些文件写进 git exclude、设 skip-worktree。
  • internal/scriptview/scriptview.go：ValidMask 只接受上面这些文件名作为遮蔽目标。

隔离的初衷是对的：防止仓库里的指令（尤其是 PR 分支里被改过的）劫持无人值守的 Run，也防止仓库里的 .mcp.json 偷偷接入外部工具。但现在只有「全部屏蔽」一档，没有「受控采纳」。结果是：

  1. 目标仓库已经维护好的 AGENTS.md（构建、测试、lint、目录约定）Agent 一行都看不到，只能在 LoopForge 里把同样内容再抄一份 Rule（domain.Agent.Rules），两边很快就不一致；
  2. monorepo 里各子目录的 AGENTS.md（按路径分层的约定）在平台 Rule 里没法表达；
  3. 用户不知道这些文件被屏蔽了，Run 详情里也看不到，排查「Agent 为什么不按仓库规范来」很难。

建议方案

保持默认屏蔽、平台定义优先不变，新增按仓库开关的「受信仓库指令」采纳：

  1. 配置：仓库（或项目）级新增 repo_instructions 设置：off（默认，就是现状）/ trusted_base。只允许采纳纯文本指令文件：AGENTS.md、AGENTS.override.md、CLAUDE.md、CODEBUDDY.md。.mcp.json、.claude/、.codex/、.codebuddy/ 等可执行/可接工具的配置继续一律屏蔽，不在这次范围内。
  2. 只信基线分支：采纳的内容从基线分支（受保护分支）的指定 commit 用 git show <base_sha>:<path> 读出，不读工作区里当前分支的版本。这样 Agent 自己改的、或外部 PR 分支里改的指令文件都不会生效，防住指令注入。工作区里这些文件照样遮蔽，现有沙箱逻辑不变。
  3. 分层合并：按 Codex 的规则，从仓库根到节点工作目录（或本次改动涉及的目录）逐级收集，越近的放越后面（优先级越高）；AGENTS.override.md 替换同级的 AGENTS.md。总大小设上限（默认 32 KiB，可配置），超出的截断并记一条告警。
  4. 注入与优先级：作为一条只读的「仓库指令」Rule，附在 Agent 定义 Rules 之后、注入执行器提示词；提示里写明「与平台规则冲突时以平台规则为准」。复用现有 Rule 注入通道，执行器适配层不用改。
  5. 可审计：Run/节点详情显示这次采纳了哪些文件（路径、基线 commit、字节数、是否截断）；observability 事件里加一条 repo_instructions.applied。
  6. 预览：仓库设置页提供「预览合并结果」，按选定的基线分支和目录，展示最终会注入的文本。

验收标准

  • 默认（off）行为与现状完全一致：现有遮蔽相关测试全部通过，所有驱动下指令文件仍不可见。
  • 开启 trusted_base 后，Agent 节点提示词里包含基线分支 AGENTS.md 的内容；工作区里该文件仍被遮蔽。
  • 指令注入防护：工作分支或 PR 分支修改了 AGENTS.md，注入的仍是基线 commit 的版本（有单测/集成测试覆盖）。
  • 嵌套目录 AGENTS.md 按「越近优先级越高」顺序合并，AGENTS.override.md 覆盖规则生效；超过大小上限时截断并告警。
  • .mcp.json、.claude/、.codex/、.codebuddy/ 在任何设置下都不会被采纳或暴露。
  • Run 详情能看到采纳的文件清单（路径 + commit + 大小）；仓库设置页可以预览合并结果。
  • seatbelt / bwrap / docker 三种驱动都验证通过。
Lenguaje dominante
Go
Estrellas
141
Forks
28
Merge medio
1 d 15 h
PR fusionados (30 d)
113

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de Tencent/LoopForge

Todos los issues de Tencent/LoopForge

Issues similares

Más issues de Go

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.