---
name: quick-ui
description: 前端小功能快速通道——给已完成的页面追加局部小交互（按钮/筛选/排序/格式化等，只消费 docs/05 已有端点）时替代 add-req 全流程。代码由主会话直改 frontend/（不起 coding.mjs、不跑行为门/e2e），原型与 docs/08 §三 FE 行文字按需同步，台账 req-ledger 重基线但绝不作废 req-done/milestone tag，Router 视一切已完成不重跑前端阶段。涉及后端/新页面/新路由即停下回落 /add-req。与 quick-field（加列+呈现）成对。
user-invocable: true
allowed-tools: Read Write Edit Grep Glob AskUserQuestion Bash(node *) Bash(git *) Bash(ls *)
---

**所有输出必须使用中文。**

# quick-ui — 前端小功能快速通道

用于**前端阶段已打 `milestone/frontend-phase`** 之后的最小前端改动形态：在已完成的页面上追加一个局部小功能。与姊妹通道的分工：

| 改动形态 | 走哪个 |
|---|---|
| 加列 + 界面展示/录入 | `/erp-workflow:quick-field` |
| 已有页面加局部小交互（纯前端） | **本 skill** |
| 新需求 / 新端点 / 新页面 / 语义变更 | `/erp-workflow:add-req`（正规通道） |

> 速度来自跳过前端阶段重跑（Preview 截图门 / 前端功能循环 / 行为门起全栈 / 全量 e2e），代价是**该功能未过行为验收**——步骤 6 登记待验，起栈后人工点一下。

`<root>` = 项目根（含 `docs/`、`frontend/`、`prototype/`、`.git`）。`${CLAUDE_PLUGIN_ROOT}` = 插件根。

## 适用边界（硬门，任一不满足即停下回落 add-req）

1. **纯前端**：不写 `backend/` / `sql/` / `scripts/` 任何文件，不需要 schema 变化。
2. **只消费既有端点**：功能所需数据/操作在 `docs/05-API接口契约.md` 已有端点上齐备（`Grep` 确认）；需要新端点或改既有端点语义 → 回落 add-req。
3. **不新增页面/路由**：改动局限在既有页面/组件内部（新增子组件文件可以，新增 router 条目不行）。
4. **归属某个已完成的 FE 行**（docs/08 §三 已有 `FE-NN` 且 `req-done/FE-NN` tag 存在）。**绝不新增 FE 行**——新增 FE 行是新功能单元，走 add-req。
5. **交互局部、低风险**：按钮/筛选/排序/格式化/展开折叠/复制导出这类；涉及跨页面状态、权限逻辑、提交链路语义变化 → 回落 add-req。

超界示例（一律停下，打印命中条目 + 建议走 `/erp-workflow:add-req`）：需要后端新查询、新页面、新路由、改表单提交语义、跨页面联动。

## 步骤 0：前置检查（全过才继续）

1. **Plan 已完结**：`Read` `docs/08-模块任务管理.md § 一`，存在任一 `- [ ]` 未勾 → 停下提示先跑 `/erp-workflow:plan-start`。
2. **coding.mjs 未在运行**：向用户确认没有 Coding Workflow 在后台跑。在跑 → 停下等它结束。
3. **工作树干净**：`git -C <root> status --porcelain` 为空。不干净 → 停下提示先处理。
4. **台账干净（关键）**：
   ```
   node ${CLAUDE_PLUGIN_ROOT}/lib/req-ledger.mjs scan <root>
   ```
   - `ledgerExists: false` → 停下提示先跑一次 `/erp-workflow:add-req` 建基线。
   - `new[]` / `changed[]` / `removed[]` 须**全空**（`changed` 仅含本次目标 FE 行（kind=fe）和/或 `__prototype__`（kind=proto）时放行——用户可能已先手改了 FE 行文字或原型）。存在其他待处理增量 → **停下**：步骤 5 的 `req-ledger commit` 是全量重基线，会把它们悄悄吞进基线、add-req 永远检测不到。提示先跑 `/erp-workflow:add-req` 清账再来。

## 步骤 1：收集改动意图 + 边界判定

从用户输入（或 `AskUserQuestion`）明确：

- **目标页面/组件**与**功能描述**（做什么、放哪、触发后发生什么）；
- **归属 FE 行**：`Grep` `docs/08 §三` 按功能名/页面定位 `FE-NN`；多命中或零命中 → `AskUserQuestion` 让用户指定；
- **数据来源**：`Grep` `docs/05` 确认所需端点已存在（边界 2 的证据）。

随后对照适用边界逐条判定，**任一超界立即停下**（打印命中条目），不做任何写操作。

## 步骤 2：原型同步（按需）

原型（`prototype/**/*.html`）是前端布局/页面/交互的权威。若本功能带来**可见的布局/控件变化**（新按钮、新筛选控件等）→ `Edit` 对应原型页面同步加上（静态呈现即可，无需真交互逻辑）；纯行为变化（如点击已有按钮的新反馈）可不动原型。

> 改了原型 → `__prototype__` 哈希变化，由步骤 5 重基线吸收；**绝不**因此删任何 `req-done/FE-*` / `milestone/frontend-phase` tag——那是 add-req 的语义（整个前端重跑），恰是本 skill 要避免的。

## 步骤 3：代码直改 + 轻量自检

**改代码**（`Grep` 在 `frontend/` 定位目标组件；分层/状态管理/请求封装遵循 `docs/04-技术规范.md § 二`，组件选型对齐 § 零 `frontend.ui_lib`，色值用 `src/styles/tokens.css` 的 token）：

- 在既有页面/组件内实现该功能；请求走项目既有的请求封装调 docs/05 已有端点。
- **不写** `backend/` / `sql/` / router 新条目——写到一半发现绕不开即停，回落 add-req（已写的前端改动 `git checkout` 丢弃）。

**轻量自检（必做，不搭测试 harness、不起栈）**：

1. **grep 清单**：新增控件文案/函数名/端点调用在目标组件内逐一 `Grep` 确认落位；确认没碰 `backend/`/`sql/`（`git status` 复核改动全在 `frontend/` + `prototype/` + docs）。
2. **语法/类型门（若命令轻量）**：docs/04 § 零 有前端 lint / 类型检查命令（如 lint script、`vue-tsc`）则跑一次，红了就修；该组件若有既有 vitest 单测且能按文件过滤，可顺带跑**该文件**；**不跑**全量测试 / e2e / 行为门。

## 步骤 4：FE 行文字同步（按需）

若新功能值得体现在功能清单里（对后续维护者有信息量）→ `Edit` `docs/08 §三` 该 `FE-NN` 行的功能描述文字（**改文字，不新增行、不动 checkbox**）。琐碎改动可不改。

改了行文字 → 该 FE 单元哈希变化，由步骤 5 重基线吸收。

## 步骤 5：台账重基线（绝不作废 tag）

仅当步骤 2/4 改动了 `prototype/` 或 docs/08 §三 FE 行（否则台账无变化，跳过本步）：

```
node ${CLAUDE_PLUGIN_ROOT}/lib/req-ledger.mjs scan <root>
```

复核输出：`changed` **仅含**本次目标 FE 行和/或 `__prototype__`，`new`/`removed` 为空（步骤 0 已保证，此处防中途意外）。确认后：

```
node ${CLAUDE_PLUGIN_ROOT}/lib/req-ledger.mjs commit <root>
```

**本 skill 全程绝不执行任何 `git tag -d`**——`req-done/FE-*` / `milestone/frontend-phase` 全部保留，Router 视前端阶段已完成，coding.mjs 不会因本次微改重跑。

## 步骤 6：待验登记

`Read` `docs/08-模块任务管理.md`：末尾若无 `## 四、微改待验清单（quick-field / quick-ui）` 小节则追加创建（若已有旧标题 `## 四、quick-field 待验字段` 则把标题更新为前者，存量条目保留），然后登记一行：

```
- [ ] <YYYY-MM-DD> <页面/组件> <功能摘要>（<FE-NN>；quick-ui）——未过行为门/e2e，待人工点验或随下次正规需求批量验收
```

（该小节位于 §三 之后，`req-ledger` 的 FE 行解析在下一个 `##` 处截断，不影响台账哈希。）验收完成后由人工勾选。

## 步骤 7：git 提交 + 完成横幅

1. 在**当前分支（默认分支）**提交全部产物：
   ```
   git -C <root> add frontend prototype docs/08-模块任务管理.md .req-ledger.json
   git -C <root> commit -m "feat(quick-ui): <页面> <功能摘要>（<FE-NN>；纯前端直改 + 台账重基线，不重跑 coding）"
   ```
2. `git -C <root> status --porcelain` 复核干净，有残留则排查补提交。
3. 打印横幅并**停下**：

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 [quick-ui] ✅ 前端小功能完成（未重跑 coding）

   功能：<页面/组件 + 功能摘要>（归属 <FE-NN>）
   端点：<复用的 docs/05 端点 或 纯展示无请求>
   原型：<已同步 <文件> 或 无布局变化未动>
   自检：grep 清单通过<；lint/类型检查通过 或 —><；<组件>单测通过 或 —>
   台账：<已重基线 或 无变化未动>；req-done/milestone tag 全部保留
   待验：docs/08 §四 已登记（未过行为门/e2e）

 起栈后请人工点验该功能；攒批待验条目可随下次正规需求一并验收后勾销。
 [ERP-HALT] 前端微改完成，已停下。
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

## 参考

- `${CLAUDE_PLUGIN_ROOT}/skills/plan/quick-field/SKILL.md`（姊妹通道：加列+呈现）
- `${CLAUDE_PLUGIN_ROOT}/skills/plan/add-req/SKILL.md`（正规增量通道；超界回落目标）
- `${CLAUDE_PLUGIN_ROOT}/lib/req-ledger.mjs`（台账 scan/commit；本 skill 只重基线、不作废 tag）
- `docs/04-技术规范.md § 二 前端规范 / § 零 命令`（分层、组件库、lint/类型检查命令）
- `docs/05-API接口契约.md`（既有端点清单，边界 2 判据）
- `docs/08-模块任务管理.md § 三`（FE 行）/ `§ 四`（微改待验清单）
- `prototype/`（前端布局/交互权威，可见变化需同步）