Build Charac server and client with OIDC, SSH sessions, and packages

docs/development.md

@@ -1,54 +1,29 @@
 # 开发与 NUKE 构建
 
-## 工具链
+使用 .NET 10 或更高版本 SDK。global.json 设置最低 SDK 并允许更高版本；项目目标框架为 net10.0，入口使用显式 Program.Main。包版本集中在 Directory.Packages.props，锁文件固定依赖解析。
 
-安装 `global.json` 指定的 .NET 10 SDK，SDK 补丁选择遵循 `latestPatch`。包版本集中放在 `Directory.Packages.props`，每个项目的 `packages.lock.json` 记录依赖解析结果。
+解决方案 WorkspaceAccess.slnx 包含 src/server/WorkspaceAccessServer.csproj、src/client/WorkspaceAccessClient.csproj、测试项目和 NUKE 项目。各项目的构建输出统一位于根目录 `temp/<项目名>/bin/`，中间文件位于 `temp/<项目名>/obj/`；`temp/` 被 Git 忽略。Windows 用 ./build.ps1，Linux 用 bash ./build.sh。
 
-`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
-```
-
-## 构建目标
-
-| 目标 | 行为 |
+| NUKE 目标 | 行为 |
 | --- | --- |
-| Restore | 恢复解决方案依赖；`--locked-restore` 启用锁定模式 |
-| Compile | Restore 后构建整个解决方案 |
-| Test | Compile 后执行核心测试并输出 TRX |
-| CheckDocs | 检查标题、相对链接文件、README 可达性及差异说明覆盖 |
-| Verify | CheckDocs 与 Test；默认目标 |
-| Publish | Verify 后按 `--runtime` 发布单一产品和部署模板 |
-| RunHost | Compile 后以 `host` 角色前台运行产品 |
-| RunAgent | Compile 后以 `agent` 角色在当前用户身份下运行产品 |
+| Restore、Compile、Test | 依次恢复、构建和运行核心测试 |
+| CheckDocs、Verify | 检查文档；Verify 组合文档与测试 |
+| Publish | Verify 后按 RID 发布 server/ 与 client/ |
+| RunServer、RunClient | 前台运行对应程序 |
 
-配置参数为 `--configuration Debug` 或 `Release`。发布 RID 为 `win-x64`、`win-arm64`、`linux-x64`、`linux-arm64`。
+Server 与 Client 共同支持 win-x64、win-arm64、linux-x64、linux-arm64；Client 另支持 linux-bionic-arm64（Android ARM64/Termux，依赖设备上的 .NET 10 运行时）。常用命令：
 
 ```powershell
 ./build.ps1 --target Verify --locked-restore
 ./build.ps1 --target Publish --runtime win-x64
-./build.ps1 --target Publish --runtime linux-x64
+./build.ps1 --target Publish --runtime linux-bionic-arm64
+dotnet run --project src/server
+dotnet run --project src/client -- --help
+dotnet run --project src/client -- status --server http://127.0.0.1:5080
 ```
 
-## 开发检查
+Server 支持全局 `--config <路径>` 指定 INI 文件，服务启动、`database migrate`、`ssh probe` 和 `ssh broker-probe` 均使用它；相对路径在开发仓库中优先按仓库根目录解析，也可使用绝对路径。未指定时，开发环境优先读取仓库根目录被 Git 忽略的 `workspace-access.config`（模板为 `workspace-access.config.example`），发布后需用 `--config` 指向外部文件，或自行把同名文件放在可执行文件旁。配置提供 `[server] domain` 和 `listen`，示例监听 http://127.0.0.1:5080；健康端点为 /health/live 与 /health/ready，Client 状态探测为 /status。单域名路由见[通信入口](client-server-transport.md)。就绪端点在 SSH 和认证集成前返回 503。变更依赖时更新集中版本与锁文件，交付前执行 Verify。平台行为验收见[验证与验收](testing.md)与[Android CLI](platforms/android-client.md)。
 
-1. 修改实现及对应设计文档。
-2. 为身份边界、并发控制和资源生命周期增加测试。
-3. 执行 Verify，检查 `artifacts/test-results/`。
-4. 涉及原生行为时，在目标系统执行[平台验收](testing.md)。
+示例：`dotnet run --project src/server -- --config workspace-access.config ssh broker-probe`；此诊断现通过 Session Manager 发送 Linux `ls` 并显示输出。EF 工具可使用 `dotnet ef database update --project src/server -- --config workspace-access.config`。`--config` 不存在时会报错，不会回退到默认文件。完整 OIDC + WebSocket 的 CLI 命令见[通信入口](client-server-transport.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)。
+数据库模型使用 EF Core 和 Npgsql。在根目录配置 `[database]` 的 `host`、`name`、`username` 等字段后运行 `dotnet run --project src/server -- database migrate`；正常启动不自动迁移。新增迁移与真实 PostgreSQL 集成测试见[数据库开发](database.md)。本机 `ssh probe` 命令可从计划部署 Server 的机器验证到目标 sshd 的主机密钥、密码认证和 PTY Shell；步骤见[SSH Broker](ssh-session.md)。