Skip to content

Commit e71f100

Browse files
CarGuoCarGuo
committed
docs: API 差集 x Fixture 契约表落地（roadmap 3.5 + AGENTS.md 扩展）
新增 roadmap 3.5 节：把 GSY 6 大模块 + 跨模块共 30+ 项 API 待办功能预先绑定 测试 fixture，每一行标注锚点来源（主仓 / CarGuo 其他仓 / CarSmallGuo / 外部妥协项）， 避免 Discussions 那种做完才发现没数据的返工。附 2026-07-06 用 CarSmallGuo 的 gho_ token 实测的 8 个 API 探针快照（milestones/assignees/PR 938 line comments/gists/notifications/pinned/rate_limit），确认哪些主仓有数据、哪些必须 用外部仓，rate limit 消耗零压力 core 4997/5000。 AGENTS.md fixture 段落从单条 PR 938 扩展为「按功能分类的 fixture 表」24 行， 挑活前一眼看清是否能上真机；探针复核方式写清可每半年重跑。 约束继承既有清单：禁止造数据；只用真实数据；外部妥协项必须在 PR 描述里显式 标注理由。roadmap 3.3 中一处 '看 3.4 那个边界' 澄清为 '看第 4 节那个边界'。
1 parent bf557aa commit e71f100

2 files changed

Lines changed: 148 additions & 1 deletion

File tree

‎AGENTS.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,4 +181,40 @@
181181
- 期望截图证据：`/tmp/gsy_smoke_07_issue_detail_scrolled.png` 与随后一屏能同时看到"Copilot 提交了评审意见"这一行**和其下方灰底 body 卡片**
182182
- 后续若需要 approved/changes_requested body 场景，请在 `CarGuo` 名下的其它 PR 里挑选并把 PR 号写回本段落，不要造 PR
183183

184+
### 按功能分类的 fixture 表（2026-07-06 扩展）
185+
186+
上面 fixture PR 只覆盖 PR timeline 一个场景。为了让**开新功能前先看有没有可用测试数据**（避免走到装机验证才发现 fixture 空——Discussions 就吃过这个亏），把 GSY 各功能域可用的真实数据源固化如下。变更本表需附带该行 API 探针的实测结果。
187+
188+
**探针复核方式**：所有 `✅` 项都用 CarSmallGuo 的 gho\_ token 在 `2026-07-06` 实测过；每半年可用 [docs/00-overview/roadmap.md §3.5 探针结果快照](file:///d:/workspace/project/gsy_github_app_flutter/docs/00-overview/roadmap.md) 那批命令重跑一次防止过时。
189+
190+
**Fixture 优先级**：主仓 [CarGuo/gsy_github_app_flutter](https://github.com/CarGuo/gsy_github_app_flutter) > CarGuo 其他仓库 > CarSmallGuo 数据 > 外部真实仓库（`flutter/flutter` / `defunkt` 等，**必须标注为"外部妥协项"**）。**禁止造数据**同 §允许 / 禁止的写操作清单。
191+
192+
| 功能域 | 首选 fixture | 备注 |
193+
|---|---|---|
194+
| PR timeline 词典化事件 | 主仓 `#938` | 见上文，已固化 |
195+
| PR review thread（line-level comment） | 主仓 `#938`（2 条：`android/app/build.gradle` L41 / L84 by Copilot） | 探针实测 |
196+
| Issue assignee 挂件 | 主仓 `#938`（assignees=`CarGuo,Copilot`） | 主仓 issue 只有 #938 有 assignee，其余是 (none) |
197+
| Issue 长 timeline / 分页 | 主仓 [`#13`](https://github.com/CarGuo/gsy_github_app_flutter/issues/13) | README 明示"所有运行问题请点这里" |
198+
| Issue comment reactions | 主仓 [`#643`](https://github.com/CarGuo/gsy_github_app_flutter/issues/643) | README 里的"登录失败"高流量 issue |
199+
| Release 详情 / reactions | 主仓 `releases`（`8.0.0` 已在真机日志出现） | 本轮真机 `versionName 8.0.0` |
200+
| Compare 视图 | 主仓 `423c762...bf557aa`（本轮实际 commit） | |
201+
| Contributors / Stargazers / Watchers | 主仓（★15461） | |
202+
| Repo Language 分布 / Community Health | 主仓（Dart+Java+ObjC+Kotlin，含 LICENSE / README） | |
203+
| Repo Branches 切换 | 主仓多分支 | |
204+
| Repo Fork 网络事件流 | 主仓 `/networks/CarGuo/gsy_github_app_flutter/events` | |
205+
| Repo Milestones | ⚠️ **主仓无**（探针 count=0）→ 外部妥协项 `flutter/flutter` | |
206+
| Repo Topics chip | ⚠️ 需重跑探针 → 若空退到 `flutter/flutter` | |
207+
| User Pinned Repositories | CarGuo（GSYVideoPlayer / gsy\_github\_app\_flutter / GSYGithubAppCompose / GSYGithubAPP / GSYGithubAppKotlin / gsy\_flutter\_book） | 探针实测 6 个 pinned |
208+
| User 贡献日历 | CarGuo（活跃开发者 calendar 稠密） | |
209+
| User Following/Followers 交集 | CarGuo × CarSmallGuo | 天然双账号 |
210+
| User 公共 Gists | ⚠️ **CarGuo 无**（探针 count=0）→ 外部妥协项 `defunkt`（3 条非空） | |
211+
| Org 详情页 / Org 事件流 | 外部妥协项 `flutter` / `dart-lang`（CarGuo 是个人账号，非组织） | |
212+
| Notifications 仓库级筛选 | 主仓（CarSmallGuo 30 条 subscribed 都指向主仓） | |
213+
| Notifications reason chip | ⚠️ CarSmallGuo 当前 reason 单一（`subscribed x 28 / manual x 2`）→ 需 mention / review\_requested 场景时另找 | |
214+
| Search Labels | 主仓 `repository_id=142308181`（本轮真机日志已确认） | |
215+
| Search Commits / Topics | 全站搜索无需锁 fixture | 主仓也在结果集 |
216+
| Rate Limit 诊断 | 当前 token 自查（无需 fixture） | 本轮实测 core 4997/5000 |
217+
218+
219+
184220

‎docs/00-overview/roadmap.md‎

Lines changed: 112 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -261,10 +261,121 @@ GitHub Actions 已在 build job 里加 `flutter test` 一步（`Run unit / widge
261261
### 3.3 低优先 / 边界待定
262262

263263
- **Gist 阅读**：完全没做。
264-
- **GitHub Actions runs 状态**：作者行为重叠多，看 3.4 那个边界定了再决定。
264+
- **GitHub Actions runs 状态**：作者行为重叠多，看第 4 节那个边界定了再决定。
265265
- **Projects V2 阅读**：~~完全没做~~ **2026-07-06 拍板归入禁止清单**（阅读也搁置），不再列入待做，见 [AGENTS.md §允许 / 禁止的写操作清单](file:///d:/workspace/project/gsy_github_app_flutter/AGENTS.md#L141-L169)。
266266
- **Copilot Chat 上下文**：GSY 定位不做 AI，一般跳过。
267267

268+
### 3.5 API 差集 × Fixture 契约表（2026-07-06 落地）
269+
270+
**这一小节的存在意义**：前面 §3.1-3.3 罗列了功能待办，但**没有把"用哪个仓库验证"钉死**。
271+
Discussions 阶段就吃过这个亏——事件识别做完才发现 GSY 关注账号里根本没 discussion 事件，
272+
真机路径覆盖不了，只能补单测。这一节把每个待办功能**预先绑定测试 fixture**，
273+
挑活前一眼看清是否能上真机；`⚠️`标记的项目要在正式开工前**先跑 API 探针**确认。
274+
275+
**Fixture 优先级规则**（与 [AGENTS.md 允许 / 禁止的写操作清单](file:///d:/workspace/project/gsy_github_app_flutter/AGENTS.md) 一致：**禁止造数据**，全部用真实数据）：
276+
277+
1. 主仓 [CarGuo/gsy_github_app_flutter](https://github.com/CarGuo/gsy_github_app_flutter)（首选）
278+
2. CarGuo 名下其他仓库：`GSYVideoPlayer / GSYGithubAppKotlin / GSYGithubAppCompose / GSYGithubAPP / gsy_flutter_book`
279+
3. 当前 adb 登录账号 `CarSmallGuo` 的通知 / 关注数据（首选，因为不用切账号）
280+
4. 外部真实仓库（`flutter/flutter` / `dart-lang` / `defunkt` 等）—— 仅在前三档无数据时启用，**必须显式标注为"外部妥协项"**
281+
282+
---
283+
284+
**探针结果快照**（2026-07-06 用 CarSmallGuo 的 gho\_ token 实测，`GET /rate_limit` 显示 core 4997/5000，探针零压力）：
285+
286+
| 探针 | 结论 |
287+
|---|---|
288+
| `GET /repos/CarGuo/gsy_github_app_flutter/milestones?state=all` | count=0 → 主仓无 milestone，需外部 fixture |
289+
| `GET /repos/CarGuo/gsy_github_app_flutter/issues?state=all&per_page=10` | #938 有 `assignees=[CarGuo,Copilot]`；其他 9 条都是 `(none)` → assignee 挂件用 #938 即可 |
290+
| `GET /repos/CarGuo/gsy_github_app_flutter/pulls/938/comments` | 2 条 line-level review comment（Copilot 对 `android/app/build.gradle` L41 / L84），完美 review thread fixture |
291+
| `GET /users/CarGuo/gists` | count=0 → CarGuo 无公开 gists，fallback 到 `defunkt`（已实测 3 条非空） |
292+
| `GET /notifications?all=true&per_page=30` | 30 条通知 reason 分布 `subscribed x 28 / manual x 2` → reason chip filter 需要更丰富 reason，实际验证时可去用 `mention` / `review_requested` 相关的仓库 |
293+
| `POST /graphql user.pinnedItems(first:6)` | CarGuo pinned 6 个仓库：`GSYVideoPlayer ★21458 / gsy_github_app_flutter ★15461 / GSYGithubAppCompose ★125 / GSYGithubAPP ★2485 / GSYGithubAppKotlin ★1586 / gsy_flutter_book ★4618` → 完美 pinned fixture |
294+
295+
---
296+
297+
#### 模块 1：动态 / 事件
298+
299+
| # | 待办功能 | fixture 锚点 | 备注 |
300+
|---|---|---|---|
301+
| 1 | 公共事件流 `/events` | 无需 fixture | 全站流，任何账号登录后即有数据 |
302+
| 2 | 组织事件 `/orgs/:org/events` | `flutter` / `dart-lang` 组织（外部妥协项） | CarGuo 是个人账号，无组织 fixture |
303+
| 3 | Repo 网络事件流 `/networks/:o/:r/events` | ✅ 主仓（fork 数够） | [Address.getReposEvent](file:///d:/workspace/project/gsy_github_app_flutter/lib/common/net/address.dart#L86-L88) URL 已在但无 UI 消费 |
304+
| 4 | 事件类型 filter | ✅ 主仓首页混合事件流（本轮真机截图 [smoke_ci344_01_home.png](file:///d:/workspace/project/gsy_github_app_flutter/tool/dbg/smoke_ci344_01_home.png) 已证 6 张卡多种事件混排） | 纯本地过滤 |
305+
306+
#### 模块 2：仓库详情
307+
308+
| # | 待办功能 | fixture 锚点 | 备注 |
309+
|---|---|---|---|
310+
| 1 | Release 详情页 + reactions | ✅ 主仓 releases（`8.0.0` 已在真机日志出现） | [release_page.dart](file:///d:/workspace/project/gsy_github_app_flutter/lib/page/release/release_page.dart) 是列表未做详情 |
311+
| 2 | Topics chip | ⚠️ 需先跑 `GET /repos/CarGuo/gsy_github_app_flutter/topics` 确认非空 | 若空，退到 `flutter/flutter`（topics 稠密） |
312+
| 3 | Labels chip | ✅ 主仓 [Address.getReposLabels](file:///d:/workspace/project/gsy_github_app_flutter/lib/common/net/address.dart#L138-L140) URL 已在 | 主仓 labels 页非空 |
313+
| 4 | Milestone | **主仓无 milestone**（探针实测 count=0） → 用 `flutter/flutter`（外部妥协项） | 已实测确认 |
314+
| 5 | Branches 切换 | ✅ 主仓多分支 | [Address.getbranches](file:///d:/workspace/project/gsy_github_app_flutter/lib/common/net/address.dart#L337-L339) URL 已在 |
315+
| 6 | Contributors / Stargazers / Watchers 列表页 | ✅ 主仓 fixture ★15461（探针实测） | UI 只有数字未做列表 |
316+
| 7 | Compare 视图 | ✅ 主仓 `423c762...bf557aa`（本轮实际存在的两个 commit） | [Address.getReposCompare](file:///d:/workspace/project/gsy_github_app_flutter/lib/common/net/address.dart#L116-L118) URL 已在 |
317+
| 8 | Language 分布条 | ✅ 主仓多语言（Dart + Java + ObjC + Kotlin） | `GET /repos/:o/:r/languages` |
318+
| 9 | Community Health | ✅ 主仓 `GET /repos/CarGuo/gsy_github_app_flutter/community/profile` | 主仓有 LICENSE / README 完整 |
319+
320+
#### 模块 3：Issue / PR
321+
322+
| # | 待办功能 | fixture 锚点 | 备注 |
323+
|---|---|---|---|
324+
| 1 | Assignee / Milestone / Label 挂件 | ✅ Assignee 用主仓 [#938](https://github.com/CarGuo/gsy_github_app_flutter/pull/938)（实测 assignees=`CarGuo,Copilot`）；Milestone 用 `flutter/flutter`；Label 用主仓 | 单一 issue detail 页混合 fixture |
325+
| 2 | PR 状态 badge (draft / mergeable / conflicts) | ✅ 主仓 #938 | AGENTS.md 已固化 |
326+
| 3 | PR reviews 完整列表 | ✅ 主仓 #938 | AGENTS.md 已固化 |
327+
| 4 | PR commits | ✅ 主仓 #938 | AGENTS.md 已固化 |
328+
| 5 | PR review thread 阶段 A/2 | ✅ **主仓 #938**（实测 2 条 line-level comment：Copilot 对 `android/app/build.gradle` L41 / L84）| 完美 review thread fixture |
329+
| 6 | Issue comment reactions | ✅ 主仓 [issue #643](https://github.com/CarGuo/gsy_github_app_flutter/issues/643)（README 里"登录失败"高流量 issue） | [Address.getIssueCommentReactions](file:///d:/workspace/project/gsy_github_app_flutter/lib/common/net/address.dart#L243-L245) URL 已在 |
330+
| 7 | Timeline 分页 | ✅ 主仓 [issue #13](https://github.com/CarGuo/gsy_github_app_flutter/issues/13)（README 明示"所有运行问题请点这里"，历史巨长 issue） | 完美长 timeline fixture |
331+
332+
#### 模块 4：搜索
333+
334+
| # | 待办功能 | fixture 锚点 | 备注 |
335+
|---|---|---|---|
336+
| 1 | Commits 搜索 | ✅ 搜 `repo:CarGuo/gsy_github_app_flutter Copilot` 命中 | 主仓自搜 |
337+
| 2 | Topics 搜索 | ✅ 搜 `flutter` / `github-client` | 全站，主仓也在结果集 |
338+
| 3 | Labels 搜索 | ✅ `GET /search/labels?repository_id=142308181&q=bug`（142308181 是主仓 id，本轮真机日志 `repo:{id:142308181}` 已确认） | 主仓 id 已固定 |
339+
| 4 | 搜索历史 UI 增强 | 无需 fixture | 本地 [search_history_repository](file:///d:/workspace/project/gsy_github_app_flutter/lib/common/repositories/search_history_repository.dart) 数据 |
340+
| 5 | 高级筛选 chip | 无需 fixture | 纯 UI |
341+
342+
#### 模块 5：用户 / 我的
343+
344+
| # | 待办功能 | fixture 锚点 | 备注 |
345+
|---|---|---|---|
346+
| 1 | 用户公共 Gists | **CarGuo 无 gists**（实测 count=0）→ 用 `defunkt`（外部妥协项，探针实测 3 条非空） | 已实测确认 |
347+
| 2 | 贡献日历 GraphQL 版 | ✅ CarGuo（活跃开发者，calendar 稠密） | 主用户已够 |
348+
| 3 | Pinned Repositories | ✅ **CarGuo 6 个 pinned**：GSYVideoPlayer / gsy_github_app_flutter / GSYGithubAppCompose / GSYGithubAPP / GSYGithubAppKotlin / gsy_flutter_book（探针实测） | 完美 fixture |
349+
| 4 | Following/Followers 交集 | ✅ CarGuo × CarSmallGuo（后者是 adb 当前登录账号，天然双账号） | 双账号 fixture |
350+
| 5 | 组织详情页 | `flutter` / `dart-lang`（外部妥协项） | CarGuo 不是组织 |
351+
352+
#### 模块 6：通知
353+
354+
| # | 待办功能 | fixture 锚点 | 备注 |
355+
|---|---|---|---|
356+
| 1 | 仓库级通知筛选 | 依赖 CarSmallGuo 订阅——**已实测 30 条通知都是主仓 subscribed** → 主仓即可 | 单仓测试足够 |
357+
| 2 | reason chip filter | **CarSmallGuo 当前 reason 单一**（subscribed x 28 / manual x 2）→ 实际验证时通过手动 mention 其他账号或订阅 `flutter/flutter` 扩容 reason 分布 | 已实测确认 |
358+
| 3 | since / before 窗口 | 无需 fixture | 参数扩展 |
359+
| 4 | 未读 badge | 无需 fixture | 现有数据算 |
360+
361+
#### 跨模块补充
362+
363+
| # | 待办功能 | fixture 锚点 | 备注 |
364+
|---|---|---|---|
365+
| 1 | Reactions 铺满（release / commit comment 等） | ✅ 主仓 issue #643 + release `8.0.0` | 主仓够用 |
366+
| 2 | Markdown / Emoji 渲染 | 无需 fixture | POST 任意 md |
367+
| 3 | License 列表 | 无需 fixture | 全站 API |
368+
| 4 | Rate Limit 诊断入口 | 无需 fixture（当前 token 自查，本轮探针实测 core 4997/5000） | 天然自证 |
369+
| 5 | Stars 增长曲线 | ✅ 主仓（README 已用 star-history 外链 badge，数据密度够画） | 主仓够用 |
370+
371+
---
372+
373+
#### 挑活契约（本节的强约束）
374+
375+
- 从本节挑一个功能开工前，**先看该行 fixture 锚点**：`⚠️` 项必须先跑一次 API 探针把它转成 `✅` 或"外部妥协项"，再动代码
376+
- 挑外部妥协项的功能时，**必须在 PR 描述里注明"本功能验证使用外部仓库 X，原因 Y"**，不能默认使用
377+
- 新增待办条目时必须补上 fixture 锚点栏；无 fixture 锚点的条目不合并入本表
378+
268379
---
269380

270381
## 四、待定义边界（做不做要先讨论）

0 commit comments

Comments
 (0)