深入PenguinHarness架构SDK、Server、CLI与Web接口边界设计完整解析【免费下载链接】penguin-harness Unified and Stable RSI Platform项目地址: https://gitcode.com/gh_mirrors/pe/penguin-harnessPenguinHarness 是一个开源、本地优先的多 Agent 应用开发平台它能自动化 AI 应用的构建、优化与部署。本文用一张分层图讲清楚它的架构核心SDKcore、Server、CLI、Web 四个接口各司其职的边界设计——哪一层负责跑 Agent、哪一层负责鉴权与持久化、哪一层只负责呈现。一张图看懂四层分工PenguinHarness 的 Monorepo 里四个packages目录正好对应四个接口层依赖关系是严格单向的接口层包名一句话定位源码入口SDKprismshadow/penguin-coreAgent / Session 运行时 OmniMessage 协议packages/core/src/index.tsServerprismshadow/penguin-server多用户鉴权、SSE 流式会话、用量计费packages/server/src/CLIprismshadow/penguin-clipenguin命令行Agent 可脚本化驱动packages/cli/src/commands/Webprismshadow/penguin-web浏览器里的完整控制台packages/web/上图即 SDK 能力的缩影一句话让 PenguinHarness 构建出带检索、引用来源的完整 RAG 应用全程仅花费约 $0.02 的 token 成本。边界设计的第一原则只有 SDK 层知道如何跑一个 AgentServer、CLI、Web 全部是 SDK 的调用方谁也不重写一份 Agent 逻辑。SDK 层Agent、Session 与三接口契约penguin-core是整个平台的唯一事实来源导出三块核心内容见 packages/core/src/index.tsOmniMessage 协议——统一的跨层消息格式一次定义SDK/Server/Web 通用三份接口契约——Human / LLM / Environment分别定义输入谁、问哪个模型、在哪个环境执行见 packages/core/src/interfaces/运行时入口——createAgent、Session、ContextEngine见 packages/core/src/agent.ts。最简用法只有一小段const agent await createAgent({ agentId: default_agent }); const session await agent.createSession({ workspaceDir: process.cwd() }); for await (const output of session.run([userText(创建 hello.txt)], { approve: async () allow, // 每次工具调用可单独审批 })) { /* 处理流式输出 */ }设计要点模型引用永远是 (provider, model_id) 二元组会话在上下文打开那一刻从磁盘组装模型上下文assembleContext压缩/切换模型都会打开一个全新的上下文——这让 SDK 天然可嵌入任何宿主程序桌面 App、CI 脚本、另一个 Agent。完整文档见 packages/docs/content/quickstart-sdk.zh.md 与 packages/docs/content/interfaces.zh.md。Server 层唯一碰数据的进程penguin-server基于 Hono 构建职责被严格圈定为三件事多用户鉴权与授权内置admin账号 首登链接机制见 packages/server/src/auth/会话执行与 SSE 流式推送所有会话的 Token 流、工具输出经 SSE 实时下发用量计费与观测成本中心、Trace 轨迹文件的落盘与导出。关键约束是Server 是数据根目录~/.penguin/data的独占使用者内置文件锁packages/server/src/lock.ts保证同一数据根只有一个 Server 进程运行。所以桌面 App 启动时发现 CLI 已起了服务就直接附着过去而不是再起一个。Trace 观测面就是这套设计的直接产出——每一轮工具调用、思考耗时、Token 成本都在执行时间线上可视化Server 落盘的 Trace 文件在 Web 端展开为轨迹观测全局统计 分轮次执行时间线。API 全貌见 packages/docs/content/server-api.zh.md。CLI 层给 Agent 用的脚本化入口penguin命令是 SDK 与 Server 的双重消费者一部分命令直接调 SDK如penguin run一次性任务一部分通过 HTTP 调用已运行的 Server如penguin server-status、penguin server-stop见 packages/cli/src/client.ts。常用命令速查命令用途penguin run -m 任务一次性跑完一个任务就退出penguin chat交互式 REPL支持 /compact、/clearpenguin server以无头模式启动服务与 Web 同一套 APIpenguin config model add添加/配置模型凭据penguin schedule/penguin cost定时任务 / 成本查询命令实现分散在 packages/cli/src/commands/ 下的 18 个模块中。这种SDK 直连 Server 代理的双通道设计让 CLI 既能离线单机跑也能管理远端服务——对用 Agent 驱动 Agent的场景尤为友好。文档见 packages/docs/content/cli.zh.md。Web 与桌面同一前端不同外壳Web 前端packages/web/只与 Server 的 HTTP/SSE 接口通信从不直接触碰文件系统或 SDK——这是它可以在浏览器里安全运行的前提。桌面 Apppackages/desktop/则更进一步内嵌 Server 内嵌 Web 前端双击即开、免登录、免终端且与 CLI 共享同一个~/.penguin/data数据根两种安装方式可无缝混用。Web 控制台左侧多会话列表 智能体/技能库/模型库/成本中心/评估中心五大导航右侧流式对话与工具执行折叠卡。为什么这样切边界三条设计原则单向依赖SDK 是唯一事实来源——Agent 循环、压缩、上下文组装只在penguin-core写一遍四个接口层零重复。数据独占Server 是单点写入者——所有状态文件经原子写packages/core/src/internal/atomic-write.ts落盘避免多进程互相踩坏数据。表现层无状态——Web 桌面只是 Server 的投影随时可关、可换升级前端不影响会话数据。快速选型我该用哪个接口你的场景推荐接口日常聊天、管理 Agent 与模型️ 桌面 App 或 Web服务器上无头跑批、接入 CI⌨️penguin server API在自己程序里嵌入 Agent 能力prismshadow/penguin-coreSDK让另一个 Agent 自动化操作本工具⌨️ CLIpenguin run等总结PenguinHarness 的架构精髓不在功能堆料而在克制——SDK 管怎么想Server 管怎么存CLI 管怎么驱动Web 管怎么看。四层边界清晰后无论嵌入宿主程序、无头部署还是多用户访问走的都是同一条经过打磨的 Agent 内核。想动手深入建议从 packages/docs/content/architecture.zh.md 与 README.md 开始。【免费下载链接】penguin-harness Unified and Stable RSI Platform项目地址: https://gitcode.com/gh_mirrors/pe/penguin-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考