# ✍️ 文章生成模块

> 从属于 AHKB-CPS 统一系统。基于知识库或手动输入，生成多种格式的专业文档。
> 🔴 **交互规则**：所有选项必须用数字编号展示，用户输入数字选择，**严禁使用 AskUserQuestion 工具**。

## 模块概述

生成多种格式的专业文档：Markdown、Word、PDF、HTML、Excel、微信公众号、小红书文案、纯文本、标准论文等。基于知识库或自由创作。

**输出能力：**

- **10 种输出格式** — Markdown、Word (.docx)、PDF、HTML、Excel (.xlsx)、微信公众号、小红书文案、纯文本 (.txt)、标准论文、自由格式
- **KB 驱动 + 独立创作** — 可从知识库检索素材，也可完全自由写作
- **模板精准生成** — 论文按学术规范，公众号按移动端排版，小红书按3:4图文风
- **自包含交付** — 文件可直接使用、拷贝、发送

> 🔴 **路径约定**：本文中所有路径均相对于 AHKB-CPS 技能目录（即 `{skill_dir}`），而非工作空间。

---

## 模块主菜单

```
═══════════════════════════════════════════════════════
        AHKB-CPS：文章生成模块菜单
═══════════════════════════════════════════════════════
  1. 🧠 基于知识库生成文章 — AI 检索知识库或你指定主题+KB补充，按指定格式生成
  2. 📄 依据指定的文档生成文章 — 从知识库已入库文档中提取内容，按格式重组
  3. ✍️ 独立生成文章       — 不依赖知识库，仅按你的输入自由生成
  e. ↩️ 返回主菜单          — 返回 AHKB-CPS 统一主菜单
═══════════════════════════════════════════════════════
请回复数字 1~3 或 e 选择操作：
```

## 菜单循环规则

- 操作完成后**返回模块主菜单**
- 仅当用户选择 `e` 时才返回 AHKB-CPS 统一主菜单
- 每次返回模块主菜单时，提示用户还可使用其他 AHKB-CPS 模块

---

# 菜单 1 — 🧠 基于知识库生成文章

## 检测知识库并选择工作模式

检查 `知识元/` 目录下是否有 ≥1 个 `.md` 文件。

**情况 A：检测到知识库（N 个知识元）** → 向用户展示：

**检测到知识库（N 个知识元），选择生成模式：**

1. 🧠 知识库驱动生成 — AI根据你的自然语言描述自动检索知识库，提取内容生成文章
2. ✏️ 手动输入制作 — 你指定主题，AI先检索知识库补充素材，再逐步配置生成

> 🔴 **两种模式都会检索知识库。** 如需完全不依赖知识库的独立生成，请使用菜单第 3 项。
>
> 也可以直接说其他要求或选项

**情况 B：无知识库** → 告知用户未检测到知识库，推荐使用菜单第 3 项「独立生成文章」。

---

## 🧠 知识库驱动模式

### Step K1 — 对话描述需求 + AI 自动检索

**(a) 用户描述需求**

**问：你想写什么主题的文章？请用一两句话描述。**

**(b) AI 自动检索知识库**

```bash
python {skill_dir}/core/kb2slides.py search --workspace "<Vault路径>" --query "用户描述的关键词" --top 15
```

**(c) 展示检索结果，确认方向**

### Step K2 — 确认素材

**以上述检索到的资料为基础写作？**

1. ✅ 确认，基于这些资料
2. 🔍 缩小范围 — 输入更具体的关键词重新搜索
3. ✏️ 我来说明 — 用户直接说明想要哪些内容

> 也可以直接说其他要求或选项

### Step K3 — 进入配置流程

确认素材后，进入下方「🔄 通用配置流程」。

---

## ✏️ 手动模式 & 配置流程

### Step M1 — 用户指定主题

**问：你想写什么主题的文章？请用一两句话描述。**

### Step M2 — 检索知识库补充素材

```bash
python {skill_dir}/core/kb2slides.py search --workspace "<Vault路径>" --query "用户输入的主题" --top 10
```

> 🔴 **知识库有料就用，没料不勉强。**

---

## 🔄 通用配置流程（所有菜单共用）

### Step C1 — 输出格式（核心步骤）

**请选择输出格式（输入数字）：**

1. 📄 Word (`.docx`) — 正式文档，可编辑，适合商务场景
2. 📑 PDF (`.pdf`) — 最终交付格式，不可编辑
3. 📝 Markdown (`.md`) — 通用标记文档，适合技术文档和笔记
4. 🌐 HTML (`.html`) — 网页格式，自包含可独立打开
5. 📊 Excel (`.xlsx`) — 结构化数据表格
6. 📱 微信公众号 — 移动端阅读优化排版
7. 📕 小红书文案 — 3:4卡片图文风
8. 📝 纯文本 (`.txt`) — 最简格式
9. 🎓 标准论文 — 摘要/引言/方法/结果/讨论/参考文献
10. ✏️ 自由格式 — AI 自主决定

> 也可以直接说其他要求或选项

### Step C2 — 内容要求

> 🔴 **以下选项决定文章的最终形态，AI 必须严格按用户选择执行，不得自行为用户降级或升级。**

**A. 文字篇幅**（选择后严格执行对应字数范围）

| 选项 | 名称 | 字数范围 | 说明 |
|:----:|------|:--------:|------|
| 1 | 🪶 短文 | 500-1000字 | 精炼简短 |
| 2 | 📄 中等 | 1000-3000字 | 标准篇幅 |
| 3 | 📚 长篇 | 3000-8000字 | 深入展开 |
| 4 | 📖 巨著 | 8000字以上 | 全面论述 |

> 🔴 **字数对照表**：用户选 1 → 500~1000字 / 选 2 → 1000~3000字 / 选 3 → 3000~8000字 / 选 4 → ≥8000字。
> 🔴 **选4时必须写到8000字以上，严禁按选3的标准处理。**

**B. 写作风格**
1. 🏢 商务正式 2. 💬 轻松对话 3. 📰 新闻报道 4. 🎓 学术严谨 5. 📱 社交媒体 6. 🎨 文学散文 7. 😂 幽默搞笑

**C. 图片**
1. 🖼️ 配图（默认） 2. 🖼️ 多图 3. 🖼️ 无图

> 🔴 **配图规则：** 图片使用 `<img>` 标签直接嵌入或 python-docx/pymupdf 嵌入。使用 `img://文件名` 占位符语法引用知识库图片。**绝不手动转 base64。**
> - **网络兜底**：WebFetch/WebSearch 下载图片失败时，**不阻塞生成**——直接用知识库已有图片

### Step C3 — 确定文章题目

> 🔴 **必须在此步骤确定文章题目，不得跳过。**

向用户展示以下选项：

**请确定文章题目：**

1. ✏️ 我来指定 — 用户直接输入题目
2. 💡 AI 推荐 — AI 根据主题和素材推荐 2~3 个题目供用户选择
3. ➡️ 暂不确定 — 先生成内容，最后由 AI 根据内容拟定题目

> 也可以直接说其他要求或选项

### Step C4 — 补充要求

**还有什么补充要求？**
1. ➡️ 没有，直接下一步 2. ✏️ 有，我来输入

### Step C5 — 确认

展示配置摘要（必须包含题目），确认后开始生成。

---

## 生成与交付

### 🔴 字体规则（必须遵守）

**必须使用本地电脑具有的中文字体，优先选择中文命名的字体。** 不要使用日文/韩文等非中文字体。

> 🔴 **严格按以下优先级选择字体：中文名称为首选的字体，它们在 Windows 系统中对中文支持最好。**

**推荐字体（按优先级排序）：**

| 优先级 | 中文名 | 英文字体名 | 适用 |
|--------|--------|----------|------|
| 1 | **黑体** | SimHei | 标题/强调 |
| 2 | **宋体** | SimSun | 正文/正式文档 |
| 3 | **楷体** | KaiTi | 引言/引文 |
| 4 | **仿宋** | FangSong | 注释/副标题 |
| 5 | **微软雅黑** | Microsoft YaHei | 屏幕阅读/正文 |
| 6 | **幼圆** | YouYuan | 轻松/儿童内容 |
| 7 | **等线** | DengXian | 正文/商务文档 |
| 8 | 其他中文命名字体 | 如 方正XXX | 根据具体需要 |

**使用方式：**
- **Word/docx**：python-docx 设置 `run.font.name = '宋体'`，中文字体名直接可用
- **PDF**：pymupdf (fitz) 设置 `page.insert_text(fontname='china-s')` 或指定中文字体文件路径
- **HTML**：CSS 写 `font-family: 'SimSun', '宋体', serif`（第一个备选用英文字体名，第二个用中文名）
- **Excel/xlsx**：openpyxl 设置 `Font(name='宋体')`

**禁止：**
- ❌ 日文字体（MS Gothic、MS Mincho、Yu Gothic、Meiryo 等）—— 这些字体的中文显示不佳
- ❌ 装饰性字体、手写体、英文花体
- ❌ 系统可能缺少的冷门字体

### 生成流程

```bash
# 1. AI 撰写文章内容
# 2. 写入临时文件（如 临时工作文件/_article.md）
# 3. 根据格式转换为目标格式（需要时）
# 4. 输出到 产品成果/ 目录
# 5. 自动打开生成的文件
python -c "import webbrowser; webbrowser.open('产品成果/标题.xxx')"
```

### 格式对应的生成方式

| 格式 | 生成方式 |
|------|---------|
| `.md` | AI 直接写 → `产品成果/标题.md` |
| `.docx` | AI 写内容 → python-docx 构建，图片用 `add_picture()` 嵌入。页脚加页码 |
| `.pdf` | AI 写内容并按页分段 → pymupdf (fitz) 逐页构建。**禁止用 `insert_html()`** |
| `.html` | AI 直接写自包含 HTML（图片用 `<img>` 内嵌 base64） |
| `.xlsx` | AI 写数据 → openpyxl 构建 |
| 微信公众号 | AI 写 HTML（微信排版规范） |
| 小红书文案 | AI 写 HTML（3:4图文风） |
| `.txt` | AI 直接写 |
| 标准论文 | AI 按论文模板写 |
| 自由格式 | AI 自主选择 |

> 📘 **PDF 分页构建参考：** 每页 A4（595×842），Y 坐标每行 ≈ 25px。**绝对不要用 `insert_html`。**

### 生成完成后提示

> ✅ 文章已生成并自动打开！
> ✅ 文件位于 产品成果/ 目录下，可直接拷贝、发送

完成后**返回模块主菜单**。

---

# 菜单 2 — 📄 依据指定的文档生成文章

## Step A — 文档选择

```bash
python {skill_dir}/core/kb2slides.py list-docs --workspace "<Vault路径>"
```

向用户展示编号列表（支持多选，如 1,3）。

## Step B — 获取文档内容

```bash
python {skill_dir}/core/kb2slides.py read-doc --workspace "<Vault路径>" --doc "文档路径"
```

## Step C — 进入通用配置流程

进入「🔄 通用配置流程」（Step C1-C5）。

---

# 菜单 3 — ✍️ 独立生成文章

> 🔴 **菜单 3 与知识库完全无关。** 不做知识库检测，不做知识库检索。

```
指定主题 → 通用配置流程(C1-C5) → 确认 → 生成 → 返回模块主菜单
```

---

# 返回

**用户选择 `e` 时：**

1. 感谢用户使用文章生成模块
2. **返回 AHKB-CPS 统一主菜单**
