# 自测报告 —— nas-console 第二阶段（D2）

- 主机：fnOS NAS / Debian 12 / root / `192.168.1.38`
- 服务：`nas-console.service`（`/etc/systemd/system/nas-console.service`），监听 `0.0.0.0:3096`
- 解释器：`/mnt/ssd/apps/trim.hermes/runtime/python/bin/python3.11`
  （aiohttp 3.14.3、PyJWT 2.13.0、cryptography 50.0.0；无新增编译依赖）
- 前端：原生 JS + 本地 vendor（marked / DOMPurify），零 CDN
- 自测脚本：`tests/selftest.sh`（端到端，可重复跑）、`tests/test-mapping.py`（事件映射确定性单测）
- 截图脚本：`tests/shot.mjs`（自带 headless chromium，独立调试端口 9333，不碰 `chromium-cdp`）
- 公网入口：`https://nas.hynixing.cn/`（Cloudflare Access 邮箱码之后才是本应用）
- 自测时间：2026-10-06 19:0x

---

## 0. 一键复跑

```bash
cd /vol1/ai/projects/ds_project/nas-console
bash tests/selftest.sh                              # 88 项，结果见 tests/last-run.txt
node tests/test-resume.mjs                          # 浏览器级：断开→重载→结果被补回
python3 tests/test-mapping.py                       # 事件映射确定性单测
export PATH=/mnt/ssd/apps/nodejs_v24/bin:$PATH
node tests/shot.mjs                                 # 输出 shots/*.png（390×844）
```

**最新一次结果：`PASS=88 FAIL=0`，全部通过 ✅**（另有 `test-mapping.py` 单测 `PASS=23 FAIL=0`、
浏览器级 `tests/test-resume.mjs` `PASS=7 FAIL=0`）

---

## 主会话指定的三项修复（先做）

### 核验项 1：预览浮层半透明 → 实心不透明

原 `.viewer` 背景是 `rgba(8,10,14,.97)`，`05/06` 两张截图能透出底下的列表内容。

```css
/* static/style.css */
.viewer{position:fixed;inset:0;background:#0b0e13;z-index:100;isolation:isolate}
.viewer-bar{background:#12161d}      /* 原本透明，会透出正文 */
.viewer-body{background:#0b0e13}     /* 原本 rgba(8,10,14,.97) */
```

实机取到的计算样式（截图脚本里直接读的 `getComputedStyle`）：

```console
$ node tests/shot.mjs
  预览浮层样式: rgb(11, 14, 19)|z=100
```

`rgb(11,14,19)` = `#0b0e13`，alpha=1，**完全不透明**；`z-index:100` 高于底部 tabbar。
`shots/05-file-preview-md.png`、`shots/06-file-preview-image.png` 已重拍，无穿透。
自测第 9 节也钉死了这三条（禁止再出现半透明 `rgba`）。

### 核验项 2：内网白名单收紧（EasyTier 朋友组网绝不能进）

用户把 `srv/auth.py` 的 `PRIVATE_NETS` 收紧为：

```python
PRIVATE_NETS = ("127.0.0.0/8", "192.168.1.0/24", "100.64.0.0/10", "::1/128")
```

**原因**：EasyTier 朋友组网是 `10.126.126.x`，原先放行整个 `10.0.0.0/8`
等于把 root 级控制台送给所有朋友。`172.16/12`、`fc00::/7`、`fe80::/10` 一并移除。

自测里的硬断言（`tests/selftest.sh` 第 2 节，直接 import 真实函数）：

```console
$ python3 -c "import sys;sys.path.insert(0,'srv');from auth import is_private_client as f; \
    print([(ip,f(ip)) for ip in ['10.126.126.2','10.0.0.1','8.8.8.8','127.0.0.1','192.168.1.5','100.64.0.9']])"
[('10.126.126.2', False), ('10.0.0.1', False), ('8.8.8.8', False),
 ('127.0.0.1', True), ('192.168.1.5', True), ('100.64.0.9', True)]
```

```console
  ✓ PASS 内网白名单正确：10.126.126.2 / 10.0.0.1 / 8.8.8.8 被拒，127 / 192.168.1 / 100.64 放行
```

### 核验项 3：PWA（添加到手机主屏）

新增：

| 文件 | 内容 |
|---|---|
| `static/manifest.json` | `name/short_name = "NAS 控制台"`、`display: standalone`、`theme_color/background_color = #0f1115`、`orientation: portrait`、192/512 图标 + 512 `maskable` |
| `static/icon-192.png` / `icon-512.png` / `icon-maskable-512.png` / `apple-touch-icon.png` | 由 `tests/make-icons.py` 用**纯标准库**（`zlib`+`struct`，无需 PIL）生成 |
| `static/sw.js` | Service Worker：外壳 network-first，`/api/**` 一律不缓存 |
| `static/index.html` | `<link rel="manifest">`、`theme-color`、`apple-touch-icon`、`apple-mobile-web-app-*` |

```console
$ curl -s http://127.0.0.1:3096/static/manifest.json | head -14
{
  "name": "NAS 控制台",
  "short_name": "NAS 控制台",
  "description": "手机远程使用 NAS 上的 Hermes / Codex / DSH，并浏览、预览、下载文件",
  "lang": "zh-CN",
  "dir": "ltr",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "orientation": "portrait",
  "theme_color": "#0f1115",
  "background_color": "#0f1115",
  ...
```

```console
$ python3 -c "import json;d=json.load(open('static/manifest.json'));print('name=',d['name'],'| display=',d['display'],'| theme=',d['theme_color'],'| icons=',len(d['icons']))"
name= NAS 控制台 | display= standalone | theme= #0f1115 | icons= 3
```

---

## 1. 服务与健康检查（§8.1）

```console
$ systemctl is-active nas-console
active
$ systemctl is-enabled nas-console
enabled
$ curl -s http://127.0.0.1:3096/healthz
ok
$ ss -ltnp | grep 3096
LISTEN 0 128 0.0.0.0:3096 0.0.0.0:* users:(("python3.11.real",pid=163562,fd=6))
$ curl -s http://127.0.0.1:3096/api/channels
{"hermes": {"ok": true, "upstream": "http://127.0.0.1:8642"},
 "dsh":    {"ok": true, "bin": "/mnt/ssd/apps/nodejs_v24/bin/dsh", "cwd": "/vol1/ai/projects/ds_project"},
 "codex":  {"ok": true, "bin": "/mnt/ssd/apps/nodejs_v24/bin/codex", "cwd": "/vol1/ai/projects", "key": true},
 "files":  {"ok": true, "roots": ["/vol1/ai/projects", "/vol1/ai/deliverables/files",
                                  "/vol1/ai/agents/hermes/media-archive", "/vol1/ai/agents/hermes/images",
                                  "/vol1/ai/agents/hermes/cache", "/mnt/ssd/minecraft/downloads"]}}
```

新增 `GET /api/channels` 作为三通道健康总览（前端顶栏与自测都用它）。

---

## 2. 第二道锁（§8.7）

```console
$ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3096/
200
$ curl -s -o /dev/null -w '%{http_code}\n' -H 'CF-Ray: 1' http://127.0.0.1:3096/
403
$ curl -s -o /dev/null -w '%{http_code}\n' -H 'CF-Ray: 1' \
    'http://127.0.0.1:3096/api/files/list?path=/vol1/ai/projects'
403
$ curl -s -o /dev/null -w '%{http_code}\n' -H 'CF-Ray: 1' \
    -H 'Cf-Access-Jwt-Assertion: not.a.token' http://127.0.0.1:3096/
403
```

伪造 JWT → 403（**不 fail-open**）；内网直连 → 200。
JWKS 磁盘缓存 `var/access-jwks.json`（2 个公钥），联网失败时用磁盘副本。

---

## 3. Hermes 通道（§8.2）

```console
$ SID="selftest-$(date +%s)"
$ curl -sN -X POST http://127.0.0.1:3096/api/hermes/chat -H 'Content-Type: application/json' \
    -d "{\"session_id\":\"$SID\",\"message\":\"只回两个字：收到\"}"
data: {"type": "session", "session_id": "selftest-1791283721", "cwd": "/vol1/ai/projects/ds_project"}
data: {"type": "text", "text": "收到"}
data: {"type": "usage", "input": 35171, "output": 2}
data: {"type": "final", "text": "收到", "session_id": "selftest-1791283721"}
```

带工具的一轮（真实历史，`selftest-1791283721` 的 6 行）：

```console
$ curl -s 'http://127.0.0.1:3096/api/hermes/sessions/selftest-1791283721/messages' \
  | python3 -c "
import json,sys
for m in json.load(sys.stdin)['data']:
    print(' -',m['role'],'| content',len(str(m.get('content') or '')),'| reasoning',
          len(str(m.get('reasoning') or '')),'| tool_calls',len(m.get('tool_calls') or []))"
 - user | content 8 | reasoning 0 | tool_calls 0
 - assistant | content 2 | reasoning 0 | tool_calls 0
 - user | content 23 | reasoning 0 | tool_calls 0
 - assistant | content 0 | reasoning 80 | tool_calls 1     ← 思考 + 工具调用
 - tool | content 151 | reasoning 0 | tool_calls 0         ← 工具结果
 - assistant | content 9 | reasoning 0 | tool_calls 0
```

自测断言：`session`/`text`/`final` 齐全、带工具任务出现 `reasoning`、工具卡 `running`→`done`、
会话列表非空且含新会话、**响应中无密钥**。

---

## 4. DSH 通道（§8.3）

会话列表（读 zstd 会话文件，带 mtime 缓存）：

```console
$ curl -s http://127.0.0.1:3096/api/dsh/sessions | head -c 220
{"object": "list", "channel": "dsh", "data": [{"id": "session-94077b4d-…", "source": "dsh",
 "cwd": "/vol1/ai/projects/ds_project", "title": "只回复两个字符：ok", "message_count": 2,
 "tool_call_count": 3, …
$ curl -s http://127.0.0.1:3096/api/dsh/health
{"channel": "dsh", "ok": true, "bin": "/mnt/ssd/apps/nodejs_v24/bin/dsh",
 "home": "/vol1/ai/home/.dsh", "cwd": "/vol1/ai/projects/ds_project",
 "bucket": "--vol1-ai-projects-ds_project--", "sessions": 88}
```

真实一轮（含工具）：

```console
$ curl -sN -X POST http://127.0.0.1:3096/api/dsh/chat -H 'Content-Type: application/json' \
    -d '{"message":"用 bash 跑 echo report-dsh 再告诉我结果"}'
data: {"type": "status", "phase": "spawning"}
data: {"type": "session", "session_id": "session-c6b9bcf1-1ce9-41dc-a17e-e4905c0db1ff", "cwd": "/vol1/ai/projects/ds_project"}
data: {"type": "status", "phase": "step_start", "turn": 1, "step": 1}
data: {"type": "text", "text": "I'll run that command.\n\n"}
data: {"type": "tool", "id": "chatcmpl-tool-95d6a1150ab4000b", "name": "bash",
       "args": {"command": "echo report-dsh", "description": "Echo report-dsh string"}, "status": "running"}
data: {"type": "tool", "id": "chatcmpl-tool-95d6a1150ab4000b", "name": "bash",
       "args": {"command": "echo report-dsh", "description": "Echo report-dsh string"},
       "status": "done", "result": "report-dsh\n", "is_error": false}
data: {"type": "status", "phase": "step_start", "turn": 1, "step": 2}
…
data: {"type": "final", "text": "…", "session_id": "session-c6b9bcf1-…"}
```

> **实测与交接文档不一致**：文档说 tool-call 内嵌在 `text` 里；实际 DSH 发的是
> 独立的 `thinking` / `tool_call` / `tool_result` 事件。适配器按**实测**写，
> 同时保留旧版内嵌形态的正则兜底。
>
> `tool_result` 只带 `callId`，所以适配器会记住 `tool_call` 里的 name/args 再补回完成事件，
> 避免 SSE 退化成 `name:"tool"`、`args` 丢失（有单测钉死）。

自测断言：列表带 `channel=dsh` 且非空、新会话拿到 `sessionId`、`text`/`final` 齐全、
续接沿用同一 id、`tool_call` 拆成工具卡且 `done` 带结果、历史含用户消息/工具结果/思考过程。

---

## 5. Codex 通道（§8.4）

```console
$ curl -s http://127.0.0.1:3096/api/codex/health
{"channel": "codex", "ok": true, "bin": "/mnt/ssd/apps/nodejs_v24/bin/codex",
 "home": "/vol1/ai/agents/codex", "cwd": "/vol1/ai/projects",
 "db": "/vol1/ai/agents/codex/thread_history_1.sqlite", "key": true}
```

真实一轮（含工具）：

```console
$ curl -sN -X POST http://127.0.0.1:3096/api/codex/chat -H 'Content-Type: application/json' \
    -d '{"message":"用 bash 跑 echo report-codex 再告诉我结果"}'
data: {"type": "session", "session_id": "01a110e8-f3b6-76f2-9372-16571727f8fc", "cwd": "/vol1/ai/projects"}
data: {"type": "text", "text": "我会用 Bash 执行这条命令，再告诉你输出。"}
data: {"type": "tool", "id": "item_3", "name": "bash",
       "args": {"command": "/bin/bash -c 'echo report-codex'"}, "status": "running"}
data: {"type": "tool", "id": "item_3", "name": "bash",
       "args": {"command": "/bin/bash -c 'echo report-codex'"}, "status": "done",
       "result": "report-codex", "is_error": false}
data: {"type": "text", "text": "执行成功，输出：\n\n```text\nreport-codex\n```"}
data: {"type": "usage", "input": 26540, "output": 72}
data: {"type": "final", "text": "我会用 Bash 执行这条命令，再告诉你输出。执行成功，输出：…",
       "session_id": "01a110e8-f3b6-76f2-9372-16571727f8fc"}
```

续接（`codex exec resume <thread_id>`）：

```console
$ curl -sN -X POST http://127.0.0.1:3096/api/codex/chat -H 'Content-Type: application/json' \
    -d '{"session_id":"01a110e8-…","message":"再跑一次 echo codex-resume"}' | head -2
data: {"type": "session", "session_id": "01a110e8-f3b6-76f2-9372-16571727f8fc", "cwd": "/vol1/ai/projects"}
```

历史（sqlite **只读** `mode=ro`）：

```console
$ curl -s 'http://127.0.0.1:3096/api/codex/sessions/01a110e8-…/messages' | head -c 260
{"object": "list", "session_id": "01a110e8-…", "data": [{"role": "user", "content": "用 bash 跑 echo report-codex 再告诉我结果"},
 {"role": "assistant", "content": "我会用 Bash 执行这条命令，再告诉你输出。"},
 {"role": "tool", "tool_call_id": "item_3", "tool_name": "bash", "args": {"command": "/bin/bash -c 'echo report-codex'"}, …
```

> ⚠️ 库里 `item_json` 是 **camelCase**（`agentMessage` / `commandExecution` / `aggregatedOutput`），
> 而 stdout 的 NDJSON 是 **snake_case** —— 两条路分别解析（单测覆盖两种）。
>
> Codex 会把「忽略未知配置项」也报成 `item.type=error`，直接透传会吓到用户 →
> 这类噪音降级为 `notice`，只有真错误才给 `error`（有单测钉死）。
>
> `OPENCODE_API_KEY` 从 systemd `Environment=` 读，只传给子进程；
> **任何接口都不会把它回给前端**（自测里 grep 过响应无密钥）。

---

## 6. 文件模块（§8.5）

```console
$ curl -s -D - -o /dev/null 'http://127.0.0.1:3096/api/files/raw?path=…交接-必读.md' \
    | grep -iE 'HTTP/|content-type|content-disposition'
HTTP/1.1 200 OK
Content-Type: text/markdown; charset=utf-8
Content-Disposition: inline; filename*=UTF-8''%E4%BA%A4%E6%8E%A5-%E5%BF%85%E8%AF%BB.md

$ curl -s -D - -o /dev/null 'http://127.0.0.1:3096/api/files/raw?path=…我要当市长-游戏企划书.docx' \
    | grep -iE 'HTTP/|content-type|content-disposition'
HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="?????-?????.docx"; filename*=UTF-8''%E6%88%91%E8%A6%81%E5%BD%93%E5%B8%82%E9%95%BF-…docx
```

中文名走 `filename*=UTF-8''…`（ASCII 兜底 `filename=` 只是兼容旧客户端）。
`.md` 显式写 `text/markdown` —— aiohttp 自带 mime 猜测在 NAS 上会把 `.md` 认成
`application/octet-stream`，页内预览会失效。

越界防护：

```console
$ curl -s -o /dev/null -w '%{http_code}\n' 'http://127.0.0.1:3096/api/files/raw?path=/etc/passwd'
403
$ curl -s -o /dev/null -w '%{http_code}\n' 'http://127.0.0.1:3096/api/files/raw?path=/vol1/ai/projects/../../etc/passwd'
403
$ ln -sfn /etc/passwd tests/escape-link-test
$ curl -s -o /dev/null -w '%{http_code}\n' 'http://127.0.0.1:3096/api/files/raw?path=…/tests/escape-link-test'
403
```

---

## 7. 三通道隔离（§8.6）

会话列表不交叉：

```console
  ✓ PASS Hermes 列表只含 Hermes 自己的会话
  ✓ PASS DSH 列表只含 DSH 自己的会话
  ✓ PASS Codex 列表只含 Codex 自己的会话
```

会话 id 格式天然不同（Hermes `selftest-*` / DSH `session-<uuid>` / Codex `<uuid v7>`），
交叉查历史必须 404：

```console
$ curl -s -o /dev/null -w '%{http_code}\n' \
    'http://127.0.0.1:3096/api/codex/sessions/session-94077b4d-ce76-4f27-8c37-47b5d598feef/messages'
404
  ✓ PASS 拿 DSH 会话 id 查 Codex 历史 → 404（不串）
  ✓ PASS 拿 Codex thread_id 查 DSH 历史 → 404（不串）
  ✓ PASS 拿 Codex thread_id 查 Hermes 历史 → 404（不串）
```

前端侧也各存各的状态（截图脚本跑完三个通道后读的真实值）：

```console
  三通道前端状态: {"hermes":{"sid":"selftest-1791283721","turns":5},
                   "codex":{"sid":"01a110e5-d9b6-7ce1-9e83-ff726f146537","turns":1},
                   "dsh":{"sid":"session-75686826-3490-4954-adeb-fa362dc3bee5","turns":1}}
```

三个 sid 互不相同、turn 数各自独立 —— 没有串台。

---

## 8. 事件映射确定性单测（补活体测不到的部分）

实测发现：DSH 的 `thinking`、Codex 的 `reasoning` / `file_change` 是否出现**取决于模型**，
线上偶发不吐。所以除了端到端自测，`tests/test-mapping.py` 用**合成事件**直接喂映射函数钉死行为：

```console
$ python3 tests/test-mapping.py
== DSH: _map_event 映射 ==
  ✓ PASS session 事件 → 取到 sessionId
  ✓ PASS thinking → reasoning（思考块）
  ✓ PASS tool_call → tool(running) 带 name/args/id
  ✓ PASS tool_result → tool(done) 带结果，id 对得上
  ✓ PASS tool_result 会沿用 tool_call 记下的 name/args（SSE 自洽，不退化成 name=tool）
  ✓ PASS 旧版内嵌 tool-call 也能拆成工具卡
== Codex: _map_item 映射（NDJSON） ==
  ✓ PASS reasoning → 思考块（text 与 summary[] 两种字段都认）
  ✓ PASS command_execution(started) → tool(running)
  ✓ PASS command_execution(completed) → tool(done) 带输出
  ✓ PASS file_change → 工具卡（含改动路径）
  ✓ PASS 真 error → error 事件
  ✓ PASS 「ignoring configuration setting」噪音 → notice（不吓用户）
== Codex: _item_to_row（sqlite camelCase → 前端行） ==
  ✓ PASS userMessage / agentMessage / reasoning / commandExecution / fileChange …
== 结果 ==
  PASS=23  FAIL=0
```

这是本轮修掉「假红」的做法：活体断言只测模型稳定产出的部分，映射正确性交给确定性单测。

---

## 9. 截图（390×844，13 张）

```console
$ export PATH=/mnt/ssd/apps/nodejs_v24/bin:$PATH
$ node tests/shot.mjs
  前端就绪，window.S 可用
  Hermes 会话: selftest-1791283721 工具数= 1
  saved shots/01-hermes-collapsed.png
  saved shots/02-hermes-reasoning-open.png
  saved shots/03-hermes-tool-open.png
  saved shots/04-files-list.png
  MD 预览: PROGRESS.md
  saved shots/05-file-preview-md.png
  预览浮层样式: rgb(11, 14, 19)|z=100
  图片目录: hermes-46f70 图片: chat-hynixing-mobile.png
  saved shots/06-file-preview-image.png
  真实发消息 → codex: 用 bash 跑 echo codex-ui 再告诉我结果
  codex 完成：turn 数 0 → 1
  saved shots/07-codex-live-turn.png
  saved shots/08-codex-sessions.png
  真实发消息 → dsh: 用 bash 跑 echo dsh-ui 再告诉我结果
  dsh 完成：turn 数 0 → 1
  saved shots/09-dsh-live-turn.png
  saved shots/10-dsh-sessions.png
  三通道前端状态: {…}
  截图完成，共 10 张（390×844）
```

| # | 文件 | 内容 |
|---|---|---|
| 01 | `01-hermes-collapsed.png` | Hermes 历史，思考过程默认折叠 |
| 02 | `02-hermes-reasoning-open.png` | 思考过程展开 |
| 03 | `03-hermes-tool-open.png` | 工具折叠卡展开（参数 + 结果） |
| 04 | `04-files-list.png` | 文件列表（图标 / 大小 / 时间 / 下载） |
| 05 | `05-file-preview-md.png` | **实心浮层**下的 MD 页内预览 |
| 06 | `06-file-preview-image.png` | **实心浮层**下的图片预览 |
| 07 | `07-codex-live-turn.png` | **浏览器里真发消息**后的 Codex 一轮（工具卡 + tokens） |
| 08 | `08-codex-sessions.png` | Codex 独立会话抽屉 |
| 09 | `09-dsh-live-turn.png` | **浏览器里真发消息**后的 DSH 一轮（思考 + 工具卡 + tokens） |
| 10 | `10-dsh-sessions.png` | DSH 独立会话抽屉 |
| 11 | `11-hermes-generating.png` | 生成中提示条（可以切走/锁屏） |
| 12 | `12-hermes-resume-attached.png` | 重载页面后重进会话，接上仍在跑的那一轮 |
| 13 | `13-hermes-resumed-done.png` | 断开期间跑完的结果被补回（不是 Operation interrupted） |

13 张的 md5 **全部不同**（`md5sum shots/*.png | sort | uniq -d | wc -l` → `0`），
且均为 390×844 @2x（780×1688 像素）。

> 07 / 09 不是摆拍：截图脚本在真实 chromium 里填输入框、点发送、等 `streaming` 结束，
> 然后才截屏。脚本现在**超时即抛错**，不会再像以前那样静默截出一堆空屏还报成功。

---

## 10. 红线遵守

```console
$ for s in dsh dsh-relay codex-web hermes hermes-gateway hermes-chat cloudflared easytier chromium-cdp nas-console; do
    printf '%-18s %s\n' "$s" "$(systemctl is-active $s)"; done
dsh                active
dsh-relay          active
codex-web          active
hermes             active
hermes-gateway     active
hermes-chat        active
cloudflared        active
easytier           active
chromium-cdp       active
nas-console        active
```

- 未停 / 未改 / 未重启任何既有服务（自测与截图前后均为 `active`）。
- **未碰 Cloudflare 任何配置**（无 token；公网入口由用户挂好）。
- 只写 `nas-console/**`、`/etc/systemd/system/nas-console.service`、`/vol1/ai/_logs/nas-console.{out,err}`。
- 前端零 CDN；服务端零新增编译依赖（只用解释器里已有的 aiohttp / PyJWT / cryptography）。
- 公网 `curl https://nas.hynixing.cn/` → `302` 跳 Access 登录页（**正常**，不是故障）：

```console
$ curl -s -o /dev/null -w '%{http_code}\n' https://nas.hynixing.cn/
302
$ curl -s -o /dev/null -w '%{redirect_url}\n' https://nas.hynixing.cn/ | head -c 120
https://flat-mode-d430.cloudflareaccess.com/cdn-cgi/access/login/nas.hynixing.cn?kid=117e3aad1e5dac16…
```

---

## 10.5 主会话核验发现的**两个真问题**（已修）

### 问题 1：客户端一断开就把生成掐了（严重，工作白做）

**事故现场**（2026-10-06 20:31，主人在手机上让 Hermes 建 skill）：

```console
$ grep -n '20:32' /vol1/ai/_logs/nas-console.err
175:2026-10-06 20:32:41,519 INFO nas-console.hermes 客户端断开 → 结束这次生成
176:2026-10-06 20:32:41,520 ERROR aiohttp.server Error handling request from 127.0.0.1
      ... hermes.py:314 _send_sse → resp.write → ClientConnectionResetError

$ grep -n '20:32' /vol1/ai/agents/hermes/logs/gateway.log
1388:2026-10-06 20:32:53,977 INFO gateway.platforms.api_server:
      SSE client disconnected; interrupted agent task chatcmpl-0645862d3d7a4fbda172a6b12ac7b

$ sqlite3 state.db "select role, substr(content,1,50) from messages
                    where session_id='nasconsole-20261006-203147-0ea7' order by id desc limit 3"
assistant|Operation interrupted.
tool|[Tool execution skipped — terminal was not started. User sen
tool|{"output": "[Command interrupted]", "exit_code": 130, "error...
```

**根因链**：手机切后台 → SSE 长连接断 → 旧代码在断开分支里 `t.cancel()` 掉上游读取
→ 上游 HTTP 连接关闭 → Hermes 判定「客户端走了」→ 中断 agent 任务 → 活儿全白干。

**修法**：把「生成」和「浏览器连接」彻底解耦（新增 `srv/turns.py`）。

```
浏览器 ──SSE──┐
              ├──► Turn（独立后台任务，上限 15 分钟）
浏览器 ──SSE──┘        │
（断了就断，回来再接）   └──► 内存 + var/turns/<ch>__<sid>.json
```

- 断开只停止写 SSE，**不取消 turn**；turn 跑完（超时 900s 才 `killpg`）。
- 事件全量缓存：内存 + 落盘 `var/turns/`；连续 `text` 合并，避免缓存爆掉。
- 新端点：`GET /api/{ch}/turns/{sid}`（快照）、`GET /api/{ch}/turns/{sid}/stream`（补播+跟随）。
- 前端：重进会话自动补播 + 继续跟随 + 弱网自动重连（最多 5 次）；
  跑完了但本地没内容就用权威历史兜底；界面加提示条
  「生成中 —— 可以切走 / 锁屏，回来还能看到结果」。
- 断开异常（`ConnectionResetError` / aiohttp 的 `ClientConnectionResetError`）一律吞掉，
  不再让 aiohttp 打 traceback。

**实测（自测第 12 节，全是真跑）**：

```console
== 12. 断开不掐生成 + 轮次缓存（问题 1） ==
  ✓ PASS 断开 3 秒后服务端这一轮仍在跑（status=running）
  ✓ PASS 断开不影响上游：这一轮自己跑完了（status=done）
  ✓ PASS 轮次缓存里能看到工具真实输出 DISC_SELFTEST_OK
  ✓ PASS 工具卡最终是 done（不是被中断的 running）
  ✓ PASS 轮次已落盘 var/turns/hermes__selftest-disc-1791291995.json
  ✓ PASS 断开后重新拉历史能看到完整回答
  ✓ PASS 全程日志无新 Traceback（11 → 11）
  ✓ PASS Hermes 侧无新的 interrupted agent task（2 → 2）
  ✓ PASS 重连 /turns/{id}/stream 能补播到断开期间的内容
  ✓ PASS 查不存在的轮次 → found:false（不报错）
```

**浏览器级验证**（`tests/test-resume.mjs`，真的发消息 + 真的重载页面）：

```console
$ node tests/test-resume.mjs
  发消息: 用 terminal 跑 sleep 20 && echo RESUME_OK，然后告诉我输出
  会话 id = nasconsole-20261006-211007-501a
  ✓ PASS 上游已开始跑工具（工具卡已渲染）
  ✓ PASS 生成期间「生成中」提示条可见
  —— 重载页面，模拟手机锁屏/切后台 ——
  ✓ PASS 重进会话后补回了用户消息（断开期间的内容没丢）
  ✓ PASS 重进后仍显示「生成中」（说明服务端还在跑，前端接上了）
  ✓ PASS 断开期间跑完的结果被补回来了（RESUME_OK 在面板里）
  ✓ PASS 没有出现 Operation interrupted
  ✓ PASS 生成结束后提示条自动隐藏
  PASS=7  FAIL=0
```

对应截图：`11-hermes-generating.png`（生成中）、`12-hermes-resume-attached.png`（重进后接上）、
`13-hermes-resumed-done.png`（断开期间跑完的结果被补回，**不是** Operation interrupted）。

> 修的过程中还发现前端一个真 bug：历史渲染把 user / assistant 拆成两个 `.turn`，
> 而缓存轮次又贴一份 → **内容重复显示两遍**（第一版 `12-*.png` 里能明显看到）。
> 已改成「一轮 = 一个 `.turn`」，并按用户消息文字认领历史里已有的那一轮就地重建。

### 问题 2：会话 cwd 为空 → 桌面端归到「Home」分组

```console
$ sqlite3 state.db "select id, source, cwd from sessions where id='nasconsole-20261006-203147-0ea7'"
nasconsole-20261006-203147-0ea7|api_server|            ← cwd 是空的

$ sqlite3 state.db "select coalesce(nullif(cwd,''),'(空)') c, count(*) from sessions group by c order by 2 desc"
(空)|201                                                  ← 201 条挤在「Home」分组
/vol1/ai/agents/hermes|15
...
```

**根因**：Hermes 的 `POST /api/sessions` **不认 `cwd` 字段**（实测传了 `cwd=…`，落库仍是空）；
桌面端侧栏按 `cwd` 分组（`tui_gateway/project_tree.py`），空 cwd 就落到最上面的「Home」。

**修法**（`srv/adapters/hermes.py::ensure_session`）：
1. `POST /api/sessions` 先建 id（带 `source=api_server`；已存在返回 409 视为成功）；
2. 再对 `state.db` 执行**唯一一条** UPDATE：

```sql
UPDATE sessions SET cwd=? WHERE id=? AND (cwd IS NULL OR cwd='')
```

**红线遵守**：这是本项目唯一一处写 Hermes 的库 —— 只这一条语句、只带 `WHERE id=?`、
只补空值（**绝不覆盖**已有 cwd）、不碰别的表/行、不改 schema；且放在线程池里执行不阻塞事件循环。

```console
$ sqlite3 state.db "select id, source, cwd from sessions where id='selftest-cwd-…'"
selftest-cwd-1791291995|api_server|/vol1/ai/projects/ds_project    ← 补上了

== 13. 建会话自动补 cwd（问题 2） ==
  ✓ PASS 新会话的 cwd 已补成 /vol1/ai/projects/ds_project（不再是空 → 不会掉进 Home 分组）
  ✓ PASS 既有会话的 cwd 未被覆盖（/vol1/ai/agents/hermes 那批还在）
```

---

## 10.6 D4：让手机端开的会话在桌面客户端里可见、可续聊

### 结论（对照实验，主会话实测）

Hermes 桌面客户端侧栏（含搜索框）**只列『本机来源』的会话**
（`source` = `desktop` / `cli` / `tui` / `local`）：

| 会话 id   | source       | 桌面端侧栏 |
|-----------|--------------|-----------|
| 标准 id   | `desktop`    | **可见** ✅ |
| 标准 id   | `api_server` | **不可见** ❌ |
| 非标准 id | `desktop`    | **可见** ✅ |

**可见性只由 `source` 决定**，与会话 id 格式、cwd、消息数都无关。

服务端侧能对上的机制：桌面侧栏的会话树由
`tui_gateway/server.py::_project_tree_inputs()` 组装，它调
`list_sessions_rich(..., exclude_sources=_PROJECT_TREE_EXCLUDED_SOURCES)`；
但后端那个常量只有 `["cron", "kanban"]` —— 也就是说「只列本机来源」这层白名单
是在**桌面客户端**那一侧做的，读后端代码推不出来，只能靠对照实验确认。

### 改法

`ensure_session()` 建会话时 `source` 从 `api_server` 改成 **`desktop`**（`409` 仍视为已存在）：

```python
json={"source": "desktop", "session_id": session_id}
```

代码注释里写清了上面这段对照实验，并标注「⚠ 别当成笔误改回 api_server」。
`cwd` 补齐逻辑**一字未动**。

**为什么改 source 不影响对话**：每次对话走 `/v1/chat/completions`，
`agent.platform` 由**本轮请求**决定（`agent/agent_init.py:632`：
`agent.platform = platform`，API 请求即 `api_server`），与库里存的 `source` 无关 ——
平台提示词（`PLATFORM_HINTS`）和工具集都不会因此变化。

### 端到端自证（要求 5：真发消息 → 读 state.db）

```console
$ SID="d4-proof-$(date +%s)"          # d4-proof-1791293844
$ curl -s -m 120 -X POST http://127.0.0.1:3096/api/hermes/chat \
    -H 'Content-Type: application/json' \
    -d "{\"session_id\":\"$SID\",\"message\":\"只回两个字：收到\"}"
data: {"type": "session", "session_id": "d4-proof-1791293844", "cwd": "/vol1/ai/projects/ds_project"}
data: {"type": "final", "text": "收到", "session_id": "d4-proof-1791293844"}

$ sqlite3 "file:$STATE_DB?mode=ro" "select id, source, cwd from sessions where id='$SID';"
d4-proof-1791293844|desktop|/vol1/ai/projects/ds_project
                    ^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                    source   cwd —— 两列都对了
```

单独看这两列：

```console
source = desktop
cwd    = /vol1/ai/projects/ds_project
```

**续聊验证**（同一会话再发一条，上下文接得上、两列不变）：

```console
$ sqlite3 "file:$STATE_DB?mode=ro" "select role, content from messages where session_id='$SID' order by id;"
user|只回两个字：收到
assistant|收到
user|我刚让你回哪两个字？只回那两个字
assistant|收到          ← 上下文接上了
```

### 自测新增断言（要求 4）

```console
== 13. 建会话自动补 cwd + source=desktop（问题 2 / D4） ==
  ✓ PASS 新会话的 cwd 已补成 /vol1/ai/projects/ds_project（不再是空 → 不会掉进 Home 分组）
  ✓ PASS 既有会话的 cwd 未被覆盖（/vol1/ai/agents/hermes 那批还在）
  ✓ PASS 新会话的 source=desktop（桌面端侧栏可见、点开可续聊；不是 api_server）
  ↳ state.db 实读: id=selftest-cwd-1791294064  source|cwd = desktop|/vol1/ai/projects/ds_project
```

### 边界（实测确认）

`409` 确实**不会覆盖**已有会话 —— 在一个老的 `api_server` 会话里再聊一次，source 保持原样：

```console
$ sqlite3 "file:$STATE_DB?mode=ro" "select id, source from sessions where id='nasconsole-20261006-212251-aec7';"
# 聊之前：nasconsole-20261006-212251-aec7|api_server
# 聊之后：nasconsole-20261006-212251-aec7|api_server     ← 没被改
```

所以 **D4 之前建的会话仍然是 `api_server`，在桌面端依旧不显示**；
不批量改是因为那会碰多行、违反「state.db 只允许带 `WHERE id=?` 的单行语句」这条红线。
要回填需要单独授权（或者用新会话重新开一段）。

---

## 11. 健壮性：客户端中途断开

手机锁屏 / 切后台 / `curl -m` 超时都会中途断开 SSE。断开是**正常事件**，
不能在日志里留 500 traceback，也不能留下子进程孤儿。

```console
$ B=$(grep -c 'Traceback' /vol1/ai/_logs/nas-console.err); echo $B
7
$ timeout 5 curl -sN -X POST http://127.0.0.1:3096/api/dsh/chat \
    -H 'Content-Type: application/json' -d '{"message":"用 bash 跑 sleep 30 再告诉我结果"}'
$ sleep 6
$ grep -c 'Traceback' /vol1/ai/_logs/nas-console.err
7                       # 没有新增
$ ps -eo comm --no-headers | grep -cx sleep
0                       # 孙进程也被回收
$ tail -1 /vol1/ai/_logs/nas-console.err
2026-10-06 19:24:08,871 INFO nas-console.stream 客户端断开 → 结束这次生成
```

自测第 11 节把这两条都钉死了：

```console
== 11. 客户端中途断开不产生 500（健壮性） ==
  ✓ PASS 中途断开后日志无新 Traceback（7 → 7）
  ✓ PASS 断开后子进程被回收，无 sleep 孤儿
```

---

## 12. 本轮踩坑与修复

| # | 现象 | 根因 | 修复 |
|---|---|---|---|
| 1 | Codex 的 `usage`/`final` 事件丢失，流看着「正常结束」 | `_stream.py` 里 `for ev in await tail()` —— `tail` 是 async generator，不是协程 | 改成 `async for ev in tail()` |
| 2 | 截图 01/02/03 字节完全相同、面板空白，脚本却报成功 | ① 顶层 `const S` 不是 `window` 属性，`Runtime.evaluate` 取不到；② 截图脚本按旧签名 `loadHistory(sid)` 调用，实际已是 `loadHistory(ch, sid)`；③ `loadHistory` 的 `catch` 静默吞异常；④ `waitFor` 超时只打日志不报错 | ① `window.S = S` 等显式挂载；② 修正调用；③ 改为 `console.error` 并显示在界面；④ 超时抛错、`evalJs` 遇页面异常抛错、并把页面 `console.error` 转发到终端 |
| 3 | DSH「完成」事件退化成 `name:"tool"`、`args` 丢失 | `tool_result` 只带 `callId` | 适配器记住 `tool_call` 的 name/args 再补回完成事件（有单测） |
| 4 | DSH 活体自测偶发「无 reasoning」假红 | `thinking` 是否出现取决于模型 | 活体只测稳定项，映射正确性交给确定性单测 |
| 5 | Codex 把「忽略未知配置项」报成 error，吓到用户 | 上游把 warning 也标成 `item.type=error` | 降级为 `notice` |
| 6 | 客户端中途断开 → 日志一堆 500 traceback | `except ConnectionResetError` 里 `raise` 又把它抛回 aiohttp | 断开只记 INFO 并取消任务，**不 re-raise**（`asyncio.CancelledError` 仍如实上抛） |
| 7 | 断开后 `sleep 30` 变孤儿 | 只 `proc.kill()` 直接子进程，`dsh → bash → sleep` 的孙进程活着 | 新增 `srv/adapters/_proc.py`：`start_new_session=True` 独立进程组 + `killpg` 整组回收（SIGTERM→SIGKILL） |
| 8 | `.md` 页内预览失效 | aiohttp `FileResponse` mime 猜测把它认成 `application/octet-stream` | 显式写 `Content-Type` |
| 9 | 重进会话后内容**重复显示两遍** | 历史渲染把 user / assistant 拆成两个 `.turn`，缓存轮次又贴一份 | 改成「一轮 = 一个 `.turn`」（user/assistant/tool 合并），`attachTurn` 按用户消息文字认领历史里已有的那一轮**就地重建** |
| 10 | Hermes 轮次一开就报 `stream_producer() takes 0 positional arguments but 1 was given` | 新 `run_turn` 按 `fn(queue)` 调生产者，hermes 的两个生产者还闭包着外层 queue、签名是 0 参 | 生产者统一改成 `async def f(queue)` |
| 11 | 截图 01/02 又变成一模一样（这次没报错） | 挑中的会话思考块只有 **1 个字符**，展开前后视觉无差别 | 挑会话时按「思考内容总字数」排序（`>60` 优先），并在截完 01/02/03 后**比对字节**，重复就抛错 |
| 13 | D4：手机端开的会话在桌面客户端里根本不出现 | 桌面端侧栏只列『本机来源』（desktop/cli/tui/local），`api_server` 一律不显示 | 建会话时 `source` 写 `desktop`；注释里钉死对照实验，防止被当笔误改回 |
| 12 | 自测第 11 节「断开后无 sleep 孤儿」变假红 | 语义改了：断开后子进程**本来就该继续跑**，7 秒时它当然还在 | 改成「等这一轮跑完再确认无孤儿」，并说明为什么不能立刻断言 |

---

## 13. 已知限制

1. DSH 的思考块是否出现取决于模型（映射本身有单测钉死）。
2. Hermes 思考块靠 1s 轮询补齐，通常出现在正文之后（上游 SSE 不带 reasoning delta）。
3. Hermes 会话列表未分页（上游默认前 50 条）；DSH/Codex 取最近 60/80 条。
4. Codex 首轮较慢（要起 node 子进程），一轮 20–60s 属正常；同一 thread 串行排队。
5. DSH 历史全盘扫描有 mtime 缓存，会话很多时首屏仍可能要几秒。
6. 图片预览用浏览器原生缩放，未做双指手势。
7. 服务以 root 运行（与 DSH / Codex 子进程要求一致）。
8. 同一会话同时只允许一轮生成，重复发返回 `409 busy`（界面上发送键此时也是禁用的）。
9. 单轮生成上限 15 分钟（`NAS_TURN_TIMEOUT`），超时才终止并回收子进程组。
10. `var/turns/` 只保留最近 80 轮（`NAS_TURN_KEEP`），更早的靠权威历史兜底。
11. 断开后如果服务重启，那一轮会被取消（`on_cleanup` 统一取消）；重启后仍能补播已完成轮次的缓存。
