贡献文档与集成

本站使用 VitePress。说明应面向任务，并从相邻 Elura 源码仓库中获取默认值、 限制、字段名称和 API 行为。

预览修改

npm install
npm run docs:dev

提交 Pull Request 前：

npm run docs:build

同时确认需要出现在导航中的页面已加入 docs/.vitepress/config.mts，并且相对 链接可以从源页面正确解析。

编写约定

• 中文页面使用简体中文和句式标题，英文页面继续使用英文。
• 产品写作 Elura，进程写作 Gateway 或 World，协议帧和路由使用 代码格式。
• 优先提供可运行命令和有源码依据的示例。
• 明确区分运行时行为与生成应用行为。
• 不记录真实密钥、端点或组织内部凭据。
• 展示版本敏感 API 时说明 0.x 兼容性风险。
• 修改英文功能说明时同步检查对应中文页面，反之亦然。

先选择页面类型

每个页面应只有一个主要任务：

页面类型	读者的问题	常见结构
教程	能否带我得到一个可运行的结果？	目标、前置条件、编号步骤、验证、故障排查、下一步
指南	如何完成这个具体任务？	背景、实现、取舍、验证、相关任务
概念	它如何工作，为什么这样设计？	心智模型、边界、生命周期、故障行为、取舍
运维	如何在生产环境运行并恢复它？	探针、信号、操作流程、故障检查、安全提示

不需要强迫每个页面使用所有标题。只保留回答读者问题所需的最小结构， 并将无关内容移到正确的页面类型。教程和指南应在结尾说明如何验证结果。

任务页标准结构

编写教程或指南时，可以从以下结构开始：

# 面向任务的标题

说明最终结果，以及预计时间或范围。

## 开始之前

只列出必需的工具、版本和现有状态。

## 1. 完成第一个操作

解释操作，提供可运行命令或代码，并标出读者必须替换的值。

## 验证结果

给出能够确认成功的命令、响应、日志或行为。

## 故障排查

将常见现象对应到检查项或修复方法。

## 下一步

链接到后续任务以及相关概念、配置或 API 页。

概念页不应模仿教程，应优先提供稳定的心智模型和明确边界。 配置和 API 查询页应保持紧凑，并有源码依据。只在图示能比文字更清楚地表达 关系或时序时才使用图示。

保持源码与文档一致

修改以下内容时应检查文档：

• 公共配置结构或默认值；
• 协议常量、帧验证或保留路由；
• CLI 目标与生成模板；
• 功能开关或 Workspace Crate；
• 管理端点、请求体、认证或状态码；
• 部署清单、健康行为或指标；
• 适配器与 Provider 能力。

条目级 API 文档属于 Rustdoc。本站主要解释组件如何组合、如何运维，以及应用 必须做出哪些取舍。

框架性能回归

tools/elura-load 与 tools/elura-perf 均为 publish = false 的 Elura 框架 维护者内部工具。它们不是应用依赖，也不属于受支持的上层 API。

• elura-load 从独立进程通过 TCP、UDP、WebSocket、QUIC 或 WebTransport 产生流量，并报告框架连接、认证和请求延迟。
• elura-perf 提供用于比较框架版本的可复现 HAProxy、多 Gateway、Redis 与 World 拓扑。

这些工具只能用于隔离的性能环境。Fixture 为单个压测容器放宽了来源 IP 限制， 不得复制到应用生产配置。应用团队应使用 WorldHarness、elura-testkit 和自己 的部署压测平台。

贡献 Provider 与 Adapter

欢迎向 Elura 仓库贡献可复用的 Provider 和 Adapter。组织专有策略应留在应用中；实现公开协议或通用基础设施能力 时，应优先提交上游 PR。

提交代码前请遵循Provider或 Adapter清单。每个合入的集成都应保持 Opt-in、 遵守核心契约语义、包含故障与安全测试、提供可审查的 Public API，并在同一变更中 更新 Rustdoc 与中英文站点内容。