DeepSeek Harness (DSH) 双半侧统一网关与鉴权桥梁插件 融合 人类端多用户安全登录 + 机器端轻量 HTTP POST / RESTful API 调度网关。
⚠️ 文档时效说明（20260923 核对）：本文部分章节写于 DSH 0.1.2 时代， 其中「需修改 DSH 源码加requireSession扩展点」的路径已不适用于 0.1.5+—— 官方已在client/connection内原生提供browserAuth.isAuthenticated()门禁， 无需再打源码补丁。改动细节见下方「🔐 公网账号系统」章节的现状标注。 阅读时以带 ✅/⚠️ 标注的现状说明为准。
⚠️ npm 上的版本已滞后：registry 上最新为0.1.0，而本仓库当前已是0.6.6。 请勿以 npm 版本为准——0.1.0缺少sessionAuth服务接线，且缺少其后的全部安全加固 （会话指纹绑定、step-up 提权、伪回环绕过修复、机器通道 fail-closed 等）。 以本仓库为准（当前0.6.7）。✅ 推荐安装方式：从本仓库源码安装
dsh plugin --profile web add git+https://github.com/ptrel1/dsh-postapi-bridge.git🔗 npm 页面（版本较旧，仅供参考）：https://www.npmjs.com/package/dsh-postapi-bridge
- 机器通道 fail-closed：/api/dsh/v1/* 非本地(严格双回环之外)请求一律要求 Bearer/X-Gateway-Token； apiToken 为空也拒绝——杜绝「token 未配 → 全网可 RCE」的 fail-open。
- 严格回环判定 isStrictLoopback：socket+Host 双回环，绝不经 X-Forwarded-For —— 伪造 XFF:127.0.0.1 与 frp 直连(socket=127,Host=公网)均无法蒙混免 token； verifyFingerprint / handleApiBridge / handleAdminUsers 三处统一。
- /health 白名单免 token：健康探测不要求凭据，其它机器通道方法一律 401。
- package.json 与 AUDIT_VERSION 对齐 0.6.4。
- 会话指纹放宽：UA 只绑定设备类别(desktop/mobile/tablet/other)而非逐字节哈希，桌面/手机切换不再误杀；旧会话回退 UA 哈希硬匹配。ipPrefixBits 默认 24→16。
- 未登录自动跳登录页：浏览器半侧包装全局 fetch 捕获 /api 401/403，仅无会话 cookie 且在登录页外时跳 /login；stepup 场景不狂跳。
- package.json 与 AUDIT_VERSION 对齐 0.6.3。
本项目的缘起，与 maibot_dsh_bridge 一脉相承，同样承接自早期架构探索原型 —— mai_study_code（麦麦学代码）。
- 前身定位：为麦麦设计"目录式 + Web 可视化 + 自进化"的代码学习/编辑工作台，后演变为独立 Web 应用（AgentLoop + WebServer + Sandbox + SSE 事件总线），其架构与 DSH 相似度约 70%~75%。
- 中断原因：自造整套轮子（Agent 循环、Web 编辑器、沙盒、权限、持久化、事件流）维护负担过高，遂暂停。
- 迁移验证：经研究确认 DSH 的架构正是最初构想的那套，转而采用 DSH 作为承载底座。
- 本项目角色：
dsh-postapi-bridge是承接该构想、为外部系统/机器人开放 DSH HTTP POST / RESTful API 调度网关 的落地插件（客户端一侧配套maibot_dsh_bridge负责麦麦接入）。
🔗 前身仓库（已归档）：https://github.com/ptrel1/mai_study_code.git
📖 该仓库 README 内含完整的架构对比、探索历史与归档说明。
当外部系统通过本网关驱动 DSH 执行长任务时，DSH 通过 compaction（压缩）体系 控制上下文增长，其二级漏斗设计对理解长任务稳定性很有帮助：
| 级别 | 机制 | 是否调 LLM |
|---|---|---|
第一级 dsh-compaction-tool-result-pruner |
超预算的 tool/result（如 read/bash 长输出）改写为「保留开头 + 省略标记 + 保留尾部」，纯语法级剪枝 |
❌ 不调 LLM |
第二级 dsh-compaction-basic |
剪枝仍不足以缓解上下文压力时，调用 LLM 生成语义摘要（retainRatio: 0.08 保留最新 8%、maxTokens: 8192、thresholdRatio: 0.8） |
✅ 仅在必要时 |
理解要点：DSH 先通过非 LLM 剪枝低成本地把工具输出"压形"，只有仍超预算才让 LLM "压义"。这对网关侧的长任务（跨多次 POST push/pull）至关重要——它避免了上下文无限膨胀，同时保住工具结果细节与对话语义，让长流程稳定可控。
- 插件本体零侵入（0-Diff）：登录页、多账号管理、机器 POST API 均基于 DSH 标准扩展点实现，无需修改官方核心代码。
✅ 20260923 核对：DSH 0.1.5+ 起已完全零侵入——官方原生提供
/api前置登录门禁 （client/connection的browserAuth.isAuthenticated()），本插件无需任何源码补丁。 早期（0.1.2）曾需加requireSession扩展点，该路径已废弃。 - 人类 Web 通道：
- 优美自适应主题登录页（
/login与/logout）； - 多账号独立权限与 Web 账号管理面板；
- 本机回环（
127.0.0.1）免密直通。
- 优美自适应主题登录页（
- 机器 POST API 通道：
- 为 MaiBot（麦麦）/ 微信机器人 / 飞书 / CI/CD 等外部系统提供免 Cookie 的纯 POST API；
- 携带
Authorization: Bearer <Token>或X-Gateway-Token即可跨域直通，无论是在容器内、公网域名还是内网反向代理，永不受 127/Cookie 重定向限制。
⚠️ 现状核对（20260923，针对 DSH 0.1.5-rc.2 实测）：本节以下原文描述的是 0.1.2 时代的实现路径。实测结论：
原文所述 0.1.5 现状 需改源码加 requireSession扩展点❌ 源码中已不存在该扩展点（全仓库 grep 无命中） 插件 provide('sessionAuth')供 DSH 调用⚠️ 仍在 provide（lib/index.js:710），但源码中零消费者 —— 属预留/历史接口鉴权由 DSH 侧统一完成 ✅ 成立，但走的是官方原生实现： packages/client/connection/src/browser-auth.ts的isAuthenticated()，由rpc-host.ts:99调用（requestRejection）✅ 现状结论：DSH 0.1.5 已把「
/api前置登录门禁」吸收进官方源码， 公网未登录访问/api/*（含remote.muxwebsocket）一律 401，loopback 恒放行。 不再需要修改 DSH 源码，本插件负责的是登录页 + 多账号 + 机器通道。因此，若你在 0.1.5+ 上看到
/api/*返回 401 —— 这是正常的门禁行为，不是故障。 （实测：dsh1 与 dsh2 的无 cookie 请求表现完全一致。）
本插件保护的是「登录页 + 管理 API + 机器通道」，无法保护官方 /api/* 核心 RPC。DSH 官方把 /api/* 的信任边界定义在"谁能连到服务"（Host 头）而非"是否登录"，且 webserver 无中间件、路由防重复、RPC interceptor 拿不到 request——纯插件无法在 /api 前置登录校验。
因此，公网场景要实现「未登录禁止调用任何 DSH 核心功能」（发消息、执行命令、读写配置等），必须：
- 修改 DSH 源码：在
packages/client/connection/src/index.ts增加默认关闭的requireSession扩展点（不开启时与官方单用户行为完全一致；配套api-request-trust.ts导出两个内部函数）；⚠️ 0.1.5+ 已不需要此步骤——官方已原生实现，见上方现状核对。 - 本插件提供实现：
ctx.provide('sessionAuth', { isAuthenticated })返回鉴权判定。⚠️ 0.1.5+ 此接口已无消费者，保留仅为兼容旧版 DSH。
配置面（settings. / credentials.*）公网可用*：原生门禁放行登录用户后，原本公网一律 403 的配置面（读配置、改配置、凭据管理、原生对话框、agent preset 管理、模型发现）在公网可访问与修改——登录校验由 DSH 侧统一完成，未登录仍被 401 拦截。 ✅ 0.1.5+ 实测确认此行为成立（门禁由官方
browserAuth.isAuthenticated()承担）。
完整决策流程（仅本地 → 不改源码；公网 → 需改源码）、源码改动方案、git 维护与升级指导，见： 🔒
skill/public-network-auth-guide.md
| 接口 | 方法 | 鉴权方式 | 说明 |
|---|---|---|---|
/login |
GET / POST |
账号/密码表单 | Web 用户登录与会话颁发 |
/logout |
GET / POST |
Cookie | 安全登出 |
/api/dsh/v1/health |
GET |
免密 / Token | 健康检查与状态探测 |
/api/dsh/v1/task |
POST |
Bearer Token | 调度 DSH 核心引擎派发 Agent 任务 |
/api/dsh/v1/mcp/tool |
POST |
Bearer Token | 直接调用 DSH 工具（如 bash, read） |
功能：为网关的每一笔请求（/api/dsh/v1/*，含 /task）固化成一条溯源记录，用于回答「谁、从哪、走什么通道、调用哪个接口/插件下发了任务」。
落册两条：
ctx.logger：进程日志中以[postapi-audit]前缀输出（DSH supervisor 的dsh-web.log/dsh-rescue.log可见）；data/access-log.jsonl：插件数据目录下的 JSON Lines 文件（默认插件目录/data/，超 5MB 自动轮转保留 3 份.1/.2/.3）。
记录四要素：
| 要素 | 字段 | 来源 |
|---|---|---|
| 来源 IP | ip / xff / loopback |
直连 IP + X-Forwarded-For 全链 + 是否回环 |
| 域名入口 | host / xForwardedHost / xForwardedProto |
Host 头与转发头 |
| 通道 | channel / channelVia |
X-DSH-Channel 头 → config.channels / DSH_GATEWAY_CHANNELS 的 token↔通道映射 → UA 推断 → unknown |
| 调用方 | caller / ua |
token 指纹（SHA256 前 8 位，明文 token 不落盘）+ User-Agent |
配置：
config.channels：{ "<token>": "通道名", ... }（把 maibot 的网关 token 映射为maibot，通道一眼可辨）；DSH_GATEWAY_CHANNELS：环境变量 JSON，格式同上（默认层，低于config.channels）；config.accessLogDir：自定义审计日志目录（默认插件data/）。
生效：改完重启 DSH（supervisorctl restart dsh-web），/api/dsh/v1/health 返回 "audited": true 作为启用标记。
# 一行命令挂载到 DSH web profile
dsh plugin --profile web add git+https://github.com/ptrel1/dsh-postapi-bridge.git
# 重启 DSH 服务生效
supervisorctl restart dsh-web📦 本仓库为当前维护源（最新
0.6.6）。⚠️ npm registry 上的dsh-postapi-bridge停留在0.1.0（缺少sessionAuth接线，会导致公网 API 403/401）， 不建议用dsh plugin add dsh-postapi-bridge安装。
cd ~/.dsh/profiles/web
dsh plugin --profile web add link:/main/app/github/dsh-postapi-bridge
# 重启 DSH 服务生效
supervisorctl restart dsh-web
⚠️ 现状（20260923）：本节论述的是为什么当初选择"源码门禁"而不是"纯插件方案"—— 这个设计判断本身仍然成立（能力边界对比见下表）。 但实现路径已变：官方在 0.1.5 把该门禁吸收进了源码本体 （client/connection的browserAuth.isAuthenticated()）， 因此使用者不再需要自己打补丁——那是上游替我们做了这件事。 下表左列「纯插件」的局限，仍是当前生态里第三方远程控制插件的真实局限。
本插件的登录鉴权依赖一个源码级扩展点（client-connection 的 requireSession）。为什么不做成"零侵入"纯插件？因为两种方案的能力边界完全不同：
| 维度 | 纯插件（零侵入） | 源码扩展点（官方原生门禁） |
|---|---|---|
能否在 /api 前置鉴权 |
不能（官方无中间件、路由防重复、interceptor 无 request） | 能：connection 路由 handler 内统一校验 |
| 覆盖范围 | 只能 gate 自己新开的通道 | 整个 /api/*：HTTP RPC + SSE + WebSocket，fail-closed |
对直连 /api（curl 绕过） |
管不住 | 一律 401/403 |
| 与官方升级的兼容性 | 天然无冲突 | 由官方维护（0.1.5+ 起无需自行 merge） |
源码门禁的好处（对比纯插件远程控制方案）：
- 守住官方唯一的门：鉴权发生在
/api入口本身，任何客户端（浏览器、curl、脚本、第三方前端）都被同一道门拦截； - 不被通道绕过：纯插件"远程控制"方案只能把流量引到自己通道再以本机身份代理回
/api，本质是可绕过的通道门禁；源码门禁没有这个缝； - 行为不漂移：loopback 恒放行、非回环未登录 401 —— 由官方语义保证；
- 配置面随用户登录开放：登录用户可在公网读写
settings.*/credentials.*（官方默认 pin loopback）。
- 设备配对 ≠ 用户登录：
dsh-remote-web-ui的"设备配对"只是给设备发 cookie，管不住直连官方/api的请求（官方源码原话："没有插件能做到；/api的围栏是 SDK 自己的接缝"）。 - 配对会绕过登录门禁：它把远程流量经
/remote通道用 loopback 反向代理（伪造Host:127.0.0.1）转回本机，而门禁对 loopback 恒放行 → 配对成功即免登录全权限。 - 本部署取舍：公网登录鉴权的唯一入口是源码级门禁（0.1.5+ 为官方原生，fail-closed）；已在 profile patch 禁用
web-ui-remote-web-ui：
# ~/.dsh/profiles/web/cordis.patch.yml
- id: web-ui-remote-web-ui
disabled: true- 详细架构对比见 🔒
skill/public-network-auth-guide.md§七。