- commit
- 769f669
- parent
- 80ecf7b
- author
- im_wower
- date
- 2026-03-29 01:10:21 +0800 CST
docs: add T-S045 artifact-db to D1 sync queue integration task Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2 files changed,
+148,
-1
+143,
-0
1@@ -0,0 +1,143 @@
2+# Task T-S045：串联 artifact-db 写入与 D1 同步队列
3+
4+## 状态
5+
6+- 当前状态：`待开始`
7+- 规模预估：`S`
8+- 依赖任务：`T-S040`、`T-S042`
9+- 建议执行者：`Claude`（需要理解 artifact-db store 和 d1-client sync-queue 的交互，在写入路径中精确插入 enqueue 调用）
10+
11+## 直接给对话的提示词
12+
13+读 `/Users/george/code/baa-conductor/tasks/T-S045.md` 任务文档，完成开发任务。
14+
15+如需补背景，再读：
16+
17+- `/Users/george/code/baa-conductor/plans/ARTIFACT_STATIC_SERVICE.md`
18+- `/Users/george/code/baa-conductor/packages/artifact-db/src/store.ts`
19+- `/Users/george/code/baa-conductor/packages/d1-client/src/sync-queue.ts`
20+- `/Users/george/code/baa-conductor/packages/d1-client/src/sync-worker.ts`
21+
22+## 当前基线
23+
24+- 仓库：`/Users/george/code/baa-conductor`
25+- 分支基线：`main`
26+- 提交：`80ecf7b`
27+
28+## 分支与 worktree（强制）
29+
30+每个任务必须使用独立的分支和 worktree，禁止直接在 main 上修改，禁止多个任务共用同一个 worktree。
31+
32+- 分支名：`feat/artifact-d1-sync`
33+- worktree 路径：`/Users/george/code/baa-conductor-artifact-d1-sync`
34+
35+开工步骤：
36+
37+1. `cd /Users/george/code/baa-conductor`
38+2. `git worktree add ../baa-conductor-artifact-d1-sync -b feat/artifact-d1-sync main`
39+3. `cd ../baa-conductor-artifact-d1-sync`
40+4. 在这个 worktree 目录里开发，不要回到主仓库目录
41+
42+完成后提交与推送（由执行者完成，不要合并）：
43+
44+1. 在 worktree 里提交所有变更（包括更新后的任务文档）
45+2. `git push -u origin feat/artifact-d1-sync`
46+
47+## 目标
48+
49+将 artifact-db 的 insertMessage / insertExecution / upsertSession 写入操作与 D1 同步队列串联，每次本地写入后自动 enqueue 一条同步记录。同时让 sync worker 定期清理已同步的记录。
50+
51+## 背景
52+
53+T-S042 实现了 D1 客户端和同步队列，但还没与 artifact-db 的写入路径串联。当前本地写入不会触发 D1 同步。`purgeSynced()` 方法已实现但未被自动调用，长期运行会积累已同步记录。
54+
55+## 涉及仓库
56+
57+- `/Users/george/code/baa-conductor`
58+
59+## 范围
60+
61+- artifact-db 写入时自动 enqueue 同步记录
62+- sync worker 定期清理已同步记录
63+- conductor 启动时注入 sync queue 到 artifact store
64+
65+## 允许修改的目录
66+
67+- `/Users/george/code/baa-conductor/packages/artifact-db/src/` （store.ts、types.ts）
68+- `/Users/george/code/baa-conductor/packages/d1-client/src/` （sync-worker.ts，如需加 purge 调度）
69+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.ts` （注入 sync queue）
70+
71+## 尽量不要修改
72+
73+- `/Users/george/code/baa-conductor/packages/d1-client/src/client.ts` （D1 客户端已完成）
74+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/local-api.ts`
75+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/instructions/`
76+- `/Users/george/code/baa-conductor/plugins/`
77+
78+## 必须完成
79+
80+### 1. artifact-db 写入时自动 enqueue
81+
82+- ArtifactStore 接受可选的 SyncQueue 实例（通过构造函数或 setter 注入）
83+- `insertMessage()` 成功后，调用 `syncQueue.enqueue("messages", id, "insert", payload)`
84+- `insertExecution()` 成功后，调用 `syncQueue.enqueue("executions", instructionId, "insert", payload)`
85+- `upsertSession()` 成功后，调用 `syncQueue.enqueue("sessions", id, "insert", payload)`
86+- enqueue 失败只 log，不影响本地写入（与 artifact 写入的 best-effort 原则一致）
87+- SyncQueue 未注入时（D1 未配置），跳过 enqueue
88+
89+### 2. sync worker 定期清理已同步记录
90+
91+- sync worker 每次扫描完 pending 记录后，调用 `purgeSynced()` 清理已同步记录
92+- 保留最近 1000 条 synced 记录（或可配置），删除更早的
93+- 清理失败只 log，不影响 sync worker 运行
94+
95+### 3. conductor 启动时注入
96+
97+- ConductorRuntime 创建 D1SyncWorker 时，同时获取其 SyncQueue 实例
98+- 将 SyncQueue 注入到 ArtifactStore
99+- D1 未配置时，ArtifactStore 的 syncQueue 为 null，写入时跳过 enqueue
100+
101+## 需要特别注意
102+
103+- enqueue 操作必须在本地 SQLite 事务提交成功之后执行，不能在事务内
104+- enqueue 失败不能回滚已成功的本地写入
105+- SyncQueue 的 `enqueue()` 写的是 sync_queue 表（d1-client 管理），不是 artifact.db 里的表——注意两个 SQLite 库的区分
106+- 所有开发必须在 worktree 中进行，不要在主仓库目录修改代码
107+
108+## 验收标准
109+
110+- D1 环境变量设置后，insertMessage 触发 sync_queue 中出现 pending 记录
111+- D1 环境变量未设置时，insertMessage 正常工作，无 enqueue 调用
112+- sync worker 扫描后，synced 记录被自动清理（保留最近 N 条）
113+- enqueue 失败时本地写入不受影响
114+- 现有测试全部通过
115+
116+## 推荐验证命令
117+
118+- `cd /Users/george/code/baa-conductor-artifact-d1-sync && pnpm build`
119+- `cd /Users/george/code/baa-conductor-artifact-d1-sync && pnpm test`
120+
121+## 执行记录
122+
123+> 以下内容由执行任务的 AI 填写，创建任务时留空。
124+
125+### 开始执行
126+
127+- 执行者：
128+- 开始时间：
129+- 状态变更：`待开始` → `进行中`
130+
131+### 完成摘要
132+
133+- 完成时间：
134+- 状态变更：`进行中` → `已完成`
135+- 修改了哪些文件：
136+- 核心实现思路：
137+- 跑了哪些测试：
138+
139+### 执行过程中遇到的问题
140+
141+> 记录执行过程中遇到的阻塞、环境问题、临时绕过方案等。合并时由合并者判断是否需要修复或建新任务。
142+
143+### 剩余风险
144+
+5,
-1
1@@ -44,7 +44,11 @@
2 | [`T-S041`](./T-S041.md) | Artifact 查询路由与会话索引 | S | T-S039 | Codex / Claude | 待开始 |
3 | [`T-S042`](./T-S042.md) | D1 异步适配器与同步队列 | M | T-S039（可并行开发） | Codex | 待开始 |
4
5-执行顺序：T-S039 先行 → T-S040 和 T-S041 可并行 → T-S042 独立
6+执行顺序：T-S039 先行 → T-S040 和 T-S041 可并行 → T-S042 独立 → T-S045 收尾
7+
8+| 任务 | 标题 | 规模 | 依赖 | 建议 AI | 状态 |
9+|---|---|---|---|---|---|
10+| [`T-S045`](./T-S045.md) | 串联 artifact-db 写入与 D1 同步队列 | S | T-S040, T-S042 | Claude | 待开始 |
11
12 ### 独立任务
13