# 文档维护规范

QuantDinger 的 `docs/` 是产品文档唯一来源，官网文档由它生成。文档不是发布后的补充物，而是功能验收的一部分。

## 信息架构

| 目录 | 面向对象 | 内容 |
| --- | --- | --- |
| `getting-started/` | 新用户 | 安装、首次使用、30 分钟上手 |
| `product/` | 研究与策略用户 | 页面能力和完整工作流 |
| `deployment/` | 管理员与运维 | 配置、部署、升级、恢复、排错 |
| `trading/` | 策略开发与交易用户 | 策略 API、券商和实盘安全 |
| `api/`、`agent/` | 开发者与 Agent | HTTP、OpenAPI、MCP 和 Agent Gateway |
| `security/`、`compliance/` | 安全与合规人员 | 报告流程、供应链和合规证据 |
| `architecture/` | 贡献者 | 系统边界、进程和扩展规则 |

## 每个功能 PR 的文档定义完成

涉及用户行为、接口、配置、数据结构或运维方式的 PR，必须同时完成：

1. 更新对应用户指南和中英文配对页。
2. 更新目录、交叉链接、配置参考和兼容性说明。
3. 对新增环境变量说明默认值、风险、是否重启以及 Secret 属性。
4. 对破坏性变更给出升级、回滚和迁移步骤。
5. 对页面变更更新截图；截图必须脱敏、裁剪到必要范围并标注适用版本。
6. 运行官网生成器、内部链接检查和多语言检查。

## 页面写作标准

- 标题直接说明任务；开头写清适用对象和前置条件。
- 先给推荐路径，再给替代方案；命令必须可复制。
- 用“预期结果”和“失败时下一步”帮助用户验证。
- 对删除、实盘、权限、密钥和不可逆操作明确警告。
- 不把临时排查报告、路线图或内部讨论发布为产品教程。
- 不承诺未经版本验证的外部服务能力。

## 截图标准

- 只使用当前稳定版界面，优先展示完整任务上下文而不是装饰性截图。
- 隐藏 API Key、Token、Cookie、邮箱、账户号、订单号和余额等敏感信息。
- 同一流程最多保留关键节点截图；文字步骤仍应独立可执行。
- 文件名使用英文小写和连字符，图片替代文本说明页面与动作。
- 界面变化后若截图不再准确，应更新或删除，不能保留误导性图片。

## 版本与审查

核心安装、配置、升级、恢复和实盘安全页面每个稳定版至少复核一次。外部服务、商店发布和 OAuth 页面应在提供商规则变化时复核。页面长期无人维护时，应明确标记适用版本或移除入口。

发布负责人应检查：新用户能否从首页找到安装；安装后能否完成配置与首个结果；管理员能否备份、升级和恢复；错误信息能否指向可操作的排错页；中英文链接是否成对可达。