Plane Agent 项目管理技能

概述

Plane 是一个开源项目/任务管理工具（类似 Jira/Linear）。本技能通过 REST API 操作 Plane，帮助 Agent 团队管理任务、追踪进度。

当前部署：http://localhost:8888 工作空间：Agent Projects（slug: agent-projects）

项目结构（2026-04-09 初始化）：

凭证配置

Setup

mkdir -p ~/.config/plane/
cat > ~/.config/plane/credentials.json << 'EOF'
{
  "PLANE_URL": "http://localhost:8888",
  "PLANE_EMAIL": "axelhu@163.com",
  "PLANE_PASSWORD": "Plane@2026Axel!",
  "PLANE_API_TOKEN": ""
}
EOF
chmod 600 ~/.config/plane/credentials.json

推荐：Setup 后改用 API Token（明文密码不安全）： 登录 Plane → 右上角头像 → Profile → API Tokens → Generate Token

账号注册与邀请

注册新账号（god-mode）

Plane 关闭了公开注册，新用户需由管理员创建：

1. 访问 god-mode 注册页

   http://localhost:8888/god-mode/
   

2. 创建用户

   • 填写邮箱、密码、用户名
   • 该邮箱会收到确认邮件（本地部署可能不发送，直接激活）

3. API 方式注册

   curl -s -X POST \
     http://localhost:8880/api/sign-up/email/ \
     -H "Content-Type: application/json" \
     -d '{
       "email": "newuser@example.com",
       "password": "YourPassword123!",
       "first_name": "User",
       "last_name": "Name"
     }'
   

邀请成员加入 Workspace

1. 通过 Web UI

   • 以管理员身份登录
   • 进入 Workspace 设置 → Members → 发送邀请
   • 输入邮箱，分配角色（Admin / Member / Viewer / Guest）

2. 通过 API 邀请

   # 获取 Workspace ID
   curl -s -b /tmp/plane-cookies.txt \
     "http://localhost:8888/api/workspaces/agent-projects/" \
     | jq '.id'
   
   # 发送邀请
   curl -s -b /tmp/plane-cookies.txt -X POST \
     "http://localhost:8888/api/workspaces/agent-projects/invitations/" \
     -H "Content-Type: application/json" \
     -H "X-CSRFTOKEN: $(cat /tmp/plane-cookies.txt | grep csrftoken | awk '{print $7}')" \
     -d '{
       "email": " invite@example.com",
       "role": "Member"
     }'
   

3. 角色说明

   角色	能做什么
   Admin	全部操作，包括管理成员和设置
   Member	创建/编辑 Issue、Pages，普通操作
   Viewer	只读，无法编辑
   Guest	仅能访问被邀请的项目

Agent 账号建议

• 每个 Agent 独立账号：方便追踪任务归属
• 邮箱格式：agent-name@your-domain.local（本地部署随意）
• 密码：Plane@2026 + 随机字符，存放在各 Agent 的 ~/.config/plane/credentials.json

核心概念

Workspace（工作空间）
  └─ Project（项目）
       ├─ Issue（任务）—— 核心单元
       │    ├── 状态：Backlog → Todo → In Progress → Done
       │    ├── 优先级：P0（紧急）→ P1 → P2 → P3 → P4
       │    ├── 负责人（assignee）
       │    ├── 标签（labels）
       │    └── 描述（Markdown，支持链接）
       └─ Pages（文档）—— 项目内建文档

认证流程

# 1. 登录获取 Session Cookie
curl -s -c /tmp/plane-cookies.txt \
  -X POST http://localhost:8888/api/sign-in/email/ \
  -H "Content-Type: application/json" \
  -d '{"email":"axelhu@163.com","password":"Plane@2026Axel!"}'

# 2. 后续请求带上 Cookie
curl -s -b /tmp/plane-cookies.txt http://localhost:8888/api/workspaces/

Agent 使用准则

核心理念：文档先行

所有任务必须有文档依据。创建 Issue 前，需求、设计、策划必须已有文档记录。

任务 → 必填：需求文档地址 / 设计文档地址 / 讨论记录地址

Issue 创建标准

每个 Issue 必须包含：

description 模板：

## 背景
[为什么做这件事，链接到需求文档/讨论记录]

## 目标
- [具体目标1]
- [具体目标2]

## 验收标准
- [ ] [可检验的标准1]
- [ ] [可检验的标准2]

## 相关文档
- 需求文档：[URL]
- 设计文档：[URL]
- 讨论记录：[URL]

## 相关代码/Git
- 仓库：[URL]
- 目录：[路径]

优先级定义

状态流转

Backlog → Todo（确认要做）→ In Progress（开始做）→ Done（完成验收）
                    ↓
               Cancelled（取消）

注意：创建 Issue 时 state 字段必须使用 状态 ID，不是状态名称。先查询再使用：

curl -s -b /tmp/plane-cookies.txt \
  "http://localhost:8888/api/workspaces/{workspace_slug}/projects/{project_id}/states/" \
  | jq '.[] | {name, id, group}'

常用操作

1. 查工作空间

curl -s -b /tmp/plane-cookies.txt \
  http://localhost:8888/api/users/me/workspaces/ \
  | jq '.results[] | {name, slug}'

2. 查项目 Issue 列表

curl -s -b /tmp/plane-cookies.txt \
  "http://localhost:8888/api/workspaces/agent-projects/projects/c223787d-905f-4e6c-a964-a2cb40295d04/issues/" \
  | jq '.results[] | {id, name, state, priority}'

3. 获取状态 ID（创建 Issue 前必须）

curl -s -b /tmp/plane-cookies.txt \
  "http://localhost:8888/api/workspaces/agent-projects/projects/c223787d-905f-4e6c-a964-a2cb40295d04/states/" \
  | jq '.[] | {name, id, group}'

4. 创建 Issue（带文档链接）

curl -s -b /tmp/plane-cookies.txt -X POST \
  "http://localhost:8888/api/workspaces/agent-projects/projects/c223787d-905f-4e6c-a964-a2cb40295d04/issues/" \
  -H "Content-Type: application/json" \
  -H "X-CSRFTOKEN: $(cat /tmp/plane-cookies.txt | grep csrftoken | awk '{print $7}')" \
  -d '{
    "name": "[任务标题]",
    "description": "## 背景\n[需求文档链接]\n\n## 目标\n- 目标1\n\n## 验收标准\n- [ ] 标准1\n\n## 相关文档\n- 需求：https://...\n- 设计：https://...",
    "priority": "2",
    "state": "{STATE_ID}"
  }' | jq '.id, .name'

5. 更新 Issue 状态

curl -s -b /tmp/plane-cookies.txt -X PATCH \
  "http://localhost:8888/api/issues/{ISSUE_ID}/" \
  -H "Content-Type: application/json" \
  -d '{"state": "{STATE_ID}"}' | jq '.id, .name, .state'

6. 创建 Pages（项目文档）

curl -s -b /tmp/plane-cookies.txt -X POST \
  "http://localhost:8888/api/workspaces/agent-projects/projects/c223787d-905f-4e6c-a964-a2cb40295d04/pages/" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "设计文档：XXX",
    "html": "<h1>XXX 设计文档</h1><p>内容...</p>"
  }' | jq '.id, .name, "url": "http://localhost:8888/\(.workspace_slug)/projects/\(.project_id)/pages/\(.id)"'

7. 查项目所有 Pages

curl -s -b /tmp/plane-cookies.txt \
  "http://localhost:8888/api/workspaces/agent-projects/projects/c223787d-905f-4e6c-a964-a2cb40295d04/pages/" \
  | jq '.results[] | {name, id}'

文档管理方案

方案对比

推荐做法

设计文档/策划案 → 存放在 Plane Pages（通过 API 创建），Issue 描述中链接到对应 Page

外部已有文档 → Issue 描述中直接引用 URL

开会讨论 → 记录在 Plane Pages 或飞书文档，Issue 链接到记录

文档命名规范

# Pages 命名
[类型]-[标题]-[日期]
示例：
- 设计-用户登录模块-20260409.md
- 策划-Agent任务分配方案-20260401.md
- 会议-项目启动会-20260405.md

错误处理

参考

详见 references/api-examples.md（按需加载）