@linkl/link-openapi-skills 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,4 @@
+Copyright (c) LINK. All rights reserved.
+
+This package is provided for authorized LINK OpenAPI integration.
+Redistribution and commercial use are subject to the publisher's license terms.

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# LINK OpenAPI Skills npm Installer
 
-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.
+> 发布前请将 package.json 中的 npm scope `@linkl` 替换为你实际拥有的 npm organization/scope（如果你没有该 scope 的发布权限）。
+
+## 一键安装
+
+```bash
+npx -y @linkl/link-openapi-skills@latest install
+```
+
+默认安装到当前项目的 Claude Code、Codex、Cursor 和 Spring AI 项目目录：
+
+- Claude Code：`.claude/skills/`
+- Codex：`.agents/skills/`
+- Cursor：`.cursor/skills/`
+- Spring AI：`src/main/resources/agent-skills/`
+
+通用 Agent Skills 目录：
+
+```bash
+npx -y @linkl/link-openapi-skills@latest install --agent agents
+```
+
+只安装指定客户端：
+
+```bash
+npx -y @linkl/link-openapi-skills@latest install --agent claude
+npx -y @linkl/link-openapi-skills@latest install --agent codex
+npx -y @linkl/link-openapi-skills@latest install --agent cursor
+```
+
+安装到个人全局目录：
+
+```bash
+npx -y @linkl/link-openapi-skills@latest install --agent all --scope global
+```
+
+更新和卸载：
+
+```bash
+npx -y @linkl/link-openapi-skills@latest update
+npx -y @linkl/link-openapi-skills@latest uninstall
+```
+
+## 本地测试
+
+```bash
+node bin/cli.js install --agent all --scope project
+node bin/cli.js update --agent all --scope project
+node bin/cli.js uninstall --agent all --scope project
+```
+
+## 发布到 npm
+
+1. 创建或确认你拥有的 npm organization/scope，例如 `@linkl`。
+2. 修改 `package.json` 的 name、version、license、repository、homepage。
+3. 先检查包内容：`npm pack --dry-run`。
+4. 登录 npm：`npm login`。
+5. 首次发布 public scoped package：`npm publish --access public`。
+6. 后续升级：修改版本号（`npm version patch`），再 `npm publish`。
+
+## 重要：Skill 和 MCP 是两回事
+
+本安装器只复制 SKILL.md 和参考资料。要让 AI 真正执行 LINK API，还必须单独部署/配置 LINK MCP Server，并由 MCP Server 从安全配置读取 `LINK_API_TOKEN`。安装器不会写入真实 Token，也不会自动配置 MCP 凭证。
+
+## 安全
+
+- npm public package 中的所有文件都可被公开下载；不要放真实 Token、客户数据、私有 endpoint 或内部源码。
+- `update` 会覆盖本安装器管理的 Skill 目录；请不要在安装目录内手工维护唯一副本。
+- `uninstall` 会删除 manifest 中记录的 Skill 目录。
+- 本包中的接口信息来自随包的 OpenAPI 3.0.1 定义；接口变更后应重新生成参考文档并发布新版本。

package/bin/cli.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { cp, mkdir, readFile, readdir, rm, writeFile, access } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SKILLS_SOURCE = path.join(PACKAGE_ROOT, 'skills');
+const PACKAGE_JSON = JSON.parse(await readFile(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'));
+const SKILL_NAMES = (await readdir(SKILLS_SOURCE, { withFileTypes: true }))
+  .filter(x => x.isDirectory()).map(x => x.name);
+
+function parseArgs(argv) {
+  const command = argv[2] || 'help';
+  const opts = { agent: 'all', scope: 'project', force: false };
+  for (let i = 3; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--force') opts.force = true;
+    else if (a === '--agent' && argv[i + 1]) opts.agent = argv[++i];
+    else if (a === '--scope' && argv[i + 1]) opts.scope = argv[++i];
+    else if (a === '--help' || a === '-h') opts.help = true;
+    else throw new Error(`未知参数：${a}`);
+  }
+  return { command, opts };
+}
+
+function targetDirs(agent, scope) {
+  const project = process.cwd();
+  const home = os.homedir();
+  const projectMap = {
+    claude: '.claude/skills',
+    codex: '.agents/skills',
+    cursor: '.cursor/skills',
+    agents: '.agents/skills',
+    'spring-ai': 'src/main/resources/agent-skills'
+  };
+  const globalMap = {
+    claude: path.join(home, '.claude', 'skills'),
+    codex: path.join(home, '.agents', 'skills'),
+    cursor: path.join(home, '.cursor', 'skills'),
+    agents: path.join(home, '.agents', 'skills')
+  };
+  const aliases = agent === 'all' ? ['claude', 'codex', 'cursor', 'spring-ai'] : [agent];
+  for (const a of aliases) {
+    if (!projectMap[a]) throw new Error(`不支持的 agent：${a}。可选 claude、codex、cursor、agents、spring-ai、all`);
+    if (scope === 'global' && !globalMap[a]) throw new Error('spring-ai 仅支持 project scope；它需要安装到当前 Spring Boot 项目的 resources 目录。');
+  }
+  return aliases.map(a => ({ agent: a, root: scope === 'global' ? globalMap[a] : path.resolve(project, projectMap[a]) }));
+}
+
+async function exists(p) { try { await access(p); return true; } catch { return false; } }
+async function readManifest(root) {
+  const p = path.join(root, '.link-openapi-skills-manifest.json');
+  try { return JSON.parse(await readFile(p, 'utf8')); } catch { return { skills: [] }; }
+}
+async function writeManifest(root, skills) {
+  await mkdir(root, { recursive: true });
+  await writeFile(path.join(root, '.link-openapi-skills-manifest.json'), JSON.stringify({
+    package: PACKAGE_JSON.name, version: PACKAGE_JSON.version, skills: [...new Set(skills)]
+  }, null, 2) + '\n', 'utf8');
+}
+
+async function installInto(root, command, force) {
+  await mkdir(root, { recursive: true });
+  const previous = await readManifest(root);
+  const managed = new Set(previous.skills || []);
+  let installed = 0, skipped = 0;
+  for (const name of SKILL_NAMES) {
+    const src = path.join(SKILLS_SOURCE, name);
+    const dest = path.join(root, name);
+    const already = await exists(dest);
+    const overwrite = command === 'update' || force || managed.has(name);
+    if (already && !overwrite) {
+      console.log(`  - 跳过已存在：${name}（如需覆盖请加 --force，或执行 update）`);
+      skipped++;
+      continue;
+    }
+    if (already && overwrite) await rm(dest, { recursive: true, force: true });
+    await cp(src, dest, { recursive: true, force: true });
+    managed.add(name); installed++;
+    console.log(`  ✓ ${command === 'update' ? '更新' : '安装'}：${name}`);
+  }
+  await writeManifest(root, [...managed]);
+  return { installed, skipped };
+}
+
+async function uninstallFrom(root) {
+  const manifestPath = path.join(root, '.link-openapi-skills-manifest.json');
+  const manifest = await readManifest(root);
+  if (!(await exists(manifestPath))) {
+    console.log(`  - 未找到本安装器的清单，跳过：${root}`); return 0;
+  }
+  let removed = 0;
+  for (const name of manifest.skills || []) {
+    await rm(path.join(root, name), { recursive: true, force: true });
+    console.log(`  ✓ 已卸载：${name}`); removed++;
+  }
+  await rm(manifestPath, { force: true });
+  return removed;
+}
+
+function help() {
+  console.log(`\nLINK OpenAPI Skills Installer v${PACKAGE_JSON.version}\n\n用法：\n  npx -y ${PACKAGE_JSON.name}@latest install [--agent all|claude|codex|cursor|agents|spring-ai] [--scope project|global] [--force]\n  npx -y ${PACKAGE_JSON.name}@latest update  [--agent ...] [--scope ...]\n  npx -y ${PACKAGE_JSON.name}@latest uninstall [--agent ...] [--scope ...]\n  npx -y ${PACKAGE_JSON.name}@latest list\n\n默认：agent=all，scope=project。\n注意：本命令安装 Agent Skills 文件；不会自动安装或启动 LINK MCP Server，也不会写入 LINK Token。\n`);
+}
+
+try {
+  const { command, opts } = parseArgs(process.argv);
+  if (opts.help || command === 'help') { help(); process.exit(0); }
+  if (command === 'list') {
+    console.log('随包 Skills：'); SKILL_NAMES.forEach(n => console.log(`  - ${n}`)); process.exit(0);
+  }
+  if (!['install', 'update', 'uninstall'].includes(command)) throw new Error(`未知命令：${command}`);
+  if (!['project', 'global'].includes(opts.scope)) throw new Error('--scope 只能是 project 或 global');
+  const targets = targetDirs(opts.agent, opts.scope);
+  console.log(`\nLINK OpenAPI Skills ${command}（${opts.scope}）`);
+  for (const t of targets) {
+    console.log(`\n[${t.agent}] ${t.root}`);
+    if (command === 'uninstall') await uninstallFrom(t.root);
+    else await installInto(t.root, command, opts.force);
+  }
+  console.log('\n完成。请重启或重新加载对应 AI 客户端，让它重新发现 Skills。');
+} catch (e) {
+  console.error(`\n错误：${e.message}`);
+  process.exit(1);
+}

package/openapi/basic-data.json

@@ -0,0 +1,432 @@
+{
+  "openapi": "3.0.1",
+  "info": {
+    "title": "链路ERP开放平台",
+    "description": "basicdataservice",
+    "contact": {
+      "name": "link",
+      "url": "https://www.linkl.com.cn"
+    },
+    "version": "1.0"
+  },
+  "servers": [
+    {
+      "url": "https://www.linkl.com.cn"
+    }
+  ],
+  "paths": {
+    "/openapi/validateRemote": {
+      "post": {
+        "tags": [
+          "API列表"
+        ],
+        "summary": "偏远验证",
+        "operationId": "validateRemote",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CLBRO_OpenApiValidateRemoteRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "*/*": {
+                "schema": {
+                  "$ref": "#/components/schemas/CLCMRULLBRO_OpenApiValidateRemoteResponse"
+                }
+              }
+            }
+          }
+        },
+        "x-order": 2,
+        "parameters": [
+          {
+            "name": "linkToken",
+            "in": "header",
+            "required": true,
+            "description": "接口访问凭证，请按接口要求填写。",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      }
+    },
+    "/openapi/validateAddress": {
+      "post": {
+        "tags": [
+          "API列表"
+        ],
+        "summary": "地址验证",
+        "operationId": "validateAddress",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CLBRO_OpenApiValidateAddressRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "*/*": {
+                "schema": {
+                  "$ref": "#/components/schemas/CLCMRULLBRO_OpenApiValidateAddressResponse"
+                }
+              }
+            }
+          }
+        },
+        "x-order": 1,
+        "parameters": [
+          {
+            "name": "linkToken",
+            "in": "header",
+            "required": true,
+            "description": "接口访问凭证，请按接口要求填写。",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      }
+    },
+    "/openapi/cityPostCodeSearch": {
+      "post": {
+        "tags": [
+          "API列表"
+        ],
+        "summary": "城市邮编查询",
+        "operationId": "cityPostCodeSearch",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CLBRO_OpenApiCityPostCodeSearchRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "*/*": {
+                "schema": {
+                  "$ref": "#/components/schemas/CLCMRULLBRO_OpenApiCityPostCodeSearchResponse"
+                }
+              }
+            }
+          }
+        },
+        "x-order": 3,
+        "parameters": [
+          {
+            "name": "linkToken",
+            "in": "header",
+            "required": true,
+            "description": "接口访问凭证，请按接口要求填写。",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "CLBRO_OpenApiValidateRemoteRequest": {
+        "required": [
+          "countryCode"
+        ],
+        "type": "object",
+        "properties": {
+          "countryCode": {
+            "type": "string",
+            "description": "国家代码(长度:[2])",
+            "example": "US"
+          },
+          "city": {
+            "type": "string",
+            "description": "市(长度:[80])"
+          },
+          "postcode": {
+            "type": "string",
+            "description": "邮编(长度:[20])"
+          }
+        },
+        "description": "偏远验证请求",
+        "title": "偏远验证请求"
+      },
+      "CLBRO_OpenApiValidateRemoteResponse": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "integer",
+            "description": "偏远类型 1:DHL 2:FEDEX 3:UPS 4:TNT 5:UPS专线 6:FEDEX专线",
+            "format": "int32"
+          },
+          "level": {
+            "type": "string",
+            "description": "偏远等级"
+          }
+        },
+        "description": "偏远验证响应",
+        "title": "偏远验证响应"
+      },
+      "CLCMRULLBRO_OpenApiValidateRemoteResponse": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "integer",
+            "description": "返回码(0:成功 其他:失败)，业务code需大于1000",
+            "format": "int32"
+          },
+          "data": {
+            "type": "array",
+            "description": "数据结果",
+            "items": {
+              "$ref": "#/components/schemas/CLBRO_OpenApiValidateRemoteResponse"
+            }
+          },
+          "msg": {
+            "type": "string",
+            "description": "错误消息"
+          }
+        },
+        "description": "Result",
+        "title": "Result"
+      },
+      "CLBRO_OpenApiValidateAddressRequest": {
+        "required": [
+          "address1",
+          "countryCode"
+        ],
+        "type": "object",
+        "properties": {
+          "countryCode": {
+            "type": "string",
+            "description": "国家代码(长度:[2])",
+            "example": "US"
+          },
+          "state": {
+            "type": "string",
+            "description": "省(长度:[100])",
+            "example": "CA"
+          },
+          "city": {
+            "type": "string",
+            "description": "市(长度:[80])"
+          },
+          "postcode": {
+            "type": "string",
+            "description": "邮编(长度:[20])"
+          },
+          "address1": {
+            "type": "string",
+            "description": "地址1(长度:[255])"
+          },
+          "address2": {
+            "type": "string",
+            "description": "地址2(长度:[255])"
+          },
+          "address3": {
+            "type": "string",
+            "description": "地址3(长度:[255])"
+          }
+        },
+        "description": "地址验证请求",
+        "title": "地址验证请求"
+      },
+      "CLBRO_OpenApiValidateAddressResponse": {
+        "type": "object",
+        "properties": {
+          "countryCode": {
+            "type": "string",
+            "description": "国家代码",
+            "example": "US"
+          },
+          "state": {
+            "type": "string",
+            "description": "省",
+            "example": "CA"
+          },
+          "city": {
+            "type": "string",
+            "description": "市"
+          },
+          "postcode": {
+            "type": "string",
+            "description": "邮编"
+          },
+          "address1": {
+            "type": "string",
+            "description": "地址1"
+          },
+          "address2": {
+            "type": "string",
+            "description": "地址2"
+          },
+          "address3": {
+            "type": "string",
+            "description": "地址3"
+          },
+          "validateType": {
+            "type": "integer",
+            "description": "验证类型 0:FEDEX 1:UPS",
+            "format": "int32",
+            "example": 0
+          },
+          "addressType": {
+            "type": "integer",
+            "description": "地址类型(1:商业 2:住宅 3:混合 4:未知 5:FBA)",
+            "format": "int32"
+          },
+          "remoteLevel": {
+            "type": "string",
+            "description": "偏远等级"
+          }
+        },
+        "description": "地址验证响应",
+        "title": "地址验证响应"
+      },
+      "CLCMRULLBRO_OpenApiValidateAddressResponse": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "integer",
+            "description": "返回码(0:成功 其他:失败)，业务code需大于1000",
+            "format": "int32"
+          },
+          "data": {
+            "type": "array",
+            "description": "数据结果",
+            "items": {
+              "$ref": "#/components/schemas/CLBRO_OpenApiValidateAddressResponse"
+            }
+          },
+          "msg": {
+            "type": "string",
+            "description": "错误消息"
+          }
+        },
+        "description": "Result",
+        "title": "Result"
+      },
+      "CLBRO_OpenApiCityPostCodeSearchRequest": {
+        "required": [
+          "countryCode"
+        ],
+        "type": "object",
+        "properties": {
+          "countryCode": {
+            "type": "string",
+            "description": "国家代码(长度:[2])"
+          },
+          "city": {
+            "type": "string",
+            "description": "市(长度:[80])"
+          },
+          "postcode": {
+            "type": "string",
+            "description": "邮编(长度:[20])"
+          }
+        },
+        "description": "城市邮编查询请求",
+        "title": "城市邮编查询请求"
+      },
+      "CLBRO_OpenApiCityPostCodeSearchResponse": {
+        "type": "object",
+        "properties": {
+          "countryCode": {
+            "type": "string",
+            "description": "国家代码"
+          },
+          "state": {
+            "type": "string",
+            "description": "省"
+          },
+          "city": {
+            "type": "string",
+            "description": "市"
+          },
+          "postcode": {
+            "type": "string",
+            "description": "邮编"
+          },
+          "remoteResults": {
+            "type": "array",
+            "description": "偏远信息",
+            "items": {
+              "$ref": "#/components/schemas/CLBRO_OpenApiValidateRemoteResponse"
+            }
+          }
+        },
+        "description": "城市邮编查询响应",
+        "title": "城市邮编查询响应"
+      },
+      "CLCMRULLBRO_OpenApiCityPostCodeSearchResponse": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "integer",
+            "description": "返回码(0:成功 其他:失败)，业务code需大于1000",
+            "format": "int32"
+          },
+          "data": {
+            "type": "array",
+            "description": "数据结果",
+            "items": {
+              "$ref": "#/components/schemas/CLBRO_OpenApiCityPostCodeSearchResponse"
+            }
+          },
+          "msg": {
+            "type": "string",
+            "description": "错误消息"
+          }
+        },
+        "description": "Result",
+        "title": "Result"
+      }
+    }
+  },
+  "x-openapi": {
+    "x-setting": {
+      "customCode": 200,
+      "language": "zh-CN",
+      "enableSwaggerModels": false,
+      "swaggerModelName": "Swagger Models",
+      "enableReloadCacheParameter": false,
+      "enableAfterScript": true,
+      "enableDocumentManage": false,
+      "enableVersion": false,
+      "enableRequestCache": true,
+      "enableFilterMultipartApis": false,
+      "enableFilterMultipartApiMethodType": "POST",
+      "enableHost": false,
+      "enableHostText": "",
+      "enableDynamicParameter": false,
+      "enableDebug": false,
+      "enableFooter": true,
+      "enableFooterCustom": false,
+      "enableSearch": true,
+      "enableOpenApi": true,
+      "enableHomeCustom": false,
+      "enableGroup": true,
+      "enableResponseCode": true
+    },
+    "x-markdownFiles": []
+  }
+}