convo-dev

README

convo-dev — Convo 插件开发脚手架

为 Convo（多平台大模型聚合网关）开发 wasm 插件所需的一切：convo-dev 脚手架 CLI + pdk SDK + 契约文档。

快速开始

# 安装脚手架命令（一次性）
go install github.com/bbsde/convo-dev@latest

# 生成插件项目（远程拉取本仓模板，无需 clone）
convo-dev init my_plugin
cd my_plugin
./build.sh          # TinyGo 编译（wasm→src/）+ cpk 打包（→dist/）

前置：Go ≥ 1.22 + TinyGo + convo 网关。

更新：convo-dev update（查 GitHub 最新 tag 并自更新；新 tag 推出后立即可更，不等代理索引）。

测试：convo-dev test（插件项目根目录跑）——静态检查 + 自动下载 convo 网关（缓存 ~/.convo-dev/gateway/）→ 临时实例安装 .cpk → echo 实调，测完自动清理；CONVO_DEV_GATEWAY=<路径> 可指定本地网关。

init 生成的项目结构：

my_plugin/
├── build.sh        # 构建脚本（wasm→src/，cpk→dist/）
├── dist/           # 分发包（my_plugin-<ver>.cpk；wasm 编译到 src/ 供目录加载）
├── docs/           # 项目文档（README 骨架 + NOTES 逆向笔记模板）
└── src/            # 源码
    ├── main.go     # OpenAI 兼容接入模板（echo + verify_key + chat 流式/非流式中继）
    ├── plugin.json # manifest（模型清单/表声明/chat_request_patch）
    ├── go.mod
    ├── migrations/ # SQLite 迁移（通用账号表标准列）
    └── ui/         # 插件管理 UI（添加账号全流程）

convo-dev init 选项：-d <dir> 目标目录、--ref <tag|分支> 拉指定版本模板（默认 main）、 --url <tarball> 镜像地址、--template <dir> 本地模板（离线）。convo-dev version 看版本。

插件能做什么

• 接入新平台：实现 /v1/chat/completions（真流式）、/v1/embeddings、/v1/images/generations、/v1/audio/speech、/v1/videos 任意组合——把任意 LLM 平台变成 Convo 的 OpenAI 兼容上游，自动获得多账号轮询、failover、熔断、用量统计。
• 自带管理 UI：单 HTML 内嵌 wasm，出现在 Convo 控制台里（添加账号、验证、状态展示）。
• 自建数据表：声明式 SQLite 迁移 + 通用账号表契约。
• 通用 action RPC：UI / 定时任务 / 账号级调用的自定义入口。

仓库结构

路径	说明
main.go + go.mod	convo-dev CLI 本体（go install github.com/bbsde/convo-dev@latest）
pdk/	插件 SDK（独立 Go module github.com/bbsde/convo-dev/pdk），wasm↔host 的全部 ABI 封装
template/	项目模板（CLI 远程拉取的源）：src/ 源码 + AGENTS.md + build.sh + docs/（契约文档四篇 + README/NOTES 骨架，随 init 进入每个插件项目）
docs/releasing.md	发布与版本管理（CLI/pdk 双 tag 序列、模板版本对齐、pdk 升级检查单）——面向本仓维护者，不随项目分发

先读 template/docs/rules.md

里面每条约定都对应真实事故（wasm 运行期崩溃、线性内存打穿、内置浏览器 404……）。脚手架模板已按约定写好，改写时别把防护改没了。（convo-dev init 后它就在你项目的 docs/rules.md。）

分发

• 自由插件：无 license 字段，打包 .cpk 即可分发。
• 付费插件：上传 Convo 插件市场定价销售，license 由市场在线签发（Ed25519 验签，绑定 wasm 指纹）。

许可

MIT © 2026 bbsde

Documentation

Overview

httpclient.go — 共享 HTTP client：代理感知（环境变量优先，Windows 系统代理兜底）。

init.go — convo-dev init：生成插件项目（远程拉取本仓 template/ 或本地模板）。

convo-dev 是 convo 插件脚手架与环境配置 CLI。

安装：

go install github.com/bbsde/convo-dev@latest

命令：

convo-dev init <name>              # 生成插件项目（远程拉模板；详见 convo-dev init -h）
convo-dev doctor                   # 环境体检：检查 go / tinygo / wasm-opt 并报告
convo-dev setup                    # 自动安装缺失工具（TinyGo / binaryen → ~/.convo-dev/tools）
convo-dev env                      # 输出 shell 集成行（eval "$(convo-dev env)"）
convo-dev update                   # 自更新到最新版（查 GitHub tag → go install）
convo-dev version

init 生成的项目结构（模板占位符 __PLUGIN_NAME__ 会被替换为 <name>）：

<name>/
├── AGENTS.md     # AI agent 工作指引（规范速查 + 必读文档索引）
├── build.sh      # tidy + TinyGo 编译（wasm 落 src/）+ cpk 打包（进 dist/）
├── dist/         # 分发包（<name>-<ver>.cpk；wasm 编译到 src/ 供目录加载）
├── docs/         # 项目文档（README 骨架 + NOTES 逆向笔记模板）
└── src/          # 源码：main.go / plugin.json / go.mod / migrations/ / ui/

setup.go — convo-dev doctor/setup/env：插件开发环境体检与自动配置。

工具安装约定：全部落 ~/.convo-dev/tools/<name>/（用户级，不动系统目录、不要管理员权限）：

~/.convo-dev/tools/tinygo/bin/tinygo(.exe)      TINYGOROOT = ~/.convo-dev/tools/tinygo
~/.convo-dev/tools/binaryen/bin/wasm-opt(.exe)

PATH 集成用 `eval "$(convo-dev env)"`；生成的项目 build.sh 也会自动探测该目录。

test.go — convo-dev test：静态检查 + 真实网关冒烟（一条命令完成"编译→装→验"闭环）。

流程：

1. 静态检查（无需网关）：plugin.json 校验（name/表名标识符/models）、sync 原语扫描、wasm 存在
2. 网关准备：~/.convo-dev/gateway/ 缓存 → 无则按公共 Release latest.json 下载（代理感知）+ sha256 校验
3. 冒烟：临时数据目录启动 convo（随机端口）→ 等 health → install-cpk 上传 → echo 实调
4. 清理：杀进程、删临时目录（网关缓存保留）

update.go — convo-dev update：检查 GitHub 最新 tag 并自更新。

util.go — 共享工具：文件树复制、下载、解压、镜像与杂项。