@hile/micro 1.0.5 → 1.0.7

package/README.md

@@ -243,6 +243,92 @@ const health = await app.dispatch('/-/health', {});
 
 ---
 
+## 配置管理
+
+### 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 格式
@@ -308,6 +394,12 @@ class Application extends Server {
 
   // 同进程调用路由
   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>>;
 }
 ```
 
@@ -318,6 +410,7 @@ class Registry extends Server {
   constructor(props?: MicroServerProps);
   listen(port: number): Promise<() => Promise<void>>;
   onFind(): void; // 幂等地挂载 /-/find 路由
+  watchEnvFile(): fs.FSWatcher | undefined; // 监听 ~/.registry/configs/ 目录内的 *.config.yaml 文件变化
 }
 ```
 

package/SKILL.md

@@ -29,8 +29,8 @@ description: Code generation and contribution rules for @hile/micro. Use when ed
 |----|------|------|---------|
 | `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 |
+| `Registry` | `registry.ts` | namespace → Set\<host:port\>, 心跳检测, /-/find 随机返回, 环境变量管理 | 自动创建 `~/.registry/` 工作目录 |
+| `Application` | `application.ts` | 注册发现 + 熔断 + 重试 + 追踪 + 心跳 + 远程环境变量读取 | `listen()` 后自动连 Registry |
 
 ### 应用模型
 
@@ -95,17 +95,28 @@ export interface RegistryFindData {
 
 export function parseAddressKey(key: string): RegistryAddress | undefined;
 export function selectRandomRegistryAddress(keys: Iterable<string>): RegistryAddress | undefined;
+// 配置文件路径工具：
+export function getRegistryConfigsDir(): string;         // 返回 ~/.registry/configs/
+export function namespaceToConfigFile(ns: string): string;  // 返回 ~/.registry/configs/{ns}.config.yaml
+export function parseConfigFilename(filename: string): string | null;  // 解析 ".config.yaml" 后缀，提取 namespace
 
 export class Registry extends Server {
   // heartbeat 常量:
   //   HEARTBEAT_INTERVAL = 1000   (1s 轮询)
   //   HEARTBEAT_TIMEOUT = 20000   (20s 未收到心跳则剔除)
+  // 工作目录: ~/.registry/ (自动创建)
+  //   - configs/ 目录存放 *.config.yaml 配置文件
+  //   - watchEnvFile() 监听 configs/ 目录，兼容 vim 原子写入
+  //   - configs Map<string, any> 按 namespace 存储解析后的 YAML 内容
+  // 内部路由:
+  //   /-/find             — 按 namespace 随机返回地址 (支持 exclude)
+  //   /-/heartbeat        — 更新实例心跳时间戳
+  //   /-/env/variables    — 按 namespace + fields 返回配置 (通过 getEnvVariables 调用)
+
   constructor(props?: MicroServerProps);
   listen(port: number): Promise<() => Promise<void>>;
   onFind(): void; // 幂等，可重复调用
-  // 内部路由:
-  //   /-/find     — 按 namespace 随机返回地址 (支持 exclude)
-  //   /-/heartbeat — 更新实例心跳时间戳
+  watchEnvFile(): fs.FSWatcher | undefined; // 监听 ~/.registry/configs/ 目录
 }
 ```
 
@@ -140,6 +151,12 @@ export class Application extends Server {
     retries?: number,     // 重试次数, 默认 1
   ): Promise<T>;
 
+  // 远程读取 Registry 的配置（强类型，按 namespace + fields）
+  getEnvVariables<
+    T extends Record<string, Record<string, any>>,
+    const Requests extends readonly EnvRequest<T>[],
+  >(...data: Requests): Promise<GetEnvVariablesResult<T, Requests>>;
+
   // 继承自 Server/MessageLoader:
   // register<T, E>(url, handler): () => void;
   // dispatch(url, data, extras): Promise<any>;
@@ -359,6 +376,72 @@ listen() teardown 触发:
 
 **不处理的情况：** 全新 namespace（无缓存）、缓存 Client 已断连。
 
+### 3.10 配置管理
+
+**存储结构：**
+
+```
+~/.registry/
+  └── configs/
+        ├── service-a.config.yaml
+        ├── service-b.config.yaml
+        └── global.config.yaml
+```
+
+**Registry 侧：**
+
+```
+Registry 构造:
+  1. 创建 ~/.registry/ 目录 (自动)
+
+Registry listen():
+  1. 调用 watchEnvFile()
+     └─ 读取 ~/.registry/configs/ 下所有 *.config.yaml → YAML.parse
+     └─ 按 namespace 存入 this.configs Map
+     └─ 监听 configs/ 目录 (兼容 vim 原子写入)
+         └─ 文件变化 → 重新 YAML.parse 并更新 this.configs
+
+/-/env/variables 端点:
+  register('/-/env/variables', async ({ data }) => {
+    data.map(({ namespace, fields }) => {
+      if (!this.configs.has(namespace))
+        return { namespace, value: null }
+      if (!fields?.length)
+        return { namespace, value: this.configs.get(namespace) }
+      // 按 fields 过滤
+      return { namespace, value: filteredConfig }
+    })
+  })
+```
+
+**Application 侧：**
+
+```typescript
+// 强类型查询
+type EnvRequest<T> = {
+  [N in keyof T]: { namespace: N; fields?: readonly (keyof T[N])[] };
+}[keyof T];
+
+type GetEnvVariablesResult<T, Requests> = UnionToIntersection<...>;
+
+getEnvVariables(...data: EnvRequest<T>[]): Promise<GetEnvVariablesResult<T, Requests>>
+```
+
+**CLI 管理配置：**
+
+通过 `hile registry configs` 子命令直接管理 `~/.registry/configs/` 下的 YAML 文件：
+
+```
+hile registry configs                              # 列出所有 namespace
+hile registry configs get <namespace>               # 查看配置（YAML/--json）
+hile registry configs set <namespace> <key>=<value> # 设置配置项
+hile registry configs del <namespace> [key]         # 删除（带确认，-y 跳过）
+```
+
+- CLI 直接读写 YAML 文件，运行中的 Registry 通过 `fs.watch` 自动感知
+- 值类型自动推断：`true/false` → boolean, `null` → null, 纯数字 → number, 以 `{`/`[` 开头 → JSON 解析为 object/array, 其余 → string
+- 实现代码在 `packages/cli/src/configs.ts`，工具函数在 `packages/micro/src/registry.ts`
+
 ---
 
 ## 4. 代码生成模板
@@ -470,6 +553,19 @@ pnpm --filter @hile/micro test     # 必须全部通过
 | 超时 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` |
+| YAML 配置加载 | `config file loading > loads yaml config files on watchEnvFile` |
+| YAML 配置热加载 | `config file loading > reloads config when yaml file changes` |
+| configs 目录不存在 | `config file loading > does not crash when configs directory does not exist` |
+| /-/env/variables 按字段过滤 | `/-/env/variables endpoint > returns requested config by namespace and fields` |
+| /-/env/variables 全字段 | `/-/env/variables endpoint > returns all config when fields not specified` |
+| 不存在的 namespace | `/-/env/variables endpoint > returns null value for non-existent namespace` |
+| /-/env/variables 空列表 | `/-/env/variables endpoint > handles empty data list` |
+| getEnvVariables 集成 | `Application.getEnvVariables > fetches config from Registry` |
+| getEnvVariables 不存在 namespace | `Application.getEnvVariables > returns null when namespace config does not exist` |
+| getRegistryConfigsDir | `config file utilities > getRegistryConfigsDir returns path ending with .registry/configs` |
+| namespaceToConfigFile | `config file utilities > namespaceToConfigFile returns path with .config.yaml suffix` |
+| parseConfigFilename 正例 | `config file utilities > parseConfigFilename extracts namespace from valid filename` |
+| parseConfigFilename 反例 | `config file utilities > parseConfigFilename returns null for non-config file` |
 
 ### 5.3 测试规范（必须遵守）
 
@@ -490,7 +586,7 @@ pnpm --filter @hile/micro test     # 必须全部通过
 4. **不要假设 `host:port` 可无损表达 IPv6** — 使用 `[IPv6]:port` 格式，`parseAddressKey` 按最后一个 `:` 切分
 5. **不要传错 Registry 端口** — 丢失 Registry 连接时依赖 `reconnectToRegistry`，不要在外部缓存 registry Client
 6. **不要在 call() 中修改原始 data 对象** — 必须使用浅拷贝 `{ ...data, _correlationId }`
-7. **不要在其他文件中重复 `selectRandomRegistryAddress` 或 `parseAddressKey`** — 这些是 Registry 的内部 helper
+7. **不要在其他文件中重复 Registry 的 helper 函数** — `selectRandomRegistryAddress`、`parseAddressKey`、`getRegistryConfigsDir`、`namespaceToConfigFile`、`parseConfigFilename` 都在 `registry.ts` 中导出复用
 8. **不要给 call() 增加非可选参数** — `timeout` 和 `retries` 都在尾部且保持可选，不影响现有调用
 
 ---
@@ -500,13 +596,18 @@ pnpm --filter @hile/micro test     # 必须全部通过
 | 文件 | 可修改 | 说明 |
 |------|--------|------|
 | `packages/micro/src/application.ts` | ✅ | 核心业务逻辑 |
-| `packages/micro/src/index.test.ts` | ✅ | 测试 |
+| `packages/micro/src/index.test.ts` | ✅ | 测试（主测试文件） |
+| `packages/micro/src/env-config.test.ts` | ✅ | 测试（环境变量配置测试） |
 | `packages/micro/src/server.ts` | ❌ | 底层协议，不动 |
 | `packages/micro/src/client.ts` | ❌ | 底层协议，不动 |
-| `packages/micro/src/registry.ts` | ❌ | 注册中心，不动 |
+| `packages/micro/src/registry.ts` | ✅ | 注册中心（配置管理、路径工具函数） |
 | `packages/micro/src/utils.ts` | ❌ | 工具函数，不动 |
 | `packages/micro/README.md` | ✅ | 用户文档 |
 | `packages/micro/SKILL.md` | ✅ | AI 参考文档 |
+| `packages/cli/src/index.ts` | ✅ | CLI 入口（registry configs 子命令组） |
+| `packages/cli/src/configs.ts` | ✅ | CLI 配置管理 handler（list/get/set/del） |
+| `packages/cli/src/start.ts` | ❌ | 启动逻辑，不动 |
+| `packages/cli/src/exitHook.ts` | ❌ | 退出钩子，不动 |
 
 ---
 
@@ -514,7 +615,9 @@ pnpm --filter @hile/micro test     # 必须全部通过
 
 | 文件 | 用途 |
 |------|------|
-| `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` | 实施计划 |
+| `packages/micro/src/registry.ts` | 注册中心（含配置管理、路径工具函数） |
+| `packages/micro/src/application.ts` | 应用服务（含 getEnvVariables） |
+| `packages/micro/src/index.test.ts` | 主测试文件（28 个用例） |
+| `packages/micro/src/env-config.test.ts` | 配置管理测试文件（13 个用例） |
+| `packages/cli/src/index.ts` | CLI 入口（含 registry configs 子命令组） |
+| `packages/cli/src/configs.ts` | CLI 配置管理 handler（list/get/set/del） |

package/dist/application.d.ts

@@ -1,6 +1,21 @@
 import { Client } from './client.js';
 import { Server, type MicroServerProps } from './server.js';
 import { RegistryAddress } from './registry.js';
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+type EnvRequest<T extends Record<string, Record<string, any>>> = {
+    [N in keyof T]: {
+        namespace: N;
+        fields?: readonly (keyof T[N])[];
+    };
+}[keyof T];
+type EnvFieldsForRequest<T extends Record<string, Record<string, any>>, N extends keyof T, F> = F extends readonly (infer K extends keyof T[N])[] ? Pick<T[N], K> : T[N];
+type EnvRequestResult<T extends Record<string, Record<string, any>>, R> = R extends {
+    namespace: infer N extends keyof T;
+    fields?: infer F;
+} ? {
+    [K in N]: EnvFieldsForRequest<T, N, F>;
+} : never;
+export type GetEnvVariablesResult<T extends Record<string, Record<string, any>>, Requests extends readonly EnvRequest<T>[]> = UnionToIntersection<EnvRequestResult<T, Requests[number]>>;
 export type ApplicationProps = {
     namespace: string;
     registry: RegistryAddress;
@@ -35,4 +50,6 @@ export declare class Application extends Server {
     private findFromRegistry;
     get(namespace: string, exclude?: string[]): Promise<Client>;
     call<T = any>(namespace: string, url: string, data: any, timeout?: number, retries?: number): Promise<T>;
+    getEnvVariables<T extends Record<string, Record<string, any>>, const Requests extends readonly EnvRequest<T>[] = readonly EnvRequest<T>[]>(...data: Requests): Promise<GetEnvVariablesResult<T, Requests>>;
 }
+export {};

package/dist/application.js

@@ -293,4 +293,15 @@ export class Application extends Server {
             throw err;
         }
     }
+    async getEnvVariables(...data) {
+        if (!this.registry)
+            throw new Error('Registry not found');
+        const { response } = this.registry.request('/-/env/variables', data);
+        const configs = await response();
+        const out = {};
+        for (const { namespace, value } of configs) {
+            out[namespace] = value;
+        }
+        return out;
+    }
 }

package/dist/registry.d.ts

@@ -10,15 +10,23 @@ export interface RegistryAddress {
 /** 将 `host:port` 或 `[ipv6]:port` 形式的 key 解析为地址（端口取最后一个 `:` 之后） */
 export declare function parseAddressKey(key: string): RegistryAddress | undefined;
 export declare function selectRandomRegistryAddress(keys: Iterable<string>): RegistryAddress | undefined;
+export declare function getRegistryConfigsDir(): string;
+export declare function namespaceToConfigFile(ns: string): string;
+export declare function parseConfigFilename(filename: string): string | null;
 export declare class Registry extends Server {
     private readonly namespaces;
     private unregisterFind?;
     private static readonly HEARTBEAT_INTERVAL;
     private static readonly HEARTBEAT_TIMEOUT;
     private readonly heartbeats;
+    private readonly workspace;
+    private readonly configFileSuffix;
+    private readonly configs;
     constructor(props?: MicroServerProps);
+    watchEnvFile(): import("node:fs").FSWatcher | undefined;
     listen(port?: number): Promise<() => Promise<void>>;
     /** 幂等：重复调用会先注销上一条 `/-/find` 再注册，避免叠多条路由 */
     onFind(): void;
     private mountFindHandler;
+    private registerEnvVariables;
 }

package/dist/registry.js

@@ -1,4 +1,8 @@
 import { Server } from './server.js';
+import { homedir } from 'node:os';
+import { resolve, join } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, readFileSync, watch } from 'node:fs';
+import YAML from 'yaml';
 /** 将 `host:port` 或 `[ipv6]:port` 形式的 key 解析为地址（端口取最后一个 `:` 之后） */
 export function parseAddressKey(key) {
     const i = key.lastIndexOf(':');
@@ -24,14 +28,33 @@ export function selectRandomRegistryAddress(keys) {
     const index = Math.floor(Math.random() * addresses.length);
     return addresses[index];
 }
+export function getRegistryConfigsDir() {
+    return resolve(homedir(), '.registry', 'configs');
+}
+export function namespaceToConfigFile(ns) {
+    return join(getRegistryConfigsDir(), `${ns}.config.yaml`);
+}
+export function parseConfigFilename(filename) {
+    if (!filename.endsWith('.config.yaml'))
+        return null;
+    return filename.slice(0, -'.config.yaml'.length);
+}
 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 ?? {});
+    workspace;
+    configFileSuffix = '.config.yaml';
+    configs = new Map();
+    constructor(props = {}) {
+        const workspace = resolve(homedir(), '.registry');
+        if (!existsSync(workspace)) {
+            mkdirSync(workspace, { recursive: true });
+        }
+        super('registry', props);
+        this.workspace = workspace;
         this.events.on('connect', (client, extras) => {
             const key = client.host + ':' + client.port;
             this.heartbeats.set(key, Date.now());
@@ -56,6 +79,7 @@ export class Registry extends Server {
             }
         });
         this.mountFindHandler();
+        this.registerEnvVariables();
         this.register('/-/heartbeat', async ({ client }) => {
             if (!client)
                 return;
@@ -63,8 +87,38 @@ export class Registry extends Server {
             this.heartbeats.set(key, Date.now());
         });
     }
+    watchEnvFile() {
+        const configFile = resolve(this.workspace, 'configs');
+        if (!existsSync(configFile))
+            return;
+        const configFiles = readdirSync(configFile).filter(filename => filename.endsWith(this.configFileSuffix));
+        for (const filename of configFiles) {
+            try {
+                const config = YAML.parse(readFileSync(resolve(configFile, filename), 'utf8'));
+                if (typeof config !== 'object' || config === null)
+                    continue;
+                this.configs.set(parseConfigFilename(filename), config);
+            }
+            catch { }
+        }
+        return watch(configFile, (_, filename) => {
+            if (!filename?.endsWith(this.configFileSuffix))
+                return;
+            try {
+                const config = YAML.parse(readFileSync(resolve(configFile, filename), 'utf8'));
+                if (typeof config !== 'object' || config === null)
+                    return;
+                this.configs.set(parseConfigFilename(filename), config);
+            }
+            catch { /* vim 替换文件时的中间态读错误，忽略 */ }
+        });
+    }
     async listen(port = 0) {
-        const teardown = await super.listen(port);
+        const registry_port = process.env.REGISTRY_PORT ? Number(process.env.REGISTRY_PORT) : 0;
+        const _port = port || registry_port;
+        if (!_port || _port <= 0)
+            throw new Error('Unable to resolve registry port: pass `port` in constructor options, or ensure process.env.REGISTRY_PORT is set.');
+        const teardown = await super.listen(_port);
         const timer = setInterval(() => {
             const now = Date.now();
             for (const [key, lastTime] of this.heartbeats) {
@@ -77,7 +131,10 @@ export class Registry extends Server {
                 }
             }
         }, Registry.HEARTBEAT_INTERVAL);
+        const watcher = this.watchEnvFile();
         return async () => {
+            if (watcher)
+                watcher.close();
             clearInterval(timer);
             await teardown();
         };
@@ -106,4 +163,21 @@ export class Registry extends Server {
             return selectRandomRegistryAddress(keys);
         });
     }
+    registerEnvVariables() {
+        this.register('/-/env/variables', async ({ data }) => {
+            return data.map(({ namespace, fields }) => {
+                if (!this.configs.has(namespace)) {
+                    return { namespace, value: null };
+                }
+                if (!fields?.length)
+                    return { namespace, value: this.configs.get(namespace) };
+                const config = this.configs.get(namespace);
+                const value = {};
+                for (const field of fields) {
+                    value[field] = config[field];
+                }
+                return { namespace, value };
+            });
+        });
+    }
 }

package/dist/server.d.ts

@@ -18,6 +18,7 @@ export declare class Server extends MessageLoader {
     protected readonly clients: Map<string, Client>;
     private readonly announceHost;
     readonly events: EventEmitter<any>;
+    get host(): string;
     constructor(namespace: string, props?: MicroServerProps);
     private upstream;
     private createClient;

package/dist/server.js

@@ -12,6 +12,9 @@ export class Server extends MessageLoader {
     clients = new Map();
     announceHost;
     events = new EventEmitter();
+    get host() {
+        return this.announceHost;
+    }
     constructor(namespace, props = {}) {
         const { advertiseHost, ...loaderProps } = props;
         super(loaderProps);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/micro",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -26,7 +26,8 @@
     "@hile/message-loader": "^1.0.8",
     "@hile/message-ws": "^1.0.6",
     "internal-ip": "^9.0.0",
-    "ws": "^8.19.0"
+    "ws": "^8.19.0",
+    "yaml": "^2.9.0"
   },
-  "gitHead": "ddc82850295d26358cbffbb695e642cdb748339d"
+  "gitHead": "fdf2a5159fef97ca1f8258d6d11c62a061fd9ef4"
 }