docs: 重写架构文档——工程级完整版(5 张 Mermaid 图 + 功能状态总表)

原文停在 2026-07-02 已严重失真:能力矩阵还写「多租户/RBAC 未动、真实计费
未做、NATS 集群未做」,而这三项均已完成并 live 验证。它又被 5 份设计文档
引用为配套文档,不能放着不管。

重写为 15 章 913 行,以代码为单一事实源:
- 分层架构图 + 3 张关键链路时序图(任务提交/语音全双工/本地执行三道闸)
  + 三机部署拓扑图,全部 Mermaid(已用 mermaid-cli 逐张渲染验证)
- 5 个服务逐个拆:internal 包职责 + 技术栈依赖表含版本
- NATS 契约总表:1 任务流 + 3 回流 + 4 组工具 RPC + 5 条持久回写流 + KV
- 编排引擎:12 种节点 kind、ReAct、11 个平台工具、harness 五件套
- 29 张表全清单 + 9 个中间件 + 迁移机制
- 13 域功能实现状态总表(✅/🟡/❌)
- 安全治理/可观测/客户端三产品面/CI-CD/技术栈速查/已知缺口

顺带记账:§9.14 点名 4 处文档与代码不符(PROGRESS.md 停更、DEPTH_ROADMAP
汇总表自相矛盾、Tier3 说 NATS 集群没做但已落地、PAYMENT_DESIGN 说不做订阅
但已实现),明确以代码为准,避免后来人被误导。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

sundynix-admin/nginx.conf

@@ -1,4 +1,14 @@
 # 运维控制台静态托管 + 反代网关 API（一个 URL 同时给前端与 /api）。
+
+# WebSocket 升级：nginx 默认会吃掉 Upgrade/Connection 头，被代理的 WS 永远握手不成功
+# （现象：HTTP 接口全好，只有 WS 报 ws error）。语音会话 /api/v1/voice/stream 与
+# 本地执行器 /api/v1/local/runner 都走 WS，必须显式转发。
+# 用 map 而非写死 "upgrade"：普通请求带上 Connection: upgrade 会干扰 keepalive。
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
 server {
     listen 80;
     server_name _;
@@ -17,6 +27,9 @@ server {
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        # WebSocket（语音会话 / 本地执行器）：不转发这两个头则握手必失败。
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
         # SSE（token 流 / 执行轨迹）：关闭缓冲 + 长超时，否则流式会被攒住/断开。
         proxy_buffering off;
         proxy_cache off;

sundynix-desktop/frontend/bindings/github.com/sundynix/sundynix-desktop/app.ts

@@ -12,6 +12,13 @@
 // @ts-ignore: Unused imports
 import { Call as $Call, CancellablePromise as $CancellablePromise, Create as $Create } from "@wailsio/runtime";
 
+/**
+ * DefaultLocalDirs 返回建议授权的常用目录（桌面/下载/文档），供设置界面一键填入。
+ */
+export function DefaultLocalDirs(): $CancellablePromise<string> {
+    return $Call.ByID(2376992125);
+}
+
 /**
  * LocalExecEnabled 供前端显示开关状态。
  */
@@ -66,11 +73,11 @@ export function SetLocalExecEnabled(on: boolean): $CancellablePromise<void> {
 }
 
 /**
- * StartLocalRunner 开启本地文件访问：以 workdir 为沙箱根连接 gateway 注册执行器。
+ * StartLocalRunner 开启本地访问：dirs 是换行分隔的授权目录列表（沙箱白名单）。
  * 幂等：重复调用先停旧连接。断线自动重连（5s 退避）直到 StopLocalRunner。
  */
-export function StartLocalRunner(gatewayURL: string, token: string, workdir: string): $CancellablePromise<void> {
+export function StartLocalRunner(gatewayURL: string, token: string, dirs: string): $CancellablePromise<void> {
-    return $Call.ByID(2808780368, gatewayURL, token, workdir);
+    return $Call.ByID(2808780368, gatewayURL, token, dirs);
 }
 
 /**

sundynix-desktop/frontend/src/lib/api.ts

@@ -1,9 +1,42 @@
 // Gateway HTTP/SSE 客户端：提交 DSL 任务、订阅 Token 流、登记偏好记忆。
 import type { TaskDsl } from "./dsl";
 
-// 开发期直连 Gateway；Wails 打包后可改为本地后端地址或经 Go 绑定。
+// 服务器地址：**运行时可配**（登录页可填），优先级 localStorage > 构建期 VITE_GATEWAY > 本地默认。
-export const GATEWAY: string =
+// 做成运行时而非只在构建期写死，是因为同一个 App 要能在「本地全栈」和「线上服务器」之间随时切，
-  (import.meta.env.VITE_GATEWAY as string | undefined) ?? "http://localhost:8080";
+// 每换一次环境就重编一次客户端不现实。改完需重载窗口（模块级常量，40+ 处调用点靠它读同一份值）。
+const GATEWAY_KEY = "sdx_gateway";
+
+function initialGateway(): string {
+  try {
+    const saved = localStorage.getItem(GATEWAY_KEY);
+    if (saved) return saved.replace(/\/+$/, ""); // 去掉尾斜杠，否则拼出 //api/v1 这种路径
+  } catch {
+    /* 隐私模式忽略 */
+  }
+  return (import.meta.env.VITE_GATEWAY as string | undefined) ?? "http://localhost:8080";
+}
+
+export const GATEWAY: string = initialGateway();
+
+// setGatewayURL 保存服务器地址（空串=清除，回落构建期默认）。调用方保存后应重载窗口使其生效。
+export function setGatewayURL(url: string): void {
+  try {
+    const v = url.trim().replace(/\/+$/, "");
+    if (v) localStorage.setItem(GATEWAY_KEY, v);
+    else localStorage.removeItem(GATEWAY_KEY);
+  } catch {
+    /* ignore */
+  }
+}
+
+// customGatewayURL 返回用户自定义的地址（没设过则空串），供设置界面回显。
+export function customGatewayURL(): string {
+  try {
+    return localStorage.getItem(GATEWAY_KEY) ?? "";
+  } catch {
+    return "";
+  }
+}
 
 export interface Identity {
   userId: string;

sundynix-desktop/frontend/src/lib/desktop.ts

@@ -33,10 +33,16 @@ export function localRunnerAvailable(): boolean {
   return inWails();
 }
 
-// startLocalRunner：以 workdir 为沙箱根开启本地文件访问（Go host 连 gateway 注册执行器）。
+// startLocalRunner：以 dirs（换行分隔的多个目录）为沙箱白名单开启本地访问。
-export async function startLocalRunner(gatewayURL: string, token: string, workdir: string): Promise<void> {
+export async function startLocalRunner(gatewayURL: string, token: string, dirs: string): Promise<void> {
-  if (!inWails()) throw new Error("本地文件访问仅桌面端可用");
+  if (!inWails()) throw new Error("本地访问仅桌面端可用");
-  await App.StartLocalRunner(gatewayURL, token, workdir);
+  await App.StartLocalRunner(gatewayURL, token, dirs);
+}
+
+// defaultLocalDirs：桌面/下载/文档的绝对路径（换行分隔），供一键填入。
+export async function defaultLocalDirs(): Promise<string> {
+  if (!inWails()) return "";
+  return App.DefaultLocalDirs();
 }
 
 export function stopLocalRunner(): void {

sundynix-desktop/frontend/src/lib/voice.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { micTapAction, nextAfterDrain, shouldSendMic, type VoiceState } from "./voice";
+import { nextAfterDrain, shouldSendMic, type VoiceState } from "./voice";
 
 // 连续对话的纯决策函数：状态门控 / 播完去向 / 点按语义。
 // VoiceClient 本体依赖 WebSocket/AudioContext（jsdom 难直测），决策逻辑抽纯函数在这测。
@@ -27,22 +27,3 @@ describe("nextAfterDrain 播完去向", () => {
   });
 });
 
-describe("micTapAction 点按语义（对话开关）", () => {
-  it("聆听中点 → 退出对话", () => {
-    expect(micTapAction("listening", true)).toBe("stop");
-    expect(micTapAction("listening", false)).toBe("stop");
-  });
-
-  it("朗读中点（对话里）→ 打断但留在对话", () => {
-    expect(micTapAction("speaking", true)).toBe("interrupt");
-  });
-
-  it("朗读中点（非对话）→ 开始对话（startConversation 内部先打断）", () => {
-    expect(micTapAction("speaking", false)).toBe("start");
-  });
-
-  it.each<VoiceState>(["idle", "ready", "connecting", "thinking"])("%s 态点 → 开始对话", (s) => {
-    expect(micTapAction(s, false)).toBe("start");
-    expect(micTapAction(s, true)).toBe("start");
-  });
-});

sundynix-desktop/frontend/src/lib/voice.ts

@@ -34,15 +34,6 @@ export function nextAfterDrain(conversation: boolean): VoiceState {
   return conversation ? "listening" : "ready";
 }
 
-// micTapAction：点按麦克风的语义（对话开关）。
-// 聆听中点 → 退出对话；朗读中点（在对话里）→ 打断但留在对话；其余 → 开始对话。
-export type MicTapAction = "start" | "stop" | "interrupt";
-export function micTapAction(state: VoiceState, inConversation: boolean): MicTapAction {
-  if (state === "listening") return "stop";
-  if (state === "speaking" && inConversation) return "interrupt";
-  return "start";
-}
-
 // 健壮性定时器时长（仅对话模式生效）
 const IDLE_EXIT_MS = 30_000; // 聆听空转：30s 无任何转写 → 自动退出对话（防 ASR 长连接白烧计费）
 const THINK_WATCHDOG_MS = 90_000; // 思考看门狗：final 后 90s 没等到朗读 → 回聆听继续对话
@@ -156,7 +147,7 @@ export class VoiceClient {
           if (m.final) {
             this.clearIdleTimer();
             this.setState("thinking");
-            if (this.conversation) this.armThinkTimer(); // 看门狗：任务失败/无 TTS 也能回到聆听
+            this.armThinkTimer(); // 看门狗:后端不回/任务失败/无 TTS 时别永远卡在"思考中"
           } else if (this.conversation && this.state === "listening") {
             this.armIdleTimer(); // 有声音活动 → 空转计时重来
           }
@@ -350,12 +341,17 @@ export class VoiceClient {
     this.clearThinkTimer();
     this.thinkTimer = window.setTimeout(() => {
       this.thinkTimer = null;
-      if (this.conversation && this.state === "thinking") {
+      if (this.state !== "thinking") return;
+      if (this.conversation) {
         this.cb.onError?.("等回答超时，继续聆听");
         this.send({ type: "start" });
         this.cb.onTurnStart?.();
         this.setState("listening");
         this.armIdleTimer();
+      } else {
+        // PTT:回待命并说清可能原因,别让用户对着"思考中"干等。
+        this.cb.onError?.("等了很久没有回答——可能后端任务没跑起来(dispatcher/模型未就绪)。去运行页看看这条任务的状态。");
+        this.setState("ready");
       }
     }, THINK_WATCHDOG_MS);
   }

sundynix-desktop/frontend/src/shell/JarvisHud.tsx

@@ -13,7 +13,9 @@ interface Props {
   transcript: string;
   reply: string;
   hint: string;
-  onMic: () => void;
+  // 按住说话（与语音坞/空格键同一套 PTT 语义）：按下开始听、松开发送。
+  onPttDown: () => void;
+  onPttUp: () => void;
   onClose: () => void;
 }
 
@@ -30,7 +32,7 @@ const CONF: Record<VoiceState, Conf> = {
 };
 const GLYPH = "ABCDEFGHJKLMNPQRSTUVWXYZ0123456789#%@*<>/\\";
 
-export function JarvisHud({ name, state, getLevel, transcript, reply, hint, onMic, onClose }: Props) {
+export function JarvisHud({ name, state, getLevel, transcript, reply, hint, onPttDown, onPttUp, onClose }: Props) {
   const canvasRef = useRef<HTMLCanvasElement>(null);
   const decRef = useRef<HTMLSpanElement>(null);
   const sigRef = useRef<HTMLElement>(null);
@@ -210,7 +212,15 @@ export function JarvisHud({ name, state, getLevel, transcript, reply, hint, onMi
         <X className="h-4 w-4" /> ESC
       </button>
 
-      <button className="jhud-core" onClick={onMic} aria-label={hint} title={hint} />
+      <button
+        className="jhud-core"
+        onPointerDown={(e) => { e.preventDefault(); onPttDown(); }}
+        onPointerUp={onPttUp}
+        onPointerLeave={onPttUp}
+        onPointerCancel={onPttUp}
+        aria-label={hint}
+        title={hint}
+      />
       <div className={"jhud-word" + (amber ? " amber" : state === "listening" ? " live" : "")}>{hint}</div>
 
       <div className="jhud-decode">

sundynix-desktop/frontend/src/shell/JarvisSettings.tsx

@@ -1,9 +1,10 @@
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { Dialog } from "../ui/Dialog";
 import { Button } from "../ui/Button";
 import { useToast } from "../ui/Toast";
 import { getMyJarvis, saveMyJarvis, type JarvisConfig, GATEWAY, getToken } from "../lib/api";
 import {
+  defaultLocalDirs,
   localExecEnabled,
   localRunnerAvailable,
   localRunnerStatus,
@@ -14,19 +15,31 @@ import {
 
 // 每用户 JARVIS 设置：名字 / 人设 / （高级）自带豆包配置。
 // 名字与人设归用户自己；豆包配置齐全则语音走用户的账号，否则走系统兜底。
-export function JarvisSettings({ open, onClose }: { open: boolean; onClose: () => void }) {
+export function JarvisSettings({
+  open,
+  onClose,
+  onSaved,
+}: {
+  open: boolean;
+  onClose: () => void;
+  onSaved?: () => void; // 保存成功后通知外层刷新（名字要立刻反映到语音坞/HUD，否则看不出生效）
+}) {
   const toast = useToast();
   const [cfg, setCfg] = useState<JarvisConfig | null>(null);
+  const toastRef = useRef(toast); // effect 里用 ref 取最新 toast，避免它进依赖
+  toastRef.current = toast;
   const [saving, setSaving] = useState(false);
   const [advanced, setAdvanced] = useState(false);
 
+  // 只在"打开"时拉一次。toast 不能进依赖——它一变就会重拉配置、把用户正在填的内容覆盖掉。
   useEffect(() => {
     if (!open) return;
     setCfg(null);
     getMyJarvis()
       .then(setCfg)
-      .catch((e) => toast.push("error", (e as Error).message));
+      .catch((e) => toastRef.current.push("error", (e as Error).message));
-  }, [open, toast]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open]);
 
   const set = (k: keyof JarvisConfig, v: string) => setCfg((c) => (c ? { ...c, [k]: v } : c));
 
@@ -42,7 +55,8 @@ export function JarvisSettings({ open, onClose }: { open: boolean; onClose: () =
         tts_resource_id: cfg.tts_resource_id,
         tts_voice_type: cfg.tts_voice_type,
       });
-      toast.push("success", "已保存，下次说话即生效");
+      toast.push("success", `已保存：${cfg.name.trim() || "JARVIS"} · 下次说话即生效`);
+      onSaved?.();
       onClose();
     } catch (e) {
       toast.push("error", (e as Error).message);
@@ -71,6 +85,15 @@ export function JarvisSettings({ open, onClose }: { open: boolean; onClose: () =
         <div className="text-slate-500">加载中…</div>
       ) : (
         <div className="space-y-4">
+          <div className="rounded-md border border-line bg-ink-900/50 px-3 py-2 text-[11px] leading-relaxed text-slate-500">
+            当前生效：助手名 <b className="text-slate-300">{cfg.name.trim() || "JARVIS"}</b>
+            {" · "}人设 <b className="text-slate-300">{cfg.persona.trim() ? "已自定义" : "默认平和"}</b>
+            {" · "}语音走 <b className="text-slate-300">{cfg.has_own_voice ? "你自己的豆包配置" : "系统配置"}</b>
+            <span className="mt-0.5 block">
+              验证是否生效：保存后按住空格问一句「你是谁」，它会用这个名字自称。
+            </span>
+          </div>
+
           <label className="block">
             <span className="text-xs text-slate-400">助手名字</span>
             <input
@@ -155,10 +178,10 @@ function LocalAccessSection() {
         stopLocalRunner();
         setStatus("offline");
       } else {
-        if (!dir.trim()) throw new Error("先填一个允许 JARVIS 访问的本地目录（绝对路径）");
+        if (!dir.trim()) throw new Error("至少填一个允许 JARVIS 访问的目录（绝对路径，每行一个）");
         await startLocalRunner(GATEWAY, getToken(), dir.trim());
         setStatus("connecting");
-        toast.push("success", "本地文件访问已开启（只读，锁定在该目录内）");
+        toast.push("success", "本地访问已开启（仅限授权目录）");
       }
     } catch (e) {
       toast.push("error", (e as Error).message);
@@ -170,24 +193,39 @@ function LocalAccessSection() {
   return (
     <div className="space-y-2 rounded-md border border-line bg-ink-900/50 p-3">
       <div className="flex items-center justify-between">
-        <span className="text-xs text-slate-400">本地文件访问（试验 · 只读）</span>
+        <span className="text-xs text-slate-400">本地访问（授权目录）</span>
         <span className={online ? "text-[11px] text-emerald-400" : "text-[11px] text-slate-500"}>
           {online ? "已开启" : status === "connecting" ? "连接中…" : "未开启"}
         </span>
       </div>
       <p className="text-[11px] leading-relaxed text-slate-500">
-        开启后 JARVIS 能<b>查看/读取</b>下面这个目录里的文件（仅此目录，不能写、不能执行命令）。
+        JARVIS 只能在你授权的这些目录里活动（其余一律拒绝）。开启后可以说
-        对话里可以说“看看我工作目录里有什么”。
+        “看看我桌面上有什么”“把下载里的图片整理一下”。默认只读；要让它动手改文件、跑命令，
+        还得单独打开下面那个开关。
       </p>
       {online ? (
-        <p className="break-all font-mono text-[11px] text-slate-400">{status.slice("online:".length)}</p>
+        <div className="space-y-0.5">
+          {status.slice("online:".length).split("\n").filter(Boolean).map((d) => (
+            <p key={d} className="break-all font-mono text-[11px] text-slate-400">· {d}</p>
+          ))}
+        </div>
       ) : (
-        <input
+        <>
-          className="w-full rounded-md border border-line bg-ink-850 px-3 py-1.5 font-mono text-sm text-slate-100 focus:border-brand focus:outline-none"
+          <textarea
-          value={dir}
+            rows={3}
-          onChange={(e) => setDir(e.target.value)}
+            className="w-full resize-none rounded-md border border-line bg-ink-850 px-3 py-1.5 font-mono text-xs text-slate-100 focus:border-brand focus:outline-none"
-          placeholder="/Users/你/Documents/某个目录"
+            value={dir}
-        />
+            onChange={(e) => setDir(e.target.value)}
+            placeholder={"每行一个目录（绝对路径），例：\n/Users/你/Desktop\n/Users/你/Downloads"}
+          />
+          <button
+            type="button"
+            className="text-[11px] text-brand-400 transition hover:underline"
+            onClick={() => void defaultLocalDirs().then((d) => d && setDir(d))}
+          >
+            + 填入常用目录（桌面 / 下载 / 文档）
+          </button>
+        </>
       )}
       <Button variant={online ? "ghost" : "secondary"} size="sm" onClick={onToggle} disabled={busy}>
         {online || status === "connecting" ? "关闭本地访问" : "开启本地访问"}

sundynix-desktop/frontend/src/shell/VoiceDock.tsx

@@ -1,13 +1,14 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { ExternalLink, Loader2, Mic, MicOff, Settings2, Maximize2, Volume2, X } from "lucide-react";
-import { VoiceClient, micTapAction, type VoiceState } from "../lib/voice";
+import { VoiceClient, type VoiceState } from "../lib/voice";
 import { JarvisSettings } from "./JarvisSettings";
 import { JarvisHud } from "./JarvisHud";
 import { getMyJarvis } from "../lib/api";
 import { useToast } from "../ui/Toast";
 import { cn } from "../ui/cn";
 
-// JARVIS 语音坞：右下角悬浮麦克风，连续对话模式（点一次进对话，VAD 自动断句、答完自动重听）。
+// JARVIS 语音坞：右下角悬浮麦克风。**按住说话、松开发送(PTT)**——按住空格或按住按钮均可。
+// VAD 自动断句在真实环境不够稳(环境音/停顿误触发)，故不再默认进连续对话模式。
 // 气泡是「迷你对话流」——保留最近几轮，旧轮淡化，新轮追加（不清屏丢上下文）。
 // onTask 不再每轮强制跳运行页（连续对话会被拽走）：任务收进对话流里的芯片，点击才跳。
 
@@ -30,18 +31,18 @@ const KEEP_TURNS = 3; // 对话流保留最近几轮（含当前轮）
 // pttActive 时显示"松开发送"替代默认聆听提示。
 function hintText(state: VoiceState, name: string, idleLeft: number | null, ptt?: boolean): string {
   if (idleLeft !== null) return `${idleLeft}s 后自动退出 · 说话取消`;
-  if (ptt && state === "listening") return "按住说话中 · 松开发送";
+  if (ptt) return "正在听 · 松开发送";
   switch (state) {
     case "connecting":
       return "连接中…";
     case "listening":
-      return "聆听中 · 说完自动发送 · 点击退出";
+      return "聆听中…";
     case "thinking":
       return `${name} 正在思考`;
     case "speaking":
       return "朗读中 · 点击打断";
     default:
-      return "点击开始对话 · 空格键按住说话";
+      return "按住空格 或 按住这里说话";
   }
 }
 
@@ -107,12 +108,14 @@ export function VoiceDock({ onTask, onNavigate }: Props) {
   const onNavigateRef = useRef(onNavigate);
   onNavigateRef.current = onNavigate;
 
-  // 助手名：挂载即拉一次（未登录/失败保持默认）。
+  // 助手名：挂载即拉一次（未登录/失败保持默认）。设置里保存后也会调它重拉——
-  useEffect(() => {
+  // 否则改完名字这里还挂着旧的，用户根本看不出配置生效了没。
+  const refreshName = useCallback(() => {
     getMyJarvis()
       .then((j) => setName(j.name || "JARVIS"))
       .catch(() => {});
   }, []);
+  useEffect(refreshName, [refreshName]);
 
   // 懒建客户端（首次点按时，带上用户手势→AudioContext 才能启动）。
   const ensureClient = useCallback((): VoiceClient => {
@@ -185,7 +188,8 @@ export function VoiceDock({ onTask, onNavigate }: Props) {
     return () => window.removeEventListener("keydown", onKey);
   }, [fullscreen]);
 
-  // PTT：按住空格语音输入，松开发送（不在对话模式时生效）。
+  // PTT：按住空格说话，松开发送——**这是默认且主要的交互方式**。
+  // VAD 自动断句在真实环境里不够稳（环境音/停顿都会误触发），所以不再自动进连续对话。
   useEffect(() => {
     const onKeyDown = (e: KeyboardEvent) => {
       if (e.key !== " " && e.code !== "Space") return;
@@ -193,9 +197,14 @@ export function VoiceDock({ onTask, onNavigate }: Props) {
       const tag = (e.target as HTMLElement).tagName;
       if (tag === "INPUT" || tag === "TEXTAREA" || (e.target as HTMLElement).isContentEditable) return;
       e.preventDefault();
+      if (e.repeat) return; // 按住不放会连发 keydown，只认第一次
 
-      const c = clientRef.current;
+      // 关键：懒建客户端。此前这里是 `if (!c) return`——用户没先点过麦克风按钮时
-      if (!c || c.inConversation() || c.getState() === "listening") return;
+      // clientRef 为 null，按空格**什么都不会发生**（PTT 形同虚设）。
+      // keydown 本身就是用户手势，可以合法启动 AudioContext。
+      const c = ensureClient();
+      if (pttRef.current || c.getState() === "listening") return;
+      if (c.inConversation()) c.stopConversation(); // 如果之前进了连续对话，PTT 优先，先退出
 
       pttRef.current = true;
       setPttActive(true);
@@ -238,30 +247,37 @@ export function VoiceDock({ onTask, onNavigate }: Props) {
         if (c && c.getState() === "listening") c.stopPTT();
       }
     };
-  }, [toast]);
+  }, [ensureClient, toast]);
 
-  // 点按语义 = 对话开关：待命点 → 进入连续对话；聆听中点 → 退出；朗读中点 → 打断但留在对话。
+  // 麦克风按钮 = 按住说话（与空格键同义）。按下开始听、松开发送——
-  const onMic = useCallback(async () => {
+  // 和 PTT 统一，别让按钮和空格键两套语义打架。
+  const pttDown = useCallback(() => {
     const c = ensureClient();
-    try {
+    if (pttRef.current || c.getState() === "listening") return;
-      switch (micTapAction(state, c.inConversation())) {
+    if (c.inConversation()) c.stopConversation();
-        case "stop":
+    pttRef.current = true;
-          c.stopConversation();
+    setPttActive(true);
-          break;
+    setOpen(true);
-        case "interrupt":
+    c.startListening().catch((err: unknown) => {
-          c.interruptAndListen();
+      pttRef.current = false;
-          break;
+      setPttActive(false);
-        case "start":
+      toast.push("error", (err as Error).message || "麦克风启动失败（检查权限）");
-          setOpen(true); // 清屏交给 onTurnStart（startConversation 里触发）
+    });
-          await c.startConversation();
+  }, [ensureClient, toast]);
-          break;
+
-      }
+  const pttUp = useCallback(() => {
-    } catch (e) {
+    if (!pttRef.current) return;
-      toast.push("error", (e as Error).message || "麦克风启动失败（检查权限）");
+    pttRef.current = false;
-    } finally {
+    setPttActive(false);
-      setConv(clientRef.current?.inConversation() ?? false);
+    const c = clientRef.current;
-    }
+    if (c && c.getState() === "listening") c.stopPTT();
-  }, [ensureClient, state, toast]);
+  }, []);
+
+  // 朗读中点一下 = 打断（此时不进入录音，只是掐掉 TTS）。
+  const onInterrupt = useCallback(() => {
+    const c = clientRef.current;
+    if (c && c.getState() === "speaking") c.bargeIn();
+  }, []);
 
   // 进全屏 JARVIS 模式：建好客户端（HUD 读实时电平），刷一次助手名。
   const openFullscreen = useCallback(() => {
@@ -275,7 +291,8 @@ export function VoiceDock({ onTask, onNavigate }: Props) {
   const busy = state === "connecting";
   const hint = hintText(state, name, idleLeft, pttActive);
   const visibleTurns = turns.filter((t) => t.me || t.ai || t.taskId);
-  const ringDur = conv ? RING_DUR[state] : undefined;
+  // 呼吸环:PTT 录音中、思考中、朗读中都亮(只变节奏);待命时熄灭。
+  const ringDur = pttActive ? RING_DUR.listening : RING_DUR[state];
   // 倒计时环：SVG 周长 182.2（r=29），剩余秒数映射到 dashoffset（收缩）。
   const cdOffset = idleLeft !== null ? (182.2 * (10 - idleLeft)) / 10 : 0;
 
@@ -351,25 +368,38 @@ export function VoiceDock({ onTask, onNavigate }: Props) {
 
       {/* 电平/静默指示 + 麦克风按钮 */}
       <div className="pointer-events-auto flex items-center gap-2.5">
-        {conv && (state === "listening" || state === "speaking") && (
+        {(pttActive || state === "speaking") && (
           <VuBars getLevel={() => clientRef.current?.level() ?? 0} active />
         )}
-        {conv && state === "thinking" && (
+        {state === "thinking" && (
           <span className="flex items-center gap-1 rounded-full bg-ink-900/80 px-2.5 py-1 text-[10px] text-slate-400">
             <MicOff className="h-3 w-3" />
-            麦克风已静默
+            已停止收音
           </span>
         )}
         <button
-          onClick={onMic}
+          // 按住说话：pointer 事件覆盖鼠标/触控/触控笔；朗读中按一下则是打断。
+          onPointerDown={(e) => {
+            e.preventDefault();
+            if (state === "speaking") {
+              onInterrupt();
+              return;
+            }
+            pttDown();
+          }}
+          onPointerUp={pttUp}
+          onPointerLeave={pttUp} // 按住时指针滑出按钮也算松开，别卡在录音态
+          onPointerCancel={pttUp}
           title={hint}
           aria-label={hint}
           className={cn(
-            "relative flex h-14 w-14 items-center justify-center rounded-full shadow-xl transition",
+            "relative flex h-14 w-14 select-none items-center justify-center rounded-full shadow-xl transition",
             "focus:outline-none focus-visible:ring-2 focus-visible:ring-brand/60",
-            conv && state === "thinking"
+            pttActive
-              ? "bg-ink-800 text-accent-400"
+              ? "scale-95 bg-danger text-white" // 录音中：红 + 缩，一眼可见"正在听"
-              : "bg-brand text-white hover:bg-brand-500 active:scale-95",
+              : state === "thinking"
+                ? "bg-ink-800 text-accent-400"
+                : "bg-brand text-white hover:bg-brand-500",
           )}
         >
           {/* 呼吸环：对话进行中常亮（三种状态只变节奏）——环在=点击是退出/打断，环灭=点击是开始 */}
@@ -411,7 +441,7 @@ export function VoiceDock({ onTask, onNavigate }: Props) {
         {hint}
       </span>
     </div>
-    <JarvisSettings open={settingsOpen} onClose={() => setSettingsOpen(false)} />
+    <JarvisSettings open={settingsOpen} onClose={() => setSettingsOpen(false)} onSaved={refreshName} />
     {fullscreen && (
       <JarvisHud
         name={name}
@@ -420,7 +450,8 @@ export function VoiceDock({ onTask, onNavigate }: Props) {
         transcript={visibleTurns[visibleTurns.length - 1]?.me ?? ""}
         reply={visibleTurns[visibleTurns.length - 1]?.ai ?? ""}
         hint={hint}
-        onMic={onMic}
+        onPttDown={pttDown}
+        onPttUp={pttUp}
         onClose={() => setFullscreen(false)}
       />
     )}

sundynix-desktop/frontend/src/ui/Toast.tsx

@@ -1,4 +1,4 @@
-import { createContext, useCallback, useContext, useRef, useState, type ReactNode } from "react";
+import { createContext, useCallback, useContext, useMemo, useRef, useState, type ReactNode } from "react";
 import { CheckCircle2, AlertTriangle, Info, X } from "lucide-react";
 import { cn } from "./cn";
 
@@ -39,8 +39,13 @@ export function ToastProvider({ children }: { children: ReactNode }) {
 
   const dismiss = (id: number) => setToasts((t) => t.filter((x) => x.id !== id));
 
+  // 必须 useMemo：`value={{ push }}` 每次渲染都造新对象，凡是把 useToast() 结果放进
+  // useEffect 依赖的组件（有 7 处）都会在**任意一条 toast 弹出时**重跑 effect。
+  // JarvisSettings 因此边填边被重新拉取覆盖；拉取失败还会 push 错误 toast → 无限循环狂闪。
+  const value = useMemo(() => ({ push }), [push]);
+
   return (
-    <Ctx.Provider value={{ push }}>
+    <Ctx.Provider value={value}>
       {children}
       <div className="pointer-events-none fixed bottom-4 right-4 z-50 flex w-80 flex-col gap-2">
         {toasts.map((t) => {

sundynix-desktop/frontend/src/views/Login.tsx

@@ -1,6 +1,6 @@
 import { useState } from "react";
 import { LogIn, UserPlus, Loader2 } from "lucide-react";
-import { authLogin, authRegister, type AuthUser } from "../lib/api";
+import { authLogin, authRegister, customGatewayURL, setGatewayURL, GATEWAY, type AuthUser } from "../lib/api";
 import { Button, Input, Field } from "../ui";
 
 // Login：未登录时的全屏鉴权门。登录/注册成功后回调 onAuthed 把用户交给 App。
@@ -66,7 +66,49 @@ export function Login({ onAuthed }: { onAuthed: (u: AuthUser) => void }) {
             {isRegister ? "去登录" : "去注册"}
           </button>
         </div>
+
+        <ServerField />
       </div>
     </div>
   );
 }
+
+// ServerField 服务器地址设置：默认折叠，展开后可指向线上后端或本地全栈。
+// 放在登录页是因为它必须在登录之前可改——地址不对就连不上、更谈不上登录。
+function ServerField() {
+  const [open, setOpen] = useState(false);
+  const [url, setUrl] = useState(customGatewayURL());
+  const [saved, setSaved] = useState(false);
+
+  const save = () => {
+    setGatewayURL(url);
+    setSaved(true);
+    // 模块级常量在加载时读定，改完必须重载窗口才生效——直接替用户重载，省得他困惑为何没变。
+    setTimeout(() => window.location.reload(), 400);
+  };
+
+  return (
+    <div className="mt-4 border-t border-line pt-3">
+      <button className="text-[11px] text-slate-500 transition hover:text-slate-300" onClick={() => setOpen((v) => !v)}>
+        {open ? "▾" : "▸"} 服务器地址
+        <span className="ml-1 text-slate-600">{GATEWAY}</span>
+      </button>
+      {open && (
+        <div className="mt-2 space-y-2">
+          <Input
+            value={url}
+            onChange={(e) => setUrl(e.target.value)}
+            placeholder="https://agent.sundynix.cn"
+            onKeyDown={(e) => e.key === "Enter" && save()}
+          />
+          <div className="flex items-center gap-2">
+            <Button size="sm" onClick={save} disabled={saved}>
+              {saved ? "已保存，重载中…" : "保存并重载"}
+            </Button>
+            <span className="text-[11px] text-slate-600">留空 = 用默认</span>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

sundynix-desktop/localexec.go

@@ -131,7 +131,7 @@ func askApproval(title, detail string) bool {
 }
 
 // execWrite 写文件（沙箱内 + 审批）。
-func execWrite(root string, req *runnerReq) *runnerResp {
+func execWrite(roots []string, req *runnerReq) *runnerResp {
 	fail := func(m string) *runnerResp { return &runnerResp{ID: req.ID, OK: false, Error: m} }
 	if !execAllowed() {
 		return fail("用户未开启「允许执行命令与写文件」。请如实告知用户需要在 JARVIS 设置里打开。")
@@ -141,7 +141,7 @@ func execWrite(root string, req *runnerReq) *runnerResp {
 	if strings.TrimSpace(rel) == "" {
 		return fail("缺少文件路径")
 	}
-	p, err := resolveInRoot(root, rel)
+	p, err := resolveAllowed(roots, rel)
 	if err != nil {
 		return fail(err.Error())
 	}
@@ -162,7 +162,7 @@ func execWrite(root string, req *runnerReq) *runnerResp {
 }
 
 // execCommand 在沙箱工作目录里跑一条命令（黑名单 + 审批 + 超时 + 输出截断）。
-func execCommand(root string, req *runnerReq) *runnerResp {
+func execCommand(roots []string, req *runnerReq) *runnerResp {
 	fail := func(m string) *runnerResp { return &runnerResp{ID: req.ID, OK: false, Error: m} }
 	if !execAllowed() {
 		return fail("用户未开启「允许执行命令与写文件」。请如实告知用户需要在 JARVIS 设置里打开。")
@@ -175,14 +175,26 @@ func execCommand(root string, req *runnerReq) *runnerResp {
 	if reason := checkDenied(cmdStr); reason != "" {
 		return fail(reason) // 硬拒：连审批框都不弹
 	}
-	if !askApproval("JARVIS 想在你的电脑上执行命令", "工作目录："+root+"\n\n命令：\n"+cmdStr) {
+	cwd := ""
+	if len(roots) > 0 {
+		cwd = roots[0]
+	}
+	// 模型可指定在哪个授权目录里跑（不给就用第一个）；越界目录直接拒。
+	if d, _ := req.Args["cwd"].(string); strings.TrimSpace(d) != "" {
+		resolved, rerr := resolveAllowed(roots, d)
+		if rerr != nil {
+			return fail(rerr.Error())
+		}
+		cwd = resolved
+	}
+	if !askApproval("JARVIS 想在你的电脑上执行命令", "工作目录："+cwd+"\n\n命令：\n"+cmdStr) {
 		return fail("用户拒绝了这次执行。")
 	}
 
 	ctx, cancel := context.WithTimeout(context.Background(), execTimeout)
 	defer cancel()
 	c := exec.CommandContext(ctx, "/bin/sh", "-c", cmdStr)
-	c.Dir = root // 工作目录锁在沙箱根
+	c.Dir = cwd // 工作目录锁在授权目录内
 	out, err := c.CombinedOutput()
 	text := string(out)
 	if len(text) > execMaxOutput {

sundynix-desktop/localexec_test.go

@@ -62,10 +62,10 @@ func TestExecDeniedWhenSwitchOff(t *testing.T) {
 	gate.mu.Unlock()
 
 	root := t.TempDir()
-	if r := execCommand(root, &runnerReq{ID: "1", Tool: "local_exec", Args: map[string]any{"command": "ls"}}); r.OK {
+	if r := execCommand([]string{root}, &runnerReq{ID: "1", Tool: "local_exec", Args: map[string]any{"command": "ls"}}); r.OK {
 		t.Fatal("开关关闭时命令仍被执行")
 	}
-	if r := execWrite(root, &runnerReq{ID: "2", Tool: "local_write_file", Args: map[string]any{"path": "x.txt", "content": "y"}}); r.OK {
+	if r := execWrite([]string{root}, &runnerReq{ID: "2", Tool: "local_write_file", Args: map[string]any{"path": "x.txt", "content": "y"}}); r.OK {
 		t.Fatal("开关关闭时写入仍被执行")
 	}
 }
@@ -82,7 +82,7 @@ func TestDenylistPrecedesApproval(t *testing.T) {
 		gate.mu.Unlock()
 	}()
 
-	r := execCommand(t.TempDir(), &runnerReq{ID: "1", Tool: "local_exec", Args: map[string]any{"command": "sudo rm -rf /"}})
+	r := execCommand([]string{t.TempDir()}, &runnerReq{ID: "1", Tool: "local_exec", Args: map[string]any{"command": "sudo rm -rf /"}})
 	if r.OK {
 		t.Fatal("黑名单命令未被拒绝")
 	}

sundynix-desktop/localrunner.go

@@ -16,11 +16,12 @@ import (
 
 // 本地执行 runner（JARVIS「本地的手」，LOCAL_AGENT_DESIGN 档 A / JARVIS_BRAIN_DESIGN P4）：
 // 桌面端 Go host 连 gateway 的 /api/v1/local/runner WS，把自己注册成本用户的本地执行器；
-// 服务端把 local_* 工具调用转发过来，这里在**用户自选工作目录的沙箱内**执行并回结果。
+// 服务端把 local_* 工具调用转发过来，这里在**用户授权目录的沙箱内**执行并回结果。
 //
-// 安全铁律（P1 只读起步）：
+// 安全铁律：
-//   - 只实现 list_dir / read_file，无写无 exec；
+//   - 多目录白名单：用户授权哪些目录（桌面/下载/文档/项目…），就只能动这些目录，其余一律拒；
-//   - 一切路径锁死在用户显式选择的 workdir 根下（清洗 + 软链解析后前缀校验，越界即拒）；
+//   - 防逃逸靠软链解析后前缀校验（软链指向白名单外也拒）；
+//   - 写文件/执行命令另有独立开关 + 硬黑名单 + 逐次原生确认框（见 localexec.go）；
 //   - 用户不点"开启"，runner 永不连接——本地访问是显式授权，不是默认能力。
 
 type runnerReq struct {
@@ -39,37 +40,69 @@ type runnerResp struct {
 
 // LocalRunner 管一条 runner 连接的生命周期（App 持有单例）。
 type LocalRunner struct {
-	mu      sync.Mutex
+	mu     sync.Mutex
-	cancel  context.CancelFunc
+	cancel context.CancelFunc
-	workdir string
+	roots  []string // 已授权目录白名单（绝对路径）
-	status  string // offline / connecting / online
+	status string   // offline / connecting / online
 }
 
-// StartLocalRunner 开启本地文件访问：以 workdir 为沙箱根连接 gateway 注册执行器。
+// StartLocalRunner 开启本地访问：dirs 是换行分隔的授权目录列表（沙箱白名单）。
 // 幂等：重复调用先停旧连接。断线自动重连（5s 退避）直到 StopLocalRunner。
-func (a *App) StartLocalRunner(gatewayURL, token, workdir string) error {
+func (a *App) StartLocalRunner(gatewayURL, token, dirs string) error {
-	abs, err := filepath.Abs(strings.TrimSpace(workdir))
+	var roots []string
-	if err != nil {
+	for _, line := range strings.Split(dirs, "\n") {
-		return fmt.Errorf("工作目录无效: %w", err)
+		d := strings.TrimSpace(line)
+		if d == "" {
+			continue
+		}
+		if d == "~" || strings.HasPrefix(d, "~/") {
+			if home, err := os.UserHomeDir(); err == nil {
+				d = filepath.Join(home, strings.TrimPrefix(strings.TrimPrefix(d, "~"), "/"))
+			}
+		}
+		abs, err := filepath.Abs(d)
+		if err != nil {
+			return fmt.Errorf("目录无效: %s", d)
+		}
+		if fi, err := os.Stat(abs); err != nil || !fi.IsDir() {
+			return fmt.Errorf("目录不存在或不是目录: %s", abs)
+		}
+		roots = append(roots, abs)
 	}
-	if fi, err := os.Stat(abs); err != nil || !fi.IsDir() {
+	if len(roots) == 0 {
-		return fmt.Errorf("工作目录不存在或不是目录: %s", abs)
+		return fmt.Errorf("至少要授权一个目录")
 	}
 	a.runner.stop()
 
 	ctx, cancel := context.WithCancel(context.Background())
 	a.runner.mu.Lock()
 	a.runner.cancel = cancel
-	a.runner.workdir = abs
+	a.runner.roots = roots
 	a.runner.status = "connecting"
 	a.runner.mu.Unlock()
 
 	wsURL := strings.Replace(strings.TrimRight(gatewayURL, "/"), "http", "ws", 1) +
 		"/api/v1/local/runner?token=" + token
-	go a.runner.loop(ctx, wsURL, abs)
+	go a.runner.loop(ctx, wsURL, roots)
 	return nil
 }
 
+// DefaultLocalDirs 返回建议授权的常用目录（桌面/下载/文档），供设置界面一键填入。
+func (a *App) DefaultLocalDirs() string {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return ""
+	}
+	var out []string
+	for _, name := range []string{"Desktop", "Downloads", "Documents"} {
+		p := filepath.Join(home, name)
+		if fi, err := os.Stat(p); err == nil && fi.IsDir() {
+			out = append(out, p)
+		}
+	}
+	return strings.Join(out, "\n")
+}
+
 // StopLocalRunner 关闭本地文件访问（幂等）。
 func (a *App) StopLocalRunner() { a.runner.stop() }
 
@@ -78,7 +111,7 @@ func (a *App) LocalRunnerStatus() string {
 	a.runner.mu.Lock()
 	defer a.runner.mu.Unlock()
 	if a.runner.status == "online" {
-		return "online:" + a.runner.workdir
+		return "online:" + strings.Join(a.runner.roots, "\n")
 	}
 	return a.runner.status
 }
@@ -100,9 +133,9 @@ func (r *LocalRunner) setStatus(s string) {
 }
 
 // loop 连接→服务→断线重连（5s 退避），直到 ctx 取消。
-func (r *LocalRunner) loop(ctx context.Context, wsURL, root string) {
+func (r *LocalRunner) loop(ctx context.Context, wsURL string, roots []string) {
 	for {
-		if err := r.serve(ctx, wsURL, root); err != nil && ctx.Err() == nil {
+		if err := r.serve(ctx, wsURL, roots); err != nil && ctx.Err() == nil {
 			r.setStatus("connecting")
 		}
 		select {
@@ -115,7 +148,7 @@ func (r *LocalRunner) loop(ctx context.Context, wsURL, root string) {
 }
 
 // serve 一条连接的会话：发 hello → 循环收请求、沙箱内执行、回结果。
-func (r *LocalRunner) serve(ctx context.Context, wsURL, root string) error {
+func (r *LocalRunner) serve(ctx context.Context, wsURL string, roots []string) error {
 	dctx, dcancel := context.WithTimeout(ctx, 10*time.Second)
 	conn, _, err := websocket.Dial(dctx, wsURL, nil)
 	dcancel()
@@ -126,7 +159,7 @@ func (r *LocalRunner) serve(ctx context.Context, wsURL, root string) error {
 	conn.SetReadLimit(1 << 20)
 	r.setStatus("online")
 
-	hello, _ := json.Marshal(runnerResp{ID: "hello", OK: true, Workdir: root})
+	hello, _ := json.Marshal(runnerResp{ID: "hello", OK: true, Workdir: strings.Join(roots, "、")})
 	if err := conn.Write(ctx, websocket.MessageText, hello); err != nil {
 		return err
 	}
@@ -140,7 +173,7 @@ func (r *LocalRunner) serve(ctx context.Context, wsURL, root string) error {
 		if json.Unmarshal(data, &req) != nil {
 			continue
 		}
-		resp := execLocal(root, &req)
+		resp := execLocal(roots, &req)
 		out, _ := json.Marshal(resp)
 		if err := conn.Write(ctx, websocket.MessageText, out); err != nil {
 			return err
@@ -155,10 +188,33 @@ const (
 	maxDirEntries = 200       // list_dir 上限条数
 )
 
-// resolveInRoot 把相对路径解析进沙箱根：清洗 + 软链解析后必须仍在 root 下，越界即错。
+// resolveAllowed 把一个路径解析并校验是否落在**任一**授权目录内。
-func resolveInRoot(root, rel string) (string, error) {
+// 单目录沙箱做不了"操作我电脑"（只能在一个文件夹里打转），改成多目录白名单：
-	p := filepath.Join(root, filepath.Clean("/"+rel)) // 前置 "/" 再 Clean：吃掉 ../ 逃逸
+// 用户授权哪些目录（桌面/下载/文档/项目目录…），agent 就只能在这些目录里动手。
-	// 软链解析（目标可能不存在：解析其父目录）
+// 路径用绝对路径（多根之下相对路径没有唯一含义），支持 ~ 展开。
+// 防逃逸仍靠"软链解析后前缀校验"——软链指向白名单之外一律拒。
+func resolveAllowed(roots []string, p string) (string, error) {
+	p = strings.TrimSpace(p)
+	if p == "" {
+		return "", fmt.Errorf("缺少路径")
+	}
+	if p == "~" || strings.HasPrefix(p, "~/") {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return "", err
+		}
+		p = filepath.Join(home, strings.TrimPrefix(strings.TrimPrefix(p, "~"), "/"))
+	}
+	if !filepath.IsAbs(p) {
+		// 相对路径按第一个授权目录解释（兜底：模型偶尔会给相对路径）
+		if len(roots) == 0 {
+			return "", fmt.Errorf("没有已授权的目录")
+		}
+		p = filepath.Join(roots[0], filepath.Clean("/"+p))
+	}
+	p = filepath.Clean(p)
+
+	// 软链解析（目标可能不存在：那就用清洗后的路径本身比对）
 	resolved, err := filepath.EvalSymlinks(p)
 	if err != nil {
 		if !os.IsNotExist(err) {
@@ -166,23 +222,34 @@ func resolveInRoot(root, rel string) (string, error) {
 		}
 		resolved = p
 	}
-	rootR, err := filepath.EvalSymlinks(root)
+	for _, root := range roots {
-	if err != nil {
+		rootR, err := filepath.EvalSymlinks(root)
-		rootR = root
+		if err != nil {
+			rootR = root
+		}
+		if resolved == rootR || strings.HasPrefix(resolved, rootR+string(filepath.Separator)) {
+			return resolved, nil
+		}
 	}
-	if resolved != rootR && !strings.HasPrefix(resolved, rootR+string(filepath.Separator)) {
+	return "", fmt.Errorf("路径 %s 不在已授权目录内（当前授权：%s）", p, strings.Join(roots, "、"))
-		return "", fmt.Errorf("路径越出工作目录沙箱")
-	}
-	return resolved, nil
 }
 
-func execLocal(root string, req *runnerReq) *runnerResp {
+func execLocal(roots []string, req *runnerReq) *runnerResp {
 	fail := func(msg string) *runnerResp { return &runnerResp{ID: req.ID, OK: false, Error: msg} }
 	rel, _ := req.Args["path"].(string)
 
 	switch req.Tool {
 	case "local_list_dir":
-		p, err := resolveInRoot(root, rel)
+		// 空路径 = 列出所有已授权目录（多根之下没有唯一"根"）。
+		// 这也是模型发现"我能访问哪些地方"的入口。
+		if strings.TrimSpace(rel) == "" {
+			data, _ := json.Marshal(map[string]any{
+				"authorized_dirs": roots,
+				"hint":            "这些是用户授权可访问的目录。要看某个目录内容，把它的绝对路径作为 path 再调一次。",
+			})
+			return &runnerResp{ID: req.ID, OK: true, Content: string(data)}
+		}
+		p, err := resolveAllowed(roots, rel)
 		if err != nil {
 			return fail(err.Error())
 		}
@@ -214,7 +281,7 @@ func execLocal(root string, req *runnerReq) *runnerResp {
 		if strings.TrimSpace(rel) == "" {
 			return fail("缺少文件路径")
 		}
-		p, err := resolveInRoot(root, rel)
+		p, err := resolveAllowed(roots, rel)
 		if err != nil {
 			return fail(err.Error())
 		}
@@ -240,10 +307,10 @@ func execLocal(root string, req *runnerReq) *runnerResp {
 
 	// 能动的手（localexec.go）：各自带独立开关 + 黑名单 + 原生审批框。
 	case "local_write_file":
-		return execWrite(root, req)
+		return execWrite(roots, req)
 
 	case "local_exec":
-		return execCommand(root, req)
+		return execCommand(roots, req)
 
 	default:
 		return fail("本地执行器不支持该操作: " + req.Tool)

sundynix-desktop/localrunner_test.go

@@ -34,7 +34,7 @@ func TestResolveInRootBlocksEscape(t *testing.T) {
 		rootR = root
 	}
 	for _, rel := range []string{"..", "../..", "../../etc/passwd", "sub/../../outside", "/etc/passwd"} {
-		p, err := resolveInRoot(root, rel)
+		p, err := resolveAllowed([]string{root}, rel)
 		// 前置 "/"+Clean 把绝对路径/.. 都钉回 root 下（如 root/etc/passwd，不算逃逸）；
 		// 无论哪种形式，成功解析的结果都必须仍在 root（解析后）之内。
 		if err == nil && p != rootR && !strings.HasPrefix(p, rootR+string(filepath.Separator)) {
@@ -53,7 +53,7 @@ func TestResolveInRootBlocksSymlinkEscape(t *testing.T) {
 	if err := os.Symlink(outside, link); err != nil {
 		t.Skip("无法创建软链，跳过")
 	}
-	if _, err := resolveInRoot(root, "evil/secret.txt"); err == nil {
+	if _, err := resolveAllowed([]string{root}, "evil/secret.txt"); err == nil {
 		t.Fatal("软链逃逸未被拦截")
 	}
 }
@@ -61,8 +61,14 @@ func TestResolveInRootBlocksSymlinkEscape(t *testing.T) {
 func TestExecLocalListAndRead(t *testing.T) {
 	root := newSandbox(t)
 
-	// list_dir 根目录
+	// list_dir 空路径 = 列出授权目录清单（模型据此发现能访问哪里）
-	resp := execLocal(root, &runnerReq{ID: "1", Tool: "local_list_dir", Args: map[string]any{"path": ""}})
+	resp := execLocal([]string{root}, &runnerReq{ID: "0", Tool: "local_list_dir", Args: map[string]any{"path": ""}})
+	if !resp.OK || !strings.Contains(resp.Content, "authorized_dirs") {
+		t.Fatalf("空路径应返回授权目录清单: ok=%v content=%s", resp.OK, resp.Content)
+	}
+
+	// list_dir 指定目录
+	resp = execLocal([]string{root}, &runnerReq{ID: "1", Tool: "local_list_dir", Args: map[string]any{"path": root}})
 	if !resp.OK {
 		t.Fatalf("list_dir 失败: %s", resp.Error)
 	}
@@ -80,19 +86,19 @@ func TestExecLocalListAndRead(t *testing.T) {
 	}
 
 	// read_file 子目录文件
-	resp = execLocal(root, &runnerReq{ID: "2", Tool: "local_read_file", Args: map[string]any{"path": "sub/b.txt"}})
+	resp = execLocal([]string{root}, &runnerReq{ID: "2", Tool: "local_read_file", Args: map[string]any{"path": "sub/b.txt"}})
 	if !resp.OK || resp.Content != "world" {
 		t.Fatalf("read_file 失败: ok=%v content=%q err=%s", resp.OK, resp.Content, resp.Error)
 	}
 
 	// read_file 越界必须拒
-	resp = execLocal(root, &runnerReq{ID: "3", Tool: "local_read_file", Args: map[string]any{"path": "../outside.txt"}})
+	resp = execLocal([]string{root}, &runnerReq{ID: "3", Tool: "local_read_file", Args: map[string]any{"path": "/etc/passwd"}})
 	if resp.OK {
 		t.Fatal("越界读未被拦截")
 	}
 
 	// 未知工具（写/exec 都不在只读版里）必须拒
-	resp = execLocal(root, &runnerReq{ID: "4", Tool: "local_write_file", Args: map[string]any{"path": "a.txt"}})
+	resp = execLocal([]string{root}, &runnerReq{ID: "4", Tool: "local_write_file", Args: map[string]any{"path": "a.txt"}})
 	if resp.OK {
 		t.Fatal("未注册操作未被拦截")
 	}

sundynix-gateway/cmd/localsim/main.go

@@ -36,36 +36,45 @@ type resp struct {
 
 func main() {
 	gw := flag.String("gw", "ws://localhost:8080", "gateway WS 基址")
-	dir := flag.String("dir", ".", "沙箱工作目录")
+	dir := flag.String("dir", ".", "授权目录，逗号分隔（模拟桌面端的多目录白名单）")
 	flag.Parse()
 	token := os.Getenv("LOCALSIM_TOKEN")
 	if token == "" {
 		log.Fatal("缺 LOCALSIM_TOKEN（用户 JWT）")
 	}
-	root, err := filepath.Abs(*dir)
+	var roots []string
-	if err != nil {
+	for _, d := range strings.Split(*dir, ",") {
-		log.Fatal(err)
+		if d = strings.TrimSpace(d); d == "" {
+			continue
+		}
+		abs, err := filepath.Abs(d)
+		if err != nil {
+			log.Fatal(err)
+		}
+		roots = append(roots, abs)
+	}
+	if len(roots) == 0 {
+		log.Fatal("至少一个目录")
 	}
-
 	url := strings.TrimRight(*gw, "/") + "/api/v1/local/runner?token=" + token
 	// 断线自动重连（对齐真桌面端 runner 的 5s 退避）：网关重启时联调不用手动重拉。
 	for {
-		if err := serveOnce(url, root); err != nil {
+		if err := serveOnce(url, roots); err != nil {
 			log.Printf("连接断开（5s 后重连）: %v", err)
 		}
 		time.Sleep(5 * time.Second)
 	}
 }
 
-func serveOnce(url, root string) error {
+func serveOnce(url string, roots []string) error {
 	conn, _, err := websocket.DefaultDialer.Dial(url, nil)
 	if err != nil {
 		return err
 	}
 	defer conn.Close()
-	log.Printf("已注册为本地执行器 workdir=%s", root)
+	log.Printf("已注册为本地执行器 授权目录=%s", strings.Join(roots, "、"))
 
-	hello, _ := json.Marshal(resp{ID: "hello", OK: true, Workdir: root})
+	hello, _ := json.Marshal(resp{ID: "hello", OK: true, Workdir: strings.Join(roots, "、")})
 	_ = conn.WriteMessage(websocket.TextMessage, hello)
 
 	for {
@@ -78,18 +87,40 @@ func serveOnce(url, root string) error {
 			continue
 		}
 		log.Printf("收到调用 tool=%s args=%v", r.Tool, r.Args)
-		out, _ := json.Marshal(handle(root, &r))
+		out, _ := json.Marshal(handle(roots, &r))
 		if err := conn.WriteMessage(websocket.TextMessage, out); err != nil {
 			return err
 		}
 	}
 }
 
-func handle(root string, r *req) *resp {
+func handle(roots []string, r *req) *resp {
+	root := roots[0]
 	rel, _ := r.Args["path"].(string)
-	p := filepath.Join(root, filepath.Clean("/"+rel)) // 简版沙箱（联调工具；正式沙箱在桌面端）
+	// 简版沙箱（联调工具；正式沙箱在桌面端 resolveAllowed）：绝对路径须落在某个授权根内。
+	p := rel
+	if p == "" {
+		p = root
+	} else if !filepath.IsAbs(p) {
+		p = filepath.Join(root, filepath.Clean("/"+p))
+	}
+	p = filepath.Clean(p)
+	inRoot := false
+	for _, rt := range roots {
+		if p == rt || strings.HasPrefix(p, rt+string(filepath.Separator)) {
+			inRoot = true
+			break
+		}
+	}
+	if !inRoot {
+		return &resp{ID: r.ID, OK: false, Error: "路径不在授权目录内: " + p}
+	}
 	switch r.Tool {
 	case "local_list_dir":
+		if strings.TrimSpace(rel) == "" {
+			data, _ := json.Marshal(map[string]any{"authorized_dirs": roots})
+			return &resp{ID: r.ID, OK: true, Content: string(data)}
+		}
 		ents, err := os.ReadDir(p)
 		if err != nil {
 			return &resp{ID: r.ID, OK: false, Error: err.Error()}

sundynix-gateway/internal/handler/platform_tools.go

@@ -73,28 +73,39 @@ func (h *Handler) platformRegistry() map[string]platTool {
 		// —— 本地的手（P4，只读起步）：执行发生在用户自己的桌面（沙箱工作目录内），服务端只路由。
 		// 桌面端不在线/没开本地访问时工具会明确报不可用——如实转告用户即可。
 		"local_list_dir": {
-			cn: "看本地目录", desc: "列出用户本地工作目录（或其子目录）里的文件。用户问“我这个目录/文件夹里有什么”时调用。仅用户桌面端在线且开启了本地访问才可用。",
+			cn: "看本地目录", desc: "列出用户电脑上某个目录里的文件。**path 留空会返回用户授权你访问的目录清单**——不知道该看哪时先这样调一次。用户问“我某个文件夹里有什么/桌面上有什么”时调用。仅用户桌面端在线且开启本地访问才可用。",
-			params: []platParam{{Name: "path", Type: "string", Desc: "相对工作目录的子路径，空=根目录"}},
+			params: []platParam{{Name: "path", Type: "string", Desc: "目录的绝对路径（如 /Users/xx/Desktop）；留空=返回授权目录清单"}},
 			inject: []string{"user_id"}, handler: h.platLocalExec,
 		},
 		"local_read_file": {
-			cn: "读本地文件", desc: "读取用户本地工作目录内某个文件的文本内容（大文件截断）。用户让“看看/读一下 某个本地文件”时调用。仅用户桌面端在线且开启了本地访问才可用。",
+			cn: "读本地文件", desc: "读取用户电脑上某个文件的文本内容（大文件截断）。用户让“看看/读一下 某个文件”时调用。仅用户桌面端在线且开启本地访问才可用。",
-			params: []platParam{{Name: "path", Type: "string", Desc: "相对工作目录的文件路径", Required: true}},
+			params: []platParam{{Name: "path", Type: "string", Desc: "文件的绝对路径", Required: true}},
 			inject: []string{"user_id"}, handler: h.platLocalExec,
 		},
 		// —— 能动的手：写文件 / 执行命令。桌面端会弹原生确认框让用户逐次批准（默认拒绝），
 		// 且命中安全黑名单的命令直接拒绝。被拒时如实告诉用户，别重试绕路。
 		"local_write_file": {
-			cn: "写本地文件", desc: "在用户本地工作目录内写入/覆盖一个文本文件。用户明确要求“写个文件/保存到本地/生成脚本”时调用。用户会在桌面端收到确认框，需其批准才真正写入。",
+			cn: "写本地文件", desc: "在用户电脑上写入/覆盖一个文本文件（只能写进用户授权的目录）。用户要求“写个文件/保存到本地/生成脚本”时调用。用户会在桌面端收到确认框，需其批准才真正写入。",
 			params: []platParam{
-				{Name: "path", Type: "string", Desc: "相对工作目录的文件路径", Required: true},
+				{Name: "path", Type: "string", Desc: "文件的绝对路径（须在授权目录内）", Required: true},
 				{Name: "content", Type: "string", Desc: "完整文件内容（会覆盖原文件）", Required: true},
 			},
 			inject: []string{"user_id"}, timeoutSec: 100, handler: h.platLocalExec,
 		},
 		"local_exec": {
-			cn: "执行本地命令", desc: "在用户本地工作目录里执行一条 shell 命令并返回输出（超时 60 秒）。用户要求“跑一下/执行/编译/查一下某个命令结果”时调用。用户会在桌面端收到确认框，需其批准才执行；删库、提权、写系统路径等危险命令会被直接拒绝。一次只提交一条命令，别猜着连环执行。",
+			cn: "操作电脑", desc: `在用户的 Mac 上执行一条 shell 命令并返回输出（超时 60 秒）。这是你操作这台电脑的主要手段，能干的远不止跑脚本：
-			params: []platParam{{Name: "command", Type: "string", Desc: "要执行的 shell 命令，如 ls -la、git status、npm test", Required: true}},
+- 文件整理：mv / cp / mkdir / 批量重命名（find + mv）
+- 找东西：mdfind "关键词"（Spotlight 全盘搜索）、grep -rn、ls
+- 开应用/开文件：open -a "Safari"、open /path/to/file、open https://...
+- 控制 App（AppleScript）：osascript -e 'tell application "Music" to play'、暂停播放、发邮件、建日历事件、取当前播放歌曲等
+- 触发快捷指令：shortcuts run "指令名"（用户在「快捷指令」App 里建的自动化，可含智能家居场景）；shortcuts list 可先列出有哪些
+- 系统信息：df -h、uptime、pmset -g batt（电量）
+用户说“打开某某/放首歌/把这些文件整理一下/找找那个文档在哪”都用这个工具。
+用户会在桌面端收到确认框，需其批准才执行；删库、提权、写系统路径等危险命令会被直接拒绝。一次只提交一条命令。`,
+			params: []platParam{
+				{Name: "command", Type: "string", Desc: "要执行的 shell 命令", Required: true},
+				{Name: "cwd", Type: "string", Desc: "在哪个授权目录里执行（绝对路径，可选；默认第一个授权目录）"},
+			},
 			inject: []string{"user_id"}, timeoutSec: 160, handler: h.platLocalExec,
 		},
 		// —— 调度：让用户能说「每天早上九点帮我看看昨天的任务」。到点由 JARVIS 自己按指令办事并播报。

sundynix-gateway/internal/handler/voice_task.go

@@ -25,9 +25,12 @@ func voiceSystemPrompt(name, persona string) string {
 	if n == "" {
 		n = defaultJarvisName
 	}
-	s := "你是 " + n + "——用户的私人语音助手，也是这套平台与他电脑的中枢。你能：查/派任务与报告、" +
+	s := "你是 " + n + "——用户的私人语音助手，也是他这台电脑的操作者。你能：" +
-		"切换客户端界面、在用户授权的工作目录里看文件读文件、写文件、执行 shell 命令、" +
+		"在用户授权的目录里看/读/写文件、执行 shell 命令（据此可以整理文件、用 mdfind 全盘找东西、" +
-		"以及建定时任务（到点自动办事并播报）。相应工具会提供给你，需要就调。" +
+		"open 打开应用和文件、osascript 控制 Mac 上的 App、shortcuts run 触发快捷指令）、" +
+		"查/派平台任务与报告、切换客户端界面、建定时任务（到点自动办事并播报）。" +
+		"用户让你「做点什么」时，先想清楚用哪个工具、一步步做，别只是嘴上答应。" +
+		"不知道能访问哪些目录，就用 local_list_dir 留空 path 查一次。" +
 		"铁律一：凡是用户问任务/报告的状态、进度、结果，**必须先调工具查真实数据再回答**——" +
 		"哪怕你觉得自己记得，也不许凭记忆或上下文编造任务状态；查不到就如实说查不到。" +
 		"铁律二：涉及写文件/执行命令，用户会在电脑上收到确认框；被拒绝或被安全策略挡下时如实告诉他，" +

sundynix-gateway/internal/handler/voice_tts.go

@@ -18,7 +18,13 @@ import (
 // TTS 就绪后补吐，保证第一句不丢。
 func (s *voiceSession) speak(taskID string) {
 	if !s.cfg.TTSEnabled() {
-		return // 没配 TTS：只回转写 + 任务，无语音朗读
+		// 没配 TTS（缺 resource-id 或音色）：不朗读，但**必须**回 tts_end——
+		// 否则客户端永远停在"思考中"，用户看到的是"提问后彻底没反应"，
+		// 完全看不出是配置问题（这里此前是静默 return，坑了整整一天）。
+		log.Printf("[voice] TTS 未配置（需 api_key + tts_resource_id + tts_voice_type 三项齐全），本轮只回文字 uid=%s", s.uid)
+		s.send(voice.ServerMsg{Type: voice.ServerError, Msg: "未配置语音合成（缺 TTS resource-id 或音色），本次只有文字回答"})
+		s.send(voice.ServerMsg{Type: voice.ServerTTSEnd})
+		return
 	}
 
 	sb := voice.NewSentenceBuffer()