LingFang Plugin SDK

用于创建、校验、构建和发布 LingFang 插件。详细约定见插件开发说明。

快速开始

lingfang-plugin create
cd <plugin-directory>
lingfang-plugin validate
lingfang-plugin build
lingfang-plugin publish

create 支持 client、nodejs 和 python 模板，并生成 manifest.json、运行时入口和可直接修改的 README.md。

描述文件

• manifest.description：列表、搜索和卡片中的纯文本短摘要，最多 4096 个字符。
• 根目录 README.md：详情页正文，可选但强烈推荐；必须是 UTF-8，最大 256 KiB。
• README 支持安全 GFM。不要依赖 raw HTML、脚本、样式或图片；可点击链接仅支持 HTTP(S)。
• README 随发行版冻结。修改说明后需要提升 manifest.version 并发布新版本。

Runtime 与能力

manifest.runtime_type 决定入口运行方式，manifest.entry 必须指向对应入口文件：

• client：桌面端内嵌页面，通常为 ui/index.html。
• nodejs：Node.js 独立进程入口。
• python：Python 独立进程入口。
• cloud / workflow：由平台云运行与工作流能力处理，不能套用前三种模板的本地入口假设。

插件使用的能力必须在 manifest.capabilities 中声明。代码通过 @lingfang/plugin-sdk 调用宿主能力，不直接读取平台密钥或桥接令牌；README 应解释每项能力的用途、访问的数据和隐私影响。

CLI 门禁

validate 和 build 使用相同的 manifest、入口与 README 边界。README 超限或不是 UTF-8 时，build 会在生成 .lfplugin 前失败。.lfplugin 必须由 lingfang-plugin build 生成，不要手工压缩 ZIP。

从 npm 安装（发布包）

本包已发布为 @lingfang/plugin-sdk，插件作者可脱离 monorepo 直接安装：

npm install @lingfang/plugin-sdk

运行时会自动带上能力调用的类型化 sdk、lingfang-plugin CLI（create/validate/build/publish）以及 manifest 校验器 @lingfang/plugin-sdk/manifest。类型入口 @lingfang/plugin-sdk/types/client-entry 供 client 插件的 TS 用户声明 window.sdk。

运行时依赖会被一并安装（含 @lingfang/contract）。nodejs 插件在 package.json 里声明 "@lingfang/plugin-sdk": "*" 即可（见 src/templates/nodejs/package.json.tmpl）。

发布（内部维护）

工作树按 main: src/index.ts 源码消费（monorepo 用）。对外发布用构建产物：

pnpm build:dist && pnpm pack:dist && npm publish ./dist

pack:dist 会将模板（src/templates/**）、README 拷入 dist/，并把 @lingfang/contract 依赖改写为真实 semver 范围、生成 bin 指向 ./cli/index.js 的 dist/package.json。