Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* env 三段组装 + process.env strip —— Claude Code spawn 用。
*
* 1. process.env 剥离敏感 OAuth token(避免 CLI 子进程读到用户系统 key)
* 2. behaviorFlags 打底(runtimeConfig 注入,host 配置)
* 3. endpoint → ANTHROPIC_BASE_URL(runtimeConfig 注入)
* 4. authEnv 最后合并(确保不被 behaviorFlags 误覆盖)
* 5. CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST=1 锁定 provider 路由
* (阻止 workdir/.claude/settings.json env 字段覆盖 app 注入的 key/baseUrl)
*
* 例外:Claude 订阅会话(`nativeCliAuth`)不走 3 / 5 —— CLI 用自己登录的凭证直连
* Anthropic,host 不接管连接,见 ClaudeEnvBuildOptions.nativeCliAuth。
*/
import type { AgentCredentialMode, AuthAdapter } from '../../interfaces/auth-adapter.js';
import type { AgentRuntimeConfig } from '../../interfaces/runtime-config.js';
import { applyPlainTextTerminalEnv } from '../shared/terminal-output.js';
export const MAKER_MODEL_CONTEXT_WINDOWS_ENV = 'XDT_MAKER_MODEL_CONTEXT_WINDOWS';
interface ModelContextWindowSource {
id: string;
contextWindow: number;
/**
* 是否把无 [1m] 后缀的 id 镜像出一个同窗口的 `${id}[1m]` 键(缺省 true,
* 兼容 provider 路由模型把 [1m] 当同窗口路由别名的历史语义)。claude-* 的
* [1m] 是真实的 1M 通道、不是同窗口别名,按会话路由注入的条目必须传 false,
* 否则 200K 会被镜像到 Fast 切换后的 [1m] 形态上(#3661)。
*/
mirrorOneMillionSuffix?: boolean;
}
interface ClaudeEnvBuildOptions {
/**
* Host-provided model context windows for provider-routed models.
*
* Claude Code's internal resolver only knows Anthropic model names and a few
* hard-coded suffixes. Maker capabilities are the source of truth for XDLLM /
* LiteLLM-routed models such as qwen/*, deepseek/*, Kimi, GLM, Gemini, GPT.
*/
modelContextWindows?: readonly ModelContextWindowSource[];
/**
* The model selected for this spawn. Claude Code's auto-compact resolver does
* not read Maker's catalog-wide window map; it needs the selected model's
* window in CLAUDE_CODE_MAX_CONTEXT_TOKENS.
*/
activeModel?: string;
/**
* 'remote': 远端 cc-mgr daemon 跑 SDK 的 env —— 从空字典起,绝不继承 desktop
* 进程 OS env(Windows HOME=C:\... 透到远端会让 cc CLI 落怪目录)。daemon 自身
* process.env 的真实远端 HOME/PATH 由 daemon 在调用 SDK 前显式合并。
* 'local'(默认): 继承 cleanProcessEnv() —— 本地子进程需本地 PATH/HOME 才能跑。
*/
mode?: 'local' | 'remote';
/** 本次子进程明确要走的凭证形态。undefined 时保持 adapter 既有 fallback。 */
credentialMode?: AgentCredentialMode;
/**
* Claude 订阅会话:CLI 自己读取、刷新本机登录凭证并直连 Anthropic。
*
* Anthropic 只允许用户用自己的订阅登录**未修改的 Claude Code**,不允许第三方应用
* 收集、存储或中转订阅凭证。所以这类 spawn:
* - 不写 ANTHROPIC_BASE_URL —— 请求不经本地 loopback proxy;
* - 不设 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST —— 该 flag 会让 CLI 不读本机凭证;
* - host 的 getAuthEnv 不递任何凭证(见 desktop auth-adapters)。
* 其余 env(行为开关、窗口、subagent 等)与其它形态一致。仅本机 spawn 有效,
* 远端 cc-mgr 会话恒为 false。
*/
nativeCliAuth?: boolean;
/**
* 会话模型,仅在未指定来源(credentialMode 为 undefined)时随 getAuthEnv 递给 adapter
* (AuthAdapterOptions.model),让它判断能否交给本机 Claude Code 登录。
*/
authModel?: string;
/**
* 本次 spawn 的会话来源(显式 providerId;null/undefined = 隐式默认路由)。
* 供 runtimeConfig.subagentModelForRoute 按父会话来源判定 subagent 覆写是否可路由
* (options.subagentModel 省略、走 runtimeConfig 回落分支时消费)。
*/
sessionProviderId?: string | null;
/**
* CC CLI 内部小模型调用(bash 命令前缀判定/标题/摘要等)的模型覆写
* (`ANTHROPIC_SMALL_FAST_MODEL`)。未设置时 CLI 用内置**裸名**默认值 ——
* 经网关路由的会话模型 id 带命名空间前缀(如 `anthropic/claude-opus-5`),
* 网关模型白名单按字面比对,CLI 的裸名默认值必被拒为 403
* user_model_access_denied(#3557)。调用方只在会话 wire 模型带命名空间时
* 传入(钉到会话自身的 wire 模型 —— 它是唯一确定已授权的 id);裸名会话
* (订阅直连 / 自定义中继)省略,保持 CLI 默认行为零变化。
*/
smallFastModel?: string;
/**
* 调用方已解析好的 `CLAUDE_CODE_SUBAGENT_MODEL` 决定(见 subagent-model-default.ts)。
* - 字符串 → 设该值;
* - `null` → 明确**不要设**(让用户手写 agent 的 frontmatter `model:` 生效);
* - 省略 → 回落读 `runtimeConfig`(未接该解析的调用方保持旧行为;有
* subagentModelForRoute 时按 sessionProviderId/credentialMode 走路由感知入口)。
*/
subagentModel?: string | null;
}
function serializeModelContextWindows(
models: readonly ModelContextWindowSource[] | undefined,
): string | undefined {
if (!models || models.length === 0) return undefined;
const entries: Record<string, number> = {};
for (const model of models) {
if (!model.id || !Number.isFinite(model.contextWindow) || model.contextWindow <= 0) {
continue;
}
const window = Math.floor(model.contextWindow);
entries[model.id] = window;
// 后缀判定大小写不敏感(#3661):用户配置 `...[1M]` 时不能再镜像出
// `...[1M][1m]` 垃圾键。镜像本身仍按原样键写入,消费侧按字面匹配。
const hasOneMillionSuffix = /\[1m\]$/i.test(model.id);
if (model.mirrorOneMillionSuffix !== false && !hasOneMillionSuffix) {
entries[`${model.id}[1m]`] = window;
}
}
return Object.keys(entries).length > 0 ? JSON.stringify(entries) : undefined;
}
/**
* Anthropic / Claude Code 体系所有"会让 CC CLI 子进程绕过 app 配置"的 env 字段
* 单一来源:
* - 鉴权字段 (API_KEY / AUTH_TOKEN / OAUTH_TOKEN / *_FILE_DESCRIPTOR)
* - endpoint 重定向 (BASE_URL / UNIX_SOCKET)
* - header 注入 (CUSTOM_HEADERS — 可塞 Authorization 直接覆盖 key)
* - provider 切换 (Vertex / Bedrock / Foundry — 走另一套体系)
* - 配置目录重定向 (CLAUDE_CONFIG_DIR — 让 CC 去读别处的 .credentials.json)
*
* 任何 host (desktop / 未来 server / CI) 都应该:
* - boot 阶段调用 stripSensitiveAnthropicEnv() 清根上的 process.env (主防线)
* - buildClaudeEnv 调用 cleanProcessEnv() 兜底自己手里的字典 (副防线)
*/
export const SENSITIVE_ANTHROPIC_ENV_KEYS = [
// 鉴权
'ANTHROPIC_API_KEY',
'ANTHROPIC_AUTH_TOKEN',
'CLAUDE_CODE_OAUTH_TOKEN',
'CINDY_CLAUDE_ACCOUNT_PROVIDER_ID',
'CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR',
'CLAUDE_CODE_API_KEY_FILE_DESCRIPTOR',
// 订阅身份元数据(与 OAUTH_TOKEN 配套,cc env-token 分支消费):不剥离的话,从
// 带这些变量的 shell 启动 Cindy(典型:终端里的 cc 会话内跑 dev)会把**别人的
// 档位/scopes**漏进子进程 —— 凭证库没提供时 getAuthEnv 不注入对应 key,继承残留
// 会顶上,订阅会话以错误 scopes/tier 起跑。
'CLAUDE_CODE_OAUTH_SCOPES',
'CLAUDE_CODE_SUBSCRIPTION_TYPE',
'CLAUDE_CODE_RATE_LIMIT_TIER',
// endpoint 重定向
'ANTHROPIC_BASE_URL',
'ANTHROPIC_UNIX_SOCKET',
// header 注入
'ANTHROPIC_CUSTOM_HEADERS',
// provider 切换
'ANTHROPIC_VERTEX_PROJECT_ID',
'ANTHROPIC_BEDROCK_BASE_URL',
'ANTHROPIC_FOUNDRY_API_KEY',
'ANTHROPIC_FOUNDRY_BASE_URL',
'ANTHROPIC_FOUNDRY_RESOURCE',
// 配置目录重定向
'CLAUDE_CONFIG_DIR',
// host 接管标记:非订阅会话由 buildClaudeEnv 显式写 '1';继承来的残留(终端里的 cc
// 会话跑 dev)会让订阅会话的 CLI 不读自己的登录凭证,而 SDK merge 只能覆盖、删不掉。
'CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST',
// 子代理派发覆盖:这是 host 独占的键(值由「Subagent 模型」设置经
// subagent-model-default.ts 解析决定),继承来的残留会以最高优先级盖掉用户手写 agent 的
// `model:`,而且**盖得静默**。典型泄漏路径:终端里的 cc 会话跑 dev,Electron 从
// process.env 继承外层会话的值 —— 那时 host 判定的「不要设」在 SDK 的
// `{...process.env, ...userEnv}` 合并里根本不生效(我们只能覆盖,删不掉)。
'CLAUDE_CODE_SUBAGENT_MODEL',
] as const;
/**
* 远端路由 materialization 覆盖前,须从 remoteEnv 剥离的鉴权 / 上游 / 定制头字段。
*
* 清单归本文件所有:buildClaudeEnv(经 getAuthEnv / endpoint / behaviorFlags)是这些
* 字段在 remoteEnv 里的唯一写入方,新增鉴权类写入时必须同步本清单,否则 route 覆盖后
* 旧字段残留、破坏「route.env 是远端鉴权唯一事实源 / 单鉴权门」不变量(消费方见
* claude-code/index.ts startSession 远端分支)。
*
* 刻意不复用 SENSITIVE_ANTHROPIC_ENV_KEYS:那是「继承残留清洗」超集,含 route 覆盖时
* 必须保留的字段(如 CLAUDE_CONFIG_DIR:远端由 cc-manager 自己决定)。
*/
export const REMOTE_ROUTE_OVERRIDE_ENV_KEYS = [
'ANTHROPIC_API_KEY',
'ANTHROPIC_AUTH_TOKEN',
'CLAUDE_CODE_OAUTH_TOKEN',
'CINDY_CLAUDE_ACCOUNT_PROVIDER_ID',
'CLAUDE_CODE_OAUTH_SCOPES',
'CLAUDE_CODE_SUBSCRIPTION_TYPE',
'CLAUDE_CODE_RATE_LIMIT_TIER',
'ANTHROPIC_CUSTOM_HEADERS',
'ANTHROPIC_BASE_URL',
] as const;
/**
* 对齐 Claude Desktop Code 的入口标记,覆盖从终端继承或路由注入的旧身份。
* 本机登录、API Key 与远端会话共用此规则;不以是否注入 OAuth token 区分入口。
*
* claude-desktop 也在 CLI 的 OAuth 刷新回调白名单内,并启用原生 desktop-host
* 配置过滤(项目级设置不能改写上游 / 鉴权)。凭证来源仍由 nativeCliAuth /
* CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST 决定,不因此注入凭证或改变认证路由。
* 远端路由 materialization 后再次调用,避免 route.env 覆盖入口。
*/
export function applyClaudeDesktopEntrypoint(env: Record<string, string>): void {
env.CLAUDE_CODE_ENTRYPOINT = 'claude-desktop';
}
/**
* !! 主防线 !! 必须由 host 在 boot 最早期(任何动态 import / spawn 之前)调用一次。
*
* 背景: Claude Agent SDK <= 0.2.112 在 spawn CLI 时强制做
* `F6 = { ...process.env, ...userEnv }`
* 我们传给 SDK 的 env 字典只能"覆盖"process.env 里的同名字段,**无法删除**它们。
* 用户系统(HKCU / shell rc)若设了 ANTHROPIC_AUTH_TOKEN 之类,会从 process.env
* 直接漏到 CC CLI 子进程,子进程的 Anthropic 客户端优先用 Bearer authToken,
* 导致 401(用了用户那把过期/无效 key)。
*
* 新版 SDK 的 options.env 替代进程环境;boot 清洗仍保护未显式传 env 的调用方。
* 旧版 SDK 的根治办法是在 boot 时就把根上的 process.env 清干净。
* cleanProcessEnv 只能作副防线(只动我们手里的字典)。
*
* 返回值: 实际清掉的 key 列表(给 host 打日志用)。
*/
export function stripSensitiveAnthropicEnv(env: NodeJS.ProcessEnv = process.env): string[] {
const stripped: string[] = [];
for (const key of SENSITIVE_ANTHROPIC_ENV_KEYS) {
if (env[key] !== undefined) {
delete env[key];
stripped.push(key);
}
}
return stripped;
}
/**
* 副防线: 剥离 process.env 里的敏感字段,只作用于本函数返回的字典副本。
*
* !! 警告: 不能单独依赖 !!
* 旧版 SDK 在 spawn 时会做 `{ ...process.env, ...userEnv }` 二次 merge — 即使我们的
* 字典里没有这些字段,process.env 上还有就会漏给子进程。真正的根治在
* stripSensitiveAnthropicEnv()(host boot 阶段调)。
*
* 这里保留是为了:
* (a) host 没接 boot strip 时仍有局部防护;
* (b) 配合 getAuthEnv 的"显式覆盖"语义,避免把 undefined 值误传给 spawn。
*/
export function cleanProcessEnv(env: NodeJS.ProcessEnv = process.env): Record<string, string> {
const sensitive = new Set<string>(SENSITIVE_ANTHROPIC_ENV_KEYS);
const out: Record<string, string> = {};
for (const [k, v] of Object.entries(env)) {
if (sensitive.has(k)) continue;
if (typeof v === 'string') out[k] = v;
}
return out;
}
/**
* `CLAUDE_CODE_SUBAGENT_MODEL` 的**唯一**写入点。
*
* - 非空串 → 设该值;
* - `null` / 空串 → **删掉这个键**;
* - `undefined` → 不动(调用方没有做过决定)。
*
* 为什么「不设」必须是 delete 而不是「跳过赋值」:local 模式的 env 是从 `cleanProcessEnv()`
* 起的,`behaviorFlags` 也可能带进来同名键。只跳过赋值的话,那个继承/外来的值会原封不动
* 留在字典里,继续以最高优先级盖掉 frontmatter —— 「明确不设」于是变成一句空话。
*
* (根因侧的防线是把该键放进 SENSITIVE_ANTHROPIC_ENV_KEYS:boot 期从 process.env 剥掉,
* 否则 SDK spawn 时的 `{...process.env, ...userEnv}` 合并我们只能覆盖、无法删除。
* 这里的 delete 负责字典层,两道一起才干净。)
*
* `discoverSubagentDefinitions` 需要本函数产出的 env(要读 `CLAUDE_CONFIG_DIR`),所以
* 「先建 env、再判定、最后回来落这个键」是合法用法,见 index.ts 的会话启动路径。
*/
export function applySubagentModelEnv(
env: Record<string, string>,
decision: string | null | undefined,
): void {
if (decision === undefined) return;
const value = (decision ?? '').trim();
if (value) env.CLAUDE_CODE_SUBAGENT_MODEL = value;
else delete env.CLAUDE_CODE_SUBAGENT_MODEL;
}
export const EXPLORE_INHERIT_CAP_DISABLE_ENV = 'CLAUDE_CODE_DISABLE_EXPLORE_INHERIT_CAP';
/**
* CC 判定「主模型是否在 Explore inherit cap 之内」用的家族词(2.1.259 反编译里的 `ven`,
* cap 值 `Cen = "opus"`,取 `ven.slice(0, indexOf(cap)+1)` = 整个数组)。CC 侧是**子串**
* 匹配、大小写不敏感,这里照抄它的口径,不要换成前缀或精确匹配。
*/
const EXPLORE_CAP_TIER_WORDS = ['haiku', 'sonnet', 'opus'] as const;
/**
* cap 只对 Claude 家族才算「限高」。家族里不在上面三档中的成员(Fable)被 cap 收到 Opus
* 是上游有意的成本上限,必须保留 —— 所以这里额外识别家族标记。
*
* 与 `apps/desktop` 的 `ANTHROPIC_WIRE_MODEL_PREFIXES` 刻意不复用:那份在 main 进程,
* maker-core 反向 import 会破坏依赖方向(见 docs/dev-rules/architecture-invariants.md)。
* 两处都只是「前缀/子串兜底地板」,新增 Anthropic 家族名时同步加词即可。
*/
const CLAUDE_FAMILY_MARKERS = ['claude', 'fable'] as const;
/**
* 内置 `Explore` 子代理的 inherit cap 是否该关掉。
*
* ## 上游行为(CC 2.1.198 起,CHANGELOG:「now inherits the main session's model (capped
* at opus) instead of running on haiku」;2.1.259 反编译)
*
* 内置 Explore 声明的是 `model: "inherit"`,但派发前先过一层 cap:
*
* ```js
* function FX(agent, mainLoopModel) {
* if (agent.agentType !== "Explore" || agent.source !== "built-in") return agent.model;
* if (env.CLAUDE_CODE_DISABLE_EXPLORE_INHERIT_CAP) return "inherit";
* return r7r(mainLoopModel) ? { inheritCap: "opus" } : "inherit";
* }
* function r7r(m) {
* if (provider() !== "firstParty") return false;
* return !containsAnyWord(m, ["haiku", "sonnet", "opus"]); // 纯子串匹配
* }
* ```
*
* 而 `{ inheritCap: "opus" }` 到了 resolver 里会被拆成裸别名 `"opus"`,之后与「用户手写
* `model: opus`」完全同路 —— **它不是天花板,是直接替换**。
*
* ## 为什么要关
*
* 「在 cap 之内」是靠**模型名里有没有那三个词**判定的。Cindy 的 fp 路由在 CC 眼里是
* firstParty,而经它路由的非 Claude 模型(`gpt-5.6-sol[1m]` 等)名字里三个词都没有,于是
* 被判成「超过 opus」→ 静默改判成 Opus。实测:GPT 会话里 8 次 Explore 派发,3 次没带
* `model` 参数的全部打到 `claude-opus-5[1m]`,跨了供应商与计费(另 5 次调用时显式写了
* 模型,per-invocation 参数优先级更高,照旧生效)。
*
* 上游的意图对 Claude 家族是成立的(别比 Opus 更贵),对它认不出的模型则是把「未知」
* 当成了「更贵」。所以只在后者把开关打开,其余场景一律保持上游行为:
*
* | 主模型 | 结果 |
* |---|---|
* | Opus / Sonnet / Haiku | 不设 —— cap 本来就不触发,行为零变化 |
* | Fable | 不设 —— 保留上游的成本上限 |
* | 非 Claude(GPT / 网关模型…) | 设 —— Explore 跟随主模型 |
*
* 非 firstParty 路由本来就走不到 cap,那里设了也只是 no-op,不额外分支。
*
* ## 已知边界
*
* - **依赖一个未公开的 env**。上游哪天移除,这里静默退回现状(不会崩)。单测钉住的只是本
* 函数的判定表,**钉不住二进制行为** —— 上面那段反编译是 2.1.259
* (`tools/claude/latest.json` 的 pin)的实测结论,升级 CC 后请回到二进制里重新核对
* `FX` / `r7r` 与 `ven`/`Cen`,再决定这张表是否还成立。
* - 本机热切若跨过这张表,由 `applyExploreInheritCapEnv(..., 'replace')` 改字典,下一
* 次 send 重建 Query 让子进程吃到新 env。远端 daemon 烤死 spawn env,跨表则拒绝切模。
*/
export function shouldDisableExploreInheritCap(activeModel: string | undefined): boolean {
const model = activeModel?.trim().toLowerCase();
// 拿不到本次 spawn 的模型时不猜,保持上游行为。
if (!model) return false;
if (EXPLORE_CAP_TIER_WORDS.some((word) => model.includes(word))) return false;
if (CLAUDE_FAMILY_MARKERS.some((word) => model.includes(word))) return false;
return true;
}
/**
* 把 Explore inherit-cap 开关写进(或移出) env 字典。
*
* - `if-undefined`:spawn 用。behaviorFlags / 用户显式设的值优先,只在键缺失时注入 `'1'`。
* - `replace`:本机热切跨策略时用。只动 Cindy 注入的 `'1'` / 缺省,不碰显式覆盖(如 `'0'`)。
*/
export function applyExploreInheritCapEnv(
env: Record<string, string>,
activeModel: string | undefined,
mode: 'if-undefined' | 'replace',
): void {
const disable = shouldDisableExploreInheritCap(activeModel);
if (mode === 'if-undefined') {
if (env[EXPLORE_INHERIT_CAP_DISABLE_ENV] === undefined && disable) {
env[EXPLORE_INHERIT_CAP_DISABLE_ENV] = '1';
}
return;
}
const current = env[EXPLORE_INHERIT_CAP_DISABLE_ENV];
if (current !== undefined && current !== '1') return;
if (disable) env[EXPLORE_INHERIT_CAP_DISABLE_ENV] = '1';
else delete env[EXPLORE_INHERIT_CAP_DISABLE_ENV];
}
/** Cindy 可改写的 cap 开关是否与目标模型失配。显式覆盖(非 `'1'`)视为用户钉死,不算失配。 */
export function exploreInheritCapEnvNeedsSync(
env: Record<string, string>,
activeModel: string | undefined,
): boolean {
const current = env[EXPLORE_INHERIT_CAP_DISABLE_ENV];
if (current !== undefined && current !== '1') return false;
return shouldDisableExploreInheritCap(activeModel) !== (current === '1');
}
/**
* 组装最终注入到 sdkQuery options.env 的字典。
* 顺序:cleanEnv → behaviorFlags → endpoint → authEnv(鉴权最后,避免被 behaviorFlags 覆盖)
*
* `mode` 决定是否继承本地 process.env:
*
* - `'local'` (默认): 继承 cleanProcessEnv() — 本地 sdkQuery 起的子进程要本地
* `PATH` / `HOME` / `USER` / `APPDATA` 才能跑(找 node / git / locale 文件等)。
*
* - `'remote'`: 不继承 process.env, 字典只含 behaviorFlags + endpoint + authEnv +
* 各种 if-undefined 注入的业务 flags(DISABLE_TELEMETRY / PYTHONUTF8 /
* API_TIMEOUT_MS / CLAUDE_ENABLE_STREAM_WATCHDOG 等)。
*
* **为什么必须**: 远端 cc-mgr daemon 收到 startParams.env 后转给远端 SDK,
* daemon 在调用 SDK 前合并自己的进程环境。如果继承了 desktop 的
* `HOME=C:\Users\REMOTE_USER`(Windows) 或 `HOME=/Users/local-user`(mac), 远端
* POSIX 的 cc CLI 就拿到了**错误的 HOME** — Windows 字面字符串带 `C:` 和反斜
* 杠在 macOS 当相对路径,被拼到 cwd 后面,session/memory/snapshot 全落到
* `<cwd>/C:\Users\REMOTE_USER/.claude/...` 这种怪目录里, 用户彻底找不到。
* PATH/APPDATA/TMP 等也类似 — 跨平台 + 跨机器透传必出事。
*
* 零继承后, daemon 显式合并自己 process.env 的真实 POSIX
* `HOME=/Users/<remote-user>` 和正确的 `PATH`, cc CLI 落到正确位置。
*
* 调试开关: 设置 host process.env.XDT_CC_DEBUG_NET=1 开启 cc 子进程网络日志,
* 输出走 stderr → maker-ipc onStderrLine → unified logger (apps/desktop/logs/...)。
* 包含: Anthropic SDK 请求日志 (URL/状态/elapsed) + Node HTTP socket 事件
* (DNS resolve / TCP connect / TLS handshake / 首字节)。海外用户排查代理延迟用。
*/
export async function buildClaudeEnv(
auth: AuthAdapter,
runtimeConfig: AgentRuntimeConfig,
options: ClaudeEnvBuildOptions = {},
): Promise<Record<string, string>> {
const mode = options.mode ?? 'local';
const nativeCliAuth = options.nativeCliAuth === true && mode === 'local';
// remote mode: 从空字典起,绝不继承 desktop 进程的 OS env(详见函数 doc)。
// local mode: 继承 cleanProcessEnv() — 本地子进程需要本地 PATH/HOME 才能跑。
const cleanEnv = mode === 'remote' ? {} : cleanProcessEnv();
const env: Record<string, string> = { ...cleanEnv };
// 函数形态按本次 spawn 的 route context 求值(如 attribution 按凭证形态、Tool Search
// 按来源能力分叉);spawnMode 让 host 区分本机/远端(只对本机有意义的 flag 不注到远端)。
const behaviorFlags =
typeof runtimeConfig.behaviorFlags === 'function'
? runtimeConfig.behaviorFlags({
credentialMode: options.credentialMode,
sessionProviderId: options.sessionProviderId,
spawnMode: mode,
})
: runtimeConfig.behaviorFlags;
if (behaviorFlags) {
Object.assign(env, behaviorFlags);
}
// 远端模式优先用 remoteEndpoint(真上游网关)—— 本地 endpoint 是 loopback proxy URL,
// 远端机器够不到(见 runtime-config.ts remoteEndpoint 文档 + index.ts 的 loopback guard)。
// remoteEndpoint 未设时回落 endpoint(host 不区分远端的旧行为)。
const endpoint =
mode === 'remote' && runtimeConfig.remoteEndpoint
? runtimeConfig.remoteEndpoint
: runtimeConfig.endpoint;
if (nativeCliAuth) {
// behaviorFlags 也不许把订阅会话改道(CLI 缺省即 api.anthropic.com)。
delete env.ANTHROPIC_BASE_URL;
} else if (endpoint) {
env.ANTHROPIC_BASE_URL = endpoint;
}
const authOptions = options.credentialMode
? {
credentialMode: options.credentialMode,
// A remote gateway fallback must not pick credentials from the original subscription.
...(options.credentialMode !== 'gateway-key' && options.sessionProviderId
? { providerId: options.sessionProviderId }
: {}),
}
: options.authModel
? { model: options.authModel }
: undefined;
const authEnv = { ...(await auth.getAuthEnv(authOptions)) };
if (mode === 'remote') {
// CLAUDE_CONFIG_DIR is a host-local path. If an auth adapter injects one
// (older Desktop dev sandboxes used a userData path), forwarding that
// literal path to a different POSIX host makes Claude resolve it relative
// to the remote cwd and write configuration data into the repository.
// The remote cc-manager owns this path and replaces it with its isolated
// ~/.xdt-server/v1/claude-home directory at the RPC boundary.
delete authEnv.CLAUDE_CONFIG_DIR;
}
Object.assign(env, authEnv);
if (nativeCliAuth) {
// fail-closed:订阅会话只用 CLI 自己的登录,host 递来的任何鉴权 / 上游字段一律不带。
for (const key of REMOTE_ROUTE_OVERRIDE_ENV_KEYS) delete env[key];
}
// Claude Code's documented child-agent model override.
//
// `options.subagentModel` 是调用方**已解析过**的决定(见 subagent-model-default.ts):
// - 字符串 → 设该值;
// - `null` → 明确「不要设」—— 用户手写 agent 自己声明了 model,设了会把它静默盖掉;
// - 省略 → 回落读 runtimeConfig(未接入该解析的调用方保持旧行为)。
// 该 env 在平台解析顺序里是最高优先级,所以「不设」是让 frontmatter 生效的唯一办法。
// runtimeConfig 回落分支里路由感知版优先:子代理请求跑在父会话来源上,覆写是否可注入
// 要按该来源判(host 的停用轴按 (来源, 模型) 记账;PR #744 review 第十九轮)。
applySubagentModelEnv(
env,
options.subagentModel !== undefined
? options.subagentModel
: ((runtimeConfig.subagentModelForRoute
? runtimeConfig.subagentModelForRoute(
options.sessionProviderId ?? null,
options.credentialMode,
)
: runtimeConfig.subagentModel
)?.trim() || undefined),
);
// #3557: 网关路由会话把 CLI 内部小模型调用钉到会话自身的 wire 模型。
// if-undefined 守卫:behaviorFlags / 用户显式覆盖优先。
if (options.smallFastModel && env.ANTHROPIC_SMALL_FAST_MODEL === undefined) {
env.ANTHROPIC_SMALL_FAST_MODEL = options.smallFastModel;
}
// 非 Claude 主模型的会话关掉内置 Explore 的 inherit cap ——
// 否则 CC 会把它静默改判成 Opus(判据与代价见 shouldDisableExploreInheritCap)。
applyExploreInheritCapEnv(env, options.activeModel, 'if-undefined');
// 第三道防线: 告诉 CC CLI "provider 路由由 host 接管"。
// CC 内部 filterSettingsEnv 看到此标记后,会从所有 settings-sourced env 中剥掉
// ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN 等 provider 相关字段,
// 防止 workdir/.claude/settings.json 或 ~/.claude/settings.json 的 env 覆盖 app 注入值。
// (第一道: boot 期 stripSensitiveAnthropicEnv 拦用户系统 env;
// 第二道: cleanProcessEnv 拦字典副本里的残留)
// ⚠️ cc >= 2.1.198 语义扩大: 设了此 flag 的子进程**完全不读**本机凭证
// (系统凭证库的 claudeAiOauth、settings 的 apiKeyHelper、/login managed key 全被禁),
// 凭证必须由 host 经上面的 authEnv 显式递入 —— 订阅模式对应 CLAUDE_CODE_OAUTH_TOKEN
// (desktop auth-adapters getAuthEnv 注入), API 模式对应 ANTHROPIC_API_KEY。
// 若 host 只设 flag 不递凭证, cc 毫秒级判 "Not logged in"(2026-07-03 线上事故)。
// 订阅会话(nativeCliAuth)反过来必须**不设**:CLI 要读自己的登录凭证。代价是 CLI 不再
// 剥掉工作区设置里的上游 / 鉴权键(SDK 模式也没有终端的工作区信任确认),所以每次拉起
// CLI 前与会话中途热加载设置时,都由 workspace-settings-guard 拒绝会改写它们的设置。
if (nativeCliAuth) {
delete env.CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST;
} else {
env.CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST = '1';
}
applyClaudeDesktopEntrypoint(env);
// xdt-maker 自己托管会话生命周期和自动任务。Claude Code 原生 cron 会读取
// workdir/.claude/scheduled_tasks.json,并把到期任务作为隐藏 meta prompt 注入
// 当前 SDK 会话;这会污染正在处理的用户任务。host-managed 会话必须强制关闭。
env.CLAUDE_CODE_DISABLE_CRON = '1';
const modelContextWindows = serializeModelContextWindows(options.modelContextWindows);
if (modelContextWindows) {
env[MAKER_MODEL_CONTEXT_WINDOWS_ENV] = modelContextWindows;
} else {
delete env[MAKER_MODEL_CONTEXT_WINDOWS_ENV];
}
const activeContextWindow = options.modelContextWindows?.find(
(model) => model.id === options.activeModel,
)?.contextWindow
?? options.modelContextWindows?.find(
(model) => model.id.replace(/\[1m\]$/i, '')
=== options.activeModel?.replace(/\[1m\]$/i, ''),
)?.contextWindow;
applyClaudeContextWindow(env, activeContextWindow, runtimeConfig.autoCompactThresholdPct);
// 关掉 CC SDK 内部的遥测 / 错误上报 / OTEL metrics export。
// 我们走自家 compat proxy + xd.inc token, 这些字段都是直打 api.anthropic.com 的
// 官方 endpoint, 必然 401 (token 不被认), 只产生日志噪音不影响功能。
// 关闭后这三类后台请求都不会发起:
// - DISABLE_TELEMETRY=1 : metrics_enabled / claude_code/metrics 上报
// - DISABLE_ERROR_REPORTING=1 : Sentry 类自动错误样本
// - OTEL_SDK_DISABLED=true : PeriodicExportingMetricReader 周期导出
// 用户 env 没显式覆盖才注入 (留个手动开 telemetry 排 SDK bug 的口子)。
if (env.DISABLE_TELEMETRY === undefined) env.DISABLE_TELEMETRY = '1';
if (env.DISABLE_ERROR_REPORTING === undefined) env.DISABLE_ERROR_REPORTING = '1';
if (env.OTEL_SDK_DISABLED === undefined) env.OTEL_SDK_DISABLED = 'true';
// Windows 下 Python piped stdout 默认走 locale encoding(cp936/GBK), 不看 chcp 65001。
// 强制 UTF-8 避免 Bash 工具执行 python 命令时中文乱码。跨平台设置无副作用。
if (env.PYTHONUTF8 === undefined) env.PYTHONUTF8 = '1';
if (env.PYTHONIOENCODING === undefined) env.PYTHONIOENCODING = 'utf-8';
applyPlainTextTerminalEnv(env);
// 上游流式中途静默断流的"透明自愈":启用 cc-code 子进程内置的原生 inactivity
// stream watchdog。它盯每条流式 HTTP 响应的 chunk 间隔(每 chunk 重置, 不误杀
// 健康活跃流), 静默超阈值后在子进程内部降级非流式 + withRetry, 在同一个 SDK
// query 里恢复 —— 对 maker 完全无感, 不中断 turn / 不提示用户。这填补了官方
// desktop 的洞: API_TIMEOUT_MS 只覆盖初始 fetch(), 不覆盖流式 body(见 cc-code
// claude.ts:1868-1873 注释), 单靠它流到一半断会挂死。
// - CLAUDE_ENABLE_STREAM_WATCHDOG : 开关(默认关), isEnvTruthy 收 1/true/yes/on
// - CLAUDE_STREAM_IDLE_TIMEOUT_MS : idle 阈值。cc 默认 90s 在 Opus xhigh/max 长
// thinking 上会误伤, 用 300s(maker 已验证过、只在真断流时触发的安全值)
// - API_TIMEOUT_MS : 对标官方 desktop(900s), 兜底初始 fetch + 非流式 fallback 请求
// 注意: 不要设 CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK —— 保持默认开, 透明恢复才生效。
// 用户显式覆盖优先(if undefined 才注入)。
if (env.CLAUDE_ENABLE_STREAM_WATCHDOG === undefined) env.CLAUDE_ENABLE_STREAM_WATCHDOG = 'true';
if (env.CLAUDE_STREAM_IDLE_TIMEOUT_MS === undefined) env.CLAUDE_STREAM_IDLE_TIMEOUT_MS = '300000';
if (env.API_TIMEOUT_MS === undefined) env.API_TIMEOUT_MS = '900000';
// 网络调试: host 设 XDT_CC_DEBUG_NET=1 即开启。该 env 由「设置 → About 的 Debug 日志开关」
// 经 ccSetDebugNet IPC 写入 (见 bootstrap-electron.ts), dev 模式硬开。开关关闭 ⇒ 该 env 被
// delete ⇒ 本块不执行 ⇒ 不注入任何调试 env (默认关闭, 生产场景日志会爆炸)。
// ANTHROPIC_LOG=debug: Anthropic SDK 打完整请求 (含 headers, 如 `anthropic-beta: fast-mode-*`)
// + 响应, 用于核验 fast / 路由头是否真的上到链路 —— info 级只有 URL+status+elapsed, 看不到
// header。代价是日志更大 (含请求体), 仅在开关打开时如此, 可由 host 显式 export ANTHROPIC_LOG
// 覆盖 (?? 保留逃生口, 如设回 info 降噪)。
// NODE_DEBUG=http,https,net,tls: Node 内置 http/socket trace, 能看到 DNS / TCP / TLS 握手时序
// (海外用户排查 llm-proxy 代理延迟用)。
if (process.env.XDT_CC_DEBUG_NET === '1') {
env.ANTHROPIC_LOG = process.env.ANTHROPIC_LOG ?? 'debug';
env.NODE_DEBUG = process.env.NODE_DEBUG ?? 'http,https,net,tls';
}
return env;
}
/** Apply the active working budget on both first spawn and history-preserving rebuilds. */
export function applyClaudeContextWindow(
env: Record<string, string>,
activeContextWindow: number | undefined,
autoCompactThresholdPct: number | undefined,
): void {
if (
activeContextWindow !== undefined
&& Number.isFinite(activeContextWindow)
&& activeContextWindow > 0
) {
env.CLAUDE_CODE_MAX_CONTEXT_TOKENS = String(Math.floor(activeContextWindow));
// Known Claude models resolve their native capacity before MAX_CONTEXT_TOKENS.
// The working window is a separate native control, used by auto-compaction.
env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = String(Math.floor(activeContextWindow));
} else {
delete env.CLAUDE_CODE_MAX_CONTEXT_TOKENS;
delete env.CLAUDE_CODE_AUTO_COMPACT_WINDOW;
}
const configuredCompactPct = Math.round(autoCompactThresholdPct ?? Number.NaN);
if (configuredCompactPct >= 50 && configuredCompactPct <= 95) {
// Claude 2.1.259 clamps AUTO_COMPACT_WINDOW to at least 100K. Preserve
// smaller user budgets through its native percentage override instead of
// silently allowing them to grow to 100K. Native output/summary reserves
// can trigger compaction earlier, never later than the requested budget.
const windowScale = activeContextWindow !== undefined && activeContextWindow > 0
? Math.min(1, activeContextWindow / 100_000) : 1;
env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE = String(configuredCompactPct * windowScale);
} else {
delete env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE;
}
}