feat(ql3): add bounded local web console

2026-09-20 16:07:11 +08:00 · 2026-08-28 05:21:43 +08:00
parent b7a8104d9f
commit 84d1a61372
19 changed files with 2333 additions and 34 deletions
@@ -11,6 +11,8 @@

 最新增量证据（2026-08-28）：

+- D-417/ADR-0512（已实现，Console Trial Kit 交付待后续切片）：开发约二十天后的阶段产物从“可直接启动的 headless runtime”继续推进到首个可操作 Web 产品面。既有可选 `@qinglong/local-api` 现在内置 `/`、`/console.css`、`/console.js` 三文件离线 Console，总计 43,252 bytes，无前端框架、CDN、网络字体、遥测或 Web Storage；它复用同一 Node 进程、loopback listener、SQLite authority、Bearer/Project Policy/durable audit/re-confirm 链，不新增 package、sidecar、数据库连接、timer、watcher 或 cache。部署者可以按 Project 查看 Task revision/content fence、显式确认启动，查看 durable Run、Workflow Step 数与 Event sequence，并对未终止 Run 提交显式 cancellation request；取消请求不会伪装成停止终态。Credential 只在当前页面内存，服务端固定 CSP/COOP/CORP/Permissions Policy/no-referrer/nosniff/DENY/no-store，远程设备只能由操作者建立 SSH tunnel，不开放 LAN/public listener。默认 Edge/Standalone 与 D-416 Trial Kit 继续 headless、零增量；Console 只进入 opt-in `edge-application-api|standalone-application-api`，两档 artifact 为 `3,953,346 / 3,953,490 bytes`、467 files、12 packages、90 loaded modules，低于 6 MiB/640-file 门。Local API 48/48、pruner 11/11、完整 backend `1,637 total / 1,635 pass / 2 conditional skip / 0 fail`、18-package clean build/test 退出 0；package boundary 保持 18 packages 且无 single-source/shallow package，Cluster dependency、122-module Edge import 与全部 14 档 Local artifact audit 均 compatible。桌面 1440×960 与手机 390×844 已检查 Task、Run/Event spine 和显式确认工作态。该切片形成可构建、可运行的 source/application-api 阶段制品，但当前 v3 Trial Kit 尚未携带 Console；把 Console image/quickstart 变成路由/NAS 可下载物、固定低性能物理 Edge 容量数据和 public release 仍是后续门。
+
 - D-416/ADR-0511（已实现，首份真实 v3 Trial Kit 待授权）：阶段产物的判定从“可下载、可验真”推进到“部署者可直接试运行”。Local Trial Kit schema 升为 `qinglong/alpha-local-trial-kit@v3`，每个 amd64/arm64 bundle 新增由唯一模板生成并绑定 archive、两个 exact image ID、source 和 architecture 的 `quickstart.sh`；离线 auditor 会重新渲染 canonical journey，拒绝即使重算 manifest/checksum 的本地脚本改写。目标路由/NAS 或单节点只需 POSIX shell、`sha256sum` 和 Docker，即可在一个尚不存在的隔离目录完成全包 checksum、镜像 load/identity 复核、128 MiB 短生命周期 operator fresh setup、首 Owner 建立，并按 Edge `128 MiB/64 PID` 或 Standalone `256 MiB/256 PID` 启动 Application、等待 `active` 后输出 logs/stop/remove 指令。显式 artifact job 在 upload 前必须执行将要上传的 exact quickstart、检查 SQLite/Owner delivery 并 graceful stop；普通 push 不生成大 archive。聚焦 materializer/milestone/stage/workflow 回归为 `26/26`，完整 backend 为 `1636 total / 1634 pass / 2 conditional skip / 0 fail`，18-package clean build/test 退出 0；package boundary 保持 `18 packages / singleSourcePackages=[] / shallowSourcePackages=[]`，Cluster dependency、122-module Edge import、镜像/版本与 14 档 Local artifact 均 compatible，基础 Edge/Standalone 仍为 `2,669,390 / 2,669,468 bytes`、325 files、58 modules。历史同源 arm64 镜像对已本地物化为 v3 八文件开发 bundle，184,648,192-byte archive 完成 checksum、canonical audit、load 与 exact identity；Docker Desktop 在 Owner directory ownership 处按既有 POSIX 不等价失败关闭，未冒充原生 Linux 成功，正式 native exact-script 证据由手动 artifact job 产生。该切片不安装宿主 Node.js，不把 Operator 变成 daemon，不增加镜像 layer、workspace package、端口或稳态 RSS，也不触碰 2.x/migration。当前产物是无外部 listener、AI-excluded 的 headless Alpha runtime，不冒充 2.x Web UI、公开 release、生产 HA 或 LTS；首份真实双架构 v3 下载物仍需维护者授权 `produce_alpha_artifacts=true`。

 - D-415/ADR-0510（已实现，首份真实 stage index 待授权）：二十天开发形成的 Local 与 Cluster 候选现在有统一、面向部署者的最外层阶段交付入口。新增 `qinglong/alpha-stage-index@v1` finalizer/auditor，仅在显式 `produce_alpha_artifacts=true + alpha_artifact_scope=all` 且 Local/Cluster milestone 都成功后运行；它重新离线审计两个索引，要求 version/source/workflow SHA/ref/run/attempt 完全一致，记录两个 milestone manifest digest，并为 amd64/arm64 写出机器可读选择：低配 Edge/Standalone 只下载一个 Local Trial Kit、稳态只运行 Application 且 Operator 短时启动；Cluster 下载 control/admin/worker，按需增加 control-ai。跨索引审计必须同时持有 stage 与两个 milestone，拒绝跨运行混用、内容/选择漂移和额外文件。该索引不重复十个大 archive，不改变 Local-only/Cluster-only 授权路径，也不冒充受保护 tag、GHCR immutable digest、签名、正式 OCI catalog、生产 deployment lock 或 HA；普通 push/PR 不生成实际阶段 artifact。实现不新增 workspace package、runtime dependency、镜像 layer、端口、daemon、timer、连接池或 Edge/Standalone 稳态 RSS。
@@ -0,0 +1,77 @@
+# ADR-0512：有界、离线的 Local Web Console
+
+- 状态：Accepted
+- 日期：2026-08-28
+- 决策：D-417
+- 关联：ADR-0367、ADR-0370、ADR-0371、ADR-0374、ADR-0375、ADR-0503、ADR-0511
+
+## 背景
+
+开发约二十天后，D-416 已把 Local Alpha 闭合为可在 fresh 目录直接启动的阶段产物，但常驻 Application 仍是 headless runtime。仓库已有可选 `@qinglong/local-api`：它在同一 Node.js 进程、同一 SQLite authority 和一个 loopback listener 上提供 Task/Run 读取、启动、取消、事件、步骤和日志 API。部署者仍需手写 HTTP 请求，无法把已有后端能力视为可操作产品。
+
+直接把 2.x 前端带入 3.0 会重新引入大依赖树、旧 API 假设和低配设备负担；单独启动前端 sidecar 又会增加第二个常驻进程、端口和部署故障面。阶段性产品需要一个足够小、可离线、与现有 authority 同源的操作界面，同时必须诚实区分默认 headless Trial Kit 和显式 opt-in 的 `application-api` Profile。
+
+## 决策
+
+### 1. Console 属于既有 Local API 制品
+
+Console 由 `@qinglong/local-api` 自带固定的 `/`、`/console.css`、`/console.js` 三文件闭包，通过既有 loopback HTTP surface 提供。它不新增 workspace package、前端框架、第三方运行时依赖、listener、sidecar、数据库连接、timer、watcher 或 cache；静态文件在进程启动时一次性加载并校验。
+
+单文件上限为 96 KiB，总闭包上限为 192 KiB。当前三文件共 43,252 bytes。运行时 artifact pruner 只允许调用方显式保留 `local-api/assets/console/console.js`；路径必须是已安装、规范化的 package-relative regular file，不能用目录通配保留未审计脚本。
+
+### 2. 第一阶段只关闭最常用操作回路
+
+Console 提供：
+
+- 按 Project 查看最多 64 个 Task，读取 revision、schema、content digest 和 enabled 状态；
+- 对当前 Task 进行带 revision/content fence 的显式确认启动；
+- 查看最多 64 个 durable Run，读取状态、version、执行归属和创建时间；
+- 查看 Run 的最多 64 条 Event sequence 与 Workflow Step 数；
+- 对未终止 Run 进行显式确认的 durable cancellation request。
+
+页面不创建或编辑 Task，不管理 Identity/Policy/Secret/Plugin，不内嵌终端，也不把“取消已请求”展示成“执行已经停止”。超过窗口的数据继续通过 API keyset/pagination 读取。
+
+### 3. 凭据和浏览器边界失败关闭
+
+静态壳层无需凭据即可从 loopback 读取，所有 `/api/v3` 请求继续经过原 Bearer authentication、Project Policy、durable audit 和 authority re-confirm。Credential 只保存在当前页面 JavaScript closure；输入框在连接后清空并禁用，断开时清除状态。禁止 URL、Cookie、`localStorage`、`sessionStorage`、Service Worker 和外部资源保存或传输 credential。
+
+服务端发送 `default-src 'none'` CSP、same-origin COOP/CORP、Permissions Policy、no-referrer、nosniff、DENY 和 no-store。HTML/CSS/JS 不引用网络字体、CDN、遥测或远程图片，不使用 inline script/style、`innerHTML` 或 `eval`。listener 继续只允许 `127.0.0.1|::1`；远程管理必须由部署者显式建立 SSH tunnel 或等价受信通道，Console 不把 Local API 扩展为 LAN/public listener。
+
+### 4. 默认 Edge/Standalone 保持零增量
+
+D-416 的 Local Trial Kit 和基础 `edge|standalone` Application 仍保持 headless，不包含 `@qinglong/local-api`。只有选择 `edge-application-api|standalone-application-api` 的制品才携带 Console，因此低配路由器不为未使用的 UI 支付包体、listener 或稳态 RSS；Cluster 节点继续使用 Cluster Control 的独立产品与部署路径。
+
+本决策形成可构建、可运行的 `application-api` 阶段制品，但不声称当前 v3 Trial Kit 已经携带 Web Console。把 opt-in Console image/quickstart 变成面向路由/NAS 的实际下载物是下一交付切片。
+
+## 被拒绝的替代方案
+
+### 新建前端 workspace package
+
+拒绝。三个离线资产没有独立领域 authority 或复用消费者；新包会重新制造用户此前指出的过细 package 和单文件包问题。
+
+### 引入 React/Vue/Umi 构建链
+
+拒绝。当前操作面规模不足以抵消依赖、漏洞、构建和低配包体成本；后续功能达到独立应用规模时再以新 ADR 评估。
+
+### 独立静态服务器或 sidecar
+
+拒绝。它增加常驻进程、端口、健康检查和跨 origin credential 处理，同时没有新的 authority 价值。
+
+### 直接监听局域网地址
+
+拒绝。Alpha 尚未关闭 TLS、CSRF、可信代理、会话撤销和远程暴露门；loopback + 显式 tunnel 保持风险可见。
+
+## 影响
+
+- `application-api` Edge/Standalone 制品当前为 3,953,346 / 3,953,490 bytes、467 files、12 packages，远低于 6 MiB/640-file budget；加载闭包为 90 modules，实测 import RSS delta 约 14.0 MiB；
+- 基础 headless Edge/Standalone、D-416 Trial Kit、Cluster Profile 和 AI/MCP Profile 不因本切片新增 Console 进程或端口；
+- Console 视觉和交互已在 1440×960 与 390×844 视口验证，工作态覆盖 Task detail、运行确认、Run evidence/Event sequence 和取消入口；
+- 当前仍缺少面向部署用户的 Console Docker image/Trial Kit 选择、真实低性能物理 Edge 容量数据，以及受保护 public release。
+
+## 验证
+
+- Local API 完整测试 48/48：包含三资产闭包、离线/credential custody、真实 loopback 静态响应、favicon、GET body/query alias 拒绝，以及既有认证 API/SQLite/过载/drain 回归；
+- runtime artifact pruner 11/11：显式 JS asset 保留、缺失/逃逸/重复路径在任何删除前失败关闭；
+- `edge-application-api` 与 `standalone-application-api` artifact audit 均 `compatible=true`，且证明 Console 被 pack、未被 runtime pruning 删除；
+- 完整 backend 为 1,637 total / 1,635 pass / 2 conditional skip / 0 fail，18-package clean build/test 退出 0；
+- package boundary 保持 18 packages 且无 single-source/shallow package，Cluster dependency、122-module Edge import 与全部 14 档 Local artifact audit 均 `compatible=true`；远程 CI 结果在本切片推送后记录。
@@ -515,6 +515,7 @@
 | [ADR-0509](./ADR-0509-cluster-alpha-bundle-and-milestone-closure.md)                                | Cluster Alpha Bundle 与跨架构里程碑闭合                                                                                                                                                                                   | Accepted（首份实际 Cluster milestone artifact 待维护者授权） |
 | [ADR-0510](./ADR-0510-cross-profile-alpha-stage-delivery-index.md)                                  | 跨 Profile Alpha 阶段交付索引                                                                                                                                                                                              | Accepted（首份实际 stage index 待维护者授权） |
 | [ADR-0511](./ADR-0511-runnable-local-alpha-quickstart.md)                                           | 可直接试运行的 Local Alpha Quickstart                                                                                                                                                                                       | Accepted（首份实际 v3 Trial Kit 待维护者授权） |
+| [ADR-0512](./ADR-0512-bounded-offline-local-web-console.md)                                        | 有界、离线的 Local Web Console                                                                                                                                                                                               | Accepted（Console Trial Kit 交付待后续切片） |

 ## 规则

@@ -17,6 +17,15 @@

 ## 当前阶段实物（2026-08-27）

+在下面保留的历史 exact-image 证据之外，2026-08-28 的源码阶段已经形成两条可独立验收的产品线：
+
+| 阶段产物 | 当前可用能力 | 仍缺少 |
+| --- | --- | --- |
+| D-416 Local Alpha Trial Kit v3 | POSIX shell + Docker 一条命令完成 checksum、load、fresh setup、首 Owner、headless Application active/stop | 首份远端双架构实际 artifact 仍需维护者授权 `produce_alpha_artifacts=true` |
+| D-417 opt-in Local Web Console | `application-api` 制品可在同进程/同 SQLite/loopback listener 上查看 Task/Run/Event 并显式运行或取消；Edge/Standalone 制品审计通过 | 尚未进入 Trial Kit Docker image/quickstart，不能冒充当前路由/NAS 下载物 |
+
+这两个边界共同防止把“20 天代码和测试”冒充“用户已经能下载并完整操作”：D-416 已关闭 fresh headless 用户旅程，D-417 已关闭 source/application-api 操作界面，但两者尚未合并成实际可下载的 Console Trial Kit。操作说明见 [Local Web Console](./ql3-local-web-console.md)。
+
 提交 `4239464af6937d56528a0a2c573d12329bc7ca55` 已形成最新 owner-private arm64 工程候选：

 - Application image ID `sha256:0d1d4b80ee46e9bb671d846f93d9a6d832c9856a91eed03f299055904da88a50`，operator image ID `sha256:b9122f481b1ba60d7eee9a3ed5ca57c9c141cbc389e7c7dbe19c6f6b1c98b49e`；
@@ -68,7 +68,9 @@ Owner delivery 保留在新数据目录的 `owner-delivery/`，operator command

 当前 Application 是无外部 listener、AI-excluded 的 headless Alpha runtime。该试运行可
 验证 3.0 SQLite、Owner authority、调度/插件基础与生命周期，但还不是 2.x Web UI 的
-可替代版本。
+可替代版本。D-417 已在 opt-in `application-api` Profile 提供首个 Local Web Console，
+但本 v3 Trial Kit 尚未携带该 Profile；不要期待 quickstart 启动后出现 Web 端口。Console
+当前使用方式与边界见 [Local Web Console](./ql3-local-web-console.md)。

 ## 手工加载与最小 smoke

@@ -0,0 +1,75 @@
+# QingLong 3.0 Local Web Console
+
+Local Web Console 是 `@qinglong/local-api` 的 opt-in 操作界面，用来查看 Task、Run 和执行事件，并显式启动或取消一次运行。它不是当前 headless Local Alpha Trial Kit 的组成部分，也不是 2.x Web UI 的完整替代品。
+
+## 选择部署档位
+
+| 场景 | 建议 |
+| --- | --- |
+| 内存很小、只需后台自动化的路由/NAS | 继续使用默认 `edge` headless Application；Console 零增量 |
+| 路由/NAS 需要临时人工查看与操作 | 选择 `edge-application-api`，只通过 loopback 或 SSH tunnel 访问 |
+| 普通单节点服务器 | 选择 `standalone-application-api` |
+| Kubernetes/Cluster 节点 | 不使用本 Local Console；继续使用 Cluster Control/Console 路径 |
+
+当前仓库能生成 Node.js `application-api` 制品；D-416 的 v3 Docker Trial Kit 仍只包含 headless Application。需要下载即用的 Console image/quickstart 时，应等待后续 Console Trial Kit 切片，不能把本页命令误认为当前公开下载物。
+
+## 前置条件
+
+- 已完成 Local fresh setup，并有受支持的 Application config；
+- Owner pepper keyring 与 SQLite active pepper 一致；
+- 已通过 [`ql3-identity`](./ql3-local-identity-credential.md) 为 active Identity 签发 API credential；
+- credential 对目标 Project 至少有读取 Task/Run 的权限；启动和取消分别还需要 `run.start` 与 `run.stop`；
+- config、keyring、database 和 credential delivery 保持既有 `0700/0600`、no-symlink 和同 UID authority。
+
+## 启动
+
+创建私有 `local-api.json`：
+
+```json
+{
+  "schema": "qinglong/local-api-process@v1",
+  "deploymentRoot": "/srv/qinglong3",
+  "applicationConfigFilePath": "/srv/qinglong3/private/application.json",
+  "ownerPepperKeyringDirectory": "/srv/qinglong3/private/owner-pepper",
+  "listener": { "host": "127.0.0.1", "port": 5701 }
+}
+```
+
+运行同一进程的 Application + API + Console：
+
+```sh
+ql3-local-api --config /srv/qinglong3/private/local-api.json
+```
+
+在设备本机打开 `http://127.0.0.1:5701/`。服务只接受 `127.0.0.1` 或 `::1`，不会监听 LAN 地址。
+
+从管理电脑访问路由/NAS 时，显式建立受信 SSH tunnel：
+
+```sh
+ssh -L 5701:127.0.0.1:5701 router.example
+```
+
+随后在管理电脑打开 `http://127.0.0.1:5701/`。不要用反向代理临时绕过 loopback；TLS、可信代理、CSRF 和远程会话边界尚未作为本阶段产品门验收。
+
+## 使用
+
+1. 输入 Project ID 和 `ql3c_…` API credential，选择“连接本机”。
+2. 在“任务”中选择 Task，核对 revision/content fence 后才能“运行一次”。
+3. 在“运行”中选择 durable Run，按 Event sequence 判断实际进度。
+4. “请求取消”只提交 durable cancellation intent；界面出现 `cancelled|failed|succeeded|timed_out` 终态前，不要认为进程已经停止。
+5. 完成后选择“断开并清除凭据”，再关闭页面。
+
+Credential 只存在当前页面内存，不进入 URL、Cookie 或 Web Storage。页面刷新会丢失 credential，需要重新输入；这是当前安全边界，不是缺陷。
+
+## 当前阶段可用边界
+
+当前可操作闭环是 Task list/read/start 与 Run list/read/events/steps/cancel。页面不负责：
+
+- 创建、编辑、启停 Task；
+- Identity、Policy、Secret、Plugin Package 或 AI 配置管理；
+- Run log 展示、终端、文件管理或 2.x 数据迁移；
+- LAN/public 暴露、TLS termination、多用户 Web session 或 Cluster 管理。
+
+三项静态资产总计 43,252 bytes，不依赖 CDN、网络字体或前端框架。`edge-application-api` 制品为 3,953,346 bytes/467 files，`standalone-application-api` 为 3,953,490 bytes/467 files；基础 headless Profile 不携带这些资产。
+
+停止 Local API 进程走与 Application 相同的 drain/shutdown 路径。Console 没有独立数据库、后台任务或需要额外清理的持久状态。