@hile/micro 2.1.1 → 3.0.1

package/AI.md

@@ -0,0 +1,368 @@
+# AI Guide For @hile/micro
+
+
+
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
+
+
+
+Purpose: Run registry-backed service discovery, RPC, streaming RPC, and pub/sub between Node services.
+
+
+
+Use this file when an AI agent installs the npm package and needs package-local examples, package selection rules, boundaries, and verification steps.
+
+
+
+## Package Selection
+
+
+
+| User asks for | Use | Also read |
+|---|---|---|
+| Build service discovery or RPC | `@hile/micro` | `packages/messaging-micro.md`, `recipes/micro-rpc-message-loader.md` |
+| Push runtime config without restarts | `@hile/micro-dynamic-configs` | `packages/messaging-micro.md`, `recipes/runtime-config.md` |
+
+
+
+# Messaging And Microservices
+
+Packages: `@hile/message-modem`, `@hile/message-ws`, `@hile/message-ipc`, `@hile/message-worker-thread`, `@hile/message-loader`, `@hile/micro`, `@hile/micro-dynamic-configs`.
+
+## Copy-Paste Example
+
+Message handler file:
+
+```ts
+// src/messages/ping.msg.ts
+import { defineMessage } from '@hile/message-loader'
+
+export default defineMessage(async ({ data, params }) => {
+  return {
+    type: 'pong',
+    data,
+    params,
+    timestamp: Date.now(),
+  }
+})
+```
+
+Microservice boot file:
+
+```ts
+// src/services/app.boot.ts
+import { defineService } from '@hile/core'
+import { Application } from '@hile/micro'
+
+export default defineService('micro.app', async (shutdown) => {
+  const app = new Application({
+    namespace: process.env.MICRO_NAMESPACE ?? 'example.service',
+    registry: {
+      host: process.env.REGISTRY_HOST ?? '127.0.0.1',
+      port: Number(process.env.REGISTRY_PORT ?? 9876),
+    },
+    advertiseHost: process.env.HILE_ADVERTISE_HOST ?? '127.0.0.1',
+  })
+
+  await app.load(new URL('../messages', import.meta.url).pathname)
+  const stop = await app.listen(Number(process.env.MICRO_PORT ?? 0))
+  shutdown(stop)
+  return app
+})
+```
+
+Caller:
+
+```ts
+const result = await app.call('example.service', '/ping', { hello: 'world' })
+```
+
+## More Examples
+
+Streaming handler:
+
+```ts
+// src/messages/events.msg.ts
+import { defineMessage } from '@hile/message-loader'
+
+export default defineMessage(async function* () {
+  for (let i = 0; i < 3; i++) {
+    yield { seq: i }
+  }
+})
+```
+
+Streaming caller:
+
+```ts
+const stream = await app.stream('example.service', '/events', {})
+for await (const chunk of stream) {
+  console.log(chunk)
+}
+```
+
+Custom WebSocket modem:
+
+```ts
+import { MessageWs } from '@hile/message-ws'
+import type WebSocket from 'ws'
+
+class RpcWs extends MessageWs {
+  constructor(ws: WebSocket, private readonly dispatch: (url: string, data: unknown) => Promise<unknown>) {
+    super(ws)
+  }
+
+  protected exec(data: { url: string; data: unknown }) {
+    return this.dispatch(data.url, data.data)
+  }
+
+  request<T>(url: string, data: unknown, timeout = 30_000) {
+    return this._send<T>({ url, data }, { timeout })
+  }
+}
+```
+
+Notice that `request()` returns a `Promise<T>`. Await it directly.
+
+## Use When
+
+Use the message packages for request/response messaging over WebSocket, process IPC, worker threads, file-system message handlers, service discovery, streaming RPC, and registry-backed pub/sub.
+
+## Do Not Use When
+
+- Do not use `stream()` for normal single-result calls.
+- Do not rely on message IDs for business idempotency. They are transport IDs.
+- Do not bypass `defineMessage()` for file-loaded handlers.
+
+## Install
+
+```bash
+pnpm add @hile/micro @hile/message-loader @hile/message-ws
+```
+
+Use transport-specific packages only when you need to build custom IPC or worker-thread bridges.
+
+## Imports
+
+```ts
+import { defineMessage, MessageLoader } from '@hile/message-loader'
+import { Application, Registry, Server } from '@hile/micro'
+import { MessageWs } from '@hile/message-ws'
+import { MessageIpc } from '@hile/message-ipc'
+import { MessageWorkerThread } from '@hile/message-worker-thread'
+```
+
+## Compose With
+
+- `@hile/context` propagates context in micro message metadata.
+- `@hile/redis-idempotency` protects retryable side effects in message handlers.
+- `@hile/redis-stream-queue` is better for durable background jobs.
+
+## Runtime And Lifecycle Notes
+
+- `MessageLoader` maps `*.msg.*` files to routes using `@hile/loader`.
+- `MessageLoader.dispatch(path, data, extras?)` invokes the matched handler.
+- `MessageModem._send()` returns a `Promise`.
+- `MessageModem._stream()` returns a Node `Readable` in object mode.
+- A stream request requires `exec()` to return an async iterable.
+- `Application.call(namespace, url, data, options?)` returns a promise.
+- `Application.stream(namespace, url, data, options?)` returns a readable stream.
+- `Application.publish(topic, payload)` returns an object with `update()` and `unpublish()`.
+- `Application.subscribe(topic, callback)` returns an unsubscribe function.
+- `Registry` stores service addresses and retained config/topic state under `~/.registry`.
+
+## Anti-Patterns
+
+- Appending a secondary response getter to `client.request('/x', data)`
+- Returning a plain object from a handler called through `stream()`.
+- Using pub/sub as a durable queue.
+- Forgetting to register `shutdown(await app.listen(...))`.
+
+## Verification Checklist
+
+- Message files default-export `defineMessage(...)`.
+- RPC callers use `await app.call(...)`.
+- Streaming handlers are async generators.
+- Registry is started before application nodes need discovery.
+- Micro apps use stable namespaces and advertise reachable hosts.
+
+
+
+# Related Recipes
+
+
+
+# Micro RPC With Message Loader
+
+## Complete Example
+
+Provider handler:
+
+```ts
+// src/messages/charge.msg.ts
+import { defineMessage } from '@hile/message-loader'
+
+export default defineMessage(async ({ data }) => {
+  return { charged: true, input: data }
+})
+```
+
+Provider boot:
+
+```ts
+// src/services/app.boot.ts
+import { defineService } from '@hile/core'
+import { Application } from '@hile/micro'
+
+export default defineService('billing.micro', async (shutdown) => {
+  const app = new Application({
+    namespace: 'billing',
+    registry: { host: '127.0.0.1', port: 9876 },
+    advertiseHost: '127.0.0.1',
+  })
+
+  await app.load(new URL('../messages', import.meta.url).pathname)
+  const stop = await app.listen(9101)
+  shutdown(stop)
+  return app
+})
+```
+
+Consumer:
+
+```ts
+const result = await app.call('billing', '/charge', {
+  tenantId: 't1',
+  amount: 100,
+})
+```
+
+## File Layout
+
+```text
+provider/
+  src/messages/charge.msg.ts
+  src/services/app.boot.ts
+consumer/
+  src/models/payments/pay.model.ts
+```
+
+## User Intent
+
+Use this recipe when services communicate over Hile registry-backed RPC.
+
+## Packages To Use
+
+- `@hile/micro`
+- `@hile/message-loader`
+- `@hile/context` when context must cross service boundaries
+- `@hile/redis-idempotency` for retryable side effects
+
+## Implementation Steps
+
+1. Start a Registry with `hile registry`.
+2. Start providers with stable namespaces.
+3. Load `*.msg.ts` handlers through `app.load()`.
+4. Call providers with `await app.call(namespace, url, data)`.
+5. Use `app.stream()` only for async-generator handlers.
+
+## Failure And Cleanup Behavior
+
+- `Application.call()` may retry; side-effecting handlers need idempotency.
+- Registry disconnect triggers reconnect; apps re-declare topics and subscriptions.
+- Circuit breaker excludes failing nodes for cooldown.
+
+## Verification Checklist
+
+- Registry is reachable.
+- Provider namespace matches consumer call.
+- Handlers default-export `defineMessage()`.
+- Consumer code awaits `app.call(...)` directly.
+
+# Runtime Dynamic Config
+
+## Complete Example
+
+```ts
+import { z } from 'zod'
+import { MicroDynamicConfigsServer } from '@hile/micro-dynamic-configs'
+
+const schema = z.object({
+  featureCheckout: z.boolean().default(false),
+  maxRetries: z.number().int().min(1).max(10).default(3),
+})
+
+const configs = new MicroDynamicConfigsServer({
+  app,
+  redis,
+  schema,
+  redis_key: 'configs:checkout',
+})
+
+const cleanup = await configs.initialize()
+shutdown(cleanup)
+
+configs.on('change:featureCheckout', (next, previous) => {
+  logger.info({ previous, next }, 'featureCheckout changed')
+})
+
+await configs.save({ featureCheckout: true })
+```
+
+## File Layout
+
+```text
+src/services/configs.boot.ts
+src/services/app.boot.ts
+```
+
+## User Intent
+
+Use this recipe when config changes should persist to Redis and be pushed through the micro registry without restarting services.
+
+## Packages To Use
+
+- `@hile/micro-dynamic-configs`
+- `@hile/micro`
+- `@hile/ioredis`
+- `zod`
+
+## Implementation Steps
+
+1. Define a Zod object schema with defaults.
+2. Create `MicroDynamicConfigsServer`.
+3. Call `initialize()` after `app` and `redis` are ready.
+4. Register cleanup with `shutdown()`.
+5. Use `.save(partial)` for changes.
+
+## Failure And Cleanup Behavior
+
+- `save()` validates fields before mutating memory.
+- Redis is written before memory and event emission update.
+- `initialize()` publishes every config field as a topic.
+- Cleanup unpublishes topics and removes listeners.
+
+## Verification Checklist
+
+- Schema defaults parse `{}`.
+- `redis_key` is app-specific.
+- Change handlers use `change:key`.
+- Cleanup from `initialize()` is registered.
+
+
+
+# Global Guardrails
+
+
+
+## Never Generate These Patterns
+
+- Do not call `loadService()` at module top level; it starts resources during import.
+- Do not default-export plain functions from `*.boot.*` files; `hile start` expects a Hile service.
+- Do not set `ctx.body` and also return a controller value.
+- Do not assume `@hile/http` Zod validation mutates or coerces `ctx.query`, `ctx.params`, or `ctx.request.body`.
+- Do not put reusable business logic only in controllers, pages, queue workers, or message handlers.
+- Do not use old message examples that append a secondary response getter; current request APIs return promises directly.
+- Do not claim exactly-once delivery or execution from Redis locks, queues, idempotency, or rate limits.
+- Do not use queue `jobId` as the only side-effect idempotency boundary.
+- Do not log the entire async context by default.

package/README.md

@@ -1,512 +1,90 @@
 # @hile/micro
 
-基于 `@hile/message-loader` 与 `@hile/message-ws` 的轻量级 **WebSocket 微服务框架**。提供服务注册与发现、心跳保活、熔断、请求超时、自动重试等功能。
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-## 架构分层
+Run registry-backed service discovery, RPC, streaming RPC, and pub/sub between Node services.
 
-```
-MessageLoader (路由) + MessageWs (请求/响应传输)
-  └── Server（WebSocket 服务底层）
-        ├── Registry（注册中心）
-        └── Application（应用服务）
-```
+This README is intentionally short and example-first. The complete AI-facing guide ships in `AI.md` in this package.
 
-| 组件 | 职责 |
-|------|------|
-| **Server** | WebSocket 监听、连接管理、消息路由。不关心注册中心 |
-| **Client** | 远端 Server 的代理，提供 `request()` / `push()` 通信接口 |
-| **Registry** | 注册中心。维护 namespace → 实例列表，心跳检测剔除死实例 |
-| **Application** | 应用服务。集成注册发现、熔断、重试等功能 |
+## When To Use
 
-一个 `Application` 实例 **同时** 扮演 provider（`register` 暴露接口）和 consumer（`get` / `call` 调用其它服务）。
+Use the message packages for request/response messaging over WebSocket, process IPC, worker threads, file-system message handlers, service discovery, streaming RPC, and registry-backed pub/sub.
 
-## 安装
+## Install
 
 ```bash
 pnpm add @hile/micro
 ```
 
-依赖：`@hile/message-loader`、`@hile/message-ws`、`ws`。
-
----
-
-## 快速开始
-
-### 1. 启动 Registry
-
-```typescript
-import { Registry } from '@hile/micro';
-
-const registry = new Registry({ advertiseHost: '127.0.0.1' });
-await registry.listen(9000);
-```
-
-### 2. 启动 Provider（服务 A）
-
-以下 `provider` 和 `consumer` 是两个不同进程（不同 namespace），**每个进程只需要一个 `Application` 实例**，同时扮演 provider 和 consumer：
-
-```typescript
-import { Application } from '@hile/micro';
-
-const provider = new Application({
-  namespace: 'payments',
-  registry: { host: '127.0.0.1', port: 9000 },
-  advertiseHost: '127.0.0.1',
-});
-
-await provider.listen(9100);
-
-provider.register('/charge', async ({ data }) => {
-  return { charged: true, amount: data.amount };
-});
-```
-
-### 3. 启动 Consumer 调用（服务 B）
-
-```typescript
-import { Application } from '@hile/micro';
-
-const consumer = new Application({
-  namespace: 'checkout',
-  registry: { host: '127.0.0.1', port: 9000 },
-  advertiseHost: '127.0.0.1',
-});
-
-await consumer.listen(9200);
-
-// call() = get() + request() + response() + 熔断 + 重试
-const result = await consumer.call('payments', '/charge', { amount: 100 });
-console.log(result); // { charged: true, amount: 100 }
-```
-
-### 4. 关闭
-
-`listen()` 返回的 teardown 函数关闭 WebSocketServer 并断开所有连接：
-
-```typescript
-const stop = await provider.listen(9100);
-await stop();
-```
-
----
-
-## 核心功能
-
-### 服务发现 (`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()` 和 `stream()` 自动跟踪每个 namespace 下各 peer 的调用结果。熔断状态保存在调用方 `Application` 的本地内存中，不依赖 Redis、数据库或 Registry 共享状态。
-
-| 场景 | 行为 |
-|------|------|
-| `closed` 状态调用失败 | 累计连续失败次数 |
-| 连续失败达到阈值 | peer 进入 `open`，选路时通过 Registry `exclude` 临时排除 |
-| 冷却时间到期 | peer 进入 `half-open`，只放行少量探测请求 |
-| `half-open` 探测成功 | 累计成功次数，达到阈值后恢复 `closed` |
-| `half-open` 探测失败 | 重新进入 `open`，冷却时间指数退避 |
-| 所有 `open` peer 都被排除 | 重置该 namespace 的本地熔断状态，重新选择 peer；若 Registry 不可用但已选中的缓存 Client 仍连接，则沿用缓存发起探测，避免完全饿死 |
-
-如果 peer 正处于 `half-open` 且探测名额已满，本次调用不会占用额外探测名额；有其他 peer 时改选其他 peer，没有可用 peer 时需要在已有探测完成后再尝试。
-
-默认策略：
-
-| 配置 | 默认值 | 说明 |
-|------|--------|------|
-| `failureThreshold` | `3` | 连续失败 3 次后打开熔断 |
-| `failureWindowMs` | `60000` | 连续失败统计窗口 |
-| `successThreshold` | `2` | half-open 连续成功 2 次后恢复 |
-| `cooldownMs` | `10000` | 首次打开后的冷却时间 |
-| `maxCooldownMs` | `120000` | 指数退避冷却上限 |
-| `halfOpenMaxProbes` | `1` | half-open 同时放行的探测数 |
+## Copy-Paste Example
 
-可以在构造 `Application` 时覆盖：
+Message handler file:
 
-```typescript
-const app = new Application({
-  namespace: 'checkout',
-  registry: { host, port },
-  circuitBreaker: {
-    failureThreshold: 3,
-    failureWindowMs: 60_000,
-    successThreshold: 2,
-    cooldownMs: 10_000,
-    maxCooldownMs: 120_000,
-    halfOpenMaxProbes: 1,
-    shouldRecordFailure: (err) => true,
-    shouldRetry: (err) => true,
-  },
-});
-```
-
-`shouldRecordFailure` 返回 `false` 的错误不会计入熔断；`shouldRetry` 返回 `false` 的错误不会自动重试。可用它们区分业务错误和连接、超时等基础设施错误。
-
-### 请求超时
-
-每个请求都有超时控制：
-
-```typescript
-// 构造时设置全局默认超时
-const app = new Application({
-  namespace: 'svc',
-  registry: { host, port },
-  requestTimeoutMs: 10_000,  // 默认 30000ms
-});
-
-// 单次调用覆盖
-await app.call('svc', '/api', data, { timeout: 5_000 });          // 5s 超时, 默认重试 1 次
-await app.call('svc', '/api', data, { timeout: 1_000, retries: 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, { timeout: 5000, retries: 3 }); // 超时 5s, 重试 3 次
-await app.call('svc', '/api', data, { timeout: 5000, retries: 0 }); // 超时 5s, 不重试
-```
-
-重试策略：失败 → 按 `shouldRecordFailure` 更新本地熔断状态 → 按 `shouldRetry` 判断是否继续下一次尝试 → 下次发现服务时用 `getActiveExcludes()` 排除 `open` 或探测名额已满的 `half-open` peer → Registry `/‑/find` 返回其他 peer。
-
-### 流式调用 (Stream)
-
-`stream()` 用于**需要持续推送数据**的场景：大数据集、实时事件、LLM token 流、进度上报等。不需要流式传输时优先用 `call()`。
-
-**Provider 侧**：消息处理器必须返回 async generator（`async function*`）。
-
-```typescript
-// 通过 register() 注册
-app.register('/events', async function* () {
-  for (let i = 0; i < 100; i++) {
-    yield { seq: i, time: Date.now() }
-    await new Promise(r => setTimeout(r, 100))
-  }
-})
-
-// 或通过 .msg 文件定义（推荐）
-// src/messages/events.msg.ts
+```ts
+// src/messages/ping.msg.ts
 import { defineMessage } from '@hile/message-loader'
-export default defineMessage(async function* ({ data }) {
-  for (const item of await fetchItems(data.query)) {
-    yield item
+
+export default defineMessage(async ({ data, params }) => {
+  return {
+    type: 'pong',
+    data,
+    params,
+    timestamp: Date.now(),
   }
 })
 ```
 
-**Consumer 侧**：`app.stream()` 返回 `Readable` stream，可用 `for await` 逐 chunk 消费。
-
-```typescript
-const stream = await app.stream('data-svc', '/events', { query: 'recent' })
-for await (const chunk of stream) {
-  console.log(chunk)  // { seq: 0, time: 1718000000000 }
-}
-```
-
-**注意事项**：
-- 普通 handler（返回非 async iterable）被 `stream()` 调用时会报错 `"Invalid async iterable"`
-- 不需要流式传输时用 `call()`，不要用 `stream()` 取单次返回值
-- `stream()` 享有与 `call()` 相同的选路与熔断；同步建流失败可按 `retries` 重试，流已返回后的异步错误会计入熔断但不会自动重放流
-
-### 健康检查
-
-每个 `Application` 自动注册 `/-/health` 端点：
-
-```typescript
-// 通过 dispatch 调用（同进程内）
-const health = await app.dispatch('/-/health', {});
-// { status: 'ok', registry: true, uptime: 123.45, namespaces: ['payments'] }
-```
-
-返回字段：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `status` | `'ok'` | 固定值 |
-| `registry` | `boolean` | 是否已连接 Registry |
-| `uptime` | `number` | 进程启动时长（秒） |
-| `namespaces` | `string[]` | 本地已缓存的 namespace 列表 |
+Microservice boot file:
 
-### 缓存降级
+```ts
+// src/services/app.boot.ts
+import { defineService } from '@hile/core'
+import { Application } from '@hile/micro'
 
-当 Registry 不可用但本地仍有已缓存的 Client 连接时，`get()` 自动降级使用缓存。熔断器在“所有 `open` peer 都被排除”并触发本地 reset 时，也会保留已经选中的可用缓存 Client，不会因为 Registry 短暂不可用而丢弃仍可通信的连接。
-
-| 场景 | 行为 |
-|------|------|
-| 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`），停止重连
-
----
-
-## 配置管理
-
-### Registry 工作目录
-
-Registry 启动时自动创建 `~/.registry/` 工作目录。YAML 配置文件存放在 `~/.registry/configs/` 下，按 namespace 分文件管理：
-
-```
-~/.registry/
-  └── configs/
-        ├── service-a.config.yaml
-        ├── service-b.config.yaml
-        └── global.config.yaml
-```
-
-### 配置文件热加载
-
-Regsitry 监听 `configs/` 目录的文件变化，新增或修改 `*.config.yaml` 文件时自动加载（兼容 vim 原子写入），无需重启：
-
-```bash
-# 创建或修改 ~/.registry/configs/my-service.config.yaml
-# Registry 自动检测变化并更新内存中的配置
-```
-
-### 远程读取配置
-
-通过 `/-/env/variables` 端点，已连服务可按 namespace 和字段从 Registry 远程读取配置：
-
-```typescript
-// Application 侧
-const result = await app.getEnvVariables(
-  { namespace: 'service-a', fields: ['db.host', 'db.port'] },
-  { namespace: 'global' },
-);
-// result = {
-//   'service-a': { 'db.host': '10.0.0.2', 'db.port': 3306 },
-//   'global': { featureFlag: true },
-// }
-```
-
----
-
-## CLI
-
-### `hile registry`
-
-启动注册中心：
-
-```bash
-# 使用默认配置
-hile registry
-
-# 指定端口
-hile registry --port 8888
-
-# 指定宣告地址
-hile registry --host 10.0.0.1
-```
-
-### `hile registry configs`
-
-管理 `~/.registry/configs/` 下的 YAML 配置文件：
-
-```bash
-# 列出所有 namespace
-hile registry configs
-
-# 查看配置（YAML 输出）
-hile registry configs get my-service
-
-# 查看配置（JSON 输出）
-hile registry configs get my-service --json
-
-# 设置配置项
-hile registry configs set my-service port=8080
-hile registry configs set my-service debug=true
-
-# 删除整个 namespace
-hile registry configs del my-service
-
-# 删除某个字段（需确认）
-hile registry configs del my-service port
-
-# 跳过确认删除
-hile registry configs del my-service -y
-```
-
-## 连接协议
-
-### 连接 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,
-    options?: {
-      timeout?: number,     // 请求超时（ms），默认 requestTimeoutMs
-      retries?: number,     // 失败重试次数，默认 1
-      signal?: AbortSignal, // 手动取消
-    },
-  ): Promise<T>;
-
-  // 流式调用：get + stream + 熔断；同步建流失败可重试
-  // provider handler 必须返回 async generator，consumer 获得 Readable stream
-  stream(
-    namespace: string,
-    url: string,
-    data: any,
-    options?: {
-      signal?: AbortSignal,
-      retries?: number,     // 失败重试次数，默认 1
+export default defineService('micro.app', async (shutdown) => {
+  const app = new Application({
+    namespace: process.env.MICRO_NAMESPACE ?? 'example.service',
+    registry: {
+      host: process.env.REGISTRY_HOST ?? '127.0.0.1',
+      port: Number(process.env.REGISTRY_PORT ?? 9876),
     },
-  ): Promise<import('stream').Readable>;
-
-  // 注册路由（provider 侧）
-  register<T = any>(url: string, handler: (ctx) => Promise<T>): () => void;
-
-  // 同进程调用路由
-  dispatch(url: string, data: any): Promise<any>;
-
-  // 远程读取 Registry 的配置（强类型）
-  getEnvVariables<
-    T extends Record<string, Record<string, any>>,
-    const Requests extends readonly EnvRequest<T>[],
-  >(...data: Requests): Promise<GetEnvVariablesResult<T, Requests>>;
-}
-```
+    advertiseHost: process.env.HILE_ADVERTISE_HOST ?? '127.0.0.1',
+  })
 
-### Registry
-
-```typescript
-class Registry extends Server {
-  constructor(props?: MicroServerProps);
-  listen(port: number): Promise<() => Promise<void>>;
-  onFind(): void; // 幂等地挂载 /-/find 路由
-  watchEnvFile(): fs.FSWatcher | undefined; // 监听 ~/.registry/configs/ 目录内的 *.config.yaml 文件变化
-}
+  await app.load(new URL('../messages', import.meta.url).pathname)
+  const stop = await app.listen(Number(process.env.MICRO_PORT ?? 0))
+  shutdown(stop)
+  return app
+})
 ```
 
-### Server
+Caller:
 
-```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>;
-}
+```ts
+const result = await app.call('example.service', '/ping', { hello: 'world' })
 ```
 
-### 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;
-  stream(url: string, data: any, options?: { signal?: AbortSignal }): Readable;
-  dispose(): void;
-}
-```
+## Boundaries
 
----
+- Do not use `stream()` for normal single-result calls.
+- Do not rely on message IDs for business idempotency. They are transport IDs.
+- Do not bypass `defineMessage()` for file-loaded handlers.
 
-## 与 Hile core 的关系
+- Appending a secondary response getter to `client.request('/x', data)`
+- Returning a plain object from a handler called through `stream()`.
+- Using pub/sub as a durable queue.
+- Forgetting to register `shutdown(await app.listen(...))`.
 
-`@hile/micro` 不依赖 `@hile/core`，可与任意 Node.js 进程或在未来由 `defineService` 包装后接入 Hile 容器。
+## Verify
 
----
+- Message files default-export `defineMessage(...)`.
+- RPC callers use `await app.call(...)`.
+- Streaming handlers are async generators.
+- Registry is started before application nodes need discovery.
+- Micro apps use stable namespaces and advertise reachable hosts.
 
-## License
+## More Context
 
-MIT
+- `AI.md` in this package: full package-local AI guide.
+- Root `llms-full.txt`: full monorepo AI context.
+- Root `references/`: source files copied from `docs/ai`.

package/dist/client.d.ts

@@ -1,4 +1,5 @@
 import { MessageWs } from "@hile/message-ws";
+import { type ContextData, type ContextInput } from '@hile/context';
 import { Server } from './server.js';
 import { WebSocket } from 'ws';
 import { EventEmitter } from 'node:events';
@@ -8,6 +9,15 @@ export interface ClientProps {
     server: Server;
     ws: WebSocket;
 }
+export type MicroMessageMetadata = {
+    context?: ContextInput<ContextData>;
+    [key: string]: unknown;
+};
+export type MicroMessage<T = any> = {
+    url: string;
+    data: T;
+    metadata?: MicroMessageMetadata;
+};
 export declare class Client extends MessageWs {
     private readonly server;
     private readonly socket;
@@ -20,10 +30,7 @@ export declare class Client extends MessageWs {
     readonly events: EventEmitter<any>;
     constructor(props: ClientProps);
     private startHeartbeat;
-    protected exec(data: {
-        url: string;
-        data: any;
-    }): Promise<any>;
+    protected exec(data: MicroMessage): Promise<any>;
     request<T = any>(url: string, data: any, options?: {
         timeout?: number;
         signal?: AbortSignal;

package/dist/client.js

@@ -1,6 +1,52 @@
 import { MessageWs } from "@hile/message-ws";
+import { isContextData, runWithContext, snapshotContext, } from '@hile/context';
 import { WebSocket } from 'ws';
 import { EventEmitter } from 'node:events';
+function createEnvelope(url, data) {
+    const context = snapshotContext();
+    if (Object.keys(context).length === 0)
+        return { url, data };
+    return {
+        url,
+        data,
+        metadata: {
+            context,
+        },
+    };
+}
+function getEnvelopeContext(data) {
+    const context = data.metadata?.context;
+    if (!isContextData(context))
+        return undefined;
+    return context;
+}
+function isAsyncIterable(value) {
+    return value != null && typeof value[Symbol.asyncIterator] === 'function';
+}
+function bindAsyncIterableToContext(iterable, context) {
+    return {
+        [Symbol.asyncIterator]() {
+            const iterator = iterable[Symbol.asyncIterator]();
+            return {
+                next() {
+                    return Promise.resolve(runWithContext(context, () => iterator.next()));
+                },
+                return(value) {
+                    if (!iterator.return) {
+                        return Promise.resolve({ done: true, value });
+                    }
+                    return Promise.resolve(runWithContext(context, () => iterator.return(value)));
+                },
+                throw(error) {
+                    if (!iterator.throw) {
+                        return Promise.reject(error);
+                    }
+                    return Promise.resolve(runWithContext(context, () => iterator.throw(error)));
+                },
+            };
+        },
+    };
+}
 export class Client extends MessageWs {
     server;
     socket;
@@ -48,24 +94,35 @@ export class Client extends MessageWs {
         }
         if (!this._online)
             throw new Error('Client is not online');
-        return this.server.dispatch(data.url, data.data, {
-            client: this,
-        });
+        const context = getEnvelopeContext(data);
+        const dispatch = async () => {
+            const result = await this.server.dispatch(data.url, data.data, {
+                client: this,
+                metadata: data.metadata,
+            });
+            if (context && isAsyncIterable(result)) {
+                return bindAsyncIterableToContext(result, context);
+            }
+            return result;
+        };
+        if (context)
+            return runWithContext(context, dispatch);
+        return dispatch();
     }
     request(url, data, options) {
         if (!this._online)
             throw new Error('Client is not online');
-        return this._send({ url, data }, options);
+        return this._send(createEnvelope(url, data), options);
     }
     push(url, data, options) {
         if (!this._online)
             throw new Error('Client is not online');
-        return this._push({ url, data }, options);
+        return this._push(createEnvelope(url, data), options);
     }
     stream(url, data, options) {
         if (!this._online)
             throw new Error('Client is not online');
-        return this._stream({ url, data }, options);
+        return this._stream(createEnvelope(url, data), options);
     }
     dispose() {
         if (this.heartbeatTimer)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/micro",
-  "version": "2.1.1",
+  "version": "3.0.1",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -11,7 +11,7 @@
   "files": [
     "dist",
     "README.md",
-    "SKILL.md"
+    "AI.md"
   ],
   "license": "MIT",
   "publishConfig": {
@@ -23,12 +23,13 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/logger": "^2.1.1",
-    "@hile/message-loader": "^2.1.1",
-    "@hile/message-ws": "^2.1.1",
+    "@hile/context": "^3.0.2",
+    "@hile/logger": "^3.0.0",
+    "@hile/message-loader": "^3.0.0",
+    "@hile/message-ws": "^3.0.0",
     "internal-ip": "^9.0.0",
     "ws": "^8.21.0",
     "yaml": "^2.9.0"
   },
-  "gitHead": "7903ae989bd001d1ed1437cb90c9e828a1909061"
+  "gitHead": "0985b6f8abc1f4de0a36324063585fdc3ac1375b"
 }