FastGPT 版本文档

调用与范围

仅手动调用，例如：

• $fastgpt-release-docs 4173
• 使用 fastgpt-release-docs 更新 v4.17.3 文档，对比上一正式版本。
• $fastgpt-release-docs v4.17.3，目标 ref 使用当前分支。

本 Skill 的产物是版本中文源文、对应英文 MDX，以及必要的同目录导航更新。调用本 Skill 不代表要求修改产品代码、切换分支、创建 worktree、提交、推送或创建 PR；这些动作按本次用户要求执行。

优先使用当前 FastGPT 仓库；当前目录不是该仓库时，使用用户指定的 FastGPT 仓库目录。先阅读仓库适用的 AGENTS.md，检查工作区，保留用户已有修改。不要因文档任务强制清理、重置或切换工作区。

1. 确认版本、文件与比较范围

版本与文件

• v4.17.3、4.17.3 和 4173 均可表示 V4.17.3。
• 简称通过已有文档的 basename、frontmatter 和 Git tag 交叉确认，不按固定字符位置硬拆版本号；无法唯一确定时只询问版本歧义。
• 优先定位已有页面。通常对应 document/content/self-host/upgrading/4-17/4173.mdx 与 4173.en.mdx；新页面沿用同系列目录和命名规则。
• 阅读目标版本、上一版本中文说明与同目录 meta.json / meta.en.json，保留既有 frontmatter、组件和有依据的人工说明。

比较范围

1. 用户指定比较基准或目标 ref 时，以其为准。
2. 未指定基准时，查找低于目标版本的最近一个正式发布 tag，按版本顺序判断，排除预发布 tag；不要直接将补丁号减一。例如存在 v4.17.2 时，V4.17.3 通常以它为基准。
3. 目标版本已有正式 tag 时，默认比较到该 tag。尚未发布且没有目标 tag 时，默认比较到最新 upstream/main；缺少该 remote 时检查实际发布仓库的 main，不把任意同名分支当成上游。
4. 按需刷新选定 remote 的 main 与版本 tags，只更新引用，不 checkout 或 rebase。若上一正式版本缺失，先检查远端；仍无法确定时询问比较基准，不自行猜测。
5. 开始分析前固定两端 commit SHA，并向用户简要说明版本、比较范围和目标文档。当前分支或未提交的产品改动仅在用户要求时纳入，不把无关工作区改动混入版本范围。

使用提交记录发现线索，使用两端最终代码差异确认事实：

git log --oneline <base-sha>..<target-sha>
git diff --stat <base-sha> <target-sha>
git diff <base-sha> <target-sha> -- <related-paths>

不要只依赖 PR 标题、commit message 或已有版本文档。阅读相关实现、配置、迁移、接口合约及必要的局部测试，核实最终用户行为。被撤回、覆盖且不再生效的改动不列为发布内容。

Pro 子模块

主仓库范围包含 Pro 变更时，同时分析两个版本实际引用的子模块提交：

git ls-tree <base-sha> pro
git ls-tree <target-sha> pro
git -C pro diff --stat <pro-base-sha> <pro-target-sha>
git -C pro log --oneline <pro-base-sha>..<pro-target-sha>

继续读取相关 Pro diff，不使用当前 Pro 分支或 Pro 最新 main 替代版本指针。必要时获取对应提交对象，不改子模块 checkout。有权限或对象缺失时，说明未核实范围，不补写推测的商业版能力。区分商业版、开源版与外部服务能力。

2. 从改动中归纳版本主题

先形成“用户变化 → 适用范围 → 边界/升级动作 → 代码证据”的候选清单，通常保留在工作上下文中，不额外生成分析报告。

• 以功能和用户结果为单位归并，不以 PR 或提交为单位列举。同一功能跨多个 PR 的实现、兼容与修复，整理成一个完整条目。
• 相同领域但结果无关的事项仍分开，不为减少条数而把互不相关的问题堆成长段。
• 一个主题原则上只放一个最合适的章节。升级指南可再次引用必要的操作与风险，但不重复整段功能说明。
• 删除合并记录、纯测试补充、临时调试、无用户影响的实现细节。值得交代的重构、依赖更新与去冗余集中放在工程改进中，不逐个包或 helper 罗列。
• 更新既有版本文档时合并、纠正和重排已有条目，避免把新发现一律追加到末尾；保留不被本次证据推翻的人工补充。

3. 中文组织与写作规则

章节

使用以下结构。升级指南固定保留下述四个子章节，其他顶层章节有内容才保留：

1. 升级指南：依次为配置变更、镜像更新、升级脚本、兼容说明。各子章节内优先说明必须操作、破坏兼容、数据与权限相关的重要事项，写清适用版本、默认值、生效范围和操作顺序。
2. 🚀 新增内容：之前不能做、现在新增的能力。已有功能扩展出新能力也归入新增，不另设“补充”。
3. ⚙️ 优化：原有功能在交互、效率、性能、诊断或兼容性上改善。
4. 🐛 修复：行为偏离预期的问题，说明触发场景与修复后的结果。
5. 🛠️ 代码优化：内部重构、去冗余、基础设施和依赖调整。用户能感知的修复移到“修复”，必须执行的升级动作放“升级指南”。

升级指南固定结构

按以下标题及顺序编写，不合并“配置变更”和“兼容说明”：

## 升级指南

### 配置变更

### 镜像更新

### 升级脚本

### 兼容说明

• 配置变更：说明本轮新增、删除或修改的环境变量与系统配置，包括默认值、配置优先级、适用范围及是否需要人工调整。
• 镜像更新：编写前期通常留空，由发布人在最后 release 阶段人工填写。不根据目标版本、依赖版本或已有旧版说明自动推导镜像 tag，也不自动填“待发布”等占位内容。保留发布人已经填写的内容；用户明确提供镜像信息并要求写入时再补充。
• 升级脚本：描述本轮相对上一版本新增或调整的自动升级脚本。核对脚本实现、注册信息及实际触发机制，说明任务名称、作用、启动时或后台自动执行、前置依赖及必要的失败重试方式。不重复罗列未变化的历史任务，不把手动脚本写成自动执行。确认本轮没有自动升级脚本时可写“本轮无自动升级脚本”。
• 兼容说明：说明接口、数据格式、权限、计费及行为变更对现有使用方式的影响，写清受影响范围和必要的适配动作；不要仅限于 API，也不要重复列出无兼容影响的普通修复。

英文版沿用同样的四段顺序与镜像留空状态，标题翻译交给 doc-i18n。

统一领域标签

新增、优化、修复及代码优化的条目前加单一领域前缀，形式为 **[工作流与 Agent]**。同一套标签贯穿各章节，不混用重要程度、实现手段和问题性质作为分类。

按主要用户入口或影响选一个标签。例如工作流选择器的交互修复仍归“工作流与 Agent”，不因为是 UI 改动就归“对话体验”。工程优化中借助请求 profile 定位系统瓶颈归“系统与运维”。

排序与粒度

• 重要内容在前，小改动在后。优先考虑用户影响、覆盖范围、安全与数据风险，再考虑功能重要性；不按 PR 编号、提交时间或文件路径排序。
• 同标签条目相邻。每个章节先按该领域最重要改动的影响决定领域组顺序，再在组内按重要程度排序；上表不是固定排序。
• 不使用“核心、体验、补充”作为并列标签。需要概括大版本时，可在开头精选 2–3 项已证实的版本亮点，不能把所有事项都标为重要。
• 同一个结果由多个 PR 完成时合并成一条，保留影响使用的条件与限制。例如“工具名重复、参数先于名称到达、并行参数混淆”可归并为模型原生工具调用流兼容性条目，而不是按三个 PR 写三条。
• 不把所有表单、权限或工具问题机械合并；只有共享同一能力或用户结果时才合并。
• 通常一条用 1–2 句讲清“变化、用途或触发条件、关键边界”。小改动简写，较长操作说明放升级指南或链接到功能文档，不为每条补充实现原理。

示例形式：

## 🚀 新增内容

1. **[工作流与 Agent]** 支持通过自然语言创建或修改工作流，确认方案后生成候选版本并应用到画布。
2. **[对话体验]** 支持恢复会话输入草稿，切换会话或刷新后继续编辑。

## 🐛 修复

1. **[工作流与 Agent]** 修复未填写说明的表单提交时误报 dataId 重复的问题，恢复后继续执行同一轮工作流。

示例只说明排版与归并方式，不作为任一版本的事实来源。编号在每个章节内连续，排序、合并后重新编号。

4. 中文完成后调用 doc-i18n

先完成中文内容的事实复核、归并、分类与排序，再加载并执行 $doc-i18n，明确只翻译本版本的中文页面和必要导航。

• 使用当前 FastGPT 仓库内 .agents/skills/doc/i18n/SKILL.md；若路径变动，通过仓库技能目录定位同名 Skill，不复制另一套翻译规则。无法找到时完成并保留中文，向用户说明缺少翻译依赖，不冒充已执行该 Skill。
• 按该 Skill 读取共享翻译规范与术语库，再更新对应 .en.mdx；英文保留中文章节、分类、条目归并关系及重要性排序，行文采用自然英文。
• 同步检查 meta.json / meta.en.json，保持页面引用一致；核对英文站内链接的 /en/ 前缀及目标页面。
• 中文后续发生实质修改时，再同步对应英文，避免两版事实、范围或条目数量漂移。

5. 验证与交付

• 对照固定的比较范围复核：重要变化无遗漏，无未经证实内容；同类改动已归并，领域成组，重要在前，每条一个领域标签，章节编号连续。
• 检查升级指南四个子标题及顺序；镜像更新按发布阶段留空或保留人工内容，自动升级脚本只描述本轮已核实的变化。
• 核对中英文版本号、数字、默认值、环境变量、接口路径、脚本 ID、商业版限制及条目对应关系。保留真实发布状态，不臆造 releaseTime 或已发布镜像 tag。
• 对本次 MDX 运行仓库的 Prettier 和中文 textlint，检查 frontmatter、组件、代码围栏及链接。执行必要的文档引用检查；按 doc-i18n 要求执行英文页面与路由校验，必要时使用局部 fixture。全站检查若报告无关旧问题，区分并说明，不顺带重写无关文档。
• 只检查和修改本次页面、必要导航及仓库流程要求的生成元数据，不主动运行全量业务测试。
• 交付时简要说明标准版本号、实际比较的两个 ref/SHA、更新文件和验证结果；指出任何无法核实的版本或 Pro 范围。提交与 PR 操作仅按用户本次或既有明确授权执行。