# PaddedCell 插件项目计划（v0.1）

> 目标：提供“安全密码管理 + 安全执行 + 安全重启”的插件能力。PaddedCell **完全涵盖 CalmGate 的全部功能**，不再另行开发 CalmGate；相关能力在本项目内实现，不直接复用原项目或命名。

---

## 1. 功能范围（已确认）

### 1.1 密码管理（Pass-like）
- 使用**内置二进制可用的加密库**实现密码加/解密，不要求依赖 `pass` 或外部进程。
- `pass` 仅作为功能类比：用于说明需要具备的“存取/轮换/删除”等能力。
- 密码存储路径模板含 `AGENT_WORKSPACE/AGENT_ID` 占位符，运行时替换。
- 该二进制后续可能需要作为 OpenClaw 的 skill 提供。

### 1.2 pass_mgr 二进制
- 必须是**可执行二进制**，禁止脚本。
- 命令（调整）：
  - `pass_mgr get <key>`
  - `pass_mgr generate <key>`（替代 agent 侧 set）
  - `pass_mgr unset <key>`
  - `pass_mgr rotate`
  - `pass_mgr admin init`
  - `pass_mgr set <agent_id> <agent_workspace> <key> <passwd> <admin_passwd>`（仅允许人类在 terminal 执行）
- 读取 `AGENT_WORKSPACE/AGENT_ID` 定位 workspace。
- **Agent 不允许执行 set**：若检测到 `AGENT` 或 `AGENT_WORKSPACE` 环境变量被设置，则 `pass_mgr set ...` 直接报错并中断。
- **未初始化禁止使用**：在 `admin init` 前，所有 `get/generate/set` 操作报错。
- **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。

#### 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. 输出物
- 技术设计稿（含流程图）
- 任务分配清单
- 测试用例列表

---

> 更新日志：v0.1（基于当前需求整理）