feat: 添加 chinaweal-quicknote 和 load-codestyle 两个 skill
- 在 marketplace.json 中注册新 skill - 更新 README.md 说明文档
This commit is contained in:
parent
cb0004f684
commit
a4f8964de2
|
|
@ -22,6 +22,22 @@
|
||||||
"skills": [
|
"skills": [
|
||||||
"./gitea-api"
|
"./gitea-api"
|
||||||
]
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "chinaweal-quicknote",
|
||||||
|
"source": "./skills",
|
||||||
|
"strict": false,
|
||||||
|
"skills": [
|
||||||
|
"./chinaweal-quicknote"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "load-codestyle",
|
||||||
|
"source": "./skills",
|
||||||
|
"strict": false,
|
||||||
|
"skills": [
|
||||||
|
"./load-codestyle"
|
||||||
|
]
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
|
|
|
||||||
22
README.md
22
README.md
|
|
@ -36,6 +36,28 @@ Gitea API 调用工具。用于与 Gitea 代码托管平台进行交互。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
### chinaweal-quicknote
|
||||||
|
|
||||||
|
众望通 PMS 系统速记相关 API 工具。用于管理个人速记、标签和附件。
|
||||||
|
|
||||||
|
**触发场景**: 速记、新增速记、查询速记、删除速记、速记标签、附件上传/下载
|
||||||
|
|
||||||
|
**前置要求**: 需要配置环境变量 `CHINAWEAL_PMS_TOKEN`
|
||||||
|
|
||||||
|
**API 基础地址**: `https://www.chinaweal.com.cn/pms-api`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### load-codestyle
|
||||||
|
|
||||||
|
代码风格参考文件加载工具。用于加载指定语言的代码风格规范。
|
||||||
|
|
||||||
|
**触发场景**: 加载代码风格、加载 Java 代码风格
|
||||||
|
|
||||||
|
**使用方式**: `/load-codestyle` 或 `/load-codestyle java`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 安装
|
## 安装
|
||||||
|
|
||||||
### 方式一：Claude Code 插件市场安装（推荐）
|
### 方式一：Claude Code 插件市场安装（推荐）
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,450 @@
|
||||||
|
---
|
||||||
|
name: chinaweal-quicknote
|
||||||
|
description: |
|
||||||
|
众望通 PMS 系统速记相关 API 工具。用于管理个人速记、标签和附件。
|
||||||
|
|
||||||
|
当用户提到以下场景时使用此 Skill：
|
||||||
|
(1) 速记、新增速记、查询速记、删除速记
|
||||||
|
(2) 速记标签管理
|
||||||
|
(3) 速记附件上传/下载/删除
|
||||||
|
(4) 发送企业微信通知
|
||||||
|
(5) 用户提到 "速记"、"quicknote"、"快记"
|
||||||
|
version: 1.0.0
|
||||||
|
license: Apache-2.0
|
||||||
|
metadata:
|
||||||
|
author: lirh
|
||||||
|
category: development
|
||||||
|
tags:
|
||||||
|
- pms
|
||||||
|
- chinaweal
|
||||||
|
- quicknote
|
||||||
|
- notes
|
||||||
|
---
|
||||||
|
|
||||||
|
# ChinaWeal 速记 API
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
|
||||||
|
此 Skill 用于调用众望通 PMS 系统的速记相关 API，包括速记管理、标签管理、附件管理和消息通知。
|
||||||
|
|
||||||
|
## 认证配置
|
||||||
|
|
||||||
|
使用此 Skill 前，需要配置环境变量 `CHINAWEAL_PMS_TOKEN`：
|
||||||
|
|
||||||
|
- **环境变量名称**: `CHINAWEAL_PMS_TOKEN`
|
||||||
|
- **用途**: PMS 系统的用户授权 Token
|
||||||
|
|
||||||
|
### 请求鉴权方式
|
||||||
|
|
||||||
|
所有 API 请求需要在请求头中携带 Authorization 信息：
|
||||||
|
|
||||||
|
```
|
||||||
|
Authorization: Bearer {CHINAWEAL_PMS_TOKEN}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Base URL
|
||||||
|
|
||||||
|
```
|
||||||
|
https://www.chinaweal.com.cn/pms-api
|
||||||
|
```
|
||||||
|
|
||||||
|
## 功能清单
|
||||||
|
|
||||||
|
### 功能1: 新增速记
|
||||||
|
|
||||||
|
创建一条新的速记记录。
|
||||||
|
|
||||||
|
**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/save`
|
||||||
|
|
||||||
|
**请求方法**: POST
|
||||||
|
|
||||||
|
**请求头**:
|
||||||
|
```
|
||||||
|
Authorization: Bearer {CHINAWEAL_PMS_TOKEN}
|
||||||
|
Content-Type: application/json
|
||||||
|
```
|
||||||
|
|
||||||
|
**请求体 (PmsQuickNote)**:
|
||||||
|
| 字段 | 类型 | 描述 |
|
||||||
|
|------|------|------|
|
||||||
|
| noteContent | string | 速记内容 |
|
||||||
|
| noteDate | string (date) | 速记日期，格式: yyyy-MM-dd |
|
||||||
|
| noteTime | string (date-time) | 速记时间 |
|
||||||
|
| tagNames | array[string] | 标签列表 |
|
||||||
|
| tagNamesStr | string | 标签名称字符串，用逗号分隔 |
|
||||||
|
|
||||||
|
**响应**: `RestResultPmsQuickNote`
|
||||||
|
- `code` - 状态码
|
||||||
|
- `msg` - 消息
|
||||||
|
- `data` - 创建的速记对象
|
||||||
|
|
||||||
|
**使用示例**:
|
||||||
|
```
|
||||||
|
帮我新增一条速记
|
||||||
|
创建一条速记，内容是今天完成了xxx
|
||||||
|
新增速记：完成了项目评审
|
||||||
|
```
|
||||||
|
|
||||||
|
### 功能2: 更新速记
|
||||||
|
|
||||||
|
更新已有的速记记录。
|
||||||
|
|
||||||
|
**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/update`
|
||||||
|
|
||||||
|
**请求方法**: POST
|
||||||
|
|
||||||
|
**请求头**:
|
||||||
|
```
|
||||||
|
Authorization: Bearer {CHINAWEAL_PMS_TOKEN}
|
||||||
|
Content-Type: application/json
|
||||||
|
```
|
||||||
|
|
||||||
|
**请求体 (PmsQuickNote)**:
|
||||||
|
| 字段 | 类型 | 描述 |
|
||||||
|
|------|------|------|
|
||||||
|
| id | string | 速记ID（必填） |
|
||||||
|
| noteContent | string | 速记内容 |
|
||||||
|
| noteDate | string (date) | 速记日期 |
|
||||||
|
| noteTime | string (date-time) | 速记时间 |
|
||||||
|
| tagNames | array[string] | 标签列表 |
|
||||||
|
| tagNamesStr | string | 标签名称字符串，用逗号分隔 |
|
||||||
|
|
||||||
|
**响应**: `RestResultPmsQuickNote`
|
||||||
|
|
||||||
|
**使用示例**:
|
||||||
|
```
|
||||||
|
更新速记 ID 为 xxx 的内容
|
||||||
|
修改速记：把内容改成xxx
|
||||||
|
```
|
||||||
|
|
||||||
|
### 功能3: 删除速记
|
||||||
|
|
||||||
|
删除指定的速记记录。
|
||||||
|
|
||||||
|
**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/delete`
|
||||||
|
|
||||||
|
**请求方法**: POST
|
||||||
|
|
||||||
|
**请求头**:
|
||||||
|
```
|
||||||
|
Authorization: Bearer {CHINAWEAL_PMS_TOKEN}
|
||||||
|
```
|
||||||
|
|
||||||
|
**查询参数**:
|
||||||
|
| 参数 | 类型 | 描述 |
|
||||||
|
|------|------|------|
|
||||||
|
| id | string | 速记ID（必填） |
|
||||||
|
|
||||||
|
**响应**: `RestResultObject`
|
||||||
|
|
||||||
|
**使用示例**:
|
||||||
|
```
|
||||||
|
删除速记 ID 为 xxx
|
||||||
|
删除速记
|
||||||
|
```
|
||||||
|
|
||||||
|
### 功能4: 分页查询速记列表
|
||||||
|
|
||||||
|
分页查询速记列表，支持按日期、内容、标签筛选。
|
||||||
|
|
||||||
|
**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/list`
|
||||||
|
|
||||||
|
**请求方法**: POST
|
||||||
|
|
||||||
|
**请求头**:
|
||||||
|
```
|
||||||
|
Authorization: Bearer {CHINAWEAL_PMS_TOKEN}
|
||||||
|
Content-Type: application/json
|
||||||
|
```
|
||||||
|
|
||||||
|
**请求体 (BaseQueryPmsQuickNoteQueryDTO)**:
|
||||||
|
| 字段 | 类型 | 描述 |
|
||||||
|
|------|------|------|
|
||||||
|
| entity.noteDate | string (date) | 速记日期，格式: yyyy-MM-dd |
|
||||||
|
| entity.noteContent | string | 速记内容（模糊搜索） |
|
||||||
|
| entity.tagName | string | 标签名称 |
|
||||||
|
| current | integer | 当前页 |
|
||||||
|
| size | integer | 每页显示条数 |
|
||||||
|
| orderFields | array[string] | 排序字段 |
|
||||||
|
| orderSorts | array[string] | 排序规则 (asc/desc) |
|
||||||
|
|
||||||
|
**响应**: `RestResultIPagePmsQuickNote`
|
||||||
|
- `data.records` - 速记列表
|
||||||
|
- `data.total` - 总记录数
|
||||||
|
- `data.current` - 当前页
|
||||||
|
- `data.size` - 每页条数
|
||||||
|
|
||||||
|
**使用示例**:
|
||||||
|
```
|
||||||
|
查询速记列表
|
||||||
|
查看最近一周的速记
|
||||||
|
按标签筛选速记
|
||||||
|
查找包含xxx的速记
|
||||||
|
```
|
||||||
|
|
||||||
|
### 功能5: 查询速记详情
|
||||||
|
|
||||||
|
根据速记ID查询详情。
|
||||||
|
|
||||||
|
**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/detail/{id}`
|
||||||
|
|
||||||
|
**请求方法**: GET
|
||||||
|
|
||||||
|
**请求头**:
|
||||||
|
```
|
||||||
|
Authorization: Bearer {CHINAWEAL_PMS_TOKEN}
|
||||||
|
```
|
||||||
|
|
||||||
|
**路径参数**:
|
||||||
|
| 参数 | 类型 | 描述 |
|
||||||
|
|------|------|------|
|
||||||
|
| id | string | 速记ID（必填） |
|
||||||
|
|
||||||
|
**响应**: `RestResultPmsQuickNote`
|
||||||
|
|
||||||
|
**使用示例**:
|
||||||
|
```
|
||||||
|
查询速记 xxx 的详情
|
||||||
|
查看速记 ID 为 xxx 的详细信息
|
||||||
|
```
|
||||||
|
|
||||||
|
### 功能6: 获取速记的标签列表
|
||||||
|
|
||||||
|
根据速记ID获取该速记的所有标签。
|
||||||
|
|
||||||
|
**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/tag/{noteId}`
|
||||||
|
|
||||||
|
**请求方法**: GET
|
||||||
|
|
||||||
|
**请求头**:
|
||||||
|
```
|
||||||
|
Authorization: Bearer {CHINAWEAL_PMS_TOKEN}
|
||||||
|
```
|
||||||
|
|
||||||
|
**路径参数**:
|
||||||
|
| 参数 | 类型 | 描述 |
|
||||||
|
|------|------|------|
|
||||||
|
| noteId | string | 速记ID（必填） |
|
||||||
|
|
||||||
|
**响应**: `RestResultListString` - 标签列表
|
||||||
|
|
||||||
|
**使用示例**:
|
||||||
|
```
|
||||||
|
获取速记 xxx 的标签
|
||||||
|
查看速记的标签列表
|
||||||
|
```
|
||||||
|
|
||||||
|
### 功能7: 获取前10个常用标签
|
||||||
|
|
||||||
|
获取当前用户使用最多的前10个标签。
|
||||||
|
|
||||||
|
**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/tag/list`
|
||||||
|
|
||||||
|
**请求方法**: POST
|
||||||
|
|
||||||
|
**请求头**:
|
||||||
|
```
|
||||||
|
Authorization: Bearer {CHINAWEAL_PMS_TOKEN}
|
||||||
|
Content-Type: application/json
|
||||||
|
```
|
||||||
|
|
||||||
|
**响应**: `RestResultListString` - 标签列表
|
||||||
|
|
||||||
|
**使用示例**:
|
||||||
|
```
|
||||||
|
获取我常用的标签
|
||||||
|
查看我使用最多的标签
|
||||||
|
```
|
||||||
|
|
||||||
|
### 功能8: 上传速记附件
|
||||||
|
|
||||||
|
为速记上传附件。
|
||||||
|
|
||||||
|
**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/attachment/upload`
|
||||||
|
|
||||||
|
**请求方法**: POST
|
||||||
|
|
||||||
|
**请求头**:
|
||||||
|
```
|
||||||
|
Authorization: Bearer {CHINAWEAL_PMS_TOKEN}
|
||||||
|
Content-Type: application/json
|
||||||
|
```
|
||||||
|
|
||||||
|
**查询参数**:
|
||||||
|
| 参数 | 类型 | 描述 |
|
||||||
|
|------|------|------|
|
||||||
|
| noteId | string | 速记ID（必填） |
|
||||||
|
|
||||||
|
**请求体**:
|
||||||
|
| 字段 | 类型 | 描述 |
|
||||||
|
|------|------|------|
|
||||||
|
| file | string | 上传的文件（base64或binary） |
|
||||||
|
|
||||||
|
**响应**: `RestResultPmsQuickNoteAttachment`
|
||||||
|
|
||||||
|
**使用示例**:
|
||||||
|
```
|
||||||
|
上传附件到速记 xxx
|
||||||
|
为速记添加附件
|
||||||
|
```
|
||||||
|
|
||||||
|
### 功能9: 获取速记附件列表
|
||||||
|
|
||||||
|
获取指定速记的所有附件。
|
||||||
|
|
||||||
|
**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/attachment/list/{noteId}`
|
||||||
|
|
||||||
|
**请求方法**: GET
|
||||||
|
|
||||||
|
**请求头**:
|
||||||
|
```
|
||||||
|
Authorization: Bearer {CHINAWEAL_PMS_TOKEN}
|
||||||
|
```
|
||||||
|
|
||||||
|
**路径参数**:
|
||||||
|
| 参数 | 类型 | 描述 |
|
||||||
|
|------|------|------|
|
||||||
|
| noteId | string | 速记ID（必填） |
|
||||||
|
|
||||||
|
**响应**: `RestResultListPmsQuickNoteAttachment`
|
||||||
|
|
||||||
|
**附件字段**:
|
||||||
|
| 字段 | 类型 | 描述 |
|
||||||
|
|------|------|------|
|
||||||
|
| id | string | 附件ID |
|
||||||
|
| noteId | string | 速记ID |
|
||||||
|
| fileName | string | 文件名 |
|
||||||
|
| fileFormat | string | 文件格式 |
|
||||||
|
| fileSize | integer | 文件大小(字节) |
|
||||||
|
| createTime | string | 创建时间 |
|
||||||
|
|
||||||
|
**使用示例**:
|
||||||
|
```
|
||||||
|
获取速记 xxx 的附件列表
|
||||||
|
查看速记有哪些附件
|
||||||
|
```
|
||||||
|
|
||||||
|
### 功能10: 下载速记附件
|
||||||
|
|
||||||
|
下载指定的速记附件。
|
||||||
|
|
||||||
|
**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/attachment/download/{attachmentId}`
|
||||||
|
|
||||||
|
**请求方法**: GET
|
||||||
|
|
||||||
|
**请求头**:
|
||||||
|
```
|
||||||
|
Authorization: Bearer {CHINAWEAL_PMS_TOKEN}
|
||||||
|
```
|
||||||
|
|
||||||
|
**路径参数**:
|
||||||
|
| 参数 | 类型 | 描述 |
|
||||||
|
|------|------|------|
|
||||||
|
| attachmentId | string | 附件ID（必填） |
|
||||||
|
|
||||||
|
**响应**: 文件内容 (byte)
|
||||||
|
|
||||||
|
**使用示例**:
|
||||||
|
```
|
||||||
|
下载附件 xxx
|
||||||
|
下载速记附件
|
||||||
|
```
|
||||||
|
|
||||||
|
### 功能11: 删除速记附件
|
||||||
|
|
||||||
|
删除指定的速记附件。
|
||||||
|
|
||||||
|
**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/quicknote/attachment/delete`
|
||||||
|
|
||||||
|
**请求方法**: POST
|
||||||
|
|
||||||
|
**请求头**:
|
||||||
|
```
|
||||||
|
Authorization: Bearer {CHINAWEAL_PMS_TOKEN}
|
||||||
|
```
|
||||||
|
|
||||||
|
**查询参数**:
|
||||||
|
| 参数 | 类型 | 描述 |
|
||||||
|
|------|------|------|
|
||||||
|
| attachmentId | string | 附件ID（必填） |
|
||||||
|
|
||||||
|
**响应**: `RestResultObject`
|
||||||
|
|
||||||
|
**使用示例**:
|
||||||
|
```
|
||||||
|
删除附件 xxx
|
||||||
|
删除速记附件
|
||||||
|
```
|
||||||
|
|
||||||
|
### 功能12: 发送企业微信通知
|
||||||
|
|
||||||
|
发送企业微信消息通知。
|
||||||
|
|
||||||
|
**接口地址**: `https://www.chinaweal.com.cn/pms-api/api/notice/entwx/send`
|
||||||
|
|
||||||
|
**请求方法**: POST
|
||||||
|
|
||||||
|
**请求头**:
|
||||||
|
```
|
||||||
|
Authorization: Bearer {CHINAWEAL_PMS_TOKEN}
|
||||||
|
```
|
||||||
|
|
||||||
|
**查询参数**:
|
||||||
|
| 参数 | 类型 | 描述 |
|
||||||
|
|------|------|------|
|
||||||
|
| message | string | 消息内容（必填） |
|
||||||
|
|
||||||
|
**响应**: `RestResultObject`
|
||||||
|
|
||||||
|
**使用示例**:
|
||||||
|
```
|
||||||
|
发送企业微信消息 xxx
|
||||||
|
发送通知：xxx
|
||||||
|
```
|
||||||
|
|
||||||
|
## 调用方式
|
||||||
|
|
||||||
|
使用 Bash 工具执行 curl 命令进行 API 调用。
|
||||||
|
|
||||||
|
### 环境变量
|
||||||
|
|
||||||
|
```bash
|
||||||
|
CHINAWEAL_PMS_TOKEN="your-token-here"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 示例命令
|
||||||
|
|
||||||
|
**新增速记**:
|
||||||
|
```bash
|
||||||
|
curl -X POST "https://www.chinaweal.com.cn/pms-api/api/quicknote/save" \
|
||||||
|
-H "Authorization: Bearer ${CHINAWEAL_PMS_TOKEN}" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"noteContent":"今天完成了项目评审","noteDate":"2026-04-10","tagNames":["工作","项目"]}'
|
||||||
|
```
|
||||||
|
|
||||||
|
**查询速记列表**:
|
||||||
|
```bash
|
||||||
|
curl -X POST "https://www.chinaweal.com.cn/pms-api/api/quicknote/list" \
|
||||||
|
-H "Authorization: Bearer ${CHINAWEAL_PMS_TOKEN}" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"current":1,"size":10}'
|
||||||
|
```
|
||||||
|
|
||||||
|
**查询速记详情**:
|
||||||
|
```bash
|
||||||
|
curl -X GET "https://www.chinaweal.com.cn/pms-api/api/quicknote/detail/{id}" \
|
||||||
|
-H "Authorization: Bearer ${CHINAWEAL_PMS_TOKEN}"
|
||||||
|
```
|
||||||
|
|
||||||
|
**删除速记**:
|
||||||
|
```bash
|
||||||
|
curl -X POST "https://www.chinaweal.com.cn/pms-api/api/quicknote/delete?id={id}" \
|
||||||
|
-H "Authorization: Bearer ${CHINAWEAL_PMS_TOKEN}"
|
||||||
|
```
|
||||||
|
|
||||||
|
## 注意事项
|
||||||
|
|
||||||
|
1. 确保环境变量 `CHINAWEAL_PMS_TOKEN` 已正确配置
|
||||||
|
2. 速记ID `id` 需要从 PMS 系统获取
|
||||||
|
3. 日期格式：`noteDate` 使用 `yyyy-MM-dd` 格式
|
||||||
|
4. 附件上传大小限制请参考 PMS 系统配置
|
||||||
|
|
@ -0,0 +1,64 @@
|
||||||
|
# load-codestyle
|
||||||
|
|
||||||
|
加载指定语言的代码风格参考文件。
|
||||||
|
|
||||||
|
## 目录结构
|
||||||
|
|
||||||
|
```
|
||||||
|
load-codestyle/
|
||||||
|
├── SKILL.md # Skill 定义文件
|
||||||
|
├── README.md # 本文件
|
||||||
|
├── style/ # 代码风格文件目录
|
||||||
|
│ ├── java/
|
||||||
|
│ │ └── java-code-style.md
|
||||||
|
│ ├── python/
|
||||||
|
│ │ └── python-code-style.md
|
||||||
|
│ └── ... # 可按需添加更多语言
|
||||||
|
└── memory/ # 记忆文件目录（自动生成）
|
||||||
|
└── codestyle-{language}.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## 使用方式
|
||||||
|
|
||||||
|
### 触发命令
|
||||||
|
|
||||||
|
- `/load-codestyle`
|
||||||
|
- `/load-codestyle java`
|
||||||
|
- "加载代码风格"
|
||||||
|
- "加载 Java 代码风格"
|
||||||
|
|
||||||
|
### 加载文件的路径
|
||||||
|
|
||||||
|
代码风格文件应放在：
|
||||||
|
```
|
||||||
|
~/.claude/skills/load-codestyle/style/{language}/*.md
|
||||||
|
```
|
||||||
|
|
||||||
|
例如 Java 语言：
|
||||||
|
```
|
||||||
|
~/.claude/skills/load-codestyle/style/java/*.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## 添加新的语言风格
|
||||||
|
|
||||||
|
1. 在 `style/` 目录下创建对应语言的文件夹
|
||||||
|
2. 添加 `.md` 格式的风格文件
|
||||||
|
3. 可以添加多个文件，会全部加载
|
||||||
|
|
||||||
|
示例：
|
||||||
|
```
|
||||||
|
style/
|
||||||
|
├── java/
|
||||||
|
│ ├── naming-conventions.md
|
||||||
|
│ ├── spring-boot-guidelines.md
|
||||||
|
│ └── database-standards.md
|
||||||
|
├── python/
|
||||||
|
│ └── python-code-style.md
|
||||||
|
└── go/
|
||||||
|
└── go-code-style.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## 已支持的语言
|
||||||
|
|
||||||
|
- Java（示例文件已添加）
|
||||||
|
- 可按需扩展其他语言
|
||||||
|
|
@ -0,0 +1,148 @@
|
||||||
|
---
|
||||||
|
name: load-codestyle
|
||||||
|
description: "加载指定语言的代码风格参考文件。Loads code style reference files for a specified language from skill目录/style/{language}/*.md"
|
||||||
|
argument-hint: "[language]"
|
||||||
|
version: "1.0.0"
|
||||||
|
user-invocable: true
|
||||||
|
allowed-tools: Read, Glob, Bash
|
||||||
|
---
|
||||||
|
|
||||||
|
# 代码风格加载器 (Code Style Loader)
|
||||||
|
|
||||||
|
## 触发条件
|
||||||
|
|
||||||
|
当用户说以下任意内容时启动：
|
||||||
|
- `/load-codestyle`
|
||||||
|
- "加载代码风格"
|
||||||
|
- "加载{语言}代码风格"
|
||||||
|
- "查看代码风格规范"
|
||||||
|
|
||||||
|
## 功能说明
|
||||||
|
|
||||||
|
本 Skill 负责从指定目录加载代码风格参考文件，并将其内容作为当前代码审查和编写的参考依据。
|
||||||
|
|
||||||
|
## 核心逻辑
|
||||||
|
|
||||||
|
### Step 1：确定语言
|
||||||
|
|
||||||
|
用户可以通过以下方式指定语言：
|
||||||
|
- 直接在命令中指定：如 `/load-codestyle java`
|
||||||
|
- 在对话中提及：如 "加载 Java 代码风格"
|
||||||
|
- 如果用户未指定，询问用户希望加载哪种语言的代码风格
|
||||||
|
|
||||||
|
### Step 2：查找风格文件
|
||||||
|
|
||||||
|
在以下位置查找代码风格文件：
|
||||||
|
|
||||||
|
**目录结构**：
|
||||||
|
```
|
||||||
|
{skill目录}/style/{language}/*.md
|
||||||
|
```
|
||||||
|
|
||||||
|
其中：
|
||||||
|
- `{skill目录}` 是技能配置的基础目录，默认为 `~/.claude/skills/load-codestyle/`
|
||||||
|
- `{language}` 是语言名称小写，如 `java`、`python`、`javascript`、`go` 等
|
||||||
|
|
||||||
|
**实际查找路径**：
|
||||||
|
```
|
||||||
|
~/.claude/skills/load-codestyle/style/{language}/*.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3：加载文件内容
|
||||||
|
|
||||||
|
1. 使用 `Glob` 工具查找匹配的文件
|
||||||
|
2. 使用 `Read` 工具读取每个匹配的文件
|
||||||
|
3. 汇总所有文件内容
|
||||||
|
|
||||||
|
### Step 4：输出结果
|
||||||
|
|
||||||
|
向用户展示：
|
||||||
|
```
|
||||||
|
已加载 {语言} 代码风格参考文件：
|
||||||
|
|
||||||
|
文件列表：
|
||||||
|
- file1.md
|
||||||
|
- file2.md
|
||||||
|
...
|
||||||
|
|
||||||
|
---
|
||||||
|
{文件1内容}
|
||||||
|
---
|
||||||
|
{文件2内容}
|
||||||
|
---
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 5：保存为上下文
|
||||||
|
|
||||||
|
将加载的风格文件内容保存到会话记忆中，以便后续代码审查和编写参考：
|
||||||
|
|
||||||
|
参考 `~/.claude/skills/load-codestyle/memory/codestyle-{language}.md`
|
||||||
|
|
||||||
|
## 支持的语言
|
||||||
|
|
||||||
|
| 语言 | 目录 |
|
||||||
|
|------|------|
|
||||||
|
| Java | `style/java/*.md` |
|
||||||
|
| Python | `style/python/*.md` |
|
||||||
|
| JavaScript | `style/javascript/*.md` |
|
||||||
|
| TypeScript | `style/typescript/*.md` |
|
||||||
|
| Go | `style/go/*.md` |
|
||||||
|
| C/C++ | `style/c/*.md` |
|
||||||
|
| Rust | `style/rust/*.md` |
|
||||||
|
| Kotlin | `style/kotlin/*.md` |
|
||||||
|
|
||||||
|
## 错误处理
|
||||||
|
|
||||||
|
- **目录不存在**：`style/{language}/` 目录不存在时，提示用户并列出已支持的目录
|
||||||
|
- **没有找到文件**：目录存在但没有 `.md` 文件时，提示用户
|
||||||
|
- **权限错误**：无法读取文件时，提示具体的权限问题
|
||||||
|
|
||||||
|
## 使用示例
|
||||||
|
|
||||||
|
```
|
||||||
|
用户：/load-codestyle java
|
||||||
|
|
||||||
|
助手：已加载 Java 代码风格参考文件：
|
||||||
|
|
||||||
|
文件列表：
|
||||||
|
- naming-conventions.md
|
||||||
|
- spring-boot-guidelines.md
|
||||||
|
|
||||||
|
---
|
||||||
|
# Java 命名规范
|
||||||
|
|
||||||
|
## 类命名
|
||||||
|
- 使用 UpperCamelCase
|
||||||
|
- 示例：UserService, OrderController
|
||||||
|
|
||||||
|
## 方法命名
|
||||||
|
- 使用 lowerCamelCase
|
||||||
|
- 示例：getUserById, createOrder
|
||||||
|
...
|
||||||
|
---
|
||||||
|
# Spring Boot 开发规范
|
||||||
|
|
||||||
|
## Controller 层
|
||||||
|
- 使用 @RestController 注解
|
||||||
|
- 返回统一响应格式 RestResult
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
## 记忆功能
|
||||||
|
|
||||||
|
本 Skill 会自动将加载的风格文件内容保存到记忆系统中，使得后续对话可以快速引用。
|
||||||
|
|
||||||
|
保存路径：`~/.claude/skills/load-codestyle/memory/codestyle-{language}.md`
|
||||||
|
|
||||||
|
格式：
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
name: codestyle-{language}
|
||||||
|
description: {语言} 代码风格参考
|
||||||
|
type: reference
|
||||||
|
language: {language}
|
||||||
|
---
|
||||||
|
|
||||||
|
{风格文件内容}
|
||||||
|
```
|
||||||
|
|
@ -0,0 +1,338 @@
|
||||||
|
# Java 代码风格规范
|
||||||
|
|
||||||
|
通用 Java 项目代码风格规范，适用于所有 Java 后端项目。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 项目结构
|
||||||
|
|
||||||
|
### 包组织
|
||||||
|
- 基础包按公司域名倒写 + 项目名，如 `com.company.project`
|
||||||
|
- 按业务域划分模块，如 `user/`、`order/`、`product/`
|
||||||
|
|
||||||
|
### 目录结构（各模块内）
|
||||||
|
```
|
||||||
|
controller/ # 控制层
|
||||||
|
service/ # 服务层接口
|
||||||
|
service/impl/ # 服务层实现
|
||||||
|
entity/ # 实体层
|
||||||
|
entity/dto/ # 数据传输对象
|
||||||
|
entity/vo/ # 视图对象
|
||||||
|
mapper/ # 数据访问层（MyBatis/JPA）
|
||||||
|
manager/ # 复杂业务编排
|
||||||
|
checker/ # 业务校验工具
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 命名规范
|
||||||
|
|
||||||
|
| 元素 | 规范 | 示例 |
|
||||||
|
|------|------|------|
|
||||||
|
| 类名 | PascalCase，2-41字符 | `UserService`、`OrderController` |
|
||||||
|
| 方法名 | camelCase，1-31字符 | `getUserById()`、`saveOrder()` |
|
||||||
|
| 变量名 | camelCase | `userId`、`orderList` |
|
||||||
|
| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`、`DEFAULT_PAGE_SIZE` |
|
||||||
|
| 包名 | 全小写，dot分隔 | `com.company.project.common.util` |
|
||||||
|
|
||||||
|
### 特定后缀/前缀
|
||||||
|
- Service 接口：前缀 `I`，如 `IUserService`
|
||||||
|
- Service 实现：后缀 `Impl`，如 `UserServiceImpl`
|
||||||
|
- DTO：后缀 `Dto` 或 `DTO`
|
||||||
|
- VO：后缀 `VO`
|
||||||
|
- 查询参数对象：后缀 `Query` 或 `Criteria`
|
||||||
|
- 校验工具类：后缀 `Checker` 或 `Validator`
|
||||||
|
- Manager：后缀 `Manager`（复杂业务编排层）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 代码格式
|
||||||
|
|
||||||
|
- **缩进**：4空格（禁止Tab）
|
||||||
|
- **行长度**：最大120-200字符
|
||||||
|
- **花括号**：K&R风格（同一行开括号）
|
||||||
|
- **文件最大行数**：通常不超过2000行
|
||||||
|
- **方法最大行数**：通常不超过150-300行
|
||||||
|
- **参数数量**：最多7-9个（超出考虑封装为对象）
|
||||||
|
- **if嵌套深度**：最多3-4层（超出考虑提取方法）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 注释规范
|
||||||
|
|
||||||
|
### 类级Javadoc
|
||||||
|
```java
|
||||||
|
/**
|
||||||
|
* 用户服务类
|
||||||
|
*
|
||||||
|
* <p>提供用户注册、登录、信息管理等核心功能</p>
|
||||||
|
*
|
||||||
|
* @author authorName
|
||||||
|
* @since 2024-01-01
|
||||||
|
*/
|
||||||
|
```
|
||||||
|
|
||||||
|
### 方法级Javadoc
|
||||||
|
```java
|
||||||
|
/**
|
||||||
|
* 根据用户ID获取用户信息
|
||||||
|
*
|
||||||
|
* @param userId 用户ID
|
||||||
|
* @return 用户信息，不存在返回null
|
||||||
|
* @author authorName
|
||||||
|
* @since 2024年1月1日 00:00:00
|
||||||
|
*/
|
||||||
|
public User getUserById(String userId) { }
|
||||||
|
```
|
||||||
|
|
||||||
|
### 字段注释
|
||||||
|
```java
|
||||||
|
/** 用户ID */
|
||||||
|
private String userId;
|
||||||
|
```
|
||||||
|
|
||||||
|
### 行内注释
|
||||||
|
- 注释放在代码上方或行尾
|
||||||
|
- 复杂业务逻辑需注释说明
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 异常处理
|
||||||
|
|
||||||
|
### 异常使用原则
|
||||||
|
- 业务异常使用自定义异常（如 `BusinessException`）
|
||||||
|
- 参数校验异常使用 `IllegalArgumentException` 或专用校验异常
|
||||||
|
- 系统异常使用 `RuntimeException` 包装
|
||||||
|
|
||||||
|
### 全局异常处理
|
||||||
|
```java
|
||||||
|
@ControllerAdvice
|
||||||
|
@RestController
|
||||||
|
public class GlobalExceptionHandler {
|
||||||
|
@ExceptionHandler(BusinessException.class)
|
||||||
|
public Result<?> handleBusinessException(BusinessException e) {
|
||||||
|
return Result.error(e.getCode(), e.getMessage());
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 日志记录
|
||||||
|
```java
|
||||||
|
log.info("用户登录成功，userId={}", userId);
|
||||||
|
log.warn("订单处理超时，orderId={}", orderId);
|
||||||
|
log.error("数据库连接失败", e);
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 常用代码模式
|
||||||
|
|
||||||
|
### DTO/Request/Response
|
||||||
|
```java
|
||||||
|
@Data
|
||||||
|
@Accessors(chain = true)
|
||||||
|
public class UserDTO implements Serializable {
|
||||||
|
@NotBlank(message = "用户名不能为空")
|
||||||
|
private String username;
|
||||||
|
|
||||||
|
@NotNull(message = "年龄不能为空")
|
||||||
|
@Min(value = 0, message = "年龄不能为负数")
|
||||||
|
private Integer age;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Entity
|
||||||
|
```java
|
||||||
|
@Data
|
||||||
|
@Entity
|
||||||
|
@Table(name = "t_user")
|
||||||
|
public class User implements Serializable {
|
||||||
|
@Id
|
||||||
|
@GeneratedValue(strategy = GenerationType.UUID)
|
||||||
|
private String id;
|
||||||
|
|
||||||
|
@Column(name = "username")
|
||||||
|
private String username;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Service
|
||||||
|
```java
|
||||||
|
public interface IUserService {
|
||||||
|
User getUserById(String userId);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Service
|
||||||
|
@RequiredArgsConstructor
|
||||||
|
public class UserServiceImpl implements IUserService {
|
||||||
|
private final IUserMapper userMapper;
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public User getUserById(String userId) {
|
||||||
|
return userMapper.selectById(userId);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Controller
|
||||||
|
```java
|
||||||
|
@RestController
|
||||||
|
@RequestMapping("/users")
|
||||||
|
@RequiredArgsConstructor
|
||||||
|
public class UserController {
|
||||||
|
private final IUserService userService;
|
||||||
|
|
||||||
|
@GetMapping("/{id}")
|
||||||
|
public Result<User> getUserById(@PathVariable String id) {
|
||||||
|
return Result.ok(userService.getUserById(id));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 校验工具
|
||||||
|
```java
|
||||||
|
public class UserValidator {
|
||||||
|
public static List<String> validate(UserDTO dto) {
|
||||||
|
List<String> errors = new ArrayList<>();
|
||||||
|
if (dto.getUsername() == null || dto.getUsername().isBlank()) {
|
||||||
|
errors.add("用户名不能为空");
|
||||||
|
}
|
||||||
|
return errors;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Enum
|
||||||
|
```java
|
||||||
|
@Getter
|
||||||
|
@AllArgsConstructor
|
||||||
|
public enum UserStatus {
|
||||||
|
ENABLE("启用", "enable"),
|
||||||
|
DISABLE("禁用", "disable");
|
||||||
|
|
||||||
|
private final String desc;
|
||||||
|
private final String code;
|
||||||
|
|
||||||
|
public static UserStatus getByCode(String code) {
|
||||||
|
return Arrays.stream(values())
|
||||||
|
.filter(e -> e.getCode().equals(code))
|
||||||
|
.findFirst()
|
||||||
|
.orElse(null);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 常量类
|
||||||
|
```java
|
||||||
|
public interface UserConstants {
|
||||||
|
int DEFAULT_PAGE_SIZE = 10;
|
||||||
|
int MAX_PAGE_SIZE = 100;
|
||||||
|
String DEFAULT_STATUS = "enable";
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. API设计规范
|
||||||
|
|
||||||
|
### HTTP方法约束
|
||||||
|
**强制约束：只能使用 GET 和 POST 方法**
|
||||||
|
|
||||||
|
| 操作 | 方法 | 路径 |
|
||||||
|
|------|------|------|
|
||||||
|
| 查询 | GET | `/users/{id}` |
|
||||||
|
| 列表 | GET | `/users?name={name}` |
|
||||||
|
| 新增 | POST | `/users` |
|
||||||
|
| 更新 | POST + `/update` | `/users/update` |
|
||||||
|
| 删除 | POST + `/remove` | `/users/remove` |
|
||||||
|
| 部分更新 | POST + `/patch` | `/users/patch` |
|
||||||
|
|
||||||
|
> **说明**：禁止使用 PUT、DELETE、PATCH 等其他HTTP方法。所有非GET请求均使用POST方法，通过路径后缀区分操作类型。
|
||||||
|
|
||||||
|
### 统一响应格式
|
||||||
|
公司基础框架提供 `RestResult<T>` 统一响应格式：
|
||||||
|
|
||||||
|
```java
|
||||||
|
return RestResult.ok(data); // 成功
|
||||||
|
return RestResult.ok(); // 无返回值的成功
|
||||||
|
return RestResult.error(ResultCode.DATA_NONE); // 错误（根据错误码）
|
||||||
|
return RestResult.error(ResultCode.BUSINESS_LOGIC_ERROR, "自定义错误信息");
|
||||||
|
```
|
||||||
|
|
||||||
|
> **说明**：`RestResult<T>` 是公司基础框架的核心组件，所有API响应必须使用该格式，不可自行定义其他响应格式。
|
||||||
|
|
||||||
|
### 统一响应格式
|
||||||
|
```java
|
||||||
|
public class RestResult<T> {
|
||||||
|
private int code;
|
||||||
|
private String message;
|
||||||
|
private T data;
|
||||||
|
|
||||||
|
public static <T> RestResult<T> ok(T data) { }
|
||||||
|
public static <T> RestResult<T> error(String message) { }
|
||||||
|
public static <T> RestResult<T> error(int code, String message) { }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. 事务处理
|
||||||
|
|
||||||
|
```java
|
||||||
|
@Transactional(rollbackFor = Exception.class)
|
||||||
|
public void saveUser(User user) {
|
||||||
|
userMapper.insert(user);
|
||||||
|
// 其他操作
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. API文档注解
|
||||||
|
|
||||||
|
### Swagger/OpenAPI 3.0
|
||||||
|
```java
|
||||||
|
@Api(tags = "用户管理")
|
||||||
|
@RestController
|
||||||
|
@RequestMapping("/users")
|
||||||
|
public class UserController {
|
||||||
|
@ApiOperation("根据ID获取用户")
|
||||||
|
@GetMapping("/{id}")
|
||||||
|
public RestResult<User> getUser(@ApiParam("用户ID") @PathVariable String id) { }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### SpringDoc OpenAPI（推荐）
|
||||||
|
```java
|
||||||
|
@Tag(name = "用户管理", description = "用户相关接口")
|
||||||
|
@RestController
|
||||||
|
@RequestMapping("/users")
|
||||||
|
public class UserController {
|
||||||
|
@Operation(summary = "根据ID获取用户")
|
||||||
|
@GetMapping("/{id}")
|
||||||
|
public RestResult<User> getUser(@Parameter(description = "用户ID") @PathVariable String id) { }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. 禁止事项
|
||||||
|
|
||||||
|
- **禁止魔法数字**：使用常量替代，如 `MAX_RETRY_COUNT`
|
||||||
|
- **禁止无用的import**：保持代码整洁
|
||||||
|
- **禁止长方法**：方法不超过150行，拆分为多个小方法
|
||||||
|
- **禁止深度嵌套**：if嵌套不超过3-4层
|
||||||
|
- **禁止硬编码**：配置信息放入配置文件
|
||||||
|
- **禁止空指针**：使用 `Objects.requireNonNull()` 或 Optional
|
||||||
|
- **禁止swallow异常**：异常必须记录或重新抛出
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. 最佳实践
|
||||||
|
|
||||||
|
- 使用 Lombok 减少样板代码（`@Data`、`@Slf4j`、`@Service`）
|
||||||
|
- 使用 `@RequiredArgsConstructor` 代替构造器注入
|
||||||
|
- 使用 Optional 处理可能为null的返回值
|
||||||
|
- 使用 Stream API 处理集合操作
|
||||||
|
- 接口方法参数不超过5个，超出使用DTO封装
|
||||||
|
- 日志记录使用占位符 `{}` 而非字符串拼接
|
||||||
Loading…
Reference in New Issue