team-toon-tack 1.7.0 → 2.0.0

package/README.zh-TW.md

@@ -2,405 +2,73 @@
 
 繁體中文 | [English](./README.md)
 
-使用 TOON 格式同步與管理 Linear 任務的 CLI 工具。
+為 Claude Code 最佳化的 Linear 工作流 — 比 MCP 節省大量 token。
 
-## 為什麼需要這個工具？
+## 特色功能
 
-在使用 Linear 管理專案任務時，常見的痛點：
+- **節省 Token** — 本地 cycle 快取避免重複 API 呼叫，比 Linear MCP 省下大量 token
+- **智慧任務挑選** — `/work-on next` 自動選擇最高優先級的未指派工作
+- **多團隊支援** — 跨多個團隊同步與過濾 issue
+- **彈性同步模式** — 選擇 remote（即時同步 Linear）或 local（離線優先，稍後用 `--update` 同步）
+- **QA/PM 團隊支援** — 完成開發任務時自動將 QA/PM 團隊的 parent issue 更新為「Testing」
+- **附件下載** — 自動下載 Linear 圖片和檔案到本地 `.ttt/output/`，供 AI 視覺分析
+- **阻塞狀態** — 等待外部依賴時可設定任務為 blocked
+- **自動安裝指令** — `ttt init` 可自動安裝 Claude Code commands，支援自訂前綴
+- **Cycle 歷史保存** — 本地 `.toon` 檔案保留 cycle 資料，方便 AI 檢閱
+- **使用者過濾** — 只顯示指派給你或未指派的工作
 
-- **AI 助手整合困難**：Claude Code 等 AI 工具無法直接讀取 Linear 的任務上下文
-- **狀態同步繁瑣**：手動在 Linear 和本地之間切換更新狀態
-- **團隊協作不透明**：難以追蹤誰在做什麼、進度如何
-
-**team-toon-tack** 解決這些問題：將 Linear 任務同步到本地 TOON 檔案，讓 AI 助手能讀取任務內容，並自動同步狀態變更。
-
-## 運作原理
-
-```
-┌─────────────┐     ┌──────────────┐     ┌─────────────┐
-│   Linear    │────▶│  ttt sync    │────▶│ cycle.toon  │
-│   (雲端)    │     │               │    │  (本地)      │
-└─────────────┘     └──────────────┘     └─────────────┘
-                                                │
-                                                ▼
-┌─────────────┐     ┌──────────────┐     ┌─────────────┐
-│   Linear    │◀────│  ttt done    │◀────│ Claude Code │
-│  狀態更新    │     │  ttt work-on │     │    讀取任務   │
-└─────────────┘     └──────────────┘     └─────────────┘
-```
-
-### 核心流程
-
-1. **同步 (sync)**
-   - 從 Linear API 抓取當前 Cycle 的任務
-   - 根據 `local.ttt` 設定過濾（標籤、排除指派人）
-   - 寫入 `cycle.toon`，包含完整任務資訊
-
-2. **開始任務 (work-on)**
-   - 讀取 `cycle.toon` 中的待處理任務
-   - 更新本地狀態為 `in-progress`
-   - 同步更新 Linear 狀態為 "In Progress"
-
-3. **完成任務 (done)**
-   - 更新本地狀態為 `completed`
-   - 同步更新 Linear 狀態為 "Done"
-   - 自動在 Linear 新增完成留言（含 commit 資訊）
-   - 若有父任務，自動更新為 "Testing"
-
-### 檔案結構與用途
-
-```
-.ttt/                    # 配置目錄（建議 gitignore）
-├── config.toon         # 團隊配置
-│   ├── teams            # Linear 團隊 ID 映射
-│   ├── users            # 成員 ID/email 映射
-│   ├── labels           # 標籤 ID 映射
-│   ├── status_transitions # 狀態映射配置
-│   └── current_cycle    # 當前 Cycle 資訊
-│
-├── local.toon          # 個人設定（必須 gitignore）
-│   ├── current_user     # 你的 user key
-│   ├── team             # 主要團隊
-│   ├── teams            # 多團隊同步（可選）
-│   ├── label            # 過濾標籤（可選）
-│   ├── exclude_labels   # 排除的標籤
-│   └── exclude_assignees # 排除的指派人
-│
-└── cycle.toon          # 任務資料（自動產生）
-    ├── cycleId          # Cycle UUID
-    ├── cycleName        # Cycle 名稱
-    ├── updatedAt        # 最後同步時間
-    └── tasks[]          # 任務列表
-        ├── id           # 任務編號 (MP-123)
-        ├── linearId     # Linear UUID
-        ├── title        # 標題
-        ├── description  # 描述（Markdown）
-        ├── status       # Linear 狀態
-        ├── localStatus  # 本地狀態
-        ├── priority     # 優先級 (1=Urgent, 4=Low)
-        ├── labels       # 標籤列表
-        ├── branch       # Git 分支名
-        ├── attachments  # 附件列表
-        └── comments     # 留言列表
-```
+## 快速開始
 
-## 安裝
+### 1. 安裝與初始化
 
 ```bash
-# npm（推薦）
 npm install -g team-toon-tack
-
-# 或用 bun
-bun add -g team-toon-tack
-```
-
-## 快速開始
-
-```bash
-# 1. 設定 Linear API 金鑰
 export LINEAR_API_KEY="lin_api_xxxxx"
 
-# 2. 初始化（會從 Linear 抓取團隊資料）
-mkdir .ttt && cd .ttt
+cd your-project
 ttt init
-
-# 3. 同步任務
-ttt sync
-
-# 4. 開始工作
-ttt work-on
 ```
 
-## 使用情境
-
-### 情境 1：每日開工流程
-
-```bash
-# 早上開始工作前，同步最新任務
-ttt sync -d .ttt
-
-# 查看待處理任務並選擇一個開始
-ttt work-on -d .ttt
-
-# Claude Code 現在可以讀取任務內容
-# 在 .ttt/cycle.toon 中找到任務描述、附件等
-```
-
-### 情境 2：搭配 Claude Code 自動化
-
-建立以下三個 slash command 檔案：
+初始化時會設定：
+- **狀態來源**：`remote`（即時更新 Linear）或 `local`（離線工作，用 `ttt sync --update` 同步）
+- **QA/PM 團隊**：跨團隊 parent issue 更新（需在 Linear 設定 parent）
+- **Claude Code commands**：自動安裝，可選前綴（如 `/ttt:work-on`）
 
-#### `.claude/commands/sync-linear.md`
+### 2. 每日工作流
 
-```markdown
----
-name: sync-linear
-description: Sync Linear issues to local TOON file
----
-
-# Sync Linear Issues
-
-Fetch current cycle's issues from Linear to `.ttt/cycle.toon`.
-
-## Process
-
-### 1. Run Sync
-
-\`\`\`bash
-ttt sync -d .ttt
-\`\`\`
-
-### 2. Review Output
+在 Claude Code 中：
 
-Script displays a summary of tasks in the current cycle.
-
-## When to Use
-
-- Before starting a new work session
-- When task list is missing or outdated
-- After issues are updated in Linear
 ```
-
-#### `.claude/commands/work-on.md`
-
-```markdown
----
-name: work-on
-description: Select and start working on a Linear issue
-arguments:
-  - name: issue-id
-    description: "Issue ID (e.g., MP-624) or 'next' for auto-select"
-    required: false
----
-
-# Start Working on Issue
-
-Select a task and update status to "In Progress" on both local and Linear.
-
-## Process
-
-### 1. Run Command
-
-\`\`\`bash
-ttt work-on -d .ttt $ARGUMENTS
-\`\`\`
-
-### 2. Review Issue Details
-
-Script displays title, description, priority, labels, and attachments.
-
-### 3. Implement
-
-1. Read the issue description carefully
-2. Explore related code
-3. Implement the fix/feature
-4. Run validation commands
-5. Commit with conventional format
-6. Use `/done-job` to complete
+/sync              # 從 Linear 取得當前 cycle 所有 issue
+/work-on next      # 挑選最高優先級任務並開始工作
+/done-job          # 完成任務，附上 AI 生成的摘要
 ```
 
-#### `.claude/commands/done-job.md`
+就這樣。
 
-```markdown
 ---
-name: done-job
-description: Mark a Linear issue as done with AI summary comment
-arguments:
-  - name: issue-id
-    description: Linear issue ID (e.g., MP-624). Optional if only one task is in-progress
-    required: false
----
-
-# Complete Task
-
-Mark a task as done and update Linear with commit details.
-
-## Process
-
-### 1. Determine Issue ID
-
-Check `.ttt/cycle.toon` for tasks with `localStatus: in-progress`.
-
-### 2. Write Fix Summary
 
-Prepare a concise summary (1-3 sentences) covering:
-- Root cause
-- How it was resolved
-- Key code changes
-
-### 3. Run Command
-
-\`\`\`bash
-ttt done -d .ttt $ARGUMENTS -m "修復說明"
-\`\`\`
-
-## What It Does
-
-- Linear issue status → "Done"
-- Adds comment with commit hash, message, and diff summary
-- Parent issue (if exists) → "Testing"
-- Local status → `completed` in `.ttt/cycle.toon`
-```
-
-#### 使用方式
-
-```
-/sync-linear        # 同步任務
-/work-on            # 互動選擇任務
-/work-on MP-624     # 指定任務
-/work-on next       # 自動選最高優先級
-/done-job           # 完成當前任務
-/done-job MP-624    # 完成指定任務
-```
-
-Claude Code 會自動：
-- 執行 `ttt work-on` 開始任務
-- 讀取任務描述和附件
-- 根據需求實作功能
-- 執行 `ttt done` 更新狀態並留言
-
-### 情境 3：完成任務並自動留言
-
-```bash
-# 完成開發後
-git add . && git commit -m "feat: implement feature X"
-
-# 標記任務完成，會自動在 Linear 新增留言
-ttt done -d .ttt -m "實作了 X 功能，修改了 Y 元件"
-```
-
-Linear 上會自動新增留言：
-```markdown
-## ✅ 開發完成
-
-### 🤖 AI 修復說明
-實作了 X 功能，修改了 Y 元件
-
-### 📝 Commit Info
-**Commit:** [abc1234](https://github.com/...)
-**Message:** feat: implement feature X
-
-### 📊 Changes
- src/components/X.vue | 50 +++
- src/utils/Y.ts       | 20 +-
- 2 files changed, 60 insertions(+), 10 deletions(-)
-```
-
-### 情境 4：團隊協作過濾
-
-前端工程師只想看前端任務：
-```toon
-# local.toon
-current_user: alice
-team: frontend
-label: Frontend
-exclude_labels[1]:
-  - Bug
-exclude_assignees[2]:
-  - bob    # 排除後端同事的任務
-  - charlie
-```
-
-後端工程師的設定（多團隊支援）：
-```toon
-# local.toon
-current_user: bob
-team: backend
-teams[2]:
-  - backend
-  - devops
-label: Backend
-```
-
-### 情境 5：狀態管理
-
-```bash
-# 查看當前進行中任務的詳細資訊
-ttt status
-
-# 查看特定任務狀態
-ttt status MP-624
-
-# 快速移動狀態
-ttt status MP-624 --set +1    # 移動到下一狀態
-
-# 配置 Linear 狀態映射
-ttt config status             # 互動式配置
-
-# 配置過濾器
-ttt config filters            # 設定 exclude_labels, exclude_assignees
-```
-
-### 情境 6：多專案管理
-
-```bash
-# 專案 A
-cd project-a
-ttt sync -d .ttt
-
-# 專案 B（不同 Linear 團隊）
-cd ../project-b
-ttt init -d .ttt  # 初始化不同的配置
-ttt sync -d .ttt
-```
-
-### 情境 7：CI/CD 整合
-
-```yaml
-# .github/workflows/sync.yml
-name: Sync Linear Tasks
-on:
-  schedule:
-    - cron: '0 9 * * 1-5'  # 週一到週五早上 9 點
-jobs:
-  sync:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - run: npm install -g team-toon-tack
-      - run: ttt sync -d .ttt
-        env:
-          LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}
-      - run: |
-          git add .ttt/cycle.toon
-          git commit -m "chore: sync linear tasks" || true
-          git push
-```
-
-## 指令參考
+## CLI 參考
 
 ### `ttt init`
 
-初始化配置檔，從 Linear 抓取團隊資料。
+在當前目錄初始化配置。
 
 ```bash
-ttt init [options]
-
-選項：
-  -d, --dir <path>      配置目錄（預設：當前目錄）
-  -k, --api-key <key>   Linear API 金鑰
-  -u, --user <email>    預選使用者
-  -l, --label <name>    預設標籤過濾
-  -f, --force           覆蓋現有配置
-  -y, --yes             非互動模式
+ttt init                           # 互動模式
+ttt init --user alice@example.com  # 預選使用者
+ttt init --label Frontend          # 設定預設標籤
+ttt init --force                   # 覆蓋現有配置
 ```
 
 ### `ttt sync`
 
-從 Linear 同步任務到本地。
+從 Linear 同步當前 cycle 的 issue。
 
 ```bash
-ttt sync [issue-id] [options]
-
-參數：
-  issue-id              可選。只同步此特定任務（如 MP-624）
-
-選項：
-  -d, --dir <path>      配置目錄
-
-範例：
-  ttt sync              # 同步所有符合條件的任務
-  ttt sync MP-624       # 只同步此特定任務
+ttt sync              # 同步所有符合條件的 issue
+ttt sync MP-123       # 只同步特定 issue
+ttt sync --update     # 將本地狀態推送到 Linear（local 模式用）
 ```
 
 ### `ttt work-on`
@@ -408,13 +76,9 @@ ttt sync [issue-id] [options]
 開始處理任務。
 
 ```bash
-ttt work-on [issue-id] [options]
-
-參數：
-  issue-id              任務編號（如 MP-624）或 "next"
-
-選項：
-  -d, --dir <path>      配置目錄
+ttt work-on              # 互動選擇
+ttt work-on MP-123       # 指定 issue
+ttt work-on next         # 自動選擇最高優先級
 ```
 
 ### `ttt done`
@@ -422,14 +86,9 @@ ttt work-on [issue-id] [options]
 標記任務完成。
 
 ```bash
-ttt done [issue-id] [options]
-
-參數：
-  issue-id              任務編號（可選）
-
-選項：
-  -d, --dir <path>      配置目錄
-  -m, --message <msg>   完成說明
+ttt done                    # 若只有一個進行中，自動選擇
+ttt done MP-123             # 指定 issue
+ttt done -m "修復了錯誤"      # 附上完成說明
 ```
 
 ### `ttt status`
@@ -437,27 +96,11 @@ ttt done [issue-id] [options]
 顯示或修改任務狀態。
 
 ```bash
-ttt status [issue-id] [--set <status>]
-
-參數：
-  issue-id              任務編號（可選，預設顯示進行中任務）
-
-選項：
-  -s, --set <status>    設定狀態
-
-狀態選項：
-  +1, -1, +2, -2       相對移動狀態
-  pending              設為待處理
-  in-progress          設為進行中
-  completed            設為已完成
-  blocked              設為後端阻擋
-  todo, done, testing  設定 Linear 狀態
-
-範例：
-  ttt status              # 顯示當前進行中任務
-  ttt status MP-624       # 顯示特定任務狀態
-  ttt status MP-624 --set +1      # 移動到下一狀態
-  ttt status MP-624 --set done    # 標記為完成
+ttt status              # 顯示當前進行中的任務
+ttt status MP-123       # 顯示特定 issue 狀態
+ttt status MP-123 --set +1      # 移動到下一狀態
+ttt status MP-123 --set done    # 標記為完成
+ttt status MP-123 --set blocked # 設為阻塞（等待外部依賴）
 ```
 
 ### `ttt config`
@@ -465,60 +108,31 @@ ttt status [issue-id] [--set <status>]
 配置設定。
 
 ```bash
-ttt config [subcommand]
-
-子指令：
-  show      顯示當前配置（預設）
-  status    配置狀態映射（todo, in_progress, done, testing）
-  filters   配置過濾器（label, exclude_labels, exclude_assignees）
-  teams     配置團隊選擇（多團隊支援）
-
-範例：
-  ttt config              # 顯示當前配置
-  ttt config status       # 配置狀態映射
-  ttt config filters      # 配置過濾器
-  ttt config teams        # 配置團隊選擇
+ttt config              # 顯示當前配置
+ttt config status       # 配置狀態映射
+ttt config filters      # 配置標籤/使用者過濾
+ttt config teams        # 配置多團隊選擇
 ```
 
-## 環境變數
-
-| 變數 | 說明 |
-|------|------|
-| `LINEAR_API_KEY` | **必填**。Linear API 金鑰（[取得方式](https://linear.app/settings/api)） |
-| `TOON_DIR` | 配置目錄路徑（可取代 `-d` 參數） |
-
-## 常見問題
-
-### Q: 為什麼用 TOON 格式？
-
-TOON 是一種人類可讀的資料格式，類似 YAML 但更簡潔。相比 JSON：
-- 更容易手動編輯
-- 支援註解
-- AI 助手更容易理解
+## 配置說明
 
-### Q: config.ttt 可以提交到 Git 嗎？
+### 目錄結構
 
-可以，但建議 gitignore。因為包含：
-- 團隊成員的 email
-- Linear 內部 UUID
-
-如果是私有倉庫且團隊成員都有 Linear 存取權，提交是安全的。
-
-### Q: 如何處理衝突？
-
-`cycle.toon` 是自動產生的，直接用 `ttt sync` 重新同步即可。
+```
+your-project/
+└── .ttt/
+    ├── config.toon     # 團隊配置（建議 gitignore）
+    ├── local.toon      # 個人設定（gitignore）
+    ├── cycle.toon      # 當前 cycle 資料（自動產生）
+    └── output/         # 下載的附件（圖片、檔案）
+```
 
-### Q: 支援哪些 Linear 功能？
+### 環境變數
 
-- ✅ Cycle 任務同步
-- ✅ 單一任務同步 (`ttt sync MP-624`)
-- ✅ 狀態雙向同步
-- ✅ 自訂狀態映射（`ttt config status`）
-- ✅ 附件和留言讀取
-- ✅ 父子任務關聯
-- ✅ 優先級排序
-- ✅ 多團隊支援
-- ✅ 標籤/用戶過濾
+| 變數 | 說明 |
+|------|------|
+| `LINEAR_API_KEY` | **必填**。你的 Linear API 金鑰 |
+| `TOON_DIR` | 配置目錄（預設：`.ttt`） |
 
 ## 授權
 

package/dist/scripts/done-job.js

@@ -104,8 +104,11 @@ Examples:
         });
         aiMessage = aiMsgResponse.aiMessage || "";
     }
-    // Update Linear
-    if (task.linearId && process.env.LINEAR_API_KEY) {
+    // Update Linear (only if status_source is 'remote' or not set)
+    const statusSource = localConfig.status_source || "remote";
+    if (task.linearId &&
+        process.env.LINEAR_API_KEY &&
+        statusSource === "remote") {
         const transitions = getStatusTransitions(config);
         // Update issue to Done
         const success = await updateIssueStatus(task.linearId, transitions.done, config, localConfig.team);
@@ -129,7 +132,20 @@ Examples:
                 if (parentIssue) {
                     const parentTeam = await parentIssue.team;
                     if (parentTeam) {
-                        const parentStates = await getWorkflowStates(config, localConfig.team);
+                        // Determine which team key to use for parent's workflow states
+                        // If qa_pm_team is configured and matches parent's team, use it
+                        // Otherwise, try to find the team key from config
+                        let parentTeamKey = localConfig.team;
+                        const teamEntries = Object.entries(config.teams);
+                        const matchingTeam = teamEntries.find(([_, t]) => t.id === parentTeam.id);
+                        if (matchingTeam) {
+                            parentTeamKey = matchingTeam[0];
+                        }
+                        else if (localConfig.qa_pm_team) {
+                            // Fallback to qa_pm_team if configured
+                            parentTeamKey = localConfig.qa_pm_team;
+                        }
+                        const parentStates = await getWorkflowStates(config, parentTeamKey);
                         const testingState = parentStates.find((s) => s.name === transitions.testing);
                         if (testingState) {
                             await client.updateIssue(parentIssue.id, {
@@ -145,6 +161,10 @@ Examples:
             }
         }
     }
+    else if (statusSource === "local") {
+        console.log(`Local: ${task.id} marked as completed`);
+        console.log(`(Linear status not updated - use 'sync --update' to push)`);
+    }
     // Sync full issue data from Linear (including new comment)
     const syncedTask = await syncSingleIssue(task.id, {
         config,