Initialize cross-platform workspace host scaffold

2026-09-29 11:30:51 +08:00
commit 4bc3552167
56 changed files with 2627 additions and 0 deletions
@@ -0,0 +1,22 @@
+# 文档库
+
+## 产品与架构
+
+- [总功能描述与平台差异](overview.md)
+- [组件架构](architecture.md)
+- [身份认证和授权](authentication.md)
+- [连接与会话协议](connection-protocol.md)
+- [交付状态](implementation-status.md)
+
+## 平台专题
+
+总功能描述中的差异表链接到每项差异的独立文档，覆盖服务宿主、用户环境、PTY、进程权限、生命周期、文件存储、系统管理和发布部署。
+
+## 开发与运行
+
+- [开发与构建](development.md)
+- [验证与验收](testing.md)
+- [Windows 部署模板](../deploy/windows/README.md)
+- [Linux 部署模板](../deploy/linux/README.md)
+
+文档中的“设计”描述目标行为，“交付状态”描述代码已经实现的能力。接口契约与平台运行验收共同约束后续开发。
@@ -0,0 +1,53 @@
+# 组件架构
+
+## 运行结构
+
+```mermaid
+flowchart LR
+    Client[远程客户端] -->|OIDC 登录| Auth[authentik]
+    Client -->|WSS| Broker[Host / Broker]
+    Broker --> Policy[认证校验与系统账户映射]
+    Broker --> Gate[Host 独占控制权]
+    Broker -->|本机认证 IPC| Agent[用户会话代理]
+    Agent --> Terminal[PTY 与终端状态]
+    Terminal --> Shell[shell / TUI 进程]
+```
+
+## 代码组织
+
+解决方案包含一个产品项目 `src/WorkspaceAccessHost.csproj`、一个测试项目 `WorkspaceAccessHost.Tests` 和一个 NUKE 构建项目 `Build`。产品代码直接在 `src/` 下通过目录和命名空间组织职责：
+
+| 产品目录 | 职责 |
+| --- | --- |
+| `Core/` | 共享模型、平台描述和契约 |
+| `Authentication/` | 外部身份、认证与系统账户映射 |
+| `Connections/` | 连接控制权、接管和工作区归属 |
+| `Terminals/` | PTY 契约、终端状态与输入输出 |
+| `Platforms/Windows/` | Windows 平台策略及 ConPTY、用户令牌、命名管道的实现位置 |
+| `Platforms/Linux/` | Linux 平台策略及 PTY、UID/GID、Unix socket 的实现位置 |
+| `Hosting/` | 服务生命周期、网络入口、连接仲裁和健康检查 |
+| `Agent/` | 用户上下文中的终端、子进程和画面状态 |
+
+领域逻辑依赖接口与共享模型，系统调用集中在对应平台目录，入口负责注册平台实现。
+
+## 程序角色
+
+同一套发布产物以 `WorkspaceAccessHost host` 运行服务宿主，以 `WorkspaceAccessHost agent` 运行用户代理。Windows 可执行文件带 `.exe` 扩展名。角色参数后的选项传递给对应宿主构建器；无参数或 `--help` 显示使用方式，未知角色以退出码 2 结束。
+
+Host 和 Agent 分别运行在服务账户与目标用户上下文中，各自拥有进程生命周期，通过本机 IPC 协作。测试与 NUKE 项目承担验证和开发控制职责。
+
+## 生命周期和信任边界
+
+authentik 身份、broker 连接、系统登录上下文、工作区和终端拥有独立标识。客户端的系统用户名是授权请求；最终账户由服务端映射规则确定。
+
+代理 IPC 需要验证对端的系统身份、目标用户、host 实例和协议版本。Windows 使用命名管道 ACL，Linux 使用 socket 文件权限与对端凭据。代理仅接受经验证的 broker 指令。
+
+broker 使用服务账户运行。Windows 用户代理通过目标用户登录启动；Linux 启动组件负责完成组、用户和会话设置后交给用户代理。系统身份切换保持在明确的本机接口中。
+
+首期 broker 进程生命周期是连接控制状态的边界。用户代理在 WebSocket 断开时持续存在；broker 重启后的代理重新登记、归属恢复与控制权版本同步需要完成集成验收。
+
+## 终端契约
+
+`IPtySessionFactory` 在已建立的用户上下文中启动终端。`IPtySession` 提供输入、输出、尺寸变更、退出状态和显式终止。工作区管理器拥有会话，传输关闭只解除附着。
+
+代理持续消费输出，维护有容量上限的历史和终端状态。快照与输出序列号形成重连边界，输出积压策略由协议规定。
@@ -0,0 +1,23 @@
+# 身份认证与授权
+
+## 身份来源
+
+authentik 提供 OIDC 身份认证、MFA 和应用访问策略。操作系统管理系统账户、组和文件权限。Host 配置受信任 issuer、客户端标识和账户映射规则，运行数据记录身份与工作区的关系。
+
+稳定外部身份为经过验证的 `(iss, sub)`。Windows 账户解析为 SID，Linux 账户解析为 UID、主组和附加组。映射配置可来自管理员配置或受管理员控制的可信声明。
+
+## 登录流程
+
+浏览器客户端采用 Authorization Code + PKCE，应用校验 state、nonce、签名、issuer、audience 和有效期。会话密钥与客户端密钥通过部署配置管理。浏览器会话使用 Secure、HttpOnly Cookie，并在握手时校验 Origin；变更操作采用 CSRF 防护。
+
+完成登录后，按 host 访问规则、目标系统账户映射和代理状态进行授权，再进入连接控制权获取阶段。每次重连与接管均重新检查授权。授权撤销时关闭传输并撤销控制权，工作区结束策略由 host 管理配置确定。
+
+## 会话归属
+
+host 工作区有一个外部身份所有者。断线保留所有者；同身份可重连或显式接管。工作区终止并清理后释放归属。两个外部身份即使映射到同一系统账户，也保持各自的工作区授权边界。
+
+## 审计
+
+记录事件时间、host、身份标识、系统账户标识、连接标识、控制权版本及结果。认证凭据、Cookie 和终端内容采用独立的数据保护策略。常规审计聚焦身份与生命周期事件。
+
+参考：[authentik OIDC](https://docs.goauthentik.io/add-secure-apps/providers/oauth2)。实现阶段见[交付状态](implementation-status.md)。
@@ -0,0 +1,39 @@
+# 连接与会话协议
+
+本文定义传输集成时应遵守的行为契约。当前共享核心实现控制权仲裁，消息编码和端点处于集成阶段。
+
+## 连接状态
+
+```text
+Authenticated → Authorized → Acquired → Attached
+                                ↑          ↓
+                             Reconnect ← Detached
+```
+
+host 工作区归属随创建建立，随显式结束释放。连接断开只改变附着状态。
+
+## 控制权
+
+- 首次授权连接取得控制权。
+- 同身份第二连接提交显式 takeover 请求后，原连接失效。
+- 其他身份得到 host 已被占用的响应。
+- 每次控制权获取生成新的连接 ID 和递增 generation。
+- 每个 broker 实例另有独立 epoch；IPC 集成使用 `(epoch, generation, connectionId)` 标识控制权。
+- WebSocket 关闭、心跳超时或授权失效时，按连接标识撤销控制权。
+
+`HostConnectionGate` 使用进程内不可伪造的 lease 对象。`TryDispatch` 在同一临界区中完成校验与同步入队，接管与输入接受存在确定顺序。接管完成后旧 lease 的输入、关闭与释放均被拒绝；接管前已接受的输入按队列顺序执行。真正传输集成应把控制消息与输入交由同一有序派发路径处理。
+
+## 消息职责
+
+| 消息 | 内容与行为 |
+| --- | --- |
+| Attach | 目标工作区、协议版本、显式接管意图 |
+| Input | 二进制终端输入，绑定已验证连接与控制权 |
+| Resize | 有界列数与行数，绑定当前控制权 |
+| Output | 二进制终端输出与递增序列号 |
+| Snapshot | 屏幕、光标、终端模式、历史边界和输出序列号 |
+| Heartbeat | 检测失效连接并触发释放 |
+| Detach | 结束传输，保留工作区 |
+| Terminate | 授权后结束工作区进程并释放归属 |
+
+终端数据按字节传输，控制消息使用独立类型。输入限制、输出缓冲上限、快照一致性和客户端尺寸变化由协议实现和测试固定。传输入口先完成认证授权，再允许升级及访问工作区。
@@ -0,0 +1,54 @@
+# 开发与 NUKE 构建
+
+## 工具链
+
+安装 `global.json` 指定的 .NET 10 SDK，SDK 补丁选择遵循 `latestPatch`。包版本集中放在 `Directory.Packages.props`，每个项目的 `packages.lock.json` 记录依赖解析结果。
+
+`src/WorkspaceAccessHost.csproj` 声明完整 RID 集合，使各平台发布共享稳定的依赖锁。产品代码直接按职责组织在 `src/` 下。解决方案包含产品、测试和 NUKE 三个项目。构建入口关闭 NUKE 遥测，编译和发布使用独立构建进程。
+
+Windows 使用 `./build.ps1`，Linux 使用 `bash ./build.sh`。两者都运行 `build/Build.csproj` 中的 NUKE 程序。也可直接执行：
+
+```text
+dotnet run --project build/Build.csproj --configuration Release -- --target Verify
+```
+
+## 构建目标
+
+| 目标 | 行为 |
+| --- | --- |
+| Restore | 恢复解决方案依赖；`--locked-restore` 启用锁定模式 |
+| Compile | Restore 后构建整个解决方案 |
+| Test | Compile 后执行核心测试并输出 TRX |
+| CheckDocs | 检查标题、相对链接文件、README 可达性及差异说明覆盖 |
+| Verify | CheckDocs 与 Test；默认目标 |
+| Publish | Verify 后按 `--runtime` 发布单一产品和部署模板 |
+| RunHost | Compile 后以 `host` 角色前台运行产品 |
+| RunAgent | Compile 后以 `agent` 角色在当前用户身份下运行产品 |
+
+配置参数为 `--configuration Debug` 或 `Release`。发布 RID 为 `win-x64`、`win-arm64`、`linux-x64`、`linux-arm64`。
+
+```powershell
+./build.ps1 --target Verify --locked-restore
+./build.ps1 --target Publish --runtime win-x64
+./build.ps1 --target Publish --runtime linux-x64
+```
+
+## 开发检查
+
+1. 修改实现及对应设计文档。
+2. 为身份边界、并发控制和资源生命周期增加测试。
+3. 执行 Verify，检查 `artifacts/test-results/`。
+4. 涉及原生行为时，在目标系统执行[平台验收](testing.md)。
+
+依赖升级时先修改集中版本，再执行 Restore，检查锁文件变化并执行 Verify。CI 先以锁定模式恢复构建程序，再通过 NUKE 验证和发布。
+
+## 本地运行
+
+Host 默认地址为 `http://127.0.0.1:5080`，命令行 `--urls` 或环境变量 `ASPNETCORE_URLS` 可覆盖地址。直接运行示例：
+
+```text
+dotnet run --project src -- host --urls http://127.0.0.1:5081
+dotnet run --project src -- agent
+```
+
+健康检查分别为 `/health/live` 和 `/health/ready`。当前行为见[交付状态](implementation-status.md)。
@@ -0,0 +1,31 @@
+# 交付状态
+
+## 框架已实现
+
+| 模块 | 可验证内容 |
+| --- | --- |
+| 解决方案 | 单一 .NET 10 产品项目、测试项目、NUKE 项目、集中包版本与依赖锁文件 |
+| NUKE | Restore、Compile、Test、CheckDocs、Verify、Publish、RunHost、RunAgent |
+| Host | `host` 角色、ASP.NET Core 入口、Windows Service / systemd 生命周期集成、loopback 健康端点 |
+| Agent | `agent` 角色、目标用户进程入口、日志、宿主退出响应 |
+| 平台层 | `Platforms/Windows` 与 `Platforms/Linux` 目录及平台描述 |
+| 核心契约 | 外部身份、终端尺寸与 PTY 会话接口 |
+| 连接仲裁 | host 独占、显式接管、断线保留归属、过期 lease 拒绝与并发控制 |
+| 开发治理 | 平台差异文档、链接和导航校验、双平台 CI、服务部署模板 |
+
+## 集成工作
+
+| 阶段 | 实现内容 | 验收入口 |
+| --- | --- | --- |
+| 用户代理 | Windows 登录启动、命名管道；Linux 用户启动组件与 socket | 系统账户归属及 IPC 对端校验 |
+| 终端后端 | ConPTY、POSIX PTY、输入输出与进程清理 | 交互 shell、尺寸变更、退出及断线运行 |
+| 认证授权 | authentik OIDC、账户映射、host 授权及撤销 | 两个外部身份和两个系统账户的访问测试 |
+| 传输接入 | WSS、显式接管、心跳、有序输入 | 旧连接输入拒绝与网络恢复 |
+| 终端状态 | 屏幕状态、输出历史、快照同步 | 全屏编辑器重连后的画面一致性 |
+| 存储验收 | 目标 VirtioFS 版本与挂载配置 | 权限、变更通知、锁与保存行为 |
+
+## 健康状态
+
+`/health/live` 表示 HTTP 宿主存活。`/health/ready` 在框架阶段返回 HTTP 503，列出 OIDC、代理 IPC、PTY 和 WebSocket 集成项。就绪检查在接入真实组件后按实际依赖状态计算。
+
+构建和发布证明代码与依赖可生成目标平台产物。操作系统用户上下文、服务安装、PTY 和 VirtioFS 行为通过目标系统上的集成验收确认。
@@ -0,0 +1,42 @@
+# 总功能描述
+
+## 产品目标
+
+Workspace Access Host 提供持续存在的字符终端工作区。用户完成 authentik OIDC 认证后，以已授权的系统用户身份访问 shell 与 TUI 程序。Windows 和 Linux 共享连接、授权和工作区模型，通过平台适配实现系统服务、用户执行上下文与伪终端。
+
+产品使用单一 C# 项目，内部按目录组织架构。发布程序通过 `host` 和 `agent` 参数分别运行系统服务与用户代理角色，共享一套部署产物。
+
+## 功能
+
+| 功能 | 当前设计 |
+| --- | --- |
+| 身份来源 | authentik 管理外部身份，操作系统管理系统账户 |
+| 身份关联 | 以 `(issuer, subject)` 标识外部身份，管理员配置系统账户映射与 host 访问规则 |
+| 远程连接 | 客户端经 WSS 连接 broker，控制与终端数据按协议传输 |
+| 连接独占 | 每个 host 一个有效远程连接；同身份显式接管时撤销旧控制权 |
+| 工作区归属 | 归属独立于连接存在；断线后原身份可重新附着 |
+| 终端持久性 | 用户代理持有 PTY 与进程，连接断开期间继续运行和读取输出 |
+| 画面恢复 | 按终端状态快照与有序输出恢复光标、屏幕及滚动历史 |
+| 输入控制 | 输入、终端缩放及会话变更均校验当前连接控制权 |
+| 文件访问 | 遵循执行账户及实际存储后端权限；并行编辑使用独立工作目录 |
+| 数据保存 | 应用负责文件保存，代理保存运行期间的终端状态；系统启动后建立新的运行会话 |
+| 审计 | 记录认证结果、映射、连接获取、接管和会话结束等事件 |
+
+## 平台差异
+
+| 项目 | Windows | Linux | 详细说明 |
+| --- | --- | --- | --- |
+| 服务宿主与 IPC | Windows Service、命名管道 | systemd、Unix domain socket | [服务宿主](platforms/service-hosting.md) |
+| 用户环境来源 | 目标用户已登录时启动用户代理，关联 SID | 为现有系统账户建立 UID/GID 用户上下文 | [用户环境](platforms/user-environment.md) |
+| 伪终端 | ConPTY 与 Windows 进程 API | POSIX PTY、控制终端与进程组 | [终端后端](platforms/terminal-backend.md) |
+| 权限与进程边界 | Windows 访问令牌、对象 ACL、Job Object | UID/GID、文件权限、cgroup 和进程组 | [权限与进程](platforms/process-security.md) |
+| 用户会话生命周期 | 跟随用户登录会话，锁屏期间保持工作区 | 跟随用户会话宿主与服务策略运行 | [生命周期](platforms/session-lifecycle.md) |
+| 文件系统与共享目录 | NTFS 或 VirtioFS；验证 SID 与宿主权限映射 | 原生文件系统或挂载目录；验证 UID/GID 与锁行为 | [存储访问](platforms/storage.md) |
+| 系统管理权限 | Windows 用户权限分配和提升策略 | sudo、polkit 与服务权限策略 | [系统管理](platforms/system-control.md) |
+| 发布与注册 | Windows RID、SCM 注册和用户登录启动 | Linux RID、systemd system/user unit | [发布部署](platforms/deployment.md) |
+
+## 使用条件
+
+Windows 标准运行方式是已登录用户代理。宿主进入等待状态后，目标用户登录即可建立代理上下文。部署可以选用专门的本地账户。Linux 的用户上下文由受控启动组件创建。两个平台的首期连接策略均为 host 级独占。
+
+当前代码覆盖范围见[交付状态](implementation-status.md)，验收项见[验证文档](testing.md)。
@@ -0,0 +1,17 @@
+# 平台发布与部署
+
+| 项目 | Windows | Linux |
+| --- | --- | --- |
+| 发布 RID | `win-x64`、`win-arm64` | `linux-x64`、`linux-arm64` |
+| 产品入口 | `WorkspaceAccessHost.exe host` / `agent` | `WorkspaceAccessHost host` / `agent` |
+| 服务管理 | SCM 注册、启动类型和账户配置 | systemd unit、服务账户和目录权限 |
+| 用户代理启动 | 用户登录启动任务或用户启动项 | 用户上下文启动组件或 user unit |
+| 本机通信路径 | 命名管道 | `/run` 下受控 socket 路径 |
+
+NUKE `Publish` 先执行 Verify，再发布单一产品的 self-contained 产物，并复制平台部署模板。输出位于 `artifacts/publish/<runtime>/`，根目录包含可执行文件、配置与运行时依赖，`deploy/` 包含部署模板。Host 和 Agent 使用同一可执行文件，通过启动参数选择角色，整套产物统一部署和更新。
+
+服务配置使用发布目录中的 `appsettings.json` 和 .NET 环境变量覆盖。初始 HTTP 端点位于 loopback。远程传输集成时由受控 TLS 入口提供 WSS，并配置 host 白名单、认证及 Origin 策略。
+
+x64 的 Windows 与 Linux 验证流程由 CI 分别执行。ARM64 产物通过指定 RID 发布，并在对应硬件或虚拟机完成运行验收。
+
+部署步骤见 [Windows](../../deploy/windows/README.md) 与 [Linux](../../deploy/linux/README.md)。服务安装由部署人员执行。
@@ -0,0 +1,16 @@
+# 进程权限与隔离
+
+| 层次 | Windows | Linux |
+| --- | --- | --- |
+| 账户权限 | 用户访问令牌、SID 与文件 ACL | UID、GID、附加组与文件权限 |
+| 代理 IPC | 命名管道 ACL 与对端身份校验 | socket 路径权限与 peer credentials |
+| 进程归属 | Job Object 与进程句柄 | 进程组与 systemd/cgroup |
+| 系统管理 | 令牌权限及提升策略 | capabilities、sudo、polkit |
+
+网络宿主以服务账户执行网络与授权逻辑；用户代理以目标账户执行终端程序。身份切换或代理创建接口接受经过验证的账户映射和限定启动参数。
+
+工作区清理追踪完整进程树。显式结束先执行有序退出，再按策略终止剩余进程，并释放 PTY 及本机通信资源。
+
+完全复用用户环境时，终端具备该用户相应的系统访问能力。部署权限策略决定进程提升、系统管理和共享目录访问范围。文件权限在实际存储后端验收，见[存储说明](storage.md)。
+
+验收包括不同账户的代理访问、伪造映射、越权工作目录、子进程清理，以及普通账户的管理权限边界。
@@ -0,0 +1,16 @@
+# 服务宿主与本机通信
+
+| 平台 | 系统入口 | 用户代理通信 |
+| --- | --- | --- |
+| Windows | Windows Service Control Manager；`AddWindowsService` | 带 SID ACL 的命名管道 |
+| Linux | systemd system unit；`AddSystemd` | 带文件权限和对端凭据检查的 Unix domain socket |
+
+Host 负责远程连接与控制权仲裁，用户代理持有工作区。服务账户具备配置读取与本机通信所需的权限。IPC 连接建立后验证协议版本、对端系统身份和目标账户。
+
+Windows 代理在目标用户登录时启动。Linux 用户代理由用户上下文启动组件管理。本机通信路径按 host 与系统用户标识确定，进程启动后执行注册握手。
+
+当前 Host 已集成系统服务生命周期与健康检查。IPC 注册属于后续集成项。部署入口见 [Windows](../../deploy/windows/README.md) 与 [Linux](../../deploy/linux/README.md)。
+
+验收：服务随系统启动；服务停止完成资源清理；代理识别正确服务身份；其他账户访问 IPC 时按规则返回拒绝结果。
+
+参考：[Windows Service](https://learn.microsoft.com/en-us/dotnet/core/extensions/windows-service)、[systemd 集成](https://devblogs.microsoft.com/dotnet/net-core-and-systemd/)。
@@ -0,0 +1,16 @@
+# 会话生命周期
+
+| 事件 | Windows | Linux |
+| --- | --- | --- |
+| 创建工作区 | 已登录用户代理建立 ConPTY | 用户上下文中的代理建立 PTY |
+| 网络断开 | 代理继续持有终端和进程 | 代理继续持有终端和进程 |
+| 同身份重新连接 | 重新授权并附着原工作区 | 重新授权并附着原工作区 |
+| 锁屏或关闭桌面连接 | 用户登录会话仍存在时保持工作区 | 按用户代理所属服务生命周期保持工作区 |
+| 用户注销 | 用户代理及进程受 Windows 登录会话清理影响 | 按 user service、会话清理及 linger 配置执行 |
+| 系统启动 | 等待目标用户代理注册后建立新工作区 | 服务准备用户上下文后建立新工作区 |
+
+持久性范围为系统本次运行期间、用户代理存活时的工作区。客户端断线仅解除连接；工作区终止是独立的授权操作。
+
+连接归属在断线后保留。同一身份重连获取新控制权，接管撤销旧连接。会话管理器完成进程清理后释放工作区归属。broker 重启后的代理重新登记属于协议集成验收范围。
+
+验收分别执行网络断开、浏览器关闭、锁屏、用户注销、代理退出和显式终止，记录工作区状态与进程结果。系统重启后验证新环境的建立条件。
@@ -0,0 +1,30 @@
+# 文件存储与 VirtioFS
+
+| 项目 | Windows | Linux |
+| --- | --- | --- |
+| 本地文件 | NTFS 等本地卷，使用 Windows 文件 API 与权限 | 原生文件系统，使用 POSIX 文件 API 与权限 |
+| 宿主共享目录 | Windows VirtioFS 驱动与 WinFsp | VirtioFS 客户端与宿主目录 |
+| 身份映射 | 验证 SID、挂载配置和宿主 UID/GID 的关系 | 验证 UID/GID、附加组及宿主权限 |
+| 变更与锁 | 验证 Windows 通知、共享模式和锁的传播 | 验证文件通知、锁及跨挂载访问行为 |
+
+## 路径安排
+
+服务配置、运行元数据及用户配置优先放在操作系统本地卷。项目文件可放在 VirtioFS 工作目录。挂载可用性和目标用户访问检查在创建工作区前执行。
+
+并行编辑为本地操作与远程操作分配独立工作目录。代码项目可以采用独立 clone 或 Git worktree，通过版本控制整合修改。远程连接独占管理客户端控制权，文件写入由应用与存储权限决定。
+
+## 兼容性记录
+
+每个部署记录 PVE、virtiofsd、Windows virtio-win / WinFsp 版本、宿主文件系统、导出路径和挂载选项。
+
+| 验证项 | 场景 |
+| --- | --- |
+| 可见性 | 目标用户代理上下文访问预期盘符或挂载点 |
+| 权限 | 两个系统账户分别读取、创建、修改和删除文件 |
+| 外部变更 | Windows 本地程序、宿主和其他 guest 修改文件后，编辑器观察变化 |
+| 锁 | 不同进程及不同访问入口的独占锁和共享模式 |
+| 保存 | 临时文件写入后重命名替换、刷新、重复保存 |
+| 路径 | Unicode、大小写、长路径与符号链接 |
+| 开发工具 | Git 操作、构建输出、文件监听和高频小文件访问 |
+
+参考：[Windows VirtioFS](https://github.com/virtio-win/kvm-guest-drivers-windows/wiki/Virtiofs:-Shared-file-system)、[Git worktree](https://git-scm.com/docs/git-worktree)。
@@ -0,0 +1,17 @@
+# 系统管理权限
+
+| 能力 | Windows | Linux |
+| --- | --- | --- |
+| 本机关机和重启 | 系统用户权限分配，包含 `SeShutdownPrivilege` | 登录会话授权、polkit、sudo 或 root 权限 |
+| 网络发起系统关机 | 对应远程管理权限及服务策略 | 对应远程管理服务和账户策略 |
+| 提升执行权限 | Windows 用户令牌与提升机制 | sudo、capabilities 及服务管理接口 |
+
+终端使用目标系统账户的权限。部署阶段明确该账户的系统管理能力，并使用操作系统策略控制可执行的管理操作。通过远程终端运行的程序属于目标机器上的本地进程。
+
+复用登录用户时，账户级权限策略也作用于该用户的其他程序。需要不同权限边界的部署使用专用执行账户或经过验证的受限上下文。
+
+管理入口与普通终端输入分别授权。系统管理操作记录请求身份、目标、时间和执行结果。系统启动后的工作区状态由[用户环境](user-environment.md)和[生命周期](session-lifecycle.md)定义。
+
+验收使用系统权限查询和具有代表性的系统管理 API，确认工作区与管理入口符合配置。PTY 输入作为终端字节流处理。
+
+参考：[Windows 关机 API 权限](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-exitwindowsex)。
@@ -0,0 +1,16 @@
+# 终端后端
+
+| 项目 | Windows | Linux |
+| --- | --- | --- |
+| 伪终端 | ConPTY | POSIX PTY master/slave |
+| 进程连接 | 伪控制台通过扩展启动属性关联用户进程 | session、控制终端、标准流和前台进程组 |
+| 尺寸变更 | `ResizePseudoConsole` | 窗口尺寸 ioctl 与终端信号行为 |
+| 生命周期 | 用户进程、管道和伪控制台句柄 | 子进程、进程组和 PTY 文件描述符 |
+
+共享接口为 `IPtySessionFactory` 与 `IPtySession`。终端输入输出按字节传递；用户代理负责持续读出、缓冲边界及终端状态。平台实现明确句柄所有权、取消和资源释放顺序。
+
+Windows 后端在用户代理上下文中创建 shell。Linux 后端使用适合托管运行时的原生启动边界完成进程和终端设置，子进程进入目标程序前完成系统调用配置。
+
+验收覆盖交互 shell、UTF-8、方向键、Ctrl+C、全屏编辑器、尺寸变更、大量输出、子进程退出及显式终止。断线后的输出持续被消费，重连恢复见[连接协议](../connection-protocol.md)。
+
+参考：[ConPTY 会话](https://learn.microsoft.com/en-us/windows/console/creating-a-pseudoconsole-session)、[Linux PTY API](https://man7.org/linux/man-pages/man3/openpty.3.html)。
@@ -0,0 +1,20 @@
+# 用户执行环境
+
+| 平台 | 环境建立 | 身份标识 | 就绪条件 |
+| --- | --- | --- | --- |
+| Windows | 复用目标用户登录后的代理上下文 | Windows SID | 指定用户的代理已注册 |
+| Linux | 为现有系统账户设置 UID、GID、附加组及用户会话 | UID 与组信息 | 账户解析、权限设置及代理启动完成 |
+
+## Windows
+
+标准部署使用目标用户登录后启动的 Agent。它继承用户权限和用户配置，终端启动时设置工作目录、环境变量和 shell 参数。专用本地账户可以作为远程工作区账户。
+
+Host 根据外部身份映射匹配该用户的 SID。目标用户代理尚未注册时，工作区状态为 `WaitingForUserSession`。锁屏状态下保留用户会话；用户注销后的行为见[生命周期](session-lifecycle.md)。
+
+## Linux
+
+系统账户由操作系统维护。启动组件按授权映射查询账户，初始化附加组、主组、UID、HOME、工作目录和登录环境；部署所需的 PAM account/session 处理归入该组件。用户代理以目标账户身份持有 PTY。
+
+## 验收
+
+检查终端中的系统身份、主目录、配置目录、环境变量和文件访问结果。Windows 验证登录前的等待状态与登录后的代理注册；Linux 验证无人交互登录时的用户上下文建立。认证归属与系统账户映射见[认证文档](../authentication.md)。
@@ -0,0 +1,29 @@
+# 验证与验收
+
+## 自动验证
+
+NUKE Verify 执行文档检查、解决方案构建和核心测试。测试包括同身份显式接管、旧 lease 输入与断开拒绝、跨 issuer 身份边界、断线后归属保留、工作区释放以及并发连接唯一获权。
+
+CI 在 Windows 与 Linux x64 上各自执行 Verify 和 Publish，保存发布产物与 TRX。发布成功作为目标 RID 构建验证，运行能力通过以下环境验收确认。
+
+## 集成验收矩阵
+
+| 领域 | Windows | Linux |
+| --- | --- | --- |
+| 服务 | SCM 启动、停止、服务账户配置 | systemd 启动、停止、权限与日志 |
+| 用户身份 | 登录代理 SID、主目录、锁屏与注销 | UID/GID/附加组、HOME、无人登录时启动 |
+| 终端 | ConPTY、PowerShell、全屏 TUI、缩放 | PTY、shell、控制终端、信号与缩放 |
+| 进程清理 | 子进程树和句柄释放 | 进程组/cgroup 与文件描述符释放 |
+| 文件 | 实际 VirtioFS 驱动与 WinFsp 配置 | 实际挂载配置与宿主 UID/GID |
+
+## 跨平台场景
+
+1. 两个客户端同时连接，确认 host 只有一个有效控制者。
+2. 同身份显式接管，旧客户端继续发送输入，确认过期输入被拒绝。
+3. 断线后另一身份尝试进入，确认工作区归属保持。
+4. 断线期间进程继续产生输出，重连后恢复终端状态。
+5. 认证过期或授权撤销后，确认传输关闭和控制权撤销。
+6. 全屏编辑器重连，确认光标、颜色、备用屏幕和尺寸一致。
+7. 显式终止清理完整进程树后，确认新的身份可以创建工作区。
+
+存储场景细化见[VirtioFS 验收](platforms/storage.md)。每次环境验收记录系统版本、运行用户、依赖版本、配置、执行步骤与实际结果。