DeepSeek Harness 系列（06）：System Prompt 组装——动态提示词的工程实现

// 最简单的用法：注册一个静态 Section
ctx.systemPrompt.section({
  name: 'my-plugin:instructions',  // 唯一名称；重复注册同一个名字会抛错
  order: 1000,                      // 排序值，所有 Section 按升序排列
  text: 'You are a helpful assistant.',  // 静态文本
})

// 动态 text：每次组装时都会重新调用这个函数
ctx.systemPrompt.section({
  name: 'my-plugin:context',
  order: 2000,
  text: (context) => {
    // context.scope 是当前 Agent 的作用域（区分不同子 Agent）
    // context.signal 是当前 Turn 的取消信号（可用于中断长时间操作）
    return `Current time: ${new Date().toISOString()}`
  },
})

// 注册一个变量（可以在任意 Section 的 text 里用 {{变量名}} 引用）
ctx.systemPrompt.variable('user_name', (context) => {
  // 从 Agent Session 的 header 里读取工作目录，或者返回默认值
  return context.agent?.session?.header?.cwd ?? 'unknown'
})
 
// 在 Section 里引用变量——不需要自己做字符串插值
ctx.systemPrompt.section({
  name: 'my-plugin:greeting',
  order: 500,
  text: 'Hello, {{user_name}}! I am your AI assistant.',
})

ctx.systemPrompt.section({
  name: 'core:agent-instructions',
  order: 0,
  text: 'You are a specialized code review agent. Be concise and focus on bugs.',
  complete: true,  // 设置为 true 时，这段就是完整的 system prompt，其他所有 Section 被忽略
})

// ctx.systemPrompt.tools() 注册一个工具 schema 提供方
// 通常由 ctx.tools 服务内部自动注册，不需要插件手动调用
// 下面的代码说明内部机制，理解即可
ctx.systemPrompt.tools((context) => {
  return {
    // 当前 Agent 作用域下所有已注册工具的 schema
    schemas: ctx.tools.schemas(context.scope),
    // 工具名称列表（用于简洁引用）
    knownNames: ctx.tools.knownNames(context.scope),
  }
})

// waterfall 监听器：在最终组装前拦截 sections 列表
ctx.on('system-prompt/assemble', async (assembly, context, next) => {
  // assembly.sections  — 已排好序的 Section 列表
  // assembly.contexts  — 动态 context 列表
  // 可以读取、修改，或完全替换 sections
 
  if (someCondition) {
    // 例：在某种条件下压制某个 Section
    assembly.sections = assembly.sections.filter(
      s => s.name !== 'some-plugin:section-to-suppress'
    )
  }
 
  // 必须调用 next()——不调用相当于中断了整个组装链
  return next()
})

每次 Step 开始前：
 
  ctx.systemPrompt.assemble(context)
    │
    ├── 收集所有已注册的 Section（全局 + 当前作用域）
    ├── 作用域 Section 遮蔽同名全局 Section
    ├── 按 order 升序排列（order 相同则按 name 的代码单元顺序）
    ├── 对动态 text 函数求值
    ├── 插值 {{variables}}
    │
    ▼
  system-prompt/assemble waterfall
    │  所有监听器依次执行，可修改 sections/contexts/tools
    │
    ▼
  renderPrompt()
    │  拼接所有段落文本
    │  注入 cache_control 标记（适合缓存的段落末尾）
    │
    ▼
  surface 事件写入 Session 日志
    │  首个 Step → 追加 system/message 节点
    │  后续 Step 提示词有变化 → 替换最新的系统节点
    │  提示词与上次相同 → 复用已有节点（不重复写入）

// 完整插件示例：注入工作目录上下文
export const name = 'my-context-plugin'
 
export function apply(ctx: Context): void {
 
  // 1. 注册一个动态 Section，把当前工作目录注入 system prompt
  ctx.systemPrompt.section({
    name: 'my-context-plugin:workspace',
    // getSectionOrder 读取预定义的顺序位置，而不是写死一个数字
    order: ctx.systemPrompt.getSectionOrder('context:workspace'),
    text: (context) => {
      const cwd = context.agent?.session?.header?.cwd
      // 没有工作目录时返回空字符串，dsh 会自动跳过空段落
      if (!cwd) return ''
      return `Working directory: ${cwd}\nAll file operations are relative to this directory.`
    },
  })
 
  // 2. 注册一个变量，供其他 Section 复用
  ctx.systemPrompt.variable('workspace_cwd', (context) => {
    return context.agent?.session?.header?.cwd ?? 'not set'
  })
 
  // 3. 用作用域 Section 覆盖全局 Section（仅在当前子 Agent 生效）
  //    适用场景：为某种特殊任务创建专用 Agent，需要完全自定义角色
  ctx.systemPrompt.section({
    name: 'core:agent-instructions',  // 与全局同名，会遮蔽它
    order: 0,
    text: 'You are a specialized code review agent. Be concise and focus only on bugs and security issues.',
    complete: true,  // 整个 system prompt 只用这一段
  })
}