文档更新原则
语言：English · 中文
Agently 的公开技术文档以主仓库 docs/ 为统一事实源。官网可以有更完整的视觉设计、导航、首页、客户介绍和营销页面，但技术文档正文、版本事实、推荐用法、代码样例、废弃提示和 release 说明应先落在主仓库。
这样做的好处很直接：功能版本更新时，代码、示例、兼容信息、Agently-Skills 和官网不会各说各话。
文档源分工
| 位置 | 负责什么 | 不负责什么 |
|---|---|---|
主仓库 docs/cn、docs/en | 技术文档事实源：能力介绍、用法说明、代码样例、场景 Playbook、release notes、废弃提示、版本提示 | 官网视觉、首页动效、客户展示、静态营销页面 |
| 官网 VitePress | 展示主仓库技术文档：导航、侧边栏、SEO、双域名、站内搜索、样式、链接检查 | 私自维护另一套技术事实 |
| 官网首页和营销页 | 产品定位、价值表达、客户案例、招聘、授权声明 | 替代主仓库技术文档源 |
| Agently-Skills | 给 coding agent 的当前推荐路径、项目结构和验证脚本 | 作为运行时 API 文档的唯一来源 |
官网可以按读者路径组织导航，但正文应从主仓库同步。需要为官网改写的技术内容，也应回写主仓库后再同步到官网。
Release 后怎么更新
每次功能版本更新后，先确定受影响范围，再改文档。
| 变更类型 | 必须检查 |
|---|---|
| 新 API / 新能力 | 对应能力页、快速开始或 Playbook、示例、release notes、能力地图 |
| 推荐用法变化 | 入门路径、代码片段、Agently-Skills、旧用法迁移说明 |
| 行为变化 | 使用说明、边界条件、错误语义、兼容说明、测试或示例输出 |
| 废弃或降级 | 废弃提示、迁移路径、旧 API 位置是否从新手路径移出 |
| Provider / 模型配置变化 | 模型设置、快速开始、兼容格式说明、示例配置 |
| Runtime / streaming / observability 变化 | Model Response、TriggerFlow、DevTools、服务化文档 |
文档合并前至少确认三件事：
- 代码和示例体现的用法与文档一致。
- release notes 讲清楚版本事实和迁移影响。
- 官网同步后没有断链、重复页面或过时入口。
写作原则
公开文档不是 API 字典。读者通常先带着业务问题进入文档，再去找 API。
| 原则 | 写法 |
|---|---|
| 开场用场景，不用定义 | 先说读者遇到的问题，再引出 Agently 能补上的工程链路 |
| 先说问题，再说方案 | 先让读者看到输出漂移、工具失控、流程不可恢复这类具体代价 |
| 利他视角 | 写“这样做帮你得到什么、少踩什么坑”，少写“你应该遵守什么原则” |
| 小标题有判断 | 用“什么时候需要 TriggerFlow”比“TriggerFlow 简介”更有用 |
| 事实先行 | 能引用代码、示例、release notes、项目证据时，不用空泛宣传 |
| 旧路径降级 | 兼容 API 可以保留，但不要放在新手第一路径里 |
避免这些写法：
- 戏剧化收束句，例如“这就是 X 的真正价值”。
- 居高临下的命令，例如“这是工程纪律，不是建议”。
- 只说抽象价值，不说明对读者有什么帮助。
- 用一段长文堆概念，没有表格、流程图、代码或验收清单。
图、表、Tips 和代码怎么组合
一篇核心文档通常至少包含两类呈现方式，不要只写连续段落。
| 内容类型 | 适合呈现 |
|---|---|
| 表格 | 能力边界、选型判断、版本差异、错误与修正、上线检查 |
| 流程图 / Mermaid | 请求链路、TriggerFlow 生命周期、服务拓扑、状态流转 |
| Tips / warning | 关键误区、兼容提示、安全边界、上线前提醒 |
| 代码块 | 推荐 API 形态、最小可运行片段、迁移前后对比 |
| 检查清单 | release 后校对、上线前验收、Playbook 落地检查 |
代码块必须服务于真实用法。不要写无法运行、过度简化到误导、或只为了展示语法的片段。涉及模型语义能力的示例，应尽量连接真实 DeepSeek 或本地 Ollama；如果外部系统是 mock，文档要说明 mock 边界。
页面结构建议
能力页优先用这个结构：
- 场景问题：什么时候读这页。
- 最小推荐用法：一段能看懂的代码或流程。
- 能力边界：负责什么、不负责什么。
- 常见升级路径：什么时候进入 Actions、Workspace、TriggerFlow、Dynamic Task。
- 常见误用：错误写法、后果、修正。
- 版本和兼容提示：如果 API 有迁移或废弃，给出明确位置。
- 下一步阅读：不要泛泛列链接，要按读者下一步任务给链接。
Playbook 页优先用这个结构：
- 业务场景和交付物。
- 推荐架构或流程图。
- 结构化输出或状态契约。
- 需要用到的 Agently 能力。
- UI / 服务 / 工作流 / 证据怎么接。
- 验收清单。
- 继续阅读。
中英文同步
主仓库应维护 docs/cn 和 docs/en 两套真实源文档。英文页不能只做中文镜像；如果暂时只能先补中文，英文页要明确标记为待翻译，不应伪装成已完成英文正文。
更新时按这个顺序：
- 先完成中文事实和结构。
- 英文同步表达，不逐字翻译，但必须保留同样的事实、边界、代码和版本提示。
- 官网从主仓库同步，不在官网单独改技术正文。
完成前检查
| 检查项 | 通过标准 |
|---|---|
| 事实来源 | 能追到代码、示例、release notes、spec 或项目证据 |
| 推荐路径 | 新手入口不推荐废弃或兼容 API |
| 代码样例 | 与当前 API 一致，必要时实际运行或指向已验证示例 |
| 场景表达 | 读者知道这页帮他解决什么问题 |
| 呈现方式 | 有表格、流程、Tips、代码或检查清单组合，不是纯长文 |
| 中英文 | 双语事实一致，链接可用 |
| 官网同步 | VitePress 构建、链接检查、sitemap 通过 |