From ccba3dba7ae8a02200a18d276bf9ceb0094adbd5 Mon Sep 17 00:00:00 2001
From: HIsheR <shawn1440982358@163.com>
Date: Fri, 23 Oct 2026 15:19:20 +0800
Subject: [PATCH] =?UTF-8?q?iter:=20=E8=87=AA=E6=88=91=E8=BF=AD=E4=BB=A3?=
 =?UTF-8?q?=E5=8D=8F=E8=AE=AE=E4=B8=8E=E7=82=B9=E5=AD=90=E5=BA=93=E5=88=9D?=
 =?UTF-8?q?=E5=A7=8B=E5=8C=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .gitignore       |  1 +
 .ua/backlog.json | 45 +++++++++++++++++++++++++++++++++++++++++++++
 ITERATION.md     | 37 +++++++++++++++++++++++++++++++++++++
 3 files changed, 83 insertions(+)
 create mode 100644 .ua/backlog.json
 create mode 100644 ITERATION.md

diff --git a/.gitignore b/.gitignore
index a3a9076..cb917eb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,4 @@ dist/
 .ua/cache/
 apps/docs/*.html
 .workbuddy/
+.gitea-token
diff --git a/.ua/backlog.json b/.ua/backlog.json
new file mode 100644
index 0000000..8ada268
--- /dev/null
+++ b/.ua/backlog.json
@@ -0,0 +1,45 @@
+{
+  "$schema": "迭代点子库，status: open=待做 / done=已完成；按数组顺序取第一条 open 执行",
+  "items": [
+    {
+      "id": "b01",
+      "title": "新增 tooltip 组件",
+      "motivation": "皮肤包 16 组件缺少悬浮提示，表单与工具栏场景常用；可复用自绘弹层与微动画既有模式",
+      "acceptance": "packages/skin/ui 新增 tooltip.ts：content/message 简单 API，hover/focus 触发，延迟约 150ms 出场，带出入场微动画与 prefers-reduced-motion 兜底，只消费 --ua-* 令牌；导出并注册进 ua.manifest.json，文档站 props 表与 llms-full.txt 同步更新；npm run check 全绿",
+      "status": "open",
+      "notes": ""
+    },
+    {
+      "id": "b02",
+      "title": "新增 toast 消息提示组件",
+      "motivation": "alert 是常驻块级元素，缺少轻量转瞬即逝的全局反馈；操作成功/失败场景刚需",
+      "acceptance": "新增 toast.ts：toast.success/error/warning/info 四个工厂函数，入参 {message, duration?}，默认 3s 自动消失，右上角堆叠，语义色复用四档 variant，出入场微动画 + prefers-reduced-motion 兜底；导出、manifest、文档、llms-full.txt 同步；npm run check 全绿",
+      "status": "open",
+      "notes": ""
+    },
+    {
+      "id": "b03",
+      "title": "新增 skeleton 骨架屏组件",
+      "motivation": "异步加载占位是数据表格与卡片的标配，配合 dataTable 空状态形成完整加载体验",
+      "acceptance": "新增 skeleton.ts：skeleton({variant: 'text'|'rect'|'circle', rows?})，呼吸/扫光微动画 + prefers-reduced-motion 静态化，只消费 --ua-* 令牌；导出、manifest、文档、llms-full.txt 同步；demo 页加一节演示；npm run check 全绿",
+      "status": "open",
+      "notes": ""
+    },
+    {
+      "id": "b04",
+      "title": "新增独立 pagination 分页器组件并与 dataTable 演示联动",
+      "motivation": "table-core 已有 pagination 插件，但皮肤包没有独立分页器；dataTable 演示也未展示分页联动",
+      "acceptance": "新增 pagination.ts：受控 API {page, pageSize, total, onChange}，页码过多时折叠省略号，键盘可达，禁用态完整；demo 页 dataTable 一节增加分页联动演示；导出、manifest、文档、llms-full.txt 同步；npm run check 全绿",
+      "status": "open",
+      "notes": ""
+    },
+    {
+      "id": "b05",
+      "title": "文档站演示区由 manifest 驱动自动生成",
+      "motivation": "目前 apps/docs/index.html 手写 props 表与演示，每加组件都要人肉同步；由 manifest 单一来源驱动可消除重复维护",
+      "acceptance": "ua CLI 新增 docs-gen 逻辑：读取各组件 ua.manifest.json 中的 components 参数表，自动生成 props 表 HTML 片段注入文档站模板；生成结果与现有手写版信息量对齐（props 名/类型/默认值/说明）；npm run check 全绿且文档站可正常打开",
+      "status": "open",
+      "notes": ""
+    }
+  ]
+}
diff --git a/ITERATION.md b/ITERATION.md
new file mode 100644
index 0000000..e4432a9
--- /dev/null
+++ b/ITERATION.md
@@ -0,0 +1,37 @@
+# 无人值守自我迭代协议（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 执行）
+
+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 中把质量要求写进条目、恢复运行。