工程实践

起因 前几天，Karpathy 发了一条推。 他讲自己怎么用 LLM 管个人知识库，用了一个词：编译（Compile）。意思是，把原始资料"编译"成结构化知识。Obsidian Vault 是代码仓库，LLM 就是编译器。 我看完愣了一下——这不就是我最近几个月一直在折腾的事吗？我一直在做一个流程，把 raw 资料变成 wiki 条目，只是一直没找到一个好的词来概括。现在有了：知识编译。 然后我就做了一个程序员会做的事：把它做成了 Obsidian 插件。 思路 传统管理知识库的方式，大家应该都不陌生：你积累了 500 篇笔记，然后加标签、建链接、分类整理，再然后……三个月后放弃了，笔记库慢慢腐烂。 编译方式不一样。你只管把原始资料丢进 raw/ 目录，LLM 负责读取、提炼、交叉引用，自动产出结构化的 wiki 页面。你只需要做两件事：喂料，提问。 这跟写代码一模一样。raw/ 是源码，wiki/ 是编译产物，index.md 是目录清单，log.md 是构建日志，编译器是 LLM。你不会手动把 .java 文件逐行翻译成 .class——同理，你也不应该手动给 500 篇笔记加标签。 三层目录，各管各的 先看一下目录结构： Vault/ ├── raw/ # 原始资料，人类添加，LLM 自动归类 │ ├── tech/ # 技术文章、论文、教程 │ ├── work/ # 工作相关文档 │ ├── reading/ # 读书笔记、播客笔记 │ ├── general/ # 其他内容 │ └── assets/ # 图片附件 │ ├── wiki/ # 编译产物，完全由 LLM 维护 │ ├── summaries/ # 每篇源文件的结构化摘要 │ ├── concepts/ # 概念页面（跨源综合） │ ├── entities/ # 人物/工具/框架页面 │ ├── comparisons/ # 对比分析 │ └── analysis/ # 深度分析（从好的问答中沉淀） │ ├── legacy/ # 已有的旧笔记库，冻结存档 ├── drafts/ # 碎片想法，人类专属 ├── CLAUDE.md # LLM 的"编译规范" ├── index.md # Wiki 主索引 └── log.md # 操作日志 我定了一个很严格的 ownership 规则： ...

一、引言 最近在用 OpenAI 的 Codex APP，官方发布了一份最佳实践指南。我仔细读了一遍，发现里面有很多实用的建议，特别是对于那些刚开始用 AI 编程工具的人。 总结整理了一下这些经验，分享给大家。如果你也在用 Codex（对于其它AI 编程工具也适用），或者对 AI 编程感兴趣，这篇文章应该能帮到你。 二、核心四要素 .webp) 想让 Codex 准确完成任务，每次提问最好包含这四个部分： 目标：你要改什么或建什么 上下文：相关文件、文档、错误信息（用 @ 提及） 约束：代码规范、安全要求、团队约定 完成标准：测试通过、行为改变、bug 复现消失 任务越复杂，越要提供详细信息。一次说清楚，可以减少很多返工。 三、七个实用技巧  1. 复杂任务先规划 遇到复杂或模糊的任务，先让 Codex 做规划再动手。 可以用 /plan 模式，让它先问清问题再执行。如果你只有个大致想法，可以让它先采访你，把模糊的想法变得具体。 对于大型项目，可以用 PLANS.md 模板来管理（建议使用 planning-with-files skill） 。 2. 创建 AI 使用说明书 可以使用 /init 命令初始化 AGENTS.md 文件，然后再根据自己的需要更新。 在项目中创建 AGENTS.md 文件，写上： 项目结构和重要目录 运行、构建、测试命令 代码规范和审查标准 “完成"的定义 这样 Codex 会自动读取，不用重复说明。 3. 配置个人设置 在 ~/.codex/config.toml 中设置： ...

在使用大模型的过程中，你肯定发现目前的大语言模型（LLM）在逻辑推理、代码编写和文本生成方面表现优异。但是，它们都有一个共同的局限：无法直接干预外部世界。 如果你要求模型“查询订单状态”或“发送一封邮件”，它通常会回复：“对不起，我无法访问您的数据库。”这是因为模型本质上只是一个预测下一个 Token 的概率模型，并没有直接访问系统资源的权限。 Tool Call（工具调用，也称 Function Calling）的出现，正是为了给模型安装上“手脚”，让它能够通过结构化的方式与外部系统交互。 ## 一、 核心概念：决策与执行分离  理解 Tool Call 的关键在于：模型本身并不执行代码，它只负责决策。 我们可以将其理解为“指挥官”与“执行官”的关系： 模型（决策者）：负责判断“当前需要调用哪个工具”、“需要传入什么参数”。 程序（执行者）：负责运行真实的后端逻辑，如数据库查询、发送邮件、鉴权、限流等。 这种“决策与执行分离”的架构，确保了系统的安全性。模型产生的只是一个 JSON 格式的调用指令，真正的执行权限始终掌握在开发者手中，而不是交给模型。 二、 通用工作流 无论是查询数据（读操作）还是执行动作（写操作），在工程上通常遵循以下五个步骤： 定义工具：开发者向模型描述可选工具的功能（建议使用动词命名，如 get_order_status）及其参数规格（使用 JSON Schema）。 发送上下文：将用户问题与工具清单一并发送给模型。 模型决策：模型判断当前问题是否需要工具。如果需要，它会返回一个结构化的响应，包含工具名、参数及唯一标识符 call_id。 本地执行：程序解析参数，调用真实的 API 或数据库，并获取结果。 生成回答：程序将执行结果回传给模型，模型结合结果生成最终的自然语言回复。 三、 Tool Call Schema 详解 Schema 是模型与程序之间的“契约”。定义得越严谨，模型调用的准确率就越高。 1. 结构示例 { "type": "function", "function": { "name": "get_order_status", "description": "根据订单号查询订单状态与物流信息", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单号，例如 1001" } }, "required": ["order_id"], "additionalProperties": false }, "strict": true } } 2. 字段含义与最佳实践 字段 说明 最佳实践 name 工具的唯一标识符 使用动词式命名，如 get_order_status description 工具的用途说明 越详细越好：说明适用场景、限制条件及返回格式 parameters 参数定义 每个参数都应包含 type 和 description required 必填参数名数组 明确模型必须提供的字段 additionalProperties 额外参数 设为 false，防止模型生成多余参数 strict 严格模式 设为 true，强制模型输出符合 Schema 的 JSON 3. 一个“好”的描述长什么样 差的描述： ...