上下文管理

什么是上下文？

上下文（Context）是传递给 API 的配置信息，用于：

配置工具所需的参数
提供业务相关的配置数据
定义系统提示词模板
指定品牌、模型等偏好设置

上下文结构

顶层 context

所有工具共享的通用上下文：

基本结构

{
  "context": {
    "preferredBrand": "品牌名称",
    "configData": {...},
    "replyPrompts": {...},
    "systemPrompts": {...},
    "dulidayToken": "your_token"
  }
}

toolContext

为特定工具提供专属上下文，会覆盖全局 context 中的同名字段：

工具特定配置

{
  "toolContext": {
    "zhipin_reply_generator": {
      "replyPrompts": {...}  // 覆盖全局设置
    }
  }
}

Context 字段速查表

context 对象包含以下字段，所有字段都是可选的：

字段	类型	使用场景
`configData`	`ZhipinData`	`zhipin_reply_generator` 工具必需
`replyPrompts`	`ReplyPromptsConfig`	`zhipin_reply_generator` 工具必需
`systemPrompts`	`Record<string, string>`	配合 `promptType` 使用
`dulidayToken`	`string`	Duliday 相关工具必需
`preferredBrand`	`string`	多品牌配置时指定默认品牌
`modelConfig`	`ModelConfig`	自定义 AI 提供商设置
`defaultWechatId`	`string`	微信相关工具使用

点击下方折叠面板查看每个字段的详细说明和示例。

字段详解

configData - 业务配置数据

业务配置数据，包含品牌信息、门店列表、筛选条件等。

工具 zhipin_reply_generator 必需 configData 和 replyPrompts，否则会返回 400 错误（或根据 contextStrategy 处理）。

configData 示例

{
  "context": {
    "configData": {
      "city": "上海",
      "stores": [
        {
          "name": "南京西路店",
          "address": "上海市静安区南京西路123号"
        }
      ],
      "brands": {
        "蜀地源冒菜": {
          "templates": {
            "general_chat": ["您好，这里是蜀地源冒菜招聘"]
          },
          "screening": {
            "age": { "min": 18, "max": 55 }
          }
        }
      },
      "defaultBrand": "蜀地源冒菜"
    }
  }
}

replyPrompts - 回复提示词配置

回复提示词配置，定义不同场景下的回复模板。类型为 Record<ReplyContext, string>。可用的场景键：

general_chat - 常规聊天
initial_inquiry - 初次询问
schedule_inquiry - 排班询问
salary_inquiry - 薪资询问
interview_request - 面试邀请
availability_inquiry - 时间确认
followup_chat - 后续跟进
age_concern - 年龄问题

replyPrompts 示例

{
  "context": {
    "replyPrompts": {
      "general_chat": "你是连锁餐饮招聘助手，请用简洁礼貌的语气与候选人沟通。",
      "initial_inquiry": "向候选人简要介绍品牌与岗位，并询问其城市与时间安排。",
      "salary_inquiry": "清晰说明薪资结构，包括基本工资、绩效奖金和福利。"
    }
  }
}

systemPrompts - 系统提示词映射表

系统提示词映射表，是一个键值对对象（Record<string, string>）。通过 promptType 参数从此映射表中查找对应的 system prompt 文本。

systemPrompts 仅用于 system prompt 查找，不影响工具集。promptType 的工具映射是内置的。详见系统提示词文档。

systemPrompts 示例

{
  "promptType": "bossZhipinSystemPrompt",
  "context": {
    "systemPrompts": {
      "bossZhipinSystemPrompt": "你是BOSS直聘招聘助手...",
      "generalComputerSystemPrompt": "你是一个通用AI助手..."
    }
  }
}

→ 使用 “你是BOSS直聘招聘助手…” 作为 system prompt

dulidayToken - Duliday API 令牌

Duliday 系统的 API 访问令牌。

所有 Duliday 相关工具（如 duliday_job_list、duliday_job_details、duliday_interview_booking）都必需此字段。

dulidayToken 示例

{
  "context": {
    "dulidayToken": "your_duliday_api_token"
  }
}

preferredBrand - 首选品牌

指定首选的品牌名称，当 configData 包含多个品牌时，使用此字段选择默认品牌。

preferredBrand 示例

{
  "context": {
    "preferredBrand": "蜀地源冒菜",
    "configData": {
      "brands": {
        "蜀地源冒菜": {...},
        "另一个品牌": {...}
      }
    }
  }
}

modelConfig - 模型配置

自定义模型配置，可以覆盖默认的 AI 提供商设置。

modelConfig 示例

{
  "context": {
    "modelConfig": {
      "chatModel": "anthropic/claude-3-7-sonnet-20250219",
      "classifyModel": "qwen/qwen-max-latest",
      "replyModel": "qwen/qwen-plus-latest",
      "providerConfigs": {
        "anthropic": {
          "apiKey": "your-key",
          "baseURL": "https://api.anthropic.com"
        }
      }
    }
  }
}

defaultWechatId - 默认微信号

默认微信号，用于微信相关工具。

defaultWechatId 示例

{
  "context": {
    "defaultWechatId": "hr_wechat_001"
  }
}

📦 sandboxId - 沙盒环境（点击展开）

E2B 沙盒 ID，用于需要沙箱环境的工具（如 computer）。

sandboxId 是顶层字段，不属于 context 对象。

sandboxId 位置示例

{
  "model": "anthropic/claude-3-7-sonnet-20250219",
  "messages": [...],
  "sandboxId": "sb_abc123",  // ← 顶层字段
  "promptType": "generalComputerSystemPrompt",
  "context": {
    // sandboxId 不在这里
    "preferredBrand": "..."
  }
}

需要沙盒的工具：

computer - E2B 计算机控制工具

查询哪些工具需要沙盒：

查询工具

curl -X GET https://huajune.duliday.com/api/v1/tools \
  -H "Authorization: Bearer YOUR_API_KEY"

响应中 requiresSandbox: true 的工具需要提供 sandboxId。

完整示例

智能回复工具
toolContext 覆盖
Duliday 工具

使用智能回复工具的完整配置示例：

智能回复工具完整配置

{
  "model": "anthropic/claude-3-7-sonnet-20250219",
  "messages": [
    {
      "role": "user",
      "content": "你好，我想了解一下这个职位"
    }
  ],
  "promptType": "bossZhipinSystemPrompt",
  "allowedTools": ["zhipin_reply_generator"],
  "context": {
    "preferredBrand": "蜀地源冒菜",
    "configData": {
      "city": "上海",
      "stores": [
        {
          "name": "南京西路店",
          "address": "上海市静安区南京西路123号"
        }
      ],
      "brands": {
        "蜀地源冒菜": {
          "templates": {
            "general_chat": ["您好，这里是蜀地源冒菜招聘，请问有什么可以帮助您？"]
          },
          "screening": {
            "age": { "min": 18, "max": 55, "preferred": [] },
            "blacklistKeywords": [],
            "preferredKeywords": []
          }
        }
      },
      "defaultBrand": "蜀地源冒菜"
    },
    "systemPrompts": {
      "bossZhipinSystemPrompt": "你是BOSS直聘招聘助手，负责与候选人沟通岗位信息。"
    },
    "replyPrompts": {
      "general_chat": "你是连锁餐饮招聘助手，请用简洁礼貌的语气与候选人沟通。",
      "initial_inquiry": "向候选人简要介绍品牌与岗位，并询问其城市与时间安排。"
    },
    "defaultWechatId": "hr_001"
  }
}

使用 toolContext 为不同工具提供不同配置：

toolContext 覆盖示例

{
  "model": "anthropic/claude-3-7-sonnet-20250219",
  "messages": [...],
  "allowedTools": ["zhipin_reply_generator", "duliday_job_list"],
  "context": {
    "preferredBrand": "全局品牌",
    "configData": {...},
    "replyPrompts": {"general_chat": "全局回复模板"}
  },
  "toolContext": {
    "zhipin_reply_generator": {
      "preferredBrand": "蜀地源冒菜",
      "replyPrompts": {
        "general_chat": "蜀地源冒菜专用回复模板"
      }
    },
    "duliday_job_list": {
      "dulidayToken": "特定的token"
    }
  }
}

合并结果：

zhipin_reply_generator 使用：
- preferredBrand: “蜀地源冒菜” （来自 toolContext）
- configData: 全局的 configData （未被覆盖）
- replyPrompts: {"general_chat": "蜀地源冒菜专用回复模板"} （来自 toolContext）
duliday_job_list 使用：
- preferredBrand: “全局品牌” （来自全局 context）
- dulidayToken: “特定的token” （来自 toolContext）

使用 Duliday 相关工具的配置示例：

Duliday 工具配置

{
  "model": "anthropic/claude-3-7-sonnet-20250219",
  "messages": [
    {"role": "user", "content": "帮我查询职位列表"}
  ],
  "allowedTools": ["duliday_job_list", "duliday_job_details"],
  "context": {
    "preferredBrand": "蜀地源冒菜",
    "dulidayToken": "your_duliday_api_token"
  }
}

所有 Duliday 工具（duliday_job_list、duliday_job_details、duliday_interview_booking）都必须提供 dulidayToken。

上下文策略

通过 contextStrategy 控制缺失上下文的处理方式：

策略	行为
`error`	返回 400 错误并列出缺失字段（默认）
`skip`	跳过无法初始化的工具
`report`	返回验证报告，不执行请求

error 策略（默认）

当工具缺少必需上下文时，立即返回 400 错误：

{
  "model": "anthropic/claude-3-7-sonnet-20250219",
  "messages": [...],
  "allowedTools": ["zhipin_reply_generator"],
  "context": {},  // 缺少 configData 和 replyPrompts
  "contextStrategy": "error"
}

{
  "error": "Tool 'zhipin_reply_generator' Missing required context: configData, replyPrompts. Please provide these fields in 'context' or 'toolContext.zhipin_reply_generator'.",
  "statusCode": 400,
  "correlationId": "req_abc123"
}

skip 策略

跳过无法初始化的工具，继续执行其他工具：

{
  "model": "anthropic/claude-3-7-sonnet-20250219",
  "messages": [...],
  "allowedTools": ["bash", "zhipin_reply_generator"],
  "context": {},  // 缺少 zhipin_reply_generator 所需的上下文
  "contextStrategy": "skip"
}

HTTP/1.1 200 OK
X-Tools-Skipped: zhipin_reply_generator (Missing required context: configData, replyPrompts)
Content-Type: application/json

{
  "success": true,
  "data": {
    "messages": [...],  // 只使用了 bash 工具
    "tools": {
      "used": ["bash"],
      "skipped": ["zhipin_reply_generator"]
    }
  }
}

report 策略

返回验证报告，不执行请求：

{
  "model": "anthropic/claude-3-7-sonnet-20250219",
  "messages": [...],
  "allowedTools": ["bash", "zhipin_reply_generator"],
  "context": {
    "configData": {...}  // 提供了 configData，但缺少 replyPrompts
  },
  "contextStrategy": "report"
}

{
  "valid": false,
  "model": {
    "valid": true
  },
  "tools": [
    {"name": "bash", "valid": true},
    {
      "name": "zhipin_reply_generator",
      "valid": false,
      "missingContext": ["replyPrompts"]
    }
  ]
}

report 策略等价于 validateOnly: true，适合在实际调用前预检配置。

验证上下文

使用 validateOnly 模式检查上下文配置：

验证模式

{
  "model": "anthropic/claude-3-7-sonnet-20250219",
  "messages": [...],
  "allowedTools": ["zhipin_reply_generator"],
  "context": {...},
  "validateOnly": true
}

返回验证报告，说明哪些工具可以成功初始化，哪些缺少必需的上下文。

validateOnly: true 的效果与 contextStrategy: "report" 相同。

快速查询 API

查看字段类型定义

curl -X GET https://huajune.duliday.com/api/v1/config-schema \
  -H "Authorization: Bearer YOUR_API_KEY"

查看工具所需上下文

curl -X GET https://huajune.duliday.com/api/v1/tools \
  -H "Authorization: Bearer YOUR_API_KEY"

下一步

工具系统

了解工具如何使用上下文

系统提示词

了解 systemPrompts 字段的详细用法

工具调用

查看完整的工具调用示例

错误处理

了解如何处理上下文缺失错误

快速开始

核心概念

功能指南

最佳实践

什么是上下文？

上下文结构

顶层 context

toolContext

Context 字段速查表

字段详解

完整示例

上下文策略

验证上下文

快速查询 API

查看字段类型定义

查看工具所需上下文

下一步

工具系统

系统提示词

工具调用

错误处理

​什么是上下文？

​上下文结构

​顶层 context

​toolContext

​Context 字段速查表

​字段详解

​完整示例

​上下文策略

​验证上下文

​快速查询 API

查看字段类型定义

查看工具所需上下文

​下一步

工具系统

系统提示词

工具调用

错误处理

什么是上下文？

上下文结构

顶层 context

toolContext

Context 字段速查表

字段详解

完整示例

上下文策略

验证上下文

快速查询 API

下一步