243 lines
5.3 KiB
Markdown
243 lines
5.3 KiB
Markdown
# Yonexus.Client — Scaffold Plan
|
|
|
|
This document refines the repository structure into concrete planned files and responsibilities.
|
|
|
|
## 1. Planned Tree
|
|
|
|
```text
|
|
.
|
|
├── plugin/
|
|
│ ├── core/
|
|
│ │ ├── localState.ts
|
|
│ │ ├── keys.ts
|
|
│ │ ├── pairing.ts
|
|
│ │ ├── auth.ts
|
|
│ │ ├── heartbeat.ts
|
|
│ │ ├── dispatch.ts
|
|
│ │ └── errors.ts
|
|
│ ├── hooks/
|
|
│ │ ├── onGatewayStart.ts
|
|
│ │ └── onGatewayStop.ts
|
|
│ ├── commands/
|
|
│ │ ├── showStatus.ts
|
|
│ │ ├── reconnect.ts
|
|
│ │ └── resetTrust.ts
|
|
│ ├── tools/
|
|
│ │ ├── sendMessageToServer.ts
|
|
│ │ └── getConnectionState.ts
|
|
│ ├── index.ts
|
|
│ └── openclaw.plugin.json
|
|
├── skills/
|
|
│ └── ...
|
|
├── servers/
|
|
│ └── clientRuntime.ts
|
|
├── scripts/
|
|
│ └── install.mjs
|
|
├── protocol/
|
|
│ └── ... (submodule)
|
|
├── PLAN.md
|
|
├── STRUCTURE.md
|
|
└── SCAFFOLD.md
|
|
```
|
|
|
|
This is a planning scaffold, not yet an implementation commitment down to exact filenames. Names may evolve, but responsibilities should remain stable.
|
|
|
|
---
|
|
|
|
## 2. `plugin/index.ts`
|
|
|
|
`plugin/index.ts` is wiring only.
|
|
|
|
Planned responsibilities:
|
|
- import client core modules
|
|
- import hooks
|
|
- import commands
|
|
- import tools
|
|
- initialize client runtime container
|
|
- register hooks with OpenClaw
|
|
- register commands with OpenClaw
|
|
- register tools with OpenClaw
|
|
|
|
Design rule:
|
|
- no reconnect/auth/pairing business logic should live directly in this file
|
|
|
|
---
|
|
|
|
## 3. `plugin/openclaw.plugin.json`
|
|
|
|
Planned manifest responsibilities:
|
|
- define plugin name: `Yonexus.Client`
|
|
- define entrypoint
|
|
- declare version
|
|
- define config schema / default config shape
|
|
- declare plugin metadata
|
|
- declare permissions if needed
|
|
|
|
### Planned Config Shape
|
|
|
|
```json
|
|
{
|
|
"mainHost": "",
|
|
"identifier": "",
|
|
"notifyBotToken": "",
|
|
"adminUserId": ""
|
|
}
|
|
```
|
|
|
|
### Planned Validation Expectations
|
|
|
|
- `mainHost` must be required
|
|
- `identifier` must be required
|
|
- `mainHost` should be a valid WebSocket endpoint
|
|
|
|
---
|
|
|
|
## 4. `plugin/core/`
|
|
|
|
### `localState.ts`
|
|
Planned responsibilities:
|
|
- load/save client local trust state
|
|
- persist secret and timestamps
|
|
- manage current pairing/auth state
|
|
|
|
### `keys.ts`
|
|
Planned responsibilities:
|
|
- generate Ed25519 keypair
|
|
- load/save encoded keys
|
|
- sign auth proof payloads
|
|
|
|
### `pairing.ts`
|
|
Planned responsibilities:
|
|
- track pending pairing flow
|
|
- accept human-provided pairing code
|
|
- send pair_confirm
|
|
- store secret after pair_success
|
|
|
|
### `auth.ts`
|
|
Planned responsibilities:
|
|
- construct proof payload
|
|
- create signature
|
|
- send auth_request
|
|
- handle auth_success/auth_failed
|
|
- react to re_pair_required
|
|
|
|
### `heartbeat.ts`
|
|
Planned responsibilities:
|
|
- schedule heartbeat loop
|
|
- stop loop on disconnect
|
|
- handle optional heartbeat_ack
|
|
|
|
### `dispatch.ts`
|
|
Planned responsibilities:
|
|
- builtin message routing
|
|
- application rule registry
|
|
- inbound message dispatch
|
|
- sendMessageToServer routing
|
|
|
|
### `errors.ts`
|
|
Planned responsibilities:
|
|
- typed/structured error definitions
|
|
- standard client-side error codes
|
|
|
|
---
|
|
|
|
## 5. `plugin/hooks/`
|
|
|
|
### `onGatewayStart.ts`
|
|
Planned responsibilities:
|
|
- initialize local state
|
|
- ensure keypair exists
|
|
- start client runtime
|
|
- attempt initial connection
|
|
|
|
### `onGatewayStop.ts`
|
|
Planned responsibilities:
|
|
- stop heartbeat
|
|
- close socket gracefully
|
|
- persist final state if needed
|
|
|
|
---
|
|
|
|
## 6. `plugin/commands/`
|
|
|
|
These are optional in early versions, but the directory should exist.
|
|
|
|
Potential first commands:
|
|
- `showStatus.ts` — inspect connection/auth/pairing status
|
|
- `reconnect.ts` — manually trigger reconnect
|
|
- `resetTrust.ts` — clear local secret and force re-pair
|
|
|
|
---
|
|
|
|
## 7. `plugin/tools/`
|
|
|
|
Potential first tools:
|
|
- `sendMessageToServer.ts`
|
|
- `getConnectionState.ts`
|
|
|
|
These should wrap core logic, not duplicate it.
|
|
|
|
---
|
|
|
|
## 8. `servers/`
|
|
|
|
### `clientRuntime.ts`
|
|
Planned responsibilities:
|
|
- manage WebSocket client runtime
|
|
- manage reconnect/backoff loop
|
|
- broker raw send/receive with server
|
|
|
|
Design rule:
|
|
- even though the client is not primarily a server, runtime/service bootstrap code still belongs in `servers/` for structural consistency
|
|
- reusable logic remains in `plugin/core/`
|
|
|
|
---
|
|
|
|
## 9. `skills/`
|
|
|
|
Initial version may keep this minimal.
|
|
|
|
Possible future skill topics:
|
|
- reconnect troubleshooting
|
|
- pairing recovery
|
|
- auth debugging guidance
|
|
|
|
---
|
|
|
|
## 10. `scripts/install.mjs`
|
|
|
|
Planned CLI responsibilities:
|
|
- `--install`
|
|
- `--uninstall`
|
|
- `--openclaw-profile-path <path>`
|
|
|
|
Planned install behavior:
|
|
- build output copied into the OpenClaw plugin directory
|
|
- install target path determined by profile path
|
|
|
|
Planned uninstall behavior:
|
|
- remove installed plugin directory
|
|
- optionally clean local client config if explicitly desired later
|
|
|
|
---
|
|
|
|
## 11. Initial Bring-Up Order
|
|
|
|
Recommended first implementation order:
|
|
1. manifest + `plugin/index.ts`
|
|
2. `servers/clientRuntime.ts`
|
|
3. `plugin/core/localState.ts`
|
|
4. hello / hello_ack routing
|
|
5. pairing flow
|
|
6. auth flow
|
|
7. heartbeat
|
|
8. commands/tools
|
|
|
|
---
|
|
|
|
## 12. Notes
|
|
|
|
- `protocol/` is the single protocol source of truth; do not duplicate protocol docs in this repo.
|
|
- File names can change, but the wiring/core/service separation should remain.
|
|
- `servers/` should exist even if early client runtime is lightweight.
|