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

---

# Yonexus

Yonexus 是一个用于 OpenClaw 的组织结构与 Agent 身份管理插件。

## 功能特性

- 组织层级：`Organization -> Department -> Team -> Agent`
- Agent 注册与多身份（Identity）管理
- 上下级关系（Supervisor，**不自动赋权**）
- 基于角色的权限控制
- Query DSL：`eq | contains | regex`
- 基于 schema 的可查询字段白名单（`queryable: true`）
- scope 共享记忆适配（org/dept/team）
- 结构化数据 JSON 持久化
- 审计日志与结构化错误码
- 导入 / 导出能力

## 项目结构

```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/
```

## 环境要求

- Node.js 22+
- npm 10+

## 快速开始

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

## 配置说明

`plugin.json` 默认包含以下配置：

- `name`: `yonexus`
- `entry`: `dist/yonexus/index.js`
- `config.dataFile`: `./data/org.json`
- `config.registrars`: 注册人白名单
- `config.schema`: 元数据字段定义与可查询性

## 已实现 API

核心 API：
- `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)`

管理 API：
- `renameDepartment(actor, deptId, newName)`
- `renameTeam(actor, teamId, newName, deptId?)`
- `migrateTeam(actor, teamId, newDeptId)`
- `deleteDepartment(actor, deptId)`
- `deleteTeam(actor, teamId, deptId?)`

数据与审计：
- `exportData(actor)`
- `importData(actor, state)`
- `listAuditLogs(limit?, offset?)`

## 测试

冒烟测试：

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

## 说明

- 结构数据保存在 JSON 文件，不进入 memory_store。
- 共享记忆通过 scope memory 适配器处理。
- 分配 identity 时，未知 meta 字段会被丢弃。
- `queryAgents` 会严格校验字段是否在 schema 中标记为可查询。