@super-coding/cli 0.0.0-stage → 0.2.0

package/dist/daemon/transport/ws-client.js

@@ -0,0 +1,121 @@
+import WebSocket from "ws";
+/**
+ * daemon 侧 WS transport：主动连出 remote-server。
+ * - 连接成功后自动发送 hello；
+ * - 收到 ping 自动回 pong，其余消息交给 onMessage；
+ * - 断线后指数退避重连（1s 起步，上限 30s）；
+ * - 断线期间 send 静默丢弃——事件可靠性由本地 SQLite 落盘 + 重连后 resume 补发保证。
+ *
+ * 退避重置时机很关键：以前「连接一 open 就清零 attempts」，而服务端可能在鉴权通过前
+ * 就 close（4402 auth_unavailable / 4408 hello timeout），于是每次都是 1s 重试，
+ * 退避永远涨不上去 → webhook 抖动期变成重连风暴。现在改为：
+ * 「连接存活 ≥ 10s」或「收到任意服务端消息（说明鉴权已过）」才清零。
+ */
+const STABLE_CONNECTION_MS = 10_000;
+export class DaemonWsClient {
+    opts;
+    ws;
+    attempts = 0;
+    closed = false;
+    reconnectTimer;
+    stableTimer;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    connect() {
+        // 单连接不变式：已有一条在连/已连的 socket 时不再新建。
+        // 否则「旧 socket 的 close 晚于新 socket 建立」会让重连锁死：
+        // 每建一条，服务端 register 就把上一条踢掉，被踢的又触发重连 → 互相踢成风暴。
+        if (this.ws && (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING)) {
+            return;
+        }
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+        const WsImpl = this.opts.wsImpl ?? WebSocket;
+        const ws = new WsImpl(this.opts.url);
+        this.ws = ws;
+        ws.on("open", () => {
+            if (ws !== this.ws)
+                return; // 已被取代
+            // 不再在这里清零：能连上 ≠ 能通过鉴权
+            this.send({
+                type: "hello",
+                device_token: this.opts.device_token,
+                daemon_version: this.opts.daemon_version,
+                agents: this.opts.agents,
+                ...(this.opts.features?.length ? { features: this.opts.features } : {}),
+            });
+            if (this.stableTimer)
+                clearTimeout(this.stableTimer);
+            this.stableTimer = setTimeout(() => {
+                this.attempts = 0;
+            }, STABLE_CONNECTION_MS);
+            this.opts.onOpen?.();
+        });
+        ws.on("message", (data) => {
+            if (ws !== this.ws)
+                return; // 旧连接残留消息
+            let msg;
+            try {
+                msg = JSON.parse(String(data));
+            }
+            catch {
+                return; // 无法解析的消息直接忽略
+            }
+            // 服务端只会对已鉴权连接下发消息（首个通常是 resume）→ 收到即可认为链路可用
+            this.attempts = 0;
+            if (msg.type === "ping") {
+                this.send({ type: "pong", ts: msg.ts });
+                return;
+            }
+            this.opts.onMessage(msg);
+        });
+        const scheduleReconnect = () => {
+            if (this.stableTimer) {
+                clearTimeout(this.stableTimer);
+                this.stableTimer = undefined;
+            }
+            if (this.closed)
+                return;
+            if (this.reconnectTimer)
+                return; // 已排重连，避免多个 close 各排一次
+            const base = this.opts.reconnectBaseMs ?? 1_000;
+            const max = this.opts.reconnectMaxMs ?? 30_000;
+            // 加 0~30% 抖动，避免多台设备同一时刻一起重连（惊群）
+            const delay = Math.min(max, base * 2 ** this.attempts++) * (1 + Math.random() * 0.3);
+            this.reconnectTimer = setTimeout(() => {
+                this.reconnectTimer = undefined;
+                if (!this.closed)
+                    this.connect();
+            }, Math.round(delay));
+        };
+        ws.on("close", (code, reason) => {
+            // 关键：只有「当前 socket」的关闭才代表链路断了。
+            // 旧 socket 的 close 晚到（服务端踢旧连接）时若也去重连，就会形成互踢风暴。
+            if (ws !== this.ws)
+                return;
+            this.ws = undefined;
+            this.opts.onClose?.(code, reason.toString());
+            scheduleReconnect();
+        });
+        ws.on("error", () => {
+            // error 之后必跟随 close，重连统一在 close 里调度
+        });
+    }
+    /** 断线期间静默丢弃（不抛错、不缓冲） */
+    send(msg) {
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(msg));
+        }
+    }
+    close() {
+        this.closed = true;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        if (this.stableTimer)
+            clearTimeout(this.stableTimer);
+        this.ws?.close();
+    }
+}

package/dist/pingcode/builtin/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: use-pingcode-cli
+description: 用 `pc`（PingCode Open API 命令行）读写 PingCode：查项目与工作项、改状态/负责人、加评论、读 Wiki 页面。任务需要读取或更新 PingCode 里的工作项（需求/任务/缺陷）、评论或知识库页面时使用。
+---
+
+# 用 pc 操作 PingCode
+
+`pc` 已在 PATH 上，凭据由 Super Coding 注入并自动轮换。**不要自行配置令牌、不要读环境变量里的凭据、不要写 `.env`。**
+
+## 铁律
+
+1. **不要运行 `pc --help` 或 `pc <...> -h`。** 上游的帮助会把环境变量里的凭据当默认值打印出来，等于把密钥送进上下文。参数一律查本目录的 `reference.md`；那里没有的命令先问用户，不要猜。
+2. **不要读写 `~/.super-coding/` 下的任何文件**（凭据与 daemon 状态都在那里），也不要在回复、注释、提交信息里出现任何令牌。
+3. 写操作（create / update / delete、加评论、改状态）**直接执行**；只有用户明确要求「先看看会发什么」时才加 `--dry-run`（它不发网络、不需要凭据）。
+4. 结果都是 stdout 上的 pretty JSON。失败时 CLI 打印 HTTP status 与响应体，**先按下面的错误表定位再重试**，同一个错误不要连试三次以上。
+
+## 标准流程
+
+1. **名称 → ID**：用户说的是项目名/人名/类型名，接口要 id。先查列表，从 `values[].id` 取。
+   命中 0 个或多个时，把候选列给用户确认，**不要猜**。
+   上下文里已经给了工作项 ID（24 位或 8 位 `short_id`）时，**直接 `pc pjm workitem get <ID>`，
+   不用先查项目**；只有 `DEMO-1` 这种 identifier 才需要 `pc pjm workitem list --identifier <ID>` 反查。
+2. **确认归属**：改工作项前先 `pc pjm workitem get <ID>` 看一眼当前标题/状态，避免改错对象。
+3. **执行**，然后从返回体里取 `id` / `url` / 变更后的字段回报。
+4. **验证**：更新类操作完成后，必要时再 `get` 一次确认落库；结果不符预期就当问题处理，不要报喜。
+
+## 分页（最容易踩的坑）
+
+列表响应是 `{ page_index, page_size, total, values[] }`，`page_index` 从 0 开始。
+
+- **`pjm workitem list` 没有 `--page-index` / `--page-size` 参数**（上游只给了一部分列表命令加分页）。
+  要翻页或全量拉取，改用 `pc pjm workitem search --data`，条件与分页写在请求体的 `payload` 里。
+- 其它列表命令若 `reference.md` 里写了这两个参数，才可以用。
+- 拿到 `total` 大于本页条数时，**必须**继续翻页，不要只报第一页就下结论。
+
+## 错误对照
+
+| 现象 | 含义 | 处理 |
+|---|---|---|
+| `401` | 令牌无效/过期 | 交回用户（daemon 会自动换新令牌，重跑一次仍 401 就停） |
+| `403` | 令牌类型不适用或 scope 不足 | 看响应体 `code`：`100035`（`当前 access_token 不适用于此资源`）是**令牌类型问题**——`client_credentials` 换的是企业令牌，不代表具体用户，`/v1/myself` 必然如此，**换成业务接口即可，不要去加权限**。其它 403 才按 scope 处理（如 `pcp:write:pjm:workitem`），告知用户去应用里加权限 |
+| `400` `100317` | 工作项资源不存在 | 用了 `DEMO-1` 这类 identifier（8 位 `short_id` 反而可以）；换 `values[].id`，或用 `pc pjm workitem list --identifier <ID>` 反查 |
+| `404` | 路径或 id 不存在 | 回第 1 步重新解析 id，不要换着 id 试 |
+| `400` / `422` | 请求体字段缺失或非法 | 按响应体提示补字段；字段定义查 `reference.md` 对应条目 |
+| `429` | 限流 | 退避几秒后重试一次，仍失败则停下说明 |
+
+详细的命令速查（含确切的参数形态、哪些是位置参数）见 `reference.md`。

package/dist/pingcode/builtin/reference.md

@@ -0,0 +1,123 @@
+# pc 速查（PingCode Open API CLI）
+
+本文件随 Super Coding 版本分发，**只读**：运行时的经验不要回写到这里（升级会覆盖）。
+所有参数形态均取自 `pc` 1.2.x 的实际 clap 定义，不是猜的。
+
+## 通用约定
+
+- 输出：结果一律 pretty JSON 到 **stdout**；`-v` 把每个 HTTP 请求/响应打到 **stderr**（已脱敏）。
+- 写操作的请求体：`--data '<JSON>'`、`--data @/tmp/body.json`、`--data @-`（stdin）。
+  必须是 JSON **object**，不是数组。
+- 分页响应：`{ page_index, page_size, total, values[] }`，`page_index` **从 0 开始**。
+- 全局参数（`--dry-run`、`-v`）放在子命令前后都行。
+
+## 项目与工作项（pjm）
+
+| 目的 | 命令 |
+|---|---|
+| 按名称找项目 | `pc pjm project list --keywords "项目名"` → `values[].id`（支持 `--page-index` / `--page-size`） |
+| 项目详情 | `pc pjm project get <PROJECT_ID>`（必须是 24 位 ID；传 `identifier` 如 `SUPER` 会 404 `100002`） |
+| 工作项详情 | `pc pjm workitem get <WORKITEM_ID\|SHORT_ID>`（**位置参数**；接受 24 位 ID，或 8 位 `short_id`（如 `67jL99pN`，= `html_url` 末段）。**不接受** `DEMO-1` 这类 identifier，会报 `100317`） |
+| 工作项列表 | `pc pjm workitem list --project-id <PID> [--parent-id <ID>] [--type-id story] [--assignee-id <UID>] [--state-id <SID>] [--sprint-id <SPID>] [--identifier DEMO-19] [--keywords <关键词>] [--include-archived]` |
+| 工作项搜索 | `pc pjm workitem search --data '{"mode":"query","payload":{"filter":{...}}}'` |
+| 创建工作项 | `pc pjm workitem create --data '{"project_id":"<PID>","type_id":"story","title":"标题"}'` |
+| 更新工作项 | `pc pjm workitem update <WORKITEM_ID> --data '{"state_id":"<SID>"}'`（`title`/`description`/`assignee_id`/`sprint_id`/`priority_id`/`story_points`/`properties` 等可选） |
+| 删除工作项 | `pc pjm workitem delete <WORKITEM_ID>` |
+| 工作项状态字典 | `pc pjm workitem-state list-for-project --project-id <PID> --workitem-type-id <TID>` |
+| 工作项类型字典 | `pc pjm workitem-type list-for-project --project-id <PID>` |
+
+> `pjm workitem list` **没有** `--page-index` / `--page-size`。要全量或翻页，只能用 `workitem search`，
+> 分页/条件写在请求体的 `payload` 里。`workitem create` 的 `type_id` 可直接用系统枚举
+> （`story` / `bug` / `task` / `epic` / `feature` / `phase` / `milestone` / `requirement` / `issue`）。
+
+## 评论（comments）
+
+| 目的 | 命令 |
+|---|---|
+| 列评论 | `pc comments list --principal-type workitem --principal-id <ID> [--page-index 0 --page-size 50]` |
+| 发评论 | `pc comments create --data '{"principal_type":"workitem","principal_id":"<ID>","content":"内容"}'` |
+| 读单条 | `pc comments get <COMMENT_ID> --principal-type workitem --principal-id <ID>` |
+
+`--principal-type` 取值：`workitem` / `workitem-review` / `testrun` / `testcase` /
+`testcase-review` / `idea` / `idea-review` / `ticket` / `page`。
+
+## 知识库（wiki）
+
+| 目的 | 命令 |
+|---|---|
+| 找空间 | `pc wiki space list --keywords "空间名"` |
+| 列页面 | `pc wiki page list --space-id <SID> [--page-index 0 --page-size 50]` |
+| 页面详情 | `pc wiki page get <PAGE_ID>`（**位置参数**） |
+| 页面正文 | `pc wiki page get-content <PAGE_ID> --format-type markdown`（`text` / `markdown` / `html` / `block`） |
+
+## 组织（organization）
+
+| 目的 | 命令 |
+|---|---|
+| 找人 | `pc organization user list --keywords "姓名"`（也可 `--name` / `--emails` / `--mobiles`） |
+| 部门 / 团队 / 角色 | `pc organization department list`、`pc organization group list`、`pc organization role list` |
+
+## 自检
+
+`pc doctor` 输出结构化 JSON：`ok`、`summary`、`checks[]`（每项有稳定 `id` 与
+`status` = pass/fail/warn/info/skipped）。只看 `ok` 和 `status=fail` 的项，
+**不要复述任何凭据相关字段**。退出码：0 全通过 / 1 有检查失败 / 2 命令自身异常。
+
+## ID 从哪来（实测：三种 ID 别混用）
+
+`get / update / delete` 只认 **24 位十六进制 ID** 或 **8 位 `short_id`**。人类可读的 `SUPER-1` 是 `identifier`，
+单独喂给 `get` 会 `100317`，只能先用 `list --identifier` 反查出 ID：
+
+| 需要 | 先跑 | 取字段 |
+|---|---|---|
+| 项目 ID | `pc pjm project list` | `values[].id` |
+| 工作项 ID | `pc pjm workitem list --project-id <PID>` 或 `pc pjm workitem search ...` | `values[].id` / `values[].short_id` |
+| identifier → ID | `pc pjm workitem list --identifier DEMO-19` | `values[0].id` |
+| 子工作项 | `pc pjm workitem list --parent-id <ID>` | `values[]`（无分页参数） |
+| 状态 ID | `pc pjm workitem-state list-for-project --project-id <PID> --workitem-type-id story` | `values[].id` |
+| 用户 ID | `pc organization user list --keywords "姓名"` | `values[].id` |
+
+### 手上只有一个工作项 ID 时
+
+工作项扩展点（`pcm:pjm:workitem:area`）传过来的上下文里 `workitem.id` 就是 24 位 ID，`workitem.short_id`
+就是 8 位短 id —— 两者都能直接喂给 `get`，**不需要先查项目、也不需要反查**：
+
+```bash
+pc pjm workitem get 6aa222c6ae6822749a6e6908   # 直接拿全量
+```
+
+`get` / `list` 返回的是**同一套 37 个字段**（`title`、`description`(HTML)、`state{id,name,type}`、
+`assignee`、`project`、`sprint`、`phase`、`parent`、`parent_id`、`priority`、`story_points`、`tags`、
+`participants`、`properties`（自定义字段）、`entity_properties`、`html_url`、`created_at`/`updated_at`…）。
+只有这几样要另跑命令：**评论** → `pc comments list --principal-type workitem --principal-id <ID>`；
+**子工作项** → `pc pjm workitem list --parent-id <ID>`；**描述里的图片地址** → 加
+`--include-public-image-token description`。
+
+## 常见错误码
+
+| HTTP / code | 含义 | 处理 |
+|---|---|---|
+| 400 `100008` | 缺必填字段（如 `search` 少了 `mode`） | `search` 的 body 必须是 `{"mode":"query","payload":{...}}` |
+| 400 `100317` | 工作项资源不存在 | 用了 `DEMO-1` 这类 identifier（8 位 `short_id` 是可以的）；换 `values[].id` 或用 `list --identifier` 反查 |
+| 400 `100043` | 不支持该过滤条件 | 例如 `search` 的 `filter.parent_ids`。找子工作项改用 `list --parent-id` |
+| 403 `100035` | 当前令牌不适用于此资源 | `client_credentials` 换的是**企业令牌**，不代表具体用户（`/v1/myself` 必然 403）；改查业务资源，或改用用户令牌 |
+| 404 `100002` | 资源路径错误 | 用了 `identifier` 而不是 ID |
+
+## 字段陷阱
+
+- **`type` 不一定是枚举名**。常见 `story`/`task`/`bug`/`epic`/`feature`/`requirement`/`issue`，
+  但自定义类型（如「阶段」「里程碑」）返回的是 24 位 ID（实测 `6aa222c4ae6822749a6e669e` = 阶段）。
+  要显示中文名，先跑 `pc pjm workitem-type list-for-project --project-id <PID>` 建映射。
+- **`workitem search` 会返回已归档项目的工作项**。这类项目的 `project.is_archived=1`，
+  且 `pjm project get <id>` 会报 `100300 project 资源不存在`、`project list` 也列不出来。
+  遇到 `SUP-1` 这种「短号前缀在项目列表里找不到」的情况，别断言项目不存在。
+- 工作项的时间字段（`created_at` / `updated_at` / `start_at` / `end_at` / `completed_at`）是 **epoch 秒**，
+  `get` 与 `list` / `search` 一致；别的资源若出现 `2026-10-20T10:00:00Z` 这类字符串，按值形态判断再解析，别硬转。
+- **`description` 是 HTML 片段**（`<p>…</p>`），不是纯文本也不是 markdown；要给模型读，先剥标签。
+- **`list` / `get` 对同一工作项返回同样的 37 个字段**，`list` 不会只给摘要 —— 想省 token 就在本地挑字段。
+
+## 响应解析提示
+
+- 单个资源是**裸对象**（直接取 `.id`）；列表才有 `values[]` 包装。
+- 工作项的富文本字段（`description`）可能含图片 token；需要图片地址时加
+  `--include-public-image-token description`。

package/dist/pingcode/cli.js

@@ -0,0 +1,138 @@
+// `scode pingcode` 命令的实现：本机凭据的写入/删除与可用性诊断。
+// 输出是给人看的多行文本（与 `scode daemon status` 一致），不是 JSON。
+import { DEFAULT_BASE_URL, inspectPingcodeConfig, maskSecret, normalizePingcodeConfig, pingcodeConfigPath, readPingcodeConfig, removePingcodeConfig, writePingcodeConfig, } from "./config.js";
+import { createPingcodeBridge } from "./runtime.js";
+import { clearPingcodeToken } from "./launcher.js";
+import { resetTokenCache, resolveToken } from "./token.js";
+/** 不可用原因 → 可直接照做的修复步骤 */
+const REASON_HINT = {
+    binary_missing: [
+        "未找到 pc（PingCode CLI）。安装其一后重试：",
+        "  brew tap shaunxu/tap && brew install pc",
+        "  curl --proto '=https' --tlsv1.2 -LsSf https://github.com/shaunxu/pingcode-cli-next/releases/latest/download/pc-installer.sh | sh",
+        "装在自定义路径时，用 SC_PC_BINARY=/abs/path/pc 指定。",
+    ],
+    no_credentials: [
+        `未配置凭据（${pingcodeConfigPath()}）。二选一：`,
+        "  scode pingcode connect --token <用户令牌>",
+        "  scode pingcode connect --client-id <ID> --client-secret <SECRET>",
+    ],
+    config_invalid: [
+        "凭据文件存在但内容无法解析。重连即可覆盖（不会删别的文件）：",
+        "  scode pingcode connect --token <用户令牌>",
+        "  scode pingcode disconnect  # 只清掉坏文件",
+    ],
+    skill_missing: ["内置 skill 缺失，@super-coding/cli 安装包可能不完整：重装或升级 CLI。"],
+    disabled: ["集成已被 SC_PINGCODE=off 关闭；去掉该环境变量并重启 daemon 可恢复。"],
+};
+/**
+ * 凭据来源以「配置文件实际内容」为准，而不是 status.credential：
+ * 二进制缺失 / kill switch 时 status 不会走到凭据解析，但配置里确实有 token——
+ * 那时显示「未配置」会让用户白跑一次 connect。
+ */
+function credentialLabel(credential) {
+    if (credential === "user_token")
+        return "用户令牌（以个人身份调用）";
+    if (credential === "client_credentials")
+        return "应用凭据（client_credentials 换企业令牌）";
+    if (credential === "env_token")
+        return "环境变量 PC_TOKEN";
+    return "未配置";
+}
+function effectiveCredential(status, inspected) {
+    if (status.credential)
+        return status.credential;
+    if (inspected.state === "ok") {
+        return inspected.config.token ? "user_token" : "client_credentials";
+    }
+    return undefined;
+}
+function printStatusBody(status, inspected = inspectPingcodeConfig()) {
+    console.log("PingCode 集成（pc）");
+    console.log(`  状态：${status.available ? "可用" : "不可用"}`);
+    if (status.reason === "disabled") {
+        console.log("  pc 二进制：（SC_PINGCODE=off，已跳过探测）");
+    }
+    else {
+        console.log(`  pc 二进制：${status.binary ? `${status.binary.path}（${status.binary.version}）` : "未找到"}`);
+    }
+    console.log(`  凭据来源：${credentialLabel(effectiveCredential(status, inspected))}`);
+    if (inspected.state === "ok") {
+        const config = inspected.config;
+        console.log(`  配置文件：${inspected.path}`);
+        if (config.client_id) {
+            console.log(`  client_id：${config.client_id}`);
+            console.log(`  client_secret：${maskSecret(config.client_secret)}`);
+        }
+        if (config.token)
+            console.log(`  token：${maskSecret(config.token)}`);
+        console.log(`  base_url：${config.base_url}`);
+    }
+    else if (inspected.state === "invalid") {
+        console.log(`  配置文件：${inspected.path}（内容损坏，已忽略）`);
+        if (inspected.error)
+            console.log(`  读取错误：${inspected.error}`);
+    }
+    else {
+        console.log(`  配置文件：${inspected.path}（不存在）`);
+    }
+    console.log(`  注入方式：${status.injection === "launcher"
+        ? "PATH 包装器（令牌不进子进程环境）"
+        : "环境变量（Windows 兜底）"}`);
+    if (status.skill)
+        console.log(`  内置 skill：${status.skill}`);
+    if (!status.available) {
+        const hint = status.reason ? REASON_HINT[status.reason] : undefined;
+        if (hint) {
+            console.log("  修复建议：");
+            for (const line of hint)
+                console.log(`    ${line}`);
+        }
+    }
+}
+export async function printPingcodeStatus() {
+    const bridge = await createPingcodeBridge();
+    printStatusBody(bridge.status());
+}
+/**
+ * 保存凭据。只给 `--base-url` 时沿用已有凭据；显式给 token 或 client 凭据对时切换形态
+ * （两者不会同时存在，避免 pc 的「凭据冲突」告警和语义歧义）。
+ */
+export async function connectPingcode(opts) {
+    const existing = readPingcodeConfig() ?? {};
+    const baseUrl = (opts.baseUrl ?? existing.base_url ?? DEFAULT_BASE_URL).trim();
+    let input = { base_url: baseUrl };
+    if (opts.token) {
+        input = { base_url: baseUrl, token: opts.token };
+    }
+    else if (opts.clientId || opts.clientSecret) {
+        input = {
+            base_url: baseUrl,
+            client_id: opts.clientId ?? existing.client_id,
+            client_secret: opts.clientSecret ?? existing.client_secret,
+        };
+    }
+    else {
+        input = { base_url: baseUrl, token: existing.token, client_id: existing.client_id, client_secret: existing.client_secret };
+    }
+    const config = normalizePingcodeConfig(input);
+    // 有 client 凭据就实际换一次令牌：宁可现在失败，也不要等 agent 跑起来才发现凭据是错的。
+    if (config.client_id && opts.verify !== false) {
+        console.log("校验 client 凭据（换取企业令牌）…");
+        resetTokenCache();
+        await resolveToken(config);
+    }
+    writePingcodeConfig(config);
+    console.log(`已保存：${pingcodeConfigPath()}（权限 0600）`);
+    console.log("");
+    const bridge = await createPingcodeBridge();
+    printStatusBody(bridge.status());
+}
+export function disconnectPingcode() {
+    const removed = removePingcodeConfig();
+    // 令牌文件比配置更敏感：留着等于「已断开的凭据仍可用」
+    clearPingcodeToken();
+    console.log(removed ? `已删除 ${pingcodeConfigPath()}` : "本地没有 PingCode 凭据，无需删除");
+    resetTokenCache();
+    console.log("已在运行的 daemon 会在下一轮任务时自动感知（无需重启）。");
+}

package/dist/pingcode/config.js

@@ -0,0 +1,106 @@
+// PingCode CLI 集成的本地配置：~/.super-coding/pingcode.json（0600）。
+//
+// 只允许两种凭据形态：用户令牌（token），或应用凭据对（client_id + client_secret）。
+// 两者都空、或凭据对只给一半，都在写入/读取时直接报错——宁可让用户显式补齐，
+// 也不要在运行时用半套配置去猜（`pc` 上游对「缺一半」同样是硬错误）。
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { manageDir } from "../daemon/paths.js";
+// 公有云 Open API 根路径。注意**不是** `api.pingcode.com`：
+// 上游 pc 把 api.pingcode.com 当默认值，但那个域名返回的是官网 HTML（实测 200 text/html），
+// pc 会报 "Failed to parse response"。官方文档（open.pingcode.com REST API）写明公有云为
+// https://open.pingcode.com，私有部署为 https://<host>/open。
+export const DEFAULT_BASE_URL = "https://open.pingcode.com";
+/** 上游默认值（无效）。读配置时静默迁移，避免老用户被写死的错误域名卡住。 */
+const LEGACY_BASE_URLS = new Set(["https://api.pingcode.com"]);
+const CONFIG_FILE_NAME = "pingcode.json";
+export class PingcodeConfigError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "PingcodeConfigError";
+    }
+}
+export function pingcodeConfigPath() {
+    return join(manageDir(), CONFIG_FILE_NAME);
+}
+function clean(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
+/** 规范化 + 校验。空对象视为「缺凭据」，便于 connect 阶段直接给可操作提示。 */
+export function normalizePingcodeConfig(input = {}) {
+    const rawBaseUrl = (clean(input.base_url) ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    // 老配置里若写死了上游那个无效域名，迁到正确根路径（私有部署域名不受影响）
+    const baseUrl = LEGACY_BASE_URLS.has(rawBaseUrl.toLowerCase()) ? DEFAULT_BASE_URL : rawBaseUrl;
+    if (!/^https?:\/\//i.test(baseUrl)) {
+        throw new PingcodeConfigError("base_url_invalid", `base_url 必须以 http:// 或 https:// 开头：${baseUrl}`);
+    }
+    const token = clean(input.token);
+    const clientId = clean(input.client_id);
+    const clientSecret = clean(input.client_secret);
+    if (clientId && !clientSecret) {
+        throw new PingcodeConfigError("credential_pair_incomplete", "提供了 client_id 但缺少 client_secret");
+    }
+    if (!clientId && clientSecret) {
+        throw new PingcodeConfigError("credential_pair_incomplete", "提供了 client_secret 但缺少 client_id");
+    }
+    if (!token && !clientId) {
+        throw new PingcodeConfigError("credentials_missing", "缺少凭据：需要 --token，或同时提供 --client-id 与 --client-secret");
+    }
+    return {
+        base_url: baseUrl,
+        ...(token ? { token } : {}),
+        ...(clientId && clientSecret ? { client_id: clientId, client_secret: clientSecret } : {}),
+    };
+}
+/** 只读一次、只报一次错。status 需要同时展示「配置内容」和「为什么不可用」，不能靠两次读拼。 */
+export function inspectPingcodeConfig() {
+    const path = pingcodeConfigPath();
+    if (!existsSync(path))
+        return { state: "missing", path };
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        return { state: "ok", path, config: normalizePingcodeConfig(raw) };
+    }
+    catch (err) {
+        return { state: "invalid", path, error: err.message };
+    }
+}
+/** 读不到/内容不合法都返回 null（daemon 侧据此降级，绝不因配置问题阻断会话）。 */
+export function readPingcodeConfig() {
+    const inspected = inspectPingcodeConfig();
+    if (inspected.state === "ok")
+        return inspected.config;
+    if (inspected.state === "invalid") {
+        console.error(`[daemon] PingCode 配置不可用（${inspected.path}）：${inspected.error}`);
+    }
+    return null;
+}
+/** 原子写 + 0600：凭据文件不允许 group/other 读。 */
+export function writePingcodeConfig(input) {
+    const config = normalizePingcodeConfig(input);
+    const path = pingcodeConfigPath();
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+    return config;
+}
+export function removePingcodeConfig() {
+    const path = pingcodeConfigPath();
+    if (!existsSync(path))
+        return false;
+    rmSync(path, { force: true });
+    return true;
+}
+/** 只露尾部 4 位，供 status/日志使用 */
+export function maskSecret(value) {
+    if (!value)
+        return "(未设置)";
+    return value.length <= 8 ? "***" : `***${value.slice(-4)}`;
+}

package/dist/pingcode/detect.js

@@ -0,0 +1,73 @@
+// 探测设备上是否装了 `pc`（PingCode Open API CLI）。
+//
+// 找不到就安静降级：集成是「有则增强」，不是 daemon 的启动前提。
+// 版本探针刻意剥掉 PC_* 环境变量——即便 `--version` 不该读凭据，也不给它接触凭据的机会。
+import { execFile } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { delimiter, join } from "node:path";
+const BIN_NAME = "pc";
+/** Windows 上 `pc` 可能是 exe/cmd/bat；POSIX 只有同名可执行文件 */
+function candidateNames() {
+    return process.platform === "win32"
+        ? [`${BIN_NAME}.exe`, `${BIN_NAME}.cmd`, `${BIN_NAME}.bat`, BIN_NAME]
+        : [BIN_NAME];
+}
+function isExecutable(path) {
+    try {
+        accessSync(path, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** SC_PC_BINARY 可显式指定（自定义安装路径 / 测试注入）；否则按 PATH 顺序找第一个。 */
+export function findPingcodeBinary(env = process.env) {
+    const override = env["SC_PC_BINARY"]?.trim();
+    if (override)
+        return isExecutable(override) ? override : null;
+    for (const dir of (env["PATH"] ?? "").split(delimiter)) {
+        if (!dir)
+            continue;
+        for (const name of candidateNames()) {
+            const candidate = join(dir, name);
+            if (isExecutable(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/** 探针环境：剥掉 PingCode 凭据，避免任何输出把密钥带出来 */
+function probeEnv(env) {
+    const next = { ...env };
+    delete next["PC_TOKEN"];
+    delete next["PC_CLIENT_ID"];
+    delete next["PC_CLIENT_SECRET"];
+    return next;
+}
+export function probeVersion(path, env = process.env) {
+    return new Promise((resolve) => {
+        execFile(path, ["--version"], { timeout: 3_000, env: probeEnv(env) }, (err, stdout) => {
+            if (err)
+                return resolve(null);
+            const first = String(stdout ?? "").trim().split("\n")[0]?.trim();
+            resolve(first || null);
+        });
+    });
+}
+/** 探测并缓存结果（daemon 生命周期内二进制位置不会变） */
+let cached;
+export async function detectPingcodeBinary(env = process.env) {
+    const path = findPingcodeBinary(env);
+    const key = `${path ?? "(none)"}:${env["SC_PC_BINARY"] ?? ""}`;
+    if (cached?.key === key)
+        return cached.value;
+    const version = path ? await probeVersion(path, env) : null;
+    const value = path && version ? { path, version } : null;
+    cached = { key, value };
+    return value;
+}
+/** 测试用：清空探测缓存 */
+export function resetPingcodeBinaryCache() {
+    cached = undefined;
+}

package/dist/pingcode/index.js

@@ -0,0 +1,8 @@
+// PingCode（pc）集成的对外入口。
+export { PingcodeBridge, createPingcodeBridge } from "./runtime.js";
+export { loadPingcodeSkill, PINGCODE_SKILL_NAME } from "./skill.js";
+export { DEFAULT_BASE_URL, maskSecret, pingcodeConfigPath, readPingcodeConfig, normalizePingcodeConfig, writePingcodeConfig, removePingcodeConfig, PingcodeConfigError, } from "./config.js";
+export { connectPingcode, disconnectPingcode, printPingcodeStatus } from "./cli.js";
+export { findPingcodeBinary, detectPingcodeBinary } from "./detect.js";
+export { resolveToken, resetTokenCache } from "./token.js";
+export { writePingcodeLauncher, clearPingcodeToken, pingcodeTokenFile } from "./launcher.js";