102 lines
3.1 KiB
Markdown
102 lines
3.1 KiB
Markdown
---
|
||
name: doc
|
||
description: 渐进式文档生成器。首次只写精炼梗概（≤300字），后续通过迭代不断完善。
|
||
---
|
||
|
||
# Doc - 渐进式文档生成器
|
||
|
||
> **核心理念**：文档是缝缝补补长出来的，不是一步到位写出来的。首次只写最重要的梗概，后续通过讨论和迭代逐步完善。
|
||
|
||
当用户调用 `doc` skill、`$doc`，或自然语言要求“用 doc 写文档”时，执行以下步骤：
|
||
|
||
## 1. 理解需求
|
||
|
||
如果用户提供了参数，使用该描述。否则询问要写什么文档。
|
||
|
||
快速确认（已知的不重复问）：
|
||
|
||
| 项目 | 默认值 |
|
||
|------|--------|
|
||
| 文档主题 | 用户指令 |
|
||
| 输出路径 | 询问用户 |
|
||
| 作者署名 | 询问用户 |
|
||
|
||
简短讨论文档边界：列出你理解的覆盖范围，标注不确定的点，让用户拍板。
|
||
|
||
> 你是执笔人，不是决策者。"写什么、不写什么"由用户决定。
|
||
|
||
## 2. 快速调研
|
||
|
||
聚焦调研，不求面面俱到：
|
||
- 扫描相关代码和现有文档
|
||
- 提取核心概念、关键接口、主要数据流
|
||
- 了解项目现有文档风格（命名、格式）
|
||
|
||
调研完成后，用 2-3 句话告诉用户你发现了什么，有什么存疑的点。**不需要正式的大纲确认环节**，直接写梗概，快速拿到反馈比完美大纲更重要。
|
||
|
||
## 3. 生成梗概
|
||
|
||
### 3.1 写作原则
|
||
|
||
**首次写作（默认模式）**：
|
||
- **言简意赅**，建议控制在 300 字以内
|
||
- 只写最重要的骨架：是什么、为什么、怎么用
|
||
- 留白是刻意的，后续迭代会填充细节
|
||
- 不需要面面俱到，抓住核心价值
|
||
|
||
**迭代补充**（用户再次调用 `doc` 指向同一文件时）：
|
||
- 读取现有内容，在此基础上增量补充
|
||
- 递增版本号，更新 `updated` 日期
|
||
- 每次迭代聚焦一个方面，不要一次补太多
|
||
|
||
### 3.2 文档头部
|
||
|
||
```markdown
|
||
---
|
||
title: {文档标题}
|
||
version: v1.0
|
||
created: {YYYY-MM-DD}
|
||
updated: {YYYY-MM-DD}
|
||
author: {作者署名}
|
||
---
|
||
```
|
||
|
||
### 3.3 内容要求
|
||
|
||
- **准确**：基于实际代码，不编造
|
||
- **精炼**：一句话能说清的不用两句
|
||
- **实用**：面向读者，提供可操作的信息
|
||
- 善用表格、代码块、ASCII 图示（但首次不强求）
|
||
|
||
## 4. 保存并输出
|
||
|
||
保存到用户指定路径。如果文件已存在，先询问是覆盖还是增量更新。
|
||
|
||
输出摘要：
|
||
|
||
```text
|
||
文档: {标题} | 版本: v1.0 | 路径: {path}
|
||
字数: ~{N}字（首版梗概）
|
||
|
||
后续可以通过 $doc 继续补充完善。
|
||
主人，用不用我沉淀 or git 提交？
|
||
```
|
||
|
||
## 工作流总览
|
||
|
||
```text
|
||
$doc <指令>
|
||
│
|
||
├── 1. 理解需求（简短确认主题、路径、署名）
|
||
├── 2. 快速调研（聚焦核心，不求全面）
|
||
├── 3. 生成梗概（≤300字，抓骨架）
|
||
└── 4. 保存输出（鼓励后续迭代）
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
- **少即是多**：首版宁短勿长，300 字是指导建议而非硬限制
|
||
- **鼓励迭代**：每次 `doc` 都是一次对话机会，文档在讨论中成长
|
||
- **不做代码改动**：本 skill 只生成文档
|
||
- **风格一致**：与项目已有文档风格保持一致
|