工具手册的机器可读重构：人机双轨 + 六模块
TL;DR
- 今天 99% 的软件工具手册、产品文档只为人类设计，直接喂给模型会出现调用错乱、参数幻觉、反复重试，推高 AI 落地成本。
- 根因是目标不同：人文手册要「让人学会用」，AI 手册要「让机器稳定、低成本、零幻觉地调用」------目标不同，内容体系必须拆分。
- 方案是人机双轨文档 ：
manual.md面向人，AI 机器视图面向模型，同源维护、独立读取。 - AI 专属手册六个模块缺一不可 ：元信息、结构化 Schema、调用约束 Prompt、Few-Shot、错误码容错、AI 可读变更日志------Prompt 只是其中之一。
- 落地二选一 ：中小工具用「单文档双分区」，企业级用「双文档分离」（
manual.md+tool-ai-spec.json）。 - 本文不涉及模型微调方法，也不讲具体文档工具教程，只讨论如何让文档成为 AI 稳定调用的基建。
背景与问题
一个反复出现的落地误区：把现成的产品手册、操作文档整份塞进上下文，指望模型自主学会工具调用。结果是 AI 读得懂、用不好，看似能用、极不稳定------调用错乱、参数幻觉、执行失败、反复重试，自动化成功率被压低，Token 成本被拉高。
人文手册与 AI 手册的目标差异：
| 维度 | 传统人文手册 | AI 专属手册 |
|---|---|---|
| 核心目标 | 让人学会用 | 让机器稳定、低成本、零幻觉地调用 |
| 内容取向 | 场景、故事、截图、FAQ | 结构化、标准化、强约束、最小信息集 |
| 优化指标 | 学习体验、上手速度 | 调用成功率、Token 成本、响应延迟 |
人文手册的四项天然属性与 AI 调用需求完全相悖：
- 信息冗余，Token 成本极高------产品介绍、操作小贴士、案例故事对人类学习有价值，对工具调用无用；多余文本持续占用上下文窗口，增加推理成本、拉长响应延迟。
- 语言模糊，存在大量歧义与默认常识------「适量填写」「按规则操作」「特殊情况除外」，人类凭经验可理解，AI 会直接产生幻觉与边界判断错误。
- 无结构化定义，机器无法精准解析------参数类型、必填项、枚举值、返回结构、错误码、限流规则极少被严格定义，AI 只能靠模型泛化能力猜测调用规则，容错率极低。
- 只讲「怎么做」，不讲「不能做什么」------能力边界、高危操作、禁止行为、参数禁忌的缺失，正是 AI 越权、误用的根源。
架构：人机双轨文档体系
不废弃人文手册，而是建立两套视图，同源维护、独立读取、各司其职：
markdown
同源维护
│
┌───────┴───────┐
▼ ▼
人文视图 AI 机器视图
manual.md tool-ai-spec
───────── ─────────────
场景/步骤/截图 元信息 + Schema
FAQ/排错 约束 Prompt + 错误码
面向「学」 面向「调」三条经得起迭代的设计规则：
- 绝不让两套视图互相污染------AI 视图不塞故事，人文视图不塞参数表。
- Prompt 只是 AI 视图的一个模块，不是全部；单独拎出来优化 Prompt，解决不了 Schema 与错误码缺失的问题。
- 同源维护、独立读取------更新时两套同步，避免新旧规则冲突。
六个核心模块
1. 工具元信息（AI 识别基础）
模型读取文档的头部信息，用于快速识别工具定位、成本与状态，避免无效调用：
- 工具唯一标识、版本号、更新时间、废弃标记
- 能力摘要：一句话明确工具「能做什么」
- 能力边界：明确工具「不能做什么」（防幻觉核心）
- 调用成本、限流规则、最大并发、超时时间
2. 结构化 Schema 定义（精准调用核心）
用机器可解析的标准化结构替代模糊文字描述，杜绝参数猜测，对标 OpenAPI 规范：
- 输入参数：名称、数据类型、必填/可选、枚举约束、格式要求、取值范围
- 返回参数：字段定义、数据类型、默认值、空值规则
- 批量调用限制：数据条数上限、文件尺寸约束
json
{
"tool_id": "export-report",
"version": "2.1.0",
"cannot_do": ["不支持导出超过 30 天的历史数据"],
"input": {
"format": { "type": "enum", "values": ["csv", "xlsx"], "required": true },
"rows": { "type": "int", "min": 1, "max": 50000, "default": 1000 }
},
"errors": { "E429": "retry_after_60s", "E403": "abort_and_report" }
}关键点：参数类型、枚举值、边界、错误码全部是声明式的 。AI 读到的是规则而不是需要推理的散文，数据格式对错由 Schema 保证，而非靠模型猜。cannot_do 字段显式声明能力边界，是防幻觉的第一道闸。
3. AI 专属调用约束 Prompt（行为规则核心）
Schema 解决「数据格式对错」，专属 Prompt 解决「AI 行为逻辑对错」，四类规则：
- 调用前置校验规则：参数非空校验、枚举匹配、权限校验逻辑
- 禁止行为规则：禁止批量超限、禁止越权调用、禁止自定义参数
- 失败处理规则：不同错误码的重试策略、终止策略、上报策略
- 结果输出规则：返回数据的整理格式、禁止编造信息、精简要求
4. 极简 Few-Shot 样例
摒弃冗长的人类操作案例，仅保留高保真、极简的「输入--输出」样例，用最少 Token 帮 AI 快速对齐标准调用逻辑，降低理解偏差。
5. 完整错误码与容错策略
单独梳理机器可读的错误码体系，明确每一类报错的成因与 AI 自动化处理方案，解决调用失败后盲目重试、卡死流程的问题。上面示例里的 "E429": "retry_after_60s" 与 "E403": "abort_and_report" 就是这个思路：限流类可退避重试，权限类必须立即中止并上报。
6. AI 可读版本变更日志
标记参数新增、废弃、规则变更内容，让 AI Agent 可自动适配工具版本迭代，避免新旧规则冲突导致的批量调用失败。
两种落地方案
| 方案 | 做法 | 优势 | 不足 | 适合 |
|---|---|---|---|---|
| 单文档双分区 | 现有 Markdown 手册中新增独立「AI 参考区块」，人类读全文，AI 只读专属区块 | 改造成本低、维护成本低、无需拆分文档 | 结构化能力有限，复杂工具的 Schema 定义不够严谨 | 中小工具、快速落地验证 |
| 双文档分离 | manual.md 面向人类；tool-ai-spec.json 面向 AI，含 Schema、Prompt、错误策略、样例 |
机器解析效率最高、零冗余、稳定性最强，可直接对接 Agent 框架与自动化工作流 | 初次改造成本稍高，需要建立规范维护机制 | 核心业务工具、企业级系统 |
决策规则：先用单文档双分区验证价值，工具进入核心链路后再升级为双文档分离。
效果、收益与适用边界
文档标准化带来的收益，远高于小规模模型微调（就我们观察到的落地案例而言，效果因团队与工具复杂度而异）：
- 大幅降低 AI 运行成本------剔除无效冗余，减少上下文 Token 消耗，降低推理成本与响应延迟。
- 彻底降低幻觉与调用失败率------Schema + 强约束 Prompt + 明确边界，从源头限制 AI 自由发挥，工具调用从「猜测式」变成「确定性」。
- 实现 AI 工作流的可维护、可迭代------版本迭代同步更新 AI 规范文档，无需反复微调模型、重写 Prompt。
反对意见与适用边界：主张「先优化模型、文档以后再说」的团队，在模型能力持续提升的语境下短期或许成立；但只要工具仍在迭代、Agent 仍在批量调用，文档不结构化带来的调用失败与重试成本就会持续累积。两种方案都保留「不足」栏------轻量方案结构化不够严谨，企业级方案初期改造成本更高，按阶段取舍即可，不存在一步到位的免费方案。
总结 + 延伸阅读
- 目标不同，内容必分：人文视图与 AI 机器视图双轨并行。
- 六个模块缺一不可：元信息、Schema、约束 Prompt、Few-Shot、错误码、变更日志。
- 先选对落地节奏：轻量单文档双分区，企业级双文档分离，先验证价值再升级标准。
真正拉开团队差距的往往不是模型选型、算法能力，而是标准化、机器可读的基础基建。建议从手头最核心的一个工具开始，先把它的「AI 参考区块」写出来。
作者简介：kylinlab.tech --- 关注 AI Agent 落地与开发者工具的工程实践。 个人站：kylinlab.tech
你在生产里给 Agent 喂工具文档用的哪种方案？评论区交流～