zhi
849effd301
- Add install.mjs: unified installer with dependency check, build, install, config - Update PROJECT_PLAN.md: add section 6 for installation script requirements - Update AGENT_TASKS.md: add T-7001~T-7005 for installation tasks - Support flags: --prefix, --build-only, --skip-check, --verbose
294 lines
10 KiB
Markdown
294 lines
10 KiB
Markdown
# PaddedCell 插件项目计划（v0.1）
|
||
|
||
> 目标：提供“安全密码管理 + 安全执行 + 安全重启”的插件能力。PaddedCell **完全涵盖 CalmGate 的全部功能**，不再另行开发 CalmGate；相关能力在本项目内实现，不直接复用原项目或命名。
|
||
|
||
---
|
||
|
||
## 1. 功能范围（已确认）
|
||
|
||
### 1.1 密码管理（Pass-like）
|
||
- 使用**内置二进制可用的加密库**实现密码加/解密，不要求依赖 `pass` 或外部进程。
|
||
- 加密算法需支持配置（默认：AES-256-GCM）。
|
||
- 不使用主密钥派生；加/解密基于每个 agent 的公私钥。
|
||
- `pass` 仅作为功能类比：用于说明需要具备的“存取/轮换/删除”等能力。
|
||
- 密码存储路径：`{openclaw_dir}/.secrets/{agent_id}/'{key}:{user}'.gpg`
|
||
- 该二进制后续可能需要作为 OpenClaw 的 skill 提供。
|
||
|
||
### 1.2 pass_mgr 二进制
|
||
- 必须是**可执行二进制**，禁止脚本。
|
||
- 命令（调整）：
|
||
- `pass_mgr get <key> [--username]`
|
||
- `pass_mgr generate <key> [--username <username>]`（替代 agent 侧 set）
|
||
- `pass_mgr unset <key>`
|
||
- `pass_mgr rotate`
|
||
- `pass_mgr admin init <admin_password> [--key-path <path_to_generate_admin_private_key>]`
|
||
- `pass_mgr set <agent_id> <agent_workspace> <key> <passwd> <admin_passwd> [--username <username>]`（仅允许人类在 terminal 执行）
|
||
- 读取 `AGENT_WORKSPACE/AGENT_ID` 定位 workspace。
|
||
- admin 密钥存放路径：`~/.pass_mgr/.priv`
|
||
- **Agent 不允许执行 set**：若检测到 `AGENT` 或 `AGENT_WORKSPACE` 环境变量被设置，则 `pass_mgr set ...` 直接报错并中断。
|
||
- **未初始化禁止使用**：在 `admin init` 前，所有 `get/generate/set` 操作报错。
|
||
- `pass_mgr get <key> --username`：返回该密码文件名中的 `user`（可为空字符串）。
|
||
- **admin 密码泄露防护**：插件需检测所有 session 的 message/tool calling 中是否包含 admin 密码明文；一旦出现：
|
||
- pass_mgr 立即变为“未初始化”状态
|
||
- 记录“严重安全漏洞”日志
|
||
- 需要人类重新执行 `pass_mgr admin init`
|
||
|
||
### 1.3 pcexec 安全执行（exec wrapper）
|
||
- 作为工具实现，TypeScript，接口与 OpenClaw 原生 exec 完全一致。
|
||
- 执行前设置环境变量（workspace/agent_id 等）。
|
||
- 解析命令中的 `pass_mgr get <key>` 调用（不限定 `$(...)` 格式）：
|
||
- 预执行获得明文
|
||
- 执行后将 stdout/stderr 中所有与明文相同的片段替换为 `######`
|
||
- 支持多次/多密码替换。
|
||
- get 失败 → 直接中断。
|
||
|
||
### 1.4 安全重启（CalmGate-like，已并入 PaddedCell）
|
||
- PaddedCell **完整承接 CalmGate 的所有功能**，不再单独开发 CalmGate。
|
||
- 提供 slash command 以启用/禁用重启功能与密码管理功能：
|
||
- `/padded-cell-ctrl status`：展示两项功能状态
|
||
- `/padded-cell-ctrl enable pass-mgr|safe-restart`
|
||
- `/padded-cell-ctrl disable pass-mgr|safe-restart`
|
||
- 权限：仅授权用户可执行（agent 不可自主调用）。
|
||
- 冷却：每个功能开关后**锁定 10 秒**，10 秒内再次尝试改变状态需返回提示“最近刚被修改过”。
|
||
|
||
#### 1.4.1 Agent 全局状态管理
|
||
- 状态集合：`idle | busy | focus | freeze | pre-freeze | pre-freeze-focus`
|
||
- 规则：
|
||
- **idle → busy**：任意非心跳 session 收到消息并开始回复
|
||
- **busy**：在其他 session 继续回复，状态不变
|
||
- **busy → idle**：所有非心跳 session 都不在回复
|
||
- **focus**：工作流占位状态；工作流外消息统一回复“在忙，无法应答”
|
||
- **freeze**：不接受新消息
|
||
- **pre-freeze / pre-freeze-focus**：不接受新消息；处理完最后一条后进入 freeze
|
||
- **pre-freeze-focus 完成后**：触发提示“整理工作进度准备重启后继续”，并向之前工作的 session 发“准备重启，重启后继续”（文案待定）
|
||
|
||
#### 1.4.2 query-restart 信号逻辑
|
||
- 收到 `query-restart`：
|
||
- idle → freeze
|
||
- busy → pre-freeze
|
||
- focus → pre-freeze-focus
|
||
- 若 **全部 agent freeze** → 返回 `OK`，否则 `NOT_READY`
|
||
|
||
#### 1.4.3 safe-restart 工具
|
||
- 每 5s 发 `query-restart` 直到收到 `OK`
|
||
- 收到 `OK` 后：
|
||
- **返回调用方**
|
||
- 启动独立新进程执行 `restart` 脚本（`sleep 60s` → `openclaw gateway restart` → `openclaw gateway status`）
|
||
- 若 5s 内未恢复：将 status append 到 log，并执行 rollback
|
||
- 重启成功后：
|
||
- 解冻所有 freeze agent
|
||
- 对之前 busy/focus 的 agent，回到之前的工作 session 发：“restart 结束了，我们继续”
|
||
- 并发控制：
|
||
- 同一时刻只允许一个 agent 执行 restart
|
||
- 其他 agent 调用直接返回 `ALREADY_SCHEDULED`，不再轮询
|
||
- 新参数：
|
||
- `rollback`（脚本路径）
|
||
- `log`（日志路径）
|
||
- 重启失败：
|
||
- 执行 rollback
|
||
- 用 default agent 在调用方 session 回复：“restart 失败，已经 rollback，请参考 log 调查。”
|
||
- 备注：restart 必须是所有计划操作的最后一步；重启后的操作需在调用前写好 md
|
||
|
||
#### 1.4.4 架构草图（初版）
|
||
```
|
||
+----------------------+ +-----------------------+
|
||
| OpenClaw Hooks | | Safe-Restart Tool |
|
||
| (message lifecycle) | | (poll query-restart) |
|
||
+----------+-----------+ +-----------+-----------+
|
||
| |
|
||
v v
|
||
+----------------------+ +-----------------------+
|
||
| Status Manager |<------>| Local API / WS |
|
||
| - state machine | | /query-restart |
|
||
| - session tracker | +-----------+-----------+
|
||
| - persistence | |
|
||
+----------+-----------+ v
|
||
| openclaw gateway
|
||
v
|
||
+----------------------+
|
||
| Storage (file+mem) |
|
||
+----------------------+
|
||
```
|
||
|
||
#### 1.4.5 数据模型（草案）
|
||
**AgentState**
|
||
```json
|
||
{
|
||
"agentId": "string",
|
||
"state": "idle|busy|focus|freeze|pre-freeze|pre-freeze-focus",
|
||
"workflow": "string|null",
|
||
"activeSessions": ["sessionKey"],
|
||
"lastSessions": ["sessionKey"],
|
||
"updatedAt": 0
|
||
}
|
||
```
|
||
|
||
**Global**
|
||
```json
|
||
{
|
||
"restartScheduledBy": "agentId|null",
|
||
"restartSession": "sessionKey|null",
|
||
"restartStatus": "idle|waiting|restarting|rollback",
|
||
"updatedAt": 0
|
||
}
|
||
```
|
||
|
||
#### 1.4.6 事件流（草案）
|
||
- **消息生命周期 hook**
|
||
- onMessageStart(session, agentId)
|
||
- 若 session 非心跳：idle → busy
|
||
- 记录 activeSessions
|
||
- onMessageEnd(session, agentId)
|
||
- 移除 activeSessions
|
||
- 若 activeSessions 为空：busy → idle
|
||
- 若处于 pre-freeze/pre-freeze-focus：且无 activeSessions → freeze
|
||
- **focus/workflow**
|
||
- workflow 打开：state → focus
|
||
- workflow 关闭：若无 activeSessions → idle，否则 busy
|
||
- focus 下非工作流消息：直接回复“在忙，无法应答”
|
||
- **query-restart**
|
||
- 根据状态映射更新
|
||
- 若全部 freeze → OK，否则 NOT_READY
|
||
- 对调用 restart 的 agent 的调用 session：不冻结
|
||
|
||
#### 1.4.7 API 设计（草案）
|
||
**POST /query-restart**
|
||
Request:
|
||
```json
|
||
{
|
||
"requesterAgentId": "string",
|
||
"requesterSessionKey": "string"
|
||
}
|
||
```
|
||
Response: `OK` / `NOT_READY` / `ALREADY_SCHEDULED`
|
||
|
||
**POST /restart-result**
|
||
Request:
|
||
```json
|
||
{
|
||
"status": "ok|failed",
|
||
"log": "/path/to/log"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 非功能需求
|
||
- 行为与原生 exec 一致（参数、错误码、输出等）。
|
||
- 输出脱敏仅针对 stdout/stderr。
|
||
- 重点目标：避免密码明文出现在 **agent 的聊天/工具调用记录** 中；日志与落盘不做强约束（允许必要场景）。
|
||
- 需要额外文档（skill 等）指导 agent 正确使用密码相关工具。
|
||
|
||
---
|
||
|
||
## 3. 里程碑与任务拆解
|
||
|
||
### M1：需求固化 & 设计确认（0.5d）
|
||
- pass 存储路径模板确认
|
||
- pass_mgr 二进制的接口与约束策略确认
|
||
- pcexec 解析/替换策略确认
|
||
|
||
**验收**：设计说明与配置清单
|
||
|
||
---
|
||
|
||
### M2：pass_mgr 二进制（1.5d）
|
||
- 实现 `get/generate/unset/rotate/admin init/set(admin-only)`
|
||
- 读取 ENV 中 workspace/agent_id
|
||
- 使用内置加密库完成加/解密、存取、轮换
|
||
- 实现“禁止 agent 执行 set”的环境变量检测
|
||
- 实现 admin 密码泄露触发“未初始化 + 严重漏洞日志”
|
||
|
||
**验收**：CLI 可独立操作密码库，异常均可中断
|
||
|
||
---
|
||
|
||
### M3：pcexec 工具（2d）
|
||
- TS 实现，完整兼容 exec 参数
|
||
- 解析 `pass_mgr get <key>`（不限定 `$(...)` 格式）
|
||
- 多密码脱敏替换
|
||
- 错误处理一致
|
||
|
||
**验收**：复杂命令场景下无明文泄漏
|
||
|
||
---
|
||
|
||
### M4：安全重启模块（2d）
|
||
- 状态机 + query-restart
|
||
- safe-restart 轮询 + rollback
|
||
- 恢复通知
|
||
|
||
**验收**：符合上文安全重启机制的关键流程
|
||
|
||
---
|
||
|
||
### M5：集成测试（1d）
|
||
- 多 agent 并发
|
||
- 多次 pass_mgr get
|
||
- exec 参数兼容
|
||
- restart 并发与失败回滚
|
||
|
||
**验收**：测试记录 + 问题清单
|
||
|
||
---
|
||
|
||
## 4. 关键待确认
|
||
1) pass_mgr rotate 的具体语义（对单个 key 还是全部？）
|
||
2) 密码存储路径模板最终格式
|
||
3) admin 密码泄露检测范围（仅 message/tool calling？是否包含文件/日志扫描）
|
||
|
||
---
|
||
|
||
## 5. 输出物
|
||
- 技术设计稿（含流程图）
|
||
- 任务分配清单
|
||
- 测试用例列表
|
||
|
||
## 6. 安装脚本
|
||
|
||
### 6.1 需求
|
||
提供统一的插件安装脚本 `install.mjs`，实现以下功能：
|
||
|
||
**检测与依赖**
|
||
- 检测系统平台 (Linux/macOS)
|
||
- 检测必要依赖 (Node.js, Go, openclaw CLI)
|
||
- 检测 openclaw 配置目录
|
||
|
||
**构建**
|
||
- 自动构建 pass_mgr Go 二进制
|
||
- 自动构建 pcexec TypeScript 模块
|
||
- 自动构建 safe-restart TypeScript 模块
|
||
|
||
**安装**
|
||
- 安装 pass_mgr 到系统 PATH (或 openclaw bin 目录)
|
||
- 安装 TypeScript 模块到 openclaw skills 目录
|
||
- 创建必要的配置文件和目录
|
||
|
||
**配置**
|
||
- 初始化 pass_mgr admin (引导用户设置 admin 密码)
|
||
- 配置环境变量
|
||
- 注册 safe-restart API 服务
|
||
|
||
**验证**
|
||
- 验证所有组件安装成功
|
||
- 输出安装摘要和下一步操作提示
|
||
|
||
### 6.2 使用方式
|
||
```bash
|
||
# 默认安装
|
||
node install.mjs
|
||
|
||
# 指定安装路径
|
||
node install.mjs --prefix /usr/local
|
||
|
||
# 仅构建不安装
|
||
node install.mjs --build-only
|
||
|
||
# 跳过依赖检测
|
||
node install.mjs --skip-check
|
||
```
|
||
|
||
---
|
||
|
||
> 更新日志：v0.1（基于当前需求整理）
|