baa-conductor

T-S041.md

  1# Task T-S041：Artifact 查询路由与会话索引
  2
  3## 状态
  4
  5- 当前状态：`已完成`
  6- 规模预估：`S`
  7- 依赖任务：`T-S039`
  8- 建议执行者：`Codex` 或 `Claude`（简单路由，边界清晰，都能做）
  9
 10## 直接给对话的提示词
 11
 12读 `/Users/george/code/baa-conductor/tasks/T-S041.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`（T-S039 合并后）
 22- 提交：`<T-S039 合并后的提交>`
 23
 24## 分支与 worktree（强制）
 25
 26每个任务必须使用独立的分支和 worktree，禁止直接在 main 上修改，禁止多个任务共用同一个 worktree。
 27
 28- 分支名：`feat/artifact-query-routes`
 29- worktree 路径：`/Users/george/code/baa-conductor-artifact-query-routes`
 30
 31开工步骤：
 32
 331. `cd /Users/george/code/baa-conductor`
 342. `git worktree add ../baa-conductor-artifact-query-routes -b feat/artifact-query-routes main`
 353. `cd ../baa-conductor-artifact-query-routes`
 364. 在这个 worktree 目录里开发，不要回到主仓库目录
 37
 38完成后提交与推送（由执行者完成，不要合并）：
 39
 401. 在 worktree 里提交所有变更（包括更新后的任务文档）
 412. `git push -u origin feat/artifact-query-routes`
 42
 43合并冲突处理：
 44
 451. 如果 `git merge` 报冲突，先 `git diff` 查看冲突文件
 462. 手动解决冲突后 `git add` 冲突文件
 473. `git merge --continue` 完成合并
 484. 不要用 `git merge --abort` 然后 force 覆盖
 49
 50## 目标
 51
 52在 conductor HTTP server 上新增消息、执行记录和会话的查询路由，供管理用途和内部调用。
 53
 54## 背景
 55
 56T-S039 建了数据库，T-S040 接入了写入。但目前只能通过静态文件访问单条记录，还缺少列表查询、筛选和分页能力。本任务补齐查询路由。
 57
 58## 涉及仓库
 59
 60- `/Users/george/code/baa-conductor`
 61
 62## 范围
 63
 64- 新增 6 个查询路由
 65- 支持分页和筛选
 66- 注册到 `/describe` 和 `/v1/capabilities`
 67
 68## 允许修改的目录
 69
 70- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/local-api.ts` （加路由）
 71- `/Users/george/code/baa-conductor/packages/artifact-db/` （如需补查询方法）
 72
 73## 尽量不要修改
 74
 75- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/instructions/` （T-S040 的范围）
 76- `/Users/george/code/baa-conductor/plugins/`
 77- `/Users/george/code/baa-conductor/packages/db/`
 78
 79## 必须完成
 80
 81### 1. 消息查询路由
 82
 83- `GET /v1/messages` — 消息列表
 84  - 查询参数：`platform`、`conversation_id`、`limit`（默认 50）、`offset`（默认 0）
 85  - 按 `observed_at` 倒序
 86  - 返回 JSON 数组，每条包含 id, platform, conversation_id, role, summary, observed_at, artifact_url
 87- `GET /v1/messages/{id}` — 单条消息详情
 88  - 返回完整 JSON（含 raw_text）
 89
 90### 2. 执行记录查询路由
 91
 92- `GET /v1/executions` — 执行记录列表
 93  - 查询参数：`message_id`、`target`、`tool`、`limit`（默认 50）、`offset`（默认 0）
 94  - 按 `executed_at` 倒序
 95  - 返回 JSON 数组，每条包含 instruction_id, message_id, target, tool, result_ok, result_summary, executed_at, artifact_url
 96- `GET /v1/executions/{id}` — 单条执行详情
 97  - 返回完整 JSON（含 result_data）
 98
 99### 3. 会话查询路由
100
101- `GET /v1/sessions` — 会话索引
102  - 查询参数：`platform`、`limit`（默认 20）、`offset`（默认 0）
103  - 按 `last_activity_at` 倒序
104- `GET /v1/sessions/latest` — 最近活跃会话
105  - 返回最近 10 个活跃 session + 每个 session 的最近消息和执行 URL
106
107### 4. 注册到 describe 和 capabilities
108
109- 所有新路由在 `/describe/business` 中可发现
110- 在 `/v1/capabilities` 中注册为 `kind: "read"`
111
112## 需要特别注意
113
114- 这些路由是只读查询，不需要 auth token
115- 返回的 artifact_url 必须是 exact URL（包含完整域名和路径）
116- `publicBaseUrl` 从 conductor 配置中获取
117- 列表查询不返回 raw_text / result_data 完整内容（太大），只返回 summary + artifact_url
118- 所有开发必须在 worktree 中进行，不要在主仓库目录修改代码
119
120## 验收标准
121
122- `curl http://100.71.210.78:4317/v1/messages` 返回 JSON 数组
123- `curl http://100.71.210.78:4317/v1/messages?platform=claude&limit=10` 筛选正常
124- `curl http://100.71.210.78:4317/v1/messages/{id}` 返回完整消息
125- `curl http://100.71.210.78:4317/v1/executions` 返回 JSON 数组
126- `curl http://100.71.210.78:4317/v1/sessions/latest` 返回最近会话索引
127- `/describe/business` 包含新路由
128- `/v1/capabilities` 包含新路由
129
130## 推荐验证命令
131
132- `cd /Users/george/code/baa-conductor-artifact-query-routes && pnpm build`
133- `cd /Users/george/code/baa-conductor-artifact-query-routes && pnpm test`
134- `curl http://100.71.210.78:4317/v1/messages | jq .`
135- `curl http://100.71.210.78:4317/v1/sessions/latest | jq .`
136- `curl http://100.71.210.78:4317/describe/business | jq .`
137
138## 执行记录
139
140> 以下内容由执行任务的 AI 填写，创建任务时留空。
141
142### 开始执行
143
144- 执行者：Claude
145- 开始时间：2026-03-29
146- 状态变更：`待开始` → `进行中`
147
148### 完成摘要
149
150- 完成时间：2026-03-29
151- 状态变更：`进行中` → `已完成`
152- 修改了哪些文件：
153  - `packages/artifact-db/src/store.ts` — 新增 `getPublicBaseUrl()` getter
154  - `apps/conductor-daemon/src/local-api.ts` — 新增 6 个查询路由 + handler + 注册到 describe/capabilities
155  - `apps/conductor-daemon/src/index.test.js` — 修正 business describe 断言正则（`/v1/exec` → `/v1/exec"` 避免误匹配 `/v1/executions`）
156- 核心实现思路：
157  - 在 `LOCAL_API_ROUTES` 数组末尾新增 6 条路由定义（artifact.messages.list/read、artifact.executions.list/read、artifact.sessions.list/latest）
158  - 将 6 个路由 ID 加入 `routeBelongsToSurface` 的 business 白名单，自动注册到 `/describe/business` 和 `/v1/capabilities`
159  - 实现 6 个 handler 函数，复用 `ArtifactStore` 已有的 `listMessages`/`getMessage`/`listExecutions`/`getExecution`/`listSessions`/`getLatestSessions`
160  - 列表路由只返回 summary + artifact_url，不返回 raw_text/result_data；详情路由返回完整内容
161  - artifact_url 通过 `buildArtifactPublicUrl(store.getPublicBaseUrl(), staticPath)` 生成，包含完整域名
162  - 新增 `readNonNegativeIntegerQuery` 用于解析 offset 参数，`tryParseJson` 用于安全解析执行记录中的 JSON 字段
163- 跑了哪些测试：
164  - `pnpm build` — 全量编译通过
165  - `pnpm test` — conductor-daemon 52 个测试全部通过，codexd 5 个测试全部通过
166
167### 执行过程中遇到的问题
168
169- 新增的 `/v1/executions` 路径命中了已有测试中 `/\/v1\/exec/u` 正则断言（原意是排除 host-ops 的 `/v1/exec`），修正为 `/\/v1\/exec"/u` 精确匹配。
170
171### 剩余风险
172
173- 无
174