---
name: edge-doc-coauthoring
description: edge_collector 文档协作规范。用于编写或更新方案设计、部署说明、协议文档、事故分析、本地模型方案、用户手册等 docs 文档时，帮助确定读者、落点、结构、验证依据和后续实施清单。
---

# edge_collector 文档协作

## 文档落点

- 协议实现：`collector/docs/protocols/`
- 协议清单：`collector/docs/协议支持清单.md`
- 边缘/云端通用方案：`docs/`
- 鲁班猫设备问题：`docs/鲁班猫1/`、`docs/鲁班猫3/`
- 本地模型方案：`docs/本地模型/`
- 部署/同步/运维：`docs/` 或 `docs/ops/`

## 写作流程

1. 明确读者：开发、运维、现场用户、管理后台用户。
2. 明确目标：评估、实施、排障、交付说明、用户操作。
3. 收集依据：代码路径、配置文件、脚本、远程验证、官方文档链接。
4. 写清边界：第一版做什么、不做什么、风险和前置条件。
5. 给出可执行步骤：命令、目录、配置示例、验证方法。

## 推荐结构

技术方案：

```text
背景与目标
当前现状
方案设计
目录/配置/API
实施步骤
验证计划
风险与对策
参考资料
```

事故分析：

```text
问题现象
影响范围
现场证据
根因分析
修复方案
验证结果
预防措施
```

用户说明：

```text
功能用途
使用步骤
参数解释
常见问题
注意事项
```

## 约束

- 给用户看的协议介绍不透露内部技术细节。
- 技术方案可写实现细节，但要标注假设和验证状态。
- 引用外部信息时提供链接。
- 不把未经验证的能力写成已完成。