[oratis]

内容

两份面向 v0.24.0（基线 26266a5，含 #359–#367）的全项目审查文档，以及 .codex 认知库的基线同步：

• docs/PROJECT_REVIEW_UX_v0.24.0.md — 12 条 UX 问题（2 个 P0）、分表面评分、三波次优化计划与度量
• docs/PROJECT_REVIEW_TECH_v0.24.0.md — 12 条技术问题、v0.21 问题追踪表、验证结果、三波次计划与度量
• .codex/{README,PROJECT,REVIEW_BASELINE}.md — 2026-09-05 验证表、指向新文档、规模与热点数字更新

核心结论

技术：v0.21 的 P0 安全边界已全部落地；主要矛盾转为可维护性（server.ts 4,188 行、单个请求回调 3,078 行；客户端 4,004 行无类型字符串，+43%）、可靠性（本机实例间歇 5s+ 卡顿，/health 只有 {ok:true}）与工程门禁（无 lint / 覆盖率 / Dependabot，PR CI 不覆盖 website/mac/iOS，--no-reflect 在 Web 模式无效）。

UX 两个 P0：

1. 错 key 后的首次运行死胡同 —— 出生仪式对 401 也重试、原始 JSON 直出、ENTER 只是用同一个错 key 再跑一遍，key 表单再也不出现。
2. feat(web): 右侧面板默认收起 #367 之后移动端布局失效 —— body.rb-collapsed .frame 特异性高于 720px 媒体查询，375px 下主区仅 75px；展开后功能栏又把聊天视图撑到 681px。

验证（2026-09-05）

检查	结果
typecheck / build	通过
npm test	1,645 个，1,644 通过，1 个 PTY 跳过，0 失败
website / macOS / iOS	12 页 / 通过（14 警告）/ 29 测试通过
npm audit --omit=dev	3 个（v0.21 为 12），均为传递依赖且可修

UX 结论来自真实浏览器实测：从 main 构建，用 soul store API 离线合成已出生的 soul 起临时实例，全程零模型调用。

后续

优化按主题分成独立 PR 陆续提交（Web UI、服务端运行时、工具链/CI/依赖、文档、原生端、CLI、静态资源、Cloud 计费、路由表重构）。

🤖 Generated with Claude Code

[oratis]

评审 — 论断逐条实证，两处数字已修

这是整条栈的施工依据（#369–#376 全部按它的编号实现），所以评审重点不是文风而是每条论断是否属实。我把可验证的都跑了一遍。

量化论断：逐条精确吻合

文档论断	实测
server.ts 4,188 行	4188 ✓
createServer 回调起于 L1107	1107 ✓
lisa-client.ts 4,004 行	4004 ✓
lisa-css.ts 2,899 行	2899 ✓
island.ts 1,501 / room.ts 1,096 / cli.ts 1,147 / agent.ts 537	全部精确 ✓
非测试 src 284 文件 / 59,744 行	284 / 59744 ✓
测试 191 文件 / 21,623 行	191 / 21623 ✓
客户端 69 处 innerHTML	69 ✓
research/ 155 个文件、10MB	155 / 10M ✓
OpenAPI 契约覆盖 8 条路由	paths 恰好 8 条 ✓

路由字面量文档记 86；我按 url === " / url.startsWith(" 去重后得 80 条 /api/*、97 条含静态路由 —— 口径差异，不算错。

两个 P0 的诊断：结构性核实通过

UX-2（移动端布局）。 核对 lisa-css.ts：body.rb-collapsed .frame { grid-template-columns: 300px 1fr } 确实在任何媒体查询之外，而 @media (max-width:720px) .frame { 1fr } 特异性更低。375px 下折叠规则胜出、.frame 仍是两列 300px 1fr → 主区 75px。诊断成立。

UX-1（首次运行死胡同）。 三条证据逐条命中：birthEnterBtn 的 handler 就是 location.reload()；birth.ts 的 catch (e) 对任何异常（含 401）都再梦一次，且文档引用的那句 the first dream slipped away (…) — dreaming again… 与源码逐字一致；new Anthropic({...}) 确实没有 timeout 选项。

T-6（--no-reflect 在 Web 模式无效） 是我最想抽查的一条，因为"接受但不生效"很容易是误判。核实：WebServerOptions 在 server.ts:211 声明了 reflect: boolean，cli.ts:567 也确实传了 reflect: args.reflect —— 但 grep "opts.reflect" src/web/server.ts 零命中。参数被接收后从未读取。属实。

已修的两处数字

1. UX-2 的特异性位数写错了，而且是读者会据以行动的那种错。 body.rb-collapsed .frame 是 (0,2,1)（两个类 + 一个类型选择器），文档写成 (0,1,1)；媒体查询里的 .frame 是 (0,1,0)，文档写成 (0,0,1)。结论不受影响（折叠规则照样胜出，这正是缺陷本身），但 UX-2 给出的修法之一是"在 720px 块内用同等特异性覆盖回来"——要照着这个数字去配平，位数就必须是对的。

2. T-2 记 88 处 esc()，实为 71 处。

不改的

.codex/ 三个文件的基线同步全部核对无误（含 v0.21 → v0.24 的规模对比：4.8 万 → 6.0 万行）。文档结构、编号与下游 8 个 PR 的对应关系清晰，docs/ 里也没有引入失效链接。

结论

这是一份证据密度罕见的规划文档 —— 我抽查的每一条承重论断都精确成立，包括最容易翻车的"参数被接收但不生效"。作为下游 8 个 PR 的施工依据，可以信。

npm run typecheck 通过（本 PR 不含代码改动）。

🤖 Generated with Claude Code