智能体配置及使用手册¶
作者:云森
邮箱:bioinfocloud@aliyun.com
文档类型:操作手册(配置指南与参考)
适用对象:希望在本地电脑上独立完成 AI 智能体安装、模型接入与日常使用的教师、科研人员与研究生
适用范围:Windows 为主,Linux 与 macOS 的关键命令一并给出
写在前面¶
这份手册解决什么问题¶
很多人第一次接触 AI 智能体时,卡住的地方并不是"不会用",而是"装不起来"。命令行窗口里一串红色报错、API 密钥不知道去哪里申请、选好了模型却不知道填什么接口地址,这些琐碎但致命的环节,把大量初学者挡在了门外。
本手册不讨论算法原理,也不评价某款模型"好不好",它只回答一件事:如何把一套能真正干活的智能体环境,从零开始在自己的电脑上搭起来,并稳定运行下去。
手册覆盖的完整路径是:
- 理解大模型的工作原理、固有缺陷与补救办法,知道自己在跟什么样的东西打交道;
- 理解智能体的基本构成,知道自己在配置什么东西;
- 了解可用的大模型与评测榜单,能独立选型;
- 装好运行环境,拿到可用的 API 密钥;
- 安装并配置五款主流智能体产品;
- 用 CC Switch 做模型路由,让原本绑定国外模型的产品也能用上国内模型。
走完这六步,你将拥有一套"模型可换、工具可扩展、成本可控"的个人智能体工作环境。
适用对象与前置条件¶
| 项目 | 说明 |
|---|---|
| 适合的读者 | 高校教师、科研人员、研究生,以及任何需要在本地使用 AI 智能体处理文档、数据或代码的人 |
| 需要的设备 | 一台能联网的电脑,Windows 10 及以上版本,建议 8 GB 以上内存 |
| 需要的知识 | 会在电脑上打开命令行窗口,会复制粘贴,能看懂文件夹路径。不需要编程基础 |
| 需要的账号 | 至少一个大模型服务平台账号,用于申请 API 密钥 |
| 网络说明 | 部分海外服务需要相应的网络条件,手册中已标注,并给出国内替代方案 |
四条推荐阅读路径¶
| 你的情况 | 建议路径 |
|---|---|
| 完全新手,想尽快用起来 | 第 1 章 → 第 4 章 → 第 7 章 → 第 8 章 → 第 10 章(WorkBuddy),先跑通一套再回头扩展 |
| 已有密钥,想换产品或换模型 | 第 9 章选型表 → 对应产品章节 → 第 15 章 CC Switch |
| 想系统掌握并自选模型 | 按顺序通读,第 5 章与第 8 章的选型部分是重点 |
| 要用它做科研、写论文、查文献 | 第 1 章 → 第 2 章(幻觉与核验)→ 第 3 章(RAG)→ 第 9 章选型,先把可靠性问题想清楚 |
第一部分 概念基础¶
本部分不安装任何软件,只解决一个前置问题:你在配置的这些东西,彼此是什么关系,能做什么,又会在什么地方出错。把概念理清楚之后,后面所有配置项的含义都会变得直观,遇到报错也更容易判断问题出在哪一层。
四章按照"从认识一个事物到用好一个事物"的顺序排列,建议依次阅读:
| 章节 | 回答的问题 | 读完你会知道 |
|---|---|---|
| 第 1 章 大模型是怎么工作的 | 这个东西到底是什么,凭什么能回答问题 | 模型的能力从哪来,边界在哪里 |
| 第 2 章 幻觉 | 它在什么地方会骗人 | 哪些输出不能信,怎么快速识别与核验 |
| 第 3 章 RAG | 有没有办法让它说真话 | 如何把真实资料接进模型,从源头减少编造 |
| 第 4 章 从大模型到智能体:七个核心概念 | 模型怎么变成能干活的助手 | 智能体、SKILL、Tool、MCP、上下文、温度各自是什么 |
先认识模型本身,再了解它的问题,然后掌握解决办法,最后才扩展到智能体这一层。这样的顺序符合初学者的认知路径,也解释了为什么本书后面要反复强调核验与检索。
如果时间紧张,至少读完第 1 章与第 4 章再进入第二部分。但在把模型用于正式工作之前,请务必补读第 2 章。
第 1 章 大模型是怎么工作的¶
1.1 一切从"预测下一个字"开始¶
大语言模型做的事情,说穿了只有一件:根据已经出现的文字,预测下一个最应该出现的字。你给它"今天天气很",它算出接下来最有可能是"好";你把答案接回原文,再让它预测下一个,如此循环往复,一句话、一段话、一篇文章就这样被"接龙"出来。
这件看似简单的事,在足够大的规模上产生了质变。当模型读过近乎互联网上所有的公开文本,并且参数量达到百亿、千亿级别时,它在这个过程中不得不学会语法、事实、逻辑乃至某种程度的推理,否则就无法准确完成预测任务。这些能力不是被显式教出来的,而是被预测任务"逼"出来的副产品。
训练大致分三个阶段:
| 阶段 | 名称 | 做什么 | 解决什么问题 |
|---|---|---|---|
| 第一阶段 | 预训练 | 在海量文本上反复练习"预测下一个字" | 获得语言能力、世界知识与基本推理能力 |
| 第二阶段 | 监督微调 | 用人工编写的高质量问答对进一步训练 | 学会理解指令,能按人类期望的方式回答 |
| 第三阶段 | 偏好对齐 | 根据人类对多个答案的偏好打分来调优 | 让回答更安全、更有用、更符合人类习惯 |
提示:理解"预测下一个字"这一点,是理解后面所有现象的关键。无论是模型的聪明、它的偏见,还是它的胡编乱造,都能从这一个机制推导出来。
1.2 三个必须知道的基本概念¶
参数:模型内部用来存储"知识"的可调节数值,可以理解为它从训练数据里压缩出来的记忆。常说的"7B","671B"指的就是参数量,1B 等于 10 亿。参数量大体决定了模型的能力上限,也决定了运行它需要的硬件资源。对个人用户而言,参数量不用记,只要知道它对应模型的"档次"即可。
Token:Token 是大模型处理文本的基本单位,也是计费单位。中文大约 2 个字折合 1 个 Token,英文常把一个长单词拆成多个 Token。我们常看到的 “支持 128K 上下文”“每百万 Token 多少钱”,这里的单位都是 Token。
上下文窗口:模型一次能同时"看到"的文字总量上限,包含你输入的内容、历史对话以及它自己的输出。超出这个上限的部分会被丢弃或压缩,这就是为什么长对话进行到后面,模型会忘记开头说过的话。
| 概念 | 一句话解释 | 与你有关的地方 |
|---|---|---|
| 参数 | 模型的知识容量 | 决定能力上限与运行成本 |
| Token | 文本的最小计量单位 | 决定你的花费,也决定上下文能装多少 |
| 上下文窗口 | 一次对话的容量上限 | 决定任务能有多长,超出就会遗忘 |
| 知识截止日期 | 训练数据覆盖到的时间 | 此后的事情模型不知道,需要联网或检索 |
注意:模型并不"知道"今天几号,也不"知道"自己的知识截止到什么时候。它对时间没有内在感知,只是训练数据里包含某个时间点之前的信息。问它截止日期之后发生的事,它往往会用旧信息拼出一个看似合理的答案,这正是下一章要讲的幻觉。
1.3 大模型擅长什么,不擅长什么¶
把能力边界说清楚,比罗列能力更重要。
| 维度 | 擅长的 | 不擅长的 |
|---|---|---|
| 语言 | 改写、润色、摘要、翻译、格式转换 | 需要绝对精确的文字,如法律条文的逐字引用 |
| 知识 | 通识性、高频出现的知识 | 长尾、冷门、时效性强的信息 |
| 推理 | 常规逻辑推演、多步骤分析、思路梳理 | 精确数值计算、严格的符号推导 |
| 创造 | 提供思路、生成草稿、启发联想 | 替代专业判断与审美决策 |
| 信息 | 已知信息的组织与重组 | 未知信息的获取,尤其是实时信息与私有数据 |
提示:一个实用的判断标准是,凡是"能靠语言规律推出来"的事,模型都做得不错;凡是"必须查证才能知道"的事,模型都不该被单独信任。写代码属于前者居多,查文献属于后者居多。
1.4 由此推出的四条使用原则¶
第一,把它当助手,不要当权威。 模型的输出是高质量的初稿,不是结论。它能帮你从一片空白迅速做到六七十分的水平,剩下的部分需要你的专业判断来补。
第二,任务拆细,一次一事。 把一个大问题拆成若干个明确的小步骤,每一步单独确认,质量远高于一次性扔给它一个笼统的要求。
第三,给出上下文和约束。 说明你的身份、目标、受众、格式要求、篇幅限制、哪些内容不要出现。信息给得越充分,输出越接近预期。
第四,让它说明依据。 要求模型在给出结论时一并说明推理过程与信息来源,并明确允许它回答"我不知道"。这一条能显著减少下一章要讲的幻觉。
第 2 章 幻觉:模型为什么会一本正经地编造¶
2.1 什么是幻觉¶
幻觉(Hallucination)指的是模型生成了与事实不符、但表述流畅且语气自信的内容。它的危险之处不在于"错",而在于"错得很像真的":格式规范、逻辑自洽、细节完整,读起来毫无破绽,让人本能地放松警惕。
在科研与教学场景中,幻觉的代价尤其高昂。一条虚构的参考文献、一个编造的统计数字、一个张冠李戴的实验方法,一旦进入论文或课件,纠正成本远高于当初核验的成本。
2.2 幻觉从何而来¶
| 成因 | 机制 | 典型表现 |
|---|---|---|
| 训练数据含噪声 | 互联网文本本身就有大量错误、过时与相互矛盾的内容 | 复述流传较广的错误说法 |
| 概率生成本质 | 模型优化的目标是"流畅合理",而不是"事实正确" | 把最像答案的内容说成答案 |
| 知识的有损压缩 | 千亿参数无法完整记住海量事实,长尾信息丢失或串接 | 冷门事实错误,细节张冠李戴 |
| 缺乏外部知识源 | 模型生成时不查资料,只能依赖内部记忆 | 对知识截止后的事件凭空推测 |
| 提示词诱导 | 引导性提问,或要求"必须给出答案" | 为迎合提问而编造 |
| 采样随机性 | 温度较高时,低概率但更"有创意"的选项被选中 | 天马行空,偏离事实 |
提示:最关键的一点是,流畅性与正确性在模型内部是两件独立的事。它说话顺溜,只说明它掌握了语言规律,完全不能证明它掌握了事实。
2.3 三种最常见的表现¶
编造文献与引用。 这是科研工作中最需要警惕的一类。模型可能生成看起来完全规范的参考文献,包含作者、期刊、年份、卷期页码甚至 DOI,但这篇文章并不存在。另一种情况是文章真实存在,但作者、结论或期刊被张冠李戴。
虚构数字与事实。 编造统计数据、实验参数、药物剂量、基因编号、政策条文的具体内容与生效时间。数字类幻觉尤其隐蔽,因为它往往与其他真实数字混在一起。
混淆与越界推断。 把 A 研究的方法说成 B 研究的结论,把动物实验的结果说成临床结论,把相关性表述为因果性。这类错误不一定是完全虚构,而是对真实信息的错误组合。
2.4 五个识别信号¶
- 具体而不可核验:给出了非常具体的细节,但按图索骥却查不到出处;
- 语气过度确定:对理应存在争议或需要限定条件的问题给出斩钉截铁的回答;
- 细节自相矛盾:同一段回答中前后数字、时间、名称不一致;
- 追问即改口:追问依据时,它承认"我无法确认"或换一个说法;
- 换个问法答案就变:同一问题重新提问,得到的答案实质性不同。
提示:一个低成本的验证技巧是"换窗口重问"。新开一个对话,把问题重新表述一遍,如果两次答案在关键事实上不一致,那么至少有一个是编的。
2.5 六条应对策略¶
| 策略 | 具体做法 |
|---|---|
| 要求提供依据 | 明确要求给出信息来源、推理过程,并允许回答"不确定" |
| 限定回答范围 | 限定只依据给定材料作答,材料中没有就直说没有 |
| 关键信息交叉验证 | 文献查数据库,数字查原始来源,法规查官方文本 |
| 降低温度 | 事实性任务把温度调到 0 或接近 0,减少随机性 |
| 引入外部知识 | 用第 3 章的 RAG 把真实资料接入,让模型看着材料回答 |
| 建立复核习惯 | 凡是要写进论文、课件、报告的内容,逐条人工核对 |
2.6 科研与教学场景的特别提醒¶
- 文献引用一律核验。凡模型给出的参考文献,都要在 Web of Science、PubMed、Google Scholar 或期刊官网检索确认,重点核对 DOI 与作者。
- 实验参数不得直接采信。剂量、浓度、温度、时间、序列、引物等关键参数,必须回到原始文献或实验记录核对。
- 专业名词重点检查。基因名、蛋白名、通路名、药物名、疾病编码这类术语,是幻觉的高发区,也是最容易被同行一眼看穿的地方。
- 统计结论需复核。样本量、P 值、置信区间、效应量等数字,用原始数据重算一遍再引用。
- 教学材料提前试做。课件中的示例、代码、数据如果来自模型生成,上课前务必自己跑一遍。
注意:不要让模型成为你了解一个陌生领域的唯一信息源。用它来建立初步框架、梳理思路、提出该查什么,然后用真实文献把框架填实。顺序反了,就会把幻觉当成知识沉淀下来。
第 3 章 RAG:给模型外挂一个资料库¶
3.1 它解决什么问题¶
第 2 章讲到的幻觉,有相当一部分源于同一个困境:模型只能依靠训练时记住的东西作答,既看不到你的私有资料,也看不到知识截止之后的新信息。
RAG(Retrieval-Augmented Generation,检索增强生成)给出的解法很朴素:先去资料库里把相关内容找出来,把找到的内容连同问题一起交给模型,让它看着材料回答。
这样一来,模型不再需要凭记忆作答,而是变成了"阅读理解"。它的语言与推理能力照常发挥作用,事实准确性则由你提供的真实资料兜底。
3.2 四步流程¶
| 步骤 | 名称 | 做什么 | 关键要点 |
|---|---|---|---|
| 第一步 | 文档准备与切分 | 把资料整理成纯文本,切成一个个语义完整的片段 | 按段落或章节切分,避免把一个完整论述拦腰截断 |
| 第二步 | 向量化与入库 | 用 Embedding 模型把每个片段转成向量,存入向量库 | 中文场景选择中文 Embedding 模型,可参考 MTEB 榜单 |
| 第三步 | 检索 | 把提问同样转成向量,找出语义最相近的若干片段 | 可先粗召回再重排序,兼顾速度与精度 |
| 第四步 | 增强生成 | 把检索到的片段拼进提示词,要求模型依据材料作答并注明出处 | 明确要求"材料中没有就回答不知道" |
提示:RAG 的效果上限由你的资料质量决定,而不是由模型决定。这就是常说的"垃圾进,垃圾出"。整理一份干净、权威、结构清晰的资料库,比换一个更强的模型更有效。
3.3 RAG、微调与长上下文怎么选¶
三种方案都能让模型"知道更多东西",但原理与代价完全不同。
| 对比项 | RAG | 微调 | 超长上下文 |
|---|---|---|---|
| 原理 | 回答时临时检索外部资料 | 用数据继续训练,改变模型自身 | 一次性把全部资料塞进输入 |
| 知识更新 | 改资料库即可,即时生效 | 需要重新训练 | 每次对话重新塞入 |
| 成本 | 低,主要是存储与检索开销 | 高,需要训练资源与数据工程 | 随资料量线性增长,很贵 |
| 可溯源 | 可以,能指出答案出自哪一段 | 不可以 | 勉强可以 |
| 擅长 | 事实问答、资料查询、需要溯源的场合 | 固定风格、特定任务格式、领域术语习惯 | 资料量不大且需要整体理解时 |
| 不擅长 | 让模型学会新的表达风格 | 频繁更新的知识 | 海量资料的日常问答 |
提示:对绝大多数个人与教学场景,RAG 是首选。它便宜、可控、随时可改,而且每一条答案都能追溯到具体的段落,这一点对科研工作尤其重要。
3.4 什么时候该用,什么时候不必用¶
适合用 RAG 的情况:你有一批自己的资料需要反复查询,比如课题组的历史文档、某个方向的文献集合、课程讲义与实验手册;你需要答案能指出处;资料会持续更新;资料总量超出上下文窗口。
不必用 RAG 的情况:你只是想让模型帮你改写、润色、梳理思路,这些任务靠模型自身能力就够;资料只有几页,直接粘贴进对话即可;你真正需要的是提升模型的推理或写作风格,那属于微调的范畴。
3.5 落地要点¶
- 资料先行。优先收录权威来源,剔除重复、过期与相互矛盾的内容,统一格式后再入库;
- 切分讲语义。按标题层级或自然段落切分,每个片段保持论点完整,片段之间可保留少量重叠以免切断语义;
- 选对 Embedding 模型。中文资料务必选用中文能力强的嵌入模型,参考 MTEB 榜单选择;
- 控制检索数量。通常取 3 到 8 个片段,太少容易漏,太多引入噪声稀释重点;
- 在提示词中设约束。明确要求只依据材料作答,材料不足时直接说明,并在答案中标注引用编号;
- 建一个小评测集。准备十几条你确定答案的问题,每次调整配置后跑一遍,用真实通过率判断改进是否有效。
3.6 RAG 的局限¶
RAG 不是万能药,它有四个绕不开的限制:
- 检索不到就答不出。如果资料库里没有,或者检索环节没召回,模型依然只能凭记忆作答,幻觉照旧;
- 切分会破坏语义。跨段落的论证、依赖表格的数据,切分后可能丢失关联;
- 不提升推理能力。RAG 只解决"知道什么",不解决"能不能想清楚",材料再全,推理薄弱的模型依然会得出错误结论;
- 纯向量检索对精确匹配不敏感。产品编号、基因符号、精确短语这类需要字面匹配的内容,需要配合关键词检索一起使用。
提示:把 RAG 理解为"给模型配了一个查得到、报得出的资料员",而不是"给模型做了知识植入手术"。它解决的是信息可及性与可溯源,不解决能力本身。
3.7 与本书后续内容的关系¶
RAG 并不是一个需要你从头搭建的东西,它已经以各种形态存在于本书后面的内容中。
智能体的 SKILL 常常就是把领域资料与操作流程打包在一起的产物;MCP 让智能体能够直接查询外部数据库与文件,本质上也是把外部信息接入生成过程;像 BioMed AI 这样的领域集成应用,内置了专业资料库与分析工具,同样属于 RAG 思路的落地形态。
理解了这一层,你在后面配置 SKILL 与插件时,就知道自己真正在做什么:不是在给模型"加知识",而是在给它接上一条通往真实资料的通道。
第 4 章 从大模型到智能体:七个核心概念¶
4.1 从"会说话"到"会干活"¶
前面三章讲的是大模型本身。你已经知道它本质上是在预测下一个字,知道它会编造,也知道可以用 RAG 给它接上真实资料。
但仍然有一个问题没有解决:模型只会说,不会做。
你问它"帮我整理这个文件夹里的实验记录",它能告诉你该怎么整理,却无法真的打开文件、读取内容、生成表格。它像一个被关在屋子里、只通过窗口与你交谈的顾问,什么都知道,什么都做不到。
智能体要解决的正是这件事。它在模型外面套上一层"手脚",让模型能够读写文件、执行命令、调用工具,并且自己规划先做什么后做什么。从模型到智能体,是本章要讲的核心跨越。
这一层跨越带来了一批新概念:智能体、SKILL、Tool、MCP、上下文、温度,再加上前面已经出现过的大模型与提示词,一共七个。下面用一个贯穿全书的比喻把它们串起来。
4.2 一个贯穿全书的比喻¶

想象你在网上买了一个柜子,需要有人上门帮你装好。整个安装过程里出现的人和物,恰好对应智能体世界的七个基本概念。
① 大语言模型 LLM —— 师傅的大脑 能听懂你的要求、看懂图纸、推理和回答问题,但只输出文字,不会真的执行动作。它是智能体的"思考核心",负责理解意图、规划步骤、判断下一步做什么。
② 智能体 Agent —— 师傅本人 + 手边的工具 在 LLM 基础上加上"动手"的能力:能自己规划先装底板还是侧板、调用工具一步步执行、中途卡住会翻说明书或换方法重试,直到任务完成。LLM + 工具调用 + 自主循环 = Agent,这是它和聊天机器人的本质区别。
③ Skill 技能包 —— 成套操作手册
一个包含 SKILL.md(外加可选脚本、参考资料)的文件夹,封装的是流程性知识:这类任务按什么步骤做、查什么信息、按什么格式输出、边界怎么处理。采用渐进披露加载:先只读摘要,命中了才读正文,正文引用时才加载附件,所以几乎不占上下文。可多本组合复用。
④ Tool 工具 —— 单件实物工具 最小的、单次调用的能力单元,一次只做一件事:卷尺只测量、螺丝刀只拧螺丝、电钻只打孔。Skill 会去调用工具,但它本身不是工具。
⑤ MCP(Model Context Protocol)—— 通用工具快接头 一套开放协议,规定智能体如何标准化接入外部能力,不必为每个工具单独写适配代码。一个 MCP 服务可对外提供三类东西:tools(工具)、resources(数据)、prompts(提示模板)。
⑥ 上下文 Context —— 师傅脑子里的现场信息 不只是聊天记录,还包括系统提示、工具返回结果、检索到的外部资料。它是有容量上限的工作记忆:装不下就会被截断或压缩总结,这才是长任务后半程"跑偏、忘事"的根因。
⑦ 温度 Temperature —— 干活的灵活度 调低:严谨保守,几乎按最可能的答案走,适合写代码、严谨推理;调高:更有创意和发散,也更容易自作主张、出错。不同厂商取值范围不同(常见 0–1 或 0–2),且即使设为 0 也不保证逐字完全一致,严谨场合应说"近似确定性"。
⑧ 提示词 Prompt —— 你下的需求单 你交给模型的任务描述与约束。写得越清楚(目标、格式、边界、示例),结果越准;写得模糊,模型就会自由发挥,出现漏项或偏差。
提示:你写下需求单(Prompt)→ 大脑(LLM)思考怎么干 → 师傅(Agent)开始动手 → 翻操作手册(Skill)查流程 → 拿起单件工具(Tool)→ 通过通用接口(MCP)接上外部系统 → 全程靠现场记忆(Context)记着进度 → 按灵活度(Temperature)决定发挥多少。
4.3 概念速查表¶
| 概念 | 比喻 | 核心特征 |
|---|---|---|
| 大语言模型 | 师傅的大脑 | 理解、推理、对话,但不动手 |
| 智能体(Agent) | 师傅本人加上工具箱 | 有目标、能规划、会调用工具、能执行 |
| SKILL | 可外部调取的成套操作手册 | 封装能力、可复用、多手册可组合,不属于大脑内部记忆 |
| Tool(工具) | 螺丝刀、卷尺这类单件工具 | 最小执行单元,单次完成单一动作 |
| MCP | 通用工具快接头协议 | 统一接入标准,让智能体即插即用各类外部工具与资源 |
| 上下文(Context) | 师傅干活记住的全部现场信息 | 保存任务历史、资料、进度,存在记忆上限 |
| 温度(Temperature) | 师傅的发挥灵活度 | 控制模型随机性,低温严谨,高温创意发散 |
| 提示词 | 你给师傅的需求单 | 任务指令,决定干什么、怎么干 |
提示:SKILL 与模型的记忆能力是两回事。模型本身的知识来自训练,是固定的;SKILL 是外部挂载的操作规程,随时可以增删更新。正因为 SKILL 可以外挂,不同人给同一个模型配上不同的 SKILL,就能把它改造成完全不同用途的专用助手,这也是本手册第 6 章与后续各产品章节反复涉及 SKILL 配置的原因。
第 5 章 主流大模型与排行榜¶
5.1 为什么需要先了解模型¶
智能体本身不生产智能,它只是把模型的能力组织起来。因此选什么模型,直接决定了智能体的能力上限、响应速度与使用成本。本章给出当前主流模型的全景图,以及判断模型强弱的权威榜单。
选择模型时通常需要在四个维度之间权衡:能力、速度、成本、可访问性。国外头部模型能力领先但访问门槛高,国内模型在中文场景与性价比上优势明显,且访问稳定。对教学与科研场景,建议以国内主流模型作为主力,必要时再用海外模型处理特定难题。
5.2 国外主流大模型¶
| 厂商 | 代表模型 | 核心优势 | 官方链接 |
|---|---|---|---|
| OpenAI | GPT-5.6 系列(Sol / Terra / Luna) | Agent 原生化、全模态、推理与编程能力突出,C 端生态最强 | https://openai.com |
| Anthropic | Claude Opus 4.8 / Sonnet 4.6 / Fable 5 | 安全对齐领先、超长上下文(最高约 200 万 Token)、企业级合规与代码工程能力强 | https://anthropic.com |
| Google DeepMind | Gemini 3.5 Pro / Flash | 原生多模态能力强,支持超长上下文,深度集成 Google 搜索、云与办公生态 | https://deepmind.google |
| Meta | Llama 4 系列(Behemoth / Maverick / Scout) | 全球开源大模型标杆,支持商业免费使用,覆盖 7B 至 2T 参数,社区生态最活跃 | https://llama.meta.com |
| xAI | Grok 4.5 / V9-Medium | 依托 X 平台实时数据,思维链推理与低延迟特性突出,适合实时资讯分析 | https://x.ai |
| Mistral AI | Mistral Large 3 / Small 4 | 欧洲 AI 代表,多语言与代码能力强,提供开源与商用并行版本 | https://mistral.ai |
5.3 国内主流大模型¶
| 厂商 | 代表模型 | 核心优势 | 官方链接 |
|---|---|---|---|
| 阿里巴巴 | 通义千问 Qwen 3.7 系列(Max / Plus / Flash) | 开源生态活跃,Agent 能力与多模态均衡,数学与代码推理国内顶尖,API 性价比高 | https://tongyi.aliyun.com/ |
| 深度求索 | DeepSeek V4 / R2 / V3 / R1 | 1.6T 参数 MoE 架构,百万级上下文,推理与代码能力顶尖,开源性价比极高 | https://deepseek.com/ |
| 腾讯混元 | Hy3 / Hy4-preview | MoE 混合专家架构,Agent 工具调用、代码与长文档能力突出,深度适配腾讯生态,支持 256K 至 960K 上下文,企业业务落地成熟,支持联网搜索 | https://hunyuan.tencent.com/ |
| 字节跳动 | 豆包 Seed 2.1 Pro / Seedance 2.0 | C 端体验领先,多模态生成与视频生成能力突出,移动端日活规模大 | https://www.doubao.com/ |
| 智谱 AI | GLM-5.2 / GLM-5 | 清华系背景,政务与学术场景优势明显,支持纯国产芯片全流程训练,长文本处理能力强 | https://chatglm.cn/ |
| 百度 | 文心一言 5.1 / ERNIE 5.0 | 中文语义理解与知识增强领先,深度整合百度搜索生态,产业落地广泛 | https://yiyan.baidu.com/ |
| 华为 | 盘古大模型 5.0 | 全栈国产化,深耕制造、能源、政务等工业场景,央企与信创项目优势明显 | https://www.huaweicloud.com/product/pangu.html |
| 科大讯飞 | 星火 4.0 Turbo | 语音交互与中文理解优势显著,教育、医疗垂直领域落地能力强 | https://xinghuo.xfyun.cn/ |
| 商汤科技 | 日日新 / SenseNova | 计算机视觉基因强,多模态融合与行业模型落地能力强 | https://www.sensetime.com/ |
| MiniMax | MiniMax M3 / M2.7 | 全球化多模态大模型代表,支持 197K 至 100 万 Token 上下文,编程与终端执行能力突出 | https://www.minimaxi.com/ |
| 月之暗面 Kimi | Kimi K3 / K2.6 | 长文本处理与 Agent 集群能力突出,支持百万 Token 级上下文,适合文献解析与研究场景 | https://kimi.moonshot.cn/ |
| 阶跃星辰 | Step 3.7 Flash | 主打轻量化端侧部署,智能车载与本地硬件终端适配能力突出 | https://www.stepfun.com/ |
| 小米 | MiMo V2.5-Pro | 端侧与云端协同,1.02T 参数,MIT 协议开源,布局端侧离线 AI 助手 | https://xiaomi.com/ |
5.4 模型排行榜怎么用¶
选模型时,与其听宣传,不如看榜单。但榜单也有门道,需要分清三类:
- 客观跑分榜:用固定测试集打分,可复现,但可能被针对性优化;
- 真人盲测对战榜:由真实用户投票,最接近实际体验,主观性较强;
- 专项榜单:只测某一项能力,比如代码、向量检索、数学推理。
注意:跑分不等于实际使用体验。做 Agent、写代码、处理长文本这类任务,一定要看对应的专项指标,综合总分往往说明不了你真正关心的那件事。
| 榜单名称 | 网址 | 类型 | 特点说明 |
|---|---|---|---|
| OpenCompass 开放罗盘 | https://opencompass.org.cn | 国内客观跑分 | 上海 AI 实验室出品,中文评测最强,包含 C-Eval、CMMLU,支持中英文闭源与开源模型,附带 CompassArena 真人对战榜 |
| SuperCLUE | https://www.superclueai.com | 国内综合评测 | 中文大模型专项,覆盖 Agent、代码、幻觉、安全性,每月更新,适合国产模型横向对比 |
| LMSYS Chatbot Arena(LMArena) | https://arena.lmsys.org | 全球真人盲测对战 | 双盲投票,反映真实对话体验,有 Expert 专家榜单,适合看实际对话能力,需海外访问 |
| HuggingFace Open-LLM-Leaderboard | https://huggingface.co/spaces/open-llm-leaderboard | 全球开源模型跑分 | 开源模型核心打榜,采用 MMLU、GSM8K 等标准测试集,只测开源权重模型,闭源商业模型不参与 |
| BigCode Models Leaderboard | https://huggingface.co/spaces/bigcode/bigcode-models-leaderboard | 代码专项榜 | 专门评测代码能力(HumanEval),选择 Agent 与开发模型时的重要参考 |
| MTEB Leaderboard | https://huggingface.co/spaces/mteb/leaderboard | Embedding 向量模型榜 | 文本嵌入与检索模型专用榜单,做 RAG 检索必看 |
| LiveBench | https://livebench.ai | 防止刷榜的客观跑分 | 每月更换全新测试题,防止模型针对数据集刷分,侧重数学、推理与代码,学术圈认可度高 |
| ModelSage | https://modelsage.cn/leaderboards | 商业模型综合对比 | 同时呈现跑分与 API 价格,适合选型,包含国内外闭源商业模型,可直接对比性价比 |
提示:初次选型建议这样组合使用榜单。先在 SuperCLUE 或 OpenCompass 上确认国内模型的综合水平,再到 ModelSage 对比价格,最后用 LiveBench 验证它是不是靠刷榜拿的分。如果任务涉及代码,额外参考 BigCode 榜单。
第 6 章 智能体产品与 SKILL 的获取¶
6.1 智能体产品全景¶
目前流行的智能体工具已经形成了完整的产品谱系,从面向办公的桌面套件,到面向开发者的终端工具,再到可编程的运行框架,形态差异很大。

提示:这张图可以帮助你快速建立全局印象。挑选产品时不必追求"最强",而要看它是否匹配你的工作场景。日常办公、写文档、做汇报选桌面套件;改代码、跑脚本选终端工具;想要把智能体嵌入自己的业务流程,才需要考虑运行框架。
6.2 SKILL 的获取渠道¶
SKILL 是决定智能体"能干什么活"的关键。下面汇总了目前常用的获取渠道,既有官方仓库,也有社区市场与专项技能。
| 序号 | 名称 | 类型 | 地址 | 简要说明 |
|---|---|---|---|---|
| 1 | Anthropic 官方仓库 | 官方仓库 | https://github.com/anthropics/skills | Agent Skills 官方仓库,含文档创作(docx / pdf / pptx / xlsx)、创意设计、开发测试等示例 Skill,约 17.7 万 Star |
| 2 | SkillsMP | 社群网站 | https://skillsmp.com/zh | Agent Skills 市场,收录 300 万以上来自公开 GitHub 仓库的 SKILL.md,支持搜索与对比 |
| 3 | SkillHub | 社群网站 | https://skillhub.cn/ | 专为中国用户优化的 AI Skills 社区,精选 Top 50 高质量技能,含安全审核与多维评估 |
| 4 | awesome-claude-skills | 开源合集 | https://github.com/ComposioHQ/awesome-claude-skills | 优秀 Claude Skills 开源集合(精选清单) |
| 5 | skills(YouTube 视频制作) | 视频制作 Skill | https://github.com/remotion-dev/skillsyoutube | Remotion 官方出品的视频制作 Skill |
| 6 | Youtube-clipper-skill | 视频剪辑 Skill | https://github.com/op7418/Youtube-clipper-skill | AI 驱动的 YouTube 剪辑工具,支持下载视频、语义分章、剪辑片段、双语字幕与字幕烧录 |
| 7 | skill-from-masters | Skill 生成 Skill | https://github.com/GBSOSS/skill-from-masters | "大师帮你创建 Skill"的元 Skill,用于辅助生成高质量技能 |
| 8 | notebooklm-skill | NotebookLM Skill | https://github.com/PleasePrompto/notebooklm-skill | 将 NotebookLM 的能力封装为可复用的 Skill |
| 9 | x-article-publisher-skill | 内容发布 Skill | https://github.com/wshuyi/x-article-publisher-skill | 把 Markdown 文章一键发布到 X(Twitter)的 Skill |
| 10 | Vidu Skills | AI 视频产品 | https://www.vidu.cn/ | 生数科技自研 AI 视频生成模型,支持文生视频、图生视频、参考生视频,含 Vidu Agent |
6.3 挑选与安装 SKILL 的三条经验¶
先看来源,再看功能。 SKILL 本质上是一段会被智能体执行的指令,来源不明就意味着风险未知。优先选择官方仓库、有明确维护者的开源项目,以及经过安全审核的社区精选。SkillHub 这类平台提供安全审核,相对更适合新手。
一个项目一个目录。 建议为每个任务单独建一个工作文件夹,把该项目用到的 SKILL 集中放置。这样做的好处是切换项目时不会互相干扰,也方便把整套配置打包分享给同事。
先跑小任务验证。 新装的 SKILL 第一次使用时,先给一个规模很小的任务,确认输出符合预期,再投入正式工作。这一步能提前暴露路径错误、依赖缺失等问题。
注意:SKILL 会被赋予执行操作的权限,安装前请浏览一下它的说明文件,了解它要访问哪些目录、调用哪些工具。不要安装来源不明、说明含糊的技能包。
第二部分 环境准备¶
本部分只有两件事:装好 Node.js,拿到 API 密钥。这两步是所有命令行类智能体的共同前提,做一次即可,后续安装任何产品都建立在这个基础之上。
第 7 章 安装 Node.js¶
7.1 为什么必须先装它¶
OpenCode、DeepSeek Harness 等智能体产品本身是用 JavaScript 生态开发的,它们的安装与运行依赖 Node.js 提供的运行时环境。这个依赖是隐式的,如果你直接去装智能体,往往会在安装阶段遇到莫名其妙的报错,追查下去才发现是 Node.js 缺失或版本过低。所以请务必提前安装。
7.2 下载与安装¶
Node.js 官方下载地址:https://nodejs.org/zh-cn
进入官网后,页面会自动推荐适合你系统的版本,选择 LTS(长期支持版)下载即可。LTS 版本更新频率低、稳定性好,适合作为日常开发环境。

安装过程一路点"下一步"即可,全部保持默认选项。安装程序会自动配置环境变量,无需手动干预。
注意:如果电脑上此前装过很旧版本的 Node.js,建议先卸载再安装新版本。部分智能体对 Node.js 版本有下限要求,版本过低会导致安装失败。
7.3 验证方法¶
安装完成后,务必重新打开一个新的命令行窗口(已经打开的窗口不会加载新的环境变量),输入以下命令并回车:
两条命令分别会输出 Node.js 与 npm 的版本号,例如 v22.11.0 与 10.9.0。只要能看到版本号,就说明安装成功。如果提示"不是内部或外部命令",说明环境变量没有生效,重启一次电脑通常即可解决。
第 8 章 API 密钥的获取与安全管理¶
8.1 什么是 API 密钥,为什么必须有它¶
大模型服务部署在厂商的服务器上,你的智能体在本地运行,两者之间的每一次对话都要通过网络完成。API 密钥就是你调用这些服务的凭证,相当于一张既证明身份又负责记账的通行证。
没有密钥,智能体就只是一个空壳,能启动但无法思考。有了密钥,你的每一次提问都会被计入账户消费。因此密钥兼具"钥匙"和"银行卡"两重属性,这也决定了它必须被妥善保管。
获取密钥有两条路径:
- 直接去模型开发商的官网申请,比如 DeepSeek、智谱 AI、阿里云百炼;
- 通过第三方聚合平台申请,一个密钥可以调用多家模型,省去逐个注册的麻烦。
两条路径没有优劣之分,取决于你的使用习惯。如果你只用某一家模型,走官网最直接;如果你想频繁对比不同模型,聚合平台效率更高。
8.2 路径一:在模型提供商官网申请¶
下面以 DeepSeek 为例,其他厂商的流程大同小异。
第一步,打开用量页面:https://platform.deepseek.com/usage

第二步,点击"创建 API key",输入名称。名称由你自己命名,作用是提醒你这个密钥的用途,比如填写"OpenCode 本机"或"教学测试"。

提示:给密钥起一个能说明用途的名字,是后续管理多个密钥时最省事的做法。当你手上有五六个密钥时,靠名称区分远比靠一串字符区分高效。
第三步,创建完成后立即复制并保存。

注意:绝大多数平台只在创建时完整显示一次密钥,关掉窗口后就再也看不到了,只能删除重建。所以请在复制后立即粘贴到密码管理器或本地加密文件中,不要只存在剪贴板里。
8.3 路径二:通过第三方聚合平台申请¶
这类平台很多,下表列出部分主流服务商。选择时重点关注三点:覆盖的模型、是否提供 Anthropic 兼容端点、以及访问是否顺畅。

| 平台 | 类型 | 覆盖模型 | Anthropic 兼容端点(BaseURL) | 特色与适合场景 |
|---|---|---|---|---|
| 阿里云百炼 Model Studio | 国内,官方 | 通义全系、DeepSeek、Kimi、GLM | https://coding.dashscope.aliyuncs.com/apps/anthropic |
官方原生适配 Claude Code,企业稳定、有发票,长期开发首选 |
| 腾讯云 TokenHub | 国内,官方 | 混元、DeepSeek、GLM、Kimi | https://tokenhub.tencentmaas.com/v1 |
腾讯生态、生产业务、日志审计、子账号管理 |
| 百度千帆 Qianfan | 国内,官方 | 文心一言、DeepSeek、Llama | 兼容多协议 | 百度云用户、企业合规、私有化场景 |
| 硅基流动 SiliconFlow | 国内,聚合 | DeepSeek、Qwen、Kimi、GLM 等 | https://api.siliconflow.cn/anthropic |
低价、国产开源模型多(本手册在用) |
| 基元律动 TokenRhythm | 国内,聚合 | 几乎所有国产模型 | 支持 Anthropic 协议 | 中国版 OpenRouter,多模型快速切换、对比测试 |
| DMXAPI | 国内,聚合 | DeepSeek、Qwen、Kimi、MiniMax | 支持 Anthropic 兼容接口 | 个人与中小团队、低延迟、可开票 |
| OpenRouter | 海外,聚合 | 500 以上模型(含 Claude、DeepSeek、Kimi) | 原生 Anthropic 协议 | 全球最知名、模型最多,国内访问有网络门槛 |
| Groq | 海外 | Llama、Qwen | OpenAI 与 Anthropic 兼容 | 极速推理 |
| Amazon Bedrock | 海外云厂 | Claude 原生托管 | AWS 侧 | 企业生产、合规、IAM、数据隔离 |
| Microsoft Foundry(Azure) | 海外云厂 | Claude 原生托管 | Azure 侧 | Azure 治理、身份、账单 |
| Google Vertex AI | 海外云厂 | Claude 原生托管 | GCP 侧 | GCP 合规、IAM |
国外模型推荐使用 OpenRouter,需要相应的网络条件。
国内模型推荐使用硅基流动与基元律动,新用户注册即有免费额度可用。本手册后续所有案例均以硅基流动作为示范平台。
注册基元律动:https://tokenrhythm.studio/i/rf_tr_9QVRNE
注册硅基流动:https://cloud.siliconflow.cn/i/zHUE3fOY
也可以扫码注册:

提示:建议你至少完成一家国内平台的注册。它不只能解决密钥问题,后面配置自定义模型、做模型路由时都会反复用到模型广场里的模型 ID。
8.4 硅基流动实操:从注册到拿到密钥¶
第一步,完成实名认证。 注册完成后,按平台要求完成实名认证。这是国内云服务的合规要求,通常在账户设置中上传信息即可。

第二步,领取新用户额度。 认证通过后即可领取 16 元优惠券,足够完成本手册全部配置并做一定量的实际使用。

第三步,创建密钥。 进入 API 密钥页面,点击"新建密钥",输入名称后确认创建。

创建成功后,直接复制密钥备用。
注意:密钥等同于你的账户资金。不要把它发给他人,也不要截图发到公开群聊、提交到代码仓库或粘贴在公开文档中。他人拿到密钥后产生的所有消费,都会从你的账户扣除。一旦发现泄露,请立即删除该密钥并重新创建。
8.5 密钥安全管理清单¶
| 风险场景 | 正确做法 |
|---|---|
| 密钥被写进代码提交到公开仓库 | 密钥只放在配置文件或环境变量中,提交前检查,或使用 .gitignore 排除配置文件 |
| 密钥截图出现在群聊或教程里 | 分享教程前对密钥打码,宁可重画截图也不要露出明文 |
| 多个产品共用一个密钥 | 按用途分别创建,出问题时可以单独作废,不影响其他产品 |
| 长期不用的密钥 | 定期清理,养成每季度核查一次密钥列表的习惯 |
| 账单异常 | 第一时间删除可疑密钥,再联系平台核对调用记录 |
提示:如果你只是想先体验一下,可以专门创建一个"试用密钥"并为其设置较小的可用额度。这样即使出问题,损失也是可控的。
第三部分 智能体产品安装与配置¶
本部分逐一讲解五款主流产品。它们之间的差别远大于差别之外的共同点,因此第 9 章先给出选型表,帮你决定该读哪几章,避免逐章读完却发现用不上。
第 9 章 五款产品总览与选型¶
9.1 产品简介¶
WorkBuddy(腾讯):腾讯云的 AI 桌面工作站与办公智能体,不只做代码。它能理解自然语言、自主规划并执行任务,产出文档、报告、代码等可验证的结果。旗下还有 CodeBuddy Code,一款带 sub-agent、MCP 与 IDE 集成的编码命令行工具。
OpenCode:开源编码智能体,终端、IDE、桌面三端可用。通过 Models.dev 接入 75 家以上模型供应商(含本地模型),模型不锁死,具备 LSP 与多会话并行能力(同一个项目可以同时跑多个 agent)。它是产品,不是框架,但提供插件机制。
Claude Code(Anthropic):终端里的交互式编码智能体,主打"人始终在循环里"(in-the-loop)。本地运行,用 CLAUDE.md 存放仓库规则,提供 25 个生命周期 hook、sub-agent 与 Agent Teams、MCP,当前在 SWE-Bench Verified 上分数较高。
OpenAI Codex(CLI):OpenAI 的编码智能体,走异步"交接"工作流,默认在云端沙箱运行,使用 AGENTS.md(开放标准),支持并行云端沙箱子智能体,单任务 Token 效率更高。
DeepSeek Harness:DeepSeek 官方推出的智能体运行框架(Harness),官方公式是 Agent = Model + Harness。模型只是"灵魂",Harness 提供让智能体在真实环境里干活的一切:文件访问、工具调用、内存、沙箱、重试、任务拆解、结果交付。架构基于 Cordis 微内核,一切皆插件,模型适配器、工具、Skill、会话、存储、agent loop 都是插件。它是"造 Agent 的环境",不是某一款具体的模型产品。
9.2 选型对照表¶
| 维度 | DeepSeek Harness | OpenCode | Claude Code | Codex CLI | WorkBuddy(腾讯) |
|---|---|---|---|---|---|
| 本质 | Agent 运行框架与开发环境 | 开源编码 Agent 产品 | 编码 Agent 产品 | 编码 Agent 产品 | 办公 Agent 套件(含 CodeBuddy 编码 CLI) |
| 出品方 | DeepSeek | 开源社区 | Anthropic | OpenAI | 腾讯云 |
| 是否开源 | 官方产品 | 开源 | 闭源 | 闭源 | 闭源 |
| 是否绑定模型 | 不绑定,可插拔 | 不绑定,75 家以上供应商与本地模型 | 绑 Claude | 绑 OpenAI | 多模型可选 |
| 运行形态 | 本地优先,插件化 | 终端、IDE、桌面 | 本地终端 | 默认云端沙箱 | 本地桌面加云 |
| 核心卖点 | 可编程运行时,一切皆插件 | 开源、模型自由、LSP、多会话并行 | 交互感、长程规划、MCP | 异步批量、并行子代理、省 Token | 办公全场景 |
| 配置与约定 | 插件与 Skill 体系 | opencode 配置与插件 | CLAUDE.md |
AGENTS.md(开放标准) |
自有文档与 CLI |
| 适用场景 | 自建与定制 Agent、教学 | 想自由选模型的编码 | 交互式重构、长任务 | 批量、测试、CI | 办公自动化加轻量编码 |
提示:如果你只想装一款,按用途选就行。写材料、做课件、处理日常文档,选 WorkBuddy;改代码且希望模型可换,选 OpenCode;追求最强的交互式编码体验,选 Claude Code;需要可编程地定制自己的智能体,选 DeepSeek Harness。
第 10 章 WorkBuddy(腾讯)¶
10.1 下载与安装¶
注册地址:https://www.workbuddy.cn/events/invite?inviteCode=yw5sxcpw2r
也可以扫码注册:

这款软件采用图形界面,安装即可使用,无需命令行操作,对新手最友好。新用户注册赠送 2000 积分,目前每日签到可获得 100 积分。
10.2 模型配置¶
如果想使用其他厂商的模型,可以在设置中配置自定义模型。


方式一:使用内置的提供商¶
如果你在 DeepSeek 或智谱 AI 平台充值过,可以直接选择对应的模型提供商。
以智谱 AI(智谱 BigModel 平台)为例,进入控制台页面创建 API Key。

注意:API Key 仅在创建时完整展示一次,后续无法查看或恢复,请立即保存到安全的地方。
创建时名称填写 workbuddy,这只是一个标识名称,用途是提醒你它用在哪里。


复制 API Key 并妥善保存。

将 API Key 粘贴到对应的输入框中,保存即可。

方式二:完全自定义模型¶
WorkBuddy 内置的模型提供商数量有限,因此需要掌握自定义配置的方法。下面仍以硅基流动为例,它汇集了绝大多数国产模型。
选择自定义时,API Key 的填写方式与前面相同,但需要自己额外填入接口地址和模型名称两项。

获取模型名称:在硅基流动的模型广场,找到想要配置的大模型。

比如要配置腾讯的 tencent/Hy4-preview,模型名称直接复制即可。

获取接口地址:点击 API 文档查看,进入后直接点击复制按钮即可。

硅基流动的接口地址统一为:
配置完成后,在对话窗口即可选择使用刚刚添加的模型。

验证方法:添加成功后,在对话窗口的模型下拉列表中能看到新模型,且发送一条简单消息能正常收到回复,即表示配置正确。若提示认证失败,优先检查 API Key 是否复制完整(前后不要带空格)。
10.3 安装与使用 SKILL¶
通过搜索即可安装 SKILL。比如想安装一个自动撰写文献综述的 SKILL,直接搜索名称并点击安装。

新建任务时,需要选择一个工作空间,也就是本地电脑上的一个文件夹。建议一个项目或任务对应一个文件夹,生成的资料都会保存在该文件夹下。

然后通过加号添加已安装的技能。

添加完成后即可开始使用。

领域集成应用:BioMed AI¶
针对部分专业领域,腾讯已经开发好集成应用,例如与华大基因合作推出的 BioMed AI。

其中集成了大量生物医药领域的 SKILL,包括许多生物信息分析工具。

提示:对生物医药方向的使用者来说,BioMed AI 值得优先尝试。它把常用的生信分析流程封装成现成能力,省去了逐个配置工具链的麻烦,适合作为教学演示与课题探索的起点。
第 11 章 OpenCode¶
11.1 下载与安装¶
打开命令行窗口(按 Win + R,输入 cmd,回车进入),输入以下命令即可安装:

OpenCode 也提供桌面版应用,可从发布页(releases page)或 https://opencode.ai/zh/download 下载。桌面版操作与其他智能体大同小异,本章介绍的是命令行启动方式,因为它的可配置性更强。
注意:如果安装命令报错,先确认第 7 章的 Node.js 是否已正确安装并能在命令行中输出版本号。
11.2 启动¶
安装完成后,重启命令行窗口,输入 opencode 并回车即可启动,启动后界面如下。

11.3 模型选择与配置¶
在窗口中输入 / 会弹出很多命令提示,常用的是模型选择与 SKILL 选择。

选择 model 后,会让你选择具体模型。此后你提交的任务都会由这个模型来完成。列表中标注 Free 的模型可以免费使用,但每天有限额,一般任务够用,缺点是并非当前主流模型。

按 Ctrl + A 显示所有模型提供商。这里选择硅基流动,因为它一个密钥就能使用国内几乎所有模型,比单独去 DeepSeek 或智谱 AI 等厂商平台订阅方便得多。

随后会弹出粘贴 Key 的窗口,把前面在硅基流动创建的密钥粘贴进去即可。

回车后就可以选择你想使用的模型。

选择完成后即可正常使用。

提示:
/命令菜单是 OpenCode 的主要交互入口,除了model,还有会话管理、SKILL 调用等命令。初次使用时不妨逐项浏览一遍,能省下大量记忆成本。
11.4 SKILL 的配置¶
OpenCode 的 SKILL 有两种配置层级,按需选择即可。
全局配置¶
修改全局配置文件,路径中的 Lenovo 是用户名,请替换为你自己的用户名。
打开文件后,把你的 SKILL 所在路径添加到 paths 中。下面的示例配置了三个路径。

{
"$schema": "https://opencode.ai/config.json",
"skills": {
"paths": [
"E:/BaiduSyncdisk/00-gitHubProjects/ai-skills/skills/skills",
"E:/BaiduSyncdisk/00-gitHubProjects/ai-skills/nature-skills/skills",
"E:/BaiduSyncdisk/00-gitHubProjects/ai-skills/OpenClaw-Medical-Skills"
]
}
}
项目配置¶
在项目文件夹中创建一个名为 .opencode/skills 的两层文件夹,把该项目用到的 SKILL 放进这个文件夹即可。
提示:全局配置适合放通用 SKILL,比如文档处理、代码规范;项目配置适合放专用 SKILL,比如某个课题特有的分析流程。两者可以同时生效,项目级配置的优先级更高。
注意:配置文件中的路径请使用正斜杠
/,即使在 Windows 上也是如此。使用反斜杠时需要在 JSON 中转义,容易出错。
第 12 章 Claude Code¶
Claude Code 是 Anthropic 推出的 AI 编程工具,直接在终端里运行。你用自然语言描述需求,它就能自主分析项目、写代码、执行命令、修复 Bug,全程自主执行。
12.1 安装¶
Windows 系统
# 以管理员身份打开 PowerShell 或命令提示符
# 全局安装
npm config set allow-scripts=@anthropic-ai/claude-code --location=user
npm install -g @anthropic-ai/claude-code
# 验证安装
claude --version
Linux 与 macOS 系统
注意:Windows 上第一条
npm config set命令是为安装脚本授权,漏掉这一步会导致安装中断。
12.2 网络配置¶
安装完成后,在你的用户目录下找到 .claude 文件夹,在其中新建一个名为 settings.json 的文件。

用记事本打开 settings.json,粘贴以下内容并保存:
注意:
7897是本例所用网络工具的端口,你需要查看自己所用软件的实际端口并相应修改。更多细节参考 https://code.claude.com/docs/en/network-config。如果你使用的是国内模型路由(见第 15 章),则无需配置代理。
12.3 启动与登录¶
在命令行窗口输入 claude 并回车即可启动,然后选择自己喜欢的风格模式。

接下来会让你选择登录方式,共有三种:
- 带有订阅套餐的 Claude 账号:Pro、Max、Team 或 Enterprise 版;
- Anthropic 控制台账号:按 API 调用量计费;
- 第三方平台:亚马逊 Bedrock、微软 Foundry 或谷歌 Vertex AI。

选择第一种:浏览器会弹出登录页面,登录后即可进入订阅选项。

网页端同样可用。

选择第二种:需要先登录 Claude 平台(https://platform.claude.com/)生成 API 密钥。

注意:此处的界面上不要点击"设置身份联合",那是面向企业单点登录的选项,个人使用不需要。

填写名称信息。

生成密钥后请立即保存。当然,使用这种方式需要先向账户充值。

提示:如果你不想订阅 Claude,也不想充值 Anthropic 控制台,最省事的方案是跳过登录配置,直接用第 15 章的 CC Switch 把 Claude Code 路由到国内模型上。
第 13 章 ChatGPT 与 Codex¶
这一款的安装最为简单,不需要命令行。
13.1 安装¶
在应用商店中直接搜索 ChatGPT 或 Codex,即可安装。

13.2 使用¶
登录 ChatGPT 账号即可使用。

提示:Codex 适合处理批量、可异步的任务,比如批量改写、自动生成测试用例。它默认在云端沙箱运行,不占用本地资源,但需要注意代码与数据会被上传到云端,涉密项目慎用。
第 14 章 DeepSeek Harness¶
14.1 产品定位¶
DeepSeek Harness 开发者预览版网址:https://www.deepseek.com/harness/

与其他几款产品不同,Harness 不是一个"开箱即用"的助手,而是一套让你构建智能体的运行环境。官方给出的公式是 Agent = Model + Harness,意思是模型提供智力,Harness 提供让这份智力在真实环境中落地的一切设施。
14.2 安装¶
通过命令行安装。下面的命令既是安装命令,也是启动命令:如果尚未安装会自动先安装,已安装则直接启动。

14.3 启动¶
启动后浏览器会自动打开页面。若没有自动打开,可在浏览器中手动访问 http://127.0.0.1:3080/。

14.4 桌面版¶
桌面版直接下载 exe 文件安装即可,下面是界面截图。

登录自己的账号后,可在设置中配置模型。

下面是一个配置案例。

配置完成后,在对话窗口即可选择已配置的模型。

14.5 安装 dsh 插件¶
在 dsh 中可以安装各种插件。获取渠道包括官方库(https://github.com/topics/dsh-plugin,目前数量较少)、医学论坛与社区,以及 SkillHub。
举例来说,有一个插件可以让你无需登录、注册或填写 API Key,就能使用包括 DeepSeek V4.1 Flash、Kimi K3 在内的前沿模型,完全免费且不限量:
- SkillHub 页面:https://skillhub.cn/plugins/Ebony-Vinyl/dsh-our-free-model
- GitHub 地址:https://github.com/Ebony-Vinyl/dsh-our-free-model

安装后立即启用。

之后就可以使用这些免费模型了。

注意:免费额度类插件通常由第三方维护,稳定性与合规性没有官方保障,适合学习试用,不建议用于正式业务。
第四部分 模型路由¶
第 15 章 CC Switch 的安装与配置¶
15.1 它解决什么问题¶
Claude Code 与 Codex 这类产品在设计时默认绑定自家模型,想让它们改用国内模型,按常规方式要手工改写一系列环境变量和配置项,过程繁琐且容易出错。
CC Switch 把这件事变成了一个可视化操作:你在界面上填好国内模型的接口信息,它负责把这些配置注入到对应产品中,并可以随时切换回原配置。这就是所谓"路由"。
对国内用户而言,它最大的价值是让原本必须用海外模型的产品也能稳定地跑在国内模型上,既省成本,又免去网络困扰。
15.2 下载及安装¶

安装后的主界面左侧列出可配置的智能体产品,可以为这些产品分别配置路由。Claude 与 Codex 尤其需要这一步,因为它们要使用国内模型时必须配置路由。

15.3 配置 Claude Code¶
以 Claude Code 为例,点击添加供应商。可以根据要使用的模型厂商配置,也可以通过第三方平台配置。

下面是自定义配置界面,把相关信息填写完整即可。

展开高级选项,配置模型角色。

五个模型角色的含义与推荐填法¶
Claude Code 在运行时会按用途调用不同角色,因此这里需要为每个角色指定一个具体的模型 ID。下表给出各角色的定位,以及以硅基流动为例推荐填入的模型 ID。
| 模型角色 | 定位与用途 | 推荐填入的模型 ID(硅基流动) |
|---|---|---|
| Sonnet | 默认主力模型,日常编码首选。中等推理能力,速度、成本、代码能力均衡,用来写业务代码、重构、代码审查、调试普通 bug,是 Claude Code 默认使用的角色。 | deepseek-ai/DeepSeek-V4-Flash |
| Opus | 强推理重型模型。用于高复杂度难题:系统架构设计、疑难底层 bug、安全审计、大规模项目方案规划。推理最强,价格最贵,速度偏慢。 | deepseek-ai/DeepSeek-V4-Pro |
| Fable | 顶级深度思考模型,比 Opus 思考深度更强,适合极复杂长链路推理、大型系统深度分析、复杂科研级代码。 | moonshotai/Kimi-K2.7-Code |
| Haiku | 轻量极速模型。适合简单、大批量、快速的任务:文件检索、简单文本提取、grep 查找、快速摘要、子代理的轻量查询。速度最快,token 最便宜。 | Qwen/Qwen3.5-35B-A3B |
| Subagent | 子代理专用模型。Claude Code 可以自动派生小的子 Agent 并行执行子任务(批量文件读取、搜索、简单处理)。这个角色专门给后台子代理使用,不会在 /model 命令菜单里显示,一般填 Haiku 或 Sonnet。 |
Qwen/Qwen3.5-35B-A3B |
提示:角色划分的本质是成本与能力的分层调度。日常任务落在便宜的 Sonnet 与 Haiku 上,遇到难题才动用 Opus 与 Fable。合理填写这五个角色,能在几乎不损失体验的前提下显著降低开销。
下面是一个设置案例。

添加完成后,即可启用该配置。

在路由页面可以检测配置是否连通。确认连通后,即可开启路由。

验证方法:重新启动命令行窗口,启动
claude,通过/model命令即可看到并切换刚刚配置的模型。如果/model菜单里没有出现新模型,检查配置是否已启用,以及命令行窗口是否为重启后的新窗口。

15.4 配置其他智能体¶
其他智能体配置国内模型的方法与 Claude Code 类似。下面是配置 ChatGPT 与 Codex 的截图案例。

配置好并开启路由后,重启 Codex 即可切换模型。

注意:每次修改路由配置后,都必须重启对应的智能体程序才能生效。这是最常见的"配置没生效"原因,排查时请首先确认这一点。
附录¶
附录 A 常见问题与故障排查¶
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
| 命令行提示"不是内部或外部命令" | 环境变量未生效,或软件未安装成功 | 关闭命令行窗口重新打开;仍无效则重启电脑;最后检查安装是否成功 |
npm install 报权限错误 |
未以管理员身份运行(Windows) | 右键选择"以管理员身份运行",或在命令前加 sudo(Linux 与 macOS) |
| 安装过程长时间无响应 | 网络不通,或 npm 源访问缓慢 | 检查网络;可尝试更换为国内 npm 镜像源 |
| 提示 API Key 无效或认证失败 | 密钥复制不完整、带空格,或已过期被删除 | 重新复制密钥,注意去除首尾空格;必要时重新创建 |
| 提示余额不足 | 账户额度用尽或未充值 | 到对应平台充值,或改用有免费额度的平台 |
| 模型列表为空或看不到某模型 | 该平台未开通此模型,或模型 ID 填写错误 | 到平台模型广场核对模型 ID,注意大小写与斜杠 |
| 配置了路由但模型没变 | 未启用配置,或未重启智能体程序 | 在 CC Switch 中确认已启用,然后关闭并重新启动该产品 |
| 长任务进行到一半开始答非所问 | 上下文窗口溢出 | 拆分任务,或改用支持更长上下文的模型 |
| 输出质量忽高忽低 | 温度设置不合适 | 严谨任务调低温度,创意任务调高温度 |
| 智能体找不到本地文件 | 工作目录选择错误 | 确认启动时所在目录,或在提示词中给出完整路径 |
| 回答流畅但内容与事实不符 | 模型幻觉 | 见第 2 章。要求提供依据,关键信息交叉验证,降低温度,改用 RAG 接入真实资料 |
| 给出的参考文献查不到 | 幻觉中的文献编造 | 到 PubMed、Web of Science 或期刊官网按 DOI 与作者核对,确认前不得引用 |
| 问同一个问题两次答案不一样 | 采样随机性,或问题本身超出模型知识范围 | 降低温度;新开对话重问比对;必要时改用检索类方案 |
| 模型不知道最近发生的事 | 知识截止日期限制 | 开启联网搜索,或用 RAG 把最新资料接入 |
| 问私有资料时答不上来 | 模型训练时不可能见过这些资料 | 用 RAG 建立本地资料库,见第 3 章 |
提示:排查问题有一个通用顺序:先确认网络,再确认密钥,最后确认配置项。绝大多数配置失败都出在这三处,而且按顺序排查能避免无谓的重装。
附录 B 术语表¶
| 术语 | 含义 |
|---|---|
| 大语言模型(LLM) | 通过大规模数据训练、能够理解与生成自然语言的基础模型,是智能体的智力来源 |
| 预训练 | 在海量文本上训练模型"预测下一个字"的阶段,模型由此获得语言能力与世界知识 |
| 监督微调(SFT) | 用人工编写的高质量问答对继续训练,让模型学会理解并按指令行事 |
| 偏好对齐 | 依据人类对答案的偏好打分来调优,使输出更安全、更有用,常见方法包括 RLHF 与 DPO |
| 参数 | 模型内部存储知识的可调节数值,参数量大体决定能力上限 |
| 知识截止日期 | 训练数据覆盖到的时间点,此后的信息模型并不掌握 |
| 幻觉(Hallucination) | 模型生成与事实不符但表述流畅、语气自信的内容 |
| 微调(Fine-tuning) | 用自己的数据继续训练模型,改变其风格或任务习惯,与 RAG 的外部检索相对 |
| 智能体(Agent) | 在大模型基础上增加规划、记忆与工具调用能力,可自主完成多步骤任务的系统 |
| SKILL | 封装了特定工作流程与工具用法的操作手册,可被智能体按需加载 |
| Tool(工具) | 完成单一动作的最小能力单元,如读取文件、执行搜索 |
| MCP | 模型上下文协议,规定智能体与外部工具、数据的统一接入方式 |
| 上下文(Context) | 模型在一次任务中能够同时"看到"的全部信息,包含历史对话与参考资料 |
| 上下文窗口 | 上下文的容量上限,超出后早期信息会被丢弃 |
| 温度(Temperature) | 控制生成随机性的参数,数值越低输出越确定,越高越发散 |
| 提示词(Prompt) | 用户输入给模型的任务指令 |
| Token | 模型处理文本的基本计量单位,也是计费单位,中文通常一个字约等于一个 Token |
| API Key | 调用模型服务的凭证,兼具身份识别与计费功能 |
| BaseURL | 接口地址,指明请求发往哪个服务端点 |
| 模型 ID | 模型在平台上的唯一标识,如 deepseek-ai/DeepSeek-V4-Flash |
| 路由 | 把原本指向某一模型的请求改道到另一模型的技术手段 |
| 沙箱 | 隔离的运行环境,在其中执行的操作不会影响本机系统 |
| Sub-agent(子代理) | 由主智能体派生、并行处理子任务的小规模智能体 |
| LSP | 语言服务器协议,为编辑器提供代码补全、跳转、诊断等能力 |
| RAG | 检索增强生成,先从资料库中检索相关内容,再连同问题交给模型作答的技术 |
| 向量库 | 存放文本向量的数据库,支持按语义相似度检索,是 RAG 的核心组件 |
| 切分(Chunking) | 把长文档切成若干语义完整片段的过程,切分质量直接决定 RAG 效果 |
| 重排序(Rerank) | 对粗召回的结果重新打分排序,提升检索精度的第二道工序 |
| Embedding | 把文本转换为向量的过程,是语义检索的基础 |
| 多模态 | 模型同时处理文字、图像、音频等多种输入形式的能力 |
| Hook | 在智能体执行流程的特定节点自动触发的自定义脚本 |
| LTS | 长期支持版,指软件中更新节奏慢、稳定性优先的版本分支 |
附录 C 密钥安全与成本管控清单¶
安全部分
- 每个用途单独创建一个密钥,命名时注明用途与设备
- 密钥只保存在密码管理器或本地加密文件中,不放在明文文档里
- 提交代码或分享文档前,检查是否夹带了密钥
- 不在群聊、论坛、公开教程中暴露密钥明文
- 每季度核查一次密钥列表,删除长期不用的密钥
- 发现泄露立即删除并重建,同时核对调用记录
成本部分
- 优先使用有免费额度的平台完成配置与试用
- 为不同角色配置不同档位的模型,日常任务用轻量模型
- 在平台设置消费提醒或额度上限
- 长任务拆分成小任务,避免上下文无谓膨胀
- 定期查看用量统计,识别异常调用
附录 D 命令速查表¶
| 操作 | 命令 |
|---|---|
| 验证 Node.js 安装 | node -v |
| 验证 npm 安装 | npm -v |
| 安装 OpenCode | npm install -g @opencode/cli |
| 启动 OpenCode | opencode |
| 安装 Claude Code(Windows) | npm install -g @anthropic-ai/claude-code |
| 安装 Claude Code(Linux 与 macOS) | sudo npm install -g @anthropic-ai/claude-code |
| 验证 Claude Code 安装 | claude --version |
| 启动 Claude Code | claude |
| 切换模型(Claude Code 内) | /model |
| 打开命令菜单(OpenCode 内) | / |
| 显示全部模型提供商(OpenCode 内) | Ctrl + A |
| 安装并启动 DeepSeek Harness | npx @deepseek-ai/dsh web |
| Harness 手动访问地址 | http://127.0.0.1:3080/ |
关键配置文件路径
| 用途 | 路径 |
|---|---|
| OpenCode 全局配置 | C:\Users\<用户名>\.config\opencode\opencode.json |
| OpenCode 项目 SKILL 目录 | <项目目录>\.opencode\skills |
| Claude Code 网络配置 | C:\Users\<用户名>\.claude\settings.json |
| 硅基流动接口地址 | https://api.siliconflow.cn/v1/chat/completions |
附录 E 主要资源索引¶
模型与评测
| 资源 | 网址 |
|---|---|
| OpenCompass 开放罗盘 | https://opencompass.org.cn |
| SuperCLUE | https://www.superclueai.com |
| LMArena | https://arena.lmsys.org |
| LiveBench | https://livebench.ai |
| ModelSage | https://modelsage.cn/leaderboards |
密钥与平台
| 资源 | 网址 |
|---|---|
| 硅基流动 | https://cloud.siliconflow.cn/i/zHUE3fOY |
| 基元律动 | https://tokenrhythm.studio/i/rf_tr_9QVRNE |
| DeepSeek 开放平台 | https://platform.deepseek.com/usage |
| 智谱 BigModel | https://bigmodel.cn/ |
产品与工具
| 资源 | 网址 |
|---|---|
| Node.js | https://nodejs.org/zh-cn |
| WorkBuddy | https://www.workbuddy.cn/events/invite?inviteCode=yw5sxcpw2r |
| OpenCode | https://opencode.ai/zh |
| DeepSeek Harness | https://www.deepseek.com/harness/ |
| CC Switch | https://ccswitch.asia/zh |
| SkillHub | https://skillhub.cn/ |
| SkillsMP | https://skillsmp.com/zh |