AI Skills 编排落地技术方案书

1. 方案概述

1.1 背景

cmclink-ibs-web-1 是一个典型的 Vue 3 企业级前端项目，业务域多、路由复杂、公共组件沉淀深、工程约束强。传统 AI 编码在此类项目中常见三个问题：

通用能力强，项目感知弱 ：模型知道 Vue、Pinia、Router 的通用写法，但不了解本仓库的 src/api/_modules、src/config/index.ts、src/components 复用体系。
技能孤岛严重：即使已经沉淀了多个 Skills，AI 也可能不知道"先调哪个、后调哪个、哪些必须串行、哪些可以并行"。
结果不可审计：AI 输出看似完整，但缺少"规则约束、执行轨迹、验证证据"三类留痕，难以进入团队级治理。

因此，本方案提出一套面向企业前端工程的 AI 辅助研发体系：以 @architect-workflow 为统一编排入口，以 .mdc Rules 为被动护栏，以 Skills 为主动执行器，以 CI/测试为质量闸门，构建"可编排、可落地、可验证、可复盘"的交付闭环。

1.2 目标

让 AI 从"代码补全工具"升级为"受约束的架构执行器"。
让 Vue 官方能力与项目业务规范形成统一编排矩阵。
让每一次 AI 交付都可追溯：有任务单、有技能轨迹、有验证证据。
让团队能量化评估 AI 提效效果，而不是停留在主观感受。

1.3 非目标

不替代人类架构师的业务边界判断。
不承诺一次性解决历史 lint 债务。
不把任何演示数据直接等同于长期生产统计结果。

2. 问题定义

2.1 现状痛点

结合当前仓库文档与已落地结构，主要问题如下：

痛点	典型表现	影响
AI 不识别项目规范	API 直接写到页面、路由注册遗漏、未走公共组件	代码返工、CR 驳回
AI 不理解组件资产	已有 `BaseQuery`、`CmcTable`、`CmcDialog` 仍被重复实现	重复造轮子、体验不一致
AI 缺少任务分解能力	新功能同时涉及 API、Store、i18n、Router 时无序推进	交付质量不稳定
AI 缺少验证闭环	只有代码，没有执行轨迹、没有质量门禁	无法做团队治理与复盘

2.2 约束条件

现有项目规范必须优先于模型默认偏好。
存量目录结构不可被随意重写。
质量门禁必须能落到仓库现有脚本。
规则和技能都要服务于"复杂 B 端页面"而不是简单 Demo。

3. 设计原则

3.1 核心原则

Rule First：先约束，再生成。
Reuse Before Rewrite：先查公共资产，再考虑新增实现。
Workflow Before Prompting：优先编排流程，而不是堆提示词。
Evidence Before Conclusion：先有代码与校验，再给结论。
Incremental Governance：先让体系接线成功，再逐步提高门槛。

3.2 理论锚点

DDD（领域驱动设计）：将 API、路由、状态、页面、工具函数按领域边界组织。
TDD / Quality Gates 思想：不是机械要求先写测试，而是强调"每次交付必须经过验证闸门"。
Composable Architecture：页面只保留编排与渲染，复杂逻辑沉到 composables / store / utils。

4. 总体架构

4.1 架构分层图

flowchart TD A[需求输入\n接口文档 / 页面截图 / 缺陷描述] --> B[Orchestrator\narchitect-workflow] B --> C1[项目 Rules\n.mdc 被动护栏] B --> C2[项目 Skills\n主动执行能力] C2 --> D1[api-definition] C2 --> D2[common-components] C2 --> D3[state-management] C2 --> D4[utils-functions] C2 --> D5[i18n-config] C2 --> D6[router-config] C2 --> D7[vue-testing-best-practices] C1 --> E[代码产物\nAPI / View / Store / Router / i18n] D1 --> E D2 --> E D3 --> E D4 --> E D5 --> E D6 --> E D7 --> F[质量闸门\nvalidate:trae-rules / type-check / lint / test] E --> F F --> G[交付物\n代码 + 调用轨迹 + 验证结果]

4.2 体系说明

调度控制层 ：由 @architect-workflow 负责识别任务类型、排序 Skill、决定并发/串行、输出风险项。
被动护栏层 ：由 .trae/rules/*.mdc 在生成时施加底线约束。
执行能力层：由 Vue 官方能力 Skill 与项目业务 Skill 共同组成。
质量闸门层 ：通过 package.json 中已存在的脚本执行统一验证，如 package.json。

4.3 Rules 与 Skills 关系图

flowchart LR A[开发者发起任务] --> B[调用 Skill] B --> C[Skill 提供方法论] C --> D[AI 生成代码] E[Rules 自动生效] --> D D --> F[输出合规代码] F --> G[CI / 测试校验]

结论：

Skill 决定"怎么做"。
Rule 决定"哪些不能做、哪些必须做"。
CI 决定"能不能交付"。

5. 能力地图

5.1 官方能力层

当前纳入编排的 Vue 官方/通用能力包括：

vue-best-practices
vue-composables
vue-debug-guides
vue-directives
vue-jsx-best-practices
vue-options-api-best-practices
vue-pinia-best-practices
vue-router-best-practices
vue-testing-best-practices

5.2 项目业务能力层

api-definition
common-components
router-config
state-management
utils-functions
i18n-config
architect-workflow

5.3 组件资产层

对复杂页面交付影响最大的不是单纯代码生成，而是 是否识别并复用现有公共资产。当前重点资产包括：

表格：CmcTable、CmcCardTable、CmcDataGrid
搜索：BaseQuery
弹窗：CmcDialog、CmcContentDialog、CmcConfirm
选择器：PortSelect、TradeLaneSelect、VesselVoyageKeywordSelect
标签：CmcTag

其中 BaseQuery 是后续规则强化的重点，因为复杂列表页的顶部搜索区不应继续让 AI 自行拼装原生 el-form。

6. 编排机制设计

6.1 任务识别矩阵

任务类型	首选编排链路
新页面 / 新功能	`architect-workflow -> api-definition -> common-components -> vue-composables -> state-management -> utils-functions -> i18n-config -> router-config -> vue-testing-best-practices`
纯接口改造	`api-definition -> utils-functions -> vue-testing-best-practices`
路由 / 权限异常	`router-config -> vue-router-best-practices -> vue-debug-guides`
重复造轮子风险	`common-components -> vue-best-practices`
国际化遗漏	`i18n-config -> vue-best-practices`

以上矩阵来源于 skills-orchestration-landing-plan.md。

6.2 编排时序图

sequenceDiagram participant U as 开发者 participant O as architect-workflow participant R as Rules participant S as Skills participant C as CI Gates U->>O: 输入需求/截图/API 文档 O->>O: 识别任务类型与领域 O->>S: 按顺序调度技能 S->>R: 代码生成时接受规则约束 R-->>S: 返回约束结果 S-->>O: 输出代码改动 O->>C: 触发校验 C-->>O: 返回 type/lint/test 结果 O-->>U: 交付代码 + 风险项 + 验证结果

6.3 互斥与优先策略

vue-best-practices 默认优先于 vue-options-api-best-practices
公共组件优先于页面自实现
@vueuse/core 优先于手写 composable
composable 优先于 utils，utils 优先于页面内联逻辑

7. 规则体系设计

7.1 Rules 的定位

Rules 是 AI 的"潜意识"和"法律系统"，不需要开发者每次重复强调，但会在生成行为时自动生效。

7.2 当前已落地的规则主题

API 设计：api-design.mdc
Vue 组件：vue-component.mdc
TypeScript：typescript.mdc
Element Plus：element-plus.mdc
Pinia：pinia-store.mdc
i18n：i18n.mdc
测试：testing.mdc
安全：security.mdc
性能：performance.mdc
样式：styling.mdc
编排：skills-orchestration.mdc

7.3 规则增强建议

本方案建议新增一类"组件强映射规则"，典型样例如下：

页面能力	强映射组件	规则建议
复杂搜索区	`BaseQuery`	禁止优先手写原生 `el-form`
标准列表表格	`CmcTable`	默认使用公共表格
复杂卡片表格	`CmcCardTable`	需要多行卡片信息时优先复用
标准详情弹窗	`CmcDialog` / `CmcContentDialog`	禁止每页重复封装

7.4 Root Cause 复盘：为何 AI 未调用 `BaseQuery`

这是一个关键治理结论：

当前规则强调了"公共组件优先"，但没有把 BaseQuery 提升为"复杂搜索区默认组件"。
BaseQuery 的可发现性不够强，AI 能看到目录，但难以快速推断其入参、插槽、注册机制。
缺少"规则 + 示例 + 单测 + README"四位一体支撑，导致模型退回到其最熟悉的原生 el-form。

因此，提升公共组件复用率的根治方案不是单点补文档，而是四件套一起做：

规则强映射：在规则层明确"哪些场景必须用哪个组件"。
组件示例：提供最小可运行 Demo。
组件单测：让 AI 能从测试中理解行为边界。
组件 README：让 AI 能快速读取"怎么用"而不是只看源码。

8. 落地实施方案

8.1 代码侧已落地内容

根据现有仓库，以下内容已经真实存在或已纳入方案：

.trae/config/trae.config.json
.trae/rules/project_rules.md
.trae/rules/*.mdc
.trae/skills/*
skills-orchestration-landing-plan.md
README.md

8.2 执行入口

统一要求：

复杂需求必须先调用 @architect-workflow
组件场景必须调用 @common-components
最终交付必须附带：
- 任务单
- Skill 调用轨迹
- 验证结果

8.3 页面级标准剧本

flowchart TD A[需求进入] --> B[识别领域] B --> C[定义 API] C --> D[映射公共组件] D --> E[拆分 composables / utils / store] E --> F[接入 i18n] F --> G[接入 Router] G --> H[执行 type/lint/test] H --> I[输出交付件]

9. 复杂页面场景演示

9.1 为什么必须用复杂场景验证

简单页面只能证明"AI 会写 Vue"，不能证明"AI 能在项目规范下稳定交付"。真正有代表性的验证对象应是"订舱管理"这类复杂 B 端页面。

9.2 订舱管理页能力拆解

以订舱管理为例，可拆解为以下能力块：

区域	页面能力	推荐组件 / 能力
顶部说明区	业务提示、快捷链接	公共 Banner / Alert 能力
功能按钮区	多个业务动作按钮	`CmcButtonGroup` 或统一按钮区
状态切换区	数量型 Tabs	`CmcTab`
搜索区	多字段联动、展开收起、高级筛选	`BaseQuery`
列表区	复杂列、状态 Tag、多行展示、勾选	`CmcTable` / `CmcCardTable`
行操作区	查看、更多、弹窗	`CmcDialog` / 下拉动作菜单
全局状态	Tab 统计、筛选条件缓存	Pinia / composables

9.3 复杂页面推荐编排链路

text 复制代码

architect-workflow
-> api-definition
-> common-components
-> vue-composables
-> state-management
-> utils-functions
-> i18n-config
-> router-config
-> vue-testing-best-practices

9.4 对 `BaseQuery` 的专项建议

若未来要让 AI 在复杂页面中稳定复用 BaseQuery，建议补齐以下资产：

src/components/BaseQuery/README.md
src/components/BaseQuery/__tests__/*
一个业务示例页面引用
一条 .mdc 规则：复杂搜索区默认使用 BaseQuery

10. 验证与验收机制

10.1 验证层次

本方案明确区分 4 个证据等级，避免把规划误写成事实：

证据等级	含义	用途
L1 文档级	有规则、有方案、有模板	说明体系已定义
L2 代码级	仓库已有落地文件	说明体系已接线
L3 校验级	脚本可执行并有结果	说明体系已可验证
L4 统计级	有长期 A/B 数据	说明体系已可量化证明 ROI

10.2 当前证据现状

基于三份核心文档与仓库现状：

L1 已具备：规则说明、编排方案、验收报告均已形成。
L2 已具备 ：.trae/config、.trae/rules、.trae/skills 已落库。
L3 部分具备 ：validate:trae-rules、type-check、lint:check 等脚本已存在，可作为门禁。
L4 待持续积累：长期真实 A/B 产能数据需要持续回收，当前更适合作为"方法学模板"而非最终经营指标。

10.3 当前校验脚本

来自 package.json 的关键脚本：

npm run validate:trae-rules
npm run type-check
npm run lint:check
npm run test
npm run analyze:arch
npm run build:sit
npm run build:uat
npm run build:prod

10.4 验收流程

flowchart LR A[代码提交前] --> B[规则校验] B --> C[类型检查] C --> D[Lint 检查] D --> E[测试执行] E --> F[人工检查点] F --> G[准入评审]

人工检查点建议包括：

401 回跳是否正确
路由守卫与 routeSource 是否匹配
i18n 是否存在漏翻
公共组件是否被正确复用

10.5 验收报告使用建议

Trae-AI-Architecture-Acceptance-Report.md 可作为阶段性成果报告，但在正式汇报时应明确：

其中方法论与体系分层可直接引用
其中 ROI 数字应标注为"阶段性样例 / 需持续校准"
最终经营级汇报应使用长期真实任务样本替换演示值

11. 治理机制

11.1 组织侧治理

架构师：维护编排矩阵、规则边界、复杂场景标准
TL：审查"是否走了正确 Skill 链路"
开发：负责输入任务单、补充业务上下文、验证结果

11.2 资产侧治理

Rules 作为制度层资产
Skills 作为执行层资产
公共组件作为 UI 资产
测试脚本与 CI 作为验证资产

11.3 持续改进机制

每月执行一次三类复盘：

规则复盘：哪些约束仍然不够具体
组件复盘：哪些公共组件仍然未被 AI 准确识别
验证复盘：哪些质量门禁还停留在建议而非阻断

12. 风险与对策

风险	描述	对策
组件可发现性不足	AI 能看到目录，但不知道怎么用	README + Demo + 单测 + 规则强映射
规则过宽	只有"优先复用"，没有"必须复用"	提升为强约束场景规则
验证深度不足	只跑 type-check，不跑关键链路	引入 Playwright 黄金路径
指标失真	把短期演示数据当经营指标	引入长期 A/B 数据采集机制
历史债务干扰	`lint` 历史问题过多影响可信度	分阶段治理，先新增后存量

13. 路线图

13.1 P1：立即可做

固化"复杂需求默认调用 @architect-workflow"
为 BaseQuery 增加 README / 示例 / 单测
在规则中加入"复杂搜索区 -> BaseQuery"强映射
将 validate:trae-rules 纳入日常检查

13.2 P2：两周内

增加复杂页面真实样本库
形成"任务单模板 + 技能轨迹模板 + 验证模板"三件套
增加 Playwright 黄金路径

13.3 P3：一月内

建立长期 A/B 数据看板
补齐 API Mock / Contract 回归
补齐可观测性链路（401、路由守卫、导出失败）

14. 汇报建议页结构

建议您做汇报时按以下顺序组织 PPT：

项目背景与传统 AI 的 3 大痛点
方案目标与设计原则
总体架构图
Rules 与 Skills 协同图
技能编排矩阵
复杂页面样例拆解（订舱管理）
验证与验收闭环
当前证据等级与阶段成果
风险与治理动作
路线图与投入产出预期

15. 参考文献

15.1 项目内参考

15.2 外部参考

Vue 官方文档：vuejs.org/
Vue Router 官方文档：router.vuejs.org/
Pinia 官方文档：pinia.vuejs.org/
Vue I18n 官方文档：vue-i18n.intlify.dev/
Vitest 官方文档：vitest.dev/
Playwright 官方文档：playwright.dev/
Mock Service Worker 官方文档：mswjs.io/
OpenTelemetry 官方文档：opentelemetry.io/

15.3 参考说明

Vue Router 作为 Vue 官方路由方案，其导航守卫、组件映射、滚动控制等能力适合承接本项目的复杂路由治理。来源
Vue 官方测试指南明确推荐在 Vue 应用中结合 @vue/test-utils、Vitest 与 Playwright 进行组件级和端到端验证。来源

16. 结论

本方案的本质，不是"给 AI 多写几个提示词"，而是把 AI 纳入前端工程体系：

用 Rules 建制度
用 Skills 建能力
用 Workflow 建顺序
用 CI / Test 建验证
用 证据分级 建可信度

对 cmclink-ibs-web-1 这类复杂前端工程而言，这套体系的价值不在于生成一个 Demo，而在于让 AI 交付逐步接近"团队可治理的工程产能"。