dsh-nous-portal-free-provider
Nous Portal 免费 Tier 接入 dsh
English
Hermes Agent（Nous Portal）上 OAuth 登录可以免费使用一些模型，包含 Hy3、Ox Alpha 等。本插件把它接到 dsh 上。
安装
从 npm 安装（预构建产物，推荐）：
dsh plugin --profile web add @jiesou/dsh-nous-portal-free-provider
或从 GitHub 安装：
dsh plugin --profile web add github:jiesou/dsh-nous-portal-free-provider
安装之后
登录：运行本插件自带的 CLI
# 根据实际 plugin 目录找到 lib/cli.js
node ~/.dsh/profiles/web/node_modules/@jiesou/dsh-nous-portal-free-provider/lib/cli.js
然后按照终端提示，使用 device code 登录即可
运行中的 dsh 热加载，无需重启
CLI 选项
--portal-url <url> Portal 地址（默认 https://portal.nousresearch.com）
--client-id <id> OAuth client id（默认 hermes-cli）
--scope <scope> 申请的 scope（默认 inference:invoke）
--dsh-home <dir> 凭据文档所在 home（默认 $DSH_HOME 或 ~/.dsh）
--path <file> 凭据文档完整路径，优先于 --dsh-home
注：插件同时注册了 dsh 授权流（ctx.authorization），但 0.1.1-rc.x 的
dsh 还没有能启动它的界面（seam 已有、surface 未发布）；上面这个独立
CLI 是当前的推荐登录路径。
认证来源（按优先级）
| 优先级 | 来源 | 说明 |
|---|
| 1 | 凭据 NOUS_PORTAL_API_KEY | 普通 sk- key，付费账户 |
| 2 | 凭据记录 <本插件>/portal | 授权流写入的 OAuth grant |
存储完全走 ctx.credentials 统一接口：refresh token 是 grant record，
token 轮换通过 modifyRecord 写回（跨进程锁）；access token 只存内存。
本插件的 settings 配置项：retryPolicy（模型请求重试策略），默认 always（每次失败都重试）；maxRequestImageBytes（单次请求内联的 base64 图片上限），默认 2097152（2 MiB）；requestImageMaxBytes（单张图片重编码后的上限），默认 1048576（1 MiB）。其余端点、目录均来自上游 /v1/models 动态发现，硬编码为免费层的合理默认值；唯一的登录入口是上面的 CLI。
图片按 DSH 的路由标准处理：这张 wire 是无状态的，留在上下文里的图片每轮都会重传一次；超过 maxRequestImageBytes 时不发请求，而是抛出 IMAGE_OFFLOAD_REQUIRED，由 DSH 把最旧的图片记入 image/offload 并重试，之后用占位文本代替（占位文本里仍带图片身份和可读路径）。两个值都是 base64 口径（约等于原图字节 ×4/3），所以 maxRequestImageBytes 必须大于单张的 base64 长度，否则一张图也放不下。
Reasoning effort（推理深度）
模型只暴露上游接受的档位，不造档位。Default 表示"不发送 reasoning_effort"字段，由上游自行决定深度。Off 是真开关——发送上游的关闭字面值（none、off 等）。上游标记为 mandatory 的模型干脆不显示 Off 选项，插件不替它伪造一个。default_effort 等元数据由上游决定，插件不替你固定某一档。
模型目录：动态发现
启动时从公开的 /v1/models 列表（无需认证）抓取一次，不轮循。
过滤出 prompt/completion 价格均为 $0 的模型作为目录，元数据
（context window、多模态输入、reasoning efforts）一并跟随上游。
免费集随上游轮换自动增减，不写死任何模型 id。挂载时上游不可达也不挂——目录暂时为空、不会拖垮插件。
错误提示
上游拒绝（"OpenRouter free models are not supported"、免费推广结束等）在终端错误事件里保留真实原因，不会被 harness 当 AUTH 吞掉。真正的鉴权失败仍按 AUTH 走，无法解析的内容原样透传。
注意事项
- refresh token 会轮换且单次使用：Portal 每次 refresh 都发新 refresh token、
旧 token 立即作废；重复提交已用过的旧 token 会被服务端视为令牌被盗、吊销整条
会话（原话
Refresh token reuse detected; please re-authenticate）。因此刷新的
「读 RT → POST → 写回新 RT」整段都在凭据服务的 modifyRecord 锁内执行，避免多进程
同时提交同一 RT。
总之：若仍看到 re-authenticate 提示，按上面 CLI 重新登录即可。
- device-code 审批页 bug：Portal 端审批 UI 曾对部分用户不渲染
（NousResearch/hermes-agent#47950）。如果授权卡住，先确认浏览器已登录
Portal 再重试。
- 协议变更（2026-08）：Portal 已下线
/api/oauth/agent-key 铸造端点，
新版 hermes-cli 直接把 refresh 换来的 access token（invoke JWT）当推理密钥，
登录 scope 改为 inference:invoke。本插件已跟进。
License
MIT
