dsh-horon 1.0.2 → 1.2.0

package/README.md

@@ -13,22 +13,20 @@
 3. **控制台**（`index.js` + `client.js`）—— dsh web 服务器上的 `/dsh-horon/` 反向代理，把 Horon 控制台塞进侧栏 iframe；它和 dsh 自己的路由走同一道 Host/Origin + 登录栅栏，所以跨机器打开 dsh 也能用。`/dsh-horon/_dsh/*` 是设置页用的状态、配置、预览、部署、日志接口。
 4. **skills 注册**（可选）—— 宿主读不到 Horon 仓库时（`artifact` / `docker` / `url` 模式），从本包的 `skills/` 注册 `horon-cli` / `horon-circuit` / `horon-plugin`；`artifact` 模式解包后也有 `app/.agents/skills`，两处内容同源（都来自锁定的 commit）。
 
-## 四种服务运行方式
+## 两种运行方式
 
-`config.mode` 决定 Horon 服务从哪来（不写 `mode` 时：有 `url` 就是 `url`，否则 `spawn`）：
+面板上只有两个选择（`config.mode`）：
 
-| mode | 做法 | 关键配置 |
-| --- | --- | --- |
-| `artifact` | **推荐**。按 `horon.lock.json` 下载 CI 发布的构建物（后端 + 打包好的控制台 + 依赖轮子），校验 sha256、解包、离线装运行时，再当本机进程跑。不需要 Horon 仓库，也不需要 git / npm / Docker，只要 Python 3.12 | `artifactDir`、`artifactUrl`、`dataDir` |
-| `docker` | **推荐**。服务是本机上的容器，镜像由 CI 按同一个 commit 构建并推到 Docker Hub；插件只 `docker pull`，不构建 | `dataDir`、`dbFile`、`envFile`、`tagPluginsDir`、`dockerBind`、`dockerPort`、`image`、`container` |
-| `spawn` | 开发用。插件自己拉起本机克隆里的 `python -m uvicorn horon_web_app:app` | `root`、`python`、`host`、`port` |
-| `url` | 服务跑在别处，插件只记地址，不启动也不部署 | `url` |
+| mode | 做法 |
+| --- | --- |
+| `artifact` | **默认**。从 GitHub Release 下载 CI 发布的构建物（后端 + 打包好的控制台 + 依赖轮子），走 `proxy`，校验 sha256，解包到 `<dataDir>/runtime/` 并离线装好运行时，然后当本机进程跑。只要 Python 3.12，不需要 Docker / git / npm / Horon 仓库 |
+| `docker` | 拉 CI 发布的镜像并作为本机容器运行（`127.0.0.1:8710`，容器名 `horon`，镜像固定取自 `horon.lock.json`），`<dataDir>` 挂到 `/data`。本机不构建 |
 
-`artifact` 与 `docker` 共用 `dataDir`（默认 `~/.horon/docker`）：数据库、`.env`、tag 插件都在那里，所以换方式、换版本都不丢记忆；构建物按 `<commit8>-<platform>` 解包，回滚就是把锁文件的 commit 改回去。
+两者共用同一个数据目录，所以随时切换都不丢记忆；容器地址、镜像名、容器名都不需要用户填。
 
-服务本身没有鉴权，默认只绑回环地址；要跨机器用请自行加一层可信网络。
+`spawn`（跑本机克隆）与 `url`（接已有远端服务）仍在代码里，供开发使用，不在面板上出现。
 
-**首次安装没有 `mode`**：插件不启动任何东西，Horon 面板会先问「下载构建物 / 拉取 Docker 镜像」。
+**首次安装没有 `mode`**：插件不启动任何东西，Horon 面板会先问「构建物 / Docker」。
 本机已有 `~/horon` 克隆的机器视为已选择 `spawn`，升级不会被重新询问。
 
 ## 安装
@@ -141,23 +139,23 @@ node test/host-smoke.mjs && node test/artifact-smoke.mjs      # 只跑纯函数
 
 | key | 默认 | 说明 |
 | --- | --- | --- |
-| `mode` | 由 `url` 推断，否则 `spawn`（首次安装面板会问） | `artifact` / `docker` / `spawn` / `url` |
-| `url` | — | 运行中的 Horon 服务地址，例如 `http://127.0.0.1:8710` |
-| `artifactDir` | `~/.horon/runtime` | 构建物解包目录，每个版本一个 `<commit8>-<platform>` 子目录 |
-| `artifactUrl` / `artifactBaseUrl` / `artifactSha256` | 取自 `horon.lock.json` | 换镜像站或本地路径时用；后两者一般不用写 |
-| `horonCommit` | `horon.lock.json` 的 commit | 临时钉到别的上游 commit（高级） |
-| `root` | `~/horon` | `spawn` 模式的 Horon 仓库根目录 |
-| `python` | `<root>/.venv/...`，没有 venv 时 `python` | 解释器；`artifact` 模式下是 bootstrap 的基础解释器 |
-| `host` / `port` | `127.0.0.1` / `8710` | `artifact` / `spawn` 模式的绑定地址 |
+| `mode` | 首次安装面板会问 | **面板只给两种**：`artifact`（构建物，免 Docker）、`docker`（拉镜像）。`spawn` / `url` 仍在代码里，供开发和接已有远端服务，不在面板上 |
+| `dataDir` | `~/.horon` | **唯一的路径设置**。数据库、`.env`、构建物、tag 插件全部由它派生；两种运行方式共用 |
+| `proxy` | `https://gh-proxy.com` | 下载代理：构建物从 GitHub Release 取；docker 模式下同时写进 `~/.docker/config.json` 的 `proxies`。留空表示直连 |
 | `autostart` | `true` | `false` 只挂插件，不拉起服务/容器 |
 | `hooks` | `true` | `false` 只留 `horon` 工具，不挂钩子（也可用环境变量 `HORON_HOOKS=off`） |
-| `skills` | `spawn` / `artifact` 模式外默认开 | 是否注册三个 horon skill |
-| `dataDir` | `~/.horon/docker` | `artifact` 与 `docker` 共用的宿主数据目录（库、`.env`、tag 插件） |
-| `dbFile` | `<dataDir>/data/horon.db` | SQLite 库；`docker` 模式挂到容器 `/data`，`artifact` 模式写进 `app/.env` 的 `HORON_DB`。从 docker 切过来时**显式写这一行**，否则会指向另一个库 |
-| `envFile` | `<dataDir>/.env` | API key / 代理；`docker` 模式缺失时从 `docker/env.example` 复制，`artifact` 模式作为 `app/.env` 的种子（`HORON_DB` 由 `dbFile` 覆盖） |
-| `tagPluginsDir` | `<dataDir>/tag_plugins` | tag 插件目录（`docker` 模式挂到 `/app/backend/tag_plugins`） |
-| `dockerBind` / `dockerPort` | `127.0.0.1` / `8710` | 容器发布地址 |
-| `image` / `container` | `<horon.lock.json image>` / `horon` | 镜像与容器名 |
+| `skills` | `spawn` 模式外默认开 | 是否注册三个 horon skill |
+
+由 `dataDir` 派生、**不需要手写**：
+
+| 路径 | 用途 |
+| --- | --- |
+| `<dataDir>/horon.db` | SQLite 库；docker 模式下整个 `<dataDir>` 挂到容器 `/data`，所以两边是同一个文件 |
+| `<dataDir>/.env` | API key / 代理。旧布局的 `<dataDir>/docker/.env` 在没有新文件时仍会被读取 |
+| `<dataDir>/runtime/<commit8>-<platform>/` | 构建物解包目录，换版本解包到新目录，旧的可回滚 |
+| `<dataDir>/tag_plugins/` | 个人 tag 插件；artifact 模式每次启动镜像进构建物的 `app/backend/tag_plugins`，docker 模式直接挂载 |
+
+开发/接入已有服务时才用：`root`（`~/horon`）、`python`、`url`、`host` / `port`（`127.0.0.1:8710`）。
 
 ## License
 

package/artifact.js

@@ -21,6 +21,16 @@ import https from 'node:https'
 import os from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import {
+  dbFileFor,
+  envFileFor,
+  expandHome,
+  proxyOf,
+  proxied,
+  resolveDataDir,
+  runtimeDirFor,
+  tagPluginsDirFor,
+} from './paths.js'
 
 const HERE = path.dirname(fileURLToPath(import.meta.url))
 export const LOCK_FILE = path.join(HERE, 'horon.lock.json')
@@ -29,10 +39,6 @@ const READY = path.join('app', '.ready.json')
 
 const text = (value) => (typeof value === 'string' && value.trim() ? value.trim() : undefined)
 
-function expandHome(value) {
-  return value === '~' || /^~[\\/]/.test(value) ? path.join(os.homedir(), value.slice(1)) : value
-}
-
 /** Bumped by CI; read at runtime so one package version can describe several deployments. */
 export function readLock() {
   try {
@@ -50,8 +56,8 @@ export function platformKey(platform = process.platform, arch = process.arch) {
   return `${platform}-${arch}`
 }
 
-export function defaultArtifactDir() {
-  return path.join(os.homedir(), '.horon', 'runtime')
+export function defaultArtifactDir(dataDir) {
+  return runtimeDirFor(dataDir ?? resolveDataDir({}))
 }
 
 function venvPython(appDir) {
@@ -66,7 +72,9 @@ export function artifactSettings(config) {
   const lock = readLock()
   const commit = text(c.horonCommit) ?? lock?.horon?.commit ?? ''
   const platform = platformKey()
-  const dir = path.resolve(expandHome(text(c.artifactDir) ?? defaultArtifactDir()))
+  const root = resolveDataDir(c)
+  // Unpacked releases live under the data directory, so one path covers the lot.
+  const dir = path.resolve(expandHome(text(c.artifactDir) ?? runtimeDirFor(root)))
   const staged = path.join(dir, `${commit.slice(0, 8)}-${platform}`)
   const short = commit.slice(0, 8)
   // `{commit8}` / `{platform}` keep one commit bump from scattering stale names over the release.
@@ -74,7 +82,10 @@ export function artifactSettings(config) {
   const given = text(c.artifactUrl)
   const name = fill(given ?? lock?.artifact?.asset ?? 'horon-app-{platform}-{commit8}.tar.gz')
   const baseUrl = fill(text(c.artifactBaseUrl) ?? lock?.artifact?.baseUrl ?? '')
-  const url = /^[a-z][a-z0-9+.-]*:\/\//i.test(name) ? name : `${baseUrl.replace(/\/+$/, '')}/${name}`
+  const direct = /^[a-z][a-z0-9+.-]*:\/\//i.test(name) ? name : `${baseUrl.replace(/\/+$/, '')}/${name}`
+  // GitHub releases are the only source; the proxy is what makes them reachable.
+  const proxy = proxyOf(c)
+  const url = proxied(direct, proxy)
   return {
     platform,
     commit,
@@ -87,16 +98,15 @@ export function artifactSettings(config) {
     sha256: lock?.artifact?.sha256?.[platform] ?? text(c.artifactSha256) ?? '',
     // The interpreter bootstrap runs with; the venv it creates is what the service runs on.
     basePython: text(c.python) ?? (process.platform === 'win32' ? 'python' : 'python3'),
-    // Shared with docker mode on purpose: switching modes keeps the database, .env and tag plugins.
-    dataDir: path.resolve(expandHome(text(c.dataDir) ?? path.join(os.homedir(), '.horon', 'docker'))),
-    // An explicit dbFile / envFile wins, so a user who ran docker mode keeps the very same memory
-    // file and API keys after switching. "My notes are gone" must not be the first report.
-    dbFile: text(c.dbFile)
-      ? path.resolve(expandHome(text(c.dbFile)))
-      : path.join(path.resolve(expandHome(text(c.dataDir) ?? path.join(os.homedir(), '.horon', 'docker'))), 'data', 'horon.db'),
-    envFile: text(c.envFile)
-      ? path.resolve(expandHome(text(c.envFile)))
-      : path.join(path.resolve(expandHome(text(c.dataDir) ?? path.join(os.homedir(), '.horon', 'docker'))), '.env'),
+    // One directory for both runtimes: switching keeps the database, the key file and tag plugins.
+    dataDir: root,
+    dbFile: text(c.dbFile) ? path.resolve(expandHome(text(c.dbFile))) : dbFileFor(root),
+    envFile: text(c.envFile) ? path.resolve(expandHome(text(c.envFile))) : envFileFor(root),
+    proxy: proxyOf(c),
+    // tag plugins are personal: they never travel in the release, so the user's directory is
+    // mirrored into the unpacked tree on every start.
+    tagPluginsDir: tagPluginsDirFor(root),
+    directUrl: direct,
     lock,
   }
 }
@@ -245,6 +255,40 @@ async function writeEnv(a, log) {
   await fs.writeFile(file, `${lines.join('\n')}\n`, 'utf8')
 }
 
+/**
+ * Mirror the user's tag plugins into the unpacked release.
+ *
+ * The release only carries the system plugins (state/action/result/exit by upstream allow-list);
+ * anything a user wrote for themselves lives in the data directory. Docker mode bind-mounts that
+ * directory over the same path, so this walk is what artifact mode needs to behave identically.
+ */
+async function syncTagPlugins(a, log) {
+  const target = path.join(a.appDir, 'backend', 'tag_plugins')
+  let names
+  try {
+    names = await fs.readdir(a.tagPluginsDir)
+  } catch {
+    return
+  }
+  const files = names.filter((name) => name.endsWith('.py'))
+  if (files.length === 0) return
+  await fs.mkdir(target, { recursive: true })
+  let copied = 0
+  for (const name of files) {
+    const from = path.join(a.tagPluginsDir, name)
+    const to = path.join(target, name)
+    try {
+      const [source, current] = await Promise.all([fs.stat(from), fs.stat(to).catch(() => undefined)])
+      if (current !== undefined && current.size === source.size && current.mtimeMs >= source.mtimeMs) continue
+      await fs.copyFile(from, to)
+      copied += 1
+    } catch {
+      // A plugin that cannot be read is skipped; the service logs its own loading errors.
+    }
+  }
+  if (copied > 0) log(`tag plugins: ${String(copied)} file(s) synced from ${a.tagPluginsDir}`)
+}
+
 /**
  * Make sure this pinned release is unpacked and its runtime is installed.
  * Resolves to `{ root, python }` for the spawn path; throws with a readable message otherwise.
@@ -257,8 +301,10 @@ export async function provisionArtifact(a, log = () => {}) {
   const python = venvPython(a.appDir)
   if (existsSync(marker) && existsSync(python)) {
     log(`artifact already installed at ${a.root}`)
-    // Still reconcile app/.env: the config may name a different database since the last start.
+    // Still reconcile both: the config may name a different directory since the last start, and
+    // tag plugins may have been edited.
     await writeEnv(a, log)
+    await syncTagPlugins(a, log)
     return { root: a.appDir, python }
   }
 
@@ -297,6 +343,7 @@ export async function provisionArtifact(a, log = () => {}) {
   log(`unpacking into ${a.root}`)
   await extract(archive, a.root, log)
   await writeEnv(a, log)
+  await syncTagPlugins(a, log)
 
   log('installing the runtime from the bundled wheels (no network)')
   const done = await run(a.basePython, [path.join(a.root, 'bootstrap.py')], {

package/client.js

@@ -41,63 +41,33 @@ window.__ModuleLoader__.load({
       sectionTitle: 'Horon 服务',
       loading: '正在读取配置…',
       mode: '运行方式',
-      modeSpawn: '本机进程（python -m uvicorn）',
       modeArtifact: '构建物（免 Docker）',
       modeDocker: 'Docker 容器（本机）',
-      modeUrl: '远端服务（只填 URL）',
-      modeHintSpawn: '由 dsh 自己拉起 Horon（需要本机 Python 环境和 Horon 仓库），开发时用。',
-      modeHintArtifact: '下载 CI 发布的构建物（后端 + 打包好的控制台 + 依赖轮子），解包到本机直接跑：不需要 Horon 仓库，也不需要 git / npm / Docker。',
-      modeHintDocker: 'Horon 跑在本机 Docker 容器里，数据全部挂载到下面这些宿主机目录。',
-      modeHintUrl: 'Horon 跑在别处，这里只记住地址；不启动也不部署。',
-      artifact: '构建物',
-      artifactHint: '按 horon.lock.json 锁定的 commit 和当前平台下载；换版本解包到新目录，旧版本留着可回滚。',
-      artifactDir: '构建物目录',
-      artifactDirHint: '默认：{def}',
-      artifactUrl: '构建物地址（可选）',
-      artifactUrlHint: '留空用 horon.lock.json 里的发布地址；也可以填镜像站或本地路径。',
-      artifactState: '构建物状态',
-      artifactMissing: '未下载',
-      artifactReady: '已就绪',
-      artifactPending: '已解包，运行时未装好',
-      artifactPin: '锁定',
+      modeHintArtifact: '从 GitHub Release 下载 CI 发布的构建物，解包到数据目录里直接跑：不需要 Horon 仓库，也不需要 git / npm / Docker。',
+      modeHintDocker: '拉取 CI 发布的镜像并作为本机容器运行，数据挂载到同一个数据目录。',
+      artifactReadyHint: '已就绪：构建物 {commit} · {platform}，位于数据目录的 runtime 下。',
+      artifactMissingHint: '还没下载：点「下载并安装」后会按锁定 commit 下载、校验摘要、离线装依赖。',
       provision: '下载并安装',
       provisioning: '下载安装中…',
-      provisionNote: '按锁定 commit 下载、校验 sha256、解包，再用自带的轮子离线装依赖。',
       provisionDone: '构建物已就绪，服务正在启动。',
       provisionFailed: '下载或安装失败，原因见日志。',
-      dataDirShared: '数据目录与 Docker 模式共用：数据库、.env、tag 插件都在这里，切换运行方式不会丢记忆。',
-      url: '服务地址',
-      urlHint: '例如 http://127.0.0.1:8710。服务本身没有鉴权，只应放在可信网络里。',
       autostart: '启动 dsh 时自动拉起',
       autostartHint: 'Docker 模式下只会 docker start 已存在的容器，不会替你创建。',
 
-      paths: '数据与挂载（全部在宿主机上）',
-      pathsHint: '留空即用默认值；路径可以写 ~，表示当前用户目录。数据库、.env、tag_plugins 都挂在宿主机上，重建容器不会丢。',
+      paths: '数据与下载',
+      pathsHint: '所有数据（数据库、.env、构建物、tag 插件）都在这一个目录下，两种运行方式共用，不会因为换方式丢记忆。留空用默认值，可以写 ~。',
       dataDir: '数据目录',
       dataDirHint: '默认：{def}',
-      dbFile: '数据库文件',
-      dbFileHint: '默认：{def}；所在目录挂到容器的 /data',
-      envFile: '环境变量文件',
-      envFileHint: '默认：{def}；API key 和代理写在这里，部署时若不存在会从 env.example 复制',
-      tagPluginsDir: 'tag 插件目录',
-      tagPluginsDirHint: '默认：{def}；挂到 /app/backend/tag_plugins',
-      dockerBind: '监听地址',
-      dockerPort: '端口',
-      bindHint: '默认 127.0.0.1',
-      portHint: '默认 8710',
-      image: '镜像',
-      container: '容器名',
+      proxy: '下载代理',
+      proxyHint: '默认 https://gh-proxy.com，用于从 GitHub Release 下载构建物；Docker 模式下拉镜像也会写进 ~/.docker/config.json。留空表示直连。',
 
       applied: '实际生效',
-      home: '用户目录',
-      platform: '当前平台',
-      bindWarning: '端口没有绑在回环地址上：Horon 服务没有鉴权，任何能访问这个端口的人都能读写你的记忆库。',
 
       save: '保存',
       saving: '保存中…',
       reset: '还原',
-      saveNote: '保存会改写 profile 的 cordis.patch.yml 并立即重载插件：本机进程模式的服务会被重启，端口改了还要刷新页面。',
-      saved: '已保存，插件正在重载；端口有变化时请刷新页面。',
+      saveNote: '保存会改写 profile 的 cordis.patch.yml 并立即重载插件：服务会按新的方式和目录重启。',
+      saved: '已保存，插件正在重载。',
       editBlocked: '这个 dsh 没有提供配置编辑器，只能手工改 profile 的 cordis.patch.yml。',
 
       deploy: '一键部署',
@@ -111,9 +81,7 @@ window.__ModuleLoader__.load({
       copyFailed: '浏览器不允许自动复制，请在下面手动选中。',
       tabCommands: '命令',
       tabCompose: 'compose',
-      tabDockerfile: 'Dockerfile',
       tabEnv: '.env 示例',
-      noContext: '镜像还没拉下来：点「一键部署」拉取即可。',
 
       onboardingTitle: '先选一种运行方式',
       onboardingNote: 'Horon 服务需要一个运行时。选一种装好就能用；之后可在「设置 → Horon 服务」里随时改。',
@@ -148,57 +116,27 @@ window.__ModuleLoader__.load({
       sectionTitle: 'Horon service',
       loading: 'Loading the settings…',
       mode: 'Mode',
-      modeSpawn: 'Local process (python -m uvicorn)',
       modeArtifact: 'Build artifact (no Docker)',
       modeDocker: 'Docker container (this host)',
-      modeUrl: 'Remote service (URL only)',
-      modeHintSpawn: 'dsh starts Horon itself from a local clone; the developer path.',
-      modeHintArtifact: 'Downloads the artifact CI released (backend + built console + pinned wheels) and runs it here: no Horon repository, no git, no npm, no Docker.',
-      modeHintDocker: 'Horon runs in a container on this host; everything below is bind-mounted from the host.',
-      modeHintUrl: 'Horon runs elsewhere; only the address is remembered. Nothing is started or deployed.',
-      artifact: 'Build artifact',
-      artifactHint: 'Downloaded for the commit pinned in horon.lock.json and this platform; a new version unpacks next to the old one, so rolling back is a config change.',
-      artifactDir: 'Artifact directory',
-      artifactDirHint: 'Default: {def}',
-      artifactUrl: 'Artifact URL (optional)',
-      artifactUrlHint: 'Empty uses the release URL in horon.lock.json; a mirror or a local path works too.',
-      artifactState: 'Artifact state',
-      artifactMissing: 'not downloaded',
-      artifactReady: 'ready',
-      artifactPending: 'unpacked, runtime not installed',
-      artifactPin: 'pinned',
+      modeHintArtifact: 'Downloads the artifact CI released from GitHub, unpacks it under the data directory and runs it: no Horon repository, no git, no npm, no Docker.',
+      modeHintDocker: 'Pulls the image CI released and runs it as a local container, with the same data directory mounted in.',
+      artifactReadyHint: 'Ready: artifact {commit} · {platform}, under the data directory runtime folder.',
+      artifactMissingHint: 'Not downloaded yet: Download and install fetches the pinned commit, verifies the digest and installs the runtime offline.',
       provision: 'Download and install',
       provisioning: 'Downloading…',
-      provisionNote: 'Downloads the pinned commit, verifies sha256, unpacks it and installs the runtime from the bundled wheels, offline.',
       provisionDone: 'The artifact is ready; the service is starting.',
       provisionFailed: 'The download or install failed; see the log.',
-      dataDirShared: 'The data directory is shared with Docker mode: database, .env and tag plugins stay put when you switch.',
-      url: 'Service URL',
-      urlHint: 'For example http://127.0.0.1:8710. The service has no auth of its own, so keep it inside a trusted network.',
       autostart: 'Start it when dsh starts',
       autostartHint: 'In Docker mode this only runs docker start on an existing container; it never creates one.',
 
-      paths: 'Data and mounts (all on the host)',
-      pathsHint: 'Leave a field empty to use the default; `~` means the home directory. The database, .env and tag_plugins live on the host, so recreating the container keeps them.',
+      paths: 'Data and downloads',
+      pathsHint: 'Everything lives under this one directory — database, .env, unpacked artifacts, tag plugins — and both runtimes share it, so switching keeps your memory. Empty uses the default; ~ works.',
       dataDir: 'Data directory',
       dataDirHint: 'Default: {def}',
-      dbFile: 'Database file',
-      dbFileHint: 'Default: {def}; its directory is mounted at /data',
-      envFile: 'Environment file',
-      envFileHint: 'Default: {def}; API keys and proxies go here, copied from env.example when missing',
-      tagPluginsDir: 'Tag plugins directory',
-      tagPluginsDirHint: 'Default: {def}; mounted at /app/backend/tag_plugins',
-      dockerBind: 'Listen address',
-      dockerPort: 'Port',
-      bindHint: 'Default 127.0.0.1',
-      portHint: 'Default 8710',
-      image: 'Image',
-      container: 'Container name',
+      proxy: 'Download proxy',
+      proxyHint: 'https://gh-proxy.com by default, used to fetch the artifact from GitHub Releases; in Docker mode it is also written into ~/.docker/config.json for pulls. Empty means a direct connection.',
 
       applied: 'In effect',
-      home: 'Home directory',
-      platform: 'Platform',
-      bindWarning: 'The port is not bound to a loopback address: the Horon service has no auth, so anyone who can reach it can read and write your memory database.',
 
       save: 'Save',
       saving: 'Saving…',
@@ -218,9 +156,7 @@ window.__ModuleLoader__.load({
       copyFailed: 'The browser refused clipboard access; select the text below instead.',
       tabCommands: 'Commands',
       tabCompose: 'compose',
-      tabDockerfile: 'Dockerfile',
       tabEnv: '.env example',
-      noContext: 'The image has not been pulled yet: press Deploy now.',
 
       onboardingTitle: 'Choose how to run it',
       onboardingNote: 'The Horon service needs a runtime. Pick one and it is ready; you can change it later under Settings → Horon service.',
@@ -532,12 +468,6 @@ window.__ModuleLoader__.load({
       )
     }
 
-    const DEFAULTS = {
-      dockerBind: '127.0.0.1',
-      dockerPort: '8710',
-      container: 'horon',
-    }
-
     function SettingsSection(props) {
       const t = props.t ?? ((key) => key)
 
@@ -728,17 +658,16 @@ window.__ModuleLoader__.load({
 
       const resolved = preview?.resolved ?? data?.resolved ?? {}
       const texts = preview?.texts ?? data?.texts ?? {}
-      const mode = draft.mode ?? data?.mode ?? 'spawn'
+      // Only the two runtimes a user actually picks between; spawn/url stay in the code for
+      // development and for an existing remote service, but they are not offered here.
+      const mode = draft.mode === 'docker' ? 'docker' : 'artifact'
       const serving = preview?.serving ?? status?.serving
       const docker = status?.docker
       const hooks = status?.hooks
-      const bind = resolved.dockerBind ?? DEFAULTS.dockerBind
-      const bindIsLoopback = ['127.0.0.1', 'localhost', '::1'].includes(String(bind))
 
       const blocks = [
         ['commands', t('tabCommands'), texts.commands],
         ['compose', t('tabCompose'), texts.compose],
-        ['dockerfile', t('tabDockerfile'), texts.dockerfile],
         ['env', t('tabEnv'), texts.envExample],
       ]
       const active = blocks.find(([key]) => key === tab) ?? blocks[0]
@@ -758,21 +687,10 @@ window.__ModuleLoader__.load({
             h(
               'select',
               { className: 'dshhw-select', value: mode, onChange: (event) => update({ mode: event.target.value }) },
-              h('option', { value: 'spawn' }, t('modeSpawn')),
               h('option', { value: 'artifact' }, t('modeArtifact')),
               h('option', { value: 'docker' }, t('modeDocker')),
-              h('option', { value: 'url' }, t('modeUrl')),
             ),
           ),
-          mode === 'url'
-            ? h(TextField, {
-                label: t('url'),
-                value: draft.url,
-                placeholder: 'http://127.0.0.1:8710',
-                width: '320px',
-                onChange: (value) => update({ url: value }),
-              })
-            : null,
           h(
             'label',
             { className: 'dshhw-check', title: t('autostartHint') },
@@ -784,42 +702,17 @@ window.__ModuleLoader__.load({
             t('autostart'),
           ),
         ),
-        h('div', { className: 'dshhw-note' }, mode === 'artifact' ? t('modeHintArtifact') : mode === 'docker' ? t('modeHintDocker') : mode === 'url' ? t('modeHintUrl') : t('modeHintSpawn')),
-        mode === 'url' ? h('div', { className: 'dshhw-hint' }, t('urlHint')) : null,
-
-        // Artifact mode: the released tree, its pin, and where it lands.
+        h('div', { className: 'dshhw-note' }, mode === 'artifact' ? t('modeHintArtifact') : t('modeHintDocker')),
         mode === 'artifact'
           ? h(
               'div',
-              { className: 'dshhw-section' },
-              h('h4', null, t('artifact')),
-              h('div', { className: 'dshhw-note' }, t('artifactHint')),
-              h(TextField, {
-                label: t('artifactDir'),
-                value: draft.artifactDir,
-                placeholder: data?.artifact?.dir ?? data?.defaultArtifactDir ?? '',
-                hint: t('artifactDirHint', { def: data?.defaultArtifactDir ?? data?.artifact?.dir ?? '' }),
-                onChange: (value) => update({ artifactDir: value }),
-              }),
-              h(TextField, {
-                label: t('artifactUrl'),
-                value: draft.artifactUrl,
-                placeholder: data?.artifact?.url ?? '',
-                hint: t('artifactUrlHint'),
-                onChange: (value) => update({ artifactUrl: value }),
-              }),
-              h(
-                'div',
-                { className: 'dshhw-hint' },
-                `${t('artifactPin')}: ${(data?.artifact?.commit ?? '').slice(0, 8)} · ${data?.artifact?.platform ?? ''} · ${t('artifactState')}: ${
-                  data?.artifactState?.ready === true
-                    ? t('artifactReady')
-                    : data?.artifactState?.installed === true
-                      ? t('artifactPending')
-                      : t('artifactMissing')
-                }`,
-              ),
-              h('div', { className: 'dshhw-hint' }, t('dataDirShared')),
+              { className: 'dshhw-hint' },
+              data?.artifactState?.ready === true
+                ? t('artifactReadyHint', {
+                    commit: (data?.artifact?.commit ?? '').slice(0, 8),
+                    platform: data?.artifact?.platform ?? '',
+                  })
+                : t('artifactMissingHint'),
             )
           : null,
 
@@ -855,7 +748,7 @@ window.__ModuleLoader__.load({
               ),
         ),
 
-        // Host mounts
+        // One directory decides everything else: database, key file, releases, tag plugins.
         h(
           'div',
           { className: 'dshhw-section' },
@@ -869,63 +762,18 @@ window.__ModuleLoader__.load({
             onChange: (value) => update({ dataDir: value }),
           }),
           h(TextField, {
-            label: t('dbFile'),
-            value: draft.dbFile,
-            placeholder: resolved.dbFile ?? '',
-            hint: t('dbFileHint', { def: resolved.dbFile ?? '' }),
-            onChange: (value) => update({ dbFile: value }),
-          }),
-          h(TextField, {
-            label: t('envFile'),
-            value: draft.envFile,
-            placeholder: resolved.envFile ?? '',
-            hint: t('envFileHint', { def: resolved.envFile ?? '' }),
-            onChange: (value) => update({ envFile: value }),
-          }),
-          h(TextField, {
-            label: t('tagPluginsDir'),
-            value: draft.tagPluginsDir,
-            placeholder: resolved.tagPluginsDir ?? '',
-            hint: t('tagPluginsDirHint', { def: resolved.tagPluginsDir ?? '' }),
-            onChange: (value) => update({ tagPluginsDir: value }),
+            label: t('proxy'),
+            value: draft.proxy,
+            placeholder: data?.defaultProxy ?? '',
+            hint: t('proxyHint'),
+            onChange: (value) => update({ proxy: value }),
           }),
           h(
             'div',
-            { className: 'dshhw-row' },
-            h(TextField, {
-              label: t('dockerBind'),
-              value: draft.dockerBind,
-              placeholder: DEFAULTS.dockerBind,
-              hint: t('bindHint'),
-              width: '170px',
-              onChange: (value) => update({ dockerBind: value }),
-            }),
-            h(TextField, {
-              label: t('dockerPort'),
-              value: draft.dockerPort === undefined ? '' : String(draft.dockerPort),
-              placeholder: DEFAULTS.dockerPort,
-              hint: t('portHint'),
-              width: '110px',
-              onChange: (value) => update({ dockerPort: value }),
-            }),
-            h(TextField, {
-              label: t('image'),
-              value: draft.image,
-              placeholder: texts.image ?? '',
-              width: '200px',
-              onChange: (value) => update({ image: value }),
-            }),
-            h(TextField, {
-              label: t('container'),
-              value: draft.container,
-              placeholder: DEFAULTS.container,
-              width: '150px',
-              onChange: (value) => update({ container: value }),
-            }),
+            { className: 'dshhw-hint' },
+            `${t('applied')}: ${resolved.dbFile ?? ''} · ${resolved.envFile ?? ''} · ${resolved.base ?? ''}`,
           ),
-          h('div', { className: 'dshhw-hint' }, `${t('home')}: ${data?.home ?? ''} · ${t('platform')}: ${data?.platform ?? ''}`),
-          h('div', { className: 'dshhw-hint' }, `${t('applied')}: ${resolved.dataDir ?? ''} → ${resolved.base ?? ''}`),
-          bindIsLoopback ? null : h('div', { className: 'dshhw-warn' }, t('bindWarning')),
+          h('div', { className: 'dshhw-note' }, t('saveNote')),
           h('div', { className: 'dshhw-note' }, t('saveNote')),
           h(
             'div',
@@ -995,7 +843,7 @@ window.__ModuleLoader__.load({
           h('div', { className: 'dshhw-note' }, t('deployNote')),
           active[2]
             ? h('pre', { className: 'dshhw-code' }, active[2])
-            : h('div', { className: 'dshhw-warn' }, texts.contextReady === false ? t('noContext') : t('loading')),
+            : h('div', { className: 'dshhw-warn' }, t('loading')),
           h('textarea', {
             ref: clip,
             className: 'dshhw-clip',

package/docker.js

@@ -21,6 +21,16 @@ import os from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { readLock } from './artifact.js'
+import {
+  dbFileFor,
+  defaultDataDir,
+  envFileFor,
+  expandHome,
+  localDirFor,
+  proxyOf,
+  resolveDataDir,
+  tagPluginsDirFor,
+} from './paths.js'
 
 const HERE = path.dirname(fileURLToPath(import.meta.url))
 export const DOCKER_DIR = path.join(HERE, 'docker')
@@ -29,6 +39,8 @@ const CONTAINER_PORT = 8710
 const LOG_LIMIT = 256 * 1024
 const READY_TIMEOUT_MS = 120_000
 const STATUS_TIMEOUT_MS = 8000
+// Same file Docker Desktop's own proxy settings are written to.
+const DOCKER_CONFIG = path.join(os.homedir(), '.docker', 'config.json')
 
 /** The published image this plugin version was built against. */
 export function defaultImage() {
@@ -36,9 +48,7 @@ export function defaultImage() {
   return image?.name && image?.tag ? `${image.name}:${image.tag}` : 'horon-service:local'
 }
 
-export function defaultDataDir() {
-  return path.join(os.homedir(), '.horon', 'docker')
-}
+export { defaultDataDir, expandHome }
 
 // Host part of a URL for a bind address; a wildcard bind is reached on loopback.
 export function urlHost(host) {
@@ -54,36 +64,30 @@ function hostTimeZone() {
   }
 }
 
-// `~` / `~/…` / `~\…` is the home directory of the user running dsh, so one config works on both
-// Windows and Linux.
-export function expandHome(value) {
-  return value === '~' || /^~[\\/]/.test(value) ? path.join(os.homedir(), value.slice(1)) : value
-}
-
-// Docker settings with every default filled in. Paths that are not set follow dataDir.
+// Docker settings with every default filled in. Everything derives from `dataDir`; the container
+// itself is fixed (loopback, 8710, the published image), because none of that is a decision a user
+// should have to make.
 export function dockerSettings(config) {
   const c = config ?? {}
   const text = (value) => (typeof value === 'string' && value.trim() ? value.trim() : undefined)
-  const file = (value) => {
-    const given = text(value)
-    return given === undefined ? undefined : path.resolve(expandHome(given))
-  }
-  const dataDir = file(c.dataDir) ?? defaultDataDir()
-  const dbFile = file(c.dbFile) ?? path.join(dataDir, 'data', 'horon.db')
-  const dockerBind = text(c.dockerBind) ?? '127.0.0.1'
-  const dockerPort = Number(c.dockerPort ?? 8710)
+  const root = resolveDataDir(c)
+  const dockerBind = '127.0.0.1'
+  const dockerPort = 8710
   return {
-    dataDir,
-    dbFile,
-    dbDir: path.dirname(dbFile),
-    localDir: path.join(dataDir, 'local'),
-    envFile: file(c.envFile) ?? path.join(dataDir, '.env'),
-    tagPluginsDir: file(c.tagPluginsDir) ?? path.join(dataDir, 'tag_plugins'),
+    dataDir: root,
+    root,
+    // The directory bind-mounted at /data; the database sits directly in it, which is the same
+    // layout artifact mode uses, so switching runtimes finds the same file.
+    dbFile: text(c.dbFile) ? path.resolve(expandHome(text(c.dbFile))) : dbFileFor(root),
+    dbDir: path.dirname(text(c.dbFile) ? path.resolve(expandHome(text(c.dbFile))) : dbFileFor(root)),
+    localDir: localDirFor(root),
+    envFile: text(c.envFile) ? path.resolve(expandHome(text(c.envFile))) : envFileFor(root),
+    tagPluginsDir: tagPluginsDirFor(root),
     dockerBind,
     dockerPort,
-    image: text(c.image) ?? defaultImage(),
-    container: text(c.container) ?? 'horon',
-    buildProxy: text(c.buildProxy) ?? '',
+    image: defaultImage(),
+    container: 'horon',
+    proxy: proxyOf(c),
     timeZone: hostTimeZone(),
     base: `http://${urlHost(dockerBind)}:${dockerPort}`,
   }
@@ -233,14 +237,14 @@ export async function renderTexts(d, platform = process.platform) {
 
 // ---- running docker --------------------------------------------------------------------------
 
-function runDocker(args, { onData, timeoutMs } = {}) {
+function runDocker(args, { onData, timeoutMs, env } = {}) {
   return new Promise((resolve) => {
     let child
     try {
       child = spawn('docker', args, {
         shell: false,
         windowsHide: true,
-        env: { ...process.env, DOCKER_CLI_HINTS: 'false' },
+        env: { ...process.env, DOCKER_CLI_HINTS: 'false', ...env },
       })
     } catch (error) {
       resolve({ code: -1, out: '', err: String(error?.message ?? error) })
@@ -273,6 +277,55 @@ function runDocker(args, { onData, timeoutMs } = {}) {
 
 const firstLine = (text) => String(text ?? '').trim().split(/\r?\n/).pop() ?? ''
 
+/**
+ * `docker pull` runs in the engine, not in this process, so an environment variable here cannot
+ * reach it. Docker Desktop reads `proxies` from ~/.docker/config.json — the same file its own
+ * Settings page writes — so the proxy is recorded there before a pull. A Linux engine keeps that
+ * value in its service unit instead, and the log says so rather than pretending it took effect.
+ */
+async function applyDockerProxy(proxy, say) {
+  if (proxy === '') {
+    say('\n# no download proxy configured; pulling directly\n')
+    return
+  }
+  let raw
+  let config = {}
+  try {
+    raw = await fs.readFile(DOCKER_CONFIG, 'utf8')
+    config = JSON.parse(raw)
+  } catch {
+    config = {}
+  }
+  const current = config.proxies?.default ?? {}
+  if (current.httpProxy === proxy && current.httpsProxy === proxy) {
+    say(`\n# docker already uses ${proxy}\n`)
+    return
+  }
+  if (raw !== undefined) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+    await fs.writeFile(`${DOCKER_CONFIG}.horon-backup-${stamp}`, raw, 'utf8')
+    say(`\n# backed up config.json -> ${path.basename(DOCKER_CONFIG)}.horon-backup-${stamp}\n`)
+  }
+  config.proxies = {
+    ...(config.proxies ?? {}),
+    default: {
+      httpProxy: proxy,
+      httpsProxy: proxy,
+      noProxy: current.noProxy ?? 'localhost,127.0.0.1,::1',
+    },
+  }
+  await fs.mkdir(path.dirname(DOCKER_CONFIG), { recursive: true })
+  await fs.writeFile(DOCKER_CONFIG, `${JSON.stringify(config, null, 2)}\n`, 'utf8')
+  say(`# recorded the proxy in ${DOCKER_CONFIG}\n`)
+  say('# Docker Desktop applies it; a Linux engine needs the same value in its service config\n')
+}
+
+// Some pulls (and `docker login`) do honour the client environment, so pass it along as well.
+function proxyEnv(proxy) {
+  if (proxy === '') return {}
+  return { HTTP_PROXY: proxy, HTTPS_PROXY: proxy, http_proxy: proxy, https_proxy: proxy }
+}
+
 export async function isServing(base, timeoutMs = 1200) {
   try {
     const response = await fetch(`${base}/api/sessions`, { signal: AbortSignal.timeout(timeoutMs) })
@@ -397,6 +450,8 @@ async function deploy(d, say) {
     return false
   }
 
+  await applyDockerProxy(d.proxy, say)
+
   // Something else on the port (typically a spawn/artifact-mode service) would make `docker run`
   // fail after a long pull; stop early instead. Our own running container is replaced below.
   const inspect = await runDocker(['inspect', '--type', 'container', '--format', '{{.State.Running}}', d.container])
@@ -419,7 +474,8 @@ async function deploy(d, say) {
     say(`created ${d.envFile} from env.example; put the API keys / proxy there\n`)
   }
 
-  if ((await step(flat(plan.pull))).code !== 0) return false
+  say(`\n$ docker ${flat(plan.pull).map(quotePosix).join(' ')}\n`)
+  if ((await runDocker(flat(plan.pull), { onData: say, env: proxyEnv(d.proxy) })).code !== 0) return false
   await step(flat(plan.remove)) // "No such container" on the first deploy is fine
   if ((await step(flat(plan.run))).code !== 0) return false
 

package/index.js

@@ -60,14 +60,9 @@ import https from 'node:https'
 import os from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { artifactSettings, artifactStatus, provisionArtifact } from './artifact.js'
+import { defaultDataDir, proxyOf } from './paths.js'
 import {
-  artifactSettings,
-  artifactStatus,
-  defaultArtifactDir,
-  provisionArtifact,
-} from './artifact.js'
-import {
-  defaultDataDir,
   deployState,
   dockerSettings,
   dockerStatus,
@@ -98,12 +93,10 @@ const ROUTE = '/dsh-horon'
 const API_PREFIX = `${ROUTE}/_dsh/`
 // The settings call carries one small config object; anything bigger is not a config edit.
 const MAX_BODY_BYTES = 512 * 1024
-// Keys the settings page may write into the profile patch.
-const EDITABLE = new Set([
-  'mode', 'url', 'autostart', 'dataDir', 'dbFile', 'envFile', 'tagPluginsDir',
-  'dockerBind', 'dockerPort', 'image', 'container',
-  'artifactDir', 'artifactUrl', 'artifactBaseUrl', 'artifactSha256', 'horonCommit', 'python', 'root',
-])
+// Keys the settings page may write into the profile patch. Everything else is derived: the
+// database, the key file, the runtime directory and the container all follow `dataDir`, and the
+// container itself is fixed (loopback, 8710, the published image).
+const EDITABLE = new Set(['mode', 'proxy', 'dataDir', 'autostart', 'hooks', 'skills', 'url', 'port', 'python', 'root'])
 const MODES = new Set(['spawn', 'artifact', 'docker', 'url'])
 // BUNDLED_SKILL_RANK of @deepseek-ai/dsh-skill: user (~/.dsh/skills) and project skills win over it.
 const SKILL_RANK = 600
@@ -331,16 +324,29 @@ function cleanInput(input) {
       out.autostart = value !== false && value !== 'false' && value !== null
       continue
     }
+    if (key === 'skills') {
+      out.skills = value !== false && value !== 'false' && value !== null
+      continue
+    }
+    if (key === 'hooks') {
+      out.hooks = value !== false && value !== 'false' && value !== null
+      continue
+    }
+    // An empty proxy is a choice ("connect directly"), not a reset, so it is stored as "".
+    if (key === 'proxy') {
+      out.proxy = String(value ?? '').trim()
+      continue
+    }
     // An emptied field clears the override instead of writing an empty string; preview and
     // deploy read it as "use the default".
     if (value === null || String(value).trim() === '') {
       out[key] = null
       continue
     }
-    if (key === 'dockerPort') {
+    if (key === 'port') {
       const port = Number(value)
-      if (!Number.isInteger(port) || port < 1 || port > 65535) throw httpError(400, 'dockerPort must be a port number')
-      out.dockerPort = port
+      if (!Number.isInteger(port) || port < 1 || port > 65535) throw httpError(400, 'port must be a port number')
+      out.port = port
       continue
     }
     if (key === 'mode' && !MODES.has(value)) throw httpError(400, 'mode must be spawn, artifact, docker or url')
@@ -400,35 +406,20 @@ function readableConfig(config) {
     url: c.url,
     autostart: c.autostart !== false,
     dataDir: c.dataDir,
-    dbFile: c.dbFile,
-    envFile: c.envFile,
-    tagPluginsDir: c.tagPluginsDir,
-    dockerBind: c.dockerBind,
-    dockerPort: c.dockerPort,
-    image: c.image,
-    container: c.container,
-    artifactDir: c.artifactDir,
-    artifactUrl: c.artifactUrl,
-    artifactBaseUrl: c.artifactBaseUrl,
-    artifactSha256: c.artifactSha256,
-    horonCommit: c.horonCommit,
-    python: c.python,
-    root: c.root,
+    proxy: c.proxy,
   }
 }
 
 function describeResolved(d) {
   return {
     dataDir: d.dataDir,
-    dbDir: d.dbDir,
     dbFile: d.dbFile,
-    localDir: d.localDir,
     envFile: d.envFile,
     tagPluginsDir: d.tagPluginsDir,
-    dockerBind: d.dockerBind,
-    dockerPort: d.dockerPort,
+    localDir: d.localDir,
     image: d.image,
     container: d.container,
+    proxy: d.proxy,
     base: d.base,
   }
 }
@@ -470,7 +461,7 @@ async function describeConfig(ctx, config) {
     platform: process.platform,
     home: os.homedir(),
     defaultDataDir: defaultDataDir(),
-    defaultArtifactDir: defaultArtifactDir(),
+    defaultProxy: proxyOf({}),
     resolved: describeResolved(s.docker),
     artifact: describeArtifact(s.artifact),
     artifactState: await artifactStatus(s.artifact),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-horon",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "Horon memory graph as a DeepSeek Harness plugin: the horon tool, lifecycle hooks, the console panel and a one-click service runtime (released artifact or Docker image)",
   "type": "module",
   "license": "MIT",
@@ -23,6 +23,7 @@
     "client.js",
     "docker.js",
     "artifact.js",
+    "paths.js",
     "horon_web_app.py",
     "horon.lock.json",
     "cordis.patch.yml",

package/paths.js

@@ -0,0 +1,60 @@
+// Where everything Horon-related lives, for both runtimes.
+//
+// One path decides all of it: `dataDir`, by default ~/.horon. The database, the key file, the
+// unpacked releases and the tag plugins are all derived from it, so a user only ever answers
+// "where do I keep this" once. Docker mode mounts the same directory into the container at /data,
+// which is what makes switching runtimes keep the memory.
+
+import { existsSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+/** The public release proxy used when downloading from GitHub by default. */
+export const DEFAULT_PROXY = 'https://gh-proxy.com'
+
+export function expandHome(value) {
+  return value === '~' || /^~[\\/]/.test(value) ? path.join(os.homedir(), value.slice(1)) : value
+}
+
+export function defaultDataDir() {
+  return path.join(os.homedir(), '.horon')
+}
+
+const text = (value) => (typeof value === 'string' && value.trim() ? value.trim() : undefined)
+
+/** The configured data directory, absolute. */
+export function resolveDataDir(config) {
+  const given = text(config?.dataDir)
+  return given === undefined ? defaultDataDir() : path.resolve(expandHome(given))
+}
+
+/**
+ * The key/value file (API keys, proxies).
+ *
+ * `<root>/.env` is the documented location. An older layout kept it in `<root>/docker/.env`;
+ * that file is still read when the new one does not exist, so upgrading does not lose the keys.
+ */
+export function envFileFor(root) {
+  const current = path.join(root, '.env')
+  if (existsSync(current)) return current
+  const legacy = path.join(root, 'docker', '.env')
+  return existsSync(legacy) ? legacy : current
+}
+
+export const dbFileFor = (root) => path.join(root, 'horon.db')
+export const runtimeDirFor = (root) => path.join(root, 'runtime')
+export const tagPluginsDirFor = (root) => path.join(root, 'tag_plugins')
+export const localDirFor = (root) => path.join(root, 'local')
+
+/** Download proxy: empty means a direct connection. */
+export function proxyOf(config) {
+  const given = config?.proxy
+  if (given === null) return ''
+  return typeof given === 'string' ? given.trim() : DEFAULT_PROXY
+}
+
+/** Prefix a URL with the proxy: https://gh-proxy.com/https://github.com/... */
+export function proxied(url, proxy) {
+  const base = String(proxy ?? '').trim().replace(/\/+$/, '')
+  return base === '' ? url : `${base}/${url}`
+}