# Personal Doc Manager

> 个人文档管理技能，管理变更记录、方案设计Spec文档、测试报告等，统一存放在docs目录下

- Skill: `bage2014/personal-doc-manager` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bage2014/personal-doc-manager`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bage2014/personal-doc-manager/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bage2014 (https://skillmd.com/u/bage2014)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bage2014/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           # 文档说明
```

## 目录说明

| 目录 | 用途 | 说明 |
|------|------|------|
| `changelog/` | 变更记录 | 记录需求变更、代码修改、配置变更等 |
| `spec/` | 方案设计 | 技术方案、架构设计、详细设计文档 |
| `report/` | 测试报告 | 测试用例、测试结果、缺陷统计 |
| `design/` | 设计文档 | UI设计、交互设计、原型文档 |
| `api/` | API文档 | 接口定义、API规范、接口变更 |
| `database/` | 数据库设计 | 表结构设计、数据迁移方案 |

## 文件名命名规范

### 格式

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

### 示例

| 类型 | 文件名示例 |
|------|-----------|
| 变更记录 | `order-新增支付接口-2026-06-25.md` |
| 方案设计 | `user-用户认证方案-2026-06-25.md` |
| 测试报告 | `order-支付功能测试报告-2026-06-25.md` |
| API文档 | `order-订单接口v2-2026-06-25.md` |
| 数据库设计 | `user-用户表结构设计-2026-06-25.md` |

### 规则

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

## 文档模板

### 变更记录文档模板

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

## 基本信息

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

## 变更原因

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

## 变更内容

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

## 影响范围

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

## 风险评估

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

## 实施计划

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

## 相关文档

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

### 方案设计Spec文档模板

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

## 基本信息

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

## 需求背景

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

## 技术方案

### 架构设计

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

### 技术选型

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

### 核心设计

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

## 接口设计

### 新增接口

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

### 接口变更

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

## 数据库设计

### 新增表

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

### 字段变更

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

## 部署方案

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

## 验收标准

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

## 参考文档

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

### 测试报告文档模板

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

## 基本信息

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

## 测试范围

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

## 测试用例统计

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

## 测试结果详情

### 通过用例

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

### 失败用例

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

## 缺陷统计

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

## 测试覆盖率

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

## 测试结论

{描述测试结论和建议}

## 附件

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

## 输入参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| docType | String | 是 | 文档类型：changelog/spec/report/design/api/database |
| module | String | 是 | 模块名称 |
| content | String | 是 | 内容描述 |
| title | String | 否 | 文档标题，默认根据模块和内容生成 |
| author | String | 否 | 作者名称 |
| projectPath | String | 否 | 项目路径，默认当前目录 |

## 输出格式

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

## 使用流程

### 创建文档

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

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

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

### 初始化文档结构

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

### 查看文档

```bash
# 列出所有文档
docs list

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

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

## 文档管理命令

### docs init

初始化文档目录结构：

```bash
docs init
```

### docs create

创建新文档：

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

### docs list

列出文档：

```bash
docs list [docType]
```

### docs view

查看文档内容：

```bash
docs view <filePath>
```

### docs rename

重命名文档：

```bash
docs rename <oldPath> <newPath>
```

### docs delete

删除文档：

```bash
docs delete <filePath>
```

## 文档状态管理

| 状态 | 说明 |
|------|------|
| 草稿 | 文档正在编写中 |
| 已审核 | 文档已通过审核 |
| 已实施 | 文档内容已开始实施 |
| 已完成 | 文档内容已实施完成 |
| 已废弃 | 文档已不再使用 |

## 最佳实践

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

## 配置要求

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

## 扩展指南

### 添加新文档类型

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

### 自定义文档模板

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

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

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