# 系统提示词构建器
**本文引用的文件**
- [client.ts](file://src/lib/sdk/client.ts)
- [system-prompt.ts](file://src/lib/sdk/system-prompt.ts)
- [workspace-fs.ts](file://src/lib/workspace-fs.ts)
- [CLAUDE.md](file://templates/init/CLAUDE.md)
- [SOUL.md](file://templates/init/SOUL.md)
- [IDENTITY.md](file://templates/init/IDENTITY.md)
- [USER.md](file://templates/init/USER.md)
- [MEMORY.md](file://templates/init/MEMORY.md)
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件系统性阐述“系统提示词构建器”的设计与实现，重点覆盖五层系统提示词架构：基础提示词、环境信息、工作空间上下文、记忆上下文、规则上下文；并深入对比 buildSystemPrompt 与 buildImSystemPrompt 的差异与适用场景；解释环境提示词的动态注入机制（平台、工作目录、Shell）；说明记忆上下文加载策略与规则上下文的路径作用域处理；最后提供定制与优化实践建议。
## 项目结构
系统提示词构建器位于 SDK 层，围绕以下三个模块协同工作：
- 客户端入口：负责组装系统提示词、构建 SDK 环境、调度工具调用与权限桥接
- 系统提示词定义：提供完整版与精简版基础提示词，以及动态环境段落
- 工作空间文件系统：负责从 .claude/ 目录动态读取配置、记忆与规则文件
```mermaid
graph TB
subgraph "SDK 核心"
A["client.ts
构建系统提示词与SDK选项"]
B["system-prompt.ts
基础提示词与环境段落"]
C["workspace-fs.ts
.claude/文件读取与聚合"]
end
subgraph "工作空间(.claude/)"
D["CLAUDE.md
项目规则(由SDK原生加载)"]
E["SOUL.md / IDENTITY.md / USER.md
个性与用户信息"]
F["MEMORY.md
长期记忆索引(前200行)"]
G["memory/*.md
主题记忆与最近2日日志"]
H["rules/*.md
无/有条件规则(含paths作用域)"]
end
A --> B
A --> C
C --> E
C --> F
C --> G
C --> H
B --> D
```
图表来源
- [client.ts:257-300](file://src/lib/sdk/client.ts#L257-L300)
- [system-prompt.ts:16-553](file://src/lib/sdk/system-prompt.ts#L16-L553)
- [workspace-fs.ts:327-458](file://src/lib/workspace-fs.ts#L327-L458)
章节来源
- [client.ts:257-300](file://src/lib/sdk/client.ts#L257-L300)
- [system-prompt.ts:16-553](file://src/lib/sdk/system-prompt.ts#L16-L553)
- [workspace-fs.ts:327-458](file://src/lib/workspace-fs.ts#L327-L458)
## 核心组件
- 基础提示词常量
- 完整版基础提示词：包含工具使用、行为规范、内存架构、Git 流程、安全与输出效率等全面指导
- 精简版基础提示词：面向 IM 场景，去除 Git、PR 模板、详细工具参考与内存架构，强调简洁与安全
- 动态环境段落：在运行时注入平台、架构、Shell、Node 版本与工作目录等上下文
- 工作空间上下文：按字母序聚合 .claude/ 根目录下所有 .md 文件（除 CLAUDE.md 与 MEMORY.md）
- 记忆上下文：仅加载 MEMORY.md 前 200 行作为索引，列出可用主题记忆文件，并注入最近 2 天的日志
- 规则上下文：扫描 rules/ 下所有 .md，无 frontmatter paths 的规则直接加载，带 paths 的规则仅列出不加载
章节来源
- [system-prompt.ts:16-553](file://src/lib/sdk/system-prompt.ts#L16-L553)
- [workspace-fs.ts:327-458](file://src/lib/workspace-fs.ts#L327-L458)
## 架构总览
五层系统提示词架构与加载顺序如下：
```mermaid
flowchart TD
Start(["开始"]) --> Base["基础提示词
FORGE_BASE_SYSTEM_PROMPT 或 FORGE_IM_SYSTEM_PROMPT"]
Base --> Env["动态环境段落
buildEnvironmentPrompt(cwd)"]
Env --> WS["工作空间上下文
loadWorkspaceContext()"]
WS --> Mem["记忆上下文
loadMemoryContext()"]
Mem --> Rules["规则上下文
loadRulesContext()"]
Rules --> Join["拼接分隔符
---"]
Join --> End(["返回最终系统提示词"])
```
图表来源
- [client.ts:257-300](file://src/lib/sdk/client.ts#L257-L300)
- [system-prompt.ts:493-508](file://src/lib/sdk/system-prompt.ts#L493-L508)
- [workspace-fs.ts:327-458](file://src/lib/workspace-fs.ts#L327-L458)
## 详细组件分析
### 组件一：系统提示词构建函数对比
- buildSystemPrompt（桌面/终端场景）
- 用途：生成完整系统提示词，适合需要 Git、PR 模板、详细工具参考与完整内存架构的对话
- 结构：基础提示词 + 环境段落 + 工作空间上下文 + 记忆上下文 + 规则上下文
- 关键点：会加载 rules 上下文，便于在复杂工程中启用条件规则
- buildImSystemPrompt（IM 场景）
- 用途：生成紧凑系统提示词，节省约 2500 token，适合消息通道（飞书/电报/Discord）
- 结构：精简基础提示词 + 环境段落 + 工作空间上下文 + 记忆上下文
- 关键点：不加载 rules 上下文，避免上下文冗余；仍保留 MEMORY.md 与近期日志，确保一致性
适用场景建议
- 桌面聊天/复杂工程任务：优先使用 buildSystemPrompt
- 轻量化 IM 交互：优先使用 buildImSystemPrompt
章节来源
- [client.ts:257-300](file://src/lib/sdk/client.ts#L257-L300)
- [system-prompt.ts:516-553](file://src/lib/sdk/system-prompt.ts#L516-L553)
### 组件二：环境提示词构建机制
- 注入内容
- 主工作目录：来自工作空间项目路径解析
- 平台与架构：process.platform 与 process.arch
- Shell：优先使用 SHELL 环境变量，Windows 默认 cmd，其他默认 /bin/sh
- Node 版本：process.version
- 应用来源：声明由 Forge 桌面应用驱动
- 动态性
- 随进程启动时的环境变化而变化，确保模型对当前运行环境有准确感知
章节来源
- [system-prompt.ts:493-508](file://src/lib/sdk/system-prompt.ts#L493-L508)
- [client.ts:257-300](file://src/lib/sdk/client.ts#L257-L300)
### 组件三：工作空间上下文加载策略
- 加载范围：.claude/ 根目录下所有 .md 文件（按文件名字母序）
- 排除项：CLAUDE.md（由 SDK 原生加载）、MEMORY.md（单独处理）
- 包含项：SOUL.md、IDENTITY.md、USER.md 及其他自定义配置文件
- 标记方式：以文件名（不含扩展名）作为标题进行包裹，形成结构化段落
章节来源
- [workspace-fs.ts:327-347](file://src/lib/workspace-fs.ts#L327-L347)
- [CLAUDE.md:13-22](file://templates/init/CLAUDE.md#L13-L22)
- [SOUL.md:1-37](file://templates/init/SOUL.md#L1-L37)
- [IDENTITY.md:1-19](file://templates/init/IDENTITY.md#L1-L19)
- [USER.md:1-18](file://templates/init/USER.md#L1-L18)
### 组件四：记忆上下文加载策略
- MEMORY.md：仅加载前 200 行作为索引，超过 200 行时附加提示，引导用户将详细内容迁移到主题文件
- 主题记忆：列出 .claude/memory/ 下的非日期与非归档文件，不自动注入，需按需读取
- 近期日志：自动注入最近 2 天的日期型日志文件
- 设计意图：保持上下文轻量，同时保留可检索的记忆清单
章节来源
- [workspace-fs.ts:355-397](file://src/lib/workspace-fs.ts#L355-L397)
- [MEMORY.md:1-4](file://templates/init/MEMORY.md#L1-L4)
### 组件五：规则上下文的路径作用域处理
- 扫描范围：递归扫描 .claude/rules/ 下的所有 .md 文件
- 无 frontmatter paths：直接加载为规则段落
- 有 frontmatter paths：仅列出文件路径，不加载；未来可结合文件匹配实现按需加载
- 设计意图：区分全局通用规则与路径作用域规则，避免无关规则进入上下文
章节来源
- [workspace-fs.ts:404-458](file://src/lib/workspace-fs.ts#L404-L458)
### 组件六：系统提示词构建流程（序列图）
```mermaid
sequenceDiagram
participant Caller as "调用方"
participant Client as "client.ts"
participant WS as "workspace-fs.ts"
participant SP as "system-prompt.ts"
Caller->>Client : 请求构建系统提示词
alt 使用IM提示
Client->>SP : 获取 FORGE_IM_SYSTEM_PROMPT
else 使用桌面提示
Client->>SP : 获取 FORGE_BASE_SYSTEM_PROMPT
end
Client->>SP : buildEnvironmentPrompt(cwd)
Client->>WS : loadWorkspaceContext()
Client->>WS : loadMemoryContext()
Client->>WS : loadRulesContext()
WS-->>Client : 返回各上下文片段
Client-->>Caller : 拼接后的系统提示词
```
图表来源
- [client.ts:257-300](file://src/lib/sdk/client.ts#L257-L300)
- [workspace-fs.ts:327-458](file://src/lib/workspace-fs.ts#L327-L458)
- [system-prompt.ts:493-508](file://src/lib/sdk/system-prompt.ts#L493-L508)
## 依赖关系分析
- client.ts 依赖
- system-prompt.ts：基础提示词与环境段落
- workspace-fs.ts：工作空间、记忆与规则上下文读取
- workspace-fs.ts 依赖
- 文件系统 API：读取 .claude/ 目录下的配置、记忆与规则文件
- 数据库：解析工作空间项目路径（非全局工作空间）
```mermaid
graph LR
Client["client.ts"] --> Sys["system-prompt.ts"]
Client --> FS["workspace-fs.ts"]
FS --> Files[".claude/ 文件系统"]
```
图表来源
- [client.ts:23-25](file://src/lib/sdk/client.ts#L23-L25)
- [workspace-fs.ts:32-42](file://src/lib/workspace-fs.ts#L32-L42)
章节来源
- [client.ts:23-25](file://src/lib/sdk/client.ts#L23-L25)
- [workspace-fs.ts:32-42](file://src/lib/workspace-fs.ts#L32-L42)
## 性能考量
- 上下文长度控制
- MEMORY.md 仅加载前 200 行，避免超长上下文
- 仅列出主题记忆文件名，不注入全文
- 最近 2 日日志按需注入，减少冗余
- 规则上下文按需加载
- 条件规则仅列出路径，不注入正文，降低 token 占用
- 精简提示词
- IM 提示词显著缩短，适合低延迟与低 token 场景
- 环境段落最小化
- 仅注入必要运行时信息，避免冗余
## 故障排查指南
- 环境段落缺失或异常
- 检查 cwd 解析是否成功（工作空间路径不存在时回退到进程当前目录）
- 确认 SHELL 环境变量是否正确，Windows 默认 cmd
- 记忆上下文为空
- 确认 .claude/memory/ 目录存在且包含有效文件
- 检查 MEMORY.md 是否存在且非空
- 规则上下文未生效
- 若规则带 paths frontmatter，属于路径作用域，不会被自动加载，需在实际操作匹配文件时再读取
- 工作空间上下文不完整
- 确认 .claude/ 根目录下 .md 文件命名合法且未被排除（CLAUDE.md、MEMORY.md 不参与此处注入）
- 权限与路径问题
- 写入 .claude/ 目录需使用 Bash heredoc 方式，避免 Write/Edit 工具被 SDK 拦截
章节来源
- [client.ts:257-300](file://src/lib/sdk/client.ts#L257-L300)
- [workspace-fs.ts:327-458](file://src/lib/workspace-fs.ts#L327-L458)
- [system-prompt.ts:493-508](file://src/lib/sdk/system-prompt.ts#L493-L508)
## 结论
该系统提示词构建器通过五层架构实现了“可扩展、可裁剪、可维护”的提示词体系：基础提示词保证行为一致性，动态环境段落提供运行时上下文，工作空间上下文承载个性化配置，记忆上下文维持跨会话连续性，规则上下文支持路径作用域的条件约束。buildSystemPrompt 与 buildImSystemPrompt 分别针对桌面与 IM 场景提供最优平衡，既满足功能需求又控制上下文成本。
## 附录
- 定制与优化实践
- 选择合适的提示词版本：复杂工程与桌面交互用完整版，IM 与轻量交互用精简版
- 控制 MEMORY.md 长度：将细节迁移到主题文件，保持索引简洁
- 合理组织 rules：通用规则直接写入正文，路径敏感规则使用 frontmatter paths 并仅列出
- 环境信息最小化：仅在必要时调整环境段落，避免过度注入
- 持续评估 token 成本：根据模型上下文窗口与任务复杂度动态调整各层内容