尧图网站建设 
人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载本篇技术指南以 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.tsloadProjectContextFiles()L75-L112负责收集所有指令文件并在reload()L322 起时与扩展、技能、提示模板、系统提示词一并装配最终通过getAgentsFiles()L276-L278对外暴露给上层系统提示词组装逻辑。二、AGENTS.md或 CLAUDE.md自动发现的项目指令2.1 搜索顺序Pi 在启动时按以下顺序查找AGENTS.md或CLAUDE.md~/.gsd/agent/AGENTS.md全局用户级从当前工作目录cwd开始逐级向上直到文件系统根目录的每一个父目录当前目录所有匹配到的文件都会被拼接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.mdAGENTS.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 建议写入的内容文档明确推荐用这些文件承载三类信息内容类型示例项目约定conventions命名规范、目录结构约定、代码风格常用命令common commands构建命令、测试命令、代码检查命令、部署命令架构笔记architectural notes模块边界、数据流、关键设计决策、本仓库不得修改的区域当前仓库本身就是很好的示范——根目录的 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-L465const 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的实际优先级是当前项目下的.gsd/SYSTEM.md或.gsd/APPEND_SYSTEM.md用户全局~/.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 Whats in this image? # 同时引用多个代码文件做评审 pi code.ts test.ts Review these files其中-p是显式声明这是图片/多模态输入的标志用于需要视觉模型参与的场景。4.2 适用场景场景命令示例说明直接评审代码pi src/main.ts Review this无需先复制粘贴源码带上下文提问pi context.md Answer this把背景资料文件作为 prompt 前缀截图/图片分析pi -p screenshot.png Whats in this image?视觉输入多文件交叉分析pi code.ts test.ts Review these files一次注入多个文件这与 GSD 的spec-driven development / context engineering定位一脉相承上下文不再依赖即时粘贴而是可复用的文件资产。五、三套上下文注入机制对比机制文件作用范围注入方式典型用途指令文件AGENTS.md/CLAUDE.md全局 各级父目录 cwd自动、拼接concatenated项目约定、常用命令、架构笔记系统提示词覆盖.gsd/SYSTEM.md、~/.gsd/agent/SYSTEM.md项目 / 全局整体替换默认提示词深度定制 Agent 行为系统提示词追加.gsd/APPEND_SYSTEM.md、~/.gsd/agent/APPEND_SYSTEM.md项目 / 全局末尾追加增量补充约束不丢弃默认行为CLI 文件参数任意文件单次会话显式内联注入代码评审、图片分析、临时上下文六、最佳实践与注意事项分层放置避免重复全局约定放~/.gsd/agent/AGENTS.md仓库级约定放仓库根目录子模块专属约定放子目录——利用从根到 cwd 自动拼接的特性让上层文件管通用约束、下层文件管局部细节。文件保持精简指令文件会被注入到每次会话的系统提示词内容越多 token 开销越大。只放每句话都需要知道的稳定信息。同目录二选一AGENTS.md优先于CLAUDE.md同目录不要同时维护两份避免内容分叉。SYSTEM.md 是替换语义使用前确认你确实想放弃内置默认系统提示词只想加约束时优先用APPEND_SYSTEM.md。利用扩展点agentsFilesOverride、systemPromptOverride、appendSystemPromptOverride是资源加载器对外提供的改写钩子resource-loader.ts扩展作者可通过它们对指令注入做程序化控制。CI / 最小上下文场景使用--bare跳过CLAUDE.md/AGENTS.md、用户设置与用户技能参考 help-text.ts 与gsd headless --bare autoL158。七、小结GSD 的上下文文件体系是一套静态文件即上下文的工程化方案AGENTS.md/CLAUDE.md负责自动化的项目指令拼接SYSTEM.md/APPEND_SYSTEM.md负责系统提示词的整体替换或追加CLI 的file语法负责单次会话的显式注入。三者组合起来正是该项目让 Agent 长时间自治运行而不丢失大局观的核心支撑之一——把项目的灵魂写进文件让每次会话都从同一份事实出发。赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐Python SDK 中的 Context 注入为 MCP 工具、资源与提示词注入请求上下文Python SDK 中的 Context 注入为 MCP 工具、资源与提示词注入请求上下文 在基于 python sdk https://link.gitc人工智能MCP 服务MCP Clientsnanobot SOUL.md 人格引导文件解析从 legacy 模板到系统提示词注入原理nanobot SOUL.md 人格引导文件解析从 legacy 模板到系统提示词注入原理 SOUL.md 是 nanobot 个人 AI 助手框架中用于定义人工智能AI AgentAgent 框架多智能体工具调用MCP Clients交互助手后端任务调度Apache APISIX ai-prompt-decorator 插件在 AI 网关统一注入系统提示词与上下文装饰Apache APISIX ai prompt decorator 插件在 AI 网关统一注入系统提示词与上下文装饰 ai prompt decoratorAPI网关后端云原生微服务上一篇GTA5线上小助手终极免费开源工具集一站式游戏增强解决方案下一篇3分钟掌握TranslucentTB让Windows任务栏透明化的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 深入理解 GSD 项目上下文文件（Context Files）：从 AGENTS.md 到系统提示词注入与 CLI 文件参数
人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载本篇技术指南以 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.tsloadProjectContextFiles()L75-L112负责收集所有指令文件并在reload()L322 起时与扩展、技能、提示模板、系统提示词一并装配最终通过getAgentsFiles()L276-L278对外暴露给上层系统提示词组装逻辑。二、AGENTS.md或 CLAUDE.md自动发现的项目指令2.1 搜索顺序Pi 在启动时按以下顺序查找AGENTS.md或CLAUDE.md~/.gsd/agent/AGENTS.md全局用户级从当前工作目录cwd开始逐级向上直到文件系统根目录的每一个父目录当前目录所有匹配到的文件都会被拼接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.mdAGENTS.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 建议写入的内容文档明确推荐用这些文件承载三类信息内容类型示例项目约定conventions命名规范、目录结构约定、代码风格常用命令common commands构建命令、测试命令、代码检查命令、部署命令架构笔记architectural notes模块边界、数据流、关键设计决策、本仓库不得修改的区域当前仓库本身就是很好的示范——根目录的 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-L465const 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的实际优先级是当前项目下的.gsd/SYSTEM.md或.gsd/APPEND_SYSTEM.md用户全局~/.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 Whats in this image? # 同时引用多个代码文件做评审 pi code.ts test.ts Review these files其中-p是显式声明这是图片/多模态输入的标志用于需要视觉模型参与的场景。4.2 适用场景场景命令示例说明直接评审代码pi src/main.ts Review this无需先复制粘贴源码带上下文提问pi context.md Answer this把背景资料文件作为 prompt 前缀截图/图片分析pi -p screenshot.png Whats in this image?视觉输入多文件交叉分析pi code.ts test.ts Review these files一次注入多个文件这与 GSD 的spec-driven development / context engineering定位一脉相承上下文不再依赖即时粘贴而是可复用的文件资产。五、三套上下文注入机制对比机制文件作用范围注入方式典型用途指令文件AGENTS.md/CLAUDE.md全局 各级父目录 cwd自动、拼接concatenated项目约定、常用命令、架构笔记系统提示词覆盖.gsd/SYSTEM.md、~/.gsd/agent/SYSTEM.md项目 / 全局整体替换默认提示词深度定制 Agent 行为系统提示词追加.gsd/APPEND_SYSTEM.md、~/.gsd/agent/APPEND_SYSTEM.md项目 / 全局末尾追加增量补充约束不丢弃默认行为CLI 文件参数任意文件单次会话显式内联注入代码评审、图片分析、临时上下文六、最佳实践与注意事项分层放置避免重复全局约定放~/.gsd/agent/AGENTS.md仓库级约定放仓库根目录子模块专属约定放子目录——利用从根到 cwd 自动拼接的特性让上层文件管通用约束、下层文件管局部细节。文件保持精简指令文件会被注入到每次会话的系统提示词内容越多 token 开销越大。只放每句话都需要知道的稳定信息。同目录二选一AGENTS.md优先于CLAUDE.md同目录不要同时维护两份避免内容分叉。SYSTEM.md 是替换语义使用前确认你确实想放弃内置默认系统提示词只想加约束时优先用APPEND_SYSTEM.md。利用扩展点agentsFilesOverride、systemPromptOverride、appendSystemPromptOverride是资源加载器对外提供的改写钩子resource-loader.ts扩展作者可通过它们对指令注入做程序化控制。CI / 最小上下文场景使用--bare跳过CLAUDE.md/AGENTS.md、用户设置与用户技能参考 help-text.ts 与gsd headless --bare autoL158。七、小结GSD 的上下文文件体系是一套静态文件即上下文的工程化方案AGENTS.md/CLAUDE.md负责自动化的项目指令拼接SYSTEM.md/APPEND_SYSTEM.md负责系统提示词的整体替换或追加CLI 的file语法负责单次会话的显式注入。三者组合起来正是该项目让 Agent 长时间自治运行而不丢失大局观的核心支撑之一——把项目的灵魂写进文件让每次会话都从同一份事实出发。赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐Python SDK 中的 Context 注入为 MCP 工具、资源与提示词注入请求上下文Python SDK 中的 Context 注入为 MCP 工具、资源与提示词注入请求上下文 在基于 python sdk https://link.gitc人工智能MCP 服务MCP Clientsnanobot SOUL.md 人格引导文件解析从 legacy 模板到系统提示词注入原理nanobot SOUL.md 人格引导文件解析从 legacy 模板到系统提示词注入原理 SOUL.md 是 nanobot 个人 AI 助手框架中用于定义人工智能AI AgentAgent 框架多智能体工具调用MCP Clients交互助手后端任务调度Apache APISIX ai-prompt-decorator 插件在 AI 网关统一注入系统提示词与上下文装饰Apache APISIX ai prompt decorator 插件在 AI 网关统一注入系统提示词与上下文装饰 ai prompt decoratorAPI网关后端云原生微服务上一篇GTA5线上小助手终极免费开源工具集一站式游戏增强解决方案下一篇3分钟掌握TranslucentTB让Windows任务栏透明化的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考