PaddedCell/REQUIREMENTS_EGO_MGR.md

# 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 能独立使用