feat: 融合 devflow-claude P0 批机制 (REQ-20260416-0017)
P0-1: SessionStart Hook — hooks/session-context.sh 从分支名解析 REQ-ID，调 MCP API 查询需求详情注入 system-reminder P0-2: PreToolUse Hook — hooks/pre-tool-confirm.sh 拦截生产推送、force push、docker prod 容器操作、git reset --hard 等 P0-3: Release Draft 闸门设计文档 — docs/design/release-draft-gate.md 完整架构 + 渐进式落地路径（拆 7 个子任务延后） 附最小可用脚本 hooks/release-draft.sh 创建 Gitea draft release P0-4: Memory 隔离规则 — 写入 req-prd / req-design / req-workflow 禁止 auto-memory 污染模板产出物（章节结构、字段定义、文档结构） P0-5: CLAUDE.md 架构检查 + 架构片段库 dev-coding skill 执行前检查架构关键词 新增 templates/claude-md-snippets/ 含 Go+Gin / React+AntD / Vue+Element / MCP+TS / generic 五套骨架 P0-6: /commit 分支保护自动化 — 新 skill dev-commit-plugin 保护分支自动建功能分支 + Conventional Commits + REQ-XXX 自动关联 安装: bash hooks/install.sh 后续: P0-3 完整实现拆 7 个子任务（P0-3.1 ~ P0-3.7） 建议先部署 hooks 跑 1-2 周观察，再推进 Release 机制落地
This commit is contained in:
@@ -490,3 +490,55 @@ fi
|
||||
| `dev-ios` | iOS 开发（插件，按需加载）|
|
||||
| `dev-android` | Android 开发（插件，按需加载）|
|
||||
| `dev-mcp` | MCP bridge 开发（插件，按需加载）|
|
||||
|
||||
---
|
||||
|
||||
## CLAUDE.md 架构检查机制（REQ-20260416-0017 P0-5）
|
||||
|
||||
**原则：本 skill 不硬编码任何项目的架构细节，从项目 CLAUDE.md 读取**。
|
||||
|
||||
### 为什么
|
||||
|
||||
同一套 skill 要支持多个技术栈（Go+Gin / React+AntD / Vue+Element / Python+FastAPI）。如果把分层、命名、目录结构写死在 SKILL.md 里，跨项目就会冲突。
|
||||
|
||||
devflow-claude 的做法（借鉴）：skill 只管**流程和模板**，项目架构由 CLAUDE.md 的 "Architecture" / "项目架构" 章节定义。
|
||||
|
||||
### 执行前检查
|
||||
|
||||
开始编码任务前，skill 先检查项目根 `CLAUDE.md`：
|
||||
|
||||
```bash
|
||||
# 检查 CLAUDE.md 是否含架构关键词
|
||||
if [ -f "CLAUDE.md" ]; then
|
||||
if grep -qiE "(架构|分层|目录结构|tech stack|architecture|project structure)" CLAUDE.md; then
|
||||
echo "✅ 检测到项目架构信息"
|
||||
else
|
||||
echo "⚠️ CLAUDE.md 缺少架构描述"
|
||||
echo " dev-coding 需要架构信息来生成准确的文件路径和分层顺序"
|
||||
echo ""
|
||||
echo " 📋 建议操作:"
|
||||
echo " - 查看预置架构片段: ai-proj-helper/skills-dev/dev-coding-plugin/templates/claude-md-snippets/"
|
||||
echo " - 选择匹配技术栈的片段，补充到 CLAUDE.md 的 '## Architecture' 章节"
|
||||
echo ""
|
||||
echo " ⚠️ 继续执行，但生成的文件路径可能不够准确"
|
||||
fi
|
||||
else
|
||||
echo "⚠️ 未找到项目 CLAUDE.md，建议创建"
|
||||
fi
|
||||
```
|
||||
|
||||
### 架构片段模板库
|
||||
|
||||
位于 `skills-dev/dev-coding-plugin/templates/claude-md-snippets/`：
|
||||
|
||||
| 文件 | 适用场景 |
|
||||
|------|---------|
|
||||
| `go-gin-gorm.md` | Go + Gin + GORM 后端（ai-proj backend 风格） |
|
||||
| `react-antd.md` | React + TypeScript + Ant Design（ai-proj frontend 风格） |
|
||||
| `vue-element.md` | Vue 3 + Element Plus（coolbuy-paas 风格） |
|
||||
| `mcp-typescript.md` | MCP bridge TypeScript（mcp-task-bridge 风格） |
|
||||
| `generic.md` | 通用空白骨架 |
|
||||
|
||||
### 非阻断原则
|
||||
|
||||
架构信息缺失时**仅警告不阻止**。用户仍可继续，但会被告知"生成的建议可能不够准确"。
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
<!-- 复制此片段到项目根 CLAUDE.md 的 "## Architecture" 章节，按实际情况填写 -->
|
||||
|
||||
## Architecture
|
||||
|
||||
### 技术栈
|
||||
|
||||
- **语言**: _TODO_
|
||||
- **框架**: _TODO_
|
||||
- **数据库**: _TODO_
|
||||
- **缓存**: _TODO_
|
||||
- **部署**: _TODO_
|
||||
|
||||
### 目录结构
|
||||
|
||||
```
|
||||
project-root/
|
||||
├── ???/ # _TODO: 说明_
|
||||
├── ???/ # _TODO_
|
||||
└── ???/
|
||||
```
|
||||
|
||||
### 分层 / 模块规则
|
||||
|
||||
1. _TODO: 依赖方向_
|
||||
2. _TODO: 允许/禁止的跨层调用_
|
||||
|
||||
### 命名规范
|
||||
|
||||
| 类型 | 约定 | 示例 |
|
||||
|------|------|------|
|
||||
| _TODO_ | _TODO_ | _TODO_ |
|
||||
|
||||
### 错误处理
|
||||
|
||||
_TODO_
|
||||
|
||||
### 日志
|
||||
|
||||
_TODO_
|
||||
|
||||
### 测试
|
||||
|
||||
_TODO_
|
||||
|
||||
### 其他关键约定
|
||||
|
||||
- _TODO_
|
||||
@@ -0,0 +1,56 @@
|
||||
<!-- 复制此片段到项目根 CLAUDE.md 的 "## Architecture" 章节 -->
|
||||
|
||||
## Architecture
|
||||
|
||||
### 分层结构（Go + Gin + GORM）
|
||||
|
||||
```
|
||||
backend/
|
||||
├── routes/ # HTTP 路由定义（按模块拆分）
|
||||
├── handlers/ # 请求解析 + 响应组装（薄层，不含业务）
|
||||
├── services/ # 业务逻辑（事务、组合、校验）
|
||||
├── models/ # GORM 数据模型
|
||||
├── database/ # Repository 层（SQL、查询）
|
||||
├── middleware/ # 认证、CORS、日志、限流
|
||||
├── migrations/ # SQL 迁移文件
|
||||
└── utils/ # 通用工具（密码、签名等）
|
||||
```
|
||||
|
||||
### 分层规则（强制）
|
||||
|
||||
1. **请求流向**：Route → Handler → Service → Database → Models
|
||||
2. **Handler 禁止直接访问 database**：必须走 Service 层
|
||||
3. **Service 禁止调用 Handler 或 Route**：单向依赖
|
||||
4. **Model 仅定义结构 + GORM tag**：不含业务方法
|
||||
|
||||
### 命名规范
|
||||
|
||||
| 类型 | 约定 | 示例 |
|
||||
|------|------|------|
|
||||
| 文件名 | snake_case | `user_service.go` |
|
||||
| 包名 | lowercase | `services`, `handlers` |
|
||||
| 导出函数/类型 | PascalCase | `CreateUser`, `UserRepository` |
|
||||
| 内部函数 | camelCase | `validatePassword` |
|
||||
| 常量 | SCREAMING_SNAKE_CASE | `MAX_RETRY_COUNT` |
|
||||
|
||||
### 错误处理
|
||||
|
||||
- 使用 `errors.New()` 或自定义 error type
|
||||
- Handler 层统一返回 `{"code": X, "msg": "...", "data": ...}`
|
||||
- Service 层返回原始 error，由 Handler 转换
|
||||
|
||||
### 日志
|
||||
|
||||
- 使用结构化 log：`log.WithField("user_id", uid).Info("...")`
|
||||
- 禁用 `fmt.Println` / `print`
|
||||
|
||||
### 测试
|
||||
|
||||
- 单元测试文件名：`xxx_test.go`
|
||||
- 使用 `testify/assert`
|
||||
- Mock 用 `testify/mock` 或 `gomock`
|
||||
|
||||
### 依赖检查
|
||||
|
||||
- **新 handler 禁止直接 `import database/`**：需走 Service 层
|
||||
- `./scripts/check-architecture.sh check` 作为 CI 门禁
|
||||
@@ -0,0 +1,75 @@
|
||||
<!-- 复制此片段到项目根 CLAUDE.md 的 "## Architecture" 章节 -->
|
||||
|
||||
## Architecture
|
||||
|
||||
### 目录结构（MCP Bridge - TypeScript）
|
||||
|
||||
```
|
||||
mcp-task-bridge/
|
||||
├── src/
|
||||
│ ├── tools/ # MCP tool 定义（每个工具一个文件）
|
||||
│ ├── resources/ # MCP resources（若有）
|
||||
│ ├── prompts/ # MCP prompts（若有）
|
||||
│ ├── client/ # 后端 REST API 客户端
|
||||
│ ├── utils/ # 工具函数
|
||||
│ └── index.ts # 入口
|
||||
├── tests/
|
||||
└── dist/ # 编译产物（不提交）
|
||||
```
|
||||
|
||||
### 工具定义规范
|
||||
|
||||
每个 MCP tool 一个文件：
|
||||
|
||||
```typescript
|
||||
// tools/create-task.ts
|
||||
export const createTaskTool: Tool = {
|
||||
name: 'create_task',
|
||||
description: '...',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: { ... },
|
||||
required: [...]
|
||||
}
|
||||
};
|
||||
|
||||
export async function handleCreateTask(args) { ... }
|
||||
```
|
||||
|
||||
### 后端 API 调用
|
||||
|
||||
- 所有 REST 请求通过 `src/client/api.ts` 统一封装
|
||||
- 认证头由 client 自动附加（不在 tool 里处理）
|
||||
- 错误统一转成 MCP error response
|
||||
|
||||
### 命名规范
|
||||
|
||||
| 类型 | 约定 | 示例 |
|
||||
|------|------|------|
|
||||
| MCP tool name | snake_case | `create_task`, `list_requirements` |
|
||||
| 文件名 | kebab-case | `create-task.ts` |
|
||||
| 函数名 | camelCase | `handleCreateTask` |
|
||||
| Tool 变量 | camelCase + `Tool` | `createTaskTool` |
|
||||
|
||||
### 构建与部署
|
||||
|
||||
- `npm run build` → `dist/`
|
||||
- **修改代码后必须重新 build**：`pkill -f mcp-task-bridge/dist/index.js` 重启 MCP server
|
||||
- 不能直接运行 TypeScript 源码
|
||||
|
||||
### 环境配置
|
||||
|
||||
- `dev` 环境：`ai-proj-dev` MCP server
|
||||
- `prod` 环境：`ai-proj-prod` MCP server
|
||||
- 禁止跨环境传数据（dev 需求不能关联 prod 任务）
|
||||
|
||||
### 测试
|
||||
|
||||
- Jest + ts-jest
|
||||
- 集成测试模拟真实 MCP 协议
|
||||
|
||||
### 常见错误
|
||||
|
||||
- **Rule 1**: MCP 端点必须 `/api/v1/mcp/` 前缀
|
||||
- **Rule 2**: 修改后必须 rebuild + 重启
|
||||
- **Rule 3**: 环境隔离（dev / prod）
|
||||
@@ -0,0 +1,78 @@
|
||||
<!-- 复制此片段到项目根 CLAUDE.md 的 "## Architecture" 章节 -->
|
||||
|
||||
## Architecture
|
||||
|
||||
### 目录结构（React + TypeScript + Ant Design）
|
||||
|
||||
```
|
||||
frontend/src/
|
||||
├── pages/ # 页面级组件（路由对应）
|
||||
├── components/ # 可复用 UI 组件
|
||||
├── services/ # API 客户端（Axios 封装）
|
||||
├── hooks/ # 自定义 React Hooks
|
||||
├── contexts/ # Context Providers（auth, timer 等）
|
||||
├── utils/ # 工具函数（auth, validation, date 等）
|
||||
├── types/ # TypeScript 类型定义
|
||||
└── config/ # Feature flags, 性能配置
|
||||
```
|
||||
|
||||
### 状态管理
|
||||
|
||||
| 状态类型 | 方案 |
|
||||
|---------|------|
|
||||
| 服务器状态 | React Query (TanStack Query) |
|
||||
| 全局状态 | Context API |
|
||||
| 本地状态 | useState / useReducer |
|
||||
| 表单状态 | Ant Design Form |
|
||||
|
||||
**禁止**：Redux / MobX（本项目不使用）
|
||||
|
||||
### 路由
|
||||
|
||||
- React Router v6
|
||||
- 路由定义集中在 `src/routes/`
|
||||
- 懒加载：`const Page = lazy(() => import(...))`
|
||||
|
||||
### API 调用
|
||||
|
||||
- 使用 `services/` 下的封装函数，不要在组件里直接 `axios.get`
|
||||
- 响应类型必须有 TypeScript interface
|
||||
- 错误统一由 axios 拦截器处理
|
||||
|
||||
### 样式
|
||||
|
||||
- Ant Design 组件 + CSS Module
|
||||
- 禁止内联 `style={{ ... }}` 用于复杂样式
|
||||
- 全局变量走 CSS Variables
|
||||
|
||||
### Modal 安全规则（重要）
|
||||
|
||||
`Modal.success/info/warning/error` 是非阻塞调用，后续 UI 操作必须放在 `onOk` 回调中：
|
||||
|
||||
```tsx
|
||||
// WRONG
|
||||
Modal.success({ title: '成功' });
|
||||
setNextModalOpen(true); // 立即执行，两个 modal 冲突
|
||||
|
||||
// CORRECT
|
||||
Modal.success({
|
||||
title: '成功',
|
||||
onOk: () => setNextModalOpen(true),
|
||||
});
|
||||
```
|
||||
|
||||
### 命名规范
|
||||
|
||||
| 类型 | 约定 | 示例 |
|
||||
|------|------|------|
|
||||
| 组件文件 | PascalCase | `UserProfile.tsx` |
|
||||
| Hook 文件 | camelCase | `useAuth.ts` |
|
||||
| 工具文件 | kebab-case | `date-utils.ts` |
|
||||
| 组件名 | PascalCase | `UserProfile` |
|
||||
| Hook 名 | `use` 前缀 | `useAuth` |
|
||||
|
||||
### 测试
|
||||
|
||||
- 单测：Jest + React Testing Library
|
||||
- E2E：Playwright
|
||||
- 测试文件：`xxx.test.tsx` 与源文件同目录
|
||||
@@ -0,0 +1,67 @@
|
||||
<!-- 复制此片段到项目根 CLAUDE.md 的 "## Architecture" 章节 -->
|
||||
|
||||
## Architecture
|
||||
|
||||
### 目录结构（Vue 3 + TypeScript + Element Plus）
|
||||
|
||||
```
|
||||
src/
|
||||
├── views/ # 页面级组件（路由对应）
|
||||
├── components/ # 可复用组件
|
||||
├── api/ # API 封装
|
||||
├── stores/ # Pinia stores
|
||||
├── composables/ # 组合式函数（use* hooks）
|
||||
├── utils/ # 工具函数
|
||||
├── types/ # TypeScript 类型定义
|
||||
└── router/ # Vue Router 配置
|
||||
```
|
||||
|
||||
### 状态管理
|
||||
|
||||
- **Pinia**（官方推荐）
|
||||
- 每个业务模块一个 store：`stores/user.ts`、`stores/order.ts`
|
||||
- 禁止直接在组件里写持久状态
|
||||
|
||||
### 路由
|
||||
|
||||
- Vue Router 4
|
||||
- 路由守卫统一在 `router/guards.ts`
|
||||
- 懒加载：`component: () => import('@/views/...')`
|
||||
|
||||
### Composition API
|
||||
|
||||
- **强制使用 `<script setup>`**，禁止 Options API
|
||||
- Props 用 `defineProps<T>()`，Emits 用 `defineEmits<T>()`
|
||||
|
||||
### API 调用
|
||||
|
||||
- `api/` 下按模块划分：`api/user.ts`、`api/order.ts`
|
||||
- 每个函数返回类型明确
|
||||
- 错误由 axios 拦截器统一处理
|
||||
|
||||
### 命名规范
|
||||
|
||||
| 类型 | 约定 | 示例 |
|
||||
|------|------|------|
|
||||
| 组件文件 | PascalCase | `UserProfile.vue` |
|
||||
| Composable | camelCase + use 前缀 | `useAuth.ts` |
|
||||
| Store | camelCase | `useUserStore` |
|
||||
| API 文件 | kebab-case | `user-api.ts` |
|
||||
| 工具函数 | camelCase | `formatDate` |
|
||||
|
||||
### 样式
|
||||
|
||||
- SCSS + Element Plus 主题
|
||||
- scoped style（避免全局污染）
|
||||
- 全局变量走 SCSS 变量或 CSS Variables
|
||||
|
||||
### 国际化
|
||||
|
||||
- 使用 vue-i18n
|
||||
- 消息文件：`src/locales/zh.json` / `en.json`
|
||||
- 禁止硬编码文本：用 `t('path.to.key')`
|
||||
|
||||
### 测试
|
||||
|
||||
- 单测：Vitest + Vue Test Utils
|
||||
- E2E：Playwright / Cypress
|
||||
8
skills-dev/dev-commit-plugin/.claude-plugin/plugin.json
Normal file
8
skills-dev/dev-commit-plugin/.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"name": "dev-commit-plugin",
|
||||
"description": "智能 /commit 命令：分支保护 + 自动建功能分支 + Conventional Commits 生成",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "qiudl"
|
||||
}
|
||||
}
|
||||
144
skills-dev/dev-commit-plugin/skills/SKILL.md
Normal file
144
skills-dev/dev-commit-plugin/skills/SKILL.md
Normal file
@@ -0,0 +1,144 @@
|
||||
---
|
||||
name: dev-commit
|
||||
description: 智能 git commit — 分支保护 + 自动建功能分支 + Conventional Commits 生成。当用户说"提交代码"、"commit"、"/commit"、"保存修改"时自动激活。
|
||||
---
|
||||
|
||||
# dev-commit Skill — 智能提交
|
||||
|
||||
借鉴自 devflow-claude `/req:commit`。源自 REQ-20260416-0017 P0-6。
|
||||
|
||||
## 核心功能
|
||||
|
||||
**用户说"/commit" 或 "提交代码" 时执行：**
|
||||
|
||||
1. **分支合规检查**
|
||||
2. **自动建功能分支**（若在保护分支）
|
||||
3. **Conventional Commits 生成**
|
||||
4. **自动关联 REQ-XXX**
|
||||
|
||||
## 流程详解
|
||||
|
||||
### 1. 分支合规检查（强制）
|
||||
|
||||
```bash
|
||||
CURRENT_BRANCH=$(git symbolic-ref --short HEAD)
|
||||
|
||||
# 保护分支名单
|
||||
PROTECTED_BRANCHES="main master develop production"
|
||||
|
||||
for b in $PROTECTED_BRANCHES; do
|
||||
if [ "$CURRENT_BRANCH" = "$b" ]; then
|
||||
IS_PROTECTED=1
|
||||
break
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
**铁律**：**绝对禁止**在 main / develop / master / production 分支上直接 commit。
|
||||
|
||||
### 2. 保护分支上有改动 → 自动建功能分支
|
||||
|
||||
```
|
||||
检测到 main/develop 有未提交改动：
|
||||
|
||||
推荐方案：
|
||||
1. 自动建分支 feat/xxx 并切换过去（推荐）
|
||||
2. 取消本次 commit，手动切分支
|
||||
3. 临时 stash 后切分支
|
||||
|
||||
【默认选 1】
|
||||
```
|
||||
|
||||
**分支命名自动推断：**
|
||||
- 从对话上下文：如果刚在讨论 "REQ-20260416-0017" → `feat/REQ-20260416-0017-summary`
|
||||
- 从文件变更：扫描 staged files 的路径 → 推断模块（如 `backend/services/user/` → `feat/user-xxx`）
|
||||
- 从 commit message 意图：如果意图是 fix → `fix/xxx`
|
||||
|
||||
**前缀规则：**
|
||||
- `feat/` — 新功能
|
||||
- `fix/` — bug 修复
|
||||
- `chore/` — 杂项（依赖升级、CI 调整等）
|
||||
- `refactor/` — 重构
|
||||
- `docs/` — 文档
|
||||
|
||||
### 3. Conventional Commits 生成
|
||||
|
||||
**格式：**
|
||||
```
|
||||
<type>(<scope>): <description> [(REQ-XXX)] [closes #N]
|
||||
```
|
||||
|
||||
**type：**
|
||||
- feat - 新功能
|
||||
- fix - 修复
|
||||
- chore - 杂项
|
||||
- refactor - 重构
|
||||
- docs - 文档
|
||||
- test - 测试
|
||||
- perf - 性能
|
||||
- style - 格式
|
||||
|
||||
**scope：**
|
||||
- 从修改的文件路径推断：`backend/services/user/` → `user`
|
||||
- `frontend/src/pages/login/` → `login`
|
||||
|
||||
**示例：**
|
||||
```
|
||||
feat(mcp): 新增 set_requirement_reviewers 工具 (REQ-20260415-0023)
|
||||
fix(frontend): 403 权限重载死循环
|
||||
chore(cicd): 精简 CI/CD 流程，移除 Staging 环境 (REQ-20260415-0004) closes #242
|
||||
```
|
||||
|
||||
### 4. REQ-XXX 自动关联
|
||||
|
||||
**查找顺序：**
|
||||
1. 当前分支名：`feat/REQ-20260416-0017-xxx` → 提取 `REQ-20260416-0017`
|
||||
2. 最近对话中提到的 REQ ID
|
||||
3. MCP 查询当前用户的"进行中"需求（如只有一个，直接用）
|
||||
|
||||
**分支名含 `-iN` 时追加 `closes #N`：**
|
||||
```
|
||||
feat/REQ-xxx-i42 + commit → commit message 自动加 "closes #42"
|
||||
```
|
||||
|
||||
### 5. 提交确认
|
||||
|
||||
提交前展示预览：
|
||||
```
|
||||
即将执行：
|
||||
分支: feat/mcp-set-reviewers
|
||||
Files: backend/mcp/tools/set_reviewers.go, mcp-task-bridge/src/tools/set-reviewers.ts
|
||||
Message:
|
||||
feat(mcp): 新增 set_requirement_reviewers 工具 (REQ-20260415-0023)
|
||||
|
||||
确认提交？(y/n)
|
||||
```
|
||||
|
||||
## 与 ai-proj 集成
|
||||
|
||||
- **查询当前需求**：通过 MCP `mcp__ai-proj__find_requirement` 或 `list_requirements` 找 user 进行中的
|
||||
- **commit 后可选**：调用 `mcp__ai-proj__update_task` 更新关联任务进度
|
||||
|
||||
## 排除项
|
||||
|
||||
本 skill **不做**：
|
||||
- 推送远程（留给 `/pr` 或 `git push`）
|
||||
- 创建 PR（留给 pull-request skill）
|
||||
- 代码评审（留给 dev-review skill）
|
||||
|
||||
职责边界清晰，防止单命令膨胀。
|
||||
|
||||
## 风险控制
|
||||
|
||||
1. **保护分支改动不得 commit** — 强制拦截
|
||||
2. **message 必须用 Conventional Commits** — 后续 changelog 依赖
|
||||
3. **REQ-XXX 关联尽量自动推断** — 但推断不出不阻断
|
||||
|
||||
## 安装方式
|
||||
|
||||
本 skill 自动随 ai-proj-helper marketplace 加载。用户说"/commit" 即激活。
|
||||
|
||||
## 参考
|
||||
|
||||
- devflow-claude: `plugins/req/commands/commit.md`
|
||||
- REQ-20260416-0017 P0-6
|
||||
Reference in New Issue
Block a user