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-03-18 16:16:47 +08:00
parent 8efefcc230
commit ed945abdf1
136 changed files with 28252 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

391
.agents/skills/dds-to-skill/SKILL.md Normal file
View File

@@ -0,0 +1,391 @@
---
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>]"
allowed-tools:
- Read
- Write
- Edit
- Glob
- Grep
- Bash
---
# DDS-to-Skill：从设计文档生成 Agent Skills
本 Skill 指导你将一份 DDS（Detailed Design Specification）或 PRD / 架构说明文档，转换为一套**可落地、含设计细节**的 Claude Code Agent Skills 套件。
> **核心理念**：生成的不是"空洞的工作流提示词"，而是**绑定了 DDS 设计细节**、能指导真实开发/审查的 Skill 套件。
---
## Phase 0：读取与理解 DDS
### 0.1 动态注入读取（必须执行）
```bash
# 动态注入：查看源文档目录上下文
!`ls -la $(dirname "$ARGUMENTS")`
# 动态注入：读取 DDS 正文（至少 3 段，覆盖全文）
!`sed -n '1,150p' "$ARGUMENTS"`
!`sed -n '150,300p' "$ARGUMENTS"`
!`sed -n '300,500p' "$ARGUMENTS"`
# 动态注入：抽取章节标题（构建 TOC）
!`grep -nE '^(#{1,6}\s+|[0-9]+(\.[0-9]+){0,3}\s+|第[一二三四五六七八九十]+章|第[0-9]+章)' "$ARGUMENTS" | head -n 80`
```
### 0.2 设计要素定向扫描（至少执行 3 项）
```bash
# API/接口
!`grep -nE "API|接口|路径|路由|request|response|错误码|error|handler" "$ARGUMENTS" | head -n 60`
# 事件/消息/Topic
!`grep -nE "事件|event|MQTT|topic|outbox|消息|payload|幂等|retry|publish|subscribe" "$ARGUMENTS" | head -n 60`
# 数据库/Schema
!`grep -nE "表|schema|字段|索引|unique|constraint|migration|DDL|PostgreSQL|MySQL|GORM" "$ARGUMENTS" | head -n 60`
# 状态机/流程
!`grep -nE "状态机|state|transition|流转|工单|workflow|回调|补偿|lifecycle" "$ARGUMENTS" | head -n 60`
# 安全/授权
!`grep -nE "RBAC|DAC|鉴权|JWT|claim|授权|TOTP|权限|auth|token|session" "$ARGUMENTS" | head -n 60`
# 模块/服务/依赖
!`grep -nE "模块|module|service|微服务|依赖|dependency|import|gateway" "$ARGUMENTS" | head -n 60`
```
### 0.3 无法读取时的降级
若无法读取文件，**必须停止**，输出"继续所需的最小信息清单"：
1. 系统模块列表（名称 + 职责 + 关键技术）
2. 每个模块的接口/API 列表
3. 事件/Topic 定义
4. 数据库表结构
5. 状态机/流程定义
6. 授权模型
7. 模块间依赖关系
**禁止在缺少源文档的情况下臆造设计细节。**
---
## Phase 1：分析与规划
### 1.1 模块识别
从 DDS 中识别所有业务模块，生成模块清单表：
| 模块名 | 职责概述 | 关键技术 | Skill 类型 |
|--------|---------|---------|-----------|
| *从 DDS 抽取* | *从 DDS 抽取* | *从 DDS 抽取* | 系统级/模块级/横切 |
### 1.2 Skill 三层架构规划
必须生成 3 类 Skills：
**A) 系统级 Skill（1 个）**
- 跨模块一致性、依赖规则、全局变更流程
- 命名：`developing-<system-name>-system`
**B) 模块级 Skills（N 个，每模块 1 个）**
- 高频开发指导：实现步骤 + 依赖影响检查
- 命名：`developing-<module-name>`
**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>` |
> 实际横切 Skills 必须根据 DDS 内容动态决定，不可少于 3 个。
### 1.3 Name 候选与确认
为每个 Skill 提供 2~3 个命名候选，从中选择 1 个并说明理由。命名规则：
- 动名词形式（如 `developing-*`、`managing-*`、`implementing-*`）
- 小写字母 + 数字 + 连字符
- ≤ 64 字符
- 包含模块名或领域名
---
## Phase 2：DDS 设计细节抽取
### 2.1 章节提取与 reference 目录构建
> **详细规则见** `reference/dds-extraction-guide.md`
从 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 类**：
| 要素类型 | 抽取内容 | 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` |
### 2.3 reference 条目格式（强制）
每条 reference 必须包含溯源信息：
```markdown
## <设计要素名称>
- **DDS-Section**: <章节标题原文>
- **DDS-Lines**: L120-L168（或近似行号）
### Extract
<结构化内容：表格/列表/代码块>
```
### 2.4 TBD 标注
如果 DDS 中某个设计要素写得不清楚或缺失：
- **必须标注 `[TBD]`**
- 输出"最小补充信息清单"
- **禁止脑补细节**
---
## Phase 3：逐个生成 SKILL.md
### 3.1 SKILL.md 结构模板
> **详细模板见** `reference/skill-templates.md`
每个 SKILL.md 必须包含以下结构：
```markdown
---
name: <skill-name>
description: <单行，< 1024 字符，中英文混合，第三人称，含功能+触发场景+关键词>
argument-hint: "<参数格式说明>"
allowed-tools:
- Read
- Write # 按需
- Edit # 按需
- Glob
- Grep
- Bash # 按需
---
# <Skill 标题>
<一段话概述本 Skill 的用途和适用范围>
## Quick Context
<动态注入命令，至少 2 处 !`command`>
## Plan
### 产物清单
### 决策点
## Verify
<按类别组织的 Checklist，可勾选>
## Execute
<分步骤的可操作指令>
## Pitfalls
<3~8 条与该模块/主题强相关的常见坑，至少 2 条引用 reference>
## Related References
<指向 reference/ 的链接列表，说明何时查阅>
```
### 3.2 Frontmatter 编写规则
> **详细规范见** `reference/frontmatter-spec.md`
**关键要点**：
- `description` **必须单行**，否则 skill 触发会失败
- 必须中英文混合，确保中文和英文查询都能命中
- 必须包含：功能说明 + 触发场景 + 关键词（含模块名）
- `allowed-tools` 遵循最小授权原则
### 3.3 内容编写原则
1. **删除常识**：只保留 DDS 特有设计与可操作步骤
2. **解释 Why**：对重要约束解释原因，不要堆砌 MUST/ALWAYS
3. **可执行动作**：禁止空话（如"检查 API 兼容"），必须写成具体审查动作
4. **设计细节绑定**：Pitfalls 和 Verify 中至少 2 处引用 `reference/` 的具体内容
5. **行数限制**：SKILL.md 主体 < 500 行
**示例 — 空话 vs 可执行动作**：
```
❌ "检查事件一致性"
✅ "在 reference/events-topics.md 找到 topic 列表，对照仓库 grep 出 publish/subscribe 点"
❌ "验证 JWT 安全"
✅ "校验 JWT claims 是否包含 tenant_id/project_id/role（来自 reference/security-model.md）"
❌ "检查 migration 可回滚"
✅ "migration 必须包含 down SQL；verify.sh grep 检查 `-- +migrate Down` 或回滚段落存在"
```
---
## Phase 4：生成 Supporting Files
### 4.1 目录结构
每个 Skill 遵循标准目录模板：
```
<skill-name>/
├── SKILL.md # 主文件（< 500 行）
├── reference/ # 设计细节（按章节分层）
│ ├── 01-<section>/
│ │ ├── apis.md
│ │ ├── db-schema.md
│ │ └── ...
│ └── 02-<section>/
│ └── ...
├── examples/ # 骨架代码示例
│ └── ...
└── scripts/ # 验证脚本
└── verify.sh # 必须提供
```
### 4.2 verify.sh 编写要求
每个 Skill 必须至少包含 1 个 `verify.sh`：
```bash
#!/bin/bash
# verify.sh - <skill-name> Skill 结构与内容验证
set -e
PASS=0; FAIL=0
check() {
if eval "$2"; then
echo "✅ PASS: $1"; ((PASS++))
else
echo "❌ FAIL: $1"; ((FAIL++))
fi
}
SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
# 结构检查
check "SKILL.md 存在" "test -f '$SKILL_DIR/SKILL.md'"
check "reference/ 目录存在" "test -d '$SKILL_DIR/reference'"
check "SKILL.md < 500 行" "[ $(wc -l < '$SKILL_DIR/SKILL.md') -lt 500 ]"
# 内容检查
check "frontmatter 包含 name" "head -20 '$SKILL_DIR/SKILL.md' | grep -q '^name:'"
check "frontmatter 包含 description" "head -20 '$SKILL_DIR/SKILL.md' | grep -q '^description:'"
check "包含 Plan 章节" "grep -q '## Plan' '$SKILL_DIR/SKILL.md'"
check "包含 Verify 章节" "grep -q '## Verify' '$SKILL_DIR/SKILL.md'"
check "包含 Execute 章节" "grep -q '## Execute' '$SKILL_DIR/SKILL.md'"
check "包含 Pitfalls 章节" "grep -q '## Pitfalls' '$SKILL_DIR/SKILL.md'"
# reference 检查
check "reference 有章节子目录" "find '$SKILL_DIR/reference' -maxdepth 1 -type d -name '0*' | grep -q ."
check "reference 文件含 DDS-Section" "grep -rq 'DDS-Section:' '$SKILL_DIR/reference/' 2>/dev/null"
echo ""
echo "=== 结果: $PASS PASS / $FAIL FAIL ==="
[ $FAIL -eq 0 ] && exit 0 || exit 1
```
### 4.3 examples/ 编写要求
- 只放**骨架与关键接口签名**，不放完整实现
- 与模块职责强相关
- 注释说明关键设计决策
---
## Phase 5：全局自检
### 5.1 输出顺序（必须遵守）
1. **Skills 清单表**：系统级 / 模块级 / 横切，含最终 name 与理由
2. **总目录树**：Unix 路径风格
3. **每个 SKILL.md**：完整内容
4. **Supporting files**：按 `文件路径 → 文件内容` 逐个输出
5. **全局自检结果**：逐条 PASS/FAIL + 修复建议
### 5.2 自检 Checklist
按以下维度逐条检查：
**结构完整性**
- [ ] 系统级 Skill 存在（1 个）
- [ ] 模块级 Skills 数量 = 模块数
- [ ] 横切 Skills ≥ 3 个
- [ ] 每个 Skill 都有 SKILL.md + reference/ + scripts/verify.sh
**Frontmatter 规范**
- [ ] description 为单行
- [ ] description < 1024 字符
- [ ] 中英文混合
- [ ] 包含触发场景和关键词
- [ ] allowed-tools 最小授权
**内容质量**
- [ ] SKILL.md < 500 行
- [ ] 包含 Plan/Verify/Execute/Pitfalls 四个章节
- [ ] ≥ 2 处 `!command` 动态注入
- [ ] Pitfalls ≥ 2 条引用 reference
- [ ] 无空话（"检查 XX 一致性"这类无具体动作的描述）
**Reference 质量**
- [ ] 每个模块 Skill 覆盖 ≥ 3 类设计要素
- [ ] reference 有章节分层目录（非扁平）
- [ ] 每条 reference 含 DDS-Section + DDS-Lines 溯源
- [ ] DDS 缺失内容标注 [TBD]
- [ ] 无脑补设计细节
---
## Quick Reference
| 需要了解... | 查阅... |
|------------|--------|
| DDS 抽取的详细方法 | `reference/dds-extraction-guide.md` |
| SKILL.md 模板（系统/模块/横切） | `reference/skill-templates.md` |
| Frontmatter 详细规范 | `reference/frontmatter-spec.md` |
| 质量自检的完整清单 | `reference/quality-checklist.md` |
| 成功案例的目录结构 | `examples/` |

137
.agents/skills/dds-to-skill/examples/conversion-example-multi-module.md Normal file
View File

@@ -0,0 +1,137 @@
# DDS-to-Skill 转换实例：完整系统（多模块）
本文展示将一个包含多模块的 DDS 文档转换为完整 Skill 套件的过程。
---
## 1. 系统概述（模拟 DDS）
```
系统名称：ProjectMoneyX（个人财务管理系统）
技术栈：Go + Gin + GORM / Vue3 + TypeScript + Vuetify3
模块列表：
- 账单导入模块（bill-import）
- 多维分析模块（analysis）
- 预算管理模块（budget）
- 账户管理模块（account）
- 规则引擎模块（rules）
```
---
## 2. Skill 套件规划
### 2.1 Skills 清单
| 类型 | Skill Name | 职责 |
|------|-----------|------|
| 系统级 | `developing-moneyx-system` | 跨模块架构、技术栈规范、依赖管理 |
| 模块级 | `developing-bill-import` | 账单导入 ETL 流水线 |
| 模块级 | `developing-analysis` | 多维财务分析与图表 |
| 模块级 | `developing-budget` | 预算创建与跟踪 |
| 模块级 | `developing-account` | 账户 CRUD 与余额同步 |
| 模块级 | `developing-rules` | 分类规则引擎 |
| 横切 | `designing-contracts` | API/DTO 契约规范 |
| 横切 | `managing-db-migrations` | 数据库迁移策略 |
| 横切 | `managing-observability` | 日志、错误追踪 |
### 2.2 总目录树
```
1-AgentSkills/
├── developing-moneyx-system/
│ ├── SKILL.md
│ ├── reference/
│ │ ├── 01-architecture/
│ │ │ └── dependencies.md
│ │ └── 02-tech-stack/
│ │ └── conventions.md
│ └── scripts/
│ └── verify.sh
├── developing-bill-import/
│ ├── SKILL.md
│ ├── reference/
│ │ ├── 01-etl-pipeline/
│ │ │ └── pipeline-design.md
│ │ ├── 02-api-design/
│ │ │ └── apis.md
│ │ └── 03-data-model/
│ │ └── db-schema.md
│ ├── examples/
│ │ └── etl-processor.go
│ └── scripts/
│ └── verify.sh
├── developing-analysis/
│ ├── ...（同上结构）
├── developing-budget/
│ ├── ...
├── developing-account/
│ ├── ...
├── developing-rules/
│ ├── ...
├── designing-contracts/
│ ├── SKILL.md
│ ├── reference/
│ │ └── api-response-spec.md
│ └── scripts/
│ └── verify.sh
├── managing-db-migrations/
│ ├── SKILL.md
│ ├── reference/
│ │ └── migration-conventions.md
│ └── scripts/
│ └── verify.sh
└── managing-observability/
├── SKILL.md
├── reference/
│ └── logging-standards.md
└── scripts/
└── verify.sh
```
---
## 3. 关键转换决策
### 3.1 模块边界划分
> **决策依据**：DDS 中每个"章节"对应一个业务域，每个业务域生成一个模块级 Skill。
### 3.2 横切关注点识别
从 DDS 全文 grep 识别跨模块使用的技术点：
```bash
# 发现所有模块都用了统一响应格式 → designing-contracts
grep -c "ResponseError\|ResponseSuccess" *.go
# 发现多个模块有 migration 文件 → managing-db-migrations
find . -name "*migration*" -o -name "*migrate*"
# 发现多个模块有日志调用 → managing-observability
grep -rn "log\.\(Info\|Error\|Debug\)" --include="*.go" | wc -l
```
### 3.3 Reference 深度决策
| 要素 | 模块 | DDS 覆盖度 | reference 策略 |
|------|------|-----------|---------------|
| API | bill-import | 完整 | 全量抽取到 apis.md |
| DB Schema | budget | 部分 | 抽取已有 + [TBD] 标注缺失 |
| 事件 | analysis | 无 | 跳过，无需创建事件 reference |
| 状态机 | bill-import | 完整 | ETL 状态流转到 state-machine.md |
---
## 4. 输出示例：系统级 Skill
```yaml
---
name: developing-moneyx-system
description: >
指导 ProjectMoneyX 个人财务管理系统的全局架构决策与跨模块一致性（Guides system-level architecture for ProjectMoneyX personal finance system）。
包含：模块注册、技术栈规范、依赖管理、响应格式统一。
触发场景 Trigger: 新增模块 / 跨模块变更 / 架构决策 / 技术栈选型。
关键词 Keywords: moneyx, system, architecture, 架构, 财务, finance, 模块, cross-module。
---
```

95
.agents/skills/dds-to-skill/examples/conversion-example-workflow.md Normal file
View File

@@ -0,0 +1,95 @@
# DDS-to-Skill 转换实例：工单流程模块
本文展示了一个从 DDS 片段到完整 Skill 的转换过程。
---
## 1. DDS 原文片段（模拟）
```markdown
## 5. 工单管理模块（rmdc-work-procedure）
### 5.1 模块职责
负责工单生命周期管理，包括创建、审批、执行、完成等流转。
### 5.2 数据库设计
#### workflows 主表
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | BIGINT | PK, AUTO_INCREMENT | 工单ID |
| type | VARCHAR(50) | NOT NULL | 工单类型 |
| status | VARCHAR(30) | NOT NULL, DEFAULT 'pending' | 当前状态 |
| creator_id | BIGINT | NOT NULL, FK → users.id | 创建人 |
| assignee_id | BIGINT | FK → users.id | 处理人 |
| version | INT | NOT NULL, DEFAULT 1 | 乐观锁版本号 |
### 5.3 状态机
- pending → submitted → under_review → approved/rejected
- submitted → revoked（创建人可撤销）
- 终态：approved, rejected, revoked, closed
### 5.4 API 接口
- POST /api/workflow/create - 创建工单
- POST /api/workflow/transition - 状态转换
- POST /api/workflow/callback - 业务回调
- POST /api/workflow/list - 工单列表
```
---
## 2. 转换步骤演示
### 步骤 1：模块识别
| 模块 | 职责 | 技术 | Skill 类型 |
|------|------|------|-----------|
| rmdc-work-procedure | 工单生命周期管理 | Go + Gin + PostgreSQL | 模块级 |
### 步骤 2：设计要素抽取
从 DDS 中识别到 4 类要素：
- ✅ API/接口 → 4 个 API 端点
- ✅ DB Schema → workflows 主表
- ✅ 状态机 → 5 个状态 + 转换规则
- ❌ 事件/Topic → DDS 未提及 → 标注 [TBD]
- ❌ 授权模型 → DDS 未提及 → 标注 [TBD]
- ✅ 依赖关系 → 业务模块回调
### 步骤 3：reference 文件生成
```
reference/
├── 01-data-model/
│ └── db-schema.md # workflows 表结构
├── 02-api-design/
│ └── apis.md # 4 个 API 定义
├── 03-workflow-engine/
│ └── state-machine.md # 状态机定义
└── 04-integration/
└── dependencies.md # 回调接口
```
### 步骤 4：SKILL.md 关键段落
```markdown
## Pitfalls
1. **版本号遗漏**: 更新工单时忘记传递 `version` 字段，导致乐观锁失效
（参考 `reference/01-data-model/db-schema.md` 中 workflows.version 字段定义）
2. **终态误转换**: 对 approved/rejected/revoked/closed 状态尝试非法转换
（参考 `reference/03-workflow-engine/state-machine.md` 中的终态定义）
3. **事件推送遗漏**: 状态变更后忘记通知相关方 [TBD - DDS 未定义事件机制]
```
---
## 3. 自检结果
| # | 检查项 | 结果 | 说明 |
|---|-------|------|------|
| S4 | SKILL.md 存在 | ✅ PASS | |
| R1 | 设计要素 ≥ 3 类 | ✅ PASS | API + DB + 状态机 + 依赖 = 4 类 |
| R5 | TBD 标注 | ✅ PASS | 事件和授权标注了 [TBD] |
| C7 | Pitfalls 引用 reference | ✅ PASS | 2 条引用了 reference 路径 |
| R6 | 无脑补 | ✅ PASS | 缺失内容均标注 [TBD] |

260
.agents/skills/dds-to-skill/reference/dds-extraction-guide.md Normal file
View File

@@ -0,0 +1,260 @@
# DDS 设计细节抽取指南
本文档详细说明如何从 DDS（详细设计说明书）中抽取设计细节，并组织到 reference/ 目录中。
---
## 1. 章节标题提取
### 1.1 标题识别规则（按优先级）
| 优先级 | 格式 | 示例 |
|-------|------|------|
| 1 | Markdown 标题 | `# 系统架构`、`## 接口设计` |
| 2 | 编号标题 | `1 概述`、`2.3 数据库设计` |
| 3 | 中文章标题 | `第一章 总体设计`、`第3章` |
| 4 | 中文小节 | `一、系统概述`、`（二）接口规范` |
### 1.2 提取命令
```bash
# 综合提取（推荐首选）
grep -nE '^(#{1,6}\s+|[0-9]+(\.[0-9]+){0,3}\s+|第[一二三四五六七八九十]+章|第[0-9]+章|[一二三四五六七八九十]+、)' "$DDS_FILE" | head -n 120
# 如果上面匹配不足，尝试更宽松的模式
sed -n '1,200p' "$DDS_FILE" | nl -ba | sed -n '1,120p'
```
### 1.3 降级策略
当标题提取不足（少于 3 个）或 DDS 格式混乱时：
```
reference/00-unknown/
├── 01-apis/
├── 02-events/
├── 03-db/
├── 04-state-machine/
└── 05-security/
```
同时在自检中标记 FAIL：
- **原因**：DDS 标题结构不可识别
- **建议**：提供 Markdown 标题 / 章节目录 / md 格式导出版本
---
## 2. 六类设计要素抽取方法
### 2.1 API/接口
**扫描关键词**：
```bash
grep -nE "API|接口|路径|路由|request|response|错误码|error|handler|endpoint|method" "$DDS_FILE" | head -n 80
```
**抽取内容**：
| 字段 | 说明 |
|------|------|
| 路径 | `/api/v1/users/list` |
| 方法 | POST / GET 等 |
| 请求字段 | 字段名、类型、是否必须、校验规则 |
| 响应字段 | 字段名、类型、说明 |
| 错误码 | code + message + 触发场景 |
| 鉴权要求 | JWT / API Key / 公开 |
**输出格式**：
```markdown
## POST /api/v1/users/list
- **DDS-Section**: 3.2 用户管理接口
- **DDS-Lines**: L120-L168
### Request
| 字段 | 类型 | 必须 | 说明 |
|------|------|------|------|
| page | int | N | 页码，默认 1 |
| page_size | int | N | 每页数量，默认 20 |
### Response
| 字段 | 类型 | 说明 |
|------|------|------|
| list | []User | 用户列表 |
| total | int | 总数 |
### 错误码
| code | message | 触发场景 |
|------|---------|---------|
| 1001 | 参数校验失败 | 字段格式错误 |
```
### 2.2 事件/Topic/消息
**扫描关键词**：
```bash
grep -nE "事件|event|MQTT|topic|outbox|消息|payload|幂等|retry|publish|subscribe|Kafka|RabbitMQ" "$DDS_FILE" | head -n 80
```
**抽取内容**：
| 字段 | 说明 |
|------|------|
| Topic/Queue 名 | `cmii/rmdc/{project_id}/command` |
| 方向 | Publish / Subscribe |
| Payload 字段 | 字段名、类型、说明 |
| QoS / 可靠性 | At-least-once / Exactly-once |
| 幂等键 | 用于去重的唯一标识字段 |
| 重试策略 | 重试间隔、最大次数、死信队列 |
### 2.3 数据库/Schema
**扫描关键词**：
```bash
grep -nE "表|schema|字段|索引|unique|constraint|migration|DDL|PostgreSQL|MySQL|GORM|column|CREATE TABLE" "$DDS_FILE" | head -n 80
```
**抽取内容**：
| 字段 | 说明 |
|------|------|
| 表名 | `users`、`workflows` |
| 字段定义 | 名称、类型、约束、默认值 |
| 索引 | 类型（唯一/普通/组合）、字段 |
| 外键关系 | 引用表、级联策略 |
| 迁移策略 | 向前兼容 / 字段演进方案 |
### 2.4 状态机/流程
**扫描关键词**：
```bash
grep -nE "状态机|state|transition|流转|工单|workflow|回调|补偿|lifecycle|FSM|guard" "$DDS_FILE" | head -n 80
```
**抽取内容**：
| 字段 | 说明 |
|------|------|
| 状态枚举 | 名称、值、描述 |
| 转换规则 | from → to、触发动作、守卫条件 |
| 角色权限 | 谁可以触发哪些转换 |
| 回调/副作用 | 状态变更后执行的操作 |
| 补偿机制 | 转换失败时的回滚策略 |
### 2.5 授权模型
**扫描关键词**：
```bash
grep -nE "RBAC|DAC|鉴权|JWT|claim|授权|TOTP|权限|auth|token|session|role|permission" "$DDS_FILE" | head -n 80
```
**抽取内容**：
| 字段 | 说明 |
|------|------|
| 认证方式 | JWT / Session / OAuth |
| JWT Claims | 包含的字段（tenant_id, role 等） |
| 角色定义 | 角色名、权限描述 |
| 权限矩阵 | 角色 × 资源 × 操作 |
| 层级设计 | 一级授权 / 二级授权 |
### 2.6 依赖关系
**扫描关键词**：
```bash
grep -nE "模块|module|service|依赖|dependency|import|gateway|调用|集成|protocol" "$DDS_FILE" | head -n 80
```
**抽取内容**：
| 字段 | 说明 |
|------|------|
| 源模块 | 调用方 |
| 目标模块 | 被调用方 |
| 协议 | HTTP / gRPC / MQTT / 内部调用 |
| 关键接口 | 跨模块调用的接口清单 |
| 失败处理 | 超时、重试、熔断策略 |
---
## 3. reference 目录组织
### 3.1 命名规范
```
reference/
├── 01-architecture-overview/ # 章节序号 + slug
│ └── dependencies.md
├── 02-api-design/
│ ├── apis.md
│ └── error-codes.md
├── 03-data-model/
│ └── db-schema.md
├── 04-message-system/
│ └── events-topics.md
├── 05-workflow-engine/
│ └── state-machine.md
└── 06-security/
└── security-model.md
```
**Slug 生成规则**：
1. 全小写
2. 非字母数字字符替换为 `-`
3. 连续 `-` 合并为单个
4. 截断到 48 字符以内
5. 序号来自 DDS 中的章节顺序
### 3.2 SKILL.md 中的引用方式
```markdown
## Pitfalls
1. **MQTT Topic 命名冲突**：新增 topic 前必须检查
`reference/04-message-system/events-topics.md` 中的 topic 清单
## Related References
| 需要了解... | 查阅... |
|------------|--------|
| API 完整定义 | `reference/02-api-design/apis.md` |
| 数据库表结构 | `reference/03-data-model/db-schema.md` |
```
### 3.3 扁平化兼容
当 DDS 章节结构不明显时，也可以采用扁平 reference，但需在自检中说明：
```
reference/
├── apis.md
├── db-schema.md
├── events-topics.md
├── state-machine.md
├── security-model.md
└── dependencies.md
```
---
## 4. TBD 标注规范
当 DDS 中某个设计要素不完整或不清晰时：
```markdown
## 消息重试策略
- **DDS-Section**: 4.3 消息可靠性
- **DDS-Lines**: L245-L260
### Extract
| 配置项 | 值 |
|-------|---|
| 最大重试次数 | [TBD - DDS 未明确指定] |
| 重试间隔 | [TBD - DDS 未明确指定] |
| 死信队列 | [TBD - DDS 仅提及概念，未给出配置] |
### 最小补充信息清单
1. 重试次数上限（建议 3~5 次）
2. 重试间隔策略（固定 / 指数退避）
3. 死信队列名称与消费策略
```

162
.agents/skills/dds-to-skill/reference/frontmatter-spec.md Normal file
View File

@@ -0,0 +1,162 @@
# Frontmatter 编写规范
Frontmatter 是 Skill 的"身份证"，决定了 Skill 何时被触发、是否被正确识别。编写不当会导致 Skill 永远不会被使用。
---
## 1. 必须字段
### 1.1 name
**规则**：
- 小写字母 + 数字 + 连字符（`-`）
- 动名词形式开头（`developing-`、`managing-`、`implementing-`、`designing-`）
- ≤ 64 字符
- 包含模块名或领域名
**常用前缀**：
| 前缀 | 适用场景 |
|------|---------|
| `developing-` | 模块开发、功能实现 |
| `managing-` | 管理类操作（DB、配置、部署） |
| `implementing-` | 特定技术方案实现 |
| `designing-` | 设计阶段的规范和契约 |
| `writing-` | 编写文档、脚本、测试 |
**示例**：
```yaml
# ✅ 正确
name: developing-work-procedure
name: managing-db-migrations
name: implementing-totp-auth
# ❌ 错误
name: WorkProcedure # 不能大写
name: work_procedure # 不能用下划线
name: wp # 太短，无法触发
```
### 1.2 description
**这是最关键的字段** —— 决定 Skill 是否能被正确触发。
**硬性规则**：
1. **必须单行**（不换行） —— 换行会导致 YAML 解析出错，Skill 静默失败
2. **< 1024 字符**
3. **第三人称**描述
4. **中英文混合** —— 确保中文和英文查询都能命中
5. **包含触发场景**（Trigger）和**关键词**（Keywords）
**结构模板**：
```
<功能概述（中英文）>。包含：<具体能力列表>。触发场景 Trigger: <场景列表>。关键词 Keywords: <关键词列表>。
```
**示例**：
```yaml
# ✅ 正确（单行，中英文混合，包含触发场景和关键词）
description: 指导 rmdc-work-procedure 工单流程模块的开发（Guides development of rmdc-work-procedure workflow module）。包含：状态机实现、工单 CRUD、并发控制、WebSocket 事件。触发场景 Trigger: 修改工单表 / 添加工单类型 / 变更状态转换 / 实现工单 API。关键词 Keywords: workflow, work-procedure, state-machine, 工单, 状态机, 流转。
# ❌ 错误 - 多行（会静默失败！）
description: |
指导工单模块开发。
包含状态机实现。
# ❌ 错误 - 太短，无关键词
description: 工单模块开发指导
# ❌ 错误 - 纯英文，中文查询无法命中
description: Guides the development of workflow module with state machine
```
**推动触发的技巧**：
- Claude 有"不触发"的倾向，所以 description 应该稍微"激进"一些
- 多列出触发场景，覆盖用户可能的表述方式
- 包含同义词（如：工单/workflow/ticket）
### 1.3 argument-hint
**规则**：
- 说明 `$ARGUMENTS` 的期望格式
- 给出 2~3 个具体示例
**示例**：
```yaml
argument-hint: "<action> <target> - e.g., 'create handler user', 'add api /workflow/create', 'update schema workflows'"
```
---
## 2. 可选字段
### 2.1 allowed-tools
**原则**：最小授权 —— 只声明 Skill 真正需要的工具。
| 工具 | 适用场景 |
|------|---------|
| `Read` | 读取文件（几乎总是需要） |
| `Glob` | 搜索文件（几乎总是需要） |
| `Grep` | 搜索文件内容（几乎总是需要） |
| `Bash` | 执行 shell 命令（按需） |
| `Write` | 创建新文件（开发类 Skill 需要） |
| `Edit` | 编辑现有文件（开发类 Skill 需要） |
**示例**：
```yaml
# 只读 Skill（审查/分析类）
allowed-tools:
- Read
- Glob
- Grep
# 开发 Skill（需要写文件）
allowed-tools:
- Read
- Write
- Edit
- Glob
- Grep
- Bash
```
---
## 3. YAML 格式注意事项
### 3.1 多行 description 的安全写法
如果 description 确实很长，使用 `>` 折叠块语法（注意：这仍然会被解析为单行）：
```yaml
description: >
指导 rmdc-work-procedure 工单流程模块的开发。
包含状态机实现、工单 CRUD、并发控制。
触发场景 Trigger: 修改工单表、添加工单类型。
```
> ⚠️ 使用 `>` 时，YAML 会将换行替换为空格，最终合并为单行。这是安全的。
> ❌ 绝不要使用 `|`（保留换行块语法），那会导致多行 description。
### 3.2 特殊字符转义
```yaml
# 包含冒号时用引号包裹
argument-hint: "<action>: <target>"
# 包含 # 时用引号
description: "指导 C# 项目开发"
```
---
## 4. 自检清单
- [ ] `name` 为动名词形式、小写连字符、≤ 64 字符
- [ ] `description` 在最终 YAML 中为单行
- [ ] `description` < 1024 字符
- [ ] `description` 包含中文和英文
- [ ] `description` 包含触发场景（Trigger）
- [ ] `description` 包含关键词（Keywords）
- [ ] `argument-hint` 有具体示例
- [ ] `allowed-tools` 遵循最小授权

114
.agents/skills/dds-to-skill/reference/quality-checklist.md Normal file
View File

@@ -0,0 +1,114 @@
# 全局质量自检清单
DDS-to-Skill 转换完成后，必须按以下清单逐条检查。每条标记 PASS 或 FAIL，FAIL 必须附修复建议。
---
## 1. 结构完整性
| # | 检查项 | 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 | 目录命名规范 | 全小写、连字符、动名词形式 |
---
## 2. Frontmatter 规范
| # | 检查项 | PASS 条件 |
|---|-------|----------|
| F1 | description 单行 | YAML 解析后 description 为单行字符串 |
| F2 | description 长度 | < 1024 字符 |
| F3 | description 中英文 | 同时包含中文和英文描述 |
| F4 | description 含触发场景 | 包含 "触发场景" 或 "Trigger" 关键词 |
| F5 | description 含关键词 | 包含 "关键词" 或 "Keywords" |
| F6 | name 格式 | 小写字母 + 数字 + 连字符，动名词开头 |
| F7 | argument-hint 存在 | frontmatter 中包含 argument-hint 字段 |
| F8 | allowed-tools 最小授权 | 只读 Skill 不包含 Write/Edit |
---
## 3. 内容质量
| # | 检查项 | PASS 条件 |
|---|-------|----------|
| C1 | SKILL.md 行数 | < 500 行 |
| C2 | 包含 Plan 章节 | grep 到 `## Plan` |
| C3 | 包含 Verify 章节 | grep 到 `## Verify` |
| C4 | 包含 Execute 章节 | grep 到 `## Execute` |
| C5 | 包含 Pitfalls 章节 | grep 到 `## Pitfalls` |
| C6 | 动态注入 | ≥ 2 处 `!` + 反引号命令 |
| C7 | Pitfalls 引用 reference | ≥ 2 条 Pitfall 中出现 `reference/` 路径 |
| C8 | 无空话 | 不含"检查 XX 一致性"这类无具体动作的描述 |
| C9 | 无常识内容 | 不含 Claude 已知的通用知识（如 HTTP 状态码定义） |
| C10 | 术语一致 | 同一概念在所有 Skill 中使用相同术语 |
---
## 4. Reference 质量
| # | 检查项 | PASS 条件 |
|---|-------|----------|
| R1 | 设计要素覆盖率 | 每个模块 Skill 覆盖 ≥ 3 类（API/事件/DB/状态机/权限/依赖） |
| R2 | 章节分层 | reference/ 下存在 `01-*` 等编号目录（或使用扁平+说明） |
| R3 | DDS 溯源 | 每条 reference 含 `DDS-Section:` 字段 |
| R4 | DDS 行号 | 每条 reference 含 `DDS-Lines:` 字段 |
| R5 | TBD 标注 | DDS 缺失内容标注 `[TBD]`，附最小补充清单 |
| R6 | 无脑补 | 所有设计细节可溯源到 DDS 原文 |
| R7 | 内容充分 | reference 包含足够的结构化数据（表格/列表/代码块） |
---
## 5. 跨 Skill 一致性
| # | 检查项 | PASS 条件 |
|---|-------|----------|
| X1 | 模块名一致 | 所有 Skill 中模块名拼写相同 |
| X2 | 错误码不冲突 | 相同错误码在不同 Skill 中含义相同 |
| X3 | API 路径不冲突 | 不同模块的 API 路径无重叠 |
| X4 | 事件/Topic 定义一致 | 同一 Topic 在发布方和订阅方 Skill 中定义相同 |
| X5 | 授权模型一致 | JWT Claims、角色定义在所有 Skill 中一致 |
---
## 6. 自检输出格式
```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
## Frontmatter 规范
- ✅ F1 PASS: 所有 description 为单行
- ❌ F2 FAIL: `developing-core` 的 description 超过 1024 字符（1156 字符）
- **修复**: 精简触发场景描述，移除重复关键词
## 内容质量
- ✅ C1 PASS: 所有 SKILL.md < 500 行
- ❌ C8 FAIL: `developing-gateway` 中 Verify 包含"检查 API 一致性"
- **修复**: 改为"对照 reference/02-api-design/apis.md 中的接口清单，grep 仓库中的 handler 注册点，确认路径和方法一致"
## 总计: XX PASS / YY FAIL
```
---
## 7. 常见 FAIL 及修复方案
| FAIL 类型 | 常见原因 | 修复方案 |
|----------|---------|---------|
| description 多行 | 使用了 `\|` 语法 | 改用 `>` 或单行字符串 |
| reference 不足 | DDS 内容被遗漏 | 重新扫描 DDS，补充缺失要素 |
| 空话 | 直接复制 DDS 原文 | 转化为可执行的审查动作 |
| 脑补 | DDS 未提及的细节 | 标注 [TBD] 并列出补充清单 |
| 横切不足 | 未充分分析 DDS | 从 DDS 中识别更多跨模块关注点 |

255
.agents/skills/dds-to-skill/reference/skill-templates.md Normal file
View File

@@ -0,0 +1,255 @@
# SKILL.md 模板库
本文档包含系统级 Skill、模块级 Skill、横切 Skill 的 SKILL.md 模板，供 DDS-to-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 模板
```markdown
---
name: developing-<module>
description: >
指导 <module> 模块的开发（Guides development of <module> module）。
包含：<模块职责概述>、API 实现、数据库操作、状态管理、安全校验。
触发场景 Trigger: 开发/修改 <module> 相关功能 / <模块特定场景>。
关键词 Keywords: <module>, <技术关键词>, <业务关键词>。
argument-hint: "<action> <target> - e.g., 'create handler', 'add api', 'update schema'"
allowed-tools:
- Read
- Write
- Edit
- Glob
- Grep
- Bash
---
# Developing <Module>
<一段话描述模块职责、技术栈、在系统中的位置>
## Quick Context
```bash
# 动态注入：查看模块结构
!`find . -name "*.go" -path "*/<module>/*" | head -20`
# 动态注入：查看现有接口
!`grep -rn "func.*Handler\|func.*Service" ./<module>/ | head -20`
```
## Plan
### 产物清单
- [ ] <根据 DDS 列出具体产物>
### 决策点
1. <从 DDS 抽取的关键决策>
2. ...
## Verify
### <验证类别 1>
- [ ] <具体检查项，引用 reference>
### <验证类别 2>
- [ ] <具体检查项>
## Execute
### 1. <步骤标题>
```bash
# 具体操作命令
```
### 2. <步骤标题>
```go
// 关键代码骨架
```
## Pitfalls
1. **<坑名>**: <描述>（参考 `reference/<file>.md`）
2. ...（至少 3 条，至少 2 条引用 reference）
## Related References
- [API 定义](reference/01-<section>/apis.md)
- [数据库 Schema](reference/02-<section>/db-schema.md)
```
---
## 3. 横切 Skill 模板
```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 必须自定义的部分
- `<尖括号>` 中的所有占位符
- Plan 的产物清单和决策点必须来自 DDS
- Verify 的检查项必须与模块设计细节对应
- Pitfalls 必须与模块/主题强相关，不可用通用建议填充
### 4.2 禁止照搬模板
模板是结构参考，不是内容来源。以下行为将导致自检 FAIL：
- 产物清单中出现模板占位符
- Pitfalls 与模块无关（如：在前端 Skill 中出现数据库 Pitfall）
- Verify 中没有引用任何 reference
### 4.3 按 DDS 内容增减
- 如果 DDS 中没有状态机，模块 Skill 可以不包含状态机相关 Verify
- 如果 DDS 中有额外的关注点（如性能优化、缓存策略），应增加对应章节
- 横切 Skill 的数量和主题必须由 DDS 内容决定

214
.agents/skills/dds-to-skill/scripts/verify-skill-output.sh Normal file
View File

@@ -0,0 +1,214 @@
#!/bin/bash
# verify-skill-output.sh
# 验证 DDS-to-Skill 转换输出的完整性和质量
#
# 用法：./verify-skill-output.sh <skills-output-dir>
# 示例：./verify-skill-output.sh /path/to/1-AgentSkills
#
# 依赖：bash, grep, sed, find, wc
set -e
SKILLS_DIR="${1:-.}"
PASS=0
FAIL=0
WARN=0
# 颜色输出
GREEN='\033[0;32m'
RED='\033[0;31m'
YELLOW='\033[0;33m'
NC='\033[0m' # No Color
pass() {
echo -e "${GREEN}✅ PASS${NC}: $1"
((PASS++))
}
fail() {
echo -e "${RED}❌ FAIL${NC}: $1"
echo -e " ${RED}修复${NC}: $2"
((FAIL++))
}
warn() {
echo -e "${YELLOW}⚠️ WARN${NC}: $1"
((WARN++))
}
echo "============================================"
echo " DDS-to-Skill 输出质量验证"
echo " 目标目录: $SKILLS_DIR"
echo "============================================"
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 个)"
else
warn "S1: 未找到系统级 Skill（名称包含 '-system'）"
fi
# S4: 每个 Skill 都有 SKILL.md
SKILL_DIRS=$(find "$SKILLS_DIR" -maxdepth 1 -type d ! -name "$(basename "$SKILLS_DIR")" 2>/dev/null)
MISSING_SKILLMD=0
for dir in $SKILL_DIRS; do
if [ ! -f "$dir/SKILL.md" ]; then
fail "S4: $dir 缺少 SKILL.md" "创建该目录下的 SKILL.md"
((MISSING_SKILLMD++))
fi
done
if [ "$MISSING_SKILLMD" -eq 0 ]; then
pass "S4: 所有 Skill 目录都有 SKILL.md"
fi
# S5: 每个 Skill 都有 reference/
MISSING_REF=0
for dir in $SKILL_DIRS; do
if [ ! -d "$dir/reference" ]; then
warn "S5: $dir 缺少 reference/ 目录"
((MISSING_REF++))
fi
done
if [ "$MISSING_REF" -eq 0 ]; then
pass "S5: 所有 Skill 目录都有 reference/"
fi
echo ""
# ============================================
# 2. Frontmatter 规范检查
# ============================================
echo "--- 2. Frontmatter 规范 ---"
for dir in $SKILL_DIRS; do
SKILL_FILE="$dir/SKILL.md"
[ ! -f "$SKILL_FILE" ] && continue
SKILL_NAME=$(basename "$dir")
# F1: name 字段
if head -20 "$SKILL_FILE" | grep -q '^name:'; then
pass "F1 [$SKILL_NAME]: frontmatter 包含 name"
else
fail "F1 [$SKILL_NAME]: 缺少 name 字段" "在 frontmatter 中添加 name 字段"
fi
# F2: description 字段
if head -20 "$SKILL_FILE" | grep -q '^description:'; then
pass "F2 [$SKILL_NAME]: frontmatter 包含 description"
else
fail "F2 [$SKILL_NAME]: 缺少 description 字段" "在 frontmatter 中添加 description 字段"
fi
# C1: 行数 < 500
LINE_COUNT=$(wc -l < "$SKILL_FILE")
if [ "$LINE_COUNT" -lt 500 ]; then
pass "C1 [$SKILL_NAME]: SKILL.md = $LINE_COUNT 行 (< 500)"
else
fail "C1 [$SKILL_NAME]: SKILL.md = $LINE_COUNT 行 (>= 500)" "将冗长内容移到 reference/ 中"
fi
done
echo ""
# ============================================
# 3. 内容质量检查
# ============================================
echo "--- 3. 内容质量 ---"
for dir in $SKILL_DIRS; do
SKILL_FILE="$dir/SKILL.md"
[ ! -f "$SKILL_FILE" ] && continue
SKILL_NAME=$(basename "$dir")
# C2-C5: 必须章节
for section in "Plan" "Verify" "Execute" "Pitfalls"; do
if grep -q "## $section" "$SKILL_FILE"; then
pass "C [$SKILL_NAME]: 包含 ## $section"
else
warn "C [$SKILL_NAME]: 缺少 ## $section 章节"
fi
done
# C6: 动态注入
INJECT_COUNT=$(grep -c '!`' "$SKILL_FILE" 2>/dev/null || echo 0)
if [ "$INJECT_COUNT" -ge 2 ]; then
pass "C6 [$SKILL_NAME]: $INJECT_COUNT 处动态注入 (>= 2)"
else
warn "C6 [$SKILL_NAME]: 仅 $INJECT_COUNT 处动态注入 (建议 >= 2)"
fi
# C7: Pitfalls 引用 reference
REF_IN_PITFALLS=$(sed -n '/## Pitfalls/,/## /p' "$SKILL_FILE" | grep -c 'reference/' 2>/dev/null || echo 0)
if [ "$REF_IN_PITFALLS" -ge 2 ]; then
pass "C7 [$SKILL_NAME]: Pitfalls 中 $REF_IN_PITFALLS 处引用 reference (>= 2)"
else
warn "C7 [$SKILL_NAME]: Pitfalls 中仅 $REF_IN_PITFALLS 处引用 reference (建议 >= 2)"
fi
done
echo ""
# ============================================
# 4. Reference 质量检查
# ============================================
echo "--- 4. Reference 质量 ---"
for dir in $SKILL_DIRS; do
[ ! -d "$dir/reference" ] && continue
SKILL_NAME=$(basename "$dir")
# R2: 章节分层
SECTION_DIRS=$(find "$dir/reference" -maxdepth 1 -type d -name '0*' 2>/dev/null | wc -l)
if [ "$SECTION_DIRS" -ge 1 ]; then
pass "R2 [$SKILL_NAME]: reference 有 $SECTION_DIRS 个章节子目录"
else
warn "R2 [$SKILL_NAME]: reference 无章节子目录（使用扁平结构）"
fi
# R3: DDS 溯源
DDS_SECTION_COUNT=$(grep -r 'DDS-Section:' "$dir/reference/" 2>/dev/null | wc -l)
if [ "$DDS_SECTION_COUNT" -ge 1 ]; then
pass "R3 [$SKILL_NAME]: $DDS_SECTION_COUNT 处 DDS-Section 溯源"
else
warn "R3 [$SKILL_NAME]: 无 DDS-Section 溯源标记"
fi
# R5: TBD 标注
TBD_COUNT=$(grep -r '\[TBD' "$dir/reference/" 2>/dev/null | wc -l)
if [ "$TBD_COUNT" -ge 0 ]; then
pass "R5 [$SKILL_NAME]: $TBD_COUNT 处 [TBD] 标注"
fi
# R1: 设计要素类型数
REF_FILES=$(find "$dir/reference" -name "*.md" 2>/dev/null | wc -l)
if [ "$REF_FILES" -ge 3 ]; then
pass "R1 [$SKILL_NAME]: $REF_FILES 个 reference 文件 (>= 3)"
else
warn "R1 [$SKILL_NAME]: 仅 $REF_FILES 个 reference 文件 (建议 >= 3)"
fi
done
echo ""
# ============================================
# 总结
# ============================================
echo "============================================"
echo " 验证完成"
echo " ✅ PASS: $PASS"
echo " ❌ FAIL: $FAIL"
echo " ⚠️ WARN: $WARN"
echo "============================================"
if [ "$FAIL" -gt 0 ]; then
exit 1
else
exit 0
fi

60
.agents/skills/dds-to-skill/scripts/verify.sh Normal file
View File

@@ -0,0 +1,60 @@
#!/bin/bash
# verify.sh - dds-to-skill Skill 自身结构验证
#
# 验证本 Skill 的文件结构和内容完整性
# 用法：cd dds-to-skill && ./scripts/verify.sh
set -e
PASS=0; FAIL=0
check() {
if eval "$2"; then
echo "✅ PASS: $1"; ((PASS++))
else
echo "❌ FAIL: $1"; ((FAIL++))
fi
}
SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
echo "=== dds-to-skill Skill 自检 ==="
echo "目录: $SKILL_DIR"
echo ""
# 结构检查
check "SKILL.md 存在" "test -f '$SKILL_DIR/SKILL.md'"
check "reference/ 目录存在" "test -d '$SKILL_DIR/reference'"
check "examples/ 目录存在" "test -d '$SKILL_DIR/examples'"
check "scripts/ 目录存在" "test -d '$SKILL_DIR/scripts'"
# SKILL.md 内容检查
check "SKILL.md < 500 行" "[ \$(wc -l < '$SKILL_DIR/SKILL.md') -lt 500 ]"
check "包含 name 字段" "head -20 '$SKILL_DIR/SKILL.md' | grep -q '^name:'"
check "包含 description 字段" "head -20 '$SKILL_DIR/SKILL.md' | grep -q '^description:'"
check "包含 argument-hint" "head -20 '$SKILL_DIR/SKILL.md' | grep -q 'argument-hint:'"
# 阶段结构检查
check "包含 Phase 0（读取）" "grep -q 'Phase 0' '$SKILL_DIR/SKILL.md'"
check "包含 Phase 1（分析）" "grep -q 'Phase 1' '$SKILL_DIR/SKILL.md'"
check "包含 Phase 2（抽取）" "grep -q 'Phase 2' '$SKILL_DIR/SKILL.md'"
check "包含 Phase 3（生成）" "grep -q 'Phase 3' '$SKILL_DIR/SKILL.md'"
check "包含 Phase 4（支撑文件）" "grep -q 'Phase 4' '$SKILL_DIR/SKILL.md'"
check "包含 Phase 5（自检）" "grep -q 'Phase 5' '$SKILL_DIR/SKILL.md'"
# Reference 文件检查
check "dds-extraction-guide.md 存在" "test -f '$SKILL_DIR/reference/dds-extraction-guide.md'"
check "skill-templates.md 存在" "test -f '$SKILL_DIR/reference/skill-templates.md'"
check "frontmatter-spec.md 存在" "test -f '$SKILL_DIR/reference/frontmatter-spec.md'"
check "quality-checklist.md 存在" "test -f '$SKILL_DIR/reference/quality-checklist.md'"
# Examples 检查
check "至少 1 个转换示例" "find '$SKILL_DIR/examples' -name '*.md' | grep -q ."
# 动态注入检查
INJECT_COUNT=$(grep -c '!\`' "$SKILL_DIR/SKILL.md" 2>/dev/null || echo 0)
check "SKILL.md 包含动态注入 (>= 2 处)" "[ $INJECT_COUNT -ge 2 ]"
echo ""
echo "=== 结果: $PASS PASS / $FAIL FAIL ==="
[ $FAIL -eq 0 ] && exit 0 || exit 1