Files
codebuddy2api1ts/参数.md
2026-04-23 20:50:35 +08:00

22 KiB
Raw Blame History

参数说明

本文基于当前代码实现整理,目的是给后续编写转发程序时提供一份可直接对照的参数参考。

涉及的主要代码位置:


1. 总览

当前仓库里有两条主要链路:

1.1 直连远端链路

入口:npm run chat:direct

对应代码:

这条链路直接请求:

  • https://copilot.tencent.com/v2/chat/completions

它需要你构造:

  1. HTTP 请求头
  2. JSON 请求体
  3. system prompt
  4. user message 包装内容
  5. CLI 上下文注入内容

这部分最适合后续做“远端转发 / 伪装成官方客户端”的参考。

1.2 本地代理链路

入口:npm run start

对应代码:

这条链路提供本地兼容接口:

  • POST /v1/chat/completions
  • POST /chat/completions
  • POST /v1/messages

它本身不直接拼远端 HTTP 头,而是把请求转成 prompt 后交给 Agent SDK。


2. 直连远端链路需要的参数

以下内容来自 src/direct-chat.ts:19-220

2.1 目标地址

CODEBUDDY_DIRECT_ENDPOINT

  • 作用:远端接口地址
  • 默认值:https://copilot.tencent.com/v2/chat/completions
  • 代码位置:src/direct-chat.ts:19
  • 是否必需:否

如果你后续写转发程序要直接打官方接口,这个值就是默认目标地址。


2.2 模型参数

CODEBUDDY_MODEL

  • 作用:请求体中的 model
  • 默认值:minimax-m2.7
  • 代码位置:src/direct-chat.ts:20
  • 是否必需:否

请求体中实际发送:

{
  "model": "minimax-m2.7"
}

2.3 鉴权参数

CODEBUDDY_API_KEY

它会被同时用于这些 header

  • authorization: Bearer <apiKey>
  • x-api-key: <apiKey>
  • x-user-id: anonymous_<apiKey后8位>

CODEBUDDY_APIKEY_FILE

  • 作用:当环境变量没有设置 CODEBUDDY_API_KEY 时,从文件读取 key
  • 默认值:apikey
  • 代码位置:src/direct-chat.ts:166
  • 是否必需:否

读取规则:

  • 逐行读取
  • 去掉空白
  • 跳过 # 注释行
  • 取第一条有效内容

如果环境变量和文件都没有,会报错:

  • Missing API key. Set CODEBUDDY_API_KEY or create apikey.

2.4 system prompt 相关参数

CODEBUDDY_DISABLE_SYSTEM_PROMPT

CODEBUDDY_SYSTEM_PROMPT

  • 作用:直接通过环境变量传入 system prompt
  • 代码位置:src/direct-chat.ts:182-183
  • 是否必需:否
  • 优先级:高于文件

CODEBUDDY_SYSTEM_PROMPT_FILE

  • 作用:从文件读取 system prompt
  • 默认值:captures/codebuddy-system-prompt.txt
  • 代码位置:src/direct-chat.ts:185-187
  • 是否必需:否

CODEBUDDY_SYSTEM_PROMPT_MODE

规则:

  • original:只使用本地原始 system prompt忽略客户端传入的 system / instructions
  • passthrough:只透传客户端传入的 system / instructions不注入本地原始 system prompt
  • hybrid:同时发送两条 system prompt本地原始 system prompt 在前,客户端传入的 system / instructions 在后

默认不会把原始 system prompt 和客户端 system prompt 同时发给上游;只有 hybrid 模式会这样做。

system prompt 注入规则

代码位置:src/direct-chat.ts:107-109

如果存在 system prompt请求体里的 messages 会变成:

[
  { "role": "system", "content": "...system prompt..." },
  ...history
]

否则直接发送历史消息。


2.5 user message 包装参数

CODEBUDDY_DISABLE_USER_QUERY_WRAP

  • 作用:关闭 <user_query>...</user_query> 包装
  • 生效条件:值为 1
  • 代码位置:src/direct-chat.ts:111-117
  • 是否必需:否

注意:当前实现里这个开关不只是去掉 <user_query> 标签。因为 buildUserContent() 在该开关为 1 时会直接返回原始字符串,所以也会同时跳过 cliUserContextBlocks 注入。

也就是说:

  • 默认模式:user.contenttext block 数组,包含 CLI 上下文和 <user_query>
  • CODEBUDDY_DISABLE_USER_QUERY_WRAP=1user.content 退化为纯字符串,不包含 CLI 上下文

默认情况下,用户输入不会直接以纯字符串发送,而是被包装成:

[
  ...cliUserContextBlocks,
  {
    "type": "text",
    "text": "<user_query>用户输入</user_query>"
  }
]

也就是说默认 user message 的 content 是一个数组,而不是纯字符串。

如果关闭包装,则发送原始字符串:

{
  "role": "user",
  "content": "用户原始输入"
}

2.6 CLI 上下文注入参数

CODEBUDDY_DISABLE_CLI_USER_CONTEXT

  • 作用:关闭从抓包文件中提取 CLI 上下文并注入 user message
  • 生效条件:值为 1
  • 代码位置:src/direct-chat.ts:190-191
  • 是否必需:否

CODEBUDDY_CLI_CAPTURE_FILE

  • 作用:指定抓包文件,用来抽取 user message 中的上下文块
  • 默认值:captures/codebuddy-chat-completion-full.redacted.json
  • 代码位置:src/direct-chat.ts:193-194
  • 是否必需:否

CLI 上下文提取规则

代码位置:src/direct-chat.ts:196-209

程序会:

  1. 读取抓包 JSON
  2. 找到 request_body.messages 里第一条 role === "user" 的消息
  3. 仅保留 content 数组中的 type === "text"
  4. 过滤掉含有 <user_query> 的块
  5. 剩余部分作为 cliUserContextBlocks

也就是说,这些上下文块本质上用于模拟官方客户端注入的:

  • memory
  • system-reminder
  • IDE context
  • 其他包装文本

这部分是当前直连效果接近官方 chat-completion 的关键参数来源。

当前抓包里 user.content 实际是 3 段 text block

  1. memory / system-reminder
  2. IDE / system-reminder
  3. <user_query>真实用户输入</user_query>

后续不同 CLI 版本、目录状态或配置下,前面的上下文 block 数量可能变化。因此转发程序不应该写死为 2 个上下文 block而应该按当前逻辑处理为

0..N 个 CLI context blocks + 1 个 <user_query> block

2.7 采样 / 推理相关参数

这些字段直接写进远端请求体。

CODEBUDDY_TEMPERATURE

CODEBUDDY_MAX_TOKENS

CODEBUDDY_REASONING_EFFORT

CODEBUDDY_VERBOSITY

CODEBUDDY_REASONING_SUMMARY


2.8 远端请求体完整结构

代码位置:src/direct-chat.ts:63-77

当前程序实际发送的 JSON 结构为:

{
  "model": "minimax-m2.7",
  "messages": [
    { "role": "system", "content": "..." },
    { "role": "user", "content": [
      { "type": "text", "text": "...context block 1..." },
      { "type": "text", "text": "...context block 2..." },
      { "type": "text", "text": "<user_query>...</user_query>" }
    ] }
  ],
  "stream": true,
  "stream_options": {
    "include_usage": true
  },
  "temperature": 1,
  "max_tokens": 48000,
  "reasoning_effort": "medium",
  "verbosity": "high",
  "reasoning_summary": "auto"
}

其中固定发送的字段有:

  • model
  • messages
  • stream: true
  • stream_options.include_usage: true
  • temperature
  • max_tokens
  • reasoning_effort
  • verbosity
  • reasoning_summary

2.9 远端请求头完整结构

代码位置:src/direct-chat.ts:130-159

当前程序会发送以下 headers

Header 来源 说明
content-type 固定 application/json
content-encoding 固定 gzip
accept 固定 application/json
x-requested-with 固定 XMLHttpRequest
authorization CODEBUDDY_API_KEY Bearer 鉴权
x-api-key CODEBUDDY_API_KEY 额外鉴权头
x-conversation-id 随机 UUID 会话 ID
x-conversation-request-id 随机 hex 请求 ID
x-conversation-message-id 随机 hex 消息 ID
x-agent-intent 固定 craft
x-ide-type 固定 CLI
x-ide-name 固定 CLI
x-ide-version 固定 2.93.3
user-agent CODEBUDDY_USER_AGENT 或默认值 模拟客户端 UA
x-trace-id 随机 hex trace id
x-request-id x-trace-id 相同 request id
b3 由 traceId + spanId 组成 b3 tracing
x-b3-traceid traceId tracing
x-b3-parentspanid 固定空串 tracing
x-b3-spanid spanId tracing
x-b3-sampled 固定 1
x-codebuddy-request 固定 1
x-user-id apiKey 后 8 位 匿名用户标识
x-product 固定 SaaS

补充:代码中会设置 x-b3-parentspanid: "",但在最终抓包中这个空 header 可能被客户端或中间层丢弃,因此抓包里不一定能看到它。这个字段不是核心鉴权字段;如果后续要严格复刻官方 CLI可以单独测试是否需要保留。

CODEBUDDY_USER_AGENT

  • 作用:覆盖 user-agent
  • 默认值:
CLI/2.93.3 CodeBuddy/2.93.3 CodeBuddy Agent SDK/0.3.28 (Node.js/25.2.1) CodeBuddy Code/2.93.3

3. 本地代理服务需要的参数

以下内容来自 src/config.tssrc/server.tssrc/codebuddy.ts

3.1 服务监听参数

PORT

  • 作用:本地 HTTP 服务监听端口
  • 默认值:8787
  • 代码位置:src/config.ts:38
  • 是否必需:否

PROXY_API_KEY

如果设置了该值,客户端调用本地代理时必须带:

Authorization: Bearer <PROXY_API_KEY>

3.2 本地代理支持的接口

代码位置:src/server.ts:29-49

OpenAI 风格

  • POST /v1/chat/completions
  • POST /chat/completions

Anthropic 风格

  • POST /v1/messages

其他接口

  • GET /health
  • GET /debug/memory
  • GET /v1/models

3.3 本地代理可接受的 OpenAI 请求参数

定义位置:src/protocols.ts:5-9

当前代码真正使用的只有:

字段 是否必需 说明
model 请求模型名
messages 消息数组
stream 是否流式输出

prompt 拼接规则

代码位置:

OpenAI 风格请求会被转成:

ROLE:
content

ROLE:
content

也就是把每条 message 变成:

  • SYSTEM:
  • USER:
  • ASSISTANT:

再按文本拼接。


3.4 本地代理可接受的 Anthropic 请求参数

定义位置:src/protocols.ts:11-16

当前代码真正使用的只有:

字段 是否必需 说明
model 请求模型名
system system prompt
messages 消息数组
stream 是否流式输出

prompt 拼接规则

代码位置:

Anthropic 风格请求会被转成:

SYSTEM:
...

USER:
...

ASSISTANT:
...

如果 system 为空,则不加 SYSTEM: 段。


3.5 content 到纯文本的转换规则

代码位置:src/prompt.ts:21-38

contentToText() 支持:

  1. string
  2. Array
  3. object

处理规则:

如果是字符串

直接返回。

如果是数组

逐项处理:

  • 如果项本身是字符串,直接保留
  • 如果项是对象,优先取 text
  • 否则尝试取 content
  • 最终用换行拼接

如果是对象

只尝试取 text

这意味着

你的 OpenAI / Anthropic 转发层如果传入类似:

[
  { "type": "text", "text": "hello" },
  { "type": "text", "text": "world" }
]

最终会变成:

hello
world

4. 本地代理服务的环境变量

4.1 模型和权限相关

CODEBUDDY_MODEL

  • 作用:本地代理默认模型
  • 代码位置:src/config.ts:40
  • 是否必需:否

如果请求体里没带 model,则用它。

CODEBUDDY_PASS_REQUEST_MODEL

如果不开启,则请求里的 model 不会真正影响底层 SDK只用于返回值展示。

CODEBUDDY_PERMISSION_MODE

允许值:

  • default
  • acceptEdits
  • bypassPermissions
  • plan
  • delegate
  • dontAsk

4.2 账号加载参数

代码位置:src/config.ts:48-76

账号加载优先级如下:

  1. CODEBUDDY_ACCOUNTS_JSON
  2. CODEBUDDY_API_KEY / CODEBUDDY_AUTH_TOKEN
  3. CODEBUDDY_APIKEY_FILE

如果全部都没有,会报错。

CODEBUDDY_ACCOUNTS_JSON

  • 作用:通过 JSON 传入多个账号
  • 代码位置:src/config.ts:49
  • 是否必需:否

支持两种格式:

[
  {
    "id": "a1",
    "apiKey": "xxx",
    "authToken": "yyy",
    "internetEnvironment": "zzz",
    "configDir": "/path/to/dir"
  }
]

或:

{
  "accounts": [
    {
      "id": "a1",
      "apiKey": "xxx"
    }
  ]
}

CODEBUDDY_API_KEY

CODEBUDDY_AUTH_TOKEN

CODEBUDDY_INTERNET_ENVIRONMENT

CODEBUDDY_APIKEY_FILE

  • 作用:凭证文件路径
  • 默认值:apikey
  • 代码位置:src/config.ts:61

CODEBUDDY_TOKEN_KIND

  • 作用:当凭证文件是“裸 token 列表”时,指定这些行应被当成 api_key 还是 auth_token
  • 可选值:api_key / auth_token
  • 默认值:api_key
  • 代码位置:src/config.ts:70

4.3 账号对象字段

定义位置:src/config.ts:4-10

单个账号支持这些字段:

字段 说明
id 账号标识
apiKey API Key
authToken Auth Token
internetEnvironment 网络环境标识
configDir 单账号配置目录

configDir 默认规则

代码位置:src/config.ts:108-118

如果未显式提供,默认会创建:

<cwd>/.codebuddy-accounts/<id>

5. Agent SDK session 实际使用的参数

代码位置:src/codebuddy.ts:83-98

创建 session 时,实际传入:

参数 来源
cwd process.cwd()
model `requestedModel
permissionMode CODEBUDDY_PERMISSION_MODE
includePartialMessages 固定 true
settingSources 固定 []
env.CODEBUDDY_API_KEY 账号配置
env.CODEBUDDY_AUTH_TOKEN 账号配置
env.CODEBUDDY_INTERNET_ENVIRONMENT 账号配置
env.CODEBUDDY_CONFIG_DIR 账号配置

这意味着后续如果你写的是“本地代理 -> Agent SDK -> CodeBuddy”的转发不需要手工拼远端 HTTP headers但需要把账号参数和 session 参数配对好。


6. 返回格式参数

以下来自 src/protocols.ts

6.1 OpenAI 非流式响应

代码位置:src/protocols.ts:26-35

固定结构:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "...",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

6.2 OpenAI 流式响应

代码位置:src/protocols.ts:37-54

每个 SSE chunk 结构:

{
  "id": "chatcmpl-...",
  "object": "chat.completion.chunk",
  "created": 1234567890,
  "model": "...",
  "choices": [
    {
      "index": 0,
      "delta": { "content": "..." },
      "finish_reason": null
    }
  ]
}

结束时输出:

data: [DONE]

6.3 Anthropic 非流式响应

代码位置:src/protocols.ts:56-67

固定结构:

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "model": "...",
  "content": [
    { "type": "text", "text": "..." }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  }
}

6.4 Anthropic 流式响应

代码位置:src/protocols.ts:69-86

事件顺序固定为:

  1. message_start
  2. content_block_start
  3. 多次 content_block_delta
  4. content_block_stop
  5. message_delta
  6. message_stop

7. 后续写转发程序时最关键的参数

如果目标是“尽可能复刻当前 direct-chat 效果”,最关键的是下面这些:

必需参数

参数 原因
CODEBUDDY_API_KEY 远端鉴权必须有
authorization / x-api-key 远端请求头必须有
model 请求体核心字段
messages 请求体核心字段
stream 当前实现固定启用
stream_options.include_usage 当前实现固定启用

高影响参数

参数 原因
system prompt 决定基础行为
cliUserContextBlocks 决定是否接近官方 chat-completion 行为
<user_query> 包装 决定用户问题在 prompt 中的结构
reasoning_effort 影响推理风格
verbosity 影响输出密度
reasoning_summary 影响返回行为
max_tokens 影响可输出长度
temperature 影响稳定性与发散度

容易忽略但建议保留的请求头

Header 原因
x-conversation-id 会话标识
x-conversation-request-id 请求标识
x-conversation-message-id 消息标识
user-agent 客户端指纹的一部分
x-ide-type / x-ide-name / x-ide-version 客户端环境标识
x-trace-id / x-request-id / b3 tracing 相关
x-codebuddy-request 客户端标识
x-product 产品标识

8. 建议的最小转发模板

如果你后续单独写一个远端转发器,建议最少保证下面这些字段齐全:

请求头最小集合

{
  "content-type": "application/json",
  "content-encoding": "gzip",
  "accept": "application/json",
  "authorization": "Bearer <apiKey>",
  "x-api-key": "<apiKey>",
  "x-conversation-id": "<uuid>",
  "x-conversation-request-id": "<hex>",
  "x-conversation-message-id": "<hex>",
  "x-agent-intent": "craft",
  "x-ide-type": "CLI",
  "x-ide-name": "CLI",
  "x-ide-version": "2.93.3",
  "user-agent": "<ua>",
  "x-trace-id": "<traceId>",
  "x-request-id": "<traceId>",
  "b3": "<traceId>-<spanId>-1-",
  "x-b3-traceid": "<traceId>",
  "x-b3-spanid": "<spanId>",
  "x-b3-sampled": "1",
  "x-codebuddy-request": "1",
  "x-user-id": "anonymous_<suffix>",
  "x-product": "SaaS"
}

请求体最小集合

{
  "model": "minimax-m2.7",
  "messages": [
    { "role": "system", "content": "..." },
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "...context 1..." },
        { "type": "text", "text": "...context 2..." },
        { "type": "text", "text": "<user_query>...</user_query>" }
      ]
    }
  ],
  "stream": true,
  "stream_options": { "include_usage": true },
  "temperature": 1,
  "max_tokens": 48000,
  "reasoning_effort": "medium",
  "verbosity": "high",
  "reasoning_summary": "auto"
}

9. 一句话结论

如果后续目标是“写一个效果尽量接近官方 chat-completion 的转发器”,真正不能少的不是只有 system prompt而是这四层一起保留

  1. system prompt
  2. cliUserContextBlocks
  3. <user_query> 包装
  4. 一整套近似官方的 headers 和请求体参数