技术博客文档标准 (technical-blog-doc v1.0)

本技能提供技术博客文档的标准化模板和写作指南，基于 Spring AI 集成 DeepSeek-OCR 2 和 GLM-OCR 的文档结构。适用于编写技术教程、集成指南、项目文档等。

0. 写作原则

技术博客文档应保持严谨性和准确性，确保所有技术内容基于可靠来源。遵循以下原则可以提升文档的可信度和参考价值：

1. 准确性优先：技术描述、性能数据和模型规格应基于官方文档或权威来源，确保信息的准确性和时效性。
2. 参考官方内容：对于模型介绍、架构说明、基准测试等核心内容，优先参考官方发布的信息（如 ModelScope、HuggingFace 等平台）。
3. 提供可追溯性：在文档中适当位置引用官方链接或来源，方便读者验证信息和深入了解相关技术。

1. 何时使用

• 创建技术教程或集成指南文档
• 编写 Spring AI 或其他框架的示例项目文档
• 为开源项目编写技术博客风格的文档
• 需要标准化、结构化的技术文档
• 用户要求"写技术博客"、"创建教程文档"、"写集成指南"

2. 文档结构模板

技术博客文档应遵循以下标准章节结构：

# {技术主题}：{具体功能} {部署/实现方式}

> {简要描述项目目标和核心功能}

## 一、项目概述

### 1.1 项目定位
{项目定位描述}

### 1.2 技术栈
| 组件 | 版本 | 说明 |
|------|------|------|
| {组件1} | {版本} | {说明} |
| {组件2} | {版本} | {说明} |

### 1.3 核心功能
- ✅ {功能1}
- ✅ {功能2}
- ✅ {功能3}

---

## 二、{技术/模型}简介

> 本节内容应基于官方参考文档，确保技术描述、性能数据和模型规格的准确性。

### 2.1 {技术/模型}介绍
{详细介绍技术或模型}

### 2.2 核心特性
| 特性 | 说明 |
|------|------|
| **特性1** | 说明 |
| **特性2** | 说明 |

### 2.3 {相关配置/格式}
{技术特定的配置或格式说明}

---

## 三、性能基准

{性能数据、基准测试结果、对比图表等}

![性能图](./assets/performance-fig1.png)

---

## 四、项目结构

### 文件说明
- `{文件路径}` - {文件说明}
- `{文件路径}` - {文件说明}

---

## 五、核心配置

### 5.1 配置文件
```{语言}
{配置内容}

5.2 依赖配置

{依赖配置}

---

六、代码实现详解

6.1

{代码示例}

6.2

---

七、API 接口说明

7.1 接口列表

| 方法 | 路径 | 说明 | |------|------|------| | POST | /api/endpoint | |

7.2 请求/响应示例

{JSON示例}

---

八、部署方式

方式一：

1.

{命令}

2.

{命令}

方式二：

---

九、使用示例

9.1 cURL 调用

{curl命令示例}

9.2 客户端

{客户端代码}

9.3 客户端

{客户端代码}

---

十、运行项目

10.1 编译

{编译命令}

10.2 运行

{运行命令}

10.3 访问 API 文档

启动后访问：

---

十一、常见问题

Q1: ？

Q2: ？

---

十二、许可证

• ：

采用 开源许可证，用户在使用本项目时应遵守该许可证的相关条款。

---

参考资源

• 官方：
• ：
• 文档：
• 官网：

---

致谢

• 感谢
• 感谢
• 感谢

## 3. 章节详细说明

### 3.1 项目概述 (`## 一、项目概述`)
- **目的**：让读者快速了解项目定位、技术栈和核心功能
- **必须包含**：
  - 项目定位：一句话说明项目目标
  - 技术栈表格：组件、版本、说明
  - 核心功能列表：使用 ✅ 标记
- **示例**：参考 DeepSeek-OCR 2 文档的 1.1-1.3 节

### 3.2 技术/模型简介 (`## 二、`)
- **目的**：详细介绍使用的核心技术或模型
- **内容要求**：
  - **基于官方参考**：技术描述、性能数据和使用说明应基于官方文档（如 ModelScope、HuggingFace 等平台），确保信息的准确性
  - **引用官方来源**：在文档中明确标注信息来源链接，方便读者追溯
  - **核心特性表格**：基于官方文档提取关键特性，以表格形式清晰呈现
  - **配置和格式说明**：技术特定的配置、Prompt格式等内容应与官方文档保持一致
- **示例**：参考 DeepSeek-OCR 2 的 2.1-2.6 节或 GLM-OCR 的 2.1-2.3 节
- **验证建议**：完成文档后建议验证技术内容与官方参考来源的一致性

### 3.3 性能基准 (`## 三、性能基准`)
- **目的**：展示技术性能数据
- **建议包含**：
  - 基准测试结果
  - 性能对比图表
  - 实际场景测试数据
- **注意**：图表应保存到 `assets/` 目录并使用 Markdown 语法引用

### 3.4 代码实现详解 (`## 六、代码实现详解`)
- **目的**：详细解释关键代码实现
- **建议结构**：
  - 按组件或功能模块组织
  - 每个子节包含代码示例和说明
  - 解释设计决策和实现细节

### 3.5 使用示例 (`## 九、使用示例`)
- **目的**：提供多种使用方式示例
- **必须包含**：
  - cURL 调用示例
  - 至少一种编程语言客户端示例
  - 清晰的输入/输出说明

## 4. 写作规范

### 4.1 标题层级
- `#` 文档标题
- `##` 一级章节（一、二、三...）
- `###` 二级章节（1.1, 2.1, 3.1...）
- `####` 三级章节（如部署方式的子步骤）

### 4.2 表格格式
```markdown
| 列1 | 列2 | 列3 |
|------|------|------|
| 内容 | 内容 | 内容 |

• 使用 :--- 左对齐，:---: 居中对齐，---: 右对齐
• 表头与内容间必须有分隔行

4.3 代码块

• 标注语言类型：bash、java、python、json、xml 等
• 长代码应适当分段并添加注释
• 命令行示例使用 bash 语言标记

4.4 图片引用

• 图片保存在 assets/ 目录
• 使用 Markdown 语法：![描述](./assets/filename.png)
• 图片文件名应具描述性：{技术}-{用途}-fig{序号}.png
• 重要要求：如果官方参考文档（如 ModelScope、HuggingFace 页面）中包含图片、图表或性能可视化内容，必须在技术博客文档中引用这些图片。图片应从官方源下载并保存到 assets/ 目录，然后在文档相应位置进行引用。

4.5 链接格式

• 外部链接：[显示文本](https://example.com)
• 内部引用：[章节名](#章节id)（注意：中文标题需URL编码）

5. 质量检查清单

完成文档后检查：

• [ ] 所有章节顺序正确（一至十四）
• [ ] 技术栈表格完整且版本准确
• [ ] 核心功能列表使用 ✅ 标记
• [ ] 基于官方参考：所有技术描述、性能数据和使用说明基于官方文档，确保信息准确性
• [ ] 代码示例可运行且无语法错误
• [ ] API接口说明完整，包含请求/响应示例
• [ ] 部署步骤详细且可复现
• [ ] 使用示例涵盖多种调用方式
• [ ] 常见问题针对实际使用场景
• [ ] 许可证信息准确
• [ ] 参考资源链接有效
• [ ] 致谢部分包含相关团队/项目
• [ ] 图片引用正确且图片文件存在
• [ ] 官方参考图片：如果官方参考文档中有图片、图表或可视化内容，已在技术博客文档中引用并保存到 assets/ 目录
• [ ] 无拼写错误和语法问题

6. 基于示例的快速开始

6.1 基于 DeepSeek-OCR 2 文档

1. 复制文档结构
2. 替换技术相关内容：
   • 技术栈表格中的组件
   • 模型介绍部分的特性
   • 代码示例中的具体实现
3. 更新性能数据和图表
4. 调整API接口定义

6.2 基于 GLM-OCR 文档

1. 复制文档结构
2. 注意 GLM-OCR 特有的"官方 SDK"章节
3. 调整Prompt格式和配置说明
4. 更新性能基准部分

7. 示例文档参考

7.1 完整示例

• DeepSeek-OCR 2: /home/wandl/workspaces/workspace-partme-ai/spring-ai-examples/docs/3-Spring AI 增强扩展/6、Spring AI 增强扩展：Spring AI 集成 DeepSeek-OCR 2 本地部署.md
• GLM-OCR: /home/wandl/workspaces/workspace-partme-ai/spring-ai-examples/docs/3-Spring AI 增强扩展/7、Spring AI 增强扩展：Spring AI 集成 GLM-OCR 本地部署.md

7.2 关键差异

| 方面 | DeepSeek-OCR 2 | GLM-OCR | |------|----------------|---------| | 模型介绍 | Visual Causal Flow 架构 | GLM-V 编码器-解码器架构 | | Prompt格式 | <image>\n<\|grounding\|> 前缀 | 任务前缀 (Text Recognition:) | | 特殊章节 | 无 | 九、官方 SDK | | 性能数据 | OmniDocBench 领先 | OmniDocBench V1.5 得分 94.62 | | 许可证 | Apache 2.0 | 未指定（参考官方） |

8. 注意事项

1. 一致性：保持整篇文档的术语、格式、风格一致
2. 可复现性：确保所有命令、配置、代码可实际运行
3. 完整性：每个章节都应提供有价值的信息，避免空章节
4. 准确性：技术细节、版本号、链接等必须准确
5. 参考官方内容：技术描述、性能数据和使用说明应基于官方参考文档，确保信息的准确性和可信度
6. 渐进式：从概述到细节，逐步深入
7. 实用性：重点关注读者实际需要的信息

9. 相关技能

• full-stack-doc: 产品文档标准，适用于PRD、架构设计等
• documentation-builder: 通用文档构建和格式化规范

---

技能版本: 1.0
创建日期: 2026-04-05
最后更新: 2026-04-05
适用场景: 技术博客、教程文档、集成指南、项目文档