AI Backlog Generator

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

功能特色

• 📄 支援多種檔案格式：PDF、Word (.docx)、純文字檔案
• 🔗 支援 Google Docs 連結解析
• 🤖 使用 OpenAI API 智慧分析會議內容
• ⚡ 自動區分前端/後端 backlog 項目
• � 直接輸出到 Google Sheets，自動建立新工作表
• �📋 包含 Area、Iteration、MoSCoW 欄位供後續管理
• 🔍 每個 backlog 項目都能追溯到原文片段
• ⚙️ 可配置的 AI 模型和參數

安裝

npm install -g ai-backlog

或者在專案中本地安裝：

npm install ai-backlog

📖 完整使用指南：請參閱 USAGE.md 獲得詳細的安裝和使用說明

快速開始

🚀 互動式設定（推薦）

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

這會引導您完成所有必要的設定，包括：

• OpenAI API Key
• AI 模型選擇
• Google 憑證檔案路徑
• Google Sheets URL
• 進階選項（保留字、自訂 prompt 等）

手動配置

如果您偏好手動設定，首次使用時工具會建立 ai_backlog.config.js 配置檔案：

module.exports = {
  // OpenAI API Key (必填)
  apiKey: process.env.OPENAI_API_KEY || '你的-openai-api-key',
  
  // Google Sheets URL (必填 - 用於輸出 backlog)
  googleSheetUrl: 'https://docs.google.com/spreadsheets/d/your-sheet-id/edit',
  
  // Google API 憑證檔案路徑 (必填)
  googleCredentials: './path/to/credentials.json',
  
  // 使用的模型
  model: 'gpt-4o', // 或 'gpt-4-turbo', 'gpt-3.5-turbo'
  
  // 保留字 - 在分析時需要特別注意的詞彙
  keepPhrases: [
    '使用者體驗',
    '效能優化',
    '安全性',
    // ... 更多保留字
  ],
  
  // AI 參數設定
  maxTokens: 4000,
  temperature: 0.1
};

環境變數設定

您也可以使用環境變數設定 API Key：

export OPENAI_API_KEY="your-openai-api-key"

使用方法

基本用法

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

# 解析 Google Docs 並寫入 Google Sheets
ai-backlog "https://docs.google.com/document/d/your-doc-id/edit"

# 使用自訂配置檔案
ai-backlog ./meeting-notes.txt -c ./custom-config.js

指令參數

# 基本使用
ai-backlog [檔案路徑或URL] [選項]

# 配置管理
ai-backlog --setup              # 互動式配置設定精靈
ai-backlog --show-config        # 顯示配置檔案位置
ai-backlog --edit-config        # 快速編輯全域配置檔案

# 自訂配置
ai-backlog input.pdf -c custom-config.js  # 使用自訂配置檔案

選項說明：

• [input]: 會議檔案路徑或 Google Docs 連結
• --setup: 執行互動式配置設定精靈（首次使用推薦）
• --show-config: 顯示配置檔案查找位置和狀態
• --edit-config: 在編輯器中開啟全域配置檔案
• -c, --config <path>: 指定自訂配置檔案路徑

支援的檔案格式

• PDF: .pdf 檔案
• Word: .docx 檔案
• 純文字: .txt, .md 檔案
• Google Docs: 透過連結存取

輸出格式

工具會生成包含以下結構的 JSON 檔案：

[
  {
    "title": "建立使用者登入功能",
    "type": "frontend",
    "description": "開發使用者登入頁面，包含帳號密碼欄位、驗證機制和錯誤提示。",
    "acceptance_criteria": [
      "使用者輸入錯誤帳號密碼時需顯示明確的錯誤訊息",
      "成功登入後自動導向到使用者的首頁",
      "支援記住我功能，7天內免重新登入"
    ],
    "effort": 5,
    "effort_analysis": "包含 UI 設計、表單驗證、錯誤處理和狀態管理，屬於中等複雜度的功能",
    "source_text": "會議中討論需要建立使用者登入功能，要求有清楚的錯誤訊息和記住我功能",
    "ai_suggestions": "建議考慮加入雙因子認證或密碼強度檢查，以提升安全性"
  },
  {
    "title": "實作使用者認證 API",
    "type": "backend", 
    "description": "建立使用者認證相關的後端 API，包含登入驗證、JWT token 生成和驗證。",
    "acceptance_criteria": [
      "提供 POST /api/auth/login 端點進行使用者驗證",
      "成功驗證後回傳 JWT token 和使用者基本資訊",
      "實作 token 過期和刷新機制"
    ],
    "effort": 8,
    "effort_analysis": "需要設計資料庫認證邏輯、JWT 實作、安全性考量和錯誤處理，複雜度較高",
    "source_text": "需要後端 API 支援登入驗證，包含 JWT token 機制",
    "ai_suggestions": ""
  }
]

"effort": 8,
"effort_analysis": "需要實作加密、JWT 機制、資料庫查詢和安全性考量，較為複雜"

} ]

### 欄位說明

- **title**: Backlog 項目標題
- **type**: 類型 (`frontend`, `backend`, `fullstack`)
- **description**: 詳細描述
- **acceptance_criteria**: 驗收條件陣列
- **effort**: 工作量評估 (費波那契數列: 1, 2, 3, 5, 8, 13, 21)
- **effort_analysis**: 工作量評估的說明

## Google Docs 整合

### 公開文件

對於公開的 Google Docs，工具會嘗試直接存取內容。

### 私人文件

對於私人文件，您需要：

1. 到 [Google Cloud Console](https://console.cloud.google.com/) 建立專案
2. 啟用 Google Docs API
3. 建立服務帳戶並下載憑證 JSON 檔案
4. 在配置檔案中設定憑證路徑：

```javascript
module.exports = {
  // ... 其他設定
  googleCredentials: './path/to/your/credentials.json'
};

開發

本地開發

# 複製專案
git clone <repository-url>
cd ai-backlog

# 安裝依賴
npm install

# 執行
node src/cli.js [arguments]

測試

npm test

授權

MIT License

貢獻

歡迎提交 Issue 和 Pull Request！

支援

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