chore(repo): initialize team collaboration repository

2026-07-27 20:40:12 +08:00
commit c91a64fddb
109 changed files with 21121 additions and 0 deletions
@@ -0,0 +1,111 @@
+# STORAGE LABOS 团队协作指南
+
+本文是团队日常 Git 操作的简明入口；完整工程约束见
+[ProjectManual.md](ProjectManual.md) 第 13 章。
+
+## 1. 首次加入项目
+
+公开仓库允许匿名克隆；需要提交代码、Issue 或 Pull Request 的成员先注册账号并由管理员批准：
+
+```bash
+git clone https://git.imagebrewing.com/yuanshuai/storage-labos.git
+cd storage-labos/flashops
+make setup
+make test
+```
+
+不要通过聊天工具传递压缩包继续开发；Git 仓库是代码和文档的唯一版本来源。
+
+## 2. 分支规则
+
+- `main`：始终保持测试通过和可发布，禁止直接开发或强制推送。
+- `feat/<short-name>`：功能开发。
+- `fix/<short-name>`：缺陷修复。
+- `docs/<short-name>`：纯文档变更。
+- `chore/<short-name>`：构建、依赖、部署与仓库维护。
+
+一项工作一个分支；不要把无关功能、生产配置和大规模格式化混在同一分支。
+
+```bash
+git switch main
+git pull --ff-only
+git switch -c feat/agent-step-lease
+```
+
+## 3. 提交前质量门
+
+```bash
+cd flashops
+make test
+make demo
+```
+
+回到仓库根目录后，只暂存本次工作涉及的文件：
+
+```bash
+git status -sb
+git add <明确的文件或目录>
+git diff --cached --stat
+git diff --cached --check
+```
+
+混合工作区不要直接使用 `git add -A`，避免把别人的改动、数据库或临时文件带入提交。
+
+## 4. 提交格式
+
+使用 Conventional Commits：`type(scope): subject`。
+
+| 类型 | 用途 | 示例 |
+|---|---|---|
+| `feat` | 新功能 | `feat(agent): add step lease polling` |
+| `fix` | 缺陷修复 | `fix(safety): reject stale host heartbeat` |
+| `docs` | 文档 | `docs(manual): add agent deployment guide` |
+| `test` | 测试 | `test(agent): cover token rotation` |
+| `refactor` | 不改变行为的重构 | `refactor(events): isolate projection writer` |
+| `perf` | 性能优化 | `perf(api): reduce timeline query cost` |
+| `chore` | 工具、依赖和部署 | `chore(ci): add Python test matrix` |
+
+主题用祈使语气、简短明确；一次提交只表达一个完整意图。
+
+## 5. 推送与 Pull Request
+
+```bash
+git commit -m "feat(agent): add step lease polling"
+git push -u origin "$(git branch --show-current)"
+```
+
+在 Gitea 创建 Pull Request，并写清：改了什么、为什么改、影响范围、验证结果和风险。
+至少一名团队成员评审且质量门通过后才能合并。当前 Gitea 未在生产服务器上启用自托管
+Runner，提交者必须在 PR 中附上本地测试结果；未来接入隔离 CI Runner 后再把自动检查设为
+必需。优先使用 Squash merge，PR 标题保持 Conventional Commit 格式；合并后删除远程功能分支。
+
+评审者重点检查：
+
+1. 安全门禁、状态机和事件写路径是否被绕过；
+2. 是否新增或修改测试；
+3. API、数据结构、配置或部署变化是否同步更新手册；
+4. 是否包含凭据、生产数据、日志、构建产物或大文件；
+5. 危险动作是否仍为默认拒绝。
+
+## 6. 冲突与回退
+
+功能分支同步 `main` 时使用团队统一方式；首阶段建议 rebase：
+
+```bash
+git fetch origin
+git rebase origin/main
+```
+
+仅允许对自己尚未合并的功能分支执行 `git push --force-with-lease`；严禁对 `main` 强推。
+已合并变更需要撤销时使用 `git revert <commit>`，不要改写共享历史。
+
+## 7. 绝不能提交的内容
+
+- `.env`、密码、Token、SSH 私钥、证书私钥；
+- `flashops/var/`、SQLite 数据库、Evidence Bundle 和日志；
+- `.venv/`、`node_modules/`、缓存和本机构建产物；
+- `~/.flashops/agent-state.json` 或任何 Agent 原始 bearer token；
+- 未脱敏的客户数据、设备序列号清单和生产备份。
+
+如果凭据误入提交：立即停止推送、通知管理员轮换凭据，再清理历史；仅删除当前文件不等于
+从 Git 历史中删除。