Documentation-Accurate Code Generation

重要提示：此技能通过强制参考文档来防止大模型产生幻觉。

使用场景

• 始终在生成代码时使用
• 始终在调用 API 时使用
• 始终在创建配置时使用
• 始终在实现功能时使用

核心理念

绝不凭记忆生成代码。始终参考文档。

存在的问题

• 大模型会虚构不存在的 API
• 方法名称可能被重命名或移除
• 参数可能发生变化或被弃用
• 返回类型可能意外改变
• 配置格式可能演进

解决方案

1. 优先加载文档 — 在编写任何代码前
2. 提取 API 签名 — 获取真实的接口签名
3. 基于文档生成 — 使用真实 API 数据
4. 与文档校验 — 检查生成的代码是否匹配
5. 追踪引用来源 — 记录所使用的文档

工作流程

1. 识别 → 需要什么代码/API/工具？
2. 定位 → 找到文档来源
3. 加载 → 获取并解析文档
4. 提取 → 拉取 API 签名、参数、示例
5. 生成 → 使用真实文档生成代码
6. 校验 → 检查代码是否符合文档
7. 引用 → 记录使用了哪些文档

文档来源

1. OpenClaw 内部文档

• 路径：C:\Users\clipp\AppData\Roaming\npm\node_modules\openclaw\docs
• 访问方式：read 工具
• 使用场景：OpenClaw 特有的 API、工具、技能

2. 工具文档

• 命令帮助：--help 参数
• 手册页：man <command>
• 官方文档：使用 web_fetch 获取

3. API 文档

• 官方文档：使用 web_fetch
• OpenAPI 规范：解析并引用
• 包管理器文档：npm、pip、cargo 的文档

4. 代码示例

• 现有代码：阅读相似实现
• 测试文件：检查测试中的使用模式
• 示例代码：查找可运行的代码样本

代码生成流程

步骤 1：文档发现

# 对于 OpenClaw 工具
read("openclaw-docs-path/tool-name.md")

# 对于外部工具
web_fetch("https://docs.tool.com/api")

# 对于本地工具
exec("tool --help")

步骤 2：API 签名提取

# 提取内容：
- 方法名称
- 参数（名称、类型、必填/可选）
- 返回类型
- 错误处理方式
- 使用示例
- 版本信息

步骤 3：代码生成

# 使用真实 API 数据生成代码
def generate_from_docs(api_docs):
    # 使用真实方法名
    # 使用真实参数名
    # 使用真实返回类型
    # 包含文档中说明的错误处理
    # 添加来自文档的函数注释
    pass

步骤 4：校验

def validate_against_docs(code, api_docs):
    # 检查方法名是否匹配
    # 检查参数名是否匹配
    # 检查类型是否匹配
    # 检查返回类型是否匹配
    # 确保没有虚构的方法
    pass

快捷操作

• codegen <api> — 基于文档参考生成代码
• validate <code> — 将代码与文档进行校验
• doc-lookup <api> — 加载并显示文档
• api-extract <tool> — 提取 API 签名

使用示例

"生成使用 OpenClaw sessions_spawn 工具的代码"
# 处理流程：加载文档 → 提取 API → 生成代码 → 校验

"创建一个使用 requests 库的 Python 脚本"
# 处理流程：获取 requests 文档 → 提取 API → 生成代码 → 校验

"为 OpenClaw channels 编写配置"
# 处理流程：加载配置文档 → 提取格式 → 生成代码 → 校验

校验规则

1. 方法名校验

• 检查方法是否存在文档中
• 确认拼写完全一致
• 确认方法未被弃用

2. 参数校验

• 所有必填参数均已包含
• 参数名称与文档完全一致
• 参数类型与文档一致
• 可选参数标记正确

3. 返回类型校验

• 返回类型与文档一致
• 错误类型与文档一致
• 边界情况已处理

4. 配置校验

• 键名与文档一致
• 值类型符合 schema
• 必填字段存在
• 格式符合规范

错误预防

常见幻觉模式

1. 不存在的方法 — 虚构的接口方法
2. 错误的参数名 — 伪造的参数名称
3. 错误的类型 — 参数或返回值类型错误
4. 缺少错误处理 — 忽略文档中说明的异常
5. 错误的配置格式 — 配置结构不正确

预防策略

1. 始终先加载文档 — 绝不凭记忆生成
2. 提取真实签名 — 不猜测接口结构
3. 全面校验 — 与真实文档比对
4. 追踪引用来源 — 明确使用了哪些文档
5. 使用真实 API 测试 — 验证代码实际可用性

集成点

与其他技能集成

• 编码技能：用于生成准确的代码
• 自我进化：通过文档校验更新技能
• 内容生成：生成准确的代码示例
• 研究任务：从真实文档中调研 API

与 OpenClaw 工具集成

• read：加载内部文档
• web_fetch：获取外部文档
• exec：通过 --help 运行工具获取文档
• edit/write：创建经过验证的代码

引用追踪

格式

# 代码生成引用记录

## 生成的代码
- 文件路径：path/to/file.py
- 生成时间：2026-02-23
- 工具名称：doc-accurate-codegen

## 文档来源
1. OpenClaw 工具文档：/docs/tools/exec.md
2. API 参考文档：https://docs.example.com/api
3. 示例代码：/examples/exec-usage.py

## 校验结果
- ✅ 方法名已校验
- ✅ 参数已校验
- ✅ 返回类型已校验
- ✅ 错误处理已校验

## 备注
- 使用 exec 工具的沙箱模式
- 所有参数均来自官方文档
- 错误处理依据 API 参考文档

输出模板

生成代码时，必须包含以下内容：

# 生成代码时参考了文档
# 来源: [文档 URL 或路径]
# 验证时间: [时间戳]
# API 版本: [如有可用版本]

def 函数名():
    """
    [来自实际文档的文档字符串]

    来源: [文档链接]
    参数: [来自文档]
    返回值: [来自文档]
    """
    # 使用实际 API 实现
    pass

最佳实践

1. 始终以文档为先 —— 未加载文档绝不生成代码
2. 精确匹配 —— 使用文档中完全一致的名称、类型、格式
3. 全面验证 —— 检查所有生成的代码
4. 追踪来源 —— 记录所使用的文档
5. 真实调用 API —— 实际运行代码以验证
6. 定期更新 —— 随着 API 变化重新检查文档
7. 错误处理 —— 包含文档中列出的所有错误情况
8. 示例参考 —— 引用文档中的有效示例

常见陷阱

1. 假设 API 稳定 —— API 会变化，始终重新检查文档
2. 依赖记忆而非文档 —— 相信文档，而非记忆
3. 仅加载部分文档 —— 加载完整的文档内容
4. 缺乏验证 —— 总是验证生成的代码
5. 缺少来源记录 —— 始终追踪文档来源

成功指标

• 幻觉率: 0%（所有代码均基于实际文档）
• 验证率: 100%（所有代码均已验证）
• 来源追踪率: 100%（所有代码均有文档来源）
• 错误率: 0%（无 API 使用错误）
• 测试通过率: 100%（所有生成代码均可正常运行）

高级功能

1. 自动文档加载

• 识别所需 API
• 自动获取相关文档
• 缓存以供后续使用

2. API 变更检测

• 监控文档变化
• 发现 API 变更时发出提醒
• 提供代码更新建议

3. 多源验证

• 交叉比对多个文档来源
• 检测不同来源之间的冲突
• 采用最权威的来源

4. 示例提取

• 从文档中提取可运行的示例
• 根据需求调整示例
• 在使用前测试示例

与 OpenClaw 的集成

工具文档

# 获取工具帮助
exec("tool --help")

# 读取工具文档
read("openclaw/docs/tools/tool-name.md")

# 检查工具示例
read("openclaw/examples/tool-usage.md")

技能文档

# 读取技能文档
read("skills/skill-name/SKILL.md")

# 检查技能示例
read("skills/skill-name/examples/")

配置文档

# 读取配置文档
read("openclaw/docs/configuration.md")

# 检查配置示例
read("openclaw/examples/config/")

注意：此技能存在的原因在于大模型容易产生幻觉。生成代码时必须始终使用此技能。防止错误的唯一方法是引用实际文档。