ShowDoc 此次更新把 AI 智能体放进了文档管理流程。项目成员不仅可以通过对话查找页面、追问内容，还能用一句话批量创建页面、统一修改整个项目中的重复信息，并让 AI 直接在编辑器中协助改稿。变化的重点不是多了一个聊天窗口，而是文档开始具备跨页面执行任务的能力。
从关键词搜索转向内容问答
传统文档搜索依赖标题、目录和关键词。它适合寻找名称明确的页面，却不擅长处理这类问题：
- 测试环境的鉴权方式是什么？
- 哪些接口仍在使用旧域名？
- 订单取消会影响哪些下游系统？
- 项目里有没有相互矛盾的超时配置？
AI 智能体可以根据项目文档理解问题，再从相关页面中组织答案。这类能力尤其适合 API 文档、技术规范、产品说明和团队知识库，因为信息往往分散在多个页面里。
不过，回答是否可靠仍然取决于文档质量。过期页面、重复规范和缺少上下文的接口说明都会影响结果。团队在使用问答功能时，应要求答案附带页面名称或引用位置，并回到原文确认关键参数，避免把生成内容直接当成系统事实。
批量创建与修改改变了维护成本
这次更新覆盖了两个长期消耗维护时间的场景。
一个是批量建页面。例如新服务立项时，可以要求智能体按照统一结构创建“服务概览、部署说明、接口约定、故障处理、变更记录”等页面。另一个是跨项目修改，例如统一替换域名、补充鉴权说明、调整页面分类，或者在所有接口文档中增加错误码约定。
批量执行的风险也比单页编辑更高。一条含糊指令可能改动几十个页面，因此提示词需要同时说明范围、规则、例外和验收条件。更稳妥的流程是：
- 先让智能体列出命中页面和拟修改内容。
- 抽查有代表性的页面，包括首页、接口页和历史归档页。
- 小范围执行并查看差异。
- 确认结果后再扩展到整个项目。
- 保留修改记录，以便发现误改时回滚。
可以这样实践：把批量任务写成可审查的变更单
下面是一个可复制并按团队情况修改的 YAML 任务单。它不是 ShowDoc 已公开接口格式，而是一种组织 AI 指令的实践模板；可以把内容粘贴到对话中，或接入团队自己的审批流程。
task: replace-api-domain
project: payment-service-docs
mode: preview
scope:
include:
- API 文档
- 部署说明
exclude:
- 历史归档
- 发布记录
changes:
- find: https://api.old.example.com
replace: https://api.example.com
- append_after: 鉴权说明
content: 所有生产请求必须携带有效的 Bearer Token。
constraints:
- 不修改代码示例中的 localhost 地址
- 不创建重复的鉴权说明
- 页面含“已废弃”标记时只报告、不修改
output:
- 列出所有命中页面
- 展示每个页面的修改前后差异
- 未经确认不得执行正式修改
可以配合下面的提示词使用：
请根据下面的 YAML 变更单检查当前项目。
本轮只执行 preview：列出命中页面、修改原因和逐页差异，不要写入任何页面。
如果规则存在歧义，停止任务并列出需要确认的问题。
确认预览后，再把 mode 改成 apply，同时保留“逐页报告结果”和“遇到歧义停止”的约束。对于域名、鉴权方式、版本号等高影响信息，还应安排项目成员复核。
编辑器里的 AI 更适合处理结构，而不是替代评审
在编辑器中，AI 可以承担格式统一、段落重写、摘要生成和缺失章节补全等工作。例如面对一份结构松散的接口说明，可以要求它按照固定模板整理：
请重构当前 API 页面，保留所有已有技术事实，不要自行补造参数。
按以下顺序组织内容：
1. 接口用途
2. 请求方法与路径
3. 鉴权方式
4. 请求参数
5. 成功响应示例
6. 错误码
7. 注意事项
发现缺失信息时使用“待补充”标记，并在文末列出待确认项。
这里最重要的限制是“不要自行补造参数”。AI 能改善表达和结构，但接口字段、权限规则、默认值与错误码仍应由服务实现、测试结果或负责人确认。
落地时先建立三条边界
团队启用智能体后，可以先从低风险任务开始，例如查找文档、生成摘要、统一标题格式，再逐步开放跨页面写入。正式使用批量修改前，建议确认三条边界：
- 权限边界：智能体只能读取和修改当前成员有权访问的项目与页面。
- 执行边界：跨页面操作默认预览，重要项目需要人工确认后写入。
- 事实边界：AI 负责检索、组织和改写，关键技术事实仍由代码、配置和责任人背书。
ShowDoc AI 智能体的实际价值，取决于团队能否把自然语言指令变成可审查、可回滚的文档操作。先建立预览、差异检查和人工复核机制，再扩大批量任务范围，才能真正降低维护成本，而不是更快地产生新的文档偏差。