| name | plane-core |
| description | 核心知識庫，供 plane-api 和 okr-to-plane 引用。不直接觸發，僅作為共享參照。包含連線設定、欄位規範、命名慣例、Member lookup、專案建立注意事項。 |
Plane 核心知識庫
此文件為共享基礎，由 plane-api 和 okr-to-plane 引用。
連線資訊
.env 位於此 skill 目錄（plane-core/），使用前先載入：
source ~/.cursor/skills/plane/plane-core/.env
export $(cat ~/.cursor/skills/plane/plane-core/.env | xargs)
初始化（首次使用）
若 .env 尚未建立，執行以下初始化流程：
步驟 1：確認 .env 是否存在
ls ~/.cursor/skills/plane/plane-core/.env
步驟 2：若不存在，從範本複製
cp ~/.cursor/skills/plane/plane-core/env.example \
~/.cursor/skills/plane/plane-core/.env
步驟 3：引導使用者填入 API Key
複製後 .env 中 PLANE_API_KEY 尚未設定，告知使用者：
.env 已建立，請填入你的 Plane API Key：
- 開啟 Plane → 右上角頭像 → Profile → API Tokens
- 建立或複製現有 Token
- 將 Token 填入：
~/.cursor/skills/plane/plane-core/.env
將 PLANE_API_KEY="你自己的 api key" 的值替換為實際 Token
完成後告訴我，我會繼續執行。
步驟 4：確認連線
使用者回報填寫完成後，執行以下指令驗證：
source ~/.cursor/skills/plane/plane-core/.env && \
curl -s -o /dev/null -w "%{http_code}" \
-H "x-api-key: $PLANE_API_KEY" \
"$PLANE_BASE_URL/api/v1/workspaces/$PLANE_WORKSPACE/projects/"
回傳 200 表示連線成功，可繼續操作。其他狀態碼代表 Token 無效或網址錯誤。
已知專案快取
讀取 ~/.cursor/skills/plane/plane-core/cache.md 取得已快取的專案 ID 與 States。
寫入時機：
- 查詢到新專案且確認會重複使用 → 寫入「已知專案」
- 查詢到新專案的 States → 寫入「已知 States」對應小節
移除時機：
快取格式（新增專案時依此格式寫入）：
## 已知專案
| 專案 | Project ID |
|------|-----------|
| {專案名稱} | `{project-uuid}` |
## 已知 States
### {專案名稱}
| 狀態 | ID |
|------|---|
| {State 名稱} | `{state-uuid}` |
欄位規範
| 欄位 | 可用值 |
|---|
priority | urgent / high / medium / low / none |
description_html | HTML 字串（<p>, <ul>, <li>, <strong> 等） |
state | State UUID |
assignees | ["user-uuid"]（陣列） |
parent | Issue UUID 或 null |
命名慣例（OKR 類型）
| 類型 | 前綴 | 範例 |
|---|
| Objective | [O] | [O] 建立 4DGS 能力 (Q1/Q2) |
| Key Result | [KR] | [KR] 完成 Blender 基礎建模培訓 |
跨季度拆分時，在標題加上季度標記：(Q1/Q4) 表示全年度計畫的 Q1 部分。
優先級建議
| 類型 | priority |
|---|
| Objective | high |
| Key Result | medium |
Member Lookup
curl -s \
-H "x-api-key: $PLANE_API_KEY" \
"$PLANE_BASE_URL/api/v1/workspaces/$PLANE_WORKSPACE/members/" \
| jq '.[] | {id, display_name, email}'
plane:get_workspace_members
plane:get_project_members
找到 user_id（UUID 格式）後，帶入 assignees: ["user-uuid"]。
建立新專案的注意事項
⚠️ 不要用 MCP plane:create_project 建立新專案。
MCP 建立的專案缺少預設 State 設定，導致後續建立 Work Item 時失敗。
正確流程：
- 讓使用者在 Plane 介面手動建立專案
- 取得 Project ID 後再繼續
若使用者堅持用 API 建立，請參考 plane-api.md 的「建立新專案的標準流程」，並在建立後手動初始化 States。
標準 States 規格（新專案用）
| 名稱 | group | color | default |
|---|
| Backlog | backlog | #D9D9D9 | false |
| Todo | unstarted | #D9D9D9 | false |
| In Progress | started | #F59E0B | true |
| Review | started | #9900EF | false |
| Done | completed | #16A34A | false |
| Cancelled | cancelled | #ABB8C3 | false |
description_html 模板
<h3>背景</h3>
<p>{背景說明}</p>
<h3>目標</h3>
<p>{本 issue 要達成的目標}</p>
<h3>實作步驟</h3>
<ol>
<li>{步驟 1}</li>
<li>{步驟 2}</li>
</ol>
<h3>前置條件</h3>
<ul>
<li>依賴 {序號}：{說明}</li>
</ul>
<h3>驗收條件</h3>
<ul>
<li>{驗收項目 1}</li>
</ul>
已知限制
- Relations API 不支援：self-hosted CE 版無
/relations/ endpoint，改用 description 的「前置條件」欄位代替
- Archive API 為非公開內部 API：需要瀏覽器 session cookie，詳見
plane-api.md
