本地服务面板 kjx-talesofai/dsh-plugin-localhost

dsh-plugin-localhost

一个面板，回答「这台机器上现在跑着什么、在哪个目录、哪个会话开的、怎么关掉」。

智能体在开发里起服务是常态：pnpm dev、python -m http.server、一个 dist/ 静态页。它们都是临时的，但不会自己消失——三个小时后你没死，那个端口也没死。这个插件把「起服务」变成一次登记，于是端口不用猜、目录不会丢、关掉有地方点。

它做什么

两种东西，都归它管；第三种它老实承认管不了。

| 类型 | 谁在跑 | 生命周期 |
| 静态页 | 插件自己（127.0.0.1 上的一个小服务器） | 跟着 DSH 一起关 |
| 命令 | 插件通过 Harness 的 subprocess 服务启动 | 插件停它就停，DSH 退出时全部停 |
| 别的进程 | 智能体自己用 bash 起的 | 不在这里。杀不掉的进程不该显示成「运行中」 |

这不是洁癖。后台进程如果没人拥有，它就会活过它该活的时间——见 docs/plan.md 里那四个活了十一天的东西。

装

github:kjx-talesofai/dsh-plugin-localhost#v0.4.0

装完重启桌面端（host 半边只在启动时加载）。

智能体怎么用

给智能体的是一个工具 serve，不是一堆 bash：

{ "action": "register", "kind": "spawned", "name": "preview",
"dir": "/path/to/project", "cmd": "pnpm dev --port $PORT",
"path": "/" }

{ "action": "register", "kind": "static", "name": "deck",
"dir": "/path/to/dist" }

返回里带 port 和 url。端口是插件分的（8840–8899），不是智能体挑的——所以「这个工作区开过哪些服务」这个问题有答案，而不是靠回忆。

其他动作：list / start / stop / remove / logs。logs 返回最近的输出，排错不用截图；remove 删掉登记并把进程停掉，别再去手改 services.json（改了也会被读回来，见下）。

想让它下次开机自己起来，注册时带上 "autoStart": true，或者之后在面板上点那颗「自动启动」。

面板

侧边栏里，紧挨在 Tailscale Remote Access 下面。每行：状态点、名字、类型、端口、状态。展开后有：

- 目录 —— 点「用 Finder 打开」
- 入口文件（静态页）—— 点「显示入口文件」，Finder 里直接选中它
- 登记会话 —— 点「跳到会话」，回到当初开它的那个对话
- 日志 —— 最近 400 行，运行中会自己滚

行上的按钮：打开 / 启动 / 停止 / 自动启动 / 收起。展开后最下面有「移除」——点一次问、点两次删，删之前先把进程停掉。

登记表就是文件。 ~/.dsh/localhost/services.json 是唯一的事实来源，内存只是它的镜像：手工删掉一行，面板下一次读就跟着没了，而且不会被下一次保存写回来。v0.3.0 及以前反过来——内存说了算，删掉的行会复活，只能重启。

老实说（边界）

- 只登记它自己起的。智能体用 bash 起的服务，这个面板看不见——它杀不掉，就不能声称拥有。
- DSH 退出 = 全部停止。重启后条目显示「已停止」，需要手动点启动；只有你显式标了「自动启动」的才会自己起来，默认不标。
- 自动启动失败不会拖垮 DSH。端口被别人占了、目录被删了，都只在那一行上写原因（红点 + 一行说明），别的服务照常起。
- 端口是分给它的，所以别在别的脚本里硬编码 8840。想要固定端口就在 cmd 里自己用 $PORT。
- 静态页由它自己发，不是复制文件：dir 改了立刻生效，dir 删了就 404。
- 只在 127.0.0.1 上。这个端口没有认证，不要以为它是个「分享」按钮；要给别人看，走 Tailscale。
- 从手机打开：面板会读 tailscale serve status，把已经发布到 tailnet 的端口配上远端地址；此时「打开」在你的手机浏览器里打开那个地址，而不是让 Mac 弹浏览器。没发布的端口在手机上不给「打开」按钮，并明说只在本机可访问。
- 静态页的 SPA 回退只对浏览器导航生效（Accept: text/html），这样 /etc/hosts 这类路径不会假装成路由。

Compatibility

实测于 macOS（Apple Silicon）+ DSH Desktop 0.2.1-rc.2。依赖的上游契约：

| 契约 | 来自 |
| webServer.register({ kind: 'exact', path })，以及 connection.admit(req) 的准入栅栏 | dsh-host-webserver、dsh-api-remotes |
| subprocess.spawn 的句柄、collected.*.readFrom(offset)、terminate()，以及服务销毁时杀掉所有在管进程 | dsh-subprocess-local |
| ctx.tools.register 的 ToolDefinition（parameters 里 required 写在字段内） | dsh-tools |
| sidebar.panellist / main 两个槽位，order 决定导航顺序 | dsh-client-ui-sidebar、dsh-client-ui-layout |
| locale.bind(ns) 支持 {name} 插值 | dsh-client-locale |
| uiWorkspace.openSession(id) 接受裸 session id | dsh-client-ui-workspace |

开发

npm test # 45 条，不需要安装任何依赖
Host 半边没有运行时依赖，所以测试真的 import 它，用假 ctx 驱动：静态服务走真实 socket，spawned 走假 subprocess，断言的是 spawn 规格，而不是「看起来跑了」。Client 半边按页面加载的方式在 node:vm 里求值，再用一个迷你 hooks 运行时把面板渲染出来断言。

没有构建步骤：client.js 就是发布物。

它做什么

两类东西，都归插件管；第三类它不假装能管：

| 类型 | 谁运行 | 生命周期 |
| static | 本插件（一个小的 127.0.0.1 服务） | 随 DSH 停止 |
| command | 本插件，经由 Harness subprocess 服务 | 收到请求时停止，DSH 退出时也停止 |
| 其他 | 智能体，用 bash | 不在此列出。杀不掉的进程，不能显示成「运行中」。 |

智能体只拿到一个工具 serve，不用再堆一堆 bash：注册一个目录或一条启动命令，就能拿回分配的端口和 URL。端口取自 8840–8899，由插件分配，智能体从不手写——正因如此，「我在这儿起了什么」这个问题才有答案。

面板位于 Tailscale Remote Access 之下：状态、名称、类型、端口，外加一个开关。展开一行，可以看到目录（在 Finder 中显示）、入口文件、注册它的会话（跳回去），以及日志尾部。

实话实说的限制

- 只列出它自己启动的东西。智能体用 bash 起的服务看不见——也杀不掉——所以不显示。
- DSH 退出会停掉一切；重启后每条记录都显示为已停止，没有任何东西会自动重启。
- 静态页面直接从所在目录提供，不复制；端口不做鉴权，且只监听回环地址。
- SPA 回退只对浏览器导航生效（Accept: text/html），所以文件缺失时仍然是 404。

开发

npm test # 45 tests, no install step

Host 半边没有运行时依赖，所以测试套件直接 import 它，驱动一个假上下文：静态服务走真实 socket，spawned 路径走假的 ctx.subprocess。Client 半边在 node:vm 里作为脚本求值，再通过一个迷你 hooks 运行时渲染。

许可证

MIT © 2026 Jiaxin Kou