PenguinHarness三大机制 · 源码架构版
公开源码核对 · 非官方讲解

把共享、隔离和复制画清楚

多用户 / Project 与沙箱 · General 生成新 Agent · 基准驱动的自我进化

点节点看实现细节与精确源码行号；播放只逐节点高亮。离线讲解 · 不调用 Penguin 后端
SYSTEM 01 / SOURCE ARCHITECTURE

Project 管共享权限，沙箱管工具能碰什么

上半图是用户与资源授权；下半图是 Session 的实际执行边界。两层不能混为一谈。

01 / 身份与资源授权 · Server / Web用户账号林老师 · 周同学登录认证验证 Bearer / CookieProject ACL目标 Project 的 owner / member无成员资格：404不是任意跨 Project 查看同 Project 成员共用资源 · 不是每人一份私有副本另一个独立授权容器Project A林老师 owner · 周同学 member共享 Agent 与对话Agents · Sessions · BenchmarkProject 级设置owner 管成员、模型等敏感项Project B另一组 owner / members另一套 Agents / Sessions进入条件仍是 B 的 owner / member管理员身份不自动绕过成员授权02 / 工具执行边界 · 启用受限策略时生效Session 策略 ≠ Project ACL；Workspace 也不等于 Project 目录Session 执行环境Workspace + scratchpad沙箱设置 → 会话快照服务器默认 · 非管理员 ceiling工具执行入口exec · 文件工具 · Hook平台沙箱 BackendmacOS Seatbelt · Linux bwrapWindows 推荐 WSL允许写入的范围Workspace + scratchpadtemp 默认也可写读写遮罩与网络显式 maskPaths + networkFull access 例外无附加限制时不走约束 backend配置的受限维度无法实施全部限制 → 拒绝执行无附加限制的 Full access01 / 身份与资源授权用户账号林老师 · 周同学登录认证验证 Bearer / CookieProject ACL目标 Project 的 owner / member无成员资格：404不是任意跨 Project 查看Project A / 共享协作资源Project A林老师 owner · 周同学 member共享 Agent 与对话Agents · Sessions · BenchmarkProject 级设置owner 管成员、模型等敏感项Project B / 另一组成员与资源Project B另一组 owner / members另一套 Agents / Sessions须另外拥有 B 成员资格；admin 也不自动绕过02 / 工具执行沙箱 · 需启用受限策略Workspace 与 Project 目录不是同一概念Session 执行环境Workspace + scratchpad沙箱设置 → 会话快照服务器默认 · 非管理员 ceiling工具执行入口exec · 文件工具 · Hook平台沙箱 BackendmacOS Seatbelt · Linux bwrapWindows 推荐 WSL允许写入的范围Workspace + scratchpadtemp 默认也可写读写遮罩与网络显式 maskPaths + networkFull access 例外无附加限制时不走约束 backend无法实施所需限制 → 拒绝执行无附加限制才走 Full access 例外

人物、Project 与资源名称为教学示例；连线说明关系，不触发真实管理操作。

多用户与 Project

同 Project 成员协作共享；进入其他 Project 要另有成员资格。工具文件/网络边界再由会话沙箱实施。

一句话记住同 Project 成员协作共享；进入其他 Project 要另有成员资格。工具文件/网络边界再由会话沙箱实施。

同 Project 共享

成员看到的是共同的 Agent 与对话资源；member 不等于可以读取所有凭据或操作 owner-only 设置。

跨 Project 要成员资格

统一 ACL 拒绝无资格访问；用户可被分别加入多个 Project。服务器管理员不自动绕过这个检查。

文件隔离需要单独配置

workspace-write 默认约束写入根，不等于只能读取该目录；maskPaths 才能遮住指定路径。干净设置可关闭沙箱，不能声称默认强租户隔离。

沙箱是可配置的宿主执行约束，不是每个 Project 自动拥有独立容器。当前快照的干净设置可为关闭；跨 Project 的文件读取还取决于 Workspace、maskPaths、宿主权限与有效沙箱配置。

SYSTEM 02 / SOURCE ARCHITECTURE

复制可配置底座，生成独立状态；运行引擎仍共享

重点展示 General 按 agent-initialization 创建的路径，同时区分 Web 手动初始化。

01 / General 创建新 Agent · 官方初始化 Skill 路径人的需求任务 · 规则 · 交付物General / Builder Agentdefault_agent · 初始化 Skill确认新 ID，再建目录目标存在就停止，不覆盖共享 Harness 引擎加载状态 · 运行循环 · 工具agents/<newAgentId>/ · 与 default_agent 同级General 的现有底座system_config.yaml → 复制Skill / Hook 包：按需选取agent_state/system_config.yaml复制基础配置，再改身份与参数agent_state/AGENTS.md另写角色与工作规则skills/ + hooks/技能附件与 Hook 脚本agent_state/memory/新建，不沿袭 General 记忆scratchpad/ · traces/scratchpad 空起步Trace 在运行后出现按需选包；其余状态与运行目录新建新 Agent 的 Session从自己的状态载入上下文Session 选底层模型provider + model_id校验文件，再试跑能加载 ≠ 已经好用另一入口：Web 手动创建core 默认初始化 + 用户选装同一引擎加载模型是运行时选择同组文件共同组成 Agent，不是串行执行步骤General 创建新 Agent / 不是整目录克隆人的需求任务 · 规则 · 交付物General / Builder Agentdefault_agent · 初始化 Skill确认新 ID，再建目录目标存在就停止，不覆盖General 的现有底座system_config.yaml → 复制Skill / Hook 包：按需选取agents/<newAgentId>/ · 独立状态目录agent_state/system_config.yaml复制基础配置，再改身份与参数agent_state/AGENTS.md另写角色与工作规则skills/ + hooks/技能附件与 Hook 脚本agent_state/memory/新建，不沿袭 General 记忆scratchpad/ · traces/scratchpad 空起步Trace 在运行后出现只复制基础 YAML其余资产分别写入或按需装包，不是串行链共享 Harness 引擎加载状态 · 运行循环 · 工具Session 选底层模型provider + model_id新 Agent 的 Session从自己的状态载入上下文校验文件，再试跑能加载 ≠ 已经好用另一入口：Web 手动创建core 默认初始化 + 用户选装

框内是组成同一 Agent 的并列文件资产，不是串行步骤。

Agent 生成 Agent

新 Agent 是独立的配置、指令、能力包和运行数据目录；可以带技能/Hook 代码，不复制整套 Harness 或模型。

一句话记住新 Agent 是独立的配置、指令、能力包和运行数据目录；可以带技能/Hook 代码，不复制整套 Harness 或模型。

复制了什么

General 基础 YAML；按需安装/复制 Skill 和 Hook 整包。包里可含脚本，但不是完整引擎代码。

新建了什么

新的 Agent 目录、角色规则、空记忆/产物目录；运行后各自留下 Trace。不是继承 General 的全部历史。

仍共享什么

Harness 的装载与执行机制、安装的 Node 运行环境。底层模型由 Session 选择；多个 Agent 可用同一个模型。

官方 Builder 配方不是递归克隆 General 全目录：只复制基础 YAML，另写 AGENTS.md，按需装包。整目录复制、快照导入和手动初始化是不同操作。

展开：新 Agent 的真实路径结构
<root>/<projectId>/
├── .project_config.toml          ← Project 级，不属于 Agent 副本
├── benchmarks/                 ← Project 级
└── agents/
    ├── default_agent/           ← General / 创建者
    └── <newAgentId>/            ← 与 General 同级
        ├── agent_state/
        │   ├── system_config.yaml  ← Builder 复制 General 后修改
        │   ├── AGENTS.md           ← 新写角色规则
        │   ├── skills/<skill>/     ← SKILL.md + 包附件/代码
        │   ├── hooks/<package>/    ← hooks.json + 包脚本
        │   ├── tools/              ← 新建预留目录
        │   └── memory/             ← 不复制 General 记忆
        ├── scratchpad/             ← 新建空目录，逐会话写入
        └── traces/                 ← 运行后出现

可选 snapshots/、workspaces/、schedule/、vault 等不表示新建时必有。
这是代码定义的路径示意，不是本机实际运行目录。
SYSTEM 03 / V2 FLOW

先把考试定下来，再让候选版本反复过关

Builder 构建与校准 Benchmark；Optimizer 修改 Agent；Evaluator 负责复测。

A / 构建评估基准 · BuilderB / 优化 Agent · Optimizer + Evaluator难度不合适，继续改题基准就绪后开始优化① 出题Builder 编写题干与评分标准② 校准试测难度，不合适就改题③ 冻结与基线固定 Benchmark，记录正式基线④ 分析评估结果Optimizer 看分数与 Trace⑤ 快照与修改只做一处有边界的改动⑥ 完整复测Evaluator 跑 Case × runs分数严格提高？候选均分 > Reference保留新版本追加记分板，关联 Trace回滚原版换一个假设，再尝试提高未提高恢复原版，换假设继续未到目标且有剩余轮次，可以继续；达到目标或轮次用尽则结束A / Builder 构建基准B / Optimizer 与 Evaluator 优化不合适就改题提高未提高① 出题Builder 编写题干与评分标准② 校准试测难度，不合适就改题③ 冻结与基线固定 Benchmark，记录正式基线④ 分析评估结果Optimizer 看分数与 Trace⑤ 快照与修改只做一处有边界的改动⑥ 完整复测Evaluator 跑 Case × runs分数严格提高？候选均分 > Reference保留新版本记分板 + Trace回滚原版换假设再尝试回滚后换一个假设再试采纳后也可继续；目标达成或轮次用尽则结束

人物、Project 与资源名称为教学示例；连线说明关系，不触发真实管理操作。

自我进化

基准冻结后不跟着候选改题；候选分数严格提高才保留，否则回滚。

一句话记住基准冻结后不跟着候选改题；候选分数严格提高才保留，否则回滚。

出题与优化分开

先校准、冻结 Benchmark 并记录正式基线，之后才进入候选优化。

改资产，不改权重

优化的是 Agent 指令、Skills 或有边界的配置，保留原版快照。

必须完整复测

分数严格提高才保留；持平/下降回滚。图沿用上一版已核验流程。

改的是指令、Skill 或安全配置，不是模型权重；评分信息隔离靠 Skill 约定与 Trace 审计。