项目定位与目标

agent-workspace-linux 提供一个独立的、隐藏的 Linux 桌面，让 AI 智能体（agent）能够通过 MCP 完全控制该桌面，而不会触碰用户真实的鼠标、键盘、焦点或浏览器。该项目的核心命题是：当 agent 需要进行 GUI 自动化、网站 QA 或浏览器操作时，应当在一个与其宿主环境隔离的 X11 会话中执行。资料来源：README.md

仓库明确定义了适用场景：

• 在 agent 不能劫持用户真实桌面或 Chrome 会话的前提下进行 GUI / Web QA；
• 在可观察、可停止的"一次性" profile 中执行浏览器自动化；
• 提供一个可启动、截图、检视后销毁的洁净 Linux 桌面；
• 为长时间运行或无头的 agent 提供一个无需人工值守的桌面环境。资料来源：README.md

项目的反向互补项目为 computer-use-linux：后者自动化的是用户当前的真实桌面，而本项目自动化的是agent 独占的隔离桌面。资料来源：README.md

系统架构总览

系统采用"MCP 前端 + 工作区守护进程 + 隐藏 X11 会话 + 可选 GPUI 浮窗"的分层结构。MCP 服务器通过 stdio 与 Claude Code、Codex 等 MCP host 通信，对外暴露约 86 个工具；后端通过一个 Unix 控制套接字（模式 0600）管理隐藏的 Xvfb 显示与窗口管理器实例。资料来源：README.md

flowchart TB
    Host["MCP Host<br/>(Claude Code / Codex)"]
    MCP["agent-workspace-linux MCP Server<br/>stdio / JSON-RPC"]
    Doc["docs/permission-model.md<br/>权限边界"]
    Daemon["工作区守护进程<br/>Unix 控制套接字 (0600)"]
    Xvfb["Xvfb 隐藏显示<br/>+ openbox 窗口管理器"]
    Apps["工作区内应用<br/>(xterm / Chromium / 自定义)"]
    CDP["Chromium DevTools<br/>(loopback CDP)"]
    Bwrap["bubblewrap<br/>挂载 / 网络隔离"]
    Viewer["GPUI 浮窗<br/>pause / read-only / stop"]
    Skill["skills/agent-workspace-linux/SKILL.md<br/>渐进式工具加载"]

    Host <-->|stdio| MCP
    MCP --> Doc
    MCP <-->|控制套接字| Daemon
    Daemon --> Xvfb
    Xvfb --> Apps
    Apps <--> CDP
    Daemon -.可选.-> Bwrap
    Daemon -.可选.-> Viewer
    Host -.按需读取.-> Skill
    Skill -.路由.-> MCP

核心组件职责划分：

• 隐藏工作区（Hidden workspace）— 私有的 Xvfb 显示 + 窗口管理器 + 控制套接字。创建时强制要求 --ack-hidden-workspace 显式确认，避免静默启动。资料来源：README.md
• 权限上限（Permission ceiling）— 可通过 --permissions file.json 或环境变量 AGENT_WORKSPACE_PERMISSIONS 声明网络模式、挂载路径、应用白名单；bubblewrap 可用时即生效，否则仅声明不执行并由运行时提示。资料来源：README.md
• Profiles — 可复用的工作区定义（挂载、网络模式、setup 命令、启动应用）。资料来源：README.md
• Viewer — 基于 GPUI 的小型浮窗，展示工作区状态与实时屏幕视图，提供 pause / read-only / stop，默认不强制置顶。资料来源：README.md
• 工作区浏览器 — 通过 loopback CDP 端点控制的、归属于工作区的 Chromium，绝不接入用户宿主 Chrome。资料来源：README.md
• Skill — 仓库内置 skills/agent-workspace-linux/SKILL.md，仅加载短描述，agent 按需读取并按"orient → start → observe → act → stop"阶段路由到具体工具，避免一次性向上下文注入全部 ~86 个工具的 schema。资料来源：README.md

安装与分发

install.sh 是仓库提供的一键脚本：构建 release 二进制、安装到 ~/.local/bin/，并将 skill 默认安装到 ~/.codex/skills/，可安全重复运行。Codex MCP 注册为可选流程，建议仅在通用 MCP host 工作流下使用 --codex-configure。资料来源：README.md

也可从源码安装：

cargo install --git https://github.com/agent-sh/agent-workspace-linux

资料来源：README.md

npm 包 @agent-sh/agent-workspace-linux 是一个分发包装器（version 0.1.4），其 postinstall 脚本从匹配的 GitHub Release 下载预编译的 Linux 二进制，并校验同名的 .sha256 附属文件。仅支持 Linux，x64 与 arm64。资料来源：npm/package.json、npm/README.md

权限边界与信任模型

仓库在 README 中以表格显式划分了四种边界控制者，这一点对理解架构至关重要：

资料来源：README.md

整体模型可概括为：默认由 agent host 拥有权限；开发者可通过 flag/env 锁定由守护进程强制执行的硬上限；Viewer 为人类提供尽力而为的实时停止能力——三者分层而非冲突。资料来源：README.md

控制套接字为同 uid 的 Unix socket，模式 0600；默认不提供跨用户保护，需要多用户隔离时应以专用用户运行。资料来源：README.md

浏览器与 CDP 子系统

scripts/lib/chrome_cdp.js 实现了一个面向 loopback 的 Chrome DevTools 客户端：使用原生 Node.js http 与 net 模块，避免引入 puppeteer 等重型依赖。其关键约束包括：

• HTTP 端点必须为 http: 且主机名必须为 127.0.0.1 / localhost / ::1，否则抛出异常。资料来源：scripts/lib/chrome_cdp.js
• WebSocket 必须为 ws: 且同样限定为 loopback，否则拒绝连接。资料来源：scripts/lib/chrome_cdp.js
• 帧解析阶段对超大长度（> Number.MAX_SAFE_INTEGER）进行显式拒绝，防止 OOM。资料来源：scripts/lib/chrome_cdp.js
• createTarget 在收到 HTTP 405 / HTTP 501 时回退到 GET，兼容某些 Chromium 版本。资料来源：scripts/lib/chrome_cdp.js

该实现支撑了"用工作区浏览器工具替代宿主 Chrome bridge"的真实 profile 验证脚本（scripts/mcp_real_profile_browser_session_dogfood.js）。资料来源：README.md

已知社区关注点

社区 issue 中已经识别出两个与架构直接相关的边界风险：

• #21 — 工作区守护进程的 live-control 闸门在 mcp-control.json 不可读时对变更型 IPC 请求 fail-open；由于守护进程是 viewer-forwarded input（不经 MCP 前端）的权威执行点，该行为放大了未经授权的写入面。资料来源：issue #21
• #22 — 宿主剪贴板粘贴到工作区没有大小上限、也没有显式同意提示，构成 host → workspace 的机密性泄露面（宿主 secret、token、提示可能进入 agent 控制的环境）。资料来源：issue #22

这两点均与 README 中"viewer 是尽力而为、安全边界在权限上限"的承诺形成张力，提示用户在依赖 Viewer 控制的同时，应优先启用开发者上限并核对 bubblewrap 是否实际生效。资料来源：README.md

See Also

• Permission Model
• GPUI Viewer Direction
• SECURITY Policy
• Sibling project: computer-use-linux

概述与设计目标

agent-workspace-linux 的核心目标是为 AI agent 提供一个完全隔离的 Linux 桌面（Xvfb 显示 + 窗口管理器 + 控制 socket），同时保证 agent 的所有输入、截图、剪贴板与浏览器控制都不会触达用户的真实桌面。围绕这一目标，项目建立了一套分层而非冲突的权限边界体系，明确区分"由谁设界"、"如何生效"以及"是否可被运行时覆盖"。

资料来源：README.md:12-22

三层边界模型

项目的权限模型由三个相互独立、互不冲突的层次组成，下表展示了它们各自的作用域与失效语义。

资料来源：README.md:62-78

关键概念

• Hidden workspace：私有 Xvfb 显示 + 窗口管理器 + 控制 socket；创建时必须使用 --ack-hidden-workspace，确保用户明确知晓。资料来源：README.md:82-86
• Permission ceiling：可选的 JSON 配置（含 network、mounts、apps），在 MCP 进程生命周期内强制生效。资料来源：README.md:82-86
• bubblewrap 隔离：挂载与网络隔离在 bubblewrap 可用时通过其执行；不可用时策略仅被声明但不会被强制执行，运行时会有相应提示。资料来源：README.md:82-86
• Workspace 浏览器：通过 loopback CDP 控制 workspace 自有 Chrome/Chromium，浏览器自动化绝不连接宿主机 Chrome。资料来源：README.md:14-22

控制状态门控与已知失效模式

viewer 与 workspace daemon 通过共享控制状态文件 mcp-control.json（状态值如 active / read_only / paused）协调暂停/只读行为。该门控是 viewer 转发的输入（不走 MCP 前端）的权威强制点，控制逻辑主要由 src/control.rs 与 src/guardrails.rs 负责。

flowchart LR
    A[viewer 用户点击暂停] --> B[写入 mcp-control.json]
    B --> C{daemon 能否读取?}
    C -- 可读 --> D[拒绝变更类 IPC]
    C -- 不可读 --> E[失败开放: 允许变更类 IPC]
    E --> F[Issue #21 报告面]

社区已记录一项目前已知缺陷：当 daemon 无法读取 mcp-control.json 时，活体控制门对变更类 IPC 请求失败开放——这意味着在配置不可达的状态下，变更类请求仍会被执行。由于 daemon 是 viewer 输入转发的唯一权威强制点，该缺陷具有较高影响，应作为 fail-closed 设计目标来处理。资料来源：Issue #21: Daemon live-control gate fails open on unreadable mcp-control.json

已知信息流风险与社区反馈

剪贴板的宿主→workspace 泄露面

社区同样记录了剪贴板方向上的风险：宿主剪贴板内容被粘贴进隔离 workspace 时没有大小上限，也没有显式提示用户"这会把宿主剪贴板内容送入 agent 控制的工作区"。这构成 host → workspace 的机密性泄露面——宿主侧的秘密、token、提示词可能被 agent 观测到。资料来源：Issue #22: No size cap or explicit consent on host->workspace clipboard paste

文档参考与可报告缺陷边界

• docs/permission-model.md 详细阐述了权威模型。资料来源：README.md:30-36
• SECURITY.md 描述信任模型与漏洞报告路径。资料来源：README.md:30-36
• 项目明确声明：host↔workspace 之间的截图、窗口、剪贴板、浏览器控制只对隐藏 workspace 生效——任何向宿主侧的泄露均视为可报告缺陷。资料来源：README.md:62-78

单用户信任前提

控制 socket 是同 uid 的 Unix socket（mode 0600），设计上不提供跨用户保护。多用户隔离需要将 MCP 以专用用户身份运行。资料来源：README.md:18-22

总结

agent-workspace-linux 的权限模型是一个分层而非冲突的体系：默认下放权给 agent host，可叠加硬性 daemon 级上限，叠加人工实时 viewer 控制。任何对边界的偏离——无论是 daemon 失败开放、剪贴板泄露，还是向宿主 Chrome 桥接——都应作为可报告缺陷处理，而非依赖运行时审批流兜底。开发者最稳妥的实践是显式提供 --permissions JSON，使网络、挂载、应用白名单在 MCP 前端与 IPC socket 双重强制生效。

另见

• README.md
• docs/permission-model.md
• SECURITY.md
• Issue #21 — Daemon live-control gate fails open
• Issue #22 — Host→workspace clipboard paste risk

MCP Tools、Workspace Lifecycle 与浏览器自动化

1. 概述

agent-workspace-linux 通过 Model Context Protocol (MCP) 在 stdio 上对外提供约 86 个工具，覆盖隐藏 X11 工作区的创建、观测、应用启动、剪贴板交互以及基于 Chrome DevTools Protocol（CDP）的浏览器自动化 资料来源：README.md。其核心理念是让 AI 代理拥有独立的桌面——一个由 Xvfb 启动的私有 X11 显示器，加上 openbox 窗口管理器和仅对该显示器可见的 CDP 浏览器——而不侵占用户真实桌面、焦点或已登录的 Chrome 会话 资料来源：README.md。

flowchart LR
    Agent[MCP 代理 / Claude Code] -- "JSON-RPC / stdio" --> MCP[agent-workspace-linux mcp]
    MCP -- "权限闸门 (MCP 前端)" --> Daemon[工作区守护进程<br/>Unix socket 0600]
    Daemon -- "X11 协议" --> Xvfb[Xvfb 隐藏显示器]
    Daemon -- "CDP over loopback" --> Chromium[Workspace Chromium]
    Daemon -- "viewer IPC" --> Viewer[GPUI 浮动查看器]
    Daemon -. "bubblewrap" .-> Sandbox[网络/挂载隔离]

2. MCP 工具与渐进式 Skill 加载

MCP 进程（agent-workspace-linux mcp）一次性向宿主（Claude Code、Codex 等）注册全部工具，但默认不在初始上下文中加载它们的全部 schema，而是发布一个短描述 Skill 资料来源：README.md。Skill 文件位于 skills/agent-workspace-linux/SKILL.md，其安装路径默认为 ~/.codex/skills/，可通过 ./install.sh --skills-dir 或 --no-skill 覆盖；Claude 用户可改用 --skills-dir ~/.claude/skills 资料来源：README.md。

工具按生命周期阶段路由：orient → start → observe → act → stop。install.sh 在安装时把 Skill 复制到宿主 Skills 目录，但 MCP 服务端的注册（mcpServers.agent-workspace-linux 的 command 与 args）由各宿主自行完成——Codex for Linux 推荐使用专门的 Agent Workspaces 功能页进行配置，而非泛用的 MCP 设置页 资料来源：npm/README.md。npm 包装器（@agent-sh/agent-workspace-linux）在 postinstall 阶段会从 GitHub Release 下载匹配架构的预编译二进制，并使用同名的 .sha256 副文件进行校验 资料来源：npm/package.json。

3. 工作区生命周期

工作区生命周期由 CLI 与 MCP 工具共同驱动，且创建隐藏工作区必须显式加上 --ack-hidden-workspace 标志，以避免静默接管 资料来源：README.md。典型快速启动流程如下 资料来源：README.md：

agent-workspace-linux doctor                       # 诊断依赖、显示、沙箱后端
agent-workspace-linux workspace start --dry-run     # 预览，不创建
agent-workspace-linux workspace start --ack-hidden-workspace --purpose "QA run"
agent-workspace-linux viewer                        # 浮动查看器
agent-workspace-linux workspace launch --name editor -- xterm
agent-workspace-linux workspace observe --screenshot --output /tmp/ws.png
agent-workspace-linux workspace stop

核心概念包括：隐藏工作区（私有 Xvfb + 控制 socket）、权限上限（JSON 中的 network/mounts/apps，由守护进程强制执行）、可复用的 Profiles（挂载、网络模式、启动命令与启动应用），以及 workspace-owned 浏览器（通过 loopback CDP 控制，不接触宿主机 Chrome） 资料来源：README.md。bubblewrap 可用时，网络隔离（disabled / local_only / inherit_host）与挂载隔离由其实施；不可用时这些策略仅声明不强制，运行时会在诊断中明确指出 资料来源：README.md。

4. 基于 Chrome DevTools Protocol 的浏览器自动化

浏览器由工作区所有：Chrome/Chromium 通过 loopback HTTP/WS 暴露 DevTools 端点，所有 CDP 调用被限定为 127.0.0.1、localhost、::1 或 [::1]，并要求 ws: / http: 协议 资料来源：scripts/lib/chrome_cdp.js:24-43 与 scripts/lib/chrome_cdp.js:90-104。chrome_cdp.js 提供如下原语：

握手实现手写完成：生成 16 字节随机 Sec-WebSocket-Key、计算 SHA-1 + base64 的期望 Sec-WebSocket-Accept，并解析 HTTP/1.1 101 响应以处理拆包 资料来源：scripts/lib/chrome_cdp.js:106-145。

对于真实账户（Slack/GitHub）验证，推荐使用 scripts/mcp_real_profile_browser_session_dogfood.js 显式 dogfood 流程：先由人工批准一份 Chrome 用户数据目录，再由脚本复制到一次性目录、复用 browser-session 模板启动，并通过 workspace 浏览器工具而不是宿主机 Chrome 桥来证明登录页可见 资料来源：README.md 与 scripts/mcp_real_profile_browser_session_dogfood.js。

5. 权限与社区关注的边界

项目在文档中显式划分了谁拥有边界 资料来源：README.md、docs/permission-model.md：

已知社区问题：

• #21 守护进程的实时控制闸门（active/read_only/paused）在 mcp-control.json 不可读时对可变 IPC 请求 fail-open——这是 viewer 转发的输入（不经过 MCP 前端）的权威执行点，因此该状态在不可读时本应拒绝但当前放行 资料来源：Issue #21。
• #22 主机→工作区的剪贴板粘贴无大小上限也无显式同意——宿主剪贴板中的密钥/令牌可能被无声地发送进 Agent 控制的工作区 资料来源：Issue #22。
• v0.1.3 引入了可选的查看器输入转发（PR #17），进一步把"查看器是旁观者"的前提改成了"可选介入者" 资料来源：Release v0.1.3。

6. 失败模式与最佳实践

• bubblewrap 缺失：网络/挂载策略仅声明、不强制。生产部署应优先在具备 bubblewrap 的环境运行。
• 单用户信任模型：控制 socket 是同 UID 的 Unix socket（权限 0600），按设计不提供跨用户保护。多用户隔离需以专用用户运行 资料来源：README.md。
• Wayland 支持：查看器在 X11/Xwayland 验证，原生 Wayland 仍在演进 资料来源：README.md。
• Live 控件是便利层，而非安全边界——所有约束都应通过 --permissions JSON 在 MCP 启动时钉死。

另请参阅

• Permission boundary
• GPUI viewer direction
• SECURITY.md
• CONTRIBUTING.md
• 兄弟项目 computer-use-linux（驱动用户真实桌面）

安装总览

agent-workspace-linux 提供三种安装通道：仓库根目录的 install.sh 一键脚本、从 git 直接 cargo install、以及 npm 包装器。每条通道的产物一致：把 agent-workspace-linux 可执行文件落到 PATH 上，并按需安装技能包（默认 ~/.codex/skills/）。install.sh 是可重复执行的，并提供多项可选开关，适合升级与清理。

资料来源：README.md

安装通道

系统依赖

install.sh 与 cargo install 通道都假定以下运行时依赖已经存在。Debian/Ubuntu 发行版一行即可：

sudo apt install xvfb openbox xdotool xauth x11-utils imagemagick xclip \
    bubblewrap pkg-config libxkbcommon-x11-dev

bubblewrap 是 mount / network 隔离的执行后端；缺失时这些策略只会被声明，不会被强制执行（运行时会在诊断中告知）。

资料来源：README.md

`install.sh` 一键安装

仓库根目录下的 install.sh 完成"构建 + 安装二进制 + 安装技能"的端到端流程。可用参数如下：

资料来源：README.md；install.sh

从源码 `cargo install`

无需 crates.io，直接从 git 拉取并以锁定版本构建：

cargo install --git https://github.com/agent-sh/agent-workspace-linux
# 或锁定标签
cargo install --git https://github.com/agent-sh/agent-workspace-linux --tag v0.1.4

该路径只安装二进制；技能包与 MCP 客户端注册需手动完成。

资料来源：README.md

npm 包装器

@agent-sh/agent-workspace-linux 是 npm 侧的分发包，仅作二进制分发使用。其 postinstall 脚本会从匹配的 GitHub Release 下载对应架构的预构建产物，并使用 .sha256 侧车文件校验完整性。package.json 中明确：

• os: ["linux"]，cpu: ["x64", "arm64"]
• engines.node >= 18
• bin.agent-workspace-linux 指向 bin/agent-workspace-linux.js

安装命令：

npm install -g @agent-sh/agent-workspace-linux

若包管理器跳过 lifecycle script（如 pnpm 配合 ignore-scripts=true），可手动补救：

node $(npm root -g)/@agent-sh/agent-workspace-linux/scripts/postinstall.js

资料来源：npm/README.md；npm/package.json

预构建二进制

每个 GitHub Release 同时附带 x86_64 与 aarch64 的 Linux 二进制及 .sha256 侧车文件；按常规方式下载、sha256sum -c 校验、chmod +x 后即可放到 PATH 上。

资料来源：README.md

MCP 主机部署

服务以 stdio 上的 JSON-RPC 对外暴露 MCP。最小化的 .mcp.json 片段：

{
  "mcpServers": {
    "agent-workspace-linux": {
      "command": "/home/YOU/.local/bin/agent-workspace-linux",
      "args": ["mcp"]
    }
  }
}

在 Codex for Linux 上，官方推荐使用专属的 Agent Workspaces 功能页配置后端、权限天花板与重连控制，避免把该后端写入通用 MCP/配置页。如果历史安装遗留了旧条目，可运行 ./install.sh --clean-codex-config 清理。

资料来源：README.md；install.sh

技能包与渐进式工具加载

MCP 一共暴露约 86 个工具，为避免全部灌入上下文，仓库随附技能 skills/agent-workspace-linux/SKILL.md。宿主只在元信息层面看到技能的简介；当任务真正需要隔离桌面或浏览器时，再按"orient → start → observe → act → stop"阶段按需载入工具 schema。./install.sh 默认把它装到 ~/.codex/skills/，Claude 用户可通过 --skills-dir ~/.claude/skills 覆盖。

资料来源：README.md

真实账号浏览器会话

对于需要在隔离工作区中复用 GitHub / Slack 已登录 Chrome profile 的场景，仓库提供 scripts/mcp_real_profile_browser_session_dogfood.js 作为可选辅助脚本。脚本会拒绝显而易见的危险 profile、把批准的 profile 复制到一次性目录、通过仓库 MCP 路径启动 browser-session 模板，并最终用工作区浏览器工具（而非主机 Chrome）验证登录页面。

底层通过 scripts/lib/chrome_cdp.js 中的 CdpConnection、createTarget、evaluateExpression、normalizeEndpoint 等函数与 Chrome DevTools 协议交互。模块强制要求端点协议为 http:、WebSocket 协议为 ws:，且主机名必须为 loopback（127.0.0.1 / localhost / ::1），以保证隔离边界不被绕过。

资料来源：scripts/lib/chrome_cdp.js

GPUI 浮窗查看器

方向与设计

GPUI 浮窗查看器是项目面向人类的"可视控制面"，由独立的方向文档 docs/gpui-viewer-direction.md 定义。它以小型浮动窗口呈现工作区状态和实时屏幕画面，并提供 pause / read-only / stop 等控制项。默认不强制置顶，定位为"人类实时监督"的便利层。

资料来源：README.md；docs/gpui-viewer-direction.md

部署形态

启动方式：

agent-workspace-linux viewer

完整工作流演示：

agent-workspace-linux doctor                       # 探测依赖/显示/沙箱后端
agent-workspace-linux workspace start --dry-run    # 演练，不创建任何东西
agent-workspace-linux workspace start --ack-hidden-workspace --purpose "QA run"
agent-workspace-linux viewer                       # 打开浮窗查看器
agent-workspace-linux workspace launch --name editor -- xterm
agent-workspace-linux workspace observe --screenshot --output /tmp/ws.png
agent-workspace-linux workspace stop

通过 MCP 主机调用时无需手敲上述命令——agent 通过匹配的 MCP 工具完成等价流程，并由技能按需加载工具 schema。

资料来源：README.md

部署时需要关注的运行时风险

v0.1.3 通过 #17 引入了"查看器输入转发（opt-in）"。随后社区报告揭示了两条与查看器/控制面相关的运行时风险，部署时必须留意：

• #21：当 mcp-control.json 不可读时，daemon 的 live-control（active / read_only / paused）闸门对变更类 IPC 失败开放（fail-open）。由于查看器转发的输入不经过 MCP 前端，daemon 是事实上的权威执行点——配置不可读时，变更类请求仍被放行，违反最小权限假设。
• #22：从主机剪贴板向工作区的粘贴没有大小上限，也没有"你正在把主机剪贴板内容送入 agent 控制的工作区"的显式同意提示——这是 host → workspace 方向的机密性表面，主机端的 secrets / tokens / 提示可能被工作区侧读取。

这两点不改变安装流程，但提醒管理员：在生产部署中应同时启用开发者权限天花板（--permissions 或 AGENT_WORKSPACE_PERMISSIONS），把 daemon 当作真正的安全边界，并将查看器仅视为辅助工具。

资料来源：README.md；社区 issue #21、#22

See Also

• Permission boundary — 权威权限模型
• GPUI viewer direction — 可视控制面的设计
• SECURITY.md — 信任模型与漏洞报告
• CONTRIBUTING.md — 贡献指南与发版门槛
• 兄弟项目：computer-use-linux — 操作用户真实桌面，与本项目互为补充

Pitfall Log / 踩坑日志

项目：agent-sh/agent-workspace-linux

摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux | host_targets=mcp_host, claude_code, claude

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux | no_demo; severity=medium

6. 安全/权限坑 · 来源证据：Daemon live-control gate fails open on unreadable mcp-control.json (mutating IPC allowed)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Daemon live-control gate fails open on unreadable mcp-control.json (mutating IPC allowed)
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/agent-sh/agent-workspace-linux/issues/21 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

7. 安全/权限坑 · 来源证据：No size cap or explicit consent on host->workspace clipboard paste

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：No size cap or explicit consent on host->workspace clipboard paste
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/agent-sh/agent-workspace-linux/issues/22 | 来源类型 github_issue 暴露的待验证使用条件。

8. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux | issue_or_pr_quality=unknown

9. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:1247893483 | https://github.com/agent-sh/agent-workspace-linux | release_recency=unknown