pingcode-devhub

v1.1.0

Published

a month ago

PingCode 智能研发协同中枢：支持 OpenAPI 任务抓取、Markdown 转换、Qoder/Copilot 全自动/MCP/Prompt 驱动、本地四态流转与发版归档

0High
0Medium
0Low

twotwopiggy

pingcode openapi copilot qoder mcp devhub kanban markdown

⚡ PingCode DevHub (智能研发协同中枢)

为系统开发工程师量身打造：通过 PingCode OpenAPI 定时拉取任务，自动转换为结构化 Markdown 任务文件，赋能 GitHub Copilot / Qoder 自主开发与验证，提供全景看板、一键 VSCode 直达与发版归档。

🌟 核心特性

零终端负担 · 现代化本地 Web UI 看板
- 包含四态生命周期看板：待开发 (Pending) ➔ 开发中 (In Progress) ➔ 待部署 (Completed) ➔ 已发布 (Archived)。
- 自动后台轮询 PingCode，无需常驻终端操作。
三维一键直达体系
- 🚀 VSCode 直达：点击卡片一键唤醒 VSCode 并打开本地 Markdown 文件。
- 🌐 PingCode 直达：点击卡片一键跳转至 PingCode 网页端原始任务。
- 📁 本地文件 定位：点击一键在 Windows 资源管理器中高亮定位文件。
- 📋 复制 Prompt：一键复制为 Copilot / Qoder 结构化适配的 Prompt 提示词。
全自动闭环 (MCP 协议 & /pingcode 指令)
- 内置标准 MCP Server (Model Context Protocol)，Copilot 和 Qoder 可直接在对话框中调用工具自主拉取、编码、测试和回写。
- 附带可直接让 Agent 执行的 自驱研发提示词模版。
高度可定制的状态映射
- 灵活支持团队自定义状态流转（如 未开始 ➔ 进行中 ➔ 待部署 (UAT) ➔ 待测试 等）。
- 支持开发交付完成后可选自动回写状态至 PingCode 平台。
一键发版 (Release Notes)
- 自动聚合已交付的 completed 任务，按 Feature / Bugfix / Task 自动分组生成标准 Release Notes，并一键归档。

📦 NPM 安装与极速运行 (NPM Installation & NPX)

本项目已支持作为标准 NPM 软件包分发与运行：

方式 1: `npx` 免安装极速运行 (推荐，无需预装)

在任意项目目录或终端直接执行，即刻拉起 Web 看板与后台同步：

npx pingcode-devhub

方式 2: 全局安装为系统 CLI 命令 (支持指定安装路径)

# 默认全局安装
npm install -g pingcode-devhub

# 或者指定安装到自定义目录 (例如 D:/my-tools)
npm install -g pingcode-devhub --prefix "D:/my-tools"

方式 3: 项目本地依赖安装

npm install -D pingcode-devhub

在项目的 package.json 中添加快速启动脚本：

"scripts": {
  "pingcode": "pingcode-devhub"
}

📂 自定义指定任务存放路径 (Task Directory)

您可以自由指定 PingCode 任务 Markdown 文件保存在哪个本地工作区（例如当前业务工程的 .tasks 或统一公共路径）：

方式 A: 启动时通过命令行参数指定 (临时指定)

# 启动时指定任务 Markdown 落盘路径
npx pingcode-devhub --task-dir "D:/Projects/MyProject/.tasks"

# 或同时指定自定义配置文件路径
npx pingcode-devhub --config "D:/Projects/MyProject/pingcode.config.json"

方式 B: 在配置文件中永久指定

编辑 pingcode.config.json：

{
  "workflow": {
    "taskDir": "D:/Projects/MyProject/.tasks"
  }
}

方式 C: 在 Web 控制台「⚙️ 设置」中随时修改

在浏览器页面右上角点击 ⚙️ 设置，在任务目录输入框中填入期望的路径并保存，系统立即自动热更新切换任务池。

🛠️ 从源码安装与本地开发 (From Source)

如果您是从 Git 仓库 Clone 源码到自定义路径并进行开发：

# 1. Clone 源码到指定目录
git clone <仓库地址> "D:/your-custom-path/pingcode"
cd "D:/your-custom-path/pingcode"

# 2. 安装依赖
npm install

# 3. 编译构建
npm run build

# 4. 运行单测
npm test

# 5. 本地启动
npm start
# 或双击 Windows 启动脚本 start-hub.bat

🚀 极速启动与体验 (Quick Start)

无论是通过 npx pingcode-devhub、pingcode-devhub 还是本地 npm start 启动：

服务均会自动在默认浏览器中打开控制台：http://localhost:3780。
默认已开启 mockMode: true，开箱即自带预置的敏捷开发 Bug 与需求卡片，无需配置即可体验看板流转、VSCode 唤醒与发版。

⚙️ PingCode OpenAPI 凭证配置流程（4 步搞定）

sequenceDiagram
    autonumber
    actor Dev as 开发工程师
    participant PC as PingCode 管理后台
    participant Hub as PingCode DevHub (Web/Config)
    participant AI as Copilot / Qoder Agent

    Dev->>PC: 1. 进入「管理后台」➔「开发集成」➔「REST API」
    PC-->>Dev: 生成 Client ID 与 Client Secret
    Dev->>Hub: 2. 打开 Web 控制台 (设置) 填入凭证与自定义状态
    Hub->>PC: 3. 点击「测试连接」验证 OAuth2 连通
    Hub->>Hub: 4. 自动定时拉取任务到 .tasks/pending/
    Dev->>AI: 发送 Agent 提示词模版
    AI->>Hub: 自动读取任务 ➔ 编码 ➔ 单测 ➔ 流转到 completed/

步骤 1：在 PingCode 平台获取 OpenAPI 凭据

使用管理员或有权限账号登录 PingCode；
点击右上角头像 ➔ 「管理后台」 ➔ 左侧菜单 「开发集成」 ➔ 「REST API」；
点击 「新建应用/凭据」：
- 名称：例如 DevHub-Agent
- 权限范围：勾选 项目管理 (pjm)、工作项查看与修改 权限；
创建成功后，复制保存生成的 Client ID 与 Client Secret。

步骤 2：在 Web 控制台配置（或编辑 `pingcode.config.json`）

运行 start-hub.bat 打开 Web 控制台（http://localhost:3780）；
点击右上角 ⚙️ 设置 按钮：
- Base URL：保持默认 https://open.pingcode.com（私有化部署填私有域名）；
- Client ID & Client Secret：粘贴刚才获取的凭据；
- 抓取的目标状态：填入自定义状态，例如：未开始, 待办, To Do, 进行中；
- 交付目标状态：填入开发交付完成的目标状态，例如：待部署；
- 定时轮询：建议设为 10 或 15 分钟；
- 取消勾选 启用 Mock 演示模式（切换到真实 PingCode 数据）；
点击 「测试连接」，提示 ✅ 连接成功 后点击 「保存配置」。

🤖 AI Agent (Copilot / Qoder) 自驱执行提示词模版

已在项目中内置了规范文件：AGENT_PROMPT.md 与 .github/copilot-instructions.md。

模版 1：【Agent 全自动自驱领单与闭环提示词】🔥（推荐）

直接复制以下内容发送给 GitHub Copilot Chat、Qoder、Cursor 等智能体：

你是一名高阶系统开发工程师智能体。请按照以下标准工作流，自主完成本地分配的 PingCode 任务：

### 执行工作流：
1. **【扫描待办】**：
   - 读取工作区 `.tasks/pending/` 目录下的 Markdown 任务文件。
   - 自动选择优先级最高（P1/紧急/高）或最新的一项任务。

2. **【标记开工】**：
   - 将选中的任务文件（如 `.tasks/pending/DEV-101.md`）移动至 `.tasks/in_progress/DEV-101.md`。
   - 更新该文件 Frontmatter 中的 `workflow_status: "in_progress"`。

3. **【研读需求与定位】**：
   - 阅读该任务的【任务描述】、【缺陷复现步骤】与【验收标准】。
   - 在代码库中检索相关文件，确定最小侵入式的修改方案。

4. **【编码实现与测试】**：
   - 按照规范编写/修改代码逻辑。
   - 编写针对性的单元测试，并执行测试命令（如 `npm test`、`pytest` 等），**确保 100% 绿灯通过**。

5. **【交付归档与汇报】**：
   - 测试通过后，将任务文件移动至 `.tasks/completed/DEV-101.md`，更新状态为 `completed`。
   - 向我汇报：完成的任务编号、修改的文件清单及测试通过结果。

请立即开始执行上述流程！

模版 2：【指定单任务执行提示词】

请协助我完成以下 PingCode 任务并实现闭环交付：

【目标任务】: .tasks/pending/DEV-101.md

【执行要求】:
1. 读取该文件并将其移至 `.tasks/in_progress/DEV-101.md`；
2. 按照任务中描述的验收标准进行编码修复与功能实现；
3. 编写/运行单元测试，确保测试用例全部绿灯通过；
4. 测试通过后将文件移至 `.tasks/completed/DEV-101.md`；
5. 输出修改摘要与测试验证结论。

🔌 与 GitHub Copilot & Qoder 原生 MCP 集成指南

DevHub 内置了符合标准 Model Context Protocol (MCP) 的工具服务，让 GitHub Copilot 和 Qoder 拥有直接与本地 PingCode 任务池交互的“双手”。

🛠️ 暴露的 MCP 工具集清单

| 工具名称 | 功能描述 | 适用场景 | |---|---|---| | pingcode_sync | 从 PingCode 抓取最新任务并写入 pending/ | 询问“帮我拉取最新待办任务”时自动调用 | | pingcode_list_tasks | 查询任务列表 (支持按 pending/in_progress 等筛选) | 询问“我有哪些任务”时自动调用 | | pingcode_get_task_detail | 读取任务的完整描述、背景与验收标准 | 开始编码前深入分析需求 | | pingcode_start_task | 将任务移至 in_progress/ 并返回需求 | 触发领单开工 | | pingcode_complete_task | 将任务移至 completed/ 并可选回写状态 | 测试通过后交付 | | pingcode_rollback_task | 将任务状态退回上一个阶段 (如退回开发) | 测试不通过或误操作回滚 | | pingcode_generate_release_notes | 聚合已完成任务生成发版日志 | 发版时自动生成 Release Notes |

1. VSCode (GitHub Copilot / Cline / Roo Code) 接入步骤

方式 A: 全网免路径配置 (推荐，基于 NPM/NPX)

若已通过 NPM 发布或全局安装，在 .vscode/settings.json 中可直接写：

{
  "mcpServers": {
    "pingcode": {
      "command": "npx",
      "args": ["-y", "pingcode-devhub", "mcp"]
    }
  }
}

方式 B: 本地源码绝对路径配置

{
  "mcpServers": {
    "pingcode": {
      "command": "node",
      "args": [
        "d:/Computers/AIDevelop/Tools/Skills/pingcode/dist/mcp/pingcode-mcp.js"
      ]
    }
  }
}

方式二：VSCode 全局 MCP 配置

按 Ctrl + Shift + P 打开命令面板；
输入并选择 Preferences: Open User Settings (JSON)；
将上述 mcpServers 对象添加到用户配置中即可对所有工程生效。

2. Qoder 接入步骤

打开 Qoder 编辑器；
点击左下角齿轮或按 Ctrl + , 打开 Settings 设置面板；
在左侧导航栏找到 Tools 或 MCP Servers（Model Context Protocol）选项；
点击 + Add New MCP Server，填入以下参数：
- Server Name (名称): pingcode
- Transport Type (通信类型): stdio
- Command (命令): node
- Arguments (参数): d:/Computers/AIDevelop/Tools/Skills/pingcode/dist/mcp/pingcode-mcp.js
- Working Directory (工作目录): d:/Computers/AIDevelop/Tools/Skills/pingcode
点击 Save 保存。看到状态指示灯变为 🟢 Connected (已连接) 即表示接入成功！

💬 接入成功后的自然语言对话实操

配置完成后，您无需再输入任何复杂命令，只需在 Copilot 或 Qoder 对话框中直接像与同事沟通一样发消息：

自主领单开发：
🗣️ “帮我完成我名下优先级最高的一个 PingCode 缺陷，改完代码后运行单测” ➔ AI 自动调用 pingcode_list_tasks ➔ pingcode_start_task ➔ 编码 ➔ 跑测试 ➔ pingcode_complete_task
状态回退：
🗣️ “刚才那个任务单测失败了，帮我回滚到开发中” ➔ AI 自动调用 pingcode_rollback_task
发版总结：
🗣️ “帮我根据本期交付的任务生成一份 v1.1.0 的 Release Notes 并归档” ➔ AI 自动调用 pingcode_generate_release_notes

📁 目录结构说明

pingcode/
├── pingcode.config.json     # 配置文件 (API 凭证、状态映射、轮询间隔)
├── start-hub.bat            # Windows 双击一键启动脚本
├── AGENT_PROMPT.md          # 专供 AI Agent 自驱执行的提示词模版
├── .tasks/                  # 本地任务四态生命周期目录
│   ├── pending/             # 待开发任务池
│   ├── in_progress/         # 正在开发中的任务
│   ├── completed/           # 已交付/待部署的任务 (等待发版)
│   └── archived/            # 已发版归档的历史任务
├── releases/                # 自动生成的 Release Notes 发版记录
├── src/
│   ├── core/                # OpenAPI 客户端、Markdown 引擎、状态机、发版生成器
│   ├── mcp/                 # MCP Server (Model Context Protocol 工具集)
│   ├── server/              # 本地 Express API 服务
│   ├── skills/              # Agent Skill 规范文件
│   └── ui/                  # 现代看板 UI 控制台 (SPA)
└── test/                    # 单元测试与验证套件

🧪 运行测试

npm test