Pi Capsule Agents：基于显式授权与成果交付的隔离式主子 Agent 插件

这份作业从零实现独立运行时，并提供 CLI、标准 MCP 和 Pi 插件三个入口。核心问题是：主、子 Agent 不共享历史、权限和工作区之后，如何仍然完成可检查的协作？

答案是：主 Agent 只委派；子 Agent 只获得点名的数据副本；隔离容器内没有模型凭据和网络；成果由宿主校验、计算哈希并独立保存。主 Agent 可把成果引用交给新的 reviewer 做独立复核。

统一入口：一次实现，多种宿主

入口与主 Agent 分开：聊天界面或命令行负责接收请求，真正的主 Agent 始终在独立容器里运行。 换客户端不会改变隔离规则，也不需要继承某个聊天应用的历史。

三种入口共用 capsule/api.py 的 run_request，协议只接受 task、inputs 和 timeout。history、workspace、environment、backend 等额外参数都会被拒绝。MCP 提供 capsule_run、capsule_demo、capsule_doctor 三个工具；支持握手、工具发现、请求取消，一次只运行一个工具调用。它不是开放 HTTP 服务。

从源码运行无需 pip 安装：python -m capsule --help。MCP 配置见 examples/mcp-config.json；需将模型名称替换为本机已安装的名称，并确保客户端能找到 capsule-agents。详细入口协议见 ENTRYPOINTS.md。

Related MCP server: engineering-mcp

交付范围与边界

• 主 Agent 和每个子 Agent 各自使用新容器、新消息列表、独立进程和临时目录。

• 主 Agent 唯一工具为 delegate。Pi 中的命令只是启动入口，不是执行任务的主 Agent。

• 子 Agent 不继承 Pi 对话、系统提示词、Skills、AGENTS.md、环境变量或认证文件。

• 输入只通过 JSON 传递明确选中的 UTF-8 文本副本；没有宿主目录挂载。

• 容器 network=none，非 root、只读根目录、撤销 capabilities、限制内存/PID/CPU。

• 模型推理由宿主 Broker 请求本机 Ollama；容器既没有 API Key，也不能自己选择推理地址。

• 子 Agent 无委派工具；reviewer 没有写工具。工具在代码中按角色拒绝，不仅靠提示词。

• 子 Agent 只能提交文本成果，不会覆盖原始文件。Broker 校验名称、数量和大小后交付。

• 任何 Agent 都不能改变宿主设定的角色、镜像、执行预算和文件目录。

“完全隔离”在这里指上述资源及上下文边界，不指绝对物理隔离。 Docker 共享宿主内核；宿主 Broker、Docker 和模型服务属于可信计算基础；模型仍可能答错或受显式输入影响。主 Agent 也可能主动把自己的信息写进委派任务，系统不声称识别所有语义泄漏。详细说明见 设计与对比。

环境

• Python 3.10+（宿主程序无第三方 Python 依赖）。

• Docker Engine / Docker Desktop，使用 Linux containers。

• 真实模型模式：已运行的本机 Ollama，并已下载一个能稳定输出 JSON 的模型。

• Pi 插件入口：Pi 0.87.1+；本次按本地示例 API 编写，其他版本需验证兼容性。

• 扩展自动测试直接加载 TypeScript，需要 Node.js 22.19+；本机使用 Node.js 24.19。

不自动安装软件、不自动下载模型、不自动读取用户工作区。Docker 不可用时，正式运行直接失败，不会降级成不安全的子进程。

1. 构建与检查

在本目录执行：

docker build -t pi-capsule-agents:1.0.0 .
python capsule/cli.py doctor

第一次构建需要下载基础镜像。正式部署建议将 Dockerfile 的基础镜像改为已核验的 digest；当前固定版本 tag 仍可能被上游更新。

2. 无模型、无费用的演示

python capsule/cli.py demo

它启动三个容器：main → analyst → reviewer。测试数据 conductivity 为 10、20、30。analyst 计算均值并提交 analysis.json；reviewer 在全新上下文中重算并核对。main 返回复核结果。

demo 的模型是确定性测试替身，证明流程可执行，不证明真实大模型的能力。 容器隔离则真实执行，前提是使用上述默认 Docker 后端。

没有 Docker 时，仅用于开发验证：

python capsule/cli.py demo --test-process

此命令有真实的独立 Python 进程，但没有操作系统沙箱；输出标记 backend=test-process。真实 run 模式拒绝这个选项。

3. 真实主、子 Agent

先通过 ollama list 找到已经安装的模型，将下方 YOUR_INSTALLED_MODEL 替换为实际名称。

python capsule/cli.py run --model YOUR_INSTALLED_MODEL --task "分析 conductivity 数据，生成结论文件，再委派独立 reviewer 复算；汇总证据和局限" --input samples.csv=examples/samples.csv

也支持无文件任务及文本资料：

python capsule/cli.py run --model YOUR_INSTALLED_MODEL --task "委派 author 起草一份实验日志模板，再由 reviewer 检查遗漏"

可重复传入 --input NAME=FILE。左侧为 Agent 看到的别名；右侧路径仅宿主读取，不交给 Agent。每份文件不超过 32KiB，总输入不超过 64KiB；本版本只支持 UTF-8 文本，不支持 PDF/图片/二进制。

4. 安装成 Pi 插件

pi install .
$env:CAPSULE_MODEL="YOUR_INSTALLED_MODEL"
# 如果 python 不在 PATH，设置完整可执行文件路径：
# $env:CAPSULE_PYTHON="D:\anaconda\python.exe"
pi

在 Pi 内执行：

/capsule-doctor
/capsule-demo
/capsule-run 委派 author 写一份实验记录规范，并委派 reviewer 审核

命令只传递你在命令后输入的任务，不传递 Pi 当前历史。也可以直接传入 JSON：/capsule-run {"task":"分析数据并独立复核","inputs":{"samples.csv":"sample,conductivity\nA,10\nB,20\nC,30\n"}}。读取本地文件请使用 CLI 的显式 --input；MCP 与 Pi 不接受任意宿主路径。每次调用都是独立任务，不支持续接历史。

输出与验收

.capsule-output/<run-id>/
├── audit.jsonl                 # 生命周期、授权引用、内容哈希，不保存完整模型会话
├── result.json                 # 成功/失败、模型类型、摘要和产物列表
└── artifacts/<agent-id>/
    └── analysis.json           # UTF-8 原始成果；不会自动运行

completed 表示流程成功结束，不保证事实正确；reviewer 的 PASS 在真实模型模式下仍是模型判断。SHA-256 证明交付字节是否变化，不证明内容正确，也不是防管理员篡改的数字签名。

测试

python -m unittest discover -s tests -v
# 已构建 Docker 镜像后，再启用真实容器集成测试：
$env:CAPSULE_DOCKER_TESTS="1"
python -m unittest discover -s tests -v
Remove-Item Env:CAPSULE_DOCKER_TESTS

覆盖未授权文件拒绝、角色权限、路径穿越、代码表达式拒绝、结果校验、主子上下文分离、独立复核、真实子进程往返和异常状态。Docker 测试检查完整演示及非 root、环境变量不继承、临时目录不复用、网络不可达、无 Docker socket。

Pi 入口测试：node --test tests/extension.test.mjs。生成干净的源码提交包：python scripts/package.py，文件输出到项目父目录的 deliverables/。包内不包括运行日志、缓存或同学仓库。

当前交付机器没有 Docker，实际运行记录见 验证记录。未执行的测试不会记作通过。

代码导航

依赖文档：Pi 扩展、Docker 容器运行、Ollama Chat API。