Yonexus/README.zh.md

English | 中文

---

Yonexus

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

功能特性

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

项目结构

.
├─ 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+

快速开始

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?)

测试

冒烟测试：

npm run test:smoke

说明

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