Claude Code 使用笔记

安装 Claude Code # macOS 用 brew 安装(推荐) brew install --cask claude-code # 或安装最新版 brew install --cask claude-code@latest # 用 npm 安装 npm install -g @anthropic-ai/claude-code 安装 cc-switch(多账号切换工具) brew install --cask cc-switch 安装后从 Launchpad 或用以下命令启动: open -a cc-switch 认证冲突处理 cc-switch 会设置 ANTHROPIC_AUTH_TOKEN 环境变量,若同时存在 claude /login 的 key,启动时会出现: ⚠ Auth conflict: Both a token (ANTHROPIC_AUTH_TOKEN) and an API key (/login managed key) are set. 想用 cc-switch 管理的账号: claude /logout 想用 /login 的 key: ...

Created 20206-04-20 · Updated 17176-10-17 · 8 min · 1585 words · -

Switching Cursor Pro to The X Subscription: Cursor 老用户的首年折扣

我之前订阅的是 Cursor Pro,每月 20 美元。2026 年 10 月 12 日,X 推出了统一订阅(The X Subscription),把 X Premium、Grok(SuperGrok)和 Cursor 合到了一个订阅里。我把 Cursor Pro 转成了统一订阅的 Premium 档。 同样是 Premium 年付,从 Cursor 那边转过去,首年约 16 美元/月;直接在 X 或 grok.com 上订,是 25 美元/月。这是给 Cursor 老用户的首年折扣,从 X 那边看不到。 为什么要换 我想要 X 的蓝 V(Premium checkmark),用来推广自己的产品 ENX。 写代码我主要用 Claude 的订阅,Cursor 用得不多,所以统一订阅里 Cursor 不包含 Claude 用量这一点,对我影响不大。 原来 Cursor Pro 一年 240 美元,统一订阅 Premium 年付原价 300 美元,多 60 美元,多出来的是 SuperGrok 和 X Premium+ 的权益。 统一订阅的档位 X 页面(x.com/i/premium_sign_up)上的年付价格: ...

Created 16166-10-16 · Updated 16166-10-16 · 2 min · 321 words · -

Loop Engineering:让 Agent 循环到可验证的完成状态

什么是 Loop Engineering Loop Engineering 是 2026 年上半年在 AI Agent 圈子里逐渐流行的说法。它的核心思路是:与其由人逐步编写 Prompt、检查结果、再发出下一条指令,不如先设计一个自动循环系统,明确目标、检查方式和停止条件,让 Agent 按照「感知 → 行动 → 观察 → 再决策」的过程反复迭代,直到任务达到可验证的完成状态。 每个 Agent 本质上都运行在某种循环中。Loop Engineering 关注的是有意识地设计这个循环,包括:Agent 每轮能看到什么、可以执行什么操作、如何取得反馈、谁负责判断完成,以及什么情况下必须停止。 这个模式可以追溯到 ReAct(Reason + Act)范式:模型推理后采取行动,再根据环境返回的观察结果继续推理。Loop Engineering 将这种「推理—行动—观察—重复」的过程扩展为可控制、可验收的工程流程。 与 Prompt Engineering 的区别 维度 Prompt Engineering Loop Engineering 人的工作 编写当前这一步的指令 设计目标、反馈、验证和停止条件 执行方式 通常是一次或少量交互 自动进行多轮迭代 完成判断 人或执行任务的模型临场判断 预先定义的检查器或验收条件 适用场景 问答、生成单个结果、短任务 自动代码生成、软件维护、多步骤自主任务 两者不是替代关系。清晰的 Prompt 仍然是循环中每一步的输入;Loop Engineering 解决的是如何让这些步骤持续运行,并在正确的时机停下来。 一个循环需要哪些部分 一个可用的 Loop 通常包含以下要素: 目标:最终需要达到的状态,而不只是要执行的动作。 行动范围:Agent 可以读取、修改和执行哪些内容。 反馈:测试、构建、CI、部署状态或其他环境输出。 完成条件:可以重复执行并得到明确结果的验收检查。 状态:跨轮次保存的需求、进度、失败摘要和已完成事项。 停止条件:成功、达到最大轮次、超时或遇到不可恢复错误。 完成条件应尽量由测试退出码、构建结果、文件状态等客观信号表达,而不是让 Agent 根据自己的回答判断「应该已经完成」。这也是 Harness Engineering 能为 Loop 提供的关键能力:Loop 决定继续还是停止,Harness 提供可重复的验收信号。 ...

Created 31316-07-31 · Updated 2026-09-02 · 2 min · 412 words · -

Matt Pocock 的 Agent Skills 与 Loop Engineering

这套 skills 是什么 Matt Pocock(Total TypeScript / aihero.dev 作者)公开了一套面向 AI 编码的 Agent Skills 集合,本质是一组 SKILL.md 文件,把「从想法到上线」的工程流程拆成若干可被 Agent 按需加载的步骤。它不是某个 IDE 插件,而是一批可以装进 Claude Code(或其他支持 skill 的 harness)的流程说明。 装好之后目录大致是这样:~/.claude/skills/ 下一批软链接指向实际的 skill 仓库;setup-matt-pocock-skills 是每个仓库跑一次的前置配置(约定 issue tracker、triage 标签、文档布局);ask-matt 是一个路由 skill,用来在记不清该用哪个流程时反查。 主流水线:idea → ship 大部分工作走这一条线: grill-with-docs:用连续追问把模糊的想法逼清楚,过程沉淀进 CONTEXT.md 和 ADR。没有工作目录时用 grill-me(无状态版)。 如果有些问题必须靠能跑的代码才能回答(状态、业务逻辑、要看的 UI),绕道 prototype 写一份一次性代码,用 handoff 在会话之间传递结论。 多会话构建:to-spec 把对话变成 spec,to-tickets 拆成一批 tracer-bullet ticket,每个声明自己的阻塞边;然后逐个 implement,ticket 之间清空上下文。单会话能做完就直接 implement。 implement 内部驱动 tdd(一次一个红-绿切片),收尾跑 code-review(Standards + Spec 两轴审查)再提交。 匝道和支线:bug 和请求堆积走 triage;线上出问题走 diagnosing-bugs(坚持先有一个已经变红的命令再谈修复);大到一个会话装不下的模糊工程走 wayfinder(先画决策地图,产出决策而非交付物,再汇入 to-spec)。 ...

Created 2026-09-02 · Updated 2026-09-02 · 2 min · 264 words · -

Graph Engineering:Python + LangGraph + Claude Code

从 Prompt 到 Graph AI 驱动开发大致走过几条主线:Prompt Engineering 解决「怎么说清楚」;Context Engineering(含 RAG)解决「给模型看什么」;Loop Engineering 解决「让 Agent 自我修正」——给一个任务,改代码、跑测试,失败了再继续修。 复杂业务里,单 Agent 的 Prompt Loop 很快会顶到天花板。Graph Engineering(图工程)把流程拆成有向图:节点专职分工,边负责确定性控制流,AI 只承担局部推理与代码生成。下面按「为什么需要 → 怎么划职责 → 怎么落地」写一版可落地的骨架。 不想额外起 Python 主控、只在 Claude Code 里管多阶段任务时,见 Graph Engineering:纯 Claude Code 实现。 为什么需要 Graph Engineering Loop Engineering 在「单任务、短轮次」时很好用。一旦任务变长、角色变多,常见会撞上三类问题。 上下文污染(Context Pollution) 循环次数上去后,会话里堆满历史报错、半成品 diff、无效尝试。模型要在噪声里找有效信号,表现会越来越差:重复改同一处、忽略刚写过的约束、或「修 A 弄坏 B」。根因往往不是模型突然变笨,而是上下文被污染了。 缺乏确定性控制(Nondeterminism) 若下一步完全由 LLM 在 Context 里自行决定,容易陷入死循环:同一失败路径反复尝试,或越改越散。控制流(何时重试、何时换策略、何时中止)若也交给模型,系统就缺少可预期的停机条件。 职责模糊 让同一个 Agent 同时做架构规划、写前后端、跑单测、做 Code Review,等于把多种能力边界揉进一次长会话。结果常常是:规划被实现细节冲淡,实现被 review 口径扯偏,测试结论又被前序噪声干扰。 Graph Engineering 的应对方式很直接:用有向图把复杂流程解耦为专职节点(Nodes);把控制流交还给确定性的代码(Edges);只把局部推理与代码生成交给 AI。 Graph Engineering 在说什么 可以把它看成三层分工: ...

Created 24246-07-24 · Updated 30306-07-30 · 2 min · 330 words · -

Graph Engineering:纯 Claude Code 实现

这篇写什么 Graph Engineering 的完整落地通常是:Python + LangGraph 当指挥官,Claude Code 当执行者,pytest 一类命令当 quality gate。有时不想额外起一个 Python 主控进程,只想在 Claude Code 里把一段有依赖关系的多阶段任务当图来管。 本文只写这条路径:控制流、节点隔离、跨节点状态都尽量落在 Claude Code 自带能力或手工骨架上,不接 LangGraph。图工程「为什么需要」以及三层分工的完整论述见母文;这里默认读者已经接受「用有向图拆专职节点、把控制流从 Prompt 里抽出来」这一目标。 能落地到两种深度,选哪种取决于要不要付节点隔离和显式状态的成本。 轻量方案:任务队列当 DAG DAG(Directed Acyclic Graph,有向无环图)说的是:节点之间有方向(A 依赖完成后才能做 B),但不能成环(不能出现 A → B → A,否则永远等不到起点)。任务列表里的「阻塞 / 被阻塞」关系正好就是这种结构——依赖边把阶段串成可调度的顺序,而不是随便挑一个未完成任务开干。 Claude Code 自带的任务系统(创建 / 更新 / 列出任务)可以把每个阶段建成一个节点,用「阻塞 / 被阻塞」关系显式建边,状态走 pending → in_progress → completed;某个节点的依赖没完成前,它不会出现在「可执行」列表里,相当于用依赖门控替代了「下一步该做什么」的临时判断。 执行仍然发生在同一个会话、同一段上下文里:Agent 顺着依赖关系挑下一个已解锁的节点,直接实现,完成后回写状态,再挑下一个。没有节点隔离,也没有单独的图执行器在跑——图的推进是模型手动读状态、手动调用更新接口完成的,不是由代码在每一步自动求值条件边。跨节点的「状态」也不是一个结构化的 state 对象,只是任务列表里的标题 / 描述 / 状态字段,加上还留在同一段对话历史里的实现细节。 适合依赖关系不复杂、能在一次会话内跑完、不需要严格隔离上下文的多阶段任务——比如按一份规格文档的实现顺序逐节点推进。 示意如下: Claude Code 单会话 +------------------------------------------+ | Task list (DAG) | | A ──► B ──► C | | pending / in_progress / completed | +------------------------------------------+ | | 同一对话上下文里依次执行 v 实现 → 回写任务状态 → 挑下一个已解锁节点 重量方案:子代理 + 独立工作树 + 显式状态文件 如果需要的是真正的节点隔离,通常要在 Claude Code 里手工搭三件东西: ...

Created 30306-07-30 · Updated 30306-07-30 · 2 min · 235 words · -

LangGraph - 构建状态化 AI 工作流的框架

什么是 LangGraph LangGraph 是 LangChain 生态系统中的一个框架,专门用于构建有状态的、多步骤的 AI 应用程序。它通过图(Graph)的方式来定义和管理复杂的 AI 工作流,让开发者能够创建具有循环、条件分支和持久化状态的智能体系统。 LangGraph 的核心理念是将 AI 应用程序建模为状态机,其中节点代表操作步骤,边代表流程控制,状态在节点之间传递和更新。 核心概念 State(状态) State 是在整个工作流中传递和更新的数据结构。通常使用 TypedDict 定义: from typing import TypedDict, Annotated from langgraph.graph import add_messages class AgentState(TypedDict): messages: Annotated[list, add_messages] user_input: str analysis_result: str Node(节点) Node 是执行具体操作的函数,接收当前状态并返回更新后的状态: def research_node(state: AgentState): # 执行研究任务 result = do_research(state['user_input']) return { "analysis_result": result, "messages": [("assistant", f"研究完成:{result}")] } Edge(边) Edge 定义节点之间的连接关系: Normal Edge(普通边):直接连接两个节点 Conditional Edge(条件边):根据状态决定下一个节点 from langgraph.graph import StateGraph, END # 普通边 workflow.add_edge("node_a", "node_b") # 条件边 def should_continue(state): if state['done']: return END return "continue_node" workflow.add_conditional_edges( "decision_node", should_continue ) Graph(图) Graph 是完整的工作流定义,包含所有节点、边和状态管理: from langgraph.graph import StateGraph workflow = StateGraph(AgentState) # 添加节点 workflow.add_node("research", research_node) workflow.add_node("analyze", analyze_node) workflow.add_node("respond", respond_node) # 定义边 workflow.add_edge("research", "analyze") workflow.add_edge("analyze", "respond") # 设置入口点 workflow.set_entry_point("research") # 编译图 app = workflow.compile() 核心特性 1. 状态持久化 LangGraph 支持状态的持久化存储,可以实现: ...

Created 18186-01-18 · Updated 26266-07-26 · 5 min · 989 words · -

LangChain

LangChain 详解 什么是 LangChain LangChain 是一个用于构建基于大语言模型(LLM)应用的开源框架。它提供了一套标准化的组件和工具,简化了 AI Agent、聊天机器人、问答系统等应用的开发过程。 核心理念:通过"链(Chain)“将多个组件连接起来,构建复杂的 LLM 应用。 官方仓库: Python:langchain-ai/langchain JavaScript/TypeScript:langchain-ai/langchainjs 核心组件 1. Models(模型) 支持多种 LLM 提供商: from langchain.llms import OpenAI, Anthropic, HuggingFaceHub from langchain.chat_models import ChatOpenAI, ChatAnthropic # OpenAI llm = OpenAI(temperature=0.7) # Claude chat = ChatAnthropic(model="claude-3-sonnet-20240229") # 本地模型 from langchain.llms import Ollama local_llm = Ollama(model="llama2") 2. Prompts(提示模板) 管理和复用提示词: from langchain.prompts import PromptTemplate, ChatPromptTemplate # 简单模板 prompt = PromptTemplate( input_variables=["product"], template="给{product}写一个广告语" ) # 聊天模板 chat_prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个{role}"), ("human", "{user_input}") ]) # 使用 formatted = prompt.format(product="智能手表") result = llm(formatted) 3. Chains(链) 将多个组件串联: from langchain.chains import LLMChain, SimpleSequentialChain # 单个链 chain = LLMChain(llm=llm, prompt=prompt) result = chain.run(product="智能手表") # 顺序链 chain1 = LLMChain(llm=llm, prompt=prompt1) # 生成产品描述 chain2 = LLMChain(llm=llm, prompt=prompt2) # 生成广告语 overall_chain = SimpleSequentialChain( chains=[chain1, chain2], verbose=True ) result = overall_chain.run("智能手表") 4. Agents(代理) 动态决策和工具调用: ...

Created 26266-04-26 · Updated 26266-07-26 · 5 min · 901 words · -

LangSmith - LLM 应用的可观测性平台

什么是 LangSmith LangSmith 是 LangChain 团队推出的 LLM 应用可观测性与评估平台,用于追踪(trace)、调试、测试和监控基于 LLM 的应用。它不要求应用一定使用 LangChain 或 LangGraph 构建——任何调用 LLM 的代码都可以接入 LangSmith,但与 LangChain / LangGraph 的集成是开箱即用的。 核心定位:LLM 应用的"生产环境可观测性 + 离线评估"工具,解决 LLM 应用调试困难、行为不透明、质量难以量化的问题。 官方仓库 / 产品:langchain-ai/langsmith-sdk(SDK 开源,平台本身为托管 SaaS,也提供自托管方案)。 为什么需要 LangSmith 传统软件的日志和监控体系(APM、ELK 等)不足以覆盖 LLM 应用的调试需求: 多步骤链路不透明:一次 Agent 调用可能包含多次 LLM 请求、工具调用、检索操作,普通日志难以还原完整调用树 Prompt 调试依赖人工:Prompt 的微小改动可能显著影响输出质量,缺乏系统化的对比手段 输出质量难以量化:LLM 输出是非确定性的自然语言,传统的断言测试不适用 成本和延迟不可见:Token 消耗、模型延迟分散在各次调用中,难以聚合分析 LangSmith 针对这些痛点提供了追踪、数据集管理、评估和监控能力。 核心功能 1. Tracing(追踪) 记录一次请求内所有 LLM 调用、工具调用、检索操作的完整调用树,包括输入、输出、耗时、Token 用量。 import os os.environ["LANGCHAIN_TRACING_V2"] = "true" os.environ["LANGCHAIN_API_KEY"] = "your-api-key" os.environ["LANGCHAIN_PROJECT"] = "my-project" # LangChain / LangGraph applications are traced automatically # once the environment variables above are set from langchain_openai import ChatOpenAI llm = ChatOpenAI(model="gpt-4") result = llm.invoke("Explain what LangSmith does") 对于不使用 LangChain 的代码,可以用 @traceable 装饰器手动接入: ...

Created 26266-07-26 · Updated 26266-07-26 · 2 min · 345 words · -

VSCode Copilot Model Bridge: 扩展桥接模型

VSCode 扩展桥接 Copilot 模型 通过 VSCode 扩展可以将 GitHub Copilot 中的 Claude 模型桥接出来,供外部 AI Agent 调用。这种实现方式主要基于以下技术方案: 实现原理 VSCode Extension API 使用 VSCode 扩展开发框架创建自定义扩展 通过 vscode.languages 和 vscode.commands API 注册命令和服务 利用 Language Server Protocol (LSP) 实现与外部通信 GitHub Copilot API 调用 扩展内部通过 Copilot 的内部 API 访问 Claude 模型 使用 vscode.authentication 获取 GitHub 认证令牌 调用 Copilot Chat API 发送请求并接收响应 MCP (Model Context Protocol) 服务器 在扩展中实现 MCP 服务器,暴露标准化的接口 MCP 定义了统一的消息格式和通信协议 支持通过 stdio、HTTP 或 WebSocket 与外部 Agent 通信 核心实现步骤 创建 VSCode 扩展 // extension.ts import * as vscode from 'vscode'; export function activate(context: vscode.ExtensionContext) { // 启动 MCP 服务器 const mcpServer = new MCPServer(); mcpServer.start(); // 注册命令处理 Copilot 请求 context.subscriptions.push( vscode.commands.registerCommand('extension.queryCopilot', async (prompt) => { return await queryCopilotModel(prompt); }) ); } 实现 MCP 服务器 // mcp-server.ts import { Server } from '@modelcontextprotocol/sdk/server/index.js'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; class MCPServer { private server: Server; constructor() { this.server = new Server({ name: 'copilot-bridge', version: '1.0.0' }, { capabilities: { resources: {}, tools: {}, prompts: {} } }); // 注册工具 this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [{ name: 'query_claude', description: 'Query Claude model via Copilot', inputSchema: { /* ... */ } }] })); } async start() { const transport = new StdioServerTransport(); await this.server.connect(transport); } } 桥接 Copilot API // copilot-bridge.ts async function queryCopilotModel(prompt: string) { // 获取 Copilot Chat API const copilot = await vscode.lm.selectChatModels({ vendor: 'copilot', family: 'claude' }); // 发送请求 const messages = [ vscode.LanguageModelChatMessage.User(prompt) ]; const response = await copilot[0].sendRequest(messages); // 收集响应流 let result = ''; for await (const chunk of response.text) { result += chunk; } return result; } 外部 Agent 调用 # external_agent.py from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def call_copilot_claude(prompt: str): # 连接到 VSCode 扩展的 MCP 服务器 server_params = StdioServerParameters( command="code", args=["--extensionDevelopmentPath=/path/to/extension"] ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: # 初始化连接 await session.initialize() # 调用工具 result = await session.call_tool("query_claude", { "prompt": prompt }) return result 关键技术点 认证与权限 ...

Created 26266-04-26 · Updated 23236-07-23 · 2 min · 417 words · -

Tool Calling Patterns: ReAct 与其它工具调用方式

其他意图识别与工具调用方式 除了传统的 Slot Filling 和现代的 Function Calling,AI Agent 还有多种实现意图识别和工具调用的方式,各有特点和适用场景。 1. ReAct(Reasoning + Acting) ReAct 是一种让 LLM 交替进行推理(Reasoning)和行动(Acting)的方法,通过思维链(Chain of Thought)引导 LLM 一步步分析问题并选择工具。 工作原理 用户输入 → LLM 推理(Thought) → 决定行动(Action) → 执行工具 → 观察结果(Observation) → 继续推理 → ... 实现示例 react_prompt_template = """ 你是一个智能助手,可以使用以下工具: 1. search(query): 搜索信息 2. calculate(expression): 计算数学表达式 3. get_weather(city): 查询天气 请按以下格式回答: Thought: [你的思考过程] Action: [工具名称] Action Input: [工具参数] Observation: [工具返回的结果] ... (重复 Thought/Action/Observation 直到得出答案) Answer: [最终答案] 问题:{question} """ # 用户问题:"北京明天的天气适合户外活动吗?" # LLM 输出: """ Thought: 我需要先查询北京明天的天气 Action: get_weather Action Input: {"city": "北京", "date": "明天"} Observation: 明天北京天气:晴,温度 22°C,微风 Thought: 根据天气信息,晴天、温度适中、微风,非常适合户外活动 Answer: 根据天气预报,北京明天天气晴朗,温度 22°C,微风,非常适合户外活动。 """ 优势 可解释性强:每一步推理过程都清晰可见 灵活性高:LLM 可以动态调整策略 支持复杂任务:可以进行多步推理和工具调用 劣势 Token 消耗大:每次推理都需要完整的对话历史 速度较慢:需要多次 LLM 调用 格式依赖:依赖 LLM 严格遵循输出格式 2. Prompt-based Tool Selection(基于提示的工具选择) 通过精心设计的 Prompt 让 LLM 直接输出工具调用的 JSON 或结构化文本。 ...

Created 26266-04-26 · Updated 23236-07-23 · 6 min · 1195 words · -

Output Constraint: LLM 输出约束

Output Constraint(输出约束) Output Constraint 是通过提示词、格式规范或模型能力,对 LLM 的输出内容、结构、长度、风格等进行约束,使输出结果可预期、可解析、可被下游系统直接消费的一类技术。 在 AI Agent 场景中,输出约束尤为重要——Agent 的输出往往需要被代码解析、传递给下一个工具,或渲染到 UI,任何格式偏差都可能导致流程中断。 约束维度 维度 说明 示例 格式约束 要求输出为特定结构 JSON、XML、Markdown 表格、YAML 内容约束 限定输出范围或值域 只能从给定选项中选择、不得包含某类内容 长度约束 限制输出的字数或条数 “不超过 100 字”、“恰好输出 3 条建议” 风格约束 限定语气、人称、语言 正式/口语、中文/英文、第一人称 Schema 约束 强制输出符合 JSON Schema 字段类型、必填项、枚举值 方式一:提示词约束(Prompt-based) 最简单直接的方式,在 System Prompt 或 User Prompt 中明确描述输出格式: system_prompt = """ 你是一个情感分析助手。 输出要求: - 只输出 JSON,不要有任何额外文字 - 格式如下: { "sentiment": "positive" | "negative" | "neutral", "confidence": 0.0 ~ 1.0, "reason": "简短理由(不超过 20 字)" } """ response = llm.call(system_prompt, user_input="这个产品真的太好用了!") # 输出:{"sentiment": "positive", "confidence": 0.95, "reason": "用户使用了强烈的赞美语气"} 优点:通用,任何模型都支持 缺点:无法 100% 保证格式,模型偶尔会"越界" ...

Created 26266-04-26 · Updated 23236-07-23 · 2 min · 316 words · -

LlamaIndex

LlamaIndex 详解 什么是 LlamaIndex LlamaIndex(原名 GPT Index)是一个专注于数据连接和检索的开源框架,主要用于构建 RAG(检索增强生成)应用。与 LangChain 相比,LlamaIndex 更专注于数据索引、检索和查询,是构建知识库和文档问答系统的首选工具。 核心定位:数据框架(Data Framework for LLM Applications) 官方仓库:run-llama/llama_index 设计哲学: LangChain:通用的 LLM 应用框架(Chain、Agent、Memory 等) LlamaIndex:专注于数据摄入、索引和检索 ⚠️ 名称说明:LlamaIndex vs Llama2 重要澄清:LlamaIndex 与 Meta 的 Llama2/Llama3 开源模型没有任何关系,它们是完全独立的项目: 项目 类型 开发者 功能 LlamaIndex 开发框架 LlamaIndex 团队(原 run-llama) 数据索引和检索框架 Llama2/Llama3 大语言模型 Meta(Facebook) 开源 LLM 模型 为什么叫 “Llama”? LlamaIndex 的命名来自"Large Language Model Applications"的缩写 与 Meta 的 Llama 模型纯属巧合(命名冲突) 实际关系: LlamaIndex 框架可以使用 Llama2/Llama3 作为底层 LLM 但 LlamaIndex 也支持 OpenAI、Claude、Gemini 等任何 LLM 两者是"框架"与"模型"的关系,而非从属关系 示例: ...

Created 26266-04-26 · Updated 23236-07-23 · 5 min · 1040 words · -

Intent Recognition and Slot Filling: 意图识别与槽位填充

AI Agent 的意图识别与工具调用 AI Agent 的一个核心应用场景是自然语言理解 → 意图识别 → 工具调用。这本质上是一个分类问题,即将用户的自然语言输入分类到不同的意图类别,然后路由到相应的工具执行具体任务。 固定 FAQ、按钮选项等不必每次都调大模型:见 Agent Token Routing(本地匹配 → 轻量分类 → 缓存 → LLM)。 工作流程 自然语言理解(NLU) 用户输入:自然语言查询或指令 Agent 使用 LLM 理解语义和上下文 意图识别(Intent Recognition) LLM 的核心作用:理解自然语言并映射到预定义的意图分类 将用户输入分类到预定义的意图类别 例如:查询天气、预订餐厅、发送邮件、查询数据库等 这是一个多分类任务 参数提取(Slot Filling) LLM 的第二个作用:从自然语言中提取关键参数供工具使用 从用户输入中提取关键参数 例如:“明天北京的天气” → 时间=明天, 地点=北京 LLM 能理解各种自然语言表达方式并提取结构化参数 工具调用(Tool Calling) 根据识别的意图,调用对应的预开发工具或函数 传递提取的参数给工具 获取工具执行结果 结果组织与返回 将工具返回的结果组织成自然语言 返回给用户 实现示例 # 意图识别与工具调用示例 class IntentBasedAgent: def __init__(self, llm): self.llm = llm self.tools = { "weather": get_weather_tool, "email": send_email_tool, "database": query_database_tool, "calendar": schedule_meeting_tool } async def process(self, user_input: str): # 1. 意图识别(分类) intent_prompt = f""" 分析用户意图,返回意图类别和参数: 用户输入:{user_input} 可选意图:weather, email, database, calendar 返回 JSON 格式:{{"intent": "...", "params": {{...}}}} """ response = await self.llm.query(intent_prompt) intent_data = json.loads(response) intent = intent_data["intent"] params = intent_data["params"] # 2. 根据意图调用相应工具 if intent in self.tools: tool = self.tools[intent] result = await tool(**params) return result else: return "抱歉,我无法理解您的意图" # 使用示例 agent = IntentBasedAgent(llm) # 用户输入:"查询明天北京的天气" # 意图识别结果:intent="weather", params={"date": "明天", "city": "北京"} # 调用工具:get_weather_tool(date="明天", city="北京") 意图识别的实现方式 1. 基于 LLM 的意图识别(推荐) # 使用 Function Calling / Tool Use tools_schema = [ { "name": "get_weather", "description": "查询天气信息", "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "城市名称"}, "date": {"type": "string", "description": "日期"} } } }, { "name": "send_email", "description": "发送邮件", "parameters": { "type": "object", "properties": { "to": {"type": "string"}, "subject": {"type": "string"}, "body": {"type": "string"} } } } ] # LLM 自动识别意图并返回应调用的工具 response = llm.chat( messages=[{"role": "user", "content": user_input}], tools=tools_schema ) # LLM 返回:tool_call = {"name": "get_weather", "arguments": {"city": "北京", "date": "明天"}} 2. 传统分类模型(轻量级场景) # 使用文本分类模型 from transformers import pipeline classifier = pipeline("text-classification", model="intent-classifier") result = classifier("查询明天北京的天气") # 输出:{"label": "weather", "score": 0.95} 3. 基于规则的意图识别(简单场景) # 关键词匹配 intent_patterns = { "weather": ["天气", "温度", "下雨"], "email": ["发邮件", "发送邮件", "写邮件"], "database": ["查询", "数据", "统计"] } def match_intent(user_input): for intent, keywords in intent_patterns.items(): if any(kw in user_input for kw in keywords): return intent return "unknown" 核心优势 解耦设计 ...

Created 26266-04-26 · Updated 23236-07-23 · 4 min · 765 words · -

Function Calling: LLM 函数调用

Function Calling(函数调用)详解 Function Calling 是现代大语言模型(如 GPT-4、Claude)提供的一项高级能力,允许 LLM 自动识别用户意图、提取参数,并生成标准化的函数调用请求。它是 AI Agent 实现工具调用的最先进方式。 什么是 Function Calling Function Calling 是 LLM 的一种特殊输出模式:不是直接返回文本,而是返回一个结构化的函数调用指令,包含: 要调用的函数名称 函数所需的参数(JSON 格式) 核心流程: 用户输入 → LLM 分析 → 返回函数调用指令 → 执行函数 → 返回结果 → LLM 生成自然语言响应 Function Calling vs 传统 Slot Filling 传统 Slot Filling 的局限 需要多步处理 步骤1:意图识别(调用一次 LLM) 步骤2:参数提取(再调用一次 LLM 或使用 NER) 步骤3:手动组装函数调用 容易出错 意图识别可能不准确 参数提取可能遗漏或错误 需要额外的数据验证逻辑 开发成本高 需要编写意图识别逻辑 需要编写参数提取和验证代码 需要维护多个处理步骤 Function Calling 的优势 一步到位 用户输入 → LLM → 直接返回完整的函数调用(包含意图和参数) 内置验证 ...

Created 26266-04-26 · Updated 23236-07-23 · 3 min · 636 words · -

Chain of Thought (CoT): 思维链

思维链(Chain of Thought,CoT) CoT 是 Chain of Thought(思维链)的缩写。 思维链是一种让大语言模型在给出最终答案之前,先逐步输出中间推理过程的提示技术,是 ReAct、Tree of Thoughts 等众多 Agent 推理框架的基础。 用一句话概括:思维链就是通过提示词告诉模型"先把推理步骤写出来,再给结论"。 一个直观的比喻:就像项目管理里不直接说"把产品做出来",而是拆成"需求 → 设计 → 开发 → 测试 → 上线"这几个里程碑节点——CoT 提示词做的就是这件事:告诉模型"达到最终答案之前,先经过哪几个中间节点"。模型拿到这些节点后,自己填充每个节点之间的具体内容,而不是直接跳到终点。里程碑节点越清晰合理,模型走偏的概率就越低。 CoT 是提示词概念还是模型推理概念 CoT 同时横跨两个层面,两者不可分离: 提示词层面:在提示词里给出推理结构框架(先分析已知条件、再逐步推理、最后给结论),但不需要也不可能提前写出每一步的具体内容 模型推理层面:模型接收到结构约束后,在逐 token 生成 response 的过程中自己填充每一步的具体内容 关键在于:LLM 是逐 token 生成的,每生成一个 token 都会参考前面所有已输出的内容。写出推理步骤不是推理完成后的附加结果,而是推理本身的载体: 写出"步骤 1:..." → 这段文字进入上下文 ↓ 生成"步骤 2:..."时参考步骤 1 → 推理被约束在正确方向上 ↓ 生成最终结论时参考所有步骤 → 结论更准确 如果不写出步骤,中间推理只存在于模型的隐式状态(注意力权重)里,无法作为显式上下文影响后续生成,更容易偏移。 因此,CoT 的本质是:显式约束 vs 隐式依赖: 不用 CoT:完全依赖模型训练出来的内部权重,简单问题通常没问题 用 CoT:在上下文层面施加显式约束,对复杂、多步骤任务效果提升明显 CoT 的收益与任务复杂度正相关——越复杂的推理任务,CoT 的价值越显著。 ...

Created 26266-04-26 · Updated 23236-07-23 · 4 min · 713 words · -

AI agent development

AI Agent 开发的本质 开发 AI Agent 的核心是将已验证的知识和流程固化成可执行的规则和指令。 具体来说: 知识固化 - 把专家经验、最佳实践、业务规则编码成 Agent 可以遵循的指令 流程自动化 - 将重复性的决策流程转化为确定性的执行步骤 质量保障 - 通过固化的规则确保每次执行的一致性,避免人为疏忽 迭代优化 - 每次发现新问题或更好的做法,就更新这些"固化的知识",Agent 的能力随之提升 本质上是把隐性知识显性化,把经验驱动变成规则驱动。 这也意味着 Agent 的质量上限取决于你固化进去的知识质量。垃圾进,垃圾出;好的经验进,稳定的高质量输出。 为什么需要固化知识 LLM 的知识覆盖面极广,解决同一个问题可能有多条路径,但其中只有少部分是最佳实践。具体输出什么内容,很大程度上取决于提示词的质量。 把已验证的解决方案固化到 Agent 里,能让 Agent 在特定领域有更稳定、更优质的表现——相当于给 LLM 划定了一条"黄金路径",避免它在众多可能性中随机游走。 常用技术栈 编程语言 Python(主流,生态丰富) JavaScript/TypeScript(Web/Node.js Agent) Go、Java(高性能/企业级) 大语言模型与 API OpenAI GPT-4/3.5、Claude、Llama Hugging Face Transformers LangChain、LlamaIndex(Agent 框架) Web 框架与服务 FastAPI、Flask(Python) Express.js(Node.js) Django 数据存储 Redis、MongoDB、PostgreSQL、SQLite 向量数据库:Milvus、Pinecone、Weaviate 消息队列与异步任务 Celery、RabbitMQ、Kafka 容器与部署 Docker、Kubernetes 云服务:AWS、Azure、GCP 前端交互 React、Vue.js WebSocket、RESTful API 其他 Prompt 工程、工具插件系统 OAuth2、JWT(安全认证) 日志与监控:Prometheus、Grafana Python 调用模型方式 AI Agent 用 Python 开发时,可以调用本地模型或云端模型: ...

Created 26266-04-26 · Updated 23236-07-23 · 3 min · 554 words · -

Agent Token Routing: 本地匹配、缓存与模型分层

问题 聊天类 Agent 里,不少问答是相对固定的模式:营业时间、退款入口、帮助说明、菜单选项等。若一律调用大模型,既费 token,又容易把标准话术写飘。 常见做法有两种: 正则或规则匹配用户输入,命中则返回固定回答 在模型前加缓存,对特定提示词返回已有内容 这两层有用,但不够。省 token 的核心不是「再找一种缓存技巧」,而是做分层路由:能确定性处理的绝不进模型。 分层路由 用户输入 → L0 本地确定性匹配(规则 / FAQ / 按钮 / 命令) → L1 轻量意图分类(小模型 / embedding / 关键词) → L2 提示词 / 响应缓存(相同或近似请求) → L3 完整 LLM(复杂推理、开放对话、工具编排) 每一层命中就短路返回;只有前面都 miss 才往下走。 层 手段 适用场景 省什么 L0 本地匹配 正则、精确字符串、按钮 payload、slash 命令、状态机固定选项 话术固定、歧义低、可穷举 零 LLM 成本 L1 轻量分类 小分类模型、embedding 相似度、关键词 + 规则 说法多变但意图有限 用便宜模型代替大模型 L2 缓存 精确 cache key、semantic cache、prompt prefix cache 输入或 system prompt 重复率高 省重复推理 L3 LLM 完整对话 / function calling 开放问答、多步推理、需工具、强个性化 正确性优先 L0:本地匹配 适合: ...

Created 23236-07-23 · Updated 23236-07-23 · 2 min · 305 words · -

Harness Engineering 与状态锚点

什么是 Harness Engineering AI 领域的 Harness Engineering 是一种针对 AI/LLM 应用的测试评估方法论,核心思想是: 构建 eval 套件(评估集)来衡量 AI 输出质量 建立 regression 检测,防止模型更新后效果变差 用数据驱动方式持续改进 prompt 和模型选择 AI 辅助开发的语境下,Harness Engineering 的核心思想是: 用自动化验证手段构建"安全网",让你能放心接受或拒绝 AI 生成的代码,而不是靠人工肉眼审查。 harness engineering 的核心流程是: 需求(Requirements) → 明确要做什么 测试套件(Test Harness) → 先写测试,定义"完成"的标准 实现(Implementation) → 写代码让测试通过 验证(Verification) → 所有测试绿灯 Harness Engineering 是一种以"脚手架优先"为核心思想的软件开发方法,尤其在 AI 辅助开发场景下越来越受到关注。 “Harness”(脚手架/支撑框架)这个词借用自工程领域,在软件中指围绕核心系统搭建的一套结构化支撑层,包括: 明确的文档约定(说明系统当前状态、设计决策) 测试框架和实验入口(可快速验证变更) 状态记录文件(捕捉项目在某个时间点的快照) 接口契约和边界定义 它的目标是让代码库对人和 AI 助手都更"可理解、可修改、可安全演进"。 状态锚点是什么 状态锚点(State Anchor) 是 Harness Engineering 的核心实践之一。 它是一个显式的文档文件(通常命名为 harness-state.md、project-state.md 等),用来在某个时间点精确记录系统的当前状态,就像 Git commit 对代码的作用,它对"上下文"做了一次快照。 ...

Created 20206-04-20 · Updated 28286-06-28 · 3 min · 440 words · -

ADR vs Task Spec:工程文档怎么分工

一句话区别 ADR(Architecture Decision Record,架构决策记录)回答 「为什么这么定」——记录一个决策和它的理由,拍板后基本不动。 Task Spec(任务规格)回答 「要做什么、怎么做、做到什么算完」——指导一次具体落地,随实施更新,是活文档。 一个朝后看(沉淀已做的决策),一个朝前看(驱动待做的执行)。 ADR 是什么 ADR 记录一个「架构上重要」的决策:背景、考虑过的方案、最终选择、以及由此带来的后果。它的价值在于把「当初为什么选 A 而不是 B」留存下来,避免几个月后自己或他人重新踩坑、甚至无意推翻。 典型结构(Michael Nygard 的经典五段): # ADR-0001: 标题 ## 状态 Accepted / Proposed / Superseded ## 背景 什么力量/约束逼出了这个决策 ## 决策 我们选了什么 ## 后果 接受了哪些代价、带来哪些影响 关键特性: 不可变:决策变了不要改旧文件,而是新写一条 ADR,引用并标记旧的为 superseded。删除会抹掉历史,正是它要避免的。 短小:通常 200–500 字,只讲决策本身,不写实现细节。 进版本库:和代码放一起(常见 docs/adr/),让「为什么」就在工程师能找到的地方。 Task Spec 是什么 Task Spec 描述一个待完成任务的规格:目标、范围(含「不做什么」)、接口/行为契约、约束、验收标准。它是给「这次要做的事」立一个清晰的「完成」定义,让人和 AI 都按同一份契约推进。 ## 目标 实现用户登录 API ## 范围 - 包含:POST /api/login、JWT 签发 - 不包含:注册、OAuth ## 约束 - 密码不得明文记录 ## 验收 - [ ] 正确凭证返回 JWT - [ ] 错误凭证返回 401 关键特性: ...

Created 28286-06-28 · Updated 28286-06-28 · 2 min · 327 words · -