release: public alpha 0.6.0 baseline

2026-10-15 03:58:31 +08:00
commit d4242ae07c
238 changed files with 37724 additions and 0 deletions
@@ -0,0 +1,131 @@
+# SDK API Reference
+
+Package:
+
+```text
+jwebot-sdk
+```
+
+Current API version:
+
+```text
+1
+```
+
+## Event
+
+`Event` is the normalized incoming message exposed to extension code.
+
+Important fields:
+
+- `event_id`
+- `observed_at`
+- `sender`
+- `text`
+- `group_fingerprint`
+- `mention_bot`
+- `confidence`
+- `sender_confidence`
+- `body_confidence`
+- `source`
+
+`sender` is an untrusted display label. `group_fingerprint` binds kernel
+delivery safety but is not a selectable target.
+
+## ReplyPlan
+
+```python
+ReplyPlan.text("visible reply")
+ReplyPlan.no_reply()
+```
+
+Maximum visible text length is 900 characters.
+
+## Fact
+
+```python
+Fact(kind="topic", text="likes servers", confidence=0.8)
+```
+
+Facts are candidates. The kernel still applies scope, sensitivity, evidence,
+expiry, and deduplication policy.
+
+## ExtensionResult
+
+```python
+ExtensionResult(
+    reply=ReplyPlan.text("visible reply"),
+    facts=(Fact(...),),
+    metadata={"source": "plugin-id"},
+)
+```
+
+Limits:
+
+- at most 12 facts;
+- at most 16 metadata entries;
+- short string metadata only.
+
+## SingleGroupContext
+
+Protocols exposed through the context:
+
+- `commands`
+- `storage`
+- `http`
+- `services`
+- `facts`
+- `scheduler`
+- `logger`
+
+Not exposed:
+
+- GUI sender;
+- group selector;
+- raw OCR or screenshots;
+- ledger or SQLite;
+- filesystem;
+- environment;
+- subprocess or shell;
+- arbitrary sockets or HTTP;
+- credentials.
+
+## CommandRegistry
+
+```python
+context.commands.register("/hello", handler)
+```
+
+The registered command must be declared in `plugin.toml`. The Kernel catalog
+detects conflicts during startup and freezes before runtime routing.
+User-visible `description` and `help` metadata also live in `plugin.toml`;
+bundled `/功能列表` output is generated from the reviewed metadata rather than
+from handler code.
+
+## ApprovedHttpClient
+
+```python
+context.http.request(
+    "approved-profile",
+    method="GET",
+    path="/bounded/path",
+    query={"key": "value"},
+)
+```
+
+The kernel owns host allowlists, credentials, proxy, timeout, cache, and
+response limits. API version 1 does not expose a general-purpose URL client.
+
+## ApprovedServiceBroker
+
+```python
+context.services.call(
+    "reviewed-profile",
+    operation="execute",
+    payload={"bounded": "data"},
+)
+```
+
+Reviewed local adapters use named profiles to request Kernel-owned behavior without
+receiving raw Ledger, provider, process, or GUI objects. Undeclared or
+unconfigured profiles fail closed.