@h-ai/cli 0.1.0-alpha.12 → 0.1.0-alpha.15

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

@@ -1,6 +1,6 @@
 ---
 name: hai-crypto
-description: 使用 @h-ai/crypto 进行加密（非对称/哈希/对称）与密码哈希；当需求涉及加密、解密、签名、验签、哈希、密码存储或密钥管理时使用。
+description: 使用 @h-ai/crypto 进行加密（非对称/哈希/对称）、密码哈希与传输加密；当需求涉及加密、解密、签名、验签、哈希、密码存储、密钥管理或 crypto.transport 时使用。
 ---
 
 # hai-crypto
@@ -19,6 +19,7 @@ description: 使用 @h-ai/crypto 进行加密（非对称/哈希/对称）与密
 | `crypto.hash` 哈希 | ✅ | ✅ | SM3 哈希、HMAC |
 | `crypto.symmetric` 对称加密 | ✅ | ✅ | SM4 ECB/CBC |
 | `crypto.password` 密码哈希 | ✅ | ❌ | 依赖 Node.js crypto（服务端专用） |
+| `crypto.transport` 传输加密 | ✅ | ✅ | 服务端管理器 + 客户端 encryptedFetch |
 
 浏览器端主要用于 kit 传输加密场景（`kit.client.create({ transport: { crypto } })`），一般不需要直接调用 crypto API。
 
@@ -30,6 +31,7 @@ description: 使用 @h-ai/crypto 进行加密（非对称/哈希/对称）与密
 - 哈希计算与 HMAC
 - 对称加密/解密（ECB/CBC 模式）
 - 密码存储与验证（加盐迭代哈希）
+- 传输加密：为 serv / kit / api-client 提供统一协议、密钥协商和请求响应加解密
 
 ---
 
@@ -139,6 +141,44 @@ if (hashed.success) {
 哈希格式：`$hai$<iterations>$<salt>$<hash>`
 **PasswordConfig**：`{ saltLength?: number, iterations?: number }`
 
+### 传输加密 — `crypto.transport`
+
+所有传输加密工厂必须从 `crypto.transport` 访问，不从子目录导入内部工厂。
+
+| 方法 | 签名 | 说明 |
+| --- | --- | --- |
+| `createServer` | `(options?) => HaiResult<TransportEncryptionManager>` | 创建服务端传输加密管理器 |
+| `createClient` | `({ keyExchangeUrl, fetch? }) => TransportClient` | 创建客户端 encryptedFetch 会话 |
+| `protocol` | `TRANSPORT_PROTOCOL` | 协议常量：`X-Client-Id`、`X-Encrypted`、默认协商路径 |
+
+```typescript
+const server = crypto.transport.createServer({ maxClients: 10000 })
+if (!server.success)
+  return server
+
+const client = crypto.transport.createClient({
+  keyExchangeUrl: 'https://api.example.com/api/v1/_hai/key-exchange',
+})
+
+const resp = await client.encryptedFetch('https://api.example.com/api/v1/echo', {
+  method: 'POST',
+  body: JSON.stringify({ hello: 'world' }),
+})
+```
+
+使用流程：
+1. 先 `await crypto.init()`。
+2. 服务端 `createServer()` 后暴露一个 POST 密钥协商端点：接收 `clientPublicKey`，返回 `serverPublicKey + clientId`。
+3. 客户端 `createClient({ keyExchangeUrl })` 后，首次 `init()` / `encryptedFetch()` 会自动做密钥协商。
+4. 协商完成后，请求附带 `X-Client-Id`；若请求有 body，则自动包装成 `{ encryptedKey, ciphertext, iv }`。
+5. 服务端先 `decryptRequest()`，业务处理后再 `encryptResponse(clientId, data)`。
+6. 客户端收到 `X-Encrypted: true` 的响应后自动解密；`destroy()` 可清空当前会话。
+
+常规应用优先使用上层封装：
+- serv：`serv.createApp({ transport: { crypto } })`
+- kit：`kit.createHandle({ crypto: { crypto, transport: true } })` + `kit.client.create({ transport: { crypto } })`
+- api-client：`apiClient.init({ transport: { crypto } })`
+
 ---
 
 ## 错误码 — `HaiCryptoError`
@@ -196,3 +236,4 @@ if (verifyResult.success && verifyResult.data) {
 - `hai-core`：配置与 HaiResult 模型
 - `hai-iam`：密码哈希（内部自动调用 crypto.password）
 - `hai-kit`：SvelteKit 集成（传输加密）
+- `hai-serv` / `hai-api-client`：跨域 HTTP API 的透明传输加密

package/templates/skills/hai-framework-sync/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: hai-framework-sync
+description: 管理 hai-framework 与应用仓库之间的依赖、技能模板、Copilot/AGENTS 指令和本地联调同步；当需求涉及 hai-framework 源头修改、skills 同步、framework:use:local、framework:watch、版本漂移或双仓 PR 时使用。
+---
+
+# hai-framework-sync — hai-framework 与应用仓库同步规范
+
+> hai-framework 是能力与 skill 模板源头；应用仓库消费这些能力，并可以有少量项目本地覆盖。同步的目标是减少漂移，而不是把两个仓库混成一个仓库。
+
+---
+
+## 适用场景
+
+- 修改 `.agents/skills/**`，且内容应成为所有 hai-framework 应用通用规范
+- 修改 `packages/cli/templates/skills/**`
+- 调整 `AGENTS.md`、`CLAUDE.md`、`opencode.json`、Copilot 指令模板
+- 使用 `framework:use:local` / `framework:watch` 联调本地 hai-framework
+- 排查应用仓库与 hai-framework npm 版本不一致
+- 规划双仓 PR 或同步发布
+
+---
+
+## 同步原则
+
+1. **通用规范先改 hai-framework**：可复用的 skill、模板、AI 工作流从 `packages/cli/templates/skills/` 起源。
+2. **应用仓库只保留项目差异**：业务上下文、项目私有路径、产品决策可以留在应用仓库。
+3. **默认 CI 使用 npm 依赖**：确保 PR 能代表真实安装环境；本地路径联调必须显式开启。
+4. **双仓改动要成套**：framework 模板、应用本地 `.agents/skills`、AGENTS/Copilot 路由同时更新。
+5. **不复制敏感聊天记录**：只同步脱敏后的团队规则和流程。
+
+---
+
+## 标准同步流程
+
+### 1. 判断来源
+
+| 变更类型 | 首选位置 |
+| --- | --- |
+| 通用 hai 模块用法 | `hai-framework/packages/cli/templates/skills/hai-*/SKILL.md` |
+| 通用 CI/PR/Issue/AI 协作流程 | `hai-framework/packages/cli/templates/skills/` |
+| 应用私有业务规则 | 应用仓库 `AGENTS.md` 或本地 skill |
+| Copilot/Claude/OpenCode 入口模板 | hai-framework 模板 + 应用仓库入口文件 |
+
+### 2. 修改源头
+
+先在 hai-framework 模板中修改或新增 skill。
+
+### 3. 同步到应用仓库
+
+把源头 skill 复制到应用仓库 `.agents/skills/<skill>/SKILL.md`，并同步入口引用：
+
+- `AGENTS.md`
+- `.github/copilot-instructions.md`
+- `CLAUDE.md`（如存在）
+- `opencode.json`（如结构变化）
+
+### 4. 验证
+
+按变更类型选择验证方式：
+
+- 仅模板 / skill 变更：检查 diff、入口引用与模板泛化程度。
+- 同步到应用仓库：按 `hai-ci` 定义的质量门禁运行。
+- 涉及 framework runtime 时，再选择：
+
+```bash
+pnpm framework:status
+pnpm framework:use:local <package>
+pnpm framework:watch <package>
+```
+
+---
+
+## 漂移检查清单
+
+- [ ] framework 模板和应用 `.agents/skills` 对同名 skill 内容一致，除非 PR 明确说明本地覆盖
+- [ ] `AGENTS.md` 的 skill 列表包含新增/重命名 skill
+- [ ] Copilot/Claude/OpenCode 入口能找到新增 skill
+- [ ] CI 默认不依赖 `/home/.../hai-framework` 本地路径
+- [ ] 本地联调结束后可恢复 npm 模式
+- [ ] README 或 PR 描述说明双仓改动顺序
+
+---
+
+## 禁止事项
+
+- ❌ 只改应用 `.agents/skills`，忘记更新 hai-framework 模板中的通用规范
+- ❌ 在 CI 默认路径中依赖本机绝对路径
+- ❌ 把 unpublished framework 行为当成已发布 npm 行为
+- ❌ 把聊天记录原文、token、私有 URL 写入模板
+- ❌ 双仓 PR 没有关联 issue 或同步说明
+
+---
+
+## 相关 Skills
+
+- `hai-ci` — CI 对 npm/local framework 模式的验证策略
+- `hai-pr-review` — 双仓 PR 审查要点
+- `hai-build` — 应用开发入口

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

@@ -1,6 +1,6 @@
 ---
 name: hai-iam
-description: 使用 @h-ai/iam 进行身份认证（密码/OTP/LDAP/API Key）、统一 Bearer Token 管理（TokenPair/refresh/revoke）与 RBAC 授权（角色/权限/通配符）；当需求涉及登录、注册、权限检查、角色管理、Token 认证或 API 契约时使用。
+description: 使用 @h-ai/iam 进行身份认证（密码/OTP/LDAP/API Key）、统一 Bearer Token 管理（TokenPair/refresh/revoke）与 RBAC 授权；当需求涉及登录、注册、权限检查、角色管理、Token 认证或通过 @h-ai/api-contract 暴露 IAM API 时使用。
 ---
 
 # hai-iam
@@ -11,7 +11,7 @@ description: 使用 @h-ai/iam 进行身份认证（密码/OTP/LDAP/API Key）、
 
 ## 运行环境
 
-> ⚠️ **服务端模块（Node.js only）。** 浏览器端通过 `api.call(iamEndpoints.xxx)` 或 `apiFetch` 调用 IAM API 端点（参见 hai-api-client / hai-kit SKILL）。`@h-ai/iam/api` 子路径导出的 Zod Schema 和 EndpointDef 可在浏览器端使用。
+> ⚠️ **服务端模块（Node.js only）。** 浏览器端通过 `@h-ai/api-client` 的 typed client 调用 IAM API，例如 `apiClient.iam.auth.login()`。HTTP 契约统一来自 `@h-ai/api-contract`。
 
 ---
 
@@ -33,7 +33,7 @@ description: 使用 @h-ai/iam 进行身份认证（密码/OTP/LDAP/API Key）、
 - API Key 管理（创建、吊销、验证）
 - 密码重置流程
 - 与 kit 集成的认证守卫
-- API 契约定义（`@h-ai/iam/api`）
+- 通过 `@h-ai/api-contract` 暴露 IAM HTTP contract
 
 ---
 
@@ -204,34 +204,14 @@ interface TokenPair {
 
 ---
 
-## API 契约 — `@h-ai/iam/api`
+## HTTP API 契约
 
-```typescript
-import { iamEndpoints } from '@h-ai/iam/api'
-
-// 9 个端点契约，含 Zod schema
-iamEndpoints.login // POST /api/v1/auth/login
-iamEndpoints.loginWithOtp // POST /api/v1/auth/login-otp
-iamEndpoints.sendOtp // POST /api/v1/auth/send-otp
-iamEndpoints.logout // POST /api/v1/auth/logout
-iamEndpoints.register // POST /api/v1/auth/register
-iamEndpoints.currentUser // GET  /api/v1/auth/me
-iamEndpoints.refreshToken // POST /api/v1/auth/refresh
-iamEndpoints.changePassword // POST /api/v1/auth/change-password
-iamEndpoints.resetPassword // POST /api/v1/auth/reset-password
-```
-
-服务端使用 `kit.fromContract()`，客户端使用 `api.call()`：
+IAM HTTP API 统一由 `@h-ai/api-contract` 的 `apiContract.iam` 定义，由 `@h-ai/serv/features/iam` 绑定到本模块。
 
 ```typescript
-// 服务端
-export const POST = kit.fromContract(iamEndpoints.login, async (input) => {
-  const result = await iam.auth.login(input)
-  return result.success ? kit.response.ok(result.data) : kit.response.unauthorized()
-})
+import { apiClient } from '@h-ai/api-client'
 
-// 客户端
-const result = await api.call(iamEndpoints.login, { username, password })
+const result = await apiClient.iam.auth.login({ identifier: username, password })
 ```
 
 ---
@@ -322,23 +302,21 @@ export const handle = kit.sequence(haiHandle)
 ### 客户端认证流程
 
 ```typescript
-import { iamEndpoints } from '@h-ai/iam/api'
-
 // 登录 → 保存 Token
-const login = await api.call(iamEndpoints.login, { username, password })
+const login = await apiClient.iam.auth.login({ identifier: username, password })
 if (login.success) {
-  await api.auth.setTokens(login.data.tokens)
+  await apiClient.auth.setTokens(login.data.tokens)
 }
 
 // 获取当前用户
-const me = await api.call(iamEndpoints.currentUser, {})
+const me = await apiClient.iam.auth.currentUser()
 
-// Token 过期时，api-client 自动调用 refreshUrl 刷新
+// Token 过期时，api-client 自动调用 refreshPath 刷新
 // 刷新失败时，清除 Token 并跳转登录页
 
 // 登出
-await api.call(iamEndpoints.logout, {})
-await api.auth.clear()
+await apiClient.iam.auth.logout({})
+await apiClient.auth.clear()
 ```
 
 ### 自动会话失效