跳转至

系统提示词生成原理

为了确保智能体的行为一致性、安全性以及对其工具和技能的认知，Kesoku 会在每个会话回合（Turn）开始时，动态编译组装一份完整的系统提示词（System Prompt）。本指南详细介绍了系统提示词的拼装结构与加载规则。

🛠️ 组装流程

提示词是由 src/kesoku/agent/prompt.py 文件中的 build_sys_prompt() 函数进行动态拼接的。拼接时采用双换行符 (\n\n) 作为分界，依次拼入以下各个层级的指示内容：

┌────────────────────────────────────────────────────────┐
│ 1. 活跃角色人设：roles/{role}/intro.md                   │
├────────────────────────────────────────────────────────┤
│ 2. Agent 工作根目录指示 (AWD)                           │
├────────────────────────────────────────────────────────┤
│ 3. 会话暂存工作区目录指示 (STAGING_DIR)                   │
├────────────────────────────────────────────────────────┤
│ 4. 内置功能交互规范 (技能、文件发送、按钮等)                │
├────────────────────────────────────────────────────────┤
│ 5. 全局配置提示词 (config.agent.user_prompts)           │
├────────────────────────────────────────────────────────┤
│ 6. 适配器动态注入上下文 (Discord 频道与成员元数据)          │
└────────────────────────────────────────────────────────┘

🔍 各模块详细解析

1. 活跃角色人设 (Active Persona)

  • 解析规则：通过当前会话 ID 在数据库中查询绑定的角色名（未绑定时默认使用 "default"）。
  • 加载逻辑：读取 roles/<角色名>/intro.md 文件的文本内容。
  • 目的：为模型赋予特定的性格、语气风格、专业背景以及对话边界。

2. Agent 工作根目录 (AWD)

  • 注入格式： 
    # Agent Working Directory
> AWD='{cfg.agent_working_dir}'
You are working in the agent working directory (AWD)...
  • 目的：明确告诉模型当前执行终端命令的工作空间根路径，限制其去任意检索 AWD 目录之外的其他敏感系统文件。

3. 会话暂存工作区 (STAGING_DIR)

  • 注入格式： 
    # Session Staging Directory
> STAGING_DIR='{sessions_dir}/{session_workspace_name}'
- This is where you are supposed to save your output files...
  • 目的：告诉模型所有在执行过程中产生的中间产物、下载的文件、生成的图片等，都必须保存到当前会话专属的暂存目录下，避免污染全局工作区。

4. 内置功能交互规范

这些是硬编码在 prompt.py 中的提示语，用于训练智能体理解和操作 Kesoku 的独特机制：

  • SKILLS_INSTRUCTIONS：指导模型如何使用 list_skills() 检索可用技能，以及使用 use_skill(name) 加载特定技能说明。
  • FILE_SENDING_INSTRUCTIONS：指导模型发送文件的特殊语法：[file: /绝对/文件/路径]。如果回复文本中包含此格式，聊天平台适配器会自动将其捕获并作为文件附件上传给最终用户。
  • QUESTION_INSTRUCTION：指导模型发送多项选择按钮的特殊语法：[question: <标题> | 选项1 | 选项2]。
  • MEMORY_AND_HISTORY_INSTRUCTIONS：指导模型如何读写 SQLite 数据库中的结构化记忆条目。
  • BACKGROUND_EXECUTION_INSTRUCTIONS：指导模型在遇到耗时较长的 background 终端命令时，如何优雅地向用户发送中间提示并立即结束本回合，等待系统后台完成通知。

5. 全局配置提示词 (User Prompts)

  • 解析规则：读取 config.toml 中 [agent].user_prompts 数组里配置的所有外部提示词文件。
  • 格式包装： 
    === BEGIN {文件名} ===
{文件内容}
=== END {文件名} ===
  • 目的：供管理员引入全局自定义的规范文档（如代码编写规范、特定的 API 调用手册等）。

6. 适配器动态注入上下文 (Adapter Custom Prompts)

  • 解析规则：各个平台的 Chatbot 适配器在调用网关时，可以通过 custom_prompt 参数动态传入上下文。
  • 目的：例如 Discord 适配器会读取当前服务器频道的成员列表、频道 ID 和用户代号，并将其拼入提示词，让 Agent 能够准确识别是在对谁说话。