# 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 已支持