[English](./README.md) | [中文](./README.zh.md)

---

# Yonexus

Yonexus is an OpenClaw plugin for organization hierarchy and agent identity management.

## Features

- Organization hierarchy: `Organization -> Department -> Team -> Agent`
- Filesystem-backed resource layout under `${openclaw dir}/yonexus`
- Agent registration and multi-identity assignment
- Supervisor relationship mapping (does **not** imply permissions)
- Role-based authorization
- Query DSL: `eq | contains | regex`
- Queryable field whitelist via schema (`queryable: true`)
- Scope shared memory adapter (`org/dept/team`)
- JSON persistence for structure data
- Audit logs and structured error codes
- Import / export support

## Project Layout

```text
.
├─ plugin.json
├─ src/
│  ├─ index.ts
│  ├─ models/
│  ├─ permissions/
│  ├─ store/
│  ├─ tools/
│  ├─ memory/
│  └─ utils/
├─ scripts/
│  ├─ install.sh
│  └─ demo.ts
├─ tests/
│  └─ smoke.ts
├─ examples/
│  └─ sample-data.json
└─ dist/
   └─ yonexus/
```

## Requirements

- Node.js 22+
- npm 10+

## Quick Start

```bash
npm install
npm run build
bash scripts/install.sh
npm run test:smoke
npm run demo
```

## Configuration

`plugin.json` includes default config:

- `name`: `yonexus`
- `entry`: `dist/yonexus/index.js`
- `config.dataFile`: `./data/org.json`
- `config.registrars`: whitelist for registrar agents
- `config.schema`: metadata field schema and queryability

## Implemented APIs

Core:
- `createOrganization(actor, name)`
- `createDepartment(actor, name, orgId)`
- `createTeam(actor, name, deptId)`
- `registerAgent(actor, agentId, name, roles?)`
- `assignIdentity(actor, agentId, deptId, teamId, meta)`
- `setSupervisor(actor, agentId, supervisorId, deptId?)`
- `whoami(agentId)`
- `queryAgents(actor, scope, query)`

Management:
- `renameDepartment(actor, deptId, newName)`
- `renameTeam(actor, teamId, newName, deptId?)`
- `migrateTeam(actor, teamId, newDeptId)`
- `deleteDepartment(actor, deptId)`
- `deleteTeam(actor, teamId, deptId?)`

Docs:
- `getDocs(scope, topic, keyword)`

Data & audit:
- `exportData(actor)`
- `importData(actor, state)`
- `listAuditLogs(limit?, offset?)`

## Testing

Smoke test:

```bash
npm run test:smoke
```

## Notes

- Structure data is persisted in JSON, not memory_store.
- Shared scope memory is handled via the scope memory adapter.
- Unknown metadata fields are dropped during identity assignment.
- `queryAgents` enforces schema queryable constraints.