doc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Doc Skill

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Generate and validate documentation for any project.

你必须执行此工作流，而非仅对其进行描述。

为任意项目生成并验证文档。

Execution Steps

执行步骤

Given

/doc [command] [target]

当收到指令

/doc [command] [target]

时：

Step 1: Detect Project Type

步骤1：检测项目类型

bash

undefined

bash

undefined

Check for indicators

检查项目标识

ls package.json pyproject.toml go.mod Cargo.toml 2>/dev/null

Check for existing docs

检查现有文档

ls -d docs/ doc/ documentation/ 2>/dev/null


Classify as:
- **CODING**: Has source code, needs API docs
- **INFORMATIONAL**: Primarily documentation (wiki, knowledge base)
- **OPS**: Infrastructure, deployment, runbooks

ls -d docs/ doc/ documentation/ 2>/dev/null


将项目分类为：
- **编码类（CODING）**：包含源代码，需要API文档
- **信息类（INFORMATIONAL）**：以文档为主（维基、知识库）
- **运维类（OPS）**：基础设施、部署、运行手册

Step 2: Execute Command

步骤2：执行指令

discover - Find undocumented features:

bash

undefined

discover - 查找未文档化的功能：

bash

undefined

Find public functions without docstrings (Python)

查找无文档字符串的公共函数（Python）

grep -r "^def " --include="*.py" | grep -v '"""' | head -20

Find exported functions without comments (Go)

查找无注释的导出函数（Go）

grep -r "^func [A-Z]" --include="*.go" | head -20


**coverage** - Check documentation coverage:
```bash

grep -r "^func [A-Z]" --include="*.go" | head -20


**coverage** - 检查文档覆盖率：
```bash

Count documented vs undocumented

统计已文档化与未文档化的数量

TOTAL=$(grep -r "^def |^func |^class " --include=".py" --include=".go" | wc -l) DOCUMENTED=$(grep -r '"""' --include="*.py" | wc -l) echo "Coverage: $DOCUMENTED / $TOTAL"


**gen [feature]** - Generate documentation:
1. Read the code for the feature
2. Understand what it does
3. Generate appropriate documentation
4. Write to docs/ directory

**all** - Update all documentation:
1. Run discover to find gaps
2. Generate docs for each undocumented feature
3. Validate existing docs are current

TOTAL=$(grep -r "^def |^func |^class " --include=".py" --include=".go" | wc -l) DOCUMENTED=$(grep -r '"""' --include="*.py" | wc -l) echo "Coverage: $DOCUMENTED / $TOTAL"


**gen [feature]** - 生成文档：
1. 读取该功能的代码
2. 理解其功能
3. 生成合适的文档
4. 写入docs/目录

**all** - 更新所有文档：
1. 运行discover查找文档缺口
2. 为每个未文档化的功能生成文档
3. 验证现有文档是否为最新版本

Step 3: Generate Documentation

步骤3：生成文档

When generating docs, include:

For Functions/Methods:

markdown

undefined

生成文档时需包含以下内容：

针对函数/方法：

markdown

undefined

function_name

Purpose: What it does

Parameters:

```
param1
```
(type): Description
```
param2
```
(type): Description

Returns: What it returns

Example:

python

result = function_name(arg1, arg2)

Notes: Any important caveats


**For Classes:**
```markdown

用途： 功能说明

参数：

```
param1
```
(类型)：参数描述
```
param2
```
(类型)：参数描述

返回值： 返回内容说明

示例：

python

result = function_name(arg1, arg2)

注意事项： 任何重要的警告信息


**针对类：**
```markdown

ClassName

Purpose: What this class represents

Attributes:

```
attr1
```
: Description
```
attr2
```
: Description

Methods:

```
method1()
```
: What it does
```
method2()
```
: What it does

Usage:

python

obj = ClassName()
obj.method1()

undefined

用途： 该类的作用

属性：

```
attr1
```
：属性描述
```
attr2
```
：属性描述

方法：

```
method1()
```
：方法功能
```
method2()
```
：方法功能

用法示例：

python

obj = ClassName()
obj.method1()

undefined

Step 4: Create Code-Map (if requested)

步骤4：创建代码映射图（若有请求）

Write to:

docs/code-map/

markdown

undefined

写入路径：

docs/code-map/

markdown

undefined

Code Map: <Project>

代码映射图：<项目名称>

Overview

概述

<High-level architecture>

<高层级架构说明>

Directory Structure

目录结构

src/
├── module1/     # Purpose
├── module2/     # Purpose
└── utils/       # Shared utilities

src/
├── module1/     # 模块用途
├── module2/     # 模块用途
└── utils/       # 共享工具

Key Components

核心组件

Module 1

模块1

Purpose: What it does
Entry point:
```
main.py
```
Key files:
```
handler.py
```
,
```
models.py
```

用途： 模块功能
入口文件：
```
main.py
```
关键文件：
```
handler.py
```
,
```
models.py
```

Module 2

模块2

...

Data Flow

数据流

<系统内的数据流转方式>

Dependencies

依赖项

<External dependencies and why> ```

<外部依赖及其作用>

undefined

Step 5: Validate Documentation

步骤5：验证文档

Check for:

Out-of-date docs (code changed, docs didn't)
Missing sections (no examples, no parameters)
Broken links
Inconsistent formatting

检查以下内容：

过时文档（代码已变更但文档未更新）
缺失章节（无示例、无参数说明）
无效链接
格式不一致

Step 6: Write Report

步骤6：撰写报告

Write to:

.agents/doc/YYYY-MM-DD-<target>.md

markdown

undefined

写入路径：

.agents/doc/YYYY-MM-DD-<target>.md

markdown

undefined

Documentation Report: <Target>

文档报告：<目标对象>

Date: YYYY-MM-DD Project Type: <CODING/INFORMATIONAL/OPS>

日期： YYYY-MM-DD 项目类型： <CODING/INFORMATIONAL/OPS>

Coverage

覆盖率

Total documentable items: <count>
Documented: <count>
Coverage: <percentage>%

可文档化项总数：<数量>
已文档化项：<数量>
覆盖率：<百分比>%

Generated

已生成文档

<list of docs generated>

<生成的文档列表>

Gaps Found

发现的文档缺口

<undocumented item 1>
<undocumented item 2>

<未文档化项1>
<未文档化项2>

Validation Issues

验证问题

<issue 1>
<issue 2>

<问题1>
<问题2>

Next Steps

后续步骤

Document remaining gaps
Fix validation issues

undefined

填补剩余文档缺口
修复验证发现的问题

undefined

Step 7: Report to User

步骤7：向用户反馈

Tell the user:

Documentation coverage percentage
Docs generated/updated
Gaps remaining
Location of report

告知用户以下信息：

文档覆盖率百分比
已生成/更新的文档
剩余的文档缺口
报告的存放位置

Key Rules

核心规则

Detect project type first - approach varies
Generate meaningful docs - not just stubs
Include examples - always show usage
Validate existing - docs can go stale
Write the report - track coverage over time

先检测项目类型 - 不同类型项目采用不同处理方式
生成有意义的文档 - 不只是生成占位符
包含示例 - 始终展示使用方法
验证现有文档 - 文档可能会过时
撰写报告 - 跟踪覆盖率变化

Commands Summary

指令汇总

Command	Action
`discover`	Find undocumented features
`coverage`	Check documentation coverage
`gen [feature]`	Generate docs for specific feature
`all`	Update all documentation
`validate`	Check docs match code

指令	操作
`discover`	查找未文档化的功能
`coverage`	检查文档覆盖率
`gen [feature]`	为特定功能生成文档
`all`	更新所有文档
`validate`	检查文档与代码是否匹配