# sundynix-agentix · JARVIS 大脑中枢设计文档

> 版本：2026-07-24
> 定位：把 JARVIS 从「任务系统的语音皮肤」升级为「平台的常驻大脑中枢」——编排、报告、知识库、本地文件、App 界面都只是它手里的工具（Claw/OpenClaw 式全局控制感）。
> 配套文档：`LOCAL_AGENT_DESIGN.md`（本地的手，双平面）、`VOICE_DESIGN.md`（耳朵和嘴）、`ARCHITECTURE_DESIGN.md`（总览）

---

## 0. 一句话结论

> **角色反转：把编排引擎从"执行主体"降级为 JARVIS 的一个工具（tool），把 JARVIS 从"任务的语音入口"升级为持有全部工具的常驻 ReAct 大脑。**
>
> 这是接线工程，不是重构工程——推理循环（react_agent.go）、语音通道、会话记忆、人格、工具协议、HITL 全部现成，缺的只有三条线：平台工具族、客户端动作通道、主动播报器。

## 1. 现状 vs 目标

**现状**：用户说话 → 每句话变一个 task → 编排引擎执行 → 念结果。JARVIS 从属于任务系统。
**目标**：JARVIS = 常驻中枢 agent。你说「看看部署状态」，它自己决定是查任务、跑命令、还是调编排；任务跑完它主动开口告诉你。任务系统从属于它。

### 已就绪的器官（盘点）

| 中枢需要的 | 已有的 | 位置 |
|---|---|---|
| 推理循环 | ReAct 循环 + `list_tools` 动态工具发现（加工具零改循环） | `dispatcher/internal/eino/react_agent.go` |
| 耳朵/嘴 | 语音 WS 全双工 + 连续对话（VAD 断句/自动重听） | `gateway/internal/handler/voice.go` |
| 短期记忆 | sessionID → fetchHistory/appendHistory 闭环 | orchestrator.go |
| 人格 | 每用户 UserJarvis（名字/人设/自带豆包） | `store/user_jarvis.go` |
| 工具协议 | 注册表 + `agent_exposed` + inject 参数 | `mcp-go/internal/mcp/gateway.go` |
| 提交关卡 | `preflightCore`/`launchCore`（无 gin，语音已复用） | `handler/task_handler.go` |
| 安全闸 | HITL 审批 + 预算护栏 + 审计 | 全栈 |
| 本地的手 | 双平面设计（档 A/B） | `LOCAL_AGENT_DESIGN.md` |

## 2. 三条缺的线

### 2.1 平台工具族 `platform_*`（让 JARVIS 操作平台本身）

新增第三个工具提供方：**gateway 自己**。理由：平台操作的权威（提交关卡、归属校验、计费）都在 gateway，工具就该长在权威所在地——而不是让 mcp-go 绕一圈回来调 gateway。

- 协议：`contract` 加 `SubjectToolsPlatform = "sundynix.tools.platform"`（+All/Queue/ToolSubjectPlatform），与 go/py 同族。
- gateway 用 `bus.ServeTool` 起一个迷你注册表（照抄 mcp-go 的 toolDef 模式：唯一事实源，dispatch 与 list_tools 共用）。
- dispatcher `agentTools` 多发现一路：`discoverTools(contract.ToolSubjectPlatform, …)`——**一行**。

**首批工具**（全部 inject `user_id`，严格归属校验）：

| 工具 | 说明 |
|---|---|
| `platform_recent_tasks` | 最近任务列表（状态/主题/耗时），答"我刚才那些任务怎么样了" |
| `platform_task_status(task_id)` | 单任务状态 + 输出摘要（TaskOwner 校验归属，别人的任务不可见） |
| `platform_gen_report(topic, kb?)` | 提交报告任务——**必须走 preflightCore/launchCore 同一关卡**（预算/积分/落库），返回 task_id |

后续扩展（同一注册表加条目即可）：`platform_run_orchestration(graph_id)`（待编排图有服务端存储后）、`platform_search_kb`、`platform_usage_today`。

### 2.2 客户端动作通道（让 JARVIS 控制界面与本机）

语音 WS 加一类下行消息：`ServerMsg{type:"action", action:"navigate", view:"runs", task_id:…}`。

- 客户端 VoiceClient 加 `onAction` 回调 → App 层 dispatcher 执行（切页面/打开面板/聚焦任务）。HUD 从显示器变驾驶舱。
- **`local.*`（读文件/跑命令）走同一条通道**下发到 Wails Go host 执行——即 `LOCAL_AGENT_DESIGN.md` 档 A 的落点，两个设计在此汇合。
- 安全：动作白名单（navigate 等 UI 动作低危先行）；`local.*` 按该文档 §8 的门禁（cwd 沙箱/HITL/仅桌面端）。

### 2.3 主动播报器（中枢与工具的本质区别）

它会先开口：任务跑完/失败、部署红了 → JARVIS 主动说"先生，报告好了"。

- 零件全齐：JetStream 有任务终态事件（status 回写已持久化）、语音 WS 常连、TTS 现成。
- 新增一个**值班推送器**：订阅当前语音会话用户的任务终态 → 判断值不值得开口（本会话触发的任务优先；免打扰规则）→ 文本 → 现有 TTS 通道播报 + 对话流插一条。
- 与连续对话状态机合流：播报只在 ready/listening 空闲时插入，说话中排队，别抢麦。

## 3. 安全边界（权力越大越要收紧）

1. 每次工具调用过 ToolPolicy；破坏性操作（exec/写文件/会烧钱的编排提交）过 HITL。
2. `platform_*` 一律 inject user_id + 服务端归属校验，模型不可指定别人的资源。
3. `platform_gen_report` 等提交类工具走 preflightCore（预算/积分硬拦截），JARVIS 不能绕过计费花钱。
4. `local.*` 只对有在线本地 runner 的桌面会话开放（见 LOCAL_AGENT_DESIGN §8）。
5. 全部动作落审计/轨迹（mcpTool 已自动落 ExecEvent span）。

## 4. 落地阶段

| 阶段 | 内容 | 改动面 | 状态 |
|---|---|---|---|
| **P1 平台工具族** | contract 加 platform subject；gateway 迷你工具注册表（recent_tasks/task_status/gen_report）；dispatcher 多发现一路 | shared 一处 / gateway 新文件 / dispatcher 一行 | **✅ 2026-07-24 live 验收全过**（真实数据/派报告走关卡/越权拒绝/积分硬拦截实测） |
| **P2 动作通道** | ServerMsg action + 客户端 onAction + navigate 白名单（platform_open_view → NATS 语音事件 → WS） | protocol/voice.ts/App | **✅ 2026-07-24 live 验通**（“打开运行页”→界面真切） |
| **P3 主动播报** | 任务终态 → announce 语音事件 → 对话流 + TTS（正朗读则排队不抢麦；prev 比对挡重投重播） | main 状态消费 + voice_event.go | **✅ 2026-07-24 live 验通**（报告跑完 JARVIS 主动开口） |
| **P4 本地的手** | LOCAL_AGENT_DESIGN 档 A：`local_list_dir/read_file`（platform 注册表）→ NATS `local.exec.<uid>` → gateway runner WS → 桌面 Go host 沙箱执行；桌面设置「本地文件访问」显式开关；`cmd/localsim` 联调工具 | gateway 2 新文件 / desktop runner+设置 | **✅ 2026-07-24 live 验通**（真读文件+离线降级+沙箱逃逸单测全拦） |
| **P4.2 能动的手** | `local_write_file` / `local_exec`：桌面端**原生确认框逐次审批**（默认拒绝/60s 超时即拒）+ 硬黑名单（删库/提权/管道下载执行/写系统路径/装开机项/摸凭据，点同意也不执行）+ 独立开关；工具自报 `timeout_sec` 突破 dispatcher 默认 3s（审批要等人） | desktop `localexec.go` / platform 注册表 / dispatcher 超时机制 | **✅ 2026-07-25 live 验通**（写脚本+执行链式两步，文件真落磁盘；黑名单 20 条单测全拦） |
| **P4.3 调度** | `sundynix_schedule` 表 + leader 锁 ticker（30s 扫）+ `platform_schedule_create/list/cancel`；存自然语言指令，到点走语音同一条关卡执行并主动播报；先推进后提交防重复烧钱，停机错过的**不补跑** | store/schedule.go、handler/schedule_tick.go | **✅ 2026-07-25 live 验通**（到点自动触发→自主调 local_exec→真跑命令→出结果） |
| **P5 常驻会话** | 每句一 task → 长驻 companion session（现靠 history 串联已够用，不急） | dispatcher | 暂缓 |

每步独立可用：P1 做完立刻能"嘴遥控平台"（问任务、派报告）。

## 5. P1 验收

- 语音问「我最近的任务都什么状态」→ JARVIS 调 `platform_recent_tasks` 报出真实列表。
- 语音说「帮我生成一份 XX 报告」→ JARVIS 调 `platform_gen_report` → 回 task_id →「已开跑」；任务在运行页可见、计费正常扣。
- 越权测试：构造 task_id 查他人任务 → 拒绝。