@metaphorli/pingcode-cli 0.3.2 → 0.3.3

package/skills/pingcode/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pingcode
-description: 当用户提到 PingCode、工作项、任务、缺陷、故事、需求、项目、迭代、用户令牌、OAuth 登录、认证、查看我的任务、创建或更新工作项时使用此 skill。即使未明确点名，只要请求涉及 PingCode 数据操作，就优先触发此 skill。
+description: 当用户提到 PingCode、工作项、任务、缺陷、故事、需求/idea、项目、迭代、用户令牌、OAuth 登录、认证、查看我的任务、创建或更新工作项时使用此 skill。即使未明确点名，只要请求涉及 PingCode 数据操作，就优先触发此 skill。
 ---
 
 # PingCode
@@ -11,18 +11,21 @@ description: 当用户提到 PingCode、工作项、任务、缺陷、故事、
 
 只要用户请求涉及 PingCode 数据，就优先触发：
 
-- 查看/查询工作项、任务、缺陷、故事、需求
-- 创建/更新/完成工作项，或修改状态、负责人、迭代
+- 查看/查询工作项、任务、缺陷、故事、需求/idea、产品
+- 创建/更新/完成工作项或需求，或修改状态、负责人、迭代
 - 初始化或切换项目、迭代、用户上下文
 - 登录 PingCode、切换令牌类型、处理认证问题
-- 任何提到「PingCode」「我的任务」「未解决缺陷」等的请求
+- 任何提到「PingCode」「我的任务」「未解决缺陷」「产品」等的请求
 
 ## 快速开始
 
 ```bash
-# 1. 认证（用户令牌）
+# 1. 认证（用户令牌，默认打开浏览器）
 pingcode auth login --client-id ID --client-secret SECRET
 
+# 1.1 无浏览器环境（远程服务器/容器）使用 URL+授权码方式
+pingcode auth login --client-id ID --client-secret SECRET --no-browser
+
 # 2. 初始化工作区上下文
 pingcode context init
 
@@ -61,9 +64,12 @@ export PINGCODE_WORKSPACE_CACHE=".pingcode/cache.json"
 
 按用户请求场景选择要阅读的参考文件：
 
-- 登录、切换令牌、询问认证方式或 grant_type → 阅读 `references/auth.md`
+- 登录、切换令牌、询问认证方式或 grant_type、查看当前认证状态 → 阅读 `references/auth.md`
 - 选择项目/迭代/用户、初始化上下文、Agent 前台问答 → 阅读 `references/ctx.md`
 - 查询/创建/更新工作项、改状态、指派负责人 → 阅读 `references/workitem.md`
+- 查询/创建/更新需求 → 阅读 `references/idea.md`
+- 查询产品列表/产品详情 → 阅读 `references/product.md`
+- 查看/创建/删除工作项评论 → 阅读 `references/comment.md`
 
 ## 自然语言速查表
 
@@ -75,16 +81,25 @@ export PINGCODE_WORKSPACE_CACHE=".pingcode/cache.json"
 | 查看我的未解决缺陷 | `pingcode workitem list --type bug --assignee @me --state 未解决 --compact` |
 | 在故事下新增任务 | `pingcode workitem create --title "标题" --type task --parent STORY-123 --dry-run` |
 | 把工作项改成已完成 | `pingcode workitem update SCR-123 --state 已完成 --dry-run` |
+| 查看某产品下的需求 | `pingcode idea list --product PRODUCT_ID --compact` |
+| 查看 PingCode 产品列表 | `pingcode product list --compact` |
+| 查看 PingCode 产品详情 | `pingcode product get PRODUCT_ID` |
+| 创建需求并预览 | `pingcode idea create --product PRODUCT_ID --title "新增登录" --dry-run` |
 | 初始化当前项目/迭代/用户 | `pingcode context init` |
-| 登录 PingCode 获取用户令牌 | `pingcode auth login --client-id ID --client-secret SECRET` |
+| 登录 PingCode 获取用户令牌（默认打开浏览器） | `pingcode auth login --client-id ID --client-secret SECRET` |
+| 登录 PingCode 获取用户令牌（无浏览器环境） | `pingcode auth login --client-id ID --client-secret SECRET --no-browser` |
+| 查看 PingCode 认证状态 | `pingcode auth status` |
+| 查看工作项评论 | `pingcode comment list SCR-123 --compact` |
+| 添加工作项评论 | `pingcode comment create SCR-123 --content "..." --dry-run` |
 
 ## 安全规则
 
 - 禁止回显令牌值。
 - 禁止猜测 `state_id`、`type_id`、`priority_id`、`project_id`、`product_id`。先通过 list 命令或上下文字典将名称解析为 ID。
+- 需求字典（`states`、`properties`、`suites`、`plans`、`priorities`）必须使用 raw ID；不要猜测 `suite_id`、`plan_id`、`state_id`、`priority_id`。`product_id` 同样必须是 raw ID。
 - HTTP 429 表示触发频率限制，等待 `x-pc-retry-after` 秒后重试。
 - 写操作先使用 `--dry-run` 预览请求，确认后再执行真实写入。
-- 默认使用 `--compact` 展示 list/show 输出，除非用户要求完整详情。
+- 默认使用 `--compact` 展示 list/get 输出，除非用户要求完整详情。
 - 未缓存工作区上下文时，不要直接执行写操作；先引导用户完成上下文初始化。
 
 ## 常见错误处理

package/skills/pingcode/references/auth.md

@@ -11,12 +11,18 @@ PingCode 支持两种令牌类型：
 
 ## 用户令牌登录
 
-首次使用用户令牌前必须先运行 `auth login`，会在浏览器中完成授权：
+首次使用用户令牌前必须先运行 `auth login`。默认行为会自动打开浏览器完成授权：
 
 ```bash
 pingcode auth login --client-id ID --client-secret SECRET
 ```
 
+如果当前环境无法打开浏览器（例如远程服务器、容器），可加上 `--no-browser`，改为打印授权 URL 并提示粘贴授权码：
+
+```bash
+pingcode auth login --client-id ID --client-secret SECRET --no-browser
+```
+
 `auth login` 默认 grant_type 为 `authorization_code`，无需显式传入。
 
 登录成功后用户令牌缓存在默认 token cache 中。后续命令自动识别缓存的 grant_type：
@@ -26,6 +32,54 @@ pingcode auth login --client-id ID --client-secret SECRET
 
 显式传 `--grant-type` 可覆盖自动识别。未缓存用户令牌时 fallback 为 `client_credentials`。
 
+## 查看认证状态
+
+使用 `auth status` 查看当前认证状态，包括凭证是否配置、token cache 是否存在、令牌是否有效、剩余有效期等：
+
+```bash
+# 查看默认 token cache 的认证状态
+pingcode auth status
+
+# 指定 token cache 和凭证
+pingcode auth status --token-cache /path/to/token.json --client-id ID --client-secret SECRET
+
+# 查看是否会使用显式传入的访问令牌（不会写入 cache）
+pingcode auth status --token TOKEN
+
+# 紧凑输出
+pingcode auth status --compact
+
+# 试运行，不发起网络请求
+pingcode auth status --dry-run
+```
+
+输出示例（已登录）：
+
+```json
+{
+  "authenticated": true,
+  "grant_type": "authorization_code",
+  "base_url": "https://open.pingcode.com",
+  "token_cache": "/Users/.../.cache/pingcode/token.json",
+  "token_cache_exists": true,
+  "token_valid": true,
+  "token_expires_at": 1739956800,
+  "token_expires_in": 7185,
+  "credentials": {
+    "client_id_configured": true,
+    "client_secret_configured": true
+  },
+  "workspace_cache": ".pingcode/cache.json",
+  "workspace_cache_exists": true
+}
+```
+
+安全规则：
+
+- `auth status` 不会回显 `access_token` 或 `refresh_token` 的值。
+- `--token` 仅用于本次检查，不会保存到 token cache。
+- 当令牌过期或 token cache 不存在时，`authenticated` 和 `token_valid` 为 `false`。
+
 ## 用户令牌下的行为
 
 使用用户令牌时，`pingcode workitem list` 不再默认按当前用户过滤（等价于加 `--all-users`），因此不需要配置 `PINGCODE_USER_ID` 或工作区用户。如需只看自己的工作项，显式加 `--assignee @me` 或 `--user-id`。`client_credentials` 模式下保持原有的默认过滤行为。

package/skills/pingcode/references/comment.md

@@ -0,0 +1,52 @@
+# 评论
+
+通过 `pingcode comment` 子命令创建、查看、获取和删除工作项评论。
+
+`principal_type` 固定为 `work_item`，只支持工作项评论。
+
+## 前置条件
+
+调用 API 前必须配置 PingCode 凭证：
+
+```bash
+export PINGCODE_CLIENT_ID="..."
+export PINGCODE_CLIENT_SECRET="..."
+```
+
+如果缺少凭证，CLI 会输出配置指引，按指引配置后重试。不要要求用户在对话中粘贴凭证或令牌。
+
+## 命令
+
+```bash
+# 创建评论
+pingcode comment create SCR-123 --content "这个工作项需要考虑性能优化"
+
+# 创建回复评论
+pingcode comment create SCR-123 --content "已确认，稍后处理" --reply-to cmt-456
+
+# 查看评论列表
+pingcode comment list SCR-123 --compact
+
+# 获取单个评论
+pingcode comment get cmt-456 SCR-123
+
+# 删除评论
+pingcode comment delete cmt-456 SCR-123
+```
+
+写操作加 `--dry-run` 可预览请求而不实际发送。列表/获取输出默认使用 `--compact`。
+
+## 操作流程
+
+1. 获取目标工作项的 id 或 identifier（如 `SCR-123`）。
+2. 创建评论时提供 `--content`（必填），可选 `--reply-to` 回复已有评论。
+3. 查看、获取或删除评论时同时提供评论 id 和工作项 id/identifier。
+4. 写操作优先使用 `--dry-run` 预览。
+
+## 安全规则
+
+- 禁止猜测 `principal_id`。identifier 会通过 `/v1/project/work_items?identifier=...` 自动解析为 id。
+- `principal_type` 固定为 `work_item`，不支持其他主体类型。
+- 写操作优先 `--dry-run` 预览。
+- HTTP 429 表示触发频率限制，等待 `x-pc-retry-after` 秒后重试。
+- 不要在最终回答中回显令牌值。

package/skills/pingcode/references/ctx.md

@@ -1,6 +1,6 @@
 # 工作区上下文
 
-配置 `.pingcode/cache.json`，让工作项命令可以使用默认的项目、迭代和用户值。
+配置 `.pingcode/cache.json`，让工作项命令可以使用默认的项目、迭代和用户值。`pingcode context list` 以 JSON 输出当前偏好和字典条目数量。
 
 ## Agent 前台问答流程
 
@@ -18,7 +18,7 @@
 ## 命令
 
 ```bash
-# 查看当前工作区偏好和缓存字典数量
+# 以 JSON 输出当前工作区偏好和缓存字典数量
 pingcode context list
 
 # 设置当前项目
@@ -38,7 +38,7 @@ pingcode context init
 
 ## 完成确认
 
-当三项偏好均已缓存后，通过 `pingcode context list` 报告已选择的当前项目、迭代和用户。工作项命令即可使用缓存默认值执行日常工作项查询和创建。
+当三项偏好均已缓存后，通过 `pingcode context list` 以 JSON 格式报告已选择的当前项目、迭代和用户。工作项命令即可使用缓存默认值执行日常工作项查询和创建。
 
 ## 终端回退
 

package/skills/pingcode/references/idea.md

@@ -0,0 +1,70 @@
+# 需求 (Idea)
+
+通过 `pingcode idea` 子命令列出、创建、查看、获取、搜索和更新 PingCode 需求。
+
+## 前置条件
+
+调用 API 前必须配置 PingCode 凭证：
+
+```bash
+export PINGCODE_CLIENT_ID="..."
+export PINGCODE_CLIENT_SECRET="..."
+```
+
+如果缺少凭证，CLI 会输出配置指引，按指引配置后重试。不要要求用户在对话中粘贴凭证或令牌。
+
+## 命令
+
+```bash
+# 查询需求列表
+pingcode idea list --product PRODUCT_ID --compact
+pingcode idea list --product PRODUCT_ID --state STATE_ID --priority PRIORITY_ID --keywords "登录页面" --compact
+pingcode idea list --product PRODUCT_ID --include-public-image-token --compact
+
+# 通过 identifier 获取需求（get 接受 identifier 或 raw ID）
+pingcode idea get SLC-1
+pingcode idea get IDEA_ID
+
+# 搜索需求
+pingcode idea search --product PRODUCT_ID --filter '{"state": {"in": ["STATE_ID"]}}' --keywords "登录" --limit 20 --page-index 1
+pingcode idea search --product PRODUCT_ID --include-public-image-token --limit 50 --page-index 1
+
+# 创建需求（--product 必须是 raw ID；--assignee 支持从缓存解析名称）
+pingcode idea create --product PRODUCT_ID --title "新增登录功能" --dry-run
+pingcode idea create --product PRODUCT_ID --title "新增登录功能" --description "支持手机号登录" --assignee "张三" --suite SUITE_ID --priority PRIORITY_ID --properties '{"custom_field": "value"}'
+
+# 更新需求（通过 identifier 或 id；支持 --title、--description、--state、--priority、--assignee、--progress、--plan-at、--real-at、--plan、--suite、--properties）
+pingcode idea update SLC-1 --state STATE_ID --priority PRIORITY_ID --dry-run
+pingcode idea update SLC-1 --title "修正后的标题" --progress 0.5 --plan-at '{"from": "2026-07-20", "to": "2026-07-30", "granularity": "day"}' --real-at '{"from": "2026-07-21", "to": "2026-07-31", "granularity": "day"}' --plan PLAN_ID --suite SUITE_ID --properties '{"custom_field": "value"}'
+
+# 查询需求字典（均需 --product raw ID）
+pingcode idea states --product PRODUCT_ID
+pingcode idea properties --product PRODUCT_ID
+pingcode idea suites --product PRODUCT_ID
+pingcode idea plans --product PRODUCT_ID
+pingcode idea priorities --product PRODUCT_ID
+
+# 查询需求状态流转历史
+pingcode idea transition-history TRANSITION_HISTORY_ID SLC-1
+pingcode idea transition-histories SLC-1
+pingcode idea transition-histories IDEA_ID
+```
+
+查询/列表输出默认使用 `--compact`。写操作加 `--dry-run` 可预览请求而不实际发送。
+
+## 操作流程
+
+1. 使用 `pingcode context init` 初始化工作区缓存，确保用户列表等字典可用。
+2. 从产品后台或字典接口获取 `product_id`、`state_id`、`priority_id`、`suite_id`、`plan_id` 等 raw ID。
+3. 使用 `pingcode idea list --product PRODUCT_ID --compact` 查看需求标识符（如 `SLC-1`）。
+4. 创建需求时先加 `--dry-run` 预览，确认无误后去掉 `--dry-run` 执行真实写入。
+5. 更新需求时通过 identifier（如 `SLC-1`）定位，涉及字典 ID 的字段均使用 raw ID。
+6. 获取单条需求用 `get`（identifier 或 raw ID 均可）。
+
+## 安全规则
+
+- 禁止猜测 `product_id`、`state_id`、`priority_id`、`suite_id`、`plan_id`。这些字段必须使用 PingCode Web UI 或字典接口返回的 raw ID。
+- 只有 `--assignee` 支持通过名称从工作区缓存解析；其他名称到 ID 的转换必须依赖缓存或字典接口。
+- 创建/更新需求前优先使用 `--dry-run` 预览请求，确认字段正确后再执行真实写入。
+- 不要在最终回答中回显令牌值。
+- HTTP 429 表示触发频率限制，等待 `x-pc-retry-after` 秒后重试。

package/skills/pingcode/references/product.md

@@ -0,0 +1,48 @@
+# 产品
+
+通过 `pingcode product` 子命令列出和获取 PingCode 产品。
+
+## 前置条件
+
+调用 API 前必须配置 PingCode 凭证：
+
+```bash
+export PINGCODE_CLIENT_ID="..."
+export PINGCODE_CLIENT_SECRET="..."
+```
+
+如果缺少凭证，CLI 会输出配置指引，按指引配置后重试。不要要求用户在对话中粘贴凭证或令牌。
+
+## 命令
+
+```bash
+# 列出产品（默认 --compact）
+pingcode product list --compact
+
+# 按关键词搜索产品
+pingcode product list --keywords "核心产品" --compact
+
+# 限制返回数量
+pingcode product list --limit 10 --compact
+
+# 查看单个产品详情（需使用产品 raw id）
+pingcode product get PRODUCT_ID
+
+# 预览 API 请求而不实际发送
+pingcode product list --dry-run
+pingcode product get PRODUCT_ID --dry-run
+```
+
+## 操作流程
+
+1. 使用 `pingcode product list --compact` 查看产品列表，记录目标产品的 `id`。
+2. 使用 `pingcode product get PRODUCT_ID` 查看某个产品的完整详情。
+3. 拿到产品 `id` 后，可在需求（idea）命令中作为 `--product` 参数使用。
+
+## 安全规则
+
+- 禁止猜测 `product_id`。应通过 `product list` 获取产品 ID 后再用于其他命令。
+- 列表/详情查询输出默认使用 `--compact`。
+- 写操作优先使用 `--dry-run` 预览（当前 product 模块仅支持查询）。
+- HTTP 429 表示触发频率限制，等待 `x-pc-retry-after` 秒后重试。
+- 不要在最终回答中回显令牌值。

package/skills/pingcode/references/workitem.md

@@ -25,13 +25,11 @@ pingcode workitem list --keywords "登录页面" --compact
 pingcode workitem create --title "New task" --type task --project PROJECT_ID --sprint SPRINT_ID
 pingcode workitem create --title "Bug fix" --type bug --assignee @me --priority high
 
-# 查看工作项
-pingcode workitem show SCR-123
-pingcode workitem show WI-AbCdEf
-
 # 获取工作项（单个工作项接口，通过 id 或 identifier）
 pingcode workitem get WORK_ITEM_ID
 pingcode workitem get WYT-852
+pingcode workitem get SCR-123
+pingcode workitem get WI-AbCdEf
 
 # 更新工作项（通过 identifier 或 id；支持 --title、--description、--type、--project、--sprint、--state、--priority、--assignee、--parent、--version、--board、--entry、--swimlane、--start-at、--end-at、--participants、--story-points、--estimated-workload、--remaining-workload、--properties）
 pingcode workitem update SCR-123 --state 已完成