可插拔编码代理 KeepLost/harniverse

Harniverse

Harniverse 是本仓库维护的 DeepSeek Harness 源码优先下游项目。它保留由 Cordis 驱动的一切皆插件架构，并通过相同的插件 seam（接缝）组合 Harniverse 特有能力与安全策略。

Harniverse 目前没有独立的 npm 发行包。npx @deepseek-ai/dsh 安装的是 DeepSeek Harness 官方包，而不是本下游项目；请按以下源码流程使用 Harniverse。

快速开始

本教程从一台新机器开始，以 Web UI 收到第一条模型回复为完成标志。

1. 检查前置条件

请安装：

- Git 2.26 或更高版本。
- Node.js 22.19.x，或 Node.js 24 及更高版本。
- pnpm 11.7.0。仓库通过 packageManager 固定该版本；如果 pnpm --version 不可用，请启用 Corepack 或按 pnpm 官方安装方式安装。

克隆前先检查工具：

git --version
node --version
pnpm --version

安装和启动 Web UI 不需要模型 API 密钥；登录后再配置提供方。

2. 从源码安装 Harniverse

git clone https://github.com/KeepLost/harniverse.git
cd harniverse
pnpm install
pnpm run build

构建会生成源码启动器所需的 Host、Client 和 Web 前端产物。请保留该 checkout；后续命令通过仓库根目录的 pnpm dsh 脚本运行 Harniverse。

3. 启动 Web UI

在终端 A 中进入 Harniverse checkout 并运行：

pnpm dsh --profile web

首次运行会初始化 web profile 并打印实际访问地址，默认为 http://127.0.0.1:3080。保持终端 A 运行，然后在浏览器中打开该地址。

运行时 profile、认证 Grant（授权）、凭据、设置与会话位于 $DSH_HOME 下，其默认值为 ~/.dsh。

4. 批准第一台浏览器

浏览器会先打开设备配对页，再加载应用：

1. 输入由 1 至 64 个字母或数字组成的设备名称，可包含空格、点、下划线或连字符；支持 我的设备 等 Unicode 名称。
2. 选择配对个人设备。
3. 保持页面打开，记下页面显示的批准码与 request id。

在终端 B 中，以同一个操作系统用户进入同一 checkout，并将该请求批准为首个 owner：

pnpm dsh auth device approve <request-id> --profile owner

如果需要重新查看 request id，请列出等待中的请求：

pnpm dsh auth device list

浏览器会轮询请求状态，并在批准后自动进入应用。页面按安装后使用方式显示 dsh auth ...；源码用户应通过 pnpm dsh auth ... 运行同一命令。

两个终端必须解析到同一个 DSH_HOME。如果你覆盖了该变量，Web 与 auth 命令必须使用相同的值，否则 auth 命令看不到浏览器请求。

使用 pnpm dsh auth grant list 列出已批准设备和 API client；它与 device list 不同，会显示已经提交的 Grant 及其 id、名称、类型、capability 和过期时间。已经认证的 owner 浏览器也可以在同一 Web origin 打开 /auth/manage，例如 https://127.0.0.1:3000/auth/manage，查看等待请求与已批准 Grant。认证活动以 owner-only JSONL 保留在 $DSH_HOME/auth/access.jsonl；测试时可以持续查看：

tail -f "${DSH_HOME:-$HOME/.dsh}/auth/access.jsonl"

Web profile 会把信任策略和连接／认证事件输出到服务器终端。每条事件包含 method 或 channel、path、peer 地址、Host、Origin，以及已知的非机密 Grant 名称／id；不会输出 cookie、Authorization 值、公钥或请求体。owner-only 审计文件仍是持久化的最小隐私记录。

使用邀请口令配对

除了在终端批准，owner 也可以预先签发一次性注册邀请。在配对页提交设备表单后，按页面提示输入邀请口令，配对立即完成，无需终端批准。

在主机上签发邀请（--profile 与 --capability 互斥，必须且只能提供一个）：

pnpm dsh auth code issue --ttl 30m --profile owner

--ttl 接受 30s、5m、12h、7d 或毫秒数，决定口令的可兑换时长。--profile 指定兑换后获得的 Grant profile（observer、operator、administrator 或 owner）；--capability 改为授予显式 harniverse. capability，但它要求已存在可授权的活动 Grant，因此全新安装的首批邀请应使用 --profile owner。--kind temporary 生成的 Grant 会在固定时限后过期并带空闲超时，且不能携带 harniverse.authorize；默认的 device 与被批准的浏览器一样持久。--bind <name> 要求兑换时使用完全相同的设备名，--count <n> 一次签发多份邀请。

每个口令输出一行制表符分隔的字段：token、id、kind、capability 和过期时间。token 以 dshi1_ 开头，仅在签发时显示一次。已保留的邀请可随时列出，也可在兑换前吊销：

pnpm dsh auth code list
pnpm dsh auth code revoke

5. 配置并选择模型

新安装在配置提供方之前没有可用的模型路由：

1. 打开设置 → 模型。
2. 对已安装的目录提供方选择添加提供方，或为 OpenAI 兼容端点选择添加自定义提供方。
3. 输入所需凭据并保存提供方。
4. 在模型选择器中选择该提供方的一个模型。

提供方会立即可用，无需重启 Harniverse。通过 UI 保存的密钥是只写的：凭据存储将密钥保存在 $DSH_HOME/.credentials.yaml，settings 只保留其引用。原生凭据、自定义端点与模型能力详见配置模型。

6. 选择工作区并运行首个任务

选择选择工作区，添加允许 Harniverse 操作的项目目录，再选中它。新的 Web UI 刻意不预选工作区；工作区与模型均未选定前，会话输入框保持不可用。

创建会话并发送：

Summarize this workspace and list its main components.

收到 assistant 回复即完成首次使用流程。受保护的操作会按照当前权限策略请求批准。

日常使用与更新

首次设置完成后，通过同一 checkout 启动：

cd harniverse
pnpm dsh --profile web

使用 Ctrl+C 停止。浏览器 Grant、提供方设置、profile 与会话会保留在 $DSH_HOME 中。

更新 checkout 后，请先刷新依赖和全部运行时产物，再重新启动：

git pull
pnpm install
pnpm run build
pnpm dsh --profile web

Headless 使用

Headless profile 使用同一个 Harniverse home、提供方设置与凭据存储。配置模型后，无需 Web UI 即可运行一个任务：

pnpm dsh --profile headless "Summarize the current project"

调用命令时所在的目录是 headless 执行的默认工作区。命令会打印 assistant 的最终回复并退出。

Harniverse home（DSH_HOME）

全部用户状态都保存在同一个根目录下：profile、浏览器 Grant 与准入审计日志、提供方设置与凭据存储、会话，以及非回环监听使用的 TLS 材料。

根目录按以下优先级解析（从高到低）：

1. 配置中的显式 dshHome；
2. DSH_HOME 环境变量（空值或仅空白字符视为未设置）；
3. 默认值 ~/.dsh。

属于同一个 Harniverse 安装的所有进程必须解析到同一个根目录。在第二个终端运行 auth 命令时，请先导出相同的 DSH_HOME，否则该命令会检查另一个 home，找不到等待中的请求。

如果本机已经运行官方 DeepSeek Harness，请让 Harniverse 使用独立的根目录，使两套安装的状态互不干扰：

export DSH_HOME=~/.harniverse
pnpm dsh --profile web

取消该变量即可回退到共享默认值 ~/.dsh。

网络安全

默认回环监听也会启用认证。不要把 --dangerously-skip-authentication 当作安装捷径。非回环监听必须提供 TLS 证书和密钥；向其他机器开放 Harniverse 前，请先阅读 Web UI 指南。

如果容器发布端口而必须绑定 0.0.0.0，不要直接调用 Web profile，改用容器启动器：

pnpm run web:container -- --port 3000

web:container 不是另一个 profile，也不会使用另一套 Web 组合。直接部署入口是 pnpm dsh --profile web --host 0.0.0.0，在没有显式证书路径时仍会拒绝启动。该包装器只负责创建或复用开发证书、处理信任设置，然后使用与下列参数等价的方式启动同一个需要认证的 web profile：

pnpm dsh --profile web \
--host 0.0.0.0 \
--port 3000 \
--tls-cert "$DSH_HOME/tls/harniverse-dev-server.crt" \
--tls-key "$DSH_HOME/tls/harniverse-dev-server.key" \
--trusted-host localhost 127.0.0.1 host.docker.internal

它会在 $DSH_HOME/tls 下创建并持久化开发 CA 与服务器证书，在镜像允许时把 CA 安装进 Linux 容器的系统信任库，然后以 HTTPS 启动仍然需要认证的 Web profile。请将 DSH_WEB_TLS_HOSTS 设置为浏览器实际使用的名称或 IP 地址（逗号分隔），并把 $DSH_HOME 挂载为 volume，使容器替换后仍复用同一个 CA。启动器会把这些 host 同时传给 Host 信任栅栏，并在启动时打印生效的 host 与显式 Origin。浏览器宿主机针对这个已挂载的 DSH_HOME 运行一次 pnpm run web:container:trust；该命令会调用 Linux、macOS 或 Windows 的系统信任工具，并可能请求管理员批准。生产环境则使用受信任的反向代理。

Tailscale 远程访问

如果浏览器位于另一台 Tailscale 设备上，请使用服务器的 Tailscale IP 或 MagicDNS 名称，不要使用打印出来的 127.0.0.1 URL。把浏览器实际使用的 authority 同时加入证书 SAN 与 Host allowlist，然后重启启动器：

export DSH_WEB_TLS_HOSTS=localhost,127.0.0.1,host.docker.internal,100.64.0.2
pnpm run web:container -- --port 3000

在远程设备打开 https://100.64.0.2:3000，在该设备安装开发 CA，然后完成正常的设备配对和 owner 批准。将 100.64.0.2 替换为服务器实际的 Tailscale IP 或 MagicDNS 名称。这种普通 Tailscale 路径是同源访问，只需配置 DSH_WEB_TLS_HOSTS；不要为它设置 DSH_WEB_TRUSTED_ORIGINS。

DSH_WEB_TRUSTED_ORIGINS 是高级集成选项，用于浏览器页面的精确 Origin 与已声明的 Harniverse 请求 Host 不同的情况，例如独立托管的控制面板。它只允许该 Origin 通过 Harniverse 的请求信任栅栏，不会添加 CORS 响应头、处理浏览器 preflight，也不会自动让独立 Web 应用具备跨 Origin 兼容性。这类集成必须自行提供完整的 CORS 或同源反向代理设计。只有把它作为完整部署的一部分时，才通过环境变量或重复的 --trusted-origin 配置精确 Origin：

export DSH_WEB_TRUSTED_ORIGINS=https://panel.example.test
pnpm dsh --profile web --host 0.0.0.0 --port 3000 \
--tls-cert /path/server.crt --tls-key /path/server.key \
--trusted-host harniverse.example.test \
--trusted-origin https://panel.example.test

启动行会显示生效的 hosts 和显式 origins。被拒绝的请求会以 403 记录 Host、Origin、Fetch-Metadata 标记、peer 和 path；通过信任栅栏与认证的请求会记录设备／Grant 和 channel。远程浏览器使用证书或 Host 列表中不存在的名称或 IP 时，会被有意拒绝，不会静默绕过栅栏。

排错

- pnpm install 报告 engine 不匹配：使用 Node.js 22.19.x，或 Node.js 24 及更高版本。
- 启动时报 frontend dist 缺失：在仓库根目录运行 pnpm run build。
- dsh: command not found：本源码流程使用 pnpm dsh，不依赖全局可执行文件。
- auth 命令找不到请求：确保两个终端由同一用户运行并使用同一 DSH_HOME，再运行 pnpm dsh auth device list。
- 已批准设备没有出现在 device list 中：该命令只显示等待中的请求；使用 pnpm dsh auth grant list 查看已批准 Grant。
- 终端没有连接行：修改源码或信任环境后必须重启当前 Web 进程，然后检查启动时的 dsh web trust: 行。通过和拒绝的连接都会输出非机密请求标记；持久化准入审计仍在 $DSH_HOME/auth/access.jsonl。
- Tailscale 浏览器收到 403 forbidden：URL 使用服务器准确的 Tailscale IP 或 MagicDNS 名称，把同一个值加入 DSH_WEB_TLS_HOSTS，在浏览器设备信任生成的 CA，并重启 pnpm run web:container。
- 自定义 UI Origin 收到 403 forbidden：请求 Host 仍需位于 --trusted-host，再通过 DSH_WEB_TRUSTED_ORIGINS 或 --trusted-origin 添加精确的 https://host[:port] Origin。这只会改变请求信任栅栏；部署仍须单独提供可用的 CORS 或同源代理。路径、凭据、query string 和通配符 Origin 都会被拒绝。
- Web UI 可以打开但不能发送：配置并选择模型，再选择工作区。
- 3080 端口已被占用：使用 pnpm dsh --profile web --port <port> 选择其他回环端口。
- 容器拒绝 --host 0.0.0.0：使用 pnpm run web:container -- --port 3000，不要手工准备证书文件。

项目关系与状态

Harniverse 继承 DeepSeek Harness、其 dsh CLI、@deepseek-ai/dsh- 包命名空间和 Cordis 插件架构。架构文档、包参考与子系统参考定义当前能力和组合；Agent Notes记录决策与所需验证。

Harniverse 的预发布政策允许在没有显式兼容性承诺的范围内修改接口。持久化格式政策保留永久仅允许增量扩展的会话 v0，以及单调递增的 SQLite schema 版本。继承的 npm 命名空间并不表示已经存在独立的 Harniverse 发行包。

请通过 Harniverse Issues 报告 Harniverse bug 与文档问题。公开插件仓库可添加 dsh-plugin topic，便于生态发现。

参与贡献与开发

提出改动前请阅读 CONTRIBUTING.md。贡献者从开发指南开始，并阅读架构文档。agent 遵循 AGENTS.md。

许可证与归属

Harniverse 是一个独立的社区项目，不隶属于 DeepSeek，未获得 DeepSeek 背书，也没有 DeepSeek 员工参与。它构建于开源的 DeepSeek Harness 之上；对原样继承的部分，该项目许可证继续适用。

Harniverse 整体按 BSD 3-Clause License 分发；自 DeepSeek Harness（由 DeepSeek AI 开发）原样继承的部分，仍保留该项目的 MIT 许可证。Harniverse 使用 Cordis，其设计参见论文 _A Programming Paradigm for Spatiotemporal Composability_。

第三方依赖及其许可证见 THIRD_PARTY_NOTICES.md。