@vthst/page-manual 1.0.0

package/README.md

@@ -0,0 +1,65 @@
+# @vthst/page-manual
+
+Claude Code skill：给 Vue 页面生成 PageGuide 帮助文档。
+
+> 按 [docs/page-guide-template.md 八章模板](./skill/docs/page-guide-template.md) 自动产出「功能说明 / 前置条件 / 页面入口 / 操作指南 / 状态说明 / 注意事项 / 常见问题 / 版本记录」八章内容，并附带「操作步骤」tab 静态步骤列表。
+
+## 支持范围
+
+- Vue 3 + vue-router 项目
+- UI 库：ant-design-vue / element-plus / naive-ui（按优先级自动检测）
+- 输入形态：
+  - `.vue` 文件相对路径（`src/views/Foo.vue`）
+  - 路由 path（`/user/profile`）
+  - 完整 URL（`http://localhost:5173/user/profile`）
+  - pageKey（`user-profile`）
+
+## 安装
+
+```bash
+npm i -g @vthst/page-manual
+```
+
+安装脚本会自动把 skill 复制到 `~/.claude/skills/page-manual/`。
+
+> ⚠️ **安装后请重启 Claude Code**，重启后才能识别新 skill。
+
+## 使用
+
+在任意 Vue 项目根目录运行：
+
+```
+/page-manual src/views/UserProfile.vue
+/page-manual /user/profile
+/page-manual http://localhost:5173/user/profile
+```
+
+多个目标用空格分隔：
+
+```
+/page-manual src/views/Foo.vue src/views/Bar.vue
+```
+
+## 卸载
+
+```bash
+npm uninstall -g @vthst/page-manual
+# 或直接调 CLI（无需走 npm）
+page-manual uninstall
+# 手动删也可以
+rm -rf ~/.claude/skills/page-manual
+```
+
+## 要求
+
+- Node.js ≥ 16.7（需要 `fs.cpSync` 原生支持）
+- Claude Code（最新稳定版）
+- 目标 Vue 项目已安装 `vue-router` + `ant-design-vue` / `element-plus` / `naive-ui` 之一
+
+## 工作流程
+
+参见 [SKILL.md](./skill/SKILL.md)。
+
+## License
+
+MIT

package/cli.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * page-manual CLI 入口
+ * 提供 install / uninstall / check / update 子命令
+ */
+const { install, uninstall, check } = require('./install')
+
+const [, , cmd = 'help'] = process.argv
+
+if (cmd === 'help' || cmd === '-h' || cmd === '--help') {
+  console.log(`
+page-manual - Claude Code skill 安装管理工具
+
+用法：
+  page-manual [命令]
+
+命令：
+  install     安装/重新安装 skill 到 ~/.claude/skills/page-manual/
+  uninstall   卸载（删除 skill 目录）
+  check       检查是否已安装
+  update      卸载后重新安装（用于升级）
+  help        显示此帮助（默认）
+
+示例：
+  page-manual install
+  page-manual uninstall
+  page-manual check
+
+安装完成后重启 Claude Code 即可使用 /page-manual 命令。
+`)
+  process.exit(0)
+}
+
+switch (cmd) {
+  case 'install':
+    install()
+    break
+  case 'uninstall':
+    uninstall()
+    break
+  case 'check':
+    process.exit(check() ? 0 : 1)
+    break
+  case 'update':
+    uninstall()
+    install()
+    break
+  default:
+    console.error(`❌ 未知命令: ${cmd}`)
+    console.error(`运行 'page-manual help' 查看用法`)
+    process.exit(1)
+}

package/install.js

@@ -0,0 +1,68 @@
+/**
+ * page-manual skill 安装/卸载核心逻辑
+ * - 既可被 cli.js 调用
+ * - 也可被 postinstall 直接调用（node install.js install）
+ */
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+
+const SKILL_NAME = 'page-manual'
+const SRC = path.join(__dirname, 'skill')
+const DEST_DIR = path.join(os.homedir(), '.claude', 'skills')
+const DEST = path.join(DEST_DIR, SKILL_NAME)
+
+function install() {
+  if (!fs.existsSync(path.join(SRC, 'SKILL.md'))) {
+    console.error(`❌ 源目录缺失 SKILL.md，npm 包可能损坏`)
+    process.exit(1)
+  }
+  fs.mkdirSync(DEST_DIR, { recursive: true })
+  fs.rmSync(DEST, { recursive: true, force: true })
+  fs.cpSync(SRC, DEST, { recursive: true })
+  console.log(``)
+  console.log(`✅ ${SKILL_NAME} skill 已安装到：${DEST}`)
+  console.log(``)
+  console.log(`   👉 重启 Claude Code 后即可使用 /page-manual 命令`)
+  console.log(``)
+  console.log(`   用法示例：`)
+  console.log(`     /page-manual src/views/UserProfile.vue`)
+  console.log(`     /page-manual /user/profile`)
+  console.log(`     /page-manual http://localhost:5173/user/profile`)
+  console.log(``)
+}
+
+function uninstall() {
+  if (fs.existsSync(DEST)) {
+    fs.rmSync(DEST, { recursive: true, force: true })
+    console.log(`✅ ${SKILL_NAME} 已卸载`)
+  } else {
+    console.log(`⚠ ${SKILL_NAME} 未安装，无需卸载`)
+  }
+}
+
+function check() {
+  return fs.existsSync(path.join(DEST, 'SKILL.md'))
+}
+
+module.exports = { install, uninstall, check, DEST, SKILL_NAME }
+
+// 被直接执行时（postinstall 或手动 node install.js）按 argv 分发
+if (require.main === module) {
+  const [, , cmd = 'install'] = process.argv
+  if (cmd === 'install') install()
+  else if (cmd === 'uninstall') uninstall()
+  else if (cmd === 'check') {
+    if (check()) {
+      console.log(`✅ ${SKILL_NAME} 已安装：${DEST}`)
+      process.exit(0)
+    } else {
+      console.log(`❌ ${SKILL_NAME} 未安装`)
+      process.exit(1)
+    }
+  }
+  else if (cmd === 'update') { uninstall(); install() }
+  else {
+    console.log(`用法：node install.js [install|uninstall|check|update]`)
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@vthst/page-manual",
+  "version": "1.0.0",
+  "description": "Claude Code skill: 给 Vue 页面生成 PageGuide 帮助文档（支持 ant-design-vue / element-plus / naive-ui）",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16.7"
+  },
+  "bin": {
+    "page-manual": "./cli.js"
+  },
+  "files": [
+    "skill/",
+    "cli.js",
+    "install.js",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node cli.js install",
+    "prepublishOnly": "node cli.js check",
+    "test": "node cli.js check"
+  },
+  "keywords": [
+    "claude-code",
+    "skill",
+    "vue",
+    "page-guide",
+    "documentation"
+  ],
+  "author": "",
+  "repository": {
+    "type": "git",
+    "url": ""
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: page-manual
+description: Use when generating a page help document (PageGuide 帮助文档) for a specified Vue page. Triggers on requests like "给 XX 写帮助文档", "/page-manual <文件路径>", "按八章模板给这个页面做 manual 文档". 仅支持含 vue-router + 三大 UI 库（ant-design-vue / element-plus / naive-ui）之一的 Vue 项目。
+argument-hint: <页面 .vue 文件的相对路径 / 路由路径 / 完整 URL>
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash
+---
+
+# 任务：给 Vue 页面「$ARGUMENTS」生成页面操作手册（PageGuide 帮助文档）
+
+## 第 0 步：参数校验
+
+**$ARGUMENTS 为空时直接终止**，回复：
+
+> 请指定目标页面：`/page-manual <页面 .vue 文件的相对路径>`
+> 例：`/page-manual src/views/Home.vue` 或 `/page-manual src/views/UserProfile.vue`
+
+禁止：拿空参数瞎猜页面开工、列页面清单引导挑选、静默继续后续步骤。
+
+---
+
+## 第一步：探测项目环境（按顺序检查，任一不通过即终止）
+
+### 1.1 路由检查
+
+读取 `<cwd>/package.json` 的 `dependencies` + `devDependencies`，**必须含 `vue-router`**。
+
+**未通过时终止**：
+
+> ❌ 未检测到 `vue-router`。page-manual skill 需要路由型 Vue 项目（依赖 vue-router 定位目标页面）。
+
+### 1.2 UI 库检测（按优先级，第一个匹配就用）
+
+读取同一 `package.json`，**按以下顺序匹配**，第一个命中的就是目标 UI 库：
+
+| 优先级 | 检测依赖 | 使用组件文件 | 配套图标库 |
+|---|---|---|---|
+| 1 | `ant-design-vue` | `src/components/PageGuide.antd.vue` | `@ant-design/icons-vue` |
+| 2 | `element-plus` | `src/components/PageGuide.element-plus.vue` | `@element-plus/icons-vue` |
+| 3 | `naive-ui` | `src/components/PageGuide.naive-ui.vue` | `@vicons/ionicons5`（或项目已有的 xicons） |
+
+**全部未通过时终止**：
+
+> ❌ 未检测到支持的 UI 库（ant-design-vue / element-plus / naive-ui）。page-manual skill 当前仅支持这三种。如需扩展请编辑本 SKILL.md 的「1.2 UI 库检测」段。
+
+**全部通过时记录到上下文**（后续步骤用）：
+
+```
+已检测 UI 库：<ant-design-vue | element-plus | naive-ui>
+将使用组件：src/components/PageGuide.<antd|element-plus|naive-ui>.vue
+组件引用名：<PageGuide>
+```
+
+### 1.3 图标库检查（按 1.2 命中结果，检查配套图标库）
+
+缺失时**警告但不停**：
+
+> ⚠ 检测到 `<UI 库>` 但缺配套图标库 `<icon 库>`。PageGuide 组件内的图标无法渲染，请 `npm i <icon 库>` 补装后重新执行。
+
+---
+
+## 第二步：读模板（必读，不读不准动笔）
+
+完整 Read 桌面 SKILL 同目录下的 `docs/page-guide-template.md` —— 八章结构、gd-* 类库、写作约定的唯一权威来源。
+
+**没找到时终止**：
+
+> ❌ 找不到模板文件 `<skill 目录>/docs/page-guide-template.md`。请确认本 skill 目录结构完整。
+
+---
+
+## 第三步：定位并通读目标页面（内容必须来自真实代码，禁止编造）
+
+### 3.0 输入形态识别（决定走 3.1 还是 3.2）
+
+按以下规则分流 `$ARGUMENTS`：
+
+| 形态 | 判定 | 后续步骤 |
+|---|---|---|
+| **文件路径** | 以 `.vue` 结尾（如 `src/views/Foo.vue`） | 走 3.2 文件路径模式 |
+| **完整 URL** | 以 `http://` 或 `https://` 开头 | 提取 pathname → 走 3.1 路由模式 |
+| **路由 path / pageKey** | 其他（以 `/` 开头 / 不含扩展名的字符串） | 走 3.1 路由模式 |
+
+### 3.1 路由模式（完整 URL / 路由 path / pageKey）
+
+**目标**：从项目 router 配置里反查 `path → component → .vue 文件路径`，找到后跳回 3.2 文件模式。
+
+1. **规范化输入**：
+   - 完整 URL（如 `http://localhost:3600/app-page/foo?x=1`）→ 提取 `pathname`（`/app-page/foo`）+ 去掉查询参数 / 锚点
+   - 以 `/` 开头（如 `/app-page/foo`）→ 去掉首尾 `/`
+   - 不含 `/`（如 `aps-foo`，pageKey 形态）→ 整段作为查找 key
+
+2. **找路由配置文件**（按顺序 Glob，任一命中即停）：
+   ```
+   src/router/index.{js,ts}
+   src/router/{router,routes}.{js,ts}
+   src/router/routes/**/*.{js,ts}
+   src/**/router/index.{js,ts}    # 兜底
+   ```
+   全部未命中 → 反问用户要 .vue 路径，**不要猜测**
+
+3. **Read 路由文件，匹配 path**：
+   - 递归展开嵌套 `children`
+   - 匹配优先级：精确匹配 → 去首尾 `/` 全等 → 路径段数相同 + 末段相等
+   - 动态路由参数 `:id` 段转正则通配后再匹配
+
+4. **提取 component**（按以下形态识别）：
+   ```js
+   // 字符串形式
+   { path: '/foo', component: 'Foo' }
+   { path: '/foo', component: '@/views/Foo.vue' }
+
+   // 动态 import
+   { path: '/foo', component: () => import('@/views/Foo.vue') }
+
+   // 普通 import（需在 routes 文件上方找 import 块）
+   import Foo from '@/views/Foo.vue'
+   { path: '/foo', component: Foo }
+   ```
+
+5. **拼 .vue 路径**（处理 `@/` 别名）：
+   - Read `vite.config.{js,ts}` 找 `resolve.alias['@']`（通常 `src/`）
+   - `@/views/Foo.vue` → `src/views/Foo.vue`
+   - 没有 `@` 别名 → 按 `src/views/<PascalCase>.vue` 推断 + Glob 确认
+
+6. **找不到时兜底**：
+   - Grep `<pageKey>` 在 `src/` 搜（匹配文件名 / 注释 / 字符串）
+   - 仍找不到 → 反问用户要 .vue 路径
+
+7. **拿到 .vue 路径后**：把 `$ARGUMENTS` 替换为该路径，跳回 3.2 文件模式继续
+
+### 3.2 文件路径模式（$ARGUMENTS 以 .vue 结尾 / 3.1 路由解析后）
+
+1. `$ARGUMENTS` 即 .vue 文件相对路径（如 `src/views/UserProfile.vue`），Glob 确认存在
+2. 找不到时 Glob 同名模糊匹配（同名 .vue 不分大小写、子目录遍历），仍无则反问用户
+3. **多目标拆分**：若用户提供的是多个目标（空格分隔），每个目标独立走完第三～六步全流程后再开始下一个
+4. 通读该页面代码，提取真实信息：
+   - 搜索区字段、按钮行按钮、表格列、弹窗表单字段（含必填项）
+   - Tab / 子表 / 展开行等页面结构
+   - 状态枚举（select options / 字典映射）、行内编辑等特殊交互
+   - 导入 / 导出 / 删除 / 审批等操作的真实行为
+5. 涉及上下游依赖的（如物料主数据联想），从代码注释或接口调用推断并在前置条件中说明
+
+---
+
+## 第四步：接入 PageGuide 组件
+
+1. **复制组件文件**：把 `src/components/PageGuide.<antd|element-plus|naive-ui>.vue` 整文件复制到目标项目 `src/components/PageGuide.vue`（或项目约定的组件子目录）
+2. **挂组件**：button-bar 末尾（其他操作按钮之后）挂 `<PageGuide>`；页面没有按钮行（纯查询/看板页）时，补一个只含 PageGuide 的空壳 `<div class="button-bar">`
+3. **截图规划**：截图按 `<项目 public 目录>/guide-images/<模块>/<子模块>/<页面key>/` 规划，文档内先写 `<a-image>` / `<el-image>` / `<n-image>`（按 1.2 命中 UI 库）+ `gd-fig-cap` 占位
+
+---
+
+## 第五步：写八章内容（结构照抄模板，逐章替换为本页真实内容）
+
+八章固定顺序固定标题，不得增删改名；本页没有的章保留标题 + 一句说明。
+版本记录起版 v1.0，日期用今天，编写人固定「管理员」。
+提示框统一 `<div class="gd-callout">`，没有 info/warn/success/danger 变体类，语义靠标题文案区分。
+行内标签用 `gd-tag-must` / `gd-tag-opt` / `gd-tag-role`（红/蓝/黄语义色）。
+图注「图 N　说明」全篇连续编号。
+
+---
+
+## 第六步：自检
+
+1. 对照模板「写作约定」逐条过一遍（编号、加粗、图注连续编号等）
+2. **没有自动化截图脚本**：本 skill 不附带项目截图脚本（不绑死具体项目）。截图由用户在 dev 环境手动 / 各自项目的截图工具完成；如本项目已有截图工具，提示用户接入；如没有，提醒用户人工补图
+3. 提醒用户：刷新页面点「帮助文档」验收（左侧目录 + 全文搜索 + 操作步骤列表 + 截图显示）

package/skill/docs/page-guide-template.md

@@ -0,0 +1,190 @@
+# 页面帮助文档标准模板（照抄骨架，只换内容）
+
+> **用途**：给任何页面写帮助文档时，直接复制本模板的骨架到该页面的 `<PageGuide>` `#doc` 插槽里，替换成该页面的内容。
+> **结构要求**：八章**固定顺序、固定标题、不得增删改名**；某章确实没有内容时保留标题 + 一句说明（如「本页无状态枚举字段」），保证所有页面的左侧目录长得一样。
+> **样板页**：`src/views/aps-pages/basic-data/ToolingInfo.vue`（工装信息）——第一份按本模板落地的完整文档，拿不准就翻它。
+
+---
+
+## 一、接入三步（页面侧）
+
+### 1. 挂组件（button-bar 末尾，SettingsPopover 之后）
+
+```vue
+<SettingsPopover ... />
+<!-- 页面帮助：左侧抽屉（左侧目录 + 全文搜索 + 八章正文） -->
+<PageGuide>
+  <template #doc>
+    <!-- ===== 一、功能说明 ===== -->
+    <div class="gd-sec-title" data-toc>一、功能说明</div>
+    ...（八章内容，见下方骨架）...
+  </template>
+</PageGuide>
+```
+
+**页面没有按钮行时**（纯查询 / 看板页，没有新增导入导出）：补一个只含 PageGuide 的空壳 button-bar，
+按钮靠右靠组件内 `margin-left:auto`，视觉与有按钮行的页面一致（表格卡右上角）：
+
+```vue
+<div class="button-bar">
+  <PageGuide>
+    <template #doc> ... </template>
+  </PageGuide>
+</div>
+```
+
+### 2. 截图放公共目录
+
+`public/guide-images/<模块>/<子模块>/<页面key>/xxx.png`，
+如 `/guide-images/aps/basic-data/tooling-info/search-area.png`。
+图注紧跟图片，全篇「图 1、图 2…」连续编号。
+
+**截图用脚本自动截，不人工补**：文档写完占位后，在 `scripts/capture-guide-images.mjs`
+的 `PAGES` 数组追加该页配置（url + outDir + waitSelector + shots），跑
+`node scripts/capture-guide-images.mjs` 自动登录 dev 环境逐状态截图。
+动作库已备好：`searchArea`（展开搜索栏）/ `settings`(设置面板) / `addModal`（新增弹窗）/
+`importModal`（导入弹窗）。前提：本地 dev server 跑在 `localhost:3600`（或用
+`GUIDE_BASE_URL` 指定）；依赖 `puppeteer-core` 已在 devDependencies，用系统 Edge 无需下载浏览器。
+
+---
+
+## 二、八章骨架（复制后逐章替换内容）
+
+```html
+<!-- ===== 一、功能说明 ===== -->
+<div class="gd-sec-title" data-toc>一、功能说明</div>
+<p>本页是 xx 模块中的<b>yy 模块</b>，集中维护/管理 <b>…</b>，为 … 提供基础数据。</p>
+<table>
+  <thead>
+    <tr><th>操作</th><th>说明</th><th>使用频率</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>查询筛选</td><td>…</td><td>高 / 中 / 低</td></tr>
+    <tr><td>新增 / 编辑</td><td>…</td><td>…</td></tr>
+    <!-- 该页全部主要操作，每行一条 -->
+  </tbody>
+</table>
+
+<!-- ===== 二、前置条件 ===== -->
+<div class="gd-sec-title" data-toc>二、前置条件</div>
+<ul>
+  <li>已登录平台，并拥有<b>xx</b>菜单的访问权限</li>
+  <li>依赖的上下游数据（如物料主数据）需已维护</li>
+</ul>
+<div class="gd-callout">
+  <div class="gd-callout-title">权限说明</div>
+  <p>若应用中心看不到「xx」菜单，请联系系统管理员开通对应角色权限。</p>
+</div>
+
+<!-- ===== 三、页面入口 ===== -->
+<div class="gd-sec-title" data-toc>三、页面入口</div>
+<div class="gd-breadcrumb">一级应用 / 二级菜单 / 页面名</div>
+<p>登录后进入<b>应用中心 → … → …</b>。页面结构说明（Tab / 主表 / 展开子表等）：</p>
+<ul>
+  <li><b>xx</b>：…</li>
+</ul>
+<p><b>搜索栏</b>：…（展开/收起行为、字段联动等）</p>
+<a-image width="100%" src="/guide-images/<模块>/<子模块>/<页面>/search-area.png" />
+<div class="gd-fig-cap">图 1　搜索栏</div>
+<p><b>设置</b>：按钮行末尾的齿轮按钮，可切行高 / 列显隐 / 列顺序，配置自动记忆。</p>
+<p><b>帮助文档</b>：按钮行最右侧的「帮助文档」按钮即本文档。</p>
+
+<!-- ===== 四、操作指南 ===== -->
+<div class="gd-sec-title" data-toc>四、操作指南</div>
+<!-- 每个操作一张 gd-op 卡片；操作少的页面 2 张，多的 6-8 张，按使用频率排序 -->
+<div class="gd-op">
+  <div class="gd-op-title" data-toc data-toc-sub>操作 1：查询筛选</div>
+  <div class="gd-op-goal">目标：…</div>
+  <div class="gd-step">
+    <span class="gd-step-num">1</span>
+    <div class="gd-step-body">
+      <div class="gd-step-title">步骤名</div>
+      <p>步骤说明，字段名用 <b>加粗</b>。</p>
+    </div>
+  </div>
+  <!-- 更多步骤…（1 步也行，3-4 步常见） -->
+  <!-- 可选：截图 + 图注 -->
+  <a-image width="100%" src="/guide-images/.../add-modal.png" />
+  <div class="gd-fig-cap">图 2　新增弹窗</div>
+  <!-- 可选：提示框（统一主题色，语义靠标题文案区分：操作结果 / 注意 / 危险操作等） -->
+  <div class="gd-callout">
+    <div class="gd-callout-title">操作结果</div>
+    <p>…</p>
+  </div>
+</div>
+<!-- 操作 2：新增 / 编辑；操作 3：批量导入（有才写）；操作 4：导出；操作 5：删除；
+     操作 6+：该页特有操作（如穴明细维护）。无导入/导出的页面跳过对应卡片，编号顺延 -->
+
+<!-- ===== 五、状态说明 ===== -->
+<div class="gd-sec-title" data-toc>五、状态说明</div>
+<p><b>xx 状态</b>（弹窗「状态」下拉项）：</p>
+<table>
+  <thead>
+    <tr><th>状态</th><th>含义</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>…</td><td>…</td></tr>
+  </tbody>
+</table>
+<!-- 有几组枚举写几组（每组一张表）；页面无状态枚举时写：本页无状态枚举字段 -->
+
+<!-- ===== 六、注意事项 ===== -->
+<div class="gd-sec-title" data-toc>六、注意事项</div>
+<ul>
+  <li>排序 / 筛选 / 列设置等通用交互提示</li>
+  <li>默认值 / 联动行为等易踩坑点</li>
+  <li>数据依赖提醒（联想为空 → 主数据未维护等）</li>
+</ul>
+
+<!-- ===== 七、常见问题 ===== -->
+<div class="gd-sec-title" data-toc>七、常见问题</div>
+<table>
+  <thead>
+    <tr><th style="width: 40%">问题</th><th>解决方式</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>…现象…</td><td>…原因 + 解决办法…</td></tr>
+  </tbody>
+</table>
+
+<!-- ===== 八、版本记录 ===== -->
+<div class="gd-sec-title" data-toc>八、版本记录</div>
+<table>
+  <thead>
+    <tr><th>版本</th><th>日期</th><th>变更内容</th><th>编写人</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>v1.0</td><td>2026-XX-XX</td><td>初版：xx操作文档</td><td>管理员</td></tr>
+  </tbody>
+</table>
+<!-- 后续文档有实质变更时加行：v1.1 / 日期 / 变更点 / 管理员；编写人固定写「管理员」 -->
+```
+
+---
+
+## 三、gd-* 类库速查（样式都在 PageGuide.vue，页面直接用类名）
+
+| 类名 | 用在 | 说明 |
+|---|---|---|
+| `gd-sec-title` + `data-toc` | 八章标题 | 一级目录（左侧 TOC 自动收集） |
+| `gd-op` | 操作卡片容器 | 一张卡片 = 一个操作 |
+| `gd-op-title` + `data-toc data-toc-sub` | 卡片标题 | 二级目录，命名格式固定「操作 N：xxx」 |
+| `gd-op-goal` | 卡片目标行 | 固定格式「目标：…」 |
+| `gd-step` / `gd-step-num` / `gd-step-title` | 步骤行 | 圆号自动编号数字手写 1/2/3 |
+| `gd-callout` | 提示框 | 统一主题色；语义靠 `gd-callout-title` 文案区分（权限说明 / 操作结果 / 注意 / 危险操作等） |
+| `gd-callout-title` | 提示框标题 | 常用文案：说明 / 注意 / 操作结果 / 危险操作 / 权限说明 |
+| `gd-tag-must` / `gd-tag-opt` / `gd-tag-role` | 行内标签 | 必填（红）/ 选填（蓝）/ 角色（黄），用在字段表格里 |
+| `gd-fig-cap` | 图注 | 紧跟 a-image，格式「图 N　说明」，全篇连续编号 |
+| `gd-breadcrumb` | 菜单路径 | 第三章开头，格式「应用 / 菜单 / 页面」 |
+| `<table>`（原生） | 各类表格 | 自带边框 / 灰表头 / 斑马纹，直接写 thead/tbody |
+| `<code>`（原生） | 行内代码 | 编码 / 路径片段 |
+
+## 四、写作约定（保持全站一致）
+
+1. **章节编号用中文数字**（一、二、…八、），标题格式「N、名称」，八章不得改名
+2. **操作卡片编号**「操作 1：…」从 1 连续编号；该页没有的操作（如无导入）直接跳过，后面的编号顺延
+3. **字段名、按钮名用 `<b>` 加粗**，与正文区分；按钮文案带「」引号，如点「查询」
+4. **截图先写完文档再截**：先留 a-image + 图注占位，再在 `scripts/capture-guide-images.mjs` 的 `PAGES` 加配置跑脚本，产物落 `public/guide-images/<模块>/<子模块>/<页面key>/`
+5. **版本记录起版 v1.0**，日期写实际发布日，编写人固定「管理员」
+6. **使用频率三档**：高（每天用）/ 中（每周用）/ 低（偶尔用）
+7. 常见问题表问题列固定 `width: 40%`，两列表头固定「问题 / 解决方式」