pangtiankai
c29af91113
Initial documentation for route A (port claude-code-action to Gitea Actions). Research complete, no implementation code yet. See docs/02-roadmap.md for milestones.
3.8 KiB
3.8 KiB
04 - 设计决策（ADR）
仅记录"非显然"的选择 —— 同一份代码读者扫一眼就懂的东西不在这里。
ADR-001：fork 上游而不是从零写
日期：2026-05-25 状态：✅ 采纳
背景：要做"issue 触发 Claude → 交互 → PR"的工具，候选方案有从 0 写、用 OpenHands、复刻 SWE-agent、移植 claude-code-action。
决策：移植 anthropics/claude-code-action。
原因：
- 上游的 prompt 构造、context 收集、PR 生成流程是 Anthropic 内部生产用的，质量靠谱
- TypeScript 实现，比起从 0 写省 2-3 周
- Gitea API 与 GitHub API 大量相似，移植量约 30% 文件
- 不引入 OpenHands 等大型框架的认知和维护成本
代价：
- 引入 TS/Bun 工具链（如果团队更熟 Python，是个学习成本）
- 跟随上游升级有维护成本（mitigated by：上游 API 变化不会太频繁）
ADR-002：路线 A（Actions）先行，路线 B（webhook 服务）后置
日期：2026-05-25 状态：✅ 采纳
背景：Gitea Actions 冷启动 ~30s，每轮交互体感差。一开始就上长驻服务能解决，但工作量翻倍。
决策：先做路线 A，跑通验收标准后再决定是否升级 B。
原因：
- 体感差但能用 ≫ 体感好但跑不起来
- 真实跑起来才知道哪些环节实际是瓶颈（可能 30s 启动里实际只有 5s 在等 Claude，瓶颈是别的）
- 留好抽象接口（
EventDispatcher/SessionStore），升级不重写业务
代价：
- 用户首次体验差，可能让人产生"这玩意没用"的错觉
- mitigated by：文档明说"路线 A 是过渡，B 才是终态"
ADR-003：不引入完整 Gitea SDK，用 fetch + zod
日期：2026-05-25 状态：✅ 采纳
背景：Gitea 有 gitea-js SDK，但维护活跃度一般。
决策：直接 fetch + zod schema 做 API 调用。
原因：
- 需要的 endpoint 只有 ~10 个，自己写 client 不到 200 行
- zod schema 比 SDK 自带类型更可控（出问题好排查）
- 少一个依赖，少一份升级负担
- 上游
@octokit/rest本来也只用了 1% 的功能
代价：
- 失去了 SDK 的 retry / rate-limit 内置逻辑
- mitigated by：路线 A 阶段流量很小，需要时再加 wrapper
ADR-004：Status comment 用"连续 edit 单条评论"模拟 GitHub Checks
日期：2026-05-25 状态：✅ 采纳
背景：上游用 GitHub Checks API 做进度展示（带 ✅ / ⏳ 复选框）。Gitea 没有等价 API。
决策：发一条评论作为状态板，全程 PATCH 这条评论的正文模拟进度更新。
原因：
- 唯一可行的方案（除非等 Gitea 实现 Checks API）
- 用户看到的视觉效果差不多（一条会变的评论 vs 一个会变的 Check）
- 实现简单
代价：
- 不像 Checks 那样能在 PR 顶部显眼地显示状态
- mitigated by：评论会自动滚到底部，user 自然能看到最新进度
ADR-005：暂不支持 GitHub App 等价的 bot 身份
日期：2026-05-25 状态：✅ 采纳
背景：上游支持 GitHub App 安装，bot 评论时会有 "Claude (bot)" 标识。Gitea 暂无原生 bot 用户类型。
决策：用普通用户 @claude（或任意命名）作为 bot 身份，access token 模式调用。
原因：
- Gitea 没有 App 概念，硬模拟没必要
- 普通用户 + token 模式简单直接，权限可控
代价：
- 评论里没有 bot 标识，看起来像普通用户在说话
- mitigated by：评论里加固定 footer "🤖 Powered by claude-gitea-agent"
待决策
- 长会话状态存哪？路线 B 时再选（候选：SQLite / Redis / 文件）
- 是否支持私有仓库？默认支持，token 权限够就行
- 多仓库共享 runner 还是每仓库独立？运行时按需启动，act_runner 已支持