refactor: restructure project layout and add install.mjs

- 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
2026-03-10 14:39:24 +00:00
parent 00ffef0d8e
commit 08a66d7659
30 changed files with 260 additions and 81 deletions
--- a/docs/.gitkeep
+++ b/docs/.gitkeep
--- a/docs/AGENT_TASKS.md
+++ b/docs/AGENT_TASKS.md
@@ -0,0 +1,54 @@
+# Yonexus — AGENT_TASKS
+
+> 目标：将插件拆解为可执行任务（按阶段/优先级）。
+
+## Phase 0 — 基础准备（P0）
+- [x] 明确插件运行环境/依赖（OpenClaw 版本、Node 版本）
+- [x] 定义最终配置文件格式（schema + permissions + registrars）
+- [x] 统一 ID 规则（org/dept/team/agent）
+
+## Phase 1 — MVP 核心（P0）
+### 数据与存储
+- [x] 设计数据模型（Org/Dept/Team/Agent/Identity/Supervisor）
+- [x] 实现 in-memory store + JSON 持久化
+- [x] 定义 CRUD API
+
+### 权限系统
+- [x] 实现权限角色（Org Admin / Dept Admin / Team Lead / Agent）
+- [x] 实现权限校验函数 authorize(action, actor, scope)
+- [x] 实现 registrars 白名单（禁止自注册）
+
+### 工具/API
+- [x] create_department
+- [x] create_team
+- [x] register_agent
+- [x] assign_identity
+- [x] set_supervisor
+- [x] whoami
+- [x] query_agents
+
+### Query DSL
+- [x] filters/op 解析（eq / contains / regex）
+- [x] schema queryable 字段约束
+- [x] pagination（limit/offset）
+
+### Scope Memory
+- [x] scope_memory.put(scopeId, text, metadata)
+- [x] scope_memory.search(scopeId, query, limit)
+- [x] 兼容 memory-lancedb-pro
+
+## Phase 2 — v1 增强（P1）
+- [x] 模糊/正则性能优化（索引/缓存）
+- [x] 管理命令与校验（重命名/删除/迁移）
+- [x] 完善错误码与审计日志
+- [x] 增加导入/导出工具
+
+## Phase 3 — 体验与文档（P1）
+- [x] README（安装/配置/示例）
+- [x] 示例数据集与演示脚本
+- [x] 安装脚本完善（build + copy 到 dist/yonexus）
+
+## Risk & Notes
+- 结构数据不进 memory_store（只做 scope 共享记忆）
+- queryable 字段必须严格按 schema 控制
+- supervisor 关系不隐含权限
--- a/docs/FEAT.md
+++ b/docs/FEAT.md
@@ -0,0 +1,86 @@
+# FEAT — Yonexus Feature List
+
+## Existing Features
+
+### Core Model & Storage
+- Organization / Department / Team / Agent / Identity / Supervisor data model
+- In-memory runtime with JSON persistence (`data/org.json`)
+- Import/export of structure data
+
+### Authorization
+- Role model: `org_admin`, `dept_admin`, `team_lead`, `agent`
+- `authorize(action, actor, scope)` permission check
+- Registrar whitelist (`registrars`) and bootstrap registration support
+
+### Core APIs
+- `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)`
+
+### Query & Search
+- Query ops: `eq`, `contains`, `regex`
+- Schema `queryable` whitelist enforcement
+- Pagination (`limit`, `offset`)
+- Basic query performance optimization (regex cache + ordered filter eval)
+
+### Management & Audit
+- `renameDepartment`, `renameTeam`, `migrateTeam`, `deleteDepartment`, `deleteTeam`
+- Structured errors via `YonexusError`
+- In-memory audit log (`listAuditLogs`)
+
+### Scope Memory
+- Scope memory adapter:
+  - `scope_memory.put(scopeId, text, metadata)`
+  - `scope_memory.search(scopeId, query, limit)`
+
+### Developer Experience
+- `README.md` + `README.zh.md`
+- Example data (`examples/sample-data.json`)
+- Demo script (`scripts/demo.ts`)
+- Smoke test (`tests/smoke.ts`)
+
+---
+
+## New Features (from NEW_FEAT)
+
+### 1) Filesystem Resource Layout
+Data-only filesystem tree under:
+- `${openclaw dir}/yonexus/organizations/<org-name>/...`
+
+Auto-create (idempotent):
+- On `createOrganization`:
+  - `teams/`, `docs/`, `notes/`, `knowledge/`, `rules/`, `lessons/`, `workflows/`
+- On `createTeam`:
+  - `teams/<team-name>/agents/`, `docs/`, `notes/`, `knowledge/`, `rules/`, `lessons/`, `workflows/`
+- On `assignIdentity`:
+  - `teams/<team-name>/agents/<agent-id>/docs|notes|knowledge|rules|lessons|workflows`
+
+### 2) Document Query Tool
+New API:
+- `getDocs(scope, topic, keyword)`
+
+Parameters:
+- `scope`: `organization | department | team | agent`
+- `topic`: `docs | notes | knowledge | rules | lessons | workflows`
+- `keyword`: regex string
+
+Behavior:
+- Read-only search by filename regex under filesystem resources
+- Structured output:
+  - `----ORG`
+  - `----DEPT`
+  - `----TEAM`
+  - `----AGENT`
+- Invalid regex returns structured error (`YonexusError: VALIDATION_ERROR`)
+
+## Notes
+- `${openclaw dir}` resolution order:
+  1. `YonexusOptions.openclawDir`
+  2. `OPENCLAW_DIR` env
+  3. `${HOME}/.openclaw`
+- Plugin code is not written into `${openclaw dir}/yonexus`; only data folders/files are used there.
--- a/docs/PLAN.md
+++ b/docs/PLAN.md
@@ -0,0 +1,127 @@
+# Yonexus — Project Plan
+
+## 1) Goal
+Build an OpenClaw plugin that models organization hierarchy and agent identities, supports supervisor relationships, provides query tools for agents, and uses shared memory per scope (org/department/team).
+
+## 2) Core Concepts
+- **Hierarchy**: Organization → Department → Team → Agent
+- **Supervisor**: each agent may have exactly one supervisor
+- **Identity**: an agent can hold multiple identities across teams/departments
+- **Schema-driven metadata**: configurable fields with per-field queryability
+- **Scope memory**: shared memory for org/department/team (using `memory_store`, compatible with memory-lancedb-pro)
+
+## 3) Storage Strategy
+- **Structure & identity data**: in-memory + JSON persistence (no memory_store)
+- **Shared memory**: memory_store keyed by scope (`org:{id}`, `dept:{id}`, `team:{id}`)
+- **Filesystem resources** (OpenClaw install dir `${openclaw dir}`):
+  - Create a data-only folder at `${openclaw dir}/yonexus` (no plugin code here)
+  - `yonexus/organizations/<org-name>/` contains: `teams/`, `docs/`, `notes/`, `knowledge/`, `rules/`, `lessons/`, `workflows/`
+  - On **create_organization**: create `<org-name>` folder and its subfolders
+  - On **create_team**: create `organizations/<org-name>/teams/<team-name>/` with `agents/`, `docs/`, `notes/`, `knowledge/`, `rules/`, `lessons/`, `workflows/`
+  - On **assign_identity**: create `organizations/<org-name>/teams/<team-name>/agents/<agent-id>/` with `docs/`, `notes/`, `knowledge/`, `rules/`, `lessons/`, `workflows/`
+
+## 4) Permissions Model (B)
+Roles:
+- Org Admin
+- Dept Admin
+- Team Lead
+- Agent
+
+Rules:
+- Supervisor is **not** a role (no inherent permissions)
+- Registration **not** self-service
+  - only configured agent list or human via slash command
+
+Permission matrix (recommended):
+- create_department → Org Admin
+- create_team → Org Admin, Dept Admin (same dept)
+- assign_identity → Org Admin, Dept Admin (same dept), Team Lead (same team)
+- register_agent → Org Admin, Dept Admin, Team Lead (scope-limited)
+- set_supervisor → Org Admin, Dept Admin (same dept)
+- query → all roles, but only schema fields with `queryable: true`
+
+## 5) Schema Configuration (example)
+```json
+{
+  "position": { "type": "string", "queryable": true },
+  "discord_user_id": { "type": "string", "queryable": true },
+  "git_user_name": { "type": "string", "queryable": true },
+  "department": { "type": "string", "queryable": false },
+  "team": { "type": "string", "queryable": false }
+}
+```
+
+## 6) Tool/API Surface (MVP)
+- `create_organization(name)`
+- `create_department(name, orgId)`
+- `create_team(name, deptId)`
+- `register_agent(agentId, name)`
+- `assign_identity(agentId, deptId, teamId, meta)`
+- `set_supervisor(actor, agentId, supervisorId)`
+- `whoami(agentId)` → identities + supervisor + roles
+- `query_agents(filters, options)` → list; supports `eq | contains | regex`
+
+Query example:
+```json
+{
+  "filters": [
+    {"field":"discord_user_id","op":"eq","value":"123"},
+    {"field":"git_user_name","op":"regex","value":"^hang"}
+  ],
+  "options": {"limit": 20, "offset": 0}
+}
+```
+
+## 7) Data Model (MVP)
+- Organization { id, name }
+- Department { id, name, orgId }
+- Team { id, name, deptId }
+- Agent { id, name, roles[] }
+- Identity { id, agentId, deptId, teamId, meta }
+- Supervisor { agentId, supervisorId }
+
+## 8) Milestones
+**Phase 0 (Design)**
+- finalize schema
+- confirm permission rules
+
+**Phase 1 (MVP)**
+- storage + JSON persistence
+- core models + tools
+- query DSL
+- scope memory adapter
+
+**Phase 2 (v1)**
+- policy refinements
+- better query pagination & filtering
+- management commands & validation
+
+## 9) Project Structure (recommended)
+```
+openclaw-plugin-yonexus/
+├─ plugin.json
+├─ src/
+│  ├─ index.ts
+│  ├─ store/        # in-memory + JSON persistence
+│  ├─ models/
+│  ├─ permissions/
+│  ├─ tools/
+│  ├─ memory/
+│  └─ utils/
+├─ scripts/
+│  └─ install.sh
+├─ dist/
+│  └─ yonexus/      # build output target
+└─ data/
+   └─ org.json
+```
+
+## 10) Install Script Requirement
+- Provide `scripts/install.sh`
+- It should register the OpenClaw plugin name as **`yonexus`**
+- Build artifacts must be placed into **`dist/yonexus`**
+
+## 11) Notes & Decisions
+- Structure data is not stored in memory_store.
+- Shared memory uses memory_store (compatible with memory-lancedb-pro).
+- Queryable fields are whitelisted via schema.