For AI agents: the complete documentation index is available at https://payhon.github.io/AppKernia/en-US/llms.txt, the full documentation bundle is available at https://payhon.github.io/AppKernia/en-US/llms-full.txt, and this page is available as Markdown at https://payhon.github.io/AppKernia/en-US/guide/plugin-development.md.
AppKernia

Plugin development (source preview)

This guide covers the plugin kernel under development, not the published 0.5.0-preview.3 binary. The product has not been upgraded to 1.0.0; server-side plugin management APIs and the complete Capability set are not available yet.

Run your first local plugin

Build from the repository source with Go 1.26.5. No npm publishing token is needed.

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

A successful run prints JSON containing production_isolation: false and a 200 Hello response. Without --call, it runs until Ctrl+C. The harness uses a temporary control database and random test identities; it does not read deployed Core configuration, credentials, or data. Shutdown revokes the Session and removes its temporary runtime directory. The sample project and signing files remain in plugin_workspace for further development; retain or remove them as appropriate.

Development mode has no production sandbox. Run only local plugins you trust. Production mode currently refuses to start on every platform. The Linux systemd/cgroup v2, bubblewrap, namespace, and seccomp integration is not complete.

Projects, signatures, and protocol

  • manifest.json receives a random permanent pluginId at project creation. Do not regenerate it on each build.
  • --sdk-dir uses server/pkg/plugin from this checkout. The public 1.0.0 SDK is not published, so retain the local replace directive.
  • build compiles the native targets declared in the Manifest. Both pack and sign create a signed .akp ZIP from the project; they do not mutate existing packages.
  • Private keys default to mode 0600. Keep them outside the project and out of Git. Packaging includes only Manifest-referenced payloads and explicit documentation, not the entire working tree.
  • Signatures cover the Manifest and all payload files. Validation rejects traversal, links, duplicate paths, digest tampering, unsupported targets, and invalid native executable formats.
  • The Go SDK uses TLS/gRPC. A single-use Bootstrap Token arrives through stdin, never command-line arguments or core.json. Request/response buffers are bounded; unbounded streams and plugin WebSockets are not supported.
  • CLI text defaults to zh-CN; set AK_LOCALE=en-US for English. Protocol fields and error codes remain stable.

Checks and current boundaries

cd server
make test-plugins
# Run the PostgreSQL control-plane lifecycle against a dedicated test database:
# AK_PLUGIN_TEST_PG_DSN='...' make test-plugins

The PostgreSQL test creates and removes a random test Schema in the selected database. Do not point it at production. Default checks cover the SQLite authorizer, chunking/cancellation through real subprocesses, development lifecycle, and restart recovery. They do not establish complete Capability support, production isolation, or native Windows acceptance.

Generated Protobuf sources are included in the source tree. Regeneration is not needed for normal builds. After editing the protocol, use protoc 36.1, protoc-gen-go 1.36.12, and protoc-gen-go-grpc 1.6.2 with make plugin-protocol.

Outstanding work includes plugin service APIs, tenant activation/grants, PostgreSQL business-data isolation, the complete Capability set, migration backups, Linux isolation, and all plugin management commands. SQLite API Clients and multi-server profiles are now implemented in source; see remote clients. The full checklist is in docs/plan/PLUGIN_IMPLEMENTATION_ADDENDUM.md. Installation channels still point to existing preview artifacts; see Install and deploy akone.