系列回顾主循环 · 代码库工具 · REPL 会话Agent 会转、会逛仓库、能开着聊了——但模型仍然不认识你的项目规矩。你在AGENTS.md里写了「issue 用某套标签」「提交用 Conventional Commits」它下一轮照样按通用习惯答。这篇讲项目上下文project context启动时发现 Markdown → 当成system prompt注入每次callModel。Skills / MCP 以后都要走这条「把外部知识塞进会话」的通道先把底座打通。缺的不是工具是「说明书」对话历史messages[]记的是这一次聊了什么。项目约定记的是这个仓库平时怎么干活——和某次用户输入无关也不该被/clear清掉。东西放哪/clear后用户问「我叫 Alice」messages没了「PR 标题用中文」写在 AGENTS.mdsystem prompt还在没有这条通道时你只能每轮手动把规矩贴进用户消息烦、费 token或者指望模型「自己去 Read AGENTS.md」不可靠且浪费一轮工具所以 v2 加的是启动加载一次每轮透传不进对话历史。一张图看清注入路径cwd 向上找 AGENTS.md / CLAUDE.md ↓ loadProjectContext() → string | undefined ↓ CLI / QueryEngine构造时拿住 ↓ query({ systemPrompt }) ↓ callModel({ systemPrompt }) ↓ adaptermessages 首位插入 { role: system, content }要点发现在 L1/入口透传穿过 L2真正变成 API 字段在 Provider 适配层。工具流水线、权限策略都不动。发现规则简单到能背下来实现集中在src/utils/projectContext.ts从cwd开始向上最多5层或碰到git root就停某一层若有文件只有AGENTS.md→ 用它只有CLAUDE.md→ 用它两个都有→ 合并AGENTS在前 分隔线 CLAUDE找到第一层有文件的目录就返回不整棵树全合并合并后超过64KB→ 截断末尾注明[project context truncated at 64KB]什么都没有→ 返回undefined静默跳过进程不挂exportasyncfunctionloadProjectContext(startCwdprocess.cwd(),):Promisestring|undefined兼容两套生态惯例本仓库用AGENTS.mdClaude 系常用CLAUDE.md——同目录就一起喂给模型。为什么不塞进messages[]设计上刻意选了systemPrompt?: string而不是messages.unshift(systemUserMsg)做法问题当第一条 user / assistant污染会话语义/clear容易误清或难清独立 systemPrompt历史只管对话system 由引擎持有每轮透传QueryEngineconstructor({…,systemPrompt?})// runTurn → query({ …, systemPrompt: this.#systemPrompt })// clear() 只清空 messages不动 systemPromptREPL 里/clear之后项目规矩仍然生效——这是验收场景里特意写明的行为。adapter 侧一行就够if(systemPrompt){result.push({role:system,content:systemPrompt})}内部循环继续只认 Anthropic 形态的 user/assistantsystem 是出站时加上的和「内部协议 / 外部协议」分层一致。CLI 三种模式一起接线启动时加载一次三种路径共用constsystemPromptawaitloadProjectContext()// pipe / headlessquery({messages,tools,toolUseContext,systemPrompt})// REPLnewQueryEngine({tools,toolUseContext,systemPrompt})无文件时systemPrompt为undefined行为和加上下文之前完全一样——无破坏性变更。和前几篇怎么拼在一起篇章补的能力一句话主循环L2 会转模型 ↔ 工具直到停代码库工具L3 会逛Glob → Grep → ReadREPLL1 能聊messages跨 turn 累积本篇项目说明书AGENTS/CLAUDE → system每轮都在Harness「八大能力柱」里这对应Context的最小切片还不是 compact / git status / 日期拼盘只是「把仓库 Markdown 说明喂给模型」。但 Skills、MCP、更多上下文源都可以复用同一条systemPrompt或以后扩展成「上下文管道」。30 秒验证在仓库根目录放或已有AGENTS.md写一句可检验的规矩例如# 测试约定 回答时先说一句项目暗号是 pineapple。然后bun run dev --随便打个招呼# 或 REPLbun run dev模型回复里应能看出它读到了这份说明。再试 /clear 再打个招呼暗号约定应仍然在——因为清的是对话不是 system。没有AGENTS.md/CLAUDE.md时行为与旧版一致不会报错退出。刻意没做什么没做为什么整棵目录树多层 CLAUDE.md 全合并v2 只取「向上找到的第一层」Memory / git status / 日期完整 context 管道留后token budget / compact先用 64KB 硬顶把 Skills 本体做完依赖本 change 的注入通道见后续 v2-skills向上爬升的护栏最多 5 层或停在.git避免一路爬到用户家目录把无关说明书吃进来。你可以从这里带走什么项目约定 ≠ 对话历史一个走 system一个走messages/clear只清后者。注入通道比文件格式更重要先打通load → systemPrompt → adapter以后 Skills / MCP 才有地方挂。无文件时静默跳过可选增强不应变成启动失败。到这里react-agent-mini 最小故事又多了一块砖——Agent 不只会「动手」还会先读你的仓库说明书。仓库与相关文档GitHubhttps://github.com/jimchou-h/react-agent-mini主循环 · 代码库工具 · REPL架构导读docs/architecture.md欢迎 Star、Issue 和 PR。本文基于 react-agent-mini 变更v2-project-contextAGENTS.md / CLAUDE.md → system prompt撰写。
