personal-doc-manager

personal-doc-manager

功能描述

个人文档管理技能，统一管理项目文档，包括变更记录文档、方案设计Spec文档、测试报告文档等。文档默认存放在项目根路径的 docs 目录下，按类型分目录管理，文件名遵循统一格式：模块-变更内容-日期.md。

触发条件

• 需要创建变更记录文档时
• 需要编写方案设计Spec文档时
• 需要生成测试报告文档时
• 需要管理项目文档结构时

何时使用

• 项目启动时需要初始化文档结构
• 需求变更时需要记录变更内容
• 技术方案设计完成后需要编写Spec文档
• 测试完成后需要生成测试报告
• 需要统一项目文档管理规范时

何时不使用

• 已有完善的文档管理系统且无需变更时
• 仅需要创建临时文档时
• 文档内容无需版本控制时

核心功能

1. 文档结构管理

• 创建标准的 docs 目录结构
• 按文档类型分目录管理
• 统一文件名命名规范

2. 变更记录文档

• 创建变更记录文档
• 记录变更原因、内容、影响范围
• 支持版本号和日期追踪

3. 方案设计Spec文档

• 创建技术方案设计文档
• 记录技术选型、架构设计、接口定义
• 支持与 common-spec-driven 技能联动

4. 测试报告文档

• 创建测试报告文档
• 记录测试用例、测试结果、缺陷统计
• 支持测试覆盖率分析

文档目录结构

项目根目录/
├── docs/
│   ├── changelog/          # 变更记录目录
│   │   └── 模块-变更内容-2026-06-25.md
│   ├── spec/               # 方案设计Spec目录
│   │   └── 模块-方案名称-2026-06-25.md
│   ├── report/             # 测试报告目录
│   │   └── 模块-测试内容-2026-06-25.md
│   ├── design/             # 设计文档目录
│   ├── api/                # API文档目录
│   ├── database/           # 数据库设计目录
│   └── README.md           # 文档说明

目录说明

文件名命名规范

格式

{模块}-{内容描述}-{日期}.md

示例

规则

• 模块：小写英文，使用连字符分隔（如 order-service）
• 内容描述：简洁描述文档内容，使用中文
• 日期：YYYY-MM-DD 格式
• 后缀：.md

文档模板

变更记录文档模板

# 变更记录：{变更主题}

## 基本信息

| 项目 | 内容 |
|------|------|
| 变更编号 | CL-{YYYYMMDD}-{序号} |
| 模块 | {模块名称} |
| 作者 | {作者} |
| 创建日期 | {YYYY-MM-DD} |
| 状态 | 草稿/已审核/已实施/已完成 |

## 变更原因

{描述变更的原因和背景}

## 变更内容

| 变更项 | 变更前 | 变更后 | 影响范围 |
|--------|--------|--------|----------|
| {变更项1} | {变更前内容} | {变更后内容} | {影响的模块/接口} |
| {变更项2} | {变更前内容} | {变更后内容} | {影响的模块/接口} |

## 影响范围

- [ ] 接口变更
- [ ] 数据库变更
- [ ] 前端页面变更
- [ ] 配置变更

## 风险评估

| 风险项 | 风险等级 | 缓解措施 |
|--------|----------|----------|
| {风险项} | 高/中/低 | {缓解措施} |

## 实施计划

| 阶段 | 时间 | 负责人 | 交付物 |
|------|------|--------|--------|
| 设计 | {日期} | {负责人} | 设计文档 |
| 开发 | {日期} | {负责人} | 代码提交 |
| 测试 | {日期} | {负责人} | 测试报告 |
| 上线 | {日期} | {负责人} | 上线验证 |

## 相关文档

- [{文档名称}](path/to/document.md)

方案设计Spec文档模板

# 方案设计：{方案名称}

## 基本信息

| 项目 | 内容 |
|------|------|
| Spec编号 | SPEC-{YYYYMMDD}-{序号} |
| 模块 | {模块名称} |
| 作者 | {作者} |
| 创建日期 | {YYYY-MM-DD} |
| 状态 | 草稿/评审中/已批准/已实施 |

## 需求背景

{描述需求背景和业务目标}

## 技术方案

### 架构设计

{描述整体架构设计，可包含架构图}

### 技术选型

| 技术 | 版本 | 选型理由 |
|------|------|----------|
| {技术名称} | {版本} | {选型理由} |

### 核心设计

{描述核心模块的设计思路}

## 接口设计

### 新增接口

| API路径 | HTTP方法 | 功能描述 |
|---------|----------|----------|
| {路径} | {方法} | {描述} |

### 接口变更

| API路径 | 变更类型 | 变更描述 |
|---------|----------|----------|
| {路径} | 新增/修改/删除 | {描述} |

## 数据库设计

### 新增表

| 表名 | 说明 |
|------|------|
| {表名} | {说明} |

### 字段变更

| 表名 | 字段名 | 变更类型 | 变更描述 |
|------|--------|----------|----------|
| {表名} | {字段名} | 新增/修改/删除 | {描述} |

## 部署方案

{描述部署步骤和注意事项}

## 验收标准

| 验收项 | 验收标准 | 状态 |
|--------|----------|------|
| {验收项} | {标准} | ✅/❌ |

## 参考文档

- [{文档名称}](path/to/document.md)

测试报告文档模板

# 测试报告：{测试主题}

## 基本信息

| 项目 | 内容 |
|------|------|
| 报告编号 | TR-{YYYYMMDD}-{序号} |
| 模块 | {模块名称} |
| 测试类型 | 单元测试/集成测试/功能测试/性能测试 |
| 测试环境 | {环境描述} |
| 作者 | {作者} |
| 创建日期 | {YYYY-MM-DD} |

## 测试范围

{描述本次测试的范围和目标}

## 测试用例统计

| 类别 | 数量 |
|------|------|
| 测试用例总数 | {数量} |
| 通过 | {数量} |
| 失败 | {数量} |
| 跳过 | {数量} |
| 通过率 | {百分比} |

## 测试结果详情

### 通过用例

| 用例编号 | 用例名称 | 测试方法 |
|----------|----------|----------|
| {编号} | {名称} | {方法} |

### 失败用例

| 用例编号 | 用例名称 | 失败原因 | 优先级 |
|----------|----------|----------|--------|
| {编号} | {名称} | {原因} | P0/P1/P2 |

## 缺陷统计

| 严重程度 | 数量 | 说明 |
|----------|------|------|
| 致命 | {数量} | {说明} |
| 严重 | {数量} | {说明} |
| 一般 | {数量} | {说明} |
| 轻微 | {数量} | {说明} |

## 测试覆盖率

| 指标 | 覆盖率 |
|------|--------|
| 代码覆盖率 | {百分比} |
| 行覆盖率 | {百分比} |
| 分支覆盖率 | {百分比} |

## 测试结论

{描述测试结论和建议}

## 附件

- [{测试用例文档}](path/to/test-cases.md)
- [{缺陷清单}](path/to/bugs.md)

输入参数

输出格式

{
  "docType": "changelog",
  "module": "order",
  "content": "新增支付接口",
  "title": "变更记录：新增支付接口",
  "filePath": "docs/changelog/order-新增支付接口-2026-06-25.md",
  "createdAt": "2026-06-25T10:00:00Z",
  "status": "success"
}

使用流程

创建文档

# 创建变更记录文档
docs create changelog --module order --content "新增支付接口"

# 创建方案设计Spec文档
docs create spec --module user --content "用户认证方案"

# 创建测试报告文档
docs create report --module order --content "支付功能测试报告"

初始化文档结构

# 在项目中初始化 docs 目录结构
docs init

查看文档

# 列出所有文档
docs list

# 列出变更记录文档
docs list changelog

# 查看文档内容
docs view docs/changelog/order-新增支付接口-2026-06-25.md

文档管理命令

docs init

初始化文档目录结构：

docs init

docs create

创建新文档：

docs create <docType> --module <module> --content <content> [--author <author>]

docs list

列出文档：

docs list [docType]

docs view

查看文档内容：

docs view <filePath>

docs rename

重命名文档：

docs rename <oldPath> <newPath>

docs delete

删除文档：

docs delete <filePath>

文档状态管理

最佳实践

1. 统一命名：严格遵守文件名命名规范，便于检索和管理
2. 分类存放：按类型分目录存放，保持文档结构清晰
3. 及时更新：变更发生后及时创建变更记录文档
4. 关联引用：在文档中关联相关文档，便于追溯
5. 版本控制：将 docs 目录纳入版本控制，便于历史追溯

配置要求

无需额外配置，默认在项目根目录创建 docs 目录。

扩展指南

添加新文档类型

1. 在文档目录结构中添加新目录
2. 创建对应的文档模板
3. 更新文档管理命令支持新类型
4. 更新文档说明

自定义文档模板

在项目根目录创建 .doc-manager.json 配置文件：

{
  "docTypes": {
    "changelog": {
      "directory": "changelog",
      "template": "changelog-template.md"
    },
    "spec": {
      "directory": "spec",
      "template": "spec-template.md"
    }
  }
}

参考经验：文档管理应遵循统一的目录结构和命名规范，确保文档易于检索和版本控制。