aws-runtime-bridge 1.9.175 → 1.9.180

package/package/aws-client-agent-mcp/README.md

@@ -1,37 +1,33 @@
 # aws-client-agent-mcp
 
-AgentsWorkStudio - Agent MCP Client
+AgentsWorkStudio — 编程 Agent 接入 MCP。
 
-编程 Agent 与调度中心的通信桥梁，基于 MCP (Model Context Protocol) 协议实现。
+把调度中心的消息、任务、记忆、文档、邮箱与能力市场能力暴露为 MCP 工具，供 ACode 运行时调用。
 
 ## 功能特性
 
-- **注册上线**: Agent 通过 MCP Tool 注册到调度中心，获得唯一标识
-- **同事发现**: 查询当前 Agent 可见的同事 Agent 列表（包含在线和离线）
-- **群聊消息**: 发送和接收公共群聊消息（支持未读消息指针）
-- **私信消息**: 
-  - 通知式: 发送后不阻塞
-  - 调用式: 发送后阻塞等待回复（带超时机制）
-- **消息主循环**: 持续监听和处理收到的消息
-- **自动重连**: WebSocket 断线后自动重连
+- **注册上线**：按角色实例注册到调度中心并保持 WebSocket 连接
+- **消息主循环**：`poll_message` 持续阻塞等待私信、群聊、流程任务、插件事件与系统通知
+- **同事发现**：可见同事（含离线）、在线状态、当前动作、工作区与邮箱地址
+- **群聊与私信**：项目公共群 / 组内群、通知式与调用式（阻塞等待回复）、引用、附件、文档卡片
+- **流程任务**：读取当前任务、提交结果、节点迭代、任务回退
+- **记忆**：实例即时/永久记忆与角色级项目文档记忆，支持文件绑定与检索
+- **产物**：Pencil 画布、draw.io、Office 文档与云文档协作
+- **邮箱**：域名邮箱收发信、正文/附件、线程回信
+- **能力市场**：安装/卸载 MCP、Skill、Plugin；在工作区内自研、临时挂载调试并转正
+- **自动重连**：心跳超时、断线、运行时 token 过期后自动重连与降级恢复
 
 ## 安装
 
 ```bash
-# 克隆项目后进入目录
-cd aws-client-agent-mcp
-
-# 安装依赖
+# 仓库内安装（通常由 aws-runtime-bridge 随包准备，无需单独安装）
+cd aws-runtime-bridge/package/aws-client-agent-mcp
 npm install
-
-# 编译 TypeScript
 npm run build
-
-# 全局安装为命令行工具
 npm install -g .
 ```
 
-安装完成后可直接使用全局命令：
+安装后可直接运行：
 
 ```bash
 aws-client-agent-mcp
@@ -42,25 +38,30 @@ aws-client-agent-mcp
 ### 环境变量
 
 | 变量名 | 说明 | 默认值 |
-|--------|------|--------|
+| --- | --- | --- |
 | `AWS_SERVER_URL` | 调度中心 WebSocket 地址 | `ws://localhost:8080/ws/agent` |
+| `AWS_MCP_HTTP_URL` | 调度中心 MCP HTTP 调用地址 | 由 `AWS_SERVER_URL` 推导为 `/mcp/call` |
 | `AWS_WORKSPACE_PATH` | Agent 所在工作区路径 | 当前进程工作目录 |
-| `AWS_ROLE_NAME` | Agent 角色名，可为空，角色配置主要由后端 runtime-bridge 提供 | 空字符串 |
-| `AWS_PROJECT_NAME` | Agent 所属项目名 | `default` |
-| `AWS_PROMPT` | Agent 提示词，可为空，角色配置主要由后端 runtime-bridge 提供 | 空字符串 |
+| `AWS_PROJECT_NAME` | Agent 所属项目 ID/名称 | `default` |
+| `AWS_ROLE_NAME` | 角色名；通常由 Bridge 下发 | 空 |
+| `AWS_PROMPT` | 角色提示词；通常由 Bridge 下发 | 空 |
 | `AWS_AGENT_ID` | 预设 Agent ID，用于绑定已有实例 | 未设置 |
 | `AWS_HEARTBEAT_INTERVAL` | 心跳间隔（毫秒） | `3000` |
-| `AWS_HEARTBEAT_TIMEOUT` | 心跳超时时间（毫秒） | `9000` |
-| `AWS_MCP_HTTP_URL` | 调度中心 MCP HTTP 调用地址 | 根据 `AWS_SERVER_URL` 推导为 `/mcp/call` |
-| `AWS_ATTACHMENT_MAX_SIZE_MB` | 附件单文件大小上限（MB）。服务端还会按流程线模板的按项上限（`maxSizeMb`，默认 200MB）二次校验 | `200` |
+| `AWS_HEARTBEAT_TIMEOUT` | 心跳超时（毫秒），超时后重连 | `9000` |
+| `AWS_RECONNECT_MAX_INTERVAL` | 重连退避上限（毫秒） | `30000` |
+| `AWS_RECONNECT_JITTER_MS` | 重连抖动（毫秒） | `1000` |
+| `AWS_RUNTIME_TOKEN_REFRESH_INTERVAL_MS` | runtime token 刷新间隔 | 12 小时 |
+| `AWS_ATTACHMENT_MAX_SIZE_MB` | 附件单文件大小上限（MB） | `200` |
 
-> 注意：当前实现不再读取 `AWS_CONFIG_PATH`。作为 stdio MCP Server 运行时，stdout 必须只输出 JSON-RPC 消息，普通日志会输出到 stderr，避免污染 MCP 握手协议。
+> 不再读取 `AWS_CONFIG_PATH`。作为 stdio MCP Server 运行时，stdout 只能输出 JSON-RPC 消息，普通日志输出到 stderr，避免污染 MCP 握手。
 
 ## 使用方式
 
-### 方式一: 作为 MCP Server 使用（推荐）
+### 方式一：由 Bridge 拉起（推荐）
 
-在 Claude Desktop 或 Cline 的配置中添加：
+在面板中为角色实例启用内置通讯 MCP，Bridge 会注入实例身份、运行时 token 与工作区路径。无需手工填写连接参数。
+
+### 方式二：作为 stdio MCP Server 手动接入
 
 ```json
 {
@@ -70,6 +71,7 @@ aws-client-agent-mcp
       "args": ["/path/to/aws-client-agent-mcp/dist/index.js"],
       "env": {
         "AWS_SERVER_URL": "ws://localhost:7380/ws/agent",
+        "AWS_MCP_HTTP_URL": "http://localhost:7380/mcp/call",
         "AWS_WORKSPACE_PATH": "/absolute/path/to/project",
         "AWS_PROJECT_NAME": "default"
       }
@@ -78,210 +80,123 @@ aws-client-agent-mcp
 }
 ```
 
-### 方式二: 命令行运行
-
-```bash
-# 设置环境变量并运行
-export AWS_SERVER_URL=ws://localhost:7380/ws/agent
-export AWS_WORKSPACE_PATH=/absolute/path/to/project
-export AWS_PROJECT_NAME=default
-aws-client-agent-mcp
-```
-
-## MCP Tools
-
-### register
-
-注册 Agent 上线。
-
-**返回值:**
-```json
-{
-  "agentId": "uuid-string",
-  "displayName": "后端开发专家-A3X7",
-  "status": "online"
-}
-```
-
-### unregister
-
-注销 Agent 下线。
-
-### get_colleague
-
-获取当前 Agent 可见的同事 Agent 列表，包含在线和离线状态。
-
-**返回值:**
-```json
-{
-  "humans": [],
-  "agents": [
-    { "id": "agent_001", "displayName": "后端开发专家-A3X7", "roleName": "后端开发专家", "prompt": "...", "onlineSince": "..." },
-    { "id": "agent_002", "displayName": "测试工程师-B8K2", "roleName": "测试工程师", "prompt": "...", "onlineSince": null }
-  ]
-}
-```
-
-### get_group_rooms
-
-获取当前 Agent 在关系图中可发现的群组列表，包括项目公共群聊以及自己所在的小组群。
-
-**返回值:**
-```json
-{
-  "groups": [
-    {
-      "id": "project:demo",
-      "projectId": "demo",
-      "roomType": "project",
-      "scopeRefId": "demo",
-      "name": "demo 公共群聊",
-      "memberUserIds": ["agent_001"]
-    },
-    {
-      "id": "inner_group:g-1",
-      "projectId": "demo",
-      "roomType": "inner_group",
-      "scopeRefId": "g-1",
-      "name": "后端小组",
-      "memberUserIds": ["agent_001", "agent_002"]
-    }
-  ]
-}
-```
-
-### send_group_message
-
-发送群消息。
-
-**参数:**
-- `content`: 消息内容（string，必需）
-
-### get_group_messages
-
-获取未读群消息。
-
-**返回值:**
-```json
-{
-  "messages": [
-    { "msgId": 1, "senderId": "...", "senderName": "...", "content": "...", "timestamp": "..." }
-  ],
-  "currentReadPos": 1,
-  "hasMore": false
-}
-```
-
-### send_dm
-
-发送私信。
-
-**参数:**
-- `targetId`: 目标用户ID（string，必需）
-- `content`: 消息内容（string，必需）
-- `requireReply`: 是否需要回复（boolean，可选）
-- `replyToCallId`: 回复的调用ID（string，可选）
-- `timeoutMs`: 超时时间（number，可选）
-
-**调用式返回值:**
-```json
-{
-  "reply": {
-    "msgId": "...",
-    "content": "...",
-    "senderId": "...",
-    "senderName": "...",
-    "timestamp": "..."
-  }
-}
-```
-
-### get_dm_messages
-
-获取私信（支持阻塞等待）。
-
-**参数:**
-- `blockIfEmpty`: 无消息时是否阻塞等待（boolean，可选，默认true）
-- `blockTimeoutMs`: 阻塞超时时间（number，可选）
-
-### start_message_loop
-
-启动消息主循环，开始监听收到的消息。
-
-### stop_message_loop
-
-停止消息主循环。
-
-### get_state
-
-获取当前 Agent 状态。
-
-**返回值:**
-```json
-{
-  "agentId": "...",
-  "displayName": "...",
-  "isConnected": true,
-  "isRunning": false
-}
+## MCP 工具
+
+工具按能力分组，默认收纳；实例能力配置决定展开哪些组。以下为核心工具（完整自定义 MCP / 插件工具另行注入）。
+
+### 身份与发现
+
+| 工具 | 说明 |
+| --- | --- |
+| `get_profile` | 当前 Agent 信息、角色、实例、模型与提示词分层 |
+| `get_colleague` | 可见同事（含离线）、在线状态、当前动作、工作区与邮箱 |
+| `get_group_rooms` | 可发现的群组（项目公共群 + 组内群） |
+| `list_project_members` | 项目人类成员（含离线）与项目角色 |
+| `list_colleague_events` | 分页查看同事行为时间线 |
+| `hire_colleague` | 发起招聘同事请求（单个/批量，需审批） |
+
+### 消息
+
+| 工具 | 说明 |
+| --- | --- |
+| `poll_message` | 阻塞获取未读私信、群聊、任务与插件事件；主循环入口 |
+| `get_message` | 非阻塞获取未读消息 |
+| `send_group` | 发群消息：可选 `projectId`、`roomId`、附件、卡片与引用 |
+| `send_private` | 发私信：`waitReply` 调用式、`replyToCallId` 回复、`priority=force` 强制纠偏 |
+| `get_dm_history` | 私信历史（可按目标用户/时间过滤） |
+| `get_group_history` | 群聊历史 |
+
+### 流程任务
+
+| 工具 | 说明 |
+| --- | --- |
+| `my_task` | 当前已分配/处理中的流程任务与输出契约 |
+| `submit_task_result` | 按 `requiredOutput` 提交结果、交付物与变更日志 |
+| `list_task_node_iterations` | 节点历史迭代 |
+| `create_task_instance_comment` | 给流程实例留言 |
+| `start_task_rollback` / `finish_task_rollback` | AI 回退任务 |
+
+### 记忆
+
+| 工具 | 说明 |
+| --- | --- |
+| `create_memory` / `read_memory` / `update_memory` / `delete_memory` | 记忆增删改查 |
+| `search_memory` / `list_memories` / `list_memories_by_file` | 检索、列表与按文件查询 |
+| `get_memory_stats` / `report_memory_stats` | 统计与上报 |
+| `claim_memory_update` / `renew_memory_lease` / `release_memory_update` | 文件变更更新租约 |
+
+### 产物与协作
+
+| 工具 | 说明 |
+| --- | --- |
+| `pencil_*` | 设计画布：创建、读取、节点编辑、分享、导出 |
+| `draw_*` | draw.io：创建、读取、cell 编辑、分享、导出 |
+| `office_*` | Word/Excel/PowerPoint：创建、查看、编辑、校验、预览、格式、云文档协作 |
+| `create_meeting` / `leave_meeting` / `end_meeting` / `meeting_speak` / `get_meeting_info` / `my_meetings` | 会议 |
+| `send_email` / `list_emails` / `read_email` / `reply_email` / `ack_email` | 角色实例域名邮箱 |
+
+### 研发与能力
+
+| 工具 | 说明 |
+| --- | --- |
+| `launch_config_*` | 项目业务程序启动项管理 |
+| `query_debug_logs` / `get_debug_log_config` | Debug 日志 |
+| `query_file_changes_history` | 跨角色/实例的文件变更历史 |
+| `list_ability_market` / `install_ability_market_item` / `uninstall_ability_market_item` | 能力市场 |
+| `ability_dev_ide` / `formal_ability` / `list_my_abilities` | 自研能力：读规范、临时挂载调试、转正、查看 |
+
+## 消息主循环
+
+`poll_message` 是 Agent 获取工作的统一入口。它会在一个调用内持续等待，直到出现可处理的事件或需要返回状态：
+
+```text
+Agent 启动
+  └─ 注册上线（Bridge 注入身份与 token）
+      └─ poll_message（持续阻塞）
+          ├─ 私信 / 群聊消息
+          ├─ 流程线任务分配
+          ├─ 插件监听器事件
+          ├─ 后台任务 / 子 Agent 状态
+          └─ 系统通知与能力热推
+              └─ 处理 → 回复/提交 → 再次 poll_message
 ```
 
-## 消息主循环流程
-
-```
-Agent 主循环:
-  ┌──────────────────────────────────────────┐
-  │  1. register() → 注册上线                 │
-  │  2. start_message_loop() → 启动循环       │
-  │  3. while(运行中):                         │
-  │     a. get_dm_messages() → 获取私信       │
-  │        ├── 有未读消息 → 立即返回          │
-  │        └── 无未读消息 → 阻塞等待          │
-  │     b. 处理私信消息                       │
-  │        - 调用式消息 → 处理 → 回复         │
-  │        - 通知式消息 → 处理/记录           │
-  │     c. get_group_messages() → 获取群聊    │
-  │     d. 处理群聊消息                       │
-  │  4. stop_message_loop() → 停止循环        │
-  │  5. unregister() → 注销下线               │
-  └──────────────────────────────────────────┘
-```
+WebSocket 消息会立即唤醒等待；监听器、记忆变更、Todo 等通过内部节拍轮询。断线后自动重连并恢复未读游标。
 
 ## 开发
 
 ```bash
-# 开发模式（自动编译）
-npm run dev
-
-# 构建
+npm run dev        # TypeScript watch
 npm run build
-
-# 运行
 npm start
+npm test
+npm run lint
 ```
 
 ## 项目结构
 
-```
+```text
 aws-client-agent-mcp/
 ├── src/
-│   ├── index.ts           # 入口文件
-│   ├── mcp-server.ts      # MCP Server 实现
-│   ├── agent-client.ts    # Agent 客户端核心
-│   ├── websocket-client.ts # WebSocket 客户端
-│   ├── config.ts          # 配置管理
-│   └── types.ts           # 类型定义
-├── dist/                  # 编译输出
-├── package.json
-├── tsconfig.json
-└── README.md
+│   ├── index.ts             # stdio MCP 入口
+│   ├── mcp-server.ts        # MCP Server 与工具分发
+│   ├── mcp-tools.ts         # 工具 schema 定义
+│   ├── tool-groups.ts       # 能力分组、收纳/展开与提示词清单
+│   ├── agent-client.ts      # 注册、消息循环、重连
+│   ├── http-client.ts       # /mcp/call 调用
+│   ├── websocket-client.ts  # 实时通道
+│   ├── message-buffer.ts    # 未读缓冲与去重
+│   ├── memory-store.ts      # 本地记忆存储
+│   ├── context-manager.ts   # 上下文压缩
+│   ├── office/              # Office 文件处理
+│   └── config.ts            # 环境变量与运行态配置
+├── dist/
+└── package.json
 ```
 
 ## 与调度中心集成
 
-确保调度中心（aws-mcp-server）已启动并运行在配置的地址上。
-
-调度中心仓库: `aws-mcp-server/`
+确保 `aws-mcp-server` 已启动且地址可达。推荐通过 Bridge 面板完成注册与实例配置；手动运行时需自行保证 `AWS_SERVER_URL`、`AWS_MCP_HTTP_URL` 与 token 有效。
 
 ## License
 

package/package/aws-client-agent-mcp/dist/ability-market-tools.d.ts

@@ -1,18 +1,75 @@
 
+
+
+
+
+
+
+
+
+
+
+
+
+
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 
 export declare const LIST_ABILITY_MARKET_TOOL: Tool;
 
+
+
+
+
 export declare const INSTALL_ABILITY_MARKET_ITEM_TOOL: Tool;
 
 export declare const UNINSTALL_ABILITY_MARKET_ITEM_TOOL: Tool;
 
+
+
+
+
+
+
 export declare const ABILITY_MARKET_TOOL_NAMES: ReadonlySet<string>;
 
+
+
+
+
+
+
+
+
 export declare const ABILITY_DEV_TOOL_NAMES: ReadonlySet<string>;
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 export declare const ABILITY_DEV_IDE_TOOL: Tool;
 
+
+
+
+
+
+
 export declare const FORMAL_ABILITY_TOOL: Tool;
 
+
+
+
+
+
+
 export declare const LIST_MY_ABILITIES_TOOL: Tool;