chore: organize planning docs

plans/PROXY_PC_EXEC.md

@@ -0,0 +1,68 @@
+# PROXY_PC_EXEC
+
+## 背景
+新增一个可代理执行的安全命令工具，整体行为尽量保持与现有 `pcexec` 一致，但允许在受控条件下以指定的代理身份注入 `AGENT_ID`。
+
+## 开发想法整理
+
+### 1. 新建工具 `proxy-pcexec`
+- 新增一个工具：`proxy-pcexec`
+- 目标是复用或对齐现有 `pcexec` 的能力与行为
+- 预期执行语义与安全边界尽量和 `pcexec` 保持一致，避免出现两套不同标准
+
+### 2. 扩展 `openclaw.plugin.json`
+需要在 `openclaw.plugin.json` 中新增配置字段：
+- `config.proxy-allowlist`
+
+用途：
+- 用于声明哪些 agent 允许调用 `proxy-pcexec`
+- 只有在该 allowlist 中的 agent，才具备调用该工具的权限
+
+建议约束：
+- `config.proxy-allowlist` 应为 agent 标识列表
+- 若调用方不在 allowlist 中，应直接拒绝调用
+- 默认配置应偏保守；未配置时建议视为不允许任何 agent 调用
+
+### 3. `proxy-pcexec` 与 `pcexec` 的关键区别
+`proxy-pcexec` 的功能与 `pcexec` 基本一致，核心差异如下：
+
+#### `pcexec`
+- 直接将调用者的 `agent-id` 注入环境变量 `AGENT_ID`
+
+#### `proxy-pcexec`
+- 不直接使用调用者的 `agent-id` 作为 `AGENT_ID`
+- 增加一个**必填**工具参数：`proxy-for`
+- 实际注入到环境变量 `AGENT_ID` 中的值，取自 `proxy-for`
+
+## 建议的行为规则
+
+### 调用参数
+`proxy-pcexec` 至少包含：
+- `command`
+- `proxy-for`（必填）
+- 其他参数可尽量与 `pcexec` 保持一致
+
+### 权限校验
+调用 `proxy-pcexec` 时应至少进行以下校验：
+1. 校验调用方 agent 是否在 `config.proxy-allowlist` 中
+2. 校验 `proxy-for` 是否存在且非空
+3. 通过校验后，再执行与 `pcexec` 等价的命令执行流程
+
+### 环境变量注入
+- `AGENT_ID` = `proxy-for`
+- 不应再把原始调用者的 `agent-id` 直接写入 `AGENT_ID`
+
+## 设计目标
+- 保持与 `pcexec` 尽可能一致，降低维护成本
+- 通过 allowlist 控制谁可以发起代理执行
+- 通过显式 `proxy-for` 参数，避免隐式身份继承
+- 让代理身份切换是显式、可审计、可配置的
+
+## 待进一步明确的问题
+- `proxy-for` 是否只允许填写已注册/已知的 agent-id
+- 审计日志中是否需要同时记录：
+  - 实际调用者 agent-id
+  - `proxy-for` 值
+  - 最终执行命令
+- `config.proxy-allowlist` 的格式是否需要支持通配、分组或仅支持精确匹配
+- 是否需要对 `proxy-for` 再增加单独 allowlist / 映射限制，避免允许调用者代理任意 agent