PingCode Skill

通过 PingCode Open API 操作研发管理平台数据。

服务地址约定：

> 若只配置了 PINGCODE_BASE_URL，脚本会自动推导 OAUTH2_ROOT；建议私有部署用户两个都显式配置以确保清晰。

新用户快速开始

> 当用户询问如何使用此 skill 时，请引导用户完成以下步骤。

本 skill 支持两种鉴权方式，至少配置一种即可使用：

企业令牌（最简单，推荐先配置）

1. 登录 PingCode 企业后台 → 应用管理 → 创建应用，类型选「企业令牌」（client_credentials）
2. 将获取的 Client ID / Client Secret 填入 .env 文件：
   PINGCODE_CLIENT_ID=你的Client ID PINGCODE_CLIENT_SECRET=你的Client Secret
3. 完成，可直接调用所有业务脚本

用户令牌（访问个人数据时需要，如「我的工作项」）

1. 在 PingCode 企业后台另建一个应用，类型选「授权码」（authorization_code），不能复用企业令牌应用
2. 回调地址填写 http://127.0.0.1:8080（推荐！高位端口无需管理员权限，授权脚本可自动捕获回调，全程零手动复制）
3. 将用户令牌应用的凭证填入 .env：
   PINGCODE_USER_CLIENT_ID=你的用户令牌应用Client ID PINGCODE_USER_CLIENT_SECRET=你的用户令牌应用Client Secret PINGCODE_REDIRECT_URI=http://127.0.0.1:8080
4. 运行 python3 scripts/auth_user.py，浏览器会自动打开，登录 PingCode 并同意授权即可
5. 授权完成后 access_token 自动写入 .env，后续脚本自动使用用户令牌

> 为什么推荐 http://127.0.0.1:8080？ 端口 80 在 macOS/Linux 上需要管理员权限，本地服务器无法绑定，会导致自动授权失败。8080 等高位端口无此限制。如果用户已在后台配置了其他回调地址（如 http://127.0.0.1），建议引导用户改为 http://127.0.0.1:8080，或使用 --manual 手动模式。

私有部署环境

公有云用户跳过此步。私有部署需额外配置：

PINGCODE_BASE_URL=https://你的域名/open
PINGCODE_OAUTH2_ROOT=https://你的域名/oauth2

> 重要：私有部署 BASE_URL 需要加 /open 路径前缀！
> - REST API 根地址：https://你的域名/open（对应公有云的 https://open.pingcode.com）
> - OAuth2 授权页面根地址：https://你的域名/oauth2（不加 /open）
> - 如果不加 /open，API 请求会返回前端 HTML 页面而非 JSON 数据
> - 示例（HTTP 私有部署）：PINGCODE_BASE_URL=http://your-domain.com/open

配置指引（详细）

本 skill 支持两种 OAuth2 鉴权方式，使用前需要根据场景选择并配置凭证。

方式一：企业令牌（client_credentials，默认）

适用于后台服务、机器人、访问企业级数据等无人值守场景。

需要提供：
- Client ID
- Client Secret

获取方式：
1. 登录 PingCode 企业后台 → 应用管理 → 创建应用
2. 应用类型选择「企业令牌」（client_credentials）
3. 配置应用的数据访问范围（工作项、项目、工时等）
4. 获取 Client ID 和 Client Secret

配置方法： 将凭证写入 skill 根目录的 .env 文件：

PINGCODE_CLIENT_ID=your_client_id
PINGCODE_CLIENT_SECRET=your_client_secret

方式二：用户令牌（authorization_code）

适用于访问用户个人数据（如「我的工作项」）、以用户身份操作等场景。

需要提供：
- 用户令牌应用的 Client ID（不能复用企业令牌应用）
- 用户令牌应用的 Client Secret
- 回调地址（redirect_uri，需与 PingCode 应用后台配置一致）

获取方式：
1. 登录 PingCode 企业后台 → 应用管理 → 创建应用
2. 应用类型选择「授权码」（authorization_code）
3. 配置回调地址（redirect_uri），推荐使用 http://127.0.0.1:8080
- 高位端口（如 8080）无需管理员权限，授权脚本可自动捕获回调
- 使用 80 端口（如 http://127.0.0.1）在 macOS/Linux 上需要 sudo 权限
4. 获取 Client ID 和 Client Secret

配置方法： 将凭证写入 .env 文件：

PINGCODE_USER_CLIENT_ID=your_user_client_id
PINGCODE_USER_CLIENT_SECRET=your_user_client_secret
PINGCODE_REDIRECT_URI=http://127.0.0.1:8080

然后运行授权脚本获取用户令牌：

# 自动模式（推荐）：自动打开浏览器 + 自动捕获回调，全程无需手动复制
python3 scripts/auth_user.py

# 手动模式：自动打开浏览器，但需手动粘贴回调 URL
python3 scripts/auth_user.py --manual

# 指定回调地址
python3 scripts/auth_user.py --redirect_uri http://127.0.0.1:8080

授权完成后，脚本会自动将 access_token 写入 .env 并切换为用户令牌模式。后续业务脚本自动使用用户令牌。

> 授权流程说明：如果未登录 PingCode，浏览器会先跳转登录页面，登录后点击同意授权。自动模式下，浏览器会显示「授权成功」页面，终端自动完成后续步骤；手动模式下，需将浏览器地址栏中的完整 URL 粘贴回终端。

私有部署环境

如果使用 PingCode 私有部署版本，需要额外配置服务地址：

# REST API 根地址（默认：https://open.pingcode.com）
# 重要：私有部署需要加 /open 路径前缀！
PINGCODE_BASE_URL=https://your-domain.com/open

# OAuth2 授权页面根地址（默认：https://open.pingcode.com/oauth2）
# 注意：OAuth2 根地址不加 /open 前缀
PINGCODE_OAUTH2_ROOT=https://your-domain.com/oauth2

> 排查提示：如果 API 调用返回 HTML 页面而非 JSON，通常是因为 BASE_URL 缺少 /open 前缀。

切换鉴权方式

# 切换到企业令牌
export PINGCODE_AUTH_MODE=client_credentials

# 切换到用户令牌（需先运行 auth_user.py 获取 access_token）
export PINGCODE_AUTH_MODE=authorization_code

也可直接在 .env 文件中设置 PINGCODE_AUTH_MODE。

功能脚本

通用 API 调用器（覆盖全部 588 个接口）

> 这是本 skill 的核心能力，可以调用 PingCode REST API 的任意接口。
> 完整接口列表见 references/api_reference.md（588 个接口，70 个分组）。

# 列出所有接口分组
python3 scripts/api_call.py --list

# 查看某分组的接口列表
python3 scripts/api_call.py --list-group 工作项

# GET 请求（查询参数用 --params key=value，多个参数空格分隔）
python3 scripts/api_call.py GET /v1/project/projects --params page_size=50 page_index=1

# POST 请求（请求体用 --body JSON字符串 或 --body-file 文件路径）
python3 scripts/api_call.py POST /v1/pjm/work_items \
  --body '{"project_id":"xxx","title":"测试","type_id":"task"}'

# 从文件读取请求体
python3 scripts/api_call.py POST /v1/pjm/work_items --body-file /tmp/workitem.json

# PATCH 请求（路径参数直接写在 URL 中）
python3 scripts/api_call.py PATCH /v1/pjm/work_items/abc123 --body '{"title":"新标题"}'

# DELETE 请求
python3 scripts/api_call.py DELETE /v1/pjm/work_items/abc123

# 原始 JSON 输出（不格式化）
python3 scripts/api_call.py GET /v1/project/projects --raw

# Wiki 操作示例（通过通用调用器）
# 列出 Wiki 空间
python3 scripts/api_call.py GET /v1/wiki/spaces --params page_size=100 page_index=1

# 分页遍历全部数据（自动翻页合并所有 values，推荐用于列表接口）
python3 scripts/api_call.py GET /v1/wiki/spaces --fetch-all

# 分页遍历 + 指定每页大小（page_size 仅作请求值，部分接口会忽略）
python3 scripts/api_call.py GET /v1/wiki/spaces --fetch-all --params page_size=50

# 在指定空间中创建页面（content 和 format_type 必须同时传递，format_type 允许值: markdown / html / block）
python3 scripts/api_call.py POST /v1/wiki/pages \
  --body '{"space_id":"空间ID","name":"页面名称","content":"页面内容","format_type":"markdown"}'

# 获取页面正文内容
python3 scripts/api_call.py GET /v1/wiki/pages/{page_id}/content

# 更新页面正文
python3 scripts/api_call.py PUT /v1/wiki/pages/{page_id}/content \
  --body '{"content":"更新后的内容","format_type":"markdown"}'

> 提示：工作项相关接口在 API 参考中使用 /v1/pjm/ 路径前缀，专用脚本中使用 /v1/project/ 路径前缀，两者均有效。使用 api_call.py 时请以 references/api_reference.md 中的路径为准。

使用流程：
1. 用 --list 查看所有分组，或用 --list-group 分组名 查看分组内接口
2. 在 references/api_reference.md 中找到目标接口的路径、方法和参数说明
3. 用 api_call.py METHOD /path --params key=value --body '{...}' 调用

用户授权（获取用户令牌）

# 自动模式（推荐）：自动打开浏览器 + 自动捕获回调
python3 scripts/auth_user.py

# 手动模式：自动打开浏览器，手动粘贴回调 URL
python3 scripts/auth_user.py --manual

# 指定回调地址
python3 scripts/auth_user.py --redirect_uri http://127.0.0.1:8080

# 只获取 token 不保存到 .env
python3 scripts/auth_user.py --dry_run

获取我的工作项

python3 scripts/get_my_tasks.py

输出示例：

📋 你的工作项列表 (共 15 条，显示前 20 条)

⬜ [5e05d844] 优化登录页面性能
   项目: Web端重构 | 状态: 待处理 | 优先级: 高
   负责人: 张三

🔄 [5e05d845] API 接口文档更新
   项目: 开放平台 | 状态: 进行中 | 优先级: 中
   负责人: 李四

获取项目列表

# 列出所有项目
python3 scripts/get_projects.py

# 以 JSON 格式输出
python3 scripts/get_projects.py --json

# 限制返回数量
python3 scripts/get_projects.py --limit 50

输出示例：

📁 项目列表 (共 3 个)

1. 🟢 [5fb277c1] 敏捷示例项目
   类型: scrum | 状态: 进行中 | 负责人: anytao
   描述: 示例项目用于演示敏捷开发流程...

2. 🟢 [5fb277c2] 产品官网重构
   类型: kanban | 状态: 进行中 | 负责人: 张三
   描述: 官网前端重构项目...

获取指定项目的全部工作项

# 通过项目名称查询
python3 scripts/get_project_workitems.py --project_name "敏捷示例"

# 通过项目 ID 查询
python3 scripts/get_project_workitems.py --project_id 62ded365

# 以 JSON 格式输出
python3 scripts/get_project_workitems.py --project_name "敏捷示例" --json

输出示例：

📋 项目工作项 - 敏捷示例 (共 82 条)

⬜ [5fb277c1] 申请售后
   类型: 需求 | 状态: 待处理 | 优先级: 普通
   负责人: anytao

⬜ [5fb277c1] 支付宝支付
   类型: 需求 | 状态: 待处理 | 优先级: 普通
   负责人: anytao

生成项目周报

# 生成周报并输出到控制台
python3 scripts/generate_weekly_report.py

# 指定项目和名称
python3 scripts/generate_weekly_report.py --project_id xxx --project_name "PingCode 重构"

# 输出到文件
python3 scripts/generate_weekly_report.py --output /tmp/weekly_report.md

输出示例：

# PingCode 项目周报
**生成时间**：2026年08月06日 14:30  
**统计周期**：2026-07-30 ~ 2026-08-06  
**数据来源**：PingCode

---

## 一、全局概览

| 指标 | 数量 | 占比 |
|------|------|------|
| 工作项总数 | 112 | 100% |
| 已完成 | 22 | 19.6% |
| 进行中 | 13 | 11.6% |
| 待处理 | 77 | 68.8% |
| 延期风险 | 10 | 8.9% |
| 本周更新 | 1 | - |
| 本周完成 | 0 | - |

### 工作项类型分布

| 类型 | 数量 |
|------|------|
| 需求 | 45 |
| 任务 | 38 |
| 缺陷 | 29 |

---

## 二、项目明细

### 敏捷示例项目

| 指标 | 数值 |
|------|------|
| 工作项总数 | 59 |
| 已完成 | 8 (14%) |
| 进行中 | 4 |
| 待处理 | 47 |
| 延期风险 | 4 |
| 本周更新 | 1 |

**已完成工作项**（共 8 个）：
- [DEMO-1] 示例需求（需求，负责人：张三）
- ...

---

## 三、下周重点建议

1. **待处理工作项较多的项目**：
   - 敏捷示例项目：47 个待处理
2. **需关注延期风险**（共 10 个延期项）：
   - 敏捷示例项目：4 个延期
3. **持续推进进行中工作项**：全局共 13 个进行中，建议跟踪完成进度
4. **本周活跃度**：共 1 个工作项有更新，0 个新完成

更新工作项

# 分配负责人
python3 scripts/update_workitem.py --workitem_id 5fb277c1 --assignee anytao

# 设置开始和截止时间
python3 scripts/update_workitem.py --workitem_id 5fb277c1 --start_date "2026-03-12" --due_date "2026-03-20"

# 同时更新多个字段
python3 scripts/update_workitem.py --workitem_id 5fb277c1 --assignee anytao --start_date "2026-03-12" --due_date "2026-03-20" --priority "高"

# 更新状态
python3 scripts/update_workitem.py --workitem_id 5fb277c1 --status "进行中"

创建工作项

# 基本用法（项目 ID + 标题必填，type_id 默认 task）
python3 scripts/create_workitem.py --project_id <id> --title "修复登录bug" --type_id bug

# 完整参数示例
python3 scripts/create_workitem.py \
  --project_id <id> \
  --title "修复登录bug" \
  --type_id bug \
  --description "登录页面在 Safari 下白屏" \
  --assignee_id <user_id> \
  --priority_id <priority_id> \
  --sprint_id <sprint_id> \
  --start_at "2026-06-18" \
  --end_at "2026-06-25" \
  --story_points 3

# type_id 固定类型：epic / feature / story / task / bug / issue

获取/删除单个工作项

# 获取详情
python3 scripts/get_workitem.py <workitem_id>

# 输出 JSON
python3 scripts/get_workitem.py <workitem_id> --json

# 删除工作项
python3 scripts/get_workitem.py <workitem_id> --delete

获取企业成员列表

# 获取所有成员（拿 user_id 用于 assignee_id 等字段）
python3 scripts/get_members.py

# 按名称搜索
python3 scripts/get_members.py --keyword "张三"

# 以 JSON 格式输出
python3 scripts/get_members.py --json

输出示例：

👥 企业成员列表 (共 12 人，显示 12 条)

🟢 张三 (@zhangsan)
   ID: a0417f68e846aae315c85d24643678a9
   邮箱: zhangsan@company.com

迭代管理

# 获取项目迭代列表
python3 scripts/sprints.py list --project_id <id>

# 按状态过滤 (pending / in_progress / completed)
python3 scripts/sprints.py list --project_id <id> --status in_progress

# 创建迭代
python3 scripts/sprints.py create \
  --project_id <id> \
  --name "Sprint 3" \
  --start_at "2026-07-01" \
  --end_at "2026-07-14" \
  --assignee_id <user_id>

# 更新迭代状态
python3 scripts/sprints.py update \
  --project_id <id> \
  --sprint_id <sprint_id> \
  --status in_progress

评论管理

# 为工作项添加评论
python3 scripts/comments.py create \
  --type work_item \
  --id <workitem_id> \
  --content "已复现，优先处理"

# 获取评论列表
python3 scripts/comments.py list --type work_item --id <workitem_id>

# 删除评论
python3 scripts/comments.py delete <comment_id>

# principal_type 允许值: work_item / test_run / test_case / ticket / idea / page

工时管理

# 获取工时类型列表（先拿到 type_id）
python3 scripts/workloads.py types

# 登记工时
python3 scripts/workloads.py create \
  --principal_id <workitem_id> \
  --type_id <type_id> \
  --duration 4 \
  --report_at "2026-06-18" \
  --report_by_id <user_id>

# 查询工时列表
python3 scripts/workloads.py list --principal_id <workitem_id>

# 按日期范围查询
python3 scripts/workloads.py list --start_at "2026-06-01" --end_at "2026-06-30"

# 更新工时
python3 scripts/workloads.py update <workload_id> --duration 6

# 删除工时
python3 scripts/workloads.py delete <workload_id>

API 参考

完整接口文档

references/api_reference.md 包含全部 588 个接口的完整参考（路径、方法、参数说明、响应示例），按 70 个分组组织。

> 当需要调用任何接口时，先在 references/api_reference.md 中查找接口路径和参数，然后用 api_call.py 调用。

接口分组索引

> 以下列出全部 70 个分组。运行 python3 scripts/api_call.py --list 可查看完整列表，--list-group 分组名 可查看分组内接口。

> 完整分组列表运行 python3 scripts/api_call.py --list 查看。

详见 references/api_docs.md 或访问 https://open.pingcode.com/

已实现的 API 端点

通用调用器（覆盖全部 588 个接口）

专用脚本（常用场景封装）

> 路径说明：专用脚本中使用 /v1/project/ 路径前缀，API 参考文档中使用 /v1/pjm/ 路径前缀，两者均有效。下表端点以 API 参考为准。

> 上表中的 {base_url} 和 {oauth2_root} 分别对应 PINGCODE_BASE_URL 与 PINGCODE_OAUTH2_ROOT，完整服务地址见文档顶部表格。

注意事项

1. 凭证安全：凭证存储在 skill 根目录 .env 文件中，脚本通过 _config.py 自动加载。环境变量可覆盖 .env 中的值。两套凭证独立配置：
   - 企业令牌：PINGCODE_CLIENT_ID / PINGCODE_CLIENT_SECRET
   - 用户令牌：PINGCODE_USER_CLIENT_ID / PINGCODE_USER_CLIENT_SECRET / PINGCODE_REDIRECT_URI / PINGCODE_ACCESS_TOKEN
2. 认证模式切换：
   - PINGCODE_AUTH_MODE=client_credentials（默认）：使用企业令牌，无需用户参与
   - PINGCODE_AUTH_MODE=authorization_code：使用用户令牌，需先运行 auth_user.py 完成授权
3. 用户令牌应用类型：用户令牌需要创建 authorization_code 类型的应用，不能复用企业令牌（client_credentials 类型）的应用
4. 回调地址：使用用户令牌时，需要在 PingCode 应用后台配置合法的 redirect_uri，并确保与 PINGCODE_REDIRECT_URI 一致。每个用户的回调地址可以不同
5. 私有部署：私有部署环境需配置 PINGCODE_BASE_URL 和 PINGCODE_OAUTH2_ROOT，详见上方「私有部署环境」章节
6. 频率限制：每分钟最多 200 次请求
7. Token 有效期：30 天
8. 分页：列表接口分页参数为 page_size（默认 30）与 page_index（从 0 开始，0 才是第一页）。注意三个实测的坑：
   - 部分接口会忽略 page_size，每页固定返回 30 条（实测 GET /v1/wiki/spaces 传任意 page_size 均只返回 30 条）；
   - total 字段可能不准确（如声称 311 但实际遍历结果不同）；
   - 因此遍历时不要用 page * page_size >= total 作为终止条件，而应以"实际返回条数 < 首页实际返回条数"判断是否到末尾。
   - 推荐直接用 --fetch-all 自动遍历（内置以上规则），见上文「分页遍历全部数据」示例。
9. 工作项类型：固定类型 epic/feature/story/task/bug/issue 用于 scrum/kanban 项目；瀑布项目使用自定义类型（通过获取工作项类型列表查询）
10. 配置模板：skill 根目录提供 .env.example 文件作为配置参考模板，可复制为 .env 后填入实际凭证
11. Token 过期刷新：用户令牌有效期 30 天，过期后需重新运行 python3 scripts/auth_user.py 获取新 token
12. --list-group 精确匹配：支持精确分组名匹配（如 --list-group 工作项 精确匹配"工作项"而非"工作项配置"），多个模糊匹配时会列出候选供选择
13. Wiki 页面内容格式：创建/更新页面时 content 和 format_type 必须同时传递，format_type 允许值为 markdown / html / block