112 lines
2.8 KiB
Markdown
112 lines
2.8 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
./tools/create-plugin.py weather-command /weather \
|
|
--author FriendName \
|
|
--description "查询指定城市天气" \
|
|
--help-entry "/weather 城市"
|
|
```
|
|
|
|
This creates:
|
|
|
|
```text
|
|
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:
|
|
|
|
```python
|
|
def handle(event: Event, arguments: str) -> ExtensionResult:
|
|
...
|
|
```
|
|
|
|
Return:
|
|
|
|
```python
|
|
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:
|
|
|
|
```toml
|
|
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:
|
|
|
|
```sh
|
|
./tools/validate-plugin.py extensions/friends/weather-command/plugin.toml
|
|
```
|
|
|
|
Run the repository gate:
|
|
|
|
```sh
|
|
./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.
|