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

Ouverte
  • Quelque chose ne va pas ?
#341 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
8/100
Type d'issue
Fonctionnalité
Clarté
Plutôt claire
Activité
Active
Stack technique
docker, git, go
Domaine
backend, security

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

背景与借鉴来源

仓库内放一份写给 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 三种驱动都验证通过。
Langage dominant
Go
Étoiles
141
Forks
28
Merge moyen
1 j 15 h
PR mergées (30 j)
113

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de Tencent/LoopForge

Toutes les issues de Tencent/LoopForge

Issues similaires

Plus d'issues Go

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.