nav/PaddedCell
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
840f8c7b67e24a624c4bf37b601c6e890aa3c1fd
PaddedCell/PROJECT_PLAN.md

8.4 KiB
Raw Blame History

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

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

1. 功能范围（已确认）

1.1 密码管理（Pass-like）

  • 使用内置二进制可用的加密库实现密码加/解密，不要求依赖 pass 或外部进程。
  • pass 仅作为功能类比：用于说明需要具备的“存取/轮换/删除”等能力。
  • 密码存储路径：{openclaw_dir}/.secrets/{agent_id}/'{key}:{user}'.gpg
  • 该二进制后续可能需要作为 OpenClaw 的 skill 提供。

1.2 pass_mgr 二进制

  • 必须是可执行二进制，禁止脚本。
  • 命令（调整）：
    • pass_mgr get <key> [--username]
    • 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 操作报错。
  • 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。

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

{
  "agentId": "string",
  "state": "idle|busy|focus|freeze|pre-freeze|pre-freeze-focus",
  "workflow": "string|null",
  "activeSessions": ["sessionKey"],
  "lastSessions": ["sessionKey"],
  "updatedAt": 0
}

Global

{
  "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:

{
  "requesterAgentId": "string",
  "requesterSessionKey": "string"
}

Response: OK / NOT_READY / ALREADY_SCHEDULED

POST /restart-result Request:

{
  "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 View Git Blame Copy Permalink