dsh-plugin-yapi 0.0.0-stage → 1.4.0

package/lib/core.js

@@ -0,0 +1,434 @@
+/**
+ * Pure helpers behind the YAPI panel.
+ *
+ * Nothing in this file touches the network or the DSH runtime: `index.js`
+ * turns a YAPI `/api/interface/get` payload into a browser-friendly document,
+ * and the tests exercise the same functions directly. Keeping the example
+ * generator here means the browser never has to understand YAPI's schema
+ * dialect.
+ */
+
+/** HTTP methods the panel knows how to color and copy. */
+export const METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']
+
+/**
+ * Trim trailing slashes so `baseUrl + pathname` never doubles a separator.
+ * An empty value stays empty: the plugin has no built-in YAPI host.
+ * @param {unknown} value - configured origin.
+ * @returns {string} normalized origin without a trailing slash.
+ */
+export function normalizeBaseUrl(value) {
+  return String(value ?? '').trim().replace(/\/+$/u, '')
+}
+
+/**
+ * Join URL fragments with exactly one slash between them.
+ * @param {...unknown} parts - origin, optional base path, optional endpoint.
+ * @returns {string} the joined address.
+ */
+export function joinUrl(...parts) {
+  let out = ''
+  for (const part of parts) {
+    const text = String(part ?? '').trim()
+    if (text === '') continue
+    if (out === '') out = text.replace(/\/+$/u, '')
+    else out += '/' + text.replace(/^\/+/u, '').replace(/\/+$/u, '')
+  }
+  return out
+}
+
+/**
+ * Pull a YAPI interface id out of a raw id, a numeric string, or a full
+ * documentation URL (`.../project/1/interface/api/10001`).
+ * @param {unknown} value - user input.
+ * @returns {number | null} a positive integer id, or null when unparseable.
+ */
+export function parseDocId(value) {
+  if (typeof value === 'number' && Number.isSafeInteger(value) && value > 0) return value
+  const text = String(value ?? '').trim()
+  if (text === '') return null
+  if (/^\d{1,12}$/u.test(text)) {
+    const id = Number(text)
+    return Number.isSafeInteger(id) && id > 0 ? id : null
+  }
+  const patterns = [
+    /\/interface\/api\/(\d{1,12})(?:[/?#]|$)/u,
+    /[?&]id=(\d{1,12})(?:[&#]|$)/u,
+    /\/api\/interface\/get\?id=(\d{1,12})(?:[&#]|$)/u,
+  ]
+  for (const pattern of patterns) {
+    const match = pattern.exec(text)
+    if (match) {
+      const id = Number(match[1])
+      if (Number.isSafeInteger(id) && id > 0) return id
+    }
+  }
+  const trailing = /(\d{1,12})\/?(?:[?#].*)?$/u.exec(text)
+  if (trailing) {
+    const id = Number(trailing[1])
+    if (Number.isSafeInteger(id) && id > 0) return id
+  }
+  return null
+}
+
+/**
+ * Turn YAPI's rich-text description into readable plain text.
+ * @param {unknown} html - the `desc` field.
+ * @returns {string} text with tags and entities removed.
+ */
+export function stripHtml(html) {
+  const text = String(html ?? '')
+  if (text === '') return ''
+  return text
+    .replace(/<br\s*\/?>/giu, '\n')
+    .replace(/<\/(?:p|div|li|h[1-6]|tr)>/giu, '\n')
+    .replace(/<li[^>]*>/giu, '- ')
+    .replace(/<[^>]+>/gu, '')
+    .replace(/&nbsp;/giu, ' ')
+    .replace(/&lt;/giu, '<')
+    .replace(/&gt;/giu, '>')
+    .replace(/&amp;/giu, '&')
+    .replace(/&quot;/giu, '"')
+    .replace(/&#39;/giu, "'")
+    .replace(/\n{3,}/gu, '\n\n')
+    .trim()
+}
+
+/** @param {unknown} value @returns {unknown} parsed JSON, or undefined. */
+function tryParseJson(value) {
+  if (typeof value !== 'string' || value.trim() === '') return undefined
+  try {
+    return JSON.parse(value)
+  } catch {
+    return undefined
+  }
+}
+
+/** @param {unknown} value @returns {string} pretty JSON, or '' when undefined. */
+function pretty(value) {
+  if (value === undefined) return ''
+  return JSON.stringify(value, null, 2)
+}
+
+/** @param {Record<string, unknown>} schema @returns {Record<string, unknown>} */
+function unwrapComposite(schema) {
+  let current = schema
+  for (let round = 0; round < 8; round += 1) {
+    if (!current || typeof current !== 'object') return {}
+    const allOf = Array.isArray(current.allOf) ? current.allOf : null
+    if (allOf && allOf.length > 0) {
+      const merged = { ...current }
+      delete merged.allOf
+      const properties = { ...(current.properties || {}) }
+      for (const member of allOf) {
+        if (member && typeof member === 'object' && member.properties) Object.assign(properties, member.properties)
+      }
+      merged.properties = properties
+      merged.type = merged.type || 'object'
+      return merged
+    }
+    const list = Array.isArray(current.oneOf)
+      ? current.oneOf
+      : Array.isArray(current.anyOf)
+        ? current.anyOf
+        : null
+    if (list && list.length > 0 && list[0] && typeof list[0] === 'object') {
+      current = list[0]
+      continue
+    }
+    return current
+  }
+  return current && typeof current === 'object' ? current : {}
+}
+
+/**
+ * Generate a copy-friendly example value from a YAPI JSON schema.
+ * @param {unknown} input - a JSON schema node.
+ * @param {{ maxNodes?: number, maxDepth?: number }} [options] - safety limits.
+ * @returns {{ value: unknown, truncated: boolean, nodes: number }} example value and limits status.
+ */
+export function exampleFromSchema(input, options = {}) {
+  const maxNodes = Number.isFinite(options.maxNodes) ? Number(options.maxNodes) : 20000
+  const maxDepth = Number.isFinite(options.maxDepth) ? Number(options.maxDepth) : 48
+  const state = { nodes: 0, truncated: false }
+
+  const walk = (node, depth) => {
+    state.nodes += 1
+    if (state.nodes > maxNodes) {
+      state.truncated = true
+      return null
+    }
+    if (typeof node === 'boolean') return node ? {} : null
+    if (!node || typeof node !== 'object') return null
+    if (depth > maxDepth) {
+      state.truncated = true
+      return null
+    }
+
+    const schema = unwrapComposite(node)
+    // YAPI keeps a resolved-schema marker in `$$ref`; it is documentation, not data.
+    if (schema.example !== undefined) return schema.example
+    if (schema.default !== undefined) return schema.default
+
+    let type = schema.type
+    if (Array.isArray(type)) type = type.find((item) => item !== 'null') || 'null'
+    if (!type) {
+      if (schema.properties) type = 'object'
+      else if (schema.items) type = 'array'
+      else if (schema.enum) type = typeof schema.enum[0] === 'number' ? 'number' : 'string'
+    }
+
+    if (schema.enum && schema.enum.length > 0) return schema.enum[0]
+    if (Array.isArray(schema.examples) && schema.examples.length > 0) return schema.examples[0]
+
+    switch (type) {
+      case 'object': {
+        const out = {}
+        const properties = schema.properties && typeof schema.properties === 'object' ? schema.properties : {}
+        for (const [key, child] of Object.entries(properties)) out[key] = walk(child, depth + 1)
+        if (Object.keys(properties).length === 0 && schema.additionalProperties && typeof schema.additionalProperties === 'object') {
+          out['additionalProp1'] = walk(schema.additionalProperties, depth + 1)
+        }
+        return out
+      }
+      case 'array': {
+        const items = Array.isArray(schema.items) ? schema.items[0] : schema.items
+        if (!items) return []
+        return [walk(items, depth + 1)]
+      }
+      case 'integer':
+        return 0
+      case 'number':
+        return 0
+      case 'boolean':
+        return false
+      case 'null':
+        return null
+      case 'string': {
+        if (schema.format === 'date-time') return '2024-01-01T00:00:00Z'
+        if (schema.format === 'date') return '2024-01-01'
+        if (schema.format === 'email') return 'user@example.com'
+        if (schema.format === 'uuid') return '00000000-0000-4000-8000-000000000000'
+        return ''
+      }
+      default:
+        return null
+    }
+  }
+
+  const value = walk(input, 0)
+  return { value, truncated: state.truncated, nodes: state.nodes }
+}
+
+/**
+ * Build the copyable request body plus the raw schema text.
+ * @param {Record<string, unknown>} raw - YAPI interface payload.
+ * @returns {{ kind: 'none'|'json'|'text', example: string, raw: string, truncated: boolean }} body views.
+ */
+export function buildRequestPayload(raw) {
+  const type = String(raw.req_body_type ?? '').toLowerCase()
+  const bodyText = typeof raw.req_body_other === 'string' ? raw.req_body_other : ''
+  const form = Array.isArray(raw.req_body_form) ? raw.req_body_form : []
+
+  if (type === 'form' || (type === '' && form.length > 0)) {
+    if (form.length === 0) return { kind: 'none', example: '', raw: bodyText, truncated: false }
+    const object = {}
+    for (const field of form) {
+      if (!field || typeof field !== 'object') continue
+      const name = String(field.name ?? '').trim() || 'field'
+      object[name] = formExample(field)
+    }
+    return { kind: 'json', example: pretty(object), raw: bodyText, truncated: false }
+  }
+
+  if (bodyText.trim() === '') return { kind: 'none', example: '', raw: '', truncated: false }
+
+  if (raw.req_body_is_json_schema === true) {
+    const schema = tryParseJson(bodyText)
+    if (schema !== undefined) {
+      const generated = exampleFromSchema(schema)
+      return { kind: 'json', example: pretty(generated.value), raw: bodyText, truncated: generated.truncated }
+    }
+  }
+
+  const parsed = tryParseJson(bodyText)
+  if (parsed !== undefined) return { kind: 'json', example: pretty(parsed), raw: bodyText, truncated: false }
+  return { kind: 'text', example: bodyText, raw: bodyText, truncated: false }
+}
+
+/**
+ * Build the copyable response body plus the raw schema text.
+ * @param {Record<string, unknown>} raw - YAPI interface payload.
+ * @returns {{ kind: 'none'|'json'|'text', example: string, raw: string, truncated: boolean }} body views.
+ */
+export function buildResponsePayload(raw) {
+  const bodyText = typeof raw.res_body === 'string' ? raw.res_body : ''
+  if (bodyText.trim() === '') return { kind: 'none', example: '', raw: '', truncated: false }
+
+  if (raw.res_body_is_json_schema === true) {
+    const schema = tryParseJson(bodyText)
+    if (schema !== undefined) {
+      const generated = exampleFromSchema(schema)
+      return { kind: 'json', example: pretty(generated.value), raw: bodyText, truncated: generated.truncated }
+    }
+  }
+
+  const parsed = tryParseJson(bodyText)
+  if (parsed !== undefined) return { kind: 'json', example: pretty(parsed), raw: bodyText, truncated: false }
+  return { kind: 'text', example: bodyText, raw: bodyText, truncated: false }
+}
+
+/** @param {Record<string, unknown>} field @returns {unknown} */
+function formExample(field) {
+  const type = String(field.type ?? '').toLowerCase()
+  const example = field.example
+  if (example !== undefined && example !== null && example !== '') {
+    if (type === 'integer' || type === 'number') {
+      const parsed = Number(example)
+      return Number.isFinite(parsed) ? parsed : example
+    }
+    if (type === 'boolean') return example === true || example === 'true' || example === '1'
+    return example
+  }
+  if (type === 'file') return ''
+  if (type === 'integer' || type === 'number') return 0
+  if (type === 'boolean') return false
+  return ''
+}
+
+/** @param {unknown} item @returns {{ name: string, type: string, required: boolean, example: string, desc: string, value: string }} */
+function normalizeParam(item) {
+  const entry = item && typeof item === 'object' ? item : {}
+  return {
+    name: String(entry.name ?? '').trim(),
+    type: String(entry.type ?? '').trim(),
+    required: entry.required === '1' || entry.required === true,
+    example: entry.example === undefined || entry.example === null ? '' : String(entry.example),
+    desc: stripHtml(entry.desc ?? ''),
+    value: entry.value === undefined || entry.value === null ? '' : String(entry.value),
+  }
+}
+
+/**
+ * Whether every character of `needle` appears in `haystack` in order.
+ * @param {string} needle - lower-case query.
+ * @param {string} haystack - lower-case target.
+ * @returns {boolean} true for an in-order subsequence match.
+ */
+function isSubsequence(needle, haystack) {
+  let index = 0
+  for (let cursor = 0; cursor < haystack.length && index < needle.length; cursor += 1) {
+    if (haystack[cursor] === needle[index]) index += 1
+  }
+  return index === needle.length
+}
+
+/**
+ * Rank a YAPI project's interface list against one keyword.
+ *
+ * Paths are the primary key (the user asked for "接口地址" search), titles are
+ * the fallback, and a cheap in-order subsequence match handles acronym-style
+ * queries such as `whlist` for `/admin/warehouse/list`.
+ * @param {unknown} list - `/api/interface/list` rows.
+ * @param {unknown} keyword - user query; spaces split it into required tokens.
+ * @param {number} [limit] - maximum rows returned.
+ * @returns {Array<Record<string, unknown>>} matching rows, best first.
+ */
+export function rankInterfaces(list, keyword, limit = 30) {
+  const query = String(keyword ?? '').trim().toLowerCase()
+  if (query === '') return []
+  const tokens = query.split(/\s+/u).filter(Boolean)
+  const ranked = []
+  for (const item of Array.isArray(list) ? list : []) {
+    if (!item || typeof item !== 'object') continue
+    const id = String(item._id ?? '')
+    const path = String(item.path ?? '')
+    const title = String(item.title ?? '')
+    const lowerPath = path.toLowerCase()
+    const lowerTitle = title.toLowerCase()
+    let score = 0
+    if (id === query) score = 1200
+    else if (lowerPath === query) score = 1100
+    else if (lowerPath.startsWith(query)) score = 1000
+    else {
+      const pathAt = lowerPath.indexOf(query)
+      if (pathAt !== -1) score = 900 - Math.min(pathAt, 80)
+      else {
+        const titleAt = lowerTitle.indexOf(query)
+        if (titleAt !== -1) score = 700 - Math.min(titleAt, 80)
+        else if (tokens.length > 1 && tokens.every((token) => `${lowerPath} ${lowerTitle}`.includes(token))) score = 500
+        else if (query.length >= 2 && isSubsequence(query, lowerPath)) score = 400
+        else if (query.length >= 2 && isSubsequence(query, lowerTitle)) score = 300
+      }
+    }
+    if (score > 0) ranked.push({ item, score, path: lowerPath })
+  }
+  ranked.sort(
+    (left, right) =>
+      right.score - left.score ||
+      left.path.length - right.path.length ||
+      left.path.localeCompare(right.path) ||
+      String(left.item._id).localeCompare(String(right.item._id)),
+  )
+  return ranked.slice(0, Math.max(1, Number.isFinite(limit) ? limit : 30)).map((entry) => entry.item)
+}
+
+/**
+ * Shape one YAPI interface payload into the document the browser renders.
+ *
+ * The browser receives both views of each body: `example` (generated, good for
+ * copying into a client) and `raw` (the schema exactly as YAPI stores it).
+ * @param {Record<string, unknown>} raw - `/api/interface/get` data.
+ * @param {Record<string, unknown> | null} project - `/api/project/get` data.
+ * @param {string} baseUrl - the YAPI origin.
+ * @returns {Record<string, unknown>} normalized document.
+ */
+export function normalizeInterface(raw, project, baseUrl) {
+  const id = Number(raw._id)
+  const projectId = Number(raw.project_id)
+  const envs = Array.isArray(project?.env)
+    ? project.env
+        .filter((env) => env && typeof env === 'object' && env.domain)
+        .map((env) => ({
+          name: String(env.name ?? '默认'),
+          domain: String(env.domain ?? ''),
+        }))
+    : []
+  const basepath = typeof project?.basepath === 'string' ? project.basepath : ''
+  const path = String(raw.path ?? '')
+
+  return {
+    id,
+    title: String(raw.title ?? ''),
+    method: String(raw.method ?? 'GET').toUpperCase(),
+    path,
+    status: String(raw.status ?? ''),
+    tags: Array.isArray(raw.tag) ? raw.tag.map((tag) => String(tag)).filter(Boolean) : [],
+    desc: String(raw.desc ?? ''),
+    markdown: String(raw.markdown ?? ''),
+    author: String(raw.username ?? ''),
+    updatedAt: Number(raw.up_time) > 0 ? Number(raw.up_time) * 1000 : null,
+    pageUrl: joinUrl(baseUrl, '/project', String(projectId), '/interface/api', String(id)),
+    project: {
+      id: projectId,
+      name: String(project?.name ?? ''),
+      basepath,
+      envs,
+      address: envs.length > 0 ? joinUrl(envs[0].domain, basepath, path) : joinUrl(basepath, path),
+    },
+    request: {
+      headers: (Array.isArray(raw.req_headers) ? raw.req_headers : []).map(normalizeParam),
+      query: (Array.isArray(raw.req_query) ? raw.req_query : []).map(normalizeParam),
+      params: (Array.isArray(raw.req_params) ? raw.req_params : []).map(normalizeParam),
+      form: (Array.isArray(raw.req_body_form) ? raw.req_body_form : []).map(normalizeParam),
+      bodyType: String(raw.req_body_type ?? ''),
+      bodyIsJsonSchema: raw.req_body_is_json_schema === true,
+      body: buildRequestPayload(raw),
+    },
+    response: {
+      bodyType: String(raw.res_body_type ?? ''),
+      bodyIsJsonSchema: raw.res_body_is_json_schema === true,
+      body: buildResponsePayload(raw),
+    },
+  }
+}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "dsh-plugin-yapi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.4.0",
+  "description": "YAPI 接口文档面板 for DeepSeek Harness：搜索、多标签、字段树、勾选复制，附带 yapi-doc skill 与零依赖 CLI。",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "lib/**/*.js",
+    "cordis.patch.yml",
+    "README.md",
+    "bin/**/*.mjs",
+    "skills/**/*",
+    "LICENSE"
+  ],
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-sidebar"
+      ]
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "yapi",
+    "yapi-doc",
+    "api-docs",
+    "api-documentation",
+    "skills"
+  ],
+  "bin": {
+    "yapi-doc": "bin/yapi-doc.mjs"
+  },
+  "license": "MIT",
+  "author": "jinshan3690",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jinshan3690/dsh-plugin-yapi.git"
+  },
+  "homepage": "https://github.com/jinshan3690/dsh-plugin-yapi#readme",
+  "bugs": {
+    "url": "https://github.com/jinshan3690/dsh-plugin-yapi/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "node --test"
+  }
+}

package/skills/yapi-doc/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: yapi-doc
+description: Read a YAPI interface document by ID, full URL, or path keyword. Use when a task needs an API method, path, headers, parameters, request body, response fields, or response example. The bundled CLI reads the local YAPI account and prints Markdown in one command.
+---
+
+# YAPI 文档读取
+
+当任务需要 YAPI 接口的方法、路径、请求头、参数、请求/返回字段或返回示例时使用本 skill。优先用随包 CLI 读取，不要打开 YAPI 页面逐个翻，也不要让用户反复贴文档。
+
+## 命令
+
+```bash
+# 按文档 ID 或完整链接读取（默认输出 Markdown）
+node "$HOME/.dsh/skills/yapi-doc/yapi-doc.mjs" 10001
+node "$HOME/.dsh/skills/yapi-doc/yapi-doc.mjs" https://your-yapi.example.com/project/1/interface/api/10001
+
+# 不知道 ID 时，先按路径 / 标题关键字搜索
+node "$HOME/.dsh/skills/yapi-doc/yapi-doc.mjs" --search warehouse --project 1
+
+# 结构化输出，方便自己过滤
+node "$HOME/.dsh/skills/yapi-doc/yapi-doc.mjs" 10001 --json
+```
+
+Windows 下把 `$HOME` 换成 `%USERPROFILE%`，路径为
+`%USERPROFILE%\.dsh\skills\yapi-doc\yapi-doc.mjs`。
+
+## 安装到其他工具
+
+DSH 用户由插件自动注册，不需要执行本节。
+
+```bash
+npm install -g github:jinshan3690/dsh-plugin-yapi
+yapi-doc sync-skills                   # 自动同步到检测到的 Trae / WorkBuddy / Qoder CN / Copilot / CodeBuddy / Agent Skills / DSH
+yapi-doc install-skill                 # 默认装到 ~/.agents/skills/yapi-doc
+yapi-doc install-skill --dir ~/.trae/skills/yapi-doc       # Trae
+yapi-doc install-skill --dir ~/.workbuddy/skills/yapi-doc  # WorkBuddy
+yapi-doc install-skill --dir <目录>    # 其他 agent 的 skills 目录
+```
+
+`install-skill` 会复制本 `SKILL.md` 和 CLI，并把下面的路径改成实际安装目录。
+
+## 选项
+
+- `--no-fields`：不输出字段说明，输出最小（方法、路径、请求头、参数、请求 Body）。只关心请求怎么发时用它。
+- `--full`：额外输出返回体示例，可能很大；只有确实需要完整响应 JSON 时才用。
+- `--json`：输出 `{ ok, data }` 结构化 JSON。
+- `--project <id>`：`--search` 使用的项目 ID（必填）。
+- `-h, --help`：帮助。
+
+## 建议的读取顺序
+
+1. 不知道 ID：先 `--search <关键字> --project <项目ID>`，从结果里拿 ID。
+2. 只需要请求信息：`--no-fields`，输出最小。
+3. 需要响应字段 / 备注：不加 `--no-fields`，默认包含请求字段和返回字段说明。
+4. 需要精确响应 JSON：再加 `--full`。
+5. 要程序化处理：`--json`。
+
+## 账号
+
+CLI 读取 `~/.dsh/dsh-plugin-yapi.json`（YAPI 面板 → 账号设置维护），也支持
+`YAPI_BASE_URL` / `YAPI_EMAIL` / `YAPI_PASSWORD` 环境变量。不需要额外配置。
+
+## 可移植性
+
+`yapi-doc.mjs` 是**零依赖的 Node 脚本**，任何能执行 shell 的工具（Codex、Claude Code、
+CI、普通终端）都可以直接运行。`SKILL.md` 本身是给支持 skill 目录约定的 agent 读的；
+`yapi-doc install-skill --dir <目录>` 可以装到任意 agent 的 skills 目录。
+DSH 会从 `~/.dsh/skills`、`.dsh/skills`、`.agents/skills` 等目录发现它。