132 lines
2.4 KiB
Markdown
132 lines
2.4 KiB
Markdown
# 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.
|