全部技能 分类浏览
← 返回
未分类

前端开发

ys-agent 前端（frontend/）功能迭代的工程规范守门 skill。当任何 agent 接到 ys-agent 前端相关任务时——新增页面、新增组件、加 API、加 Pinia store、改路由、写 mock、调整布局、修改样式、对接后端接口、迁移 demo 代码、做主题、加权限、写公共组件、做数据可视化、做表单、做弹窗、做表格、做搜索过滤、调 Element Plus 用法、做响应式、做性能优化，或仅仅是在 frontend/ 目录下编辑任何 .vue / .ts / .scss / .css / vite.config / tsconfig / package.json 文件——都必须先调用本 skill，按统一的工程规范实施，避免不同 agent 各自发挥导致目录混乱、风格漂移、重复造轮子。即使任务听起来很小（"加个按钮""改个文案"），只要发生在 frontend/ 下，也要先读本 skill，确认正确的放置位置、命名、引入方式后再动手。
ys-agent 前端（frontend/）功能迭代的工程规范守门 skill。当任何 agent 接到 ys-agent 前端相关任务时——新增页面、新增组件、加 API、加 Pinia store、改路由、写 mock、调整布局、修改样式、对接后端接口、迁移 demo 代码、做主题、加权限、写公共组件、做数据可视化、做表单、做弹窗、做表格、做搜索过滤、调 Element Plus 用法、做响应式、做性能优化，或仅仅是在 frontend/ 目录下编辑任何 .vue / .ts / .scss / .css / vite.config / tsconfig / package.json 文件——都必须先调用本 skill，按统一的工程规范实施，避免不同 agent 各自发挥导致目录混乱、风格漂移、重复造轮子。即使任务听起来很小（"加个按钮""改个文案"），只要发生在 frontend/ 下，也要先读本 skill，确认正确的放置位置、命名、引入方式后再动手。
user_fbf2a1f5
未分类 community v1.0.0 1 版本 100000 Key: 无需
★ 0
Stars
📥 25
下载
💾 0
安装
1
版本
#latest

概述

ys-agent 前端开发规范 skill

为 ys-agent 项目的 frontend/ 模块提供一套强约束的工程规范，让每个接手前端迭代的 agent 都按同一套思路落地，杜绝"我以为可以这样做"。

本 skill 是 docs/frontend-engineering-plan.md 的可执行延伸：plan 描述"为什么"，本 skill 提供"怎么做"。

0. 触发判断（先读完再决定动不动）

只要满足任一条件，就在动手前完整读完本 SKILL.md 并按工作流执行：

  • 任务描述出现 frontend / Vue / Element Plus / Pinia / 路由 / 组件 / 接口对接 / mock / 样式 / 主题 / 布局 等关键词
  • 任务路径涉及 frontend/、docs/sessions/S13-*、docs/frontend-engineering-plan.md
  • 用户引用了 S13 文档里出现的页面（Skill 广场 / MCP 广场 / Tool 广场 / 我的 Skill / 我的 MCP / Playground）
  • 任何代码改动落在 frontend/src/ 下，无论改一行还是改一个目录

不确定就读，本 skill 是项目级"前端开发指南"，读它的成本永远低于偏离规范后返工的成本。

1. 核心原则（铁律）

这 9 条是任何 agent 都不能绕开的底线。违反任意一条 = PR 必须返工。

  1. 目录即契约：每类文件有且只有一个正确位置，详见 references/conventions.md。新增文件前先翻"目录契约"表，再下手。
  2. 组件不直接调 axios：HTTP 一律走 src/api/；视图通过 Pinia store action 拿数据；store 调 api/modules/；axios 只在 src/api/client.ts 里实例化；各微服务实例在 src/api/services/index.ts 声明；模块文件 import 对应 service client，不直接使用 axios。新增微服务时，除了在 services/index.ts 加 client，还必须同步：① .env.development 声明独立路径前缀（如 /api-xxx）和 VITE_XXX_API_TARGET；② vite.config.ts 追加对应 dev proxy rewrite 条目。开发环境多个 VITE_*_API_BASE 禁止共用同一个 /api，否则无法按微服务独立路由。完整四步见 references/anti-patterns.md A25。
  3. 类型先行：每个接口都要在 src/types/api/<域>.ts 定义 Request / Response 类型；store / view 直接复用类型，不允许 any（确需 any 必须 PR 写理由）。
  4. Element Plus 按需 + 自动注册：直接 用即可，禁止 import { ElButton } from 'element-plus'。图标分两种场景，规则不同：
    • 模板中作为子元素展示（如 内）：直接 import { IconName } from '@element-plus/icons-vue' 后在模板里写 ，unplugin-vue-components 会识别 PascalCase 静态 tag 并自动处理。不要用 （string literal），该形式无法被静态分析器解析，图标同样不渲染。
    • 作为 JavaScript 值传给 :icon prop（如 ）：必须直接 import { IconName } from '@element-plus/icons-vue' 后传入，resolveComponent('IconName') 在此项目中不可用（@element-plus/icons-vue 是独立包，app.use(ElementPlus) 不全局注册图标组件，resolveComponent 会返回字符串而非组件，导致图标静默不渲染）。详见 references/anti-patterns.md A27。
  5. 样式走 SCSS 变量：颜色、间距、圆角、阴影、字号一律从 @/styles/variables.scss 取；业务组件禁止写死十六进制颜色。Element 主题色覆盖只能改 @/styles/element-overrides.scss。
  6. Mock 与真后端零代码切换：开发期通过 VITE_USE_MOCK=true 启用 MSW；任何接口对接前先写 mock handler，再写真接口对接，保证前端可独立运行。
  7. 路由 = 单一来源：菜单、面包屑、title 全部从 routes 的 meta 派生，禁止在 SideMenu / Breadcrumb 里手写菜单数据。路由 meta.title 和 meta.group 必须存储 i18n key（如 'skill.square.title'、'nav.group.square'），禁止存储中文文本。SideMenu 读取后通过 $t() 翻译展示。
  8. 可保留资产不删：旧 demo（ChatView / chat store / 三栏布局）已迁移到 src/views/playground/，禁止因为"看着乱"就删除；任何与流式 SSE 协议相关的代码改动需在 commit message 写明。
  9. 所有用户可见文本必须走 i18n：模板文本、ElMessage 提示、表单校验 message、组件 props 默认值、路由 title——任何用户能看到的字符串禁止硬编码中文或英文，必须通过 $t('key') 或 t('key') 引用。翻译 key 集中在 src/i18n/locales/*.json，命名规范见 references/conventions.md §10。例外情况（不走 i18n，在代码行尾加 // i18n-ignore 并说明原因）：① mock 数据中的业务模拟文本（如虚构的 skill 名称）；② 品牌名和产品固有专有名词（如 ys-agent、Skill、MCP、Tool、Playground）——这些是产品术语，各语言保持原文，直接写在代码中即可；③ 纯技术标识（如日志 tag、API path）。

2. 你接到任务后的第一步：选 workflow

打开 references/workflows.md，找到与任务最匹配的那个 workflow 并完整跟随。Workflow 覆盖 10 类常见任务：

ID任务类型触发短语
----------------------
W1新增业务页面（广场 / 详情 / 创建 / 我的）"加一个 X 页面"、"做 Y 详情页"、"S13 的 Z 页面"
W2新增 API 模块"对接 X 接口"、"调用后端 Y"、"加个请求"
W3新增 / 修改 Pinia store"把 X 状态存起来"、"做个全局 Y"、"按 store 重构"
W4新增公共组件"封装一个 X 组件"、"做个复用的 Y"、"抽公共组件"
W5新增 / 修改路由"加路由"、"改菜单"、"调跳转"
W6新增 MSW mock"前端先跑通"、"后端没好"、"补 mock"
W7新增 / 修改类型"TS 类型对不上"、"接口改了"、"加类型"
W8主题 / 样式调整"换颜色"、"暗色模式"、"全站调 X 风格"
W9迁移 / 重构"把 X 挪到 Y"、"重构 Z"
W10国际化（i18n）"加翻译"、"多语言"、"改文案"、"新增语言"、新增任何用户可见文本

没匹配上的任务：不要硬套，回到本 SKILL.md 的"通用工作流"节走。

> ⚠️ 重要：W1-W9 的任何 workflow 只要涉及用户可见文本（标题、按钮、提示、校验消息、路由 title 等），都必须同时执行 W10 的文本国际化步骤。W10 不是可选的独立 workflow，而是其他 workflow 的伴生要求。

3. 通用工作流（任何任务都先走一遍）

执行任何前端改动前，至少做完以下 4 步：

Step 1 · 定位

  1. 用 Read 打开 docs/frontend-engineering-plan.md，确认任务在改造方案里的位置（哪个目录、哪个文件、哪个阶段）。
  2. 用 Glob/Grep 检查 frontend/src/ 下是否已有相关文件，优先 Edit 已有文件而不是新建。
  3. 如果是新文件，对照 references/conventions.md 的"目录契约"表确认放置位置。

Step 2 · 类型先行 + 文本先行

  1. 涉及接口的，先在 src/types/api/<域>.ts 加类型。
  2. 涉及组件 Props/Emits 的，先在

    Skill工具集 © 2026