Skip to content

README.md

Latest commit

 

History

History
66 lines (46 loc) · 4.13 KB

README.md

File metadata and controls

66 lines (46 loc) · 4.13 KB
Raw

今日节奏板（Focus Ledger）

一个范围刻意很小、但数据链路完整的浏览器应用：用户查看今日四项安排，在真实 Univer Sheet 中增加 15 分钟复盘时间，审阅 worktree 后决定合入或丢弃。

页面内的内容区域由 @univerjs-pro/cowork Viewer 渲染，不是 iframe、图片或静态 mock。应用首次启动会从 data/focus-plan.csv 导入 .runtime/focus-ledger.univer，在初始化 worktree 中执行 univer-scripts/bootstrap.mjs，用 inspect range A1:E5 读回并验证显式单元格类型，再 ready、merge 到 trunk。页面的领域按钮会创建另一个真实 worktree，执行 univer-scripts/add-review-time.mjs，读回 D5/E5 后才显示“ready”。合入和丢弃由 Cowork controller action 执行。

公开零部件与连接

  • univer-cli@0.3.5：项目内 CLI executable、匹配版本的 Runtime Skills、daemon/Gateway；
  • @univerjs-pro/cowork@0.1.0：controller、Gateway data source、content surface、React Viewer 与 styles；
  • Cowork 声明的完整 Univer SDK peer cohort：由 npm lockfile 固定，版本记录在 univer.compatibility.json；
  • React 19、Vite 8、Express 5、http-proxy：应用 shell、生产构建和同源 HTTP/WebSocket 代理；
  • Gateway protocol 1（来自已安装 Cowork declarations 的公开常量）。

网络路径只有一条：

宿主机浏览器 -> http://<host>:4173/gateway/*
            -> 应用同源 HTTP/WebSocket proxy
            -> daemon status --json 返回的容器内 Gateway origin
            -> .runtime/focus-ledger.univer

前端只构造 ${window.location.origin}/gateway，API 也只公开 same-origin:/gateway，不会把 daemon 的 127.0.0.1:9123 发给宿主机浏览器。

本 CLI build 没有在 Gateway 上公开 Cowork 默认探测的 container SSE route；宿主因此使用 Cowork 声明中的公开 eventSourceFactory 扩展点连接同源 /api/ledger/events。CLI 创建 ready worktree 后宿主广播生命周期变化，controller 自动刷新；Viewer 的协作 WebSocket 仍原样透传 Gateway。

安装、构建与启动

要求 Node.js 22（本交付验证版本为 22.23.1，Linux x64）。

npm ci
npm run build
npm start

生产服务固定监听 0.0.0.0:4173。首次启动会创建 .runtime/ 并完成真实 Univerfile 初始化；后续启动从同一 target 读回验证。可用以下入口探活：

curl --noproxy '*' http://127.0.0.1:4173/api/health
curl --noproxy '*' http://127.0.0.1:4173/api/ledger

验证

npm run typecheck
npm test
npm run build
npm run verify:data
npm run test:e2e

verify:data 通过安装版本 CLI 对当前 target 执行结构化读回。Playwright 用生产入口等待 Cowork Viewer ready，断言 Canvas 存在，执行“增加 15 分钟复盘 → 合入到当前版本”，再从同一 target 读取 D5 的 { v, t }；同时收集浏览器 Gateway HTTP/WebSocket 请求，拒绝 daemon loopback、console error、资源 404 和跨域失败。

关键运行状态

运行时 metadata 保存在 .runtime/focus-ledger.json，原样持久化 target、unitId、初始化 worktreeId、commit sequence 与最近验证时间。.runtime/ 是部署数据，不提交 Git；正式部署应像本应用一样把它与 UNIVER_HOME 放在持久卷中。

当前公开能力边界

  • Cowork 0.1.0 的公开 Gateway container 是 local-univerfile | custom；本应用使用前者并由同一个 daemon 访问容器内绝对路径。它没有假设原始 Univerfile Link 可直接作为 Cowork container。
  • Cowork 主要提供 headless 状态、actions 和 Viewer；页面布局、中文文案、领域按钮、CLI adapter、daemon 生命周期与持久化由本应用负责。
  • 本应用只覆盖单个 Sheet target 和单用户本地 daemon，不提供账号、权限、多租户、远程持久化或冲突解决 UI。
  • Viewer 的 live trunk 编辑能力由 Cowork 提供；应用专有的“增加 15 分钟”仍刻意走 CLI worktree，以便在合入前留下结构化读回证据。