企业官网建设流程全解析

jcode 系统提示词配置指南：用 Markdown 文件分层定制 Agent 行为，无需重新构建

【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcode

jcode 的系统提示词（system prompt）并非一整段写死的字符串，而是由七个按序组装的层叠片段拼接而成，其中多个层完全由用户可编辑的 Markdown 文件驱动。本文基于官方文档 SYSTEM_PROMPT_CONFIG.md 逐层拆解这套机制：你可以学会在不重新编译 jcode 的前提下，用prompt-overlay.md追加指令、用system-prompt.md整体替换基础提示词、用preferred-tools.md引导工具选择，并理解每层内容的加载优先级、生效时机，以及它与 provider 缓存前缀（static/dynamic 拆分）之间的底层关系。

一、系统提示词的七层装配顺序

官方文档定义的层顺序如下（后文源码实现与该顺序完全对应）：

1. 基础系统提示词（Base system prompt）— 内置于 crates/jcode-base/src/prompt/system_prompt.md，可用文件覆盖（见第三节）；
2. 能力模块（Capability modules）— 例如 Mermaid 渲染指引，随功能开关条件注入；
3. 自开发指引（Self-dev guidance）— 仅在 self-dev 会话（jcode 修改自身代码库的会话）中注入；
4. AGENTS.md— 项目级./AGENTS.md与全局~/AGENTS.md；
5. 提示词叠加层（Prompt overlay）—./.jcode/prompt-overlay.md与~/.jcode/prompt-overlay.md；
6. 首选工具指引（Preferred tools）—./.jcode/preferred-tools.md与~/.jcode/preferred-tools.md；
7. 记忆与活动技能提示词（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_capability（prompt_tests.rs）验证了开启时静态段包含该指引、关闭时完全消失。

Self-dev 层只在自开发会话出现。普通会话不会看到 "Self-Development Access" 段落——非 self-dev 会话通过工具 schema 感知该入口（见测试test_non_selfdev_prompt_leaves_selfdev_guidance_to_the_tool_schema，prompt_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_dirs（prompt_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实现）：

1. 依次检查项目文件、全局文件，第一个非空文件胜出；
2. 空文件或仅含空白字符的文件不会生效，会继续回退（项目空白 → 全局；都空白 → 内置默认）。这个保护确保你不可能"意外把一个空提示词发给模型"；
3. 替换只作用于基础层。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_prompt（prompt_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_path（prompt_tests.rs）分别覆盖了同路径与符号链接两种情形；
• 会话内快照保证缓存前缀稳定。长生命周期 agent 使用build_system_prompt_split_with_agents_md（prompt.rs）传入会话开始时捕获的 AGENTS.md 快照。若会话中途有工具修改了AGENTS.md，本会话的提示词前缀保持不变（provider 缓存不失效），新会话才捕获最新内容。测试captured_agents_md_keeps_split_prompt_stable_after_file_write（prompt_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_md（prompt.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（动态段），与框架的缓存设计方向一致。

ContextInfo（prompt.rs）还为每层记录了字符数（prompt_overlay_chars、preferred_tools_chars、project_agents_md_chars等），并提供了带标签的 breakdown（sys/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_prompt（prompt.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_default（prompt_tests.rs）用"无覆盖 → 全局覆盖 → 项目覆盖 → 项目空白回退全局"四步把整条优先级链钉死。

七、配置速查表

八、生效时机与修改注意事项

结合文档与源码，修改这些文件时的三条规则：

1. 只对新建会话生效。运行中会话保留启动时捕获的提示词；AGENTS.md 的会话内快照机制（第四节）进一步保证缓存前缀不失效；
2. 改用户文件零成本，改内置文件要重编译。system_prompt.md等内置模板经由include_str!编译期嵌入，修改后需重新构建；
3. 空白文件是安全回退而非"清空"。无论是system-prompt.md还是swarm-prompt.md，trim 后为空的文件都会被跳过（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