line-persona: Instructions file for Codex

AGENTS.md：給 AI 助理的施工手冊

這個檔是寫給 AI 編碼助理（Codex / Claude Code / 任何能讀檔、開 code 的 agent） 看的。 你（AI）打開這個 repo，就照這份把使用者的「LINE AI 分身」從頭架到能跑，並能依需求擴充。 人類使用者的白話說明在 使用手冊.md，技術說明在 README.md。

---

這個專案是什麼

line-persona（暱稱「LINE 影分身」）= 一個最小可跑的 LINE 原生 AI 分身框架。 使用者餵自己的資料（人格 + 知識），接雲端或本地 LLM，就能在 LINE 上自動回覆。 核心設計：低門檻。一般人不寫 code，靠你（AI）幫他架。

技術棧：Node.js + Express + @line/bot-sdk + dotenv，LLM 走 OpenAI-compatible /chat/completions。

架構地圖（你動手前先讀懂）

src/server.js        ── LINE webhook 入口：簽章驗證、event 路由、reply、群組存 groupId(供日後主動 push)、1:1 私訊「輸入中」動畫(LINE_LOADING_SECONDS，0＝關；對方要開著聊天室、用 LINE iOS/Android 13.16.0+ 才看得到，LINE 不回報有沒有顯示)
src/brain.js         ── 「大腦插孔」：handleMessage(ctx) -> string。預設組 persona prompt 後呼 llm
src/adapters/llm.js  ── 單一 LLM adapter，OpenAI-compatible，全參數走 .env
src/persona.js       ── 開機讀 persona/*.md 組成 system prompt
src/escalation.js    ── 【選配·預設關閉】轉真人閉環。沒開時 brain.js 與 server.js（私訊媒體）的呼叫直接返回
src/history.js       ── 【選配·預設關閉】多輪對話記憶（只在記憶體）。沒開時 brain.js 只送當句
persona/profile.md   ── 分身人格（誰、口吻、邊界）  ← 使用者要改的
persona/knowledge.md ── 分身知識（FAQ、基本資訊）    ← 使用者要改的
.env.example         ── 設定範本（複製成 .env 填）
data/                ── 執行期資料（groups.json 等），已 gitignore

---

🛠️ 標準施工流程（使用者說「幫我架 / 設定 / 弄好」時，照這跑）

1. 先問使用者拿 3 樣東西（缺哪個就問哪個，別自己編）：
   • LINE Channel access token 和 Channel secret（到 https://developers.line.biz 申請 Messaging API）
   • 大腦選哪個：雲端（OpenAI / Gemini / Claude 的 API key）或本地（Ollama，免 key）
   • 分身的人設與知識：他是誰、做什麼、講話風格、要能回答哪些常見問題
2. 建 .env：cp .env.example .env（Windows：Copy-Item .env.example .env），填入上面拿到的值。
   • 雲端範例：LLM_BASE_URL=https://api.openai.com/v1、LLM_MODEL=gpt-4.1-mini
   • 本地範例：LLM_BASE_URL=http://localhost:11434/v1、LLM_API_KEY 留空、LLM_MODEL=llama3.1
3. 改人設：把使用者給的內容寫進 persona/profile.md（人格 + 邊界，務必含「不確定就說轉真人、不要亂編」）和 persona/knowledge.md（FAQ / 基本資訊）。
4. 安裝啟動：npm install → npm start。
5. 自驗：curl http://localhost:3000/ 應回 line-persona is running（port 被占就改 .env 的 PORT）。
6. 開對外網址：用 tailscale funnel 3000（免費固定）或 ngrok http 3000，取得 HTTPS 網址。
7. 告訴使用者：把 <那個網址>/webhook 貼到 LINE 後台的 Webhook URL，按驗證。注意結尾要有 /webhook。
8. 請使用者用 LINE 傳訊息實測，回報結果。