agentos/AGENTS.md

AgentOS 工程约定

本文件面向在本仓库内工作的代码代理。修改前先读本文件、根 Cargo.toml，再读目标 crate 的源码。不要根据旧 Python 版本、Octos 或 npu_features/ 中的厂商样例臆测当前行为；crates/ 才是实现事实来源。

项目目标

AgentOS 是运行在裸 Linux 上的 low-level OS agent，而不是 Linux 发行版、 容器沙箱或内核 fork。核心原则是尽量复用 Linux 原生能力：进程 UID/GID、 文件权限、Unix 凭据、pidfd、no_new_privs、Btrfs subvolume/snapshot 和设备 ioctl。

当前安全模型是稳定的 AgentId -> (owner UID, agent UID, agent GID) 绑定：

• agent 进程不能以 UID 0 或 GID 0 运行；
• 每次执行前必须核对进程的 effective UID/GID；
• 一个状态数据库中，agent UID 只能绑定给一个 active AgentId；
• 不额外构造 namespace、容器或通用 sandbox；
• no_new_privs 是补充保护，不能替代 UID/GID 和工具策略；
• 模型不能获得任意 shell，更不能直接获得 root shell。

不要把 owner_uid 与 agent_uid 混为一谈。前者表示拥有者，后者才是内核 实际执行主体。新增 daemon 或 broker 时，Unix socket 对端必须用内核提供的 peer credentials 鉴权，不能信任请求体里的 UID。

当前成熟度边界

已经可用：

• agentos one-shot CLI、doctor 和确定性 fake backend；
• OpenAI-compatible Chat Completions / Responses 非流式后端；
• agentos.chat.v1 内部协议、严格工具 schema、预算和循环检测；
• 只读 Linux 工具、SQLite 审计/记忆、Btrfs worldline 与 copy fallback；
• CALCULET PCIe ABI、Rust ioctl/DMA 包装、Calbin 解析、张量/命令结构；
• Candle/Qwen3 host pipeline、tool-call 模板和 CALRT 张量适配；
• 旧 llama-server UDS bridge；HTTP 消息格式直接承载在 AF_UNIX 上，不经过 TCP。

尚未完成：

• 纯 Rust CALRT 的 CCU relocation、job launch/completion 和设备 KV reset；
• 可在真实 NPU 上完成推理的 npu_candle backend；
• typed mutation broker 和任何变更型系统工具；
• 长驻 AgentOS control daemon、control UDS RPC、服务安装和完整硬件端到端测试。

ConfiguredRuntime::submit() 当前必须 fail closed 并返回 HardwareExecutionUnavailable。在没有真实板卡证据前，不得把 npu_candle 标记为 ready，不得让 auto 选择它，也不得用 mock 测试宣称 硬件推理已验证。

Workspace 与模块所有权

除 agentos-cli 外，crates/ 下均为 library crate。

Crate	职责
agentos-cli	agentos 与 agentos-npu-bridge 两个 binary；只做参数解析和装配入口
agentos-runtime	composition root、环境配置、identity/backend/tool 装配、doctor
agentos-agent	有预算的 agent loop、工具调度、循环检测、审计事件
agentos-protocol	provider-neutral agentos.chat.v1 类型与 ChatBackend trait
agentos-inference	ntex HTTP、OpenAI-compatible、subprocess、fake/scripted backend
agentos-tools	fail-closed registry、schema 校验、审批契约和 Linux 只读工具
agentos-core	ID、principal、execution identity、审计和 worldline 公共类型
agentos-kernel	Linux/rustix 边界、凭据、pidfd、文件原子写、Btrfs ioctl
agentos-memory	SQLite WAL、FTS5、principal 绑定、memory 和 audit event
agentos-worldline	类 Git 的 filesystem history、branch/commit/diff/rollback/recovery
agentos-npu	NPU probe、旧 bridge、Rust Candle NPU backend 装配
agentos-candle	Qwen3 模板/tokenizer/sampling 与 Calbin prefill/decode host runner
calculet-pcie-abi	驱动 0.9.0 / ABI 1.0.0 的 64-bit Linux ioctl 布局
calculet-pcie	安全的设备、BAR、DMA、MSI、reset 和 board/process API
calculet-calrt	Calbin、allocator、tensor、command stream、DeviceIo 和 runtime 骨架

保持依赖方向从高层向低层：

agentos-cli -> agentos-runtime -> agentos-agent/tools/inference/npu/worldline/memory
agentos-npu -> agentos-candle -> calculet-calrt -> calculet-pcie -> calculet-pcie-abi
agentos-kernel/core/protocol 是底层公共边界

不要让底层 crate 反向依赖 CLI 或 runtime。跨 provider 的消息类型放在 agentos-protocol；Linux syscall/ABI 放在 agentos-kernel 或对应的 calculet-* crate；composition 逻辑只放在 agentos-runtime。

不可破坏的设计约束

Linux 与系统调用

• 项目只支持 Linux；当前 CALCULET ABI 只验证过 64-bit Linux。
• 项目自有的低层 syscall/ioctl 优先走 rustix，不要直接新增 libc 调用。
• 这不表示最终二进制完全不链接 libc；Rust std、OpenSSL 等依赖仍可使用 系统 ABI。
• unsafe 仅允许出现在无法避免的 ABI 边界，必须就结构布局、指针生命周期 和 opcode 写英文 SAFETY 注释，并在调用前完成长度、对齐和范围校验。
• 不要为了 worldline patch 内核。优先使用现有 Btrfs ioctl；非 Btrfs 环境保留 copy fallback。

工具与权限

• registry 必须显式 allowlist；未知工具一律拒绝。
• 所有 tool schema 默认 strict：object、列出全部 required、 additionalProperties: false。
• 参数和输出必须有字节上限，外部命令必须有 deadline、kill_on_drop，并移除 API key 环境变量。
• 只有标记为 ConcurrencyClass::Safe 的只读工具可以并行；变更工具必须 exclusive。
• 现有 ApprovalLedger 只是进程内、单次、精确参数绑定的契约。实现 mutation 前还必须有 typed broker、内核凭据校验、持久审计和失败恢复，不能把审批 ID 当作任意命令授权。
• 不得增加通用 shell、exec、任意路径写入或任意 systemd unit 工具。

推理后端

• 内部统一使用 agentos.chat.v1，provider 差异留在 backend adapter。
• 缺少 NPU 硬件时的 mock 是远程 OpenAI-compatible 模型，不是内置 FakeBackend。远程传输可以使用 HTTP 或 HTTPS；使用 HTTPS 时必须验证 peer。
• 本机常驻模型服务必须使用 filesystem Unix domain socket，禁止监听或连接 localhost、loopback 或其他 TCP 地址。纯 Rust Candle in-process 路径不需要 IPC。
• 本机 llama-server 可以保留 OpenAI-compatible HTTP 消息格式，但必须通过 ntex 自定义 connector 承载在 AF_UNIX 上，用户配置只能暴露 socket path，不能 接受本机 URL。
• OpenAI-compatible HTTP 和 UDS HTTP client 使用 ntex，不要引入 reqwest。
• 禁止自动 redirect；响应大小、超时和 retry 必须有界。
• 支持 Chat Completions 与 Responses 两种方言，但不要假设所有兼容服务支持 完全相同的字段。新增兼容逻辑必须有请求构造和响应解析测试。
• subprocess backend 只通过 stdin/stdout 传 JSON，stderr 仅用于有界错误信息； 不要把 secret 传给子进程。它只作为显式测试/bridge adapter，不能代表本机 常驻模型传输，也不能进入 auto。
• auto 当前顺序是 UDS legacy NPU、远程 OpenAI-compatible。Fake 和 subprocess 必须显式选择，Rust Candle NPU 在硬件提交完成前不能进入 auto。

NPU

• npu_features/ 是忽略提交的厂商源码/部署抓取，仅作逆向参考，不能成为 发布包运行时依赖。
• 原始版本边界是 driver package 0.9.0、driver ABI 1.0.0、CALRT 0.7.6。
• ioctl struct 使用 repr(C, packed)，任何改动都必须同步 size/opcode 测试。
• DMA 单次上限 8 MiB，已知 H2C/C2H 各 8 个 channel；不要绕过现有验证。
• Calbin 参数部署会真实写设备。没有用户明确要求和真实硬件测试计划时，不要 默认开启 deploy_parameters。
• captured Qwen3 fixture 的 logits 是 151936，tokenizer vocab 是 151669；额外 267 个 padded logits 必须在采样前屏蔽。
• host-side MockDevice 测试只能验证解析、地址、buffer 和命令编码，不能证明 job submission、同步、KV cache 或输出数值正确。远程模型 mock 同样不能证明 NPU 硬件正确。
• legacy llama-server 的默认 socket 是 /run/agentos/npu.sock；doctor 必须检查 它确实是可写的 Unix socket，不能仅检查路径存在。

Worldline 与持久化

• Btrfs commit tree 使用 readonly snapshot；branch/current 使用 writable snapshot。
• copy fallback 用于开发和无 Btrfs 环境，但当前不会提供内核强制的只读 commit tree。不要在文档里把它描述成与 Btrfs 等价的不可变性。
• commit 是内容/元数据哈希标识；rollback 必须创建新 commit，不能改写历史。
• checkout 要保留 transaction journal、目录 fsync 和可恢复的 replaced tree。
• 分支提交必须检查 base HEAD，禁止 stale branch 覆盖新 HEAD。
• SQLite principal 绑定不可静默重绑；schema 变更要考虑已有数据库升级。

Rust 与依赖规则

• 使用 workspace 的 Rust edition，不添加 MSRV 或 rust-toolchain.toml。
• 第三方依赖集中写在根 Cargo.toml 的 [workspace.dependencies]。
• 版本只写主版本号，例如 serde = "1"，不要固定 1.2.3。
• 内部 crate 统一用 *.workspace = true。
• 读取依赖源码时，从 $CARGO_HOME/registry/src 找实际锁定版本，不靠记忆猜 API。
• 优先复用已有 crate 和抽象，不复制协议类型、HTTP client、schema validator、 runtime probe 或设备 ABI。
• 代码注释默认英文；用户可见文档分别维护英文与中文。
• 不要加入 Python、reqwest 或直接 libc 依赖。
• 保持开发/测试 profile 的快速编译取向，除非有基准数据，不要随意调高 dev 优化或减少 codegen units。

修改流程

1. 用 rg 定位实现和调用方，先确认改动属于哪个 crate。
2. 先写清安全边界和失败模式；系统层能力默认 fail closed。
3. 修改公共协议时，同步所有 backend、tool adapter、CLI 和双语 README。
4. 新增环境变量时，同步 RuntimeConfig::from_env、doctor 和配置表。
5. 新增 NPU ABI 时，对照 npu_features/cal-pcie-0.9.0 或 CALRT 源码，并补布局、 opcode、边界和 mock 测试。
6. 不要改写或删除用户的 npu_features/ 抓取、模型文件和未提交工作。

完成前至少执行：

cargo fmt --all --check
cargo test --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings

涉及 CLI 时还要实际运行相关命令；涉及 OpenAI-compatible 时至少覆盖两种 API 方言的 serialization/parsing；涉及硬件而本机无板卡时，明确报告未执行的验证。

部分 NPU 测试依赖本地、被 .gitignore 忽略的 npu_features/snapshot_20260801。fixture 不存在时，应将硬件抓取测试与普通 workspace 测试分层，而不是把模型数据提交进仓库或伪造通过结果。

完成标准

一次改动只有在以下条件都满足时才算完成：

• crate 边界和依赖方向没有被破坏；
• 非法输入、权限不足、后端缺失和硬件缺失均 fail closed；
• 无 secret 出现在日志、tool output、子进程或 doctor 报告中；
• 单元/集成测试覆盖正常路径与关键拒绝路径；
• fmt、workspace test、严格 clippy 通过；
• README 与实际成熟度一致，未把 host-side MockDevice 或远程模型 mock 写成 NPU 硬件验证。