# 架構分層

Agenvoy 的每一層、實作它的 package 與其職責。

| 層 | 套件 | 職責 |
|---|---|---|
| Entry | `cmd/app` | argv dispatch（`stop` / `update` / `--daemon` / `-p`，v1.3.9 起為 `POST /v1/send` 的單次呼叫用戶端；`--enable-claude-code` 已移除於 v1.2.3）；stdin 非 TTY 時作為 MCP server；初始化 sandbox、filesystem policy、MCP manager |
| App services | `internal/app` | 建立 agent registry 與監看 `config.json`，daemon 與 TUI 皆使用；重新載入 Telegram / Discord、session watcher、MCP 設定、聊天推送 hook 與 skill 執行僅 daemon 使用（v1.2.0 起 TUI 不再開啟任何 MCP 連線）；daemon 啟動由 TUI 使用 |
| Startup | `internal/startup` | 以 launchd plist（macOS）或 systemd service（Linux）登入時啟動，由 `/config` 切換；由 `internal/runtime/startup` 移入，原路徑已不存在 |
| Notes | — | 操作者筆記（`internal/note`、`find_note` 工具、`/v1/note*` 與啟動時的筆記 migration）已於 v1.0.23 移除；舊版 `history.db` 留下的 `note` 表不再被讀取 |
| Runtime singleton | `internal/runtime` | `~/.config/agenvoy/runtime.uid` 鎖（UID、PID、啟動時間）；紀錄中的 daemon 仍存活時，第二個 daemon 直接中止；v1.3.7 起 `agen stop` 會停掉所有執行中的 daemon——以 `ps` 找到的每個 `agen --daemon` 程序（`ListDaemons`）加上紀錄中的 PID——逐一送出 SIGTERM，3 秒寬限後改送 SIGKILL |
| Engine | `internal/agents/exec` | `Prepare` / `Run`（skill 比對、指名 skill、模型解析；`Start` 於 v1.2.1 更名為 `Run`）；iteration loop；tool dispatch；結合 tier 與優先序的 dispatcher 路由自 v1.2.1 起位於 `exec/model`（`Route`，dispatcher 在 `select_with_llm.go`、v1.3.1 起與其競速的 decision model 分派在 `select_with_decision.go`（`select_with_jev.go` 的 TypeSafe beta dispatcher 移除於 v1.3.1），`Next` 負責 fallback 與健康檢查；v1.1.0 起 reasoning 設為 `auto` 的 session 依 dispatcher 判定的工作類型取得等級，取代全域 `auto_reasoning` 開關，且 `pass` tier 模型不會被 dispatcher 選中、也不作為 fallback）；cooldown 與重試（`retryHandler`）；subagent host（`exec/subagent.Exec`，v1.3.0 起最多 `max(NumCPU / 2, 3)` 個並行，之前為 3 個） |
| Decision | `internal/agents/decision` | v1.3.1 新增。設定的 decision model（`typesafe` 或 `openrouter`，以 `router.NewDecision` 建立）：`Available` 列出可選模型（快取 15 分鐘，排除不支援的模型），`Ready` / `Request` / `Decide` / `Batch` / `Confident` 供分派、監看檢查、`search_web` / `fetch_page` 過濾、turn context 的工具缺口提示與 skill 過濾、summary 過濾（cron 階段，以及 v1.3.7 起每個 turn 對 summary 條目的相關性判斷）與 context 超限時的工具步驟刪減共用 |
| Compaction | `internal/agents/exec/compact` | 各模型門檻、tool 歷史與舊歷史折疊、trim 與 raw-tool fallback；v1.3.0 起由超限錯誤學到的輸入上限（`NoteOverflow`）與超限時刪到 80% 的 trim（`TrimRatio`），v1.3.1 起其前先以 decision model 刪減工具步驟 |
| Providers | `go-llm-router` v0.10.2（外部模組） | 跨 14 個 provider 條目及任何 OpenAI 相容端點的統一 `Agent.Send()`；`claude-code` provider（v1.1.0 起位於本 repo，v1.1.4 移入 `go-llm-router`）以本機 `claude` CLI 作為模型，只要偵測到 `claude` binary 就自動啟用（`agen --enable-claude-code` 啟用方式已移除於 v1.2.3）；reasoning 與 fast 模式正規化。speech-to-text 與 text-to-speech 各自獨立路由，由 OpenAI、Gemini 與（v1.0.17 起）OpenRouter 支援 |
| Tools | `internal/tools` + `internal/runtime/toolAdapter` | built-in / API / script / extension tool 定義 |
| MCP | `internal/runtime/mcp` | 建構於官方 `modelcontextprotocol/go-sdk` 的 client 與 server，單一套件 |
| Sandbox | `go-pkg/sandbox` | OS-native 隔離；`Wrap()` 建立指令，v1.3.0 起由 `Run()` 執行 |
| Filesystem | `go-pkg/filesystem`（+ `reader/`）+ `internal/filesystem` | policy-aware 寫入；ToriiDB pathing |

Session 儲存、儀表板、pending 路由、記憶、排程、IPC 與 TUI 見 [執行期分層](/zh/architecture-layers-runtime)。