cloud
92 lines
2.1 KiB
Markdown
92 lines
2.1 KiB
Markdown
---
|
|
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 引用：浏览器或图片查看器打开检查
|