Skip to content

Commit 908621e

Browse files
CarGuoCarGuo
committed
docs: Add AI collaboration ecosystem and architecture guides
- Initialize `docs/` directory with project map, architecture layering, and state management matrix. - Add `AGENTS.md` and context-specific agent guides in `lib/` directories. - Implement AI task playbooks, feature playbooks, and review harness in `docs/05-ai/`. - Add ADRs for state management policies in `docs/06-decisions/`. - `SearchPage`: Refactor filter reset logic to `SearchBloc` and `GSYSearchDrawer` to ensure proper cleanup on dispose. - `README.md`: Update with entry points for AI collaboration.
1 parent 32ff0e7 commit 908621e

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

51 files changed

+2751
-16
lines changed

‎AGENTS.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# GSY GitHub App Flutter 协作说明
2+
3+
这是一个 Flutter GitHub 客户端，同时也是带有教学展示性质的示例工程。
4+
不要假设整个仓库是单一架构风格。多种状态管理方案并存是当前设计现实，不是偶然脏代码。
5+
6+
## 进入仓库后先读
7+
8+
在进行非微小改动前，先读这些文件：
9+
10+
1. `README.md`
11+
2. `docs/README.md`
12+
3. `docs/00-overview/project-map.md`
13+
4. `docs/01-architecture/app-layering.md`
14+
5. `docs/01-architecture/state-management-matrix.md`
15+
16+
## 工作规则
17+
18+
- 改动尽量限制在当前功能域，不要顺手做跨模块重构。
19+
- 非任务明确要求时，不要迁移状态管理框架。
20+
- 优先遵循目标模块现有模式，而不是引入新的全局规范。
21+
- `*.g.dart`、多语言生成文件、env 生成文件都视为生成产物；优先重新生成，不要手改。
22+
- 不要提交密钥。`lib/common/config/ignoreConfig.dart` 属于本地或 CI 环境材料。
23+
24+
## 高风险目录
25+
26+
- `lib/app.dart`：应用根装配、导航、全局报错、Redux 和 Riverpod 混合接线
27+
- `lib/common/net/`：共享网络栈、拦截器、GraphQL/REST 入口
28+
- `lib/common/repositories/`：功能数据访问边界
29+
- `lib/env/`：构建期环境配置和生成文件
30+
- `lib/common/localization/`：ARB 与多语言生成输出
31+
32+
## 建议修改策略
33+
34+
- 纯 UI 任务：优先只改页面或局部 widget，不碰全局状态
35+
- API 任务：同时检查 `common/net` 与对应 `common/repositories`
36+
- 状态任务：沿用该模块当前已有状态方案，除非任务明确要求迁移
37+
- 配置/构建任务：同步更新 `docs/03-runbooks/` 中的操作说明
38+
39+
## Review 规则
40+
41+
- 中等以上改动默认使用独立 reviewer 上下文
42+
- 每次非微小代码改动后，默认拉起新的 reviewer subagent 或新的干净上下文审查刚刚的修改
43+
- author 在通过一轮新的 reviewer subagent 审查前，不应直接宣告代码任务完成
44+
- reviewer 不应复用 author 的完整上下文历史
45+
- 先看 `docs/05-ai/review-harness.md`
46+
- reviewer 提示模板见 `docs/05-ai/prompts/reviewer-system.md`
47+
- `tool/ai/build_review_bundle.ps1` 只是可选辅助，不是主流程
48+
49+
## 本地最小验证
50+
51+
按改动范围选择最小验证集合：
52+
53+
- `flutter pub get`
54+
- `dart run build_runner build --delete-conflicting-outputs`
55+
- `flutter gen-l10n`
56+
- `flutter analyze`
57+
- `flutter build apk --release --target-platform=android-arm64 --no-shrink`
58+
59+
说明：
60+
61+
- 改模型、env、注解生成代码时跑 `build_runner`
62+
- 改 ARB 或本地化输入时跑 `flutter gen-l10n`
63+
- 改 Android 构建、依赖或运行时关键路径时跑 APK 构建
64+
65+
## 当前已知约束
66+
67+
- 仓库目前没有提交进来的 `test/` 测试目录
68+
- CI 使用 GitHub Actions，当前偏重构建成功
69+
- 项目同时使用 Redux、Riverpod、Provider、Signals
70+
- OAuth 登录相关流程依赖本地 `ignoreConfig.dart`

‎README.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,50 @@
2222
* ### 简单 Flutter 独立学习项目 ( https://github.com/CarGuo/gsy_flutter_demo )
2323

2424

25+
## AI 协作与贡献入口
26+
27+
如果你希望用 AI 或更工程化的方式参与这个仓库，建议不要只看本 README，先看下面这些文档入口：
28+
29+
- 总导航：`docs/CONTRIBUTING_AI.md`
30+
- 文档索引：`docs/README.md`
31+
- 项目地图：`docs/00-overview/project-map.md`
32+
- 分层边界：`docs/01-architecture/app-layering.md`
33+
- 状态管理边界：`docs/01-architecture/state-management-matrix.md`
34+
- 手工回归矩阵：`docs/04-quality/smoke-matrix.md`
35+
36+
按任务类型进入：
37+
38+
- 修 Bug：`docs/05-ai/task-playbooks/fix-bug.md`
39+
- 新增页面：`docs/05-ai/task-playbooks/add-page.md`
40+
- 新增接口：`docs/05-ai/task-playbooks/add-api.md`
41+
- 状态整理：`docs/05-ai/task-playbooks/refactor-state.md`
42+
43+
按功能域进入：
44+
45+
- 仓库详情：`docs/05-ai/feature-playbooks/repos-change.md`
46+
- 趋势页：`docs/05-ai/feature-playbooks/trend-change.md`
47+
- 通知页：`docs/05-ai/feature-playbooks/notify-change.md`
48+
- Issue：`docs/05-ai/feature-playbooks/issue-change.md`
49+
- 搜索：`docs/05-ai/feature-playbooks/search-change.md`
50+
- 用户页：`docs/05-ai/feature-playbooks/user-change.md`
51+
- 首页容器：`docs/05-ai/feature-playbooks/home-change.md`
52+
- 动态页：`docs/05-ai/feature-playbooks/dynamic-change.md`
53+
- Release：`docs/05-ai/feature-playbooks/release-change.md`
54+
- Push 提交详情：`docs/05-ai/feature-playbooks/push-change.md`
55+
- 调试页：`docs/05-ai/feature-playbooks/debug-change.md`
56+
57+
长期规则：
58+
59+
- 状态管理收敛策略：`docs/06-decisions/ADR-0001-状态管理收敛策略.md`
60+
- 新增功能默认状态方案：`docs/06-decisions/ADR-0002-新增功能默认状态方案.md`
61+
62+
Review harness：
63+
64+
- author / reviewer 分离：`docs/05-ai/review-harness.md`
65+
- reviewer prompt：`docs/05-ai/prompts/reviewer-system.md`
66+
- review bundle 脚本（可选辅助）：`tool/ai/build_review_bundle.ps1`
67+
68+
2569

2670
## 相关文章
2771

‎docs/00-overview/project-map.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# 项目地图
2+
3+
## 项目定位
4+
5+
`gsy_github_app_flutter` 是一个跨平台 GitHub 客户端。
6+
它既是完整功能应用，也是偏教学展示风格的工程，因此仓库中会刻意保留多种实现方式，而不是追求所有模块都完全统一。
7+
8+
## 运行主链路
9+
10+
高层数据链路可以概括为：
11+
12+
`UI/Page -> 状态层 -> Repository -> 网络/数据库 -> Model -> UI 刷新`
13+
14+
应用入口和全局装配主要集中在：
15+
16+
- `lib/main.dart`
17+
- `lib/app.dart`
18+
19+
这些位置负责：
20+
21+
- 应用启动
22+
- 环境配置装配
23+
- 根导航
24+
- 多语言和主题
25+
- 全局错误处理
26+
- 全局状态容器接线
27+
28+
## 目录地图
29+
30+
- `lib/main.dart`：应用启动、Zone 异常兜底、环境包装
31+
- `lib/app.dart`：`MaterialApp`、路由、Redux 根 store、Riverpod 容器、HTTP 错误监听
32+
- `lib/common/config/`：应用配置和 OAuth 本地配置
33+
- `lib/common/net/`：API 客户端、拦截器、GraphQL、数据转换
34+
- `lib/common/repositories/`：功能层数据访问边界
35+
- `lib/common/localization/`：本地化扩展、ARB、生成代码
36+
- `lib/db/`：本地数据库 provider 和 SQL 辅助
37+
- `lib/env/`：环境配置及其生成文件
38+
- `lib/model/`：数据模型和序列化生成文件
39+
- `lib/page/`：页面功能目录，如 `repos`、`issue`、`trend`、`notify`、`user`
40+
- `lib/provider/`：Provider/Riverpod 相关共享状态
41+
- `lib/redux/`：Redux state、reducer、middleware
42+
- `static/`：静态资源
43+
- `.github/workflows/`：GitHub Actions 配置
44+
45+
## 对协作者很重要的现实
46+
47+
- 项目里同时存在多种状态管理方案
48+
- 同时使用 REST 和 GraphQL
49+
- 生成代码是日常开发流程的一部分
50+
- 根 README 主要承担项目介绍和运行说明，不足以替代工程地图
51+
52+
## AI 最容易犯错的地方
53+
54+
- 误以为整个项目已经统一到某一种状态管理
55+
- 为了解决页面局部问题去改 `lib/app.dart`
56+
- 直接手改生成文件而不是回到源输入
57+
- 忘记 `ignoreConfig.dart` 的本地依赖
58+
59+
在修改共享链路前，先看架构文档和对应模块文档。

‎docs/01-architecture/app-layering.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# 应用分层
2+
3+
## 目的
4+
5+
这个仓库不是严格单一架构实现，而是采用“整体分层明确、局部实现多样”的方式。
6+
协作者不需要强行统一写法，但需要尊重已有边界，避免把局部需求扩散成全局耦合。
7+
8+
## 1. 入口与应用壳层
9+
10+
- `lib/main.dart`
11+
- `lib/app.dart`
12+
- `lib/env/`
13+
14+
职责：
15+
16+
- 应用启动
17+
- 环境配置装配
18+
- 根导航与多语言/主题
19+
- 全局异常处理
20+
- 全局状态容器接线
21+
22+
原则：
23+
24+
- 不要把功能业务逻辑直接塞进这里
25+
- 除非是全局行为问题，否则尽量不要改 `lib/app.dart`
26+
27+
## 2. UI 层
28+
29+
- `lib/page/`
30+
- 各功能目录下的局部 widget
31+
- `lib/common/` 下复用 UI 组件
32+
33+
职责：
34+
35+
- 页面渲染
36+
- 用户交互响应
37+
- 将数据请求和状态变化委托给状态层或 repository
38+
39+
原则：
40+
41+
- 优先在功能目录内完成 UI 改动
42+
- 页面不要直接承接太多网络协议细节
43+
44+
## 3. 状态层
45+
46+
- `lib/redux/`
47+
- `lib/provider/`
48+
- `lib/app.dart` 中接入的 Riverpod 容器
49+
- 指定页面中的 Signals
50+
51+
职责：
52+
53+
- 维护视图状态
54+
- 协调异步加载
55+
- 向 UI 暴露状态变化
56+
57+
原则：
58+
59+
- 新改动优先沿用目标模块当前已有状态方案
60+
- 不要在无关任务里做状态管理迁移
61+
62+
## 4. Repository 层
63+
64+
- `lib/common/repositories/`
65+
66+
职责：
67+
68+
- 将功能请求翻译成网络或数据库访问
69+
- 隔离页面/状态层与具体传输实现
70+
71+
原则：
72+
73+
- 改接口时优先在 repository 边界收口
74+
- 页面不要绕过 repository 直接铺开网络细节
75+
76+
## 5. 数据与传输层
77+
78+
- `lib/common/net/`
79+
- `lib/db/`
80+
- `lib/model/`
81+
82+
职责：
83+
84+
- HTTP/GraphQL 访问
85+
- 拦截器与响应转换
86+
- 本地持久化
87+
- 序列化与模型转换
88+
89+
原则：
90+
91+
- 不要从页面直接复制网络调用逻辑
92+
- 共用行为优先收敛到共享网络层或 repository
93+
94+
## 生成代码约束
95+
96+
以下内容应视为生成产物：
97+
98+
- `lib/model/` 下的 `*.g.dart`
99+
- `lib/env/` 下生成文件
100+
- `lib/common/localization/l10n/` 下生成输出
101+
- `riverpod_annotation` 对应的 `*.g.dart`
102+
103+
原则：
104+
105+
- 优先修改源输入，再重新生成
106+
- 非必要不要直接手改生成文件
107+
108+
## 改动入口建议
109+
110+
- 页面展示问题：先看 `lib/page/<feature>/`
111+
- API/模型问题：看 `common/net`、`common/repositories`、`model`
112+
- 全局主题/语言/导航问题：看 `lib/app.dart` 和共享 provider/redux
113+
- 构建或配置问题：看 `lib/env/`、`pubspec.yaml` 和 runbook

‎docs/01-architecture/state-management-matrix.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# 状态管理矩阵
2+
3+
## 为什么要有这份文档
4+
5+
这个项目刻意保留了多种状态管理方式用于展示和演进。
6+
这对学习有价值，但也意味着协作者和 agent 很容易“按自己的偏好”误改边界。
7+
这份文档的目的是停止猜测。
8+
9+
## 当前分布
10+
11+
### Redux
12+
13+
- 主要承担应用级共享状态，例如登录态和用户信息
14+
- 根 store 在 `lib/app.dart` 中创建
15+
- reducer 和 middleware 位于 `lib/redux/`
16+
17+
### Riverpod
18+
19+
- 用于部分全局共享状态，例如灰度模式、语言、主题
20+
- 也用于部分功能模块，例如趋势页相关数据流
21+
- 根容器同样在 `lib/app.dart` 中接入
22+
23+
### Provider
24+
25+
- 仍存在于部分功能模块，尤其是较早的页面链路
26+
- 典型例子是仓库详情页的跨 tab 状态共享
27+
28+
### Signals
29+
30+
- 用于局部页面状态
31+
- 当前通知页和部分文件列表相关页面会使用
32+
33+
## 工作策略
34+
35+
- 不要再引入第五种状态管理模式
36+
- 无关任务里不要顺手把模块从一种方案迁到另一种方案
37+
- 新状态优先跟随“最近的既有模式”，而不是个人习惯
38+
- 如果一个需求同时涉及全局状态和页面局部状态，要明确边界，避免双份真相
39+
40+
## 评审时必问的问题
41+
42+
1. 这份状态是页面局部、功能局部，还是应用全局？
43+
2. 目标模块原来已经在用哪种状态方案？
44+
3. 这次改动是否真的需要碰 `lib/app.dart`？
45+
4. 会不会让 Redux、Riverpod、Provider 或 Signals 之间出现重复状态源？
46+
47+
## 后续方向
48+
49+
如果将来要收敛状态管理种类，应先在 `docs/06-decisions/` 记录决策，再开始迁移。
50+
不要让“慢慢改着改着就变了”成为默认路径。

‎docs/02-features/debug.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# 调试页功能
2+
3+
## 相关文件
4+
5+
- `lib/page/debug/debug_data_page.dart`
6+
- `lib/page/debug/debug_label.dart`
7+
- `lib/common/net/interceptors/log_interceptor.dart`
8+
- `lib/common/logger.dart`
9+
10+
## 当前实现
11+
12+
调试页用于查看开发过程中的：
13+
14+
- HTTP Response
15+
- HTTP Request
16+
- HTTP Error
17+
- Talker 错误日志
18+
19+
并支持复制链接、复制数据、弹出 JSON 查看器。
20+
21+
## 数据流
22+
23+
调试页本身不发起业务请求，而是消费全局日志和拦截器收集到的数据。
24+
25+
## 状态管理
26+
27+
- 页面本地 tab 状态
28+
- 数据由全局日志容器和拦截器静态列表提供
29+
30+
## 高风险点
31+
32+
- 这是辅助调试能力，不应影响线上业务路径
33+
- 改日志结构时要同步看调试页展示
34+
- 大量数据展示和复制逻辑集中在单页内部
35+
36+
## 修改建议
37+
38+
- 仅在需要增强调试体验时修改
39+
- 不要把正式业务依赖绑到调试页上
40+
- 改日志采集字段时，顺带检查调试页是否还能正确显示

0 commit comments

Comments
 (0)