后端开发 (BackendDevSkill)

该技能根据用户指令或工作项描述，自动完成后端代码开发的完整流程。

参数

所有参数均可选，技能会智能从用户自然语言描述中解析所需信息：

user_input: 用户指令 - 自然语言描述开发需求，如"帮我实现登录接口"、"完成用户管理模块"
workitem_id: 工作项 ID（可选）- 提供后获取工作项详情
demand_content: 需求内容文本（可选）- 直接提供需求描述
repo_url: 代码仓库地址（可选）- 提供后用于初始化或克隆代码库
target_branch: 目标分支（可选）- 默认使用主分支
language: 目标编程语言（可选）- 支持 Java/Python/Go/Node.js/C#
- 未指定时，技能会：
  1. 从工作项描述或代码仓库智能识别技术栈
  2. 识别失败时使用默认技术栈（Java/Spring Boot）
  3. 在架构设计确认环节提示用户，支持修改

入门方式：用户只需用自然语言描述"要做什么"，如"帮我实现用户登录功能"，无需了解任何参数含义。

输出格式

输出必须包含以下部分：

需求分析结果：功能点列表（Markdown 表格）
技术文档集：架构设计文档、API 文档、数据库设计文档等
代码文件列表：生成的代码文件路径及简要说明
单元测试报告：生成的测试文件及覆盖率说明
代码审查报告：发现的问题及修复建议（Markdown 表格）
Git 提交信息：提交信息及待提交文件列表

功能点列表格式

| 编号 | 功能名称 | 功能描述 | 输入 | 输出 | |:----:|:--------:|:--------:|:----:|:----:| | 1 | 用户登录 | 支持账号密码登录，返回 JWT 令牌 | 账号、密码 | JWT 令牌、用户信息 | | 2 | 密码加密 | 使用 BCrypt 加密存储密码 | 明文密码 | 加密后密码 |

技术文档集

技能将生成以下技术文档（均为 Markdown 格式）：

| 文档名称 | 文件路径 | 内容说明 | |---------|---------|---------| | 架构设计文档 | docs/design.md | 模块划分、技术选型、核心流程 | | API 接口文档 | docs/api.md | OpenAPI 3.0 格式的接口定义 | | 数据库设计文档 | docs/database.md | ER 图、表结构、SQL 脚本 | | 部署文档 | docs/deploy.md | 环境配置、部署步骤、依赖说明 | | 使用说明 | docs/README.md | 快速开始、配置说明、示例 |

代码审查报告格式

| 序号 | 文件路径 | 行号 | 严重程度 | 问题描述 | 修复建议 | |:----:|:--------:|:----:|:--------:|:--------:|:--------:| | 1 | AuthController.java | 25 | 高危 | JWT 密钥硬编码 | 从配置文件读取密钥 |

开发流程

生成后端代码时，必须按以下流程执行：

1. 需求接收

检测输入是否包含工作项 ID。
若包含，获取工作项详情。
若不包含，解析用户输入的自然语言，提取需求核心内容。

2. 需求分析

调用 LLM 分析需求，提取功能点。
生成 JSON 格式的功能点列表。
输出功能点列表供用户预览。

3. 架构设计

技术栈识别：
- 从工作项描述、代码仓库配置文件（pom.xml/package.json 等）智能识别技术栈
- 若未指定或无法识别，使用默认技术栈（Java/Spring Boot）
- 在架构设计文档中明确标注所选技术栈
调用 LLM 生成技术设计文档，包含：
- 模块划分
- 数据库 ER 图描述及 SQL
- API 接口定义 (OpenAPI 格式)
- 核心类图描述
- 技术栈说明（如：Java 17 + Spring Boot 3.x + MySQL 8.0）
将设计文档保存为 docs/design.md。
【人工确认点】：输出设计文档摘要（含技术栈选择），等待用户确认或修改。
- 提示格式示例：技术栈：Java (Spring Boot) [默认] | 如需更换，请在此阶段告知（支持：Python/Go/Node.js/C#）

4. 技术文档生成

生成完整的 API 接口文档（docs/api.md）：
- 使用 OpenAPI 3.0 规范
- 包含所有接口的路径、方法、参数、返回值
- 提供请求/响应示例
生成数据库设计文档（docs/database.md）：
- 实体关系图（ER 图）描述
- 表结构定义（字段、类型、约束）
- 初始化 SQL 脚本
生成部署文档（docs/deploy.md）：
- 环境要求（JDK/Python/Node 版本等）
- 依赖安装步骤
- 配置文件说明
- 启动命令
生成使用说明文档（docs/README.md）：
- 项目简介
- 快速开始指南
- 配置说明
- 使用示例
【人工确认点】：输出文档列表和摘要，等待用户确认。

5. 代码生成

根据设计文档，调用 LLM 生成代码文件：
- Controller 层
- Service 层
- DAO/Repository 层
- Entity/DTO 层
- 配置文件 (application.yml 或对应语言配置)
将生成的代码文件写入本地代码库对应目录。

6. 单测生成

调用 LLM 为 Service 和 Controller 生成单元测试。
覆盖正常流程、边界条件、异常处理。
使用对应语言的测试框架（如 Java 的 JUnit 5 + Mockito，Python 的 pytest，Go 的 testing 等）。
将单测文件写入测试目录（如 src/test/java 或对应语言测试目录）。

7. 代码审查

调用 LLM 或静态分析工具进行审查。
检查维度：规范、Bug、安全、性能、测试覆盖。
生成审查报告，列出问题及建议。
【人工确认点】：输出审查报告摘要，等待用户确认自动修复或人工处理。

8. 代码修复

遍历审查报告中的问题。
调用 LLM 根据建议自动修改代码。
对修复后的代码进行快速二次审查（可选）。
更新本地代码文件。

9. Git 仓库初始化

检查当前工作目录是否已存在 Git 仓库。
若不存在 Git 仓库：
- 使用 git init 初始化本地 Git 仓库。
若已存在 Git 仓库：
- 检查当前分支状态。
配置 Git 用户信息（按以下优先级顺序）：
1. 检查全局配置：执行 git config --global user.name 和 git config --global user.email
  - 如果全局配置存在，直接使用全局的账号和邮箱
2. 检查局部配置：如果全局未配置，执行 git config user.name 和 git config user.email
  - 如果当前仓库配置存在，使用局部配置的账号和邮箱
3. 用户输入：如果全局和局部均未配置，提示用户填写 Git 账号和邮箱
  - 使用用户提供的账号和邮箱执行 git config user.name "<账号>" 和 git config user.email "<邮箱>"
创建并切换到新分支（如 feature/<工作项 ID>-<功能简述>）。
【人工确认点】：输出 Git 初始化结果（仓库路径、分支名称、Git 用户配置），等待用户确认。

10. Git 提交准备

生成 Git 提交信息：feat: <工作项 ID> <标题>。
计算文件变更列表 (Diff)。
【人工确认点】：输出待提交文件列表和 Commit Message，等待用户确认。

11. 执行 Git 提交

使用 git 命令或端侧提供的 Git 工具执行 git add 和 git commit。
记录 Commit Hash。
输出成功消息。

信息优先级规则

优先级顺序

工作项详情 > 用户指令（含上下文）

优先级执行规则

当不同来源的信息发生冲突时，以优先级高的信息为准。
如果工作项明确定义了功能范围，即使与用户指令冲突，也以工作项为准。
用户指令可以作为补充和细化，但不能推翻已明确的功能范围。

严禁行为

严禁跳过人工确认点直接继续执行。
严禁在未确认代码库存在的情况下直接写入文件。
严禁在代码中硬编码敏感信息（密码、密钥等）。
严禁生成不符合代码规范的代码。
严禁在未进行代码审查的情况下直接提交。
严禁在用户未确认的情况下执行 Git 提交。
严禁在输出中包含未经验证的假设性内容。

实现说明

使用 MCP 收集参数（可留空让用户自行填写）。
严格遵循优先级顺序：工作项详情 > 用户指令。
在架构设计、技术文档生成、Git 初始化、代码审查、Git 提交五个节点必须等待用户确认。
确保单元测试覆盖核心逻辑。
当可选参数未提供时，基于已有信息智能生成。
代码文件路径必须使用相对路径，严禁包含绝对路径或敏感信息。
技术文档必须使用 Markdown 格式，代码示例需包含语言标识。
Git 初始化在代码修复之后执行，确保所有生成的文件和修复后的代码都能被一次性版本管理。

异常处理规则

工具调用失败：立即停止当前步骤，向用户报告失败原因，提供重试或人工介入选项。
用户取消操作：清理未确认的临时产物，保留已确认的产物，输出当前进度摘要。
代码生成质量不达标：主动告知用户，提供重新生成或人工修改选项。
网络或环境异常：暂停执行，保存当前状态，待环境恢复后提示用户继续。
文档生成失败：保留已生成的文档，报告失败部分，提供重新生成选项。
Git 初始化失败：报告失败原因，提供手动初始化选项或取消操作。

MCP 交互闸门（必须严格执行）

当 Skill 执行过程中需要通过 MCP 补充信息时，所有"列举候选项 -> 用户选择 -> 继续调用下一步工具"的链路都必须经过显式确认闸门。

在获取工作项详情后：
- 向用户展示工作项关键信息（标题、描述、验收标准）。
- 请求用户确认是否基于此需求继续。
在生成架构设计文档后：
- 向用户展示设计文档摘要。
- 请求用户明确确认"确认继续"或"提出修改意见"。
在生成技术文档集后：
- 向用户展示文档列表和摘要。
- 请求用户明确确认"确认继续"或"提出修改意见"。
在 Git 初始化完成后：
- 向用户展示 Git 仓库信息（路径、分支名称、初始状态）。
- 请求用户明确确认"确认继续"或"提出修改意见"。
在生成代码审查报告后：
- 向用户展示审查报告摘要（问题数量、严重程度分布）。
- 请求用户明确确认"自动修复"或"人工处理"。
在执行 Git 提交前：
- 向用户展示待提交文件列表和 Commit Message。
- 请求用户明确确认"提交"或"取消/修改"。

严禁在用户没有明确确认前执行以下动作：

跳过确认直接继续下一步。
根据猜测替用户做决定。
将未回复视为"同意继续"。

执行状态机（必须遵守）

当涉及人工确认时，按以下状态执行：

requirement_received
- 输出需求摘要并等待用户确认。
- 结束当前轮，不进入 analysis。
requirement_confirmed
- 用户明确确认需求后，才允许进入 analysis。
analysis_completed
- 输出功能点列表并等待用户确认。
- 结束当前轮，不进入 design。
design_confirmed
- 用户明确确认设计后，才允许进入 doc_generation。
doc_generation_completed
- 输出技术文档列表并等待用户确认。
- 结束当前轮，不进入 code_generation。
doc_confirmed
- 用户明确确认文档后，才允许进入 code_generation。
code_generation_completed
- 代码生成完成，进入 test_generation。
test_generation_completed
- 单测生成完成，进入 code_review。
code_review_completed
- 输出审查报告并等待用户确认。
- 结束当前轮，不进入 fix。
review_confirmed
- 用户明确确认修复后，才允许进入 fix。
fix_completed
- 代码修复完成，进入 git_init。
git_init_completed
- Git 初始化完成，输出仓库信息并等待用户确认。
- 结束当前轮，不进入 git_commit_prep。
git_init_confirmed
- 用户明确确认 Git 初始化后，才允许进入 git_commit_prep。
git_commit_ready
- 输出提交信息并等待用户确认。
- 结束当前轮，不进入 git_commit。
commit_confirmed
- 用户明确确认提交后，才允许执行 git commit。

任何时候都不允许跨状态自动推进；每个需要用户确认的状态都必须等待用户显式确认后再继续。

用例级别定义

| 级别 | 定义 | 覆盖原则 | |------|------|---------| | P1 | 核心功能、主流程 | 必须覆盖，阻塞发布 | | P2 | 高频功能、重要边界、异常处理 | 应当覆盖，影响核心体验 | | P3 | 次要功能、一般边界、低频场景 | 尽量覆盖，不阻塞发布 | | P4 | 辅助功能、极端边界、兼容性 | 按需覆盖，仅在要求时生成 |

分批生成规则（强制交互闸门）

当用户要求生成大量代码或复杂功能时，必须执行以下交互流程：

1. 风险提示

当检测到功能复杂或代码量较大时，主动提示用户：

⚠️ 风险提示：当前需求较为复杂，可能影响生成质量和一致性。
- 建议分模块生成以确保质量
- 是否确认一次性生成？或选择分模块生成？

2. 等待用户回复

必须停止并等待用户明确回复，禁止自动继续。可选回复：

确认继续 → 按规则一次性生成
分模块 → 按模块分批生成
取消 → 停止执行

3. 分批执行规则

确认后，按以下规则分批生成：

| 批次 | 内容 | 输出后 | |------|------|--------| | 第一批（核心集） | 核心模块代码 + 单测 + 核心文档 | 询问用户是否需要扩展 | | 第二批（扩展集） | 辅助模块代码 + 单测 + 补充文档 | 完成 |

4. 质量临界点判断

在生成过程中，发现以下情况时应主动停下并告知用户：

触发条件（满足任一即可）：

核心功能已覆盖完全，且质量已充分。
继续生成会明显导致代码重复、逻辑混乱。
已生成代码的独立验证价值明显下降。

停下时告知用户：

✅ 已生成核心模块代码，覆盖充分。
当前覆盖范围的质量已达最佳状态，继续生成会引入重复或低质量代码。
如需补充特定模块，请明确告知，否则当前代码已足够。

字符安全和格式规则

文件路径净化：代码文件路径必须是相对路径，严禁包含绝对路径或敏感信息。
代码格式：确保生成的代码是合法的，正确处理特殊字符（如注释、字符串转义）。
提交信息格式：
- 格式：<type>: <工作项 ID> <描述>
- 示例：feat: REQ-123 实现用户登录功能
- 严禁包含特殊字符或换行符。
文档格式：
- 所有文档使用 Markdown 格式
- 代码块需包含语言标识（如 java, python）
- 表格需使用标准 Markdown 表格语法
- 链接需使用相对路径

多语言支持

本技能支持以下后端语言，根据项目配置或用户指令自动识别：

Java: Spring Boot + JUnit 5 + Mockito
Python: Flask/Django + pytest
Go: Gin + testing 标准库
Node.js: Express + Jest
C#: ASP.NET Core + xUnit

代码规范、测试框架和配置文件根据识别的语言自动适配。

技术文档规范

架构设计文档 (design.md)

必须包含以下章节：

项目概述：功能简介、技术选型
系统架构：分层架构说明、模块划分
核心流程：关键业务流程时序图描述
数据库设计：ER 图、表结构
接口设计：API 概览
部署架构：环境要求、部署拓扑

API 接口文档 (api.md)

必须使用 OpenAPI 3.0 格式，包含：

接口列表：所有接口的路径、方法、描述
请求参数：参数名、类型、必填、描述
响应结构：状态码、响应体结构
示例：请求示例、响应示例
错误码：错误码定义及说明

数据库设计文档 (database.md)

必须包含：

ER 图：实体关系描述
表结构：表名、字段、类型、约束、说明
索引设计：索引名、字段、类型
SQL 脚本：建表语句、初始化数据

部署文档 (deploy.md)

必须包含：

环境要求：运行时版本、依赖服务
依赖安装：包管理命令、依赖列表
配置说明：配置文件路径、关键配置项
启动步骤：启动命令、验证方法
常见问题：FAQ 及解决方案

Git 分支命名规范

新分支命名格式：feature/<工作项 ID>-<功能简述>
示例：feature/REQ-123-user-login
功能简述应使用小写字母，单词间用连字符分隔

使用示例

场景：实现用户登录功能

用户输入:

"帮我实现这个需求：实现用户登录功能，支持账号密码登录，返回 JWT 令牌，关联工作项：REQ-123"

智能体执行日志:

[需求接收]: 检测到工作项 ID REQ-123，获取详情。
- [STATE: requirement_received]
- 输出: "已获取工作项 REQ-123 详情：实现用户登录功能。是否确认基于此需求继续？"
- 用户操作: 点击 "确认继续"
[需求分析]: 分析需求，生成功能点列表：
- FP001: 用户登录接口
- FP002: 密码加密
- FP003: JWT 令牌生成
- [STATE: analysis_completed]
- 输出: "已生成功能点列表（共 3 个）。是否确认继续？"
- 用户操作: 点击 "确认继续"
[架构设计]: 生成 docs/design.md，包含数据库设计和 API 定义。
- [STATE: design_confirmed]
- 输出: "已生成架构设计文档，包含 user 表设计及 /api/auth/login 接口定义。是否确认继续？"
- 用户操作: 点击 "确认继续"
[技术文档生成]: 生成 API 文档、数据库设计文档、部署文档。
- [STATE: doc_generation_completed]
- 输出: "已生成技术文档集（4 份文档）。是否确认继续？"
- 用户操作: 点击 "确认继续"
[代码生成]: 生成 AuthController.java, AuthService.java 等文件。
[单测生成]: 生成 AuthServiceTest.java。
[代码审查]: 发现 JWT 密钥硬编码问题 (HIGH)。
- [STATE: code_review_completed]
- 输出: "代码审查发现 1 个高危问题：JWT 密钥硬编码。建议自动修复。是否确认？"
- 用户操作: 点击 "自动修复"
[代码修复]: 自动修改代码，将密钥改为从配置文件读取。
[Git 初始化]: 检查并初始化 Git 仓库，创建分支 feature/REQ-123-user-login。
- [STATE: git_init_completed]
- 输出: "已初始化 Git 仓库，创建分支 feature/REQ-123-user-login。是否确认继续？"
- 用户操作: 点击 "确认继续"
[Git 提交准备]: 生成提交信息 "feat: REQ-123 实现用户登录功能"。
- [STATE: git_commit_ready]
- 输出: "准备提交以下文件：AuthController.java, AuthService.java, docs/*... 提交信息：feat: REQ-123 实现用户登录功能。是否确认提交？"
- 用户操作: 点击 "确认"
[Git 提交]: 执行 git add 和 git commit。
- [STATE: commit_confirmed]
[完成]: 任务结束，输出 Commit Hash。

版本历史

v1.0.0 (2026-06-03): 初始版本，包含核心开发流程及人工确认机制。
- 实现需求分析、架构设计、代码生成、单测生成、代码审查、代码修复、Git 提交全流程。
- 在架构设计、代码审查、Git 提交三个节点引入人工确认机制。
- 集成工作项和代码仓库能力。
- 定义严格的 MCP 交互闸门和执行状态机。
- 补充异常处理规则和多语言支持说明。
- 修复严禁行为编号错误。
v1.1.0 (2026-06-04): 补充技术文档输出功能。
- 新增技术文档集生成（架构设计、API 文档、数据库设计、部署文档、使用说明）。
- 新增技术文档生成步骤和确认节点。
- 更新状态机，增加文档生成和确认状态。
- 补充技术文档规范章节，明确各文档的内容结构。
- 更新使用示例，展示完整的文档生成流程。
v1.2.0 (2026-06-04): 优化 Git 初始化流程。
- 新增 Git 仓库初始化步骤，置于技术文档生成之前。
- 新增 Git 初始化确认节点和对应状态。
- 更新严禁行为，禁止在未初始化 Git 仓库的情况下生成代码。
- 新增 Git 分支命名规范说明。
- 更新 MCP 交互闸门，增加 Git 初始化后的确认环节。
- 更新使用示例，展示完整的 Git 初始化流程。
v1.2.1 (2026-06-04): 优化描述信息。
- 更新技能描述，更清晰地表达技能的核心价值和功能特点。
- 强调"全栈开发"、"完整开发闭环"、"多语言自动适配"等关键特性。
v1.2.2 (2026-06-04): 调整 Git 初始化位置并修复流程编号。
- 将 Git 初始化步骤移至代码修复之后（步骤 9），允许先生成文档和代码。
- 修正开发流程步骤编号，确保顺序连续（1-11）。
- 更新状态机以匹配新的流程顺序。
- 修复步骤 4 中的文字乱码问题。
- 更新严禁行为，移除"严禁在未初始化 Git 仓库的情况下生成代码文件"。
- 更新使用示例，展示新的执行顺序。