OA/zentao-flow

Fork 0

Files

T

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

2026-10-08 16:15:33 +08:00

6.6 KiB

Raw Blame History

name, description

name	description
docmap	项目文档架构生成技能。从代码、SQL、接口定义、文档中提炼产品视角的架构文档。输出：《产品整体架构文档》+ 各模块《功能模块拆解文档》+ 系统能力模型。适用场景：新项目入手、产品知识基座构建、PRD 生成前的背景探索。触发关键词：分析项目架构、生成产品文档、生成架构文档、理解系统、/docmap

name

description

docmap

项目文档架构生成技能。从代码、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

路径发现策略：

检查默认路径是否存在
不存在时扫描项目根目录寻找对应内容
向用户确认发现的路径，确认后把最终路径映射写入 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

必须包含：

产品定位（目标、价值、用户、场景）
系统整体架构（分层、技术概览、依赖关系）
业务架构图（Mermaid）
核心业务流程说明（Mermaid 流程图）
数据架构（实体、关系、生命周期）
权限与角色体系（角色定义、权限分层）
系统扩展点分析

2.2 功能模块拆解文档

目录： outputs/02-功能模块/
命名： {序号}-{模块名}.md

每个模块包含：

模块定位
功能清单（表格）
核心逻辑（规则、校验、状态流转 Mermaid）
数据结构（表、字段、关联）
对外接口（API、事件、回调）
异常与边界处理

Phase 3：系统能力模型

文件： outputs/03-系统能力模型.md

包含：

核心能力清单（不超过 10 项）
能力依赖关系图（Mermaid）
可复用能力清单（表格）
平台级能力
业务定制能力

Phase 4：质量检查

执行验证脚本检查输出完整性：

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 初始版本

6.6 KiB Raw Blame History Unescape Escape