release: public alpha 0.6.0 baseline

docs/author-guide.md

@@ -0,0 +1,111 @@
+# 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.