Architecture

🌐 English | 中文

Architecture

Philont uses a kernel-style separation, borrowed from operating-system design: a small, strict mechanism core defines how tools run and how policy is enforced, while the heavy, evolving capabilities (deep reasoning, memory, self-learning) live in a policy/userspace layer. The model behind the API is treated like an untrusted, replaceable component that is only ever asked to take the next step.

This split is how Philont tries to make smaller models practical for long-running work — see Why Smaller Models.

Package layout

Philont-Agent/
├── agent-policy/   Permission matrix, validator chain, SHA-256 audit log, grant store.
├── agent-tools/    Built-in tools (fs, shell, network, git, vision, reasoning runtimes) + SKILL.md loader.
├── agent-mcp/      MCP bridge — mounts external MCP servers as native tools.
├── agent-plugins/  Third-party plugin discovery and sandboxed loading.
├── agent-memory/   5-layer memory, self-learning loop, autonomy drives, plan tools, deep_explore state.
├── server/         HTTP + WebSocket server; chat handler; WeChat / Telegram gateways; gates.
├── web-ui/         Lit-based Web UI (chat · memory · autonomy).
├── launcher/       Supervisor: setup wizard + process management.
└── demo/           End-to-end demos.

Build order (each depends on the previous): agent-policy → agent-tools → agent-mcp → agent-plugins → agent-memory → server / web-ui / launcher. scripts/build-all.{sh,ps1} handles it.

The layers, bottom to top

Layer	Package(s)	Responsibility
Mechanism (kernel)	agent-policy	The non-negotiable core: a 3×4 capability matrix, a validator chain, a grant store, and a SHA-256-chained audit log. Decides whether a tool call may run. See Permission & Security.
Tool runtime	agent-tools, agent-mcp, agent-plugins	The set of things the agent can do: filesystem, shell, network, git, vision, and the formal-reasoning runtimes (z3, PARI/GP, magnitude). External capabilities mount via MCP; third-party code via plugins.
Policy (userspace)	agent-memory	The "intelligence": 5-layer persistent memory, the self-learning/reflection loop, the autonomous drives, the plan-protocol tools, and deep_explore reasoning-tree state.
Orchestration	server	The turn loop (chat-handler.ts): builds context, calls the model, runs tools through the policy core, and applies the in-turn gates (plan, honesty, viability) that intercept and correct the model before its output reaches a user.
Surfaces	web-ui, launcher, channel gateways	Where you interact: Web UI, WeChat, Telegram, headless CLI — all driven by one server process.

The turn loop (server/src/chat-handler.ts)

A single user/channel turn flows through roughly these stages:

1. Build context — assemble a memory prefix (facts/skills/notes index, host environment, active plan) and recall conversation history from the global timeline (recency + FTS keyword recall). The model does not carry a session buffer across turns; it re-recalls from the raw timeline each turn (see Memory System).
2. Classify — for a complex request the model calls task_mode_classify; slow arms the plan protocol.
3. Tool loop — each model step proposes a tool call. The call passes through the policy core (matrix → grant → validator chain → audit) and the plan gate (blocks write/execute before a plan exists). Read-only exploration flows freely.
4. In-turn correction — repeated same-root-cause failures trigger reflection; an active plan can be auto-revised.
5. Honesty gates — before final text is streamed to the user, it is checked against the turn's real tool results; a detected lie forces one honest regeneration.
6. Close & learn — the plan closes with a verified outcome; a reflection pass distills routing rules, playbooks, and skills.

Why kernel-style?

Three properties fall out of the separation:

• Model-agnostic. Because rigor lives in the runtime, the model is swappable: Claude, DeepSeek, GLM, Kimi, MiniMax, Gemini, or your own endpoint. No code changes — just config.
• Enforced, not suggested. A gate is code in the turn loop. Unlike a system-prompt instruction, the model cannot choose to ignore it.
• Auditable. Every tool call and every policy decision is appended to a hash-chained audit log, so the agent's behaviour is reconstructable after the fact.

---

中文

English | 中文

架构

Philont 借鉴操作系统设计,采用 kernel 式分层:一个小而严格的机制(mechanism)内核定义工具如何运行、策略如何执行;而沉重且持续演化的能力(capability)(深度推理、记忆、自学习)放在 policy/用户态层。API 背后的模型被当作一个不可信、可替换的组件,每次只被要求走下一步。

这一分层是 Philont 尝试让较小模型实际承担持续性工作的方式 —— 见为什么把较小模型作为一等目标。

包结构

Philont-Agent/
├── agent-policy/   权限矩阵、校验链、SHA-256 审计日志、授权存储。
├── agent-tools/    内置工具(文件/shell/网络/git/vision/推理运行时) + SKILL.md 加载器。
├── agent-mcp/      MCP 桥 —— 把外部 MCP server 挂载为原生工具。
├── agent-plugins/  第三方插件发现与沙箱加载。
├── agent-memory/   5 层记忆、自学习回路、自主驱动、plan 工具、deep_explore 状态。
├── server/         HTTP + WebSocket 服务;chat handler;微信/Telegram 网关;各类门。
├── web-ui/         基于 Lit 的 Web UI(对话 · 记忆 · 自主)。
├── launcher/       监督进程:首次向导 + 进程管理。
└── demo/           端到端示例。

构建顺序(逐级依赖):agent-policy → agent-tools → agent-mcp → agent-plugins → agent-memory → server / web-ui / launcher。由 scripts/build-all.{sh,ps1} 处理。

分层(自底向上)

层	包	职责
机制(内核)	agent-policy	不可妥协的核心:3×4 能力矩阵、校验链、授权存储、SHA-256 链式审计日志。决定一次工具调用能否运行。见 权限与安全。
工具运行时	agent-tools、agent-mcp、agent-plugins	agent 能做的事:文件、shell、网络、git、vision,以及形式推理运行时(z3、PARI/GP、magnitude)。外部能力通过 MCP 挂载;第三方代码通过插件。
策略(用户态)	agent-memory	「智能」所在:5 层持久记忆、自学习/反思回路、自主驱动、plan 协议工具、deep_explore 推理树状态。
编排	server	turn 主循环(chat-handler.ts):构建上下文、调用模型、把工具走策略内核,并施加 turn 内的各类门(plan / 诚实 / 可行性)在输出到达用户前拦截并纠正模型。
触面	web-ui、launcher、渠道网关	你交互的地方:Web UI、微信、Telegram、无头 CLI —— 全部由同一个 server 进程驱动。

turn 主循环(server/src/chat-handler.ts)

一次用户/渠道 turn 大致经过以下阶段:

1. 构建上下文 —— 组装记忆前缀(facts/skills/notes 索引、主机环境、活跃 plan),并从全局时间线召回对话历史(最近 + FTS 关键词召回)。模型不跨 turn 携带会话缓冲,而是每 turn 从原始时间线重新召回(见 记忆系统)。
2. 分类 —— 复杂请求下模型调 task_mode_classify;slow 武装 plan 协议。
3. 工具循环 —— 模型每步提出一次工具调用。调用先过策略内核(矩阵 → 授权 → 校验链 → 审计),再过 plan 门(计划存在前挡住 写/执行)。只读探索可自由通过。
4. turn 内纠偏 —— 反复同根因失败触发反思;活跃 plan 可被自动修订。
5. 诚实门 —— 最终文本流式发给用户前,先与本 turn 真实工具结果对账;检出谎言则强制一次诚实重写。
6. 关闭与学习 —— plan 以可验证结果关闭;一次反思过程蒸馏出路由规则、playbook、skill。

为何用 kernel 式?

分层带来三个性质:

• 模型无关。 因为严谨性在运行时,模型可替换:Claude、DeepSeek、GLM、Kimi、MiniMax、Gemini 或你自己的端点。改配置即可,无需改代码。
• 强制而非建议。 门是 turn 循环里的代码。不同于系统提示词指令,模型无法选择忽略它。
• 可审计。 每次工具调用、每个策略决策都追加进哈希链式审计日志,事后可重建 agent 的行为。