yingqi-z20/Agent-libOS

# Agent libOS Agent libOS 是一个实验性的、以 Agent 为中心的 libOS 运行时，使用 Python 编写。 它支持以下论文主题： 该运行时将 Agent 建模为一个长期运行、可调度、可中断且受能力控制的 `AgentProcess`，而不是将其视为单一的聊天请求或工作流线程。Agent 可以激活 Skill、注册 Deno/TypeScript JIT 工具，注册、执行或从 checkpoint 提交新 image，fork 子进程，进行 checkpoint/fork 状态，并使用已注册的远程资源，但这些自演化机制本身并不授予资源权限。 当前的贡献在于运行时的权限边界： ``` process identity + capability + primitive + audit ``` 面向 LLM 的工具、Skill、JIT 工具、image 定义、子进程、checkpoint 以及远程端点可见性都是人体工程学辅助功能。它们并不是安全边界。 受保护的影响仅发生在 libOS 原语内部，在这些原语中，进程身份、能力、人类批准、策略、提供者隔离、事件和审计记录都得到了严格执行。 本项目仍在积极开发中。[agent_libos_design_doc.md](agent_libos_design_doc.md) 是一个历史设计存档，可能描述了计划中或已被取代的接口。 ## 当前系统 目前的实现包括： - Agent 进程生命周期：`spawn`、`fork`、`exec`、`wait`、`signal`、`pause`、`resume` 和 `exit`。 - 分层的进程资源预算，用于工具调用、LLM token 使用、子进程 wall/CPU/RSS 使用、文件系统字节数、JSON-RPC 字节数以及 Deno 系统调用。 - 通过 `Runtime.run_until_idle()` 和异步主机包装器 `Runtime.arun_until_idle()` 实现的基于线程的进程调度，从而确保被阻塞的时间片不会独占调度器进度。 - 用于文件系统和 shell 操作的进程本地工作目录。 - 用于 IPC 的持久进程消息队列，包括中断传递。 - 绑定到对象的后台工具任务，它们可以通过相同的持久消息队列通知进程，包括可选的 owner-change watches，而无需将其运行器的子进程暴露给 LLM 调度器。 - 用于普通问题和逐次使用批准的人类队列集成。 - 默认使用进程私有的 Object Memory 命名空间，并可通过能力机制使用显式的共享命名空间。 - 结构化的 Capability 权限，用于文件系统、shell、时钟、人类、进程、image、checkpoint、skill 和 Object Memory 原语，包括类型化的资源匹配、deny/ask/allow 效果、一次性授权、衰减、撤销和审计谱系。 - 用于可注入文件系统、时钟、shell 和人类 I/O 后端的 Resource Provider Substrate，以及用于预注册远程端点的基于 HTTP 的 JSON-RPC 客户端提供者。 - 在 `Runtime.open()` 返回之前从清单声明的 Python 入口点加载的可信启动 Runtime Modules。模块可以注册工具、image、系统调用、provider hooks 和启动钩子，但不授予进程资源权限。 - 一个直接的工作流入口点，供用户通过 ToolBroker 运行一个对 image 可见的工具，而无需调用 LLM 调度器。 - 为进程/对象元数据、能力、消息、人类请求、LLM 调用、事件、审计记录、工具、Skill/JIT 元数据和限定范围的 checkpoint 提供 SQLite 持久化。 - Deno/TypeScript JIT 工具，只能通过 `libos.syscall` 访问 libOS。 - 声明式 Skill，可以在不授予资源权限的情况下添加提示指令、可见工具和 JIT 候选项。 - 仅限客户端的基于 HTTP 的 JSON-RPC 2.0，包含已注册的端点、方法能力、提供者分类的外部效应、审计和 checkpoint。 - 一个确定性的运行时安全基准测试套件，包含 20 多个已提交的任务，包括自演化子集、基线、副作用预言机和指标收集。 ## 文档 从这里开始，然后根据需要阅读更深层的参考资料： - [docs/architecture.md](docs/architecture.md)：运行时层、provider substrate 以及工具/原语边界。 - [docs/runtime_model.md](docs/runtime_model.md)：进程生命周期、调度器、cwd、人类队列、IPC、fork/spawn/exec 和等待。 - [docs/capabilities.md](docs/capabilities.md)：资源命名、权限、一次性授权、人类批准、shell 策略和文件系统隔离。 - [docs/object_memory.md](docs/object_memory.md)：命名空间、对象权限、文件/对象桥接、上下文物化和 payload 持久化。 - [docs/tools_and_jit.md](docs/tools_and_jit.md)：内置工具、ToolBroker、Deno/TypeScript JIT 工具、syscall 协议和沙箱规则。 - [docs/modules.md](docs/modules.md)：可信启动 Runtime Module 清单、信任模型、注册接口、CLI 和 checkpoint 行为。 - [docs/jsonrpc.md](docs/jsonrpc.md)：仅限客户端的 JSON-RPC 端点注册、capability 资源、工具、syscall 和 checkpoint 行为。 - [docs/skills.md](docs/skills.md)：标准 `SKILL.md` 包、工作区/全局源、信任、activate/unload 语义、捆绑的 JIT 工具和 `swe-agent`。 - [docs/checkpoints.md](docs/checkpoints.md)：限定范围的快照、恢复、fork、重放诊断、仅追加历史记录和外部效应。 - [docs/cli.md](docs/cli.md)：稳定的 CLI 命令参考和示例。 - [docs/gui.md](docs/gui.md)：Electron 桌面控制台、本地 GUI 服务器、HTTP/SSE API 和开发命令。 - [docs/benchmark.md](docs/benchmark.md)：M1 运行时安全基准测试任务、运行器、预言机、输出和指标。 - [docs/mini_swe_agent_image.md](docs/mini_swe_agent_image.md)：仅限包的 `mini-swe-agent` image 行为和已知的接口差异。 - [docs/development.md](docs/development.md)：设置、测试、真实 LLM 冒烟测试、配置默认值和贡献规则。 - [docs/invariants.md](docs/invariants.md)：当前不变式到测试的映射。 - [docs/artifact_anonymity.md](docs/artifact_anonymity.md)：匿名 artifact 卫生检查清单。 - [docs/paper_thesis.md](docs/paper_thesis.md)：当前的论文主题和非目标。 - [benchmarks/runtime_safety/schema.md](benchmarks/runtime_safety/schema.md)：基准测试任务 schema v0。 ## 快速开始 安装依赖项： ``` uv sync --frozen --all-groups ``` 运行测试： ``` uv run python scripts/test_matrix.py --lane unit uv run python scripts/test_matrix.py --lane security uv run python scripts/test_matrix.py --lane runtime uv run python scripts/check_test_invariants.py ``` `runtime` 和 `all` 通道默认使用受限的 pytest-xdist 并行度，以控制 CI 的 wall-clock 时间。传入 `--workers 1` 进行串行故障诊断，或传入 `--workers N` / `--workers auto` 覆盖任何 Python 通道的工作进程数。GUI 通道会构建共享的前端 artifact，应单独运行。Pytest 会在测试会话结束时删除在被忽略的 `agent_outputs/` 下创建的文件；在调试生成的文件时请使用 `--keep-agent-outputs`。 运行确定性的本地演示： ``` uv run agent-libos demo ``` 在开发模式下运行 Electron GUI： ``` npm --prefix gui install npm --prefix gui run electron:dev ``` GUI 会启动一个本地 `agent-libos-gui-server`，订阅运行时事件，并提供一个以进程为中心的控制台，用于处理并发消息、中断、人类批准、调度器控制、image 选择/注册/提交、审计检查和 LLM 调用可见性。 该演示不会调用真实模型。它会执行进程 spawn/fork、Object Memory、在 Deno 可用时进行 Deno/TypeScript JIT 验证、checkpoint、授权前拒绝能力、人类批准、文件系统写入、最终报告对象创建以及审计跟踪生成。 运行一个小型的确定性基准冒烟测试： ``` uv run python experiments/run_benchmark.py --suite benchmarks/runtime_safety --runner agent_libos_full --limit 3 --output .benchmark_runs/m1-smoke uv run python experiments/collect_metrics.py .benchmark_runs/m1-smoke ``` 该基准测试默认使用模拟/计划操作，不消耗模型 token。真实模型基准冒烟测试是可选的，必须通过 `--llm real --limit 1` 或单个 `--task` 来限定范围。 ## 持久化运行时 使用 `--db` 将运行时状态保存在 SQLite 中： ``` uv run agent-libos --db .agent_libos.sqlite init uv run agent-libos --db .agent_libos.sqlite spawn --image coding-agent:v0 --goal "Summarize README.md" uv run agent-libos --db .agent_libos.sqlite run --max-quanta 10 uv run agent-libos --db .agent_libos.sqlite processes uv run agent-libos --db .agent_libos.sqlite resources uv run agent-libos --db .agent_libos.sqlite audit uv run agent-libos --db .agent_libos.sqlite workflow run get_working_directory ``` 省略 `--max-quanta` 会持续运行直到运行时空闲；仅当您需要有界限的运行时才提供它。 `workflow run ` 会从默认 image 派生出一个新进程，调用一个可见工具，持久化结果对象，并退出该进程。传入 `--image ` 以使用另一个 image 的工具表。它不会绕过原语能力检查、资源预算、人类批准或审计。 每次 LLM 动作选择调用都会作为一行 `llm_calls` 持久化，包含提示消息、可见工具 schema、模型输出、工具调用、可用时的 token 使用量、暴露时的推理元数据、原始提供者响应 JSON 和错误。 ``` uv run agent-libos --db .agent_libos.sqlite llm-calls --pid ``` ## 真实 LLM 配置 为真实模型执行创建一个本地 `.env` 文件： ``` OPENAI_BASE_URL=https://example-openai-compatible-endpoint/v1 OPENAI_LANGUAGE_MODEL=your-model OPENAI_API_KEY=... ``` 客户端使用 OpenAI Python SDK。默认情况下，它对 OpenAI 托管的模型使用 Responses API，对于自定义的 OpenAI 兼容 `base_url` 提供者，则回退到 Chat Completions。设置 `OPENAI_API_MODE=responses` 或 `OPENAI_API_MODE=chat` 可强制指定一种模式。 可选的配置项包括 `OPENAI_TIMEOUT`、`OPENAI_MAX_RETRIES`、`OPENAI_STORE`、`OPENAI_REASONING_EFFORT`、`OPENAI_VERBOSITY` 以及特定于提供者的 `OPENAI_ENABLE_THINKING`。 ## 常见 CLI 示例 发送普通和中断消息： ``` uv run agent-libos --db .agent_libos.sqlite message "Please inspect the latest result" uv run agent-libos --db .agent_libos.sqlite interrupt "Stop current work and read this first" ``` 运行交互式 Codex CLI 风格循环： ``` uv run agent-libos --db .agent_libos.sqlite run --interactive --pid --max-quanta 20 ``` 手动控制进程 cwd 和生命周期： ``` uv run agent-libos --db .agent_libos.sqlite cd src uv run agent-libos --db .agent_libos.sqlite exec images/review-agent "Review README.md" --pid --run uv run agent-libos --db .agent_libos.sqlite exit --payload '{"done":true}' ``` 将 checkpoint 提交到新的 checkpoint 派生 image 中： ``` uv run agent-libos --db .agent_libos.sqlite images commit stateful-agent:v0 --name stateful-agent uv run agent-libos --db .agent_libos.sqlite spawn --image stateful-agent:v0 --goal "Reuse the baked state" ``` 注册并激活 SWE-Agent 风格的 Skill： ``` uv run agent-libos --db .agent_libos.sqlite skills validate skills/swe-agent uv run agent-libos --db .agent_libos.sqlite skills register skills/swe-agent uv run agent-libos --db .agent_libos.sqlite skills activate swe-agent ``` 注册并调用预配置的 JSON-RPC 端点： ``` uv run agent-libos --db .agent_libos.sqlite jsonrpc register endpoint.yaml uv run agent-libos --db .agent_libos.sqlite capabilities grant jsonrpc:demo-weather:forecast --rights read uv run agent-libos --db .agent_libos.sqlite jsonrpc call demo-weather forecast --params-json '{"city":"Beijing"}' ``` 检查或更改运行时权限： ``` uv run agent-libos --db .agent_libos.sqlite capabilities list --subject uv run agent-libos --db .agent_libos.sqlite capabilities explain filesystem:workspace:README.md read uv run agent-libos --db .agent_libos.sqlite capabilities grant filesystem:workspace:README.md --rights read ``` 针对另一个工作区启动编码 Agent： ``` uv run python scripts/run_coding_agent.py --workspace /path/to/repo --goal "Implement the requested change" ``` 启动器在挂载目标工作区之前，会从此 Agent libOS 检出中加载 `.env`。它不会自动读取目标工作区的 `.env`；当运行需要不同的凭证文件时，请传入 `--env-file /path/to/env`。 在 Windows PowerShell 上： ``` uv run python scripts\run_coding_agent.py --workspace ..\some-repo --goal "Summarize the current project" ``` 有关完整的命令参考，请参见 [docs/cli.md](docs/cli.md)。 ## 核心不变式 - 工具可见性不是资源权限。 - Capability 记录是类型化的权限声明，具有显式的 allow/deny/ask 效果、颁发者谱系、委派深度、状态、过期时间和可选的使用计数。 - Skill 和 JIT 工具不授予文件系统、shell、人类、对象、进程、image、checkpoint 或 JSON-RPC 远程权限。 - JIT syscall 绕过了面向 LLM 的工具表，但不会绕过原语能力检查、权限策略、人类批准或审计。 - 人类批准是原语/syscall 的一部分。调用者看到的是最终成功或最终失败，而不是挂起/重试协议。 - `process.exit` 和 `process.exec` 是来自 TypeScript 的普通 syscall。运行时会在 JIT 工具返回其正常工具结果后应用生命周期更改。 - Checkpoint 恢复仅涵盖可重构的进程子树状态。它不会删除仅追加的审计/事件/LLM 调用，也不会回滚文件系统、shell、image、网络或提供者端的影响。 - Checkpoint 派生的 image 捕获的是内部可重构的运行时状态，而不是外部提供者状态。它们所需的能力是声明性的，不会在 spawn 或 exec 时自动授予。 - 提供者将外部效应分类为 `irreversible`、`rollbackable` 或 `no_rollback_required`；checkpoint 恢复时报告这些类别的 `restore_external_policy="report_only"`。 - Resource Provider Substrate 后端执行主机效应，但原语拥有能力检查、策略决策、事件和审计。 有关测试覆盖率，请参见 [docs/invariants.md](docs/invariants.md)。 ## 开发 运行标准的本地检查： ``` uv sync --frozen --all-groups uv run python -m compileall agent_libos tests scripts experiments benchmarks uv run python scripts/test_matrix.py --lane all --workers 4 uv run python scripts/check_test_invariants.py uv run python scripts/test_matrix.py --lane gui git diff --check ``` 使用 `uv run python scripts/clean_agent_outputs.py` 来试运行清理已累积的本地输出，并添加 `--yes` 将其删除。 Deno 对于 Python 单元测试套件是可选的。如果您想验证并运行来自另一个二进制文件的真实 Deno/TypeScript JIT 工具，请安装 `deno` 或传入一个使用 `dataclasses.replace(DEFAULT_CONFIG, tools=replace(...))` 构建运行时配置。 运行时默认值位于 `agent_libos.config.DEFAULT_CONFIG` 中，包括调度器时间片、worker、排空和关闭限制；进程预算；image ID；工作区命名空间；工具限制；文件系统/Object Memory 大小限制；Deno 沙箱限制；JSR 导入允许列表；shell 策略列表；启动器预设；Skill 默认值；以及 checkpoint 默认值`AgentLibOSConfig` 在构造时进行验证，因此无效或反转的边界会在 Runtime 启动之前失败。 使用 `uv add ` 添加运行时依赖，使用 `uv add --dev ` 添加开发依赖。在依赖项更改后提交 `pyproject.toml` 和 `uv.lock`。

标签：AI智能体, Python, 安全边界, 库操作系统, 无后门, 逆向工具