企业官网建设流程全解析

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用

本篇技术指南以 GSD 项目（docs/dev/what-is-pi/13-context-files-project-instructions.md）为骨架，系统讲解 Pi/GSD 如何在启动时自动加载指令文件（AGENTS.md / CLAUDE.md、SYSTEM.md / APPEND_SYSTEM.md），以及如何通过 CLI 文件参数（@ 语法）将任意文件直接注入 prompt。读完你将从"靠聊天记录喂上下文"升级为"用工程化文件体系治理上下文"，并掌握与源码实现对应的完整配置方法与运行机制。

一、为什么需要"上下文文件"：把项目约定变成系统提示词

在长时间自治运行（long-running autonomous operation）的 Agent 工作流中，最大的风险是"丢失大局观"：模型上下文窗口有限、会话会被压缩（compaction）、新会话会丢失旧记忆。GSD 的解法非常朴素而强大——把项目约定、常用命令、架构笔记写进固定的指令文件，让 Pi 在每次启动时自动把这些文件拼接进系统提示词（system prompt）。

这意味着：

• 约定不会随会话消亡，每次启动都会重新注入；
• 约定是纯文本文件，天然可版本控制、可评审、可跨团队复用；
• 项目级约定与用户级约定可以分层叠加，实现"全局默认 + 项目覆盖"。

从源码看，这一机制由资源加载器统一实现。核心实现位于 packages/pi-coding-agent/src/core/resource-loader.ts：loadProjectContextFiles()（L75-L112）负责收集所有指令文件，并在reload()（L322 起）时与扩展、技能、提示模板、系统提示词一并装配，最终通过getAgentsFiles()（L276-L278）对外暴露给上层系统提示词组装逻辑。

二、AGENTS.md（或 CLAUDE.md）：自动发现的项目指令

2.1 搜索顺序

Pi 在启动时按以下顺序查找AGENTS.md或CLAUDE.md：

1. ~/.gsd/agent/AGENTS.md（全局用户级）
2. 从当前工作目录（cwd）开始，逐级向上直到文件系统根目录的每一个父目录
3. 当前目录

所有匹配到的文件都会被拼接（concatenated）并纳入系统提示词。因此，你可以同时拥有：

• 一个全局指令文件（比如通用的代码风格、通用工作流偏好）；
• 多个层级目录指令文件（比如~/projects/foo/AGENTS.md与~/projects/foo/packages/bar/AGENTS.md）；
• 它们按"从根到 cwd"的顺序合并，形成完整的上下文栈。

2.2 源码级验证

resource-loader.ts中loadContextFileFromDir()（L57-L73）实现了核心查找逻辑：

const candidates = ["AGENTS.md", "CLAUDE.md"]; for (const filename of candidates) { const filePath = join(dir, filename); if (existsSync(filePath)) { return { path: filePath, content: readFileSync(filePath, "utf-8") }; } }

注意：每个目录只取第一个命中的候选文件。也就是说，如果同一个目录里同时存在AGENTS.md和CLAUDE.md，AGENTS.md优先级更高，CLAUDE.md会被忽略。

而loadProjectContextFiles()（L75-L112）则精确复刻了文档中的三段式搜索：

const globalContext = loadContextFileFromDir(resolvedAgentDir); // ① ~/.gsd/agent ... let currentDir = resolvedCwd; const root = resolve("/"); while (true) { const contextFile = loadContextFileFromDir(currentDir); // ② 当前目录 ... currentDir = parentDir; // ③ 逐级向上到 / }

其中resolvedAgentDir来自getAgentDir()，即文档中的~/.gsd/agent。循环从 cwd 一路向上直到文件系统根目录，用seenPaths去重（同一路径不会重复注入），并用ancestorContextFiles.unshift(...)保证拼接顺序为"从根目录到当前目录"，最后把全局文件放在最前面。

2.3 建议写入的内容

文档明确推荐用这些文件承载三类信息：

当前仓库本身就是很好的示范——根目录的 CONTEXT.md、VISION.md 以及 CONTRIBUTING.md 正是这类"项目级上下文"的实践形态。对于 Agent 而言，把这些信息固化到AGENTS.md后，每次会话都不需要人类重新解释项目背景。

2.4 --bare 开关：何时跳过指令文件

部分场景（CI、生态工具自检、无头模式）希望以最精简的上下文运行。CLI 提供了--bare标志：在 src/help-text.ts 中可以看到其定义为--bare Minimal context: skip CLAUDE.md, AGENTS.md, user settings, user skills，并在 L158 给出了gsd headless --bare auto的用法示例（面向 CI / 生态使用）。

同时，resource-loader.ts的DefaultResourceLoaderOptions支持agentsFilesOverride回调（L152-L154），允许上层在加载后对agentsFiles做过滤或重排——这也是扩展系统干预指令注入的官方扩展点。

三、系统提示词覆盖与追加：SYSTEM.md 与 APPEND_SYSTEM.md

除了拼接式的指令文件，GSD 还提供了两对文件，用于整体替换或追加默认系统提示词：

3.1 SYSTEM.md：整体替换默认系统提示词

• .gsd/SYSTEM.md（项目级）
• ~/.gsd/agent/SYSTEM.md（全局用户级）

只要存在其中任一文件，其内容就会完全取代内置的默认系统提示词。适合深度定制 Agent 人格/行为边界的场景（例如给 Pi 定制一套专属的行为准则或领域专家设定）。

3.2 APPEND_SYSTEM.md：在默认提示词之后追加

• .gsd/APPEND_SYSTEM.md（项目级）
• ~/.gsd/agent/APPEND_SYSTEM.md（全局用户级）

与替换相反，追加文件保留内置默认系统提示词，仅在其末尾追加你的内容。适合增量式微调：既不想放弃内置行为，又想补充项目专属约束。

3.3 源码实现：搜索路径与优先级

在resource-loader.ts的reload()中（L454-L465）：

const baseSystemPrompt = resolvePromptInput( this.systemPromptSource ?? this.discoverFileInSearchPaths("SYSTEM.md"), "system prompt", ); ... const appendSource = this.appendSystemPromptSource ?? this.discoverFileInSearchPaths("APPEND_SYSTEM.md"); const resolvedAppend = resolvePromptInput(appendSource, "append system prompt"); const baseAppend = resolvedAppend ? [resolvedAppend] : [];

其中discoverFileInSearchPaths()（L765-L774）定义了搜索目录顺序：

const searchDirs = [join(this.cwd, CONFIG_DIR_NAME), this.agentDir]; for (const dir of searchDirs) { const filePath = join(dir, filename); if (existsSync(filePath)) return filePath; } return undefined;

CONFIG_DIR_NAME即.gsd。因此SYSTEM.md/APPEND_SYSTEM.md的实际优先级是：

1. 当前项目下的.gsd/SYSTEM.md（或.gsd/APPEND_SYSTEM.md）
2. 用户全局~/.gsd/agent/SYSTEM.md（或APPEND_SYSTEM.md）

项目级优先于全局级，这符合"全局默认 + 项目覆盖"的通用分层思路。

resolvePromptInput()（L40-L55）还有一个值得注意的细节：如果传入的路径存在则读取文件内容，若读取失败则回退为把原始路径字符串当作提示词使用（并打印黄色警告），保证容错性。

此外，DefaultResourceLoaderOptions还提供了systemPrompt/appendSystemPrompt直接注入参数，以及systemPromptOverride/appendSystemPromptOverride两个钩子（L155-L156），供宿主程序或扩展在运行期改写最终系统提示词。

四、CLI 文件参数：用 @ 语法直接把文件注入 prompt

第三类上下文注入方式是命令行文件参数：在 prompt 中直接引用本地文件，让文件内容以"内联资源"形式进入模型上下文。

4.1 基础用法

# 把 prompt.md 的内容作为提问背景 pi @prompt.md "Answer this" # 把截图作为图片输入（视觉模型场景） pi -p @screenshot.png "What's in this image?" # 同时引用多个代码文件做评审 pi @code.ts @test.ts "Review these files"

其中-p是显式声明"这是图片/多模态输入"的标志，用于需要视觉模型参与的场景。

4.2 适用场景

这与 GSD 的"spec-driven development / context engineering"定位一脉相承：上下文不再依赖即时粘贴，而是可复用的文件资产。

五、三套上下文注入机制对比

六、最佳实践与注意事项

1. 分层放置，避免重复：全局约定放~/.gsd/agent/AGENTS.md，仓库级约定放仓库根目录，子模块专属约定放子目录——利用"从根到 cwd 自动拼接"的特性，让上层文件管通用约束、下层文件管局部细节。
2. 文件保持精简：指令文件会被注入到每次会话的系统提示词，内容越多 token 开销越大。只放"每句话都需要知道"的稳定信息。
3. 同目录二选一：AGENTS.md优先于CLAUDE.md，同目录不要同时维护两份，避免内容分叉。
4. SYSTEM.md 是替换语义：使用前确认你确实想放弃内置默认系统提示词；只想加约束时优先用APPEND_SYSTEM.md。
5. 利用扩展点：agentsFilesOverride、systemPromptOverride、appendSystemPromptOverride是资源加载器对外提供的改写钩子（resource-loader.ts），扩展作者可通过它们对指令注入做程序化控制。
6. CI / 最小上下文场景使用--bare：跳过CLAUDE.md/AGENTS.md、用户设置与用户技能，参考 help-text.ts 与gsd headless --bare auto（L158）。

七、小结

GSD 的上下文文件体系是一套"静态文件即上下文"的工程化方案：AGENTS.md/CLAUDE.md负责自动化的项目指令拼接，SYSTEM.md/APPEND_SYSTEM.md负责系统提示词的整体替换或追加，CLI 的@file语法负责单次会话的显式注入。三者组合起来，正是该项目"让 Agent 长时间自治运行而不丢失大局观"的核心支撑之一——把项目的灵魂写进文件，让每次会话都从同一份事实出发。

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用