cw-ai-backlog/USAGE.md

AI-powered tool to generate backlog items from meeting documents and output to Google Sheets

# AI Backlog Generator 使用指南

> 一個使用 AI 技術從會議文件自動生成 backlog 項目並直接寫入 Google Sheets 的 CLI 工具

## 🚀 快速開始

### 安裝

```bash
# 全域安裝（推薦）
npm install -g cw-ai-backlog
```

#### 📦 Mac 使用者：如果沒有 Node.js 環境

如果您的電腦還沒有安裝 Node.js，請先按照以下步驟安裝：

**第一步：安裝 NVM（Node 版本管理工具）**
```bash
# 複製以下指令並在終端機執行
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
```

**第二步：重新啟動終端機**
- 關閉目前的終端機視窗
- 重新開啟終端機

**第三步：確認 NVM 安裝成功**
```bash
# 執行以下指令，應該會顯示版本號
nvm --version
```
如果顯示版本號（例如：0.39.0），表示安裝成功！

**第四步：安裝 Node.js**
```bash
# 安裝 Node.js 版本 20（推薦版本）
nvm install 20

# 設定為預設版本
nvm use 20
```

**第五步：確認安裝成功**
```bash
# 檢查 Node.js 版本
node --version

# 檢查 npm 版本
npm --version
```
如果兩個指令都顯示版本號，表示環境準備完成！

現在您可以安裝 AI Backlog 工具了：
```bash
npm install -g cw-ai-backlog
```

### 🎯 互動式設定（推薦新使用者）

```bash
# 執行互動式配置設定精靈
ai-backlog --setup
```

這會引導您完成所有必要的設定：
- ✅ OpenAI API Key 設定和驗證
- ✅ AI 模型選擇  
- ✅ Google 憑證檔案路徑（可選）
- ✅ Google Sheets URL（可選）
- ✅ 進階選項（保留字、自訂 prompt 等）

### 📍 配置檔案管理

```bash
# 查看配置檔案位置和狀態
ai-backlog --show-config

# 快速編輯全域配置檔案
ai-backlog --edit-config
```

**配置檔案查找順序：**
1. **當前目錄**：`./ai_backlog.config.js`
2. **使用者家目錄**：`~/.ai_backlog.config.js` ⭐ **推薦**
3. **XDG 配置目錄**：`~/.config/ai-backlog/config.js`

### 基本使用

```bash
# 解析本地檔案並寫入 Google Sheets
ai-backlog ./meeting-notes.pdf

# 解析公開 Google Docs
ai-backlog "https://docs.google.com/document/d/your-doc-id/edit"

# 使用自訂配置檔案
ai-backlog ./meeting.md -c ./project-config.js
```

## ⚙️ 設定方式

### 方法一：互動式設定（推薦）

```bash
ai-backlog --setup
```

這是最簡單的設定方式，會引導您完成所有配置。

### 方法二：手動設定

**快速編輯配置檔案：**
```bash
# 自動在編輯器中開啟全域配置檔案
ai-backlog --edit-config
```

**手動編輯配置檔案：**
```bash
# macOS/Linux
nano ~/.ai_backlog.config.js

# 或使用 VS Code
code ~/.ai_backlog.config.js
```

### 方法三：環境變數

```bash
# 設定環境變數（適用於基本使用）
export OPENAI_API_KEY="your-openai-api-key"

# 加入 shell 配置檔案以持久化
echo 'export OPENAI_API_KEY="your-openai-api-key"' >> ~/.zshrc
```

## 📋 配置檔案格式

完整的配置檔案範例：

```javascript
module.exports = {
  // OpenAI API Key (必填)
  apiKey: 'your-openai-api-key',
  
  // 使用的模型
  model: 'gpt-4o', // 或 'gpt-4-turbo', 'gpt-3.5-turbo'
  
  // Google API 憑證檔案路徑（寫入 Sheets 必填）
  googleCredentials: './path/to/credentials.json',
  
  // Google Sheets URL（寫入 Sheets 必填）
  googleSheetUrl: 'https://docs.google.com/spreadsheets/d/your-sheet-id/edit',
  
  // 保留字 - 在分析時需要特別注意的詞彙
  keepPhrases: [
    '使用者體驗',
    '效能優化', 
    '安全性'
  ],
  
  // 自訂 prompt 指示
  customPrompt: [
    '只分析紫色標記的內容',
    '專注於特定標題以下的內容',
    '忽略草稿或註解部分'
  ],
  
  // AI 參數設定
  maxTokens: 4000,
  temperature: 0.1
};
```

## 🔧 Google 服務設定

### 🌟 建立 Google Cloud Service Account（詳細教學）

如果您是第一次使用 Google Cloud 服務，請按照以下步驟建立 Service Account：

#### 第一步：建立 Google Cloud 專案

1. **前往 Google Cloud Console**
   - 開啟瀏覽器，前往 [https://console.cloud.google.com/](https://console.cloud.google.com/)
   - 使用您的 Google 帳號登入

2. **建立新專案**
   - 點擊頂部的「選取專案」下拉選單
   - 點擊「新增專案」
   - 輸入專案名稱（例如：`ai-backlog-tool`）
   - 點擊「建立」

3. **確認專案已選取**
   - 等待專案建立完成（約 30 秒）
   - 確認頂部顯示您剛建立的專案名稱

#### 第二步：啟用必要的 API

1. **啟用 Google Sheets API**
   - 在左側選單中點擊「API 和服務」> 「程式庫」
   - 搜尋「Google Sheets API」
   - 點擊進入後，點擊「啟用」

2. **啟用 Google Drive API**
   - 同樣在「程式庫」中搜尋「Google Drive API」
   - 點擊進入後，點擊「啟用」

3. **啟用 Google Docs API**（如需解析私人 Google Docs）
   - 搜尋「Google Docs API」
   - 點擊進入後，點擊「啟用」

#### 第三步：建立 Service Account

1. **前往憑證頁面**
   - 在左側選單點擊「API 和服務」> 「憑證」

2. **建立 Service Account**
   - 點擊頂部的「+ 建立憑證」
   - 選擇「服務帳戶」

3. **填寫 Service Account 詳細資訊**
   - **服務帳戶名稱**：`ai-backlog-service`
   - **服務帳戶 ID**：會自動產生，如 `ai-backlog-service@your-project.iam.gserviceaccount.com`
   - **服務帳戶說明**：`用於 AI Backlog 工具存取 Google Sheets`
   - 點擊「建立並繼續」

4. **設定權限**（可選）
   - 這個步驟可以跳過，直接點擊「完成」

#### 第四步：下載憑證檔案

1. **找到剛建立的 Service Account**
   - 在憑證頁面的「服務帳戶」區段中找到您剛建立的帳戶

2. **建立金鑰**
   - 點擊 Service Account 的 email 地址
   - 切換到「金鑰」分頁
   - 點擊「新增金鑰」> 「建立新的金鑰」
   - 選擇「JSON」格式
   - 點擊「建立」

3. **儲存憑證檔案**
   - 檔案會自動下載到您的電腦
   - 檔案名稱類似：`your-project-abc123.json`
   - **重要**：將此檔案放在安全的位置，不要分享給他人

#### 第五步：記錄 Service Account Email

**複製 Service Account 的 Email 地址**（稍後設定 Google Sheets 時需要）：
```
ai-backlog-service@your-project.iam.gserviceaccount.com
```

### Google Sheets 輸出設定

#### 完成上述 Service Account 設定後，接續以下步驟：

**第六步：建立 Google Sheets**
1. 前往 [Google Sheets](https://sheets.google.com/)
2. 點擊「空白」建立新的試算表
3. 為試算表命名（例如：`AI Backlog 匯出`）
4. 複製瀏覽器網址列中的 URL

**第七步：共享 Google Sheets 給 Service Account**
1. 在 Google Sheets 中點擊右上角的「共用」按鈕
2. 在「新增使用者和群組」欄位中，貼上您的 Service Account Email：
   ```
   ai-backlog-service@your-project.iam.gserviceaccount.com
   ```
3. 將權限設定為「編輯者」
4. **取消勾選**「通知使用者」（因為這是機器帳戶）
5. 點擊「共用」

**第八步：設定工具配置**
在您的配置檔案中加入：
```javascript
module.exports = {
  // 其他設定...
  googleCredentials: './path/to/your-service-account-key.json',
  googleSheetUrl: 'https://docs.google.com/spreadsheets/d/your-sheet-id/edit'
};
```

**完成！** 現在您的工具可以自動將 backlog 寫入 Google Sheets 了。

#### 📋 設定檢查清單

- ✅ Google Cloud 專案已建立
- ✅ Google Sheets/Drive/Docs API 已啟用  
- ✅ Service Account 已建立
- ✅ JSON 憑證檔案已下載並妥善保存
- ✅ Google Sheets 已建立並共享給 Service Account
- ✅ 配置檔案已更新

### Google Docs 解析設定

**公開文件**：無需設定，確保文件為「知道連結的使用者可以檢視」

**私人文件**：使用與 Google Sheets 相同的服務帳戶憑證

## 💡 使用情境

### 情境一：僅使用本地檔案
```bash
# 最簡設定，只需要 OpenAI API Key
ai-backlog meeting.pdf

# 輸出：顯示錯誤訊息，因為沒有設定 Google Sheets
```

### 情境二：完整功能使用
```bash
# 需要完整設定（API Key + Google 憑證 + Sheets URL）
ai-backlog --setup  # 一次設定完成
ai-backlog meeting.pdf  # 直接輸出到 Google Sheets
```

### 情境三：公開 Google Docs
```bash
# 需要 OpenAI API Key + Google Sheets 設定
ai-backlog "https://docs.google.com/document/d/public-doc-id/edit"
```

## 📋 指令參數

```bash
ai-backlog [檔案路徑或URL] [選項]
```

| 參數 | 說明 | 範例 |
|------|------|------|
| `[input]` | 檔案路徑或 Google Docs URL | `meeting.pdf`, `"https://docs.google.com/..."` |
| `--setup` | 執行互動式配置設定 | `ai-backlog --setup` |
| `--show-config` | 顯示配置檔案位置 | `ai-backlog --show-config` |
| `--edit-config` | 編輯全域配置檔案 | `ai-backlog --edit-config` |
| `-c, --config <path>` | 自訂配置檔案路徑 | `ai-backlog input.pdf -c ./config.js` |
| `-V, --version` | 顯示版本號 | `ai-backlog --version` |
| `-h, --help` | 顯示幫助資訊 | `ai-backlog --help` |

## 📁 支援的檔案格式

| 格式 | 副檔名 | 說明 |
|------|--------|------|
| PDF | `.pdf` | 自動提取文字內容 |
| Word | `.docx` | 支援現代 Word 格式 |
| 純文字 | `.txt`, `.md` | 直接讀取內容 |
| Google Docs | URL | 透過連結存取 |

## 📊 輸出格式

工具會在指定的 Google Sheets 中建立新的工作表，包含以下欄位：

| 欄位 | 說明 | 來源 |
|------|------|------|
| **Area** | 功能領域 | **使用者填寫** |
| **Iteration** | 迭代週期 | **使用者填寫** |
| **BacklogLink** | Backlog 連結 | **使用者填寫** |
| Title | backlog 項目標題 | AI 生成 |
| Type | 類型（frontend/backend/fullstack） | AI 生成 |
| Description | 詳細描述 | AI 生成 |
| Acceptance Criteria | 驗收條件 | AI 生成 |
| **AssignedTo** | 指派對象 | **使用者填寫** |
| Effort | 工作量估算（費波那契數列） | AI 生成 |
| Effort Analysis | 工作量分析說明 | AI 生成 |
| Source Text | 對應的原文片段 | AI 生成 |
| **MoSCoW** | 優先級（Must/Should/Could/Won't） | **使用者填寫** |

### 範例 JSON 格式（供參考）

```json
[
  {
    "title": "建立使用者登入功能",
    "type": "frontend",
    "description": "開發使用者登入頁面，包含帳號密碼欄位、驗證機制和錯誤提示。",
    "acceptance_criteria": [
      "使用者輸入錯誤帳號密碼時需顯示明確的錯誤訊息",
      "成功登入後自動導向到使用者的首頁",
      "支援記住我功能，7天內免重新登入"
    ],
    "effort": 5,
    "effort_analysis": "包含 UI 設計、表單驗證、錯誤處理和狀態管理，屬於中等複雜度的功能"
  }
]
```

### 欄位說明

| 欄位 | 類型 | 說明 |
|------|------|------|
| `title` | String | Backlog 項目標題 |
| `type` | String | 類型：`frontend`、`backend`、`fullstack` |
| `description` | String | 功能詳細描述 |
| `acceptance_criteria` | Array | 驗收條件列表 |
| `effort` | Number | 工作量評估（費波那契數列：1,2,3,5,8,13,21） |
| `effort_analysis` | String | 工作量評估說明 |

## 💡 使用範例

### 工作流程整合
```bash
# 在 package.json 中設定 npm script
{
  "scripts": {
    "generate-backlog": "ai-backlog ./docs/meeting-notes.md"
  }
}

# 執行
npm run generate-backlog
```

### 初次使用流程
```bash
# 1. 安裝工具
npm install -g cw-ai-backlog

# 2. 互動式設定
ai-backlog --setup

# 3. 測試使用
ai-backlog ./test-meeting.pdf

# 4. 查看結果
# 開啟 Google Sheets 查看生成的 backlog
```

## 🛠️ 進階配置

### 自訂 AI 分析指示

使用 `customPrompt` 可以為 AI 提供特定的分析指示：

```javascript
customPrompt: [
  '只分析紫色或醒目標記的內容',
  '專注於特定標題以下的內容',
  '忽略草稿、註解或待確認的部分',
  '僅針對已確認的需求項目生成 backlog',
  '優先分析新功能相關的討論'
]
```

**常見使用場景：**
- 📝 **文件部分分析**：只分析特定顏色標記或特定章節
- 🎯 **需求篩選**：忽略草稿或未確認的內容
- 📋 **優先級控制**：專注於高優先級或緊急需求
- 🔍 **範圍限定**：只分析特定功能模組的討論

### 自訂保留字

在配置檔案中加入特定領域的關鍵詞：

```javascript
keepPhrases: [
  // 技術相關
  '微服務架構',
  'RESTful API',
  'GraphQL',
  'Docker',
  'Kubernetes',
  
  // 業務相關
  '使用者體驗',
  '轉換率',
  'A/B 測試',
  '數據分析',
  
  // 流程相關
  'CI/CD',
  '版本控制',
  '程式碼審查',
  '自動化測試'
]
```

### 調整 AI 參數

```javascript
module.exports = {
  // 選擇模型（影響成本和品質）
  model: 'gpt-4.1-nano',           // 最新、最智慧
  // model: 'gpt-4-turbo',   // 平衡性能與成本
  // model: 'gpt-3.5-turbo', // 最經濟
  
  // 控制輸出長度
  maxTokens: 4000,          // 預設值，可調整
  
  // 控制創意程度（0-1）
  temperature: 0.1          // 較低值 = 更一致的輸出
};
```

## 🚨 常見問題

### Q: 顯示「請設定 OPENAI_API_KEY」錯誤
**A:** 確保已正確設定 OpenAI API Key：
- 檢查環境變數：`echo $OPENAI_API_KEY`
- 或在配置檔案中直接設定 `apiKey`

### Q: Google Docs 無法存取
**A:** 檢查以下事項：
- 確認文件是公開的或已正確設定服務帳戶
- 檢查 Google Docs URL 格式是否正確
- 確認已啟用 Google Docs API（如使用服務帳戶）

### Q: 生成的 backlog 品質不佳
**A:** 嘗試以下調整：
- 在配置中加入更多相關的 `keepPhrases`
- 使用更詳細的會議記錄
- 調整 `temperature` 參數
- 升級到 `gpt-4.1-nano` 模型

### Q: 解析 PDF 失敗
**A:** 確認 PDF 檔案：
- 是文字型 PDF（非掃描影像）
- 檔案沒有密碼保護
- 檔案沒有損壞

## 📝 最佳實踐

1. **會議記錄品質**：提供詳細、結構化的會議記錄可獲得更好的結果
2. **保留字設定**：根據專案領域自訂保留字
3. **定期更新**：保持工具為最新版本以獲得改進功能
4. **成本控制**：使用適當的模型平衡品質與成本

## 🔗 相關資源

- [OpenAI API 文件](https://platform.openai.com/docs)
- [Google Docs API 文件](https://developers.google.com/docs/api)
- [專案 GitHub 倉庫](https://github.com/your-username/ai-backlog)

## 📄 授權

MIT License

---

如有問題或建議，請在 GitHub Issues 中提出。