release: public alpha 0.6.0 baseline
This commit is contained in:
JWeBot Contributors
@@ -0,0 +1,176 @@
|
||||
# Configuration Guide
|
||||
|
||||
JWeBot configuration is a versioned profile package compiled into runtime
|
||||
files. Source checkout paths and Git history never contain a populated profile.
|
||||
|
||||
## Storage
|
||||
|
||||
Defaults:
|
||||
|
||||
| Purpose | Path |
|
||||
|---|---|
|
||||
| Profiles | `~/.config/jwebot/profiles/` |
|
||||
| Active profile | `~/.config/jwebot/current` |
|
||||
| Generated runtime | `~/.config/jwebot/current/generated/` |
|
||||
| Private state | `~/.local/state/jwebot/profiles/<profile>/` |
|
||||
|
||||
Override roots with `JWEBOT_CONFIG_ROOT` and `JWEBOT_CONFIG_STATE_ROOT`.
|
||||
|
||||
## Lifecycle
|
||||
|
||||
Create:
|
||||
|
||||
```sh
|
||||
./tools/jwebot-config.py init personal
|
||||
```
|
||||
|
||||
Validate and activate:
|
||||
|
||||
```sh
|
||||
./tools/jwebot-config.py validate personal
|
||||
./tools/jwebot-config.py activate personal
|
||||
```
|
||||
|
||||
Import:
|
||||
|
||||
```sh
|
||||
./tools/jwebot-config.py import /protected/profile.tar.gz --activate
|
||||
```
|
||||
|
||||
Redacted export:
|
||||
|
||||
```sh
|
||||
./tools/jwebot-config.py export personal \
|
||||
--output /tmp/personal-redacted.tar.gz
|
||||
```
|
||||
|
||||
The compiler validates every component, writes a temporary `generated`
|
||||
directory, records SHA-256 digests in `manifest.json`, and renames it
|
||||
atomically. Services never read partially generated config.
|
||||
|
||||
## Components
|
||||
|
||||
### Bot
|
||||
|
||||
`components/bot.toml` controls:
|
||||
|
||||
- `JWEBOT_BOT_MENTION`;
|
||||
- the private identity note written to `JWEBOT_PRIVATE_CONTEXT_FILE`;
|
||||
- cloud agent name;
|
||||
- bounded remote memory path.
|
||||
|
||||
### Providers
|
||||
|
||||
`components/providers.toml` controls:
|
||||
|
||||
- DeepSeek base URL;
|
||||
- optional cloud host;
|
||||
- Steam owner ID;
|
||||
- mandatory loopback Steam proxy.
|
||||
|
||||
API keys belong only in `secrets/runtime.env`:
|
||||
|
||||
```ini
|
||||
JWEBOT_EDGE_DEEPSEEK_API_KEY=
|
||||
JWEBOT_EDGE_STEAM_API_KEY=
|
||||
```
|
||||
|
||||
Steam uses `JWEBOT_EDGE_STEAM_ID64` and
|
||||
`JWEBOT_EDGE_STEAM_PROXY_URL`. No source file contains a fixed friend roster.
|
||||
|
||||
### Runtime
|
||||
|
||||
`components/runtime.toml` controls:
|
||||
|
||||
- Edge and local extension enablement;
|
||||
- telemetry and OCR prewarm;
|
||||
- delivery enablement;
|
||||
- extension mode and transport;
|
||||
- publisher principal;
|
||||
- Host timeout and fallback;
|
||||
- GUI sender timeout.
|
||||
|
||||
### Debug
|
||||
|
||||
`components/debug.toml` generates:
|
||||
|
||||
- `JWEBOT_DEBUG_ENABLED`;
|
||||
- `JWEBOT_DEBUG_CAPTURE_PAYLOADS`;
|
||||
- `JWEBOT_DEBUG_INCIDENT_RETENTION_DAYS`;
|
||||
- `JWEBOT_DEBUG_SESSION_RETENTION_DAYS`;
|
||||
- `JWEBOT_DEBUG_INCIDENT_ROOT`;
|
||||
- `JWEBOT_DEBUG_SESSION_ROOT`.
|
||||
|
||||
Message bodies, sender names, raw group identifiers, provider payloads, and
|
||||
environment values remain forbidden in telemetry and public incident records.
|
||||
Schemas live in `config/schemas/`.
|
||||
|
||||
### Notification
|
||||
|
||||
`components/notification.toml` compiles to the file referenced by
|
||||
`JWEBOT_HEALTH_NOTIFICATION_CONFIG`.
|
||||
|
||||
The adapter is an absolute argv array. JWeBot does not invoke a shell. The
|
||||
notification body is supplied on stdin, and a zero exit status confirms
|
||||
delivery. Provider credentials belong in the secret environment.
|
||||
|
||||
### Deployment
|
||||
|
||||
`components/deployment.toml` generates root-only values:
|
||||
|
||||
- `JWEBOT_RUNTIME_USER`;
|
||||
- `JWEBOT_RUNTIME_HOME`;
|
||||
- `JWEBOT_RUNTIME_PYTHON`;
|
||||
- `JWEBOT_PRODUCTION_BACKUP_ROOT`.
|
||||
|
||||
The generated file is `current/generated/root.env`. Root deployment tooling
|
||||
may source only this validated file.
|
||||
|
||||
### Private Context
|
||||
|
||||
`context/people.json` contains person aliases, optional identity facts, display
|
||||
IDs, and clock targets. It compiles to `JWEBOT_PRIVATE_CONTEXT_FILE`.
|
||||
|
||||
Each person may also define a private `steam_id64` and `steam_aliases`. When at
|
||||
least one mapping is present, Steam status and playtime are strictly scoped to
|
||||
those mapped people and use their group display IDs. With no private mapping,
|
||||
the provider falls back to public friend discovery.
|
||||
|
||||
This file is local-only PII. Default export removes all entries.
|
||||
|
||||
### Overrides
|
||||
|
||||
`overrides/runtime.env` accepts non-secret `JWEBOT_*` and `WECHAT_*` values.
|
||||
`overrides/root.env` accepts deployment overrides. Secret-shaped keys are
|
||||
rejected from runtime overrides and must live under `secrets/`.
|
||||
|
||||
## Legacy Migration
|
||||
|
||||
```sh
|
||||
./tools/jwebot-config.py migrate-legacy personal \
|
||||
--repository /path/to/old/checkout \
|
||||
--environment /protected/legacy/environment \
|
||||
--activate
|
||||
```
|
||||
|
||||
The migration:
|
||||
|
||||
1. archives root-level debug, incident, report, and operations material;
|
||||
2. converts static aliases and bot identity into private context;
|
||||
3. separates secret environment keys from non-secret overrides;
|
||||
4. compiles and activates the profile;
|
||||
5. leaves the source checkout unchanged.
|
||||
|
||||
## Runtime Compatibility
|
||||
|
||||
The Edge CLI still reads the former
|
||||
`~/.config/wechat-health-watch/environment` only as a compatibility fallback.
|
||||
New systemd units use the generated profile directly.
|
||||
|
||||
## Validation
|
||||
|
||||
```sh
|
||||
./tools/check-config.sh
|
||||
./tools/check-secrets.py
|
||||
PATH="$PWD/.venv/bin:$PATH" ./tools/check-local.sh
|
||||
```
|
||||
Reference in New Issue
Block a user