跳转到主要内容
产品文档放在 docs/product/zh-CN 与 docs/product/en,内部设计决策保留在 docs/plans 等工程目录,真实结果放在 testing/evidence。不要把追加式工程日志直接当作当前使用教程。

从用户问题开始

按内容任务书确认页面 ID、目标路径、读者和职责。一页承担一个主要问题:教程带读者完成固定任务,操作指南解决具体目标,概念解释机制,参考精确定义契约。 每页包含:一句话回答、何时使用、版本/能力前提、具体步骤或定义、成功判据、重要失败出口、来源和最多三个下一步。使用术语表,API 字段、方法名和状态值不翻译。

写可核验的内容

字段与默认值来自当前 schema/实现;能力来自注册表;已验证范围来自带时间、SDK、协议和场景的证据。代码示例必须说明依赖、客户端初始化、输入、结果和清理。局部片段明确前置变量;占位域名和测试对象不得伪装成可直接使用的公共服务。 不要复制多份字段表后独立维护。可运行示例放 examples,指南链接或抽取它;生成表注明来源和快照时间。教程不因当前实现缺失而缩减验收旅程;出现冲突先记录并查证。

小改动的完整过程

以修改 E2B 模板说明为例:
  1. 对照 integrations/sandboxes/e2b.ts 与对应验收记录确认变化,是 schema 默认值、资源前提还是新验证范围。
  2. 修改两种语言的同一路径 integrations/sandboxes/e2b.md;必要时同步总览与 OCI 指南,保留历史证据时间。
  3. 示例若涉及参数变化,修改其真实源文件并做适当语法/类型检查;未重新执行云任务就明确说明。
  4. 更新 coverage.json 中该项的实际状态和验证范围。draft 不自动升级 complete;链接存在也不能证明内容完整。
  5. 运行结构检查并人工阅读两个版本,确认来源、限制、下一步与语义一致。
该检查只覆盖规划编号、文件、内联 Markdown 文件链接、围栏配对和首页可达性,不检查外部 URL、锚点、示例正确性或云行为。—require-complete 额外检查覆盖状态,仍不代替逐篇审阅。保存报告前确认路径适合本次工作;后续日期的验收应使用对应新文件。

检查本地章节链接与嵌入资源

移动页面、修改标题或更新目录链接后,补充运行链接检查:
它解析 Markdown 链接、引用式链接和图片,以及引号包围的 HTML href / src、单一来源的 srcset 属性;范围包括两份根 README。检查会解码本地路径并将片段定位到显式 HTML 锚点或规范化标题,代码围栏内的示例不会当成待验证链接。自检覆盖解析边界,不验证文章内容准确性。 报告写明具体标题规范化规则,不宣称与尚未配置的文档渲染器完全一致。重要目录目标宜使用显式稳定锚点,并在翻译和重命名标题时保留。多候选 srcset 和非 Markdown 文件的片段会报告为不支持,不会静默记为通过。检查不发送外部请求;远端徽章或 URL 仍须单独验证。链接检查通过不代表视觉、翻译、示例执行或发布门禁完成。保留后续审阅时使用新的报告文件名。

检查 Python 与 TypeScript 示例语法

安装仓库依赖和 Python 3 后,可以在不执行示例的情况下检查产品文档代码块:
Markdown 解析器识别 python/py、typescript/ts 代码块,包括嵌套代码块。Python AST 和 TypeScript 解析器按页面、代码块编号、块内行号报告语法错误;报告保留页面及片段哈希和解析器版本。有语法错误时命令失败,shell、JSON 和其他语言不在范围内。当前解释器接受语法,不证明所有声明的最低 Python/运行时版本都支持。 语法解析不解析变量和导入、不对 TypeScript 做类型检查,不执行安装、不请求 API,也不验证结果。缺少必要 client、ID 或凭据的上下文片段仍可能语法通过。应另外使用实际安装的 SDK,对适用示例做类型或运行检查,并区分模拟、本地包与真实云证据。

更新生成参考,而不是手工修补表格

SDK 方法导航维护在 sdk-reference-map.json。每个准确方法名对应响应/错误契约与上下文示例。两套生成脚本会拒绝遗漏或过时的映射,TypeScript 还会拒绝重复映射名。新增或重命名方法时,同步映射、审阅实际示例,再生成参考页。方法名出现且链接有效,不证明示例正确或该方法通过真实旅程。 当前仓库有三项源码索引生成器。安装仓库依赖后,在仓库根目录运行受影响的生成器;它们会更新文件,不是只读检查:
保留 http-routes、python-methods、ts-methods 的 begin/end 标记;运行前确认标记成对存在,运行后检查差异。不要在生成区手工添加说明,再期望下一次生成保留它。解释文字与示例放在标记外。 HTTP 生成器只识别当前 server.ts 中直接写出的 api.get/post/put/patch/delete 字面量路由,并调用权限分类函数。它没有启动服务、请求真实 API,也不覆盖其他监听器或动态路由注册。新增路由应同步归属映射和双语资源契约;仅有分配到页面的记录仍是草稿,不能自动证明字段完整。

内容修改的交付清单

审阅记录至少写出:页面 ID、核对的源码或证据、实际改动、执行命令与结果、未验证范围。coverage.json 的状态不能替代这份记录。reviewed 与 complete 应对应明确的审阅结论;存在未完成的该页要求时不要升级为 complete。整套发布还需独立核对任务书和发布条件。

逐项检查双语语义

两种语言逐项比较对象归属、参数默认值、成功与失败条件、能否重试、清理完成条件、版本和证据日期。例如“可以重复提交相同幂等意图”不能翻译成“可以重新执行任务”,“调用完成”不能翻译成“业务写入成功”。API ID、十进制游标和错误码保持原样;示意输出与实际运行输出的标签在两种语言中也必须一致。 结构检查不会检查这种等价性,也不会渲染 Mermaid 或实际运行所有命令。发布前单独阅读渲染结果中的表格、代码、图和窄屏布局,确认下一步链接符合读者当前任务。检查结果只对实际检查过的范围作结论。

双语审阅实例:清理完成条件

容量指南中的清理行是一个小型语义修订实例。统一要求“确认远端缺失”过于宽泛:部分 Provider 还要求删除回执完成并核对关联资源。当前英文容量指南与中文容量指南使用相同、范围更准确的完成条件。 该实例在两种语言中修正了一个具体条件,没有修改 API 或执行新的删除。涉及可执行参数的修改,还需同步并验证共享示例源文件,不能照搬本次无代码变更的验证范围。

代码片段改动实例:保持同一 Python 环境

Python 参考页原先将 SDK 安装到已激活的 .venv,后面的诊断命令却使用 .local/docs-example-venv/bin/python。后者是独立教程选择的有效环境,但本页并未创建它。这次小改动让诊断命令使用本页安装步骤已经选择的解释器。 修正后的 Python 参考与带日期的安装/语法证据让改动可以复核。证据记录实际解释器及验证范围。若以后 CLI 发生变化,应先修改实际程序,再同步两种语言的命令与验证,不能因为旧译文的代码仍能解析就保留过时内容。

双语言与 UI

两种语言使用相同 slug 与等价任务步骤。同步安全边界、错误动作、参数和完成标准,不只翻译标题。尚未同步的页面明确版本或回退状态,不挂空白译文或把旧译文标为最新。 文档译文与产品 UI catalog 是两回事。改 UI 文案还要遵守Console 契约:完整 en/zh-CN catalog、匹配插值、可访问名称、动态错误、Intl 格式和双语言浏览器检查。截图使用实际 UI,不暴露凭据或私有资源。

Mermaid 渲染检查

解析成功只证明语法可用。2026-11-20 的本地浏览器预览使用 Mermaid 12.3.0,20 幅图均生成 SVG,但默认 HTML 节点标签出现长文字裁切;设置 htmlLabels: false,并对 flowchart 同样禁用 HTML labels 后,抽查的首页长标签可以换行显示。正式站点应固定自己的 Mermaid 版本并重新验收,不能把临时预览的配置当作已有站点功能。 复杂时序图不要只用 max-width: 100% 强行压缩到手机宽度。保留可读字号,在专用容器内横向滚动,或提供可放大的独立图;容器应有可理解的名称和键盘访问。检查页面本身没有被撑宽、图的右侧仍可到达,并为图提供正文解释。解析、SVG 生成、视觉抽查与完整无障碍检查分别记录。 本次只抽查了中英文首页、英文代码地图与 worker 恢复时序图;窄屏检查为本地预览,未完成全部页面和正式主题验收。见图示渲染记录。 后续概念页审阅使用同一 Mermaid 版本,当前 26 幅概念图均成功生成 SVG。桌面抽查发现并修正了中文 Harness 标签拆词。英文 worker 恢复时序图在 390px 视口中,将 1727.5 SVG 单位压缩至 292 CSS 像素,文字无法阅读。应将它作为响应式回归案例;SVG 成功不能关闭视觉验收。见概念图渲染审阅。 后续当前图表审阅生成了 42 张产品文档图,发现并修复英文后端恢复时序图的分号解析错误,以及中文概览中 Runtime 单词被拆行的问题。概览、首个任务解释、Session 关系与 serverless 生命周期共八张图完成双语桌面审阅。390px 预览将 SVG 保持自然宽度,放入有名称且可聚焦的滚动区域;页面没有被撑宽,worker 时序图可用右方向键滚动。这验证了预览方案,不代表站点已经部署该功能,也不证明每张图的视觉与可访问性检查均已完成。

发布审阅

读者能否按步骤走通、失败能否恢复、资源能否清理、验证是否超出证据,是人工审阅重点。区分 contract、simulation、real-cloud 与 planned;不把计划写成 passed。公开文档不包含 .local、Token、备份或未经脱敏的用户内容。 当前页面是写作流程,不宣称所有规划文章已完成。下一步:提案与贡献、证据阅读。