CreateSessionOptions

createSession 的选项。三档模型来源互斥:令牌档(token + baseUrl,模型与能力位由平台 bundle 供给)/ 托管档(model 为别名字符串,五层配置装配)/ 注入档(client + model 对象,零配置零 IO); 其余为工具与权限、会话参数、持久化与快照 / 恢复 / fork 三组可选项。

属性

adjudication?

optional adjudication?: AdjudicationOptions;

裁决人(仅令牌档):bundle 生效裁决人档缺省即装配——「本应 ask」的工具调用先经裁决人:判危险按姿态落地 (人在环 → 经 permission.askUser 携理由交用户终审;无人环 → deny 理由回喂模型),判安全且资格半径覆盖 → 放行,缺省安全的操作恒不送裁决人。姿态缺省按 askUser 在场推导;enabled:false 回到 default 模式现状; 与 permission.mode 同现 fail-fast。托管/注入档无任命来源,传本位 fail-fast。

---

baseUrl?

optional baseUrl?: string;

平台 API 基址(令牌档必填,如 https://api.example.com)

---

capabilities?

optional capabilities?: AppCapabilities;

能力位档;缺省 DEFAULT_APP_CAPABILITIES(令牌档由 bundle 供给)

---

checkpoints?

optional checkpoints?: SessionCheckpointOptions;

上下文快照:完整上下文的自包含只读拷贝,可列举 / 可恢复 / 可删除。落点三选一:store (自建 CheckpointStore)> dir(独立目录,独立生命周期)> 缺省同居——会话 store 自带的 checkpoints(createFileSessionStore = <sessionDir>/checkpoints,随会话删除)。三者皆缺 = 快照未接线:checkpoint()/listCheckpoints()/deleteCheckpoint() 抛 checkpoints_not_wired, restore() 返回 rejected:'store_not_wired',compact() 缺省不落快照(显式 checkpoint:true 才抛)。

---

client?

optional client?: ModelClient;

注入模式的模型客户端(与 model 对象成对;测试传 scripted client)

---

compaction?

optional compaction?: false | QueryCompactionOptions;

上下文压缩(kernel 自动压缩):缺省 {}(自动压缩,仅上下文窗口已知的轮生效——阈值代数依赖窗口, 与 TUI/serve 同守卫);false 显式禁用。

---

config?

optional config?: LoadedConfig;

已装载配置注入缝:提供时跳过 loadConfig

---

contextWindowTokens?

optional contextWindowTokens?: number;

注入模式的上下文窗口(托管模式自 capability.maxContext 取,忽略本值)

---

cwd?

optional cwd?: string;

项目层配置发现起点与工具 cwd;缺省 process.cwd()

---

env?

optional env?: Record<string, string | undefined>;

环境变量注入缝;缺省 process.env

---

fetchImpl?

optional fetchImpl?: any;

fetch 注入缝(透传协议适配器)

---

fork?

optional fork?: {
  checkpointId: string;
  sessionId: string;
};

fork 快捷形 = fork() + resume:以 store 里源会话 sessionId 的快照 checkpointId 建出新会话 记录(源会话零改动)并立即打开它;新会话事件流紧随 session.created 签发 session.forked{ sourceSessionId, checkpointId, sessionId }。 须与 store 同给(新会话落在该 store);与 resume / initialMessages 互斥(同给 fail-fast invalid_options,先于任何 IO);sessionId 同给时 = 新会话 id。快照经与 checkpoints 选项同一落点解析读取(store > dir > 会话 store 同居);快照不存在抛 checkpoint_not_found。

checkpointId

checkpointId: string;

sessionId

sessionId: string;

---

initialMessages?

optional initialMessages?: readonly IRMessage[];

历史预载(恢复场景):后续轮以「预载历史 + 新 user 消息」起步

---

loadOptions?

optional loadOptions?: Omit<LoadConfigOptions, "cwd" | "env">;

loadConfig 其余注入缝(fs/homedir/platform;测试 hermetic 用)

---

maxOutputTokens?

optional maxOutputTokens?: number;

注入模式的输出上限(maxTokens 事前钳制上界;托管模式自 capability.maxOutput 取,忽略本值)

---

maxTokens?

optional maxTokens?: number;

缺省 8192

---

maxTurnsPerQuery?

optional maxTurnsPerQuery?: number;

单轮 modelTurns 护栏;缺省 200(与 serve 对齐)

---

mcp?

optional mcp?: McpSessionOption;

MCP 外接:McpHost 实例 = 应用级共享(跨会话复用连接,生命周期归调用方 dispose); { servers } 选项对象 = 会话级临时 host,会话 close 时自动断连收口。受 mcp 能力位。

---

model?

optional model?: string | ResolvedModel;

模型档(三档判定):

• 字符串(别名/ref)→ 托管模式(五层配置)或令牌模式(bundle 别名, token 在场时);缺省 ‘main’;
• ResolvedModel 对象 → 注入模式,必须与 client 成对提供。

---

onDecision?

optional onDecision?: (record) => void;

权限终局审计记录出口(kernel onDecision 缝;ToolDecisionRecord 与 cli decisions.jsonl 行同形, 含机器放行 classifier / mode)。缺省:裁决人终局(source ‘classifier’)经 onWarning / onPlatformWarning 通报 permission_decided;传自己的写入器即接管,传 () => {} 静默。事件流本身已携 tool.permission.decided{allow|deny, decisionSource}(含机器放行),本缝是审计半边。

参数

record

ToolDecisionRecord

返回

void

---

onHistoryCommit?

optional onHistoryCommit?: (history, meta) => void | Promise<void>;

可注入持久化缝(形态对齐 cli 的 onHistoryCommit):每轮终态收口(历史快照已就位) 时捕获全量历史深拷贝，按会话提交顺序回调，存到哪由开发者决定。缺省缺席 = 纯内存 零变化(SDK 恒不引入任何隐式落盘)。 meta.rewritten:本轮历史前缀被就地改写(session.compacted 压缩折叠, 或 session.microcompacted 旧 tool_result 原位存根化——SDK 无 CLI 的 journal 存根重演机制,对落盘方两者同为「已存内容不再与内存对齐」), 落盘方不得按长度增量追加,须整卷轮换。 回调抛错(含异步 reject)恒不破会话主流程:吞错并合成 turn.error(scope=‘sdk.persistence’)入事件流;事件流已终结时退化 console.warn(错误不静默消失)。rewritten 提交失败后,下一次提交恒再以 rewritten:true 交付 (存储与回调独立内存位),落盘方不会只凭「本轮无改写」走增量径而留下「旧前缀 + 新尾巴」拼接体。 idle()/session.ended 仍不等异步提交；需要真实完成使用 drain()/closeAsync()。 回调中不得等待本会话 drain()，否则会等待回调自身；retryPersistence 不重放回调。

参数

history

readonly IRMessage[]

meta

HistoryCommitMeta

返回

void | Promise<void>

---

onInputsConsumed?

optional onInputsConsumed?: (texts) => void;

Actual user input incorporation; not acceptance or a new turn.

参数

texts

readonly string[]

返回

void

---

onPlatformWarning?

optional onPlatformWarning?: (warning) => void;

平台提示帧承接(仅令牌档产生;其余档恒不触发)。平台以 t.warn 结构化告知非致命降级 (如 thinking_unavailable_on_face:思考被请求而当前供应商面无从外露,回答照常仅无思考; balance_low:余额预警)。缺席时缺省承接 = console.warn 每码一次(告知恒不静默蒸发); 提供回调即全量接管(不去重,原始帧逐一交付,呈现策略归开发者)。

参数

warning

PlatformWarning

返回

void

---

onWarning?

optional onWarning?: (warning) => void;

通用告警通道:平台提示帧(source:'platform',与 onPlatformWarning 同源同 code)与 SDK 自身非致命提示 (source:'sdk':cwd_mismatch_on_restore / cwd_mismatch_on_resume)统一汇入。与 onPlatformWarning 同给时平台告警各到一次不重复(后者是已发版的平台子集通道,恒不收 sdk 源)。缺席时:平台源按 onPlatformWarning / console.warn 现状回落;sdk 源回落为 turn.error{scope:'sdk.notice', recoverable:true} 入事件流(提示不丢)。

参数

warning

SdkWarning

返回

void

---

permission?

optional permission?: PermissionOptions;

---

promptChannel?

optional promptChannel?: PromptChannel;

AskUser 工具交互通道;缺省 UnavailableChannel(结构化降级,不挂起)

---

resume?

optional resume?: {
  sessionId: string;
  store: SessionStore;
};

一等恢复:自 store 取回历史与 meta 预载(与 initialMessages 互斥; sessionId 同给时必须与 resume.sessionId 一致)。resume 径内置配对治理 (repairHistoryPairing):断尾 tool_call 补 isError 占位、孤儿 tool_result 截断到干净边界——kernel 对 initialMessages 原样收不校验, 治理保证 wire 恒不 400。目标不存在抛 TansrSdkError(‘session_not_found’); 存储损坏由 store.get 结构化上抛(恒不静默)。

sessionId

sessionId: string;

store

store: SessionStore;

---

sessionId?

optional sessionId?: string;

缺省 randomUUID()

---

signal?

optional signal?: any;

会话级中断信号:abort 即 close(运行中轮先优雅中止,尾部事件不丢)

---

skills?

optional skills?: SdkSkillsOptions;

skills 注入:custom(defineSkill 内联)+ dirs(<name>/SKILL.md 目录)。SDK 恒零发现 (不扫 ~/.tansr 与 cwd);受 skills 能力位。

---

store?

optional store?: SessionStore;

在场时自动接管会话登记(store.create,幂等;令牌档的平台会话 ULID 映射随登记落 SessionRecordMeta)与每轮落卷(store.commit; store 先行、onHistoryCommit 回调后行,失败面同 sdk.persistence 吞错 纪律)。与 resume 正交:续存一个恢复的会话把同一 store 同时传两处。 缺席 = 纯内存零变化(SDK 恒不引入任何隐式落盘)。

---

system?

optional system?: IRSystemSegment[];

业务提示词：平台 fallback 策略下显式值（含 []）覆盖；prepend 策略保留平台段在前。SDK 段创建时固定；平台正文和策略在每个新轮前自动刷新。

---

systemAppend?

optional systemAppend?: IRSystemSegment[];

业务段选定后追加的宿主指南，不触发平台默认覆盖；权限与工具指南仍独立装配。

---

thinking?

optional thinking?: {
  budget?: number;
};

思考生成(生成面旋钮;呈现面走 SessionView 的 delivery 选项,两旋钮 正交):逐轮透传 IRRequest.thinking(budget = 思考 token 预算,按模型 方言映射)。缺省缺席 = 不注入(沿模型/适配器缺省,多数模型即不产思考)。 会话中可经 setThinking 动态换,下一轮生效。

budget?

optional budget?: number;

---

token?

optional token?: string;

app_user 短期令牌(开发者服务端换发;终端分发形态)。在场即令牌档: 模型与能力位由平台 bundle 供给,恒零本地配置 IO(config/loadOptions/ capabilities 均不可同给)。

---

tools?

optional tools?: SdkToolsOptions;

三环工具入口:builtin(环2 内置,词表逐名)/ platform(环3 平台能力,现只校验位)/ custom (环1 defineTool 产物)。缺席 = 装配能力位放行的全部内置工具;tools: { builtin: [] } = 零内置。

このページは役に立ちましたか？

はいいいえ