Freebuff 免费模型接入 MYCF711/freebuff-auth

magpie 与 DeepSeek Harness 的 Freebuff 服务商

在 magpie 和 DeepSeek Harness 里用 Freebuff 的免费模型——走账号自己的浏览器登录，配一个多账号池，每日额度用完就轮换，支持流式工具调用。

Freebuff 是 Codebuff 的免费档。用起来不花钱，但额度小、还限时：5 freebucks 买一小时会话，一个账号一天 25 freebucks。

非官方。与 Codebuff、Freebuff 均无关联。

状态：beta（0.3.0-beta.1）。 工具调用路径已实现，覆盖 38 条断言，线格式也对照过 Freebuff 自己的客户端——但尚未在真实 Freebuff 账号上端到端跑过（开发期间能用的那个账号被封了）。请用 @beta 安装；stable 标签要等这项测试跑完才放。

三个包

一个仓库，一个协议核心，两层薄壳：

freebuff-core ──┬──> magpie-freebuff-provider
└──> dsh-freebuff-provider

| 包 | 是什么 | 装到哪 |
| freebuff-core | 协议核心：设备签名、目录、会话准入、SSE 工具调用解析、消息归一化。不直接安装——两层壳都依赖它。 | — |
| magpie-freebuff-provider | magpie / OpenCode 插件：导出 config / auth / provider 钩子。 | magpie、OpenCode |
| dsh-freebuff-provider | DSH 包 + 本地网关：在 127.0.0.1:8937 上提供 OpenAI 兼容端点。 | DeepSeek Harness |

为什么是两层壳而不是一个包： magpie 要的是带钩子的插件对象；DSH 要的是它能用 OpenAI 协议对话的 HTTP 端点。底下的协议——设备签名、会话准入、账号轮换、工具调用解析——完全一样，所以只在 freebuff-core 里放一份。

安装

已发布到 npm，标签 @beta：

| 包 | |
| freebuff-core | 协议核心，内联进两个包——不单独安装 |
| magpie-freebuff-provider | magpie / OpenCode |
| dsh-freebuff-provider | DeepSeek Harness |

magpie

magpie plugin add magpie-freebuff-provider@beta
magpie plugin login freebuff

或者从打包好的 tarball 装：

npm pack --workspace magpie-freebuff-provider --pack-destination dist
magpie plugin add ./dist/magpie-freebuff-provider-0.3.0-beta.1.tgz

DeepSeek Harness

dsh plugin --profile desktop add dsh-freebuff-provider@beta

包里带一个网关二进制。启动它：

npx freebuff-gateway
or
node node_modules/dsh-freebuff-provider/gateway.mjs

然后把 DSH 服务商指向它。在 ~/.dsh/profiles/<name>/cordis.patch.yml 里加上：

- id: llm-pi-ai
name: "@deepseek-ai/dsh-llm-pi-ai"
config:yaml
providers:
freebuff:
displayName: Freebuff
apiKeyEnv: FREEBUFF_LOCAL_KEY
api: openai-completions
baseURL: http://127.0.0.1:8937/v1
models:
- id: freebuff/solar-pro4
name: Solar Pro 4 · 0fb contextWindow: 1048576 maxTokens: 32768
input: [text, image]
sh
set FREEBUFF_LOCAL_KEY=local-freebuff

不想手写这段配置的话，dsh-freebuff-provider 里的 patchEntry() 可以用代码生成： js
import { patchEntry } from 'dsh-freebuff-provider'
console.log(JSON.stringify(patchEntry(8937), null, 2))

登录

两种方式，magpie 和网关里都能用：

浏览器登录。 打开 Freebuff 自己的登录页，登录后账号自动接入。重复操作可以添加更多账号，账号池会全部收下。

Token。 粘贴已有的 Freebuff authToken（36 位 UUID）。登录时不发送任何内容，所以无头环境也能用。获取方式：~/.config/manicode/credentials.json → default.authToken，官方命令行登录一次后就会写入。

模型

调用时从账号的模型目录实时抓取，所以始终跟随 Freebuff 实际提供的模型。锁定的行（付费套餐）会被过滤掉。

四个 0fb 模型不花 freebucks，但仍占用当天的一个会话窗口。5fb–20fb 的模型会消耗 freebucks。

工具调用以流式透传：tools、tool_choice 和 parallel_tool_calls 发给 Freebuff；tool_calls 以标准 OpenAI 增量返回。

配额

1. 5 freebucks = 一小时。 固定，不可暂停，不可退款。
2. 每天 25 freebucks，太平洋时间午夜重置（约北京时间 15:00）。每个账号每天最多 5 个会话。
3. 每个账号同一时间只能有一个高级会话。 开第二个会顶掉第一个。

插件不会开启付不起的会话：价格高于剩余余额的模型会被拦下，并给出可读的原因。余额为零时 0fb 模型仍可开启。

同时运行两个宿主

不要让两个宿主共用一个 Freebuff 账号。 Freebuff 每个账号只允许一个会话，magpie 和 DSH 网关用同一账号会互相顶掉会话——你会看到一连串 409。

二选一：

- 只用一个宿主。 关掉另一个（magpie plugin off freebuff，或停掉网关）。
- 用两个账号。 每个宿主登录不同的 Freebuff 账号。

还有一项更隐蔽的代价：每个 shell 都会生成自己的 Ed25519 设备密钥，所以一个账号从两边访问看起来像两台机器。这是会导致账号被标记的模式之一。

让账号保持存活

- 每个账号只用一个客户端——不要插件、桌面应用和命令行同时上。
- 不要重建设备密钥。 它只创建一次并复用；替换它等于注册新设备。
- 拉开模型切换的间隔。 一分钟内切换好几次，正是容易引起注意的模式。
- 403 account_suspended 表示账号已被封禁。 停手，别再试探。请通过 Freebuff 账号页面申诉。

故障排查

| 你看到的现象 | 含义 |
| 403 free_mode_cli_required | 请求看起来不像官方命令行发出的，通常是请求头集合跑偏了。 |
| 403 account_suspended | 账号被封，不是限流。停手并申诉。 |
| 402 Out of credits | 每日 freebucks 已用完，太平洋时间午夜重置。 |
| 409 session_model_mismatch | 会话是为另一个模型打开的，插件会重新打开。 |
| 429 rate_limited | 单模型每日调用次数超限，retryAfterMs 给出等待时长。 |
| 没有列出模型 | 还没登录，或者目录请求失败。 |
| magpie 显示 0 个模型 | config 没跑过，或者静态表被覆盖了。 |

开发 sh
npm install # links the three workspaces
npm test # 26 assertions across all three packages
npm run pack:all # tarballs into dist/

scripts/test-installed.mjs 还会把 tarball 装进一个临时目录再检查一遍，这样打包错误在发布前就能暴露出来。

协议说明

请求用 Ed25519 设备密钥签名，签名覆盖六行载荷：版本、方法、路径、时间戳、body SHA-256、fetch id。user 消息的 content 是 {type:"text",text} 片段组成的数组，不是裸字符串；role:"tool" 携带带下划线的 tool_call_id —— 这两点都和 Freebuff 自家客户端发的一致。会话在 /attempt 端点释放，官方客户端用的就是这个；另一个端点会让整条会话链失效。

许可证

MIT。见 LICENSE。