ENTRY 001
LLM 上下文預設：甚麼路徑會加、甚麼不加
一句話總結：每一次 LLM 呼叫的
system 內容，是由
core/mokagi.py → get_system_context() 組出來的 ＝
「soul/ 目錄下被選中的檔案」＋「一段自動產生的 【環境】資訊」。
而「被選中的檔案」由前端傳入的 context_files 決定：沒傳＝全部 soul 檔都加；空陣列＝全不加；有清單＝只加清單內的檔。
① 真正寫在程式碼的哪一句（檔案 → 行號）
| 邏輯 | 檔案位置 | 行號 |
|---|---|---|
組上下文的核心函式 get_system_context(agent_name, owner, owner_time, context_files=None) | core/mokagi.py | 221 |
靈魂目錄路徑 soul_dir = …/{work_dir}/soul | core/mokagi.py | 270-271 |
掃描所有檔：for filename in sorted(os.listdir(soul_dir)) | core/mokagi.py | 274-276 |
過濾條件：if context_files is not None and filename not in context_files: continue | core/mokagi.py | 277-279 |
只讀「普通檔」、跳過子目錄 os.path.isfile | core/mokagi.py | 281-282 |
每份檔內容包成區塊 ## 來自 {filename} | core/mokagi.py | 283-287 |
| 最後附上【環境】資訊（時間/系統/目錄/工具/房間/權限…） | core/mokagi.py | 291-302 |
系統上下文快取 60 秒 _system_context_ttl = 60 | core/shared.py | ─ |
| 第一輪真正的 system 組裝（把前端 context_files 傳進來） | core/mokagi.py（process_message） | 3085 |
「工具循環用」的無 soul 版本（context_files=[]） | core/mokagi.py | 3087 |
| 工具循環中把 system 換成無 soul 版 | core/mokagi.py | 3127、3320 |
# —— core/mokagi.py 行 3084-3087（process_message 內）——
# 系統提示：基本角色定義，由 context_files 控制載入哪些靈魂文件
agent_body = get_system_context(agent_name, owner, owner_time, context_files=context_files)
# 🔧 工具循環用的無 soul 版本（純工具推理，不加載 soul 文件）
agent_body_no_soul = get_system_context(agent_name, owner, owner_time, context_files=[])同一份
get_system_context() 在 core/prompt_manager.py 也有副本（launcher／背景程序用）；另有 call_llm(include_soul=True) 開關（core/mokagi.py 行 1011／1046-1057）可把 soul 合併進 system_prompt，供角色扮演等呼叫點使用。② 甚麼路徑「會加」、甚麼「不加」
✅ 會自動加進 system_prompt 的
加~/.mok/agent/{Agent名}/soul/ 下的所有檔案（不分副檔名，txt/md 皆可；內容非空且能用 utf-8 讀取）— 依檔名字母排序，故常用數字前綴控制先後，例如 00_共通規則.md、agent.md、user.md。
加自動產生的「【環境】」區塊（程式碼在行 293-301）——永遠加，即使 context_files=[] 也保留。
❌ 預設「不加」的（要另外靠工具/記憶去讀）
不加jobs/、logs/、soul/ 以外的 *.md（例如房間根目錄的 保留清單.md、知識庫檔案）
不加Agent 個人設定檔 ~/.mok/agent/{Agent名}/.{Agent名}（如 .mokagi說明）與 .memory/ 資料庫
不加soul/ 裡的子目錄（不遞迴）、空檔案、讀取失敗的檔案
不加工具循環（多輪工具調用）的後續迭代：system 被換成 agent_body_no_soul，soul 不重複載入、歷史/記憶/語義搜索也改由 LLM 自己呼叫 memory 等工具取得。
③ 各「入口路徑」預設到底載入哪些 soul 檔（實測對照表）
| 入口／前端 | 設定寫在（檔案） | 行號 | 預設 context_files | 效果 |
|---|---|---|---|---|
網頁個人對話 html/user.html | html/user.html | 198 | ['agent.md'] | 只載 agent.md |
API／客服 html/static/api.js | html/static/api.js | 608 | CONFIG.context_files || ['agent.md'] | 沒設時只載 agent.md |
會議模式 html/會議模式/index.html | html/會議模式/index.html | 713、987 | ['agent.md','user.md'] | agent＋user，不含 soul.md |
SocketIO 聊天 /api/chat（後端接收前端參數） | frontends/mok_web.py | 1070、640 | data.get("context_files", None) | 前端沒帶＝None＝全部 soul 檔都加 |
Telegram frontends/mok_tg.py | frontends/mok_tg.py | ─（無此參數） | None | 全部 soul 檔都加 |
網頁主頁聊天 html/index.html＋html/static/main.js | html/static/main.js | 2392、2444 | （不帶 context_files） | =None＝全部 soul 檔都加 |
直播房3 agent/病毒引擎/jobs/直播房3/index.html | mok_web.py:1827 → 8935 _llm_bridge.py → /api/chat | bridge 476、632 | （不帶 context_files） | =None＝全部 soul 檔；另前置注入【直播模式】守則＋真實時間、以 guest 入 core；mokagi 失效時 fallback raw deepseek |
對照官方 README 的「文件使用時機」表（
※ 註：實際程式目前 user.html 只送
※ 另：README 未列 網頁主頁聊天（
~/.mok/README.md 行 226-230）：多輪工具調用循環＝無；會議模式＝agent.md＋user.md；api客服模式＝agent.md＋user.md；個人對話＝agent.md＋soul.md＋user.md；tg對話＝agent.md＋soul.md＋user.md。
※ 註：實際程式目前 user.html 只送
['agent.md']，與 README 描述略有出入，以程式碼為準。※ 另：README 未列 網頁主頁聊天（
html/index.html＋html/static/main.js）與 直播房3（/api/llm_bridge/<agent> → 本機 8935 bridge → /api/chat）兩條；兩者都不帶 context_files＝None＝全部 soul 檔都加。
④ 常被誤會的路徑：/game、/game2、🎮 按鈕
/game/、/game2/ 只是 mok_web.py 的靜態網頁資產路由（行 1642-1643，serve html/game、html/game2 的 3D／賽車小遊戲網頁），主頁的 🎮 按鈕（html/index.html 行 160）也是右側面板工具——這些都不屬於「LLM 上下文」，不會被注入 system_prompt。若想把某個遊戲／專案「教」給 Agent，正解仍是寫成 soul/*.md（或放知識庫、用工具讀取）。
⑤ 想改預設時的 3 個下手點
| 目的 | 改哪裡 |
|---|---|
| 讓「某一種前端」多載/少載某靈魂檔 | 改該頁面的 context_files（user.html:198、api.js:608、會議模式:713…） |
| 讓所有 Agent「預設必載」某規則檔 | 放到每個 soul/ 底下（前端沒指定清單時＝全載）；或調整後端呼叫點的預設值 |
| 調整【環境】區塊內容（節省 token 等） | core/mokagi.py 行 291-302 的 env_info |