jcode 系统提示词配置指南用 Markdown 文件分层定制 Agent 行为无需重新构建【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcodejcode 的系统提示词system prompt并非一整段写死的字符串而是由七个按序组装的层叠片段拼接而成其中多个层完全由用户可编辑的 Markdown 文件驱动。本文基于官方文档 SYSTEM_PROMPT_CONFIG.md 逐层拆解这套机制你可以学会在不重新编译 jcode 的前提下用prompt-overlay.md追加指令、用system-prompt.md整体替换基础提示词、用preferred-tools.md引导工具选择并理解每层内容的加载优先级、生效时机以及它与 provider 缓存前缀static/dynamic 拆分之间的底层关系。一、系统提示词的七层装配顺序官方文档定义的层顺序如下后文源码实现与该顺序完全对应基础系统提示词Base system prompt— 内置于 crates/jcode-base/src/prompt/system_prompt.md可用文件覆盖见第三节能力模块Capability modules— 例如 Mermaid 渲染指引随功能开关条件注入自开发指引Self-dev guidance— 仅在 self-dev 会话jcode 修改自身代码库的会话中注入AGENTS.md— 项目级./AGENTS.md与全局~/AGENTS.md提示词叠加层Prompt overlay—./.jcode/prompt-overlay.md与~/.jcode/prompt-overlay.md首选工具指引Preferred tools—./.jcode/preferred-tools.md与~/.jcode/preferred-tools.md记忆与活动技能提示词Memory and active skill prompt— 动态内容不参与缓存。这一装配过程的核心实现在 crates/jcode-base/src/prompt.rs 的build_system_prompt_full_with_capabilities函数中它按「基础提示词 → self-dev 指引 → AGENTS.md → prompt overlay → preferred tools → memory → 可用技能列表 → 活动技能」的顺序向parts向量追加片段最后用\n\n连接成完整提示词同时返回一份ContextInfo结构记录每一层的字符数供上下文占用面板展示。其中几个细节值得展开基础提示词的内容与身份约束。内置默认提示词 system_prompt.md 包含身份声明Your name is Jcode、自主性与持久性要求、编码规范默认边做边提交、使用非交互命令和用户交互约定默认回复不超过 5 行、响应以 Markdown 渲染等。crates/jcode-base/src/prompt_tests.rs 中有专门的测试确保默认提示词不包含 Claude Code 身份字样说明这一层内容本身是受测试约束的产品行为覆盖它时要注意保持语义完整。能力模块的条件注入。以 Mermaid 为例crates/jcode-base/src/prompt.rs 中的MERMAID_PROMPT常量只有简短两句指引是否注入由PromptCapabilities { mermaid: bool }决定该值读取自配置项features.mermaid。测试mermaid_prompt_module_follows_capabilityprompt_tests.rs验证了开启时静态段包含该指引、关闭时完全消失。Self-dev 层只在自开发会话出现。普通会话不会看到 Self-Development Access 段落——非 self-dev 会话通过工具 schema 感知该入口见测试test_non_selfdev_prompt_leaves_selfdev_guidance_to_the_tool_schemaprompt_tests.rs。二、追加指引prompt-overlay.md最常用的定制方式官方文档给出的推荐路径是不触碰默认提示词用叠加文件追加指令~/.jcode/prompt-overlay.md— 全局生效作用于所有项目./.jcode/prompt-overlay.md— 仅作用于当前项目。两个文件都存在时都会被包含而不是二选一。源码中对应 crates/jcode-base/src/prompt.rs 的load_prompt_overlay_files_from_dir它先读项目目录下的.jcode/prompt-overlay.md再读全局~/.jcode/prompt-overlay.md全局目录由crate::storage::jcode_dir()解析测试环境下可通过JCODE_HOME环境变量重定向。每个文件的内容会被包上标题后加入提示词# Project Prompt Overlay (.jcode/prompt-overlay.md) 你的项目级指引原文 # Global Prompt Overlay (~/.jcode/prompt-overlay.md) 你的全局指引原文这一点被测试test_prompt_overlay_files_are_loaded_from_project_and_global_jcode_dirsprompt_tests.rs完整验证同时写入全局与项目两个 overlay 后最终提示词同时包含两份内容且ContextInfo.prompt_overlay_chars 0。实际用法示例在~/.jcode/prompt-overlay.md中写提交信息使用 Conventional Commits 格式在某个仓库的./.jcode/prompt-overlay.md中写本项目测试用cargo test -p crate单独跑即可实现全局风格 项目特例的叠加而不必修改任何 jcode 二进制。三、整体替换基础提示词system-prompt.md当你想彻底重写第一层而不是追加时创建以下任一文件./.jcode/system-prompt.md— 项目级优先级最高~/.jcode/system-prompt.md— 全局级。规则与文档一致且由 prompt.rs 的load_base_system_prompt实现依次检查项目文件、全局文件第一个非空文件胜出空文件或仅含空白字符的文件不会生效会继续回退项目空白 → 全局都空白 → 内置默认。这个保护确保你不可能意外把一个空提示词发给模型替换只作用于基础层。AGENTS.md、overlay、preferred tools、技能与记忆照常叠加在其上。对应实现逻辑// crates/jcode-base/src/prompt.rs (L15-L32 摘要) let candidates [ Some(project_dir.join(.jcode).join(system-prompt.md)), // 项目优先 crate::storage::jcode_dir().ok().map(|dir| dir.join(system-prompt.md)), // 全局 ]; for path in candidates.into_iter().flatten() { if let Ok(content) std::fs::read_to_string(path) { let trimmed content.trim(); if !trimmed.is_empty() { return trimmed.to_string(); // 第一个非空文件生效 } } } DEFAULT_SYSTEM_PROMPT.to_string() // 兜底编译期内嵌的默认提示词测试project_system_prompt_file_replaces_default_base_promptprompt_tests.rs验证了三件事写入You are a custom agent.后load_base_system_prompt返回该文本、完整提示词中不再出现内置默认文案随后把文件改写成空白函数立即回退到DEFAULT_SYSTEM_PROMPT。内置的system_prompt.md本身通过include_str!在编译期嵌入二进制prompt.rs因此修改内置文件必须重新构建文档提到 self-dev 场景下用selfdev build-reload而上述四个用户文件全部在运行时读取改完即对新会话生效。四、AGENTS.md 加载细节去重与会中快照第四层./AGENTS.md与~/AGENTS.md的加载逻辑在 prompt.rs 的load_agents_md_files_from_dirs中有两个容易踩坑的细节同一文件只加载一次。若项目AGENTS.md与全局~/AGENTS.md经canonicalize解析后指向同一真实文件例如工作目录就是$HOME或项目文件是全局文件的符号链接只会以 Project Instructions (AGENTS.md) 身份注入一份避免内容重复。测试agents_md_same_canonical_file_is_loaded_only_as_project_instructions与agents_md_symlink_alias_is_deduplicated_by_canonical_file_pathprompt_tests.rs分别覆盖了同路径与符号链接两种情形会话内快照保证缓存前缀稳定。长生命周期 agent 使用build_system_prompt_split_with_agents_mdprompt.rs传入会话开始时捕获的 AGENTS.md 快照。若会话中途有工具修改了AGENTS.md本会话的提示词前缀保持不变provider 缓存不失效新会话才捕获最新内容。测试captured_agents_md_keeps_split_prompt_stable_after_file_writeprompt_tests.rs精确验证了这一行为会话内改写文件后static_part不变而新快照构建出的下一会话提示词包含新内容。这与文档Notes一节的说法一致这些文件的修改对新会话生效运行中的会话保留启动时捕获的提示词。五、静态/动态拆分为什么第 7 层不参与缓存文档说记忆与活动技能提示词是 dynamic, not cached。底层机制是 prompt.rs 的SplitSystemPrompt结构把完整提示词拆成两段static_part可缓存基础提示词 能力模块 self-dev 指引 AGENTS.md overlay preferred tools 技能列表dynamic_part不缓存memory 提示词、活动技能提示词以及运行时的 system reminder。build_system_prompt_split_with_capabilities_and_agents_mdprompt.rs将各层分别归入 static 或 dynamic 段。这样做的收益由上游调用方兑现crates/jcode-app-core/src/agent/prompting.rs 中的log_prompt_prefix_accounting会按system tools估算前缀 token 数并记入日志——静态前缀在多轮请求间保持逐字节一致就能命中 provider 的 prompt 缓存这正是 jcode 主打的低内存/低开销运行时的组成部分之一。对使用者的含义是把稳定内容放 overlay/preferred-tools静态段把随对话变化的内容留给 memory动态段与框架的缓存设计方向一致。ContextInfoprompt.rs还为每层记录了字符数prompt_overlay_chars、preferred_tools_chars、project_agents_md_chars等并提供了带标签的 breakdownsys/agents/~agents/skills/dev/mem/overlay/tools你可以借此确认某个 overlay 文件确实被加载、占用了多少上下文。六、Swarm 的平行通道swarm-prompt.md 与 /swarm-prompt文档最后提到的 swarm 模型路由指引有一套与上述机制完全同构的独立文件内置默认crates/jcode-base/src/prompt/swarm_prompt.md内容为 worker 的模型选择策略model参数如何覆盖agents.swarm_model、effort分档实现类任务low、设计/调试用默认、批量读取用none、以及普通与 light 模式下只有 root 会话可以派生 agent等结构约束覆盖文件./.jcode/swarm-prompt.md项目优先与~/.jcode/swarm-prompt.md全局加载函数load_swarm_promptprompt.rs沿用项目 → 全局 → 内置默认、空白文件继续回退的三级优先级交互命令在 TUI 中输入/swarm-prompt或/swarm-prompt edit/open会先定位已有非空覆盖文件项目优先于全局若都不存在则把内置默认写入全局文件再用$VISUAL/$EDITOR缺省 nano打开编辑。实现见 crates/jcode-tui/src/tui/app/commands.rs 的ensure_swarm_prompt_edit_path与handle_swarm_prompt_command。生效时机与主提示词相同但更细新派生的 agent 立即加载最新内容已在运行的 agent 保留会话创建时捕获的提示词以维持其工具定义与上下文缓存前缀稳定。测试test_swarm_prompt_prefers_project_then_global_then_defaultprompt_tests.rs用无覆盖 → 全局覆盖 → 项目覆盖 → 项目空白回退全局四步把整条优先级链钉死。七、配置速查表文件作用范围语义优先级/组合~/.jcode/system-prompt.md全局替换基础提示词项目级存在且非空时被其压过./.jcode/system-prompt.md单项目替换基础提示词最高优先级空白则回退~/AGENTS.md全局追加项目指令层与./AGENTS.md同时加载同一真实文件只计一次./AGENTS.md单项目追加项目指令层见上~/.jcode/prompt-overlay.md全局追加指引与项目 overlay 同时包含./.jcode/prompt-overlay.md单项目追加指引见上~/.jcode/preferred-tools.md全局追加工具偏好与项目级同时包含./.jcode/preferred-tools.md单项目追加工具偏好见上~/.jcode/swarm-prompt.md/./.jcode/swarm-prompt.md全局/项目替换swarm 模型路由指引项目 → 全局 → 内置默认八、生效时机与修改注意事项结合文档与源码修改这些文件时的三条规则只对新建会话生效。运行中会话保留启动时捕获的提示词AGENTS.md 的会话内快照机制第四节进一步保证缓存前缀不失效改用户文件零成本改内置文件要重编译。system_prompt.md等内置模板经由include_str!编译期嵌入修改后需重新构建空白文件是安全回退而非清空。无论是system-prompt.md还是swarm-prompt.mdtrim 后为空的文件都会被跳过load_base_system_prompt/load_swarm_prompt均以!trimmed.is_empty()为生效条件你可以放心创建空文件占位。如果你只想追加几条团队约定比如提交规范、测试命令创建.jcode/prompt-overlay.md是最小侵入的方案不改任何二进制、不动 AGENTS.md新会话启动即生效且通过ContextInfo的overlay标签可在上下文占用面板中验证加载情况。【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 jcode 系统提示词配置指南：用 Markdown 文件分层定制 Agent 行为，无需重新构建
jcode 系统提示词配置指南用 Markdown 文件分层定制 Agent 行为无需重新构建【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcodejcode 的系统提示词system prompt并非一整段写死的字符串而是由七个按序组装的层叠片段拼接而成其中多个层完全由用户可编辑的 Markdown 文件驱动。本文基于官方文档 SYSTEM_PROMPT_CONFIG.md 逐层拆解这套机制你可以学会在不重新编译 jcode 的前提下用prompt-overlay.md追加指令、用system-prompt.md整体替换基础提示词、用preferred-tools.md引导工具选择并理解每层内容的加载优先级、生效时机以及它与 provider 缓存前缀static/dynamic 拆分之间的底层关系。一、系统提示词的七层装配顺序官方文档定义的层顺序如下后文源码实现与该顺序完全对应基础系统提示词Base system prompt— 内置于 crates/jcode-base/src/prompt/system_prompt.md可用文件覆盖见第三节能力模块Capability modules— 例如 Mermaid 渲染指引随功能开关条件注入自开发指引Self-dev guidance— 仅在 self-dev 会话jcode 修改自身代码库的会话中注入AGENTS.md— 项目级./AGENTS.md与全局~/AGENTS.md提示词叠加层Prompt overlay—./.jcode/prompt-overlay.md与~/.jcode/prompt-overlay.md首选工具指引Preferred tools—./.jcode/preferred-tools.md与~/.jcode/preferred-tools.md记忆与活动技能提示词Memory and active skill prompt— 动态内容不参与缓存。这一装配过程的核心实现在 crates/jcode-base/src/prompt.rs 的build_system_prompt_full_with_capabilities函数中它按「基础提示词 → self-dev 指引 → AGENTS.md → prompt overlay → preferred tools → memory → 可用技能列表 → 活动技能」的顺序向parts向量追加片段最后用\n\n连接成完整提示词同时返回一份ContextInfo结构记录每一层的字符数供上下文占用面板展示。其中几个细节值得展开基础提示词的内容与身份约束。内置默认提示词 system_prompt.md 包含身份声明Your name is Jcode、自主性与持久性要求、编码规范默认边做边提交、使用非交互命令和用户交互约定默认回复不超过 5 行、响应以 Markdown 渲染等。crates/jcode-base/src/prompt_tests.rs 中有专门的测试确保默认提示词不包含 Claude Code 身份字样说明这一层内容本身是受测试约束的产品行为覆盖它时要注意保持语义完整。能力模块的条件注入。以 Mermaid 为例crates/jcode-base/src/prompt.rs 中的MERMAID_PROMPT常量只有简短两句指引是否注入由PromptCapabilities { mermaid: bool }决定该值读取自配置项features.mermaid。测试mermaid_prompt_module_follows_capabilityprompt_tests.rs验证了开启时静态段包含该指引、关闭时完全消失。Self-dev 层只在自开发会话出现。普通会话不会看到 Self-Development Access 段落——非 self-dev 会话通过工具 schema 感知该入口见测试test_non_selfdev_prompt_leaves_selfdev_guidance_to_the_tool_schemaprompt_tests.rs。二、追加指引prompt-overlay.md最常用的定制方式官方文档给出的推荐路径是不触碰默认提示词用叠加文件追加指令~/.jcode/prompt-overlay.md— 全局生效作用于所有项目./.jcode/prompt-overlay.md— 仅作用于当前项目。两个文件都存在时都会被包含而不是二选一。源码中对应 crates/jcode-base/src/prompt.rs 的load_prompt_overlay_files_from_dir它先读项目目录下的.jcode/prompt-overlay.md再读全局~/.jcode/prompt-overlay.md全局目录由crate::storage::jcode_dir()解析测试环境下可通过JCODE_HOME环境变量重定向。每个文件的内容会被包上标题后加入提示词# Project Prompt Overlay (.jcode/prompt-overlay.md) 你的项目级指引原文 # Global Prompt Overlay (~/.jcode/prompt-overlay.md) 你的全局指引原文这一点被测试test_prompt_overlay_files_are_loaded_from_project_and_global_jcode_dirsprompt_tests.rs完整验证同时写入全局与项目两个 overlay 后最终提示词同时包含两份内容且ContextInfo.prompt_overlay_chars 0。实际用法示例在~/.jcode/prompt-overlay.md中写提交信息使用 Conventional Commits 格式在某个仓库的./.jcode/prompt-overlay.md中写本项目测试用cargo test -p crate单独跑即可实现全局风格 项目特例的叠加而不必修改任何 jcode 二进制。三、整体替换基础提示词system-prompt.md当你想彻底重写第一层而不是追加时创建以下任一文件./.jcode/system-prompt.md— 项目级优先级最高~/.jcode/system-prompt.md— 全局级。规则与文档一致且由 prompt.rs 的load_base_system_prompt实现依次检查项目文件、全局文件第一个非空文件胜出空文件或仅含空白字符的文件不会生效会继续回退项目空白 → 全局都空白 → 内置默认。这个保护确保你不可能意外把一个空提示词发给模型替换只作用于基础层。AGENTS.md、overlay、preferred tools、技能与记忆照常叠加在其上。对应实现逻辑// crates/jcode-base/src/prompt.rs (L15-L32 摘要) let candidates [ Some(project_dir.join(.jcode).join(system-prompt.md)), // 项目优先 crate::storage::jcode_dir().ok().map(|dir| dir.join(system-prompt.md)), // 全局 ]; for path in candidates.into_iter().flatten() { if let Ok(content) std::fs::read_to_string(path) { let trimmed content.trim(); if !trimmed.is_empty() { return trimmed.to_string(); // 第一个非空文件生效 } } } DEFAULT_SYSTEM_PROMPT.to_string() // 兜底编译期内嵌的默认提示词测试project_system_prompt_file_replaces_default_base_promptprompt_tests.rs验证了三件事写入You are a custom agent.后load_base_system_prompt返回该文本、完整提示词中不再出现内置默认文案随后把文件改写成空白函数立即回退到DEFAULT_SYSTEM_PROMPT。内置的system_prompt.md本身通过include_str!在编译期嵌入二进制prompt.rs因此修改内置文件必须重新构建文档提到 self-dev 场景下用selfdev build-reload而上述四个用户文件全部在运行时读取改完即对新会话生效。四、AGENTS.md 加载细节去重与会中快照第四层./AGENTS.md与~/AGENTS.md的加载逻辑在 prompt.rs 的load_agents_md_files_from_dirs中有两个容易踩坑的细节同一文件只加载一次。若项目AGENTS.md与全局~/AGENTS.md经canonicalize解析后指向同一真实文件例如工作目录就是$HOME或项目文件是全局文件的符号链接只会以 Project Instructions (AGENTS.md) 身份注入一份避免内容重复。测试agents_md_same_canonical_file_is_loaded_only_as_project_instructions与agents_md_symlink_alias_is_deduplicated_by_canonical_file_pathprompt_tests.rs分别覆盖了同路径与符号链接两种情形会话内快照保证缓存前缀稳定。长生命周期 agent 使用build_system_prompt_split_with_agents_mdprompt.rs传入会话开始时捕获的 AGENTS.md 快照。若会话中途有工具修改了AGENTS.md本会话的提示词前缀保持不变provider 缓存不失效新会话才捕获最新内容。测试captured_agents_md_keeps_split_prompt_stable_after_file_writeprompt_tests.rs精确验证了这一行为会话内改写文件后static_part不变而新快照构建出的下一会话提示词包含新内容。这与文档Notes一节的说法一致这些文件的修改对新会话生效运行中的会话保留启动时捕获的提示词。五、静态/动态拆分为什么第 7 层不参与缓存文档说记忆与活动技能提示词是 dynamic, not cached。底层机制是 prompt.rs 的SplitSystemPrompt结构把完整提示词拆成两段static_part可缓存基础提示词 能力模块 self-dev 指引 AGENTS.md overlay preferred tools 技能列表dynamic_part不缓存memory 提示词、活动技能提示词以及运行时的 system reminder。build_system_prompt_split_with_capabilities_and_agents_mdprompt.rs将各层分别归入 static 或 dynamic 段。这样做的收益由上游调用方兑现crates/jcode-app-core/src/agent/prompting.rs 中的log_prompt_prefix_accounting会按system tools估算前缀 token 数并记入日志——静态前缀在多轮请求间保持逐字节一致就能命中 provider 的 prompt 缓存这正是 jcode 主打的低内存/低开销运行时的组成部分之一。对使用者的含义是把稳定内容放 overlay/preferred-tools静态段把随对话变化的内容留给 memory动态段与框架的缓存设计方向一致。ContextInfoprompt.rs还为每层记录了字符数prompt_overlay_chars、preferred_tools_chars、project_agents_md_chars等并提供了带标签的 breakdownsys/agents/~agents/skills/dev/mem/overlay/tools你可以借此确认某个 overlay 文件确实被加载、占用了多少上下文。六、Swarm 的平行通道swarm-prompt.md 与 /swarm-prompt文档最后提到的 swarm 模型路由指引有一套与上述机制完全同构的独立文件内置默认crates/jcode-base/src/prompt/swarm_prompt.md内容为 worker 的模型选择策略model参数如何覆盖agents.swarm_model、effort分档实现类任务low、设计/调试用默认、批量读取用none、以及普通与 light 模式下只有 root 会话可以派生 agent等结构约束覆盖文件./.jcode/swarm-prompt.md项目优先与~/.jcode/swarm-prompt.md全局加载函数load_swarm_promptprompt.rs沿用项目 → 全局 → 内置默认、空白文件继续回退的三级优先级交互命令在 TUI 中输入/swarm-prompt或/swarm-prompt edit/open会先定位已有非空覆盖文件项目优先于全局若都不存在则把内置默认写入全局文件再用$VISUAL/$EDITOR缺省 nano打开编辑。实现见 crates/jcode-tui/src/tui/app/commands.rs 的ensure_swarm_prompt_edit_path与handle_swarm_prompt_command。生效时机与主提示词相同但更细新派生的 agent 立即加载最新内容已在运行的 agent 保留会话创建时捕获的提示词以维持其工具定义与上下文缓存前缀稳定。测试test_swarm_prompt_prefers_project_then_global_then_defaultprompt_tests.rs用无覆盖 → 全局覆盖 → 项目覆盖 → 项目空白回退全局四步把整条优先级链钉死。七、配置速查表文件作用范围语义优先级/组合~/.jcode/system-prompt.md全局替换基础提示词项目级存在且非空时被其压过./.jcode/system-prompt.md单项目替换基础提示词最高优先级空白则回退~/AGENTS.md全局追加项目指令层与./AGENTS.md同时加载同一真实文件只计一次./AGENTS.md单项目追加项目指令层见上~/.jcode/prompt-overlay.md全局追加指引与项目 overlay 同时包含./.jcode/prompt-overlay.md单项目追加指引见上~/.jcode/preferred-tools.md全局追加工具偏好与项目级同时包含./.jcode/preferred-tools.md单项目追加工具偏好见上~/.jcode/swarm-prompt.md/./.jcode/swarm-prompt.md全局/项目替换swarm 模型路由指引项目 → 全局 → 内置默认八、生效时机与修改注意事项结合文档与源码修改这些文件时的三条规则只对新建会话生效。运行中会话保留启动时捕获的提示词AGENTS.md 的会话内快照机制第四节进一步保证缓存前缀不失效改用户文件零成本改内置文件要重编译。system_prompt.md等内置模板经由include_str!编译期嵌入修改后需重新构建空白文件是安全回退而非清空。无论是system-prompt.md还是swarm-prompt.mdtrim 后为空的文件都会被跳过load_base_system_prompt/load_swarm_prompt均以!trimmed.is_empty()为生效条件你可以放心创建空文件占位。如果你只想追加几条团队约定比如提交规范、测试命令创建.jcode/prompt-overlay.md是最小侵入的方案不改任何二进制、不动 AGENTS.md新会话启动即生效且通过ContextInfo的overlay标签可在上下文占用面板中验证加载情况。【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考