08a66d7659
- Move src/ → plugin/ with subdirectories: - plugin/core/ (business logic, models, store, permissions, utils, memory) - plugin/tools/ (query, resources) - plugin/commands/ (placeholder for slash commands) - plugin/hooks/ (placeholder for lifecycle hooks) - plugin/index.ts (wiring layer only, no business logic) - Add install.mjs with --install, --uninstall, --openclaw-profile-path - Add skills/ and docs/ root directories - Move planning docs (PLAN.md, FEAT.md, AGENT_TASKS.md) to docs/ - Remove old scripts/install.sh - Update tsconfig rootDir: src → plugin - Update README.md and README.zh.md with new layout - Bump version to 0.2.0 - All tests pass
119 lines
3.0 KiB
Markdown
119 lines
3.0 KiB
Markdown
[English](./README.md) | [中文](./README.zh.md)
|
||
|
||
---
|
||
|
||
# Yonexus
|
||
|
||
Yonexus 是一个用于 OpenClaw 的组织结构与 Agent 身份管理插件。
|
||
|
||
## 功能特性
|
||
|
||
- 组织层级：`Organization -> Department -> Team -> Agent`
|
||
- 基于文件系统的资源目录：`${openclaw dir}/yonexus`
|
||
- Agent 注册与多身份（Identity）管理
|
||
- 上下级关系（Supervisor，**不自动赋权**）
|
||
- 基于角色的权限控制
|
||
- Query DSL：`eq | contains | regex`
|
||
- 基于 schema 的可查询字段白名单（`queryable: true`）
|
||
- scope 共享记忆适配（org/dept/team）
|
||
- 结构化数据 JSON 持久化
|
||
- 审计日志与结构化错误码
|
||
- 导入 / 导出能力
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
.
|
||
├─ plugin/
|
||
│ ├─ index.ts # 接线层：初始化、注册命令/hooks/tools
|
||
│ ├─ commands/ # slash commands
|
||
│ ├─ tools/ # 查询与资源工具
|
||
│ ├─ hooks/ # 生命周期钩子
|
||
│ └─ core/ # 业务逻辑、模型、存储、权限
|
||
├─ skills/ # 技能定义
|
||
├─ docs/ # 项目文档
|
||
├─ scripts/ # 演示与工具脚本
|
||
├─ tests/ # 测试
|
||
├─ install.mjs # 安装/卸载脚本
|
||
├─ plugin.json # 插件清单
|
||
├─ README.md
|
||
└─ README.zh.md
|
||
```
|
||
|
||
## 环境要求
|
||
|
||
- Node.js 22+
|
||
- npm 10+
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
npm install
|
||
npm run build
|
||
npm run test:smoke
|
||
npm run demo
|
||
```
|
||
|
||
## 安装 / 卸载
|
||
|
||
```bash
|
||
# 安装（构建并复制到 ~/.openclaw/plugins/yonexus）
|
||
node install.mjs --install
|
||
|
||
# 安装到自定义 openclaw profile 路径
|
||
node install.mjs --install --openclaw-profile-path /path/to/.openclaw
|
||
|
||
# 卸载
|
||
node install.mjs --uninstall
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
`plugin.json` 默认包含以下配置：
|
||
|
||
- `name`: `yonexus`
|
||
- `entry`: `dist/yonexus/index.js`
|
||
- `config.dataFile`: `./data/org.json`
|
||
- `config.registrars`: 注册人白名单
|
||
- `config.schema`: 元数据字段定义与可查询性
|
||
|
||
## 已实现 API
|
||
|
||
核心 API：
|
||
- `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)`
|
||
|
||
管理 API：
|
||
- `renameDepartment(actor, deptId, newName)`
|
||
- `renameTeam(actor, teamId, newName, deptId?)`
|
||
- `migrateTeam(actor, teamId, newDeptId)`
|
||
- `deleteDepartment(actor, deptId)`
|
||
- `deleteTeam(actor, teamId, deptId?)`
|
||
|
||
文档检索：
|
||
- `getDocs(scope, topic, keyword)`
|
||
|
||
数据与审计：
|
||
- `exportData(actor)`
|
||
- `importData(actor, state)`
|
||
- `listAuditLogs(limit?, offset?)`
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
npm run test:smoke
|
||
```
|
||
|
||
## 说明
|
||
|
||
- 结构数据保存在 JSON 文件，不进入 memory_store。
|
||
- 共享记忆通过 scope memory 适配器处理。
|
||
- 分配 identity 时，未知 meta 字段会被丢弃。
|
||
- `queryAgents` 会严格校验字段是否在 schema 中标记为可查询。
|