zeaslity/ProjectAGiPrompt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

超大量更新

Browse Source
This commit is contained in:
zeaslity
2026-04-29 09:46:36 +08:00
parent ed945abdf1
commit e7c301023c
349 changed files with 83923 additions and 560 deletions
Download Patch File Download Diff File Expand all files Collapse all files

160
.agents/skills/dds-to-skill/SKILL.md
View File

@@ -1,11 +1,11 @@
---
name: dds-to-skill
description: >
将 DDS（详细设计说明书）/ PRD / 架构文档转换为一套可落地的 Claude Code Agent Skills（Converts DDS/PRD/Architecture docs into production-ready Agent Skills）。
包含系统级 Skill、模块级 Skills、横切 Skills 的完整生成流程，涵盖设计细节抽取、reference 分层、frontmatter 规范、质量自检。
触发场景 Trigger: 当用户需要将 DDS 文档转为 Skills / 需要从架构设计文档生成开发指导 Skill / 需要批量创建模块级 Skill 套件。
关键词 Keywords: DDS, PRD, 架构说明, 设计文档, skill 生成, skill 套件, agent skill, 模块拆分, reference 抽取, 契约, API, 状态机, 事件, Schema。
argument-hint: "<dds-file-path> [--output-dir <skills-output-dir>] [--project-name <name>]"
将单模块 DDS（详细设计说明书）/ PRD / 架构文档转换为一个 All-in-One 全栈开发指导 Skill（Converts a single-module DDS/PRD/Architecture doc into one All-in-One development guidebook Skill）。
输出唯一的 developing-<module-name> Skill，涵盖 API、数据库、状态机、事件、安全等全栈设计细节抽取与 reference 分层索引。
触发场景 Trigger: 当用户需要将单模块 DDS 文档转为可落地的开发指导 Skill / 需要从架构设计文档生成 All-in-One 开发向导。
关键词 Keywords: DDS, PRD, 架构说明, 设计文档, skill 生成, all-in-one, agent skill, reference 抽取, API, 状态机, 事件, Schema。
argument-hint: "<dds-file-path> [--output-dir <skills-output-dir>] [--module-name <name>]"
allowed-tools:
- Read
- Write
@@ -15,11 +15,16 @@ allowed-tools:
- Bash
---
# DDS-to-Skill：从设计文档生成 Agent Skills
# DDS-to-Skill：从设计文档生成 All-in-One 开发指导 Skill
本 Skill 指导你将一份 DDS（Detailed Design Specification）或 PRD / 架构说明文档，转换为一套**可落地、含设计细节**的 Claude Code Agent Skills 套件。
本 Skill 指导你将一份单模块 DDS（Detailed Design Specification）或 PRD / 架构说明文档，转换为**唯一一个**包含全栈开发细节的 `developing-<module-name>` Skill。
> **核心理念**：生成的不是"空洞的工作流提示词"，而是**绑定了 DDS 设计细节**、能指导真实开发/审查的 Skill 套件。
> **核心理念**：一个 DDS 输入 → 一个 Skill 输出。生成的不是"空洞的工作流提示词"，而是**绑定了 DDS 设计细节**、能指导真实全栈开发的 All-in-One 指导书。
> **⚠️ 强制约束**：
> - **禁止**生成系统级 Skill（`*-system`）
> - **禁止**生成横切/全局 Skill（`managing-*`、`designing-*`、`implementing-auth` 等）
> - 唯一合法输出为 **1 个** `developing-<module-name>` 目录
---
@@ -66,62 +71,73 @@ allowed-tools:
若无法读取文件，**必须停止**，输出"继续所需的最小信息清单"：
1. 系统模块列表（名称 + 职责 + 关键技术）
2. 每个模块的接口/API 列表
1. 模块名称、职责与关键技术栈
2. 接口/API 列表
3. 事件/Topic 定义
4. 数据库表结构
5. 状态机/流程定义
6. 授权模型
7. 模块间依赖关系
7. 外部依赖关系
**禁止在缺少源文档的情况下臆造设计细节。**
---
## Phase 1：分析与规划
## Phase 1：分析与规划（单模块全包容）
### 1.1 模块识别
### 1.1 模块识别与命名
从 DDS 中识别所有业务模块，生成模块清单表：
从 DDS 中识别目标模块，确定唯一 Skill 名称：
| 模块名 | 职责概述 | 关键技术 | Skill 类型 |
|--------|---------|---------|-----------|
| *从 DDS 抽取* | *从 DDS 抽取* | *从 DDS 抽取* | 系统级/模块级/横切 |
| 项目 | 内容 |
|------|------|
| 模块名 | *从 DDS 抽取* |
| 职责概述 | *从 DDS 抽取* |
| 关键技术栈 | *从 DDS 抽取* |
| **Skill 名称** | `developing-<module-name>` |
### 1.2 Skill 三层架构规划
> **命名规则**：
> - 动名词 `developing-` 前缀 + 模块名
> - 小写字母 + 数字 + 连字符
> - ≤ 64 字符
必须生成 3 类 Skills：
### 1.2 单模块 All-in-One 规划
**A) 系统级 Skill（1 个）**
- 跨模块一致性、依赖规则、全局变更流程
- 命名：`developing-<system-name>-system`
**唯一输出**为 `developing-<module-name>`，该 Skill 必须涵盖以下所有职责：
**B) 模块级 Skills（N 个，每模块 1 个）**
- 高频开发指导：实现步骤 + 依赖影响检查
- 命名：`developing-<module-name>`
- ✅ 模块架构总览与技术栈说明
- ✅ 数据库 Schema 与迁移指导
- ✅ API/接口实现指导
- ✅ 状态机/业务流程实现指导
- ✅ 事件/消息处理指导
- ✅ 安全/授权实现指导（如适用）
- ✅ 外部依赖与集成点说明
- ✅ 可观测性/监控/日志规范（如适用）
**C) 横切 Skills（≥ 3 个）**
- 基于 DDS 内容选择，常见横切关注点：
**⚠️ 以下生成物被严格禁止**：
| 横切主题 | 适用场景 | 参考命名 |
| 禁止类型 | 匹配模式 | 禁止原因 |
|---------|---------|---------|
| API/事件/Schema 契约 | 有跨模块接口定义 | `designing-contracts` |
| 数据库迁移 | 有 DB Schema 定义 | `managing-db-migrations` |
| 可观测性/审计 | 有日志/监控/审计需求 | `managing-observability` |
| 安全/认证 | 有 RBAC/JWT/授权体系 | `implementing-auth` |
| 前端开发规范 | 有前端架构设计 | `frontend-<framework>` |
| 后端编码规范 | 有后端技术栈规范 | `backend-<framework>` |
| 部署/运维 | 有 K8S/Docker/CI 设计 | `deploying-<target>` |
| 系统级 Skill | `*-system` | 单模块场景无需跨系统协调 |
| 横切/契约 Skill | `designing-*` | 所有契约信息收入唯一 Skill 的 reference/ |
| 横切/管理 Skill | `managing-*` | 所有运维/迁移/监控信息收入唯一 Skill |
| 横切/实现 Skill | `implementing-*` | 所有实现指导收入唯一 Skill 的 Execute 章节 |
> 实际横切 Skills 必须根据 DDS 内容动态决定，不可少于 3 个。
### 1.3 Reference 目录规划
### 1.3 Name 候选与确认
规划 `reference/` 的分层目录结构，将所有设计细节（API、DB、状态机、事件等）集中在唯一 Skill 下：
为每个 Skill 提供 2~3 个命名候选，从中选择 1 个并说明理由。命名规则：
- 动名词形式（如 `developing-*`、`managing-*`、`implementing-*`）
- 小写字母 + 数字 + 连字符
- ≤ 64 字符
- 包含模块名或领域名
```
developing-<module-name>/reference/
├── 01-<section-slug>/
│ ├── apis.md
│ ├── db-schema.md
│ └── events-topics.md
├── 02-<section-slug>/
│ └── state-machine.md
└── 03-<section-slug>/
└── security-model.md
```
---
@@ -133,34 +149,22 @@ allowed-tools:
从 DDS 章节标题构建 `reference/` 分层目录：
```
<skill-name>/reference/
├── 01-<section-slug>/
│ ├── apis.md
│ ├── db-schema.md
│ └── events-topics.md
├── 02-<section-slug>/
│ └── state-machine.md
└── 03-<section-slug>/
└── security-model.md
```
**目录命名规范**：
- 有序前缀 `01-`、`02-`... + slug
- slug：全小写，非字母数字字符替换为 `-`，连续 `-` 合并，≤ 48 字符
### 2.2 六类设计要素抽取（必须覆盖）
每个模块级 Skill 的 reference/ 必须覆盖**至少 3 类**：
唯一 Skill 的 reference/ 必须覆盖**至少 3 类**：
| 要素类型 | 抽取内容 | reference 文件名 |
|---------|---------|-----------------|
|---------|---------|-----------------|
| **API/接口** | 路径、方法、请求/响应字段、错误码 | `apis.md` |
| **事件/Topic** | 字段、版本、幂等键、重试语义 | `events-topics.md` |
| **DB Schema** | 字段、索引、约束、迁移策略 | `db-schema.md` |
| **状态机/流程** | 状态、转移、守卫条件、回调、补偿 | `state-machine.md` |
| **授权模型** | JWT claims、RBAC/DAC、权限层级 | `security-model.md` |
| **依赖关系** | 跨模块调用链路、协议、集成点 | `dependencies.md` |
| **依赖关系** | 外部调用链路、协议、集成点 | `dependencies.md` |
### 2.3 reference 条目格式（强制）
@@ -186,17 +190,17 @@ allowed-tools:
---
## Phase 3：逐个生成 SKILL.md
## Phase 3：生成 SKILL.md
### 3.1 SKILL.md 结构模板
> **详细模板见** `reference/skill-templates.md`
每个 SKILL.md 必须包含以下结构：
唯一的 SKILL.md 必须包含以下结构：
```markdown
---
name: <skill-name>
name: developing-<module>
description: <单行，< 1024 字符，中英文混合，第三人称，含功能+触发场景+关键词>
argument-hint: "<参数格式说明>"
allowed-tools:
@@ -208,9 +212,9 @@ allowed-tools:
- Bash # 按需
---
# <Skill 标题>
# Developing <Module>
<一段话概述本 Skill 的用途和适用范围>
<一段话描述模块职责、技术栈、适用范围>
## Quick Context
<动态注入命令，至少 2 处 !`command`>
@@ -220,13 +224,13 @@ allowed-tools:
### 决策点
## Verify
<按类别组织的 Checklist，可勾选>
<按类别组织的全栈 Checklist：数据库→API→状态机→事件→安全>
## Execute
<分步骤的可操作指令>
<分步骤的全栈开发指令：数据库→API→状态机→事件→安全>
## Pitfalls
<3~8 条与该模块/主题强相关的常见坑，至少 2 条引用 reference>
<3~8 条与该模块强相关的常见坑，至少 2 条引用 reference>
## Related References
<指向 reference/ 的链接列表，说明何时查阅>
@@ -249,6 +253,7 @@ allowed-tools:
3. **可执行动作**：禁止空话（如"检查 API 兼容"），必须写成具体审查动作
4. **设计细节绑定**：Pitfalls 和 Verify 中至少 2 处引用 `reference/` 的具体内容
5. **行数限制**：SKILL.md 主体 < 500 行
6. **全栈覆盖**：Verify 和 Execute 必须覆盖数据库、API、状态机、事件等全栈层面
**示例 — 空话 vs 可执行动作**：
@@ -269,10 +274,10 @@ allowed-tools:
### 4.1 目录结构
每个 Skill 遵循标准目录模板：
唯一 Skill 遵循标准目录模板：
```
<skill-name>/
developing-<module-name>/
├── SKILL.md # 主文件（< 500 行）
├── reference/ # 设计细节（按章节分层）
│ ├── 01-<section>/
@@ -289,7 +294,7 @@ allowed-tools:
### 4.2 verify.sh 编写要求
每个 Skill 必须至少包含 1 个 `verify.sh`：
唯一 Skill 必须包含 1 个 `verify.sh`：
```bash
#!/bin/bash
@@ -341,9 +346,9 @@ echo "=== 结果: $PASS PASS / $FAIL FAIL ==="
### 5.1 输出顺序（必须遵守）
1. **Skills 清单表**：系统级 / 模块级 / 横切，含最终 name 与理由
1. **Skill 信息表**：唯一 `developing-<module-name>` 的 name、职责概述、覆盖的设计要素类型
2. **总目录树**：Unix 路径风格
3. **每个 SKILL.md**：完整内容
3. **SKILL.md**：完整内容
4. **Supporting files**：按 `文件路径 → 文件内容` 逐个输出
5. **全局自检结果**：逐条 PASS/FAIL + 修复建议
@@ -351,11 +356,11 @@ echo "=== 结果: $PASS PASS / $FAIL FAIL ==="
按以下维度逐条检查：
**结构完整性**
- [ ] 系统级 Skill 存在（1 个）
- [ ] 模块级 Skills 数量 = 模块数
- [ ] 横切 Skills ≥ 3 个
- [ ] 每个 Skill 都有 SKILL.md + reference/ + scripts/verify.sh
**唯一收敛性（最高优先级）**
- [ ] 仅存在 1 个 `developing-<module-name>` 目录
- [ ] 不存在任何 `*-system` 系统级 Skill
- [ ] 不存在任何 `managing-*` / `designing-*` / `implementing-*` 横切 Skill
- [ ] 唯一 Skill 有 SKILL.md + reference/ + scripts/verify.sh
**Frontmatter 规范**
- [ ] description 为单行
@@ -370,9 +375,10 @@ echo "=== 结果: $PASS PASS / $FAIL FAIL ==="
- [ ] ≥ 2 处 `!command` 动态注入
- [ ] Pitfalls ≥ 2 条引用 reference
- [ ] 无空话（"检查 XX 一致性"这类无具体动作的描述）
- [ ] Verify 和 Execute 覆盖全栈层面（数据库→API→状态机→事件）
**Reference 质量**
- [ ] 每个模块 Skill 覆盖 ≥ 3 类设计要素
- [ ] 覆盖 ≥ 3 类设计要素
- [ ] reference 有章节分层目录（非扁平）
- [ ] 每条 reference 含 DDS-Section + DDS-Lines 溯源
- [ ] DDS 缺失内容标注 [TBD]
@@ -385,7 +391,7 @@ echo "=== 结果: $PASS PASS / $FAIL FAIL ==="
| 需要了解... | 查阅... |
|------------|--------|
| DDS 抽取的详细方法 | `reference/dds-extraction-guide.md` |
| SKILL.md 模板（系统/模块/横切） | `reference/skill-templates.md` |
| SKILL.md 模板（模块全栈开发指导书） | `reference/skill-templates.md` |
| Frontmatter 详细规范 | `reference/frontmatter-spec.md` |
| 质量自检的完整清单 | `reference/quality-checklist.md` |
| 成功案例的目录结构 | `examples/` |

81
.agents/skills/dds-to-skill/reference/quality-checklist.md
View File

@@ -8,13 +8,13 @@ DDS-to-Skill 转换完成后，必须按以下清单逐条检查。每条标记
| # | 检查项 | PASS 条件 |
|---|-------|----------|
| S1 | 系统级 Skill 存在 | 恰好 1 个 `developing-*-system` Skill |
| S2 | 模块级 Skills 数量 | = DDS 中识别的模块数 |
| S3 | 横切 Skills 数量 | ≥ 3 个 |
| S4 | 每个 Skill 有 SKILL.md | 所有 Skill 目录下存在 SKILL.md |
| S5 | 每个 Skill 有 reference/ | 所有 Skill 目录下存在 reference/ |
| S6 | 每个 Skill 有 verify.sh | 所有 Skill 的 scripts/ 下存在 verify.sh |
| S7 | 目录命名规范 | 全小写、连字符、动名词形式 |
| S1 | 唯一收敛 | 仅存在 1 个 `developing-<module-name>` 目录 |
| S2 | 无越界系统级 Skill | 不存在任何 `*-system` 目录 |
| S3 | 无越界横切 Skill | 不存在 `managing-*` / `designing-*` / `implementing-*` 等横切目录 |
| S4 | Skill 有 SKILL.md | `developing-<module-name>` 目录下存在 SKILL.md |
| S5 | Skill 有 reference/ | `developing-<module-name>` 目录下存在 reference/ |
| S6 | Skill 有 verify.sh | `developing-<module-name>` 的 scripts/ 下存在 verify.sh |
| S7 | 目录命名规范 | 全小写、连字符、`developing-` 前缀 |
---
@@ -27,9 +27,9 @@ DDS-to-Skill 转换完成后，必须按以下清单逐条检查。每条标记
| F3 | description 中英文 | 同时包含中文和英文描述 |
| F4 | description 含触发场景 | 包含 "触发场景" 或 "Trigger" 关键词 |
| F5 | description 含关键词 | 包含 "关键词" 或 "Keywords" |
| F6 | name 格式 | 小写字母 + 数字 + 连字符，动名词开头 |
| F6 | name 格式 | 小写字母 + 数字 + 连字符，`developing-` 开头 |
| F7 | argument-hint 存在 | frontmatter 中包含 argument-hint 字段 |
| F8 | allowed-tools 最小授权 | 只读 Skill 不包含 Write/Edit |
| F8 | allowed-tools 最小授权 | 工具列表按需最小化 |
---
@@ -45,8 +45,8 @@ DDS-to-Skill 转换完成后，必须按以下清单逐条检查。每条标记
| C6 | 动态注入 | ≥ 2 处 `!` + 反引号命令 |
| C7 | Pitfalls 引用 reference | ≥ 2 条 Pitfall 中出现 `reference/` 路径 |
| C8 | 无空话 | 不含"检查 XX 一致性"这类无具体动作的描述 |
| C9 | 无常识内容 | 不含 Claude 已知的通用知识（如 HTTP 状态码定义） |
| C10 | 术语一致 | 同一概念在所有 Skill 中使用相同术语 |
| C9 | 无常识内容 | 不含 AI 已知的通用知识（如 HTTP 状态码定义） |
| C10 | 全栈覆盖 | Verify 和 Execute 至少覆盖数据库、API 两个层面 |
---
@@ -54,7 +54,7 @@ DDS-to-Skill 转换完成后，必须按以下清单逐条检查。每条标记
| # | 检查项 | PASS 条件 |
|---|-------|----------|
| R1 | 设计要素覆盖率 | 每个模块 Skill 覆盖 ≥ 3 类（API/事件/DB/状态机/权限/依赖） |
| R1 | 设计要素覆盖率 | 覆盖 ≥ 3 类（API/事件/DB/状态机/权限/依赖） |
| R2 | 章节分层 | reference/ 下存在 `01-*` 等编号目录（或使用扁平+说明） |
| R3 | DDS 溯源 | 每条 reference 含 `DDS-Section:` 字段 |
| R4 | DDS 行号 | 每条 reference 含 `DDS-Lines:` 字段 |
@@ -64,51 +64,50 @@ DDS-to-Skill 转换完成后，必须按以下清单逐条检查。每条标记
---
## 5. 跨 Skill 一致性
| # | 检查项 | PASS 条件 |
|---|-------|----------|
| X1 | 模块名一致 | 所有 Skill 中模块名拼写相同 |
| X2 | 错误码不冲突 | 相同错误码在不同 Skill 中含义相同 |
| X3 | API 路径不冲突 | 不同模块的 API 路径无重叠 |
| X4 | 事件/Topic 定义一致 | 同一 Topic 在发布方和订阅方 Skill 中定义相同 |
| X5 | 授权模型一致 | JWT Claims、角色定义在所有 Skill 中一致 |
---
## 6. 自检输出格式
## 5. 自检输出格式
```markdown
# 全局自检结果
## 结构完整性
- ✅ S1 PASS: 系统级 Skill `developing-xxx-system` 存在
- ✅ S2 PASS: 模块级 Skills 数量 = 5（匹配 DDS 中的 5 个模块）
- ❌ S3 FAIL: 横切 Skills 仅 2 个，少于要求的 3 个
- **修复**: 从 DDS 中识别出缓存策略章节，建议增加 `managing-cache` Skill
- ✅ S4 PASS: 所有 Skill 目录下存在 SKILL.md
## 结构完整性（唯一收敛性）
- ✅ S1 PASS: 仅存在 1 个模块 Skill `developing-rmdc-feishu-operator`
- ✅ S2 PASS: 不存在任何 `*-system` 系统级 Skill
- ✅ S3 PASS: 不存在任何 `managing-*` / `designing-*` / `implementing-*` 横切 Skill
- ✅ S4 PASS: SKILL.md 存在
- ✅ S5 PASS: reference/ 目录存在
- ✅ S6 PASS: scripts/verify.sh 存在
- ✅ S7 PASS: 目录命名 `developing-rmdc-feishu-operator` 符合规范
## Frontmatter 规范
- ✅ F1 PASS: 所有 description 为单行
- ❌ F2 FAIL: `developing-core` 的 description 超过 1024 字符（1156 字符）
- **修复**: 精简触发场景描述，移除重复关键词
- ✅ F1 PASS: description 为单行
- ✅ F2 PASS: description 长度 = 856 字符 (< 1024)
- ✅ F3 PASS: description 同时包含中文和英文
- ✅ F4 PASS: description 包含触发场景
- ✅ F5 PASS: description 包含关键词
## 内容质量
- ✅ C1 PASS: 所有 SKILL.md < 500 行
- ❌ C8 FAIL: `developing-gateway` 中 Verify 包含"检查 API 一致性"
- **修复**: 改为"对照 reference/02-api-design/apis.md 中的接口清单，grep 仓库中的 handler 注册点，确认路径和方法一致"
- ✅ C1 PASS: SKILL.md = 380 行 (< 500)
- ✅ C10 PASS: Verify 覆盖数据库、API、状态机、事件 4 个层面；Execute 覆盖 6 个步骤
- ❌ C8 FAIL: Verify 中包含"检查通知一致性"
- **修复**: 改为"对照 reference/03-notification/card-templates.md 中的模板列表，grep 仓库中的 SendCard 调用点，确认 template_id 一致"
## 总计: XX PASS / YY FAIL
## Reference 质量
- ✅ R1 PASS: 覆盖 5 类设计要素（API、事件、DB、状态机、依赖）
- ✅ R3 PASS: 所有 reference 条目含 DDS-Section 溯源
## 总计: 14 PASS / 1 FAIL
```
---
## 7. 常见 FAIL 及修复方案
## 6. 常见 FAIL 及修复方案
| FAIL 类型 | 常见原因 | 修复方案 |
|----------|---------|---------|
|----------|---------|---------|
| 越界生成多个 Skill | 习惯性拆分横切关注点 | 将横切内容收入唯一 Skill 的 reference/ 和 Execute 步骤 |
| 生成了 *-system Skill | 沿用旧的三层架构模式 | 删除系统级 Skill，将跨模块依赖收入 Plan 决策点或 Pitfalls |
| description 多行 | 使用了 `\|` 语法 | 改用 `>` 或单行字符串 |
| reference 不足 | DDS 内容被遗漏 | 重新扫描 DDS，补充缺失要素 |
| 空话 | 直接复制 DDS 原文 | 转化为可执行的审查动作 |
| 脑补 | DDS 未提及的细节 | 标注 [TBD] 并列出补充清单 |
| 横切不足 | 未充分分析 DDS | 从 DDS 中识别更多跨模块关注点 |
| 全栈覆盖不足 | Verify/Execute 仅覆盖部分层面 | 根据 DDS 内容补充数据库/API/状态机/事件等层面 |

282
.agents/skills/dds-to-skill/reference/skill-templates.md
View File

@@ -1,107 +1,18 @@
# SKILL.md 模板库
本文档包含系统级 Skill、模块级 Skill、横切 Skill 的 SKILL.md 模板，供 DDS-to-Skill 转换时参照。
本文档包含单模块全栈开发指导书的 SKILL.md 模板，供 DDS-to-Skill 转换时参照。
> **注意**：本框架仅生成唯一的 `developing-<module-name>` Skill，不生成系统级或横切级 Skill。
---
## 1. 系统级 Skill 模板
```markdown
---
name: developing-<system>-system
description: >
指导 <系统名> 系统级开发决策与跨模块一致性（Guides system-level development for <system>）。
包含：架构总览、模块注册、依赖规则、全局变更流程、版本兼容策略、技术栈规范。
触发场景 Trigger: 新增模块 / 跨模块变更 / 全局架构决策 / 技术栈选型。
关键词 Keywords: <system>, system, architecture, 架构, 模块, 依赖, 兼容, cross-module。
argument-hint: "<module-name|change-type> - 指定涉及的模块名或变更类型"
allowed-tools:
- Read
- Glob
- Grep
- Bash
---
# Developing <System> System
<一段话描述系统整体架构、技术栈、模块组成>
## Quick Context
```bash
# 动态注入：查看系统模块结构
!`ls -la <project-root>/`
# 动态注入：搜索模块间依赖
!`grep -rnE "import|module|service" <project-root>/ | head -30`
```
## Architecture Overview
<ASCII 架构图或层次说明>
## Module Registry
| 模块 | 职责 | 技术 | Skill |
|------|------|------|-------|
| ... | ... | ... | `developing-<module>` |
## Plan
### 产物清单
- [ ] 确定变更涉及的模块列表
- [ ] 确认是否涉及跨模块通信
- [ ] 确认是否涉及契约变更
- [ ] 确认是否需要数据库迁移
### 决策点
1. 变更是否影响多个模块？
2. 是否需要版本兼容处理？
3. 是否需要全局配置变更？
## Verify
- [ ] 模块间依赖无循环
- [ ] 共享契约版本一致
- [ ] 全局配置项完整
- [ ] 技术栈版本对齐
## Execute
### 添加新模块
1. 在项目根目录创建模块目录...
2. 注册到路由/网关...
3. 更新模块依赖图...
### 跨模块变更
1. 列出所有受影响模块...
2. 按依赖顺序逐个修改...
3. 运行集成测试...
## Pitfalls
1. **循环依赖**: 模块间禁止直接 import，必须通过共享接口定义
2. **版本不一致**: 修改共享结构需同步更新所有消费方
3. ...
## Related References
- [模块依赖关系](reference/dependencies.md)
- [技术栈规范](reference/tech-stack.md)
```
---
## 2. 模块级 Skill 模板
## 1. 模块全栈开发指导书模板
```markdown
---
name: developing-<module>
description: >
指导 <module> 模块的开发（Guides development of <module> module）。
包含：<模块职责概述>、API 实现、数据库操作、状态管理、安全校验。
触发场景 Trigger: 开发/修改 <module> 相关功能 / <模块特定场景>。
关键词 Keywords: <module>, <技术关键词>, <业务关键词>。
<module> 系统全栈开发指导 Skill（Full-stack development guide for <module>）。涵盖 <技术栈概述>、<核心数据模型概述>、<核心业务流程概述>、<关键集成点概述>。触发场景 Trigger: 开发/修改/调试 <module> 任意模块时、审查代码变更时、排查问题时。关键词 Keywords: <模块名>, <技术关键词>, <业务关键词>。
argument-hint: "<action> <target> - e.g., 'create handler', 'add api', 'update schema'"
allowed-tools:
- Read
@@ -114,7 +25,7 @@ allowed-tools:
# Developing <Module>
<一段话描述模块职责、技术栈、在系统中的位置>
<一段话描述模块的整体职责、核心技术栈、适用范围。强调这是该模块的唯一全栈开发向导，涵盖数据库、API、状态流转、事件处理等所有开发层面。>
## Quick Context
@@ -124,132 +35,137 @@ allowed-tools:
# 动态注入：查看现有接口
!`grep -rn "func.*Handler\|func.*Service" ./<module>/ | head -20`
# 动态注入：查看数据库相关文件
!`find . -name "*.sql" -o -name "*migration*" -o -name "*model*" | head -20`
```
## Plan
### 产物清单
- [ ] <根据 DDS 列出具体产物>
- [ ] <根据 DDS 列出具体产物：数据库模型、API handler、状态机实现等>
- [ ] <每一项都应对应 reference/ 中的设计细节>
### 决策点
1. <从 DDS 抽取的关键决策>
1. <从 DDS 抽取的关键决策，如技术选型、架构权衡>
2. ...
## Verify
### <验证类别 1>
- [ ] <具体检查项，引用 reference>
> 全栈验证按以下顺序依次进行，确保底层就绪后再构建上层。
### <验证类别 2>
- [ ] <具体检查项>
### 数据层验证
- [ ] 数据库表结构与 `reference/<section>/db-schema.md` 一致
- [ ] 索引、约束、外键按设计实现
- [ ] 迁移脚本可回滚（包含 down 语句或回滚段落）
### API 层验证
- [ ] API 路径、方法与 `reference/<section>/apis.md` 定义一致
- [ ] 请求/响应字段与设计文档吻合
- [ ] 错误码覆盖文档中定义的所有异常场景
### 状态机/业务流程验证
- [ ] 状态枚举与 `reference/<section>/state-machine.md` 中的状态集一致
- [ ] 状态转移条件（守卫）按设计实现，无非法跳转
- [ ] 回调/补偿逻辑在异常路径上正确触发
### 事件/消息验证
- [ ] Topic 命名与 `reference/<section>/events-topics.md` 一致
- [ ] Payload 字段完整且版本正确
- [ ] 幂等键生成逻辑正确，消费端实现去重
### 安全/授权验证（如适用）
- [ ] 授权模型与 `reference/<section>/security-model.md` 一致
- [ ] 敏感操作有权限校验
## Execute
### 1. <步骤标题>
```bash
# 具体操作命令
> 全栈开发按以下顺序推进，先夯实基础再构建业务。
### Step 1：数据库 Schema 实现
1. 根据 `reference/<section>/db-schema.md` 创建数据库模型/实体
2. 编写迁移脚本（必须包含 up 和 down）
3. 创建索引和约束
```go
// 关键模型骨架（从 reference 中抽取）
```
### 2. <步骤标题>
### Step 2：核心 API / Handler 实现
1. 根据 `reference/<section>/apis.md` 注册路由
2. 实现请求校验与响应序列化
3. 实现错误码映射
```go
// 关键代码骨架
// 关键 handler 骨架
```
### Step 3：状态机 / 业务流程实现
1. 根据 `reference/<section>/state-machine.md` 定义状态枚举与转移表
2. 实现守卫条件与副作用
3. 实现异常路径的回调/补偿
```go
// 关键状态转移骨架
```
### Step 4：事件/消息处理实现
1. 根据 `reference/<section>/events-topics.md` 注册事件处理器
2. 实现发布端 payload 构建
3. 实现消费端幂等处理
```go
// 关键事件处理骨架
```
### Step 5：安全/授权实现（如适用）
1. 根据 `reference/<section>/security-model.md` 实现授权中间件
2. 配置权限检查
### Step 6：可观测性与监控（如适用）
1. 接入日志、指标、追踪
2. 配置关键业务指标告警
## Pitfalls
1. **<坑名>**: <描述>（参考 `reference/<file>.md`）
2. ...（至少 3 条，至少 2 条引用 reference）
2. **<坑名>**: <描述>（参考 `reference/<file>.md`）
3. ...（至少 3 条，至少 2 条引用 reference）
## Related References
- [API 定义](reference/01-<section>/apis.md)
- [数据库 Schema](reference/02-<section>/db-schema.md)
- [数据模型定义](reference/01-<section>/db-schema.md) — 修改表结构时查阅
- [API 接口定义](reference/01-<section>/apis.md) — 新增/修改接口时查阅
- [状态机定义](reference/02-<section>/state-machine.md) — 修改业务流程时查阅
- [事件/Topic 定义](reference/02-<section>/events-topics.md) — 修改事件处理时查阅
```
---
## 3. 横切 Skill 模板
## 2. 模板使用注意事项
```markdown
---
name: <crosscut-skill-name>
description: >
<横切关注点>的统一规范与实现指导（Guides <crosscut concern> across all modules）。
包含：<具体内容列表>。
触发场景 Trigger: <触发场景列表>。
关键词 Keywords: <关键词列表>。
argument-hint: "<module-name|file-path> - 指定要应用规范的模块或文件"
allowed-tools:
- Read
- Glob
- Grep
- Bash
---
# <横切 Skill 标题>
<描述这个横切关注点在系统中的重要性和适用范围>
## Quick Context
```bash
# 动态注入
!`<扫描所有模块中与该横切主题相关的文件>`
```
## Plan
### 产物清单
- [ ] <横切维度的产物>
### 决策点
1. <跨模块的统一决策>
2. ...
## Verify
- [ ] <跨模块一致性检查>
- [ ] <规范合规检查>
- [ ] ...
## Execute
### 全局规范
<适用于所有模块的规则>
### 模块适配
<各模块的特殊处理>
## Pitfalls
1. **<跨模块一致性问题>**: <描述>
2. ...
## Related References
- [全局规范定义](reference/<global-spec>.md)
```
---
## 4. 模板使用注意事项
### 4.1 必须自定义的部分
### 2.1 必须自定义的部分
- `<尖括号>` 中的所有占位符
- Plan 的产物清单和决策点必须来自 DDS
- Verify 的检查项必须与模块设计细节对应
- Pitfalls 必须与模块/主题强相关，不可用通用建议填充
- Execute 的步骤必须绑定 reference/ 中的具体设计文档
- Pitfalls 必须与模块强相关，不可用通用建议填充
### 4.2 禁止照搬模板
### 2.2 禁止照搬模板
模板是结构参考，不是内容来源。以下行为将导致自检 FAIL：
- 产物清单中出现模板占位符
- Pitfalls 与模块无关（如：在前端 Skill 中出现数据库 Pitfall）
- Verify 中没有引用任何 reference
- Pitfalls 与模块无关
- Verify/Execute 中没有引用任何 reference
- Execute 步骤缺失具体的代码骨架或命令
### 4.3 按 DDS 内容增减
### 2.3 按 DDS 内容增减
- 如果 DDS 中没有状态机，模块 Skill 可以不包含状态机相关 Verify
- 如果 DDS 中有额外的关注点（如性能优化、缓存策略），应增加对应章节
- 横切 Skill 的数量和主题必须由 DDS 内容决定
- 如果 DDS 中没有状态机，可以省略 Step 3 和状态机验证
- 如果 DDS 中没有事件系统，可以省略 Step 4 和事件验证
- 如果 DDS 中有额外的关注点（如缓存策略、性能优化），应在 Verify 和 Execute 中增加对应章节
- Verify 和 Execute 的分层顺序可根据 DDS 中的技术架构调整，但必须保持"先基础后上层"的原则
### 2.4 全栈覆盖要求
作为唯一的开发指导书，必须确保：
- 所有原本属于"横切 Skill"（如数据库迁移、安全认证、可观测性）的知识都内嵌到 Verify/Execute 的对应步骤中
- 原本属于"系统级 Skill"（如跨模块依赖、全局配置）的知识收入 Plan 的决策点或 Pitfalls 中
- 所有设计细节的完整数据存放在 `reference/` 下，SKILL.md 中仅以引用方式指向

102
.agents/skills/dds-to-skill/scripts/verify-skill-output.sh
View File

@@ -1,10 +1,14 @@
#!/bin/bash
# verify-skill-output.sh
# 验证 DDS-to-Skill 转换输出的完整性和质量
# 验证 DDS-to-Skill 转换输出的完整性和质量（单模块 All-in-One 模式）
#
# 用法：./verify-skill-output.sh <skills-output-dir>
# 示例：./verify-skill-output.sh /path/to/1-AgentSkills
#
# 校验规则：
# - 仅允许存在 1 个 developing-* 目录
# - 不允许存在 *-system、managing-*、designing-*、implementing-* 等越界 Skill
#
# 依赖：bash, grep, sed, find, wc
set -e
@@ -37,26 +41,56 @@ warn() {
}
echo "============================================"
echo " DDS-to-Skill 输出质量验证"
echo " DDS-to-Skill 输出质量验证（单模块模式）"
echo " 目标目录: $SKILLS_DIR"
echo "============================================"
echo ""
# ============================================
# 1. 结构完整性检查
# 1. 唯一收敛性检查（最高优先级）
# ============================================
echo "--- 1. 结构完整性 ---"
echo "--- 1. 唯一收敛性 ---"
# S1: 检查是否有系统级 Skill
SYSTEM_SKILLS=$(find "$SKILLS_DIR" -maxdepth 1 -type d -name "*-system*" 2>/dev/null | wc -l)
if [ "$SYSTEM_SKILLS" -ge 1 ]; then
pass "S1: 存在系统级 Skill ($SYSTEM_SKILLS 个)"
# S1: 确认 developing-* 目录数量恰好为 1
DEV_SKILLS=$(find "$SKILLS_DIR" -maxdepth 1 -type d -name "developing-*" 2>/dev/null | wc -l)
if [ "$DEV_SKILLS" -eq 1 ]; then
DEV_SKILL_NAME=$(find "$SKILLS_DIR" -maxdepth 1 -type d -name "developing-*" -exec basename {} \;)
pass "S1: 恰好存在 1 个模块 Skill: $DEV_SKILL_NAME"
elif [ "$DEV_SKILLS" -eq 0 ]; then
fail "S1: 未找到任何 developing-* 目录" "确认输出目录正确，并确保生成了 developing-<module-name> Skill"
else
warn "S1: 未找到系统级 Skill（名称包含 '-system'）"
fail "S1: 发现 $DEV_SKILLS 个 developing-* 目录（应为 1 个）" "合并或删除多余的 developing-* 目录，仅保留 1 个"
fi
# S4: 每个 Skill 都有 SKILL.md
SKILL_DIRS=$(find "$SKILLS_DIR" -maxdepth 1 -type d ! -name "$(basename "$SKILLS_DIR")" 2>/dev/null)
# S2: 反向校验 — 不允许存在系统级 Skill
SYSTEM_SKILLS=$(find "$SKILLS_DIR" -maxdepth 1 -type d -name "*-system*" 2>/dev/null | wc -l)
if [ "$SYSTEM_SKILLS" -eq 0 ]; then
pass "S2: 不存在越界的系统级 Skill (*-system)"
else
SYSTEM_NAMES=$(find "$SKILLS_DIR" -maxdepth 1 -type d -name "*-system*" -exec basename {} \; | tr '\n' ', ')
fail "S2: 发现 $SYSTEM_SKILLS 个越界的系统级 Skill: $SYSTEM_NAMES" "删除系统级 Skill，将跨模块内容收入唯一的 developing-* Skill"
fi
# S3: 反向校验 — 不允许存在横切 Skill (managing-*, designing-*, implementing-*)
CROSSCUT_SKILLS=$(find "$SKILLS_DIR" -maxdepth 1 -type d \( -name "managing-*" -o -name "designing-*" -o -name "implementing-*" \) 2>/dev/null | wc -l)
if [ "$CROSSCUT_SKILLS" -eq 0 ]; then
pass "S3: 不存在越界的横切 Skill (managing-*/designing-*/implementing-*)"
else
CROSSCUT_NAMES=$(find "$SKILLS_DIR" -maxdepth 1 -type d \( -name "managing-*" -o -name "designing-*" -o -name "implementing-*" \) -exec basename {} \; | tr '\n' ', ')
fail "S3: 发现 $CROSSCUT_SKILLS 个越界的横切 Skill: $CROSSCUT_NAMES" "删除横切 Skill，将其内容收入唯一的 developing-* Skill 的 reference/ 和 Execute 中"
fi
echo ""
# ============================================
# 2. 结构完整性检查
# ============================================
echo "--- 2. 结构完整性 ---"
# 获取唯一的 developing-* 目录
SKILL_DIRS=$(find "$SKILLS_DIR" -maxdepth 1 -type d -name "developing-*" 2>/dev/null)
# S4: Skill 有 SKILL.md
MISSING_SKILLMD=0
for dir in $SKILL_DIRS; do
if [ ! -f "$dir/SKILL.md" ]; then
@@ -64,28 +98,40 @@ for dir in $SKILL_DIRS; do
((MISSING_SKILLMD++))
fi
done
if [ "$MISSING_SKILLMD" -eq 0 ]; then
pass "S4: 所有 Skill 目录都有 SKILL.md"
if [ "$MISSING_SKILLMD" -eq 0 ] && [ -n "$SKILL_DIRS" ]; then
pass "S4: Skill 目录有 SKILL.md"
fi
# S5: 每个 Skill 都有 reference/
# S5: Skill 有 reference/
MISSING_REF=0
for dir in $SKILL_DIRS; do
if [ ! -d "$dir/reference" ]; then
warn "S5: $dir 缺少 reference/ 目录"
fail "S5: $dir 缺少 reference/ 目录" "创建 reference/ 并按 DDS 章节填充设计细节"
((MISSING_REF++))
fi
done
if [ "$MISSING_REF" -eq 0 ]; then
pass "S5: 所有 Skill 目录都有 reference/"
if [ "$MISSING_REF" -eq 0 ] && [ -n "$SKILL_DIRS" ]; then
pass "S5: Skill 目录有 reference/"
fi
# S6: Skill 有 scripts/verify.sh
MISSING_VERIFY=0
for dir in $SKILL_DIRS; do
if [ ! -f "$dir/scripts/verify.sh" ]; then
fail "S6: $dir 缺少 scripts/verify.sh" "创建 scripts/verify.sh 验证脚本"
((MISSING_VERIFY++))
fi
done
if [ "$MISSING_VERIFY" -eq 0 ] && [ -n "$SKILL_DIRS" ]; then
pass "S6: Skill 目录有 scripts/verify.sh"
fi
echo ""
# ============================================
# 2. Frontmatter 规范检查
# 3. Frontmatter 规范检查
# ============================================
echo "--- 2. Frontmatter 规范 ---"
echo "--- 3. Frontmatter 规范 ---"
for dir in $SKILL_DIRS; do
SKILL_FILE="$dir/SKILL.md"
@@ -106,6 +152,14 @@ for dir in $SKILL_DIRS; do
fail "F2 [$SKILL_NAME]: 缺少 description 字段" "在 frontmatter 中添加 description 字段"
fi
# F6: name 以 developing- 开头
SKILL_NAME_VALUE=$(head -20 "$SKILL_FILE" | grep '^name:' | sed 's/^name:[[:space:]]*//')
if echo "$SKILL_NAME_VALUE" | grep -q '^developing-'; then
pass "F6 [$SKILL_NAME]: name 以 developing- 开头"
else
fail "F6 [$SKILL_NAME]: name 不以 developing- 开头 (当前: $SKILL_NAME_VALUE)" "修改 name 为 developing-<module-name> 格式"
fi
# C1: 行数 < 500
LINE_COUNT=$(wc -l < "$SKILL_FILE")
if [ "$LINE_COUNT" -lt 500 ]; then
@@ -118,9 +172,9 @@ done
echo ""
# ============================================
# 3. 内容质量检查
# 4. 内容质量检查
# ============================================
echo "--- 3. 内容质量 ---"
echo "--- 4. 内容质量 ---"
for dir in $SKILL_DIRS; do
SKILL_FILE="$dir/SKILL.md"
@@ -156,9 +210,9 @@ done
echo ""
# ============================================
# 4. Reference 质量检查
# 5. Reference 质量检查
# ============================================
echo "--- 4. Reference 质量 ---"
echo "--- 5. Reference 质量 ---"
for dir in $SKILL_DIRS; do
[ ! -d "$dir/reference" ] && continue
@@ -201,7 +255,7 @@ echo ""
# 总结
# ============================================
echo "============================================"
echo " 验证完成"
echo " 验证完成（单模块 All-in-One 模式）"
echo " ✅ PASS: $PASS"
echo " ❌ FAIL: $FAIL"
echo " ⚠️ WARN: $WARN"