English

本页是 Cargo workspace 中 23 个 Rust crate 的规范映射。根 Cargo.toml 统一提供版本、edition、Rust 版本、作者、许可证和仓库信息。默认 workspace member 是 sonicterm-app。发布的二进制 crate 是 sonicterm-mac、 sonicterm-windows 和 sonicterm-linux；Linux 可执行文件名为 sonicterm。

flowchart BT
    types["sonicterm-types"]
    resource["sonicterm-resource"]
    grid["sonicterm-grid"]
    vt["sonicterm-vt"]
    io["sonicterm-io"]
    logging["sonicterm-logging"]
    cfg["sonicterm-cfg"]
    text["sonicterm-text"]
    ui["sonicterm-ui"]
    model["sonicterm-render-model"]
    fontparts["font-config · fontconfig · freetype · harfbuzz"]
    font["sonicterm-font"]
    engine["sonicterm-engine"]
    block["sonicterm-block-glyph"]
    gpu["sonicterm-gpu"]
    core["sonicterm-app-core"]
    app["sonicterm-app"]
    platforms["mac · windows · linux"]

    resource --> types
    grid --> types
    vt --> grid
    vt --> types
    io --> types
    logging --> types
    cfg --> logging
    cfg --> types
    text --> types
    ui --> cfg
    ui --> grid
    model --> cfg
    model --> grid
    model --> ui
    font --> fontparts
    engine --> font
    engine --> text
    gpu --> block
    gpu --> model
    gpu --> engine
    gpu --> text
    core --> types
    app --> core
    app --> vt
    app --> io
    app --> cfg
    app --> ui
    app --> model
    app --> gpu
    app --> resource
    app --> logging
    platforms --> app
    platforms --> core

图中只画主要架构依赖。下方每个条目列出准确的第一方 Cargo 依赖。除非条目另有说明， 这些都是普通 Cargo 依赖，而不是构建或测试依赖。sonicterm-logging 还以 dev dependency 使用启用 test-util 的 sonicterm-resource。sonicterm-font 的 fontconfig 别名仅在 Android 和非 macOS Unix 目标启用；config、freetype、harfbuzz 是库别名，不是额外 crate。 工作区没有第一方 build-dependency 边。外部构建工具和原生链接要求仍由 FFI 与平台 crate 管理。

本表用于查找状态所有者与公开接口；下方条目列出准确依赖和源码。未特别注明的路径相对于 所属 crate。兼容 trait 不一定驱动生产；本表也不是 unsafe 调用审计。

职责： 供整个 workspace 共用的轻量契约，包括单元格、几何、颜色、操作、 修饰键、字形/窗口/超链接标识、shell 引用、粘贴编码、资源类型和后端 trait。

第一方依赖： 无。

阅读： src/{cell,action,glyph_key,geom,resource}.rs、src/traits/。

职责： 进程内资源治理器，包含 owner 层级、分片账本、自动释放的 RAII 预留、取消 token 和有界回收任务管理器。

管理器关闭时唤醒容量等待者并返回 ShuttingDown，预留期限与关闭同时发生时也如此。 已完成任务在计数器锁释放后析构，因此原生句柄许可的析构可以归还计数。 槽位通知在析构之后发生；即使析构展开退出，也不会丢失通知。 shutdown_handle() 返回可克隆的 ReapShutdownHandle；它的 close_admission(drain_by) 只收紧共享期限，不运行另一个轮询循环，也不设置取消 token。 运行中的调用与延迟等待都遵守自身期限和共享期限中较早的那个。

try_reserve_unit(ReapUnitDemand) 原子预留一个任务及各个 ReapHandlePermit； BelowMinimumCapacity 表示固定上限无法容纳整个单元，与容量已被占用时的 QueueFull 区分。sink 条目持有容量直到进程退出，因此 QueueFull 不一定是临时状态。调用方必须 限制重试，再采用同步回退，同时继续持有未完成的资源。只有任务开始执行时才申领 helper。普通任务仍按调用申领；选择整组模式的任务在计数器锁 释放后接收一个完整 HelperGrant，重试时使用 Held。每个 worker 持有 grant 克隆并 占据组内一个槽位；启动失败只归还该槽位，不释放任务持有的整组 grant。helper 计数表示 预留容量，包括没有 worker 运行时仍被保留的 grant。

选择收集模式的任务保留被中止等待的 helper 句柄，并向 collect_settled_retained 提供 整个任务的完成状态。收集器在待处理任务重试前执行，只在管理器锁之外 join 已结束的 句柄，然后归还任务许可并撤回未解决 owner 记录。选择该模式要求每个任务拥有唯一的 传输 owner，共享 owner 的任务保持不可收集。requeue_unstarted 让符合条件的工作 跨越正常运行期限。每次唤醒、复查和运行返回后，调用方必须先收集已完成的保留任务并检查 控制消息，再查询 has_startable_work。查询不自行收集；它让延续任务停等，直到完整 grant 可以接纳。接纳关闭后，不再走这条正常重试路径。

UnresolvedSink 在独立持有的列表中保留未完成的原生载荷及其记账。条目占用任务接纳 容量，shutdown 同时报告条目和仍打开的无槽位取消副本。sink 的终态释放会遗忘未完成 条目，不执行尚不能安全完成的原生析构，也不归还其记账。账本允许已退役的 PtyTransport 直接属于 GUI 进程，不允许它属于该进程的窗口、窗格或本地 PTY。

第一方依赖： sonicterm-types。

阅读： src/{ledger,owner,reservation,reaper,cancel}.rs。

职责： 主屏幕和备用屏幕、可见行、有界回滚缓冲、光标、宽字符和组合字符、 超链接、提示区、脏行与行存储。

第一方依赖： sonicterm-types。

阅读： src/{grid,line,hyperlink}.rs。

职责： 基于 vte 的 ANSI/VT 解析器与执行器，把控制序列转换为网格修改、 终端回复和类型化事件。OSC 7 会分别保留主机 authority 与解码后的路径，供需要 识别主机的工作目录逻辑使用。

第一方依赖： sonicterm-grid、sonicterm-types。

阅读： src/vt.rs、tests/autowrap/main.rs、 tests/control_sequences/main.rs。

职责： 本地 PTY 与进程传输、调整大小和子进程清理、shell 选择，以及前台 进程发现。PtyHandle::into_teardown 不等待就转移原生清理所有权。PtyTeardown 在重试期间持有原生资源、逐句柄许可、阶段状态和 worker 句柄；不依赖后端的 NativeWorkerSpawner 契约让 App 提供整组 helper grant，而 IO 无需依赖资源治理器。 PtyCompletion 分别观察成功阶段、线程实际退出与 join。

第一方依赖： sonicterm-types。

阅读： src/{pty,proc_info,foreground_proc}.rs。

职责： tracing 输出、日志保留、panic 工件、致命退出标记、会话标记、 有界诊断记录、事后证据发现和进程内存采样。

第一方依赖： sonicterm-types；测试还以 test-util 使用 sonicterm-resource。

阅读： src/{lib,config,cleanup,crash,exit_trace,breadcrumbs,postmortem,session_state}.rs。 具体字段和排查方法见日志。

职责： 唯一负责解析 sonicterm.toml、主题和键位 TOML、尺寸、资源查找、 类型化 URI/路径识别，以及安全 URI 打开策略。

第一方依赖： sonicterm-logging、sonicterm-types。

阅读： src/{config,theme,keymap,assets,url_scan,url_open,launch_url,dimension}.rs。 launch_url.rs 把 ssh: 和 x-man-page: 链接校验为固定客户端的 argv。

职责： 与渲染器无关的界面状态和布局，包括标签页、窗格、命令面板、搜索、 选区、READONLY/复制模式、滚动条、输入法、广播、通知和本地化。

第一方依赖： sonicterm-cfg、sonicterm-grid、sonicterm-types。

macOS 文本编辑通过 AppKit attributed-string 纯字符串单词边界 API 实现 Option 删除， 并严格转换 UTF-16/UTF-8 位置。按目标启用的 objc2-app-kit、objc2-foundation 依赖 不创建原生视图或窗口。规范分解使用 unicode-normalization；终端编码仍属于 app， 不进入这些文本框编辑操作。

标签页布局读取每个标签页存储的标题宽度。渲染器在绘制标签栏之前用标签字体测量它 （TabBar::refresh_content_widths），每个 TabBarLayout::compute* 都据此确定标签页 尺寸，因此绘制、点击判定、拖动与拆出插入位置以及溢出选择器无需字体即可共用同一布局。 每个宽度都限制在标签栏上次布局所用的 tab_min_width 与 tab_max_width 之间 （tab_width_limits_of）：配置在启动和重新加载时设置进程级上下限，每次测量都会把它们记录到 标签栏上。拥挤判断和溢出阈值只使用由字体/缩放推导的可读宽度。 标签页被按下或拖动、或指针停留在标签栏上时，变化的标题、徽章或权限标记会被测量， 但要等没有标签页被按下或拖动且指针离开标签栏后才重新布局；字体、缩放或宽度限制变化会 立即重新布局标签栏。指针是否停留在标签栏上取自该窗口自己的指针位置，分发器会在覆盖层、 模态界面或处理函数消费事件之前记录每一次移动和离开。若某次重绘的帧没有呈现，则恢复屏幕上 仍在显示的宽度和上下限（TabBar::restore_laid_out_widths），因此点击和拖放都以用户看到的标签栏为准。 fit_title_to_width 在字素边界处截断放不下的标题。

渲染器把标签标题字体保存在一个不依赖设备的类型（TabTitleFont）中，它持有标题字体栈、栅格尺寸， 以及存储宽度所依据的键。GpuRenderer::set_font、缩放因子重建和 GpuRenderer::measure_tab_widths 都经由它，因此字体或缩放变化会作用于下一次测量，而测量只在 CPU 上进行。

标签栏上的指针输入由 WindowState::route_tab_press、route_tab_motion 和 route_tab_release 路由：它们接收绘制出的标签栏布局、指针位置和窗口的手势状态，并返回要执行的动作； App::apply_tab_press、apply_tab_motion 和 apply_tab_release 执行该动作。主窗口和子窗口的 指针处理函数只提供原生输入：标签栏布局（主窗口取自原生窗口尺寸，子窗口取自渲染器），以及拆出 标签页所需的事件循环。

命令面板分开管理元数据、显示与执行：

• command_label::descriptor 定义变体身份、分类、本地化键、英文别名、目标要求与 READONLY 许可。App 提供窗口内 CommandContext；disabled_reason 没有原生句柄、 终端载荷或执行权限。英文后备保留动作参数字面值。
• CommandPalette 在刷新时用 I18n 缓存标签、搜索文字、首个绑定提示和界面文字。 语言刷新重建所有模式文字，仅 Commands 重新过滤索引。PaletteLayout 把缓存身份用于帧键， 不逐帧翻译。Fluent 数量/标题短语按一个内部值槽拆分以保留词序；不解释标题，光标单独追加。
• highlighted 保留行身份，current 排除禁用项。PaletteEntry 区分命令和 TabId 目标。App 在附着窗口解析存活目标的当前下标；关闭目标不会选择替代项。
• App 在输入前刷新上下文，渲染时使用已持有网格。输入选区验证采用 try_lock，不会重复获取 render guard。溢出与原生/本地拖放快照保留绝对索引；仅标签页模式复用面板。唯一模态指针 记录在释放时验证身份/可用性，不抢占先开始的终端或界面手势。

阅读： src/{tabs,pane,command_palette,command_label,search,selection,copy_mode,ime,overlays,i18n}.rs。

职责： 与具体渲染器无关的窗格、几何、覆盖层和输入数据。它通过 boundary::{grid,cfg,ui} 重新导出网格、配置和界面类型，让 GPU crate 只依赖一条 明确的模型边界。

第一方依赖： sonicterm-cfg、sonicterm-grid、sonicterm-types、 sonicterm-ui。

阅读： src/{pane_render,inputs,geometry,lib}.rs。

职责： CPU 字形图集、行级字形缓存、塑形记录，以及渲染器使用的 GlyphInstance 数据。

第一方依赖： sonicterm-types。

阅读： src/{glyph_atlas,row_glyph_cache,shape,lib}.rs。

职责： 字体配置值模型，包括文本样式、属性、字重、宽度、光栅器选择和策略。 Rust library 名为 config。

第一方依赖： 无。

阅读： src/lib.rs。

职责： 手写的 Fontconfig ABI 声明，以及 Android 和非 macOS Unix 字体发现所用的 构建/链接封装。build.rs 通过 pkg-config 探测系统 Fontconfig。

第一方依赖： 无。

阅读： build.rs、手写的 src/lib.rs。

职责： 生成的 FreeType ABI 和定点数工具。build.rs 编译内嵌的 zlib、libpng 与 FreeType，并导出构建路径。

第一方依赖： 无。

阅读： build.rs、bindings.h、src/{lib,types,fixed_point}.rs。

职责： 生成的 HarfBuzz ABI。build.rs 针对 FreeType 构建结果编译内嵌的 HarfBuzz C++ 合并源码。原生原子操作、互斥锁和线程安全的静态初始化保持启用： 不同线程上的独立字体对象仍共享 HarfBuzz 回调表。字体封装测试在不共享可变字体对象的 情况下并发创建和销毁字体。

第一方依赖： 以依赖别名 freetype 使用 sonicterm-freetype。

阅读： build.rs、bindings.h、生成的 src/lib.rs。

职责： 安全的字体发现和匹配、HarfBuzz 塑形、回退、 FreeType/DirectWrite/HarfBuzz 光栅化、COLR 字形和原生 handle 封装。

第一方依赖： 以 config 使用 sonicterm-font-config，以 freetype 使用 sonicterm-freetype，以 harfbuzz 使用 sonicterm-harfbuzz；Android 和非 macOS Unix 构建还以 fontconfig 使用 sonicterm-fontconfig。

阅读： src/db.rs、src/locator/、src/shaper/、src/rasterizer/、 src/{ftwrap,hbwrap,fcwrap,parser}.rs。

职责： 小型字体引擎边界。FontStack 把塑形与光栅结果转换为单元格尺寸和 图集 RasterTile。

第一方依赖： 以 config 使用 sonicterm-font-config，另依赖 sonicterm-font、sonicterm-text、sonicterm-types。

阅读： src/fontstack.rs。

职责： 方框线、块元素、Powerline、Braille、六分块、八分块和合成终端符号的 几何与光栅化。

第一方依赖： 无。

阅读： src/{lib,glue,customglyph}.rs；来源说明见 LICENSE-WEZTERM。

职责： wgpu 设备与 surface、帧组装、脏行损伤、quad 与字形输出、图集上传、 保留帧、软件 adapter 检测，以及 Windows CPU 呈现数据。

第一方依赖： sonicterm-block-glyph、sonicterm-engine、 sonicterm-render-model、sonicterm-text、sonicterm-types。

私有 FramePlan 从元数据组合帧标识、模式、损伤、窗格裁剪、视口槽位和预期修订号。 生产路径在组帧阶段使用这些决策，此时持有借用网格和解析器守卫，并进行有状态的图集/缓存操作； 呈现在它们释放后进行。它不是快照，也不是多线程渲染器边界。

present.rs 承载呈现交接点：wgpu 与 Windows GDI 呈现器共用一个交接点，以及 render_releasing 在 FrameOutcome 中返回的带类型 PresentOutcome 及已呈现帧的回执。兼容包装 render_with_outcome 只返回该结果，render 再把它映射回 Result<()>。

阅读： src/{core,present,frame_plan,atlas_upload,row_quad_cache,chrome_text,cursor,color,software_frame,software_windows}.rs。

职责： 不依赖后端的 AppIntent、AppEffect、AppState、reducer、稳定的 effect 顺序和状态机。实时窗口/标签页/窗格结构仍由 sonicterm-app 持有。

第一方依赖： sonicterm-types。

阅读： src/{app_state,intent,effect,reducer,state_machine}.rs。

职责： 跨平台 winit 编排，管理窗口、渲染器、标签页、窗格、PTY/解析器、 输入、配置重载、重绘、覆盖层、标签页转移、有界目标探测和原生直接打开。一个 ReaperDriver 负责全部 PTY 回收运行。retire_pane 将原生托管移至唯一的进程直属 PtyTransport，计为一个 ReaperWork 条目，再释放窗格记账。活跃转移保留其预留。 finish_session 在关闭前退役全部窗格，并缓存拆除是否完成；ShellRunResult 将该 结果与原应用运行结果分开保存。

第一方依赖： sonicterm-app-core、sonicterm-cfg、sonicterm-gpu、 sonicterm-grid、sonicterm-io、sonicterm-logging、 sonicterm-render-model、sonicterm-resource、sonicterm-text、 sonicterm-types、sonicterm-ui、sonicterm-vt。

macOS 依赖： objc2、objc2-foundation、objc2-app-kit 和 objc2-quartz-core，已经通过其他 crate 存在于 lockfile 中，用于每窗口的 NSView.displayLink 及其 tick target（src/app/display_link.rs）。

阅读： src/app/{mod,window_state,window_registry,session,input_dispatch,effects}.rs、 src/app/{event_loop,window_event,window_keyboard,window_pointer,spawn_pane,reaper_driver,keymap_dispatch,path_target,tear_out}.rs、 src/shell.rs。

职责： macOS 二进制与 AppKit 胶水，包括启动、NSMenu、带可执行文件分类的打开文档 与打开 URL 事件、NSPasteboard 标签页交接、NSWindow 设置和 app bundle 入口。

第一方依赖： sonicterm-app、sonicterm-app-core、sonicterm-cfg、 sonicterm-logging、sonicterm-types。

阅读： src/{main,menubar,open_documents,open_urls,executable_classify,os_drag_mac,tab_drag_os}.rs。 原生边界见平台集成。

职责： Windows 二进制与 Win32 界面胶水，包括 DPI 设置、CLI、muda 菜单、 DWM backdrop、OLE 标签页拖放、软件呈现支持、Win32 资源和 WiX metadata。 ConPTY 仍封装在 sonicterm-io 后。

第一方依赖： sonicterm-app、sonicterm-app-core、sonicterm-cfg、 sonicterm-logging、sonicterm-types。

阅读： src/{main,cli,startup,backdrop,menubar,os_drag_win,software_presenter}.rs、 build.rs、wix/main.wxs。

职责： 发布用 Linux sonicterm 二进制，包括 X11/Wayland identity、能力收敛、 诊断、打包字体预检和 desktop/AppStream metadata。

第一方依赖： sonicterm-app、sonicterm-app-core、sonicterm-cfg、 sonicterm-engine、sonicterm-logging。

阅读： src/main.rs、resources/。

每个 crate 都有本地 CLAUDE.md，记录约束和本地 gate。安装包布局见打包； CI 行为见CI 与 Coverage，发布行为见发布流程。