HIsheR
40 lines
2.9 KiB
Markdown
40 lines
2.9 KiB
Markdown
# 无人值守自我迭代协议（ITERATION.md）
|
||
|
||
> 本协议由自动化 Agent 执行，也可供人工参考。任何迭代必须遵守 `CODING.md`、`AGENTS.md`、`ARCHITECTURE.md` 三份规范，门禁 `npm run check` 不通过的一切产出作废。
|
||
|
||
## 分支流水线
|
||
|
||
```
|
||
qa/probe ──门禁通过──▶ qa/stable ──人工审阅──▶ main（受保护，禁直接推送）
|
||
```
|
||
|
||
| 分支 | 用途 | 谁能写 |
|
||
|---|---|---|
|
||
| `main` | 稳定发布线，受 Gitea 分支保护 | 仅人工审阅后合并 |
|
||
| `qa/stable` | 集成测试线，所有通过门禁的迭代落在这里 | 自动化（仅 fast-forward 合并） |
|
||
| `qa/probe` | 试验分支，每轮迭代的工作现场，可被强制重置 | 自动化 |
|
||
|
||
## 每轮迭代流程（自动化 Agent 执行）
|
||
|
||
> 所有远程推送一律使用认证包装脚本：`node scripts/gitea.mjs push <remote> <分支>`（令牌读自本地 `.gitea-token`，不入库；凭据管理器不可用）。
|
||
|
||
1. **同步**：`git fetch --all --prune`，切到 `qa/stable` 并 `git pull`；从其最新提交强制重建 `qa/probe` 并切换过去。
|
||
2. **选题**：读 `.ua/backlog.json`，取第一条 `status === "open"` 的条目；若全部关闭，按《选题规则》自行补充一条新点子后继续。
|
||
3. **实现**：按 `CODING.md` 编码规范实现，保持低侵入，单文件 < 200 行，涉及组件需同步 manifest/docs/llms-full.txt。
|
||
4. **门禁**：跑 `npm run check`（build → style → typecheck → smoke → index）。
|
||
- **通过**：提交到 `qa/probe`（commit message 以 `iter:` 开头，注明 backlog 条目 id），推送 `qa/probe`，fast-forward 合并到 `qa/stable` 并推送；将 backlog 条目 `status` 置为 `done` 并随迭代提交。
|
||
- **失败**：尝试修复一次；仍失败则放弃本轮——`qa/probe` 直接重置回 `qa/stable`，backlog 条目在 `notes` 里追加失败原因、`status` 保持 `open`，提交并推送该元数据变更（仅改 `.ua/backlog.json`，不碰代码）。
|
||
5. **留痕**：在 `.ua/iterations.log` 追加一行 JSON：`{时间, 条目id, 结果, 摘要}`，随本轮提交。
|
||
6. **边界**：不改 `main` 分支保护、不删分支、不动 `.workbuddy/`、不重写历史、不 force push 到 `qa/stable` 与 `main`。
|
||
|
||
## 选题规则（自主补点子时）
|
||
|
||
- 只从以下方向选：组件补充（皮肤包缺的常规组件）、既有组件的可用性细节、文档站与 Agent 文档完善、构建/门禁工具链改进、演示页完善。
|
||
- 单轮改动范围可控：新增文件 + 少量既有文件修改，避免跨包大规模重构。
|
||
- 每条点子必须写清 `title / motivation / acceptance`（验收标准，可被 `npm run check` 与人工检查验证）。
|
||
|
||
## 人工介入点
|
||
|
||
- 审阅 `qa/stable` 的提交，确认质量后合入 `main`（PR 或本地 merge 后推送）。
|
||
- 发现自动化产出质量下滑时：暂停自动化、在 backlog 中把质量要求写进条目、恢复运行。
|