開發指南

本專案以 Next.js 15（App Router）、React 19 和 Tailwind CSS 為基礎，使用 TypeScript 撰寫。開始開發前，請先依照快速開始完成本機設定。

常用指令

npm run dev          # 啟動開發伺服器（Turbopack）
npm test             # 執行單元與介面測試
npm run lint         # 程式碼檢查
npx tsc --noEmit     # 型別檢查
npm run build        # 正式版建置
npm start            # 執行正式版建置

提交變更前，建議依序執行測試、程式碼檢查、型別檢查和正式版建置。

測試

npm test 會執行 tests/api.test.ts 和 tests/i18n.test.ts。api.test.ts 會匯入其餘的測試檔案，因此一個指令就能執行全部測試。偵錯時，也可以用 tsx 單獨執行某個檔案：

npx tsx tests/pastedText.test.ts

測試檔案	涵蓋內容
`api.test.ts`	API 路由、服務商設定和請求驗證，並匯入其他測試
`i18n.test.ts`	文案完整性（每個鍵都有三種翻譯，且預留位置一致）、錯誤訊息在地化和各語言的回答要求
`analysisHistory.test.ts`	最近紀錄的去除重複、排序和數量上限
`analysisUrls.test.ts`	解析時連結的保護與還原
`dailySentence.test.ts`	今日一句的產生與驗證
`localOutput.test.ts`	羅馬拼音轉換、串流輸出解析和模型回應解析
`pastedText.test.ts`	貼上網頁和 Markdown 時的格式清理
`phraseRange.test.ts`	多詞圈選與合併
`readingLayout.test.ts`	注音排版中詞與標點的分組
`requestMetrics.test.ts`	Umami 請求指標與錯誤分類
`wordDetailContext.test.ts`	長文中單字詳解的上下文擷取
`wordDetailDictionary.test.ts`	單字詳解結構化結果的解析

專案結構

app/
  api/                # Next.js API 路由（解析、翻譯、釋義、圖片辨識、朗讀、對話等）
  api/_utils/         # 服務商設定、OpenAI 相容 Proxy、工作階段驗證、逾時和今日一句產生
  components/         # 輸入區、解析結果、單字詳情、譯文、AI 助手、設定對話框等
  contexts/           # 介面語言與主題
  hooks/              # 單字詳情、多詞圈選和最近紀錄
  i18n/               # 介面語言與文案（以簡體中文原文為鍵）
  lib/                # 模型清單與各功能的提示詞
  services/api.ts     # 前端 API 呼叫、串流解析和長文分段
  utils/              # 分段、羅馬拼音、貼上清理、統計等工具函式
components/ui/        # 通用 UI 元件
docs/                 # 截圖和 AI Agent 部署指南
tests/                # 測試

新增介面文案

文案定義在 app/i18n/messages.ts 中。簡體中文原文就是鍵，其他三種語言則是值：

app/i18n/messages.ts

"历史记录": {"zh-TW": "歷史紀錄", "en": "History", "ko": "기록"},

在元件中透過 t("历史记录") 使用。新增文案時，請同時提供 zh-TW、en 和 ko 三種翻譯，i18n.test.ts 會檢查完整性。

持續整合

.github/workflows/docker.yml 會在推送到任何分支、推送 v* 標籤、提交 Pull Request 或手動觸發時執行：

驗證

使用 Node.js 22 依序執行 npm ci、npm test、npm run lint 和 npm run build。

建置映像檔

驗證通過後建置 Docker 映像檔。一般分支和 Pull Request 只建置 linux/amd64，用來檢查映像檔能否成功建置。

發布映像檔

推送到預設分支、howendev/dev 分支或任何標籤時，會同時建置 linux/amd64 和 linux/arm64，並在設定了 Docker Hub secrets 時推送多架構映像檔。

架構	建置環境
`linux/amd64`	`ubuntu-latest`
`linux/arm64`	`ubuntu-24.04-arm`

映像檔標籤

觸發方式	產生的標籤
推送到預設分支	`latest`、`<分支名稱>`、`sha-<短提交雜湊>`
推送到 `howendev/dev`	`latest`、`howendev-dev`、`sha-<短提交雜湊>`
推送標籤	`<標籤名稱>`、`sha-<短提交雜湊>`

Docker Hub secrets

在 GitHub 儲存庫中開啟 Settings → Secrets and variables → Actions，新增：

Secret	說明
`DOCKERHUB_USERNAME`	Docker Hub 使用者名稱。
`DOCKERHUB_TOKEN`	Docker Hub Personal Access Token。請勿使用帳號密碼。

未設定這兩個 secrets 時，工作流程只會建置映像檔而不推送，並輸出一則警告。

不要把執行階段的金鑰寫入 Docker 映像檔。DEEPSEEK_API_KEY、GEMINI_API_KEY、CODE 和 Umami 設定應在執行容器時，透過 .env.production 或 -e 參數注入。

Docker 映像檔

Dockerfile 以 node:22-alpine 進行多階段建置，並使用 Next.js standalone 輸出：

執行階段以非 root 使用者 nextjs 執行。
預設監聽 0.0.0.0:3002。
映像檔包含 LICENSE、NOTICE、LICENSING.md 和 LICENSES/ 授權檔案。

貢獻

歡迎提交 Issue 和 Pull Request。新的貢獻請使用與 AGPL-3.0-only 相容的授權，並保留所引入第三方程式碼的聲明。詳見授權條款。

開始使用

使用指南

設定與部署

開發

更多

常用指令

測試

專案結構

新增介面文案

持續整合

映像檔標籤

Docker Hub secrets

Docker 映像檔

貢獻

​常用指令

​測試

​專案結構

​新增介面文案

​持續整合

​映像檔標籤

​Docker Hub secrets

​Docker 映像檔

​貢獻

常用指令

測試

專案結構

新增介面文案

持續整合

映像檔標籤

Docker Hub secrets

Docker 映像檔

貢獻