s10 系统提示词构建：System Prompt - Harness Engineering - 后端

# 三行速读

system prompt 应该是分段装配管道，不是超长静态字符串。
静态段与动态段分离，才能兼顾稳定性与时效性。
输入工程做得好，后续扩展（技能、记忆、协议）都更顺滑。

# 先修知识

已读 s05、s09，理解技能与记忆都可能注入输入面。
知道 “模型看到的是拼装结果，不是你脑中的逻辑图”。

# 读完后你应该能做到（可检验清单）

画出本项目 prompt 分段装配顺序。
解释为什么 dynamic 信息不该混进 static core。
独立改一个 prompt section 且不影响其他 section。

# 本篇要解决什么

很多新手把 system prompt 写成超长字符串，后来谁也不敢动。s10 要解决的是输入工程问题：系统提示词应该是可组装管道，而不是一段 “神秘全文”。

# 用一个类比先理解

像搭积木：

底层积木是稳定规则（身份、原则）；
中层积木是能力说明（工具、技能、记忆）；
顶层积木是动态上下文（时间、目录、当前状态）。

你不会每次都把所有积木重做一遍。

# 为什么这一步必须现在做

系统能力增长后，提示词维护会成为主要复杂度来源。先把结构化装配建立起来，后续才能安全迭代。

# 关键代码怎么读

# 1) 动态边界标记

1	DYNAMIC_BOUNDARY = "=== DYNAMIC_BOUNDARY ==="

这是静态段与动态段的分界线，后续可用于缓存和调试。

# 2) Prompt Builder 分段函数

class SystemPromptBuilder:
    def _build_core(self) -> str: ...
    def _build_tool_listing(self) -> str: ...
    def _build_skill_listing(self) -> str: ...
    def _build_memory_section(self) -> str: ...
    def _build_claude_md(self) -> str: ...
    def _build_dynamic_context(self) -> str: ...

每段一个职责，改动互不干扰。

# 3) 统一组装出口

def build(self) -> str:
    sections = []
    ...
    sections.append(DYNAMIC_BOUNDARY)
    ...
    return "\n\n".join(sections)

所有输入最终通过一个出口拼装，行为可预测。

# 4) 每轮提醒单独注入

1
2
3

def build_system_reminder(extra: str = None) -> dict:
    content = "<system-reminder>\n" + "\n".join(parts) + "\n</system-reminder>"
    return {"role": "user", "content": content}

短时信息走提醒通道，不污染长期规则段。

# 你可以怎么复现

打印 /prompt 查看完整拼装结果。
只改某一段 builder，验证其他段不受影响。
增加一条动态提醒，看是否只影响当前轮。

# 常见误区

误区 1：把所有信息写进 core，导致核心规则膨胀。
误区 2：不区分长期规则与短期上下文。
误区 3：缺少统一装配入口，后续难排查。

# 一句话总结

s10 让 prompt 从 “文案” 变成 “可维护输入系统”。

# 补充解读：Prompt 管道的工程收益

# A. `_build_tool_listing()` 让模型能力可见

for tool in self.tools:
    props = tool.get("input_schema", {}).get("properties", {})
    params = ", ".join(props.keys())
    lines.append(f"- {tool['name']}({params}): {tool['description']}")

这段的价值是 “显式能力说明”。模型知道能做什么，调用错误率会下降。

# B. `_build_skill_listing()` 与 s05 串联

它只加载技能元信息，不加载全文。说明 s10 与 s05 是配套关系：prompt 里暴露目录，具体内容按需拉。

# C. `_build_claude_md()` 多层指令链

1
2
3

user_claude = Path.home() / ".claude" / "CLAUDE.md"
project_claude = self.workdir / "CLAUDE.md"
subdir_claude = cwd / "CLAUDE.md"

这让指令体系支持 “全局 -> 项目 -> 子目录” 叠加，方便多仓库复用。

# D. `build()` 的静态 / 动态分离可缓存

教学版每轮重建，真实系统可缓存静态前缀，仅刷新动态尾部，显著节约 token。

# 进阶练习

为每个 section 增加长度统计，监控 token 成本。
给 prompt builder 增加 “禁用某段” 开关，测试行为变化。
对比 “全量重建” 和 “静态缓存” 性能差异。

# 统一术语口径（本章）

Prompt Pipeline ：由多个分段构成的可维护输入装配链。
Static Section ：长期稳定的提示段。
Dynamic Section ：每轮更新的上下文提示段。

# 章节衔接（从易到难）

本章解决 “输入工程可维护性”。
下一章 s11 进入 “失败恢复机制如何保证完成率”。

Harness Engineering