JWeBot/docs/author-guide.md

Extension Author Guide

JWeBot extensions are reviewed Python packages for one preselected WeChat group. They do not receive WeChat GUI access or server credentials.

Create A Command Extension

From the repository root:

./tools/create-plugin.py weather-command /weather \
  --author FriendName \
  --description "查询指定城市天气" \
  --help-entry "/weather 城市"

This creates:

extensions/friends/weather-command/
  plugin.toml
  README.md
  src/weather_command.py
  tests/test_plugin.py

The generator refuses invalid IDs, invalid command names, and existing destinations. The required author and user-facing description/help metadata are recorded in plugin.toml. The Kernel uses that metadata to generate help.

Implement Behavior

The handler receives:

def handle(event: Event, arguments: str) -> ExtensionResult:
    ...

Return:

ExtensionResult(reply=ReplyPlan.text("result"))

Use ReplyPlan.no_reply() when no visible response is appropriate.

Do not return raw strings or call a sender.

Request Capabilities

Declare only what the extension needs:

author = "FriendName"
description = "查询指定城市天气"
help = ["/weather 城市"]

[capabilities]
commands = ["/weather"]
storage = false
network_profiles = []

Network access requires a separately reviewed named profile. Never put an API key in source, tests, manifest, logs, or README.

The plugin entrypoint registers exactly the commands declared in the manifest. Registration freezes at startup; runtime command mutation is rejected.

Test Locally

Validate the manifest:

./tools/validate-plugin.py extensions/friends/weather-command/plugin.toml

Run the repository gate:

./tools/check-local.sh

On Python earlier than 3.11, install requirements-dev.txt so TOML validation uses tomli.

Submit

1. Create a branch.
2. Add the extension, tests, and README.
3. Run the local gate.
4. Open a PR in the Git hosting repository.
5. Explain every requested command, storage permission, and network profile.
6. Wait for capability and code review.

Merge does not imply immediate production activation. A reviewed publisher must sign the canonical release record with a key that is not available to extension code. Production provisioning and isolated-host activation remain separately controlled steps.

Review Checklist

• Uses only imports from jwebot_sdk plus Python pure-data helpers.
• Returns structured plans.
• Does not read environment variables or files.
• Does not use subprocess, sockets, SSH, Docker, VNC, or GUI APIs.
• Does not accept or construct a target group.
• Does not log message bodies or secrets.
• Has deterministic tests for success and failure behavior.
• Manifest matches registered commands exactly.