feat(extensions): refine cross-surface integration experience

Author: limityan

docs/architecture/extensions/external-ai-work-sources-design.md

@@ -12,7 +12,10 @@ OpenCode Prompt Command 适配器接入本地用户全局/项目来源；Desktop
 交互式 TUI（ChatMode）可列出并执行 prompt-only Command。第二条纵向切片已让受支持的单文件 OpenCode `.js` standalone Tool 经静态
 预览、来源/能力确认和同名冲突选择后进入现有 Tool Runtime；Desktop 与交互式 TUI（ChatMode）使用同一决策状态。第三条纵向
 切片已把 OpenCode 全局/项目 Subagent 的安全子集通过独立 provider 契约接入现有 Subagent owner：首次启用与
-同名冲突使用非阻塞决策，fresh 调用固定不可变 generation，更新和撤下不会静默切换到同名实现。完整
+同名冲突使用非阻塞决策，fresh 调用固定不可变 generation，更新和撤下不会静默切换到同名实现。第四条纵向切片
+已把 OpenCode 用户/项目 MCP 的 local stdio 与 HTTPS remote 安全子集接入现有 MCP owner，沿用显式审批、冲突、
+工作区隔离和失败回推；现有 Skill Registry 另行展示来源、用户/项目作用域和固定优先级产生的覆盖结果，不并入上述
+可执行来源选择规则。完整
 TypeScript/Bun、包依赖、package plugin、Codex/Claude Code 适配器、primary agent 替换和外部 Subagent 续接仍属于
 后续阶段，不能因来源被识别就宣称已经可用。
 
@@ -60,7 +63,9 @@ TypeScript/Bun、包依赖、package plugin、Codex/Claude Code 适配器、prim
 
 ### 3.1 首次发现
 
-发现始终在后台进行。Desktop、交互式 TUI（ChatMode）和未来 Web 入口消费同一只读来源状态，但按宿主展示：
+发现始终在后台进行。Desktop、交互式 TUI（ChatMode）和 Peer 控制界面消费事实所在 Host 的同一来源状态，但按
+宿主展示；Peer 控制界面只代理 Peer Host，不读取控制端同名来源。Server 当前只提供只读快照，未来 Web 入口必须
+通过已接入的 Host 能力消费，不能由浏览器扫描来源：
 
 ```text
 已发现 OpenCode 工作内容

docs/architecture/extensions/opencode-extension-compatibility.md

@@ -104,7 +104,7 @@ OpenCode，和 OpenCode 配置/插件进入 BitFun 是两个独立验收方向
 | 独立 `tui.json/jsonc` | 融合现有能力 + 转换参数 | 未实现 | 可完整适配 | OC-R1 | 按 global、`OPENCODE_TUI_CONFIG`、project、`.opencode` 独立顺序加载，不能复用主配置优先级 | [TUI 来源](opencode-config-assets-adapter-design.md#32-tui-独立来源顺序) |
 | Rules / Instructions | 转换参数 | 未实现 | 可完整适配 | OC-R1 | R1 映射本地/已缓存内容；需要主动联网的远程 instruction 在 R2 通过归属模块保护后获取 | [声明式资产](opencode-config-assets-adapter-design.md#5-声明式资产映射) |
 | Agents / Modes | 融合现有能力 + 转换参数 | 部分实现：Subagent 安全子集 | 可主要适配 | OC-R1 | 已支持全局/项目 Markdown、JSON/JSONC 的 subagent/all、prompt、description、disable/hidden、精确模型与工具映射，并接入审批、冲突、更新、撤下和 fresh single-run Task；primary/mode、permission、variant/options、采样与续接明确降级 | [Agents 与 Skills](opencode-config-assets-adapter-design.md#52-agentsmodes-与-skills) |
-| Skills | 转换参数 | 未实现 | 可完整适配 | OC-R2 | R1 发现/展示；R2 保留按需加载及 allow/deny/ask 顺序，可执行资源走 Skill 归属模块保护 | [Agents 与 Skills](opencode-config-assets-adapter-design.md#52-agentsmodes-与-skills) |
+| Skills | 转换参数 | 部分实现：现有 Registry 发现与来源/覆盖展示 | 可完整适配 | OC-R2 | 已沿用现有根顺序发现 `.opencode` 等用户/项目 Skill，并在 GUI/TUI 展示来源、作用域和覆盖结果；尚未复现 OpenCode 按需加载、完整配置合并及 allow/deny/ask 顺序，也未并入外部来源策略 owner | [Agents 与 Skills](opencode-config-assets-adapter-design.md#52-agentsmodes-与-skills) |
 | References | 补基础能力 + 转换参数 | 未实现 | 可主要适配 | OC-R2 | R1 解析；R2 支持本地目录和 Git repository/branch/description/hidden，异步准备并接入 `@alias` | [声明式资产](opencode-config-assets-adapter-design.md#5-声明式资产映射) |
 | Commands | 补扩展接口 + 转换参数 | 部分实现：prompt-only 子集 | 可完整适配 | OC-R2 | 已支持全局/项目 JSON、JSONC、Markdown 命令、`$ARGUMENTS` 与位置参数，并接入动态命令目录、运行时刷新和显式冲突选择；`@file`、shell、Agent/model/variant/subtask 保持受限且不做部分执行 | [Commands](opencode-config-assets-adapter-design.md#53-commands) |
 | Models / Providers 配置 | 融合现有能力 | 未实现 | 可主要适配 | OC-R1 | 静态字段进入模型归属模块；动态模型、鉴权和请求头交给插件运行时 | [声明式资产](opencode-config-assets-adapter-design.md#5-声明式资产映射) |

docs/architecture/extensions/plugin-runtime-host-design.md

@@ -301,7 +301,9 @@ CLI 已允许在包文件缺失或损坏时清理残留启用状态，这是现
 已经接入 prompt-only Command、受支持的单文件 `.js` standalone Tool、Subagent 安全子集和 OpenCode MCP 配置
 安全子集；其中 standalone Tool
 通过窄 `ScriptToolRuntime` 真实执行，但这不证明 package plugin、Hook、完整 Client 或 TUI target 已经可运行。
-四个切片当前都只支持本地执行域；Remote 外部来源发现、审批与冲突决策明确返回不支持，不回退读取本机来源。MCP
+四个切片当前都只在事实所在 Host 的本地执行域运行；本机 Desktop/CLI 直接使用本机 Host，Peer 控制界面可代理
+Peer Host 的来源发现、审批与冲突决策，并按 Host 身份与工作区隔离结果。该能力不等于 SSH Remote 工作区执行；
+SSH Remote 外部来源发现仍明确返回不支持，也不回退读取控制端或 Host 的同名本机来源。MCP
 运行实例和工具 route 额外按规范化 workspace 隔离；更新、停用、空闲回收和删除先撤 route，再异步回收连接与进程，
 慢启动在发布工具前复核撤销状态。
 

docs/architecture/product-architecture.md

@@ -233,11 +233,12 @@ Plugin Runtime P0 只验证了 BitFun 专用插件目录中的来源校验、工
 不能称为“OpenCode 插件运行时”。详细代码事实集中在
 [`plugin-runtime-host-design.md#8-当前实现附录`](extensions/plugin-runtime-host-design.md#8-当前实现附录)。
 
-与 Plugin Runtime 分离的三条纵向基线已经通过各自的能力专属 provider 契约接入：Prompt Command 可发现本地
+与 Plugin Runtime 分离的四条纵向基线已经通过各自的能力专属 provider 契约接入：Prompt Command 可发现本地
 用户/项目 OpenCode Command、处理跨来源冲突，并在 CLI/TUI 中执行受支持的 prompt-only 模板；standalone Tool
 可把受支持的单文件 `.js` 经确认后接入现有 Tool Runtime；Subagent 可把全局/项目声明的安全子集经确认和同名冲突
-选择后接入现有 Task/Subagent owner，并以 generation lease 固定 fresh single-run 调用。三类贡献对象互不复用，
-主体逻辑不按生态分支。当前仍不表示 package plugin、Hook、primary agent、外部 agent 续接、Remote 来源发现或完整
+选择后接入现有 Task/Subagent owner，并以 generation lease 固定 fresh single-run 调用；MCP 可把受支持的用户/项目
+配置经确认和同名冲突选择后交给现有 MCP owner 运行。四类贡献对象互不复用，主体逻辑不按生态分支。当前仍不表示
+package plugin、Hook、primary agent、外部 agent 续接、SSH Remote 工作区来源发现或完整
 配置兼容已经可用。
 
 目标路线不要求 OpenCode 插件作者维护 `bitfun.plugin.json` 或复制到 `.bitfun/plugins`。BitFun 直接发现用户和
@@ -326,13 +327,13 @@ flowchart LR
 
 | 产品形态 | 当前扩展能力 | 入口行为 |
 |---|---|---|
-| Desktop / product-full | 生产入口仍依赖 `bitfun-core/product-full` 作为兼容组装层；“外部 AI 应用”设置已消费 OpenCode Command、standalone Tool 和 Subagent 的统一来源快照、审批、冲突选择与诊断；Skills 场景和设置列表显示已发现 Skill 的生态来源与覆盖结果 | 仅本地执行域支持当前三条可执行纵向切片；Skill 仍使用独立 Registry，不据来源展示宣称已并入外部来源协调器。受管 package plugin 仍只有静态预览，不能据设置页接入宣称完整 OpenCode 插件运行时 |
+| Desktop / product-full | 生产入口仍依赖 `bitfun-core/product-full` 作为兼容组装层；Beta“外部 AI 应用”设置已消费 OpenCode Command、standalone Tool、Subagent 和 MCP 的统一来源快照、审批、冲突选择与诊断；MCP 原生清单优先展示，外部候选保持独立来源、作用域和覆盖状态；Skills 场景显示已发现 Skill 的生态来源、用户/项目作用域与覆盖结果 | 当前四条可执行纵向切片由事实所在 Host 执行；本机 Desktop 使用本机 Host，Peer 控制界面代理 Peer Host，不在控制端回退发现或执行。Skill 仍使用独立 Registry，不据来源展示宣称已并入外部来源协调器。受管 package plugin 仍只有静态预览，不能据设置页接入宣称完整 OpenCode 插件运行时 |
 | CLI | 入口仍以 `bitfun-core/product-full` 作为执行兼容 owner；交互式 TUI 已可执行受支持的 Prompt Command，并在通用 `/tools` 与 `/agents` 入口按文字分组消费与 Desktop 相同的审批、冲突和刷新状态；`/agents` 同时承载主 Agent 切换、Subagent 管理和“外部 AI 应用”，不再注册 `/subagents` 或 `external-*` 平行命令。活动 turn 期间仍可查看和管理，只有主 Agent 切换被禁用。Skill 列表显示来源，模式配置按实际选择结果说明覆盖来源 | 已批准的 standalone Tool 进入现有 Tool Runtime；已批准的外部 Subagent 只支持 fresh single-run。CLI/TUI 不解析生态文件、不启动第二套 worker/Agent owner；非交互入口和 Remote 未接入时不得借本机 TUI 路径代执行。本地 Agent 与 Peer Host 路径选择 `DeliveryProfile::Cli` 并消费同一 Runtime Parts/SDK；主会话的恢复、转录、本地分支、用量报告生成/卡片持久化、模式更新与精确结算走 SDK，Peer Host 的基础会话创建/恢复/重命名/归档和 thread-goal 查询也走同一 SDK；远程分支明确不支持。TUI 模式切换异步持久化，期间保持输入和 resize 响应，只在成功后提交本地状态，失败保留原选择；用户可切换会话，退出有等待完成与再次强制退出两级路径。失效的主会话模式由 Core 恢复为可执行模式，TUI 显示迁移并阻止启动输入自动执行。本地工作区快照准备、会话文件清单、类型化统计和工作区文件回滚由 Desktop/Peer Host 共用的窄 owner port 调用现有 Core 实现；它不进入 SDK，不接受远程身份，Desktop 保留既有远程空结果，Peer Host 返回明确不支持错误，历史维护仍归宿主。账号同步、富历史及 Peer Host/ACP 其余持久化维护缺口仍由单一 Core 兼容门面转发。本切片不改变扩展执行边界 |
 | HarmonyOS PC 原生 CLI/TUI | 未来平台目标，当前未实现 | 目标、问题和风险见平台规约；具体适配另立专题，HAP、手机 Remote App 与远端代执行均不替代 |
 | HarmonyOS PC GUI | 完整 HarmonyOS PC 支持的另一目标形态，当前未实现 | 与 CLI/TUI 共享稳定能力和 Runtime 语义，但独立设计宿主、界面与发布验证；Web、Remote 或现有 Tauri Desktop 均不能替代 |
 | HarmonyOS 手机 Remote App | `src/apps/mobile/harmonyos` 是 phone-only ArkTS 远程入口，不持有本地 Rust Agent Runtime | 保持当前能力并按移动端专题独立演进；本轮不提前设计移动 Runtime/TUI/GUI，也不能据此宣称 HarmonyOS PC 本地能力 |
 | ACP | CLI 托管的服务端仍以 `bitfun-core/product-full` 作为兼容执行层 | 入口已选择 `DeliveryProfile::Acp` 并消费 Runtime Parts；组装层在入队前原子拒绝忙碌会话，不改变其他产品入口的排队行为；活动会话模型与模式写入走 SDK。`session/load` 先校验和建立临时 MCP，再恢复 Core，在历史回放成功后才发布活动状态；失败会卸载本次内存状态而不删除历史。同 ID 的重叠打开/关闭被明确拒绝。成功的 `session/close` 阻止新轮次、排空队列和后台子会话，再卸载临时 Core 状态并回收 MCP 与连接；失败保留会话所有权和历史，返回可重试阶段。持久化历史仍可重新加载。完整历史、模型/模式目录与配置读取仍留在现有 Core/ACP 归属，不据此宣称完整解耦 |
-| Server / Remote | 当前生产路由没有插件状态消费闭环；Remote 插件执行未实现 | 不在本地替远端项目发现、准备或执行插件；未接入时返回明确不支持 |
+| Server / Remote | Server 可返回 Host 只读外部来源快照并对变更操作 fail closed；Peer Host 已代理外部来源快照、策略和既有四类操作；SSH Remote 工作区的外部来源发现与执行仍未实现 | 只读 Host 不伪装为可管理；控制端用 Host 身份与工作区共同隔离异步结果。Peer Host 只处理 Host 上的真实工作区，不在控制端替远端发现；SSH Remote 未接入时返回明确不支持且不回退本机来源 |
 | Web / Mobile Web | 依赖现有后端入口，不持有插件执行单元 | 对应 profile 当前为空计划或未接入生产，不能据枚举值宣称独立产品能力 |
 | SDK | 仅有 preview 门面、空 profile 计划和测试替身 | 不牵引 `product-full`、具体服务管理器或插件 host ABI；未满足独立嵌入验证前不宣称可发布 |
 

docs/plans/opencode-extension-compatibility-plan.md

@@ -333,7 +333,8 @@ PR5 不新增扩展类型或运行能力，只补齐 Command、Tool、Subagent 
   因此只建议安装或修复后刷新，并说明用户可以继续使用其他能力；扩展入口不得建议或触发重启，也不得打断执行中的 session。
   未来若产品增加统一重启动作，必须由 session owner
   提供活动任务保护与恢复契约，默认允许“稍后”，不能由扩展模块自行判断。
-- Remote 工作区继续显示明确不支持；不加载本机配置代替远程配置。普通轮询仍为 5 秒，仅发现进行中使用 750 ms 有界轮询；
+- SSH Remote 工作区继续显示明确不支持；不加载本机配置代替远程配置。Peer 控制界面代理 Peer Host 的真实状态和操作，
+  不把控制端状态混入 Host。provider discovery deadline 仍为 5 秒；仅发现进行中使用请求完成后再调度的 750 ms、1.5 s、3 s、5 s 退避轮询；
   本轮不增加 watcher、全局扫描、遥测平台或磁盘缓存，不改变 system prompt。
 
 PR5 的退出条件是：三类已处理冲突在 GUI 中可见可改选；Tool/Subagent 在 TUI 中使用通用能力入口；原生候选顺序、