Communitygithub.com

V4TIME/V4SKILL

在 Termux 中建置 Flask AI 應用程式,並整合 NaraRouter。

V4SKILL 是什麼?

此技能指導開發者在 Android 的 Termux 環境中,使用 Python 與 Flask 建立本機 AI Web 應用程式。它專注於整合多種 AI API,特別是 NaraRouter 和 NVIDIA NIM API,並提供統一的調度引擎。技能也涵蓋語音模式(使用 Web Speech API)、會話管理,以及遵循使用者偏好的極簡設計原則。支援的開發工具鏈包括 Python、Flask 和底層的 urllib,而非 requests,以確保在行動網路環境下的穩定性。同時,它強調了持續備份至 GitHub 的重要性,以及一個結構化的除錯流程來排查伺服器、靜態檔案和 JavaScript 的常見問題。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/V4TIME/V4SKILL/tree/HEAD/termux-flask

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

在 Termux 中執行本機 AI Web 應用程式

在執行 Termux 的 Android 裝置上建置並執行本機 Web 應用程式,整合 AI API(特別是 NaraRouter),並可選擇使用 Hermes Agent 作為推理後端。

使用時機

  • 使用者想要在手機上執行本機 AI 助手/聊天介面
  • 在 Termux 中使用 Python/Flask 建置 Web 應用程式
  • 透過描述驅動的路由整合多個 AI API
  • 透過瀏覽器 Web Speech API 新增語音模式
  • 跨聊天管理工作階段與記憶
  • 使用者貼上開發工具的安裝說明(二進位發行版、Rust/cargo、npm/npx、pip),並要求安裝與使用 — 先評估在手機/Termux 環境中的可行性,取得許可後再安裝

架構模式

瀏覽器(Android 上的 Chrome) → Flask 後端(Termux) → AI API
                                 ↓
                             Hermes Agent(可選,作為大腦)

關鍵原則: Web 應用程式是介面層。Hermes Agent(若使用)是大腦。Flask 後端則作為兩者之間的橋樑。

快速開始

# 在 Termux 中
mkdir ~/sayip && cd ~/sayip
mkdir -p templates static/css static/js storage/sessions
# app.py — 最小化 Flask 入門
from flask import Flask, render_template, request, jsonify
from pathlib import Path
import json, time, uuid, os

app = Flask(__name__, template_folder="templates")
HERMES_HOME = Path(os.path.expanduser("~/.hermes"))
SAYIP_STORAGE = Path(os.path.expanduser("~/sayip/storage"))

@app.route("/")
def index():
    return render_template("chat.html")

@app.route("/api/chat", methods=["POST"])
def chat():
    data = request.get_json()
    # ... 處理訊息,呼叫 API,回傳回應

if __name__ == "__main__":
    app.run(host="127.0.0.1", port=5000)
# 執行
python3 app.py
# 在 Chrome 中開啟:http://127.0.0.1:5000

API 整合模式

NaraRouter(首要推薦)

NaraRouter 是一個統一的 AI 閘道,提供 53 個以上的模型,並有免費層級可用。

金鑰格式: sk-nry-...(以 sk-nry- 開頭)

端點(皆使用相同基礎 URL + Bearer 金鑰):

端點類型用途
https://router.bynara.id/v1/chat/completionsOpenAI 相容聊天、一般任務
https://router.bynara.id/v1/messagesAnthropic 相容Anthropic 格式請求
https://router.bynara.id/v1/responsesOpenAI Responses有狀態回應 API
https://router.bynara.id/v1/embeddingsOpenAI Embeddings向量嵌入
https://router.bynara.id/v1/modelsLIST取得您的方案可用的模型
https://api-images.bynara.id/v1/images/generations圖片生成文字轉圖片
https://api-images.bynara.id/v1/images/edits圖片編輯圖片編輯

使用前測試金鑰:

curl -s -X POST https://router.bynara.id/v1/chat/completions \
  -H "Authorization: Bearer sk-nry-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"agnes-2.5-flash","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'

已知可用的免費層級模型: agnes-2.5-flash、agnes-2.0-flash

檢查您方案的模型:

curl -s https://router.bynara.id/v1/models \
  -H "Authorization: Bearer sk-nry-YOUR_KEY" | python3 -c "import sys,json; [print(m['id']) for m in json.load(sys.stdin).get('data',[])]"

重要: 並非所有 53 個模型都在每個方案中。deepseek-v4-pro-0813-bynara 需要額度。deepseek-v4-flash-free 可能不包含在內。設定前務必測試。

NVIDIA NIM API(integrate.api.nvidia.com/v1)

NVIDIA NIM 透過一個與 OpenAI 相容的端點提供 82 個以上的模型。 基礎 URL: https://integrate.api.nvidia.com/v1 端點: https://integrate.api.nvidia.com/v1/chat/completions 金鑰格式: nvapi-(例如 nvapi-_qJeGmEP...)

使用前測試金鑰:

curl -s -X POST https://integrate.api.nvidia.com/v1/chat/completions \
  -H "Authorization: Bearer nvapi-..." \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"model":"nvidia/nemotron-3.5-lightning-30b-a3b","messages":[{"role":"user","content":"hi"}],"max_tokens":10,"stream":true}'

已知可用的免費層級模型(已在 Termux 行動網路測試):

模型 ID金鑰狀態備註
nvidia/nemotron-3.5-lightning-30b-a3bnvapi-...可用快速(簡單任務約 5-7 秒),推理能力強,支援思考模式。在行動裝置上最可靠。
gpt-oss-20bnvapi-...可用OpenAI 相容
deepseek-ai/deepseek-v4-pro-0813nvapi-...逾時風險在桌面上可用,在 Termux 行動網路上經常逾時
moonshotai/kimi-k3nvapi-...逾時風險具備視覺能力,但在行動網路上會逾時

金鑰不對稱警告: 並非所有模型都適用於所有金鑰。金鑰 1(nvapi-_qJeGmEP...)有更廣泛的存取權限。金鑰 2(nvapi-WDb7Rr...)限制較多 — 某些模型會回傳 404。在設定前,務必使用特定金鑰測試模型。

失效金鑰指標:

  • 401 Unauthorized — 金鑰無效/已過期
  • 404 Not Found 針對某個模型 — 該模型不在這個帳號/金鑰下
  • 連線逾時(30 秒以上)— API 從此網路無法存取/速度緩慢
  • Teamorouter sk-teamo-... 金鑰 → 在 OpenAI 端點(https://api.teamorouter.com/v1)回傳 insufficient_balance;在 Anthropic 端點(https://api.teamorouter.com)不支援該模型。已失效。雖然提供 deepseek-v4-pro-free 模型,但餘額不足無法使用。

完整詳細資訊請參閱 references/nvidia-api.md:模型特定的 Python 模式(Nemotron 思考模式、DeepSeek 非串流、Kimi 視覺多模態)、串流 reasoning_content 提取、用於 urllib 的執行緒式硬逾時模式,以及視覺負載格式。

API 調度引擎

當您設定多個 API 時,請建置一個調度器,它會:

  1. 分類任務(數學、程式、科學、一般)
  2. 根據描述文字選擇最佳的 API
  3. 呼叫該 API,回傳結果
  4. 如果第一個 API 失敗,則回退到其他 API

整合詳細資訊請參閱 references/nararouter-api.md。

使用標準函式庫 urllib,而非 requests

在 Termux 中,pip install requests 在下載大型套件時可能會逾時。請改用 Python 的標準函式庫 urllib — 它始終可用,且能良好處理 JSON API:

import urllib.request, json

def call_api(url, payload, api_key):
    data = json.dumps(payload).encode()
    headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
    req = urllib.request.Request(url, data=data, headers=headers, method="POST")
    with urllib.request.urlopen(req, timeout=30) as resp:
        return json.loads(resp.read())

設計偏好(使用者特定)

極簡、專業、非 AI 生成的外觀:

  • 暗色主題,緊湊間距,無漸層,無裝飾性陰影
  • 在適當的地方使用等寬字型(程式碼、API 金鑰、時間戳記)
  • 聊天氣泡使用簡單矩形 — 除非有功能性需求,否則不要使用圓角
  • 側邊欄 = 純文字列表,除非有意義,否則不要使用圖示
  • 搜尋參考實作,而非從頭開始設計
  • 有疑慮時,寧可刪減功能,也不要增加功能

具體的反模式 — 這些會讓 Web 應用程式看起來像 AI 生成的,應予以刪除:

  • 每個標題/圖塊/按鈕中的表情符號(🤖、⚙、🎭、🔌、🧠、💬、🎤)— 移除。僅使用純文字標籤。
  • 懸停時的強調發光 / box-shadow(box-shadow: 0 0 12px var(--accent-glow))— 移除。僅使用純色。
  • 彈跳 / 脈動 / 滑入的關鍵影格動畫(@keyframes bounce、@keyframes pulse、@keyframes slideDown)— 移除。不要有動態設計。
  • 帶有圖示的啟動畫面歡迎卡片(含有 welcome-icon、welcome-hints 網格的 .welcome-screen)— 替換為輸入區域中的一行提示佔位文字。
  • Logo 旁邊的裝飾性品牌圖示(帶有表情符號的 .brand-icon)— 移除。
  • 裝飾標頭的功能帶、徽章、狀態點(.health-badge、.health-dot)— 移除或使其純粹功能化。
  • 漸層背景、毛玻璃效果、半透明疊加層 — 永不使用。

經驗法則: 在瀏覽器中開啟頁面,並問自己:「人類開發者會為一個工具手寫這樣的 CSS 嗎?」如果答案是否定的(因為它有動畫、發光或表情符號裝飾),就刪掉它。正常的工具看起來像終端機、筆記應用程式或極簡的聊天介面 — 而不是像著陸頁。

語音模式:

  • 使用 Web Speech API(SpeechRecognition + SpeechSynthesis)— 免費,瀏覽器內建
  • 切換按鈕來切換文字/語音模式
  • 在語音模式下:麥克風持續監聽,語音→文字→發送,回應→朗讀
  • 語音品質受限於 Android 上 Chrome 提供的功能 — 不要承諾「Ultron 語音」

工作流程偏好(使用者特定)

安裝套件前先詢問: 在執行 pip install 或 apt install 之前,先詢問使用者。這是不可協商的。

持續顯示進度: 如果一個任務需要超過幾分鐘的時間,請顯示中間結果。不要長時間沒有輸出。如果卡住了,請說明情況以及正在嘗試的方法。

無安全說教: 使用者了解 API 金鑰的風險。除非明確要求,否則不要對金鑰安全、暴露或最佳做法進行說教。他們在相關時提供了自己的解釋。

偏好可行的解決方案勝於完美的架構: 先讓東西跑起來。NaraRouter 金鑰測試顯示了這一點 — 測試金鑰,找到可用的模型,進行設定。不要過度規劃。

儲存空間是易失性的 — 儘早備份到 GitHub: 在 Termux/Android 上,應用程式儲存空間(~/sayip/storage/)可能會在伺服器重啟、Termux 重啟或裝置重啟時被清除。在設定 API 金鑰和設定後,立即透過 SSH 將專案推送到 GitHub 儲存庫,以便可以恢復設定。在會話期間,不要假設 storage/ 在重啟後仍然存在 — 在任何重啟後都應重新檢查。由於行動網路會封鎖連接埠 22,通常需要使用 SSH-over-port-443 技巧(請參閱 references/termux-git-ssh.md)。

語音模式必須經過端到端測試才能宣告完成: chat.js 中的 Web Speech API 接線(setupVoice、startListening、speakText)不等同於語音模式可以運作。透過實際對著手機麥克風說話並聽到回應朗讀出來來測試。Android 上的 Chrome 是目標瀏覽器 — 這才是重要的,而非桌面版 Chrome。

除錯

連接埠 5000 已被佔用:

fuser -k 5000/tcp  # 終止佔用連接埠 5000 的程式
# 或使用 ss 檢查:
ss -tlnp | grep 5000

Flask 應用程式無法啟動 / 崩潰:

  • 檢查語法:python3 -c "import py_compile; py_compile.compile('app.py', doraise=True)"
  • 在啟動前檢查連接埠是否空閒
  • 使用 timeout 15 python3 app.py 來查看啟動輸出,而不會阻塞

API 回傳 401/403/payment_required:

  • 金鑰可能無效、已過期,或該模型不在您的方案中
  • 在應用程式中設定之前,先直接使用 curl 測試金鑰
  • 檢查 /v1/models 以查看您的方案實際包含哪些模型

Pip 安裝逾時:

  • 行動裝置上的 Termux 在安裝大型套件時,網路可能緩慢/不穩定
  • 盡可能使用標準函式庫替代方案(urllib 替代 requests)
  • 如果必須安裝,請使用 pip3 install --timeout 30 <package> 以快速失敗

被強制終止的背景 Flask 程序會短暫保留連接埠:

  • 在 pkill -9 -f "[p]ython3 app.py" 之後,等待 2-3 秒再重新啟動。
  • 如果收到「Address already in use」,表示舊程序尚未完全釋放 socket — 請等待更長時間。

在重新啟動 Flask 伺服器以套用程式碼變更之前,請先終止舊程序:

  • 模式:pkill -9 -f "[p]ython3 app.py" && sleep 3 && cd ~/sayip && python3 app.py &
  • 跳過終止步驟會導致「Address already in use」,新實例將無法啟動。
  • 重新啟動後,務必使用 curl -s --max-time 3 http://127.0.0.1:5000/api/health 進行驗證。

當使用者回報 Web 應用程式壞了 / JS 有問題 / 無法運作時,請按此順序診斷:

  1. 確認伺服器正在執行:curl -s --max-time 3 http://127.0.0.1:5000/api/health
  2. 檢查靜態檔案是否回傳 200:curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:5000/static/style.css(以及 app.js、chat.js、voice.js、settings.js)
  3. 檢查伺服器實際提供什麼 HTML:curl -s http://127.0.0.1:5000/ | grep -E 'static/|style.css|app.js|chat.js|voice.js' — 確認 HTML 中的路徑與 Flask 提供的相符
  4. 如果靜態檔案回傳 404,但 HTML 連結顯示相對路徑(如 style.css)而非 /static/style.css,這就是錯誤 — 將兩個模板都修補為使用 /static/ 前綴
  5. 讀取 JS 檔案,並針對 HTML 實際包含的內容檢查每個 document.querySelector / getElementById / .querySelector 呼叫 — 缺少元素會使整個腳本崩潰
  6. 檢查 null 參考導致的崩潰:在沒有漢堡選單元素的頁面上呼叫 el("hamburger")、在 .wrap 不存在時呼叫 messagesEl.querySelector(".wrap")、在 .composer 不存在時呼叫 document.querySelector(".composer .wrap") — 這些都會使 IIFE 崩潰,並導致整個頁面的 JS 失效
  7. 保護元素查詢:在使用結果之前,使用 var el = document.querySelector(selector); if (!el) return;

在進行任何 HTML/模板編輯後,透過檢查伺服器實際提供的內容來驗證前端修復:

  • 對頁面 URL 執行 curl,並 grep 尋找靜態路徑(/static/style.css、/static/js/app.js),即可確認修復已生效。
  • 直接對靜態檔案 URL 執行 curl,並使用 -o /dev/null -w '%{http_code}' 來確認它回傳 200。
  • 在針對執行中的伺服器通過這兩項檢查之前,不要假設 HTML 編輯已生效。

此專案中最常見的「所有 JS 都壞了」原因:

  • HTML 模板使用了相對靜態路徑(style.css、app.js、chat.js),而非 Flask 的 /static/ 前綴(/static/style.css、/static/js/app.js、/static/js/chat.js)。
  • 瀏覽器請求 http://127.0.0.1:5000/style.css → 404。沒有 CSS、沒有 JS 載入 → 頁面沒有樣式且無法運作。
  • 修復:修補兩個模板中的路徑...

Individual skills in this repo

This repo contains 12 individual skills — each has its own dedicated page.

相關技能