tutti/CONTRIBUTING.zh-TW.md

為 Tutti 做貢獻

English | 简体中文 | 繁體中文

感謝你有興趣為 Tutti 做貢獻！本指南涵蓋開發環境設定、專案規範，以及讓你的變更順利合併所需的資訊。

參與本專案即表示你同意遵守我們的行為準則。

註：本程式碼庫使用內部代號 tutti，你會在目錄與二進位檔命名中看到它（如 services/tuttid）。

儲存庫結構

• apps/desktop：Electron 桌面外殼、renderer UI、preload 橋接層和原生桌面整合
• services/tuttid：長駐本機的常駐服務，核心業務邏輯所在
• packages/clients/*：共用的領域用戶端
• packages/configs/*：共用的工程設定
• packages/ui/*：共用的視覺系統邊界

開發環境

建議的本機環境：

• Node.js 24 或更高；.node-version 固定了專案基線
• pnpm 10.11.0
• Go 1.24
• golangci-lint v2.12.0

安裝 workspace 相依套件：

pnpm install

對於新建的連結 Git worktree，請改用：

pnpm setup:worktree

這個命令會安裝 workspace 相依套件，接著在平行測試執行前預熱 Electron。它會重用 共享的 Electron 下載快取，並將執行環境解壓縮到新 worktree；不會重用其他 worktree 的 Electron.app。

安裝固定版本的 golangci-lint：

pnpm install:golangci-lint

檢查本機環境：

pnpm setup:dev

以包含前置檢查和預先建置 tuttid 的方式啟動桌面應用程式開發：

make dev-gui

如果你已有可用的 daemon 二進位檔，只想執行原本的 Electron/Vite 開發流程，pnpm dev:desktop 仍然可用。

常用指令

make dev-gui
pnpm build
pnpm typecheck
pnpm lint
pnpm lint:ts
pnpm lint:go
pnpm test:ts
pnpm test:go
pnpm check:golangci-version
pnpm install:golangci-lint
pnpm generate:defaults
pnpm check:defaults-generated

完整驗證入口：

pnpm check:full

儲存庫規則

• 業務邏輯歸屬 services/tuttid
• UI 與桌面整合歸屬 apps/desktop
• 只有存在真實共用邊界時，程式碼才應進入 packages/
• 業務程式碼檔案應保持在 800 行以內；超過即為重構訊號

深入參考：

• 架構總覽：docs/architecture/README.md
• 專案結構：docs/architecture/project-structure.md
• 儲存庫約定：docs/conventions/README.md
• 靜態分析與 lint 規則：docs/conventions/static-analysis.md
• Agent 貢獻者說明：AGENTS.md

提交規範

我們遵循 Conventional Commits：

<type>(<scope>): <subject>

本儲存庫中的範例：

fix(workspace-files): avoid protected directory prefetch
fix(agent): preserve provider permission defaults

常用類型：feat、fix、docs、refactor、test、chore。

開發者原創證書（DCO）

我們要求貢獻者簽署 Developer Certificate of Origin。這是一份輕量聲明，表示你有權依照本專案的授權條款（Apache-2.0）提交貢獻。

用 -s 參數為每個 commit 加上簽署：

git commit -s -m "feat(scope): add something"

這會在 commit message 末尾加上一行 Signed-off-by: Your Name <your@email>。

Pull Request 流程

1. Fork 儲存庫並從 main 建立分支。建議的分支命名：feat/...、fix/...、docs/...
2. 完成你的變更；每個 PR 只聚焦一件事
3. 送出 PR，清楚描述動機與變更內容
4. CI 會根據變更檔案執行相關的 TypeScript、Go、套件和工具檢查；所有選取的檢查必須通過
5. 維護者會 review 你的 PR；請回應回饋，並把討論保留在 PR 中

本機鉤子使用 husky：

• pre-commit 執行暫存區格式化和 UI 邊界檢查
• pre-push 透過 pnpm check:changed -- --push-ready 執行變更感知的推送檢查

Pull Request 評審門禁

Tutti 使用 external-pr-review-gate workflow 區分內部團隊變更和外部貢獻。官方作者由組織變數 TUTTI_RD_MEMBERS 定義；GitHub 團隊 tutti-rd 是外部 PR 的 review 請求目標。

• tutti-rd 成員發起的 PR 不會自動請求 reviewer，也不需要額外官方 approve 即可通過評審門禁
• 非 tutti-rd 作者發起的 PR 會自動請求 @tutti-os/tutti-rd review
• 外部 PR 只有在目前 head commit 獲得 tutti-rd 成員 approve 後才能合併
• 推送新提交會刷新門禁；新的 head commit 需要重新獲得通過評審
• 官方團隊成員變更時，維護者必須同時更新 TUTTI_RD_MEMBERS 和 tutti-rd 團隊

---
config:
  layout: dagre
  theme: redux
  look: neo
---
flowchart TB
    A["PR 開啟 / 重新開啟 / 標記為可評審 / 推送新提交"] --> B{"PR 作者是否在官方成員名單？"}
    B -- 是 --> C["不自動請求 Reviewer"]
    C --> P["✅ 通過"]
    P --> M["可以合併"]
    B -- 否 --> D["自動請求 @tutti-os/tutti-rd Review"]
    D --> E{"目前 head commit 是否有官方 Review？"}
    E -- 已 Approve --> P
    E -- 沒有通過評審 --> F["❌ 未通過"]
    F --> N["不能合併"]
    G["外部貢獻者推送新提交"] --> A

    G@{ shape: rounded}

文件語言策略

• README.* 和 CONTRIBUTING.* 以英文、簡體中文、繁體中文三種語言維護
• 英文版是唯一基準（source of truth）——修改 README.md 或 CONTRIBUTING.md 時，須在同一個 PR 中同步更新 *.zh-CN.md 和 *.zh-TW.md
• 譯文與英文版衝突時，以英文版為準
• LICENSE、NOTICE、CODE_OF_CONDUCT.md、SECURITY.md 與 docs/ 目錄只維護英文

回報問題

• Bug 回報與功能請求：使用 issue 模板
• 安全漏洞：請勿提交公開 issue——參見 SECURITY.md

授權

向 Tutti 提交貢獻，即表示你同意你的貢獻以 Apache License 2.0 授權釋出。

翻譯說明：本文件與英文版內容同步，如有出入，以英文版為準。