快速开始讲的是「把系统跑起来」。本页讲的是「把改动安全地合进来」——RakullApp 现在是一个单一大仓库（monorepo），全部源码都在这一个仓库里，只有一条主线 main。所以贡献的方式非常简单：
一个仓库、一条主线。 所有源码都在 RakullApp 里，改动只需在本仓走「分支 → PR → 合并到 main」。不再有子模块指针，也不需要自底向上逐仓合并。 合并到 main 之后，被改动的子目录会由 mirror-sync 工作流自动推送到对应的下游镜像仓库（供各微服务独立部署）。

​
仓库模型

RakullApp 曾经是三层 git 子模块，现在已扁平化成单仓库：原先每个子模块的源码，都作为普通目录直接进了主仓，只有一条线性主线 main。各微服务仍留着自己的独立仓库，但已经降级成只读的下游镜像——由主仓合并触发的同步单向更新，日常开发不要直接克隆或改动。 全部镜像都在 GitHub 组织 AgentEndeavour 下，推送目标分支均为 main：
主仓目录下游镜像（AgentEndeavour/…）说明
rakullapp_coreRakullApp-CoreFlutter 客户端
rakullapp_core/thirdparty/UILibraryUILibrary设计系统组件库
docsRakullDoc本文档站
docs/user-guideRakullPublicDoc公开用户文档
ImmersivellwebappImmersivellwebapp旧版 Web 应用
rakull_serverRakullServer后端聚合仓
rakull_server/agent_serverRakullAgentServerAI 计算（内部）
rakull_server/collection_serverRakullCollectionServer收藏（面向客户端）
rakull_server/data_serverRakullDataServer持久化 / Model（内部）
rakull_server/immersive_study_serverRakullImmersiveStudyServer控制器 / App Server
rakull_server/manager_serverRakullManagerServerAdmin Server
rakull_server/user_managerRakullUserManager鉴权 / 管理
rakull_server、rakullapp_core、docs 这三个「父目录」镜像现在把各自的子目录也一并装了进去（扁平、自包含），不再是过去那种只挂子模块的壳仓库。所以改动某个叶子目录时，会连它上面每一级的祖先 prefix 一起同步。
为什么还保留这些镜像？ 每个微服务可以从自己的镜像仓库独立构建、发布（镜像里仍保留各自的 .github/workflows/）；需要被外部单独引用（作为依赖或下游集成）时，镜像也提供一个稳定入口。写入方向永远是「monorepo → 镜像」，任何对镜像 main 的直接改动都会在下次同步时被覆盖。 镜像怎么更新、第一次怎么初始化、令牌怎么配，见仓库镜像同步。

​
一次性准备

1

克隆主仓（无需子模块）

git clone git@github.com:AgentEndeavour/RakullApp.git
cd RakullApp
普通 clone 就能拿到全部源码；不再需要 --recurse-submodules 或 git submodule update。
2

安装 pre-commit 钩子

仓库带 lint/格式化钩子（后端 Ruff、客户端 dart format/analyze）。一次性安装：
uv tool install pre-commit
bash scripts/install_precommit_all.sh
详见代码规范与提交检查。

​
标准开发流程

无论改动落在哪个子目录（客户端、某个后端服务、文档……），流程都是同一条：
1

同步并 rebase 到最新 main

git checkout main
git fetch origin
git rebase origin/main
2

切到你自己的分支

永远在分支上开发，不要直接改 main：
git checkout -b feat/<范围>-<简述>     # 例：feat/data-server-add-progress-endpoint
分支名必须使用 <type>/<短描述>。允许的类型为 feat、fix、docs、refactor、test、chore、build、ci、perf、revert；不要使用开发者姓名作为永久分支。
3

开发

  • 先规划：较大的需求先进入 plan 模式，在 .cursor/plans/ 写计划并对齐后再动手（见 vibe-coding-workspace/base_knowledge/workflow.md）。
  • 本地联调：bash scripts/run_all_servers.sh，客户端用 --dart-define 指向本地服务（见安装与快速开始）。
  • 外部 AI/COS 密钥优先通过 http://localhost:8015 的管理后台配置；部署级密钥只进入环境变量或 gitignored 本地文件，切勿提交真实密钥。
  • 改到哪个目录就补哪层的测试，保持绿灯（见测试）。
4

add 与 commit

git add -A
git commit -m "feat(data_server): add per-article progress endpoint"
git commit 会触发 pre-commit：后端跑 ruff-check --fix + ruff-format，客户端跑 dart format + dart analyze。钩子如果自动改了文件，本次提交会中止——把改动 git add 后再次提交即可。提交信息必须遵循 Conventional Commits（约定式提交）：<type>(可选范围): 描述。新增功能用 feat，缺陷修复用 fix，文档用 docs；“debug”是过程而不是提交类型，调试产生的修复仍写作 fix(scope): ...。不使用 [feature] 或 [debug] 方括号标签。
5

推送分支并向 main 提 PR，然后等评审合并

git push -u origin feat/<范围>-<简述>
到 GitHub 对 RakullApp 发起 PR：base = main，compare = 你刚推送的分支。PR 描述按下方模板补齐功能文档。然后：
  • 等待仓库根部的 CI 变绿（按改动路径触发，只跑与你改动相关的那条）：rakull_server/** 改动触发 .github/workflows/ci-backend.yml，按服务矩阵跑 uv run pytest；rakullapp_core/** 改动触发 .github/workflows/ci-client.yml，跑 flutter analyze + flutter test；只改文档等无关子树时两者都会跳过；
  • 等待评审通过、PR 合并。AI 和自动化脚本不得合并 PR，也不得启用 GitHub auto-merge；必须由人工评审者完成合并。
6

合并后：镜像自动同步（无需手动操作）

PR 合并到 main 会触发 mirror-sync 工作流，把本次改动涉及的子目录用 git subtree split 推送到对应的下游镜像仓库。你不需要做任何额外操作——不要手动 push 镜像仓库，也不要在镜像仓库里开分支。原理与排障见仓库镜像同步。

​
PR 模板：功能文档

每个 PR 都要随手把对应功能写成文档，沿用 vibe-coding-workspace/requirements/functions/<领域>/<功能>.md 的结构（Context / Task / 逻辑）。把下面这段复制进 PR 描述并填写： 
## 功能：<领域> — <功能名>

### Context（背景）
- 影响子目录 / 平台：<例如 rakull_server/data_server、rakullapp_core(web/desktop)>
- 相关服务 / 模块：<例如 immersive_study_server 控制器、user_manager 鉴权>
- 关联需求文档：vibe-coding-workspace/requirements/functions/<领域>/<功能>.md

### What & Why（做了什么、为什么）
- <一句话说明这个 PR 解决的问题与目标>

### 逻辑 / 流程（Logic）
1. <按调用链或用户操作顺序，逐步描述数据怎么流转>
2. ...

### 测试
- [ ] 受影响服务 `uv run pytest -q` 全绿 /（客户端）`flutter test` 全绿
- [ ] pre-commit（Ruff / dart）无报错

### 文档
- [ ] 已更新 docs（中文 + `i18n/en/` 英文镜像），如有新页面已加进 `docs.json` 导航
「功能文档」描述当前实现的行为，和架构文档、服务模块文档互补。改了面向用户的行为，也记得更新对应的用户指南。

​
提交信息与代码规范

类型用途示例
feat新功能feat(reader): add paragraph loop
fix缺陷修复fix(auth): reject expired token
docs仅文档docs(workflow): add recovery guide
refactor不改变行为的重构refactor(api): extract error mapper
test测试test(progress): cover empty article
chore / build / ci维护、构建、CIchore(ci): tune mirror-sync trigger
perf / revert性能优化、回退perf(search): reduce duplicate queries
关卡工具说明
提交前（本地）pre-commit后端 Ruff check --fix + format；客户端 dart format + dart analyze
PR（远端）主仓 CI ci-backend.yml / ci-client.yml（路径白名单）仅 rakull_server/** 改动：后端 uv run pytest -m "not integration"（各服务矩阵）；仅 rakullapp_core/** 改动：客户端 flutter analyze + flutter test
  • 后端规则集中在每个服务的 pyproject.toml 的 [tool.ruff]；详见代码规范。
  • 各服务子目录下仍保留自己的 .github/workflows/——这些只在下游镜像仓库里运行，主仓 PR 由根部的 ci-backend.yml / ci-client.yml 按改动路径分别把关。

​
流程全貌

​
常见陷阱

RakullServer、RakullAgentServer 等现在是只读下游镜像，会被主仓同步覆盖。所有改动都在 RakullApp monorepo 里进行；不要克隆或向镜像仓库 push。
外部 AI/COS 密钥优先通过管理后台配置；部署级密钥只放环境变量或 gitignored 本地文件（config.local.yaml、.secrets/ 等）。真实 Key 一旦提交需立刻吊销并轮换。
文档站是双语镜像：docs/<page> 与 docs/i18n/en/<page> 必须成对更新，新增页面要同时加进 docs.json 里 zh 与 en 两套导航。

​
下一步

仓库镜像同步（运维）

同步脚本、CI 触发、令牌配置与镜像初始化。

代码规范与提交检查

pre-commit + Ruff / dart 的安装与日常使用。

安装与快速开始

安装依赖，一键启动后端并运行本地客户端。

测试

后端 pytest 与客户端 flutter test 的运行方式。