功能

能力	使用体验
自带模型路由	安装后模型选择器出现 PackyCode 分组，不需要配置 provider，也不用改 cordis.patch.yml
多 Key 按顺序使用	额度用尽或 Key 被拒绝时自动切到下一个可用 Key；失败的那一步由重试接手
按分组选 Key	每个 Key 后面列出它所在的 PackyCode 分组和能用的模型；当前 Key 的分组用不了所选模型（例如没有 cc 分组却选了 Claude）时，这一轮自动改用分组合适的 Key
余额一眼可见	设置页列出每个 Key 的剩余、已用、额度、重置周期和用量条，并给出这些 Key 的合计；输入框右侧显示当前 Key 的剩余额度
Claude 走本机 CLI	claude-opus-5-5、claude-sonnet-5-5、claude-haiku-5-5 由本机官方 Claude Code CLI 执行；设置页可以检测并一键安装
网页搜索可走 PackyCode	可选：DSH 的 web_search 改用 PackyCode 搜索，后端在 DeepSeek 与 GPT 之间切换；可只对 PackyCode 模型生效
凭据不离开本机	Key 只存在 DSH 凭据文件里。浏览器只能看到备注、状态和余额，拿不到 Key

安装

先准备好 DeepSeek Harness 和 PackyCode（PackyAPI）的 API Key。尚未安装 DSH，可查看 DSH 官方说明。

1. 安装插件

打开桌面应用的插件页，点击添加插件，在包名或地址中填入：

dsh-packycode-api

在安装源中选择官方源，然后点击安装。需要固定版本时填入 dsh-packycode-api@1.1.1。

完成后手动重启桌面应用。仅刷新页面不会重新加载 Host 里的插件。

2. 添加 Key

打开 设置 → PackyCode，在「添加 Key」里粘贴 API Key。备注可选，用来区分多个 Key。点「添加」。

不要把 Key 粘贴到公开 Issue、聊天记录或截图里。插件不会读取环境变量 PACKY_CODE_API_KEY，也不会在失败时偷偷改用别的 provider。

3. 选择模型

回到对话，在模型选择器里选 PackyCode 分组下的模型。deepseek-flash、gpt-6.1-sol 和 gpt-6-astra 添加 Key 后即可用。三个 Claude 模型还需要本机装有 Claude Code CLI，见下文。

检查安装 / 其它 profile / 本地目录

桌面应用的插件页可以看到已安装状态与版本，也可以在那里启用、停用或卸载。

仅用于非 desktop profile： dsh plugin --profile <name> add dsh-packycode-api@1.1.1。不要对 desktop 使用它 —— CLI 会直接拒绝（profile "desktop" is managed exclusively by the Electron application）。

本地开发可以用绝对路径：dsh plugin --profile <name> add link:/path/to/dsh-packycode-api。

没有浏览器的 profile 也能走模型路由，只是看不到设置页和输入框额度。

日常使用

换 Key。 Key 按添加顺序使用。点「切到此 Key」指定优先使用的 Key，下一轮就生效；「重命名」改备注（最多 60 字，不能为空）；充值或更换后点「重新启用」。

看分组。 「账户与 Key」里每个 Key 下面列出它所在的 PackyCode 分组（鼠标悬停可看分组说明），以及能用哪些模型：✓ 可用、◐ 部分可用、✕ 不可用。分组由网关自己报出（对一个不存在的模型 id 的拒绝里会写明「已选分组」，不产生费用），再对照 PackyCode 公开的模型分组表。Claude 需要 cc / cc-sale / cc-expensive / claude-officially 之一（claude-haiku-5-5 只在 cc 和 claude-officially）；GPT 需要 codex / codex-sale；DeepSeek 需要 deepseek-officially / deepseek-sale。

看余额。 「账户与 Key」顶部的合计是已列出的这些 Key 的剩余、已用与额度，不是 PackyCode 账号下全部令牌的账单。读失败的 Key 不计入合计，并会注明个数；某个 Key 这次读失败但之前读到过，会继续显示上次的余额并注明读取时间（输入框里显示为 ≈US$…），重启 DSH 后才清空。输入框右侧只在选中 PackyCode 模型时显示当前 Key 的剩余额度。「刷新」会跳过约 60 秒的缓存。默认模型接口是 https://cf.api.fan，余额接口是 https://www.packyapi.ai，可在「高级：接口地址」里改。旧默认值 https://www.packyapi.com 在国内网络下 DNS 被污染、直连会 fetch failed，即使设置里保存的是它，插件也会先试 .ai。

用 Claude。 设置页的「Claude Code CLI」卡片会检测本机 CLI。每一轮 Claude 对话的思考区都会写明这一轮用的是哪个 Key（只显示备注名）。没装时点「安装 Claude Code CLI」，本机执行 npm install -g @anthropic-ai/claude-code（需要 Node.js 18+）。装好后不用重启 DSH。Windows 上另外需要 Git for Windows。

网页搜索。 DSH 的 web_search 默认调用 DeepSeek 官方接口（用 DEEPSEEK_API_KEY 计费）。在 设置 → PackyCode → 网页搜索 里可以改走 PackyCode：

搜索路由	效果
不接管（默认）	不改 DSH 的搜索设置
自动（按模型路由）	PackyCode 模型用 PackyCode 搜索，其他模型照旧
始终使用 PackyCode 搜索	原本走 DSH 默认搜索的请求都改走 PackyCode

搜索后端	模型与协议	说明
DeepSeek（默认）	deepseek-flash，/v1/messages + web_search_20250305	每次约几千 token；需要 DeepSeek 分组
GPT	gpt-6.1-sol，/v1/responses + web_search	结果通常更新、更准，每次约 2–3 万输入 token；需要网关把这个 Key 的 GPT 请求路由到它的分组

PackyCode 没有专用搜索接口：一次搜索就是一次带服务端搜索工具的模型调用，用这里的 Key 计费，额度用尽或 Key 被拒绝时同样切到下一个 Key。

Claude CLI 的搜索。 Claude 模型和 claude_code 委派工具都通过临时 MCP 搜索工具使用上表选定的 DeepSeek/GPT 后端，原生 WebSearch 被禁用。原因是原生搜索会额外发一个 Claude 服务端搜索子请求，PackyCode 的 Claude 上游可能把它拒为「不是官方 CLI」，即使普通对话能正常工作。新的调用链是：

Claude Code CLI → 本机临时 MCP web_search → 插件选定的 DeepSeek/GPT 后端

• 后端选择对 CLI 生效；路由选择只影响 DSH。 即使选了「不接管」，CLI 搜索仍用这里选的后端，不转到 DSH 默认搜索。更改后端后下一次搜索即使用新选择。
• Claude 普通对话仍需要 Claude 分组；搜索需要存入插件的 Key 覆盖 DeepSeek 或 GPT 分组，可以是另一个 Key。搜索错误会返回给 CLI，不伪造成功、不自动切另一个后端。
• 只读、编辑模式单独自动允许这个只读 MCP 搜索工具，不增加 Shell 或文件写权限；用户/管理员的拒绝规则仍有效。CLI 的 --allowedTools 是自动批准列表，不是可用工具的排他列表，已有其他工具权限保持原样。
• 每轮最多 8 次搜索，最多同时 2 次；查询不超过 2000 字符，每次最多 8 个来源，整体搜索预算 60 秒。标题生成不启动 MCP 或进行搜索。
• 思考区会显示 ▸ 网页搜索：PackyCode DeepSeek（MCP，原生 WebSearch 已禁用）（或 GPT）。临时服务只监听 127.0.0.1，配置中仅含本机一次性凭证，不含搜索 API Key；CLI 结束、取消、超时或插件卸载时关闭并清理，不修改用户现有 MCP 配置。

网页搜索是怎么接进 DSH 的

• 插件向 DSH 的 web 服务注册两个搜索后端：packycode-api（始终走 PackyCode）和 packycode-api-auto（按发起会话的模型路由）。只注册不会改变任何行为。
• 选「自动」或「始终」时，插件在当前 profile 的 cordis.patch.yml 末尾写入一段带 # >>> dsh-packycode-api: web search provider 标记的 - id: web 配置，把 web 行的基础 searchProvider 指向上面的后端；DSH 会热加载这个文件，不用重启。切回「不接管」会删掉这段，其它内容原样保留。
• 不直接改 web 运行时的搜索槽位：Codex、Kimi 等订阅插件每次 web 重启都会重写那个槽位，两边都写会互相触发重启。它们对自己不负责的模型会回退到 web 行的基础配置，所以写基础配置能和它们共存：Codex 模型仍走 Codex 搜索，其余请求才轮到这里的选择。
• 这段配置用注释记下写入前的基础搜索（# fallback: …）。「自动」模式下非 PackyCode 模型的请求交给它；如果它又把请求转回本插件，就直接交给 DSH 内置的 deepseek-official，不会循环。
• 结果只取结构化数据：DeepSeek 用 web_search_tool_result 块，GPT 用 url_citation 标注和 web_search_call 记录；模型写的摘要作为 content 一并返回。
• 当前 Key 的分组覆盖不到所选后端的模型（网关报 当前令牌未覆盖供应商）时，会试下一个 Key，不停用 Key；都不行就提示切换后端。
• 设置页会显示当前生效的基础搜索和运行时搜索。如果另一个插件的补丁排在后面并覆盖了基础搜索，这里会提示。

什么时候会自动切换 Key

• 会切换并停用当前 Key： 额度用尽（网关报额度、余额、insufficient quota 之类），或 Key 被拒绝（HTTP 401 / 无效的令牌）。失败的那一步由 harness 重试，从而用上新 Key。
• 按分组改用，不停用： 分组读数显示当前 Key 用不了这一轮的模型、而另一个 Key 能用时，这一轮直接用那个 Key（Claude 轮次会在思考区写明「当前 Key「A」的分组不能用 …，本轮改用 Key「B」」）。「使用中」的 Key 不变，其它模型照常用它。只在有证据时才改用：分组还没读到的 Key 照旧使用。
• 不会切换： 限速（429）；网关把上游渠道故障误报成 400（当前令牌未覆盖供应商 …）；以及「只允许官方客户端」的 403。后一种会直接说明原因，而不是显示成 API Key 无效。
• 全部 Key 都停用时，请求失败并说明没有可用 Key，不会回退到别的凭据。

模型与分组

模型	怎么调用	推理档位	适合的令牌分组
deepseek-flash	HTTP，chat/completions	可关；low / high / max	deepseek-officially、deepseek-sale
gpt-6.1-sol	HTTP，Responses，可带图	不能关；low / medium / high / xhigh / max	codex、codex-sale
gpt-6-astra	同上	同上	同上
claude-opus-5-5	本机 Claude Code CLI	选择器档位同上，实际档位由 CLI 决定	能给官方 CLI 用的分组，比如cc分组
claude-sonnet-5-5	同上	同上	同上
claude-haiku-5-5	同上；会话标题也固定走它	同上	同上

列表里看得到模型，不代表当前令牌分组一定放行。换分组时不要把对应分组一起去掉。

协议、分组和 CLI 的具体约束

• OpenAI / Codex 必须走 Responses。gpt-6.1-sol 和 gpt-6-astra 已固定为 openai-responses，base URL 是 https://cf.api.fan/v1，不要把 /responses 写进根地址。
• Codex 分组的 Responses 请求必须带 prompt_cache_key，否则 403。harness 会带会话 id；没有会话 id 时插件补一个兜底值。
• Anthropic 的 base URL 不带 /v1（客户端自己拼 /v1/messages）。三个 Claude 模型虽然目录里声明了 Messages 协议，实际请求由本机 CLI 发出。
• cc（Claude Code 专用）只接受官方 Claude CLI。用普通 API 客户端调 Claude 会 403：This API endpoint is only accessible via the official Claude CLI。本插件因此调用本机 claude，而不是改去 cc-sale，也不是伪造客户端身份。令牌如果没有开放给官方 CLI 的分组，这三个模型仍然不可用。
• 选了 Claude 模型但本机没有 CLI 时，这一回合会直接说明未安装，并指向设置页的安装按钮。
• CLI 使用插件配置的地址和当前 Key（ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN），以及独立配置目录 ~/.dsh/packycode-claude-cli。不隔离的话，~/.claude/settings.json 里的 env 会盖掉插件 Key。
• CLI 权限默认跟随当前会话：read-only → 只读，workspace-write → 可编辑，danger-full-access 且不再审批 → full。CLI 不能向 DSH 弹审批，所以只要会话还要审批，就不会给它 full。也可把设置项 claudeCliMode 固定成 read-only / edit / full。claudeCliPath 留空则自动查找；claudeCliCwd 留空则用当前会话工作区。
• 思考过程和工具调用（▸ Bash、▸ Read，失败时带 ✗）会出现在这一回合的思考区。它们是进度，不是 DSH 的工具调用。CLI 自己的工具不受 DSH 沙箱约束。
• 思考区第一行是「▸ 启动 Claude Code CLI…」，CLI 起来后显示版本和模型。网关限流或繁忙（429、503 账号并发排队已满 等）时，CLI 会自己重试最多 10 次，每次重试都会显示成 ↻ 网关返回 HTTP 503，CLI 自动重试 n/10，不再像卡住。重试用完仍失败时，会说明是 PackyCode 的 Claude 上游繁忙，不是 Key 的问题。CLI 启动后 2 分钟内没有任何输出会被停止并报告原因。
• 对话记录和图片通过 stdin 交给 CLI（--input-format stream-json），不走命令行参数：Windows 命令行长度有上限，而且命令行带不了图片。对话里的图片会以图片形式发给 Claude（与 HTTP 路由相同的压缩规格：每张不超过 2048×2048、约 1 MiB；一回合最多 20 张、合计 20 MiB，超出时先舍弃最早的）。没随消息发出的图片会写明本机只读副本的路径，CLI 需要时可以用 Read 读取。
• 每次运行都带 --append-system-prompt（委派说明）。在 -p 模式下，官方 CLI 有追加说明时会以 "You are Claude Code, Anthropic's official CLI for Claude …" 自我介绍，没有时是 "You are a Claude agent, built on Anthropic's Claude Agent SDK."；后者曾被上游当成非官方 CLI 拒绝（403 only accepts requests from the official Claude Code CLI）。这是官方 CLI 自己的行为，插件没有改写它的系统提示词。
• 会话跑在 Claude 模型上时，生成标题改用 claude-haiku-5-5，只读、临时目录，避免为起标题跑一整轮 Opus。
• 会话跑在 gpt-6-astra 上时，标题改由 gpt-6.1-sol 生成（同一个 Codex 分组）；对话本身仍然用 Astra。其它模型的标题由会话模型自己生成。
• 另有 claude_code 工具：当前模型是 gpt-6.1-sol、gpt-6-astra 或 deepseek-flash 时，可以把一个任务委派给本机 Claude Code。请求的 mode 不会超过会话权限允许的上限。
• 声明了模型不支持的推理档位会被 harness 在发请求前拒绝，不要随手改档位映射。

更新与卸载

更新： 打开 设置 → PackyCode，有新版本时点「更新插件」。它会在当前 profile 目录里用 DSH 自带的 pnpm 安装精确版本，并读回 package.json 确认版本落地。本地 link: 开发安装不会出现这个按钮。完成后完全退出并重新打开桌面应用。只刷新页面不会重载 Host。也可以在插件页重新安装 dsh-packycode-api。

卸载： 用过 PackyCode 网页搜索的话，先在 设置 → PackyCode → 网页搜索 切回「不接管」，再到插件页卸载本插件，然后重启桌面应用。否则 cordis.patch.yml 里会留下指向已卸载后端的 web 配置，web_search 会报 configured web provider "packycode-api-auto" is not registered；这时手动删掉带 dsh-packycode-api: web search provider 标记的那一段即可。卸载不会删除其它插件、整个 profile，也不会撤销 PackyCode 控制台里的令牌。

常见问题

某个模型不可用，但 Key 是有效的？ 看「账户与 Key」里这个 Key 的分组和 ✓ / ✕：分组不覆盖这个模型时，换一个分组合适的 Key，或在 PackyCode 控制台给 Key 加上对应分组。存了分组合适的 Key 时，插件会自动用它跑这个模型。分组拒绝不会停用 Key。

Claude 报「PackyCode 的上游拒绝了这次 Claude Code CLI 请求」或「只接受官方 Claude Code CLI」？ 最常见的原因是这一轮用的 Key 没有 Claude 分组：PackyCode 对这种 Key 也会回这句话（或 400 当前令牌未覆盖供应商）。现在报错会直接写明「本轮使用的 Key「…」所在分组（…）不包含能用 claude-… 的分组」，并说明不需要更新 CLI。只有 Key 确实有 Claude 分组时仍被拒，才需要按报错里的提示检查 CLI 版本或联系 PackyCode。

余额对不上账号账单？ 设置页合计的是这里列出的 Key，不含同账号下没添加到本插件的其它令牌。个别 Key 读失败时会单独注明，不会被算成 0。

余额显示 读取失败: https://www.packyapi.com: fetch failed？ 这是 1.0.4 及更早版本的默认余额接口在国内网络下被 DNS 污染，开了代理才能连上，所以有时正常、有时失败。新版本默认改用 https://www.packyapi.ai。模型列表是插件内置的，不需要向 PackyCode 查询，不受影响。

选了 Claude 模型一直显示「深度求索中」？ 看思考区：有 ↻ 网关返回 HTTP 503/429 说明 PackyCode 的 Claude 上游在排队或限流，CLI 正在自动重试；只有「▸ 启动 Claude Code CLI…」没有「已启动」，说明本机 CLI 没起来（Windows 上先确认装了 Git for Windows，并在终端执行 claude --version）。

限速之后 Key 被停用了？ 不该发生。429 不会切换 Key。额度用尽或 401 才会停用；充值后点「重新启用」。

插件页安装报 ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION？ pnpm 默认拒绝发布不满 24 小时的包，并且会检查 profile 里的整个 lockfile。报错里点名的往往是另一个刚更新过的插件，不是本插件。等它发布满 24 小时再重试，或把报错里的 包名@版本 加到 profile 目录 pnpm-workspace.yaml 的 minimumReleaseAgeExclude 下。已安装本插件后，设置页的「更新插件」不受这个限制。

网页搜索报「no stored API key's group covers …」？ 所选搜索后端的模型不在你的令牌分组里（或网关暂时把它路由到了别的供应商）。在 设置 → PackyCode → 网页搜索 换一个后端，或添加分组覆盖它的 Key。

装了 CLI 还是不能用 Claude？ 从 Finder 或开始菜单启动时，PATH 往往比终端短。插件会再查官方安装位置、常见包管理器目录和 npm prefix -g。仍找不到就在设置里填 claudeCliPath，或点「重新检测」。改的是 Host 或重新安装了插件时，要完全退出并重启桌面应用。

安全边界

本项目是社区插件，与 DeepSeek、PackyCode 无隶属或背书关系。模型请求会发到你配置的 PackyCode 接口；凭据不返回浏览器，不代表推理在本地完成。Claude 模型还会在本机启动官方 CLI。

Key 存在本机 DSH 凭据文件（~/.dsh/.credentials.yaml，权限由 DSH 设为仅所有者可读），不进设置文档、日志或对话记录。余额请求只在宿主侧发出，带超时并禁止重定向。

普通问题请提交 Issue。不要附带 Key、令牌或凭据文件内容。更多说明见 SECURITY.md。

本地开发

git clone https://github.com/BaronCyrus/dsh-packycode-api.git
cd dsh-packycode-api
pnpm install --frozen-lockfile
pnpm run check

pnpm run check 会跑全部测试、重新构建，并在 .artifacts/ 打出 tarball。lib/ 是已提交的构建产物，改 src/ 后用 pnpm run build 生成，不要手改。

真机网关用 node scripts/live-check.mjs 验证：它通过插件注册的同一条路由，读余额和分组、让每个 HTTP 模型回答一次、演练 Key 轮换和失败分类，只打印 Key 的末 4 位。加 --with-cli 会用本机 Claude Code CLI 跑三个 Claude 模型，加 --with-search 会每个搜索后端各搜一次；默认运行只消耗少量额度。

Claude CLI 的 MCP 接口验证用 node scripts/cli-search-check.mjs：运行真实 CLI，普通 Claude 响应和搜索数据默认由本地测试服务模拟，不消费额度；会检查三种权限模式、原生搜索禁用和临时资源清理。加 --live --backend deepseek 或 --live --backend gpt 会让只读模式的那一次搜索走真实后端（其它两种模式仍模拟）。这不等于验证了真实 Claude 上游对话或运行中的 DSH 集成。

使用 Agent 修改或发布时，先读 AGENTS.md。发布由推送 v* 标签触发 Publish workflow，不要在本机执行 npm publish。

License

MIT