docs: add bilingual README with top language navigation
This commit is contained in:
124
README.md
124
README.md
@@ -1,14 +1,54 @@
|
|||||||
# Yonexus (MVP foundation)
|
[English](./README.md) | [中文](./README.zh.md)
|
||||||
|
|
||||||
OpenClaw plugin foundation for:
|
---
|
||||||
- Organization hierarchy (Org/Dept/Team)
|
|
||||||
- Agent registration + multi-identity
|
# Yonexus
|
||||||
- Supervisor mapping
|
|
||||||
|
Yonexus is an OpenClaw plugin for organization hierarchy and agent identity management.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- Organization hierarchy: `Organization -> Department -> Team -> Agent`
|
||||||
|
- Agent registration and multi-identity assignment
|
||||||
|
- Supervisor relationship mapping (does **not** imply permissions)
|
||||||
- Role-based authorization
|
- Role-based authorization
|
||||||
- Query DSL (`eq | contains | regex`) with schema queryable guard
|
- Query DSL: `eq | contains | regex`
|
||||||
- Scoped shared memory adapter (compatible with memory tools)
|
- 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
|
||||||
|
|
||||||
## Quick start
|
## 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
|
```bash
|
||||||
npm install
|
npm install
|
||||||
@@ -18,32 +58,50 @@ npm run test:smoke
|
|||||||
npm run demo
|
npm run demo
|
||||||
```
|
```
|
||||||
|
|
||||||
## Current status
|
## Configuration
|
||||||
|
|
||||||
Implemented in this branch:
|
`plugin.json` includes default config:
|
||||||
- Data models + JSON persistence store
|
|
||||||
- Permission checker `authorize(action, actor, scope)`
|
- `name`: `yonexus`
|
||||||
- Core APIs:
|
- `entry`: `dist/yonexus/index.js`
|
||||||
- `createDepartment`
|
- `config.dataFile`: `./data/org.json`
|
||||||
- `createTeam`
|
- `config.registrars`: whitelist for registrar agents
|
||||||
- `registerAgent`
|
- `config.schema`: metadata field schema and queryability
|
||||||
- `assignIdentity`
|
|
||||||
- `setSupervisor`
|
## Implemented APIs
|
||||||
- `whoami`
|
|
||||||
- `queryAgents`
|
Core:
|
||||||
- Query parser/executor with pagination
|
- `createDepartment(actor, name, orgId)`
|
||||||
- Scope memory adapter (`put/search`)
|
- `createTeam(actor, name, deptId)`
|
||||||
- Management APIs:
|
- `registerAgent(actor, agentId, name, roles?)`
|
||||||
- `renameDepartment`
|
- `assignIdentity(actor, agentId, deptId, teamId, meta)`
|
||||||
- `renameTeam`
|
- `setSupervisor(actor, agentId, supervisorId, deptId?)`
|
||||||
- `migrateTeam`
|
- `whoami(agentId)`
|
||||||
- `deleteDepartment`
|
- `queryAgents(actor, scope, query)`
|
||||||
- `deleteTeam`
|
|
||||||
- Error code model (`YonexusError`) and audit logs
|
Management:
|
||||||
- Import/export APIs (`importData` / `exportData`)
|
- `renameDepartment(actor, deptId, newName)`
|
||||||
|
- `renameTeam(actor, teamId, newName, deptId?)`
|
||||||
|
- `migrateTeam(actor, teamId, newDeptId)`
|
||||||
|
- `deleteDepartment(actor, deptId)`
|
||||||
|
- `deleteTeam(actor, teamId, deptId?)`
|
||||||
|
|
||||||
|
Data & audit:
|
||||||
|
- `exportData(actor)`
|
||||||
|
- `importData(actor, state)`
|
||||||
|
- `listAuditLogs(limit?, offset?)`
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
Smoke test:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run test:smoke
|
||||||
|
```
|
||||||
|
|
||||||
## Notes
|
## Notes
|
||||||
|
|
||||||
- Persistence file defaults to `data/org.json`.
|
- Structure data is persisted in JSON, not memory_store.
|
||||||
- Meta fields are validated against schema; unknown fields are dropped.
|
- Shared scope memory is handled via the scope memory adapter.
|
||||||
- Supervisor relation does not imply permissions.
|
- Unknown metadata fields are dropped during identity assignment.
|
||||||
|
- `queryAgents` enforces schema queryable constraints.
|
||||||
|
|||||||
107
README.zh.md
Normal file
107
README.zh.md
Normal file
@@ -0,0 +1,107 @@
|
|||||||
|
[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 中标记为可查询。
|
||||||
Reference in New Issue
Block a user