@cjhyy/code-shell-server

@cjhyy/code-shell-server

CodeShell 服务端传输与管理服务（纯 Node、零 Electron）：mobile remote 的 HTTP/WS host、配对、passcode 门、tunnel、rooms、上传，供 Desktop Web 与 Hub 共用的配置/会话/文件/Link 服务，以及 个人 Hub Web host（code-shell-serve）。

完整的原生 Node.js 安装、模型配置、管理员初始化、systemd 后台运行、HTTPS 和备份步骤见 服务端部署指南。

聚焦入口

宿主代码应选择职责最窄的稳定入口：

入口	职责
@cjhyy/code-shell-server/storage	磁盘 Session、附件暂存、图片探测和稳定 client-message ID
@cjhyy/code-shell-server/worker	与传输无关的 stdio worker 生命周期和行协议桥接
@cjhyy/code-shell-server/auth	独立服务可复用的单 owner HTTP 初始化、登录及会话撤销
@cjhyy/code-shell-server/remote-relay	设备出站 WSS 连接器、固定回环目标、受限二进制字节流与 v1 协议
@cjhyy/code-shell-server/mobile-remote	配对、访问门禁、rooms、上传、LAN/tunnel host 和移动端协议类型
@cjhyy/code-shell-server/serve	Headless HTTP/WebSocket host 与 code-shell-serve CLI 组合默认值
@cjhyy/code-shell-server/desktop-web	设备配对换 Cookie、已知 Workspace 校验与共享管理 HTTP API
@cjhyy/code-shell-server/links	Link 目录、连接管理、设备授权及受限 HTTP handler

import { listDiskSessions } from "@cjhyy/code-shell-server/storage";
import { RemoteHostManager } from "@cjhyy/code-shell-server/mobile-remote";
import { WorkerBridgeCore } from "@cjhyy/code-shell-server/worker";

包根入口保留 storage、worker、mobile-remote、serve 和 desktop-web 的兼容导出； Link 和独立服务认证分别使用 /links、/auth 入口。新消费方应避免根入口，以免只使用 storage 或 transport 时也求值无关的宿主组合。

/storage、/worker 和 /mobile-remote 没有 Coding/Web 静态导入。外部 Agent 策略由产品宿主通过 ResidentAgentOptions.appendSystemPrompt 注入。 /serve 则是有意保留的开箱即用产品入口：CLI 被调用时解析 Coding stdio worker 和已构建的 Web app。

电脑出站中继使用 /remote-relay。先以 mode: "relay" 启动已配置访问口令的 RemoteHostManager，再把 host.relayTarget() 交给连接器；该能力在 Host 停止时立即 撤销，不能继续暴露复用原端口的其他服务。协议、生命周期和真实网络测试范围见 设备中继说明。桌面登记设置和物理手机验收仍是后续工作。

MobileUploadService.revokeDevice(deviceId) 同步禁止该设备的新票据和领取操作， 中止尚未被任务认领的上传，并返回可等待的临时文件清理结果。RemoteHostManager 的同名方法会调用它、报告异步清理错误；stop() 会等待清理完成。已被任务认领的 附件保留至原持有者 finalize 或 release；撤销后的 release 不会重新开放票据。 自定义 uploads 适配器也必须实现这项设备级撤销。其他设备的上传不受影响。

独立服务的单 owner 认证

/auth 直接复用 Hub 的认证实现，运行时仅导出 createHubAuth 和 HUB_SESSION_COOKIE，同时提供 HubAuth、HubAuthOptions、HubSession 类型。 它不会创建 HTTP listener、Worker、项目或设备中继，也不提供多租户身份体系。

宿主通过 createHubAuth({ dataDir, publicOrigin, onRevoke }) 创建认证服务，先将请求 交给 auth.handle(request, response) 处理现有 /api/v1/auth/* 端点。其他受保护 路由必须同时检查 auth.isOriginAllowed(request) 和 await auth.authenticate(request)； 认证成功本身不授予文件、工具或手机配对权限。

publicOrigin 是部署者配置的可信根 Origin，公网必须使用 HTTPS，不能从请求的 转发头推导。dataDir 保存单 owner 账号和会话；首次返回的 bootstrapToken 应交给 管理员私密保存，不能记录到公共日志。onRevoke(sessionId) 用于同步撤销宿主持有的 连接，长期连接还应重新检查会话有效性；Cookie/令牌只能用于本服务。 多个独立认证服务应使用不同主机名和数据目录；Cookie 不按端口隔离，只更换监听 端口不能隔离浏览器登录。

HubAuth.store 保留原有返回类型，供宿主检查活动会话；本入口不额外导出 store 构造器或令牌解析工具。bun run test:package-release 会从实际 tarball 的公开入口 检查严格 NodeNext 类型，并用原生 Node HTTP 验证初始化、登录、Origin、撤销和重载。

两种宿主，共用浏览器工作台

packages/web/app/Workbench.tsx 组合对话、模型、Skills、MCP、历史、文件及 Link 页面。 Hub 的 App / useHubController 提供管理员认证后的状态与操作；Desktop 的 DesktopApp 使用原有 useRemoteApp 和设备协议，驱动原来的 Desktop Worker。 Desktop Web 不会创建第二个 Hub Worker，也不需要再建 Hub 管理员。

createDesktopWebApi 将配对设备换成短期 HttpOnly Cookie，用于同一套受限 HTTP 管理服务。宿主注入已知 Workspace 解析、运行门禁和热更新回调；业务服务复用 hub/ 与 /links 实现。Electron 原生 renderer 仍使用原来的 IPC。 具体文件与环境差异见 共享 Web 工作台。

Desktop Web 和 Hub 在注销或显式撤销会话时，会关闭该会话尚未完成的受保护 HTTP 响应，包括正在下载的文件，并停止源文件读取、释放句柄。其他会话的下载不受影响； 已经返回接受结果的后台任务仍由原来的任务生命周期管理。注销请求本身仍返回成功。

code-shell-serve — 个人 Hub Web host

在任意机器上把一个 workspace 变成浏览器可访问的 CodeShell：

# 构建（repo 内，先按部署指南安装依赖）
bun run build:server

# 启动
node packages/server/dist/bin/code-shell-serve.js \
  --cwd ~/work/my-repo \
  --port 8790 \
  --data-dir ~/codeshell-data

首次启动会打印带 #setup= 的管理员初始化链接。创建管理员后，可在 Web「设置 → 模型与连接」添加连接并选择默认模型，也可以预先准备 Workspace 的 .code-shell/settings.local.json。没有可用模型时 HTTP 健康检查和配置界面仍可使用，对话需要先完成模型配置。

当前 Web 工作台提供：

• 对话、Markdown/代码/表格、模型提供的思考内容、工具结果、子任务、附件、审批与停止；刷新时恢复已保存历史和有界的当前运行事件。
• 会话搜索、重命名、归档/恢复、Markdown/JSON 导出；Workspace 文件列表、文本/图片预览和认证下载。
• 模型连接增删改、默认/辅助模型选择和真实连接测试；项目 Skills 增删改、启停、GitHub 预览安装/更新；MCP 配置、启停、工具权限和临时连接探测。
• 独立 Link 页面：token 验证连接、重命名/断开、绑定宿主已登录 CLI，以及配置了应用 client ID 的 GitHub/GitLab 设备授权。
• 单管理员登录、设备撤销、手机布局和 PWA 页面外壳。

浏览器可以连接远端 Hub；Desktop 开启的 Web 可访问桌面已知项目，独立 Hub 固定一个 Workspace。Electron 原生窗口的远端执行目标、Hub 多 Workspace、团队账号隔离、插件市场和远程 Panel Host 仍属后续范围。

架构

浏览器 SPA（packages/web dist-app）
   │  HTTP /api/v1/* + WS /ws（管理员 Session Cookie 与 Origin 校验）
headless serve（本包 serve/）
   │  stdio line-JSON-RPC（WorkerBridgeCore：按需 spawn、崩溃记账）
agent-server-stdio worker（Core 入口 + Coding 能力包）

• 浏览器使用受限的 Core 协议投影：serve 自己处理会话列表/详情，只允许向 worker 转发 agent/run、agent/approve、agent/cancel，并在转发前校验 Workspace 与 Session 归属。配置通过专用认证 HTTP 接口修改；任意配置 RPC 和 Workspace 切换不对 Web 开放。
• 每个 tab 的请求 ID 会在 host 内重写，响应只回到发起 tab；agent/streamEvent 等通知才广播给所有已认证 tab，避免多 tab 使用相同本地 ID 时串包。
• 默认使用 Hub 单管理员初始化、登录与可撤销 Session Cookie；--auth passcode 保留旧共享口令模式。当前只支持单用户、单 Workspace。
• 默认只绑 127.0.0.1；远端可用 SSH 转发或 HTTPS 反向代理。HTTPS 部署需通过 --public-url 或对应环境变量配置实际公开 Origin，不能只改监听地址。
• 会话持久在 serve 独占的 Worker data root（默认 <data-dir>/worker）；重启后可恢复列表与已保存历史，不会自动继续被中断的任务。活动运行缓冲有上限，超过后明确退回持久历史。
• Server 与 Desktop 复用 Core 引擎、SettingsManager、Skills 管理及会话数据逻辑；共享的 web 库负责浏览器可用的消息投影。工具、MCP 和 Skill 脚本在服务端执行。桌面窗口、钥匙串、IPC 和 Panel Host 不随 Web 部署迁移。

Hub HTTP 接口分组

这些是当前 Web 使用的受限接口，不是多租户 Gateway。除初始化、登录及健康检查等公开入口外，要求有效管理员登录；浏览器请求还受 Origin 校验。

路径	用途
/api/v1/auth/*	初始化、登录/退出、登录状态及 /sessions 设备管理
/api/v1/uploads/:browserId	当前登录 Session 所属的受限附件暂存
/api/v1/configuration/*	模型连接、默认值和配置摘要
/api/v1/skills/*	项目 Skill 管理与 GitHub 安装/更新
/api/v1/mcp/*	MCP 配置、继承、启停和连接探测
/api/v1/sessions/*	Workspace 内会话查询、标题、归档与导出
/api/v1/files/*	Workspace 内文件列表、预览和下载
/api/v1/links/*	Link 连接、CLI 状态/绑定及设备授权

审批快照、设备 lease 和运行流通过 /ws 协议交换。配置写入 Workspace 本地层，任务运行期间拒绝修改（409），空闲保存后通过 Core 热更新用于下一次任务。列表和详情不返回已保存的模型密钥或 MCP 敏感值。模型测试会发送一次可能计费的请求；MCP 测试只连接及列工具，stdio 测试会启动配置的程序。完整的功能边界与限额见部署指南。

Link 新连接写入宿主用户级 CredentialStore，不会放入模型配置的 credentials[]。 Web 只绑定已经登录的 CLI，不接受任意命令或启动交互式登录。token 与设备授权在验证后保存， 写入前重新检查发起者和连接版本；注销、设备撤销及关闭服务取消未完成操作。 断开绕过运行忙碌门禁，以便 Core 凭证订阅取消活跃 LinkAction。 当前 Link OAuth 过期需重新授权，没有自动续期或云端 Link Server；多设备共用一个宿主用户的连接。

CLI 参数

参数	默认	说明
--cwd	当前目录	worker 的 workspace 根
--port	8790	监听端口
--host	127.0.0.1	监听地址
--auth	hub	hub 管理员认证或 passcode 旧模式
--public-url	根据监听地址生成	浏览器实际访问的根 Origin，也可用 CODE_SHELL_SERVE_PUBLIC_URL；非 loopback 要求 HTTPS
--passcode	旧模式下自动生成	显式传入会默认选择 passcode 模式，不能与 --auth hub 同用
--data-dir	~/.code-shell/serve	认证数据与隔离 Worker 数据根；设置 CODE_SHELL_HOME 时默认改为其下的 serve
--static-root	自动解析 web dist-app	覆盖静态资源目录
--debug-logs	关闭	包含可能带任务正文的 Worker 诊断，仅写入私有日志

Web 客户端开发

先运行本地 Hub（后端默认 8790），再启动 Vite。开发时把 Hub 的公开 Origin 设为实际 Vite 地址，例如 --public-url http://127.0.0.1:5173；Vite 代理 /api 和 /ws 到 127.0.0.1:8790。浏览器始终使用该 Vite Origin 登录和访问：

bun run --cwd packages/web dev:app --host 127.0.0.1 --port 5173 --strictPort

Docker 部署到其他机器见 Docker 部署说明。默认宿主机端口为 8791，可与原生 Node.js 服务并行。

更新 Hub 后需重建并重启服务。Desktop Web 的入口构建到 packages/desktop/out/mobile， 还依赖新的主进程 HTTP 接线，因此必须重新构建 Desktop 并重启应用；只更新 Hub 的 dist-app 或刷新旧桌面的浏览器页面不会完成升级。

The focused /remote-relay entry also exposes environmentIdentity(dataDir) so desktop enrollment uses the same stable identity as its Web descriptor. It is not added to the root entry. DeviceRelayState includes terminal unauthorized for TLS-verified 401/403 control handshakes; temporary failures continue reconnecting.