@hile/micro 1.0.3 → 1.0.5

package/SKILL.md

@@ -1,159 +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`**：基于 `ws` 的 `WebSocketServer`，用 **URL 路径** 携带对端身份与命名空间；对内用 `MessageLoader.register` / `dispatch` 处理消息路由。
-- **`Client`**：连接到远端 `Server`，`request(url, data)` / `push(url, data)` 将负载交给本端 `Server.dispatch`；`dispose()` 会移除监听并 **关闭底层 WebSocket**，避免 `listen` 关闭阶段挂住。
-- **`Registry`**：固定 `namespace` 为 `'registry'`，维护「逻辑 namespace → 一组 `host:port`」；`/-/find` 在集合中 **随机** 返回一条地址（见 `selectRandomRegistryAddress`）。
-- **`Application`**：`Server` 的子类；`listen(port)` 后自动 `connect` 到注册中心；`get(targetNamespace)` 向注册中心查询并 **缓存** 到目标服务的 `Client`，目标断连后删除缓存以便下次重新发现。
-
-依赖链：
+### 依赖链
 
 ```
-MessageLoader (路由) + MessageWs (请求/响应传输)
-  └── Server / Client
-        ├── Registry
-        └── Application
+@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**。
+## 2. 类型定义（代码生成时必须一致）
 
-生成侧：`Server.connect()` 使用：
+### Server (`server.ts`)
 
-```text
-ws://{host}:{port}/${this.ipv4}/${this.port}/${this.namespace}
+```typescript
+export type MicroServerProps = MessageLoaderProps & {
+  advertiseHost?: string;  // 缺省 getLocalIPv4(), 皆无则构造抛错
+};
+
+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>;
+}
 ```
 
-其中 `this.ipv4` 来自 `getLocalIPv4()`（见 `utils.ts`），`this.port` 为当前 `listen` 端口，`this.namespace` 为构造传入的字符串（如 `provider`、`consumer`、`registry`）。
-
-### 2.2 MessageLoader 路由
+### Client (`client.ts`)
 
-- 对内消息体为 `{ url, data }`，与 `Client.exec` 一致。
-- `Registry` 注册：`register<RegistryFindData>('/-/find', handler)`，请求体 `{ namespace: string }`。
-
----
+```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
-// registry.ts
 export interface RegistryFindData {
   namespace: string;
+  exclude?: string[];
 }
 
-export interface RegistryAddress {
-  host: string;
-  port: number;
-}
+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 { /* ... */ }
+### Application (`application.ts`)
 
-// application.ts
+```typescript
 export type ApplicationProps = {
   namespace: string;
   registry: RegistryAddress;
-} & MessageLoaderProps;
+  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>;
+---
 
-// 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. 功能详解（含状态机与逻辑流）
+
+### 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 数组
+```
 
-## 4. 代码生成模板与规则
+**生命周期：**
 
-### 4.1 Registry 服务端
+```
+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
-const registry = new Registry();
-const dispose = await registry.listen(registryPort);
-// shutdown: await dispose();
+// 非对象/假值/数组 → 包装
+!data || typeof data !== 'object' || Array.isArray(data)
+  → data = { _correlationId: randomUUID(), data }
+
+// 对象无 _correlationId → 浅拷贝注入
+else if (!data._correlationId)
+  → data = { ...data, _correlationId: randomUUID() }
+
+// 对象已有 _correlationId → 保留（透传）
 ```
 
-### 4.2 可被发现的服务（Application）
+- 使用 `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 app = new Application({
-  namespace: 'my-service',
+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 值（不会延长总时间）
+
+### 3.6 健康检查
+
+在 `Application` 构造函数中注册：
+
+```typescript
+this.register('/-/health', async () => ({
+  status: 'ok' as const,
+  registry: !!this.registry,      // 是否连上 Registry
+  uptime: process.uptime(),        // 进程运行秒数
+  namespaces: [...this.namespaces.keys()],  // 已缓存的 namespace
+}));
+```
+
+只在 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 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 dispose = await app.listen(appPort);
+const consumer = new Application({
+  namespace: 'consumer',
+  registry: { host: '127.0.0.1', port: registryPort },
+  ...testAdvertise,
+});
+
+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();
+}
+```
 
-app.register('/hello', async ({ data }) => {
-  return { ok: true, data };
+### 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');
+```
 
-const peer = await otherApp.get('my-service');
-const { response } = peer.request('/hello', { x: 1 });
-const result = await response();
+### 4.4 熔断测试模板
+
+```typescript
+// 两个 provider 同 namespace, 一个失败, 排除后应选另一个
+// 见 circuit breaker test "excludes a failing peer and selects a different one"
+
+// 单个 peer 全排除后应重置并重试该 peer
+// 见 circuit breaker test "resets breaker when all peers are excluded"
+```
+
+### 4.5 缓存降级测试模板
+
+```typescript
+// 1. 首次 call → 建立缓存
+// 2. 切换为失败 handler → call 失败 → peer 被排除
+// 3. 切回成功 handler → call 带 exclude → Registry find 返回 undefined
+// 4. catch 块降级 → 返回缓存 Client → 请求成功
 ```
 
-### 4.2 连接超时
+---
+
+## 5. 测试门禁（修改时必须遵守）
 
-`Server.connect` 默认 **5 秒** 内未完成握手则 `reject(new Error('Connection timeout'))`。自定义第三参仅限受保护方法与测试辅助类，不要在公开 API 上强制调用方传入。
+### 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**（当前实现按 **首个 `:` 分割**，仅适合 IPv4 或不含冒号的 host）。
-- `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

@@ -1,19 +1,38 @@
 import { Client } from './client.js';
-import { Server } from './server.js';
-import { MessageLoaderProps } from '@hile/message-loader';
+import { Server, type MicroServerProps } from './server.js';
 import { RegistryAddress } from './registry.js';
 export type ApplicationProps = {
     namespace: string;
     registry: RegistryAddress;
-} & MessageLoaderProps;
+    /** `/-/find` 等待响应的上限（毫秒），默认 `10000` */
+    registryLookupTimeoutMs?: number;
+    /** 单次 request() 等待响应的上限（毫秒），默认 `30000` */
+    requestTimeoutMs?: number;
+} & MicroServerProps;
 export declare class Application extends Server {
     private registry?;
     private reconnectTimeout?;
+    private registryReconnectPromise;
+    /** 为 true 时不再向 Registry 重连（listen 返回的 teardown 已触发） */
+    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>;
 }