Feat/agent access

[SkylistqAq]

No description provided.

[github-actions]

审查总结

本 PR 新增外部 Agent 访问能力（持久连接 token + /v1/mcp/agents MCP 端点 + 桌面连接页/安装代写）。整体设计扎实：token 只存 sha256、明文仅创建/轮换返回一次、REST 走全局 bearer、MCP 端点以连接 token 自鉴权、读路径按 roomIds 过滤且有较完整的测试覆盖（鉴权豁免、暂停即时失效、幂等重放都测到了）。但写路径存在一处授权范围绕过，建议修复后再合入。

阻塞问题

1. everroom_submit 的 result_text 条目可绕过 Room 范围校验，向未授权 Room 写入（授权绕过）

apps/gateway/src/modules/agent-access/service.ts:359-362 中，processItem 的范围校验只对 artifact_file 生效：

const roomId = item.roomId ?? connection.scopes.writebackRoomId ?? null;
if (item.kind === "artifact_file" && roomId && !this.roomAllowed(connection, roomId)) {
  return { ...base, status: "rejected", error: "room_out_of_scope" };
}

而 result_text 的 schema 明确允许调用方携带任意 roomId（apps/gateway/src/modules/agent-access/tools-write.ts:46-53、types.ts:103）。复现路径：持有一个仅授权 roomIds: ["room-a"]、writebackRoomId: null 的连接 token 的外部 Agent，提交 { kind: "result_text", title: "x", content: "# x", roomId: "room-b" } —— 文件会以 roomId=room-b、pipelines.room: true 入库（见 create-server.ts 中 agentAccessImportArtifact），并返回 everroom://open/file/... 深链，即写入了连接未被授权的 Room。

同文件 artifact_file 分支与 everroom_register_file（tools-write.ts:130-135）都做了同样的范围校验，可确认这是遗漏而非设计意图。影响：对外暴露的 MCP 写端点的授权被扩大（例如被提示注入的外部 Agent 可向用户未授权的 Room 写内容）。建议去掉 item.kind === "artifact_file" && 条件对两类条目统一校验，并补一条「result_text 携带越界 roomId 应 rejected」的测试（现有 apps/gateway/tests/agent-access.test.ts:351-394 未覆盖该场景）。

建议修复（非阻塞）

2. writebackRoomId 未校验在授权 Room 范围内

• apps/gateway/src/modules/agent-access/routes.ts:38-50（parseScopes）创建/更新时不校验 writebackRoomId ∈ roomIds；
• 桌面表单 apps/desktop/src/renderer/src/components/pages/AgentConnectionCreateForm.tsx:152-158 在「仅选定 Room」模式下，回写下拉仍列出全部 Room。

修复问题 1 后，越界的 writebackRoomId 会导致所有回写条目被拒（与 UI 预期不一致）；建议网关侧校验，表单只列选定 Room。

3. 已吊销/暂停的连接仍可换取安装代写内容

apps/gateway/src/modules/agent-access/service.ts:165-169 的 verifyTokenMatch 不检查 status，routes.ts:270-287 对 revoked 连接仍会返回含明文 token 的安装计划。该端点虽有全局 bearer 保护，影响有限，但建议非 active 连接直接 403/404，与 MCP 端点行为一致。

4. 含 token 的配置文件权限与备份残留

apps/desktop/src/main/agent-access/installer.ts:92 新建 ~/.claude.json、~/.cursor/mcp.json（内含 Bearer token）使用默认 0644 权限，多用户机器上其他本地用户可读，建议新建文件用 0600。另外 ${path}.everroom-backup-${Date.now()} 备份会无限累积（重新安装后备份里也含 token），可考虑只保留最近一份。

小问题 / 备注

• apps/gateway/src/modules/agent-access/tools-read.ts:527：非 "all" 范围的记忆检索只取前 10 个 Room（roomIds.slice(0, 10)），超出部分静默漏检；建议在工具描述中注明或改为分页/上限提示。
• apps/gateway/src/modules/agent-access/routes.ts:218-223：每次自检都以 selftest-${Date.now()} 新建一条 submission（citation）永久落库，调试数据会随自检持续膨胀；可考虑复用固定 submissionId（利用幂等重放）。
• apps/gateway/src/modules/agent-access/mcp-routes.ts:5-7：body schema 只接受单个 JSON-RPC 对象，批量数组会得到普通 400（非 JSON-RPC 错误形状）；发送 batch 的旧版 MCP 客户端会不兼容。
• apps/gateway/src/modules/agent-access/mcp-routes.ts:49-56：DELETE /v1/mcp/agents 对无效 token 也返回 204，与 POST 的 401 不一致（且 closeSession 内的 verifyBearer 会顺带刷新 lastSeenAt）。
• apps/gateway/src/modules/agent-access/install.ts:27-29：连接名未转义直接写入 SKILL.md 的 YAML frontmatter（name 仅限长度、未限字符），含换行/--- 的名称会破坏 frontmatter；建议过滤控制字符。
• apps/gateway/drizzle/meta/_journal.json 丢失文件末尾换行（不影响解析），建议恢复以减少 diff 噪音。

值得肯定

• 凭证管理规范：sha256 落库 + 唯一索引、前缀展示、明文一次性返回；
• 读路径每个 fetch 目标都做 roomInScope 校验，搜索 roomIds 下推到 SQL 条件；
• 测试真引导整服务器覆盖鉴权豁免与迁移（0081），桌面 installer 对损坏 JSON 的保守处理也有测试。

此 PR 修改了高风险文件，需要人工批准，不会自动合并。

• apps/gateway/drizzle/0081_agent_access.sql
• apps/gateway/drizzle/meta/_journal.json