Add project plan
This commit is contained in:
root
239
PROJECT_PLAN.md
Normal file
239
PROJECT_PLAN.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# 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（基于当前需求整理）
|
||||
Reference in New Issue
Block a user