深入 Cline SDK 的 cline/shared 共享原语包路径解析、会话配置、日志契约与跨客户端 DTO【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline本文基于 Cline 仓库中cline/shared包的官方说明文档系统讲解这个实验性experimental共享包的核心职责它如何以./storage等子路径导出 Node 端文件系统路径解析器、如何定义跨客户端统一的BasicLogger日志契约、如何集中AgentMode/SessionPromptConfig等会话配置原语、以及它是如何承载cline/cli与宿主应用之间共享的聊天/Provider RPC 载荷 DTO 的。读完本文你可以在基于 Cline SDK 构建宿主、运行时或 IDE 扩展时正确复用这些跨包契约避免重复定义类型与重复推导数据目录。包定位跨包原语的统一出口cline/shared在 sdk/packages/shared/README.md 中被标注为 experimental 包其定位是own shared cross-package primitives即持有跨包共享的原语session common types/utilities。它不是某个具体功能的实现包而是 Cline 各包core、agents、CLI、宿主应用之间的契约层与工具层日志类型、会话配置形状、hook 会话上下文、运行时载荷 DTO 都在这里集中定义避免每个宿主重复定义相似字段。从 sdk/packages/shared/package.json 可以看到该包的工程形态多子路径导出exports 字段cline/shared按子路径拆分为多个独立入口宿主可以只引入自己需要的部分.根入口同时区分browser条件导出./dist/index.browser.js与 Node 入口./dist/index.js./browser、./types、./storage、./db、./node、./automation、./remote-config运行环境engines.node 22构建脚本为BUILD_MODEpackage bun bun.mts单元测试走vitest run --config vitest.config.ts。依赖极窄仅aws4fetch、jsonrepair、zod、zod-to-json-schema四个运行时依赖符合共享原语包不引入重依赖的设计取向。README 中的两条中央文档入口也值得保留包级总览见 sdk/packages/README.md架构与交互见 sdk/ARCHITECTURE.md。storage 子路径导出Node-only 文件系统路径解析器README 明确指出Node-only 的文件系统路径解析器位于cline/shared/storage子路径导出下代表性函数为resolveClineDataDir、resolveDbDataDir、resolveSessionDataDir、resolveTeamDataDir。之所以单独走./storage子路径而不是根入口正是因为这些函数依赖node:fs/node:path等 Node 运行时能力不能进入浏览器构建对应 package.json 中.入口的browser条件导出走的是index.browser.js而./storage只声明了typesimport两个条件。实现位于 sdk/packages/shared/src/storage/paths.ts其核心模式高度一致优先读取显式环境变量否则从 Cline 数据根目录派生。以四个代表性函数为例paths.ts L179-L245export function resolveClineDataDir(): string { const explicitDir process.env.CLINE_DATA_DIR?.trim(); if (explicitDir) { return explicitDir; } return join(resolveClineDir(), data); } export function resolveSessionDataDir(): string { const explicitDir process.env.CLINE_SESSION_DATA_DIR?.trim(); if (explicitDir) { return explicitDir; } return join(resolveClineDataDir(), sessions); } // resolveTeamDataDir - CLINE_TEAM_DATA_DIR默认 data/teams // resolveDbDataDir - CLINE_DB_DATA_DIR默认 data/db整理成一张可操作的参数表函数环境变量覆盖默认值resolveClineDataDir()CLINE_DATA_DIRClineDir/dataresolveSessionDataDir()CLINE_SESSION_DATA_DIRdata/sessionsresolveTeamDataDir()CLINE_TEAM_DATA_DIRdata/teamsresolveDbDataDir()CLINE_DB_DATA_DIRdata/dbresolveConnectorDataDir()CLINE_CONNECTOR_DATA_DIRdata/connectors这套环境变量可覆盖 目录层级派生的设计有一个直接收益CLI、hub 守护进程、IDE 宿主等所有客户端只要遵守同一组环境变量约定就能落到同一份数据目录上无需各自实现路径推导。sdk/packages/shared/src/storage/paths.test.ts 中的用例印证了这一点例如设置CLINE_DATA_DIR/tmp/cline-data后断言resolveClineDataDir()为/tmp/cline-data、resolveSessionDataDir()为/tmp/cline-data/sessions、resolveTeamDataDir()为/tmp/cline-data/teams、resolveDbDataDir()为/tmp/cline-data/db。paths.ts 中还有一组围绕 connector 的路径解析例如resolveConnectorLogPath(channel, instanceKey)会把非法字符替换为_后落到data/logs/connectors/channel/key.log——源码注释解释了它放在共享包的原因CLI直接 spawn 分离 connector与 hub supervisorspawn 并回收 connector必须对该日志路径达成一致所以它住在两边都不属于的公共位置。附赠能力容错 Unicode 文件名解析同目录下的 sdk/packages/shared/src/storage/path-resolution.ts 提供了一个值得注意的健壮性工具resolveExistingFilePathmacOSSonoma 及以后在截屏文件名 AM/PM 前插入 U202F 窄不换行空格当路径经过剪贴板、终端、粘贴解码层后被归一化成普通空格时字面fs.stat会抛 ENOENT。该函数按顺序尝试 macOS AM/PM 变体、NFD 归一化变体、弯引号U2019变体最后回退到父目录枚举做规范空白折叠匹配从而把被打伤的路径恢复到真实磁盘条目。对需要在多种客户端间传递文件路径的 Cline 宿主来说这是一个典型的共享包收编边角坑位的例子。BasicLogger跨客户端日志契约README 的第二块内容是跨客户端日志契约cline/shared导出BasicLogger让 runtime、SDK 与宿主应用共享同一个 logger 类型。实现只有 45 行位于 sdk/packages/shared/src/logging/logger.tsexport interface BasicLogger { /** 冗长诊断宿主应在非调试模式下 no-op 或过滤 */ debug: (message: string, metadata?: BasicLogMetadata) void; /** 运维消息取代旧版 info / 非 error warn 的拆分 */ log: (message: string, metadata?: BasicLogMetadata) void; error?: ( message: string, metadata?: BasicLogMetadata { error?: unknown }, ) void; }设计要点有三刻意保持最小接口。debug/log必填error可选——源码注释说明宿主如果没有独立 error 通道可以走log并在BasicLogMetadata.severity中标error。这解释了为什么 metadata 里有一个severity?: info | warn | error字段它是给那些把单一log方法映射到多级输出如 Pino 的 info vs warn的后端做消歧用的。BasicLogMetadata约定了一批跨组件查询键sessionId、runId、providerId、toolName、durationMs同时继承Recordstring, unknown允许宿主自由扩展。noopBasicLogger作为全 no-op 安全默认值注入缺失时可直接兜底。这种接口 约定字段 no-op 兜底的三件套使得宿主可以把自己的 loggerpino、VS Code 的日志 API 等适配进来而 SDK 内部代码永远只面向BasicLogger编程。会话配置原语AgentMode 与三个 Session 配置接口README 强调会话配置原语被集中在此so hosts/runtimes can compose one base shape instead of redefining similar fields repeatedly宿主/运行时组合出一个基础形状而不是反复重定义相似字段。实现位于 sdk/packages/shared/src/session/runtime-config.ts四个原语在 sdk/packages/shared/src/index.ts 的 L568-L581 统一从根入口导出。export type AgentMode act | plan | yolo | zen; export interface SessionPromptConfig { mode?: AgentMode; systemPrompt?: string; rules?: string; maxIterations?: number; } export interface SessionWorkspaceConfig { cwd: string; workspaceRoot?: string; } export interface SessionExecutionConfig { enableTools: boolean; teamName?: number | undefined extends undefined ? string : never; // 实际为 teamName?: string missionLogIntervalSteps?: number; missionLogIntervalMs?: number; maxConsecutiveMistakes?: number; toolPolicies?: Recordstring, ToolPolicy; }上面SessionExecutionConfig按源码原样为teamName?: stringtoolPolicies即 README 所说的canonicalToolPolicymap shapeToolPolicy类型来自 sdk/packages/shared/src/llms/tools.ts。三个接口分工清晰SessionPromptConfig提示词维度——模式、系统提示词、rules、最大迭代数SessionWorkspaceConfig工作区维度——cwd必填、workspaceRoot可选SessionExecutionConfig执行维度——工具开关唯一必填的enableTools、团队名、任务日志节奏、连续错误上限、按工具名的策略表。同一文件还定义了运行期配置扩展原语供宿主裁剪默认加载的扩展类型export type RuntimeConfigExtensionKind | rules | skills | workflows | plugins | hooks; export const DEFAULT_RUNTIME_CONFIG_EXTENSIONS RUNTIME_CONFIG_EXTENSION_KINDS; // 默认全部启用并配套isRuntimeConfigExtensionKind类型守卫、parseRuntimeConfigExtensions从未知输入过滤去重出合法 kind 数组、hasRuntimeConfigExtension未显式指定时按默认全开判断三个辅助函数。会话标识方面sdk/packages/shared/src/session/index.ts 提供createSessionId(prefix, suffix)用 nanoid 的小写字母数字字母表生成 5 位随机串拼上毫秒时间戳形如prefixts_nanoid5suffix时间戳在前保证可排序随机后缀避免并发碰撞。Hook 会话上下文原语README 声明该包还导出 hook 会话上下文原语used across agents/core/CLIHookSessionContext、resolveHookSessionContext(...)、resolveRootSessionId(...)、resolveHookLogPath(...)。当前源码中前两者的实现在 sdk/packages/shared/src/session/hook-context.ts并由 sdk/packages/shared/src/index.ts L552-L560 导出export interface HookSessionContext { rootSessionId?: string; } export type HookSessionContextProvider | HookSessionContext | ((input?: HookSessionContextLookup) HookSessionContext | undefined); export function resolveHookSessionContext( provider?: HookSessionContextProvider, input?: HookSessionContextLookup, ): HookSessionContext | undefinedresolveHookSessionContext的设计点在于provider 既可以是静态上下文对象也可以是一个函数由调用方在 hook 触发时惰性求值HookSessionContextLookup提供hookName/conversationId/agentId/parentAgentId供求值使用解析结果会对rootSessionId做 trim 归一化空值统一收敛为undefined。resolveRootSessionId则是从上下文中取根会话 ID 的轻量辅助。需要如实说明的是在检索当前仓库源码时resolveHookLogPath仅在 sdk/packages/shared/README.md 中出现当前session/hook-context.ts与根入口导出表中未见同名函数——从源码结构看该函数可能已被移除或改名而 hook 日志路径目前以事件载荷字段的形式存在sdk/packages/shared/src/hooks/events.ts L277-L282 的HookEventPayloadSchema中sessionContext对象包含可选的rootSessionId与hookLogPath两个字符串字段。也就是说hook 写日志的位置这一信息通过 hook 事件 schema 的sessionContext.hookLogPath在 hook 执行侧传递。跨客户端运行时载荷 DTOrpc/runtime 契约README 后半部分说明cline/shared还导出跨客户端运行时载荷 DTO供多个宿主cline/cli、cline/code复用so request/response contracts are not duplicated outside transport wiring请求/响应契约不在传输接线之外重复定义。实现集中在 sdk/packages/shared/src/rpc/runtime.ts共 468 行根入口 L412-L456 将其类型全部转出。聊天运行时载荷export interface ChatRuntimeConfig extends SessionPromptConfig { cwd?: string; apiKey?: string; logger?: RuntimeLoggerConfig; enableTools: boolean; enableSpawn?: boolean; enableTeams?: boolean; disableMcpSettingsTools?: boolean; autoApproveTools?: boolean; missionStepInterval?: number; missionTimeIntervalMs?: number; timeoutSeconds?: number; toolPolicies?: SessionExecutionConfig[toolPolicies]; toolExecutors?: HubToolExecutorName[]; configExtensions?: RuntimeConfigExtensionKind[]; } export interface ChatStartSessionRequest extends ChatRuntimeConfig { sessionId?: string; workspaceRoot: string; provider: string; model: string; source?: string; interactive?: boolean; }可以看到 RPC 层与上文会话原语是组合关系ChatRuntimeConfig extends SessionPromptConfig因此继承mode/systemPrompt/rules/maxIterationstoolPolicies直接复用SessionExecutionConfig[toolPolicies]的类型configExtensions复用RuntimeConfigExtensionKind[]。这正是 README 所说compose one base shape的落地会话配置原语在 RPC 契约中被二次组合而非复制。README 提到的initialMessages、可选toolPolicies、用于默认系统提示词组装的可选rules以及让宿主把序列化日志配置跨传输边界传过去的可选loggerRuntimeLoggerConfig在源码中均可对应到字段export interface RuntimeLoggerConfig { enabled?: boolean; level?: trace | debug | info | warn | error | fatal | silent; destination?: string; name?: string; bindings?: Recordstring, string | number | boolean; }其中bindings是 README 特别点名的能力宿主可以为所有运行时日志记录附加稳定的上下文字段例如clientId、clientType、clientApp从而让远端 runtime 产出的日志在宿主侧可按客户端维度检索。回合与结果侧同样有完整契约ChatRunTurnRequest携带config一个完整的ChatStartSessionRequest、prompt、可选attachmentsuserImages: string[]与userFiles: ChatAttachmentFile[]以及delivery?: queue | steerChatTurnResult返回text、带缓存 token 与成本信息的usageinputTokens/outputTokens/cacheReadTokens?/cacheWriteTokens?/totalCost?、iterations、finishReason以及每次工具调用的明细数组toolCalls: ChatToolCallResult[]含name/input/output/error/durationMs。同一文件还定义了ChatStartSessionArtifactssessionId/manifestPath/messagesPath说明启动会话会落盘 manifest 与消息文件并返回其路径。Provider 运行时载荷Provider 侧契约覆盖目录查询、模型操作与增改 ProviderProviderActionRequest、ProviderCatalogResponse、ProviderOAuthLoginResponse以及 README 点名的细粒度复用契约AddProviderActionRequest、SaveProviderSettingsActionRequest、ProviderCapability由ProviderCapabilitySchema推导与 OAuth 相关的 Provider ID 类型。它们集中在 runtime.ts L271-L414 附近ProviderSettingsActionRequest等联合类型把目录/模型操作与 settings 宿主的 add/save 操作统一在一棵类型树下——这意味着一个实现ProviderClient的宿主可以处理整个 Provider 操作面而无需为每个 action 单独定义 DTO。使用建议把 cline/shared 当作契约层消费基于以上源码事实对要在 Cline 生态里构建宿主或 SDK 集成的开发者有三条可直接落地的实践数据目录不要自己拼路径。凡是涉及会话、团队、数据库、connector 落盘一律调用cline/shared/storage的resolve*函数并遵守CLINE_DATA_DIR等环境变量约定保证多客户端数据一致实现见 sdk/packages/shared/src/storage/paths.ts回归见 paths.test.ts。日志注入统一实现BasicLogger。宿主把 pino/VS Code logger 适配成{ debug, log, error? }缺省用noopBasicLogger跨传输边界传日志配置时用RuntimeLoggerConfig并善用bindings打上clientId等稳定维度。RPC 契约不要本地复刻。跨客户端的请求/响应一律引用ChatStartSessionRequest、ChatRunTurnRequest、ChatTurnResult、ProviderActionRequest等导出类型需要裁剪默认加载的扩展时用parseRuntimeConfigExtensions/hasRuntimeConfigExtension保持与 core 相同的默认全开语义。需要说明的适用前提该包在 README 中自标 experimental当前版本为 package.json 中的0.0.82要求 Node 22对resolveHookLogPath等 README 与源码存在出入的导出以仓库当前src/与根入口的实际导出为准。包级全景core/llms/agents 各包职责与交互可继续阅读 sdk/packages/README.md 与 sdk/ARCHITECTURE.md。【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考