小马办公室（Pony Office）产品需求文档（PRD）

一个 Marvis 式多 Agent 桌面应用：用户向「领队马」下达任务，领队马在一间温暖质感的虚拟办公室里，把活儿派给各只职能小马协作完成。

项	内容
文档版本	v1.0
日期	2026-06-10
产品定位	演示级但闭环真实（真 LLM、真数据分析）
目标场景	电信培训演示

1. 产品概述

1.1 一句话描述

一个 Electron 桌面应用：画面是一间 2D 侧视的极简风办公室，里面住着若干只「小马 Agent」。用户像老板一样给领队马发消息（例如上传一份 xlsx 数据并提出分析需求），领队马理解意图后将任务拆解、派发给数据马、报表马等职能小马，整个协作过程以动画形式在办公室场景中透明演出，最终产出可视化报告。

1.2 核心价值

多 Agent 协作可视化：把抽象的 LLM 多 Agent 编排变成「小马在办公室里跑动、对话、干活」的具象演出，演示感染力强。
真实闭环：从 xlsx 上传 → text-to-SQL 分析 → ECharts 报表，全程真实执行，不是预录脚本。
可扩展的小马体系：用户可「招聘」自定义小马，通过皮肤、Skill（prompt）、MCP（工具）三要素自由组装新职能。
可控可信的 Agent 执行边界：通过审批、权限策略和审计日志，把文件写入、删除、脚本执行、MCP 调用等高风险动作纳入人类可见、可拒绝、可追溯的治理流程。

1.3 范围声明（明确不做）

❌ 用户系统、登录、权限
❌ 多人协作、云端部署、运维监控
❌ 隐藏的「假结果」演示兜底脚本（失败就优雅认错，保持真实）
❌ 真实邮件发送（SMTP）等高演示风险的外部副作用

2. 用户与场景

2.1 目标用户

主要：培训演示者（操作者本人）
次要：培训听众（观看者，需要"一眼看懂"）

2.2 核心用户故事

作为演示者，我上传一份电信业务 xlsx（各营业厅月度宽带/套餐办理量、用户增长、投诉率），对领队马说："分析一下各营业厅的业务表现，给我出一份报告。"

领队马走到数据马工位旁，气泡显示派单内容；数据马头顶出现进度条，对数据库执行 SQL 分析；完成后领队马把结果转交报表马；报表马生成带 ECharts 图表的 HTML 报告，"钉"在办公室白板上；我点开报告面板查看，并可导出 PDF、让文件马归档到工作区目录。

2.3 次要用户故事

作为演示者，我点击办公室的空工位，「招聘」一只新小马：起名、选皮肤（调色板+配件）、勾选 Skill、绑定 MCP server，保存后它立即入驻办公室并可接单。
作为演示者，我让文书马根据分析结果写一份工作总结邮件草稿。
作为演示者，我让文件马把生成的报告归档到指定文件夹。

3. 功能需求

3.1 小马体系

3.1.1 预置阵容（5 预置 + 1 空工位）

小马	职能	能力实现	可删除
领队马	理解用户意图、拆解任务、派单、汇总结果	内置「派单」工具（dispatch tool call）	否
数据马	数据分析	text-to-SQL：读取表 schema + 抽样行 → 写 SQL 查 SQLite → 解读结果	否
报表马	生成可视化报告	内置报表工具：产出 HTML + ECharts，渲染到报告面板，可导出 PDF	否
文件马	本地文件操作	官方 filesystem MCP server（限定工作区目录）	否
文书马	写总结、邮件草稿、文案	纯 LLM 能力（无外部工具）	否
（空工位）	——	点击即进入「招聘新小马」流程	——

预置小马不可删除，但可换皮肤、可追加 Skill 和 MCP 绑定。
办公室上限 6 只小马（5 预置 + 1 自定义），侧视场景横向容纳。

3.1.2 小马数据模型

一只小马 = 名字 + 皮肤 + N 个 Skill + N 个 MCP server 绑定

Pony {
  id: string
  name: string            // 如"数据马"
  role: string            // 职能简述，领队马派单时参考
  builtin: boolean        // 预置马不可删除
  skin: {
    palette: PaletteId    // 预设调色板之一
    accessories: AccessoryId[]  // 配件槽
  }
  skills: SkillId[]       // 勾选的 skill（markdown prompt）
  mcpServers: McpServerId[]   // 绑定的全局 MCP server
  builtinTools: ToolId[]  // 预置马专属的内置工具（SQL/报表/派单等）
}

3.1.3 Skill 体系

一个 Skill = 一份 markdown 文档（职责描述 + 工作方法 + 输出格式要求）。
勾选后注入该小马的 system prompt。
提供预置 Skill 库（与预置马职能对应），同时支持用户新建/编辑自定义 Skill（应用内 markdown 编辑器）。
能力型扩展（查天气、操作文件等）一律走 MCP，不另设插件体系。

3.1.4 MCP 配置

全局 MCP server 列表：应用设置中维护（表单填 name / command / args / env，底层存 JSON 结构于 SQLite）。
每马勾选绑定：在小马编辑页勾选它能使用哪些 server。
预装演示用 server：官方 filesystem server（绑定文件马，限定「办公室工作区」目录）。
MCP server 以 stdio 子进程方式由主进程托管，工具列表自动发现并合并进小马的工具集。

3.1.5 招聘新小马（自定义小马）

流程：点击空工位 → 弹出招聘表单 →

起名 + 填写职能描述（领队马派单时据此判断给谁）
选皮肤：调色板（5 套预设）+ 配件槽
勾选 Skill（预置库 + 自定义）
勾选 MCP server 绑定
保存 → 新小马以入场动画入驻空工位，立即可被领队马派单

3.2 对话与任务流

3.2.1 对话入口

用户只与领队马对话：底部一条输入框（像老板给主管发消息）。
支持文字输入 + xlsx 文件上传（拖拽或点击附件按钮）。
点击其他小马仅查看状态与配置，不可直接聊天。

3.2.2 任务编排（领队马派单）

编排实现：Vercel AI SDK 的 tool-calling 循环 + 自写薄层派单逻辑。
领队马的工具集中含 dispatch(ponyId, taskBrief) 工具：每次派单即一次 tool call。
被派单的小马以自己的 system prompt（角色 + skills）+ 工具集（内置工具 + 绑定的 MCP 工具）执行子任务，结果回传领队马。
领队马可串联多次派单（如：数据马结果 → 转交报表马），最终向用户汇报。

3.2.3 数据分析链路（核心闭环）

用户上传 xlsx
  → 主进程 SheetJS 解析 → 灌入 SQLite（每个 sheet 一张表）
  → 数据马获得：表 schema + 每表抽样 5 行
  → LLM 编写 SQL（只读 SELECT）→ 执行 → 拿到结果集
  → LLM 解读结果，形成分析结论
  → 领队马转交报表马
  → 报表马产出 HTML + ECharts 报告 → 渲染到报告面板

演示数据：电信业务数据（各营业厅月度宽带/套餐办理量、用户增长、投诉率），预制并围绕它调优 prompt。
SQL 限制：只允许 SELECT；执行失败时把报错信息回喂给数据马自动重试（最多 2 次）。

3.2.4 报告产出

形态：应用内「报告面板」展示 HTML 报告（想象成钉在办公室白板上），图表用 ECharts。
支持导出 PDF（Electron printToPDF）。
报告文件可由文件马归档至工作区目录。

3.2.5 失败兜底（三道防线）

SQL / 工具执行失败 → 报错自动回喂小马重试（最多 2 次）。
重试耗尽 → 小马在场景里播放「挠头道歉」动画，气泡说明失败原因，请用户换个问法。
不做任何隐藏假结果脚本，保持闭环真实。

3.3 协作可视化（全透明）

场景动画演出：领队马走到目标小马工位旁 → 头顶气泡显示派单摘要 → 干活的小马头顶进度指示 → 完成后成果传递动画（如报表马把报告钉上白板）。
侧边任务日志：右侧可收起的面板，文字流展示完整细节（派单内容、SQL 语句、工具调用、结果摘要），供想看细节的观众查看。
动画由主进程的 Agent 事件流（IPC 推送）驱动：task_dispatched / tool_call_started / tool_call_finished / task_completed / task_failed 等。

3.4 安全审批与权限治理中心（Approval & Governance Center）

本模块为整个 Agent 系统提供独立可信边界，不属于某个数字员工，也不替代现有小马配置。所有高风险工具调用在进入真实执行前先经过主进程风控判断；需要人类决策时，由主进程发起审批请求，渲染进程只负责展示和回传一次性审批结果。

3.4.1 审批队列

高风险动作不得直接执行，需生成 approval_required 事件或等价 IPC 请求。
审批请求至少包含：请求 id、发起 runId/taskId、发起小马、工具名、资源目标、参数摘要、风险等级、触发原因、创建时间。
用户可在审批中心或弹窗中选择「允许」或「拒绝」。
拒绝应作为正常失败路径回传给 Agent，任务日志和场景状态要保持一致，不得自动绕过或重试同一危险动作。

3.4.2 权限策略

支持按数字员工配置权限边界：
- 文件读取范围。
- 文件写入范围。
- 是否可调用 MCP。
- 是否可运行 Skill script。
- 是否可导出/归档报告。
支持策略等级：
- 只读：仅允许查询、读取、查看报告等无副作用操作。
- 工作区写入：允许写入办公室工作区内的新文件。
- 需审批写入：覆盖、移动、删除、批量写入、脚本执行等动作必须审批。
- 禁止危险操作：直接拒绝删除、越界路径、敏感环境变量读取、任意命令执行等行为。
预置小马提供默认策略；自定义小马保存时必须有明确策略，不能默认获得高权限。

3.4.3 工具调用风控

所有 MCP/tool call 入参在主进程预检查，外部工具结果、上传文件、LLM 输出均视为不可信输入。
文件路径需 canonicalize 后校验是否位于工作区内，拒绝 ../、符号链接逃逸和工作区外路径。
覆盖、删除、移动文件必须触发审批。
Skill script 执行默认触发审批；涉及网络、写文件、子进程、环境变量访问时提高风险等级。
访问疑似敏感 env（如 API key、token、password、secret、Authorization）直接拒绝，不进入审批。
工具调用真实执行前必须绑定一次性授权 token，防止渲染进程伪造长期权限。

3.4.4 审计日志

每次审批和高风险拦截必须记录审计日志：时间、runId、taskId、发起小马、工具名、参数摘要、资源目标、风险等级、用户决策、最终执行结果。
审计日志应可在治理中心查看、筛选和复制摘要，用于演示「AI Agent 可控、可追溯」。
日志必须脱敏，不能记录完整 API key、token、password、Authorization、MCP env 或用户上传数据全文。

3.4.5 一次性授权 token

主进程生成短期、一次性 approvalToken，绑定请求 id、动作类型、工具名、资源目标和过期时间。
渲染进程只回传用户决策和 token，不获得长期权限。
主进程执行前校验 token 是否存在、未过期、未使用、动作和目标完全匹配。
token 使用后立即失效；超时或窗口关闭视为拒绝。

4. 视觉与交互设计

4.1 设计风格

有机极简主义 × 高级室内设计：

色彩：暖色调中性色——亚麻白、燕麦、驼色、赭石、鼠尾草绿、赤陶，点缀黄铜金。
质感：UI 面板用 CSS 实现亚麻纹理、皮革质感卡片、黄铜描边、柔和漫射阴影。
氛围：宁静且专业的办公室——暖光、绿植、木质工位、白板。
字体：衬线标题 + 无衬线正文的高级编辑感搭配（中文需选对应气质字体）。

4.2 场景（PixiJS）

视角：2D 侧视、横向展开的办公室，轻微透视感（非等距）。
小马：程序化矢量绘制（Pixi Graphics 几何体——圆润色块 + 简约线条），动画为骨骼式程序动画（位移/缩放/摇摆/眨眼/呼吸 idle）。
场景元素：木质工位 × 6、白板（报告入口）、绿植、暖色吊灯、窗户光影。
动画清单（按优先级）：idle 呼吸/眨眼、行走、对话气泡、干活（打字摆动）、进度指示、成果传递、挠头道歉、新马入场。

4.3 皮肤系统

调色板（5 套预设，锁定在设计体系内）：亚麻白、驼色、赭石、鼠尾草绿、赤陶。
配件槽：眼镜、领结、贝雷帽、黄铜吊牌（可多选，不同槽位）。
不开放自由调色盘，保证任意组合不破坏整体质感。

4.4 UI 分层

层	技术	内容
场景层	PixiJS canvas	办公室、小马、气泡、光影、动画
UI 层	React + HTML/CSS	底部对话输入条、右侧任务日志、报告面板、小马配置页、招聘表单、全局设置（MCP / 模型）

气泡归场景层（跟随小马位置）；一切表单、长文本、报告归 UI 层。
安全审批与权限治理中心归 UI 层展示，但审批请求生成、策略判断、token 校验和真实执行必须全部在主进程完成。

4.5 音效（加分项）

环境音：柔和办公室底噪（可开关）。
事件音：键盘声（小马干活）、纸张声（报告产出）、轻快提示音（任务完成）。

5. 技术架构

5.1 技术栈

层	选型
应用壳	Electron + Vite + React + TypeScript
场景渲染	PixiJS v8
Agent 编排	Vercel AI SDK（tool-calling 循环 + 流式输出）+ 自写派单薄层
LLM	国内模型（DeepSeek / 通义 / Kimi 等）走 OpenAI 兼容接口，可配置切换
MCP	`@modelcontextprotocol/sdk`（官方 TS SDK），stdio 子进程托管
数据库	SQLite（better-sqlite3）
表格解析	SheetJS（xlsx）
图表	ECharts

5.2 进程边界

主进程：Vercel AI SDK / LLM 调用、MCP client 与子进程托管、SQLite、文件操作、xlsx 解析、报表 HTML 生成、PDF 导出。
渲染进程：纯 UI（Pixi 场景 + React 面板），不直接接触 Node API。
IPC：渲染进程发起任务请求；主进程以事件流推送 Agent 进度事件，驱动场景动画与任务日志。

5.3 持久化

单一 SQLite 文件承载全部状态：小马配置（皮肤/Skill/MCP 绑定）、Skill 库、全局 MCP server 列表、对话历史、上传的数据表。一个文件拷走即可整体迁移。
审批策略、审批记录、审计日志也存入 SQLite；敏感字段只保存脱敏摘要或哈希，不保存明文密钥。
API key 等敏感信息走 .env，不入库。

5.4 安全边界

数据马 SQL 只允许 SELECT。
filesystem MCP 限定在「办公室工作区」目录内。
删除 / 覆盖类文件操作前弹确认框。
高风险工具调用必须经过审批与权限治理中心：主进程发起 approval_required，渲染进程展示决策，主进程用一次性 token 校验后执行。
访问敏感环境变量、工作区外路径、符号链接逃逸、未授权 MCP/Skill script 调用应直接拒绝。
渲染进程启用 contextIsolation，禁用 nodeIntegration。

6. 里程碑建议

阶段	内容	验收标准
M1 骨架	Electron + Vite + React + Pixi 脚手架；侧视办公室场景；3 只矢量小马 idle 动画	应用启动，办公室有呼吸感
M2 闭环	LLM 接入；领队马派单；xlsx → SQLite；数据马 text-to-SQL；报表马 ECharts 报告	核心用户故事（2.2）端到端跑通
M3 演出	协作动画全套（行走/气泡/进度/传递/道歉）；任务日志面板；失败重试	协作过程全透明可看
M4 扩展	招聘新小马；皮肤系统；Skill 库与编辑器；MCP 配置 UI；文件马 + 文书马；审批与权限治理基础能力	次要用户故事（2.3）跑通，高风险操作可审批、可拒绝、可审计
M5 打磨	音效、光影、报告 PDF 导出、电信演示数据调优、演示彩排	完整演示彩排一次通过

7. 验收清单（演示日检查表）

上传电信 xlsx → 领队马派单 → 数据马 SQL 分析 → 报表马出 ECharts 报告，全程动画演出无卡顿
任务日志可展开查看 SQL 与工具调用细节
现场招聘一只新小马（皮肤 + Skill + MCP）并成功接单
文件马把报告归档到工作区目录（含删除确认框演示）
高风险操作进入审批队列，用户允许/拒绝后结果正确回传，审计日志可查
故意提一个会失败的问题，验证重试与「挠头道歉」流程
报告导出 PDF 成功
断网 / API 超时情况下应用不崩溃，有明确错误提示

附录 A：关键决策记录

决策点	选择	备选与理由
产品深度	演示级但闭环真实	不做产品化外围，但拒绝假演示
形态	Electron 桌面应用	让 filesystem MCP 等本地能力有用武之地
LLM	国内模型 + OpenAI 兼容协议	代码只依赖 OpenAI SDK 格式，随时可换
编排	Vercel AI SDK + 自写薄层	比 LangGraph 轻、比纯手写省事，自带 MCP client 支持
数据分析	xlsx 入库 + 模型写 SQL	比预置聚合工具上限高；演示数据固定，SQL 出错率可控
数据库	SQLite	生态最稳、踩坑最少
美术	程序化矢量小马	换肤变成纯数据问题，规避美术产能风险
视角	2D 侧视	实现成本比等距低一半以上，更贴极简风
对话入口	仅领队马	保护「领队派单」核心叙事，省多会话管理
失败处理	重试 + 优雅认错	不做假结果脚本，保持真实
风险治理	人类审批 + 权限策略 + 审计日志	让可扩展 Agent 系统在演示和真实使用中保持可控、可拒绝、可追溯

FilesExpand file tree

prd.md

Latest commit

History