Blizzard
94 lines
7.1 KiB
Markdown
94 lines
7.1 KiB
Markdown
# 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 验通**（真读文件+离线降级+沙箱逃逸单测全拦） |
|
||
| **P5 常驻会话** | 每句一 task → 长驻 companion session（现靠 history 串联已够用，不急） | dispatcher | 暂缓 |
|
||
|
||
每步独立可用：P1 做完立刻能"嘴遥控平台"（问任务、派报告）。
|
||
|
||
## 5. P1 验收
|
||
|
||
- 语音问「我最近的任务都什么状态」→ JARVIS 调 `platform_recent_tasks` 报出真实列表。
|
||
- 语音说「帮我生成一份 XX 报告」→ JARVIS 调 `platform_gen_report` → 回 task_id →「已开跑」；任务在运行页可见、计费正常扣。
|
||
- 越权测试：构造 task_id 查他人任务 → 拒绝。
|