aws-runtime-bridge 1.0.0

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

@@ -0,0 +1,288 @@
+# aws-client-agent-mcp
+
+AgentsWorkStudio - Agent MCP Client
+
+编程 Agent 与调度中心的通信桥梁，基于 MCP (Model Context Protocol) 协议实现。
+
+## 功能特性
+
+- **注册上线**: Agent 通过 MCP Tool 注册到调度中心，获得唯一标识
+- **同事发现**: 查询当前 Agent 可见的同事 Agent 列表（包含在线和离线）
+- **群聊消息**: 发送和接收公共群聊消息（支持未读消息指针）
+- **私信消息**: 
+  - 通知式: 发送后不阻塞
+  - 调用式: 发送后阻塞等待回复（带超时机制）
+- **消息主循环**: 持续监听和处理收到的消息
+- **自动重连**: WebSocket 断线后自动重连
+
+## 安装
+
+```bash
+# 克隆项目后进入目录
+cd aws-client-agent-mcp
+
+# 安装依赖
+npm install
+
+# 编译 TypeScript
+npm run build
+
+# 全局安装为命令行工具
+npm install -g .
+```
+
+安装完成后可直接使用全局命令：
+
+```bash
+aws-client-agent-mcp
+```
+
+## 配置
+
+### 环境变量
+
+| 变量名 | 说明 | 默认值 |
+|--------|------|--------|
+| `AWS_SERVER_URL` | 调度中心 WebSocket 地址 | `ws://localhost:8080/ws/agent` |
+| `AWS_WORKSPACE_PATH` | Agent 所在工作区路径 | 当前进程工作目录 |
+| `AWS_ROLE_NAME` | Agent 角色名，可为空，角色配置主要由后端 runtime-bridge 提供 | 空字符串 |
+| `AWS_PROJECT_NAME` | Agent 所属项目名 | `default` |
+| `AWS_PROMPT` | Agent 提示词，可为空，角色配置主要由后端 runtime-bridge 提供 | 空字符串 |
+| `AWS_AGENT_ID` | 预设 Agent ID，用于绑定已有实例 | 未设置 |
+| `AWS_INTERNAL_API_KEY` | 调度中心内部 API 密钥 | `agentswork-internal-dev-key` |
+| `AWS_HEARTBEAT_INTERVAL` | 心跳间隔（毫秒） | `3000` |
+| `AWS_HEARTBEAT_TIMEOUT` | 心跳超时时间（毫秒） | `9000` |
+| `AWS_MCP_HTTP_URL` | 调度中心 MCP HTTP 调用地址 | 根据 `AWS_SERVER_URL` 推导为 `/mcp/call` |
+
+> 注意：当前实现不再读取 `AWS_CONFIG_PATH`。作为 stdio MCP Server 运行时，stdout 必须只输出 JSON-RPC 消息，普通日志会输出到 stderr，避免污染 MCP 握手协议。
+
+## 使用方式
+
+### 方式一: 作为 MCP Server 使用（推荐）
+
+在 Claude Desktop 或 Cline 的配置中添加：
+
+```json
+{
+  "mcpServers": {
+    "agentswork": {
+      "command": "node",
+      "args": ["/path/to/aws-client-agent-mcp/dist/index.js"],
+      "env": {
+        "AWS_SERVER_URL": "ws://localhost:7380/ws/agent",
+        "AWS_WORKSPACE_PATH": "/absolute/path/to/project",
+        "AWS_PROJECT_NAME": "default"
+      }
+    }
+  }
+}
+```
+
+### 方式二: 命令行运行
+
+```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",
+      "projectName": "demo",
+      "roomType": "project",
+      "scopeRefId": "demo",
+      "name": "demo 公共群聊",
+      "memberUserIds": ["agent_001"]
+    },
+    {
+      "id": "inner_group:g-1",
+      "projectName": "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
+}
+```
+
+## 消息主循环流程
+
+```
+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() → 注销下线               │
+  └──────────────────────────────────────────┘
+```
+
+## 开发
+
+```bash
+# 开发模式（自动编译）
+npm run dev
+
+# 构建
+npm run build
+
+# 运行
+npm start
+```
+
+## 项目结构
+
+```
+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
+```
+
+## 与调度中心集成
+
+确保调度中心（aws-mcp-server）已启动并运行在配置的地址上。
+
+调度中心仓库: `aws-mcp-server/`
+
+## License
+
+MIT

package/package/aws-client-agent-mcp/dist/activity-reporter.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Agent 活动上报服务
+ * 负责将 Agent 的活动状态实时上报到调度中心
+ */
+import type { AgentActivityEvent, ActivityEventType } from './activity-types.js';
+/**
+ * 活动上报服务配置
+ */
+interface ActivityReporterConfig {
+    /** WebSocket 客户端 */
+    wsClient: {
+        send: (message: unknown) => Promise<void>;
+        isConnected: () => boolean;
+    };
+    /** Agent ID */
+    agentId: string;
+    /** 是否启用上报 */
+    enabled: boolean;
+    /** 批量上报间隔(ms) */
+    batchInterval?: number;
+    /** 批量大小 */
+    batchSize?: number;
+}
+export type ActivityReporterTransport = ActivityReporterConfig['wsClient'];
+interface OperationOptions {
+    detail?: string;
+    toolName?: string;
+    toolInput?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    inputSummary?: string;
+    parentOperationId?: string;
+}
+interface OperationCompletionOptions {
+    detail?: string;
+    resultSummary?: string;
+    metadata?: Record<string, unknown>;
+}
+interface WaitingStateOptions {
+    parentOperationId?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Agent 活动上报服务
+ */
+export declare class ActivityReporter {
+    private config;
+    private pendingQueue;
+    private batchTimer;
+    private isProcessing;
+    private maxRetries;
+    private activeOperations;
+    constructor(config: ActivityReporterConfig);
+    /**
+     * 启动批量上报定时器
+     */
+    private startBatchTimer;
+    /**
+     * 停止批量上报
+     */
+    stop(): void;
+    /**
+     * 上报活动事件
+     */
+    reportActivity(event: AgentActivityEvent): void;
+    /**
+     * 上报活动事件（便捷方法）
+     */
+    report(type: ActivityEventType, detail: string, toolName?: string, toolInput?: Record<string, unknown>): void;
+    /**
+     * 生成并上报结构化操作开始事件
+     */
+    startOperation(type: ActivityEventType, options?: OperationOptions): string;
+    /**
+     * 上报操作完成事件
+     */
+    completeOperation(operationId: string, options?: OperationCompletionOptions): void;
+    /**
+     * 上报操作失败事件
+     */
+    failOperation(operationId: string, error: string | Error, options?: Omit<OperationCompletionOptions, 'resultSummary'>): void;
+    /**
+     * 上报等待态
+     */
+    reportWaitingState(type: Extract<ActivityEventType, 'waiting_reply' | 'waiting_permission'>, detail: string, options?: WaitingStateOptions): void;
+    startSkillOperation(skillName: string, metadata?: Record<string, unknown>, detail?: string): string;
+    startMcpOperation(serverName: string, toolName: string, toolInput?: Record<string, unknown>, detail?: string): string;
+    /**
+     * 上报工具调用
+     */
+    reportToolUse(toolName: string, toolInput: Record<string, unknown>): void;
+    /**
+     * 上报 Skill 调用
+     */
+    reportSkillUse(skillName: string, detail?: string): void;
+    /**
+     * 上报 MCP 调用
+     */
+    reportMcpUse(serverName: string, toolName: string, detail?: string): void;
+    /**
+     * 上报思考中状态
+     */
+    reportThinking(detail?: string): void;
+    /**
+     * 上报空闲状态
+     */
+    reportIdle(): void;
+    /**
+     * 上报等待回复状态
+     */
+    reportWaitingReply(): void;
+    /**
+     * 上报错误
+     */
+    reportError(error: string | Error): void;
+    private createOperationEvent;
+    /**
+     * 刷新待上报的活动
+     */
+    private flushPending;
+    /**
+     * 获取待上报队列大小
+     */
+    getPendingCount(): number;
+    /**
+     * 是否启用
+     */
+    isEnabled(): boolean;
+    /**
+     * 设置启用状态
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * 更新当前 reporter 绑定的 agentId。
+     */
+    setAgentId(agentId: string): void;
+}
+/**
+ * 初始化全局 ActivityReporter
+ */
+export declare function initActivityReporter(config: ActivityReporterConfig): ActivityReporter;
+/**
+ * 获取全局 ActivityReporter
+ */
+export declare function getActivityReporter(): ActivityReporter | null;
+/**
+ * 停止全局 ActivityReporter
+ */
+export declare function stopActivityReporter(): void;
+export {};
+//# sourceMappingURL=activity-reporter.d.ts.map

package/package/aws-client-agent-mcp/dist/activity-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-reporter.d.ts","sourceRoot":"","sources":["../src/activity-reporter.ts"],"names":[],"mappings":"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"}