Compare commits
2 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 zhanxi
|
8a28ca4d83 | ||
 湛兮
|
e9931a0923 |
@@ -0,0 +1,23 @@
|
||||
# access-manage Agent Skills
|
||||
|
||||
本目录存放 `access-manage` 的项目级 Agent skill。规则参考 SeaCloud 项目的 agent skill 组织方式，并按当前 Fastify、TypeScript、mysql2 和学习型后端项目场景保留最小必要规范。
|
||||
|
||||
## 使用入口
|
||||
|
||||
1. 进入仓库后先读 `AGENTS.md` 和 `RTK.md`。
|
||||
2. 创建或修改代码文件时，使用 `header-comment-sync` 保持中文文件头、导出声明和复杂逻辑注释同步。
|
||||
3. 提交或推送代码时，使用 `chinese-commit-message` 生成英文 type 前缀加中文摘要的 commit message。
|
||||
4. 目录、关键文件或脚本发生变化时，继续使用 `readme-structure-sync` 同步 README。
|
||||
5. 所有 skill 的触达文件补齐规则只处理本次任务相关文件，不要求为了单次任务全仓扫描。
|
||||
|
||||
## 当前项目事实
|
||||
|
||||
- 应用类型：门店员工权限管理后端。
|
||||
- 技术栈：Fastify、TypeScript、mysql2、zod、@fastify/jwt。
|
||||
- 关键边界：保持 controller、service、repository 分层，不引入 ORM。
|
||||
|
||||
## Skill 索引
|
||||
|
||||
- `header-comment-sync`：中文文件头、导出声明、复杂逻辑和风险边界注释。
|
||||
- `chinese-commit-message`：中文提交信息格式。
|
||||
- `readme-structure-sync`：README 与目录结构同步规则。
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
name: chinese-commit-message
|
||||
description: 在本仓库执行 git commit、整理提交说明或准备推送时使用，保持提交信息使用英文类型前缀加中文描述。
|
||||
---
|
||||
|
||||
# 中文提交信息
|
||||
|
||||
## 何时使用
|
||||
|
||||
- 用户要求提交、推送或整理 commit message。
|
||||
- 你准备执行 `git commit`。
|
||||
- 需要总结当前 diff 的提交说明。
|
||||
|
||||
## 核心要求
|
||||
|
||||
1. 提交信息必须使用英文 type 加中文摘要，例如 `feat: 补齐后端 agent skill 规范`。
|
||||
2. 常用 type 优先使用 `feat`、`fix`、`refactor`、`docs`、`chore`。
|
||||
3. 不强制 scope；只有模块边界非常清楚时才使用 `feat(auth): ...`。
|
||||
4. 标题部分使用简洁中文，直接说明改动，不写“修改一下”“更新代码”这类空泛描述。
|
||||
5. 非 trivial 改动建议补中文正文，用扁平 bullet 按文件或内容块说明关键动作。
|
||||
6. 正文与标题之间空一行；正文每条 bullet 对应一个独立文件或明确内容块。
|
||||
7. 如果用户指定提交信息，优先尊重用户原意，只做必要格式整理。
|
||||
|
||||
## 触达文件补齐
|
||||
|
||||
- 不要求为了提交信息单独全仓扫描。
|
||||
- 提交前如果 diff 中的触达文件明显违反对应 skill 的触达补齐要求，应先修正当前相关链路，再整理 commit message。
|
||||
- commit 正文应概括本次触达补齐，例如“补齐触达文件注释”“同步 README 目录说明”。
|
||||
|
||||
## 推荐结构
|
||||
|
||||
```text
|
||||
feat: 补齐后端 agent skill 规范
|
||||
|
||||
- .agents/README.md: 新增项目级 skill 索引和使用入口
|
||||
- .agents/skills: 补充中文提交与注释同步规则
|
||||
- AGENTS.md: 增加本地 skill 入口
|
||||
```
|
||||
|
||||
## 不推荐写法
|
||||
|
||||
- `新增规则`
|
||||
- `feat: add skills`
|
||||
- `fix bug`
|
||||
- `update`
|
||||
- 复杂改动只有标题没有正文。
|
||||
- 正文写成长段流水账或嵌套列表。
|
||||
|
||||
## 落地检查
|
||||
|
||||
- type 是否合理。
|
||||
- 中文摘要是否覆盖主改动。
|
||||
- 是否需要正文。
|
||||
- 正文是否按文件或内容块归纳。
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
name: header-comment-sync
|
||||
description: 在本仓库创建或修改 ts、tsx、js、jsx、mjs、cjs、vue、astro 文件时使用，保持中文文件头、导出声明、复杂逻辑和风险边界注释准确。
|
||||
---
|
||||
|
||||
# 注释规范与同步
|
||||
|
||||
## 目标
|
||||
|
||||
让下一次进入文件的维护者能快速理解当前职责、关键约束和风险边界。注释解释“为什么”和“边界”，不复述代码表面行为。
|
||||
|
||||
## 适用场景
|
||||
|
||||
- 新增或修改 controller、service、repository、schema、types、config、db、middleware、utils 或脚本文件。
|
||||
- 修改鉴权、权限、事务、SQL 条件、迁移、环境变量校验、后端协议转换或错误处理逻辑。
|
||||
- 发现旧注释与当前代码行为不一致。
|
||||
|
||||
## 核心原则
|
||||
|
||||
- 注释使用中文，描述当前事实。
|
||||
- 简单局部变量不强行注释。
|
||||
- 文件头说明文件当前职责，1 到 2 行即可。
|
||||
- 导出的函数、类型、常量、配置对象、repository method、service method 应有用途说明。
|
||||
- 复杂兼容逻辑、SQL 约束、事务边界、权限映射、密码安全和审计边界需要短注释。
|
||||
- TODO/FIXME 必须说明触发条件、剩余动作和可删除条件。
|
||||
|
||||
## 文件头规则
|
||||
|
||||
- 每个适用文件都要有准确文件头。
|
||||
- 如果文件必须以 `"use client"` 或 `"use server"` 开头，文件头注释放在指令之后、导入之前。
|
||||
- Vue 文件不为了补头注释重排模板结构；在 `<script>` 或 `<script setup>` 顶部补当前职责说明。
|
||||
- 文件头不要写“本文件用于...”这类空话，直接说明业务角色。
|
||||
|
||||
```ts
|
||||
/**
|
||||
* 员工仓储层，集中封装员工查询、状态变更、角色绑定和凭据安全相关 SQL。
|
||||
*/
|
||||
```
|
||||
|
||||
## JSDoc 与局部注释
|
||||
|
||||
- 导出的函数、类、类型、常量和配置对象优先使用 JSDoc。
|
||||
- 非导出但复杂的解析、格式化、请求构造、状态派生、事务回调也要补。
|
||||
- 只在局部逻辑确实有约束时使用行内注释，例如事务顺序、兼容字段、后端协议和临时迁移。
|
||||
- 不要在每一行、简单赋值、短生命周期变量上堆注释。
|
||||
|
||||
## 触达文件补齐
|
||||
|
||||
- 不要求为了注释规范单独全仓扫描。
|
||||
- 只要本次任务修改了适用文件，就顺手补齐明显缺失或过时的文件头、导出声明、共享类型、复杂回调和协议注释。
|
||||
- 大文件可按触达区域优先，但同文件内裸露的顶层导出和共享类型应一起补。
|
||||
- 如果一次补齐整个大文件会明显超出需求范围，至少补齐当前需求链路和顶层声明，并在交付说明里说明剩余范围。
|
||||
|
||||
## 不推荐的写法
|
||||
|
||||
- 注释只写“处理数据”“点击事件”这种无信息内容。
|
||||
- 注释描述旧方案，和当前代码矛盾。
|
||||
- 为简单赋值、短生命周期变量写注释。
|
||||
- 用英文口号、emoji 或情绪化标记替代项目内中文说明。
|
||||
|
||||
## 落地检查
|
||||
|
||||
- 修改后的文件头是否准确。
|
||||
- 新增/修改的导出声明是否有必要说明。
|
||||
- 复杂逻辑是否解释了约束而不是复述代码。
|
||||
- 旧注释是否仍然可信。
|
||||
@@ -1 +1,14 @@
|
||||
@RTK.md
|
||||
|
||||
# access-manage Agent 入口
|
||||
|
||||
## 必用 Skill
|
||||
|
||||
- 创建或修改 `ts`、`tsx`、`js`、`jsx`、`mjs`、`cjs`、`vue`、`astro` 文件时，使用 `./.agents/skills/header-comment-sync/SKILL.md`。
|
||||
- 执行 `git commit`、整理提交说明或准备推送时，使用 `./.agents/skills/chinese-commit-message/SKILL.md`。
|
||||
- 新增、删除、移动目录或关键入口文件时，继续使用 `./.agents/skills/readme-structure-sync/SKILL.md`。
|
||||
|
||||
## 本地规则
|
||||
|
||||
- 先读 `RTK.md`，再按任务读取 `.agents/README.md` 中匹配的 skill。
|
||||
- skill 的触达文件补齐只处理本次修改相关文件，不为单次任务全仓扫描。
|
||||
|
||||
@@ -36,8 +36,11 @@
|
||||
```text
|
||||
.
|
||||
├── .agents/
|
||||
│ ├── README.md # 项目级 Agent skill 索引和使用入口
|
||||
│ └── skills/
|
||||
│ └── readme-structure-sync/ # README 和目录结构同步维护规则
|
||||
│ ├── chinese-commit-message/ # 中文提交信息规范
|
||||
│ ├── header-comment-sync/ # 中文文件头和注释同步规范
|
||||
│ └── readme-structure-sync/ # README 和目录结构同步维护规则
|
||||
├── .env.development # 默认本地开发环境变量文件，不提交到仓库
|
||||
├── .env.local / .env.production # 可选环境变量文件，不提交到仓库
|
||||
├── .gitignore # Git 忽略规则，排除本地配置、依赖和编译产物
|
||||
@@ -93,6 +96,9 @@
|
||||
|
||||
| 路径 | 作用 |
|
||||
| --- | --- |
|
||||
| `.agents/README.md` | 项目级 Agent skill 索引和使用入口。 |
|
||||
| `.agents/skills/chinese-commit-message/` | 项目内 skill。约定提交信息使用英文 type 前缀加中文描述。 |
|
||||
| `.agents/skills/header-comment-sync/` | 项目内 skill。约定触达代码文件时同步中文文件头、导出声明和复杂逻辑注释。 |
|
||||
| `.agents/skills/readme-structure-sync/` | 项目内 skill。约定当目录、重要文件或 `package.json` 脚本变化时，同步更新 README。 |
|
||||
| `.env.development` | 当前 `package.json` 脚本默认读取的本地开发环境变量文件；该文件只保留在本机，不提交到仓库。 |
|
||||
| `.env.local` / `.env.production` | 本机已有的其他环境变量文件；代码已允许 `APP_ENV=local/develop/production` 区分本地、测试和生产，切换脚本时可以复用。 |
|
||||
|
||||
Reference in New Issue
Block a user