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.
111 lines
3.8 KiB
Markdown
111 lines
3.8 KiB
Markdown
# 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 已支持
|