[Feature] 受控采纳仓库内 AGENTS.md 等 Agent 指令：只读基线分支版本、按目录分层合并注入，默认仍屏蔽
维护者通常 1 天内回复
还没有人认领这个 Issue。
评估
调研方向
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.
由索引模型根据 Issue 内容生成。
描述
背景与借鉴来源
仓库内放一份写给 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，还有带applyToglob 的.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 偷偷接入外部工具。但现在只有「全部屏蔽」一档，没有「受控采纳」。结果是：
- 目标仓库已经维护好的
AGENTS.md（构建、测试、lint、目录约定）Agent 一行都看不到，只能在 LoopForge 里把同样内容再抄一份 Rule（domain.Agent.Rules），两边很快就不一致； - monorepo 里各子目录的
AGENTS.md（按路径分层的约定）在平台 Rule 里没法表达； - 用户不知道这些文件被屏蔽了，Run 详情里也看不到，排查「Agent 为什么不按仓库规范来」很难。
建议方案
保持默认屏蔽、平台定义优先不变，新增按仓库开关的「受信仓库指令」采纳：
- 配置：仓库（或项目）级新增
repo_instructions设置：off（默认，就是现状）/trusted_base。只允许采纳纯文本指令文件：AGENTS.md、AGENTS.override.md、CLAUDE.md、CODEBUDDY.md。.mcp.json、.claude/、.codex/、.codebuddy/等可执行/可接工具的配置继续一律屏蔽，不在这次范围内。 - 只信基线分支：采纳的内容从基线分支（受保护分支）的指定 commit 用
git show <base_sha>:<path>读出，不读工作区里当前分支的版本。这样 Agent 自己改的、或外部 PR 分支里改的指令文件都不会生效，防住指令注入。工作区里这些文件照样遮蔽，现有沙箱逻辑不变。 - 分层合并：按 Codex 的规则，从仓库根到节点工作目录（或本次改动涉及的目录）逐级收集，越近的放越后面（优先级越高）；
AGENTS.override.md替换同级的AGENTS.md。总大小设上限（默认 32 KiB，可配置），超出的截断并记一条告警。 - 注入与优先级：作为一条只读的「仓库指令」Rule，附在 Agent 定义 Rules 之后、注入执行器提示词；提示里写明「与平台规则冲突时以平台规则为准」。复用现有 Rule 注入通道，执行器适配层不用改。
- 可审计：Run/节点详情显示这次采纳了哪些文件（路径、基线 commit、字节数、是否截断）；
observability事件里加一条repo_instructions.applied。 - 预览：仓库设置页提供「预览合并结果」，按选定的基线分支和目录，展示最终会注入的文本。
验收标准
- 默认（
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 三种驱动都验证通过。
- 主要语言
- Go
- 星标
- 141
- 派生
- 28
- 平均合并
- 1 天 15 小时
- 30 天内合并 PR
- 113
环境准备
- 提供 Dockerfile 或 Docker Compose 文件
- 有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
Tencent/LoopForge 的其他 Issue
-
难度 2/5 1-3 小时 新手友好度 74/100
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 75/100
维护者通常 1 天内回复
-
[Bug]: 官方镜像未安装 wecom-cli，企业微信通知报「通知服务未安装 wecom-cli」可能已有人在做 @newexploreor 于 1 天前认领。 未关闭bug
难度 2/5 1-3 小时 新手友好度 76/100
Tencent/LoopForge#156 · 1 条评论 · 已指派 1 人 ·
维护者通常 1 天内回复
-
【架构优化】合并 gitwork/workbranch.go 中 push/pull 重复的默认提交身份注入为 withFallbackIdentity可能已有人在做 @fx-kurumi 今天认领。 未关闭
难度 2/5 1-3 小时 新手友好度 40/100
维护者通常 1 天内回复
-
【架构优化】从 runtime.installNPMCLI 中拆出 npm 参数拼装 npmCLIInstallArgs 与安装结果启用 activateNPMStage可能已有人在做 @fx-kurumi 今天认领。 未关闭
难度 2/5 1-3 小时 新手友好度 30/100
维护者通常 1 天内回复
查看 Tencent/LoopForge 的全部 Issue
相似的 Issue
-
team:library-maintainers
难度 2/5 1-3 小时 新手友好度 82/100
padok-team/burrito#1208 · 1 条评论 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 62/100
bazel-contrib/rules_go#4784 · 1 条评论 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 75/100
-
难度 2/5 1-3 小时 新手友好度 62/100
POSIdev-community/aictl#40 ·
-
难度 1/5 1 小时以内 新手友好度 62/100
prime-radiant-inc/evener#6306 ·
维护者通常 1 天内回复