# 文档编写规范

## 目标

- 让仓库文档易于导航、结构一致。
- 公共概念尽量提供中英文双语版本。
- 文档尽量“耐久”：使用相对路径链接代码，避免大量依赖易变的行号。

## 语言与命名

- 英文：`{topic}-en.md`
- 中文：`{topic}-zh.md`
- 若确实需要单文件双语（少见），可不加后缀，但优先拆分为 en/zh 两份。

## 结构建议

- 开头给出“本文解决什么问题/适用场景”。
- 使用相对路径引用代码（例如 `../src/...`）。
- 运维/排障类文档建议包含“如何验证”。

## 何时需要更新文档

- 任何影响以下内容的 API/ABI 变更：
  - hostcalls
  - CLI 参数 / 配置
  - HTTP/gRPC endpoints
- 任何语义变更会导致旧文档误导读者的情况。

## 风格

- 不写入 secret/token。
- 多给可执行/可复现的例子。
- 中英文尽量保持章节编号一致，方便对照。

