assistant/docs/REFERENCE_PENGUINUNIOS.md

对照：同事的 PenguinUniOS（D:\qiekj\agent-a2a）

2026-09-17 调研。同一公司同类产品的另一条实现路线，用来对齐桌面端形态、借鉴工程做法。不是要照搬全部。

1. 它是什么

三端 monorepo（npm workspaces，Node 24，uv 管 Python 3.12）：

端	栈	职责
apps/learning 学习端	FastAPI + React/TS/Vite；SQLite（documents JSON 表）+ PostgreSQL 17（知识）；Playwright + 自研观察 JS	探索学校系统 → 证据 → 模型评判 / 人审 → Ed25519 签名发布「能力包」（form-v1 等）
apps/desktop 桌面端	Electron 44 + React 19 + TS；Vite / esbuild；两个 uv 虚拟环境的 Python worker 用 PyInstaller 冻结随包分发，stdio JSONL 通信	无登录聊天、多模型、消费学习端发布的能力、WebContentsView 内嵌浏览器、密码管理、编排调试
apps/admin 管理端	FastAPI + React/TS + Ant Design 6；PostgreSQL（16 表）；scrypt 口令、Fernet 密钥指纹	学校、成员、账号角色、模型连接、桌面接入 Token、审计
packages/contracts	Pydantic 单源 → 生成 TS + JSON Schema，CI 带 --check	三端 DTO
specs/	78 个带日期编号的中文规格	每个行为 / 协议变化先改规格

2. 桌面端长什么样

• ChatGPT 式浅色工作台。左侧 296px 侧栏：品牌、新建对话、历史搜索（置顶 / 归档 / 重命名 / 删除确认）、密码管理、模型选择、底部身份。顶栏：对话标题 + 菜单，「浏览器 / 导出 / 复制」。中间消息流最大宽 800px，欢迎页给目标入口；输入框带加号上传、模式胶囊、停止 / 发送。
• 右侧浏览器面板：打开时占 384px 到 40%。工具栏显示标题、地址、「暂停 / 接管浏览器 / 继续 / 收起」。实现：主进程 WebContentsView 挂到主窗口 contentView，渲染层 BrowserPanel.tsx 用 ResizeObserver 量出占位 div 的位置，经 IPC 让主进程 setBounds；用户在面板里点键盘或鼠标时主进程拦截输入并自动进入接管。
• 任务卡挂在消息流里：状态标签（排队中 / 正在理解目标 / 等待补充信息 / 等待原页登录 / 正在办理 / 已填写尚未提交 / 已暂停 / 原网页填写中 / 正在核验结果 / 核验完成 / 办理未完成 / 结果待核实 / 已取消）、目标、Agent 控制状态、事件时间线、带选项的追问表单（单选 + 自填，Enter 发送且中文输入法合成期间不发）、回执、动作按钮。
• 视觉规范（docs/standards/FRONTEND.md）：不用渐变 / 阴影 / Emoji 图标；Lucide 图标；PC 间距 8px 倍数、正文 14px；颜色圆角走设计变量（白底、#f7f7f7 侧栏、黑色 accent、16px 圆角）。
• 执行模型：DOM 观察与动作在 Electron 主进程自研，browser-use 0.13.10 只调 Agent.get_model_output() 做单步决策；每步绑定观察版本，单次提交窗口，提交后独立核验，结果未知进 uncertain 不自动重试。

3. 和我们的差别

维度	我们	他们
执行	browser-use Agent.run() 全程自主 + YAML 业务 + learned 注入 + 确认卡片	自研执行器逐步严格校验，模型只在枚举动作里选；能力由学习端先编译再发布
知识	YAML 出厂 + 运行中自动沉淀 learned（内容判重、自动晋升）	学习端探索 → 证据 → 评判 → 签名发布 form-v1；桌面只消费
浏览器	独立 Chrome 停靠 + CDP 收起展开	WebContentsView 真正内嵌
数据	MySQL（Docker）	学习端 SQLite+PG，管理端 PG
身份	单机 default 用户，密码本人×系统带角色	三端各自认证，统一身份 C1 只有设计
桌面栈	Electron + 原生 JS	Electron + React/TS/Vite，PyInstaller 打包
文档	CLAUDE / DESIGN / PROGRESS	AGENTS / specs 编号 / VALIDATION 记录，「禁止虚报」写进规范

两条路线各有道理：他们控制力和审计更强，工程量大得多，且依赖学习端先把能力编译好；我们上手快、靠 learned 越用越快，但对陌生控件和异常页面的稳定性依赖模型。中期可以走混合：稳定业务编译成确定性流程（他们 form-v1 的思路），陌生 / 第三方系统用我们的 Agent 路线。

4. 值得借鉴（按价值）

1. 桌面端形态与栈：React/TS/Vite、WebContentsView 内嵌浏览器、任务卡与追问表单结构、状态词汇、视觉规范、Lucide 图标。→ 我们的渲染层按此重做（DESIGN 第 8 节新增第 14 项）。
2. 打包链：uv 虚拟环境 + PyInstaller onedir 冻结 Python worker + electron-builder extraResources。→ 解决我们「学校用户装不了」。
3. 契约单源：Pydantic → TS/JSON Schema，CI 校验。→ 渲染层改 TS 时顺手做。
4. 提交结果未知不重试：uncertain 状态、证据不可覆写、pending 不自动重放。→ 我们提交类步骤补 uncertain 分支。
5. 管理端模板：FastAPI 工厂 + PG + Ant Design 6 + scrypt + Fernet 指纹 + 手工 DDL 三重 guard + 每校独立密钥。→ 我们的后台 / 服务端层直接参照，甚至复用其 schools / members / accounts / audit / provider_connections 表。
6. 「禁止虚报」与验收记录：每个 spec 区分已实现 / 待验收 / 不能据此声称。→ 我们 PROGRESS 已接近，再严一点。
7. 规格编号即变更日志；每校独立签名密钥，平台密钥不进交付包。

5. 不建议现在照搬

• 学习端整套编译发布链（探索 → 证据 → 评判 → 签名）：太重，且他们自己的漂移自动失效、自动补学、SQLite → PG 迁移都还没闭环。
• documents JSON 单表设计。
• 他们的统一身份（未实现）、租户计费（延后）、达梦支持（未实现）。

6. 待你们决定

1. 桌面端按第 2 节重做渲染层，同时对齐打包链？
2. 数据库要不要从 MySQL 换成 PostgreSQL，与管理端一致（现在切代价最低：只有 PyMySQL 一层）。
3. 仓库关系：继续独立仓库但对齐规范，还是将来合入 agent-a2a 作为一个 app？合入则要遵守其 docs/standards/GIT.md（逐文件暂存、Conventional Commit、不建分支）。
4. 执行路线：近期保持 browser-use run() + learned；中期是否引入「稳定业务编译成确定性流程」的混合模式。