@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/skills/distill/upstream-fetcher.js

@@ -0,0 +1,202 @@
+/**
+ * upstream-fetcher.ts
+ *
+ * Clones / refreshes the 4 upstream skill repos into
+ * `~/.claude-forge/skills-cache/<upstream>/`. Uses `git` via child_process
+ * with a hard timeout and depth=1 to keep size bounded.
+ *
+ * Spec ref: 1846-skills-distilled-from-upstreams-spec.md Phase A.
+ *
+ * NOT exercised in unit tests (we mock the fetcher). Real runs hit network.
+ */
+import { execFile } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { homedir } from 'node:os';
+import { logger } from '../../core/utils/logger.js';
+const execFileAsync = promisify(execFile);
+/**
+ * Default upstream registry. Q1 + Q2 defaults applied:
+ *  - obra/superpowers, anthropics/skills, affaan-m/ECC active
+ *  - karpathy skipped (license unclear; local karpathy-guidelines exists)
+ */
+export const DEFAULT_UPSTREAMS = [
+    {
+        id: 'obra-superpowers',
+        url: 'https://github.com/obra/superpowers.git',
+        license: 'MIT',
+        sparsePaths: ['skills'],
+    },
+    {
+        id: 'anthropics-skills',
+        url: 'https://github.com/anthropics/skills.git',
+        license: 'Apache-2.0',
+        sparsePaths: ['skills'],
+    },
+    {
+        id: 'affaan-m-ecc',
+        url: 'https://github.com/affaan-m/ECC.git',
+        license: 'MIT',
+    },
+    {
+        id: 'multica-karpathy',
+        url: 'https://github.com/multica-ai/andrej-karpathy-skills.git',
+        license: 'unclear',
+        skip: true,
+    },
+];
+/** Default cache root. Tests override via opts.cacheRoot. */
+export function defaultCacheRoot() {
+    return path.join(homedir(), '.claude-forge', 'skills-cache');
+}
+const DEFAULT_TIMEOUT = 120_000; // 2 min cap per repo
+/** Stat helper — false on ENOENT. */
+async function pathExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve current HEAD commit in a cached repo. Returns 'unknown' on failure
+ * so callers can still log/proceed without crashing.
+ */
+async function resolveHead(repoPath, timeoutMs) {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], {
+            cwd: repoPath,
+            timeout: timeoutMs,
+        });
+        return stdout.trim();
+    }
+    catch (err) {
+        logger.warn(`[upstream-fetcher] rev-parse failed for ${repoPath}: ${err}`);
+        return 'unknown';
+    }
+}
+/**
+ * Fetch one upstream into `cacheRoot/<id>/`. Idempotent — re-uses existing
+ * clone unless `force=true`.
+ */
+export async function fetchUpstream(upstream, opts) {
+    if (upstream.skip) {
+        return {
+            upstream,
+            status: 'skipped',
+            path: '',
+        };
+    }
+    const repoPath = path.join(opts.cacheRoot, upstream.id);
+    const exists = await pathExists(repoPath);
+    try {
+        if (exists && !opts.force) {
+            const commit = await resolveHead(repoPath, opts.timeoutMs);
+            return { upstream, status: 'cached', path: repoPath, commit };
+        }
+        if (exists && opts.force) {
+            // Pull latest. depth=1 prior clone => fetch --depth=1 first.
+            await execFileAsync('git', ['fetch', '--depth=1', 'origin'], {
+                cwd: repoPath,
+                timeout: opts.timeoutMs,
+            });
+            await execFileAsync('git', ['reset', '--hard', 'origin/HEAD'], {
+                cwd: repoPath,
+                timeout: opts.timeoutMs,
+            });
+            const commit = await resolveHead(repoPath, opts.timeoutMs);
+            return { upstream, status: 'updated', path: repoPath, commit };
+        }
+        // Fresh clone — depth=1, no submodules. Sparse checkout if specified.
+        await fs.mkdir(opts.cacheRoot, { recursive: true });
+        if (upstream.sparsePaths && upstream.sparsePaths.length > 0) {
+            // git clone --depth=1 --filter=blob:none --sparse
+            await execFileAsync('git', [
+                'clone',
+                '--depth=1',
+                '--filter=blob:none',
+                '--sparse',
+                upstream.url,
+                repoPath,
+            ], { timeout: opts.timeoutMs });
+            await execFileAsync('git', ['sparse-checkout', 'set', ...upstream.sparsePaths], { cwd: repoPath, timeout: opts.timeoutMs });
+        }
+        else {
+            await execFileAsync('git', ['clone', '--depth=1', upstream.url, repoPath], { timeout: opts.timeoutMs });
+        }
+        const commit = await resolveHead(repoPath, opts.timeoutMs);
+        return { upstream, status: 'cloned', path: repoPath, commit };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.error(`[upstream-fetcher] ${upstream.id} failed: ${msg}`);
+        return {
+            upstream,
+            status: 'error',
+            path: repoPath,
+            error: msg,
+        };
+    }
+}
+/** Fetch all upstreams. Returns one FetchResult per upstream. */
+export async function fetchAllUpstreams(opts = {}) {
+    const cacheRoot = opts.cacheRoot ?? defaultCacheRoot();
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT;
+    const force = opts.force ?? false;
+    const upstreams = opts.upstreams ?? DEFAULT_UPSTREAMS;
+    await fs.mkdir(cacheRoot, { recursive: true });
+    const results = [];
+    for (const u of upstreams) {
+        const r = await fetchUpstream(u, { cacheRoot, timeoutMs, force });
+        results.push(r);
+        logger.info(`[upstream-fetcher] ${u.id}: ${r.status}` + (r.commit ? ` @${r.commit.slice(0, 8)}` : ''));
+    }
+    return results;
+}
+/**
+ * Enumerate candidate skill files inside a cached upstream. Returns absolute
+ * file paths that look like skill markdown (SKILL.md, *.md inside `skills/`).
+ *
+ * Heuristic chosen because the 4 upstreams have inconsistent layouts:
+ *  - obra/superpowers: `skills/<name>/SKILL.md`
+ *  - anthropics/skills: `<name>/SKILL.md`
+ *  - affaan-m/ECC: flat `*.md`
+ */
+export async function listUpstreamSkills(repoPath) {
+    const out = [];
+    await walkMarkdown(repoPath, repoPath, out);
+    // Filter: prefer SKILL.md when present; otherwise *.md anywhere except
+    // README / CHANGELOG / LICENSE.
+    const skillMd = out.filter(p => path.basename(p).toUpperCase() === 'SKILL.MD');
+    if (skillMd.length > 0)
+        return skillMd;
+    return out.filter(p => {
+        const base = path.basename(p).toUpperCase();
+        return !['README.MD', 'CHANGELOG.MD', 'LICENSE.MD', 'CONTRIBUTING.MD'].includes(base);
+    });
+}
+async function walkMarkdown(root, dir, out) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        // Skip .git, node_modules, etc.
+        if (e.name.startsWith('.') || e.name === 'node_modules')
+            continue;
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) {
+            await walkMarkdown(root, full, out);
+        }
+        else if (e.isFile() && e.name.toLowerCase().endsWith('.md')) {
+            out.push(full);
+        }
+    }
+}
+//# sourceMappingURL=upstream-fetcher.js.map

package/dist/skills/distill/upstream-fetcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream-fetcher.js","sourceRoot":"","sources":["../../../src/skills/distill/upstream-fetcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAEpD,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAgB1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAA4B;IACxD;QACE,EAAE,EAAE,kBAAkB;QACtB,GAAG,EAAE,yCAAyC;QAC9C,OAAO,EAAE,KAAK;QACd,WAAW,EAAE,CAAC,QAAQ,CAAC;KACxB;IACD;QACE,EAAE,EAAE,mBAAmB;QACvB,GAAG,EAAE,0CAA0C;QAC/C,OAAO,EAAE,YAAY;QACrB,WAAW,EAAE,CAAC,QAAQ,CAAC;KACxB;IACD;QACE,EAAE,EAAE,cAAc;QAClB,GAAG,EAAE,qCAAqC;QAC1C,OAAO,EAAE,KAAK;KACf;IACD;QACE,EAAE,EAAE,kBAAkB;QACtB,GAAG,EAAE,0DAA0D;QAC/D,OAAO,EAAE,SAAS;QAClB,IAAI,EAAE,IAAI;KACX;CACF,CAAC;AAEF,6DAA6D;AAC7D,MAAM,UAAU,gBAAgB;IAC9B,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,eAAe,EAAE,cAAc,CAAC,CAAC;AAC/D,CAAC;AAqBD,MAAM,eAAe,GAAG,OAAO,CAAC,CAAC,qBAAqB;AAEtD,qCAAqC;AACrC,KAAK,UAAU,UAAU,CAAC,CAAS;IACjC,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,WAAW,CAAC,QAAgB,EAAE,SAAiB;IAC5D,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE;YACnE,GAAG,EAAE,QAAQ;YACb,OAAO,EAAE,SAAS;SACnB,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CAAC,2CAA2C,QAAQ,KAAK,GAAG,EAAE,CAAC,CAAC;QAC3E,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAAkB,EAClB,IAA8D;IAE9D,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;QAClB,OAAO;YACL,QAAQ;YACR,MAAM,EAAE,SAAS;YACjB,IAAI,EAAE,EAAE;SACT,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,CAAC;IAE1C,IAAI,CAAC;QACH,IAAI,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YAC1B,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;YAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAChE,CAAC;QAED,IAAI,MAAM,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACzB,6DAA6D;YAC7D,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE;gBAC3D,GAAG,EAAE,QAAQ;gBACb,OAAO,EAAE,IAAI,CAAC,SAAS;aACxB,CAAC,CAAC;YACH,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,aAAa,CAAC,EAAE;gBAC7D,GAAG,EAAE,QAAQ;gBACb,OAAO,EAAE,IAAI,CAAC,SAAS;aACxB,CAAC,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;YAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QACjE,CAAC;QAED,sEAAsE;QACtE,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAEpD,IAAI,QAAQ,CAAC,WAAW,IAAI,QAAQ,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5D,kDAAkD;YAClD,MAAM,aAAa,CACjB,KAAK,EACL;gBACE,OAAO;gBACP,WAAW;gBACX,oBAAoB;gBACpB,UAAU;gBACV,QAAQ,CAAC,GAAG;gBACZ,QAAQ;aACT,EACD,EAAE,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,CAC5B,CAAC;YACF,MAAM,aAAa,CACjB,KAAK,EACL,CAAC,iBAAiB,EAAE,KAAK,EAAE,GAAG,QAAQ,CAAC,WAAW,CAAC,EACnD,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,CAC3C,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,aAAa,CACjB,KAAK,EACL,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,EAC9C,EAAE,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,CAC5B,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAChE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,MAAM,CAAC,KAAK,CAAC,sBAAsB,QAAQ,CAAC,EAAE,YAAY,GAAG,EAAE,CAAC,CAAC;QACjE,OAAO;YACL,QAAQ;YACR,MAAM,EAAE,OAAO;YACf,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,GAAG;SACX,CAAC;IACJ,CAAC;AACH,CAAC;AAED,iEAAiE;AACjE,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAqB,EAAE;IAC7D,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,gBAAgB,EAAE,CAAC;IACvD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,eAAe,CAAC;IACpD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC;IAClC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,iBAAiB,CAAC;IAEtD,MAAM,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE/C,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,MAAM,CAAC,GAAG,MAAM,aAAa,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;QAClE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAChB,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACzG,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,QAAgB;IACvD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC5C,uEAAuE;IACvE,gCAAgC;IAChC,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,UAAU,CAAC,CAAC;IAC/E,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IACvC,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;QACpB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QAC5C,OAAO,CAAC,CAAC,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,iBAAiB,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACxF,CAAC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,IAAY,EAAE,GAAW,EAAE,GAAa;IAClE,IAAI,OAAmC,CAAC;IACxC,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,gCAAgC;QAChC,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,cAAc;YAAE,SAAS;QAClE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;YACpB,MAAM,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QACtC,CAAC;aAAM,IAAI,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9D,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/skills/distilled/distilled-api-design.md

@@ -0,0 +1,495 @@
+---
+name: distilled-api-design
+version: 0.1.0-distilled
+description: 'Distilled IT-universal skill: api-design (score 4.5/5)'
+keywords:
+  - api
+  - design
+  - api design
+  - api 设计
+  - restful
+  - openapi
+  - 接口设计
+  - rest api
+  - web api
+  - http api
+  - endpoint
+rubric_version: 2
+distilled_from:
+  - upstream: https://github.com/winspan/claude-forge.git
+    license: MIT
+    commit: 7d96b86c
+    paths:
+      - official/official-api-design.md
+distilled_at: '2026-05-27T01:54:02.489Z'
+distilled_by: claude-sonnet-4-6
+it_universal_score: 4.5
+it_universal_dims:
+  d1: 1
+  d2: 1
+  d3: 1
+  d4: 0.5
+  d5: 1
+it_universal_rationale: REST/openapi principles, lang-agnostic; D4 partial.
+---
+
+## 触发条件
+
+- 设计新的 HTTP API、gRPC 服务或内部模块接口
+- 现有 API 需要版本升级或重构
+- 团队需要统一的接口设计规范
+- 发现接口调用方式不一致或难以理解
+
+## 核心原则
+
+1. **契约先行** — 先定义接口规格（OpenAPI/Protobuf/IDL），再实现，避免实现驱动设计
+2. **资源导向** — 围绕资源（名词）而非操作（动词）建模，操作通过标准方法表达
+3. **幂等性保证** — 更新和删除操作必须幂等，确保重试安全
+4. **版本隔离** — 破坏性变更必须升版本，保护现有调用方
+5. **一致性优先** — 错误格式、分页、认证方式在整个系统内保持统一
+
+## 工作流
+
+1. **识别资源和操作** — 列出核心资源（如 users、orders），明确需要的操作（创建、查询、更新、删除）
+2. **编写接口规格** — 使用 OpenAPI（REST）、Protobuf（gRPC）或等效 IDL 定义完整契约
+3. **Mock 验证** — 用 mock 服务器或桩代码让调用方试用，收集反馈
+4. **确定版本策略** — 新 API 从 v1 开始，破坏性变更升版本号
+5. **实现接口** — 按规格实现，确保幂等性和错误处理
+6. **性能测试** — 验证 P99 响应时间和超时配置
+7. **文档发布** — 生成可交互文档（Swagger UI / gRPC reflection）
+8. **监控上线** — 记录错误率、延迟、调用量
+
+## 反模式
+
+- **动词式 URL** — `/getUser`、`/createOrder` 违反 REST 原则，应用 `GET /users/{id}`、`POST /orders`
+- **URL 中传敏感数据** — 密码、token 不应出现在 query string，必须用 body 或 header
+- **不一致的错误格式** — 不同端点返回不同错误结构，调用方无法统一处理
+- **无版本管理** — 直接修改现有接口导致调用方崩溃
+- **忽略幂等性** — PUT/DELETE 不幂等导致重试产生副作用
+
+## 验证标准
+
+- [ ] 接口规格文件（OpenAPI/Protobuf）已编写并通过 lint
+- [ ] URL 使用名词复数，操作通过 HTTP 方法或 RPC 方法名表达
+- [ ] 错误响应格式统一（如 `{ code, message, data }`）
+- [ ] 分页接口返回 `total` 或 `next_token`
+- [ ] PUT/PATCH/DELETE 操作已验证幂等性
+- [ ] 认证统一使用 Authorization header 或等效机制
+- [ ] 版本号在 URL 路径（如 `/v1/`）或 header 中明确标识
+- [ ] P99 响应时间 < 200ms，超时配置统一（如 30s）
+- [ ] 可交互文档已生成并可访问
+
+## 适用范围
+
+- **HTTP API 层** — RESTful 服务、GraphQL 端点
+- **RPC 服务层** — gRPC、Thrift、内部微服务通信
+- **CLI 工具** — 命令行工具的子命令和参数设计
+- **SDK/客户端库** — 对外暴露的编程接口
+- **内部模块接口** — 跨模块调用的函数签名和数据契约
+
+## 上游对照
+
+本技能整合自单一上游的 api-design 规范（来源见 frontmatter），已泛化为跨语言、跨协议的通用 API 设计指南。
+
+## 示例（伪代码）
+
+### 场景：设计用户管理 API
+
+#### 步骤 1：定义资源和操作
+
+```
+资源：User
+操作：
+  - 创建用户
+  - 查询用户列表
+  - 查询单个用户
+  - 更新用户
+  - 删除用户
+```
+
+#### 步骤 2：编写 OpenAPI 规格（REST 示例）
+
+```yaml
+openapi: 3.0.0
+info:
+  title: User API
+  version: 1.0.0
+paths:
+  /v1/users:
+    get:
+      summary: List users
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+        - name: size
+          in: query
+          schema:
+            type: integer
+            default: 20
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/User'
+                  total:
+                    type: integer
+    post:
+      summary: Create user
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateUserRequest'
+      responses:
+        '201':
+          description: Created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        '400':
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/users/{id}:
+    get:
+      summary: Get user by ID
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        '404':
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+    put:
+      summary: Update user (idempotent)
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateUserRequest'
+      responses:
+        '200':
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+    delete:
+      summary: Delete user (idempotent)
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '204':
+          description: Deleted
+        '404':
+          description: Not found (still returns 204 for idempotency)
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        email:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+    CreateUserRequest:
+      type: object
+      required:
+        - name
+        - email
+      properties:
+        name:
+          type: string
+        email:
+          type: string
+        password:
+          type: string
+          format: password
+    UpdateUserRequest:
+      type: object
+      properties:
+        name:
+          type: string
+        email:
+          type: string
+    Error:
+      type: object
+      properties:
+        code:
+          type: string
+        message:
+          type: string
+        data:
+          type: object
+```
+
+#### 步骤 3：Mock 验证（伪代码）
+
+```javascript
+// 使用 mock 服务器（如 Prism、WireMock）
+mock_server.start(openapi_spec)
+
+// 调用方测试
+response = http.get("/v1/users?page=1&size=10")
+assert response.status == 200
+assert response.body.total >= 0
+assert response.body.data.length <= 10
+```
+
+#### 步骤 4：实现接口（多语言示例）
+
+**Node.js (Express)**
+
+```javascript
+app.get('/v1/users', async (req, res) => {
+  const page = parseInt(req.query.page) || 1
+  const size = parseInt(req.query.size) || 20
+  
+  const users = await db.users.findMany({
+    skip: (page - 1) * size,
+    take: size
+  })
+  const total = await db.users.count()
+  
+  res.json({ data: users, total })
+})
+
+app.put('/v1/users/:id', async (req, res) => {
+  // 幂等：相同输入多次调用结果一致
+  const user = await db.users.upsert({
+    where: { id: req.params.id },
+    update: req.body,
+    create: { id: req.params.id, ...req.body }
+  })
+  res.json(user)
+})
+```
+
+**Python (FastAPI)**
+
+```python
+@app.get("/v1/users")
+async def list_users(page: int = 1, size: int = 20):
+    users = await db.users.find_many(
+        skip=(page - 1) * size,
+        take=size
+    )
+    total = await db.users.count()
+    return {"data": users, "total": total}
+
+@app.put("/v1/users/{user_id}")
+async def update_user(user_id: str, body: UpdateUserRequest):
+    # 幂等实现
+    user = await db.users.upsert(
+        where={"id": user_id},
+        update=body.dict(exclude_unset=True),
+        create={"id": user_id, **body.dict()}
+    )
+    return user
+```
+
+**Go (Gin)**
+
+```go
+func ListUsers(c *gin.Context) {
+    page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
+    size, _ := strconv.Atoi(c.DefaultQuery("size", "20"))
+    
+    users, _ := db.Users.FindMany(
+        db.Skip((page-1)*size),
+        db.Take(size),
+    )
+    total, _ := db.Users.Count()
+    
+    c.JSON(200, gin.H{
+        "data": users,
+        "total": total,
+    })
+}
+
+func UpdateUser(c *gin.Context) {
+    id := c.Param("id")
+    var body UpdateUserRequest
+    c.BindJSON(&body)
+    
+    // 幂等：upsert 语义
+    user, _ := db.Users.Upsert(
+        db.Where("id", id),
+        db.Update(body),
+        db.Create(map[string]interface{}{"id": id, ...}),
+    )
+    c.JSON(200, user)
+}
+```
+
+#### 步骤 5：统一错误处理
+
+```javascript
+// 中间件捕获所有错误
+app.use((err, req, res, next) => {
+  const errorResponse = {
+    code: err.code || 'INTERNAL_ERROR',
+    message: err.message || 'An error occurred',
+    data: err.details || null
+  }
+  res.status(err.statusCode || 500).json(errorResponse)
+})
+```
+
+#### 步骤 6：幂等性验证测试
+
+```python
+# 测试 PUT 幂等性
+response1 = client.put("/v1/users/123", json={"name": "Alice"})
+response2 = client.put("/v1/users/123", json={"name": "Alice"})
+assert response1.json() == response2.json()
+
+# 测试 DELETE 幂等性
+client.delete("/v1/users/123")  # 204
+client.delete("/v1/users/123")  # 仍返回 204，不报错
+```
+
+#### 步骤 7：版本升级示例
+
+```yaml
+# v2 引入破坏性变更：email 改为 emails 数组
+paths:
+  /api/v2/users:
+    post:
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                emails:  # v1 是 email (string)，v2 是 emails (array)
+                  type: array
+                  items:
+                    type: string
+```
+
+#### 步骤 8：性能监控（伪代码）
+
+```javascript
+// 记录每个请求的延迟
+app.use((req, res, next) => {
+  const start = Date.now()
+  res.on('finish', () => {
+    const duration = Date.now() - start
+    metrics.record('api.latency', duration, {
+      endpoint: req.path,
+      method: req.method
+    })
+  })
+  next()
+})
+
+// 告警：P99 > 200ms
+if (metrics.percentile('api.latency', 99) > 200) {
+  alert('API latency exceeds threshold')
+}
+```
+
+### 跨协议对比：gRPC 等效设计
+
+```protobuf
+syntax = "proto3";
+
+service UserService {
+  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
+  rpc GetUser(GetUserRequest) returns (User);
+  rpc CreateUser(CreateUserRequest) returns (User);
+  rpc UpdateUser(UpdateUserRequest) returns (User);  // 幂等
+  rpc DeleteUser(DeleteUserRequest) returns (google.protobuf.Empty);  // 幂等
+}
+
+message ListUsersRequest {
+  int32 page = 1;
+  int32 size = 2;
+}
+
+message ListUsersResponse {
+  repeated User data = 1;
+  int32 total = 2;
+}
+
+message User {
+  string id = 1;
+  string name = 2;
+  string email = 3;
+  google.protobuf.Timestamp created_at = 4;
+}
+
+message CreateUserRequest {
+  string name = 1;
+  string email = 2;
+  string password = 3;
+}
+
+message UpdateUserRequest {
+  string id = 1;
+  string name = 2;
+  string email = 3;
+}
+
+message GetUserRequest {
+  string id = 1;
+}
+
+message DeleteUserRequest {
+  string id = 1;
+}
+```
+
+### 关键要点总结
+
+1. **契约先行**：OpenAPI/Protobuf 规格在实现前完成并 mock 验证
+2. **资源导向**：URL 用名词（`/users`），操作用 HTTP 方法（GET/POST/PUT/DELETE）
+3. **幂等保证**：PUT/DELETE 多次调用结果一致，测试覆盖
+4. **版本隔离**：破坏性变更升版本号（`/api/v2/`）
+5. **一致性**：错误格式、分页、认证方式全局统一
+6. **性能监控**：P99 < 200ms，超时 30s，记录关键指标