Telegram-Panel/docs/developer/documentation.md

文档维护

本项目使用 MkDocs Material 生成文档站，文档源文件统一放在 docs/。

本地预览

使用 uv（推荐）：

uv venv
uv pip install -r requirements-docs.txt
uv run mkdocs serve

生成静态站点：

uv run mkdocs build

目录约定（面向使用者优先）

• docs/getting-started/：从 0 到可用（安装、升级、FAQ）
• docs/guides/：日常使用与操作指南
• docs/deployment/：反向代理、Webhook、生产运维相关
• docs/reference/：配置/数据库/API 等参考型内容
• docs/developer/：模块开发与维护者说明

新增/移动页面的规则

• 新页面：直接在对应目录新增 *.md
• 侧边栏与顺序：在 mkdocs.yml 的 nav: 中维护
• 链接：尽量使用相对路径链接（例如 ../guides/sync.md），避免写死仓库 URL

重要改动文档门禁

新增功能、用户可见行为、API、配置项、数据结构、模块宿主合同、部署方式、运维状态或兼容性行为时，必须在同一个提交或 PR 中同步更新文档。根目录 AGENTS.md 是 Agent 执行门禁；本页负责说明文档落点。

按改动类型选择文档位置：

• 模块开发、宿主 API、页面内嵌合同、任务编辑器和运行态：docs/developer/modules.md
• API、配置、环境变量、数据库和持久化格式：docs/reference/
• Docker、云端部署、升级、回滚和健康检查：docs/deployment/ 或 docs/getting-started/
• 用户可见的新功能和快速配置：README.zh-CN.md 及对应使用指南
• 发布分支、云端验收和分支清理：开发发布流程

每个重要改动至少写清：适用版本、前置条件、行为或合同、验证步骤、失败排查和回滚方式。只更新代码而不更新文档，不能视为完成；若确实不需要文档，必须在提交说明或 PR 中记录原因。

近期功能文档对照

当前最近一批改动的文档落点如下，后续开发按同一规则维护：

• WARP 默认协议、HTTP/SOCKS5 选择和 Compose 配置：README.zh-CN.md、.env.example、docker-compose.warp.yml；实现合同和模块影响见 docs/developer/modules.md。
• 任务中心只展示宿主验证通过的可创建编辑器、独立配置页编辑已有任务：docs/developer/modules.md。
• 模块页面内嵌链路、运行态字段、打包校验和生产复核：docs/developer/modules.md 及 skills/tgpanel-module-workflow/references/。
• dev -> 云端验收 -> main 的发布顺序：开发发布流程。

后续功能若改变以上行为，必须同时修改对应条目，不得只追加代码或测试。

GitHub Pages 发布

已内置工作流：.github/workflows/docs.yml。

启用方式（只需要做一次）：

1. 仓库 Settings → Pages
2. Source 选择 GitHub Actions

之后每次合并到 main（且改动命中 docs/**/mkdocs.yml 等）会自动构建并发布。