内核内部

⚫ 本文档面向编写或修改内核代码本身的人。完整规范见 SPEC.md（英文，事实来源）；这里是一张简略地图。语义来自 agent_os_core 源码。

14.1 模型

内核是一个单一的 async 运行时（Tokio），带有事件循环，它：

1. 维护进程表（DashMap<Pid, AgentProcess>）；
2. 每个 tick 调用调度器（schedule() → ScheduleDecision）；
3. 分发回合（run_turn(pid)），调用提供者并执行 tool-call 循环；
4. 在分发前限制资源（预算、组、并发上限）；
5. 路由 IPC；
6. 中介每一次 tool 调用；
7. 向监听者发出事件；
8. 管理会话（SessionRegistry）。

内核持有可选的服务句柄，由宿主在加载时一次性接入（message_store、state_store、provider、pricing 等）——如果句柄未接入，相应的 syscall 会回应“未配置”。

模块化。 功能（cron、workflow、connectors、memory、model_router、通道等）已从内核中移出到模块，并作为 host 端口接入。Kernel 不再有类型化字段 cron_service/workflow_service/connector_service，而是有一个中性的接缝 kernel::KernelServices，由宿主从端口 agent_os.Cron / agent_os.Workflow / agent_os.Connectors 填充（kernel.services().set_*）。内核不依赖任何功能；详情见 docs/27-core-modularization.md §5 和 32-building-a-module。

加载循环：

loop {
    decision = schedule()
    match decision {
        Run(pid)       → run_turn(pid)
        Idle           → sleep(50ms)
        AtConcurrencyLimit → sleep(50ms)
        Shutdown       → break
    }
}

14.2 基本抽象

进程状态机

spawn → Created → (init) → Ready ⇄ Running → (exit) → Terminated
                              │
                              └→ Blocked{reason} → (unblock) → Ready

• Created — 已分配，未初始化。
• Ready — 等待调度器（is_runnable()）。
• Running — 消耗推理。
• Blocked { reason } — 等待外部事件（tool 结果、IPC、输入）。
• Terminated { exit_code } — 已完成（0）或被杀死（≠0）。

回合与 tool-call 循环

1. 内核选择进程 P。
2. 将 P 的上下文 + 最近的 tool 结果发送给提供者。
3. 提供者流式输出 token。
4. 如果 LLM 请求 tool-call，内核暂停流，校验调用，执行处理程序（带截止时间），将结果作为 tool 消息添加，并恢复推理。
5. 当 agent yield、阻塞、时间片耗尽或预算用尽时，回合结束。

并发仅在 provider.stream 周围以 Semaphore 计量——tool 调用和钩子无需许可即可进行，因此慢工具不会让其他会话“饥饿”。

上下文窗口

ContextWindow { max_tokens, messages, eviction, summary }。驱逐策略： Fifo（丢弃旧的）、SummaryFirst { keep }（将旧的折叠为摘要，默认 keep=8）、SlidingWindow { n }。驱逐还会清理那些父 assistant 消息已被删除的孤立 tool 结果。

预算

TokenBudget { max_per_turn, bucket: TokenBucket, max_total, … }。 TokenBucket — 经典漏桶（capacity + refill_rate）。组 BudgetGroup 增加两个可选层：per-user（user_id 上的子桶）和 per-session。分发前检查：组 → per-user → per-session（can_consume_for）；耗尽的层 — BudgetLevel::{Group,User,Session}。

IPC 与 syscall

MessagePayload：Text、Json、Signal（Terminate/Pause/Resume/Interrupt）、SpawnRequest、SpawnResult。

Syscall：Spawn、Fork、Kill、Yield、Send/Recv、ToolCall、SetState/GetState/DeleteState、Checkpoint/Restore。

钩子

HookHandler 带以下点位：before_user_message（transform/inject/suppress/reply/notice）、before_tool_call（rewrite args / deny / short-circuit）、after_tool_result（redact/transform）、before_inference（请求变更；deny → 阻止，response → 合成响应）、before_retry（允许/禁止重试 + backoff）、before_syscall（syscall/IPC 过滤，deny）、after_turn、after_assistant_message（output-guardrail）、on_token（流式审核）、before_context_evict（自定义压缩）、after_loop、on_spawn/on_terminate/on_error、on_session_created/on_session_closed、on_budget_threshold。另有 merge_user（身份合并）、memory_inspect（检查）、apply_feedback（like/dislike）。

组合：Hook.priority（越高越早）、enabled、激活条件 when { templates, agents, users, sessions }、global（目录 config/hooks/*.yaml）。每次调用都经过 Kernel::run_hook（catch_unwind + 超时 hook_secs），并在 (hook, point) 对的 HookMetric 中计入（GET /v1/hooks/metrics）。HookOutcome { inject, replace_message, reply, notice, suppress }。

14.3 调度器

SchedulingPolicy：RoundRobin（默认）、PriorityPreemptive、FairShare、DeadlineDriven。Scheduler { policy, time_slice, max_concurrent }。 ScheduleDecision：Run(pid) | Idle | AtConcurrencyLimit | Shutdown。

14.4 推理提供者

trait InferenceProvider {
    fn provider_type(&self) -> &str;
    async fn stream(&self, request) -> Result<Box<dyn Stream<Item=Result<InferenceEvent, InferenceError>>>>;
}
enum InferenceEvent { Token(String), ToolCall(ToolCallRequest), Done(InferenceStats) }

具体实现 — OpenAiProvider（reqwest + SSE）。Pricing 根据统计估算成本。

14.5 存储子系统

14.6 事件与监听者

内核通过总线发出类型化的 ProcessEvent：TurnStart、Token、ToolCall、ToolResult、ToolProgress、TurnEnd、StateChange、Error、Spawned、Terminated、BudgetConsumed、BudgetExhausted、RateLimited、ScheduleBlocked、会话生命周期事件、Cost、工作流步骤。监听者实现 ProcessListener（所有方法默认 no-op）。

14.7 加载

1. 宿主加载配置并构建 Kernel。
2. ToolRegistry 注册内置工具和用户工具； HookRegistry — 钩子。
3. InferenceProvider 连接到 LLM。
4. 连接服务句柄（message_store、state_store、cron_service、 workflow_service、pricing）。
5. 加载代理模板（内置 + YAML）。
6. 生成 Bootstrap 代理（或在会话首次请求时惰性生成）。
7. 调度器循环启动。
8. 宿主监听外部请求（HTTP + SSE）。

14.8 设计决策

1. 默认采用协作式多任务；抢占为可选项。
2. spawn 和 fork — 两者均受支持；fork 始终继承预算组。
3. 工具级成本核算 — 每个 ToolResult 携带 ToolCost。
4. I/O 经由内核 — 代理从不直接调用工具。
5. 子系统为选择性加入 — 未连接时返回“未配置”，而非崩溃。

14.9 非目标

多租户（一个实例 = 一个租户）、分布式调度器、 微调、内核中的图工作流（这属于服务端层）、实时保证。

14.10 源码地图

14.11 构建与测试

由三个 crate 组成的 Cargo 工作区：

cargo build                       # debug-сборка всех бинарников
cargo run --bin agent-os -- serve # запуск сервера (грузит config/server.yaml)

cargo test -p agent_os_core       # юнит-тесты ядра/инструментов/хуков
cargo test -p agent_web_bot       # тесты сервера, auth, proxy, login, sessions
cargo test -p agent_web_bot --lib # HTTP-слой (роутинг, auth, login, access-лог)

widget/ 中的组件在 agent_web_bot 处通过 npm 自动构建 build.rs — 无需单独的 npm run build。集成测试 crates/host/tests/ 需要有效的 LLM 密钥，默认不运行。