commit 572e7d57b08244404e5234dcfb64fd703557e11a Author: root Date: Thu Mar 5 07:38:20 2026 +0000 Add project plan diff --git a/PROJECT_PLAN.md b/PROJECT_PLAN.md new file mode 100644 index 0000000..14cc408 --- /dev/null +++ b/PROJECT_PLAN.md @@ -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 ` + - `pass_mgr generate `（替代 agent 侧 set） + - `pass_mgr unset ` + - `pass_mgr rotate` + - `pass_mgr admin init` + - `pass_mgr set `（仅允许人类在 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 ` 调用（不限定 `$(...)` 格式）： + - 预执行获得明文 + - 执行后将 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 `（不限定 `$(...)` 格式） +- 多密码脱敏替换 +- 错误处理一致 + +**验收**：复杂命令场景下无明文泄漏 + +--- + +### 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（基于当前需求整理）