[xiaoyumuxi]

问题与结果

工具插件目前无法打开 Lithe 的集成终端，Docker 等交互客户端只能要求用户手动执行命令。本改动在既有函数协议 3 和宿主服务 dispatcher 上开放插件自有原生终端，复用 TerminalFeatureModel、SwiftTerm 和 macOS PTY；宿主不增加 Docker 或其他工具专属分支。

API 编号与本 PR 范围

本 PR 对应原定 API-01–44 中的 API-24：插件自有终端。沿用既有 44 项编号，下面六个公共方法均归属 API-24；这 44 项按能力规划分组，每项可包含多个方法。编号依据：本分支 API-01–44 完成度总表。

原计划编号	本 PR 新增公共方法	用途
API-24	lithe/host/terminal/create	经执行确认创建插件自有原生终端，返回 terminalID 和 generation
API-24	lithe/host/terminal/show	显示并选中本插件终端
API-24	lithe/host/terminal/close	结束进程树并关闭标签，按字节预算保留显示历史和启动配置
API-24	lithe/host/terminal/reopen	经重新确认，用原启动配置创建新进程，递增 generation 并恢复有界显示历史
API-24	lithe/host/terminal/dispose	关闭终端并彻底释放句柄、启动配置和历史
API-24	lithe/host/terminal/onExit	订阅终端各 generation 的退出结果

API-24 从“未做”更新为“部分完成”：本 PR 接入本机 macOS；sendText、输出读取、Windows 和远程支持未开放，完整 GUI 验收仍 pending。六个方法统一要求 terminal.create 权限、backend:2 和既有函数协议 3；API-24 是规划编号，与协议版本、能力版本分别记录。

改动

• 新权限 terminal.create（要求 backend:2），在 Core 白名单、清单 schema、能力发现和 macOS 组合根注册六个方法：create/show/close/reopen/dispose/onExit。Web 页面经自己的 backend 函数调用，不增加私有终端传输或直接 web terminal bridge。
• create 用 executable/argv 分离的直接进程启动，支持工作区目录资源 cwd、环境覆盖/删除、标题及显示选项。创建与重开均显示可取消执行确认，并在异步边界重新核对 context、authority 和取消；首版本机 macOS，remote 明确拒绝，Windows 不注册 handler。
• close 清理进程树并关闭原生标签，保留启动配置与有界纯文本显示历史；reopen 沿用 terminalID、递增 generation 并启动新进程，不重放输入、不恢复 Shell 变量或旧进程内存。
• 插件可在 create/close 设置 retainedContextBytes：默认 16 KiB，范围 0–256 KiB，0 表示不保留；按 UTF-8 scalar 边界截断，使用 SwiftTerm 自己的组合字符解码与宽字符处理，恢复时只喂显示器、从不写 stdin。历史和启动信息仅在宿主内存保存。
• 句柄隔离到 plugin/backend session/context，最多保留八个句柄；dispose 彻底释放。退出订阅每个 generation 只发布一次，取消重开不伪造退出事件或占用新 generation，旧回调不影响新进程。
• 工作区关闭/替换、后端退出、插件禁用/更新清理所属终端，用户自建终端不受影响；用户关闭标签或自然退出后仍可重开。
• 补齐安装权限说明、中英 i18n 及生成表、API-24 进度、正式契约/共享 fixture、决策 Note 和独立功能矩阵记录。
• show:false 创建/重开保留已有活动终端，不挂载标签或请求输入焦点；显式 show 后才挂载并选择。
• 用户关标签与自然退出同样等待有界原生清理，只保留预算内文本并释放完整会话与渲染缓冲区，0 字节预算生效；清理期间返回 busy，退出通知在清理完成后发送。
• 执行确认以可滚动、选择和复制的原生 TextKit 视口展示完整程序、argv 与 cwd，JSON 转义保留参数边界和控制字符。
• 修复同一子进程重复登记回收时释放未激活 DispatchSource 的崩溃，重复登记复用已有观察源。

本地验证

• 最终修复使用 Swift 6.3.3 + 本机已有 macOS 26.5 SDK：75 项相关 Swift 测试全部通过，覆盖终端模块、宿主服务、消息、原生 PTY、标签放置与子进程回收。用户关标签/自然退出 × 0/8 字节四种释放场景合计约 0.17 秒，长参数完整呈现与取消约 0.04 秒；逐项 HTML/JUnit 在 .artifacts/test-stability/plugin-terminal-review-fixes.*。原实现另有 46 项相关测试通过，报告为 plugin-terminal-final.*。
• cargo test --manifest-path rust/Cargo.toml -p lithe-core --target aarch64-apple-darwin：1,542 项单测和相关集成全部通过；另对函数协议与 terminal 权限 31 项做独立计时。
• 本次修复的共享契约、service boundaries、Agent Notes、Windows boundaries、i18n 语言/生成校验与 35 项测试、runtime bundle immutability、测试稳定性、功能矩阵变更/完整性门禁通过。Rust 注释/格式沿用原实现检查结果，本次未修改 Rust 代码。
• 在配套 SDK 工作区运行 LITHE_PLUGIN_SDK_TERMINAL_E2E=1 node scripts/sdk-e2e.mjs --source <此工作树> --ref codex/plugin-terminal-api，三个 SDK 的示例后端及原有领域场景对宿主提交 f989e5e0a018361645219000e552051f19c6bbb4 全部通过。Rust 新场景经真实 Core 验证六方法链路中的创建、订阅、关闭、重开和释放；实际 PTY 由宿主测试验证。
• 测试启动的临时 PTY/后端与测试应用均已退出。真实 PTY 测试有一处注明理由的有界 10ms 轮询，仅观察原生 I/O，5 秒本地截止时间。

范围与后续

• 真实安装插件的完整点击、焦点、Ctrl-C、缩放和退出 GUI 验收仍 pending，矩阵未标 verified；Windows 和远程终端未实现。
• Docker 插件的按钮接入不在本 PR；不开放 sendText、读取终端输出或枚举用户终端。
• 配套 Node/Java/Rust SDK PR：lithe-plugin-docs#14。主仓库合并后需在 lithe-plugin-docs 运行 node scripts/contract.mjs sync --revision <合并后的 preview commit>，同步契约副本后再发布 SDK；本 PR 不修改 SDK 版本或发布包。
• 提交前静态核对未发现需要阻塞合并的问题，原主检出中的目录浏览改动未包含在此分支。