Files

zhi 21d04b17cd feat: add --uninstall support to install script

- Add --uninstall flag to remove installed components
- List items to be removed before confirmation
- Remove pass_mgr binary, skills modules, and env config
- Preserve admin key directory (warns user to remove manually)
- Update PROJECT_PLAN.md with uninstall usage

2026-03-05 10:13:29 +00:00

10 KiB

Raw Blame History

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

{
  "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. 关键待确认

pass_mgr rotate 的具体语义（对单个 key 还是全部？）
密码存储路径模板最终格式
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 使用方式

# 默认安装
node install.mjs

# 指定安装路径
node install.mjs --prefix /usr/local

# 仅构建不安装
node install.mjs --build-only

# 跳过依赖检测
node install.mjs --skip-check

# 卸载
node install.mjs --uninstall

# 从指定路径卸载
node install.mjs --uninstall --prefix /usr/local

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

10 KiB Raw Blame History Unescape Escape