桔子会话（Juzi Session）
DSH 的 outbound agent 远程会话插件。工具前缀 juzi_*。
目标：被控端（Windows / Linux）主动出站连接 DSH，由 DSH 生成一次性配对链接、自动登记机器并下发命令；后续增加交互终端（PTY）和文件传输。
下载
- 最新 Release
- Windows：
remote-agent-windows-amd64.exe - Linux：
remote-agent-linux-amd64
工具路由
先看 远程类插件怎么选。本插件只管理 juzi_hosts 里的 outbound agent，不是 Server Deck SSH，也不是 dsh-remote。
为什么
- 目标机经常没有 sshd / WinRM，或不允许开系统服务
- 家宽 CGNAT，无法依赖入站端口
- 希望像 browser-skill 一样：被控端主动连出，DSH 侧统一管理
状态
| 阶段 | 内容 | 状态 |
|---|---|---|
| P0 | 出站连接 + 机器台账 + juzi_exec |
Linux 验收通过 |
| P0.5 | 配对链接 / 自动注册 / 180 天凭证 / 插件明暗主题 | Linux 验收通过 |
| P0.5-Win | 托盘 + 本地设置 UI + Windows 服务 | 已交叉编译，待 Windows 实机验收 |
| P1 | 审计、续期细节、更多设备管理 | 未开始 |
| P2 | 交互终端（ConPTY / pty） | 未开始 |
| P3 | 文件传输（单文件上传/下载、2 并发 + 4 排队） | 阶段 1 已实现，续传恢复/本地 UI 收尾中 |
目标架构
Windows / Linux 目标机
└─ remote-agent（Go 单文件）
│ 出站 WebSocket（配对 / 设备凭证 + 心跳 + 重连）
▼
DSH 插件「桔子会话」监听 0.0.0.0:47777
├─ /api/remote-shell/agent 配对、注册、心跳、命令
├─ 机器台账（设备凭证只存 SHA-256）
├─ 工具：juzi_hosts / juzi_exec / juzi_session_*
└─ 设置页：生成一次性链接、自动列表、撤销、明暗跟随 DSH
配对流程
- 在 DSH 插件页「配对地址」里添加多个入口：名称 + 前缀（不添加则自动使用 LAN 地址）
- 点「生成连接链接」，得到一次性链接（5 分钟有效，secret 在
#fragment 中）：
wss://agent6.potatooo.top:777/api/remote-shell/agent#
前缀建议指向 Lucky / Cloudflare 的公网入口；插件实际监听仍是内部的 47777。
- 在目标机运行：
remote-agent --pair 'ws://192.168.5.8:47777/api/remote-shell/agent#'
- agent 首次连接后自动登记，并保存 180 天设备凭证
- 之后直接运行
remote-agent即可用凭证重连，不再需要链接
DSH 侧不再需要“先创建机器”。
Windows Agent
单文件 remote-agent.exe，默认托盘模式：
# 单机托盘 + 本地设置页
.\remote-agent.exe
# 安装/解除 Windows 服务（需管理员）
.\remote-agent.exe service install
.\remote-agent.exe service uninstall
- GUI 子系统，双击不弹控制台窗口；只有托盘图标
- 托盘菜单：打开设置 / 重连 / 开机启动 / 安装服务 / 解除服务 / 退出
- 开机启动写当前用户
HKCU\...\Run，登录后启动托盘，不需要管理员 - 本地设置页可修改上报的设备名称，保存后自动重连
- 本地设置页可清除配对凭证 / 恢复默认配置
- 支持「以管理员身份重启」（按需 UAC，不强制开机弹窗）
- 单实例保护：重复双击不会开第二个 agent
- 关闭浏览器设置页不会退出；托盘继续运行
- CLI 命令（service install 等）会自动附加到父控制台
- 本地设置页端口：
49777–49796自动避让，仅绑127.0.0.1 - 服务模式：LocalSystem、自动启动、失败重启；无托盘/窗口
- 设置页跟随 Windows 系统明暗
Linux Agent
保留 headless 二进制，不做 GUI/服务安装器：
./remote-agent-linux-amd64 --pair 'ws://192.168.5.8:47777/api/remote-shell/agent#'
Linux 其他机器优先建议 SSH；agent 只用于没有 sshd / NAT 后的边缘场景。
目录
agent/ Go agent（Linux headless + Windows tray/service）
plugin/ DSH 插件 bundle
docs/ 计划、验收、Windows 说明
连续执行与权限
- Windows
cmd输出按 OEM 代码页兜底解码；中文命令字面量和文件编码仍建议用 PowerShell juzi_exec是一次性命令：每次新 shell，cd/ 变量不跨命令，没有交互 stdin- 需要连续状态时用
juzi_session_*：持久 shell，每条命令仍返回 exit code / stdout / stderr / cwd - 真正的交互终端（xterm / ConPTY）仍未实现，agent 不需要读终端屏幕
- Windows 上当前 agent 若以普通权限启动，UAC 过滤后是 Medium；需要管理员请安装为服务（LocalSystem）或以管理员身份启动
- UAC 不能静默绕过；无人值守优先用服务模式
异步任务
长任务用 juzi_job_*，不阻塞 DSH 工具调用；Web 设置页有独立「任务」卡片。详见 异步任务。
Windows 验证
见 Windows 实机验证清单。
签名
Windows 二进制当前未签名，SmartScreen/Defender 可能提示。可选方案见 Windows 二进制签名。
安全
- agent 仅以运行它的用户权限执行命令，不提供提权
- 配对 secret 只存 SHA-256；一次性、5 分钟
- 设备凭证 180 天，插件侧只存哈希；撤销后立即断开
- 插件 agent 端口默认
0.0.0.0:47777，仅 token 保护；不要直接映射公网 - 文件传输不做路径白名单；默认上传目录为 Downloads，服务模式为 ProgramData，Linux 服务为
~/.local/share/juzi/downloads；默认不覆盖
许可
上游 agent 为 MIT，派生代码必须保留版权声明。详见 docs/ATTRIBUTION.md。
本仓库自身许可待定。
