sundynix-agentix/JARVIS_BRAIN_DESIGN.md

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 查他人任务 → 拒绝。