Probe Architecture

Probe 探针架构设计

草案 — 代码库尚无 Probe 实现。跟踪 Issue #43。

把数字生命的手伸向你授权的地方——不搬家，不挪窝，只是多了一双手。

核心理念

脑在逸灵风，手在外面。

逸灵风（部署主机）是完整的运行时——意识、记忆、身份、推理、工具系统。它不被移植、不被拆分、不被动摇。

Probe 是一个轻量代理，部署在你指定的机器上（本地电脑、远程服务器等），与逸灵风建立加密连接，作为 Agent 的「远程手」。

你在 WebUI Studio 里对话，Agent 在逸灵风上思考，通过 Probe 在目标机器上执行操作。

你的浏览器                    逸灵风（脑）                      目标机器（手）
┌──────────────┐   WebUI   ┌────────────────────┐ 加密隧道  ┌──────────────┐
│ Studio       │ ←───────→ │ Agent（LLM+记忆）  │ ←───────→ │ Probe Agent  │
│ 对话 + 展示  │           │ + 工具系统          │  WS/wss   │ - 文件读写   │
│ + diff 预览  │           │ + Probe 路由        │           │ - 命令执行   │
└──────────────┘           │ + 授权网关          │           │ - git 操作   │
                           └────────────────────┘           │ - 项目索引   │
                                                             │ - 代码分析   │
                                                             └──────────────┘

为什么不是反向 Remote

VS Code Remote：本地 UI + 远端执行（手在远端） Cursor：本地 UI + 云端 AI（脑在云端，手在本地）

Probe 是另一种对称：

脑固定在逸灵风（身份/记忆的连续性）
手可伸缩到任意授权机器（灵活性）

逸灵风是锚点，不是工具。锚点不动，手可以伸很远。

场景

场景一：分析伙伴本地项目

伙伴（如张三）在本地机器装 Probe，在 WebUI 说「帮我看一下那个项目的模块依赖」，Probe 读取文件树和 import 关系发回逸灵风，Agent 分析后展示结果。

场景二：维护远程服务器

Probe 部署在某台服务器上，Agent 直接检查日志、查配置、定位问题，不需要伙伴 SSH 进去再口述。

场景三：结对编程任何地方

Probe 指向任意代码目录，Agent 读代码、提建议、生成 diff，伙伴审阅后 apply。全程一个浏览器搞定。

Probe Agent 设计

极轻

目标：单文件 Go 二进制或 Python 单脚本，零依赖。

功能：

与逸灵风建立 WebSocket 加密连接（wss）
接受指令并执行（白名单约束）
返回结果（文件内容、命令输出、diff 等）
心跳保活

安全模型

三层授权：

层	机制	说明
连接层	TLS + Token	Probe 启动时生成一次性 Token，与逸灵风握手验证
路径层	白名单	可配置允许读/写的路径范围，越界拒绝
操作层	每步确认	写操作、删除操作默认需伙伴在 WebUI 点击确认

默认安全策略：

只读模式（默认）——可读文件，不可写
写模式需伙伴在 Studio 中显式授权
Probe 不持久化任何数据，全部透传
连接断开自动销毁 Token

指令集（v1）

文件类：
  read <path>          读取文件内容
  read_tree <path>     读取目录结构（深度可配）
  grep <pattern>       文本搜索
  stat <path>          文件元信息

代码类：
  git_diff <path>      查看工作区变更
  git_log <path>       查看提交历史
  ast_parse <path>     解析代码结构（函数/类/导入）

执行类：
  run <command>        执行命令（需授权）
  run_background      后台运行（用于启动服务等）

系统类：
  ping                 心跳
  info                 系统信息

不做的（v1 范围外）

不代理想法——Probe 不做任何决策，只执行指令返回结果
不存状态——Probe 不记录任何历史，每次连接是干净的
不主动推送——Probe 只响应指令，不主动上报（除非心跳断开重连）
不搞复杂协议——JSON over WebSocket，简单到用手都能拼

逸灵风端改动

需要在逸灵风中新增：

Probe 路由——管理多路 Probe 连接（可能同时在多台机器装 Probe）
授权网关——处理伙伴的确认/拒绝操作
会话上下文——将 Probe 操作结果注入到当前对话的上下文中，让 Agent 能「看到」远程文件

Studio WebUI 改动

Probe 的操作结果以结构化的方式展示在 Studio 面板：

┌─────────────────────────────────────────┐
│ 💬 我：帮我看一下 server.ts 第20行附近    │
│                                          │
│ 📁 Probe → 张三-笔记本                   │
│   读 /projects/server/server.ts:18-25    │
│                                          │
│ ```typescript                            │
│ 18: function handleConnection(ws) {      │
│ ...                                      │
│ ```                                      │
│                                          │
│ Agent：这里缺错误处理。要改吗？            │
│                                          │
│ ┌───────┐ ┌───────┐                     │
│ │ 改    │ │ 跳过  │                     │
│ └───────┘ └───────┘                     │
└─────────────────────────────────────────┘

实现优先级

Phase 0：概念验证 — Probe 在本地跑，连逸灵风，读文件返回
Phase 1：基础可用 — 文件读写 + grep + git_diff，WebUI 展示结果
Phase 2：多路 + 安全 — 多 Probe 管理、授权确认、白名单配置
Phase 3：代码智能 — ast_parse、重构建议、自动 diff 生成

开放问题

Probe 首次连接如何安全配对？（扫描二维码？一次性链接？）
多台机器时，WebUI 如何切换目标？（Probe 选择器）
读大文件时如何分页/流式传输？
需要让 Probe 支持 NAT 穿透吗？还是假设可直连？

状态：草案