kai/web-terminal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0fa0b69ce9fa5a15c630e55ce92781dd6ccf7321
web-terminal/docs/PROGRESS_LOG.md
Yaojia Wang 0e10dc21c3 feat: T2 freeze src/types.ts (shared contracts) 
- All ARCHITECTURE §3 interfaces as pure types; dependency-free (no ws/node/DOM)
  so both backend and frontend can import it
- Refinements vs §3 (documented): EnvLike (not NodeJS.ProcessEnv), WebSocketLike +
  WS_OPEN (not ws.WebSocket), added Config.wsPath (invariant 8)
- ARCHITECTURE §3.1/§3.4 reconciled to match (anti-drift)
- tsc --noEmit passes

T2 of docs/PLAN.md
2026-06-16 07:58:52 +02:00

9.2 KiB
Raw Blame History

Web Terminal 实施进度日志 (Progress Log)

用途: 记录 PLAN.md 各任务的完成情况,作为跨会话记忆文件。 新会话开工前必读本文件。只记已发生的事实(含失败、跳过),不预填未来,不写愿望。 谁来写(G1): 本文件仅由 orchestrator(主会话)写入 —— 它不在任何任务的 Owns: 里, 防止并行 subagent 并发写冲突。被派的 subagent 不写本文件,而是把日志条目作为返回结果交回, 由 orchestrator 在每批 agent 返回后立即追加(不要攒到最后)。 完整维护规则见 CLAUDE.md → Development Workflow。

状态图例

标记 含义
[ ] TODO — 未开始
[~] IN PROGRESS — 进行中
[x] DONE — 完成且已验证
[!] BLOCKED — 受阻(须在详细日志写明阻塞原因)

当前焦点 (Current Focus)

新会话读到的第一块。保持准确,只描述"此刻"。

  • Wave: W0(T1 ✓ T2 ✓)→ W1 可放开并行 + T3
  • 任务: 下一步派 W1 批次(单批 ~3–5 个,worktree 隔离):T3 mock + T4 config + T5 protocol + T6 ring-buffer + T7 origin(再一批 T8–T11 前端)。dispatch prompt 见 DISPATCH.md。
  • 下一步: git commit 本次(T2)后,按 DISPATCH 派第一批 W1 builder;每批返回后 orchestrator 写 LOG。
  • 阻塞: 无。src/types.ts 已冻结,所有 W1 任务可只读 import。
  • 最后更新: 2026-06-16

任务总览 (Task Overview)

任务定义见 PLAN.md;按 Wave 分组。Steps 完成数 = PLAN 中该任务的勾选项。 多 agent 并行:同一 Wave 内任务互不依赖,可并行;跨 Wave 按依赖推进。

任务 Wave 模块 状态 Steps (完成/总) 完成日期
T1 W0 脚手架 + 装齐依赖 [x] 5/5 2026-06-16
T2 W0 src/types.ts 共享契约(冻结源) [x] 8/8 2026-06-16
T3 W0 mock IPty 测试替身 [ ] 0/2 —
T4 W1 config.ts [ ] 0/5 —
T5 W1 protocol.ts [ ] 0/4 —
T6 W1 ring-buffer.ts [ ] 0/4 —
T7 W1 http/origin.ts [ ] 0/3 —
T8 W1 public/index.html [ ] 0/1 —
T9 W1 public/style.css [ ] 0/1 —
T10 W1 public/keybar.ts [ ] 0/4 —
T11 W1 public/main.ts [ ] 0/6 —
T12 W2 session/session.ts [ ] 0/7 —
T13 W3 session/manager.ts [ ] 0/6 —
T14 W4 server.ts 接线 [ ] 0/6 —
T15 W4 集成 / E2E 测试 [ ] 0/2 —
T16 W5 验收 F1–F3(终端/TUI/resize) [ ] 0/3 —
T17 W5 验收 F4+F9(LAN/Origin) [ ] 0/2 —
T18 W5 验收 F5+F6(保活/回放) [ ] 0/2 —
T19 W5 验收 F7(移动键栏) [ ] 0/1 —
T20 W5 验收 F8(退出处理) [ ] 0/2 —
T21 W5 安全核对 + README + LOG 收尾 [ ] 0/3 —

验收清单映射 (Acceptance — TECH_DOC §8)

功能验收独立于阶段勾选;F* 全绿才算 v0.1 完成。

编号 功能 状态 验证方式 / 备注
F1 交互式终端(ls/补全/Ctrl+C/历史) [ ]
F2 全彩 + 全屏程序(vim/top/claude) [ ]
F3 终端自适应(resize 不错位) [ ]
F4 局域网访问(手机/他机) [ ] 与 F9 联测,确认 Origin 白名单含网卡 IP
F5 会话保活(断开重连仍在跑) [ ]
F6 重连回放(环形缓冲) [ ] 验证 ANSI/中文不乱码(M2)
F7 移动快捷键栏 [ ]
F8 进程退出处理 [ ] 含 detach 后退出补发 exit(L1)
F9 Origin 校验(401) [ ] 含 /term 路径限制(L3)

详细日志 (Detailed Log)

倒序,最新在最上。每个子任务一条。复制下方模板填写。

2026-06-16 · T1 脚手架 + 一次性装齐依赖

  • 状态: [x] DONE
  • 改动: package.json(scripts + 全部依赖 + postinstall)、tsconfig.json(后端 NodeNext/strict)、 tsconfig.web.json(前端 DOM/Bundler,当前 noEmit 仅类型检查)、vitest.config.ts(node 环境 + passWithNoTests)、.gitignore、package-lock.json、目录骨架 src{,/http,/session} public test{,/helpers,/integration}(各带 .gitkeep)。
  • 验证:
    • npm install 成功(运行时 72 包 + 开发包,0 漏洞)。解析版本(均比预期新的主版本):express 5.2、 @xterm/xterm 6.0、addon-fit 0.11、ws 8.21、node-pty 1.1;dev:typescript 6.0、vitest 4.1、tsx 4.22、@types/node 25。
    • node -e require('node-pty') → OK;真实 PTY spawn echo hello-from-pty → 16 bytes、exitCode 0(沙箱外验证)。
    • npm test → exit 0(passWithNoTests)。
  • 决策 / 偏离 PLAN:
    1. node-pty spawn-helper 修复:1.1.0 的 prebuild 自带 spawn-helper 但权限 -rw-r--r--(缺 +x), 导致 posix_spawnp failed。加 postinstall: chmod +x .../prebuilds/darwin-*/spawn-helper(对 Linux 无害,|| true), 使每次 install / 每个 worktree 自动修复。T12 spawn PTY 依赖此修复。
    2. 依赖解析到较新主版本(express 5 / xterm 6 / typescript 6 / vitest 4):T7/T11/T14/T15 注意 API 差异 (express 5 路由、xterm 6 import 形态)。
    3. 加了 PLAN 未列的脚本 dev/typecheck 与 postinstall(便利 + 必需修复),属合理补充,未改 PLAN 意图。
  • 遗留 / 待办: 无(原前端打包待决项已解决,见下补记)。
  • commit: b126cf0

2026-06-16 · T2 冻结共享类型契约 src/types.ts

  • 状态: [x] DONE
  • 改动: 新建 src/types.ts(纯类型,无实现);删 src/.gitkeep。含 Config、ClientMessage/ServerMessage/ ParseResult、Dims、IPty(子集)+ IDisposable/PtyEvent、RingBuffer、WebSocketLike + WS_OPEN、SessionMeta/Session (lastOutputAt/exitedAt/exitCode)、SessionManager、MountKeybar;各模块工厂函数签名以注释列为 import 锚点。 同步更新 ARCHITECTURE §3.1/§3.4(加 wsPath、EnvLike、WebSocketLike 注记,防漂移)。
  • 验证: npx tsc -p tsconfig.json --noEmit PASS;grep 确认无 ws/NodeJS/DOM 外部类型依赖(仅注释提及)。
  • 决策 / 偏离 ARCHITECTURE §3(为"前后端共享 → 必须无外部类型依赖"):
    1. loadConfig(env: EnvLike) 替代 NodeJS.ProcessEnv(EnvLike = Readonly<Record<string,string|undefined>>,process.env 可赋值)。
    2. Session.attachedWs: WebSocketLike 替代 ws 的 WebSocket(真实 ws 结构兼容);导出 WS_OPEN=1 供 M5 守卫。
    3. 新增 Config.wsPath(默认 '/term'):不变量 8 要求 WS 路径入 config,§3.1 原 Config 漏列,已补;T4 需从 env WS_PATH 读、T14 用 cfg.wsPath。 三处均已回写 ARCHITECTURE,types.ts 为权威冻结源。
  • 遗留 / 待办: 无。W1 全部任务现可只读 import src/types.ts。注意:IPty/WebSocketLike 是结构子集, 实现方(T12/T14)可把真实 node-pty IPty / ws.WebSocket 直接赋值(结构兼容)。
  • commit: (见下次提交)

2026-06-16 · T1 补记 — 前端打包定为 esbuild

  • 状态: [x] DONE
  • 改动: 装 esbuild(dev);package.json 接 build:web/dev:web(打包 public/main.ts → public/build/main.js); .gitignore 改忽略 public/build/;tsconfig.web.json 注释更新为"仅类型检查";前端构建约定写入 PLAN §1 并更新 T8/T11/T14 与 DISPATCH.md、ARCHITECTURE §5。
  • 验证: esbuild 0.28.1;临时入口 --bundle --format=esm --outdir=public/build 出 main.js+.map,smoke 通过。
  • 决策: 三选一中选 esbuild(极快、零配置、与 node-pty/tsx 生态一致);现在装好避免 W1 并发 install。 约定:入口 main.ts、产物 public/build/(已 gitignore)、index.html 用 <script type=module src=./build/main.js>、server 静态托管 public/。
  • commit: (见下次提交)

2026-06-15 · T0 项目记录起点(计划就绪)

  • 状态: [x] DONE
  • 改动: 创建 docs/PROGRESS_LOG.md、docs/PLAN.md(细粒度 T1–T21、为多 agent 并行设计);CLAUDE.md 加入 plan/log 工作流约束。
  • 验证: 文档自检;LOG 任务总览的 Steps 总数已与 PLAN 各任务勾选项对齐。
  • 决策 / 偏离 PLAN: 采用 TypeScript(ARCHITECTURE §0);两份设计文档已多团队交叉验证并修订 12 项;计划按依赖分 W0–W5 波次,W1 含 9 个零交叉并行任务。
  • 遗留 / 待办: 进入 W0 / T1(脚手架 + 装齐依赖);T1 完成后 T2 冻结 src/types.ts,随后 W1 可大规模并行。
  • commit: N/A