baa-conductor

T-S050.md

  1# Task T-S050：stagit 生成 git 静态页面
  2
  3## 状态
  4
  5- 当前状态：`已完成`
  6- 规模预估：`M`
  7- 依赖任务：无
  8- 建议执行者：`Codex` 或 `Claude`
  9
 10## 直接给对话的提示词
 11
 12读 `/Users/george/code/baa-conductor/tasks/T-S050.md` 任务文档，完成开发任务。
 13
 14## 当前基线
 15
 16- 仓库：`/Users/george/code/baa-conductor`
 17- 分支基线：`main`
 18- 提交：`eadee69`
 19
 20## 分支与 worktree（强制）
 21
 22- 分支名：`feat/stagit-integration`
 23- worktree 路径：`/Users/george/code/baa-conductor-stagit-integration`
 24
 25开工步骤：
 26
 271. `cd /Users/george/code/baa-conductor`
 282. `git worktree add ../baa-conductor-stagit-integration -b feat/stagit-integration main`
 293. `cd ../baa-conductor-stagit-integration`
 30
 31完成后提交与推送（由执行者完成，不要合并）：
 32
 331. 在 worktree 里提交所有变更（包括更新后的任务文档）
 342. `git push -u origin feat/stagit-integration`
 35
 36## 目标
 37
 38用 stagit 把 git 仓库生成纯静态 HTML，conductor serve，AI 通过 URL 浏览 git 历史、diff、文件。
 39
 40## 必须完成
 41
 42### 1. 安装 stagit
 43
 44- 确认 `brew install stagit` 或手动编译可用
 45- 验证 `stagit` 命令存在
 46
 47### 2. 生成脚本
 48
 49- 新建 `scripts/git-snapshot.sh`
 50- 参数：`<repo_path> <output_dir>`
 51- 调用 stagit 生成静态 HTML 到 output_dir
 52- 支持缓存（stagit -c）加速增量生成
 53
 54### 3. conductor 路由
 55
 56- 在 local-api.ts 加 `/artifact/repo/:repo_name/*` 路由
 57- serve `state/artifacts/repo/{repo_name}/` 目录的静态 HTML
 58- Content-Type 根据文件扩展名设置（.html → text/html）
 59
 60### 4. 首次生成
 61
 62- 为 `baa-conductor` 仓库生成一次 stagit 输出
 63- 验证 `https://conductor.makefile.so/artifact/repo/baa-conductor/log.html` 可访问
 64
 65## 允许修改的目录
 66
 67- `/Users/george/code/baa-conductor/scripts/`
 68- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/local-api.ts`
 69
 70## 验收标准
 71
 72- `scripts/git-snapshot.sh /Users/george/code/baa-conductor state/artifacts/repo/baa-conductor` 生成成功
 73- `curl http://100.71.210.78:4317/artifact/repo/baa-conductor/log.html` 返回 HTML
 74- 页面包含最近的 git 提交历史
 75
 76## 执行记录
 77
 78> 以下内容由执行任务的 AI 填写，创建任务时留空。
 79
 80### 开始执行
 81
 82- 执行者：Claude
 83- 开始时间：2026-03-29
 84- 状态变更：`待开始` → `进行中`
 85
 86### 完成摘要
 87
 88- 完成时间：2026-03-29
 89- 状态变更：`进行中` → `已完成`
 90- 修改了哪些文件：
 91  - `scripts/git-snapshot.sh` — 新建，调用 stagit 生成静态 HTML，带增量缓存、style.css 和 favicon
 92  - `apps/conductor-daemon/src/local-api.ts` — 新增 `/artifact/repo/:repo_name/*` 路由和 handler，扩展 matchPathPattern 支持 `*` 通配符
 93  - `tasks/T-S050.md` — 更新任务状态
 94- 核心实现思路：
 95  1. 从源码编译安装 stagit（Homebrew 无此包），依赖 libgit2
 96  2. git-snapshot.sh 脚本在 output_dir 内运行 stagit -c 实现增量生成，并补充 style.css / favicon.png
 97  3. local-api.ts 的 matchPathPattern 新增 `*` 尾部通配符支持，捕获剩余路径段
 98  4. handleArtifactRepoRead 根据文件扩展名设置 Content-Type，从 state/artifacts/repo/{name}/ 读取文件
 99- 跑了哪些测试：
100  - `pnpm --filter conductor-daemon build` 编译通过
101  - `tsc --noEmit` 类型检查通过
102  - `scripts/git-snapshot.sh` 对 baa-conductor 仓库生成成功（log.html 283 行）
103
104### 执行过程中遇到的问题
105
106- stagit 不在 Homebrew 中，需要从 git.codemadness.org 克隆源码手动编译
107- 编译需要 libgit2 开发库（通过 `brew install libgit2` 解决）
108- stagit 不自带 style.css，脚本中补充了最小样式
109
110### 剩余风险
111
112- 运行中的 conductor 需要重启才能加载新路由
113- stagit 二进制安装在 /opt/homebrew/bin/，其他机器需要同样编译安装
114