空缺的博客

DeepSeek Harness 写第一个插件：给 Agent 加个 IP 查询工具

2026-08-27T12:00:00.000Z

生命不息，折腾不止。上次说好的「写插件」来了——今天手把手给 dsh 的 Agent 造一个 IP 查询工具，让它多一门手艺。

从基础安装到接中转站，dsh 已经跑起来了。但光会用别人的东西，那只是「用户」；能往里加自己的东西，才叫「玩家」。dsh 最迷人的地方就在这：一切皆插件，工具、模型、会话、UI 全都可以自己换。今天就兑现承诺，写第一个插件。

一、先搞懂：dsh 的「一切皆插件」到底是啥

DeepSeek Harness（简称 dsh）的核心设计就一句话：一切皆插件。模型适配器、工具、会话存储、Agent 循环、甚至 Web UI 的面板，全都是插件。底层由 Cordis 这个元框架负责加载、卸载和依赖解析，插件之间通过「服务」和「事件」协作。

所以插件不是外挂，它可以替换或扩展 Agent 的任何部分。理解了这个，你就摸到了 dsh 的命门。

那一个插件到底长啥样？官方文档（仓库里的 docs/user/develop/basic/index.zh.md）说得很直白：

插件是一个导出 apply 函数的 TypeScript 模块。框架在加载时调用 apply，传入一个 ctx（上下文对象），你通过 ctx 注册能力。

最简单的插件，就这么几行：

import type { Context } from '@deepseek-ai/cordis'

export const name = 'my-plugin'

export function apply(ctx: Context) {
  // 在这里注册你的能力
}

几个要点记一下：

name：插件名，要唯一
apply(ctx)：入口函数，ctx 是「上下文对象」，注册工具、监听事件、开定时器都通过它
inject：声明依赖，比如 export const inject = ['tools']，框架会等工具注册表就绪后才调用你的 apply

还有两个很贴心的设计：

自动清理：通过 ctx 注册的事件监听、工具、定时器，插件卸载时全部自动清理，你永远不用手写 removeListener
ctx.effect()：如果你有网络连接这种要手动关闭的资源，用 ctx.effect(() => { ...; return () => 清理 }) 告诉框架怎么收尾

插件有三种写法：函数（日常够用）、对象（带生命周期钩子）、类（Service 子类，给别人提供服务）。写工具插件，函数形式基本就够了。

二、最小闭环：先让 dsh 认你这个插件

环境要求：Node ^22.19 或 >=24，低于这个版本 dsh 起不来。还没装 dsh 的先把 Web 版跑起来：

1 2	npx @deepseek-ai/dsh web # Web UI 地址：http://127.0.0.1:3080

然后建个本地开发目录，写一个最朴素的插件：

1	mkdir -p scratch-plugin/src

// scratch-plugin/src/hello-plugin.ts
import type { Context } from '@deepseek-ai/cordis'

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  console.log('[hello-plugin] plugin loaded!')
}

再建一个覆盖层文件 cordis.yml。注意：本地开发阶段，插件路径要写绝对路径，相对路径会解析失败：

# scratch-plugin/cordis.yml
- insert:
    - id: hello
      name: '/绝对/路径/到/scratch-plugin/src/hello-plugin.ts'

用覆盖层启动：

1	npx @deepseek-ai/dsh web --patch ./scratch-plugin/cordis.yml

启动日志里看到 [hello-plugin] plugin loaded!，说明 dsh 已经认你了。最小闭环达成：加载插件 → 注册能力 → 生效。

三、实战：写一个 IP 归属地查询工具

插件本身没意思，给 Agent 加个真能干的工具才有意思。今天的目标：让 dsh 里的 Agent 学会查 IP 归属地——你说「帮我看看 8.8.8.8 是哪的」，它调工具给你返回「美国弗吉尼亚州 Ashburn，运营商 Google LLC」。

我用纯 ESM 写（免构建，Node 直接跑），接口用 ip-api.com 的免费 JSON 接口，不用注册不用 key，自用完全够（免费版每分钟约 45 次限额，商用要付费，以官网为准）。

// index.js
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'ip-lookup'
export const inject = ['tools']

export function apply(ctx) {
  ctx.tools.register(defineTool({
    name: 'ip_lookup',
    description: '查询 IP 地址的归属地信息（国家、城市、运营商）',
    parameters: {
      ip: { type: 'string', required: true, description: '要查询的 IP 地址，例如 8.8.8.8' },
    },
    async execute(args) {
      const res = await fetch(`http://ip-api.com/json/${args.ip}?lang=zh-CN`)
      const data = await res.json()
      if (data.status !== 'success') {
        throw new Error(`查询失败：${data.message || '未知错误'}`)
      }
      return {
        ip: data.query,
        country: data.country,
        regionName: data.regionName,
        city: data.city,
        isp: data.isp,
      }
    },
    output: {
      schema: {
        type: 'object',
        additionalProperties: true, // 这个必须写 true，否则注册直接失败
        properties: {
          ip: { type: 'string' },
          country: { type: 'string' },
          regionName: { type: 'string' },
          city: { type: 'string' },
          isp: { type: 'string' },
        },
      },
      render(output) {
        return `IP ${output.ip} 归属地：${output.country} ${output.regionName} ${output.city}，运营商：${output.isp}`
      },
    },
  }))
}

代码不长，拆开讲：

defineTool 从 @deepseek-ai/dsh-tools 导入，帮你做参数校验和输出校验
parameters：声明参数 schema，模型会照着这个自动生成调用参数
execute(args)：真正干活的地方，这里就是调 ip-api.com 的 HTTP 接口
output.schema：返回值校验；output.render：把结构化结果渲染成模型能直接读的话
坑：object 类型的输出 schema 必须写 additionalProperties: true，不然注册直接失败——我在这上面栽过

装进 profile 跑起来（两种方式二选一）：

# 方式一：本地路径直接装（需要 pnpm，没有就先 npm install -g pnpm）
dsh plugin --profile web add .

# 方式二：开发时用覆盖层（不需要 pnpm）
npx @deepseek-ai/dsh web --patch ./cordis.patch.yml

然后在 Web UI 里开个新会话，直接说：

帮我查一下 8.8.8.8 的归属地

你会看到 Agent 展开工具调用：IN 传参、OUT 返回结果，一气呵成。至此「加载插件 → 注册工具 → 模型调用 → 返回结果」的完整闭环就通了。

顺带说一句：不想手敲这些代码的话，可以把插件开发文档扔给 DeepSeek 让它自己写——社区里已经有人这么干出了 arXiv 搜索插件。模型写插件、你负责验收，这就是 Agent 时代的生产方式。dsh 默认接 DeepSeek 官方，习惯走中转的朋友也可以在 provider 里配 ai.aklibk.com，基础接入方式前面那篇讲过了，不重复。

四、从本地到发布：三件套打包

本地能跑只是第一步，想让插件真正可安装、可分享，需要三件套：

1. package.json（声明这是个 dsh 插件）

{
  "name": "dsh-ip-lookup",
  "version": "0.1.0",
  "type": "module",
  "main": "index.js",
  "files": ["index.js", "cordis.patch.yml"],
  "keywords": ["dsh-plugin", "deepseek-harness"],
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}

2. index.js——就是上面那个插件本体

3. cordis.patch.yml（告诉 dsh 怎么挂载它）

1
2
3

- insert:
    - id: ip-lookup
      name: dsh-ip-lookup

⚠️ files 数组里必须包含 cordis.patch.yml！漏了它，包能装上但插件层根本不生效——这是发布目录里最常见的翻车点，装完发现啥都没有，先查这个。

发布三步走：

推到 GitHub 公开仓库
仓库打上 dsh-plugin topic——这是官方约定的发现机制，社区目录就靠它索引
README 里写清安装方式、插件能访问什么、测试过的 dsh 版本

之后别人一条命令就能装：

1	dsh plugin --profile web add github:你的账号/dsh-ip-lookup

装完重启 profile 就生效。如果插件装了但界面/工具没出现，别急着猜，先看配置树：

1	dsh --profile web --dump-config

它会打印当前真正组合出的插件树，你的插件在不在里面一目了然——不在就是安装环节的问题，不是代码问题。

五、踩坑清单 & 安全提醒（必看）

把这一路的坑汇总一下：

object 输出 schema 要写 additionalProperties: true，否则 defineTool 注册直接失败
files 漏掉 cordis.patch.yml → 装上了但没挂载层，等于白装
patch 是整行替换，不是深合并：改配置要重述整行 config，只写想改的那个字段会丢掉其它配置
插件是可信代码：dsh 插件跑在宿主进程里，能碰你的文件、网络、浏览器、终端。装社区插件前先看 README 和安装脚本，最好固定 tag/commit，再单独开个 profile 试装，别拿主力工作区当试验场
本地开发挂本地路径时用绝对路径，相对路径会解析失败

写完第一个插件，dsh 在你手里就不再是「开箱即用」的工具，而是「随你捏」的工作台了。

生命不息，折腾不止。下一篇咱们玩个大的：把一个任务拆给多个 Agent 并行干——多 Agent 协作实战，看看 dsh 怎么让几个「分身」同时开跑、最后汇总结论。

DeepSeek V4 接入 MCP 实战：给 Agent 装上「手和脚」

2026-08-26T13:00:00.000Z

生命不息，折腾不止。上一篇我们把代码从旧模型名迁到了 V4，今天再往前一步：把 MCP 接上，让 Agent 真正长出手和脚，能调工具、能干活。

一、MCP 是啥？为什么 2026 年你必须会

先花 30 秒把概念捋清楚，不然下面全是黑话。

MCP（Model Context Protocol，模型上下文协议） 是 Anthropic 在 2024 年 11 月开源的一个开放标准，江湖人称 「AI 应用的 USB-C 接口」。意思很直白：以前每个 AI 工具接一个新数据源，都要单独写一套集成代码，维护成本爆炸；MCP 把「工具提供方」和「AI 应用方」彻底解耦——一个 MCP Server 写一次，Claude、GPT、Gemini、DeepSeek 通吃。

这两年它已经从「Anthropic 家的小协议」长成事实标准了：OpenAI、Google、Microsoft 全都原生支持，Python + TypeScript 两个 SDK 月下载量逼近一个亿，官方 Registry 里登记的 Server 接近一万个。所以学 MCP 不是追新，是补 2026 年的基本功。

它的架构就三层，记住这张图：

Host（宿主）：你天天用的 AI 应用，比如 Claude Code、Cursor、Claude Desktop
Client（客户端）：Host 内部为每个 Server 开的一条连接，你不需要管它
Server（服务端）：提供外部能力的进程，比如 GitHub、数据库、文件系统、天气 API

Server 对外只暴露三种东西：工具（Tools）——模型能调用的函数；资源（Resources）——模型能读的数据；提示词（Prompts）——预写的模板。日常折腾 90% 都在跟 Tools 打交道，今天的实战也围绕它展开。

传输方式有两种：stdio（本地进程，Claude Code / Cursor 默认）和 Streamable HTTP（远程服务，2025 年 11 月规范引入，老掉牙的 SSE 已被官方淘汰）。

二、DeepSeek V4 接 MCP 的底牌：双兼容 + 一个致命坑

DeepSeek V4（2026 年 4 月 24 日发布，MIT 协议）天生就是干这活的料，原因有仨：

1. 接口双兼容，客户端即插即用。 V4 同时提供 OpenAI 兼容和 Anthropic 兼容两套 API，base URL 都是 https://api.deepseek.com，官方文档的示例代码直接填这个地址即可。任何 MCP 客户端只要把模型名填成 deepseek-v4-pro 或 deepseek-v4-flash，直接就能用，不需要任何代理和中间层。

2. 1M 上下文，长任务不爆。 V4 两个模型都支持 100 万 token 上下文，配合它家新的混合注意力架构（KV 缓存省约 90%），以前跑长上下文 Agent 动不动 OOM 的场景，现在便宜又流畅。

3. 便宜。 MCP 干活是典型的「多轮工具调用」：模型列工具 → 调工具 → 读结果 → 再调……一个用户问题背后可能是 3-5 次 API 调用。这个场景下 V4 的价格优势被放大得很明显，flash 干杂活、pro 出结论，成本比国外旗舰低一个量级。

但有个致命坑必须先说：别把 deepseek-r1 指给 MCP 客户端！ R1 这个老模型从设计上就不支持 function calling（工具调用），V4 发布也没改变这一点。你把 MCP 客户端指向 r1，它不会报错，而是一本正经地编造工具输出——看起来像调了工具，实际全是幻觉，这在 Agent 场景里是灾难级的。记住：凡是要接 MCP、要调工具的活，一律用 deepseek-v4-pro 或 deepseek-v4-flash。

三、实战一：3 分钟把现成的 DeepSeek MCP Server 接进 Claude Code

先说最省事的路径：社区有人把 DeepSeek 的 API 包装成了标准 MCP Server，装好直接当工具用。以 @arikusi/deepseek-mcp-server 为例（npm 包名 deepseek-mcp-server，MCP Registry 有登记，也有其他同类项目，比如 DMontgomery40/deepseek-mcp-server，原理一样）：

第 1 步：拿到你的 DeepSeek API Key

去 DeepSeek 开放平台（platform.deepseek.com）创建一个 Key，形如 sk-xxx。充个 20 块够折腾很久。

第 2 步：一条命令注册进 Claude Code

1
2
3

claude mcp add -s user deepseek \
  npx @arikusi/deepseek-mcp-server \
  -e DEEPSEEK_API_KEY=sk-你的key

解释一下：-s user 表示对当前用户全局生效（想只对某个项目生效就把 -s user 换成 -s project）；后面 npx @arikusi/deepseek-mcp-server 是启动命令，npm 会自动拉包，无需手动安装；-e 把 API Key 传进这个子进程的环境变量。

第 3 步：重启 Claude Code，验证注册成功

完全退出 Claude Code 再重新进入（MCP 配置只在启动时加载），然后敲：

/mcp

能看到 deepseek 服务器出现在列表里就成功了。它的工具大概长这样：deepseek_chat（对话）、deepseek_fim（代码补全）、deepseek_sessions（多轮会话），还带成本统计。

第 4 步：让它干活

直接下指令试试，比如：

1	用 deepseek 工具帮我写一个 Python 快排，要求带注释

Claude Code 会把 deepseek_chat 工具连同你的问题一起发给模型（此时驱动 Claude Code 主循环的可以是任何模型），DeepSeek 返回结果后作为工具结果回传，你看到的是一套完整的「Agent 把活外包给 DeepSeek」的流程。默认模型是 deepseek-v4-flash，追求质量可以在调用参数里指定 deepseek-v4-pro。

想删掉这个工具：claude mcp remove deepseek。想查看配置详情：claude mcp get deepseek。

四、实战二：20 行代码写一个自己的 MCP Server

现成的 Server 是别人给你做好的轮子，但真正的乐趣是给自己的数据写工具。用 Python 的 FastMCP 库，20 行代码搞定。以下以官方快速入门为基准，用最新版（FastMCP 3.x）写法：

第 1 步：装环境（用 uv，一行命令装好）

curl -LsSf https://astral.sh/uv/install.sh | sh
uv init my-mcp && cd my-mcp
uv venv && source .venv/bin/activate
uv add "mcp[cli]" httpx

第 2 步：写你的第一个工具

新建 server.py，复制粘贴：

from fastmcp import FastMCP

mcp = FastMCP("my-tools")

@mcp.tool
def add(a: int, b: int) -> int:
    """两个整数相加，先拿它练手"""
    return a + b

@mcp.tool
def get_weather(city: str) -> str:
    """模拟查天气，真实项目里这里换成 requests 调天气 API 即可"""
    return f"{city} 今天晴，26℃"

if __name__ == "__main__":
    mcp.run()  # 默认 stdio 传输

看到了吗？一个 @mcp.tool 装饰器，函数签名 + 中文注释，工具定义、参数校验、文档生成全自动。这就是 FastMCP 的全部魔法。

第 3 步：先本地跑通（可选）

1	fastmcp run server.py

会以 stdio 模式启动。想远程访问就加传输参数：

1	fastmcp run server.py --transport http --port 8000

第 4 步：接进 Claude Code

1	claude mcp add -s user my-tools python /绝对路径/server.py

重启 Claude Code 后 /mcp 里就能看到 my-tools。现在你可以让它「算一下 127 和 358 的和」，看它怎么一步步调用 add 工具；或者加个真天气 API，让 DeepSeek V4 帮你查全球任意城市的天气——模型负责理解，工具负责执行，这就是 Agent 的最小形态。

五、避坑清单（都是真金白银换来的）

模型名必须写对。 MCP 客户端里只填 deepseek-v4-pro / deepseek-v4-flash。填 deepseek-r1 会幻觉工具输出；填 deepseek-chat / deepseek-reasoner 这些 2026 年 7 月已退役的旧名会直接报错。
API Key 一定要传进 Server 进程。 用 claude mcp add 时 -e DEEPSEEK_API_KEY=... 不能漏；手动启动的话先 export DEEPSEEK_API_KEY=sk-xxx。忘了传的表现是 Server 起来但一问就 401。
base URL 要认准。 官方是 https://api.deepseek.com，有些教程让你填别的兼容端点，请确认来源可信。走第三方兼容端点时，记得模型名也要按对方文档改（比如换成你自己的中转站模型名）。
改完配置必须重启客户端。 Claude Code 只在启动时加载 MCP，热改配置不生效，claude mcp add 完没重启然后到处找 bug 的，都是这一步栽的。
别用 SSE 老传输。 2025 年 11 月之后的规范已经切到 Streamable HTTP，新写远程 Server 直接上 HTTP；看到「SSE」字样的老教程留个心眼，写法可能过时了（以官方文档 modelcontextprotocol.io 为准）。
本地 Server 别开公网。 自己写的 stdio Server 只服务本机；要远程用就加 OAuth 认证，裸奔在公网等于把工具权限白送。

六、下一站：让 Agent 打组合拳

今天这两套实战下来，你已经能给 DeepSeek V4 接上「手和脚」了：现成的 Server 拿来即用，自定义工具 20 行就能上。接下来就是组合拳阶段——把 DeepSeek V4 接进 Claude Code 当主力模型，再配上 MCP 工具，一套完整的低成本 Agent 工作台就搭起来了。

顺带说一句，如果你想让 Claude / GPT / Gemini 这些国外模型也走同样的 MCP 玩法，又不想折腾海外信用卡和网络，可以看看 ai.aklibk.com 中转站：一个 Key 通吃 Claude / GPT / Gemini / DeepSeek，人民币按量付费，国内直连免绑卡，DeepSeek 系模型价格还更便宜——同一套 MCP 配置，改个 base URL 和模型名就能切换底层模型，这正是「写一次、处处可用」的价值所在。

生命不息，折腾不止。下一篇聊《DeepSeek V4 + Claude Code 实战：把 Agent 工具接上 DeepSeek》，手把手把整套 Agent 编程工作台搭起来，让 Claude Code 的干活主力变成 DeepSeek V4，配上 MCP 一起上阵。

DeepSeek V4 API 迁移实战：旧名已退役，5 分钟换新模型

2026-08-26T12:00:00.000Z

生命不息，折腾不止。DeepSeek 把用了两年的旧模型名 deepseek-chat 直接砍了，这篇带你 5 分钟完成迁移，顺带躲开账单刺客。

如果你手上还有跑着的 DeepSeek 代码，先别慌，大概率就是改一个字符串的事。但你要是真以为「改个名字」就完事，那 thinking 模式、分时定价这两个新东西分分钟教做人。这篇把来龙去脉、迁移步骤、省钱技巧一次讲清楚。

一、先搞清楚发生了什么

DeepSeek 在 2026 年 4 月 24 日发布了 V4 预览版（MIT 协议开源），API 里新增了两个正式模型名：deepseek-v4-flash 和 deepseek-v4-pro。当时旧的 deepseek-chat / deepseek-reasoner 还在，只是被悄悄当作别名转发到 V4。

然后关键节点来了：2026 年 7 月 24 日 15:59 UTC（北京时间当天 23:59），旧模型名正式退役。之后任何请求只要还写 deepseek-chat 或 deepseek-reasoner，直接返回错误，没有宽限期，没有降级。

官方文档现在只列三个模型名：

模型	说明
`deepseek-v4-flash`	日常主力，快、便宜（当前版本 V4-Flash-0731）
`deepseek-v4-pro`	旗舰，最强推理（当前版本 V4-Pro-0813）
`deepseek-v4-flash-vision-exp`	实验性视觉模型，支持图片输入

好消息是 base URL 完全没变：OpenAI 格式还是 https://api.deepseek.com，Anthropic 格式是 https://api.deepseek.com/anthropic。所以绝大多数项目就是「改个模型名字符串」的事。

二、Flash 还是 Pro？V4 家族怎么选

先看参数和定位（官方公布）：

deepseek-v4-flash：284B 参数 MoE（每次激活 13B），官方称 SWE-bench Verified 72.1%，主打性价比，适合日常对话、批量任务、对延迟敏感的场景。
deepseek-v4-pro：1.6T 参数 MoE（每次激活 49B），官方称 SWE-bench Verified 80.6%，复杂代码、深度推理场景选它。
两者都是 1M token 上下文窗口，最大输出 384K，支持 JSON 输出、Tool Calls、Responses API、Anthropic 兼容格式。

价格（官方文档，单位：美元 / 每 100 万 tokens）：

计费项	v4-flash（峰值/非峰值）	v4-pro（峰值/非峰值）
输入·缓存命中	$0.014 / $0.007	$0.044 / $0.022
输入·缓存未命中	$0.44 / $0.22	$1.32 / $0.66
输出	$1.32 / $0.66	$3.96 / $1.98

注意这个分时定价，DeepSeek 算是第一个这么玩的大厂：工作日（周一至周五）UTC 01:00-04:00 和 06:00-10:00（北京时间 09:00-12:00、14:00-18:00）是峰值，其余时间半价。习惯白天跑批量的同学，挪到晚上能省一半。

选型建议：无脑先上 flash，日常 90% 的场景它都扛得住；真遇到复杂推理和代码题感觉不够，再单独把那条链路切到 pro，别全局升级。

三、迁移实操：改一个字符串，5 分钟收工

旧代码搜索清单先摆出来，对着改就行：

deepseek-chat → deepseek-v4-flash（日常对话、非思考场景）
deepseek-reasoner → deepseek-v4-flash（要省钱的推理场景）或 deepseek-v4-pro（要顶配推理）

改完用 Python + OpenAI SDK 验证（官方示例）：

# pip install openai
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com",
)

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "你是一个全能助手"},
        {"role": "user", "content": "用一句话解释什么是 MoE"},
    ],
    stream=False,
)
print(response.choices[0].message.content)

不写代码，直接 curl 验也行：

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "你好"}]
  }'

注意一个小坑：thinking 模式默认是开的（默认档位 high），所以第一次调用如果发现返回结构里多了一个 reasoning_content 字段，别慌，那是思维链，正常现象。

四、躲开账单刺客：thinking 模式和三个参数坑

迁移完第一件事，建议打开你的账单对比一下。很多人（包括我）发现同样一批任务，跑完价格直接翻倍——原因就一个：V4 默认开 thinking 模式，输出前先吐一大段思维链，而思维链 token 是按输出价计费的，输出恰恰是最贵的部分。

三个参数坑，逐个说：

1. 关 thinking / 降档 effort。 OpenAI 格式下 thinking 开关要放在 extra_body 里（Chat Completions 接口不支持顶层传）：

# 关闭思维链：想省钱、只要快速答案的场景
response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "今天杭州天气怎么样"}],
    extra_body={"thinking": {"type": "disabled"}},
)

# 保留思维链但降档：日常够用，token 少很多
response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "写一段二分查找"}],
    reasoning_effort="low",
    extra_body={"thinking": {"type": "enabled"}},
)

reasoning_effort 支持 low / high / max（medium、xhigh 会被映射成 high）。如果走 Anthropic 格式，对应参数是 reasoning: {"effort": "none/low/high/max"}，none 即关闭 thinking。

2. thinking 模式下，temperature、top_p、presence_penalty、frequency_penalty 全部无效。 不报错，但静默失效。老代码里调这些参数的，迁移后别指望它们还起作用。

3. 多轮对话 + 工具调用时，reasoning_content 必须原样回传。 请求带了 tools 参数的话，每一轮把 assistant 返回的 reasoning_content 拼进下一轮消息，哪怕那一轮没有工具调用，漏了直接 400 报错。不带 tools 的普通多轮则不用管，传了也会被忽略。

五、进阶玩法：让 Claude Code 用上 DeepSeek

V4 一个很香的点：官方把 Anthropic 兼容接口和 Agent 工具集成都做好了。Claude Code、GitHub Copilot、OpenCode 这类 Agent 工具，理论上可以直接把后端模型换成 DeepSeek，不用写代码，改环境变量指向 https://api.deepseek.com/anthropic 就行（具体变量名和配置方式以 DeepSeek 官方 Agent 集成文档为准，不同工具略有差异）。DeepSeek 官方还放出了自己的 agent harness —— DeepSeek Harness，现在还是 developer preview，想尝鲜的可以去官方指南看 quickstart。

另外多说一句：如果你嫌一个模型一个平台地注册、充值、管理 key 太麻烦，想一个 key 通吃 Claude / GPT / Gemini / DeepSeek、人民币按量付费的话，可以看看 ai.aklibk.com 这个中转站，模型切换就是改个模型名的事，跟你今天学的这套玩法无缝衔接。DeepSeek 系列在里面价格也挺实在，多模型对接 + 便宜，正好互补。

生命不息，折腾不止。下一篇可以聊聊怎么把 DeepSeek V4 接进自己的 MCP 服务，让 Agent 真正干起活来，敬请期待。

dsh 写第一个插件：30 行给 Agent 加个会干活的工具

2026-08-26T12:00:00.000Z

生命不息，折腾不止。上次把 DeepSeek Harness 接上中转站只是「会用」，这篇带你走进它的灵魂——自己动手写插件，30 行代码给 Agent 加一个会干活的工具。

一、插件到底是个啥：一切皆插件

DeepSeek Harness（命令行叫 dsh）是 DeepSeek 官方开源的 Agent 框架，它的核心设计就一句话：一切皆插件。这句话不是营销，是字面意思——模型适配器、工具注册表、会话日志、甚至 agent 主循环本身，全都是插件。整个产品就是启动时从若干层配置里组合出来的一棵插件树。

底层驱动是一个叫 Cordis 的插件框架（DeepSeek 魔改了一份 vendored 版本）。在 dsh 眼里，插件就是一个 TypeScript 模块，导出 apply(ctx) 函数，框架加载插件时会调用它，把 ctx 上下文对象传进来，你就在里面注册各种能力。

import type { Context } from '@deepseek-ai/cordis'

export const name = 'my-plugin'

export function apply(ctx: Context) {
  // 在这里注册工具、监听事件、挂服务……
}

这就是一个插件的全部骨架。好处显而易见：想加什么能力不用改主程序，写个插件挂上去就行；插件卸载时，通过 ctx 注册的一切（事件监听、工具、定时器）会自动清理，不用担心残留。

插件有三种形态：函数插件（最常见，上面的就是）、对象插件（带 apply 方法的对象）、类插件（Service 子类，适合对外提供服务）。在你需要公开服务之前，一直用函数形态就够了。

二、环境准备：把源码仓库拉下来

写 dsh 插件，官方推荐在源码仓库里开发，这样能用仓库自带的命令行和脚本（typecheck / lint / test / build），还能用 vendored 启动器做不需要 API Key 的纯链路验证。

环境要求：Node.js ^22.19 或 >=24，包管理器用 pnpm（仓库用 Corepack 锁了版本）。

1
2
3

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install

装完先跑一把确认环境 OK：

1
2
3

pnpm run typecheck   # 类型检查（strict）
pnpm run lint        # oxlint
pnpm run build       # tsc + tsdown 产出 lib/

注意：dsh 目前是 developer preview（v0.1 预览版），README 里大写加粗写着「THERE WILL BE COMPATIBILITY-BREAKING CHANGES」——接口会变，插件开发时留意版本，后续文章会讲怎么 pin 版本。

三、30 行写第一个插件：hello 走一个

在仓库根目录建个临时目录，创建 tmp/hello-plugin/hello.ts：

import type { Context } from '@deepseek-ai/cordis'

export const name = 'hello'

export function apply(ctx: Context) {
  ctx.logger.info('hello from my first plugin')
}

再建一个 cordis.yml（Cordis 配置清单，loader 按它挂插件）：

1	- name: './hello.ts'

然后从 tmp/hello-plugin 目录用仓库自带的 vendored 启动器跑起来（这一步不需要 API Key）：

1	node --import tsx ../../vendor/cordis/bin.js

预期输出：

1	[info] hello from my first plugin

发生了什么？启动器创建根 Context 并挂上 Loader 插件 → Loader 读取 cordis.yml → 把 ./hello.ts 作为子插件挂载 → Cordis 调用你的 apply(ctx)。链路通了，插件的「最小闭环」就成立了。

一个正式的函数插件通常导出四样东西，认识一下：

导出	作用
`name`	插件显示名，仅用于诊断日志
`inject`	声明依赖的服务（如 `['tools']`），loader 会等它们就绪才执行 `apply`
`Config`	可选，部署期配置的校验 schema
`apply(ctx, config)`	插件主体，注册一切能力

两个细节：函数插件必须用命名导出（export function apply），别配默认导出，否则 loader 会丢掉 inject 元数据；有 Config 时 apply 签名是 (ctx, config)，没有时是 (ctx)。

四、把插件挂到 dsh 上：三条路

写好的插件怎么让 dsh 真正加载？三条路，按场景选：

路 1：临时 overlay（调试最快）。写一个 patch 文件，用 --patch 参数启动：

# scratch-plugin/cordis.yml
- insert:
    - id: hello
      name: '/绝对路径/to/deepseek-harness/scratch-plugin/src/hello.ts'

1	pnpm dsh web --patch ./scratch-plugin/cordis.yml

打开 http://127.0.0.1:3080（dsh Web UI 默认端口），终端里能看到 [hello-plugin] plugin loaded!。注意插件路径必须写绝对路径。

路 2：外置插件（正式安装，推荐）。把插件做成独立 npm 包（package.json 里声明 "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }），然后用 dsh plugin 子命令装进 profile——它本质是在 profile 目录里调 pnpm，所以 pnpm 的子命令全能透传：

dsh plugin --profile web add ./hello-plugin          # 本地包
dsh plugin --profile web add github:你的账号/你的仓库   # Git 源，可加 #commit 锁版本
dsh plugin --profile web remove hello-plugin          # 卸载
dsh plugin --profile web update                       # 更新全部

profile 是 dsh 的「可运行环境」，目录在 $DSH_HOME/profiles/<名字>/，web、headless 是内置模板。装完插件记得重启 dsh web，宿主代码在启动时加载，只刷新页面不够。

路 3：看插件树 debug。插件装了却没生效，别对着界面猜，直接打印最终组合出来的配置树：

1	dsh --profile web --dump-config

任何打印出来的行，都可以用你自己的 patch 按行 id 替换。记住 dsh 配置的四层加载顺序：profile bundles → profile 的 cordis.patch.yml → 家目录 $DSH_HOME/cordis.patch.yml → 每个 --patch overlay。后层按行胜出，patch 替换的是整行 config（不是深度合并），改一个字段也得把整行键重述一遍——这是新手最常踩的坑。

五、实战：给模型加一个会干活的工具

插件最常见的用途就是给模型加工具。工具注册在 ctx.tools 上，schema 会自动进入 prompt 组装，模型就能「看到」它并主动调用。

下面是一个完整可运行的最小工具插件（30 行上下，名副其实）：让 Agent 能读文件。核心 API 是 defineTool（来自 @deepseek-ai/dsh-tools）+ ctx.tools.register()：

import { readFile } from 'node:fs/promises'
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'demo-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'read_file',
    description: 'Read a file from disk.',        // 模型看到的能力描述
    parameters: {
      path: { type: 'string', required: true, description: 'Absolute path' },
      limit: { type: 'number' },                    // 可选项，默认不要求提供
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args, exec) {
      // args 已经被 defineTool 按 schema 校验并推导出类型
      return readFile(args.path, { encoding: 'utf8', signal: exec.signal })
    },
  }))
}

拆开看 execute() 契约的几条硬规则：

args 自动校验：defineTool 会在 execute 前校验模型生成的参数（类型、必填、枚举、嵌套），你拿到的 args 类型和 schema 一致；
只返回一个规范 JSON 值：output.schema 定义返回值，execute 只返回它；抛异常 = 出错（isError），业务上的非理想状态（比如非零退出码）也要放进规范值返回；
遵守 exec.signal：信号触发时要取消进行中的工作，别硬扛；
只注册一次：注册借用的是只读定义，事后别改 schema；想换工具就释放它所属的 effect 再注册新的。

这样一个插件装好后，你在 Web UI 里跟 Agent 说「读一下 /opt/xxx/config.yaml 的前 50 行」，模型就会自己调 read_file 工具，把内容读回来再回答你——这就是给 Agent 装「手」的过程。

六、进阶玩法：inject 依赖与事件钩子

不想加新工具，只想在某个环节「插一脚」？用事件钩子。dsh 主循环是事件驱动的，钩子插件就是往这些事件上挂监听器。比如下面这个权限门插件，在每次工具调用前拦截，按规则允许或拒绝：

import type { Context } from '@deepseek-ai/cordis'
import type { PreToolDecision, ToolExecution } from '@deepseek-ai/dsh-tools'

declare function isAllowed(exec: ToolExecution): Promise<boolean>

export const name = 'permission-gate'

export function apply(ctx: Context) {
  ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
    if (!(await isAllowed(exec))) {
      return { kind: 'deny', reason: 'Denied by policy.' }
    }
    return next()
  })
}

tools/pre-execute 是 waterfall 事件：监听器收到 (...args, next)，必须调用 next() 把结果传给下一个监听器；不调 next() 直接 return 就是短路（截断整条链）。这是写监听器最容易踩的坑——忘了 next()。

常用扩展点速查：

你想做什么	用哪个
允许 / 拒绝 / 询问工具调用	`tools/pre-execute`，返回 `{ kind: 'deny' }` / `{ kind: 'ask' }`
工具调用必须被最终否决、不可撤销	`ctx.tools.guard()`
包裹工具执行生命周期（超时/重试/指标）	`tools/execute`
改写工具结果或呈现内容	`tools/post-execute`
只观察最终结果（审计/记录）	`tools/result`

七、避坑提醒

安全第一：插件跑在 dsh 宿主进程里，属于可信代码——装第三方插件前，先看它仓库是否公开、许可证和维护者是否清楚、要什么权限，别因为一行安装命令就跳过检查（官方文档自己都反复强调）；
预览版接口会变：dsh 还是 v0.1 preview，插件契约可能随版本变动，开发时把 harness 版本记进 README，跟 GitHub Discussions 的变更公告；
函数插件别配默认导出：会丢 inject 元数据，导致依赖的服务没就绪就执行 apply；
patch 替换整行：不是深度合并，改一个键也要重述整行；
跑真实模型要 API Key：工具插件要真正被模型调用，得有模型可跑。官方 key 直接填 DEEPSEEK_API_KEY 就行；想一个 Key 玩遍 Claude、GPT、Gemini、DeepSeek 全系模型，可以接 ai.aklibk.com 中转站——OpenAI 兼容接口、人民币按量付费，DeepSeek 系模型价格还便宜，settings 里改个 base URL 就换底层模型，插件的价值直接翻倍。

生命不息，折腾不止。下一篇《DeepSeek Harness 多 Agent 协作实战》，教你把一个大任务拆给多个 Agent 并行干活，让 dsh 从「单打独斗」升级成「团队作战」。

Cursor 接入中转站教程：改一行 Base URL，Claude/GPT 国内直连还便宜

2026-08-22T13:00:00.000Z

生命不息，折腾不止。Cursor 好用，但内置模型要开 Pro 订阅（$20/月）、还得绑海外卡。这篇讲清楚怎么给它接上中转站——改一行 Base URL，Claude、GPT 随便用，人民币按量付费，不用订阅、不用绑卡。

一、Cursor 为什么接中转站

Cursor 是国内开发者用得最多的 AI 代码编辑器，但它的模型分两条路：

内置模型（GPT-4o、Claude 等）—— 要开 Pro 订阅，$20/月，绑海外信用卡；
自定义 API Key —— 填自己的 OpenAI 兼容 key，按量付费。

接中转站就是走第二条路，好处很直接：

不用买 $20/月订阅，充几块钱就能用；
Claude、GPT、Gemini 全都能调，人民币按量付费，用多少花多少；
中转站接口国内直连，不用折腾网络和绑卡。

二、三步接好中转站

第一步：打开模型设置

点 Cursor 右上角齿轮进 Cursor Settings，找到 Models（有的版本叫 Models & API Keys）。

第二步：填 Key 和 Base URL

在 OpenAI API Key 区域：

粘贴中转站的 sk- 开头的 Key；
勾选 Override OpenAI Base URL（覆盖默认地址）；
Base URL 填：https://ai.aklibk.com/v1

⚠️ 结尾是 /v1：不要只填域名、不要补全到 /chat/completions、也不要在末尾多加斜杠。这一个输入框是 90% 接入失败的根源。

第三步：加模型并验证

添加你要用的模型（如 claude-sonnet-4-5、gpt-4o，以中转站后台模型列表为准），点 Verify 验证，通过就能正常用了。

三、两个高频坑

Base URL 格式：必须是 https://ai.aklibk.com/v1，结尾 /v1，别多别少；
模型名：必须和中转站后台的模型 ID 完全一致，填错一个字符 Verify 就过不了。

四、常见问题

Verify 失败：先查 Base URL 是不是 /v1 结尾，再核对模型名；
报 401：Key 没填对，去中转站后台重新复制令牌；
能用哪些模型：Claude、GPT、Gemini、DeepSeek 都行，看中转站开通了哪些。

五、写在最后

Cursor + 中转站，是把 AI 编程成本压到最低的组合——不用 $20 订阅、不用绑卡，按量付费想用多少用多少。中转站我平时用 ai.aklibk.com，Claude/GPT/Gemini/DeepSeek 全系都有，人民币按量、注册即用。

生命不息，折腾不止。后续继续分享 Cline、Roo Code 这些 AI 编程工具的接法。

DeepSeek Harness 接入中转站：一个工具用遍 Claude/GPT/Gemini，按量付费超便宜

2026-08-22T12:00:00.000Z

生命不息，折腾不止。DeepSeek Harness（dsh）是 DeepSeek 官方出的插件化 Agent 框架，虽然名字带 DeepSeek，但它是「一切皆插件」——通过自定义 provider，Claude、GPT、Gemini、DeepSeek 全都能接进来，一个工具想用哪个切哪个。再配个中转站，按量付费还便宜。

一、DeepSeek Harness 是什么

DeepSeek Harness（dsh）是 DeepSeek AI 开源的一个 Agent 框架，核心设计是「一切皆插件」，底层基于 Cordis 架构。你在本地跑一个 Web UI，让 AI Agent 读写项目文件、执行命令、分解任务、维护计划，可以理解为「本地版 AI 编程助手」。

它最值钱的一点：不锁死 DeepSeek。原生支持「自定义 provider」，任何 OpenAI 兼容的接口都能接进来，等于一个框架吃下所有主流模型。

二、两个真正的好处：多模型 + 便宜

1. 一个工具，用遍所有模型

Harness 里可以同时配多个 provider——Claude 一个、GPT 一个、Gemini 一个、DeepSeek 一个。写代码用 Claude、跑推理用 DeepSeek、多模态用 Gemini，同一个工作流里随意切换，不用装一堆客户端。

2. 按量付费，比官方便宜

中转站把 Claude、GPT、Gemini、DeepSeek 这些官方接口转成人民币按量付费的 OpenAI 兼容接口：

不用绑海外信用卡、不用买官方订阅，充几块钱就能试；
按 token 计费，用多少花多少，比官方订阅/按刀计费灵活太多。

对想一次试遍各家模型的开发者来说，这是成本最低的玩法。

三、安装 Harness

先装好 Node.js，一条命令启动：

1	npx @deepseek-ai/dsh web

Web UI 默认跑在 http://127.0.0.1:3080（本地自动开浏览器；SSH 环境加 --no-open）。

四、接入中转站（核心步骤）

打开 Settings → Models
点 Add a custom provider（不是 Add provider，那个是官方目录）
按下面填写：
- Provider ID：小写、唯一，比如 claude、gpt、gemini、deepseek（想接几个模型就建几个）
- Display name：随意，比如「Aklibk · Claude」
- Base URL：https://ai.aklibk.com/v1
- API protocol：选 OpenAI Completions
- API key：中转站后台生成的令牌（同一个 key 通吃所有模型）
- Model：按需填，例如 claude-sonnet-4-5、gpt-4o、gemini-2.5-pro、deepseek-chat，以中转站后台模型列表为准
保存即可，不用重启服务，下一条请求就生效。

中转站里一个 API key 就能调用全部模型，所以你只需要建多个 provider（区分模型），共用同一个 Base URL 和 key 就行。

五、（进阶）用配置文件批量配

不想点 UI，直接改 $DSH_HOME/settings.yaml，一次配齐多个模型：

llm-pi-ai:
  providers:
    claude:
      apiKeyEnv: AKLIBK_API_KEY
      api: openai-completions
      baseURL: https://ai.aklibk.com/v1
      models:
        - id: claude-sonnet-4-5
    gpt:
      apiKeyEnv: AKLIBK_API_KEY
      api: openai-completions
      baseURL: https://ai.aklibk.com/v1
      models:
        - id: gpt-4o
    deepseek:
      apiKeyEnv: AKLIBK_API_KEY
      api: openai-completions
      baseURL: https://ai.aklibk.com/v1
      models:
        - id: deepseek-chat
        - id: deepseek-reasoner

Key 存在 $DSH_HOME/.credentials.yaml，settings 里只留引用。

六、常见问题

模型列表拉不到：Base URL 或协议填错了，确认是 https://ai.aklibk.com/v1 + OpenAI Completions；
请求 401：API key 没填对，去中转站后台重新复制令牌；
某模型报错：确认中转站开了这条线，换个模型 ID 试。

七、写在最后

DeepSeek Harness + 中转站，是「一个框架玩转所有主流模型」最省心的组合。中转站我平时用 ai.aklibk.com，Claude、GPT、Gemini、DeepSeek 全系都有，人民币按量付费、注册即用，想试哪家切哪家，成本还低。

生命不息，折腾不止。后续继续分享 DeepSeek Harness 写插件、跑多 Agent 协作的玩法。

Claude Code 国内配置教程：免翻墙免绑卡，用中转站一步到位

2026-08-22T10:00:00.000Z

生命不息，折腾不止。Claude Code 是 Anthropic 官方的终端 AI 编程工具，写代码体验一流，但国内直接用有两道门槛：网络连不上、官方 API 要绑海外信用卡。这篇讲清楚怎么在国内把它配好，用中转站一步到位。

一、Claude Code 是什么

Claude Code 是 Anthropic 推出的命令行 AI 编程助手，装进终端里，能用自然语言帮你写代码、改 bug、跑测试、做 code review。相比网页版，它直接读你本地项目、改文件，编程效率提升明显。

二、国内直接用的两道坎

网络：Anthropic 的 API 在国内无法直连，直连会一直超时；
支付：官方 API 按 token 计费，需要海外信用卡才能充值。

这两道坎，正好是”中转站”存在的意义。

三、中转站是什么、怎么解决

中转站（API 网关）把 Claude、GPT、Gemini 这些官方模型接口，转成国内能直连、人民币按量付费的接口。你不用翻墙、不用绑卡，注册充个几块钱就能用，成本比官方还低。

以中转站 ai.aklibk.com 为例，它支持 Claude 全系模型，接入方式就是改两个环境变量。

四、配置步骤（3 分钟搞定）

注册中转站拿 Key：打开 ai.aklibk.com 注册，后台「订阅/令牌」里生成一个 API Key（复制好备用）。

装 Claude Code（任选一种）：

# 方式一：npm（推荐）
npm install -g @anthropic-ai/claude-code

# 方式二：一键脚本
curl -fsSL https://claude.ai/install.sh | bash

设置中转站环境变量（关键一步）：
1
2
export ANTHROPIC_BASE_URL=https://ai.aklibk.com
export ANTHROPIC_API_KEY=你的中转站Key
把这两行写进 ~/.bashrc 或 ~/.zshrc，以后就不用重复设。
启动：
1
claude
首次会问你登录方式，选「使用 API Key」即可，然后就能直接对话、写代码了。

五、常见问题

报 401 / 403：Key 没填对，或 base_url 拼错，检查下有没有多余空格；
报连接超时：base_url 没设成中转站地址，还在连官方；
模型怎么选：中转站后台一般有 Claude 多档模型可选，按需选，代码场景选能力强的，省着用可以选便宜档；
贵不贵：按量计费，写一下午代码也就几毛到几块钱，比官方订阅灵活多了。

六、写在最后

Claude Code + 中转站这套组合，是目前国内用 Claude 编程最省心的路子之一。如果你也在折腾 AI 编程工具，中转站可以直接用 ai.aklibk.com，注册即用、人民币按量付费，不折腾网络和绑卡。

生命不息，折腾不止。后面继续分享 Cursor、Codex 这些 AI 编程工具的国内配置方法。

ChatGPT 在中国大陆的安装教程

2026-08-14T14:30:00.000Z

生命不息，折腾不止。这篇整理一份 ChatGPT 在中国大陆的完整安装教程：从网络环境、注册账号，到各平台客户端的下载安装，一次讲清楚。

先说结论

在中国大陆使用 ChatGPT，一共四步：网络环境 → 注册账号 → 下载安装 → 登录使用。

其中最容易卡住的是第二步（注册）：OpenAI 不接受中国大陆的 +86 手机号，这是绝大多数人第一次尝试时被挡下的地方。下面按顺序走。

第一步：网络环境

ChatGPT 官网（chat.openai.com / chatgpt.com）和官方客户端在中国大陆无法直接访问，需要可访问国际网络的网络环境（代理/VPN），这一步是前提，没有它后面都白搭。

⚠️ 请确保你的网络环境符合当地法律法规，本文仅作技术交流。

第二步：注册账号

访问 https://chat.openai.com，点 Sign up 注册，建议全程在稳定的网络环境下操作。

需要的材料：

材料	要求	说明
邮箱	海外邮箱优先	Gmail、Outlook 等；不建议用国内邮箱，收验证信容易出问题
手机号	海外手机号，不接受 +86	可用接码平台（一次性，适合体验）或 eSIM 虚拟号（长期稳定，推荐）

注册流程：

打开官网 → 点 Sign up → 用邮箱或 Google/Microsoft 账号注册
查收验证邮件，点击确认链接
输入手机号接收短信验证码（这是关键一步，必须是非中国大陆号码）
设置密码，完成注册

💡 小建议：如果只是临时体验，一次性接码号够用；如果打算长期使用甚至升级 Plus，建议一开始就用稳定的虚拟号，避免后面换号引发账号风控。

第三步：下载安装客户端

🪟 Windows

官方桌面版：到官网 https://openai.com/chatgpt/download 下载 Windows 安装包
Microsoft Store：直接搜索 “ChatGPT” 安装（微软商店版更新最省心）

🍎 macOS

官网下载 .dmg 安装包，拖进”应用程序”即可。

📱 iPhone / iPad（iOS）

关键点：需要海外 Apple ID，因为中国大陆区的 App Store 没有 ChatGPT：

注册/切换一个海外区 Apple ID（美区等）
App Store 搜索 “ChatGPT” → 下载
下载完成后可以切回国内 ID，App 不受影响

🤖 Android

有 Google Play 的设备：直接在 Play 商店搜索 “ChatGPT” 安装
没有 Google Play：下载官方 APK 安装包手动安装（注意核对来源，认准官方渠道）

第四步：登录使用

打开客户端 → 用刚才注册的账号登录 → 开始对话。

免费版就能满足日常问答、写作、翻译等需求。需要更强模型、更长上下文、更高频次的话，可以考虑升级：

档位	价格	适合
Free	$0	日常体验
Plus	约 $20/月	日常高频使用
Pro	约 $200/月	重度专业用户

💰 付费提醒：国内发行的信用卡在 OpenAI 支付页面大概率被风控拦截，需要用海外信用卡或虚拟信用卡（Visa/Mastercard 虚拟卡）支付。

常见问题

Q：收不到短信验证码？
检查号码是否真的为海外号（+86 不行），或换一个接码平台重试。

Q：登录时提示 “Unable to load site”？
通常是网络环境不稳定，换个节点或刷新重试。

Q：会不会封号？
用一次性接码号注册、IP 频繁跳变、多账号同 IP 都容易触发风控。稳定使用建议：固定网络环境、正规虚拟号、别干批量注册的事。

Q：扣款失败会怎样？
虚拟卡额度不足或过期会导致续费失败，轻则降级，重则账号异常。订阅后记得保证卡内余额充足。

写在最后

如果只是偶尔想用 AI 写点东西，其实不一定要死磕 ChatGPT 官方这套流程——API 中转方式对国内用户更省心：

不用折腾海外手机号、虚拟信用卡
人民币付款，按量计费
一个 Key 同时调用 GPT、Claude、Gemini 等主流模型

我在用的中转站是 Aklibk API 中转站（ai.aklibk.com），稳定、便宜，注册即用，也可以接 Claude Code、Codex 等编程工具，适合开发者或需要稳定调用的场景。

无论如何，希望这份教程能帮你顺利用上 ChatGPT。折腾快乐！

CC Switch 安装教程：AI 编程工具配置一键切换

2026-08-14T14:00:00.000Z

生命不息，折腾不止。上一篇写了 Sub2API 部署，这篇配套来一个桌面小工具：CC Switch —— 装好它，Claude Code、Codex 的 API 供应商配置就能像换壁纸一样一键切换。

这是什么

CC Switch 是一个开源的跨平台桌面工具（GitHub 上 127k+ stars），专为 AI 编程工具设计：

支持 Claude Code、Codex、OpenCode、OpenClaw、Grok Build、Hermes Agent 等主流工具
把多个 API 供应商配置（官方、各种中转站）存起来，点一下就能切换，不用再手动改配置文件
还带 MCP 服务器管理、配置导入导出、速度测试（测每个中转的延迟）、会话历史浏览等功能

简单说：你手里有 N 个中转站/Key，CC Switch 就是它们的遥控器。

技术栈：Tauri 2（Rust 后端 + React 前端）原生桌面应用，数据存在本地 SQLite（~/.cc-switch/cc-switch.db），轻量不占资源。

下载安装

最新版本 v3.19.2（2026-08-06 发布），下载地址：https://github.com/farion1231/cc-switch/releases

系统要求：Windows 10+ / macOS 12+ / Linux（Ubuntu 22.04+、Debian 11+、Fedora 34+）

🪟 Windows

二选一：

安装版：下载 CC-Switch-v3.19.2-Windows.msi，双击安装
绿色版：下载 CC-Switch-v3.19.2-Windows-Portable.zip，解压即用，免安装

🍎 macOS

方式一：Homebrew（推荐）

1	brew install --cask cc-switch

方式二：手动下载 CC-Switch-v3.19.2-macOS.dmg，拖进应用程序即可。
（macOS 版已通过苹果签名公证，不会提示”无法打开”）

🐧 Linux

# Debian / Ubuntu
wget https://github.com/farion1231/cc-switch/releases/download/v3.19.2/CC-Switch-v3.19.2-Linux-x86_64.deb
sudo dpkg -i CC-Switch-v3.19.2-Linux-x86_64.deb

# Fedora / RHEL
sudo dnf install CC-Switch-v3.19.2-Linux-x86_64.rpm

# 通用 AppImage（任何发行版）
chmod +x CC-Switch-v3.19.2-Linux-x86_64.AppImage
./CC-Switch-v3.19.2-Linux-x86_64.AppImage

# Arch Linux
paru -S cc-switch-bin

基本使用

安装后打开，主界面长这样：

三步上手：

添加供应商：点”添加”，填入名称、API 地址、API Key（就是中转站给你的那串）

设为当前：选中要用的供应商点”切换”，CC Switch 会自动写入 Claude Code / Codex 的配置文件
随时切换：换供应商点一下就行；还能用内置的速度测试比较各中转站的延迟，挑快的用

常见问题

供应商和工具怎么对应？ 每个供应商可以单独设置支持哪些工具（Claude Code / Codex / …），切换时只影响勾选的那些
数据存在哪？ 本地 SQLite：~/.cc-switch/cc-switch.db，支持配置导入导出，换电脑可以直接备份
macOS 打不开？ 到”系统设置 → 隐私与安全性”里允许”仍要打开”（新版已签名公证，一般不会遇到）

其他版本

CLI 版：cc-switch-cli（4.6k stars）——终端党专用，纯命令行切换
Web 版：cc-switch-web（500 stars）——可部署到服务器，浏览器访问

参考

项目主页：https://github.com/farion1231/cc-switch
官方网站：https://ccswitch.io
更新日志：https://github.com/farion1231/cc-switch/blob/main/CHANGELOG.md

Sub2API 部署全记录：把 AI 订阅变成 API 中转

2026-08-14T13:30:00.000Z

生命不息，折腾不止。这篇记录一下 Sub2API 的完整部署过程，包括 Docker Compose 部署、反向代理、HTTPS 证书等实战经验。

这是什么

Sub2API 是一个开源的 AI API 网关中转项目（GitHub 上 37k+ stars），核心功能是：

一个订阅，全家共享：把 Claude、ChatGPT、Gemini、Grok 等官方订阅接入进来，按配额分配给多个用户/工具使用，也就是俗称的”拼车”
原生工具无缝使用：接入后，Claude Code、Codex、Gemini CLI 等原生工具可以直接指向自己的服务地址，体验和官方几乎一致
自带管理后台：账号管理、配额分配、用量统计，还内置了支付系统（易支付 / 支付宝 / 微信 / Stripe），开箱即用

简单说：订阅是”一个包月账号”，Sub2API 把它变成”一个 API 服务”，谁都能用。

技术栈：Go 后端 + Vue 前端管理面板 + PostgreSQL + Redis，Docker 一键部署。

架构一览

整个链路分三块：

部分	说明
订阅源	Claude Pro / ChatGPT Plus / Gemini / Grok 等官方订阅
Sub2API 网关	核心服务（配额分配 + API 中转 + 管理后台），搭配 PostgreSQL（数据）和 Redis（缓存/队列）
使用端	Claude Code、Codex、Gemini CLI、任意 OpenAI 兼容客户端

部署步骤

前置条件

一台 Linux 服务器（本教程用 Docker 方式，不需要会编程）
Docker 20.10+ 和 Docker Compose v2+

方式一：官方一键脚本（最省事）

# 创建部署目录
mkdir -p sub2api-deploy && cd sub2api-deploy

# 下载并运行部署准备脚本（自动生成密钥、下载 compose 模板）
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

# 启动
docker compose up -d

脚本会自动生成 JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD 等安全凭证并写入 .env，记得保存好输出的凭证。

方式二：手动部署（可控性更强）

# 1. 克隆仓库
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api/deploy

# 2. 复制环境变量模板
cp .env.example .env
chmod 600 .env

# 3. 生成安全密钥
openssl rand -hex 32   # 用作 JWT_SECRET
openssl rand -hex 32   # 用作 TOTP_ENCRYPTION_KEY
openssl rand -hex 32   # 用作 POSTGRES_PASSWORD

# 4. 编辑 .env，至少填这几项
# POSTGRES_PASSWORD=上面生成的
# JWT_SECRET=上面生成的
# TOTP_ENCRYPTION_KEY=上面生成的
# ADMIN_EMAIL=admin@example.com
# ADMIN_PASSWORD=你的管理员密码

# 5. 创建数据目录并启动
mkdir -p data postgres_data redis_data
docker compose up -d

# 6. 查看状态和日志
docker compose ps
docker compose logs -f sub2api

两种 Compose 模板怎么选

模板	数据存储	迁移便利性	适用场景
`docker-compose.local.yml`	本地目录	✅ 打包整个目录即可	生产环境、频繁备份
`docker-compose.yml`	Docker 命名卷	⚠️ 需要 docker 命令	简单体验

推荐用 docker-compose.local.yml（数据在本地目录，备份迁移都方便）。

初始管理员

如果是手动部署，首次启动后管理员账号密码会在日志里输出：

1	docker compose logs sub2api \| grep "admin password"

用日志里的账号登录管理后台，首次登录会强制要求修改密码。之后就可以在后台添加订阅、创建用户、分配配额了。

反向代理 + HTTPS（实战经验）

服务默认监听 8080 端口。安全第一：不要让 8080 直接暴露公网，建议：

只绑定本机回环地址（.env 里 BIND_HOST=127.0.0.1），对外只开放 80/443
用 Nginx / OpenResty 做反向代理
套一层 HTTPS 证书

我的部署是：Cloudflare 灰云解析 → OpenResty 反向代理 → 127.0.0.1:8080，证书用 Let’s Encrypt（acme.sh 自动续期，到期前自动换新），HTTP 访问自动 301 跳转 HTTPS。

关键配置参考：

server {
    listen 80;
    server_name sub-api.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name sub-api.example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

小坑提醒：如果 Nginx/OpenResty 跑在 Docker 容器里，证书路径必须是挂载进容器的目录，容器内看不到宿主机其他路径的证书文件。

升级与维护

# 拉取最新镜像
docker compose pull

# 重新创建容器
docker compose up -d

# 重启
docker compose restart

也可以直接在**管理后台左上角点”检测更新”**在线升级（支持一键更新和回滚）。

日常维护就三件事：备份数据目录、定期升级、看日志。

注意事项

⚠️ 上游条款风险：该项目官方声明，使用它可能违反 Anthropic 等上游服务商的用户协议，账号风险自行承担，请确认合规后再使用
📖 项目仅供技术学习与研究，作者不对账号封禁、服务中断、数据丢失等损失负责
🚫 未经授权，请勿用本项目从事商业运营

参考

项目主页：https://github.com/Wei-Shaw/sub2api
部署文档：仓库 deploy/ 目录（含 Caddyfile、Docker 说明、数据管理进程说明等）