# Platform Architecture

> ```skill

- Skill: `gabrielmoreira/platform-architecture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/platform-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/platform-architecture/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/gabrielmoreira/platform-architecture

---

```skill
---
name: platform-architecture
description: |
  平台架构知识 - 帮助 AI 理解你的软件架构层次，正确识别用户意图。
  触发关键词: 平台, 组件, 应用, 框架, 架构, 分层
  核心功能: 区分平台代码和应用代码，引导正确的代码搜索位置。
---

# 平台架构知识

> ⚠️ **重要**: 此 Skill 帮助 AI 理解你的软件架构层级，避免混淆"平台/框架"和"应用/业务"代码。
>
> 📌 **此文件需要根据你的项目定制**。下方提供了通用模板和 AI 填充指南。

---

## 🏗️ 架构分层

> 📋 **AI 填充 Prompt** — 复制以下内容发送给 Copilot 生成此部分：
>
> ```
> 请根据我的项目架构，生成一份架构分层图。我的项目结构如下：
> [在此粘贴你的项目目录结构或简要描述]
>
> 请按以下格式生成（从上到下为依赖方向）：
> Layer N: 最上层（业务应用层）- 应用名称和仓库
> Layer N-1: 框架/中间件层 - 通用组件和仓库
> Layer 1: 基础设施层 - 底层服务和工具库
> 每层说明：用途、代码仓库名、主要模块。
> ```

```
项目架构（从上到下）：

┌─────────────────────────────────────────────────────────────┐
│ Layer 3: Applications（业务应用层）                           │
│ ├── 应用 A：[你的应用名]                                     │
│ └── 应用 B：[你的应用名]                                     │
│     代码仓库: [你的应用仓库名]                                │
│     特点: 特定业务场景的逻辑                                  │
├─────────────────────────────────────────────────────────────┤
│ Layer 2: Framework/Platform（框架/平台层）⭐                  │
│ ├── 框架能力: [如 IOC容器、配置驱动、插件系统]                 │
│ └── 通用组件: [如 用户管理、权限、日志、缓存]                  │
│     代码仓库: [你的平台仓库名]                                │
│     特点: 所有应用共用的通用能力                               │
├─────────────────────────────────────────────────────────────┤
│ Layer 1: Infrastructure（基础设施层）                         │
│ ├── 数据库、消息队列、存储服务                                │
│ └── 工具库、算法库                                           │
└─────────────────────────────────────────────────────────────┘
```

---

## 🔑 关键概念对照表

> 📋 **AI 填充 Prompt** — 复制以下内容发送给 Copilot：
>
> ```
> 根据我项目的架构分层，生成“用户说的 → 实际含义”的对照表。
> 格式：| 用户说的 | 实际含义 | 代码仓库 | 搜索位置 |
> 覆盖：1. "平台/框架/组件"指哪层 2. "应用/业务"指哪层 3. 常见歧义词
> ```

| 用户说的 | 实际含义 | 代码仓库 | 搜索位置 |
|----------|----------|----------|----------|
| **平台**、框架、组件 | 框架/平台层 (Layer 2) | `{{PLATFORM_REPO}}` | 本地工作区优先 → MCP 远程 |
| **应用**、业务逻辑 | 业务应用层 (Layer 3) | `app-*` | 当前工作区 |
| **当前项目** | 应用特有代码 | 当前仓库 | 当前工作区 |

---

## 🔍 搜索策略

### ⭐ 本地优先原则

> 在多根工作区场景下，用户可能同时打开应用项目和平台仓库。
> **必须优先在本地工作区搜索，本地没有时才通过 MCP 远程搜索。**

```
搜索优先级:
1️⃣ 本地工作区（包括打开的平台仓库文件夹）
2️⃣ MCP 远程仓库（本地无结果时）
```

---

## 🎯 意图识别规则

### 当用户提到以下关键词时，应搜索 **平台仓库**:

> 📋 **AI 填充 Prompt** — 复制以下内容发送给 Copilot：
>
> ```
> 列出我的平台/框架层的所有核心模块，每个模块包含：
> - 用户可能使用的关键词（中文和英文）
> - 模块在代码仓库中的路径
> 格式：| 关键词 | 对应模块 | 仓库搜索路径 |
> ```

| 关键词 | 对应模块 | 搜索路径 |
|--------|----------|----------|
| [你的平台关键词] | [模块名] | `[模块路径]/` |

### 当用户提到以下关键词时，应搜索 **当前工作区**:

| 关键词 | 含义 | 搜索位置 |
|--------|------|----------|
| 应用内, 业务逻辑 | 应用特有代码 | 当前项目 |
| [你的业务关键词] | [业务模块] | `src/` |

---

## 📦 平台组件清单

> 📋 **AI 填充 Prompt** — 复制以下内容发送给 Copilot：
>
> ```
> 请帮我整理平台/框架层的完整组件清单。
> 信息来源：[粘贴你的 package.json / pom.xml / go.mod
>              或组件目录结构]
> 格式：### 前端组件 | 组件 | 功能 | 包名/路径 |
>       ### 后端组件 | 组件 | 功能 | 包名/路径 |
> ```

| 组件 | 功能 | 包名 |
|------|------|------|
| [待填充] | [待填充] | [待填充] |

---

## 🚨 常见混淆场景

### 混淆1: "平台模块" vs "应用内功能"

```
用户: "平台的某功能怎么工作的"

❌ 错误: 在当前应用项目中搜索 → 找到的是应用层调用代码，不是平台实现
✅ 正确: 先在本地查找平台仓库，没有则通过 MCP 搜索远程
```

### 混淆2: 未明确层级

```
用户: "某功能怎么实现的"

✅ 正确: 先判断属于哪一层
   1️⃣ 是否是平台通用组件（见上表）→ 是则搜索平台仓库
   2️⃣ 否则搜索当前工作区
   3️⃣ 不确定 → 两边都搜，并说明来源
```

---

## 💡 执行建议

### 1. 始终先确认代码层级

```markdown
🔍 **层级确认**:
   用户问题: "{用户问题}"
   关键词提取: {提取的关键词}
   层级判断: {平台层 | 应用层 | 需要确认}
   搜索目标: {平台仓库 | 当前工作区 | 两者}
```

### 2. 搜索结果要说明来源

```markdown
📂 **搜索结果来源**:
   - 仓库: [仓库名] ([平台层/应用层])
   - 路径: [具体路径]
```

### 3. 主动提示用户（用 ask_questions 对话框）

当不确定时:
```
header: "代码层级"
question: "您说的 'xxx' 是指..."
options:
  - label: "平台/框架层的实现"
  - label: "当前应用中的业务逻辑"
```