@hile/micro 1.0.4 → 1.0.5

package/README.md

@@ -1,14 +1,24 @@
 # @hile/micro
 
-基于 `@hile/message-loader` 与 `@hile/message-ws` 的轻量级 **WebSocket 服务注册与发现**：用固定格式的连接 URL 标识对端，`Registry` 按逻辑 namespace 记录实例，`Application` 从注册中心拉取地址并缓存到远端服务的会话。
+基于 `@hile/message-loader` 与 `@hile/message-ws` 的轻量级 **WebSocket 微服务框架**。提供服务注册与发现、心跳保活、熔断、请求超时、自动重试、调用链路追踪等功能。
 
-## 概念分层
+## 架构分层
 
-1. **`Server`**：实现「服务」的 **底层协议与运行时**——基于 `ws` 监听、按路径解析对端身份，对内用 `MessageLoader` 做 `{ url, data }` 路由；不关心注册中心，只负责连接语义与消息派发。
-2. **`Registry`**：**注册中心**，维护「逻辑 namespace → 一组实例地址」，`/-/find` 随机返回其一。
-3. **`Application`**：**基于 `Server` 的具体应用侧实现**——继承 `Server`，在 `listen` 后自动连上 `Registry`，用 `get(namespace)` 发现其它服务并缓存 `Client`。
+```
+MessageLoader (路由) + MessageWs (请求/响应传输)
+  └── Server（WebSocket 服务底层）
+        ├── Registry（注册中心）
+        └── Application（应用服务）
+```
+
+| 组件 | 职责 |
+|------|------|
+| **Server** | WebSocket 监听、连接管理、消息路由。不关心注册中心 |
+| **Client** | 远端 Server 的代理，提供 `request()` / `push()` 通信接口 |
+| **Registry** | 注册中心。维护 namespace → 实例列表，心跳检测剔除死实例 |
+| **Application** | 应用服务。集成注册发现、熔断、重试、追踪等功能 |
 
-同一进程里通常只建一个 `Application`，它 **同时** 扮演 **provider**（`register` 暴露接口）与 **consumer**（`get` + `request`/`push` 调用其它 namespace）；文档里把「提供方 / 调用方」拆开示例，是为了说明两种用法，而不是两类不同的类。
+一个 `Application` 实例 **同时** 扮演 provider（`register` 暴露接口）和 consumer（`get` / `call` 调用其它服务）。
 
 ## 安装
 
@@ -16,34 +26,13 @@
 pnpm add @hile/micro
 ```
 
-依赖：`@hile/message-loader`、`@hile/message-ws`、`ws`（随 workspace 一并解析）。
-
----
-
-## 能做什么？
-
-| 组件 | 作用 |
-|------|------|
-| `Server` | **底层协议**：监听 WebSocket；解析路径中的调用方地址与可选分段；对内用 `register`/`dispatch` 处理 `{ url, data }` |
-| `Client` | 连到远端 `Server`，`request`/`push` 走 `MessageModem`，`dispose()` 会关闭底层连接 |
-| `Registry` | **注册中心**：固定 namespace `'registry'`；实例上线/下线更新 namespace→地址集合；`/-/find` **随机** 返回其中一个地址 |
-| `Application` | **基于 `Server` 的应用实现**：启动后连接 Registry；`register` 侧即 provider、`get` 侧即 consumer；`get(ns)` 查询并 **缓存** 到目标服务的 `Client`，断连后清空缓存 |
-
-连接串格式（出站）：
-
-`ws://目标主机:端口/{宣告地址}/{本机监听端口}/{本机namespace}`
-
-宣告地址：构造 `Server` / `Application` / `Registry` 时可通过 **`advertiseHost`** 显式传入；未传则使用 `getLocalIPv4()`。若二者皆无（例如无可用 IPv4），**构造阶段即抛错**。容器、多网卡或 CI 环境建议设置 `advertiseHost`（如 `127.0.0.1` 或 Pod IP）。
-
-`Application` 还支持 **`registryLookupTimeoutMs`**（默认 `10000`），限制对 Registry `/-/find` 的响应等待时间。
-
-出站 `connect` 默认 **5 秒**握手超时，超时报错 `Connection timeout`。
+依赖：`@hile/message-loader`、`@hile/message-ws`、`ws`。
 
 ---
 
-## 快速示例
+## 快速开始
 
-### 1. Registry
+### 1. 启动 Registry
 
 ```typescript
 import { Registry } from '@hile/micro';
@@ -52,7 +41,9 @@ const registry = new Registry({ advertiseHost: '127.0.0.1' });
 await registry.listen(9000);
 ```
 
-### 2. 服务提供方（被其它 Application 发现的进程）
+### 2. 启动 Provider（服务 A）
+
+以下 `provider` 和 `consumer` 是两个不同进程（不同 namespace），**每个进程只需要一个 `Application` 实例**，同时扮演 provider 和 consumer：
 
 ```typescript
 import { Application } from '@hile/micro';
@@ -70,7 +61,7 @@ provider.register('/charge', async ({ data }) => {
 });
 ```
 
-### 3. 调用方（通过 Registry 解析地址）
+### 3. 启动 Consumer 调用（服务 B）
 
 ```typescript
 import { Application } from '@hile/micro';
@@ -83,38 +74,280 @@ const consumer = new Application({
 
 await consumer.listen(9200);
 
-const remote = await consumer.get('payments');
-const { response } = remote.request('/charge', { amount: 100 });
-const result = await response<{ charged: boolean; amount: number }>();
-console.log(result);
+// call() = get() + request() + response() + 熔断 + 重试
+const result = await consumer.call('payments', '/charge', { amount: 100 });
+console.log(result); // { charged: true, amount: 100 }
 ```
 
-### 关闭
+### 4. 关闭
 
-`listen` 返回的 teardown 函数会关闭 WebSocketServer 并对已有 `Client` 调用 `dispose()`：
+`listen()` 返回的 teardown 函数关闭 WebSocketServer 并断开所有连接：
 
 ```typescript
 const stop = await provider.listen(9100);
-// ...
 await stop();
 ```
 
 ---
 
-## 与 Hile core 的关系
+## 核心功能
 
-`@hile/micro` **不依赖** `@hile/core`，可与任意 Node.js 进程或在未来由 `defineService` 包装后接入 Hile 容器。
+### 服务发现 (`get`)
 
----
+按 namespace 从 Registry 获取一个远端 Client 并缓存：
+
+```typescript
+const client = await consumer.get('payments');
+const { response } = client.request('/charge', { amount: 100 });
+const result = await response();
+```
+
+- 首次查询通过 Registry `/-/find` 获取地址
+- 结果**缓存**在内存中（namespace → Client）
+- 当 Client 断连时自动清理缓存，下次 `get` 重新发现
+
+### 熔断器 (Circuit Breaker)
+
+`call()` 自动跟踪每个 namespace 下各 peer 的调用失败。失败的 peer 被临时排除，**30 秒冷卻期**后自动恢复。
+
+| 场景 | 行为 |
+|------|------|
+| 调用 peer A 失败 | A 加入排除列表（30s cooldown） |
+| 再次调用该 namespace | Registry `/‑/find` 带上 `exclude`，返回其他 peer |
+| 所有 peer 都被排除 | 重置排除列表，重新从所有 peer 中选择 |
+| 调用成功 | 该 peer 从排除列表中移除 |
+
+排除列表：
+- 键：`${host}:${port}`
+- 存储：`Map<namespace, Map<peerKey, openedAt>>`
+- 冷卻期：`CB_COOLDOWN_MS = 30_000`（30 秒）
+- 过期检查：`getActiveExcludes()` 在每次 `call()` 调用时执行
+
+### 请求超时
+
+每个请求都有超时控制：
+
+```typescript
+// 构造时设置全局默认超时
+const app = new Application({
+  namespace: 'svc',
+  registry: { host, port },
+  requestTimeoutMs: 10_000,  // 默认 30000ms
+});
+
+// 单次调用覆盖
+await app.call('svc', '/api', data, 5_000);   // 5s 超时
+await app.call('svc', '/api', data, 1_000, 0); // 1s 超时, 不重试
+```
+
+超时触发时，底层 MessageModem 会向对端发送 **ABORT** 消息取消远程执行。
+
+### 手动取消请求
+
+使用 `get()` 拿到 Client 后，`request()` 返回的 `abort()` 可主动取消正在等待响应的请求：
+
+```typescript
+const client = await consumer.get('payments');
+const { response, abort } = client.request('/charge', { amount: 100 });
+
+// 例如 5 秒后主动取消
+setTimeout(() => abort(), 5000);
+
+try {
+  const result = await response();
+} catch (err) {
+  // 超时或手动 abort 都会 reject
+}
+```
+
+- `abort()` 向对端发送 **ABORT 消息**，让远程 handler 提前终止
+- 超时到期内部也会调用 `controller.abort()`，机制相同
+- 适用场景：用户取消、页面卸载、竞态淘汰
+
+### 自动重试
+
+`call()` 默认 retries=1，失败后自动换 peer 重试：
+
+```typescript
+await app.call('svc', '/api', data);        // 默认重试 1 次
+await app.call('svc', '/api', data, 5000, 3); // 超时 5s, 重试 3 次
+await app.call('svc', '/api', data, 5000, 0); // 超时 5s, 不重试
+```
+
+重试策略：失败 → `recordFailure`（peer 被排除）→ 递归 `call(retries-1)` → `getActiveExcludes` 排除已失败的 peer → Registry `/‑/find` 返回其他 peer。
+
+### Correlation ID 链路追踪
+
+`call()` 自动为每次调用注入唯一 `_correlationId`：
+
+```typescript
+provider.register('/api', async ({ data }) => {
+  console.log(data._correlationId); // 自动注入的 UUID
+});
+```
+
+行为规则：
+
+| 入参 data | 结果 |
+|-----------|------|
+| `null / undefined` | 包装为 `{ _correlationId, data: null }` |
+| 字符串 / 数字 | 包装为 `{ _correlationId, data: '原始值' }` |
+| 数组 | 包装为 `{ _correlationId, data: [原始数组] }` |
+| `{ value: 1 }` (无 `_correlationId`) | 扩展为 `{ value: 1, _correlationId: 'uuid' }` |
+| `{ _correlationId: 'trace-1' }` | 保留已有 ID，**不覆盖** |
 
-## 文档策略
+> **注意：** 原 data 对象不会被修改（使用浅拷贝 `{ ...data, _correlationId }`）。
 
-| 文档 | 读者 | 用途 |
+### 健康检查
+
+每个 `Application` 自动注册 `/-/health` 端点：
+
+```typescript
+// 通过 dispatch 调用（同进程内）
+const health = await app.dispatch('/-/health', {});
+// { status: 'ok', registry: true, uptime: 123.45, namespaces: ['payments'] }
+```
+
+返回字段：
+
+| 字段 | 类型 | 说明 |
 |------|------|------|
-| 本 README | 使用者 | 安装、概念、示例 |
-| `SKILL.md` | AI / 贡献者 | 路由约定、类型、反模式、测试门禁 |
+| `status` | `'ok'` | 固定值 |
+| `registry` | `boolean` | 是否已连接 Registry |
+| `uptime` | `number` | 进程启动时长（秒） |
+| `namespaces` | `string[]` | 本地已缓存的 namespace 列表 |
+
+### 缓存降级
+
+当 Registry 不可用但本地仍有已缓存的 Client 连接时，`get()` 自动降级使用缓存：
+
+| 场景 | 行为 |
+|------|------|
+| Registry 宕机 + 缓存有效 | 返回缓存 Client，继续服务 |
+| Registry 宕机 + 缓存已过期 | 报错 |
+| 全新 namespace + Registry 宕机 | 报错 |
+| Registry 恢复 | 恢复正常查询 |
+
+### Registry 心跳保活
+
+- **Application** 每 10 秒向 Registry 推送 `/-/heartbeat`
+- **Registry** 每 1 秒检查所有实例的心跳时间戳
+- 超过 20 秒未收到心跳的实例被自动剔除并断开连接
+
+### Registry 重连
+
+当 Application 与 Registry 的连接断开时：
+1. 立即尝试重连（`reconnectToRegistry`）
+2. 若失败，3 秒后重试（`scheduleRegistryRetry`）
+3. 若 `listen()` 返回的 teardown 已触发（`stopped = true`），停止重连
+
+---
+
+## 连接协议
+
+### 连接 URL 格式
+
+出站 WebSocket URL：
+
+```
+ws://{targetHost}:{targetPort}/{announceHost}/{listenPort}/{namespace}
+```
+
+- `announceHost`：构造时传入 `advertiseHost` 或自动获取的 IPv4
+- `listenPort`：`listen(port)` 设置的端口
+- `namespace`：构造时传入的 namespace 字符串
+
+### 入站路径解析
+
+`Server.onConnected` 将 URL 路径按 `/` 分割为：
+
+```
+[callerHost, callerPort, ...extras]
+```
+
+- `extras` 以 `/` 分段，Registry 用 `extras.join('/')` 作为 namespace
+
+---
+
+## API 参考
+
+### ApplicationProps
+
+```typescript
+type ApplicationProps = {
+  namespace: string;                           // 本服务 namespace
+  registry: { host: string; port: number };    // Registry 地址
+  registryLookupTimeoutMs?: number;            // /-/find 超时，默认 10000
+  requestTimeoutMs?: number;                   // 单次请求超时，默认 30000
+} & { advertiseHost?: string };                // 出站宣告地址
+```
+
+### Application
+
+```typescript
+class Application extends Server {
+  constructor(props: ApplicationProps);
+
+  // 启动监听，自动连接 Registry，启动心跳
+  listen(port: number): Promise<() => Promise<void>>;
+
+  // 获取 namespace 对应的远端 Client（缓存 + 自动发现）
+  get(namespace: string, exclude?: string[]): Promise<Client>;
+
+  // 一站式调用：get + request + response + 熔断 + 重试 + 追踪
+  call<T = any>(
+    namespace: string,
+    url: string,
+    data: any,
+    timeout?: number,     // 请求超时（ms），默认 requestTimeoutMs
+    retries?: number,     // 失败重试次数，默认 1
+  ): Promise<T>;
+
+  // 注册路由（provider 侧）
+  register<T = any>(url: string, handler: (ctx) => Promise<T>): () => void;
+
+  // 同进程调用路由
+  dispatch(url: string, data: any): Promise<any>;
+}
+```
+
+### Registry
+
+```typescript
+class Registry extends Server {
+  constructor(props?: MicroServerProps);
+  listen(port: number): Promise<() => Promise<void>>;
+  onFind(): void; // 幂等地挂载 /-/find 路由
+}
+```
+
+### Server
+
+```typescript
+class Server extends MessageLoader {
+  constructor(namespace: string, props?: MicroServerProps);
+  listen(port: number): Promise<() => Promise<void>>;
+  setPort(port: number): this;
+  // 以下方法受保护：
+  protected connect(host: string, port: number, timeout?: number): Promise<Client>;
+}
+```
+
+### Client
+
+```typescript
+class Client extends MessageWs {
+  request(url: string, data: any, timeout?: number): { abort(): void; response<T>(): Promise<T> };
+  push(url: string, data: any, timeout?: number): void;
+  dispose(): void;
+}
+```
+
+---
+
+## 与 Hile core 的关系
 
-仓库线上文档见 Mintlify：**API 参考 → @hile/micro**（若已启用）。
+`@hile/micro` 不依赖 `@hile/core`，可与任意 Node.js 进程或在未来由 `defineService` 包装后接入 Hile 容器。
 
 ---
 

package/SKILL.md

@@ -1,163 +1,520 @@
 ---
 name: micro
-description: Code generation and contribution rules for @hile/micro. Use when editing this package or when the user asks about @hile/micro patterns or API.
+description: Code generation and contribution rules for @hile/micro. Use when editing this package or when the user asks about @hile/micro API, types, patterns, or features.
 ---
 
-# @hile/micro
+# @hile/micro — AI Skill Reference
 
-本文档面向 **AI 编码模型** 与 **贡献者**：在修改或生成 `@hile/micro` 相关代码前必读，保证与现有 WebSocket 路由、注册中心与 `MessageLoader` 约定一致。
+本文档面向 **AI 编码模型**。在生成或修改 `@hile/micro` 代码前必读，保证与现有架构、API 约定、状态机、测试模式一致。
 
 ---
 
 ## 1. 架构总览
 
-`@hile/micro` 在 `@hile/message-loader` + `@hile/message-ws` 之上提供 **轻量级进程间服务发现与会话**。分层理解：
-
-- **`Server`**：实现服务的 **底层协议与运行时**——`WebSocketServer` + 路径约定；对内 `MessageLoader.register` / `dispatch` 完成 `{ url, data }` 路由。不包含注册中心逻辑。
-- **`Registry`**：**注册中心**，固定 `namespace` 为 `'registry'`，维护「逻辑 namespace → 一组 `host:port`」；`/-/find` 在集合中 **随机** 返回一条地址（见 `selectRandomRegistryAddress`）。
-- **`Application`**：**基于 `Server` 的应用侧实现**（`extends Server`）；`listen(port)` 后自动 `connect` 到注册中心；`get(targetNamespace)` 向注册中心查询并 **缓存** 到目标服务的 `Client`，目标断连后删除缓存以便下次重新发现。
-- **`Client`**：连接到远端 `Server`，`request(url, data)` / `push(url, data)` 将负载交给本端 `Server.dispatch`；`dispose()` 会移除监听并 **关闭底层 WebSocket**，避免 `listen` 关闭阶段挂住。
-
-**应用模型**：`Application = provider + consumer`——同一实例既可 `register(...)`（对外提供能力），也可 `get(ns)` 再 `request`/`push`（消费其它 namespace）。文档示例常拆成两个进程分别演示 provider / consumer，API 层面仍是同一个类。
-
-依赖链：
+### 依赖链
 
 ```
-MessageLoader (路由) + MessageWs (请求/响应传输)
-  └── Server（底层协议）+ Client
-        ├── Registry（注册中心，一种特殊的 Server 用法）
-        └── Application（基于 Server，叠加上注册发现）
+@hile/message-loader (路由: register/dispatch)
+  └── @hile/message-ws (WebSocket 请求/响应, MessageModem timeout/abort)
+        └── packages/micro
+              ├── Server   — WebSocket 监听 + 连接管理 + Client 生命周期
+              ├── Client   — 远端代理, request/push/dispose
+              ├── Registry — 注册中心 (extends Server)
+              └── Application — 应用服务 (extends Server)
 ```
 
----
+### 分层职责
 
-## 2. 路由与 URL 约定（强约束）
+| 类 | 文件 | 职责 | 关键约束 |
+|----|------|------|---------|
+| `Server` | `server.ts` | WebSocketServer 生命周期, 出入站连接, Client Map | 不感知 Registry |
+| `Client` | `client.ts` | 远端 Server 的 WebSocket 会话代理 | `dispose()` 必须关闭底层 socket |
+| `Registry` | `registry.ts` | namespace → Set\<host:port\>, 心跳检测, /-/find 随机返回 | `namespace` 固定 `'registry'` |
+| `Application` | `application.ts` | 注册发现 + 熔断 + 重试 + 追踪 + 心跳 | `listen()` 后自动连 Registry |
 
-### 2.1 入站连接路径
+### 应用模型
 
-对端发起连接时的 URL 必须为：
+一个 `Application` 实例同时是 provider 和 consumer。不要创建两个类来区分角色。
 
-```text
-ws://{listenHost}:{listenPort}/{callerHost}/{callerPort}/{...extras}
+```
+Application:
+  └─ register(url, handler)   → provider 侧
+  └─ get(namespace)           → consumer 侧, 返回 Client
+  └─ call(namespace, url, data) → consumer 侧, get+request+熔断+重试 一站式
 ```
 
-解析规则见 `Server.onConnected`：
-
-- 至少 **三段** 路径：`callerHost`、`callerPort` 以及后续 `extras`（可为空）。
-- `extras` 以 `/` 分段，在 `events.emit('connect', client, extras)` 中交给业务；**Registry** 用 `extras.join('/')` 作为 **服务逻辑 namespace**。
+---
 
-生成侧：`Server.connect()` 使用：
+## 2. 类型定义（代码生成时必须一致）
 
-```text
-ws://{host}:{port}/${this.ipv4}/${this.port}/${this.namespace}
-```
+### Server (`server.ts`)
 
-其中 `this.ipv4` 来自 `getLocalIPv4()`（见 `utils.ts`），`this.port` 为当前 `listen` 端口，`this.namespace` 为构造传入的字符串（如 `provider`、`consumer`、`registry`）。
+```typescript
+export type MicroServerProps = MessageLoaderProps & {
+  advertiseHost?: string;  // 缺省 getLocalIPv4(), 皆无则构造抛错
+};
 
-### 2.2 MessageLoader 路由
+export class Server extends MessageLoader {
+  protected readonly clients = new Map<string, Client>(); // key: "host:port"
+  public readonly events = new EventEmitter(); // connect/disconnect
+
+  constructor(namespace: string, props?: MicroServerProps);
+  public listen(port: number): Promise<() => Promise<void>>; // 返回 teardown
+  public setPort(port: number): this;
+  protected connect(host: string, port: number, timeout?: number): Promise<Client>;
+  // 继承自 MessageLoader:
+  // register<T, E>(url, handler): () => void;
+  // dispatch(url, data, extras): Promise<any>;
+}
+```
 
-- 对内消息体为 `{ url, data }`，与 `Client.exec` 一致。
-- `Registry` 注册：`register<RegistryFindData>('/-/find', handler)`，请求体 `{ namespace: string }`。
+### Client (`client.ts`)
 
----
+```typescript
+export class Client extends MessageWs {
+  public readonly host: string;
+  public readonly port: number;
+  public readonly events = new EventEmitter(); // connect/disconnect
+
+  request(url: string, data: any, timeout?: number): {
+    abort(): void;
+    response<T = any>(): Promise<T>;  // 超时或 abort 时 reject
+  };
+  push(url: string, data: any, timeout?: number): void;
+  dispose(): void;  // 关闭底层 WebSocket
+}
+```
 
-## 3. 类型与关键 API（生成代码须一致）
+### Registry (`registry.ts`)
 
 ```typescript
-// server.ts
-export type MicroServerProps = MessageLoaderProps & {
-  /** 出站 URL 宣告段；缺省 getLocalIPv4()，皆无则构造抛错 */
-  advertiseHost?: string;
-};
+export interface RegistryFindData {
+  namespace: string;
+  exclude?: string[];
+}
 
-// registry.ts
 export function parseAddressKey(key: string): RegistryAddress | undefined;
+export function selectRandomRegistryAddress(keys: Iterable<string>): RegistryAddress | undefined;
 
-export function selectRandomRegistryAddress(
-  keys: Iterable<string>,
-): RegistryAddress | undefined;
+export class Registry extends Server {
+  // heartbeat 常量:
+  //   HEARTBEAT_INTERVAL = 1000   (1s 轮询)
+  //   HEARTBEAT_TIMEOUT = 20000   (20s 未收到心跳则剔除)
+  constructor(props?: MicroServerProps);
+  listen(port: number): Promise<() => Promise<void>>;
+  onFind(): void; // 幂等，可重复调用
+  // 内部路由:
+  //   /-/find     — 按 namespace 随机返回地址 (支持 exclude)
+  //   /-/heartbeat — 更新实例心跳时间戳
+}
+```
 
-export class Registry extends Server { /* constructor(props?: MicroServerProps); onFind() 幂等 */ }
+### Application (`application.ts`)
 
-// application.ts
+```typescript
 export type ApplicationProps = {
   namespace: string;
   registry: RegistryAddress;
-  /** 默认 10000；对 `/-/find` 的 response 等待上限 */
-  registryLookupTimeoutMs?: number;
+  registryLookupTimeoutMs?: number; // /-/find 超时, 默认 10_000
+  requestTimeoutMs?: number;        // 单次请求超时, 默认 30_000
 } & MicroServerProps;
 
 export class Application extends Server {
-  listen(port: number): Promise<() => Promise<void>>;
-  get(namespace: string): Promise<Client>;
+  // 内部常量:
+  //   HEARTBEAT_INTERVAL = 10000   (10s 向 Registry 推送心跳)
+  //   CB_COOLDOWN_MS = 30000      (熔断冷卻期 30s)
+  // 内部状态:
+  //   namespaces: Map<ns, { host, port, status: IDLE|PENDING|READY, handlers }>
+  //   circuitBreakers: Map<ns, Map<peerKey, openedAt>>
+
+  constructor(props: ApplicationProps);
+  listen(port: number): Promise<() => Promise<void>>; // 自动连 Registry + 启心跳
+
+  get(namespace: string, exclude?: string[]): Promise<Client>;
+  // call() = get + request + response + correlationId + 熔断 + 重试 + 超时
+  call<T = any>(
+    namespace: string,
+    url: string,
+    data: any,
+    timeout?: number,     // 单次超时, 默认 requestTimeoutMs
+    retries?: number,     // 重试次数, 默认 1
+  ): Promise<T>;
+
+  // 继承自 Server/MessageLoader:
+  // register<T, E>(url, handler): () => void;
+  // dispatch(url, data, extras): Promise<any>;
 }
+```
+
+---
 
-// server.ts — connect 第三参仅用于测试或内部，默认超时 5s
-protected async connect(host: string, port: number, timeout?: number): Promise<Client>;
+## 3. 功能详解（含状态机与逻辑流）
 
-// client.ts
-export class Client extends MessageWs {
-  request(url: string, data: any, timeout?: number): ReturnType<MessageWs['_send']>;
-  push(url: string, data: any, timeout?: number): void;
-  dispose(): void;
-}
+### 3.1 服务发现 `get(namespace, exclude?)`
+
+```
+get(ns, exclude?)
+  ├─ namespaces 无此 ns → 创建 IDLE 条目
+  ├─ status=READY + (client 已断连 or peer 被 exclude)
+  │     └─ 重置为 IDLE, 清空 host/port
+  ├─ status=READY + client 有效 + 未被 exclude
+  │     └─ 直接返回缓存 Client (快路径)
+  └─ 否则:
+        └─ 新建 Promise, handler 入队
+        └─ status=IDLE → PENDING → findFromRegistry(ns, exclude)
+              ├─ Registry 返回地址 → connect → status=READY
+              │     └─ 注册 disconnect → 清理 namespace 缓存
+              │     └─ resolve 所有 handler
+              └─ Registry 失败 or 无数据 →
+                    └─ catch: 检查旧缓存 (cachedHost/cachedPort)
+                          ├─ 缓存有效 → 降级: restore status=READY, resolve
+                          └─ 无缓存 → delete namespace, reject 所有 handler
+                    └─ finally: handlers.clear()
 ```
 
-`Application` 内部缓存查找状态为 `IDLE` → `PENDING` → `READY`：首次 `get` 必须从 `IDLE` 触发 `findFromRegistry`，禁止再出现「初始状态与触发条件不匹配」导致永久挂起。
+**关键点：**
+- `cachedHost` / `cachedPort` 在缓存失效前保存，用于降级路径
+- 降级时恢复 `stack.host/port/status=READY`，使后续调用走快路径
+- 多并发 `get()` 共享同一个 Promise，handler 入队后统一 resolve/reject
 
----
+### 3.2 熔断器 (Circuit Breaker)
+
+**数据结构：** `Map<namespace, Map<peerKey, openedAt>>`
+
+```
+call() 失败:
+  recordFailure(ns, host, port)
+    → excludes.set("host:port", Date.now())
+
+call() 成功:
+  recordSuccess(ns, host, port)
+    → excludes.delete("host:port")
+
+getActiveExcludes(ns):
+  → 遍历 excludes, 移除 Date.now() - openedAt >= 30000 的过期条目
+  → 返回活跃的 exclude key 数组
+```
+
+**生命周期：**
+
+```
+peer 首次失败
+  → circuitBreakers: { svc: { "127.0.0.1:8080": now } }
+  → getActiveExcludes("svc") → ["127.0.0.1:8080"]
+  → next call() 的 get() 带上 exclude, 排除该 peer
+  → Registry 返回其他 peer (有则) 或 undefined (无则)
+  → 如果所有 peer 都被排除, catch 块 delete circuitBreakers, 无 exclude 重试
+=> "全排除 → 重置" 策略: 当 Registry 找不到未被排除的 peer, 熔断器清空, 从不安全全量重试
+```
+
+**冷卻期:** `CB_COOLDOWN_MS = 30000` (30 秒)。到期后 `getActiveExcludes` 自动清除旧条目。
+
+### 3.3 Correlation ID
+
+`call()` 自动处理 `_correlationId`：
+
+```typescript
+// 非对象/假值/数组 → 包装
+!data || typeof data !== 'object' || Array.isArray(data)
+  → data = { _correlationId: randomUUID(), data }
+
+// 对象无 _correlationId → 浅拷贝注入
+else if (!data._correlationId)
+  → data = { ...data, _correlationId: randomUUID() }
+
+// 对象已有 _correlationId → 保留（透传）
+```
+
+- 使用 `import { randomUUID } from 'node:crypto'`（Node >= 14.17）
+- 永远不修改原始 data 对象（浅拷贝 `{ ...data }`）
+- retry 递归时 data 已包含 `_correlationId`，自动透传
+
+### 3.4 请求超时
+
+**配置链：**
+
+```
+ApplicationProps.requestTimeoutMs (default 30_000)
+  → call(timeout?)  // 可选 override
+    → client.request(url, data, timeout ?? this._requestTimeoutMs)
+      → MessageModem._send({ url, data }, timeout)
+        → MessageModem._write(data, timeout, twoway=true)
+          → setTimeout(reject, timeout)
+          → 超时: 发送 ABORT 消息 → 对端取消执行
+```
+
+- 超时默认 30 秒（MessageModem 默认值）
+- 超时触发时向对端发送 **ABORT** 消息（不是仅仅本地 reject）
+- 支持每个调用单独覆盖
+
+### 3.5 手动取消（abort）
+
+`client.request()` 返回的 `abort()` 函数可主动取消请求，**与超时共享同一套 ABORT 机制**：
+
+```typescript
+const client = await app.get('svc');
+const { response, abort } = client.request('/api', data);
+
+// 主动取消
+abort();
+await response(); // → reject (AbortException)
+
+// 典型场景：竞态淘汰
+const req = client.request('/slow', data);
+// 如果其他条件满足，提前取消
+if (cached) abort();
+```
+
+**实现原理：**
+- `request()` 内部通过 `MessageModem._write()` 创建 `AbortController`
+- `abort()` 调用 `controller.abort()` 触发 ABORT 消息发送
+- 超时到期也调用同一个 `controller.abort()`，机制完全相同
+- 区别仅在于触发源头：手动调用 vs 定时器到期
+
+**适用场景：** 用户取消操作、页面/组件卸载、竞态条件（先发请求后发先至时取消旧请求）
+
+```typescript
+call(ns, url, data, timeout, retries = 1):
+  get(ns, exclude) → client
+  try:
+    client.request(url, data, timeout) → response() → result
+    recordSuccess(ns, host, port)
+    return result
+  catch err:
+    recordFailure(ns, host, port)
+    if retries > 0:
+      return call(ns, url, data, timeout, retries - 1) // 递归
+    throw err
+```
+
+**重试语义：**
+- 首次失败 → peer 被排除
+- 递归 `call(retries-1)` → `getActiveExcludes` 包含已失败的 peer
+- `get()` 带上 exclude → Registry 返回其他 peer
+- 所有 peer 都失败 → 熔断全排除 → catch 块重置 → 无 exclude 重试
+- 每个 retry 共享同一个 timeout 值（不会延长总时间）
 
-## 4. 代码生成模板与规则
+### 3.6 健康检查
 
-### 4.1 Registry 服务端
+在 `Application` 构造函数中注册：
 
 ```typescript
-const registry = new Registry({ advertiseHost: '127.0.0.1' });
-const dispose = await registry.listen(registryPort);
-// shutdown: await dispose();
+this.register('/-/health', async () => ({
+  status: 'ok' as const,
+  registry: !!this.registry,      // 是否连上 Registry
+  uptime: process.uptime(),        // 进程运行秒数
+  namespaces: [...this.namespaces.keys()],  // 已缓存的 namespace
+}));
 ```
 
-### 4.2 可被发现的服务（Application）
+只在 Application 上注册，Server 和 Registry 没有。
+
+### 3.7 Registry 心跳
+
+```
+Application (10s 间隔):
+  startHeartbeat():
+    setInterval(10000):
+      registry.push('/-/heartbeat', {})
+
+Registry (1s 间隔检查, 20s 超时):
+  构造函数:
+    events.on('connect', ...) → heartbeats.set(key, Date.now())
+    register('/-/heartbeat', ...) → heartbeats.set(key, Date.now())
+  listen():
+    setInterval(1000):
+      for each heartbeat entry:
+        if now - lastTime >= 20000:
+          clients.get(key).dispose()  // 剔除死实例
+```
+
+### 3.8 Registry 重连
+
+```
+listen():
+  reconnectToRegistry() → connect + events.on('disconnect')
+
+disconnect 触发:
+  registry = undefined
+  reconnectToRegistry():
+    ├─ 成功 → 恢复正常
+    └─ 失败 → scheduleRegistryRetry():
+          └─ setTimeout(3000) → reconnectToRegistry()
+               └─ 失败 → scheduleRegistryRetry() (循环)
+
+listen() teardown 触发:
+  stopped = true → 停止所有重连尝试
+```
+
+### 3.9 缓存降级
+
+**触发条件：** `get()` 的 registry lookup 失败，但 `this.clients` 中仍然有之前缓存的 Client（WebSocket 未断开）。
+
+**处理流程：**
+1. `cachedHost` / `cachedPort` 在缓存失效前保存
+2. Registry lookup 失败 → catch 块
+3. `cachedHost && this.clients.has(cachedKey)` → 有效缓存
+4. 恢复 `stack.host/port/status=READY`，resolve 所有 handler
+5. 后续 `get()` 命中快路径，直接返回该 Client
+
+**不处理的情况：** 全新 namespace（无缓存）、缓存 Client 已断连。
+
+---
+
+## 4. 代码生成模板
+
+### 4.1 三节点测试拓扑（所有 test 必须使用）
 
 ```typescript
-const app = new Application({
-  namespace: 'my-service',
+const registryPort = await getAvailablePort();
+const providerPort = await getAvailablePort();
+const consumerPort = await getAvailablePort();
+
+const registry = new Registry(testAdvertise);
+const provider = new Application({
+  namespace: 'svc',
+  registry: { host: '127.0.0.1', port: registryPort },
+  ...testAdvertise,
+});
+const consumer = new Application({
+  namespace: 'consumer',
   registry: { host: '127.0.0.1', port: registryPort },
-  advertiseHost: '127.0.0.1',
+  ...testAdvertise,
 });
-const dispose = await app.listen(appPort);
 
-app.register('/hello', async ({ data }) => {
-  return { ok: true, data };
+const disposeRegistry = await registry.listen(registryPort);
+const disposeProvider = await provider.listen(providerPort);
+const disposeConsumer = await consumer.listen(consumerPort);
+const unregister = provider.register('/echo', async ({ data }) => {
+  return { value: data.value };
+});
+
+try {
+  // ... test logic ...
+} finally {
+  unregister();
+  await disposeConsumer();
+  await disposeProvider();
+  await disposeRegistry();
+}
+```
+
+### 4.2 call() 的 timeout + retries 参数顺序
+
+```typescript
+// signature: call(ns, url, data, timeout?, retries?)
+await app.call('svc', '/api', data);              // 默认超时 + 1 次重试
+await app.call('svc', '/api', data, 5000);          // 5s 超时 + 1 次重试
+await app.call('svc', '/api', data, 5000, 0);       // 5s 超时 + 不重试
+await app.call('svc', '/api', data, undefined, 0);  // 默认超时 + 不重试
+```
+
+### 4.3 超时测试 Handler
+
+```typescript
+// handler 延迟 500ms, call 超时 50ms → 应 reject
+provider.register('/slow', async () => {
+  await new Promise(resolve => setTimeout(resolve, 500));
+  return { value: 'too-late' };
 });
+await expect(consumer.call('svc', '/slow', {}, 50, 0)).rejects.toThrow('Abort');
+```
+
+### 4.4 熔断测试模板
+
+```typescript
+// 两个 provider 同 namespace, 一个失败, 排除后应选另一个
+// 见 circuit breaker test "excludes a failing peer and selects a different one"
 
-const peer = await otherApp.get('my-service');
-const { response } = peer.request('/hello', { x: 1 });
-const result = await response();
+// 单个 peer 全排除后应重置并重试该 peer
+// 见 circuit breaker test "resets breaker when all peers are excluded"
 ```
 
-### 4.2 连接超时
+### 4.5 缓存降级测试模板
 
-`Server.connect` 默认 **5 秒** 内未完成握手则 `reject(new Error('Connection timeout'))`。自定义第三参仅限受保护方法与测试辅助类，不要在公开 API 上强制调用方传入。
+```typescript
+// 1. 首次 call → 建立缓存
+// 2. 切换为失败 handler → call 失败 → peer 被排除
+// 3. 切回成功 handler → call 带 exclude → Registry find 返回 undefined
+// 4. catch 块降级 → 返回缓存 Client → 请求成功
+```
+
+---
+
+## 5. 测试门禁（修改时必须遵守）
+
+### 5.1 运行命令
+
+```bash
+pnpm --filter @hile/micro build    # 必须通过
+pnpm --filter @hile/micro test     # 必须全部通过
+```
+
+### 5.2 测试覆盖要求
+
+修改行为时至少覆盖：
+
+| 场景 | 测试位置 |
+|------|----------|
+| 服务发现端到端 | `application discovery > resolves a provider through the registry` |
+| listen teardown 后可重新 listen | `application discovery > allows listen again after teardown` |
+| Registry 不可达时 listen 回滚 | `application discovery > rolls back listen when registry is unreachable` |
+| 心跳保活 | `heartbeat > keeps client alive when heartbeats arrive on time` |
+| 心跳超时剔除 | `heartbeat > disconnects client that stops sending heartbeats` |
+| call() 基本调用 | `circuit breaker > call() returns data on success` |
+| 熔断排除 | `circuit breaker > excludes a failing peer and selects a different one` |
+| 全排除重置 | `circuit breaker > resets breaker when all peers are excluded` |
+| Correlation ID 注入 | `correlation ID > injects _correlationId into call() data` |
+| Correlation ID 透传 | `correlation ID > preserves existing _correlationId` |
+| 健康检查 | `health endpoint > /-/health returns status and registry state` |
+| 超时 reject | `request timeout > rejects when request exceeds the timeout` |
+| 超时充足则成功 | `request timeout > succeeds when timeout is long enough` |
+| 缓存降级 | `cache degradation > uses cached client when registry lookup fails due to exclusion` |
+
+### 5.3 测试规范（必须遵守）
+
+- 端口必须使用 `getAvailablePort()` 获取
+- 所有清理必须放在 `finally` 块中
+- 清理顺序：`unregister()` → `disposeConsumer` → `disposeProvider` → `disposeRegistry`
+- 禁止使用真实定时等待代替事件驱动（心跳测试是唯一例外，因其依赖实时时钟）
+- 禁止 mock `Application`、`Registry`、`Server`、`Client` 的内部方法
+- 禁止共享可变状态（每个测试独立端口）
+
+---
 
-### 4.3 随机选择
+## 6. 反模式（禁止）
 
-`/-/find` 返回的地址必须来自 Registry 内存集合内的 `host:port` 键；新增选择策略时需保持 **Registry 端无额外状态机**（尽量无 cursor），除非你同时补充设计与测试。
+1. **不要修改 WebSocket URL 三段式约定**不同时更新 `Server.onConnected` 和 `Server.connect` 的拼接格式
+2. **不要在 Registry 中按 Set 迭代顺序固定返回第一个**（破坏负载分散）
+3. **不要在 `Client.dispose()` 中删除 `socket.close()`**（会导致 WebSocketServer.close 长时间等待）
+4. **不要假设 `host:port` 可无损表达 IPv6** — 使用 `[IPv6]:port` 格式，`parseAddressKey` 按最后一个 `:` 切分
+5. **不要传错 Registry 端口** — 丢失 Registry 连接时依赖 `reconnectToRegistry`，不要在外部缓存 registry Client
+6. **不要在 call() 中修改原始 data 对象** — 必须使用浅拷贝 `{ ...data, _correlationId }`
+7. **不要在其他文件中重复 `selectRandomRegistryAddress` 或 `parseAddressKey`** — 这些是 Registry 的内部 helper
+8. **不要给 call() 增加非可选参数** — `timeout` 和 `retries` 都在尾部且保持可选，不影响现有调用
 
 ---
 
-## 5. 反模式（禁止）
+## 7. 文件改动范围
 
-- 修改 WebSocket URL 三段式约定却不同时更新 **`Server.onConnected`** 与 **`Server.connect`** 的拼接格式。
-- 在 `Registry` 中按 `Set` **迭代顺序** 固定返回「第一个」实例（破坏负载分散）；除非你明确改需求并改写测试。
-- `Client`/`Server` **`dispose`** 后不关闭 **`ws`**（会导致 **`WebSocketServer.close`** 长时间等待）；本包已在 `Client.dispose` 内关闭socket，不要随意删除。
-- 假设 `host:port` 串可无损表达 **IPv6**：注册表 Set 的键应使用 **`[IPv6]:port`**；`selectRandomRegistryAddress` / `parseAddressKey` 按 **最后一个 `:`** 切分 host 与 port。
-- `Application.props.registry` **不要传错端口**；丢失与注册中心的连接时依赖 `reconnectToRegistry`，不要在外部缓存 `registry` Client 绕过重连语义。
+| 文件 | 可修改 | 说明 |
+|------|--------|------|
+| `packages/micro/src/application.ts` | ✅ | 核心业务逻辑 |
+| `packages/micro/src/index.test.ts` | ✅ | 测试 |
+| `packages/micro/src/server.ts` | ❌ | 底层协议，不动 |
+| `packages/micro/src/client.ts` | ❌ | 底层协议，不动 |
+| `packages/micro/src/registry.ts` | ❌ | 注册中心，不动 |
+| `packages/micro/src/utils.ts` | ❌ | 工具函数，不动 |
+| `packages/micro/README.md` | ✅ | 用户文档 |
+| `packages/micro/SKILL.md` | ✅ | AI 参考文档 |
 
 ---
 
-## 6. 测试与改动范围
+## 8. 参考文件
 
-- 包内测试：`packages/micro/src/index.test.ts`（Vitest）。
-- 修改行为时至少覆盖：**随机选择 helper**、`Application` 端到端发现、**连接超时**。
-- 发布前在项目根或通过 filter 运行：`pnpm --filter @hile/micro test` 与 `pnpm --filter @hile/micro build`。
+| 文件 | 用途 |
+|------|------|
+| `packages/micro/src/application.ts` | 完整实现（共 ~310 行） |
+| `packages/micro/src/index.test.ts` | 28 个测试用例 |
+| `docs/superpowers/specs/2026-05-14-micro-improvements-design.md` | 四种改进的设计规约 |
+| `docs/superpowers/plans/2026-05-14-micro-improvements.md` | 实施计划 |

package/dist/application.d.ts

@@ -6,6 +6,8 @@ export type ApplicationProps = {
     registry: RegistryAddress;
     /** `/-/find` 等待响应的上限（毫秒），默认 `10000` */
     registryLookupTimeoutMs?: number;
+    /** 单次 request() 等待响应的上限（毫秒），默认 `30000` */
+    requestTimeoutMs?: number;
 } & MicroServerProps;
 export declare class Application extends Server {
     private registry?;
@@ -15,11 +17,22 @@ export declare class Application extends Server {
     private stopped;
     private readonly _registry_address;
     private readonly _registryLookupTimeoutMs;
+    private readonly _requestTimeoutMs;
     private readonly namespaces;
+    private static readonly HEARTBEAT_INTERVAL;
+    private heartbeatTimer?;
+    private static readonly CB_COOLDOWN_MS;
+    private readonly circuitBreakers;
     constructor(props: ApplicationProps);
     listen(port?: number): Promise<() => Promise<void>>;
     private scheduleRegistryRetry;
     private reconnectToRegistry;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private recordSuccess;
+    private recordFailure;
+    private getActiveExcludes;
     private findFromRegistry;
-    get(namespace: string): Promise<Client>;
+    get(namespace: string, exclude?: string[]): Promise<Client>;
+    call<T = any>(namespace: string, url: string, data: any, timeout?: number, retries?: number): Promise<T>;
 }

package/dist/application.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { Server } from './server.js';
 var RegistryLookupStatus;
 (function (RegistryLookupStatus) {
@@ -43,19 +44,32 @@ export class Application extends Server {
     stopped = false;
     _registry_address;
     _registryLookupTimeoutMs;
+    _requestTimeoutMs;
     namespaces = new Map();
+    static HEARTBEAT_INTERVAL = 10000;
+    heartbeatTimer;
+    static CB_COOLDOWN_MS = 30_000;
+    circuitBreakers = new Map();
     constructor(props) {
-        const { namespace, registry, registryLookupTimeoutMs = 10_000, ...microAndLoader } = props;
+        const { namespace, registry, registryLookupTimeoutMs = 10_000, requestTimeoutMs = 30_000, ...microAndLoader } = props;
         super(namespace, microAndLoader);
         assertValidRegistrySocket('registry address', registry.host, registry.port);
         this._registry_address = registry;
         this._registryLookupTimeoutMs = registryLookupTimeoutMs;
+        this._requestTimeoutMs = requestTimeoutMs;
+        this.register('/-/health', async () => ({
+            status: 'ok',
+            registry: !!this.registry,
+            uptime: process.uptime(),
+            namespaces: [...this.namespaces.keys()],
+        }));
     }
     async listen(port = 0) {
         this.stopped = false;
         const callback = await super.listen(port);
         try {
             await this.reconnectToRegistry();
+            this.startHeartbeat();
         }
         catch (err) {
             try {
@@ -68,6 +82,7 @@ export class Application extends Server {
         }
         return async () => {
             this.stopped = true;
+            this.stopHeartbeat();
             if (this.reconnectTimeout) {
                 clearTimeout(this.reconnectTimeout);
                 this.reconnectTimeout = undefined;
@@ -119,14 +134,66 @@ export class Application extends Server {
         });
         return this.registryReconnectPromise;
     }
-    async findFromRegistry(namespace) {
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(() => {
+            if (!this.registry)
+                return;
+            try {
+                this.registry.push('/-/heartbeat', {});
+            }
+            catch {
+                // registry connection may have dropped between null-check and push
+            }
+        }, Application.HEARTBEAT_INTERVAL);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = undefined;
+        }
+    }
+    recordSuccess(ns, host, port) {
+        const excludes = this.circuitBreakers.get(ns);
+        if (excludes) {
+            excludes.delete(`${host}:${port}`);
+            if (excludes.size === 0)
+                this.circuitBreakers.delete(ns);
+        }
+    }
+    recordFailure(ns, host, port) {
+        let excludes = this.circuitBreakers.get(ns);
+        if (!excludes) {
+            excludes = new Map();
+            this.circuitBreakers.set(ns, excludes);
+        }
+        excludes.set(`${host}:${port}`, Date.now());
+    }
+    getActiveExcludes(ns) {
+        const excludes = this.circuitBreakers.get(ns);
+        if (!excludes)
+            return [];
+        const now = Date.now();
+        const active = [];
+        for (const [key, openedAt] of excludes) {
+            if (now - openedAt >= Application.CB_COOLDOWN_MS) {
+                excludes.delete(key);
+            }
+            else {
+                active.push(key);
+            }
+        }
+        if (excludes.size === 0)
+            this.circuitBreakers.delete(ns);
+        return active;
+    }
+    async findFromRegistry(namespace, exclude) {
         if (!this.registry)
             throw new Error('Registry not found');
-        const { response } = this.registry.request('/-/find', { namespace });
-        const p = response();
-        return await withTimeout(p, this._registryLookupTimeoutMs, 'Registry /-/find');
+        const { response } = this.registry.request('/-/find', { namespace, exclude });
+        return await withTimeout(response(), this._registryLookupTimeoutMs, 'Registry /-/find');
     }
-    get(namespace) {
+    get(namespace, exclude) {
         if (!this.namespaces.has(namespace)) {
             this.namespaces.set(namespace, {
                 host: '',
@@ -136,8 +203,12 @@ export class Application extends Server {
             });
         }
         const stack = this.namespaces.get(namespace);
+        // Save old cache info before potential invalidation (used for cache degradation)
+        const cachedHost = stack.host;
+        const cachedPort = stack.port;
         if (stack.status === RegistryLookupStatus.READY &&
-            !this.clients.has(`${stack.host}:${stack.port}`)) {
+            (!this.clients.has(`${stack.host}:${stack.port}`) ||
+                (exclude?.length && exclude.includes(`${stack.host}:${stack.port}`)))) {
             stack.status = RegistryLookupStatus.IDLE;
             stack.host = '';
             stack.port = 0;
@@ -150,7 +221,7 @@ export class Application extends Server {
             stack.handlers.add([resolve, reject]);
             if (stack.status === RegistryLookupStatus.IDLE) {
                 stack.status = RegistryLookupStatus.PENDING;
-                this.findFromRegistry(namespace).then(data => {
+                this.findFromRegistry(namespace, exclude).then(data => {
                     if (!data)
                         return Promise.reject(new Error('Namespace not found'));
                     assertValidRegistrySocket('peer address from registry', data.host, data.port);
@@ -170,6 +241,19 @@ export class Application extends Server {
                         }
                     });
                 }).catch(e => {
+                    // Registry unavailable but previously cached client still valid -> degrade
+                    const cachedKey = `${cachedHost}:${cachedPort}`;
+                    if (cachedHost && this.clients.has(cachedKey)) {
+                        const client = this.clients.get(cachedKey);
+                        // Restore cache so subsequent calls hit the fast path
+                        stack.host = cachedHost;
+                        stack.port = cachedPort;
+                        stack.status = RegistryLookupStatus.READY;
+                        for (const [resolve] of stack.handlers.values()) {
+                            resolve(client);
+                        }
+                        return;
+                    }
                     this.namespaces.delete(namespace);
                     for (const [_, reject] of stack.handlers.values()) {
                         reject(e);
@@ -178,4 +262,35 @@ export class Application extends Server {
             }
         });
     }
+    async call(namespace, url, data, timeout, retries = 1) {
+        // Inject or preserve correlation ID (no mutation of original data)
+        if (!data || typeof data !== 'object' || Array.isArray(data)) {
+            data = { _correlationId: randomUUID(), data };
+        }
+        else if (!data._correlationId) {
+            data = { ...data, _correlationId: randomUUID() };
+        }
+        const exclude = this.getActiveExcludes(namespace);
+        let client;
+        try {
+            client = await this.get(namespace, exclude);
+        }
+        catch {
+            this.circuitBreakers.delete(namespace);
+            client = await this.get(namespace);
+        }
+        try {
+            const { response } = client.request(url, data, timeout ?? this._requestTimeoutMs);
+            const result = await response();
+            this.recordSuccess(namespace, client.host, client.port);
+            return result;
+        }
+        catch (err) {
+            this.recordFailure(namespace, client.host, client.port);
+            if (retries > 0) {
+                return this.call(namespace, url, data, timeout, retries - 1);
+            }
+            throw err;
+        }
+    }
 }

package/dist/registry.d.ts

@@ -1,6 +1,7 @@
 import { Server, type MicroServerProps } from './server.js';
 export interface RegistryFindData {
     namespace: string;
+    exclude?: string[];
 }
 export interface RegistryAddress {
     host: string;
@@ -12,7 +13,11 @@ export declare function selectRandomRegistryAddress(keys: Iterable<string>): Reg
 export declare class Registry extends Server {
     private readonly namespaces;
     private unregisterFind?;
+    private static readonly HEARTBEAT_INTERVAL;
+    private static readonly HEARTBEAT_TIMEOUT;
+    private readonly heartbeats;
     constructor(props?: MicroServerProps);
+    listen(port?: number): Promise<() => Promise<void>>;
     /** 幂等：重复调用会先注销上一条 `/-/find` 再注册，避免叠多条路由 */
     onFind(): void;
     private mountFindHandler;

package/dist/registry.js

@@ -27,10 +27,14 @@ export function selectRandomRegistryAddress(keys) {
 export class Registry extends Server {
     namespaces = new Map();
     unregisterFind;
+    static HEARTBEAT_INTERVAL = 1000;
+    static HEARTBEAT_TIMEOUT = 20000;
+    heartbeats = new Map();
     constructor(props) {
         super('registry', props ?? {});
         this.events.on('connect', (client, extras) => {
             const key = client.host + ':' + client.port;
+            this.heartbeats.set(key, Date.now());
             const namespace = extras.join('/');
             if (!this.namespaces.has(namespace)) {
                 this.namespaces.set(namespace, new Set());
@@ -39,6 +43,7 @@ export class Registry extends Server {
         });
         this.events.on('disconnect', (client, extras) => {
             const key = client.host + ':' + client.port;
+            this.heartbeats.delete(key);
             const namespace = extras.join('/');
             if (this.namespaces.has(namespace)) {
                 const keys = this.namespaces.get(namespace);
@@ -51,6 +56,31 @@ export class Registry extends Server {
             }
         });
         this.mountFindHandler();
+        this.register('/-/heartbeat', async ({ client }) => {
+            if (!client)
+                return;
+            const key = client.host + ':' + client.port;
+            this.heartbeats.set(key, Date.now());
+        });
+    }
+    async listen(port = 0) {
+        const teardown = await super.listen(port);
+        const timer = setInterval(() => {
+            const now = Date.now();
+            for (const [key, lastTime] of this.heartbeats) {
+                if (now - lastTime >= Registry.HEARTBEAT_TIMEOUT) {
+                    const client = this.clients.get(key);
+                    if (client) {
+                        this.heartbeats.delete(key);
+                        client.dispose();
+                    }
+                }
+            }
+        }, Registry.HEARTBEAT_INTERVAL);
+        return async () => {
+            clearInterval(timer);
+            await teardown();
+        };
     }
     /** 幂等：重复调用会先注销上一条 `/-/find` 再注册，避免叠多条路由 */
     onFind() {
@@ -63,9 +93,16 @@ export class Registry extends Server {
         }
         this.unregisterFind = this.register('/-/find', async ({ data }) => {
             const namespace = data.namespace;
-            const keys = this.namespaces.get(namespace);
+            let keys = this.namespaces.get(namespace);
             if (!keys)
                 return;
+            if (data.exclude?.length) {
+                const excludeSet = new Set(data.exclude);
+                const filtered = [...keys].filter(k => !excludeSet.has(k));
+                if (filtered.length === 0)
+                    return;
+                keys = new Set(filtered);
+            }
             return selectRandomRegistryAddress(keys);
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/micro",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -28,5 +28,5 @@
     "internal-ip": "^9.0.0",
     "ws": "^8.19.0"
   },
-  "gitHead": "46d4b998c1fd2fd725bf484ca634f25b61f19cd5"
+  "gitHead": "ddc82850295d26358cbffbb695e642cdb748339d"
 }