@metaphorli/pingcode-cli 0.3.2

package/scripts/pingcode.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+'use strict';
+
+// ── Library layer ────────────────────────────────────────────────────
+// Import everything from the shared core module and re-export it
+// so that require('./pingcode') remains fully backward-compatible
+// for existing tests and the unified pingcode skill.
+const core = require('./core');
+
+module.exports = { ...core };
+
+// ── Module registry ──────────────────────────────────────────────────
+// Import command modules so they self-register with the shared registry.
+// (Side-effect imports; no circular dependency because these import from
+// ./shared and ../core, never from ../pingcode.)
+require('./commands/context');
+require('./commands/workitem');
+require('./commands/auth');
+
+const shared = require('./commands/shared');
+
+// ── Dispatcher ───────────────────────────────────────────────────────
+function fatal(message) {
+  console.error(`error: ${message}`);
+  process.exit(1);
+}
+
+async function dispatcherMain(argv) {
+  const tokens = argv || process.argv.slice(2);
+
+  // (1) No args, or --help / -h as the first positional arg → help.
+  if (tokens.length === 0 || tokens[0] === '--help' || tokens[0] === '-h') {
+    shared.printModulesHelp();
+    process.exit(0);
+  }
+
+  const firstArg = tokens[0];
+
+  // (2) Recognised module name → dispatch to that module.
+  const mod = shared.getModule(firstArg);
+  if (mod) {
+    try {
+      await mod.run(tokens.slice(1));
+      process.exit(0);
+    } catch (exc) {
+      fatal(exc.message);
+    }
+  }
+
+  // (3) Unknown argument.
+  fatal(`Unknown module: ${firstArg}`);
+}
+
+// ── Entry point ──────────────────────────────────────────────────────
+if (require.main === module) {
+  dispatcherMain().catch((exc) => {
+    console.error(`error: ${exc.message}`);
+    process.exitCode = 1;
+  });
+}

package/skills/pingcode/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: pingcode
+description: 当用户提到 PingCode、工作项、任务、缺陷、故事、需求、项目、迭代、用户令牌、OAuth 登录、认证、查看我的任务、创建或更新工作项时使用此 skill。即使未明确点名，只要请求涉及 PingCode 数据操作，就优先触发此 skill。
+---
+
+# PingCode
+
+统一的 PingCode CLI 操作 skill：认证、工作区上下文与工作项。
+
+## 何时使用此 skill
+
+只要用户请求涉及 PingCode 数据，就优先触发：
+
+- 查看/查询工作项、任务、缺陷、故事、需求
+- 创建/更新/完成工作项，或修改状态、负责人、迭代
+- 初始化或切换项目、迭代、用户上下文
+- 登录 PingCode、切换令牌类型、处理认证问题
+- 任何提到「PingCode」「我的任务」「未解决缺陷」等的请求
+
+## 快速开始
+
+```bash
+# 1. 认证（用户令牌）
+pingcode auth login --client-id ID --client-secret SECRET
+
+# 2. 初始化工作区上下文
+pingcode context init
+
+# 3. 列出工作项
+pingcode workitem list --assignee @me --compact
+```
+
+## 前置条件
+
+调用任何 API 前必须配置 PingCode 凭证：
+
+```bash
+export PINGCODE_CLIENT_ID="..."
+export PINGCODE_CLIENT_SECRET="..."
+```
+
+可选配置：
+
+```bash
+export PINGCODE_BASE_URL="https://open.pingcode.com"
+export PINGCODE_TOKEN_CACHE="$HOME/.cache/pingcode/token.json"
+export PINGCODE_WORKSPACE_CACHE=".pingcode/cache.json"
+```
+
+不要要求用户在对话中粘贴凭证或令牌，不要在最终回答中回显令牌值。
+
+## 执行工作项命令前检查
+
+在回答 `pingcode workitem *` 相关请求前，先确认工作区缓存是否完整：
+
+1. 运行 `pingcode context list` 查看 `current_user_id`、`current_project_id`、`current_sprint_id` 是否已缓存
+2. 缺少任一项时，先引导用户完成 `pingcode context init`（终端交互）或按 Agent 前台问答流程选择项目、迭代、用户
+3. 完成后再重试原工作项命令
+
+## 路由表
+
+按用户请求场景选择要阅读的参考文件：
+
+- 登录、切换令牌、询问认证方式或 grant_type → 阅读 `references/auth.md`
+- 选择项目/迭代/用户、初始化上下文、Agent 前台问答 → 阅读 `references/ctx.md`
+- 查询/创建/更新工作项、改状态、指派负责人 → 阅读 `references/workitem.md`
+
+## 自然语言速查表
+
+将常见请求映射为 CLI 命令：
+
+| 用户请求 | 对应命令 |
+|---|---|
+| 查看我当前没完成的任务 | `pingcode workitem list --assignee @me --state 进行中 --compact` |
+| 查看我的未解决缺陷 | `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 context init` |
+| 登录 PingCode 获取用户令牌 | `pingcode auth login --client-id ID --client-secret SECRET` |
+
+## 安全规则
+
+- 禁止回显令牌值。
+- 禁止猜测 `state_id`、`type_id`、`priority_id`、`project_id`、`product_id`。先通过 list 命令或上下文字典将名称解析为 ID。
+- HTTP 429 表示触发频率限制，等待 `x-pc-retry-after` 秒后重试。
+- 写操作先使用 `--dry-run` 预览请求，确认后再执行真实写入。
+- 默认使用 `--compact` 展示 list/show 输出，除非用户要求完整详情。
+- 未缓存工作区上下文时，不要直接执行写操作；先引导用户完成上下文初始化。
+
+## 常见错误处理
+
+- 缺少 `PINGCODE_CLIENT_ID`/`PINGCODE_CLIENT_SECRET`：输出配置指引，不要索取用户粘贴 secret。
+- 用户令牌模式下工作项过滤行为变化：不再默认按当前用户过滤，需显式加 `--assignee @me`（详见 `references/auth.md`）。
+- 429 限流：读取响应头 `x-pc-retry-after` 后等待并重试。
+- 缓存中缺少项目/迭代/用户：先执行 `pingcode context init` 或按 Agent 前台问答流程补全。
+

package/skills/pingcode/references/auth.md

@@ -0,0 +1,33 @@
+# 认证
+
+PingCode 支持两种令牌类型：
+
+- `client_credentials` → 企业令牌。不区分用户身份，拥有系统管理员权限。
+- `authorization_code` → 用户令牌。代表具体人类用户，适合以个人身份操作 PingCode。
+
+## 企业令牌
+
+已配置凭证但未缓存用户令牌时，命令默认按 `client_credentials` 执行。
+
+## 用户令牌登录
+
+首次使用用户令牌前必须先运行 `auth login`，会在浏览器中完成授权：
+
+```bash
+pingcode auth login --client-id ID --client-secret SECRET
+```
+
+`auth login` 默认 grant_type 为 `authorization_code`，无需显式传入。
+
+登录成功后用户令牌缓存在默认 token cache 中。后续命令自动识别缓存的 grant_type：
+
+- 缓存为企业令牌 → 按 `client_credentials` 执行
+- 缓存为用户令牌 → 按 `authorization_code` 执行
+
+显式传 `--grant-type` 可覆盖自动识别。未缓存用户令牌时 fallback 为 `client_credentials`。
+
+## 用户令牌下的行为
+
+使用用户令牌时，`pingcode workitem list` 不再默认按当前用户过滤（等价于加 `--all-users`），因此不需要配置 `PINGCODE_USER_ID` 或工作区用户。如需只看自己的工作项，显式加 `--assignee @me` 或 `--user-id`。`client_credentials` 模式下保持原有的默认过滤行为。
+
+`@me` 身份解析方式不变：仍然从工作区缓存、`PINGCODE_USER_ID` 或 `PINGCODE_USER_NAME` 展开，不会从令牌本身推断。

package/skills/pingcode/references/ctx.md

@@ -0,0 +1,51 @@
+# 工作区上下文
+
+配置 `.pingcode/cache.json`，让工作项命令可以使用默认的项目、迭代和用户值。
+
+## Agent 前台问答流程
+
+默认不使用终端交互式 `pingcode context init` 命令，而是通过以下 Agent 前台问答流程，让用户在对话中选择，Agent 使用非交互式 CLI 命令写入配置。
+
+1. 对一个选择组执行 list 命令
+2. 在对话中以编号列表展示结果（包含显示名、用户名/邮箱/identifier 及 ID）
+3. 要求用户回复一个编号、ID 或精确名称
+4. 将回复解析为对应选项
+5. 执行对应的 `context set-current-*` 命令
+6. 继续下一个选择组
+
+一次只问一个选择问题。不要要求用户粘贴凭证或令牌。
+
+## 命令
+
+```bash
+# 查看当前工作区偏好和缓存字典数量
+pingcode context list
+
+# 设置当前项目
+pingcode context set-current-project PROJECT_ID_OR_NAME
+
+# 为已缓存的当前项目设置当前迭代
+pingcode context set-current-sprint SPRINT_ID_OR_NAME
+
+# 设置当前用户
+pingcode context set-current-user USER_ID_OR_NAME
+
+# 交互式初始化所有三项偏好
+pingcode context init
+```
+
+如果工作区缓存为空，先运行 `pingcode context init` 填充缓存，再设置单项偏好。
+
+## 完成确认
+
+当三项偏好均已缓存后，通过 `pingcode context list` 报告已选择的当前项目、迭代和用户。工作项命令即可使用缓存默认值执行日常工作项查询和创建。
+
+## 终端回退
+
+如果用户明确要求终端交互，运行：
+
+```bash
+pingcode context init
+```
+
+该命令使用 Node.js readline，可能在工具终端而非 Agent 对话前台显示。

package/skills/pingcode/references/workitem.md

@@ -0,0 +1,64 @@
+# 工作项
+
+通过 `pingcode workitem` 子命令列出、创建、查看、获取和更新 PingCode 工作项。
+
+## 前置条件
+
+调用 API 前必须配置 PingCode 凭证：
+
+```bash
+export PINGCODE_CLIENT_ID="..."
+export PINGCODE_CLIENT_SECRET="..."
+```
+
+如果缺少凭证，CLI 会输出配置指引，按指引配置后重试。不要要求用户在对话中粘贴凭证或令牌。
+
+## 命令
+
+```bash
+# 查询工作项
+pingcode workitem list --assignee @me --state 进行中 --compact
+pingcode workitem list --type bug --assignee @me --compact
+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
+
+# 更新工作项（通过 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 已完成
+pingcode workitem update WI-AbCdEf --state 进行中 --priority high
+pingcode workitem update SCR-123 --title "Updated title" --story-points 3 --start-at 1736985600
+```
+
+查询/列表输出默认使用 `--compact`。写操作加 `--dry-run` 可预览请求而不实际发送。
+
+## 操作流程
+
+1. 使用 list 命令将名称解析为 ID，默认加 `--compact`。PingCode 写接口通常需要 ID。
+2. 目标项目/产品/工作项和状态 ID 明确后直接执行写命令。
+3. 写操作优先使用 `--dry-run` 预览。
+
+## 默认值与身份
+
+当前用户/项目/迭代默认值来自工作区缓存（`.pingcode/cache.json`）。缓存不完整时先用 `pingcode context init` 初始化，然后重试原命令。
+
+查询时 CLI 自动应用缓存的当前用户/项目/迭代过滤条件，除非传了显式参数或 `--all-users`、`--all-projects`、`--all-sprints`。创建时默认使用 `assignee_id=@me`，除非用户明确要求"所有人"或指定了其他负责人。
+
+用户令牌登录及其对默认过滤行为的影响（不再隐式按当前用户过滤；需显式加 `--assignee @me`）见 `references/auth.md`。
+
+## 安全规则
+
+- 禁止猜测 `state_id`、`type_id`、`priority_id`、`project_id`、`product_id`。
+- 状态变更优先使用缓存的状态字典；否则先获取工作项项目和类型的有效状态后再更新。
+- 创建/更新需要 `priority_id` 或自定义 `properties` 时，先通过 `context init` 刷新字典。
+- HTTP 429 表示触发频率限制，等待 `x-pc-retry-after` 秒后重试。
+- 不要在最终回答中回显令牌值。