chore: organize planning docs
This commit is contained in:
279
achieve/REQUIREMENTS_EGO_MGR.md
Normal file
279
achieve/REQUIREMENTS_EGO_MGR.md
Normal file
@@ -0,0 +1,279 @@
|
||||
# PaddedCell 需求更新 — ego-mgr & 重命名
|
||||
|
||||
> 版本：v0.2
|
||||
> 日期：2026-03-24
|
||||
> 状态：待实现
|
||||
|
||||
---
|
||||
|
||||
## 1. 重命名：pass_mgr → secret-mgr
|
||||
|
||||
### 1.1 范围
|
||||
所有文档、代码、技能引用中的 `pass_mgr` 统一更名为 `secret-mgr`：
|
||||
|
||||
- 二进制文件名：`pass_mgr` → `secret-mgr`
|
||||
- 命令引用：`pass_mgr <cmd>` → `secret-mgr <cmd>`
|
||||
- 文档：README.md, PROJECT_PLAN.md, SKILL.md 等
|
||||
- 技能目录：`skills/pass-mgr/` → `skills/secret-mgr/`
|
||||
|
||||
### 1.2 命令保持不变
|
||||
```bash
|
||||
secret-mgr list # List keys for current agent
|
||||
secret-mgr get-secret --key <key> # Output secret
|
||||
secret-mgr get-username --key <key> # Output username
|
||||
secret-mgr set --key <key> --secret <s> [--username <u>] # Set entry
|
||||
secret-mgr generate --key <key> [--username <u>] # Generate random secret
|
||||
secret-mgr unset --key <key> # Delete entry
|
||||
secret-mgr get <key> # Legacy (maps to get-secret)
|
||||
secret-mgr admin handoff [file] # Export build secret
|
||||
secret-mgr admin init-from [file] # Re-encrypt data
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 新增 ego-mgr 二进制（Go）
|
||||
|
||||
### 2.1 功能概述
|
||||
`ego-mgr` 管理 Agent 的个人信息（名字、邮箱、出生日期等），支持：
|
||||
- **Agent Scope 字段**：每个 Agent 独立存储，值可不同
|
||||
- **Public Scope 字段**：全局共用，所有 Agent 共享同一值
|
||||
|
||||
### 2.2 数据存储
|
||||
- **文件路径**：`~/.openclaw/ego.json`
|
||||
- **格式**：JSON
|
||||
- **Schema**：
|
||||
```json
|
||||
{
|
||||
"columns": ["col1", "col2", "..."],
|
||||
"public-columns": ["pub-col1", "pub-col2", "..."],
|
||||
"public-scope": {
|
||||
"pub-col1": "value1",
|
||||
"pub-col2": "value2"
|
||||
},
|
||||
"agent-scope": {
|
||||
"agent-id-1": {
|
||||
"col1": "value-x",
|
||||
"col2": "value-y"
|
||||
},
|
||||
"agent-id-2": {
|
||||
"col1": "value-z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 命令接口
|
||||
|
||||
#### 2.3.0 帮助
|
||||
```bash
|
||||
ego-mgr --help
|
||||
```
|
||||
输出命令使用说明和示例。
|
||||
|
||||
#### 2.3.1 增加字段
|
||||
```bash
|
||||
# Agent Scope 字段
|
||||
ego-mgr add column <column-name> [--default <default-value>]
|
||||
|
||||
# Public Scope 字段
|
||||
ego-mgr add public-column <column-name> [--default <default-value>]
|
||||
```
|
||||
- `--default`：可选，设置默认值（不设置则默认为空字符串）
|
||||
- 字段已存在时返回错误
|
||||
|
||||
### 2.3.2 删除字段
|
||||
```bash
|
||||
ego-mgr delete <column-name>
|
||||
```
|
||||
- 删除指定字段及其所有值（包括 `public-scope` 和所有 `agent-scope` 中的值）
|
||||
- 字段不存在时返回错误
|
||||
|
||||
#### 2.3.3 设置字段值
|
||||
```bash
|
||||
ego-mgr set <column-name> <value>
|
||||
```
|
||||
- 字段必须已存在（通过 `add column` 或 `add public-column` 创建）
|
||||
- 字段不存在时返回错误
|
||||
- 根据字段类型自动写入 `agent-scope` 或 `public-scope`
|
||||
|
||||
#### 2.3.4 查询字段
|
||||
```bash
|
||||
# 获取单个字段值
|
||||
ego-mgr get <column-name>
|
||||
|
||||
# 列出所有字段和值（先 Public 后 Agent Scope）
|
||||
ego-mgr show
|
||||
|
||||
# 仅列出字段名（先 Public 后 Agent Scope）
|
||||
ego-mgr list columns
|
||||
```
|
||||
|
||||
### 2.4 输出示例
|
||||
|
||||
#### ego-mgr show
|
||||
```
|
||||
pub-col1: val1
|
||||
pub-col2: val2
|
||||
...
|
||||
col1: valx
|
||||
col2: valy
|
||||
```
|
||||
|
||||
#### ego-mgr list columns
|
||||
```
|
||||
pub-col1
|
||||
pub-col2
|
||||
...
|
||||
col1
|
||||
col2
|
||||
```
|
||||
|
||||
#### ego-mgr get <column>
|
||||
```
|
||||
<value>
|
||||
```
|
||||
（仅输出值，无额外格式）
|
||||
|
||||
### 2.5 安全约束
|
||||
- **必须由 pcexec 调用**：检测到非 pcexec 环境（缺少 `AGENT_VERIFY` 等环境变量）时拒绝执行
|
||||
- **Agent 隔离**：Agent 只能读写自己的 `agent-scope` 字段，不能访问其他 Agent 的数据
|
||||
- **Public Scope 读取**：所有 Agent 可读取 `public-scope`
|
||||
|
||||
### 2.6 字段命名规则
|
||||
- **字符限制**：无限制（允许空格、特殊字符）
|
||||
- **长度限制**：无限制
|
||||
- **大小写**：区分大小写
|
||||
- **唯一性**：public-column 和 column 名字不能重复（全局唯一）
|
||||
|
||||
### 2.7 初始化逻辑
|
||||
- `ego.json` 不存在时，由 PaddedCell 安装脚本自动创建空结构：
|
||||
```json
|
||||
{
|
||||
"columns": [],
|
||||
"public-columns": [],
|
||||
"public-scope": {},
|
||||
"agent-scope": {}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.8 并发安全
|
||||
- 写操作（`add`, `delete`, `set`）必须使用文件锁，防止多 Agent 并发写入导致数据损坏
|
||||
- 读操作（`get`, `show`, `list columns`）无需锁
|
||||
|
||||
### 2.9 Agent 自动注册
|
||||
- **读/写操作时**：如果当前 `agent-id` 不存在于 `agent-scope` 中，自动创建空条目：
|
||||
```json
|
||||
"agent-scope": {
|
||||
"new-agent-id": {}
|
||||
}
|
||||
```
|
||||
- **字段验证**：如果 `column-name` 不存在于 `columns` 或 `public-columns` 中，返回错误（退出码 2）
|
||||
|
||||
### 2.10 错误退出码
|
||||
| 退出码 | 含义 |
|
||||
|--------|------|
|
||||
| 0 | 成功 |
|
||||
| 1 | 参数错误 / 用法错误 |
|
||||
| 2 | 字段不存在（column-name 不在 columns 或 public-columns 中） |
|
||||
| 3 | 字段已存在 |
|
||||
| 4 | 权限错误（非 pcexec 环境 / Agent 越权） |
|
||||
| 5 | 文件锁获取失败 |
|
||||
| 6 | JSON 解析/写入错误 |
|
||||
|
||||
### 2.11 值的大小限制
|
||||
- 单字段值长度无限制
|
||||
|
||||
---
|
||||
|
||||
## 3. 新增 ego-mgr Skill
|
||||
|
||||
### 3.1 Skill 路径
|
||||
`~/.openclaw/skills/ego-mgr/SKILL.md`
|
||||
|
||||
### 3.2 Skill 功能
|
||||
- 指导 Agent 正确使用 `ego-mgr` 命令
|
||||
- 说明字段管理流程（先 `add column`，再 `set`）
|
||||
- 提供常见用例（设置名字、邮箱、时区等）
|
||||
|
||||
### 3.3 触发条件
|
||||
- 用户请求管理 Agent 个人信息
|
||||
- 用户询问 ego-mgr 用法
|
||||
- 需要存储/读取 Agent 配置信息
|
||||
|
||||
---
|
||||
|
||||
## 4. 依赖关系
|
||||
|
||||
```
|
||||
+------------------+
|
||||
| pcexec |
|
||||
+--------+---------+
|
||||
|
|
||||
v
|
||||
+--------+---------+ +------------------+
|
||||
| ego-mgr |<----| ~.openclaw/ |
|
||||
| secret-mgr | | ego.json |
|
||||
+------------------+ +------------------+
|
||||
```
|
||||
|
||||
- `ego-mgr` 和 `secret-mgr` 都必须通过 `pcexec` 调用
|
||||
- `pcexec` 负责：
|
||||
- 注入环境变量（`AGENT_VERIFY`, `AGENT_ID`, `AGENT_WORKSPACE`）
|
||||
- 解析并脱敏敏感信息
|
||||
- 验证执行上下文
|
||||
|
||||
---
|
||||
|
||||
## 5. 待确认事项
|
||||
|
||||
1. **字段类型**：是否支持字段类型约束（如 email、date、number）？
|
||||
|
||||
---
|
||||
|
||||
## 6. 实现任务清单
|
||||
|
||||
### M1：重命名 pass_mgr → secret-mgr & 初始化 ego.json
|
||||
- [ ] 重命名二进制文件
|
||||
- [ ] 更新所有文档引用
|
||||
- [ ] 更新 Skill 目录和引用
|
||||
- [ ] 更新 install.mjs 安装脚本
|
||||
- [ ] install.mjs 自动创建空 `ego.json` 结构
|
||||
|
||||
### M1.5：pass_mgr → secret-mgr 数据迁移
|
||||
**迁移步骤**：
|
||||
1. 删除旧的 `pass_mgr` 前，执行：`pass_mgr admin handoff`（导出当前 build secret）
|
||||
2. 安装新的 `secret-mgr` 后，执行：`secret-mgr admin init-from`（用新 secret 重新加密数据）
|
||||
3. 重启 gateway：`openclaw gateway restart`
|
||||
|
||||
### M2：实现 ego-mgr 二进制
|
||||
- [ ] 设计 JSON Schema 和文件结构
|
||||
- [ ] 实现 `--help`
|
||||
- [ ] 实现 `add column` / `add public-column`
|
||||
- [ ] 实现 `delete`
|
||||
- [ ] 实现 `set`
|
||||
- [ ] 实现 `get` / `show` / `list columns`
|
||||
- [ ] 实现 pcexec 环境检测
|
||||
- [ ] 实现 Agent 隔离逻辑
|
||||
- [ ] 实现文件锁（并发安全）
|
||||
- [ ] 实现错误退出码
|
||||
|
||||
### M3：编写 ego-mgr Skill
|
||||
- [ ] 创建 `skills/ego-mgr/SKILL.md`
|
||||
- [ ] 编写使用示例
|
||||
- [ ] 集成到 OpenClaw Skill 系统
|
||||
|
||||
### M4：集成测试
|
||||
- [ ] 测试 ego-mgr 与 pcexec 集成
|
||||
- [ ] 测试多 Agent 隔离
|
||||
- [ ] 测试 Public/Agent Scope 分离
|
||||
- [ ] 测试边界条件（字段不存在、重复添加等）
|
||||
|
||||
---
|
||||
|
||||
## 7. 验收标准
|
||||
|
||||
1. `secret-mgr` 所有原有功能正常工作，文档更新完成
|
||||
2. `ego-mgr` 支持完整的 CRUD 操作
|
||||
3. `ego-mgr` 只能通过 `pcexec` 调用
|
||||
4. Agent 数据隔离正确，Public Scope 共享正确
|
||||
5. Skill 文档清晰，Agent 能独立使用
|
||||
Reference in New Issue
Block a user