---
name: edge-markdown-docs
description: edge_collector Markdown 文档编写与处理规范。用于创建、更新、拆分、合并、校对 docs、collector/docs、协议文档、部署说明、测试报告、故障报告、本地模型方案等 Markdown 文档，并维护目录、链接、图片引用和读者边界。
---

# edge_collector Markdown 文档处理

## 适用范围

- `docs/`
- `collector/docs/`
- `collector/docs/protocols/`
- `docs/本地模型/`
- `docs/鲁班猫*/`
- `.agents/skills/`

## 工作流

1. 先确认读者：用户、运维、开发、客户交付。
2. 选择落点：优先更新已有文档，避免重复文档。
3. 读取相邻文档，保持标题层级和术语一致。
4. 写完后检查链接、图片路径、代码块语言和表格可读性。
5. 技术文档标注假设和验证状态，用户文档隐藏内部实现细节。

## 推荐结构

技术方案：

```text
背景与目标
现状与问题
方案设计
接口/配置/目录
实施步骤
验证计划
风险与回滚
```

操作说明：

```text
功能用途
使用前准备
操作步骤
参数说明
常见问题
注意事项
```

故障报告：

```text
问题现象
影响范围
证据
根因
修复
验证
预防措施
```

## 格式规则

- 标题层级从 `#` 开始，不跳级。
- 命令使用 `bash` 代码块。
- JSON 使用 `json` 代码块。
- 表格列不要过宽，必要时拆成列表。
- 图片放到文档同级 `assets/` 或专题目录下，并用相对路径引用。
- 引用外部资料时给链接。

## 当前项目特别规则

- 协议用户介绍不要透露 helper、SDK、库路径、内部进程。
- 部署文档要写清是否会覆盖运行配置。
- 云平台 AI 文档不要展示真实 key。
- 远程主机文档不要写明密码。
- 同主机编译部署仍要使用 `scripts/migrate_edge.sh`。

## 校验

至少执行：

```bash
rg -n "TODO|待确认|change_me|password|secret" docs collector/docs .agents/skills
```

按文档类型补充：

- JSON 示例：`jq empty`
- Shell 示例：`bash -n`
- SVG 引用：浏览器或图片查看器打开检查