# 00-写作规范




## 目录



- [一、文档结构规范](#一文档结构规范)

- [二、格式规范](#二格式规范)

- [三、源码引用规范](#三源码引用规范)

- [四、术语规范](#四术语规范)

- [五、示例模板](#五示例模板)




## 一、文档结构规范



### 1.1 文件命名



- 使用 `序号-文档名称.md` 格式

- 序号使用两位数（01, 02, 03...）

- 文档名称使用中文，简洁明了



**示例**:

- ✅ `01-项目总览.md`

- ✅ `03-技能系统技术文档.md`

- ❌ `1.项目总览.md`（序号应为两位数）

- ❌ `skill-system.md`（应使用中文）



### 1.2 文档头部



每个文档必须以以下格式开头：



```markdown

# 文档标题





## 目录



- [一、概述](#一概述)

- [二、核心概念](#二核心概念)

- [三、实现细节](#三实现细节)

- [四、使用示例](#四使用示例)

- [五、API参考](#五api参考)

- [六、最佳实践](#六最佳实践)




## 导航



**上一篇**：[00-写作规范](00-写作规范.md)  

**下一篇**：[02-EvoFlow 架构分析](02-EvoFlow%20架构分析.md)



> **文档版本**：v2.0  

> **最后更新**：2026-03-30  

> **作者**：银泰



📚 返回总览：[EvoFlow技术总览](01-EvoFlow技术总览.md)

```



### 1.3 章节结构



| 章节 | 必需 | 内容说明 |

|------|------|---------|

| 一、概述 | ✅ | 一句话理解 + 架构位置 |

| 二、核心概念 | ✅ | 关键术语、数据模型、架构图 |

| 三、实现细节 | ✅ | 源码分析、关键逻辑 |

| 四、使用示例 | ⚪ | 使用场景和示例 |

| 五、API参考 | ⚪ | API 接口说明 |

| 六、最佳实践 | ⚪ | 建议和注意事项 |

| 附录 | ⚪ | 相关链接、术语表 |




## 二、格式规范



### 2.1 语言



- **主语言**: 中文

- **术语标注**: 首次出现的关键术语后标注英文原文

- **代码**: 保持英文，注释可用中文



**示例**:

```markdown

## 技能系统（Skills System）



技能（Skill）是 EvoFlow 中用于封装领域知识的可插拔模块...

```



### 2.2 标题层级



- 一级标题 `#`: 文档标题（仅一个）

- 二级标题 `##`: 主要章节（一、二、三...）

- 三级标题 `###`: 章节内小节

- 四级标题 `####`: 具体内容点



### 2.3 列表和表格



**无序列表**: 用于列举特性、步骤等

```markdown

- 特性1

- 特性2

  - 子特性

```



**有序列表**: 用于步骤说明

```markdown

1. 第一步

2. 第二步

3. 第三步

```



**表格**: 用于对比、参数说明

```markdown

| 字段 | 类型 | 说明 |

|------|------|------|

| name | string | 名称 |

```



### 2.4 代码块



- 使用围栏式代码块（三个反引号）

- 标注语言类型

- 关键代码需加注释



**示例**:

```markdown

```python

# 加载所有技能

skills = load_skills(enabled_only=True)

```

```




## 三、源码引用规范



### 3.1 引用格式



每个源码引用必须包含：

1. **源码位置**: 文件路径（相对 backend 目录）

2. **逻辑说明**: 简述该代码的功能

3. **代码片段**: 关键代码



**标准格式**:

```markdown

**源码位置**: `backend/packages/harness/evoflow/skills/types.py#L22-L48`



**逻辑说明**: `Skill` 类定义了技能的核心数据结构，包含元数据、路径信息和启用状态。



```python

@dataclass

class Skill:

    """技能数据类，包含技能的完整元数据和路径信息"""

    

    name: str  # 技能名称

    description: str  # 技能描述

    # ...

```

```



### 3.2 路径规范



- 使用相对路径（相对于 backend 目录）

- 包含行号范围（`#L10-L50`）

- 使用反引号包裹路径



**示例**:

- ✅ `backend/packages/harness/evoflow/skills/loader.py#L24-L100`

- ❌ `D:\github\EvoFlow\backend\packages\...`（不要用绝对路径）

- ❌ `skills/loader.py`（路径不完整）



### 3.3 代码选择原则



- 只引用关键逻辑代码

- 删除无关的细节（如日志、异常处理）

- 保留核心算法和数据结构

- 添加必要的注释说明




## 四、术语规范



### 4.1 中英对照表



| 中文术语 | 英文原文 | 说明 |

|---------|---------|------|

| 技能 | Skill | 封装领域知识的可插拔模块 |

| 工具 | Tool | 原子化操作能力 |

| 子代理 | Subagent | 独立任务执行者 |

| 中间件 | Middleware | Agent 执行链上的处理组件 |

| 沙箱 | Sandbox | 隔离的执行环境 |

| 智能体 | Agent | AI 代理程序 |

| 线程 | Thread | 对话会话的上下文 |

| 记忆 | Memory | 跨对话的持久化信息 |

| 护栏 | Guardrails | 工具调用前的安全检查 |

| 编排 | Orchestration | 多组件协调执行 |



### 4.2 术语使用规则



1. **首次出现**: 中文（英文）

   ```markdown

   技能（Skill）是 EvoFlow 的核心扩展机制...

```



2. **后续出现**: 直接使用中文

   ```markdown

   技能可以通过以下方式加载...

   ```



3. **代码中**: 保持英文原文

   ```markdown

   调用 `load_skills()` 函数加载所有技能...

   ```




## 五、示例模板



### 5.1 完整文档模板



```markdown

# XX-模块名称技术文档




## 目录



- [一、概述](#一概述)

- [二、核心概念](#二核心概念)

- [三、实现细节](#三实现细节)

- [四、使用示例](#四使用示例)

- [五、API参考](#五api参考)

- [六、最佳实践](#六最佳实践)




## 一、概述



### 1.1 一句话理解



用一句话概括该模块的核心功能。



### 1.2 架构位置



```mermaid

flowchart LR

    A[上游模块] --> B[当前模块] --> C[下游模块]

    

    


## 导航



**上一篇**：[00-写作规范](00-写作规范.md)  

**下一篇**：[02-EvoFlow 架构分析](02-EvoFlow%20架构分析.md)



> **文档版本**：v2.0  

> **最后更新**：2026-03-30  

> **作者**：银泰



📚 返回总览：[EvoFlow技术总览](01-EvoFlow技术总览.md)

```




## 二、核心概念



### 2.1 关键术语



| 术语 | 说明 |

|------|------|

| 术语1 | 解释 |

| 术语2 | 解释 |



### 2.2 数据模型



**源码位置**: `backend/packages/harness/evoflow/xxx/types.py`



**逻辑说明**: 简述数据模型的作用。



```python

@dataclass

class DataModel:

    """数据模型说明"""

    field1: str

    field2: int

```




## 三、实现细节



### 3.1 核心功能A



**源码位置**: `backend/packages/harness/evoflow/xxx/module.py#L10-L50`



**逻辑说明**: 该功能的作用和实现思路。



```python

def core_function():

    """核心功能说明"""

    # 关键逻辑

    pass

```



### 3.2 核心功能B



...




## 四、使用示例



### 4.1 场景1



描述使用场景...



```python

# 示例代码

```



### 4.2 场景2



...




## 五、API参考



### 5.1 函数/类A



| 参数 | 类型 | 必需 | 说明 |

|------|------|------|------|

| param1 | str | 是 | 参数说明 |



### 5.2 函数/类B



...




## 六、最佳实践



### 6.1 建议1



说明...



### 6.2 注意事项



- 注意点1

- 注意点2




## 附录



### A. 相关文档



- [相关文档1](xxx.md)

- [相关文档2](xxx.md)



### B. 相关源码



- `backend/packages/harness/evoflow/xxx/`

- `backend/app/gateway/routers/xxx.py`




**文档结束**



> 本文档遵循 [EvoFlow 技术文档写作规范](00-写作规范.md)

```



### 5.2 源码引用模板



```markdown

**源码位置**: `backend/packages/harness/evoflow/路径/文件.py#L行号-L行号`



**逻辑说明**: 

简述该代码的功能、作用，以及为什么这样实现。



```python

# 关键代码段，删除无关细节

# 添加必要的中文注释

```

```




## 六、检查清单



发布文档前，请确认：



- [ ] 文档头部包含版本、更新日期、源码路径

- [ ] 有目录且链接正确

- [ ] 关键术语首次出现标注英文

- [ ] 源码引用包含路径、说明、代码片段

- [ ] 代码块标注了语言类型

- [ ] 表格对齐正确

- [ ] 没有拼写错误

- [ ] 所有链接可访问




## 导航



**上一篇**：无（本文档为规范说明）  

**下一篇**：[01-项目总览](01-项目总览.md)



> **文档版本**：v1.0  

> **最后更新**：2026-03-30  

> **作者**：银泰



📚 返回总览：[EvoFlow技术总览](01-EvoFlow技术总览.md)
