From 63d7fb569e0c0162d67c2e79357e371fa0d7193c Mon Sep 17 00:00:00 2001 From: nav Date: Tue, 24 Mar 2026 00:40:05 +0000 Subject: [PATCH] feat: add ego-mgr requirements & secret-mgr rename spec --- REQUIREMENTS_EGO_MGR.md | 266 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 266 insertions(+) create mode 100644 REQUIREMENTS_EGO_MGR.md diff --git a/REQUIREMENTS_EGO_MGR.md b/REQUIREMENTS_EGO_MGR.md new file mode 100644 index 0000000..5c41fb9 --- /dev/null +++ b/REQUIREMENTS_EGO_MGR.md @@ -0,0 +1,266 @@ +# 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 ` → `secret-mgr ` +- 文档：README.md, PROJECT_PLAN.md, SKILL.md 等 +- 技能目录：`skills/pass-mgr/` → `skills/secret-mgr/` +- 环境变量：`AGENT_PASS_MGR_*` → `AGENT_SECRET_MGR_*`（如存在） + +### 1.2 命令保持不变 +```bash +secret-mgr list # List keys for current agent +secret-mgr get-secret --key # Output secret +secret-mgr get-username --key # Output username +secret-mgr set --key --secret [--username ] # Set entry +secret-mgr generate --key [--username ] # Generate random secret +secret-mgr unset --key # Delete entry +secret-mgr get # 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 [--default ] + +# Public Scope 字段 +ego-mgr add public-column [--default ] +``` +- `--default`：可选，设置默认值（不设置则默认为空字符串） +- 字段已存在时返回错误 + +### 2.3.2 删除字段 +```bash +ego-mgr delete +``` +- 删除指定字段及其所有值（包括 `public-scope` 和所有 `agent-scope` 中的值） +- 字段不存在时返回错误 + +#### 2.3.3 设置字段值 +```bash +ego-mgr set +``` +- 字段必须已存在（通过 `add column` 或 `add public-column` 创建） +- 字段不存在时返回错误 +- 根据字段类型自动写入 `agent-scope` 或 `public-scope` + +#### 2.3.4 查询字段 +```bash +# 获取单个字段值 +ego-mgr get + +# 列出所有字段和值（先 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 +``` + +``` +（仅输出值，无额外格式） + +### 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 错误退出码 +| 退出码 | 含义 | +|--------|------| +| 0 | 成功 | +| 1 | 参数错误 / 用法错误 | +| 2 | 字段不存在 | +| 3 | 字段已存在 | +| 4 | 权限错误（非 pcexec 环境 / Agent 越权） | +| 5 | 文件锁获取失败 | +| 6 | JSON 解析/写入错误 | + +### 2.10 值的大小限制 +- 单字段值长度无限制 + +--- + +## 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）？ +2. **迁移策略**：现有 `pass_mgr` 数据如何迁移到 `secret-mgr`？ + +--- + +## 6. 实现任务清单 + +### M1：重命名 pass_mgr → secret-mgr & 初始化 ego.json +- [ ] 重命名二进制文件 +- [ ] 更新所有文档引用 +- [ ] 更新 Skill 目录和引用 +- [ ] 更新 install.mjs 安装脚本 +- [ ] install.mjs 自动创建空 `ego.json` 结构 + +### 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 能独立使用