维护与重新生成文档

文档从飞书工作流程出发，再解释支撑这些流程的产品对象。本文描述已实现的发布结构与更新方法。

信息结构

层次	回答读者什么问题	内容来源
从飞书开始	如何得到一个可用助手？	docs/tutorials/
在飞书中工作	如何对话、协作、委派和自动化？	docs/guides/
产品概念	专家、Session、Task 和实例分别是什么？	docs/concepts/
参考手册	有哪些命令、字段和参数？	docs/reference/
运维与集成	如何安装、诊断、连接主机和工具？	现有运维资料及选定 CLI 指南
产品模型与维护	哪些行为是正式契约，如何维护？	docs/current/、Task 模型、维护者设计记录和项目资料

显式双语目录 docs/navigation.json 管理页面范围、顺序、短导航标题和状态。 make docs-index 据此生成两种语言的仓库索引，网站同步器消费同一份目录。 页面使用稳定的源文件路径和网页路由，不随侧边栏标题更名而移动；合并或删除页面时， 同步更新目录及指向它的链接。 报告和规划记录仍保存在仓库作为背景，不混入当前文档发布集合。

目录标注目标规格和历史记录，在索引及网站状态提示中展示。目标规格不能作为已上线能力 承诺。产品模型继续作为维护者的详细契约，不充当用户的第一篇教程。

简短架构原则归入对应的当前模型或指南。具有独立设计理由、备选方案与取舍的记录放在 docs/maintainers/，明确标注历史状态，无需单独设置架构决策目录。删除的旧记录仍可从 Git 历史查阅。

哪些内容生成，从哪里生成

产物	真实输入	命令
中英文飞书命令帮助	internal/bridge/command 与 Bridge 双语词表	make feishu-doc
中英文 CLI 参考	装配后的 Cobra 命令树与文档翻译	make cli-doc
中英文配置参考	配置元数据与文档翻译	make config-doc
中英文 MCP 参考	已注册工具 Schema 与文档翻译	make mcp-doc
中英文仓库索引	docs/navigation.json	make docs-index
网页、侧边栏、编辑链接	公共 Markdown 配对页面与目录	网站 sync-docs.py，然后 VitePress

教程、指南、概念和产品契约要对照代码与行为测试编写，不能通过导出 API 注释忠实地重建。 重新生成处理机械事实和导航；人工审阅检查语义、可读性、中英一致性以及完整读者路径。

更新流程

1. 识别真实读者流程与实现位置。行为改变时，先修订所属产品模型，再改实现和行为测试。
2. 同步修改受影响指南的两种语言。操作步骤要包含准备条件、执行步骤、预期结果、失败路径 与下一步链接。自然语言请求注明依赖 Agent，并说明如何核实实际保存的对象。
3. 在 docs/navigation.json 登记新页面和双语标题，生成、历史或目标规格文档显式设置状态。
4. 在公共仓根目录重新生成并校验：

make docs
make docs-check

检查包含参考漂移、缺失语言配对或切换链接、未登记的发布页面、本地文件死链，以及教程和 指南 shell 代码块中直接执行的 amux 命令名、flag。不会对真实安装执行这些示例。 命令检查不证明参数值、权限或运行结果正确；文件链接检查不验证锚点或外部网站。

脚本或代码变化仍需完整 scripts/check.sh 门禁，文档检查已包含在内。 可执行提示词和 Skill 不作为需要双语配对的页面。

预览与发布

在独立网站 checkout 使用明确的公共源码路径，避免误同步旧快照：

python3 sync-docs.py /path/to/amux
npm run docs:build
npm run docs:dev

两种语言分别检查：飞书入口 → 对话指南 → 对象概念 → 命令参考 → 排障，同时检查搜索和 旧深链接。网站的 docs/upstream/index.md 与 zh/index.md 保留为手写落地页，其他同步 页面和导航都是产物，不在网站仓修改。

上线时先合公共文档，现有网站同步器已经能够发现新页面，再合网站目录消费端和落地页改动。 这样新导航上线前，目的页面就已存在。消费端也兼容尚未提供目录清单的旧版源码。 公共 main 文档变化触发 sync-docs.yml：同步、构建死链检查，再提交变化的网站源文件。 网站 push 后自动构建，生产部署仍是独立的手动 workflow；同步成功不等于已经发布生产。