t3code 客户端运行时包 t3tools/client-runtime面向 Web 与移动端的共享客户端行为架构解析【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code本文以 t3code 开源仓库中 packages/client-runtime/README.md 为骨架深入剖析该包的设计哲学如何通过按子路径导出subpath exports组织 Web 与移动端共享的客户端逻辑如何划分授权、连接、环境、RPC、语音输入等能力边界以及connection如何组合authorization、relay、rpc形成监督者式的环境会话管理体系。读完本文你将掌握该包全部公共子路径的职责划分、依赖方向约束以及如何在应用侧以最窄子路径完成正确导入。一、包定位没有根导出no root export的共享客户端库t3tools/client-runtime是 t3code monorepo 中专门承载Web 与移动端共享客户端行为的包其源码位于 packages/client-runtime/src。它被apps/web与apps/mobile两个平台应用共同消费而平台差异原生能力、持久化方案则由外部注入的platform服务来抽象。该包在 package.json 中声明为private: true仅用于仓库内部不会发布到公共 registrytype: module使用 ESM 模块规范依赖t3tools/contracts与t3tools/shared两个 workspace 包以及effect、unified、remark-parse、micromark-extension-directive等后者服务于 Markdown 解析相关能力如markdown-links、markdown-images。最重要的设计约束是这个包没有任何根导出root export。也就是说你无法通过import { X } from t3tools/client-runtime一次性拿到所有 API。所有公共 API 都按子路径组织每个子路径对应一个明确的职责域。这一约束带来的好处有三点依赖清晰调用方只依赖自己真正用到的能力编译器可以精确追踪体积可控Tree-shaking 与代码分割在 ESM 环境下更加彻底API 边界可审计哪些文件是公共边界、哪些是内部实现一目了然。二、公共子路径全景一张表看懂能力边界README 用一张表概括了全部公共子路径及其职责。下表完整继承并补充了实际 exports 映射依据 package.json 的exports字段子路径职责实际入口文件exports 映射authorizationBearer 与 DPoP 授权以及 token 持久化契约src/authorization/index.tsconnection目标targets、目录catalog、监督supervision、重试、注册表与 onboardingsrc/connection/index.tsenvironment环境标识、描述符、端点与作用域密钥scoped keyssrc/environment/index.tserrors共享客户端错误检查src/errors/index.tsoperations多步骤应用工作流src/operations/index.tsoperations/projects多步骤项目创建工作流src/operations/projects.tsplatform平台能力与持久化服务契约src/platform/index.tsrelay托管 relay API 与环境发现src/relay/index.tsrpcHTTP/RPC 客户端、协议、会话与订阅src/rpc/index.tsstate/domain聚焦的共享状态、保留策略、reducer 与 Atom 构造器src/state/*.tsvoice-input录音生命周期、转写契约与草稿插入src/voice-input/index.ts除了 README 表格列出的子路径仓库还通过exports暴露了一批单文件子路径它们与表格中的领域子路径平级属于同一套窄导入体系的组成部分包括load-balancingsrc/load-balancing.ts负载均衡相关逻辑markdown-links/markdown-images/media-reference/media-source/media-actionsMarkdown 链接、图片与媒体资源的解析和处理codex-file-citations/codex-artifact-templates/codex-markdown-directivesCodex 相关的文件引用、产物模板与 Markdown 指令file-preview文件预览逻辑text-paste文本粘贴处理project-favicon-cache项目 favicon 缓存pending-requests挂起请求管理providerSkillsprovider 技能查询thread-pull-request-compatibility线程与 PR 兼容层work-log/*工作日志的用户输入、展示、命令标签与滚动锚点work-log/user-input、work-log/presentation、work-log/tool-presentation、work-log/command-label、work-log/scroll-anchor。state 域最典型的窄导入实践state是子路径数量最多的领域。README 特别强调不存在一个宽泛的state导出必须使用领域路径。仓库中实际暴露的state/*子路径覆盖了应用运行时所需的全部领域例如state/auth鉴权状态对应 src/state/auth.tsstate/shellShell 状态对应 src/state/shell.ts配套shellReducer.ts、shellCommands.tsstate/threads会话线程状态对应 src/state/threads.ts配套threadReducer.ts、threadState.ts、threadRetention.tsstate/terminal终端状态对应 src/state/terminal.ts配套terminalSession.ts、terminalOutput.tsstate/vcs版本控制状态对应 src/state/vcs.ts配套vcsAction.ts、vcsRef.ts、vcsCommandScheduler.tsstate/projects、state/entities、state/git、state/usage、state/device、state/preview、state/review、state/server、state/runtime、state/connections、state/session、state/models、state/orchestration、state/presentation、state/pull-requests、state/source-control、state/shared-settings、state/filesystem、state/attachments、state/assets、state/deviceHubAccess、state/provider-instance-display、state/project-grouping、state/relayrelayDiscovery.ts、state/subagentRuntime、state/thread-sort、state/thread-settled、state/thread-search等。每个state文件遵循聚焦状态 保留策略 reducer Atom 构造器的组织模式。以voice-input为例可看到这种模式的典型结构状态只描述phase阶段与error错误信息不掺入具体平台的录音实现。README 中的说法独立 state 模块消费 connection 注册表向应用自有的运行时暴露聚焦状态或 Atom 构造器在 src/state 目录下得到了完整印证这些文件互相解耦、按领域组织并大量配合同名.test.ts测试文件如shell.test.ts、threadReducer.test.ts、vcsAction.test.ts、usage.test.ts等保证状态收敛逻辑的正确性。导入示例合法import { EnvironmentSupervisor } from t3tools/client-runtime/connection; import { shellAtom } from t3tools/client-runtime/state/shell; import { threadReducer } from t3tools/client-runtime/state/threads; import { VoiceInputController } from t3tools/client-runtime/voice-input;导入示例不合法import { ... } from t3tools/client-runtime或from t3tools/client-runtime/state—— 包没有根导出也没有宽泛的state导出。三、依赖方向从 platform 契约到 connection 监督README 明确了包内的依赖方向这是理解整个运行时架构的关键平台应用提供platform服务。connection组合这些能力与authorization、relay、rpc监督环境会话。独立的state模块消费 connection 注册表暴露聚焦状态或 Atom 构造器给应用自有的运行时。这条依赖链可以概括为三段式平台应用apps/web、apps/mobile │ 提供 platform 服务实现 ▼ platform能力与持久化契约 │ ▼ connection监督者──组合──► authorizationBearer/DPoP token 持久化 │ relay托管 relay API 与环境发现 │ rpcHTTP/RPC 客户端与协议 ▼ state/domain消费 connection 注册表暴露 Atom/reducer3.1 platform契约而非实现src/platform/index.ts 导出capabilities.ts、persistence.ts、source.ts、storageDocument.ts四组内容。它定义的是契约平台能力capabilities与持久化服务persistence接口由各平台应用自行实现客户端运行时只依赖接口不依赖具体实现。这保证了 Web 端浏览器 LocalStorage/IndexedDB与移动端React Native AsyncStorage 等可以各自接入而共享逻辑完全不变。3.2 connection环境会话的监督者src/connection 是整个包中结构最丰富的领域之一README 提到的targets、catalog、supervision、retries、registry、onboarding在目录中都有对应文件catalog.ts环境目录catalogconnectivity.ts连通性检测credentialStore.ts凭据存储driver.ts连接驱动导出ConnectionDriverProgress与EnvironmentConnectionLeaselayer.ts以Connection命名的 Effect Layer 组装入口model.ts连接模型onboarding.tsonboarding 流程导出ConnectionOnboarding、PairingConnectionInput、SshConnectionInput、BearerConnectionUpdateInput等类型覆盖 Bearer配对与 SSH 两种接入方式presentation.ts连接展示层profileStore.tsprofile 存储registry.ts环境注册表导出EnvironmentRegistry、EnvironmentNotRegisteredError、PlatformEnvironmentRemovalErrorresolver.ts目标解析supervisor.ts环境监督者导出EnvironmentSupervisor与EnvironmentSupervisorOptionswakeups.ts唤醒机制。其中EnvironmentSupervisor正是 README 所说supervision监督能力的实现——它负责在连接生命周期内监督环境会话配合 registry 处理注册/注销配合 resolver 处理目标解析配合 catalog 维护环境目录。从命名与目录结构可以推断connection将连接一个环境这一复杂流程拆解为可独立测试的模块supervisor.test.ts、registry.test.ts、resolver.test.ts、onboarding.test.ts、errors.test.ts、presentation.test.ts等测试文件见 src/connection逐一验证每个环节。3.3 authorization 与 relay身份与通道src/authorization/index.ts 导出remote.ts远程授权逻辑、service.tsAuthorizedRemoteEnvironment、AuthorizedRemoteHttpEnvironment类型与TokenStoretoken 持久化命名空间。README 所述Bearer 和 DPoP 授权加上 token 持久化契约正是这三部分的职责Bearer 用于传统令牌认证DPoPDemonstrating Proof-of-Possession用于将令牌绑定到特定密钥防止令牌被窃取后跨设备重用token 持久化契约则定义了令牌如何安全落盘/落库。src/relay 提供托管 relay API 与环境发现即通过中继服务器建立远程环境的可达路径这在 Web 端浏览器无法直接访问用户本机服务与移动端需要跨网络访问场景中尤为关键。3.4 rpc统一的远程调用通道src/rpc/index.ts 导出client.ts、http.ts、protocol.ts与session.ts覆盖 HTTP/RPC 客户端、传输协议、以及RpcSession会话管理。connection监督的环境会话其实际数据通路就是由rpc提供的——它承担了长连接 订阅的会话语义配合state/session等状态模块支撑起应用内对环境会话状态的实时反映。四、voice-input录音、转写与草稿插入的三段式生命周期README 对voice-input给出了专门说明voice-input 控制器接收录制回调与一个选定的VoiceTranscriber。准备阶段将转写绑定到其实现与解析出的 locale一个取消信号覆盖两个操作。应用提供录制事件、权限、原生转写实现与展示。这段描述在 src/voice-input/controller.ts 中有完整实现支撑export const VOICE_RECORDING_LIMIT_SECONDS 5 * 60; export type VoiceInputPhase idle | preparing | recording | transcribing | error; export type VoiceInputState { readonly phase: VoiceInputPhase; readonly error: string | null; readonly errorAction: retry | settings | null; }; export interface VoiceRecorder { readonly uri: string | null; prepareToRecordAsync(): Promisevoid; record(options: { readonly forDuration: number }): void; stop(): Promisevoid; }从源码可以梳理出该控制器的核心设计阶段机VoiceInputPhase定义了idle → preparing → recording → transcribing → error的完整状态流转voiceInputBlocksSubmission()与voiceInputFreezesEditor()都基于preparing/recording/transcribing 三态判断是否阻塞提交、冻结编辑器避免用户在语音录制/转写过程中误提交表单5 分钟上限VOICE_RECORDING_LIMIT_SECONDS 5 * 60单次录音超过该时长即触发上限处理依赖注入式控制器VoiceInputControllerDependencies声明了全部外部依赖——recorder录音器符合VoiceRecorder接口、getTranscriber获取当前选定的VoiceTranscriber、requestPermission权限请求返回granted与canAskAgain、configureRecording/releaseRecording录制会话的配置与释放、deleteRecording删除录音文件、readDraft/commitDraft读写编辑器草稿快照、onStateChange状态变更回调。这些依赖全部由应用侧注入运行时本身不关心录音是 Expo AV、Web MediaRecorder 还是原生模块实现取消信号覆盖两阶段README 强调preparation 绑定转写实现与 locale一个取消信号同时覆盖两个操作即当用户取消时无论当前处于转写准备preparing还是转写执行transcribing阶段都会通过同一个 abort 机制终止。transcription.ts中导出的throwIfVoiceTranscriptionAborted与PreparedVoiceTranscription正是这一机制的实现载体草稿插入的冲突处理resolveTranscriptCommit(captured, current, transcript, locale)根据录制时快照captured与当前编辑器快照current的关系返回三种提交结果commit可提交携带文本与选区、stale编辑器内容已变化放弃提交、empty转写结果为空。这一设计防止了用户录音期间编辑了正文转写完成后被覆盖的竞态问题。voice-input的公共导出见 src/voice-input/index.ts控制器侧导出VoiceInputController、VOICE_RECORDING_LIMIT_SECONDS、VoiceInputPhase、VoiceInputState、VoiceRecorder、VoiceDraftSnapshot等转写侧导出VoiceTranscriber、PreparedVoiceTranscription、VoiceTranscriptionError、VoiceTranscriptionErrorCode等。配套的 controller.test.ts 对阶段流转、提交阻断与草稿提交结果做了完整验证。五、子路径索引与领域文件公共 API 边界的判定标准README 给出了一个对维护者与调用方都极具操作性的准则子路径索引subpath index与显式导出的领域文件是公共 API 边界其余所有文件都是实现细节。这句话意味着两件事对于调用方只能从exports声明的子路径导入见 package.json 的exports字段不要直接深挖src/connection/someInternalFile.ts这类内部文件否则未来重构时你的导入会断裂对于维护者判断一个文件是否属于公共 API只需看它是否出现在exports映射中——例如src/state/threads.ts被映射为./state/threads它就是公共边界而src/state/threadReducer.ts、src/state/threadState.ts这类未映射文件则是纯实现细节可以自由重构。这种显式 exports 白名单模式让 API 兼容性管理变得可机械化审计新增能力时在exports中登记即为公开否则保持私有。六、如何在应用中使用本包6.1 导入路径规则速查领域子路径t3tools/client-runtime/connection、t3tools/client-runtime/rpc、t3tools/client-runtime/authorization、t3tools/client-runtime/platform、t3tools/client-runtime/relay、t3tools/client-runtime/environment、t3tools/client-runtime/errors、t3tools/client-runtime/operations、t3tools/client-runtime/voice-input嵌套子路径t3tools/client-runtime/operations/projects、t3tools/client-runtime/work-log/presentation状态域t3tools/client-runtime/state/shell、t3tools/client-runtime/state/threads、t3tools/client-runtime/state/terminal、t3tools/client-runtime/state/vcs等完整清单以 package.json 的exports为准单文件工具子路径t3tools/client-runtime/load-balancing、t3tools/client-runtime/markdown-links、t3tools/client-runtime/file-preview等。6.2 消费方视角平台应用如何接入从 README 的依赖方向描述可以总结出接入该包的标准流程实现 platform 契约在 Web 与移动端应用中分别实现 src/platform 定义的能力与持久化接口注入 voice-input 依赖在需要语音输入的应用中按VoiceInputControllerDependencies注入录音器、权限请求、转写器与草稿读写回调使用 connection 建立会话通过connection子路径中的ConnectionOnboarding配对/SSH 接入、EnvironmentRegistry注册表与EnvironmentSupervisor监督者建立并维护环境会话底层自动组合authorizationBearer/DPoP 授权与 token 持久化、relay中继通道与rpc会话协议消费 state 模块在各业务组件中按领域导入state/domain的 Atom 构造器或 reducer把连接注册表派生出的状态接入应用自有的状态运行时。6.3 开发与验证包提供了两个脚本命令见 package.jsonpnpm --filter t3tools/client-runtime typecheck # tsc --noEmit 类型检查 pnpm --filter t3tools/client-runtime test # vp test run 运行测试仓库为几乎所有公共能力都配备了同名的.test.ts测试如markdownLinks.test.ts、filePreview.test.ts、threads-pagination.test.ts、controller.test.ts等新增或修改子路径能力时应当遵循同样的源码 测试 exports 登记三件套模式。七、总结窄导入、强边界、可组合t3tools/client-runtime的技术要点可以浓缩为四句话无根导出所有公共 API 通过exports白名单按子路径暴露杜绝隐式全局依赖契约与实现分离platform只定义契约Web/移动端各自实现connection是监督者组合authorization、relay、rpc管理环境会话state/domain是聚焦的状态消费者生命周期可编程voice-input用依赖注入的控制器 阶段机 统一取消信号 草稿快照冲突检测把录音 → 转写 → 插入草稿这一多平台流程抽象为纯共享逻辑API 边界可审计子路径索引与显式导出的领域文件即公共 API其余均为实现细节——这一约定让跨 Web/移动端的共享客户端层可以持续演进而不破坏调用方。对于希望在 t3code 中新增共享客户端能力的开发者最直接的行动路径是在 packages/client-runtime/src 下按领域新增文件在 package.json 的exports中登记子路径补充配套测试然后在 Web 或移动端应用中以最窄子路径导入使用。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考