# 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.