OA/zentao-flow
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 根目录文档、脚本、gitignore

Browse Source
This commit is contained in:
guoqibing
2026-10-08 16:15:33 +08:00
commit e98660ce4e
284 changed files with 26838 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/docmap/SKILL.md
+187
View File
@@ -0,0 +1,187 @@
---
name: docmap
description: |
项目文档架构生成技能。从代码、SQL、接口定义、文档中提炼产品视角的架构文档。
输出：《产品整体架构文档》+ 各模块《功能模块拆解文档》+ 系统能力模型。
适用场景：新项目入手、产品知识基座构建、PRD 生成前的背景探索。
触发关键词：分析项目架构、生成产品文档、生成架构文档、理解系统、/docmap
---
# docmap — 项目文档架构生成
## 触发条件
- 用户说"分析项目架构"、"生成产品文档"、"生成架构文档"
- 用户说"帮我理解这个系统"、"先了解项目再写 PRD"
- 直接输入 `/docmap [项目路径]`
---
## 角色定位
资深产品架构师 + 系统架构师 + 技术产品经理。从代码和文档中提炼产品层逻辑，而非重复代码结构。
---
## Phase 0：资源发现与确认
扫描以下资源路径（以项目根为准，默认路径为本项目实际结构）：
| 资源 ID | 默认路径 | 内容 | 优先级 |
|---------|---------------------------------------|------|--------|
| SRC-KNOWLEDGE | `assets/codemap/`、`assets/domainmap/` | 已有结构化知识（YAML 知识图谱），存在时优先消费 | P0 |
| SRC-FEAT | `prds/` | 功能需求文档 | P0 |
| SRC-CODE | `codes/`（源码子仓库） | 代码结构 | P0 |
| SRC-SQL | `docs/sql/` 或各仓库内 SQL | 数据库设计 | P1 |
| SRC-API | `docs/open-api/` | 接口定义 | P1 |
| SRC-REVIEW | `docs/` 下评审类目录 | 评审报告 | P2 |
**路径发现策略：**
1. 检查默认路径是否存在
2. 不存在时扫描项目根目录寻找对应内容
3. 向用户确认发现的路径，确认后把最终路径映射写入 `materials_index.md`
**输出：** `materials_index.md`（资料索引）
---
## 输入来源与技能边界
- codemap / domainmap 产出**结构化事实**（YAML 知识图谱：符号、API、调用链、数据对象、实体、流程、规则等）；docmap **消费其产出**，撰写叙事性产品文档，不重复生成结构化事实。
- 当 `assets/codemap/`、`assets/domainmap/` 存在时，模块边界、数据流、业务流程等分析应**优先引用**其中的结构化事实，而非从原始代码重新挖掘；原始代码仅用于补充知识图谱未覆盖的细节。
- 引用结构化知识时按 `[SRC-KNOWLEDGE]` 标注证据（见"证据标注"节）。
---
## Phase 1：项目深度理解
6 个维度分析（每个维度必须有输出）：
| 维度 | 分析问题 | 主要资源 |
|------|---------|---------|
| 系统目标 | 产品要解决什么问题？核心价值是什么？ | SRC-FEAT |
| 核心业务流程 | 主流程是什么？关键节点有哪些？ | SRC-FEAT + SRC-CODE |
| 系统角色 | 有哪些用户角色？各自的操作边界？ | SRC-FEAT |
| 模块边界 | 系统拆分为哪些模块？边界如何划定？ | SRC-CODE |
| 数据流 | 数据从哪里来、流向哪里？生命周期？ | SRC-SQL + SRC-API |
| 系统依赖 | 内外部依赖有哪些？集成点在哪？ | SRC-API + SRC-CODE |
**输出：** `phase1_analysis.md`
---
## Phase 2：输出文档生成
### 2.1 产品整体架构文档
**文件：** `outputs/01-产品整体架构.md`
必须包含：
1. 产品定位（目标、价值、用户、场景）
2. 系统整体架构（分层、技术概览、依赖关系）
3. 业务架构图（Mermaid）
4. 核心业务流程说明（Mermaid 流程图）
5. 数据架构（实体、关系、生命周期）
6. 权限与角色体系（角色定义、权限分层）
7. 系统扩展点分析
### 2.2 功能模块拆解文档
**目录：** `outputs/02-功能模块/`
**命名：** `{序号}-{模块名}.md`
每个模块包含：
1. 模块定位
2. 功能清单（表格）
3. 核心逻辑（规则、校验、状态流转 Mermaid）
4. 数据结构（表、字段、关联）
5. 对外接口（API、事件、回调）
6. 异常与边界处理
---
## Phase 3：系统能力模型
**文件：** `outputs/03-系统能力模型.md`
包含：
1. 核心能力清单（不超过 10 项）
2. 能力依赖关系图（Mermaid）
3. 可复用能力清单（表格）
4. 平台级能力
5. 业务定制能力
---
## Phase 4：质量检查
执行验证脚本检查输出完整性：
```bash
python3 scripts/validate_output.py {workdir}/outputs
```
- **参数：** `outputs` 子目录路径（脚本位于本技能 `scripts/` 下，参数可写相对项目根路径或绝对路径）
- **报告输出：** `{workdir}/validation_report.md`（即 outputs 的父目录）
- **退出码：** 存在失败项时为非零；仅有警告项时为零
检查项（与脚本口径一致）：
- 目录结构完整（`01-产品整体架构.md`、`02-功能模块/`、`03-系统能力模型.md`）
- 架构文档 7 个章节完整
- 架构文档至少 2 个 Mermaid 图
- 模块文档都有功能清单表格
- 能力模型包含能力依赖关系图（Mermaid）及平台级/业务定制能力区分
- 模块文档 stateDiagram 状态流转图（警告项，不阻断：无状态机的模块可豁免）
- 模糊表述（"等"、"等情况"、"等多种"等；警告项，不阻断）
**输出：** `validation_report.md`
---
## 写作原则
- **产品视角**，不重复代码结构
- **逻辑严谨**，不泛泛而谈
- **可长期维护**
- 禁止模糊表达："等情况"、"等多种"、"其他相关"
### 证据标注
- `[SRC-KNOWLEDGE]` - 已有结构化知识库（codemap / domainmap）
- `[SRC-FEAT]` - 功能文档
- `[SRC-CODE]` - 代码结构
- `[SRC-SQL]` - 数据库设计
- `[SRC-API]` - 接口定义
- `[ASSUMPTION]` - 无证据推断
---
## 工作目录结构
```
{workdir}/
├── materials_index.md
├── phase1_analysis.md
├── outputs/
│ ├── 01-产品整体架构.md
│ ├── 02-功能模块/
│ │ └── {序号}-{模块名}.md
│ └── 03-系统能力模型.md
└── validation_report.md
```
---
## 使用 bundled resources
### 参考模板
- `references/architecture_template.md` - 架构文档模板
- `references/module_template.md` - 模块文档模板
- `references/capability_template.md` - 能力模型模板
### 验证脚本
- `scripts/validate_output.py` - 输出质量检查脚本
---
## 版本历史
- **v1.1**（2026-08）输入源对齐项目实际结构（`codes/`、`prds/`、`docs/` 子目录）；新增"输入来源与技能边界"，消费 codemap/domainmap 已有产出；Phase 4 补验证脚本调用示例，检查项口径与脚本实现对齐
- **v1.0** 初始版本
.agents/skills/docmap/references/architecture_template.md
+154
View File
@@ -0,0 +1,154 @@
# 产品整体架构文档
## 1. 产品定位
### 1.1 产品目标
<!-- 描述产品要解决的核心问题 -->
### 1.2 核心价值
<!-- 产品的独特价值主张 -->
### 1.3 目标用户
<!-- 主要用户群体及其特征 -->
### 1.4 使用场景
<!-- 典型使用场景描述 -->
---
## 2. 系统整体架构
### 2.1 架构分层
```
┌─────────────────────────────────────────┐
│ 表现层 (Presentation) │
├─────────────────────────────────────────┤
│ 业务层 (Business) │
├─────────────────────────────────────────┤
│ 数据层 (Data) │
├─────────────────────────────────────────┤
│ 基础设施层 (Infrastructure) │
└─────────────────────────────────────────┘
```
### 2.2 技术架构概览
<!-- 技术栈、框架选择、部署架构 -->
### 2.3 系统依赖关系
<!-- 内部模块依赖、外部服务依赖 -->
---
## 3. 业务架构图
```mermaid
graph TB
subgraph 业务域A
A1[子域1]
A2[子域2]
end
subgraph 业务域B
B1[子域3]
B2[子域4]
end
A1 --> B1
A2 --> B2
```
### 3.1 核心业务域划分
<!-- 各业务域的职责说明 -->
### 3.2 业务域关系
<!-- 域之间的协作关系 -->
### 3.3 主业务流程
<!-- 端到端业务流程概述 -->
---
## 4. 核心业务流程说明
### 4.1 用户主流程
```mermaid
flowchart LR
A[开始] --> B[步骤1]
B --> C[步骤2]
C --> D[步骤3]
D --> E[结束]
```
### 4.2 管理流程
```mermaid
flowchart TD
A[管理操作] --> B{判断}
B -->|条件1| C[处理1]
B -->|条件2| D[处理2]
```
### 4.3 数据流转流程
<!-- 数据在系统中的流动路径 -->
---
## 5. 数据架构
### 5.1 核心数据实体
<!-- 主要数据实体列表 -->
| 实体名称 | 描述 | 主要属性 |
|---------|------|---------|
| 实体A | 描述A | 属性1, 属性2 |
| 实体B | 描述B | 属性3, 属性4 |
### 5.2 实体关系
```mermaid
erDiagram
ENTITY_A ||--o{ ENTITY_B : contains
ENTITY_A {
string id
string name
}
ENTITY_B {
string id
string entity_a_id
}
```
### 5.3 数据生命周期
<!-- 数据的创建、更新、归档、删除流程 -->
---
## 6. 权限与角色体系
### 6.1 角色定义
| 角色名称 | 职责描述 | 操作范围 |
|---------|---------|---------|
| 角色A | 职责A | 范围A |
| 角色B | 职责B | 范围B |
### 6.2 权限分层
<!-- 权限的层级结构 -->
### 6.3 控制逻辑
<!-- 权限校验的实现逻辑 -->
---
## 7. 系统扩展点分析
### 7.1 可扩展模块
<!-- 设计上预留的扩展点 -->
### 7.2 可插拔能力
<!-- 可替换/可插拔的组件 -->
### 7.3 易变业务点
<!-- 预期会频繁变化的业务逻辑 -->
.agents/skills/docmap/references/capability_template.md
+69
View File
@@ -0,0 +1,69 @@
# 系统能力模型总结
## 1. 当前系统具备的核心能力
<!-- 每项能力一句话概括，不超过 10 项 -->
1. **能力1**: 一句话描述该能力
2. **能力2**: 一句话描述该能力
3. **能力3**: 一句话描述该能力
---
## 2. 能力依赖关系图
```mermaid
graph TD
subgraph 平台层
P1[平台能力1]
P2[平台能力2]
end
subgraph 业务层
B1[业务能力1]
B2[业务能力2]
end
P1 --> B1
P2 --> B2
B1 --> B2
```
---
## 3. 可复用能力清单
| 能力名称 | 复用场景 | 复用方式 |
|---------|---------|---------|
| 能力1 | 场景A, 场景B | 方式描述 |
| 能力2 | 场景C | 方式描述 |
---
## 4. 平台级能力
<!-- 多个业务都依赖的底层能力 -->
### 4.1 能力A
- **描述**:
- **使用方**:
- **实现位置**:
### 4.2 能力B
- **描述**:
- **使用方**:
- **实现位置**:
---
## 5. 业务定制能力
<!-- 特定业务场景才需要的能力 -->
### 5.1 业务X 定制能力
- **描述**:
- **业务场景**:
### 5.2 业务Y 定制能力
- **描述**:
- **业务场景**:
.agents/skills/docmap/references/module_template.md
+114
View File
@@ -0,0 +1,114 @@
# {模块名称}
## 1. 模块定位
### 1.1 模块目标
<!-- 该模块要解决什么问题 -->
### 1.2 解决问题
<!-- 具体解决的业务/技术问题 -->
---
## 2. 功能清单
| 功能名称 | 功能描述 | 输入 | 输出 | 依赖模块 |
|---------|---------|------|------|---------|
| 功能1 | 描述1 | 输入1 | 输出1 | 模块A |
| 功能2 | 描述2 | 输入2 | 输出2 | 模块B |
---
## 3. 核心逻辑
### 3.1 业务规则
<!-- 穷举所有业务规则 -->
1. **规则1**: 规则描述
2. **规则2**: 规则描述
### 3.2 校验逻辑
<!-- 穷举所有校验条件 -->
| 校验项 | 校验规则 | 错误提示 |
|-------|---------|---------|
| 校验1 | 规则描述 | 错误信息 |
| 校验2 | 规则描述 | 错误信息 |
### 3.3 状态流转
```mermaid
stateDiagram-v2
[*] --> 初始状态
初始状态 --> 状态A: 事件1
状态A --> 状态B: 事件2
状态B --> [*]: 结束
状态A --> 异常状态: 异常事件
```
---
## 4. 数据结构
### 4.1 涉及数据表
<!-- 该模块涉及的数据库表 -->
| 表名 | 描述 | 关键字段 |
|-----|------|---------|
| 表A | 描述A | 字段1, 字段2 |
| 表B | 描述B | 字段3, 字段4 |
### 4.2 字段说明
<!-- 关键字段逐个说明 -->
**表A**
| 字段名 | 类型 | 说明 | 约束 |
|-------|------|------|------|
| id | bigint | 主键 | 自增 |
| name | varchar | 名称 | 非空 |
### 4.3 数据关联
<!-- 与其他模块的数据关联关系 -->
---
## 5. 对外接口
### 5.1 API 列表
| 接口 | 方法 | 路径 | 描述 |
|-----|------|------|------|
| 接口1 | GET | /api/xxx | 描述1 |
| 接口2 | POST | /api/yyy | 描述2 |
### 5.2 事件机制
<!-- 发布/订阅的事件 -->
| 事件名称 | 触发时机 | 消费者 |
|---------|---------|--------|
| 事件1 | 时机1 | 消费者A |
### 5.3 回调机制
<!-- 回调接口定义 -->
---
## 6. 异常与边界处理
### 6.1 异常情况
| 异常场景 | 处理方式 | 返回信息 |
|---------|---------|---------|
| 场景1 | 处理方式1 | 信息1 |
| 场景2 | 处理方式2 | 信息2 |
### 6.2 边界条件
| 边界条件 | 处理逻辑 |
|---------|---------|
| 条件1 | 逻辑1 |
| 条件2 | 逻辑2 |
### 6.3 性能考虑
<!-- 大数据量、高并发等场景的处理 -->
.agents/skills/docmap/scripts/validate_output.py
+246
View File
@@ -0,0 +1,246 @@
#!/usr/bin/env python3
"""
docmap 输出质量验证脚本
检查生成的文档是否符合规范要求
检查项分两级：
- 失败项（failed）：结构/内容缺失，退出码非零
- 警告项（warning）：可疑但不阻断（如 stateDiagram、模糊表述），不影响退出码
"""
import re
import sys
from datetime import datetime
from pathlib import Path
from dataclasses import dataclass
from typing import List
# 模糊表述"等"的白名单（合理用法，不算模糊）
DENG_WHITELIST = [
"等于", "等待", "对等", "等级", "等同", "同等", "均等",
"不等", "稍等", "优等", "劣等", "等比", "等值",
]
@dataclass
class ValidationResult:
passed: bool
message: str
file: str = ""
warning: bool = False # True 表示警告项，不计入失败、不影响退出码
class DocmapValidator:
def __init__(self, outputs_dir: str):
self.outputs_dir = Path(outputs_dir)
self.results: List[ValidationResult] = []
def validate(self) -> List[ValidationResult]:
"""执行所有验证"""
self.results = []
# 检查目录结构
self._check_directory_structure()
# 验证架构文档
self._validate_architecture_doc()
# 验证模块文档
self._validate_module_docs()
# 验证能力模型
self._validate_capability_doc()
return self.results
def _check_directory_structure(self):
"""检查输出目录结构"""
if not self.outputs_dir.exists():
self.results.append(ValidationResult(
False, "输出目录不存在", str(self.outputs_dir)
))
return
# 检查必需文件
required_files = ["01-产品整体架构.md", "03-系统能力模型.md"]
for f in required_files:
path = self.outputs_dir / f
if not path.exists():
self.results.append(ValidationResult(
False, f"缺少必需文件: {f}", str(self.outputs_dir)
))
# 检查模块目录
module_dir = self.outputs_dir / "02-功能模块"
if not module_dir.exists():
self.results.append(ValidationResult(
False, "缺少功能模块目录", str(self.outputs_dir)
))
def _validate_architecture_doc(self):
"""验证架构文档"""
doc_path = self.outputs_dir / "01-产品整体架构.md"
if not doc_path.exists():
return
content = doc_path.read_text(encoding='utf-8')
# 检查 7 个必需章节
required_sections = [
"产品定位",
"系统整体架构",
"业务架构图",
"核心业务流程",
"数据架构",
"权限与角色体系",
"系统扩展点分析"
]
for section in required_sections:
if section not in content:
self.results.append(ValidationResult(
False, f"缺少章节: {section}", str(doc_path)
))
# 检查 Mermaid 图（至少 2 个）
mermaid_count = content.count("```mermaid")
if mermaid_count < 2:
self.results.append(ValidationResult(
False, f"Mermaid 图数量不足: 需要至少 2 个，实际 {mermaid_count} 个", str(doc_path)
))
else:
self.results.append(ValidationResult(
True, f"Mermaid 图数量: {mermaid_count} 个", str(doc_path)
))
# 检查模糊表述（警告项，不阻断）
fuzzy_patterns = [r"等情况", r"等多种", r"其他相关", r"等等", r"诸如此类"]
for pattern in fuzzy_patterns:
matches = re.findall(pattern, content)
if matches:
self.results.append(ValidationResult(
False, f"发现模糊表述 '{pattern}': 出现 {len(matches)} 次",
str(doc_path), warning=True
))
def _validate_module_docs(self):
"""验证模块文档"""
module_dir = self.outputs_dir / "02-功能模块"
if not module_dir.exists():
return
module_files = list(module_dir.glob("*.md"))
if not module_files:
self.results.append(ValidationResult(
False, "功能模块目录为空", str(module_dir)
))
return
for module_file in module_files:
content = module_file.read_text(encoding='utf-8')
# 检查功能清单表格
if "| 功能名称 |" not in content and "|功能名称|" not in content:
self.results.append(ValidationResult(
False, "缺少功能清单表格", str(module_file)
))
# 检查状态流转 Mermaid（警告项，不阻断：无状态机的模块可豁免）
if "```mermaid" not in content or "stateDiagram" not in content:
self.results.append(ValidationResult(
False, "缺少状态流转 Mermaid 图", str(module_file), warning=True
))
# 检查模糊表述"等"（警告项，不阻断；白名单词不算命中）
hit_lines = []
for lineno, line in enumerate(content.split('\n'), 1):
stripped = line
for word in DENG_WHITELIST:
stripped = stripped.replace(word, "")
if "等" in stripped:
hit_lines.append(lineno)
if hit_lines:
self.results.append(ValidationResult(
False,
f"可能包含模糊表述 '等'（行: {', '.join(map(str, hit_lines))}）",
str(module_file), warning=True
))
def _validate_capability_doc(self):
"""验证能力模型文档"""
doc_path = self.outputs_dir / "03-系统能力模型.md"
if not doc_path.exists():
return
content = doc_path.read_text(encoding='utf-8')
# 检查能力依赖关系图
if "```mermaid" not in content:
self.results.append(ValidationResult(
False, "缺少能力依赖关系图", str(doc_path)
))
# 检查平台级/业务定制能力区分
if "平台级能力" not in content or "业务定制能力" not in content:
self.results.append(ValidationResult(
False, "缺少平台级/业务定制能力区分", str(doc_path)
))
def generate_report(self) -> str:
"""生成验证报告"""
passed = [r for r in self.results if r.passed]
warnings = [r for r in self.results if not r.passed and r.warning]
failed = [r for r in self.results if not r.passed and not r.warning]
report = ["# docmap 输出质量验证报告\n"]
report.append(f"**验证时间:** {datetime.now().isoformat()}\n")
report.append(f"**输出目录:** {self.outputs_dir}\n")
report.append(f"**通过项:** {len(passed)}\n")
report.append(f"**警告项:** {len(warnings)}\n")
report.append(f"**失败项:** {len(failed)}\n\n")
if failed:
report.append("## ❌ 失败项\n")
for r in failed:
report.append(f"- **{r.file}**: {r.message}\n")
report.append("\n")
if warnings:
report.append("## ⚠️ 警告项（不阻断）\n")
for r in warnings:
report.append(f"- **{r.file}**: {r.message}\n")
report.append("\n")
if passed:
report.append("## ✅ 通过项\n")
for r in passed:
report.append(f"- **{r.file}**: {r.message}\n")
return "\n".join(report)
def main():
if len(sys.argv) < 2:
print("Usage: python validate_output.py <outputs_directory>")
sys.exit(1)
outputs_dir = sys.argv[1]
validator = DocmapValidator(outputs_dir)
validator.validate()
report = validator.generate_report()
print(report)
# 保存报告
report_path = Path(outputs_dir).parent / "validation_report.md"
report_path.write_text(report, encoding='utf-8')
print(f"\n报告已保存: {report_path}")
# 仅失败项影响退出码；警告项不阻断
failed = [r for r in validator.results if not r.passed and not r.warning]
sys.exit(1 if failed else 0)
if __name__ == "__main__":
main()