refactor: extract shared relay service and enforce Cargo boundary

.dockerignore

@@ -0,0 +1,14 @@
+**
+!src/
+!src/apps/
+!src/apps/relay-server/
+!src/apps/relay-server/Dockerfile
+!src/apps/relay-server/Cargo.toml
+!src/apps/relay-server/src/
+!src/apps/relay-server/src/**
+!src/crates/
+!src/crates/services/
+!src/crates/services/relay-service/
+!src/crates/services/relay-service/Cargo.toml
+!src/crates/services/relay-service/src/
+!src/crates/services/relay-service/src/**

AGENTS-CN.md

@@ -26,7 +26,7 @@ Stable Contracts and Security Control Plane 的边界以
 | 1 | 接口与入口层 | `src/apps/*`, `src/web-ui`, `src/mobile-web`, `BitFun-Installer`, `tests/e2e`, `src/crates/interfaces` | 产品宿主、命令、UI 入口、协议接口和跨形态测试 | desktop、CLI、server、relay、Web UI、mobile web、installer、E2E、`acp` | 最近的本地 `AGENTS.md`；[interfaces](src/crates/interfaces/AGENTS.md) |
 | 2 | 产品组装层 | `src/crates/assembly` | 兼容导出、产品能力选择、product-full 接线和 adapter/service 注册 | `core`, `product-capabilities` | [AGENTS.md](src/crates/assembly/AGENTS.md) |
 | 3 | 适配层 | `src/crates/adapters` | AI/API/transport/WebDriver/OpenCode 协议 adapter 和外部 provider 转换 | `ai-adapters`, `api-layer`, `opencode-adapter`, `transport`, `webdriver` | [AGENTS.md](src/crates/adapters/AGENTS.md) |
-| 4 | 服务实现层 | `src/crates/services` | 可复用 OS、filesystem、terminal、MCP、remote、git、watch、process、LSP plugin registry、session persistence primitives、network 和 MiniApp runtime IO 实现 | `services-core`, `services-integrations`, `terminal` | [AGENTS.md](src/crates/services/AGENTS.md) |
+| 4 | 服务实现层 | `src/crates/services` | 可复用 OS、filesystem、terminal、MCP、remote、git、watch、process、LSP plugin registry、session persistence primitives、network 和 MiniApp runtime IO 实现 | `services-core`, `services-integrations`, `relay-service`, `terminal` | [AGENTS.md](src/crates/services/AGENTS.md) |
 | 5 | 执行原语层 | `src/crates/execution` | 可移植 agent、harness、stream、DeepReview policy/report、plugin host 边界、typed-service、tool-contract、tool-group 和 tool-execution 构件 | `agent-runtime`, `agent-stream`, `tool-contracts`, `harness`, `plugin-runtime-host`, `runtime-services`, `tool-provider-groups`, `tool-execution` | [AGENTS.md](src/crates/execution/AGENTS.md) |
 | 6 | 稳定契约与产品领域层 | `src/crates/contracts` | 跨层共享 DTO、事件形状、runtime port、LSP protocol/plugin DTO、产品领域契约和策略 | `core-types`, `events`, `runtime-ports`, `product-domains` | [AGENTS.md](src/crates/contracts/AGENTS.md) |
 

AGENTS.md

@@ -27,7 +27,7 @@ Keep crate dependencies inside each layer to the smallest set needed.
 | 1 | Interfaces and entrypoints | `src/apps/*`, `src/web-ui`, `src/mobile-web`, `BitFun-Installer`, `tests/e2e`, `src/crates/interfaces` | Product hosts, commands, UI entrypoints, protocol interfaces, and cross-surface tests | desktop, CLI, server, relay, Web UI, mobile web, installer, E2E, `acp` | nearest local `AGENTS.md`; [interfaces](src/crates/interfaces/AGENTS.md) |
 | 2 | Product assembly | `src/crates/assembly` | Compatibility exports, product capability selection, product-full wiring, and adapter/service registration | `core`, `product-capabilities` | [AGENTS.md](src/crates/assembly/AGENTS.md) |
 | 3 | Adapters | `src/crates/adapters` | AI/API/transport/WebDriver/OpenCode protocol adapters and external-provider translation | `ai-adapters`, `api-layer`, `opencode-adapter`, `transport`, `webdriver` | [AGENTS.md](src/crates/adapters/AGENTS.md) |
-| 4 | Services | `src/crates/services` | Reusable OS, filesystem, terminal, MCP, remote, git, watch, process, LSP plugin registry, session persistence primitives, MiniApp runtime IO, and network implementations | `services-core`, `services-integrations`, `terminal` | [AGENTS.md](src/crates/services/AGENTS.md) |
+| 4 | Services | `src/crates/services` | Reusable OS, filesystem, terminal, MCP, remote, git, watch, process, LSP plugin registry, session persistence primitives, MiniApp runtime IO, and network implementations | `services-core`, `services-integrations`, `relay-service`, `terminal` | [AGENTS.md](src/crates/services/AGENTS.md) |
 | 5 | Execution primitives | `src/crates/execution` | Portable agent, harness, stream, DeepReview policy/report, plugin host boundary, typed-service, tool-contract, tool-group, and tool-execution building blocks | `agent-runtime`, `agent-stream`, `tool-contracts`, `harness`, `plugin-runtime-host`, `runtime-services`, `tool-provider-groups`, `tool-execution` | [AGENTS.md](src/crates/execution/AGENTS.md) |
 | 6 | Stable contracts and product domains | `src/crates/contracts` | Shared DTOs, event shapes, runtime ports, LSP protocol/plugin DTOs, and product domain contracts/policies | `core-types`, `events`, `runtime-ports`, `product-domains` | [AGENTS.md](src/crates/contracts/AGENTS.md) |
 

Cargo.toml

@@ -13,6 +13,7 @@ members = [
     "src/crates/adapters/transport",
     "src/crates/services/services-core",
     "src/crates/services/services-integrations",
+    "src/crates/services/relay-service",
     "src/crates/services/terminal",
     "src/crates/assembly/product-capabilities",
     "src/crates/contracts/product-domains",

docs/architecture/agent-runtime-services-design.md

@@ -714,7 +714,7 @@ ping 路由。未接入入口的 profile、枚举分支和单元测试仍不能
 | 阶段 | 约束 |
 |---|---|
 | 当前 | CLI 与 Peer Host 消费真实 Runtime Parts 与 SDK，Core 兼容门面只承接 SDK v1 缺口；不扩张字段或再造描述符 |
-| 迁移 | 迁移执行 owner 或继续接入 ACP、Desktop 前，必须分别证明行为等价；`assembly/core -> apps/relay-server` 反向依赖仍需消除 |
+| 迁移 | 迁移执行 owner 或继续接入 ACP、Desktop 前，必须分别证明行为等价；relay 的 Cargo 反向边已删除，room/device 状态、account/sync 存储、asset store 与 HTTP/WebSocket router 已下沉，但 embedded TCP bind、静态 fallback 和任务生命周期仍是 assembly 兼容债务 |
 | 完成 | 每个声称支持的 profile 都由生产入口消费组装结果，并有最小入口验证；无消费方的 profile 不对外宣称可用 |
 
 产品定义、品牌资源和界面布局的长期边界以
@@ -1007,7 +1007,8 @@ Product 测试：
 
 仍需完成：
 
-- 消除 `assembly/core -> apps/relay-server` 的反向依赖，并用通用边界检查固定依赖方向。
+- 把 embedded relay 的 TCP bind、静态 fallback 和任务生命周期移出 assembly；room/device 状态、account/sync
+  存储、asset store 与 HTTP/WebSocket router 已归属 `services/relay-service`，Cargo 反向边已删除并由通用边界检查保护。
 - 继续缩小 CLI 的 Core 兼容门面；只有稳定端口、真实生产调用方和行为等价测试齐备时才迁移 owner。
 - 让 ACP、Desktop 依次接入产品组装，并为每条路径证明行为等价；ACP 生命周期和 Desktop 平台资源仍留在入口。
 - 为 Agent Runtime SDK 增加至少一个非 `bitfun-core` 的真实嵌入方；预览 facade 和单元测试不等于外部可用 SDK。

docs/architecture/platform-portability-design.md

@@ -65,13 +65,13 @@ Runtime。Rust target 可编译、`hdc shell` 能运行二进制和 HAP 内能
 
 ## 4. 当前代码事实与风险
 
-基线为上游 `5e48999f94daf119c1217ed6b71ba878d564f5dd`。下表只记录已经从 manifest 或代码确认的事实；
+本轮 Relay 边界核对基线为上游 `cabbce88348a24124714101a9e6c2f6371206fa1`（2026-07-16）。下表只记录已经从 manifest 或代码确认的事实；
 目标依赖解析结果仍需由 target-specific `cargo tree` 证明。
 
 | 已确认事实 | 风险或影响 | 最小处理 |
 |---|---|---|
 | CLI 直接启用 `bitfun-core/product-full` | 不能据此形成可裁剪的 HarmonyOS 产物 | 先建立目标依赖清单，再按真实阻塞项拆分 |
-| `assembly/core` 依赖 `apps/relay-server` | 编译依赖方向反转 | 抽取可复用 relay owner，保持 standalone/embedded 行为等价 |
+| `assembly/core -> apps/relay-server` 反向边已删除，room/device 状态、account/sync 存储、asset store 与 HTTP/WebSocket router 已归属 `services/relay-service`；embedded TCP bind、静态 fallback 与任务生命周期仍在 assembly | `product-full` 仍携带具体宿主生命周期，不能据此证明 HarmonyOS 本地产品可用 | 后续把 embedded 宿主逻辑移到具体宿主；本轮不扩张 HarmonyOS 接口 |
 | `assembly/core` 直接包含 bundled `rusqlite` | 交叉编译包含原生 C 风险 | 在本地会话样例需要时验证或替换存储实现 |
 | 非 Windows `git2` 使用 vendored OpenSSL | OHOS 原生构建和动态链接风险 | Git 只在编码就绪阶段取证，不阻塞最小界面 |
 | CLI 无条件依赖 `arboard` | 可能带入桌面 Linux/X11 依赖 | 剪贴板改为可选能力，不阻塞核心路径 |

docs/architecture/product-architecture.md

@@ -270,8 +270,9 @@ flowchart LR
 - GUI/TUI 布局选择不复制主题 schema，不固化动态能力状态，也不携带可执行 UI 或任意构建脚本。
 - 新 profile 只有在真实入口消费组装结果、能力可用性和类型化降级后才算接入；仅有枚举、空计划、re-export
   或单测不构成产品支持。
-- assembly 不新增对 app crate 的依赖。现有嵌入式 relay 反向依赖必须通过抽取可复用 relay owner 消除，并由
-  边界检查阻止同类依赖回流。
+- assembly 不得依赖 app crate。relay 的 room/device 状态、account/sync 存储、asset store 与 HTTP/WebSocket router
+  归属 `services/relay-service`，Cargo metadata 实际解析图检查阻止同类依赖回流。embedded TCP bind、静态 fallback
+  和任务生命周期暂留 assembly 兼容路径，仍需迁往具体宿主；这项边界修复不构成 HarmonyOS 本地产品支持。
 - 平台支持按“目标依赖、编译、目标产品运行”三层取证。HarmonyOS 本地候选在 HAP 真机证明输入/绘制、路径、
   网络、存储和进程行为前不能标记可用，也不能静默回退 Desktop/Remote 执行。
 - 文档、边界脚本和 focused 测试能说明本次变更保护了哪个稳定接口切面，或删除/降级了哪个过宽接口。

docs/plans/core-decomposition-completed.md

@@ -18,6 +18,7 @@
 - 已抽取 `bitfun-core-types`、`bitfun-events`、`bitfun-runtime-ports`、`bitfun-agent-stream` 等基础契约；LSP protocol DTO 和 plugin manifest DTO 已进入 `bitfun-core-types`。
 - 已建立 `bitfun-services-core`、`bitfun-services-integrations`、`bitfun-agent-tools`、`tool-runtime`、`bitfun-tool-packs`、`bitfun-agent-runtime`、`bitfun-runtime-services`、`bitfun-harness`、`bitfun-product-domains`、`bitfun-product-capabilities` 等归属 crate。
 - `src/crates` 已按 `interfaces / assembly / adapters / services / execution / contracts` 六层布局整理，DeepReview path classifier、边界规则、Cargo workspace 路径和根/层级 AGENTS 已同步。
+- Cargo metadata 实际解析图检查已覆盖 workspace 与独立 manifest 的 normal、build、dev 依赖及 optional/target 变体；未知 crate 层级与反向依赖会直接失败。
 
 ## 2. 已迁移归属
 
@@ -28,6 +29,7 @@
 - `runtime-services` 已承接 typed runtime service assembly、capability availability、provider registry、capability validation、无副作用 capability marker ports 和 backend event delivery；core backend event system 只保留兼容 re-export。
 - `bitfun-events` 已承接 backend event DTO、agentic event DTO、framework-neutral Agentic frontend event projection、AgenticEvent projection manifest、event version / aggregate / replay / retention facts、legacy WebSocket event allowlist 和 platform-neutral `EventEmitter` trait；Tauri/WebSocket transport 只负责 delivery。
 - `services-integrations` 已承接 remote-connect primitives、wire command routing / response assembly、remote chat image metadata / display helper projection、remote image lifecycle attachment mapping、LAN IP/URL 探测、ngrok 进程/tunnel lifecycle、mobile-web relay upload manifest / incremental upload / fallback upload、IM bot provider-neutral config / persistence / file auto-push / locale / menu / state / command parsing、Weixin provider client、workspace search concrete owner、remote SSH/SFTP/PTY owner、Remote SSH disabled runtime surface、Remote SSH workspace/session identity helper、remote workspace-search disabled surface、DeepResearch report IO / display-map sidecar、MiniApp host dispatch / storage / worker / import IO、announcement remote fetch/cache、browser CDP endpoint HTTP probing / page creation、WebFetch / WebSearch concrete HTTP provider、debug-log 文件追加 / 脱敏 / HTTP dispatch、review-platform provider service / token store / HTTP transport / Git provider integration，以及 MCP server registry、connection pool、catalog cache、reconnect retry state、runtime-only config overlay、local command resolution helper、lifecycle status policy 和 MCP OAuth credential vault / store / authorization bootstrap；core 仍保留 debug-log HTTP ingest server、persisted turn adapter 和 MCP auth 的产品 data-dir 注入、授权入口、错误映射与 deprecated 兼容 wrapper。
+- `relay-service` 已承接 room/device 状态、account/sync 存储、asset store 和 HTTP/WebSocket router；standalone app 保留 bind、环境配置、静态 fallback、进程生命周期和管理 CLI，embedded 入口复用同一 router。embedded 的 bind、静态 fallback 和任务生命周期仍在 assembly 兼容路径，尚未完成宿主归位。
 - `tool-contracts` 已承接 provider-neutral tool DTO、manifest/catalog/admission/result presentation、Computer Use DTO/input parser/screenshot payload、confirmation facts、truncation recovery presentation、runtime restriction policy、provider-entry materialization、materialized tool snapshot、provider identity、permission/effect filter、cancellation contract 和 stale-call guard；core 只保留 Computer Use 旧 public path re-export / compatibility shim、产品 Tool trait 适配与产品执行入口。
 - `tool-execution` 已承接 local / remote IO helper、Bash shell helper、batching plan、retry policy、state counting、tool state event payload shaping / result redaction、cancellation-state/token-store policy、background exec output capture、ExecCommand provider-neutral 呈现 / 输入默认值 / 结果 shape / shell metadata / shell argv / remote shell probe / remote env snapshot 解析、cache 与 capture policy / lifecycle facts / control facts / completion shape、prompt-safe tool context facts / custom-data materialization、Computer Use loop detection / screenshot hash / verification / retry policy、WebFetch readable extraction / fallback / title / format facts、WebSearch Exa text result parsing，以及 File tool 的 provider-neutral 结果展示、写入 mode/status/line-count 规则、Edit guardrail 分类和 Delete success 文本；core 只保留 ToolResult 包装、权限、checkpoint、runtime handles、host adapter 调用、read-state adapter、remote FS 调用、Web tool network provider 调用和旧工具入口。
 - `runtime-ports` / `terminal-core` / `services-integrations` 已承接 ExecCommand 会话执行端口和 concrete provider：`TerminalPort` 暴露本地命令执行、stdin 写入、会话控制和生命周期事件边界，`RemoteExecPort` 暴露远端 SSH 命令执行、bounded one-shot command、stdin、会话控制和生命周期事件边界；`TerminalRuntimePort` 复用原本地 `ExecProcessManager` 行为，`RemoteExecRuntimePort` 复用原 remote exec manager 与旧 SSH one-shot 行为，当前 desktop / CLI 产品入口和保留 server bootstrap 初始化路径通过 `CoreRuntimeServicesProvider` 构造 provider 并显式注入 `ConversationCoordinator` / 执行上下文 / `ToolRuntimeHandles`；core `ExecCommand` / `WriteStdin` / `ExecControl` 只消费端口，不再直接调用全局本地或远端进程 manager。

docs/plans/core-decomposition-plan.md

@@ -27,7 +27,7 @@
 | Server / Remote / Web / Mobile Web / SDK profile | 当前为空计划、未接入入口或仅有 preview 测试 | 不得据枚举值宣称产品能力已交付 |
 | Agent Runtime SDK | 已有无 `bitfun-core` 依赖的 v1 preview 门面和 smoke test | 发布边界仍需真实嵌入方证明 |
 | 插件运行时 | 现有路径只覆盖 BitFun 原生包和 OpenCode custom tool 静态名称预览 | 不能据通用 envelope 或静态候选扩张稳定 ABI |
-| Relay | `assembly/core` 直接依赖 `apps/relay-server` 以复用嵌入式 relay | 依赖方向反转，且当前边界检查未阻止该问题 |
+| Relay | room/device 状态、account/sync 存储、asset store 与 HTTP/WebSocket router 已归属 `services/relay-service`，standalone 与 embedded 入口同向消费；embedded 宿主逻辑仍在 assembly 兼容路径 | Cargo metadata 门禁覆盖 workspace、独立 manifest、normal/build/dev 依赖及 optional/target 变体；宿主归位是独立后续工作 |
 | CLI CI | 独立 Linux job 运行 CLI test，通用三平台 workspace check 覆盖 CLI 编译；发布工作流负责打包 | 参数/序列化/前置失败和组装已有 focused contract；真实模型/PTY、Patch I/O 失败与常规 package smoke 仍需补齐 |
 
 ## 3. 目标依赖与归属
@@ -41,17 +41,18 @@
 | contracts | 稳定 DTO、事实和端口 | 依赖上层或持有运行时行为 |
 
 需要同时被独立应用和嵌入式模式复用的能力，先下沉为 services/adapters owner，再由 app 与 assembly 同向消费。
-Relay 是该规则的首个修复对象；不能把 `apps/relay-server` 改名后继续作为下层库。
+Relay 已按该规则完成首个修复；后续共享实现仍不得以 app crate 充当下层库。
 
 ## 4. 迁移顺序
 
-### 4.1 先修边界保护
+### 4.1 已完成边界保护
 
-1. 抽取 relay router、room 与 asset-store 的可复用 owner。
-2. 让 standalone relay app 和嵌入式入口都依赖该 owner，删除 `assembly/core -> apps/relay-server`。
-3. 为 crate 层级依赖增加通用边界检查和反向用例，避免只保护已知 crate 名称。
+1. relay router、room、存储与 asset-store 已归属 `services/relay-service`。
+2. standalone relay app 和嵌入式入口共同依赖该 owner，`assembly/core -> apps/relay-server` 已删除。
+3. crate 层级依赖已增加 Cargo metadata 通用检查和反向用例，不再只保护已知 crate 名称。
 
-退出条件：生产行为与 standalone/embedded relay 测试等价，Cargo 图不再包含 assembly → apps。
+共享 owner 与 Cargo 方向的退出条件已满足：standalone 与 embedded 入口共用同一已测试 router，Cargo 图不再包含
+assembly → apps。embedded 的 bind、静态 fallback 和任务生命周期移出 assembly 是独立后续工作。
 
 ### 4.2 切换 CLI 纵向路径
 
@@ -121,7 +122,7 @@ Core 只为插件兼容提供已有 owner 的窄接口：真实工具、类型
 |---|---|
 | 文档与仓库边界 | `pnpm run check:repo-hygiene`，`node --test scripts/check-core-boundaries.test.mjs`，`node scripts/check-core-boundaries.mjs` |
 | 入口 profile 迁移 | 对应 app 的 check/test、入口级 smoke、profile/服务可用性断言、旧路径等价用例 |
-| Relay owner 迁移 | standalone 与 embedded focused tests、Cargo 依赖方向失败用例 |
+| Relay 共享 owner / Cargo 方向 | standalone 与 embedded focused tests、Cargo 依赖方向失败用例；embedded 宿主归位另行验证生命周期等价 |
 | Agent Runtime / SDK | `cargo test -p bitfun-agent-runtime`，最小 no-`bitfun-core` 嵌入测试 |
 | 插件首个执行切片 | runtime ports、Host、adapter、Tool Runtime 与真实冻结 fixture 的端到端调用 |
 | CLI | `cargo check -p bitfun-cli`，`cargo test -p bitfun-cli`，结构化协议和 package smoke |