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 类常见任务：

没匹配上的任务：不要硬套，回到本 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 的，先在
   目录

   作者最新文章

   英国宣布设立全球首个AI生物安全实验室

   2026-10-26 14:09

   特斯拉将自主研发人工智能地图导航系统

   2026-10-26 14:10

   Android 中 runOnUiThread 延迟执行的根源与解决方案

   2026-10-26 14:13

   Composer PHP 版本检测失败的完整排查与修复指南

   2026-10-26 14:14

   如何解决 runOnUiThread 延迟 30 秒执行的问题

   2026-10-26 14:16

   HTML5 Canvas 双色切换：点击矩形实现红绿循环变色

   2026-10-26 14:18

   Java 中实现正则捕获组模板展开（类似 Go 的 ExpandString）

   2026-10-26 14:19

   jQuery 表单提交失效的常见原因与正确实现方案

   2026-10-26 14:20

   Android 中 runOnUiThread 延迟执行的根因分析与解决方案

   2026-10-26 14:21

   PHP 中 unset() 无法彻底释放对象引用的原因解析

   2026-10-26 14:27

   热门AI工具

   更多

   

   WorkBuddy

   一款AI办公效率工具，主要用于腾讯云推出的AI原生桌面智能体工作台，适合需要提升相关任务效率的用户。

   AI办公学习Agent智能体

   

   豆包大模型

   豆包大模型是一款由字节跳动推出的企业级大语言模型服务平台。

   AI编程开发AI大模型

   

   PixPix Hot

   PixPix是一款面向电商视觉生产的AI商品图生成工具。

   电商工具AI绘画作图

   

   UP简历 Hot

   一款AI办公效率工具，主要用于基于AI技术的免费在线简历制作工具，适合需要提升相关任务效率的用户。

   AI办公学习工作效率

   

   AionClaw Hot

   AionClaw是一款面向办公、创作和编程任务的AI桌面智能体。

   Agent智能体桌面Agent

   

   切问学术 Hot

   切问学术是一款AI论文写作工具，复旦大学NLP团队推出的AI学术智能体。

   Agent智能体

   

   DeepSeek

   DeepSeek是一款面向对话、写作、编程和推理场景的AI大模型工具。

   AI编程开发AI聊天问答

   

   立刻MV Hot

   立刻MV是一款AI文本写作工具，AI 音乐视频（MV）创作工具。

   AI视频创作

   

   创客贴AI Hot

   创客贴AI是一款AI图像与设计工具，AI辅助的智能在线设计工具。

   AI设计工具