taiga-stories

Taiga 故事

沒有瀏覽器控制。上傳作業透過 Taiga REST API，使用 scripts/taiga_stories.py 執行，該腳本僅使用 Python 標準函式庫。相同的工具適用於任何 Taiga 專案，專案設定在 .env 中。

設定（每個儲存庫一次）

1. 將 .env.example 複製到儲存庫根目錄的 .env，並設定 TAIGA_PROJECT_URL 為專案連結，例如 https://taiga.example.com/project/my-project。
2. 可選：設定 STORIES_DIR（預設為 stories）。

.env 不包含機密資訊，且已被 git 忽略。Token 絕對不能放在其中。

撰寫故事

每個故事是 stories/ 中的一個 .md 檔案，遵循 story-template.md。

• **檔案名稱：**全小寫、無重音符號、單字間以連字號分隔（例如 automatic-slug.md）。

• 第一行：# Story: <標題>。「Story:」後面的文字將成為 Taiga 的標題。對於錯誤修正，請使用 Fix — <發生什麼事>。

• 標頭：**Project:**、**Branch:**、**Version:**、**Date:** 和 **Points:**，每行一個。

• **點數：**沒有預設值。在將新故事儲存到 stories/ 之前，請使用 story-points 技能估算其點數（CODE_REPO_PATH 的提交歷史），並讓使用者確認。在 **Points:**（葡萄牙文為 **Pontos:**）中寫入值。必須是專案點數尺度中的名稱（1、2、3、5、8、13、21）。

• 章節，按此順序：## User story（As / I want / so that，各自獨立一行並以粗體顯示）、## Description（為產品負責人撰寫的散文，無程式碼行話）、## Acceptance criteria（- [ ] 核對清單，[x] 表示已完成且測試通過）、## Tasks 和 ## Deployment notes（若非部署相關則使用 ## Notes）。

• **任務：**依序歸類在 ### Backend、### Frontend、### Tests 和 ### Documentation 下，省略空的分組。每個任務為 N. **標題**，其描述縮排在下一行。編號跨組連續。

• **語言：**整個故事（包括標題）使用使用者請求的語言撰寫。葡萄牙文的請求會得到葡萄牙文的故事。兩種標題集合皆可解析：

  英文	葡萄牙文
  # Story:	# História:
  **Project:** / **Branch:** / **Version:** / **Date:** / **Points:**	**Projeto:** / **Branch:** / **Versão:** / **Período:** / **Pontos:**
  ## User story (As / I want / so that)	## História de usuário (Como / quero / para)
  ## Description	## Descrição
  ## Acceptance criteria	## Critérios de aceite
  ## Tasks (### Backend, ### Frontend, ### Tests, ### Documentation)	## Tarefas (### Backend, ### Frontend, ### Testes, ### Documentação)
  ## Deployment notes / ## Notes	## Observações para implantação / ## Observações
  Fix — ...	Correção — ...

• **防火牆友善文字：**在描述中，避免在 code 前方直接使用 ;（請改用句號）、避免逐字標籤如 <script>（請寫「the script tag」）、以及避免路線旁邊的 Class::method 鏈。腳本會嘗試繞過這些問題，但文字品質會變差。

檢查格式（不需網路，不需 token）：

python -X utf8 .claude/skills/taiga-stories/scripts/taiga_stories.py validate [file.md ...]

修復錯誤。任務沒有描述只是一個可接受的警告。缺少 **Points:** 在這裡只是警告，但會阻止上傳。

上傳至 Taiga

每次務必先在聊天中提問

使用 AskUserQuestion，若不可用則直接提問。不要重複使用先前的答案：

1. **目的地：**哪個 Sprint（確切名稱，例如 Sprint 34）或 backlog。
2. **工作階段 Token：**在開啟的 Taiga 分頁中，按 F12 > 主控台 > localStorage.getItem("token")。僅作為命令的內嵌環境變數使用。切勿將其寫入 .env 或任何檔案。
3. **缺少點數：**如果要上傳的故事沒有 **Points:**（--dry-run 會顯示 MISSING），請使用 story-points 技能估算這些故事，列舉其標題並讓使用者確認。將每個值寫入該故事的 **Points:** 行（葡萄牙文為 **Pontos:**），緊接在 **Date:** / **Período:** 之後。已經有點數的故事不會再次估算。 上傳作業會在建立任何項目之前停止，只要有任何故事缺少有效值。

如果 .env 遺失，也請詢問 Taiga 專案連結，並從 .env.example 建立 .env。

步驟

S=.claude/skills/taiga-stories/scripts/taiga_stories.py
python -X utf8 $S validate
python -X utf8 $S upload --sprint "Sprint 34" --dry-run        # 或 --backlog
TAIGA_TOKEN='<token>' python -X utf8 $S upload --sprint "Sprint 34"

在末尾傳入檔案名稱，以僅上傳部分故事。然後向使用者回報建立了多少故事和任務，以及腳本改寫了哪些文字（以及哪些任務的描述被捨棄）。

預設行為：Token 擁有者為故事與任務的負責人，狀態為專案預設值，點數來自每個故事的 **Points:** 欄位，使用專案的可計算角色。

腳本：

• 跳過標題已存在於專案中的故事。僅在使用者要求時使用 --force；
• 在執行中斷時可恢復執行，而不會產生重複（狀態記錄在 stories/.taiga_state.json）。如果中斷，只需再次執行；
• 改寫被防火牆封鎖的文字，並在結尾列出它們。

不要在可能失敗的步驟之後使用 ; 串聯其他建立指令。中途失敗可能導致重複。

經驗教訓

• ** Cloudflare 403 且回應為 HTML 主體**（「Just a moment...」）表示 WAF 封鎖了文字，而非權限問題。腳本會使用更平實的變體重試。如果某個任務最終沒有描述，請將其重寫為純散文（無反引號、無 ::），並使用 PATCH 更新，同時傳送當前的 version。
• 403 且 JSON 為 PermissionDenied 是真正的權限錯誤。一般成員可能無法刪除使用者故事（任務則沒問題），因此請避免重複。如果發生重複，請使用 PATCH 重複利用該故事（主題、描述、點數、里程碑、指派對象、version），而非刪除它。
• 點數放在 points: {"<可計算角色 ID>": <點數 ID>} 中，點數 ID 透過其名稱在專案尺度中查詢。
• 在 Windows 上，Python 無法看到 Git Bash 的 /tmp。請使用 Windows 路徑，並以 -X utf8 執行 Python，以便正確列印重音符號。