# win-openclaw

**Repository Path**: yang-junwang/win-openclaw

## Basic Information

- **Project Name**: win-openclaw
- **Description**: 打造一个 单渠道飞书 完美适配windows 的龙虾
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-05-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Feishu Windows OpenAI Agent

一个运行在 Windows 本地环境中的 Feishu + OpenAI Agent 服务，当前以 FastAPI 为后端入口，负责接收飞书消息、编排 Agent 调用、执行受控工具，并记录消息与审计数据。

## 当前进度

当前仓库已经完成了可运行的后端骨架，并打通了基础主链路：

- FastAPI 应用可启动
- `/health`、`/admin/status`、`/webhook/feishu` 路由可用
- 飞书默认可通过 WebSocket 长连接接收事件，不依赖公网 webhook
- 飞书 webhook 请求可完成载荷解析、事件分类和消息处理分发
- Agent 已接入 OpenAI `Responses API`
- 未配置 `OPENAI_API_KEY` 时可回退到本地 stub 回复
- 工具注册中心、ACL、审批、沙箱、审计、内存数据库结构已经就位
- 启动时会自动初始化 OpenClaw 风格的 workspace 引导文件

当前更接近“可演示原型”而非完整生产版本。真实飞书消息发送、完整验签、持久化会话记忆和测试覆盖仍需继续补齐。

目前已经支持三类执行能力：

- 常用 Windows 显式工具，例如打开应用、关闭应用、关闭浏览器、查看进程、查看系统资源
- 全局桌面控制工具，例如鼠标移动点击、键盘输入、热键、滚轮、截图、剪贴板、活动窗口读取
- 基于 UI Automation 的窗口探测与控件操作，例如列窗口、聚焦窗口、查看控件树、点击指定控件
- 通用 `run_powershell_script` 兜底工具，由模型按用户意图生成并执行 PowerShell
- 外部能力挂载工具，把复杂浏览器能力按需拉入当前宿主执行面

此外，当前 Agent 运行时已经补上一层更强的动作请求约束：

- 对明显包含“打开 / 启动 / 执行 / 点击 / 输入 / 处理”这类动作意图的请求，会优先要求 planner 选择工具，而不是直接自然语言回复
- 对明显依赖当前界面的请求，会优先要求先观察桌面状态，再决定后续动作
- 如果首轮 planner 仍直接回复，运行时会自动追加一次“必须至少选择一个工具”的重试
- 如果二次规划仍未产生工具调用，系统会返回“缺少具体执行线索”的明确提示，而不是假装已经处理

## 项目结构

```text
app/
  api/              FastAPI 路由
  agent/            Agent 编排、Prompt、OpenAI 客户端、工具调度
  channel_feishu/   飞书消息解析、验签、Webhook 处理
  core/             配置、日志、核心契约
  db/               SQLAlchemy 模型、会话、仓储实现
  policy/           ACL、风险分级、审批、沙箱策略
  services/         消息处理、工具服务、审计服务
  tools/            本地工具定义与注册
config/             ACL / 工具策略配置
scripts/            启动脚本
tests/              测试目录
workspace/          Agent 工作区与引导文件
```

## 快速启动

Python 版本要求：`3.11+`

1. 创建虚拟环境
2. 安装依赖
3. 复制环境变量模板
4. 按需填写 OpenAI / 飞书配置
5. 启动服务

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
Copy-Item .env.example .env
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
```

也可以使用脚本启动：

```powershell
powershell -ExecutionPolicy Bypass -File scripts/start.ps1
```

服务默认地址：

- API: `http://127.0.0.1:8000`
- Health Check: `GET /health`
- Admin Status: `GET /admin/status`
- Feishu Webhook: `POST /webhook/feishu`

飞书默认连接模式：

- `FEISHU_CONNECTION_MODE=websocket`：长连接模式，参考 OpenClaw，不依赖公网地址
- `FEISHU_CONNECTION_MODE=webhook`：回调模式，需要飞书可访问你的服务地址

## 环境变量

`.env.example` 当前包含以下关键项：

- `OPENAI_API_KEY`
- `FEISHU_APP_ID`
- `FEISHU_APP_SECRET`
- `FEISHU_VERIFICATION_TOKEN`
- `FEISHU_ENCRYPT_KEY`
- `FEISHU_REPLY_CHUNK_SIZE`
- `FEISHU_REPLY_RETRY_ATTEMPTS`
- `FEISHU_REPLY_RETRY_DELAY_SECONDS`
- `FEISHU_REPLY_STREAM_CHUNK_DELAY_SECONDS`
- `EXTERNAL_CAPABILITY_TIMEOUT_SECONDS`
- `BROWSER_USE_COMMAND`
- `BROWSER_USE_ARGS`
- `PLAYWRIGHT_MCP_COMMAND`
- `PLAYWRIGHT_MCP_ARGS`

此外代码中也支持：

- `APP_SQLITE_URL`
- `APP_WORKSPACE_ROOT`
- `OPENAI_BASE_URL`
- `OPENAI_MODEL`
- `OPENAI_REASONING_MODEL`
- `OPENAI_DISABLE_RESPONSE_STORAGE`
- `OPENAI_REASONING_EFFORT`
- `OPENAI_SERVICE_TIER`
- `CAPCUT_MATE_BASE_URL`
- `CAPCUT_MATE_API_PREFIX`
- `CAPCUT_MATE_TIMEOUT_SECONDS`

## 外部能力挂载

当前项目本身就是宿主 runtime。

也就是说：

- `Feishu Agent 服务` 自己维护会话、审批、审计、工具路由
- `browser-use`、`Playwright MCP` 这类能力作为外部 provider 挂到当前宿主上
- 飞书消息进来后，仍然由当前项目自己决定是否调用这些外部能力

默认配置：

```env
EXTERNAL_CAPABILITY_TIMEOUT_SECONDS=180
BROWSER_USE_COMMAND=browser-use
BROWSER_USE_ARGS=
PLAYWRIGHT_MCP_COMMAND=npx
PLAYWRIGHT_MCP_ARGS=-y @playwright/mcp@latest
NATIVE_DESKTOP_MCP_COMMAND=npx
NATIVE_DESKTOP_MCP_ARGS=-y native-devtools-mcp
```

当前内置的外部能力工具：

- `capability_status`
- `browser_agent_task`
- `desktop_mcp_status`
- `desktop_mcp_take_screenshot`
- `desktop_mcp_find_text`
- `desktop_mcp_click_text`
- `desktop_mcp_click`
- `desktop_mcp_move_mouse`
- `desktop_mcp_drag`
- `desktop_mcp_scroll`
- `desktop_mcp_type_text`
- `desktop_mcp_press_key`
- `desktop_mcp_focus_window`
- `desktop_mcp_list_windows`
- `desktop_mcp_take_ax_snapshot`

当前内置的剪辑 skill 工具：

- `capcut_skill_status`
- `capcut_create_draft`
- `capcut_get_draft`
- `capcut_save_draft`
- `capcut_add_videos`
- `capcut_add_images`
- `capcut_add_captions`
- `capcut_add_effects`
- `capcut_easy_create_material`
- `capcut_submit_export`
- `capcut_export_status`
- `jianying_skill_status`
- `jianying_skill_asset_search`
- `jianying_skill_draft_list`
- `jianying_skill_draft_summary`
- `jianying_skill_auto_export`
- `jianying_skill_prompt_to_draft`

设计原则：

- 当前仓库是宿主，不再把任务转交给别的宿主
- 外部能力按需探测、按需调用，不整包硬编码进主流程
- 浏览器复杂任务优先通过已挂载的 `browser-use` / `Playwright MCP` 解决
- Windows 桌面复杂任务优先通过已挂载的 `native-devtools-mcp` 解决，本地 `pyautogui` / `pywinauto` 工具保留为兜底

## 接入 capcut-mate skill

当前仓库已经支持把 `capcut-mate` 作为一个结构化视频剪辑 skill 挂到宿主 runtime 上，而不是把剪辑逻辑硬编码进主 Agent。

推荐部署方式：

1. 单独启动 `capcut-mate` 服务，默认地址 `http://127.0.0.1:30000`
2. 在当前项目 `.env` 中配置：

```env
CAPCUT_MATE_BASE_URL=http://127.0.0.1:30000
CAPCUT_MATE_API_PREFIX=/openapi/capcut-mate/v1
CAPCUT_MATE_TIMEOUT_SECONDS=120
```

当前挂载的最小可用 skill 面包括：

- `capcut_skill_status`：检查服务可达性
- `capcut_create_draft`：创建草稿
- `capcut_get_draft`：读取草稿文件列表
- `capcut_save_draft`：保存草稿
- `capcut_add_videos`：批量添加视频素材
- `capcut_add_images`：批量添加图片素材
- `capcut_add_captions`：批量添加字幕
- `capcut_add_effects`：批量添加特效
- `capcut_easy_create_material`：快速混排视频、图片、音频、字幕
- `capcut_submit_export`：提交导出任务
- `capcut_export_status`：查询导出进度

这套接法更适合：

- 批量自动出片
- 脚本驱动素材编排
- Agent 先规划镜头和文案，再调用剪辑 skill 落草稿

它不等价于把桌面剪映完整嵌进本项目。当前定位是：

- 当前项目负责会话、消息、调度、审批、审计
- `capcut-mate` 负责草稿编辑与导出执行
- 最终导出稳定性仍取决于 `capcut-mate` 所在机器上的剪映/Jianying 自动化环境

## 结合 jianying-editor-skill

当前仓库也支持把 `jianying-editor-skill` 作为更上层的“导演层 skill”接入。

推荐分工：

- `jianying-editor-skill`：自然语言到草稿脚本、资产搜索、草稿巡检、桌面导出
- `capcut-mate`：HTTP 化草稿编排、状态回读、服务化调度
- `win-openclaw`：消息入口、Agent 编排、权限、审计、任务路由

建议环境变量：

```env
JY_EDITOR_SKILL_ROOT=C:\Users\Arvin\AppData\Local\Temp\jianying-editor-skill-inspect
JY_EDITOR_SKILL_PYTHON=
JY_PROJECTS_ROOT=C:\jianying\JianyingPro Drafts
```

当前可用工具：

- `jianying_skill_status`
- `jianying_skill_asset_search`
- `jianying_skill_draft_list`
- `jianying_skill_draft_summary`
- `jianying_skill_auto_export`
- `jianying_skill_prompt_to_draft`
- `jianying_skill_quick_edit`

其中 `jianying_skill_prompt_to_draft` 是一句话生成草稿的最小落点。它当前先走轻量模式：

- `mode=title_card`：一句话生成标题卡草稿
- `mode=narrated`：一句话生成旁白+字幕草稿（依赖该 skill 的 TTS 环境）

如果你想要更接近“给一句话直接出一个能继续剪的草稿”，优先用 `jianying_skill_quick_edit`。它会把 `jianying-editor-skill` 的 Quick Edit 流程挂进当前宿主：

- 支持只给一句话，直接生成标题卡或旁白字幕草稿
- 支持额外传 `media_dir`，从目录里顺序导入本地视频、图片、音频
- 支持额外传 `media_paths`
- 支持额外传 `cloud_music_query`
- 生成后会自动补一轮 `draft_summary` 和基础验收结果，方便 Agent 判断是否真的做完

建议用法：

```text
帮我做一个有点电影感的竖屏片头

帮我把 D:\素材\露营 这个目录里的视频和图片剪成一个短片，配旁白“周末逃离城市”
```

## 安装 browser-use skill

如果你希望当前宿主获得更强的网页 agent 能力，推荐安装 `browser-use`。

这里的意思不是“把任务交给外部宿主”，而是把 `browser-use` 安装成当前机器上的可调用能力，再由本项目按需调用。

官方文档：

- Browser Use 文档：<https://docs.browser-use.com/open-source/customize/integrations/mcp-server>
- Browser Use 仓库：<https://github.com/browser-use/browser-use>

Browser Use 官方文档给出的本地 MCP 启动方式是：

```bash
uvx --from 'browser-use[cli]' browser-use --mcp
```

它同时也提供 CLI / skill 体系。对本项目来说，更实用的是直接安装可执行的 `browser-use` 命令，然后由 `browser_agent_task` 调用。

## 安装 Playwright MCP

如果你希望当前宿主拥有标准化浏览器自动化能力，推荐安装官方 `Playwright MCP`。

官方文档：

- Playwright MCP 仓库：<https://github.com/microsoft/playwright-mcp>

官方标准配置示例：

```toml
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
```

在支持 Codex MCP 管理的环境里，也可以直接执行：

```bash
codex mcp add playwright npx "@playwright/mcp@latest"
```

Playwright MCP 适合：

- 稳定网页操作
- 可重复浏览器流程
- 结构化页面读取

## 推荐宿主模式

对于这个项目，推荐把宿主能力分成两层：

1. `browser-use skill`
   负责更 agentic 的网页任务，例如“帮我登录后台并找到今天新增订单”
2. `Playwright MCP`
   负责更稳定、更结构化的网页自动化

推荐顺序：

- 先给宿主安装 `Playwright MCP`
- 再给宿主安装 `browser-use skill`
- Feishu 里复杂浏览器任务统一走 `browser_agent_task`

## Feishu 如何调用外挂能力

当前模型是：

- 飞书收到任务
- 当前仓库做会话、风控、审批
- 如果需要复杂浏览器能力，调用已安装的 `browser-use` 命令
- 如果后续补上 `Playwright MCP` 客户端，则由当前宿主直接接入，不改变上层会话模型

对应代码：

- [app/tools/external_capabilities.py](./app/tools/external_capabilities.py)

推荐先在本机验证：

```text
查询 capability_status
调用 browser_agent_task，打开 example.com 并告诉我页面标题
```

## 完整电脑操作能力

当前宿主除了 PowerShell 和显式应用命令外，已经补上了一组更接近 OpenClaw 的桌面操作工具：

- 全局输入输出
  - `move_mouse`
  - `click_at`
  - `scroll_mouse`
  - `type_text`
  - `press_key`
  - `send_hotkey`
- 屏幕与窗口状态
  - `get_active_window`
  - `get_cursor_position`
  - `take_screenshot`
  - `observe_desktop`
  - `perceive_desktop`
  - `get_desktop_state`
- 剪贴板
  - `read_clipboard`
  - `write_clipboard`
- UI Automation
  - `list_windows`
  - `inspect_window`
  - `focus_window`
  - `type_into_window`
  - `click_window_control`
  - `close_window`

推荐执行策略：

1. 先用 `get_active_window` / `list_windows` / `inspect_window` 看清当前界面
2. 再优先走显式控件操作，例如 `click_window_control`、`type_into_window`
3. 控件树不够时，再退到全局鼠标键盘工具
4. 浏览器复杂流程继续交给 `browser_agent_task`

这套分层会比“所有事都直接拼 PowerShell”稳定得多，也更接近 OpenClaw 那种宿主直接控电脑的体验。

## Observe / Perceive / Think / Act / Loop

当前已经补上一个最小可用的电脑操作闭环：

1. `Observe`
   - `observe_desktop`
   - 自动截图
   - 记录当前活动窗口、鼠标位置、可见窗口列表
2. `Perceive`
   - `perceive_desktop`
   - 优先走模型视觉理解
   - 失败时可退到 OCR 路径
3. `Think`
   - 由现有多步 agent loop 基于最新桌面状态继续规划
4. `Act`
   - 使用 `click_window_control`、`type_into_window`
   - 或使用 `move_mouse`、`click_at`、`type_text`、`send_hotkey`
5. `Loop`
   - 再次调用 `observe_desktop`
   - 必要时用 `get_desktop_state` 取回上一步短期状态

短期桌面状态现在会按 session 写入本地内存数据库：

- `observation`
- `perception`

这意味着同一条会话里，模型不用每一轮都重新“盲猜”界面，而是可以读取上一轮的观测和理解结果继续决策。

## 回复投递

当前飞书回复侧已经补上了 OpenClaw 风格的轻量发送层增强：

- 长消息自动分块
- 分块进入本地发送队列
- 队列顺序投递，形成渐进式回复
- 单块失败自动重试

当前实现不是 token 级流式生成，而是“生成完成后按块渐进式发送”，更适合当前飞书文本通道。

相关配置：

- `FEISHU_REPLY_CHUNK_SIZE`：单块最大字符数
- `FEISHU_REPLY_RETRY_ATTEMPTS`：单块最大重试次数
- `FEISHU_REPLY_RETRY_DELAY_SECONDS`：重试基础延迟
- `FEISHU_REPLY_STREAM_CHUNK_DELAY_SECONDS`：相邻分块发送间隔

## Workspace 引导文件

服务启动时会在 `APP_WORKSPACE_ROOT` 对应目录中自动补齐以下文件：

- `AGENTS.md`
- `SOUL.md`
- `TOOLS.md`
- `BOOTSTRAP.md`
- `IDENTITY.md`
- `USER.md`
- `MEMORY.md`
- `DREAMS.md`
- `memory/YYYY-MM-DD.md`

这组文件参考 OpenClaw 的 workspace 约定，用来承载：

- agent 规则
- agent 身份和风格
- 可用工具目录
- 启动约束
- 用户长期偏好

当前实现位于 [workspace.py](d:/Arvin/dev_project/win-openclaw/app/core/workspace.py)。

## 系统提示分层加载

当前项目已经把 OpenClaw 风格的系统提示文件同步存到内存数据库中，而不是每次都整包加载。

当前会写入 `prompt_documents` 的层级包括：

- `core`：`AGENTS`
- `persona`：`SOUL`
- `identity`：`IDENTITY`
- `bootstrap`：`BOOTSTRAP`
- `user`：`USER`
- `tools`：`TOOLS`
- `memory`：`MEMORY` / `DREAMS`

加载策略：

- `AGENTS + SOUL + IDENTITY`：始终加载
- `BOOTSTRAP`：仅在冷启动或首轮对话时加载
- `TOOLS`：当前消息明显涉及命令、文件、系统、进程、浏览器、PowerShell 时加载
- `USER`：当前消息涉及偏好、称呼、长期习惯、记忆用户资料时加载
- `MEMORY / DREAMS`：默认不进入主 system prompt，优先通过 `memory_search` / `memory_get` 按需读取

这样可以减少无关 prompt 注入，让 system prompt 更接近 OpenClaw 的“分层、按场景装配”方式。

## 记忆系统

当前仓库已经补上 OpenClaw 风格的本地记忆骨架：

- `workspace/MEMORY.md`：长期稳定记忆
- `workspace/memory/YYYY-MM-DD.md`：每日记忆
- `workspace/DREAMS.md`：后台整理结果预留

同时提供两个本地工具：

- `memory_search`：检索长期记忆、每日记忆和 dreams
- `memory_get`：读取指定记忆文件或行区间

实现方式：

- 文件是事实来源
- 本地运行时会构建一个进程内的 SQLite FTS 内存索引
- 不依赖额外向量数据库或外部服务

## 数据库存储

当前默认数据库已经调整为内存模式：

- 默认值：`APP_SQLITE_URL=sqlite+pysqlite://`
- 实现方式：SQLite + SQLAlchemy + `StaticPool`
- 特点：单进程共享、无需落盘、适合本地开发和快速联调

当前这套模式适合：

- 本地单机运行
- 飞书机器人原型验证
- 工具调用和审计链路联调

如果后续需要长期保留消息、审批和记忆数据，建议改回文件型 SQLite：

```env
APP_SQLITE_URL=sqlite:///data/app.db
```

## 数据库适配建议

结合当前项目形态，推荐顺序如下：

1. `SQLite 内存库`
   适合现在这版单机开发、快速调试、反复重启验证。
2. `SQLite 文件库`
   最适合你这个项目的第一阶段上线形态。单机、低运维、可持久化、和当前 SQLAlchemy 模型完全兼容。
3. `PostgreSQL`
   适合后续做多渠道、多进程、多实例部署，或者把审批、审计、记忆做成真正长期资产时再切。

不建议当前阶段优先上 MySQL 或更重的数据库，收益不大，维护成本更高。

## OpenAI 运行方式

- 配置了 `OPENAI_API_KEY` 时，Agent 会调用官方 OpenAI `Responses API`
- 未配置 `OPENAI_API_KEY` 时，服务仍可启动，并返回本地 stub 回复
- 当前支持单轮工具调用流程：模型发起 function call -> 本地执行工具 -> 追加 `function_call_output` -> 获取最终回复
- 当前 planner 带有“动作请求二次强制规划”逻辑：当用户请求明显需要动手执行时，系统会优先争取至少一次工具调用，再决定是否直接回复

## 动作请求判定

当前项目参考 OpenClaw 的运行时思路，不再把“要不要真正执行工具”完全交给模型一句话决定，而是增加了一层轻量动作策略：

- `action_required`
  识别“请帮我打开 / 运行 / 点击 / 执行 / 输入 / 处理”等明确操作请求
- `requires_observation`
  识别“看一下当前界面 / 下一步点哪里 / 按钮在哪里 / 输入框在哪里”等先看界面的请求

对应行为：

- `action_required=true`
  planner 首轮如果没有选工具，会自动再重试一次，并明确要求“必须输出至少一个 tool_call”
- `requires_observation=true`
  planner 如果仍直接回复，运行时会优先尝试强制落回 `observe_desktop` / `perceive_desktop` 这类观察工具
- 两轮后仍无法形成有效工具调用时，系统会明确告诉用户“还缺应用名、窗口名、路径或界面线索”，避免出现“光说话不干活”的假完成

相关实现：

- [action_policy.py](/C:/project/win-openclaw/win-openclaw/app/agent/action_policy.py)
- [openai_client.py](/C:/project/win-openclaw/win-openclaw/app/agent/openai_client.py)
- [prompt_builder.py](/C:/project/win-openclaw/win-openclaw/app/agent/prompt_builder.py)

运行日志中可以重点看这些事件：

- `openai_planner_tool_selected`
- `openai_planner_direct_reply`
- `openai_planner_action_required_retry`
- `openai_planner_action_required_forced_observation`

## Windows 命令执行能力

当前项目不是只支持几条写死命令。

除了显式工具外，还提供了一个高风险兜底工具：

- `run_powershell_script`

它的用途是：

- 当现成工具不足以覆盖用户意图时
- 由模型生成对应的 PowerShell 脚本
- 在本地 Windows 上直接执行

这让 Agent 可以覆盖更多 OpenClaw 风格的本地操作场景，而不是只能处理固定关键词。

当前策略：

- 优先使用显式工具，例如 `close_browser`、`open_application`
- 桌面图形界面优先使用 `inspect_window`、`click_window_control`、`type_into_window`
- 控件级工具不够时，再使用 `move_mouse`、`click_at`、`type_text`、`send_hotkey`
- 显式工具不足时，才退到 `run_powershell_script`
- `run_powershell_script` 属于高风险工具，默认走“两步确认”流程
- 像关机、重启、递归强删、改执行策略、删注册表等脚本，会先被风险规则直接拦截

推荐在飞书中这样测试：

```text
用 powershell 打开记事本
确认执行

用 powershell 列出当前正在运行的 chrome 进程
确认执行

用 powershell 获取当前时间并返回结果
确认执行
```

高风险审批流程：

1. 先发送原始请求，例如“用 powershell 打开记事本”
2. 系统返回“已进入待确认队列”
3. 你在同一会话中回复“确认执行”才会真正运行
4. 回复“取消执行”会直接放弃这次待执行操作

如果模型选择了通用 PowerShell 工具，你会在控制台或 `data/uvicorn.err.log` 中看到类似日志：

- `openai_planner_tool_selected`
- `powershell_script_started`
- `powershell_script_completed`

## 多步 Agent Loop

当前 agent 已经不再局限于“单次规划 -> 单次工具调用 -> 单次收尾”。

现在支持：

- 多轮工具规划与执行循环
- 上一轮工具结果返回后继续规划下一步
- 工具失败后重新选择其他工具或改成解释性回复
- 一次任务中累积多步工具轨迹

典型可支持链路：

- 先列目录，再读文件，再写回文件
- 先查记忆，再决定是否继续调用工具
- 某个工具失败后，尝试改走其他工具

相关代码：

- [app/agent/orchestrator.py](./app/agent/orchestrator.py)
- [app/agent/openai_client.py](./app/agent/openai_client.py)

## 硬审批绑定

高风险工具现在不仅会进入待确认队列，还会记录一份本地执行绑定：

- 审批码 `approval_code`
- 当前工作目录 `cwd`
- 工具名
- 精确 payload
- 对 PowerShell 会额外记录 executable path 和 argv

确认时支持：

```text
确认执行
确认执行 ABC123
取消执行
取消执行 ABC123
```

如果绑定内容发生变化，会拒绝继续执行。

## 多 Agent / Delegate 骨架

当前已经补上一个最小可用的会话级 agent 绑定层。

内置 profile：

- `default`
- `system`
- `files`
- `memory`

飞书 / 文本控制命令：

```text
/agent status
/agent use system
/agent use files
/delegate files 读取 workspace 下的 demo.txt
```

说明：

- `/agent use ...` 会把当前会话持久绑定到某个 agent
- `/delegate ...` 是一次性的任务委派，不会永久改掉当前会话绑定

## Feishu 原生审批卡片

当前高风险操作除了文本审批外，已经增加了飞书 interactive card 按钮审批：

- `批准执行`
- `拒绝执行`

卡片内容会显示：

- 工具名
- 风险等级
- 审批码
- 执行预览
- 执行绑定摘要

实现方式：

- 机器人先发送文本审批提示
- 同时发送一张 interactive card
- 用户点击按钮后，回调会进入 `/webhook/feishu`
- 服务端根据 `approval_code` 和 thread/chat 上下文匹配待审批记录
- 执行完成后返回 toast，并回发处理结果

相关代码：

- [app/services/feishu_card_service.py](./app/services/feishu_card_service.py)
- [app/channel_feishu/webhook.py](./app/channel_feishu/webhook.py)
- [app/channel_feishu/feishu_client.py](./app/channel_feishu/feishu_client.py)

## Thread-Bound Runtime

当前会话运行时已经支持 thread 级绑定。

如果飞书消息带有：

- `thread_id`
- `root_id`
- `parent_id`

系统会优先把 session key 解析为：

```text
thread:{chat_id}:{thread_id_or_root_id_or_parent_id}
```

这意味着：

- 同一个群里不同线程可以绑定不同 agent
- 同一个群里不同线程可以各自保留独立上下文
- 审批按钮也会优先按 thread session 匹配，而不是整个 chat 共用一条待审批队列

## 主要设计说明

- 消息处理主链路位于 `app/services/message_service.py`
- Agent 编排入口位于 `app/agent/orchestrator.py`
- 工具注册入口位于 `app/tools/registry.py`
- 策略控制核心位于 `app/services/tool_service.py` 和 `app/policy/`
- 数据表定义位于 `app/db/models.py`
- 数据库初始化位于 `app/db/session.py`
- workspace 初始化位于 `app/core/workspace.py`

## 后续优先事项

- 完善飞书请求验签与安全校验
- 为 `USER.md / MEMORY` 补充长期记忆写入机制
- 将 workspace 引导文件和 prompt 装配做更细粒度映射
- 让 Agent 工具执行链路完整接入 ACL / 审批 / 沙箱 / 审计
- 增加最小可用测试集

## 相关文档

- [AGENTS.md](./AGENTS.md)
- [docs/FEISHU_机器人配置说明.md](./docs/FEISHU_机器人配置说明.md)
- [OPENCLAW_架构说明.md](./OPENCLAW_架构说明.md)
- [FEISHU_WINDOWS_OPENAI_开发方案.md](./FEISHU_WINDOWS_OPENAI_开发方案.md)
- [README_openclaw_概览.md](./README_openclaw_概览.md)
- [开发任务分解.md](./开发任务分解.md)