feat(doct): add app server design

AGENTS-CN.md

@@ -25,7 +25,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`、`sdk-host` | 最近的本地 `AGENTS.md`；[interfaces](src/crates/interfaces/AGENTS.md) |
 | 2 | 产品组装层 | `src/crates/assembly` | 兼容导出、产品能力选择、product-full 接线、adapter/service 注册和生态无关的来源协调 | `core`, `external-sources`, `product-capabilities` | [AGENTS.md](src/crates/assembly/AGENTS.md) |
-| 3 | 适配层 | `src/crates/adapters` | AI/transport/WebDriver 协议 adapter、外部 AI work source adapter（OpenCode/Claude Code/Codex）和外部 provider 转换 | `agent-runtime-ipc`、`ai-adapters`, `opencode-adapter`, `claude-code-adapter`, `codex-adapter`, `static-hook-support`, `transport`, `webdriver` | [AGENTS.md](src/crates/adapters/AGENTS.md) |
+| 3 | 适配层 | `src/crates/adapters` | AI/transport/WebDriver 协议 adapter、外部 AI work source adapter（OpenCode/Claude Code/Codex）和外部 provider 转换 | `agent-runtime-ipc`（仅迁移）、`ai-adapters`, `opencode-adapter`, `claude-code-adapter`, `codex-adapter`, `static-hook-support`, `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`, `relay-service`, `page-function-runtime`, `terminal` | [AGENTS.md](src/crates/services/AGENTS.md) |
 | 5 | 执行原语层 | `src/crates/execution` | 可移植 agent、harness、stream、DeepReview policy/report、插件运行时客户端、typed-service、tool-contract、tool-group 和 tool-execution 构件 | `agent-runtime`, `agent-stream`, `tool-contracts`, `harness`, `plugin-runtime-client`, `runtime-services`, `tool-provider-groups`, `tool-execution`, `tool-call-jsonrepair` | [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) |
@@ -191,13 +191,23 @@ await api.invoke('your_command', { request: { ... } });
 仓库级拆解规则：
 
 - 不要把 DTO / contract 抽取误判为 runtime owner 已迁移。
-- 产品表面可以有差异；共享稳定 facts 或 ports，不共享 UI、protocol、lifecycle 或平台实现。
+- 产品表面可以有差异；共享稳定 facts 或 ports。只有 Rich Client App Server consumer 等明确版本化的同一产品家族
+  才共享 protocol；UI、lifecycle 和平台实现仍不共享。
 - 迁移 runtime owner 必须有评审过的 port/provider 设计、旧路径兼容、行为等价测试；如果可能改变行为边界，还需要先确认。
 
 涉及 Agent Runtime 部署、多 GUI/TUI/Remote 实例、共享 Session 控制或进程拓扑时，还必须阅读
 [`docs/architecture/agent-runtime-deployment-design.md`](docs/architecture/agent-runtime-deployment-design.md)。
-Rust Runtime 或 Node/Bun Plugin Host 不得默认按 Client、workspace、session 或 plugin 分进程；进程边界必须来自真实状态
-owner、execution/security domain、可兼容的安全条件和测量后的容量事实。
+App Server 只存在 Embedded（一个 Client 对一个 Server）与 Shared（同一种 `client_kind` 的多个 Client 对一个
+Server）两种部署。Shared Rust Runtime 或 Node/Bun Plugin Host 不得默认按窗口、workspace、session 或 plugin 分进程；
+进程边界必须来自真实状态 owner、`client_kind`、execution/security domain、可兼容的安全条件和测量后的容量事实。
+
+涉及 Rich Client 前后端分离、Desktop 替换 Electron、VS Code Extension 接入、App Server schema/transport 或第一方 GUI
+进程拓扑时，还必须阅读
+[`docs/architecture/app-server-architecture-design.md`](docs/architecture/app-server-architecture-design.md)。Rich Client（包括交互式
+TUI）的 Embedded 与 Shared 部署共享同一 App Server wire，但领域契约仍归 Runtime/能力 owner。Embedded 只接受一个
+Client；Shared 只接受固定 `client_kind` 的多个 Client，TUI、Tauri Desktop、Electron Desktop、VS Code 和 Web 不得连接
+同一个实例；`client_kind` 表示具体宿主形态，不是宽泛界面类别。网络、租户和运维约束不形成 Hosted 第三形态。
+Headless CLI、ACP、SDK Host 保持独立协议和生命周期边界，不保留第二套 Shared TUI wire 或 handler。
 
 ### CLI 产品线护栏
 

AGENTS.md

@@ -26,7 +26,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`, `sdk-host` | nearest local `AGENTS.md`; [interfaces](src/crates/interfaces/AGENTS.md) |
 | 2 | Product assembly | `src/crates/assembly` | Compatibility exports, product capability selection, product-full wiring, adapter/service registration, and ecosystem-neutral source coordination | `core`, `external-sources`, `product-capabilities` | [AGENTS.md](src/crates/assembly/AGENTS.md) |
-| 3 | Adapters | `src/crates/adapters` | AI/transport/WebDriver protocol adapters, external AI work source adapters (OpenCode/Claude Code/Codex), and external-provider translation | `agent-runtime-ipc`, `ai-adapters`, `opencode-adapter`, `claude-code-adapter`, `codex-adapter`, `static-hook-support`, `transport`, `webdriver` | [AGENTS.md](src/crates/adapters/AGENTS.md) |
+| 3 | Adapters | `src/crates/adapters` | AI/transport/WebDriver protocol adapters, external AI work source adapters (OpenCode/Claude Code/Codex), and external-provider translation | `agent-runtime-ipc` (migration-only), `ai-adapters`, `opencode-adapter`, `claude-code-adapter`, `codex-adapter`, `static-hook-support`, `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`, `miniapp-market-service`, `relay-service`, `page-function-runtime`, `terminal` | [AGENTS.md](src/crates/services/AGENTS.md) |
 | 5 | Execution primitives | `src/crates/execution` | Portable agent, harness, stream, DeepReview policy/report, plugin runtime client, typed-service, tool-contract, tool-group, and tool-execution building blocks | `agent-runtime`, `agent-stream`, `tool-contracts`, `harness`, `plugin-runtime-client`, `runtime-services`, `tool-provider-groups`, `tool-execution`, `tool-call-jsonrepair` | [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) |
@@ -203,18 +203,35 @@ details in the nearest module `AGENTS.md`.
 Repository-level decomposition rules:
 
 - Do not confuse DTO/contract extraction with runtime owner migration.
-- Product surfaces may diverge; share stable facts or ports, not UI, protocol,
-  lifecycle, or platform implementation.
+- Product surfaces may diverge; share stable facts or ports. Share a protocol
+  only inside an explicitly versioned product family such as Rich Client App
+  Server consumers, and never share UI, lifecycle, or platform implementation.
 - Moving runtime ownership requires a reviewed port/provider design, old-path
   compatibility, behavior equivalence tests, and explicit confirmation when a
   behavior boundary could change.
 
 For Agent Runtime deployment, multi-GUI/TUI/Remote instances, shared Session
 control, or process-topology changes, also read
 [`docs/architecture/agent-runtime-deployment-design.md`](docs/architecture/agent-runtime-deployment-design.md).
-Do not key Rust Runtime or Node/Bun Plugin Host processes by client, workspace,
-session, or plugin by default; use the responsible state module, execution and
-security conditions, and measured capacity.
+App Server has only Embedded (one client to one server) and Shared (multiple
+clients of one `client_kind` to one server) deployments. Do not key Shared Rust
+Runtime or Node/Bun Plugin Host processes by window, workspace, session, or
+plugin by default; use the responsible state module, `client_kind`, execution
+and security conditions, and measured capacity.
+
+For Rich Client/backend separation, Desktop-to-Electron replacement, VS Code
+Extension integration, App Server schema/transport, or first-party GUI process
+topology, also read
+[`docs/architecture/app-server-architecture-design.md`](docs/architecture/app-server-architecture-design.md).
+Rich Clients, including interactive TUI, share one App Server wire across
+Embedded and Shared deployments, while domain contracts remain with their
+Runtime/capability owners. An Embedded server accepts exactly one client; a
+Shared server accepts multiple clients of one fixed `client_kind`, so TUI,
+Tauri Desktop, Electron Desktop, VS Code, and Web never connect to the same
+instance. `client_kind` identifies the concrete host form, not a broad UI
+category. Network, tenant, and operational constraints do not create a Hosted
+third deployment. Headless CLI, ACP, and SDK Host keep separate protocol and
+lifecycle boundaries; do not retain a second Shared TUI wire or handler.
 
 ### CLI product-line guardrails