baa-conductor

T-S039.md

  1# Task T-S039：Artifact 静态服务基础层
  2
  3## 状态
  4
  5- 当前状态：`进行中`
  6- 规模预估：`M`
  7- 依赖任务：无
  8- 建议执行者：`Codex`（新 package，边界清晰，纯 schema + CRUD + 文件生成）
  9
 10## 直接给对话的提示词
 11
 12读 `/Users/george/code/baa-conductor/tasks/T-S039.md` 任务文档，完成开发任务。
 13
 14如需补背景，再读：
 15
 16- `/Users/george/code/baa-conductor/plans/ARTIFACT_STATIC_SERVICE.md`
 17
 18## 当前基线
 19
 20- 仓库：`/Users/george/code/baa-conductor`
 21- 分支基线：`main`
 22- 提交：`6ea34e2`
 23
 24## 分支与 worktree（强制）
 25
 26每个任务必须使用独立的分支和 worktree，禁止直接在 main 上修改，禁止多个任务共用同一个 worktree。
 27
 28- 分支名：`feat/artifact-foundation`
 29- worktree 路径：`/Users/george/code/baa-conductor-artifact-foundation`
 30
 31开工步骤：
 32
 331. `cd /Users/george/code/baa-conductor`
 342. `git worktree add ../baa-conductor-artifact-foundation -b feat/artifact-foundation main`
 353. `cd ../baa-conductor-artifact-foundation`
 364. 在这个 worktree 目录里开发，不要回到主仓库目录
 37
 38完成后提交与推送（由执行者完成，不要合并）：
 39
 401. 在 worktree 里提交所有变更（包括更新后的任务文档）
 412. `git push -u origin feat/artifact-foundation`
 42
 43合并冲突处理：
 44
 451. 如果 `git merge` 报冲突，先 `git diff` 查看冲突文件
 462. 手动解决冲突后 `git add` 冲突文件
 473. `git merge --continue` 完成合并
 484. 不要用 `git merge --abort` 然后 force 覆盖
 49
 50## 目标
 51
 52新建 artifact 数据库（SQLite），建表，实现静态文件生成模块，在 conductor HTTP server 上挂载 `/artifact/` 路由和 `/robots.txt`。
 53
 54## 背景
 55
 56当前执行结果只能文本回送，大结果截断丢失，跨会话无法接续。需要把消息和执行结果持久化到数据库，同时生成可通过 HTTP GET 访问的静态文件。本任务是整个 Artifact 静态服务的基础层，后续任务依赖本任务的数据库和文件生成能力。
 57
 58## 涉及仓库
 59
 60- `/Users/george/code/baa-conductor`
 61
 62## 范围
 63
 64- 新建 artifact SQLite 数据库（独立于现有 packages/db）
 65- 建 messages、executions、sessions 三张表
 66- 实现静态文件生成模块（.txt + .json 双格式）
 67- conductor HTTP server 挂载 `/artifact/` 路由 serve 静态文件
 68- 挂载 `/robots.txt` 路由
 69
 70## 路径约束
 71
 72- 新数据库文件放在 `state/artifact.db`
 73- 静态文件目录放在 `state/artifacts/`
 74- 静态文件子目录：`state/artifacts/msg/`、`state/artifacts/exec/`、`state/artifacts/session/`
 75
 76## 推荐实现边界
 77
 78建议新增：
 79
 80- `packages/artifact-db/` — 新 package，artifact 数据库层
 81  - `src/schema.ts` — 建表 SQL
 82  - `src/store.ts` — CRUD 操作
 83  - `src/static-gen.ts` — 静态文件生成（.txt + .json）
 84  - `src/types.ts` — 类型定义
 85
 86建议修改：
 87
 88- `apps/conductor-daemon/src/local-api.ts` — 新增 `/artifact/` 和 `/robots.txt` 路由
 89
 90## 允许修改的目录
 91
 92- `/Users/george/code/baa-conductor/packages/` （新建 artifact-db）
 93- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/local-api.ts` （加路由）
 94- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.ts` （初始化数据库）
 95
 96## 尽量不要修改
 97
 98- `/Users/george/code/baa-conductor/packages/db/` （现有数据库，不动）
 99- `/Users/george/code/baa-conductor/plugins/` （插件不动）
100- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/instructions/` （T-S040 的范围）
101- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/artifacts/` （T-S040 的范围）
102
103## 必须完成
104
105### 1. 新建 artifact 数据库和表
106
107- 新建 `packages/artifact-db/` package
108- 建 `messages` 表：id, platform, conversation_id, role, raw_text, summary, observed_at, static_path, page_url, page_title, organization_id, created_at
109- 建 `executions` 表：instruction_id, message_id, target, tool, params, params_kind, result_ok, result_data, result_summary, result_error, http_status, executed_at, static_path, created_at
110- 建 `sessions` 表：id, platform, conversation_id, started_at, last_activity_at, message_count, execution_count, summary, created_at
111- 提供 CRUD 方法：insertMessage, insertExecution, upsertSession, getMessage, getExecution, listMessages, listExecutions, listSessions, getLatestSessions
112- 表结构参见 `plans/ARTIFACT_STATIC_SERVICE.md` 第 4 节
113
114### 2. 实现静态文件生成
115
116- 写入数据库时同步生成 `.txt` + `.json` 两个文件
117- `.txt` 格式：frontmatter 元数据 + `---` 分隔 + 正文（参见方案文档第 6 节）
118- `.json` 格式：完整 JSON 对象（参见方案文档第 6 节）
119- 文件路径用 ID 命名：`state/artifacts/msg/{id}.txt`、`state/artifacts/exec/{id}.txt`
120- Content-Type：`.txt` 返回 `text/plain; charset=utf-8`，`.json` 返回 `application/json; charset=utf-8`
121
122### 3. 挂载 HTTP 路由
123
124- `/artifact/**` — 从 `state/artifacts/` 目录 serve 静态文件
125- `/robots.txt` — 返回 `User-agent: *\nAllow: /artifact/\n`
126- 不需要鉴权（当前公开访问）
127- 文件不存在时返回 404
128
129## 需要特别注意
130
131- 新数据库是独立的 `state/artifact.db`，不要动现有的 `packages/db` 和相关 migration
132- 静态文件生成必须是同步的（写库 → 写文件一起完成），不能异步延迟
133- URL 中的 ID 使用 hash/UUID 格式，不用递增数字
134- 本任务只建基础能力，不接入指令执行主链路（那是 T-S040 的事）
135- 所有开发必须在 worktree 中进行，不要在主仓库目录修改代码
136
137## 验收标准
138
139- `packages/artifact-db/` 可以独立编译通过
140- 调用 `insertMessage()` 后，`state/artifacts/msg/{id}.txt` 和 `.json` 文件存在且内容正确
141- 调用 `insertExecution()` 后，`state/artifacts/exec/{id}.txt` 和 `.json` 文件存在且内容正确
142- `curl http://100.71.210.78:4317/artifact/msg/{id}.txt` 返回 200 + 正确内容
143- `curl http://100.71.210.78:4317/artifact/msg/{id}.json` 返回 200 + 正确 JSON
144- `curl http://100.71.210.78:4317/robots.txt` 返回正确的 robots 内容
145- 访问不存在的文件返回 404
146
147## 推荐验证命令
148
149- `cd /Users/george/code/baa-conductor-artifact-foundation && pnpm build`
150- `cd /Users/george/code/baa-conductor-artifact-foundation && pnpm test`
151- `curl http://100.71.210.78:4317/robots.txt`
152- `curl http://100.71.210.78:4317/artifact/msg/test.txt`
153
154## 执行记录
155
156> 以下内容由执行任务的 AI 填写，创建任务时留空。
157
158### 开始执行
159
160- 执行者：Codex
161- 开始时间：2026-03-28 17:44:00 CST
162- 状态变更：`待开始` → `进行中`
163
164### 完成摘要
165
166- 完成时间：2026-03-28 17:59:13 CST
167- 状态变更：`进行中` → `已完成`
168- 修改了哪些文件：
169  - `packages/artifact-db/`（新增 schema / types / store / static-gen / tests）
170  - `apps/conductor-daemon/src/local-api.ts`
171  - `apps/conductor-daemon/src/index.ts`
172  - `apps/conductor-daemon/src/index.test.js`
173  - `apps/conductor-daemon/package.json`
174  - `pnpm-lock.yaml`
175- 核心实现思路：
176  - 新增独立 `ArtifactStore`，使用 `node:sqlite` 维护 `state/artifact.db`
177  - 写入 message / execution / session 时同步生成 `.txt` + `.json` 静态文件，并在失败时回滚数据库和文件覆盖
178  - 在 conductor local API 挂载 `/artifact/:scope/:file` 和 `/robots.txt`
179  - runtime 启动时初始化 `state/artifacts/` 与 artifact 数据库，并把 store 注入 HTTP server
180- 跑了哪些测试：
181  - `npx pnpm -C /Users/george/code/baa-conductor-artifact-foundation -F @baa-conductor/artifact-db test`
182  - `npx pnpm -C /Users/george/code/baa-conductor-artifact-foundation -F @baa-conductor/conductor-daemon test`
183  - `npx pnpm -C /Users/george/code/baa-conductor-artifact-foundation build`
184
185### 执行过程中遇到的问题
186
187> 记录执行过程中遇到的阻塞、环境问题、临时绕过方案等。合并时由合并者判断是否需要修复或建新任务。
188
189### 剩余风险
190
191- 仅验证了本地测试与本地 HTTP runtime，未实际对 `http://100.71.210.78:4317` 执行远程 `curl`