@gong-ym/ai-spec-auto 0.2.3

package/.agents/rules/profiles/vue/13-/344/273/243/347/240/201/346/240/274/345/274/217/345/214/226/344/270/216/346/243/200/346/237/245.md

@@ -0,0 +1,159 @@
+---
+alwaysApply: false
+description: Vue 项目的代码格式化与静态检查规范，包括 ESLint、Prettier、Stylelint 的工具链职责、统一配置规则与开发流程集成。当配置或调整 lint/format 工具时读取此规则。
+---
+
+# 代码格式化与检查（Vue）
+
+## 工具链
+
+| 工具 | 职责 | 配置文件 |
+|------|------|----------|
+| **Prettier** | 代码格式化（缩进、引号、分号等） | `.prettierrc.json` |
+| **ESLint** | 代码质量与风格检查（未使用变量、潜在 bug 等） | `.eslintrc.cjs` / `.eslintrc.js` |
+| **Stylelint** | 样式文件检查（CSS/SCSS/Less 规范） | `.stylelintrc.json` |
+
+三者职责不重叠：Prettier 管格式，ESLint 管逻辑，Stylelint 管样式。
+
+## 配置来源
+
+- 项目根目录的 lint/format 配置文件由**规范库统一管理**
+- `install.sh init` 时自动部署到目标项目，`update` 时同步更新
+- 项目可在基础配置上**扩展**（如追加 i18n 插件），但不应修改基础规则
+
+## Prettier 统一规则
+
+| 配置项 | 值 | 说明 |
+|--------|-----|------|
+| `semi` | `true` | 语句末尾加分号 |
+| `tabWidth` | `2` | 缩进 2 空格 |
+| `singleQuote` | `true` | 使用单引号 |
+| `printWidth` | `100` | 单行最大宽度 |
+| `trailingComma` | `"es5"` | 对象/数组末尾加逗号（减少 diff 噪音） |
+| `endOfLine` | `"auto"` | 自动适配换行符 |
+| `arrowParens` | `"avoid"` | 单参数箭头函数省略括号 |
+| `proseWrap` | `"never"` | Markdown 不自动换行 |
+
+## ESLint 核心规则
+
+### 通用基础
+
+- 项目根据自身技术栈在 `extends` 中配置合适的共享规则集
+- 项目可追加插件（如 `@intlify/vue-i18n`、`eslint-plugin-import` 等）
+
+### Vue 项目
+
+```js
+// .eslintrc.cjs
+module.exports = {
+  root: true,
+  // 项目按需配置 extends（如 eslint:recommended、plugin:vue/vue3-recommended 等）
+};
+```
+
+### React 项目
+
+```js
+// .eslintrc.js
+module.exports = {
+  root: true,
+  settings: {
+    'import/resolver': {
+      alias: [['@', './src']],
+    },
+  },
+  // 项目按需配置 extends（如 eslint:recommended、plugin:react/recommended 等）
+};
+```
+
+## Stylelint 核心规则
+
+- 继承 `stylelint-config-standard` 基础规则
+- Vue 项目追加 `stylelint-config-html/vue` 和 `stylelint-config-recommended-vue`
+- 使用 `postcss-html` 作为自定义语法解析器（解析 `.vue` 文件中的 `<style>`）
+- 忽略与业务组件库冲突的规则（如 `no-descending-specificity`）
+
+## 开发流程集成
+
+### IDE 保存时自动格式化（推荐）
+
+项目可在 `.vscode/settings.json` 中配置：
+
+```json
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit",
+    "source.fixAll.stylelint": "explicit"
+  }
+}
+```
+
+### 提交前自动检查（husky + lint-staged）
+
+使用 `husky` 注册 Git hooks，`lint-staged` 只检查暂存文件：
+
+| 工具 | 职责 | 配置文件 |
+|------|------|----------|
+| husky | 注册 Git hooks（pre-commit、commit-msg） | `.husky/` |
+| lint-staged | 对暂存文件执行 lint/format | `.lintstagedrc` |
+| commitlint | 校验 commit message 格式 | `commitlint.config.js` |
+
+**部署前提**：上述 `.husky/`、`.lintstagedrc`、`commitlint.config.js` 仅在执行 `install.sh` / `install.ps1` 时**选择安装提交校验**（`--husky` 或交互选 Y）后才会复制到目标项目并配合 `husky install` 注册 Git hooks。若选择跳过提交校验（`--no-husky` 或交互选 N），则不会下发这些文件；仅安装 lint/format 时只会得到 ESLint、Prettier、Stylelint 等配置。
+
+**lint-staged 检查范围**：
+
+```json
+{
+  "src/**/*.{vue,less,scss,css}": [
+    "stylelint --fix"
+  ],
+  "src/**/*.{js,ts,jsx,tsx,json,vue}": [
+    "eslint --fix"
+  ]
+}
+```
+
+### Commit Message 规范（Conventional Commits）
+
+统一使用 [Conventional Commits](https://www.conventionalcommits.org/) 格式，由 commitlint 强制校验：
+
+```
+<type>(<scope>): <subject>
+```
+
+| type | 说明 |
+|------|------|
+| `feat` | 新功能 |
+| `fix` | 修复 bug |
+| `docs` | 文档变更 |
+| `style` | 代码格式（不影响逻辑） |
+| `refactor` | 重构（非新功能、非修复） |
+| `test` | 测试相关 |
+| `chore` | 构建、工具、依赖等杂项 |
+
+**示例**：
+
+```
+feat(order): 新增工单批量导出功能
+fix(auth): 修复 token 过期后未跳转登录页的问题
+docs(api): 补充资产库接口类型定义
+```
+
+- `scope` 可选，建议填写业务模块名
+- `subject` 使用中文，简明扼要
+
+## 忽略文件约定
+
+各工具的 ignore 文件遵循统一基线，至少忽略以下目录：
+
+```
+node_modules
+dist
+lib
+assets
+public
+```
+
+项目可根据实际情况追加特有的忽略路径。

package/.agents/skills/README.md

@@ -0,0 +1,171 @@
+---
+name: skills-index
+description: 技能目录索引。安装到目标项目后此目录为扁平结构（common + profile 合并），此处为源仓库的分层结构。
+---
+
+# 技能目录结构
+
+本目录推荐采用 **common + profiles + domains（可选）** 的分层组织。
+
+结论先说：
+
+- 不建议按“专家名”建 skill 目录
+- 优先按“复用范围”和“技术栈”组织 skill
+- 角色负责职责边界，skill 负责具体方法
+
+## 官方标准与本仓库约束
+
+本仓库的 skill 资产默认同时满足两层约束：
+
+- 官方 Agent Skills 规范：frontmatter、description、progressive disclosure、bundled resources
+- 本仓库扩展：`.agents/rules/`、OpenSpec、Hub 同步、eval 基线
+
+强制规则：
+
+- `SKILL.md` frontmatter 只允许 `name`、`description`、`license`、`compatibility`、`metadata`、`allowed-tools`
+- `description` 必须同时表达“能力范围”和“何时使用”
+- 依赖本仓库目录、OpenSpec、Browser、Vitest 等环境时，必须写 `compatibility`
+- bundled resources 统一使用 skill 根目录下的 `references/`、`scripts/`、`assets/`
+- 新建 skill 默认补 `evals/train_queries.json`、`evals/validation_queries.json`、`evals/evals.json`
+
+校验入口：
+
+```bash
+node ./bin/validate-registry.js --json
+python3 .agents/skills/common/skill-creator/scripts/quick_validate.py <skill-dir>
+```
+
+详细说明见：
+
+- [Skill官方标准与创建规范](/Users/lizhenwei/workspace/vueworkspace/bairong/br-ai-spec/docs/four/Skill官方标准与创建规范.md)
+- [Skill官方审计基线](/Users/lizhenwei/workspace/vueworkspace/bairong/br-ai-spec/docs/four/Skill官方审计基线.md)
+
+## common/ — 通用技能（与技术栈无关）
+
+| 技能 | 用途 | 配合规范 |
+|------|------|----------|
+| `create-proposal` | 提案前置分析与 OpenSpec 增强层 | - |
+| `archive-change` | 变更归档增强层（规范合并 + 目录校验） | - |
+| `design-analysis` | 设计稿分析，产出 UI 分析清单 | - |
+| `config-and-secret-scan` | 配置规范与敏感信息扫描 | `08-通用约束` |
+| `route-permission-map` | 路由、权限与菜单映射审计 | `06-路由规范` |
+| `dependency-impact-graph` | 依赖影响分析与回归范围评估 | - |
+| `ui-verification` | UI 还原验收 | - |
+| `execute-task` | Superpowers 四步循环执行 | `12-Superpowers执行规范` |
+| `project-init` | 自动分析项目生成 01/03，并在自定义规则缺失时补生成 04/05/06/07/09 | - |
+| `install-ai-spec-auto` | 在当前项目自动执行 ai-spec-auto init 安装，并完成安装前检查与安装后自检 | - |
+| `using-superpowers` | 技能调度核心规范 | - |
+| `find-skills` | 查找开源 skills | - |
+| `skill-creator` | 创建 skill 指导 | - |
+| `skill-optimizer` | 审查与优化现有 skill | - |
+| `web-design-guidelines` | 网页设计指导 | - |
+
+## profiles/react/ — React 技术栈技能
+
+| 技能 | 用途 | 配合规范 |
+|------|------|----------|
+| `create-component` | 创建 TSX 组件 + SCSS Modules | `04-组件规范` |
+| `create-route` | 创建 Page/Loader 路由 | `06-路由规范` |
+| `create-store` | 创建 Zustand Store | `07-状态管理` |
+| `create-api` | 创建 HTTP 接口封装 | `05-API规范` |
+| `theme-variables` | Antd 主题 CSS 变量使用 | `09-样式规范` |
+| `vercel-react-best-practices` | React 最佳实践 | - |
+| `vercel-composition-patterns` | React 复合组件模式 | - |
+
+## profiles/vue/ — Vue 技术栈技能
+
+| 技能 | 用途 | 配合规范 |
+|------|------|----------|
+| `create-component` | 创建 SFC 组件 | `04-组件规范` |
+| `create-view` | 创建 Vue 页面模块 | `03-项目结构` |
+| `create-route` | 创建 Vue 路由模块与入口注册 | `06-路由规范` |
+| `create-store` | 创建 Pinia Store | `07-状态管理` |
+| `create-api` | 创建 API 接口封装 | `05-API规范` |
+| `theme-variables` | 组件库主题 token 使用 | `09-样式规范` |
+
+## domains/ — 按能力域沉淀的可复用技能（可选）
+
+这里的 `domains（能力域）` 是一种**分类和复用标签**，也是 `sync（同步）` 与 `Hub（平台）` 识别能力域 skill 的正式目录结构。
+
+| 技能 | 用途 | 配合规范 |
+|------|------|----------|
+| `ui-ux-pro-max` | 设计协作专家专用的 UI/UX 设计决策能力，可选安装完整版资源 | - |
+
+只有在某个 skill 同时满足下面两个条件时，才建议放到 `domains/`：
+
+- 明显属于某个能力域，例如性能、安全、可观测性
+- 会被多个专家复用，而不是只服务某一个专家
+
+例如未来可能出现：
+
+- `domains/demand-design/ui-ux-pro-max`
+- `domains/performance/lighthouse-audit`
+- `domains/observability/sentry-triage`
+- `domains/security-a11y/security-review`
+
+## 为什么不建议用 `skills/<expert-name>/`
+
+因为 expert 和 skill 的关系是多对多：
+
+- 一个专家会调用多个 skill
+- 一个 skill 也会被多个专家复用
+
+如果按专家名组织 skill，后续会很快出现重复和耦合：
+
+- `frontend-implementer/create-api`
+- `code-guardian/create-test`
+- `performance-expert/create-test`
+
+这种结构很难维护，也不利于后续插件页面做聚合展示。
+
+如果当前阶段一定要采用 `skills/<expert-id>/`，建议至少补充：
+
+- `skill（技能）` 的 `owner_role（归属专家）`
+- `role（专家角色）` 的 `domains（能力域）`
+
+这样 `sync（同步）` 才能通过元数据做本地聚合，而不是靠目录猜。
+
+---
+
+## 快速查找（按场景选择技能）
+
+| 场景 | 技能文件 |
+|------|----------|
+| 创建提案时 | `.agents/skills/common/create-proposal/SKILL.md`（前置分析后委托 `/opsx:propose`） |
+| 归档变更时 | `.agents/skills/common/archive-change/SKILL.md`（规范合并 + 归档校验） |
+| 新增接口 | `.agents/skills/profiles/<stack>/create-api/SKILL.md` |
+| 创建/拆分组件 | `.agents/skills/profiles/<stack>/create-component/SKILL.md` |
+| 新增页面路由 | React 用 `.agents/skills/profiles/react/create-route/SKILL.md`；Vue 用 `.agents/skills/profiles/vue/create-route/SKILL.md` |
+| 新增全局状态 | `.agents/skills/profiles/<stack>/create-store/SKILL.md` |
+| 编写样式/主题适配 | `.agents/skills/profiles/<stack>/theme-variables/SKILL.md` |
+| 开始执行 tasks.md | `.agents/skills/common/execute-task/SKILL.md` |
+| 分析设计稿 | `.agents/skills/common/design-analysis/SKILL.md` |
+| 做 Figma 解析、标注提取和 UI 设计决策 | `.agents/skills/domains/ui-ux-pro-max/SKILL.md`（设计协作专家专用，可选安装完整版资源） |
+| UI 还原验收 | `.agents/skills/common/ui-verification/SKILL.md` |
+| 扫描敏感信息 / 统一配置规范 | `.agents/skills/common/config-and-secret-scan/SKILL.md` |
+| 核对路由、菜单和权限 | `.agents/skills/common/route-permission-map/SKILL.md` |
+| 评估包或模块改动影响 | `.agents/skills/common/dependency-impact-graph/SKILL.md` |
+| 安装 ai-spec-auto 到当前项目 | `.agents/skills/common/install-ai-spec-auto/SKILL.md` |
+| 初始化项目规范 | `.agents/skills/common/project-init/SKILL.md` |
+| 每次对话启动的技能调度 | `.agents/skills/common/using-superpowers/SKILL.md` |
+| 优化现有 skill | `.agents/skills/common/skill-optimizer/SKILL.md` |
+
+## 使用说明
+
+项目在 `.agents/skills` 下定义了与规范配套的技能，用于承载具体实践步骤与示例代码，避免在规范中塞入过多细节。后续如有新的实践场景，建议以新的技能目录形式补充。
+
+## 当前项目的推荐组织方式
+
+- 与技术栈无关的 skill 放 `common/`
+- 与 React / Vue 强绑定的 skill 放 `profiles/react/`、`profiles/vue/`
+- 与设计、安全、性能、可观测等能力域强绑定，且需要被专家链按能力域识别的 skill，放 `domains/`
+
+当前阶段先保持：
+
+```text
+.agents/skills/
+├── common/
+├── domains/
+├── profiles/react/
+└── profiles/vue/
+```

package/.agents/skills/common/archive-change/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: archive-change
+description: 当用户执行 `/opsx:archive`、`/opsx-archive` 或要求归档当前 OpenSpec 变更时，校验归档前置条件、合并增量规范并输出归档摘要。
+compatibility: Requires an OpenSpec workspace with openspec/changes/, the local ai-spec-auto archive-change command, and repository write access for spec/archive updates.
+---
+
+# 归档变更（OpenSpec 增强层）
+
+## 定位
+
+本技能是 OpenSpec `/opsx:archive` 的**增强层**，确保归档流程中规范合并和目录操作的正确性。
+
+职责划分：
+
+| 层 | 职责 | 产物位置 |
+|----|------|----------|
+| **本技能** | 规范合并 + 目录创建 + 路径校验 + 摘要输出 | `openspec/specs/` |
+| **OpenSpec** | 归档命令调度、产物完整性检查 | `openspec/changes/archive/` |
+| **config.yaml** | 桥接 ai-spec-auto  规范到 OpenSpec rules | `openspec/config.yaml` |
+
+## 使用时机
+
+当用户执行以下操作时触发：
+
+- `/opsx:archive`
+- `/opsx-archive`
+- "归档变更"
+- "归档当前变更"
+
+优先执行命令：
+
+```bash
+./node_modules/.bin/ai-spec-auto archive-change --target . --change-id <name> --complete-run --json
+```
+
+除非该命令不可用，否则不要手工执行 `mkdir`、`cp`、`mv` 去合并或迁移目录。
+该命令成功后会直接完成运行收尾；不要再手工补 `runtime-state complete`，也不要额外执行 `protocol-advance`。
+
+## 环境依赖
+
+- 需要本地存在 `openspec/changes/<change-id>/` 与 `openspec/specs/`
+- 默认依赖 `ai-spec-auto archive-change` 命令而不是手工目录操作
+- 会引用仓库内的 OpenSpec 与 `.agents/rules` 约束，不适合作为脱离仓库的通用归档 skill
+
+## 归档前核对清单
+
+- [ ] 变更目录和关键文档齐全
+- [ ] `tasks.md` 完成状态已核对
+- [ ] 已确认优先使用 `ai-spec-auto archive-change`
+
+---
+
+## 步骤 1：归档前检查
+
+确认变更目录完整性：
+
+| 检查项 | 路径 | 必须存在 |
+|--------|------|----------|
+| 变更元数据 | `openspec/changes/<name>/.openspec.yaml` | 是 |
+| 提案文档 | `openspec/changes/<name>/proposal.md` | 是 |
+| 增量规范 | `openspec/changes/<name>/specs/` | 是 |
+| 技术设计 | `openspec/changes/<name>/design.md` | 是 |
+| 任务清单 | `openspec/changes/<name>/tasks.md` | 是 |
+
+检查 `tasks.md` 中的任务完成状态：
+
+- 全部完成 `[x]` → 正常归档
+- 存在未完成 `[ ]` → 警告但不阻止，输出未完成任务列表
+
+---
+
+## 步骤 2：合并增量规范到 openspec/specs/
+
+**这是最关键的步骤，必须严格执行。**
+
+### 2.1 确保目标目录存在
+
+```text
+openspec/specs/ 不存在 → 创建目录
+```
+
+### 2.2 遍历增量规范
+
+遍历 `openspec/changes/<name>/specs/` 下的每个域目录：
+
+```text
+openspec/changes/<name>/specs/
+├── ui/
+│   └── component-name.spec.md
+├── api/
+│   └── endpoint-name.spec.md
+└── ...
+```
+
+### 2.3 按域合并
+
+对每个 `<domain>/` 目录：
+
+1. 检查 `openspec/specs/<domain>/` 是否存在，不存在则**创建**
+2. 将增量规范文件**复制**到 `openspec/specs/<domain>/`
+3. 如果目标已存在同名 spec 文件：更新内容（保留未涉及的 capability），不覆盖
+
+### 2.4 合并示例
+
+变更前：
+
+```text
+openspec/
+├── specs/                          ← 可能不存在，需创建
+└── changes/
+    └── add-button-global-component/
+        └── specs/
+            └── ui/
+                └── app-button.spec.md
+```
+
+合并后：
+
+```text
+openspec/
+├── specs/
+│   └── ui/                         ← 新建域目录
+│       └── app-button.spec.md      ← 从增量规范复制
+└── changes/
+    └── archive/
+        └── 2026-03-23-add-button-global-component/
+            └── ...                  ← 归档后的完整变更
+```
+
+---
+
+## 步骤 3：归档变更目录
+
+将变更目录移动到**正确的归档路径**：
+
+```text
+源：openspec/changes/<name>/
+目标：openspec/changes/archive/YYYY-MM-DD-<name>/
+```
+
+**注意路径**：归档目录是 `openspec/changes/archive/`，**不是** `openspec/archive/`。
+
+确保 `openspec/changes/archive/` 目录存在，不存在则创建。
+
+---
+
+## 步骤 4：输出合并摘要
+
+归档完成后，输出以下摘要信息：
+
+```text
+归档摘要：
+- 变更名称：<name>
+- 归档路径：openspec/changes/archive/YYYY-MM-DD-<name>/
+- 规范合并：
+  - 新增域：<列出新增的 domain 目录>
+  - 新增规范：<列出新增的 spec 文件>
+  - 更新规范：<列出已存在并被更新的 spec 文件>
+- 任务完成状态：N/M 已完成
+```
+
+---
+
+## 常见错误与防范
+
+| 错误 | 正确做法 |
+|------|----------|
+| 归档到 `openspec/archive/` | 归档到 `openspec/changes/archive/YYYY-MM-DD-<name>/` |
+| 跳过规范合并直接归档 | 必须先合并到 `openspec/specs/` 再归档 |
+| `openspec/specs/` 不存在时跳过合并 | 不存在则创建目录，然后合并 |
+| 覆盖已有规范 | 已有同名 spec 时合并内容，保留未涉及的 capability |
+
+---
+
+## 相关规范与技能
+
+- `openspec/config.yaml` — archive rules 定义归档规则
+- `.agents/skills/create-proposal/SKILL.md` — 提案前置分析（上游流程）
+- `.agents/skills/execute-task/SKILL.md` — 任务执行（上游流程）
+- `docs/openspec-guide.md` — OpenSpec 完整工作流说明