web前端给项目加入skills目录，Ai自动查找技能（后端也能参考）

hhemin2026-05-18 11:33

本教学指南旨在帮助初学者快速了解本项目的 AI 技能 (Skills) 体系。通过这套体系，AI 不再是单纯回答问题的聊天助手，而是能严格遵守当前项目规范、并自动执行各种脚手架命令的高级开发伙伴。

📑 目录 (Table of Contents)

  1. 系统目录结构概览
  2. 智能索引系统：INDEX.md
  3. 编辑器触发入口：workflows
  4. 幕后自动化英雄：scripts
  5. [如何编写自定义 Skill](#如何编写自定义 Skill "#5-%E5%A6%82%E4%BD%95%E7%BC%96%E5%86%99%E8%87%AA%E5%AE%9A%E4%B9%89-skill")
  6. 实战教学：多语言翻译智能流水线
  7. 结语

1. 系统目录结构概览

本项目的 AI 驱动力全部隐藏在项目根目录的 .agent/ 文件夹下。在学习任何具体技能之前，你需要先了解这个"三位一体"的目录结构：

text 复制代码 
.agent/
├── skills/          ← 【核心规范区】
│   ├── INDEX.md     ← AI 必读的中央总目录
│   └── translation/ ← 多语言翻译规范
│       └── SKILL.md ← 规范的载体文件
├── scripts/         ← 【自动化引擎】存放驱动 AI 执行的后台 Shell 脚本
│   ├── find-skill.sh  ← 根据关键词自动寻找规范路径
│   └── sync-index.sh  ← 一键扫描并更新 INDEX.md 目录
└── workflows/       ← 【捷径触发器】编辑器中控制 AI 技能的入口
    └── skill.md     ← 响应 "/skill" 命令的工作流

运作逻辑 ：你在编辑器对话框中通过 workflows 发送快捷指令，指令在背后调用 scripts 进行解析与查找，最终精准提取 skills 目录下的特定开发规范供 AI 学习执行。

2. 智能索引系统：INDEX.md

📌 文件路径 ：.agent/skills/INDEX.md

INDEX.md 是整个 AI 系统运作的中枢神经。它相当于一个路牌，告诉 AI："当用户要做 A 类任务时，你应该去 B 路径读取对应的规范"。

💡 新手注意 ：如果你后续新增了任何领域的 Skill，不需要且严禁 手动修改这个表格！所有的目录更新都由后续要讲的 scripts 自动化脚本负责完成。

以下是该文件的完整源码：

markdown 复制代码 
---
name: 项目技能索引 (Skills Index)
description: RobotAdminPlatform 技能目录导航，快速定位各领域 skill。开始任何任务前先读此文件确认使用哪个 skill。
---

# RobotAdminPlatform --- Skills 索引

> 读此文件后，根据任务类型定位对应 skill，再用 `view_file` 读取对应 SKILL.md 获取完整规范。

## 📂 技能目录

<!-- SKILLS_START -->
| 任务类型 | 关键词 | Skill 路径 |
|---|---|---|
| **翻译管理 (Translation Management)** | 翻译、lang、i18n、语言、translation、多语言、词条、同步、zh-cn、git diff | `.agent/skills/translation/SKILL.md` |
| **ui-ux-pro-max** | UI、设计、颜色、布局、design、color、样式、高级、Pro、aesthetic | `.agent/skills/ui-ux-pro-max/SKILL.md` |

<!-- SKILLS_END -->

## 💡 使用规则

1. **先查索引**：任务开始时先读本文件，不要直接猜测或跳过
2. **按需加载**：只 `view_file` 当前任务需要的 skill，不要全部读取
3. **多领域叠加**：一个任务可能涉及多个 skill，分别加载即可

3. 编辑器触发入口：workflows

当你想让 AI 快速进入某种开发状态，又不想长篇大论解释时，你可以通过工作流走捷径。这是我们在编辑器控制特定 Skill 加载的唯一快捷入口。

📌 文件路径 ：.agent/workflows/skill.md

在这个文件中，定义了对 AI 喊出 /skill [关键词] 时的内部执行流。它告诉 AI 不要做盲目的动作，严格按指令搜寻。

以下是该文件的完整源码：

markdown 复制代码 
---
description: 根据关键词快速定位并读取项目 Skill 规范。使用方式: /skill [关键词]
---

// turbo-all
1. 运行辅助脚本查找并返回路径。
   ```bash
   ./.agent/scripts/find-skill.sh [关键词]
   ```
2. 使用 `view_file` 读取该 SKILL.md 文件获取详细规范。

它是如何工作的？ 当你在聊天框输入 /skill 翻译，AI 会瞬间拦截这条命令，在后台执行上方的 Shell 脚本。它不需要你告诉它翻译规范在哪，而是自己把路径查出来，并在一秒钟内完成阅读，进入"懂翻译规范"的形态。

!IMPORTANT\] **workflows 是 Antigravity 编辑器的项目全局配置** 。`workflows/` 目录下的每个 `.md` 文件都对应编辑器中的一条斜杠命令（`/skill`、`/fix` 等）。当用户在对话框输入对应命令时，Antigravity 会自动读取该文件并按其指令驱动 AI 执行------这是整套技能系统的"神经触发点"，连接了用户指令与 scripts 自动化脚本之间的通路。 具体使用的编辑器（如 Cursor、VSCode 插件或 Antigravity 独立客户端）可自行查询对应平台的 workflow 配置文档。

4. 幕后自动化英雄：scripts

AI 能够如此智能且不需要人工维护目录，全靠 .agent/scripts 目录下的自动化脚本。其中最典型的代表是自动更新 Skills 目录的脚本。

📌 文件路径 ：.agent/scripts/sync-index.sh

前文提到你不需要手动维护 INDEX.md，正是因为这个脚本的存在。这体现了"文档即工程"的思维。你只需要专注于编写 Skill 本身的内容，剩下的合并、建表、防冲突工作，都由脚本全自动收尾。

以下是该文件的完整源码：

bash 复制代码 
#!/bin/bash

# RobotAdminPlatform Skill 索引同步脚本
# 功能：扫描所有 SKILL.md，提取元数据并自动更新 INDEX.md 的表格区域。

PROJECT_ROOT=$(pwd)
SKILLS_DIR="$PROJECT_ROOT/.agent/skills"
INDEX_FILE="$SKILLS_DIR/INDEX.md"
TEMP_FILE="$SKILLS_DIR/INDEX.md.tmp"

# 表格头
TABLE_HEADER="| 任务类型 | 关键词 | Skill 路径 |\n|---|---|---|"
TABLE_BODY=""

# 遍历所有子目录下的 SKILL.md
for skill_file in $(find "$SKILLS_DIR" -name "SKILL.md" | sort); do
    # 忽略根目录下的任何潜在文件（虽然目前没有）
    if [[ "$skill_file" == "$INDEX_FILE" ]]; then continue; fi

    # 提取 name 和 keywords
    NAME=$(grep "^name:" "$skill_file" | cut -d':' -f2- | sed 's/^ //')
    KEYWORDS=$(grep "^keywords:" "$skill_file" | cut -d':' -f2- | sed 's/^ //')
    
    # 计算相对路径
    REL_PATH=".agent/skills/${skill_file#$SKILLS_DIR/}"
    
    # 格式化为表格行
    TABLE_BODY="${TABLE_BODY}| **$NAME** | $KEYWORDS | \`$REL_PATH\` |\n"
done

# 使用 sed 替换 INDEX.md 中标记之间的内容
# 注意：Mac 上的 sed 行为略有不同，这里使用临时文件方案更稳健
START_MARKER="<!-- SKILLS_START -->"
END_MARKER="<!-- SKILLS_END -->"

# 构建新的表格内容
NEW_CONTENT="$TABLE_HEADER\n$TABLE_BODY"

# 执行替换逻辑
awk -v start="$START_MARKER" -v end="$END_MARKER" -v content="$NEW_CONTENT" '
    $0 ~ start { print $0; print content; skip = 1; next }
    $0 ~ end { skip = 0 }
    !skip { print $0 }
' "$INDEX_FILE" > "$TEMP_FILE"

mv "$TEMP_FILE" "$INDEX_FILE"

echo "INDEX.md 已成功同步。"

4.2 find-skill.sh --- 关键词路由脚本

📌 文件路径 ：.agent/scripts/find-skill.sh

这个脚本是 /skill 命令能够"即刻命中"目标 Skill 的核心。它接收一个关键词，在 INDEX.md 的表格中进行智能匹配（英文关键词走单词边界匹配，中文关键词走模糊匹配），最终返回对应 SKILL.md 的绝对路径，交由 AI 直接读取。

以下是该文件的完整源码：

bash 复制代码 
#!/bin/bash

# RobotAdminPlatform Skill 路由脚本
# 使用方法: ./find-skill.sh [关键词]

PROJECT_ROOT=$(pwd)
INDEX_FILE="$PROJECT_ROOT/.agent/skills/INDEX.md"

if [ -z "$1" ]; then
    echo "使用方法: $0 [关键词]"
    exit 1
fi

KEYWORD=$1

# 在第一列（任务类型）或第二列（关键词）中严格搜索关键词
# 使用 awk 处理表格列，并根据关键词类型选择匹配策略
RESULT_LINE=$(awk -F'|' -v kw="$KEYWORD" '
    BEGIN {
        # 如果是全英文/数字关键词，则使用单词边界匹配（防止 "UI" 匹配到 "build"）
        # 如果包含中文或其他字符，则使用模糊匹配以增强灵活性
        if (kw ~ /^[a-zA-Z0-9]+$/) {
            pattern = "(^|[^a-zA-Z0-9])" tolower(kw) "([^a-zA-Z0-9]|$)"
        } else {
            pattern = tolower(kw)
        }
    }
    tolower($2) ~ pattern || tolower($3) ~ pattern {
        print $0;
        exit;
    }
' "$INDEX_FILE")

# 从匹配行中提取 Skill 路径（Markdown 表格的第 4 列）
SKILL_PATH=$(echo "$RESULT_LINE" | awk -F'|' '{print $4}' | sed 's/ //g' | sed 's/`//g')

if [ -z "$SKILL_PATH" ]; then
    echo "错误: 未找到与关键词 '$KEYWORD' 匹配的 Skill"
    exit 1
fi

# 如果路径是相对路径，转换为项目绝对路径
if [[ "$SKILL_PATH" == .* ]]; then
    FULL_PATH="$PROJECT_ROOT/${SKILL_PATH#./}"
else
    FULL_PATH="$SKILL_PATH"
fi

echo "$FULL_PATH"

!TIP\] **两个脚本的分工** ：`sync-index.sh` 负责**写** （维护 INDEX.md 目录表格），`find-skill.sh` 负责**读**（根据关键词查路径）。前者是维护工具，后者是运行时工具，两者共同构成 scripts 目录的完整闭环。

5. 如何编写自定义 Skill

Skill 实际上是一个位于 .agent/skills/[技能名称]/SKILL.md 的 Markdown 文件。 不论是多语言翻译、组件库用法、还是 API 封装逻辑，都可以写为一个 Skill。编写的核心步骤如下：

5.1 YAML 元数据要求

为了能被 sync-index.sh 脚本正确抓取，每个 SKILL.md 的最顶部必须包含一段标准的 YAML 前置元数据（Frontmatter）：

yaml 复制代码 
---
name: 你的技能名称 (中英标识)
description: 简短描述这个技能覆盖的场景。
keywords: 触发词1、触发词2、工具、规范
---

5.2 内容编写要点

  1. 指出核心原则与禁忌：强调底线。比如规定「严禁修改 src/lang/，必须修改 project/ 目录」。
  2. 提供标准用法与代码片段：直接贴出在本项目中正确的 Hook 引入方式、函数传参格式等。
  3. 利用高亮提醒块 ：利用 > [!CAUTION], > [!WARNING], > [!TIP] 等 GitHub Alerts 语法对 AI 进行视觉和逻辑上的双重"强约束"。

6. 实战教学：多语言翻译智能流水线 (Translation)

处理具体业务逻辑的 Skill 时，侧重点在于定义标准工作流。

📌 教学文件 ：.agent/skills/translation/SKILL.md

如果没有下述的长篇严密规范，接到"翻译"指令的 AI 会像无头苍蝇一样乱找乱改。但在这个 Skill 中，我们赋予了 AI 机器极其严密的操作流水线，让原本枯燥的"查修改点 -> 找语言包 -> 翻译 -> 粘贴"变成了全自动。

以下是该文件的完整源码：

markdown 复制代码 
---
name: 翻译管理 (Translation Management)
description: 项目 i18n 翻译规范，包含多项目优先级、模块映射、标准用法及长度规范。当被要求「同步翻译」时，AI 应自动通过 git 检测当前 zh-cn 的实际改动，再将差异同步到其他所有语言文件。
keywords: 翻译、lang、i18n、语言、translation、多语言、词条、同步、zh-cn、git diff
---

# 翻译管理 (Translation Management)

## 1. 多项目翻译优先级与运行机制
- **支持语言**: `zh-cn`（基准）→ `en`, `zh-tw`, `ar`, `az`, `de`, `ee`, `el`, `es`, `fr`, `id`, `it`, `ja`, `ko`, `pt`, `ru`, `th`, `tr`, `vi`
- **覆盖逻辑**: 翻译加载顺序为 `Target Project`（如 Ads, HDS）→ `Default`
- **合并规则**: 先加载 `Default` 的基础翻译，再根据当前项目覆盖差异部分
- **运行机制**: 通过 `shell/replace-file.js` 抽取 `project/` 目录下文件覆盖替换 `src/` 目录

> [!CAUTION]
> **严禁直接修改 `src/lang/` 等会被动态替换的目录！**
> 真正的修改必须在 `project/` 对应目录下进行：
> - 通用翻译 → `project/Default/src/lang/`
> - 特定项目翻译 → `project/HDS/src/lang/` 等对应目录

---

## 2. 翻译文件目录结构

```
project/
├── Default/src/lang/
│   ├── zh-cn/          ← 唯一基准，所有改动从这里出发
│   │   ├── AdsPage.ts
│   │   ├── FacilityPage.ts
│   │   ├── SystemPage.ts
│   │   ├── common.ts
│   │   └── ...（共 ~20 个 .ts 文件）
│   ├── en/             ← 同步目标语言之一
│   ├── ko/
│   ├── ja/
│   ├── zh-tw/
│   └── ...（其余 15 种语言）
└── HDS/src/lang/
    ├── zh-cn/          ← HDS 项目的基准翻译（独立维护）
    └── ...
```

文件格式统一使用 TypeScript `export default { ... }` 嵌套对象。

---

## 3. 模块映射规范 (Module Mapping)
- **命名约定**: 视图模块 `XXXPage` 通常对应语言包中的 `XXX-mgt` 或 `XXXMgt`
- **示例**: `AdsPage` 模块 → 翻译文件 `AdsPage.ts`
- **核心分类**:
  - `Rules.ts` --- 表单校验规则翻译
  - `RobotControl.ts` --- 设备控制相关（指令/动作/状态）
  - `common.ts` --- 全局公共词汇与按钮
  - `options.ts` --- 下拉选项文案

---

## 4. zh-cn 变更同步工作流（重点）

> **触发时机**：当用户说「同步翻译」、「帮我同步语言包」或类似指令时，执行以下工作流。
> **不需要用户事先告知改了哪里**，AI 自行通过 git 查当前改动。

### 4.1 第一步：用 git 检测当前 zh-cn 的实际改动

收到同步指令后，**第一步就跑 git 命令**，自动获取 zh-cn 改动内容：

```bash
# 优先：查看尚未提交的 zh-cn 改动（最常见场景）
git diff HEAD -- 'project/*/src/lang/zh-cn/**'

# 补充：查看已提交但想回溯的改动
git diff <旧commit> <新commit> -- 'project/*/src/lang/zh-cn/**'

# 快速定位哪些文件有改动
git diff HEAD -- 'project/*/src/lang/zh-cn/**' --name-only
git status --short -- 'project/*/src/lang/zh-cn/**'
```

> [!TIP]
> 如果 `git diff HEAD` 无输出（变更已提交），改用 `git diff HEAD~1 HEAD` 查最新一次提交。

### 4.2 第二步：识别四类变更并处理

| 变更类型 | 如何识别（git diff 输出） | 如何同步到其他语言 |
|---|---|---|
| **值修改**（语义变化） | `-  name: "企业管理员"` → `+  name: "公司管理员"` | 找到其他语言同 key，按新语义重新翻译并替换 |
| **新增 key** | `+  newKey: "新词条"` | 在其他语言相同位置插入该 key，翻译对应语言的值 |
| **删除 key** | `-  oldKey: "旧词条"` | 在其他语言文件中找到并删除同名 key |
| **位置移动** | key 位置变化但 key/value 不变 | 其他语言保持 key 对应关系正确即可，位置可选同步 |

### 4.3 第三步：同步到其他语言文件

**适用语言列表**（逐一检查，或根据 `project/Default/src/lang/` 下实际存在的语言目录确认）：
`en`, `zh-tw`, `ko`, `ja`, `ar`, `az`, `de`, `ee`, `el`, `es`, `fr`, `id`, `it`, `pt`, `ru`, `th`, `tr`, `vi`

**同步原则**：
1. **以 zh-cn 的 key 结构为权威**：其他语言的 key 结构必须与 zh-cn 完全一致（相同的嵌套层级、key 名）
2. **只翻译 value**：key 名保持与 zh-cn 完全相同，不翻译 key
3. **删除 key 时**：其他语言也必须删除，保持结构一致，防止冗余词条积累
4. **新增 key 时**：如暂时无法翻译，可先使用 zh-cn 值占位，但必须标注待翻译
5. **值修改时**：必须根据新的中文含义重新翻译，不能保留旧翻译

### 4.4 实际示例

**zh-cn 改动前**：
```typescript
// zh-cn/FacilityPage.ts
businessAndId: "企业id",
```

**zh-cn 改动后**：
```typescript
// zh-cn/FacilityPage.ts
businessAndId: "公司id",
```

**需同步到 en**（值语义变化，`enterprise` → `company`）：
```typescript
// en/FacilityPage.ts
businessAndId: "Company ID",   // 修改前可能是 "Enterprise ID"
```

**需同步到 ko**：
```typescript
// ko/FacilityPage.ts
businessAndId: "회사 ID",      // 修改前可能是 "기업 ID"
```

---

## 5. 多项目同步注意事项

- `project/Default/src/lang/zh-cn/` 和 `project/HDS/src/lang/zh-cn/` 是**独立**的翻译基准
- 修改 Default 的 zh-cn → 只同步 Default 下的其他语言
- 修改 HDS 的 zh-cn → 只同步 HDS 下的其他语言
- **两套翻译不互相覆盖**，但 HDS 加载时会先 merge Default 的翻译

---

## 6. 标准用法

废弃自定义 `Lang` Hook，统一使用 `vue-i18n` 原生调用：

```typescript
import i18n from "@/lang";
i18n.t("AdsPage.tip.copyListJsonConfirm", { name: row.name })
```

- **变量处理**: 翻译字符串中使用 `{variableName}` 作为占位符
- **翻译重点**: 仅对用户可见的 UI 字符串翻译（MessageBox 提示语、表单 Label、按钮文本等）
- **技术排除**: 严禁将 `console.log` 日志、技术变量名、内部状态码加入翻译包

---

## 7. 长度规范
按钮 (`button`)、提示语 (`tip/tips`) 应尽量**简短明了**，避免过长词组导致 UI 排版异常。

7. 结语

通过 .agent/ 目录下的这套三位一体架构（skills 规范大脑 + scripts 自动化肢体 + workflows 快捷触发神经），项目建立了一个可自我维护、可生长的 AI 开发协作系统。

  • 规范即代码 (Docs as Code) ：以往文档写出来就落灰，现在规范成了可执行的准则，AI 每次干活前必读，确保不写野路子代码。
  • 极简的协作体验 ：任何新来的 AI 或者同事，不需要长篇大论的口头交接，一个 /skill 命令下去，项目规范自动拉平。

从盲目瞎猜的聊天助手，到懂业务、守规矩、还会跑脚本的高级研发伙伴，全部的奥秘都在这套架构之中。

相关推荐
代码煮茶1 小时前
Vue3 组件库二次封装实战 | 基于 Element Plus 封装企业级 UI 组件库
前端·javascript·vue.js
KaMeidebaby1 小时前
卡梅德生物技术快报｜单克隆抗体人源化 PEG 修饰质控方法体系构建与验证
服务器·前端·数据库·人工智能·算法·百度·新浪微博
元宵大师1 小时前
[升级V2.1.5]回测模块重构:参数确认+异步进度+日志持久化！本地Web版多因子轮动系统
前端·重构
咋吃都不胖lyh1 小时前
限流重试、指数退避、随机抖动
前端
之歆1 小时前
DAY_11JavaScript BOM与DOM深度解析：底层原理与工程实践（上）
开发语言·前端·javascript·ecmascript
冴羽yayujs2 小时前
GitHub 前端热榜项目 - 日榜(2026-05-17)
前端·github
老马95272 小时前
opencode8-桌面应用实战 3
前端·人工智能·后端
逆yan_2 小时前
🧭 基于 pnpm Workspace 和 Turborepo 的 Monorepo 最佳实践
前端·javascript·架构
广州华水科技2 小时前
单北斗形变监测一体机在大坝安全监测中的应用与技术优势
前端
热门推荐
01GitHub 镜像站点02Codex 接入 DeepSeek API 完整配置文档03Gemini大升级、AI眼镜首发、Android XR亮相，13天后见分晓04【AI】2026 年具身智能模型和世界模型总结05Codex 手机端连接教程：三分钟搞定，附完整步骤06人工智能最新动态 AI 日报 · 2026年5月10日07CC-Switch & Claude 基于 Linux 服务器安装使用指南08裂开！ChatGPT 居然开始要手机号验证，附详细解决方法092026年AI前瞻：量子AI、具身智能与科学发现的新纪元10几个好用的ip纯净度检测网站