@h-ai/cli 0.1.0-alpha.47 → 0.1.0-alpha.49

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "0.1.0-alpha.47",
+  "version": "0.1.0-alpha.49",
   "description": "Hai Framework CLI for project scaffolding and code generation.",
   "license": "Apache-2.0",
   "keywords": [
@@ -34,7 +34,7 @@
     "ora": "^9.1.0",
     "prompts": "^2.4.2",
     "yaml": "^2.7.0",
-    "@h-ai/core": "0.1.0-alpha.47"
+    "@h-ai/core": "0.1.0-alpha.49"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/templates/apps/api/apps/{{projectName}}-service/config/_serv.yml.hbs

@@ -2,6 +2,10 @@
 # {{projectName}} API Service - Serv / HTTP 入口配置
 # =============================================================================
 
+server:
+  host: 127.0.0.1
+  port: 3000
+
 http:
   apiPrefix: /api/v1
   openapi:

package/templates/apps/api/apps/{{projectName}}-service/src/index.ts.hbs

@@ -1,3 +1,4 @@
+import type { ServConfig } from '@h-ai/serv'
 import process from 'node:process'
 import { core } from '@h-ai/core'
 import { serv } from '@h-ai/serv'
@@ -9,7 +10,11 @@ const logger = core.logger.child({ app: '{{api.servicePackageName}}', scope: 'en
 async function main(): Promise<void> {
   await initApp()
 
+  // host/port 来自 config/_serv.yml 的 server（HOST/PORT 环境变量高于配置文件）。
+  const { server } = core.config.getOrThrow<ServConfig>('serv')
   serv.listen({{api.serviceAppFactoryName}}(), {
+    host: server.host,
+    port: server.port,
     onListening: info => logger.info('API service listening', { address: info.address, port: info.port }),
     onClose: closeApp,
   })

package/templates/apps/fullstack/packages/{{projectName}}-serv/config/_serv.yml.hbs

@@ -5,6 +5,10 @@
 # 业务接口路径直接写在对应 *-contract.ts；公共 HTTP 传输配置以本文件为准。
 # =============================================================================
 
+server:
+  host: 127.0.0.1
+  port: 3000
+
 http:
   apiPrefix: /api/v1
   openapi:

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/index.ts.hbs

@@ -1,18 +1,18 @@
-import process from 'node:process'
+import type { ServConfigInput } from '@h-ai/serv'
 import { core } from '@h-ai/core'
-import { serv } from '@h-ai/serv'
+import { serv, ServConfigSchema } from '@h-ai/serv'
 import { createServerApp } from './app-server.js'
 
 // 加载 config/ 下的 _core.yml / _serv.yml 等配置文件（约定优于配置）
 core.init({ configDir: './config', logging: { level: 'info' } })
 
+// host/port 来自 config/_serv.yml 的 server（HOST/PORT 环境变量高于配置文件）。
+const { server } = ServConfigSchema.parse(core.config.get<ServConfigInput>('serv') ?? {})
 const app = createServerApp()
-const port = process.env.PORT ? Number(process.env.PORT) : 3000
-const host = process.env.HOST ?? '127.0.0.1'
 const listenApp = app as Parameters<typeof serv.listen>[0]
 
 serv.listen(listenApp, {
-  port,
-  host,
-  onListening: info => core.logger.info('{{fullstack.servPackageName}} listening', { host, port: info.port }),
+  host: server.host,
+  port: server.port,
+  onListening: info => core.logger.info('{{fullstack.servPackageName}} listening', { host: server.host, port: info.port }),
 })

package/templates/base/package.json.hbs

@@ -1,6 +1,6 @@
 {
   "name": "{{projectName}}",
-  "version": "0.1.0-alpha.47",
+  "version": "0.1.0-alpha.49",
   "private": true,
   "description": "{{#if_eq appType 'admin'}}Enterprise management system built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'website'}}Enterprise website built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'h5'}}Mobile H5 app built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'api'}}REST API service built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'mobile-app'}}Mobile app built with hai Agent Framework{{/if_eq}}",
   "keywords": ["hai", {{#unless isSvelteOnlyApp}}"sveltekit", {{/unless}}"svelte5", "{{appType}}"],

package/templates/skills/hai-ai/SKILL.md

@@ -202,6 +202,7 @@ await ai.llm.ask('翻译这段话', { tempModel: { model: 'gpt-4o', apiKey: 'sk-
 
 ```ts
 import { createMcpServer, StreamableHTTPServerTransport } from '@h-ai/ai'
+import { core } from '@h-ai/core'
 
 const server = createMcpServer({ name: 'my-server', version: '1.0.0' })
 server.registerTool('search', {
@@ -211,7 +212,7 @@ server.registerTool('search', {
   content: [{ type: 'text', text: `Results for ${query}` }],
 }))
 
-await server.connect(new StreamableHTTPServerTransport({ sessionIdGenerator: crypto.randomUUID }))
+await server.connect(new StreamableHTTPServerTransport({ sessionIdGenerator: core.id.uuid }))
 ```
 
 ## 记忆、RAG 与知识库

package/templates/skills/hai-app-create/SKILL.md

@@ -233,7 +233,7 @@ export async function createArticle(input: CreateArticleInput): Promise<HaiResul
   logger.debug('Creating article', { title: input.title })
 
   const result = await reldb.crud.create('articles', {
-    id: crypto.randomUUID(),
+    id: core.id.uuid(),
     ...input,
     created_at: new Date().toISOString(),
   })

package/templates/skills/hai-core/SKILL.md

@@ -316,6 +316,14 @@ core.id.isValidUUID('f47ac10b-...')    // true/false
 core.id.isValidNanoId('abc123', 6)     // true/false
 ```
 
+#### UUID 生成规范（强制）
+
+- 生成 UUID **一律用 `core.id.uuid()`**，禁止裸调 `crypto.randomUUID()`。
+- 原因：`crypto.randomUUID` 仅在**安全上下文（HTTPS / localhost）**下可用，生产 http 环境会抛
+  `crypto.randomUUID is not a function`；`core.id.uuid()` 已做 `randomUUID → getRandomValues → Math.random` 三级兜底，Node.js 与浏览器通用。
+- 需要不带横线的 compact 形式：`core.id.uuid().replaceAll('-', '')`。
+- 代码评审与新建代码时以此为准，发现裸调 `crypto.randomUUID()` 一律改走 `core.id.uuid()`。
+
 ### 工具函数
 
 #### 类型检查 — `core.typeUtils`

package/templates/skills/hai-kit/SKILL.md

@@ -131,6 +131,10 @@ transport 默认保护同源 `/api/*` endpoint 与 SvelteKit `__data.json` 页
 同时驱动 `hooks.server.ts` 与浏览器端 `kit.client.installBrowserTransport()`：
 
 ```yml
+server:
+  host: 127.0.0.1
+  port: 3000
+
 transport:
   keyExchangePath: /api/_hai/key-exchange
   requireEncryption: true
@@ -150,7 +154,8 @@ import rawKitConfig from '../config/_kit.yml?raw'
 export const appKitConfig = resolveKitConfig(parse(rawKitConfig) ?? {})
 ```
 
-`_kit.yml` 只放公开的 transport 路径/开关，不放密钥；如自定义 `keyExchangePath`，浏览器端必须同步映射为 `keyExchangeUrl`。
+`resolveKitConfig()` 同时解析 `server`（host/port）与 `transport`；host/port 优先级为 `HOST` / `PORT` 环境变量 > `_kit.yml` 的 `server` > 默认 `127.0.0.1:3000`（与 `@h-ai/serv` 同构）。
+`_kit.yml` 只放公开的 server/transport 路径/开关，不放密钥；如自定义 `keyExchangePath`，浏览器端必须同步映射为 `keyExchangeUrl`。
 
 ## 核心 API
 

package/templates/skills/hai-reldb/SKILL.md

@@ -307,7 +307,7 @@ class UserRepository extends BaseReldbCrudRepository<User> {
 **自动能力**：
 
 - `createdAt` / `updatedAt` 字段自动填充时间戳
-- 主键生成（非 autoIncrement 主键默认使用 `crypto.randomUUID()`）
+- 主键生成（非 autoIncrement 主键默认使用随机 UUID，底层带安全上下文守卫，不可用时回退；业务侧手动生成 UUID 一律用 `core.id.uuid()`）
 - BOOLEAN → 1/0（SQLite/MySQL）或 true/false（PostgreSQL）
 - TIMESTAMP → 毫秒时间戳（SQLite）或 Date（PG/MySQL）
 - JSON → 字符串序列化（SQLite/MySQL）或原生 JSONB（PG）

package/templates/skills/hai-serv/SKILL.md

@@ -86,8 +86,11 @@ const app = serv.createApp({
   },
 })
 
-// Node.js 启动（自动读取 PORT / HOST 环境变量；onClose 自动监听 SIGINT/SIGTERM）
+// Node.js 启动（host/port 来自 _serv.yml 的 server；HOST/PORT 环境变量高于配置文件；onClose 自动监听 SIGINT/SIGTERM）
+const { server } = core.config.getOrThrow<ServConfig>('serv')
 serv.listen(app, {
+  host: server.host,
+  port: server.port,
   onListening: info => logger.info('API service listening', { port: info.port }),
   onClose: closeApp, // 业务模块关闭函数（ai/storage/iam/reldb 等反向释放）
 })
@@ -265,6 +268,10 @@ const app = serv.createApp({
 
 ```yaml
 # config/_serv.yml
+server:
+  host: 127.0.0.1
+  port: 3000
+
 http:
   apiPrefix: /api/v1
   openapi: