108 lines
2.3 KiB
Markdown
108 lines
2.3 KiB
Markdown
[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 中标记为可查询。
|