@mcohenchen/pingcode-mcp 0.0.0-stage → 0.3.2

package/.env.example

@@ -0,0 +1,29 @@
+# 正式使用请写 ~/.config/pingcode-mcp/config.json（运行 `pingcode-mcp init` 生成模板），
+# MCP 客户端只配 "command": "pingcode-mcp"。
+# 本文件仅用于本机开发 / selftest：复制为 .env（已在 .gitignore 中），不要提交真实 token。
+
+# --- 单令牌（兼容 / 本机开发；生成名为 "default" 的 profile，仅当没有其他 profile 时生效） ---
+# PingCode Open API access token (Bearer)
+PINGCODE_ACCESS_TOKEN=
+# Optional, defaults to https://open.pingcode.com
+PINGCODE_API_BASE_URL=https://open.pingcode.com
+# Optional: your tenant's web address, used to match full page URLs
+PINGCODE_WEB_BASE_URL=https://your-tenant.pingcode.com
+# Optional: wiki space identifier used by pingcode_wiki_list_pages when no space is given
+PINGCODE_DEFAULT_SPACE=DEMO
+
+# --- 可选覆盖 ---
+# Config file location (default: ~/.config/pingcode-mcp/config.json, or $XDG_CONFIG_HOME/pingcode-mcp/config.json)
+# PINGCODE_CONFIG=/path/to/config.json
+# Default profile name (overrides "defaultProfile" in config)
+# PINGCODE_DEFAULT_PROFILE=demo
+
+# Rate limiting: max retries on HTTP 429 (default 4; per-profile "maxRetries" overrides)
+# PINGCODE_MAX_RETRIES=4
+# Minimum gap between requests per profile client, in ms (default 0 = off)
+# PINGCODE_MIN_INTERVAL_MS=0
+
+# --- 高级 / 兼容，不推荐 ---
+# PINGCODE_PROFILES 以 JSON 覆盖配置文件（同名 profile 按字段合并）。多 profile 请写进 config.json，
+# 不要把这段 JSON 塞进 MCP 客户端的 env。
+# PINGCODE_PROFILES=[{"name":"demo","webBaseUrl":"https://your-tenant.pingcode.com","accessToken":"pcpat_REPLACE_ME"}]

package/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+本文件遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
+
+## [0.3.2] - 2026-11-05
+
+### Changed
+
+- npm 包名改为 `@mcohenchen/pingcode-mcp`（`publishConfig.access=public`）；全局命令仍为 `pingcode-mcp`
+- 目录结构重构（无行为变化）：`src/pingcode.ts` 拆分为 `src/client/`（`client.ts` 客户端与 429 重试、`profile.ts` 按 profile 取客户端、`errors.ts`、`refs.ts`）、`src/wiki/`、`src/pjm/`、`src/comments/`；`src/config.ts` → `src/config/index.ts`；工具注册从 `src/index.ts` 移到 `src/tools/`（`common` / `profiles` / `wiki` / `pjm` / `comments` / `register`），`src/index.ts` 仅保留 CLI 参数、服务器创建与连接
+- 离线单测 `scripts/unit-X.ts` → `scripts/unit/X.ts`，`npm run test:unit` 路径同步更新
+
+## [0.3.1] - 2026-11-05
+
+### Added
+
+- 工作项评论工具：`pingcode_work_item_comment_list`、`pingcode_work_item_comment_create`、`pingcode_work_item_comment_delete`（工作项解析与 profile 选择沿用 `pingcode_work_item_get`）
+- `pingcode_work_item_comment_list` 默认过滤已删除评论（`is_deleted=1`、内容为空）；`include_deleted=true` 时全部返回并标记 `deleted: true`
+- `PingCodeClient.post` / `PingCodeClient.delete`：与 `get` 共用请求封装（429 重试、最小请求间隔、错误格式），错误信息带实际 HTTP 方法
+- 离线单测 `scripts/unit-comments.ts`（已并入 `npm run test:unit`）；selftest 增加 DEMO-29 评论新增 → 列出 → 删除冒烟（可用 `SELFTEST_WORK_ITEM` 指定工作项），并清理自己创建的评论
+
+### Note
+
+- **不提供修改评论的工具**：PingCode Open API 不支持更新评论（`OPTIONS /v1/comments/{id}` 返回 `Allow: HEAD,GET,DELETE`，PATCH/PUT 返回 405）。需要改内容时只能删除后重新创建。
+- 列表使用 `GET /v1/comments?principal_type=work_item&principal_id=…`：`/v1/project/work_items/{id}/comments` 的响应不含 `is_deleted` 字段，无法可靠区分已删除评论。
+
+## [0.3.0] - 2026-11-05
+
+### Added
+
+- 项目管理工具：`pingcode_project_get`、`pingcode_work_item_get`、`pingcode_sprint_list`、`pingcode_sprint_work_items`
+- PJM URL 解析：项目 / 看板 / 迭代 / 工作项完整 URL（按主机名匹配 profile，与 Wiki 一致）
+- `incomplete_only`：按 `state.type !== completed` 过滤迭代未完成工作项
+- 看板 URL 中 web short id 无法从 Open API 反查时的解析策略：仅当恰好一个 `in_progress` 迭代时自动选用，否则返回 `candidates` 供选择
+- README「使用示例」与「多 profile / 多租户时 agent 怎么选」（区分 profile / wiki space / project）
+- 离线单测 `scripts/unit-pjm.ts`；selftest 增加 DEMO-77 与 Sprint2 未完成列表冒烟
+
+### Changed
+
+- 工具描述补充多 profile 选择提示：有完整 URL 不问租户；仅有短标识且多 profile 时先 `pingcode_list_profiles` 再问；先定租户再定 space/project/sprint
+
+## [0.2.2] - 2026-11-05
+
+### Added
+
+- HTTP 429 限流等待与重试：统一请求封装读取 `x-pc-retry-after`，无 header 时按 1s/2s/4s/8s… 指数退避，单次等待上限 60s
+- 环境变量 `PINGCODE_MAX_RETRIES`（默认 4；设为 `0` 关闭重试）与 profile 字段 `maxRetries` / `max_retries`（优先级：profile > 环境变量 > 默认）
+- 可选客户端最小请求间隔 `PINGCODE_MIN_INTERVAL_MS`（默认 0；按 profile 客户端分别节流）
+- 每次重试向 stderr 输出一行日志（次数、等待秒数、来自 header 或退避）
+- 离线单测 `scripts/unit-ratelimit.ts`（已并入 `npm run test:unit`）
+- README「限流与重试」说明；`.env.example` 补充上述环境变量
+
+### Changed
+
+- 429 重试耗尽后仍抛出原有 `PingCodeError`（`status` 为 429），错误文案注明已重试次数
+- 401 / 403 / 404 / 5xx 与网络错误不重试
+
+## [0.2.1] - 2026-11-05
+
+### Changed
+
+- 配置以 `~/.config/pingcode-mcp/config.json` 为主路径；MCP 客户端推荐只配 `"command": "pingcode-mcp"`
+- `PINGCODE_PROFILES` 仍可用作覆盖，但文档明确不推荐塞进客户端 `env`
+- 文档与 `.env.example` 改为「配置文件优先、`.env` 仅本机开发/selftest」
+
+### Added
+
+- `pingcode-mcp init` 生成配置模板说明与引导（无 profile 时 stderr / 工具错误提示配置路径）
+
+## [0.2.0] - 2026-11-05
+
+### Added
+
+- 多租户 profile：`name`、`apiBaseUrl`、`webBaseUrl`、`accessToken`、`defaultSpaceIdentifier`
+- 配置文件 `~/.config/pingcode-mcp/config.json` 与环境变量 `PINGCODE_PROFILES` / `PINGCODE_DEFAULT_PROFILE`
+- 工具 `pingcode_list_profiles`（令牌脱敏）
+- `pingcode_wiki_read_page` 按完整 URL 主机名匹配 `webBaseUrl` 自动选 profile
+- `pingcode_wiki_list_pages` 支持空间短标识（如 `DEMO`），结果缓存 5 分钟
+- 全局可执行命令 `pingcode-mcp`（`npm i -g .` / `bin`）
+- CLI：`--version` / `--help` / `init`
+- 离线单测 `scripts/unit-profiles.ts`
+
+## [0.1.0] - 2026-11-05
+
+### Added
+
+- 初版 MCP（stdio）：`pingcode_check_auth`、`pingcode_wiki_read_page`、`pingcode_wiki_list_spaces`、`pingcode_wiki_list_pages`
+- 页面短 ID / 长 ID / Wiki URL 解析；正文以 Markdown 拉取
+- 单令牌环境变量 `PINGCODE_ACCESS_TOKEN` 等；`.env` 本机开发；`npm run selftest`

package/README.md

@@ -1,3 +1,341 @@
-# Temporary Holding Version
+# pingcode-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+基于 [Model Context Protocol](https://modelcontextprotocol.io) 的 PingCode MCP 服务器（stdio 传输），让 Claude 等 MCP 客户端可以读取 PingCode **知识库（Wiki）** 与 **项目管理（项目 / 工作项 / 迭代 / 工作项评论）**。支持多个 PingCode 租户（多 profile），可全局安装为 `pingcode-mcp` 命令；推荐把所有租户写在 `~/.config/pingcode-mcp/config.json`，MCP 客户端只配 `"command": "pingcode-mcp"`。
+
+变更记录见 [CHANGELOG.md](./CHANGELOG.md)。
+
+## 工具
+
+所有工具都接受可选参数 `profile`（profile 名称 = 租户）。省略时：完整 `*.pingcode.com` URL 会按主机名匹配 `webBaseUrl`；否则使用默认 profile。选择规则见下方「多 profile / 多租户时 agent 怎么选」。
+
+| 工具 | 说明 | 对应 API |
+| --- | --- | --- |
+| `pingcode_list_profiles` | 列出已配置的 profile：名称、是否默认、`apiBaseUrl`、`webBaseUrl`、`defaultSpaceIdentifier`，令牌脱敏（仅显示后 4 位） | — |
+| `pingcode_check_auth` | 校验访问令牌，返回当前用户 | `GET /v1/myself` |
+| `pingcode_wiki_read_page` | 读取页面 Markdown。`url_or_id` 支持完整 URL、短 ID 或 24 位长 ID | `GET /v1/wiki/pages/{id}` + `…/content?format_type=markdown` |
+| `pingcode_wiki_list_spaces` | 列出知识库空间 | `GET /v1/wiki/spaces` |
+| `pingcode_wiki_list_pages` | 列出空间下的页面（`space_id` / `space_identifier` / `space`，或 profile 的 `defaultSpaceIdentifier`） | `GET /v1/wiki/pages?space_id=...` |
+| `pingcode_project_get` | 获取项目。支持 identifier（`DEMO`）、id，或 `…/pjm/projects/DEMO/…` URL | `GET /v1/project/projects?identifier=` / `{id}` |
+| `pingcode_work_item_get` | 获取工作项。支持 `DEMO-77`、短/长 id，或 `…/pjm/workitems/…` URL | `GET /v1/project/work_items?identifier=` / `{id}` |
+| `pingcode_work_item_comment_list` | 列出工作项评论；默认过滤已删除（`is_deleted=1`、内容为空），`include_deleted=true` 时全部返回并标 `deleted: true` | `GET /v1/comments?principal_type=work_item&principal_id=` |
+| `pingcode_work_item_comment_create` | 给工作项新增评论（`content`） | `POST /v1/project/work_items/{id}/comments` |
+| `pingcode_work_item_comment_delete` | 删除工作项评论（`comment_id`） | `DELETE /v1/comments/{id}?principal_type=work_item&principal_id=` |
+| `pingcode_sprint_list` | 列出项目下的迭代 | `GET /v1/project/projects/{id}/sprints` |
+| `pingcode_sprint_work_items` | 列出迭代工作项；`incomplete_only` 过滤未完成；也可传看板/迭代 URL | `GET /v1/project/work_items?project_id&sprint_id` |
+
+> **不支持修改评论。** PingCode Open API 对评论没有 PATCH/PUT（`OPTIONS /v1/comments/{id}` 返回 `Allow: HEAD,GET,DELETE`，PATCH/PUT 返回 405），因此本服务器不提供 update/edit 工具。要改评论只能删掉再新增一条。
+
+出错时工具返回 `isError: true`，消息包含 profile、HTTP 状态码和 PingCode 错误码，例如：
+
+```
+PingCode API 错误 [profile demo]: GET /v1/wiki/pages/NOPE1234 -> HTTP 400, code=100903: 页面不存在或无权访问
+```
+
+## 使用示例（给人和 agent）
+
+以下用演示租户 `https://wyav20261105054550583.pingcode.com`（项目/空间标识均为 `DEMO`）说明三类常见操作。
+
+### 1. 读知识库页面
+
+用户给了 Wiki URL 时，直接调用 `pingcode_wiki_read_page`，**不要**再问选哪个 profile（主机名会自动匹配）：
+
+```json
+{
+  "url_or_id": "https://wyav20261105054550583.pingcode.com/wiki/spaces/DEMO/pages/gjui-JX2"
+}
+```
+
+返回页面标题、Markdown 正文等（示例页名一般为 "Getting Started"）。若只有短 ID `gjui-JX2` 且配置了多个 profile，先 `pingcode_list_profiles`，把「名称 + webBaseUrl」列给用户选租户。
+
+### 2. 查看需求 / 工作项 DEMO-77
+
+```json
+{
+  "work_item": "DEMO-77"
+}
+```
+
+或带完整 URL（自动选 profile）：
+
+```json
+{
+  "work_item": "https://wyav20261105054550583.pingcode.com/pjm/workitems/t_SLq5Dw"
+}
+```
+
+`pingcode_work_item_get` 返回精简字段：`identifier`、`title`、`type`、`state`、`assignee`、`sprint`、`project`、`html_url`、`description_summary`。示例：`DEMO-77` / `[Server] Get a paginated product list` / 状态「进行中」(`in_progress`) / 迭代 Sprint2。
+
+### 3. 看某个迭代还剩什么没完成
+
+看板 URL 示例：
+
+```text
+https://wyav20261105054550583.pingcode.com/pjm/projects/DEMO/sprints/CU4DQFbH/board
+```
+
+调用 `pingcode_sprint_work_items`：
+
+```json
+{
+  "url": "https://wyav20261105054550583.pingcode.com/pjm/projects/DEMO/sprints/CU4DQFbH/board",
+  "incomplete_only": true
+}
+```
+
+或显式指定项目与迭代名：
+
+```json
+{
+  "project": "DEMO",
+  "sprint": "Sprint2",
+  "incomplete_only": true
+}
+```
+
+「未完成」= `state.type` 不是 `completed`（含 `pending` / `in_progress` 等）。  
+说明：看板路径里的 `CU4DQFbH` 是 Web short id，Open API 的 sprint 列表**不返回** `short_id`，无法反查。若项目里恰好只有一个 `in_progress` 迭代，会自动选用并在结果里加 `note`；否则返回 `needs_sprint_selection` + `candidates`（name/status/id），请列出选项让用户选，**不要瞎猜**。该演示项目的 boards 接口可能返回「项目不支持看板」，未完成项以 sprint + work_items 过滤即可。
+
+## 多 profile / 多租户时 agent 怎么选
+
+先分清三个概念，**不要混问**：
+
+| 概念 | 是什么 | 例子 |
+| --- | --- | --- |
+| **profile** | 一个 PingCode **租户**（不同 `*.pingcode.com` + 令牌） | `demo` → `https://wyav….pingcode.com` |
+| **wiki space** | 某租户下的**知识库空间**标识 | `DEMO`（Wiki） |
+| **project** | 某租户下的**项目**标识 | `DEMO`（PJM；可与 space 同名） |
+
+选择顺序：**先定租户（profile），再定空间 / 项目 / 迭代**。
+
+1. **用户给了完整 URL**（Wiki 或 `/pjm/projects/…` / `/pjm/workitems/…`）→ 用主机名匹配各 profile 的 `webBaseUrl`，**不要问**用户选哪个租户。
+2. **用户显式说了 profile 名** → 用它。
+3. **只有** `DEMO-77` / 短 id / 裸 `DEMO`，且配置了**多个** profile → **先**调用 `pingcode_list_profiles`，再**询问用户选哪个租户/profile**，选项列成 `名称 + webBaseUrl`。不要默默用 default，除非只有一个 profile，或用户已指定且匹配唯一合理。
+4. **同一租户下**多个 wiki space、或多个 sprint 且无法从 URL/名称唯一确定 → 再问 space 或 sprint（列出候选）。看板 short id 无法映射时同理，看工具返回的 `candidates`。
+5. **不要**把「问 space」和「问 profile」当成一回事：space/project 标识（如 `DEMO`）在不同租户里可能都存在；先定租户，再定空间/项目/迭代。
+
+`pingcode_wiki_read_page` / 项目管理工具在传入完整 URL 且未传 `profile` 时的主机匹配细节，与下文「页面 URL 与 profile 的匹配」相同（PJM URL 同样按 host 选择）。
+
+## 快速开始（推荐）
+
+三步：写配置文件 → 全局安装 → MCP 客户端只配 `command`。
+
+### 1. 写配置文件 `~/.config/pingcode-mcp/config.json`
+
+```json
+{
+  "defaultProfile": "demo",
+  "profiles": [
+    {
+      "name": "demo",
+      "apiBaseUrl": "https://open.pingcode.com",
+      "webBaseUrl": "https://your-tenant.pingcode.com",
+      "accessToken": "pcpat_REPLACE_ME",
+      "defaultSpaceIdentifier": "DEMO"
+    },
+    {
+      "name": "other",
+      "webBaseUrl": "https://other.pingcode.com",
+      "accessToken": "pcpat_REPLACE_ME"
+    }
+  ]
+}
+```
+
+可以用 `pingcode-mcp init` 生成模板（见第 2 步之后），再把 `accessToken`、`webBaseUrl` 换成自己的。配置文件包含令牌，请 `chmod 600 ~/.config/pingcode-mcp/config.json`。
+
+### 2. 全局安装
+
+推荐从 npm 安装（包名 `@mcohenchen/pingcode-mcp`，命令仍是 `pingcode-mcp`）：
+
+```bash
+npm i -g @mcohenchen/pingcode-mcp
+pingcode-mcp --version
+pingcode-mcp init     # 生成 ~/.config/pingcode-mcp/config.json 模板（已存在时拒绝覆盖，加 --force 强制）
+```
+
+或从源码安装：
+
+```bash
+git clone https://github.com/xl495/pingcode-mcp.git && cd pingcode-mcp
+npm install
+npm run build
+npm i -g .
+pingcode-mcp --version
+pingcode-mcp init
+```
+
+`pingcode-mcp init` 写入的位置是 `PINGCODE_CONFIG`（如设置）或默认配置路径；目录不存在会自动创建，文件权限为 600。
+
+### 3. MCP 客户端只配 `command`
+
+令牌和租户都在配置文件里，MCP 客户端配置**不需要 `env`**：
+
+**Claude Code**
+
+```bash
+claude mcp add pingcode -- pingcode-mcp
+```
+
+或在项目根目录的 `.mcp.json` 中：
+
+```json
+{
+  "mcpServers": {
+    "pingcode": {
+      "command": "pingcode-mcp"
+    }
+  }
+}
+```
+
+**Claude Desktop / Cursor**
+
+Claude Desktop 编辑 `claude_desktop_config.json`（macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`，Windows: `%APPDATA%\Claude\claude_desktop_config.json`）；Cursor 编辑 `~/.cursor/mcp.json` 或项目内 `.cursor/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "pingcode": {
+      "command": "pingcode-mcp"
+    }
+  }
+}
+```
+
+GUI 客户端的 `PATH` 可能不包含 npm 全局 bin 目录；如果找不到命令，把 `command` 改成 `which pingcode-mcp` 输出的绝对路径。未全局安装时，可用 `"command": "node", "args": ["/absolute/path/to/pingcode-mcp/dist/index.js"]`。修改配置文件或客户端配置后重启客户端。
+
+启动时如果没有任何 profile，服务器会在 stderr 打印一次提示（配置文件路径 + 最小示例）；调用工具时也会返回同样的引导。
+
+## 配置
+
+### 配置文件
+
+位置：默认 `~/.config/pingcode-mcp/config.json`（设置了 `XDG_CONFIG_HOME` 时为 `$XDG_CONFIG_HOME/pingcode-mcp/config.json`；Windows 上是 `%USERPROFILE%\.config\pingcode-mcp\config.json`），可用环境变量 `PINGCODE_CONFIG` 指定其他路径。
+
+每个 profile 的字段（也接受 snake_case 写法）：
+
+| 字段 | 别名 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `name` | | 多个 profile 时必填 | profile 名称；只有一个时默认为 `default` |
+| `accessToken` | `access_token` | 是 | PingCode 开放平台访问令牌（以 Bearer 方式发送） |
+| `apiBaseUrl` | `api_base_url` | 否 | 默认 `https://open.pingcode.com` |
+| `webBaseUrl` | `web_base_url` | 否 | 租户 Web 地址，用于按 Wiki/PJM URL 主机名选择 profile |
+| `defaultSpaceIdentifier` | `default_space_identifier` | 否 | 默认知识库空间标识，如 `DEMO` |
+| `maxRetries` | `max_retries` | 否 | 该 profile 遇到 HTTP 429 时的最大重试次数（覆盖 `PINGCODE_MAX_RETRIES`） |
+
+`profiles` 也可以写成以名称为键的对象：`{"profiles": {"demo": {...}, "other": {...}}}`。
+
+默认 profile：`PINGCODE_DEFAULT_PROFILE` > 配置中的 `defaultProfile` > 名为 `default` 的 profile > 第一个 profile。
+
+### 单令牌环境变量（兼容 / 本机开发）
+
+不写配置文件时，也可以只设置一个令牌，自动生成名为 `default` 的 profile。**仅当没有任何其他 profile 时生效**，主要用于本机开发和 `npm run selftest`：
+
+| 环境变量 | 必填 | 说明 |
+| --- | --- | --- |
+| `PINGCODE_ACCESS_TOKEN` | 是 | 访问令牌 |
+| `PINGCODE_API_BASE_URL` | 否 | 默认 `https://open.pingcode.com` |
+| `PINGCODE_WEB_BASE_URL` | 否 | 租户 Web 地址（匹配 Wiki/PJM URL） |
+| `PINGCODE_DEFAULT_SPACE` | 否 | 默认知识库空间标识 |
+
+可以复制 `.env.example` 为 `.env`。`.env` 会从项目根目录（以及当前工作目录）加载，已有的环境变量优先。
+
+### 高级 / 兼容：`PINGCODE_PROFILES`
+
+`PINGCODE_PROFILES` 环境变量可以用 JSON（数组，或与配置文件相同结构的对象）定义 profile，作为对配置文件的**覆盖**：同名 profile 按字段合并，环境变量一侧优先。它仍受支持，但**不推荐**——尤其不要把这段大 JSON 塞进 MCP 客户端配置的 `env` 里（难维护、令牌散落在多个客户端配置中）。多租户请写进配置文件。
+
+```bash
+# 仅在确有需要时（例如 CI 临时覆盖某个 profile 的令牌）
+export PINGCODE_PROFILES='[{"name":"demo","accessToken":"pcpat_REPLACE_ME"}]'
+```
+
+完整的加载顺序（优先级从高到低）：`PINGCODE_PROFILES` > 配置文件 > 单令牌环境变量（仅当前两者都没有 profile 时）。日常只需关心配置文件。
+
+### URL 与 profile 的匹配
+
+Wiki 与 PJM 工具在传入完整 URL 时共用同一套主机匹配（`selectProfile`）：
+
+- 传了 `profile` 参数：总是使用该 profile（仍从 URL 中解析资源 ID）
+- 完整 URL（Wiki 或 `https://xxx.pingcode.com/pjm/projects/DEMO/...` 等）且未传 `profile`：按主机名匹配各 profile 的 `webBaseUrl`（忽略大小写和末尾斜杠）
+  - 恰好一个匹配：使用它
+  - 多个匹配：如果默认 profile 在其中则用默认 profile，否则报错
+  - 没有匹配：报错并列出所有 profile 及其 `webBaseUrl`；例外：只配置了一个 profile 且它没有设置 `webBaseUrl`（典型的旧版单令牌配置）时直接使用它
+- 短 ID / 长 ID / 相对路径 / 裸 identifier（如 `DEMO-77`）：使用默认 profile（多 profile 时 agent 应先问用户，见上文）
+
+### 空间标识
+
+`pingcode_wiki_list_pages` 可以直接用空间标识（如 `DEMO`）代替 24 位 `space_id`，服务器会分页列出空间并解析（大小写不敏感，也接受完全相同的空间名称），结果缓存 5 分钟。示例参数：
+
+```json
+{ "space_identifier": "DEMO", "page_size": 20 }
+{ "space": "DEMO", "profile": "other" }
+{}
+```
+
+最后一种需要 profile 配置了 `defaultSpaceIdentifier`（或旧版的 `PINGCODE_DEFAULT_SPACE`）。
+
+### 限流与重试
+
+PingCode Open API 限流约为每个身份 200 次/分钟。所有请求都经过统一的请求封装：
+
+- 收到 HTTP 429 时读取响应头 `x-pc-retry-after`（秒），等待后重试；没有该头（或无法解析）时按指数退避 1s / 2s / 4s / 8s…；单次等待最多 60 秒
+- 最大重试次数默认 4，优先级：profile 的 `maxRetries` > 环境变量 `PINGCODE_MAX_RETRIES` > 4（设为 `0` 关闭重试）
+- 每次重试会在 stderr 输出一行日志（第几次重试、等待秒数、等待来源）；重试用尽后照常抛出 `PingCodeError`（`status` 为 429）
+- 可选的客户端最小请求间隔：`PINGCODE_MIN_INTERVAL_MS`（毫秒，默认 `0` 不限制；按 profile 的客户端分别计算），例如设为 `300` 可将单个 profile 控制在约 200 次/分钟以内
+
+非 429 的错误（401/403/404/5xx、网络错误）不会重试。
+
+### 4. 给工作项写评论 → 查看 → 删除
+
+以 Sprint2 中的 `DEMO-29`（View product details）为例。`work_item` 与 `pingcode_work_item_get` 一样支持 `DEMO-29`、短/长 id 或完整工作项 URL，profile 选择规则也一致。
+
+写评论 `pingcode_work_item_comment_create`：
+
+```json
+{ "work_item": "DEMO-29", "content": "已确认详情页字段，待联调" }
+```
+
+返回 `{ profile, work_item: { id, identifier, title }, comment: { id, content, created_at, created_by } }`。
+
+查看评论 `pingcode_work_item_comment_list`：
+
+```json
+{ "work_item": "DEMO-29" }
+```
+
+返回 `{ profile, work_item, total, comments: [...] }`，默认不含已删除评论。
+
+删除评论 `pingcode_work_item_comment_delete`（`comment_id` 取自上一步）：
+
+```json
+{ "work_item": "DEMO-29", "comment_id": "6aec49a1a23bd060a59436cc" }
+```
+
+删除后 PingCode 会保留一条 `is_deleted=1`、`content` 为空的记录；默认列表会过滤掉，传 `"include_deleted": true` 可看到（标记 `deleted: true`）。
+
+**不支持修改评论**：Open API 没有评论更新接口，需要改内容时请先删除再重新创建。
+
+## 开发与测试
+
+```bash
+npm run test:unit   # 离线单元测试：profile、Wiki/PJM URL、sprint 选择、429 重试/限流、评论（mock fetch）
+npm run selftest    # 真实 API 冒烟测试（使用 .env / 配置的 profile；SKIP_LIVE=1 跳过）
+npm test            # 两者依次执行
+npm start           # 从源码以 stdio 方式启动（需先 npm run build）
+```
+
+- `src/index.ts`：入口（`--version` / `--help` / `init` 参数、创建 MCP 服务器、`registerAllTools`、连接 stdio）
+- `src/init.ts`：`pingcode-mcp init` 配置模板与无配置提示
+- `src/config/index.ts`：profile 加载（环境变量 / 配置文件 / 旧版单令牌）、默认 profile、URL 主机匹配、令牌脱敏
+- `src/client/`：`client.ts` API 客户端（429 重试、最小请求间隔）；`profile.ts` 按 profile 缓存的客户端（`getClientFor` / `getClientForProfile`）；`errors.ts` `PingCodeError`；`refs.ts` URL/id 解析共用正则
+- `src/wiki/index.ts`：Wiki URL 解析、页面读取、空间/页面列表、空间标识解析
+- `src/pjm/index.ts`：PJM URL 解析、项目/工作项/迭代、sprint 选择策略
+- `src/comments/index.ts`：工作项评论 list/create/delete
+- `src/tools/`：MCP 工具注册（`common.ts` 公共参数与结果封装；`profiles` / `wiki` / `pjm` / `comments` 各自的工具；`register.ts` 汇总注册）
+- `scripts/unit/profiles.ts`：profile 加载/选择、Wiki URL 解析的离线单测
+- `scripts/unit/ratelimit.ts`：429 重试 / 退避 / 最小间隔（mock `fetch`，注入 `sleep`）
+- `scripts/unit/pjm.ts`：PJM URL 解析、未完成过滤、sprint 选择策略的离线单测
+- `scripts/unit/comments.ts`：评论 list/create/delete 路径与参数、`include_deleted` 过滤、`post`/`delete` 方法（mock `fetch`）
+- `scripts/selftest.ts`：真实 API 冒烟（Wiki + DEMO-77 + Sprint2 未完成 + DEMO-29 评论新增→列出→删除，会清理自己创建的评论；`SELFTEST_WORK_ITEM` 可换工作项；`SKIP_LIVE=1` 跳过）
+
+注意：stdout 是 MCP 协议通道，日志请写到 stderr。

package/dist/client/client.js

@@ -0,0 +1,124 @@
+import { PingCodeError } from "./errors.js";
+import { parseNonNegativeInt, resolveProfile } from "../config/index.js";
+export const DEFAULT_MAX_RETRIES = 4;
+/** Upper bound for a single 429 wait (x-pc-retry-after or backoff). */
+export const MAX_RETRY_WAIT_MS = 60_000;
+const BACKOFF_BASE_MS = 1_000;
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Wait before retry `attempt` (1-based): x-pc-retry-after seconds if valid, else 1s/2s/4s…; capped. */
+export function retryDelayMs(retryAfter, attempt) {
+    const secs = retryAfter !== null && retryAfter.trim() ? Number(retryAfter.trim()) : NaN;
+    if (Number.isFinite(secs) && secs >= 0)
+        return { ms: Math.min(secs * 1000, MAX_RETRY_WAIT_MS), fromHeader: true };
+    return { ms: Math.min(BACKOFF_BASE_MS * 2 ** (attempt - 1), MAX_RETRY_WAIT_MS), fromHeader: false };
+}
+export class PingCodeClient {
+    profile;
+    maxRetries;
+    minIntervalMs;
+    fetchImpl;
+    sleep;
+    log;
+    /** Earliest time the next request may start (min-interval throttle). */
+    nextSlotAt = 0;
+    constructor(profile = resolveProfile(), options = {}) {
+        this.profile = profile;
+        this.maxRetries =
+            options.maxRetries ?? profile.maxRetries ?? parseNonNegativeInt(process.env.PINGCODE_MAX_RETRIES) ?? DEFAULT_MAX_RETRIES;
+        this.minIntervalMs = options.minIntervalMs ?? parseNonNegativeInt(process.env.PINGCODE_MIN_INTERVAL_MS) ?? 0;
+        this.fetchImpl = options.fetch ?? ((...args) => fetch(...args));
+        this.sleep = options.sleep ?? defaultSleep;
+        this.log = options.log ?? ((msg) => console.error(msg));
+    }
+    /** Reserve the next request slot (synchronously, so concurrent callers queue up) and wait for it. */
+    async throttle() {
+        if (this.minIntervalMs <= 0)
+            return;
+        const now = Date.now();
+        const at = Math.max(now, this.nextSlotAt);
+        this.nextSlotAt = at + this.minIntervalMs;
+        if (at > now)
+            await this.sleep(at - now);
+    }
+    /** Single entry point for HTTP: throttling + retry on 429. */
+    async request(url, init) {
+        const method = init.method ?? "GET";
+        for (let attempt = 1;; attempt++) {
+            await this.throttle();
+            let res;
+            try {
+                res = await this.fetchImpl(url, { ...init, signal: AbortSignal.timeout(30_000) });
+            }
+            catch (err) {
+                throw new PingCodeError(`请求 PingCode 失败 (profile ${this.profile.name}, ${method} ${url.pathname}): ${err.message}`);
+            }
+            if (res.status !== 429 || attempt > this.maxRetries)
+                return res;
+            const { ms, fromHeader } = retryDelayMs(res.headers.get("x-pc-retry-after"), attempt);
+            await res.body?.cancel().catch(() => { });
+            this.log(`pingcode-mcp: HTTP 429 [profile ${this.profile.name}] ${method} ${url.pathname}; ` +
+                `retry ${attempt}/${this.maxRetries} in ${ms / 1000}s (${fromHeader ? "x-pc-retry-after" : "backoff"})`);
+            await this.sleep(ms);
+        }
+    }
+    get(apiPath, query = {}) {
+        return this.requestJson("GET", apiPath, query);
+    }
+    post(apiPath, body, query = {}) {
+        return this.requestJson("POST", apiPath, query, body);
+    }
+    delete(apiPath, query = {}) {
+        return this.requestJson("DELETE", apiPath, query);
+    }
+    /** JSON request with auth headers; non-2xx responses become PingCodeError. */
+    async requestJson(method, apiPath, query, body) {
+        const url = new URL(this.profile.apiBaseUrl + apiPath);
+        for (const [k, v] of Object.entries(query)) {
+            if (v !== undefined && v !== "")
+                url.searchParams.set(k, String(v));
+        }
+        const headers = {
+            Authorization: `Bearer ${this.profile.accessToken}`,
+            Accept: "application/json",
+        };
+        const init = { method, headers };
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            init.body = JSON.stringify(body);
+        }
+        const res = await this.request(url, init);
+        const text = await res.text();
+        let data = undefined;
+        if (text) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = text;
+            }
+        }
+        if (!res.ok) {
+            const code = typeof data === "object" && data ? data.code ?? data.error_code ?? data.error : undefined;
+            const msg = typeof data === "object" && data
+                ? data.message ?? data.msg ?? data.error_description ?? JSON.stringify(data)
+                : (data || res.statusText);
+            const hint = res.status === 401
+                ? `（令牌无效或已过期，请检查 profile "${this.profile.name}" 的 accessToken / PINGCODE_ACCESS_TOKEN）`
+                : res.status === 403
+                    ? "（权限不足）"
+                    : res.status === 404
+                        ? "（资源不存在或无权访问）"
+                        : res.status === 429
+                            ? `（触发限流，已重试 ${this.maxRetries} 次）`
+                            : "";
+            throw new PingCodeError(`PingCode API 错误 [profile ${this.profile.name}]: ${method} ${url.pathname} -> HTTP ${res.status}` +
+                (code !== undefined ? `, code=${code}` : "") +
+                `: ${String(msg).slice(0, 500)}${hint}`, res.status, code);
+        }
+        return data;
+    }
+}
+export function checkAuth(client) {
+    return client.get("/v1/myself");
+}
+//# sourceMappingURL=client.js.map

package/dist/client/errors.js

@@ -0,0 +1,11 @@
+export class PingCodeError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "PingCodeError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/client/profile.js

@@ -0,0 +1,18 @@
+import { getProfiles, resolveProfile, selectProfile } from "../config/index.js";
+import { PingCodeClient } from "./client.js";
+const clients = new Map();
+/** Cached client for a named profile (or the default profile). */
+export function getClientForProfile(name) {
+    return clientFor(resolveProfile(name, getProfiles()));
+}
+/** Client for a request: explicit profile, else the profile matching the URL host, else the default. */
+export function getClientFor(opts) {
+    return clientFor(selectProfile(opts, getProfiles()));
+}
+function clientFor(profile) {
+    let c = clients.get(profile.name);
+    if (!c)
+        clients.set(profile.name, (c = new PingCodeClient(profile)));
+    return c;
+}
+//# sourceMappingURL=profile.js.map

package/dist/client/refs.js

@@ -0,0 +1,13 @@
+// Shared patterns for parsing PingCode URLs / ids (wiki, pjm, comments).
+export const LONG_ID_RE = /^[0-9a-f]{24}$/i;
+export const SCHEME_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
+export const HOST_PREFIX_RE = /^[a-z0-9-]+(\.[a-z0-9-]+)+(:\d+)?\//i;
+export const decode = (s) => {
+    try {
+        return decodeURIComponent(s);
+    }
+    catch {
+        return s;
+    }
+};
+//# sourceMappingURL=refs.js.map