| name | generate-project-profile |
| description | 当用户要求「生成项目画像」「生成 project profile」「扫描项目生成 Markdown」时触发。也可被外部平台（如 llm-orchestration-platform）通过指令触发，用于为 AI Agent 生成标准化的项目知识上下文。 |
生成项目画像（Project Profile）
核心原则
代码感知是一切 AI 辅助开发的基石。 本 Skill 将项目代码转化为结构化 Markdown 文档，作为需求分析、方案设计、方案审查等后续环节的知识上下文。
核心思想：
- 不重复造轮子 — 让编码工具（Claude Code / Cursor / Windsurf 等）充当代码理解引擎，本 Skill 只定义输出规范
- 业务能力优先 — 画像不是技术档案，而是回答"这个系统能做什么、业务怎么跑"
- 图谱可拼接 — 每个微服务的画像是知识图谱的一个节点，通过标准化的服务交互和事件契约描述，多个画像可拼接为全局业务能力图谱
触发场景
用户说以下任意一种时，必须调用本 Skill：
- 生成项目画像 / generate project profile
- 扫描项目生成 Markdown / 生成项目 profile
- 为 AI Agent 准备项目上下文
- 更新 project-profile.md
与 init-project-docs 的关系
| 维度 | init-project-docs | generate-project-profile |
|---|
| 目标读者 | 人（开发者阅读理解项目） | AI Agent（程序化消费知识上下文） |
| 输出文件 | 3 份文档（概要 + 架构 + 开发参考） | 3 份文档（索引 + 业务上下文 + 编码规范） |
| 侧重点 | 业务流程图、架构图、开发场景速查 | 结构化能力清单、服务交互契约、实体状态机 |
| 使用方式 | 人工阅读 | 注入 Agent Context / 向量化分片检索 / 多服务画像拼接为知识图谱 |
两者可以共存，不冲突。
执行流程
flowchart TD
A(["收到生成项目画像指令"]) --> B["探索项目根目录<br/>识别构建工具和语言"]
B --> C["读取构建配置<br/>pom.xml / build.gradle / package.json"]
C --> D["扫描项目目录结构<br/>识别模块划分"]
D --> E["读取 Entity/Model 层<br/>提取数据模型和状态枚举"]
E --> F["读取 Service 层<br/>提取能力清单，按业务域分组"]
F --> G["读取 Controller/API 层<br/>提取对外暴露接口"]
G --> G2["扫描 Feign/HTTP Client<br/>提取对外调用的下游服务"]
G2 --> G3["扫描消息监听/发布<br/>提取事件契约"]
G3 --> H["读取配置文件<br/>识别服务注册名称"]
H --> I["归纳核心业务流程<br/>识别实体状态机"]
I --> I2["扫描约束与扩展点<br/>事务/幂等/鉴权/状态守卫"]
I2 --> J["归纳编码约定<br/>提取典型代码范式"]
J --> K{"docs/ 目录存在?"}
K -->|否| L["创建 docs/ 目录"]
K -->|是| M["检查已有画像文件"]
L --> N["生成 3 个文件"]
M --> N
N --> N1["project-profile.md<br/>索引 + 项目概述 + 技术栈"]
N --> N2["business-context.md<br/>数据模型/能力/流程/约束/接口/服务调用/事件"]
N --> N3["coding-conventions.md<br/>编码约定 + 配置概要"]
N1 --> O(["输出文件路径，告知用户完成"])
N2 --> O
N3 --> O
输出规范
物理拆文件 — 消灭幻觉的根因
一个文件塞所有维度，LLM 会把无关信息"创造性关联"，产生幻觉。 比如编码约定里的 Result<T> 包装模式，在做需求分析时可能被 AI 编出"当前已有统一退款结果包装类"的结论。
解法：每个消费阶段只给它需要的那份文件，物理隔离无关信息。
文件结构
docs/
├── project-profile.md ← 索引文件（轻量，每次都加载）
├── business-context.md ← 业务上下文（需求分析 / 方案设计加载）
└── coding-conventions.md ← 编码规范（代码生成阶段加载）
| 文件 | 消费阶段 | 内容 | 信噪比 |
|---|
project-profile.md | 每次 | 项目概述 + 技术栈 + 指向其他文件的引用 | 极高（~500 token） |
business-context.md | 需求分析 / 方案设计 | 数据模型与状态机 + 业务能力 + 业务流程 + 约束 + 接口 + 服务调用 + 事件 | 高（~3K-5K token，全是业务信息） |
coding-conventions.md | 代码生成 | 编码约定 + 配置概要 | 高（~1K-2K token，全是编码规范） |
各文件包含的维度
project-profile.md（索引）
| # | 维度 | 说明 |
|---|
| 1 | 项目概述 | 项目名、用途、语言版本、模块列表、服务注册名称 |
| 2 | 技术栈 | 框架、中间件、版本 |
business-context.md（业务上下文）
| # | 维度 | 数据来源 | 说明 |
|---|
| 3 | 数据模型与状态机 | Entity + 枚举类 | 实体、核心字段、关联关系、实体状态流转 |
| 4 | 业务能力清单 | Service 接口/类 | 按业务域分组，标注业务语义 |
| 5 | 核心业务流程 | Service 调用链推断 | 关键流程 + 状态变迁 + 事件。每步附证据来源 |
| 6 | 关键约束与扩展点 | Service + AOP + 配置 | 事务边界、幂等点、鉴权、状态守卫、失败补偿 |
| 7 | 对外暴露接口 | Controller 层 | Method + URL + 入参 + 出参 |
| 8 | 对外调用服务 | FeignClient / HTTP Client | 本服务调用了谁 |
| 9 | 事件与消息契约 | MQ Listener + Publisher | 发布/消费的事件 |
coding-conventions.md（编码规范）
| # | 维度 | 数据来源 | 说明 |
|---|
| 10 | 编码约定 | 代码归纳 | 命名规范、异常处理、通用基类 + 代码片段 |
| 11 | 配置概要 | application*.yml | 仅业务相关配置 |
模板文件
每个输出文件对应一个模板：
template.md → 生成 docs/project-profile.md（索引）business-context-template.md → 生成 docs/business-context.md（业务上下文）coding-conventions-template.md → 生成 docs/coding-conventions.md（编码规范）
与 v1（旧版 10 维度）的映射
| v1 维度 | v2 去向 | 原因 |
|---|
| 3. 项目结构（目录树） | 删除 | AI 可自行 ls/Glob，目录树占 token 但不帮助理解业务 |
| 4. 分层架构 | 删除 | "DDD-lite / MVC"标签对需求分析无价值，编码约定中已含分层规则 |
| 5. 数据模型 | 升级为 3. 数据模型与状态机 | 增加实体状态枚举和状态流转 |
| 6. Service 能力清单 | 升级为 4. 业务能力清单 | 按业务域分组 + 业务语义标注 |
| 7. API 接口 | 升级为 7. 对外暴露接口 | 强调"对外暴露"语义，区分于调用下游 |
| 8. 外部依赖服务 | 拆分为 8 + 9 | 拆为"对外调用服务"（HTTP）和"事件契约"（MQ），为图谱拼接提供边 |
| 9. 配置概要 | 精简为 11. 配置概要 | 只保留业务配置，去掉 server.port 等噪音 |
| 10. 编码约定 | 保留为 10. 编码约定 | 不变 |
| （无） | 新增 5. 核心业务流程 | 回答"业务怎么跑"，附证据来源 |
| （无） | 新增 6. 关键约束与扩展点 | 回答"改这里容易炸在哪、改动半径多大" |
维度详细说明
A 组：业务认知层 — 需求分析消费
A 组回答"这个系统是什么、能做什么业务、业务怎么跑、碰什么会炸"。是 AI 做需求影响分析的核心依据。
维度 1 — 项目概述
必须包含 服务注册名称（如 Spring Cloud 的 spring.application.name），这是跨服务图谱拼接的主键。
维度 2 — 技术栈
保持不变，用于方案设计阶段判断技术可行性。
维度 3 — 数据模型与状态机
v1 只列字段和关联。v2 增加实体状态枚举和状态流转：
| 实体 | 状态枚举 | 流转路径 |
|------|---------|---------|
| Order | CREATED → PAID → SHIPPED → COMPLETED | 正常流程 |
| Order | PAID → REFUNDING → REFUNDED | 退款流程 |
| Order | CREATED → CANCELLED | 取消流程 |
为什么关键：退货需求的第一个问题就是"订单有哪些状态，退货应该插入到哪个状态之后"。没有状态机，AI 只能猜。
维度 4 — 业务能力清单
v1 按 Service 类列方法签名。v2 改为按业务域分组，每个能力附一句话业务语义：
### 订单域
| 能力 | Service#Method | 说明 |
|------|---------------|------|
| 创建订单 | OrderService#placeOrder | 校验库存 → 锁库存 → 创建订单 → 发布 ORDER_CREATED 事件 |
| 取消订单 | OrderService#cancelOrder | 仅 CREATED 状态可取消 → 释放库存 → 发布 ORDER_CANCELLED |
| 查询订单 | OrderService#getOrderDetail | 支持按 ID / 用户 / 状态查询 |
### 支付域
| 能力 | Service#Method | 说明 |
|------|---------------|------|
| 发起支付 | PaymentService#createPayment | 调用第三方支付网关 → 更新订单状态为 PAID |
为什么关键：AI 看到"退货退款需求"时，能直接定位到订单域和支付域的现有能力，判断哪些能复用、哪些需新增。
维度 5 — 核心业务流程（新增）
用文字（非 Mermaid）简明描述 2-5 个核心业务流程，标注涉及的 Service、状态变迁和事件。每个流程末尾必须附证据来源：
### 下单流程
1. 用户提交订单 → OrderController#placeOrder
2. OrderService 校验库存 → 调用 inventory-service 锁定库存
3. 创建 Order（状态 CREATED）→ 写入 t_order
4. 发布事件 ORDER_CREATED → 通知 notification-service
> 证据来源：OrderServiceImpl#placeOrder, InventoryFeignClient#lockStock, OrderCreatedProducer#send
为什么关键：这是连接所有维度的"胶水"。有了流程，AI 才能理解"退货退款"应该在哪个流程之后发生，涉及哪些 Service、改哪些状态、发什么事件。
证据锚点规则：维度 3（状态机）、4（能力清单）、5（业务流程）、6（约束）中涉及推断的内容，必须在段落末尾标注 > 证据来源：{类名#方法名} 或 > 证据来源：{文件路径}。这让下游 Agent 能区分"从代码中提取的事实"和"推断的结论"。
维度 6 — 关键约束与扩展点（新增）
回答"这个需求该插在哪、最容易炸在哪、改动半径有多大"：
### 事务边界
| 方法 | 事务范围 | 说明 |
|------|---------|------|
| OrderService#placeOrder | 创建订单 + 订单明细在同一事务 | 库存锁定通过 Feign 调用，不在事务内 |
| PaymentService#handleCallback | 更新 Payment + 更新 Order 在同一事务 | 事件发布在事务提交后 |
### 幂等点
| 接口/方法 | 幂等键 | 机制 |
|-----------|--------|------|
| PaymentController#callback | paymentId | 数据库唯一索引 |
| OrderService#cancelOrder | orderId + status | 状态守卫（仅 CREATED 可取消） |
### 鉴权入口
| 接口 | 鉴权方式 | 说明 |
|------|---------|------|
| /api/orders/** | JWT Token | 通过 SecurityFilter 统一校验 |
| /api/internal/** | 服务间签名 | 仅内部调用，非用户接口 |
### 状态变更守卫
| 实体 | 守卫规则 | 违反后果 |
|------|---------|---------|
| Order | CREATED → CANCELLED 仅允许用户主动或超时 | 抛 IllegalStateException |
| Order | PAID 后不可直接 CANCELLED，必须走退款流程 | 抛 BusinessException |
### 外部依赖失败补偿
| 外部依赖 | 失败处理 | 说明 |
|---------|---------|------|
| inventory-service 锁库存 | 失败则订单创建失败，无需补偿 | 强依赖 |
| payment-gateway | 超时则标记 PENDING，定时任务轮询查询 | 最终一致 |
### 不可轻易改动的核心规则
- 订单金额一旦创建不可修改（审计要求）
- 支付回调必须验签（安全要求）
- ...
> 证据来源：OrderServiceImpl#placeOrder, SecurityConfig, PaymentCallbackController#callback
为什么关键：需求分析时，AI 不仅要知道"有什么能力"，还要知道"碰什么会炸"。退货需求必然涉及状态变更守卫、事务边界调整、新增幂等点，没有这个维度 AI 只能盲猜风险点。
C 组：接口与交互 — 跨服务图谱的边
维度 7 — 对外暴露接口
沿用原 API 接口维度，但明确语义为"本服务对外暴露的能力"。
维度 8 — 对外调用服务（从原"外部依赖"拆出）
专门描述本服务调用了哪些其他服务：
| 目标服务 | 调用方式 | 接口 | 用途 |
|---------|---------|------|------|
| inventory-service | Feign | POST /api/inventory/lock | 下单时锁定库存 |
| inventory-service | Feign | POST /api/inventory/release | 取消订单时释放库存 |
| payment-gateway | HTTP | POST /api/pay/create | 发起第三方支付 |
为什么关键：这是图谱的"出边"。AI 做退货需求分析时，能立刻知道 order-service 调了 inventory-service 和 payment-gateway，退货流程大概率也需要调这两个。
维度 9 — 事件与消息契约（从原"外部依赖"拆出）
### 发布的事件
| Topic/Exchange | 事件类型 | Payload 关键字段 | 触发条件 |
|----------------|---------|-----------------|---------|
| order-events | ORDER_CREATED | orderId, userId, amount | 订单创建成功 |
| order-events | ORDER_PAID | orderId, paymentId | 支付回调成功 |
| order-events | ORDER_CANCELLED | orderId, reason | 用户取消订单 |
### 消费的事件
| Topic/Exchange | 事件类型 | 来源服务 | 处理逻辑 |
|----------------|---------|---------|---------|
| payment-events | PAYMENT_SUCCESS | payment-service | 更新订单状态为 PAID |
为什么关键：这是图谱的"事件边"。退货需求需要发布 ORDER_REFUNDED 事件，notification-service 可能需要消费它来发退款通知。没有事件契约，AI 不知道现有的事件体系怎么设计。
D 组：编码规范 — 代码生成阶段消费
维度 10（编码约定）和维度 11（配置概要）在需求分析阶段价值低，但在方案设计和代码生成阶段需要。保留但降级到最后。
配置概要精简规则：只保留业务相关配置（功能开关、限额、重试次数、超时时间等），去掉 server.port、spring.datasource.url 等纯基础设施配置。
知识图谱拼接规范
图谱节点（每个微服务的 profile 是一个节点）
每个 profile 通过以下字段成为图谱节点：
- 节点 ID：维度 1 中的服务注册名称（如
order-service）
- 节点能力：维度 4（业务能力清单）
- 节点数据模型：维度 3（数据模型与状态机）
图谱边（服务间关系）
| 边类型 | 数据来源 | 方向 |
|---|
| 同步调用 | 维度 8（对外调用服务）→ 目标服务的维度 7（对外暴露接口） | A → B |
| 事件驱动 | 维度 9 发布侧 → 维度 9 消费侧 | A ⇢ B（虚线表示异步） |
| 共享概念 | 维度 3 中出现相同实体名或外键引用 | A ⇔ B（双向） |
拼接示例
order-service payment-service inventory-service
┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ 维度4: 创建订单 │──Feign──→ │ 维度6: POST /pay │ │ 维度6: POST /lock │
│ 维度4: 取消订单 │──Feign──→ │ │←Feign── │ │
│ 维度8: ORDER_PAID │⇠ 事件 ⇠ │ 维度8: PAY_SUCCESS │ │ │
│ 维度8: ORDER_CREATED│⇢ 事件 ⇢ │ │ │ 维度8: ORDER_CREATED│
│ │──Feign──→ │ │ │ (消费→扣减库存) │
└─────────────────┘ └──────────────────┘ └──────────────────┘
退货需求影响分析时，AI 可以沿着这些边自动推导：
- 退货需要退款 → 沿同步调用边找到 payment-service
- 退货需要归还库存 → 沿同步调用边找到 inventory-service
- 退货需要通知用户 → 沿事件边找到 notification-service（消费 ORDER_REFUNDED）
编码约定维度（维度 10）采集指南
这个维度需要从代码中归纳，不是简单提取。重点关注：
- 异常处理模式 — 项目用统一异常类还是 Result 包装？怎么抛、怎么捕？
- 返回值包装 — 用
Result<T> / ResponseEntity / 裸返回？
- 参数校验方式 — JSR303 注解 / 手动校验 / AOP？
- 日志规范 — log 变量命名、日志级别使用习惯
- 通用基类/工具类 — BaseEntity / BaseService / 自定义工具类
- 命名习惯 — DTO/VO/Request/Response 后缀规则
必须附 2-3 个从项目中提取的真实代码片段，展示项目的"标准写法"。
质量标准
- 业务可理解：非技术人员读到维度 4-5 也能理解系统做什么
- AI 友好：表格优先，避免大段叙述；每个维度可独立被向量化分片
- 图谱可拼接：维度 1 有服务注册名、维度 8-9 有明确的服务名引用
- 证据可追溯：推断型维度（3-6）附证据来源锚点，标注关键类名和方法名
- 信息完整：找不到的维度标注「未检测到」，不要编造
- 脱敏处理：密码、密钥、Token 等敏感配置值用
*** 替代
- 可验证：每个维度的数据都能追溯到具体文件路径
- 可增量更新：文档头部记录生成时间，便于判断是否过期
- 精简干练：不输出对需求分析无价值的信息（纯目录树、纯基础设施配置等）
语言与框架适配
本 Skill 不限定语言和框架。根据项目实际情况调整：
| 项目类型 | 构建配置 | 数据模型来源 | Service 来源 | API 来源 | 服务调用来源 | 事件来源 |
|---|
| Java Spring | pom.xml | @Entity / @Table | @Service 类 | @RestController | @FeignClient / RestTemplate | @RabbitListener / @KafkaListener |
| Java MyBatis | pom.xml | Mapper XML / Entity | @Service 类 | @RestController | @FeignClient / RestTemplate | @RabbitListener |
| Node.js | package.json | Prisma / Mongoose | service/ 目录 | router/ / controller/ | axios / fetch 调用 | event emitter / MQ consumer |
| Python Django | requirements.txt | models.py | views.py / services/ | urls.py | requests / httpx | celery tasks |
| Go | go.mod | model/ 目录 | service/ 目录 | handler/ / router/ | HTTP client | goroutine / channel |
| Vue/React | package.json | 不适用 | store/ / composables/ | api/ 目录 | 不适用 | 不适用 |
前端项目：跳过维度 3（数据模型）、5（业务流程）、7（对外调用）、8（事件契约），标注「不适用」。
探索策略
- 先读构建配置（pom.xml / package.json），确定语言、框架、模块结构
- 读配置文件确认服务注册名称（
spring.application.name），这是图谱节点 ID
- Entity 层完整读取，字段信息不能遗漏，额外扫描枚举类找状态定义
- Service 层优先读接口（
I*.java），按业务域分组，减少 token 消耗
- Controller 层重点读注解和方法签名，不需要读方法体
- 扫描 Feign / RestTemplate / HTTP Client，提取对外调用清单
- 扫描 MQ Listener / Publisher，提取事件契约
- 从 Service 实现中推断核心业务流程，关注状态变更和事件发布点
- 扫描约束与扩展点：
@Transactional 找事务边界、唯一索引/幂等键、SecurityConfig/Filter 找鉴权入口、状态守卫（if status != XXX throw）、外部调用的重试/降级/补偿逻辑
- 编码约定需要读 2-3 个典型实现类的完整代码，才能归纳出模式
- 配置文件只提取业务相关项，跳过基础设施配置
Mermaid 语法强制规范
- 节点/边标签含
=、,、/、<、>、(、)、[、]、: 时必须加引号
< > 改用文字（如：大于、小于、请求体、响应体）- 不使用 emoji
classDiagram 方法名不含中文
注意事项
- 本 Skill 属于分析类，不进入功能开发或 bug 修复链路
- 生成完成后不需要触发
design-doc-required
- 如项目已有画像文件，询问用户是覆盖还是跳过
- 多服务/Monorepo 项目：每个可独立部署的服务生成独立的 3 份文件，不合并。可选生成聚合索引文件
- 单体多模块项目（所有模块共同部署为一个服务）：生成一份统一 profile
- 前端项目跳过不适用的维度，标注「不适用」
- 业务流程描述用编号列表，不用 Mermaid（流程图在 init-project-docs 中画，这里追求精简可检索）
- 维度 8-9 中引用的目标服务名必须与对方 profile 的服务注册名称一致，这是图谱拼接的前提
- 推断型内容必须附证据来源，格式：
> 证据来源：{ClassName#methodName} 或 > 证据来源：{file_path}
