写文档防坑清单 - Lessons Learned¶
历史归档: 本文档原是 T6 SDK 手册(13 份)的系统性 API 错误清单,2026-04-10 全部修正完毕. docs/sdk/ 已于 2026-04-18 退役,由 godoc (pkgsite) 自动生成接口文档 + core/examples/ Example 函数替代. 现仅保留根因 + 写文档时的检查清单,作为未来防止文档与代码漂移的参考.
权威参考(写文档前先 grep 这些文件)¶
| 文件 | 内容 |
|---|---|
core/pkg/engine/engine.go |
Config 结构,engine.New(*Config) (*Engine, error),(*Engine).Run(ctx, prompt) |
core/pkg/flyto/events.go |
所有事件类型与字段名 |
core/pkg/flyto/provider.go |
ModelProvider 接口(只有 Name/Stream/Models 三个方法) |
core/examples/examples_test.go |
最简可运行示例 (Example_basic / Example_withPricing) |
tui/cmd/flyto/main.go |
完整入口(生产权威) |
根因¶
T6 初稿是凭印象 / 凭"AI SDK 应该长什么样"的直觉写出来的,没有 grep 真实代码. 错误模式高度系统性 -- 同一种虚构 API 在 13 个文件里反复出现:
| 类别 | 虚构形式 | 实际形式 |
|---|---|---|
| 构造函数 | engine.New(cfg) 单返回值 |
(*Engine, error) 双返回值 |
| 工具配置 | Tools: builtin.NewRegistry(...) |
Tools: []string{"Bash", "Read", ...} |
| 选项函数 | engine.WithTools(...),engine.WithProvider(...) |
不存在--一切走 Config 字段 |
| 事件字段 | TextDeltaEvent.Delta,ToolCallEvent.Tool.Name |
TextDeltaEvent.Text,ToolUseEvent.ToolName |
Run 签名 |
Run(ctx, "", WithMessages(...)) |
Run(ctx, prompt),历史由 Engine 内部维护 |
| Provider 接口 | 5+ 方法,含 Close() / DefaultModel() / 回调式 stream |
3 方法:Name() / Stream() / Models() |
所有文件已修正(13/13 ✅,2026-04-10).如果重新出现以上模式,说明又回到"凭印象写"了.
写文档的检查清单(防止重蹈覆辙)¶
- 每个代码示例先编译:把例子保存为
_example_test.go,跑go vet. - 类型字段必须 grep:写
e.SomeField之前,grep -n "SomeField" core/pkg/flyto/. - 构造函数签名必须读源:不要凭习惯写
New(cfg),先打开engine.go看返回值数. - 接口列表必须从源拷贝:
flyto.ModelProvider增删方法必须先改core/pkg/flyto/provider.go. - 价格表对照静态字面量:
docs/providers/*.md的模型表必须 1:1 对应var xxxModels = []flyto.ModelInfo{...}.
关联事故¶
- T3: 同一类型的错误--审计代码时没读真实文件,写出"P0 项目"指向不存在的函数.详见
docs/feature-audit/ERRATA.md. - T5: provider 文档静态表与代码漂移(gpt 模型缺失,Gemini 1.5 Pro 上下文窗口写错 16 倍)--修于 2026-04-11.
归档作者:Claude(主进程自主工作) 创建:2026-04-10 简化:2026-04-11(13 份原文已全部修正,删除冗余对照表)