feat(voice): 提升桌面端语音交互与本地任务执行支持

2026-07-24 16:40:25 +08:00
parent e9a8b9b4c6
commit aba88193d8
33 changed files with 1909 additions and 102 deletions
@@ -0,0 +1,163 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+	"net/http"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/gorilla/websocket"
+
+	"github.com/sundynix/sundynix-shared/contract"
+)
+
+// 本地执行 runner 接入（JARVIS P4「本地的手」，LOCAL_AGENT_DESIGN 档 A）：
+// 桌面端 Go host 登录后连本 WS，把自己注册成该用户的本地执行器。local_* 工具调用
+// 经 NATS sundynix.local.exec.<uid>（request-reply，本连接队列组订阅）路由到这里，
+// 转发给 runner 执行、结果原路回。runner 掉线即退订——调用方拿到"不在线"而非干等。
+//
+// 安全：执行发生在**用户自己的机器**、以用户 OS 身份、锁在用户自选的工作目录（沙箱在
+// runner 侧强制）；服务端只做路由。归属天然成立：subject 按 uid 分桶，工具 inject user_id。
+
+var runnerUpgrader = websocket.Upgrader{
+	ReadBufferSize: 4096, WriteBufferSize: 4096,
+	CheckOrigin: func(*http.Request) bool { return true }, // 鉴权由 token 把关
+}
+
+const (
+	runnerCallTimeout = 12 * time.Second // 等 runner 回执行结果（只读文件操作，够了）
+	runnerWriteWait   = 10 * time.Second
+)
+
+// runnerReq / runnerResp 是 gateway ↔ 桌面 runner 的 WS 消息（JSON 文本帧）。
+type runnerReq struct {
+	ID   string         `json:"id"`
+	Tool string         `json:"tool"`
+	Args map[string]any `json:"args,omitempty"`
+}
+
+type runnerResp struct {
+	ID      string `json:"id"`
+	OK      bool   `json:"ok"`
+	Content string `json:"content,omitempty"`
+	Error   string `json:"error,omitempty"`
+	Workdir string `json:"workdir,omitempty"` // hello 帧带：runner 声明的沙箱根（仅展示/日志）
+}
+
+// LocalRunner: GET /api/v1/local/runner —— 桌面端注册本地执行器（WS，?token= 鉴权）。
+func (h *Handler) LocalRunner(c *gin.Context) {
+	uid := userID(c)
+	if uid == "" {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "需要登录"})
+		return
+	}
+	conn, err := runnerUpgrader.Upgrade(c.Writer, c.Request, nil)
+	if err != nil {
+		return
+	}
+	defer conn.Close()
+
+	r := &runnerConn{conn: conn, pending: map[string]chan *runnerResp{}}
+
+	// 队列组订阅本用户执行主题：多台桌面在线时 NATS 队列组自动挑一台执行。
+	drain, err := h.bus.ServeTool(contract.LocalExecSubject(uid), "local-"+uid, r.forward)
+	if err != nil {
+		log.Printf("[local] runner 订阅失败 uid=%s: %v", uid, err)
+		return
+	}
+	log.Printf("[local] 本地执行器上线 uid=%s", uid)
+
+	// 读循环：分发 runner 的执行回执；连接断开即退出。
+	for {
+		_, data, rerr := conn.ReadMessage()
+		if rerr != nil {
+			break
+		}
+		var resp runnerResp
+		if json.Unmarshal(data, &resp) != nil {
+			continue
+		}
+		if resp.ID == "hello" {
+			log.Printf("[local] runner 声明工作目录 uid=%s dir=%s", uid, resp.Workdir)
+			continue
+		}
+		r.deliver(&resp)
+	}
+
+	dctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	drain(dctx)
+	cancel()
+	r.failAll("本地执行器已断开")
+	log.Printf("[local] 本地执行器下线 uid=%s", uid)
+}
+
+// runnerConn 一条 runner 连接：串行化写 + 按请求 id 关联回执。
+type runnerConn struct {
+	conn    *websocket.Conn
+	writeMu sync.Mutex
+	mu      sync.Mutex
+	pending map[string]chan *runnerResp
+	seq     atomic.Int64
+}
+
+// forward 把一次 local_* 工具调用转发给 runner，等回执（NATS ServeTool 的 handler）。
+func (r *runnerConn) forward(ctx context.Context, call *contract.ToolCall) *contract.ToolResult {
+	id := fmt.Sprintf("r%d", r.seq.Add(1))
+	ch := make(chan *runnerResp, 1)
+	r.mu.Lock()
+	r.pending[id] = ch
+	r.mu.Unlock()
+	defer func() {
+		r.mu.Lock()
+		delete(r.pending, id)
+		r.mu.Unlock()
+	}()
+
+	data, _ := json.Marshal(runnerReq{ID: id, Tool: call.Tool, Args: call.Args})
+	r.writeMu.Lock()
+	_ = r.conn.SetWriteDeadline(time.Now().Add(runnerWriteWait))
+	werr := r.conn.WriteMessage(websocket.TextMessage, data)
+	r.writeMu.Unlock()
+	if werr != nil {
+		return &contract.ToolResult{OK: false, Error: "转发本地执行失败: " + werr.Error()}
+	}
+
+	select {
+	case resp := <-ch:
+		return &contract.ToolResult{OK: resp.OK, Content: resp.Content, Error: resp.Error}
+	case <-time.After(runnerCallTimeout):
+		return &contract.ToolResult{OK: false, Error: "本地执行超时（桌面端未响应）"}
+	case <-ctx.Done():
+		return &contract.ToolResult{OK: false, Error: "本地执行取消: " + ctx.Err().Error()}
+	}
+}
+
+// deliver 把 runner 回执投递给等待中的 forward。
+func (r *runnerConn) deliver(resp *runnerResp) {
+	r.mu.Lock()
+	ch := r.pending[resp.ID]
+	r.mu.Unlock()
+	if ch != nil {
+		select {
+		case ch <- resp:
+		default:
+		}
+	}
+}
+
+// failAll 连接断开时让所有在途调用立即失败（别干等超时）。
+func (r *runnerConn) failAll(msg string) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for id, ch := range r.pending {
+		select {
+		case ch <- &runnerResp{ID: id, OK: false, Error: msg}:
+		default:
+		}
+	}
+}
@@ -0,0 +1,253 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"log"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/sundynix/sundynix-shared/contract"
+)
+
+// 平台工具族（JARVIS 大脑中枢，见 JARVIS_BRAIN_DESIGN.md §2.1）：gateway 自己作为第三个工具
+// 提供方（与 mcp-go/mcp-py 同协议）。平台操作的权威——提交关卡 preflightCore/launchCore、
+// 归属校验、计费——都在 gateway，工具就长在权威所在地，而不是让 mcp-go 绕一圈回来调。
+// dispatcher 经 list_tools 动态发现，加工具只改这里的注册表。
+//
+// 安全铁律：①一律 inject user_id + 服务端归属校验，模型不可指定别人的资源；
+// ②会烧钱的提交（gen_report）必须走 preflightCore（预算/暂停/积分硬拦截）同一关卡。
+
+// platParam 工具参数声明（与 mcp-go paramSpec 同构，list_tools JSON 契约一致）。
+type platParam struct {
+	Name     string `json:"name"`
+	Type     string `json:"type"`
+	Desc     string `json:"desc"`
+	Required bool   `json:"required"`
+}
+
+// platTool 一个平台工具：元信息 + 处理函数（注册表 = 唯一事实源，dispatch 与 list_tools 共用）。
+type platTool struct {
+	cn      string
+	desc    string
+	params  []platParam
+	inject  []string
+	handler func(context.Context, *contract.ToolCall) *contract.ToolResult
+}
+
+// platformRegistry 平台工具注册表。想加新工具（run_orchestration/search_kb/usage_today…）只改这里。
+func (h *Handler) platformRegistry() map[string]platTool {
+	return map[string]platTool{
+		"platform_recent_tasks": {
+			cn: "最近任务", desc: "查询当前用户最近的任务运行列表（状态/主题/时间）。用户问“我最近的任务怎么样了/都有什么任务”时调用。",
+			inject: []string{"user_id"}, handler: h.platRecentTasks,
+		},
+		"platform_task_status": {
+			cn: "任务状态", desc: "查询某个任务的当前状态与输出摘要。用户问“那个任务/报告跑完了吗、结果是什么”时调用。",
+			params: []platParam{{Name: "task_id", Type: "string", Desc: "任务 ID", Required: true}},
+			inject: []string{"user_id"}, handler: h.platTaskStatus,
+		},
+		"platform_gen_report": {
+			cn: "生成报告", desc: "提交一个报告生成任务（异步跑，规划→分章→成稿）。用户要“写/生成一份 XX 报告”时调用。返回 task_id 后告诉用户已开跑、可稍后询问进度，不要原地等待结果。",
+			params: []platParam{
+				{Name: "topic", Type: "string", Desc: "报告主题", Required: true},
+				{Name: "kb", Type: "string", Desc: "参考知识库名（可选，用户提到才填）"},
+			},
+			inject: []string{"user_id", "tenant_id", "session_id"}, handler: h.platGenReport,
+		},
+		"platform_open_view": {
+			cn: "打开界面", desc: "把用户的客户端界面切到某个页面。用户说“打开/带我去/看看 运行页、报告页、知识库”等时调用。view 取值：home(工作台)/studio(编排)/kb(知识库)/runs(运行)/report(报告)/memory(记忆)/usage(用量)。",
+			params: []platParam{
+				{Name: "view", Type: "string", Desc: "目标页面：home/studio/kb/runs/report/memory/usage", Required: true},
+				{Name: "task_id", Type: "string", Desc: "可选：聚焦的任务 ID（配合 runs 页）"},
+			},
+			inject: []string{"user_id"}, handler: h.platOpenView,
+		},
+		// —— 本地的手（P4，只读起步）：执行发生在用户自己的桌面（沙箱工作目录内），服务端只路由。
+		// 桌面端不在线/没开本地访问时工具会明确报不可用——如实转告用户即可。
+		"local_list_dir": {
+			cn: "看本地目录", desc: "列出用户本地工作目录（或其子目录）里的文件。用户问“我这个目录/文件夹里有什么”时调用。仅用户桌面端在线且开启了本地访问才可用。",
+			params: []platParam{{Name: "path", Type: "string", Desc: "相对工作目录的子路径，空=根目录"}},
+			inject: []string{"user_id"}, handler: h.platLocalExec,
+		},
+		"local_read_file": {
+			cn: "读本地文件", desc: "读取用户本地工作目录内某个文件的文本内容（大文件截断）。用户让“看看/读一下 某个本地文件”时调用。仅用户桌面端在线且开启了本地访问才可用。",
+			params: []platParam{{Name: "path", Type: "string", Desc: "相对工作目录的文件路径", Required: true}},
+			inject: []string{"user_id"}, handler: h.platLocalExec,
+		},
+	}
+}
+
+// platLocalExec 把 local_* 调用经 NATS 路由到该用户的桌面 runner（见 local_runner.go）。
+// 无 runner 在线时 NATS 无应答 → 明确报"不在线"，绝不挂起任务。
+func (h *Handler) platLocalExec(ctx context.Context, call *contract.ToolCall) *contract.ToolResult {
+	uid, _ := call.Args["user_id"].(string)
+	if uid == "" {
+		return &contract.ToolResult{OK: false, Error: "缺少用户身份"}
+	}
+	cctx, cancel := context.WithTimeout(ctx, 15*time.Second)
+	defer cancel()
+	res, err := h.bus.CallTool(cctx, contract.LocalExecSubject(uid), call)
+	if err != nil {
+		return &contract.ToolResult{OK: true, Content: "本地执行器不在线：用户桌面端未运行或未开启本地文件访问。请如实告知用户。"}
+	}
+	return res
+}
+
+// ServePlatformTools 以队列组订阅 sundynix.tools.platform.>，返回 drain 供优雅停机。
+func (h *Handler) ServePlatformTools() (func(context.Context), error) {
+	reg := h.platformRegistry()
+	names := make([]string, 0, len(reg))
+	for n := range reg {
+		names = append(names, n)
+	}
+	sort.Strings(names)
+	drain, err := h.bus.ServeTool(contract.SubjectToolsPlatformAll, contract.QueueToolsPlatform,
+		func(ctx context.Context, call *contract.ToolCall) *contract.ToolResult {
+			return h.platformDispatch(reg, ctx, call)
+		})
+	if err != nil {
+		return nil, err
+	}
+	log.Printf("[platform] 平台工具就绪 %s (queue=%s): %s",
+		contract.SubjectToolsPlatformAll, contract.QueueToolsPlatform, strings.Join(names, ", "))
+	return drain, nil
+}
+
+func (h *Handler) platformDispatch(reg map[string]platTool, ctx context.Context, call *contract.ToolCall) *contract.ToolResult {
+	log.Printf("[platform] tool=%s task=%s", call.Tool, call.TaskID)
+	if call.Tool == "list_tools" {
+		return platListTools(reg)
+	}
+	td, ok := reg[call.Tool]
+	if !ok {
+		return &contract.ToolResult{OK: false, Error: "unknown platform tool: " + call.Tool}
+	}
+	return td.handler(ctx, call)
+}
+
+// platListTools 自省：JSON 契约与 mcp-go listTools 一致（dispatcher toolCatalogEntry 同一解析）。
+func platListTools(reg map[string]platTool) *contract.ToolResult {
+	type info struct {
+		Name   string      `json:"name"`
+		CN     string      `json:"cn"`
+		Desc   string      `json:"desc"`
+		Agent  bool        `json:"agent_exposed"`
+		Params []platParam `json:"params,omitempty"`
+		Inject []string    `json:"inject,omitempty"`
+	}
+	out := make([]info, 0, len(reg))
+	for name, td := range reg {
+		out = append(out, info{Name: name, CN: td.cn, Desc: td.desc, Agent: true, Params: td.params, Inject: td.inject})
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
+	data, _ := json.Marshal(map[string]any{"service": "gateway-platform", "tools": out})
+	return &contract.ToolResult{OK: true, Content: string(data)}
+}
+
+// ---- 工具实现 ----
+
+// platRecentTasks 最近任务列表（owner 隔离：只看自己的）。
+func (h *Handler) platRecentTasks(ctx context.Context, call *contract.ToolCall) *contract.ToolResult {
+	uid, _ := call.Args["user_id"].(string)
+	if uid == "" {
+		return &contract.ToolResult{OK: false, Error: "缺少用户身份"}
+	}
+	rows := h.db.RecentRuns(ctx, uid, 10)
+	type item struct {
+		TaskID string `json:"task_id"`
+		Status string `json:"status"`
+		Topic  string `json:"topic,omitempty"`
+		At     string `json:"at"`
+	}
+	out := make([]item, 0, len(rows))
+	for _, r := range rows {
+		out = append(out, item{TaskID: r.TaskID, Status: r.Status, Topic: r.Topic, At: r.At.Format("01-02 15:04")})
+	}
+	if len(out) == 0 {
+		return &contract.ToolResult{OK: true, Content: "没有任何任务运行记录。"}
+	}
+	data, _ := json.Marshal(out)
+	return &contract.ToolResult{OK: true, Content: string(data)}
+}
+
+// platTaskStatus 单任务状态 + 输出摘要。归属校验：不是本人的任务一律说不存在（不泄露存在性）。
+func (h *Handler) platTaskStatus(ctx context.Context, call *contract.ToolCall) *contract.ToolResult {
+	uid, _ := call.Args["user_id"].(string)
+	taskID, _ := call.Args["task_id"].(string)
+	if uid == "" || strings.TrimSpace(taskID) == "" {
+		return &contract.ToolResult{OK: false, Error: "缺少 task_id"}
+	}
+	owner := h.db.TaskOwner(ctx, taskID)
+	if owner == "" || owner != uid {
+		return &contract.ToolResult{OK: true, Content: "没有找到这个任务（ID 不存在或不属于当前用户）。"}
+	}
+	status, detail := h.db.GetTaskStatus(ctx, taskID)
+	output, _ := h.db.GetRunDetail(ctx, taskID)
+	if rs := []rune(output); len(rs) > 600 {
+		output = string(rs[:600]) + "…（已截断）"
+	}
+	data, _ := json.Marshal(map[string]string{
+		"task_id": taskID, "status": status, "detail": detail, "output_preview": output,
+	})
+	return &contract.ToolResult{OK: true, Content: string(data)}
+}
+
+// platOpenView 界面动作（P2 动作通道）：经语音事件通道把 navigate 发到该用户的语音会话，
+// 由客户端按白名单执行。视图合法性双重校验（此处 + 会话 onVoiceEvent + 客户端），宁可不动。
+func (h *Handler) platOpenView(_ context.Context, call *contract.ToolCall) *contract.ToolResult {
+	uid, _ := call.Args["user_id"].(string)
+	view, _ := call.Args["view"].(string)
+	taskID, _ := call.Args["task_id"].(string)
+	if uid == "" || view == "" {
+		return &contract.ToolResult{OK: false, Error: "缺少 view"}
+	}
+	if !navigateViews[view] {
+		return &contract.ToolResult{OK: false, Error: "未知页面: " + view + "（可用 home/studio/kb/runs/report/memory/usage）"}
+	}
+	if err := h.bus.PublishVoiceEvent(uid, &contract.VoiceEvent{Action: "navigate", View: view, TaskID: taskID}); err != nil {
+		return &contract.ToolResult{OK: false, Error: "下发界面动作失败: " + err.Error()}
+	}
+	return &contract.ToolResult{OK: true, Content: "已让客户端切到 " + view + " 页。告诉用户已打开即可。"}
+}
+
+// platGenReport 提交报告任务——与 HTTP GenerateReport 同一条关卡与发射流程
+// （preflightCore：预算/暂停/计费租户/积分硬拦截；launchCore：落库+录像+Publish）。
+func (h *Handler) platGenReport(ctx context.Context, call *contract.ToolCall) *contract.ToolResult {
+	uid, _ := call.Args["user_id"].(string)
+	topic, _ := call.Args["topic"].(string)
+	kb, _ := call.Args["kb"].(string)
+	tid, _ := call.Args["tenant_id"].(string)   // 发起任务的活跃租户（计费口径跟 HTTP 提交一致）
+	sid, _ := call.Args["session_id"].(string) // 挂回发起会话（语音会话可续聊“报告好了吗”）
+	topic = strings.TrimSpace(topic)
+	if uid == "" || topic == "" {
+		return &contract.ToolResult{OK: false, Error: "缺少报告主题"}
+	}
+
+	billingTenant, block := h.preflightCore(ctx, uid, tid)
+	if block != nil {
+		return &contract.ToolResult{OK: true, Content: "无法提交：" + block.message()}
+	}
+	id := newReportID()
+	graph, _ := json.Marshal(map[string]any{"topic": topic})
+	task := &contract.Task{
+		ID:    id,
+		Graph: graph,
+		Meta: map[string]any{
+			contract.MetaIntent:    contract.IntentReport,
+			contract.MetaTopic:     topic,
+			contract.MetaKB:        kb,
+			contract.MetaUserID:    uid,
+			contract.MetaTenantID:  billingTenant,
+			contract.MetaSessionID: sid,
+		},
+	}
+	if err := h.launchCore(ctx, uid, task); err != nil {
+		return &contract.ToolResult{OK: false, Error: "报告任务提交失败: " + err.Error()}
+	}
+	data, _ := json.Marshal(map[string]string{
+		"task_id": id, "msg": "报告任务已提交开跑，请告知用户任务号并说明完成后可询问进度。",
+	})
+	return &contract.ToolResult{OK: true, Content: string(data)}
+}
@@ -524,6 +524,9 @@ func (h *Handler) StatsOverview(c *gin.Context) {
 	// 此前这里走 RecentTasks()，于是运行历史加了 topic 字段、工作台完全没跟上，
 	// 还在显示 report_<hex>；而且 RecentTasks 没有租户过滤，口径也不一致。
 	recent := h.db.RecentRuns(ctx, uid, 8)
+	if recent == nil {
+		recent = []store.RunRow{} // nil slice 会序列化成 null（不是 []）——新账号空数据曾把前端打成白屏
+	}

 	// 服务健康（与 Health 同口径：本地可判 + milvus/neo4j 经 mcp-go）。
 	services := gin.H{"gateway": true, "nats": true, "db": h.db.Enabled(), "redis": h.cache.Enabled(), "milvus": false, "neo4j": false}
@@ -55,8 +55,17 @@ func (h *Handler) VoiceStream(c *gin.Context) {
 		tenantID: tenantID(c), sessionID: sessionID(c),
 		jarvisName: jname, jarvisPersona: jpersona,
 	}
+	// 语音事件通道（JARVIS 动作/主动播报）：会话生命周期内订阅本用户主题。
+	// navigate → 转发客户端执行；announce → 对话流显示 + TTS 念出来。
+	unsubEv, everr := h.bus.SubscribeVoiceEvent(uid, sess.onVoiceEvent)
+	if everr != nil {
+		log.Printf("[voice] 订阅语音事件失败 uid=%s: %v", uid, everr) // 降级：会话照常，仅无动作/播报
+	}
 	sess.send(voice.ServerMsg{Type: voice.ServerReady})
 	sess.run()
+	if unsubEv != nil {
+		_ = unsubEv()
+	}
 	sess.stopASR() // 连接结束，收掉在跑的识别会话
 	sess.stopTTS() // 连带停掉在朗读的下行 TTS
 }
@@ -86,6 +95,9 @@ type voiceSession struct {
 	turnMu     sync.Mutex // 护住一轮的转写累计 + 提交去重（ASR 结果 goroutine 与 ClientEnd 兜底 goroutine 都访问）
 	latestText string     // 本轮最近一次转写（部分/最终）；ClientEnd 时兜底用它提交
 	submitted  bool       // 本轮是否已提交——Final 与 ClientEnd 两条路径只落一次
+
+	annMu      sync.Mutex // 护住主动播报队列（NATS 事件 goroutine 与 TTS 收尾 goroutine 都访问）
+	pendingAnn []string   // 正在朗读时到达的播报先排队，本轮 TTS 播完再念（别抢麦）
 }

 // send 下发一条控制/事件消息（文本帧，JSON）。并发安全。
@@ -0,0 +1,119 @@
+package handler
+
+import (
+	"context"
+	"log"
+
+	"github.com/sundynix/sundynix-gateway/internal/voice"
+	"github.com/sundynix/sundynix-shared/contract"
+)
+
+// 语音事件下行（JARVIS_BRAIN_DESIGN.md P2 动作通道 + P3 主动播报）：
+// 服务端任意副本经 NATS sundynix.voice.event.<uid> 发事件，本会话订阅并落地——
+//   navigate  → 转发客户端（界面跳转，客户端按白名单执行）
+//   announce  → 对话流显示 + TTS 念出来；正在朗读则排队，播完再念（别抢麦）
+
+// navigateViews 是允许下发给客户端的视图白名单（与桌面端 ViewKey 对齐）。
+// 模型/工具给出未知视图时丢弃——动作通道宁可不动，不执行任意指令。
+var navigateViews = map[string]bool{
+	"home": true, "studio": true, "kb": true, "runs": true, "report": true, "memory": true, "usage": true,
+}
+
+// onVoiceEvent 处理一条发给本用户的语音事件（NATS 订阅回调，会话生命周期内挂载）。
+func (s *voiceSession) onVoiceEvent(ev *contract.VoiceEvent) {
+	switch ev.Action {
+	case "navigate":
+		if !navigateViews[ev.View] {
+			log.Printf("[voice] 丢弃未知视图的 navigate uid=%s view=%q", s.uid, ev.View)
+			return
+		}
+		s.send(voice.ServerMsg{Type: voice.ServerAction, Action: "navigate", View: ev.View, TaskID: ev.TaskID})
+	case "announce":
+		if ev.Text == "" {
+			return
+		}
+		s.announce(ev.Text)
+	}
+}
+
+// announce 主动播报一段话：正在朗读则入队（speak/上一条播报收尾时 flush），空闲则立刻念。
+func (s *voiceSession) announce(text string) {
+	s.ttsMu.Lock()
+	busy := s.tts != nil
+	s.ttsMu.Unlock()
+	if busy {
+		s.annMu.Lock()
+		s.pendingAnn = append(s.pendingAnn, text)
+		s.annMu.Unlock()
+		return
+	}
+	go s.speakAnnounce(text)
+}
+
+// flushAnnounces 取出并播报排队的第一条（TTS 收尾处调用；逐条播，每条播完又会走到这里）。
+func (s *voiceSession) flushAnnounces() {
+	s.annMu.Lock()
+	if len(s.pendingAnn) == 0 {
+		s.annMu.Unlock()
+		return
+	}
+	text := s.pendingAnn[0]
+	s.pendingAnn = s.pendingAnn[1:]
+	s.annMu.Unlock()
+	go s.speakAnnounce(text)
+}
+
+// speakAnnounce 把一段播报文本念出来：对话流先显示（announce 消息），再走与 speak() 同构的
+// TTS 会话（登记到 s.tts → 客户端可打断；首帧 speaking、收尾 tts_end——客户端状态机零新分支）。
+// TTS 未配置/启动失败则只显示文字（静默降级，播报不该弄挂会话）。
+func (s *voiceSession) speakAnnounce(text string) {
+	s.send(voice.ServerMsg{Type: voice.ServerAnnounce, Text: text})
+	if !s.cfg.TTSEnabled() {
+		return
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	ts, err := voice.StartTTS(ctx, s.cfg)
+	if err != nil {
+		cancel()
+		log.Printf("[voice] 播报 TTS 启动失败 uid=%s: %v", s.uid, err)
+		return
+	}
+	// 登记为当前 TTS：barge-in/会话收尾都能掐掉它；已有别的在念（竞态）就放弃朗读只留文字。
+	s.ttsMu.Lock()
+	if s.tts != nil {
+		s.ttsMu.Unlock()
+		cancel()
+		ts.Close()
+		return
+	}
+	s.tts = ts
+	s.ttsCancel = cancel
+	s.ttsMu.Unlock()
+
+	_ = ts.Speak(text)
+	_ = ts.Finish()
+
+	first := true
+	for pcm := range ts.Audio() {
+		if first {
+			s.send(voice.ServerMsg{Type: voice.ServerSpeaking})
+			first = false
+		}
+		s.sendAudio(pcm)
+	}
+	if e := ts.Err(); e != nil {
+		log.Printf("[voice] 播报 TTS 出错 uid=%s: %v", s.uid, e)
+	}
+	s.send(voice.ServerMsg{Type: voice.ServerTTSEnd})
+
+	s.ttsMu.Lock()
+	if s.tts == ts {
+		s.tts = nil
+		s.ttsCancel = nil
+	}
+	s.ttsMu.Unlock()
+	ts.Close()
+	cancel()
+	s.flushAnnounces() // 队列里还有播报就接着念
+}
@@ -25,8 +25,10 @@ func voiceSystemPrompt(name, persona string) string {
 	if n == "" {
 		n = defaultJarvisName
 	}
-	s := "你是 " + n + "——用户的私人语音助手。这是语音对话，务必简短：先直接给结论，" +
-		"一两句话说清，通常不超过三句，别铺垫、别列清单、别念代码、别复述问题。口语化、自然。"
+	s := "你是 " + n + "——用户的私人语音助手，也是这套平台的中枢：你能直接查用户最近的任务、" +
+		"查某个任务的状态和结果、派发报告生成任务（相应工具会提供给你，需要就调，别凭空编造任务状态）。" +
+		"这是语音对话，务必简短：先直接给结论，一两句话说清，通常不超过三句，别铺垫、别列清单、" +
+		"别念代码、别复述问题。口语化、自然。派了任务就告诉用户已开跑、稍后可以问进度，不要干等。"
 	if p := strings.TrimSpace(persona); p != "" {
 		s += "\n你的语气与人设：" + p
 	} else {
@@ -37,12 +39,16 @@ func voiceSystemPrompt(name, persona string) string {

 // buildVoiceGraph 把一句转写组成最简可执行图：input(转写) → agent(用户的 JARVIS，带其名字+人设)。
 // 与前端画布 exportDsl 同构（kind=input/agent、config.text/system），dispatcher 直接吃。
+// autonomous=true：走 ReAct 自主工具（含 platform_* 平台工具族）——JARVIS 是大脑中枢不是应声虫，
+// 见 JARVIS_BRAIN_DESIGN.md。不需要工具的闲聊模型直接作答，时延不受影响。
 func buildVoiceGraph(query, name, persona string) json.RawMessage {
 	g := map[string]any{
 		"version": "voice-1",
 		"nodes": []map[string]any{
 			{"id": "voice_in", "kind": "input", "config": map[string]any{"text": query}},
-			{"id": "voice_agent", "kind": "agent", "config": map[string]any{"system": voiceSystemPrompt(name, persona)}},
+			{"id": "voice_agent", "kind": "agent", "config": map[string]any{
+				"system": voiceSystemPrompt(name, persona), "autonomous": true,
+			}},
 		},
 		"edges": []map[string]any{
 			{"source": "voice_in", "target": "voice_agent"},
@@ -112,6 +112,7 @@ func (s *voiceSession) speak(taskID string) {
 	s.ttsMu.Unlock()
 	ts.Close()
 	cancel()
+	s.flushAnnounces() // 朗读期间排队的主动播报，本轮播完接着念（别抢麦）
 }

 // stopTTS 掐掉当前下行 TTS（打断 / 会话结束）。幂等。Close 后 Audio 关闭 → 音频泵自然收尾。
@@ -71,6 +71,22 @@ func (b *Bus) CallTool(ctx context.Context, subject string, call *contract.ToolC
 	return b.inner.CallTool(ctx, subject, call)
 }

+// ServeTool 以队列组订阅一族工具主题并按调用分发（平台工具族：gateway 自己当工具提供方，
+// 见 JARVIS_BRAIN_DESIGN.md §2.1）。返回 drain 供优雅停机。
+func (b *Bus) ServeTool(subject, queue string, h sharedbus.ToolHandler) (func(context.Context), error) {
+	return b.inner.ServeTool(subject, queue, h)
+}
+
+// PublishVoiceEvent 给某用户的语音会话发事件（JARVIS 动作/主动播报；无会话则静默丢弃）。
+func (b *Bus) PublishVoiceEvent(uid string, ev *contract.VoiceEvent) error {
+	return b.inner.PublishVoiceEvent(uid, ev)
+}
+
+// SubscribeVoiceEvent 订阅某用户的语音事件（语音 WS 会话生命周期内挂载）。
+func (b *Bus) SubscribeVoiceEvent(uid string, onEvent func(*contract.VoiceEvent)) (func() error, error) {
+	return b.inner.SubscribeVoiceEvent(uid, onEvent)
+}
+
 // Ping 同步探测某节点健康（如 dispatcher 心跳主题）。无人应答 / 超时即返回错误（视为下线）。
 func (b *Bus) Ping(ctx context.Context, subject string) ([]byte, error) {
 	return b.inner.Ping(ctx, subject)
@@ -73,6 +73,7 @@ func New(db *store.Postgres, cache *store.Redis, bus *nats.Bus, blobStore *blob.
 		api.GET("/reports/:id/download", middleware.AuthFromHeaderOrQuery(), h.ExportReport)   // 兼容旧入口（默认 docx）
 		api.POST("/billing/callback/:channel", h.PaymentCallback)                            // 支付回调（渠道服务器带不了 Bearer；渠道验签是唯一的门）
 		api.GET("/voice/stream", middleware.AuthFromHeaderOrQuery(), h.VoiceStream)           // 语音会话 WebSocket（?token= 鉴权，WS 带不了 Bearer 头）
+		api.GET("/local/runner", middleware.AuthFromHeaderOrQuery(), h.LocalRunner)           // 桌面本地执行器注册 WebSocket（JARVIS 本地的手）

 		// —— 受保护：owner 作用域业务，必须携带有效 JWT ——
 		p := api.Group("", middleware.RequireAuth())
@@ -100,6 +100,18 @@ type AdminEval struct {

 // TaskOwner 按 task_id 返回提交者 user.id（供 SSE/导出等公开 by-id 端点做归属校验）。
 // 跨租户查（WithoutTenant）：这些端点无租户上下文，靠 owner 判权。不存在返回空串。
+// TaskTopic 报告类任务的主题（graph 顶层 topic；普通任务无此字段返回空）。主动播报用。
+func (p *Postgres) TaskTopic(ctx context.Context, taskID string) string {
+	if p.db == nil || taskID == "" {
+		return ""
+	}
+	var topic string
+	p.db.WithContext(WithoutTenant(ctx)).Table("sundynix_task").
+		Where("task_id = ? and deleted_at is null", taskID).
+		Select("coalesce(graph->>'topic','')").Scan(&topic)
+	return topic
+}
+
 func (p *Postgres) TaskOwner(ctx context.Context, taskID string) string {
 	if p.db == nil || taskID == "" {
 		return ""
@@ -35,6 +35,10 @@ type ServerMsg struct {
 	TaskID string `json:"task_id,omitempty"`
 	// error：出错文案
 	Msg string `json:"msg,omitempty"`
+	// action：JARVIS 让客户端执行的界面动作（P2 动作通道，见 JARVIS_BRAIN_DESIGN.md §2.2）。
+	// 目前仅 navigate：Action="navigate" + View（+可选 TaskID 聚焦某任务）。客户端按白名单执行。
+	Action string `json:"action,omitempty"`
+	View   string `json:"view,omitempty"`
 }

 // 服务端消息类型。
@@ -46,6 +50,8 @@ const (
 	ServerSpeaking   = "speaking"   // Agent 开始出声（首段 TTS 音频将至）
 	ServerTTSEnd     = "tts_end"    // 本轮 TTS 播放完毕
 	ServerError      = "error"      // 出错
+	ServerAction     = "action"     // 界面动作指令（navigate 等，客户端白名单执行）
+	ServerAnnounce   = "announce"   // 主动播报（text 显示到对话流；随后照常走 speaking/音频/tts_end）
 )

 // 音频格式（与火山 ASR/TTS 约定，客户端按此采集/播放）。