uncaged/workflow
10
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: CAS-based thread storage (replace .data.jsonl) #155

New Issue
Closed
opened 2026-05-09 06:35:29 +00:00 by xiaoju · 1 comment
xiaoju commented 2026-05-09 06:35:29 +00:00
Owner
Copy Link
Copy Source

RFC: CAS-Based Thread Storage

Full design: docs/plans/2026-05-09-cas-thread-storage.md

Supersedes #154 (closed). Implementation issue: #155.

Phase 拆分

Phase 1: Protocol Types + CAS Helpers

新类型定义 + 基础工具函数，不改任何运行时行为。

scope:

  • workflow-protocol: 新增 StartNode, StateNode, ContentMerkleNode 类型
  • workflow-cas: collectRefs(payload) — 从 payload 递归提取所有 CAS hash
  • workflow-cas: findReachableHashes(roots, cas) — 从根集合递归标记可达 hash
  • 单元测试覆盖所有新类型和函数

验证: 类型编译通过 + 工具函数测试通过
Testing issue: 待创建

Phase 2: Engine Write Path

引擎写入改为 CAS 节点 + threads.json，替代 .data.jsonl。

scope:

  • workflow-execute/engine.ts: 写 StartNode、StateNode CAS blob，不再 appendDataLine
  • workflow-execute: threads.json 管理（创建、更新 head）
  • workflow-execute: 完成时写 __end__ StateNode，从 threads.json 移到 history/{date}.jsonl
  • StartNode 的 prompt 存入 CAS 引用

验证: 跑一个 hello-template workflow，检查 CAS 里有 StartNode + StateNode blob，threads.json 正确，无 .data.jsonl 产生
Testing issue: 待创建

Phase 3: Engine Read Path + Runtime

从 CAS 链构建 ThreadContext，extract phase 扩展。

scope:

  • workflow-runtime: 从 head hash 走链构建 ThreadContext（resolve ancestors、content from CAS）
  • workflow-execute/extract-fn.ts: 扩展 extractor 输出 { meta, contentPayload, refs[] }
  • Content Merkle 节点写入（type: "content", payload, refs）
  • createWorkflow 接收 CAS-resolved context

验证: 跑多步 workflow（solve-issue），验证 ThreadContext 正确构建，content Merkle 节点包含 refs
Testing issue: 待创建

Phase 4: Fork + GC

基于 CAS 链的零拷贝 fork + 简化 GC。

scope:

  • workflow-execute/fork-thread.ts: fork 创建新 StateNode 指向 fork point，注册新 threadId
  • workflow-execute/gc.ts: mark-and-sweep 从 threads.json + history 收集 roots，递归 refs[] 标记
  • 清理旧 .data.jsonl 相关代码

验证: fork 一个 thread，验证 CAS 节点共享；GC 后未引用的 blob 被清理
Testing issue: 待创建

Phase 5: CLI + Dashboard

用户界面适配新存储。

scope:

  • cli-workflow: thread list 从 threads.json + history 读取
  • cli-workflow: thread show 走 CAS 链展示
  • cli-workflow: thread rm 从 index 删除 + 可选 GC
  • cli-workflow/serve: SSE watch threads.json
  • workflow-dashboard: 适配新数据源

验证: CLI 命令正常工作，dashboard 实时显示 thread 进度
Testing issue: 待创建

完成标准

  • 所有 Phase 的 testing issue 已 close
  • bun run check 通过
  • 无 .data.jsonl 残留代码路径

Ref

小橘 🍊（NEKO Team）

## RFC: CAS-Based Thread Storage Full design: [`docs/plans/2026-05-09-cas-thread-storage.md`](https://git.shazhou.work/uncaged/workflow/src/branch/main/docs/plans/2026-05-09-cas-thread-storage.md) Supersedes #154 (closed). Implementation issue: #155. ## Phase 拆分 ### Phase 1: Protocol Types + CAS Helpers 新类型定义 + 基础工具函数，不改任何运行时行为。 **scope:** - `workflow-protocol`: 新增 `StartNode`, `StateNode`, `ContentMerkleNode` 类型 - `workflow-cas`: `collectRefs(payload)` — 从 payload 递归提取所有 CAS hash - `workflow-cas`: `findReachableHashes(roots, cas)` — 从根集合递归标记可达 hash - 单元测试覆盖所有新类型和函数 **验证:** 类型编译通过 + 工具函数测试通过 **Testing issue:** 待创建 ### Phase 2: Engine Write Path 引擎写入改为 CAS 节点 + threads.json，替代 .data.jsonl。 **scope:** - `workflow-execute/engine.ts`: 写 StartNode、StateNode CAS blob，不再 appendDataLine - `workflow-execute`: threads.json 管理（创建、更新 head） - `workflow-execute`: 完成时写 `__end__` StateNode，从 threads.json 移到 `history/{date}.jsonl` - StartNode 的 prompt 存入 CAS 引用 **验证:** 跑一个 hello-template workflow，检查 CAS 里有 StartNode + StateNode blob，threads.json 正确，无 .data.jsonl 产生 **Testing issue:** 待创建 ### Phase 3: Engine Read Path + Runtime 从 CAS 链构建 ThreadContext，extract phase 扩展。 **scope:** - `workflow-runtime`: 从 head hash 走链构建 `ThreadContext`（resolve ancestors、content from CAS） - `workflow-execute/extract-fn.ts`: 扩展 extractor 输出 `{ meta, contentPayload, refs[] }` - Content Merkle 节点写入（type: "content", payload, refs） - `createWorkflow` 接收 CAS-resolved context **验证:** 跑多步 workflow（solve-issue），验证 ThreadContext 正确构建，content Merkle 节点包含 refs **Testing issue:** 待创建 ### Phase 4: Fork + GC 基于 CAS 链的零拷贝 fork + 简化 GC。 **scope:** - `workflow-execute/fork-thread.ts`: fork 创建新 StateNode 指向 fork point，注册新 threadId - `workflow-execute/gc.ts`: mark-and-sweep 从 threads.json + history 收集 roots，递归 refs[] 标记 - 清理旧 .data.jsonl 相关代码 **验证:** fork 一个 thread，验证 CAS 节点共享；GC 后未引用的 blob 被清理 **Testing issue:** 待创建 ### Phase 5: CLI + Dashboard 用户界面适配新存储。 **scope:** - `cli-workflow`: `thread list` 从 threads.json + history 读取 - `cli-workflow`: `thread show` 走 CAS 链展示 - `cli-workflow`: `thread rm` 从 index 删除 + 可选 GC - `cli-workflow/serve`: SSE watch threads.json - `workflow-dashboard`: 适配新数据源 **验证:** CLI 命令正常工作，dashboard 实时显示 thread 进度 **Testing issue:** 待创建 ## 完成标准 - [ ] 所有 Phase 的 testing issue 已 close - [ ] `bun run check` 通过 - [ ] 无 .data.jsonl 残留代码路径 ## Ref 小橘 🍊（NEKO Team）
xiaoju commented 2026-05-09 08:16:20 +00:00
Author
Owner
Copy Link
Copy Source

验证结果汇总

  • ✅ Phase 1: Protocol Types + CAS Helpers (#156)
  • ✅ Phase 2: Engine Write Path (#157)
  • ✅ Phase 3: Engine Read Path + Runtime (#158)
  • ✅ Phase 4: Fork + GC (#159)
  • ✅ Phase 5: CLI + Dashboard (#160)

验证

  • bun run check: tsc + biome 全部通过
  • bun test: 166 pass, 0 fail
  • 零 .data.jsonl 生产代码路径

小橘 🍊（NEKO Team）

## 验证结果汇总 - ✅ Phase 1: Protocol Types + CAS Helpers (#156) - ✅ Phase 2: Engine Write Path (#157) - ✅ Phase 3: Engine Read Path + Runtime (#158) - ✅ Phase 4: Fork + GC (#159) - ✅ Phase 5: CLI + Dashboard (#160) ## 验证 - `bun run check`: tsc + biome 全部通过 - `bun test`: 166 pass, 0 fail - 零 `.data.jsonl` 生产代码路径 小橘 🍊（NEKO Team）
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
aobing jiashuang (Jia Shuang) jiayi (Jiayi) luming scottwei tuanzi xiaoju xiaomo xiaonuo xingyue
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: uncaged/workflow#155
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?