插件开发（源码预览）

本页针对正在开发的插件内核，不适用于已发布的 0.5.0-preview.3 二进制。产品版本尚未升级到 1.0.0，服务端插件管理 API 和完整 Capability 尚未开放。

运行第一个本地插件

在仓库根目录构建当前源码。需要 Go 1.26.5；无需 npm 发布令牌。

cd server
GOTOOLCHAIN=go1.26.5 go build -o ./bin/akone ./cmd/akone
akone_path="$PWD/bin/akone"
sdk_path="$PWD"
plugin_workspace=$(mktemp -d)

"$akone_path" plugin init --dir "$plugin_workspace/hello" --sdk-dir "$sdk_path"
"$akone_path" plugin validate --dir "$plugin_workspace/hello"
"$akone_path" plugin keygen --output "$plugin_workspace/development.key"
"$akone_path" plugin build --dir "$plugin_workspace/hello"
"$akone_path" plugin pack --dir "$plugin_workspace/hello" \
  --key "$plugin_workspace/development.key" --output "$plugin_workspace/hello.akp"
"$akone_path" plugin dev --package "$plugin_workspace/hello.akp" \
  --public-key "$plugin_workspace/development.key.pub" --call hello

成功时输出结构化 JSON，包含 production_isolation: false 和 Hello 路由的 200 响应。不传 --call 时保持运行，按 Ctrl+C 停止。dev 使用独立临时控制库与随机测试身份，不读取已部署 Core 的配置、凭据或数据；退出自动注销 Session 并删除运行时临时目录。上例创建的开发工程和签名文件留在 plugin_workspace，便于继续修改，需自行妥善保管或清理。

开发模式没有生产沙箱。只运行自己信任的本地插件，不运行来历不明的制品。 当前所有平台的生产模式都拒绝启动；Linux 的 systemd/cgroup v2、bubblewrap、namespace 和 seccomp 组合尚未完成。

工程、签名与协议

manifest.json 中的 pluginId 在创建时随机生成并永久保存，不要在每次构建时更换。
--sdk-dir 使用当前仓库的 server/pkg/plugin SDK。公开 1.0.0 SDK 尚未发布，当前不能删除本地 replace 后期待下载成功。
build 为 Manifest 中声明的目标构建原生二进制；pack 和 sign 均从工程生成已签名 .akp ZIP，不修改既有制品。
私钥默认权限为 0600，必须放在工程外，不能进入 Git。打包只收集 Manifest 引用的文件及显式文档，不递归打包工作树。
验签覆盖 Manifest 与全部有效载荷；拒绝路径穿越、链接、重复路径、摘要篡改、错误平台和无效原生可执行格式。
Go SDK 使用 TLS/gRPC；Bootstrap Token 从标准输入管道单次消费，不进入参数或 core.json。普通请求体与响应均有界，不支持无限流或插件 WebSocket。
CLI 文案默认 zh-CN，可通过 AK_LOCALE=en-US 切换；协议字段与错误码不随语言改变。

验证与当前边界

cd server
make test-plugins
# 使用专用测试数据库可额外执行 PostgreSQL 控制面生命周期测试：
# AK_PLUGIN_TEST_PG_DSN='...' make test-plugins

PostgreSQL 测试只在指定库中新建和清理随机测试 Schema，不应指向生产数据库。默认测试包括 SQLite 授权器隔离、真实子进程的分块/取消、开发生命周期和重启恢复。它们不代表完整 Capability、生产隔离或 Windows 原生验收。

源码目录已经包含生成的 Protobuf 文件，无需每次构建重新生成。修改协议后，用 protoc 36.1、protoc-gen-go 1.36.12 和 protoc-gen-go-grpc 1.6.2 执行 make plugin-protocol。

下一阶段仍需完成插件服务 API、租户激活/授权、PostgreSQL 业务数据隔离、完整 Capability、迁移备份、Linux 隔离及全部插件管理命令。SQLite API Client 和多服务器 Profile 已在当前源码补齐，见远程客户端指南。完整清单保存在仓库 docs/plan/PLUGIN_IMPLEMENTATION_ADDENDUM.md。当前安装渠道仍使用已有预览制品，见 akone 安装与部署。

#插件开发（源码预览）

#运行第一个本地插件

#工程、签名与协议

#验证与当前边界

插件开发（源码预览）

运行第一个本地插件

工程、签名与协议

验证与当前边界