dsh-apis-plugin 0.1.0

package/README.md

@@ -0,0 +1 @@
+# dsh-apis-plugin

package/api-tools.js

@@ -0,0 +1,185 @@
+// 可复用的「接口工具插件」工厂：把任意一套 HTTP 接口注册成 agent 的 {prefix}_api_doc / {prefix}_api_request 双工具
+// 领域差异（settings 命名空间、工具名前缀、领域名、文档目录、baseUrl、默认接口列表）由调用方注入，
+// 其中 domain / toolPrefix / apiDir 也可在部署侧 cordis.patch.yml 的 config 里覆盖；
+// 工具描述 prompt 在这里按领域名拼接，实现一处逻辑多处复用
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import Schema from '@deepseek-ai/schemastery'
+
+// 读取目录下 apis.txt 作为默认接口列表；支持空行与 # 注释
+function loadApisTxt(dir) {
+  if (!dir) return []
+  try {
+    return readFileSync(join(dir, 'apis.txt'), 'utf8')
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith('#'))
+  } catch {
+    return []
+  }
+}
+
+// 读取目录下 api_doc.md 作为接口文档
+function loadApiDoc(dir) {
+  if (!dir) return ''
+  try {
+    return readFileSync(join(dir, 'api_doc.md'), 'utf8')
+  } catch {
+    return ''
+  }
+}
+
+// 把文档按 --- 分节，每节含一个接口的说明（兼容 CRLF 换行）
+function splitDocSections(doc) {
+  return doc.split(/\r?\n-{3,}\r?\n/).map((s) => s.trim()).filter(Boolean)
+}
+
+// 判断实际请求路径是否命中配置的接口（支持 {param} 模板段）
+function matchEndpoint(path, configured) {
+  const pattern = new RegExp('^' + configured.replace(/\{[^}]+\}/g, '[^/]+') + '/?$')
+  return pattern.test(path)
+}
+
+/** 从 cordis.patch.yml 提取插件 id（insert 列表第一项），作为命名空间唯一来源 */
+export function readPatchId(dir) {
+  const yml = readFileSync(join(dir, 'cordis.patch.yml'), 'utf8')
+  const m = yml.match(/^\s*-\s*id:\s*(\S+)\s*$/m)
+  if (!m) throw new Error('cordis.patch.yml 中未找到 insert 的 id')
+  return m[1]
+}
+
+/** 把 client.js 的 NS 字面量回写为 yml id（浏览器侧无法读 yml，只能靠此处同步） */
+export function syncClientNs(dir, ns) {
+  const file = join(dir, 'client.js')
+  const code = readFileSync(file, 'utf8')
+  const updated = code.replace(/^(\s*const NS = ")[^"]*(";\s*$)/m, `$1${ns}$2`)
+  if (updated !== code) writeFileSync(file, updated)
+}
+
+/**
+ * 构造一个可被 cordis 直接加载的插件模块：{ Config, inject, apply }
+ * @param {object} options
+ * @param {string} options.ns               settings 命名空间，须与前端卡片的 NS 一致
+ * @param {string} [options.toolPrefix]     工具名前缀默认值，生成 {prefix}_api_doc / {prefix}_api_request，可被 config 覆盖
+ * @param {string} [options.domain]         领域名默认值，用于拼接工具描述 prompt，可被 config 覆盖
+ * @param {string} [options.apiDir]         apis.txt 与 api_doc.md 所在目录默认值，可被 config 覆盖
+ * @param {string} [options.defaultBaseUrl] 接口服务前缀默认值（域名 + nginx 前缀 + 网关路由段）
+ * @param {string[]} [options.defaultEndpoints] yml 之外的额外默认接口
+ */
+export function defineApiPlugin(options) {
+  const { ns, toolPrefix = 'api', domain = '', apiDir = '', defaultBaseUrl = '', defaultEndpoints = [] } = options
+
+  const Config = Schema.object({
+    // 领域名：用于拼接工具描述 prompt
+    domain: Schema.string().default(domain),
+    // 工具名前缀：生成 {prefix}_api_doc / {prefix}_api_request
+    toolPrefix: Schema.string().default(toolPrefix),
+    // apis.txt 与 api_doc.md 所在目录（留空则只用 endpoints）
+    apiDir: Schema.string().default(apiDir),
+    endpoints: Schema.array(Schema.string()).default([]),
+    // 接口服务前缀：域名 + nginx 前缀 + 网关路由段
+    // （接口路径本身已含服务前缀，最终形如 /prod-api/xxx/users/detail）
+    baseUrl: Schema.string().default(defaultBaseUrl),
+  })
+
+  // 依赖部署挂载的设置服务与工具服务
+  const inject = ['settings', 'tools']
+
+  function apply(ctx, config) {
+    // config 覆盖优先，回退工厂默认值（兼容旧用户层保存值缺字段的情况）
+    const prefix = config.toolPrefix || toolPrefix
+    const domainName = config.domain || domain
+    const docDir = config.apiDir || apiDir
+
+    // 合并 apis.txt 与 yml 配置作为 base 层默认值（去重）
+    const endpoints = [...new Set([...loadApisTxt(docDir), ...defaultEndpoints, ...(config.endpoints ?? [])])]
+
+    // 以组合配置为 base 层注册 settings 命名空间，卸载插件时注册随 fiber 一并清理
+    const scope = ctx.settings.register(ns, Config, { base: { ...config, endpoints } })
+
+    // 每次已提交变更后收到通知
+    ctx.effect(
+      () => scope.watch(() => {
+        console.log(`${ns}: settings updated`)
+      }),
+      `${ns}: settings watch`,
+    )
+
+    // ---------- agent 工具 ----------
+    const docSections = splitDocSections(loadApiDoc(docDir))
+
+    // 当前生效的接口列表（用户层保存值优先，回退默认值）
+    function currentEndpoints() {
+      try {
+        const value = scope.get()
+        if (Array.isArray(value?.endpoints) && value.endpoints.length) return value.endpoints
+      } catch { /* scope.get 不可用时回退 */ }
+      return endpoints
+    }
+
+    // 工具 1：查接口文档，让模型了解每个接口的参数与响应（prompt 按领域名拼接）
+    ctx.tools.register({
+      name: `${prefix}_api_doc`,
+      description: `查询${domainName}接口文档。传 path（如 /users/page）返回该接口的详细参数与响应说明；不传 path 返回通用说明和全部已配置接口目录。发起请求前先用它确认参数。`,
+      parameters: {
+        path: { type: 'string', description: '接口路径，如 /users/{id}' },
+      },
+      output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] },
+      async execute(args) {
+        const list = currentEndpoints()
+        if (!args.path) {
+          return '【通用说明】\n' + (docSections[0] ?? '') + '\n\n【已配置接口目录】\n' + list.join('\n')
+        }
+        const norm = ('/' + args.path.trim().replace(/^\/+/, '')).split('?')[0]
+        const hit = docSections.filter((s) => s.includes('`' + norm + '`'))
+        if (hit.length) return hit.join('\n\n---\n\n')
+        return `文档中未找到 ${norm}。已配置接口目录：\n` + list.join('\n')
+      },
+    })
+
+    // 工具 2：真正调用接口拿数据（prompt 按领域名拼接）
+    ctx.tools.register({
+      name: `${prefix}_api_request`,
+      description: `调用${domainName}接口并返回 JSON 数据。path 必须是已配置的接口（支持 /orders/{id} 这类模板路径，模板段填实际值）；GET 用 query 传参，POST 用 body 传 JSON。调用前建议先用 ${prefix}_api_doc 确认参数。`,
+      parameters: {
+        path: { type: 'string', required: true, description: '接口路径，如 /users/detail 或 /orders/123' },
+        method: { type: 'string', description: 'HTTP 方法，默认 GET' },
+        query: { type: 'json', description: 'query 参数对象，如 { "keyword": "abc" }' },
+        body: { type: 'json', description: 'POST 请求体（JSON 对象）' },
+      },
+      output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] },
+      async execute(args) {
+        const list = currentEndpoints()
+        const method = (args.method ?? 'GET').toUpperCase()
+        const norm = ('/' + args.path.trim().replace(/^\/+/, '')).split('?')[0]
+
+        const matched = list.find((e) => matchEndpoint(norm, e))
+        if (!matched) {
+          return `接口 ${norm} 不在已配置列表中。可用接口：\n` + list.join('\n')
+        }
+
+        const url = new URL(config.baseUrl.replace(/\/+$/, '') + matched)
+        for (const [k, v] of Object.entries(args.query ?? {})) {
+          url.searchParams.set(k, String(v))
+        }
+
+        const response = await fetch(url, {
+          method,
+          headers: { Accept: 'application/json', ...(args.body != null ? { 'Content-Type': 'application/json' } : {}) },
+          ...(method !== 'GET' && args.body != null ? { body: JSON.stringify(args.body) } : {}),
+        })
+        const text = await response.text()
+
+        if (!response.ok) {
+          return `HTTP ${response.status} ${response.statusText}\n` + text.slice(0, 4000)
+        }
+        // 非文件流接口直接返回 JSON 文本，超长截断
+        return text.length > 30000 ? text.slice(0, 30000) + '\n…（超长截断）' : text
+      },
+    })
+
+    console.log(`[${ns}] loaded; endpoints=${endpoints.length}, doc sections=${docSections.length}`)
+  }
+
+  return { Config, inject, apply }
+}

package/client.js

@@ -0,0 +1,188 @@
+// 浏览器半侧：在「插件配置」标签页为 dsh-apis-plugin 命名空间注册一张可编辑卡片
+// 样式与 DOM 结构对齐原生 PluginCard（li 卡片 + SVG 箭头 + 放弃/保存 footer）
+window.__ModuleLoader__.load({
+	id: "dsh-apis-plugin",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		let react_jsx_runtime = require("react/jsx-runtime");
+		let react = require("react");
+
+		/** 本卡片编辑的 settings 命名空间，由宿主侧 index.js 按 cordis.patch.yml 的 id 自动回写 */
+		const NS = "dsh-apis-plugin";
+
+		/** bind 后的命名空间 scope，写入经由它进行（apply 时赋值） */
+		let scope;
+
+		// 复刻原生 PluginCard.module.css 的样式（类名自持，不依赖其哈希类）
+		const css = `
+			.apis-card{border:.5px solid var(--dsw-alias-border-l4);background:var(--dsw-alias-bg-layer-3);border-radius:16px;list-style:none;transition:border-color .16s,background .16s}
+			.apis-card:hover{border-color:var(--dsw-alias-label-dimmed)}
+			.apis-card[data-open=true]{background:var(--dsw-alias-bg-layer-2);border-color:var(--dsw-alias-label-dimmed)}
+			.apis-header{appearance:none;width:100%;font:inherit;color:inherit;text-align:left;cursor:pointer;background:0 0;border:0;border-radius:12px;align-items:center;gap:12px;padding:14px 16px;display:flex}
+			.apis-headText{flex-direction:column;flex:1;gap:4px;min-width:0;display:flex}
+			.apis-name{color:var(--dsw-alias-label-primary);font-size:15px;font-weight:600;line-height:1.4}
+			.apis-description{color:var(--dsw-alias-label-tertiary);font-size:13px;line-height:1.5}
+			.apis-chevron{color:var(--dsw-alias-label-tertiary);flex:none;transition:transform .16s}
+			.apis-body{border-top:.5px solid var(--dsw-alias-border-l2);margin:0 16px;padding:12px 0 8px;display:grid;gap:10px}
+			.apis-footer{border-top:.5px solid var(--dsw-alias-border-l2);justify-content:flex-end;align-items:center;gap:8px;padding:12px 0 4px;display:flex}
+			.apis-saved{color:var(--dsw-alias-label-tertiary);margin-right:auto;font-size:12px}
+			.apis-btn{appearance:none;font:inherit;cursor:pointer;border:1px solid transparent;border-radius:8px;padding:5px 14px;font-size:13px;line-height:1.5}
+			.apis-btn:disabled{opacity:.4;cursor:default}
+			.apis-discard{border-color:var(--dsw-alias-border-l2);color:var(--dsw-alias-label-secondary);background:0 0}
+			.apis-discard:hover:not(:disabled){color:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-label-dimmed)}
+			.apis-save{background:var(--dsw-alias-label-primary);color:var(--dsw-alias-bg-layer-3)}
+			.apis-row{display:flex;align-items:center;gap:8px}
+			.apis-rowLabel{width:44px;flex-shrink:0;font-size:13px;color:var(--dsw-alias-label-primary)}
+			.apis-input{box-sizing:border-box;flex:1;min-width:0;font:inherit;color:var(--dsw-alias-label-primary);background:transparent;border:.5px solid var(--dsw-alias-border-l4);border-radius:8px;padding:6px 10px}
+			.apis-remove{appearance:none;font:inherit;font-size:13px;cursor:pointer;background:none;border:none;border-radius:8px;padding:5px 10px;color:var(--dsw-alias-label-tertiary)}
+			.apis-remove:hover:not(:disabled){color:var(--dsw-alias-label-primary)}
+			.apis-add{appearance:none;font:inherit;font-size:13px;cursor:pointer;background:none;border:none;border-radius:8px;padding:2px 0;color:var(--dsw-alias-label-secondary);margin-right:auto}
+			.apis-add:hover:not(:disabled){color:var(--dsw-alias-label-primary)}
+		`;
+		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=dsh-apis-plugin]") === null) {
+			const tag = document.createElement("style");
+			tag.dataset.pluginCss = "dsh-apis-plugin";
+			tag.textContent = css;
+			document.head.appendChild(tag);
+		}
+
+		/** 与 slots 的 observableHook 约定兼容的极简 snapshot store（getSnapshot/subscribe） */
+		function createStore(initial) {
+			let state = initial;
+			const listeners = new Set();
+			return {
+				getSnapshot: () => state,
+				subscribe(listener) {
+					listeners.add(listener);
+					return () => listeners.delete(listener);
+				},
+				set(next) {
+					state = next;
+					listeners.forEach((l) => l());
+				},
+			};
+		}
+
+		/** 原生卡片同款的下拉箭头（14px 线性 chevron） */
+		function Chevron({ open }) {
+			return react_jsx_runtime.jsx("svg", {
+				width: 14, height: 14, viewBox: "0 0 14 14", fill: "none", "aria-hidden": true,
+				className: "apis-chevron",
+				style: { transform: open ? "rotate(180deg)" : "none" },
+				children: react_jsx_runtime.jsx("path", {
+					d: "M3.5 5.25 7 8.75l3.5-3.5",
+					stroke: "currentColor", strokeWidth: 1.2, strokeLinecap: "round", strokeLinejoin: "round",
+				}),
+			});
+		}
+
+		function ApisCard(props) {
+			const state = props.useApisCard((s) => s);
+			const [draft, setDraft] = react.useState(null); // string[]，null 表示未编辑
+			const [saving, setSaving] = react.useState(false);
+			const [saved, setSaved] = react.useState(false); // 保存成功后短暂提示
+			const [open, setOpen] = react.useState(false); // 折叠态只显示标题行
+			const ready = state.status === "ready" && state.writable;
+
+			/** 当前展示的接口列表：编辑中取 draft，否则取已保存值 */
+			const list = draft ?? (state.value?.endpoints ?? []).map(String);
+			const dirty = draft !== null;
+
+			async function save() {
+				if (saving || !ready || !dirty) return;
+				setSaving(true);
+				await scope.set("endpoints", draft);
+				setSaving(false);
+				setDraft(null);
+				setSaved(true); // 显示「已保存」提示，2 秒后消失
+				setTimeout(() => setSaved(false), 2000);
+			}
+
+			// 单行：接口N 标签 + 输入框 + 删除按钮
+			const row = (v, i) => react_jsx_runtime.jsxs("div", {
+				className: "apis-row",
+				children: [
+					react_jsx_runtime.jsx("div", { className: "apis-rowLabel", children: `接口${i + 1}` }),
+					react_jsx_runtime.jsx("input", {
+						value: v, disabled: !ready || saving,
+						onChange: (e) => setDraft(list.map((x, j) => (j === i ? e.target.value : x))),
+						className: "apis-input",
+					}),
+					react_jsx_runtime.jsx("button", {
+						type: "button", disabled: !ready || saving, "aria-label": `删除接口${i + 1}`,
+						onClick: () => setDraft(list.filter((_, j) => j !== i)),
+						className: "apis-remove", children: "✕",
+					}),
+				],
+			});
+
+			return react_jsx_runtime.jsxs("li", {
+				className: "apis-card",
+				"data-open": open,
+				children: [
+					// 折叠头：标题 + 描述 + 箭头，点击切换展开
+					react_jsx_runtime.jsxs("button", {
+						type: "button",
+						className: "apis-header",
+						"aria-expanded": open,
+						onClick: () => setOpen((v) => !v),
+						children: [
+							react_jsx_runtime.jsxs("div", { className: "apis-headText", children: [
+								react_jsx_runtime.jsx("span", { className: "apis-name", children: "通用接口管理插件" }),
+								react_jsx_runtime.jsx("span", { className: "apis-description", children: "接口列表配置" }),
+							] }),
+							react_jsx_runtime.jsx(Chevron, { open }),
+						],
+					}),
+					// 展开体：接口行列表 + 底部操作条（与原生一致：分隔线 + 右对齐按钮）
+					open && react_jsx_runtime.jsxs("div", { className: "apis-body", children: [
+						!state.writable && react_jsx_runtime.jsx("span", { className: "apis-description", children: "只读" }),
+						list.map(row),
+						react_jsx_runtime.jsx("button", {
+							type: "button", disabled: !ready || saving,
+							onClick: () => setDraft([...list, ""]),
+							className: "apis-add", children: "＋ 添加接口",
+						}),
+						react_jsx_runtime.jsxs("div", { className: "apis-footer", children: [
+							// 保存成功后的短暂提示（占按钮行左侧）
+							react_jsx_runtime.jsx("span", { className: "apis-saved", children: saved ? "已保存" : "" }),
+							react_jsx_runtime.jsx("button", {
+								type: "button", disabled: !dirty || saving,
+								onClick: () => setDraft(null),
+								className: "apis-btn apis-discard", children: "放弃修改",
+							}),
+							react_jsx_runtime.jsx("button", {
+								type: "button", disabled: !ready || !dirty || saving,
+								onClick: save, children: saving ? "保存中…" : "保存",
+								className: "apis-btn apis-save",
+							}),
+						] }),
+					] }),
+				],
+			});
+		}
+
+		/** 需要的浏览器侧服务 */
+		const inject = ["slots", "settingsScope"];
+
+		/**
+		 * 以命名空间为 key 注册到 settings.plugin.item 槽位：
+		 * 「插件配置」标签页会为每个被服务且被认领的命名空间渲染一张卡片
+		 */
+		function apply(ctx) {
+			scope = ctx.settingsScope.bind({ namespace: NS });
+			const store = createStore(scope.getSnapshot());
+			ctx.effect(() => scope.subscribe(() => store.set(scope.getSnapshot())));
+			ctx.effect(() => ctx.slots.inject("settings.plugin.item", () => ctx.slots.register({
+				name: "settings.plugin.item",
+				key: NS,
+				inject: () => ({ hooks: { apisCard: store } }),
+			}, ApisCard)));
+		}
+
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});

package/cordis.patch.yml

@@ -0,0 +1,15 @@
+- insert:
+    - id: dsh-apis-plugin
+      # 注：商店发布形态用包名；本地开发调试时临时换回 file:// 直连源码
+      name: dsh-apis-plugin
+      config:
+        # 领域名：拼接工具描述 prompt
+        domain: ""
+        # 工具名前缀：生成 {prefix}_api_doc / {prefix}_api_request
+        toolPrefix: api
+        # apis.txt 与 api_doc.md 所在目录（可选，留空则只用 endpoints）
+        apiDir: ""
+        # 默认接口列表
+        endpoints: []
+        # 接口服务前缀：域名 + nginx 前缀 + 网关路由段
+        baseUrl: ""

package/index.js

@@ -0,0 +1,18 @@
+// 通用接口管理插件：把任意一套 HTTP 接口注册成 agent 可用的文档查询与请求双工具
+// 领域差异（工具前缀、领域名、文档目录、baseUrl、默认接口列表）全部由部署侧 cordis.patch.yml 的 config 注入；
+// 通用逻辑（工具注册、prompt 拼接、接口匹配、settings 注册）在同目录 api-tools.js 的 defineApiPlugin
+import { fileURLToPath } from 'node:url'
+import { dirname } from 'node:path'
+import { defineApiPlugin, readPatchId, syncClientNs } from './api-tools.js'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+// 命名空间以 cordis.patch.yml 的 id 为准，加载时自动同步到 client.js
+const ns = readPatchId(here)
+syncClientNs(here, ns)
+
+const plugin = defineApiPlugin({ ns })
+
+export const Config = plugin.Config
+export const inject = plugin.inject
+export const apply = plugin.apply

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "dsh-apis-plugin",
+  "version": "0.1.0",
+  "description": "通用接口管理插件：把任意一套 HTTP 接口注册成 agent 可用的文档查询与请求双工具",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "api-tools.js",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.2"
+  }
+}