文件 v0.30.0
首頁 GitHub

Session 與 Agent

Session

Session 是 Agenvoy 的核心單位。每個 session 擁有自己的對話 context、記憶、agent 人格與工具配置。

儲存路徑：~/.config/agenvoy/sessions/<sid>/

檔案 用途
bot.md Agent 人格定義（frontmatter + markdown 內文）
status.json 目前執行狀態與 active task 清單
action.log 工具呼叫稽核日誌
summary.json / summary.meta.json 滾動摘要與其增量游標
usage.log 供 /usage 使用的各模型 token 用量紀錄
input_history 該 session 的 TUI 輸入歷史
mcp.json Session 範圍的 MCP server 配置

History、summary 與 config flag 存於 ToriiDB（DBSessionHist、DBSessionSummary、DBConfig），而非 per-session JSON。

Session prefix 與生命週期

Prefix 生命週期
cli-* 永久（由 TUI /new 或 POST /v1/session 建立）
http-* 永久（由 POST /v1/send 帶 persist=true 建立）
dc-* 永久（Discord channel）
tg-* 永久（Telegram chat — per-chat，該 chat 內所有使用者共用）
temp-* idle 30 分鐘後回收（POST /v1/send 與 subagent session 的預設值）

清理透過 cron 每 30 分鐘執行一次（並於啟動時執行一次），僅針對 temp-* prefix — cli-*、http-*、dc-* 與 tg-* 永不自動回收。

bot.md — Agent 人格

每個 session 可宣告自己的人格：

***
name: mobile-builder
***

You are an expert mobile application architect specializing in
SwiftUI, Jetpack Compose, and React Native...

Frontmatter 的 name 同時作為查找鍵（GetSessionIDByName）；內文於每一輪 render 進 system prompt 的 ## Bot Persona 區塊。以 TUI /bot 或 GET / POST /v1/session/:id/persona 編輯。

Agent routing

三種方式決定由哪個 agent 處理任務：

1. 自動 — dispatcher LLM 分析輸入，並透過 SelectAgent() 挑選最合適的 provider。

2. :name 一次性覆寫 — 在任何輸入前加上 :session-name，即可將單一命令派送至指定 session，而不改變 primary pointer：

:mobile-builder build me a SwiftUI login screen

exec.Run 中的解析順序：:name session 指派 → skill 匹配（/skill-name）→ model:<hint> 路由偏好 → Execute。無法解析的名稱會讓該次執行直接失敗，而非靜默回退。

3. invoke_subagent 工具 — agent 於執行期間 in-process（無 HTTP）呼叫另一個 agent，從 parent ctx 繼承 AllowAll 與 WorkDir。

Subagent 在只收集（collection-only）憲章下執行——負責蒐集與回報，不巢狀、不寫入。排除集由三部分組成：

來源 排除項目
憲章基礎 invoke_subagent、list_subagent_sessions、write_file、patch_file、generate*（萬用字元）
TUI 專屬 tool / skill install_dependence；extension-upload、extension-install
呼叫端的 exclude_tools 母 agent 傳入的任何項目

ask_user 不被排除——subagent 可透過共用的 pending registry 向使用者提問。同時最多 3 條 subagent 並行執行（maxConcurrentSubagents）；第 4 條在等待空位時，自身的 MaxSubagentTimeoutMin（30 分鐘）timeout 已在倒數，因此大量 fan-out 應以 3 為單位分批派送。每筆結果帶有用量前綴，並匯總進母 session 的總計。

Permission mode

Mode 行為
single-confirm 每個非 ReadOnly 工具呼叫都需使用者確認（agen cli 的預設值）
always-allow 工具自動執行；LLM 被指示對七類真正不可逆的操作先呼叫 ask_user

在 always-allow 下仍需明確 ask_user 的七類不可逆操作：

  1. 檔案系統 —— rm -rf / rm -r、刪除目錄或非本次任務產生的既有檔案
  2. 資料庫 —— DROP DATABASE / DROP TABLE / TRUNCATE、無 WHERE 的 DELETE / UPDATE、任何正式環境 DSN
  3. Git —— reset --hard、對 main/master 的 push --force、刪除共用分支、clean -fdx
  4. 系統 —— chmod 777 / chown -R、/etc / /usr / /System 底下的修改、launchctl / systemd 變更、sudo 提權
  5. 覆寫 —— 未讀取過的非空既有檔案、.env / 憑證 / lock 檔 / .git/index
  6. 雲端與基礎設施 —— gcloud / aws / kubectl delete、terraform destroy
  7. 行程 —— shutdown / reboot、對系統服務 PID 執行 kill -9

一般寫入（write_file / patch_file、build 與測試指令、git status / add / commit、唯讀 shell）直接執行。此閘門由 system prompt（configs/prompts/system_prompt/always_allow.md）強制，而非硬編碼的 Go 端 filter。

Per-session 併發

MaxSessionTasks（NumCPU × 4）限制單一 session 可同時執行的 Execute() 呼叫數。超額的呼叫者透過 EnterConcurrent(sid) 等待，並在有空位後才出現於 status.json。此值為套件常數，不從 config.json 讀取。

取消執行

取消是逐任務而非逐 session：POST /v1/session/:id/cancel/:task_id 停止單一執行中的任務，task_id 取自 /v1/session/:id/status。刻意不提供「全部取消」的變體，因此可在不影響同 session 其他任務的前提下丟棄某個長跑任務。在 TUI 中，執行期間按 Esc 會對當前任務開啟取消確認 popup。

EN