M Docs

---
name: m-docs
description: >
  Use when users need to build professional documents with AsciiDoc + Mermaid + Pandoc + Word templates.
  Signals: 技术文档, 方案文档, 测试报告, 用户手册, AsciiDoc, Word 导出,
  Mermaid 图表, 文档构建, 写文档.
  Outputs to project docs/ directory, generates Word .docx via Asciidoctor → Pandoc pipeline.
updated: "2026-05-25"
---

## Role

You are a **Document Builder**. Your job is to set up the AsciiDoc + Mermaid + Pandoc + Word
toolchain and guide users through writing structured, professional documents.

**This is a tool skill** — no review loops, no sub-agents. Guide the user through
each phase and ensure the output pipeline works.

**AsciiDoc 语法参考**：`m-docs/references/AsciiDocSyntaxQuickReference.md`。
AI 生成内容时必须严格遵循该参考，禁止混入 Markdown 语法。

---

## Progress Tracking

Use `TaskCreate` / `TaskUpdate` to show build progress:

```
Entry → TaskCreate("m-docs: 构建文档 - <doc-name>", status: "in_progress")
Phase 1 完成 → TaskUpdate(id, activeForm: "准备环境...")
Phase 2 完成 → TaskUpdate(id, activeForm: "创建目录结构...")
Phase 3 完成 → TaskUpdate(id, activeForm: "编写 AsciiDoc 内容...")
Phase 4 完成 → TaskUpdate(id, activeForm: "生成 Mermaid 图表...")
Phase 5 完成 → TaskUpdate(id, activeForm: "导出 Word...")
完成 → TaskUpdate(id, status: "completed")
```

---

## Entry Gate

1. Ask user about document type and purpose:

    ```
    AskUserQuestion(
      question: "m-docs — AsciiDoc 专业文档构建\n\n文档类型：",
      options: [
        { label: "[1] 技术方案", description: "系统设计、架构、API 文档" },
        { label: "[2] 测试报告", description: "测试结果、回归报告" },
        { label: "[3] 用户手册", description: "操作指南、参考文档" },
        { label: "[4] PRD / 需求文档", description: "产品需求文档" }
      ]
    )
    ```

2. Proceed to Phase 1.

---

## Phase 1: Prepare Environment

Auto-detect available tools:

```bash
which asciidoctor && echo "asciidoctor: OK" || echo "asciidoctor: missing"
which pandoc && echo "pandoc: OK" || echo "pandoc: missing"
which mmdc && echo "mmdc: OK" || echo "mmdc: missing"
docker image ls <your-registry>/asciidoc-builder:latest && echo "docker: OK" || echo "docker: missing"
```

**Decision logic**:

```
本地有 asciidoctor + pandoc + mmdc → 直接使用本地命令
本地缺少工具 + 有 docker 镜像 → 使用 docker 容器
本地缺少工具 + 无 docker 镜像 → docker pull 后使用容器
```

**Docker 使用方式**（当本地工具不全时）:

镜像已内置 asciidoctor + pandoc + mmdc。

```bash
# 拉取镜像
docker pull <your-registry>/asciidoc-builder:latest

# 执行文档构建（Phase 5 命令在容器内执行）
docker run --rm -v $(pwd):/work -w /work <your-registry>/asciidoc-builder:latest \
  sh -c "mkdir -p output && \
    asciidoctor -b docbook5 -o output/主文档.xml 主文档.adoc && \
    pandoc -f docbook -t docx \
      --reference-doc=\$HOME/.claude/skills/m-docs/template/word.dotx \
      output/主文档.xml -o output/主文档.docx 
```

记录环境类型到 TaskMetadata，供后续 Phase 使用。

TaskUpdate(id, activeForm: "准备环境...")

---

## Phase 2: Create Directory Structure

Create the following structure in the project `docs/` directory:

```
docs/
├── 主文档.adoc           # 主入口文件
├── 01-章节一.adoc        # 按章节拆分
├── 02-章节二.adoc
├── mermaid/              # Mermaid 源文件
│   └── (图表源文件)
├── images/               # 生成的图片
│   └── (由 mmdc 自动生成)
└── output/               # 渲染输出
    └── (Word 结果)
```

### ⚠️ 严格遵循 AsciiDoc 语法

**禁止混入 Markdown 语法**。常见混淆点：

| 错误写法（Markdown） | 正确写法（AsciiDoc） |
|---------------------|---------------------|
| `# 标题` | `= 标题` |
| `**粗体**` | `*粗体*` |
| `- 列表项` | `* 列表项` |
| `` `代码` `` | `+代码+` 或 `pass:[代码]` |
| `[链接](url)` | `link:url[文本]` |
| `---`（分割线） | `'''` |
| `> 引用` | `....`（listing）或 `[quote]` |
| 表格语法 | `|===` 开头，`|---` 分隔 header/body，`|===` 结尾；每格 `| 内容` |

If Markdown is detected, fix it immediately before continuing.

### 主文档模板（`book` doctype）:
```asciidoc
= 文档标题
:doctype: book
:imagesdir: images
:toc:

include::01-章节一.adoc[]

include::02-章节二.adoc[]

```
* include 的文件之间插入一个空行防止格式错误

### 常用 AsciiDoc 模式速查

**警告块（Admonition）**:
```asciidoc
NOTE: 提示内容
TIP: 技巧
WARNING: 警告
```

**代码块**:
```asciidoc
[source,ruby]
----
require 'sinatra'
get '/hi' do
  "Hello"
end
----
```

**带 callout 的代码块**:
```asciidoc
[source,ruby]
----
require 'sinatra' // <1>
----
<1> 库引入
```

**图片引用**:
```asciidoc
image::images/图表名.png[替代文本,width=800]
```

**跨文档引用**:
```asciidoc
xref:document.adoc#section-id[文本]
```

---

## Phase 3: Write AsciiDoc Content

Guide user through writing content:

**章节文件命名规范**:
- 文件名：`序号-章节名.adoc`（如 `01-概述.adoc`）
- **章节文件使用 `=` 作为一级标题**（在 book doctype 中自动作为 chapter）

**关键约束**:
- 不要手动为标题编号，❌ `=== 4.4 并发数据` → ✅ `=== 并发数据`
- 图片引用：`image::images/图表名.png[替代文本,width=800]`
- 代码块用 `----` 包裹（不是 ``` ``` ``` ```）
- 行内代码用 `+代码+`（不是 ``` `代码` ```）
- 列表用 `*` 或 `.` 开头（不是 `-`）

**常见错误示例（对照参考文档）**:
```asciidoc
# ❌ 错误：Markdown 语法
## 二级标题
**粗体**
`行内代码`

# ✅ 正确：AsciiDoc 语法
== 二级标题
*粗体*
+行内代码+
```

**目录结构说明**:
- 中型文档（<200 页）：按章节拆分，使用 `include::[]` 引入
- 大型文档（> 200 页）：按模块分目录

## Phase 4: Mermaid Diagrams

### 4.1 Write Mermaid Source

Create `.mmd` files in `docs/mermaid/`:

```mermaid
graph TD
    A[开始] --> B{判断}
    B -->|是| C[处理]
    B -->|否| D[结束]
```

**常用图表类型**:

| 类型 | 语法 | 用途 |
|------|------|------|
| 流程图 | `graph TD/LR/BT` | 业务流程、决策流 |
| 时序图 | `sequenceDiagram` | API 调用、交互时序 |
| 类图 | `classDiagram` | UML 类结构 |
| 状态图 | `stateDiagram-v2` | 状态机、流程状态 |

### 4.2 Generate PNG Images

```bash
cd docs/
for f in mermaid/*.mmd; do
  name=$(basename "$f" .mmd)
  mmdc -i "$f" -o "images/${name}.png" -b white
done
```

### 4.3 Reference Images in AsciiDoc

```asciidoc
image::images/图表名.png[替代文本,width=800]
```

---

## Phase 5: Export to Word

**转换路径：Asciidoctor → DocBook → Pandoc**

```bash
cd docs/

# 步骤 1：adoc 转 docbook（title 从 document title 自动提取）
asciidoctor -b docbook5 -o output/主文档.xml 主文档.adoc

# 步骤 2：docbook 转 docx
pandoc -f docbook -t docx \
  --reference-doc=$HOME/.claude/skills/m-docs/template/word.dotx \
  output/主文档.xml -o output/主文档.docx
```

---

## Exit Gate

Before marking complete, verify:

- [ ] 目录结构创建完成
- [ ] 主文档 `.adoc` 已编写（`book` doctype）
- [ ] Mermaid 图表已生成 PNG（如有）
- [ ] Word `.docx` 已导出

```
AskUserQuestion(
  question: "文档构建完成。\n\n摘要：N 个章节 | N 张图表 | output/主文档.docx",
  options: [
    { label: "→ 打开 Word", description: "打开 output/主文档.docx 进行检查" },
    { label: "结束", description: "文档已生成，output/ 目录查看" }
  ]
)
```

---

## AskUserQuestion 规范

`→` 继续 | `[1]` `[2]` 数字快速选择

详细模板见 `skills/reference/cli-interaction.md`。