@tier0/sdk-v2 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tier0/sdk-v2",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Tier0 Cloud new-architecture SDK for TypeScript and JavaScript",
   "license": "MIT",
   "type": "module",
@@ -156,7 +156,7 @@
   "scripts": {
     "sync:contracts": "node scripts/sync-contracts.mjs",
     "generate": "node scripts/generate-openapi.mjs && node scripts/generate-uns-v2.mjs",
-    "check:contracts": "node scripts/check-contracts.mjs && node --test scripts/retired-stream-probe.test.mjs && node scripts/generate-openapi.mjs --check && node scripts/generate-uns-v2.mjs --check",
+    "check:contracts": "node scripts/check-contracts.mjs && node --test scripts/retired-stream-probe.test.mjs scripts/retired-http-push.test.mjs scripts/sync-contracts.test.mjs && node scripts/generate-openapi.mjs --check && node scripts/generate-uns-v2.mjs --check",
     "check:skills": "node scripts/check-skills.mjs && node scripts/check-skill-examples.mjs",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
     "build": "node scripts/build.mjs",

package/skills/tier0-sdk-v2/tier0-sdk-v2-source/SKILL.md

@@ -23,10 +23,10 @@ Source 维护连接配置、认证引用与源状态。脚本处理用 [Stream](
 
 ## 核心约束
 
-1. Source 配置统一使用 documents.*，原生文档为 `{name,protocol,config}`。http 原生协议与 http-api adapter 不可互换。
+1. Source 配置统一使用 documents.*，原生文档为 `{name,protocol,config}`，HTTP API 显式指定 `config.role`。HTTP 统一为 `protocol: http-api` + `config.role: client/server`；Client 主动请求，Server 接收入站请求，不能互换。HTTPServer 统一接收入站请求，固定前缀后的路由和响应时机属于 Stream；旧 http_push 不再用于新建。
 2. 已有 ID 和 revision 时优先用 documents.update 的 patch，避免额外 get；完整替换 document 前读取完整文档，安全列表摘要不能无损回写。原生 ID 是十进制字符串，revision 原样传递，不转 Number。
 3. 现有 Source 修改、启停、删除都要 expectedRevision。没有任何 Stream 引用时可直接提交；有草稿、活动、历史或不可见引用时仍需 confirmedImpactRevision。先形成精确意图，再读取全部影响分页；回执不可合成、跨意图复用或静默刷新。提供的回执始终严格校验，不自动获取并同意影响。
-4. 配置中保留认证/TLS 引用，不写明文秘密；HTTP 新凭据走创建专用 credentials。
+4. 配置中保留认证/TLS 引用，不写明文秘密；HTTP Client 新凭据走创建专用 credentials；Server 不携带 Client auth/TLS 配置。
 5. desiredState 不代表实际健康，保存配置不代表 Stream 已切换至新 configRevision。运行状态另行读取。
 
 ## 返回值与异常

package/skills/tier0-sdk-v2/tier0-sdk-v2-source/references/create.md

@@ -6,15 +6,16 @@
 | --- | --- | --- | --- |
 | dryRun | boolean | 是 | true 校验；false 保存 |
 | document.name | string | 是 | 1–128 字符 |
-| document.protocol | string | 是 | 原生协议，如 http、mqtt、modbus |
-| document.config | object | 是 | configVersion=2、endpoint、options；见[协议配置](protocols.md) |
+| document.protocol | string | 是 | 原生协议，如 http-api、mqtt、modbus |
+| document.config.role | client / server | HTTP API 显式指定 | client 主动请求；server 接收入站请求 |
+| document.config | object | 是 | endpoint、options；见[协议配置](protocols.md) |
 | document.description | string | 否 | 最多 512 字符 |
-| credentials | object | 否 | 仅创建时提供新 HTTP 凭据，与已有 auth/TLS 引用互斥 |
+| credentials | object | 否 | 仅创建 HTTP Client 时提供新凭据，与已有 auth/TLS 引用互斥 |
 | idempotencyKey | string | 否 | 建议提供，最多 128 字符，同一业务意图保持不变 |
 
-## 完整示例：HTTP 数据源
+## 完整示例：HTTP Client 数据源
 
-传入实际端点、名称和意图键。此函数创建配置，不启用源。client 从服务端环境读取 API Host/Key，也可显式注入。
+传入实际端点、名称和意图键。此函数创建 `http-api` + `config.role: client` 配置，不启用源。client 从服务端环境读取 API Host/Key，也可显式注入。
 
 ```ts
 import { createClient, type Tier0Client, type CloudSourceDocument } from '@tier0/sdk-v2';
@@ -23,8 +24,8 @@ export async function createHttpSource(
   endpoint: string, name: string, intentKey: string, client: Tier0Client = createClient(),
 ) {
   const document: CloudSourceDocument = {
-    name, protocol: 'http', description: '订单系统 HTTP 接入',
-    config: { configVersion: 2, endpoint, options: {} },
+    name, protocol: 'http-api', description: '订单系统 HTTP 接入',
+    config: { role: 'client', endpoint, options: {} },
   };
   const saved = await client.source.documents.create({
     dryRun: false, document, idempotencyKey: intentKey,
@@ -36,7 +37,9 @@ export async function createHttpSource(
 
 一次提交即可返回完整 data：id、revision、document、desiredState、runtimeState、health、createdAt、updatedAt，无需另行 get。需要单独预检时可先传 `dryRun: true`，返回 `{ validated: true, sideEffects: false }`，没有 ID。预检不保留提交条件；实际保存仍会校验。ID 原样保留十进制字符串。
 
-## HTTP Bearer 凭据
+HTTP Server 同样使用 `protocol: http-api`，角色为 `config.role: server`；其配置以 `source.protocols.list({})` 返回的正式合同为准，不能复用下方 Client 的主动请求示例。入站业务统一绑定 HTTPServer Source，路由和响应时机在 Stream 定义；202 状态不能据此报告 Stream 执行完成。
+
+## HTTP Client Bearer 凭据
 
 token 从服务端密钥提供者取得，不写入脚本、文档、日志或仓库。
 
@@ -49,7 +52,7 @@ export async function createAuthenticatedHttpSource(
 ) {
   const saved = await client.source.documents.create({
     dryRun: false, idempotencyKey: intentKey,
-    document: { name, protocol: 'http', config: { configVersion: 2, endpoint, options: {} } },
+    document: { name, protocol: 'http-api', config: { role: 'client', endpoint, options: {} } },
     credentials: { method: 'GET', kind: 'bearer', material: { token } },
   });
   if (!('id' in saved.data)) throw new Error('未返回 Source ID');
@@ -58,3 +61,58 @@ export async function createAuthenticatedHttpSource(
 ```
 
 配置保存不代表连接健康；见[查询](read.md)。仅在任务包含启用时执行[启停](state.md)。结果未知时保留原请求、requestId、意图键，先核对列表/历史，不自动重复创建。
+
+## HTTP Server：管理配置
+
+正式协议目录规定 Server 的 `config.endpoint` 为 `http://managed`、`options` 为 `{}`，不携带 Client 的 `auth` / `tls` 或创建专用 `credentials`。该函数只保存 Source，不启用、不创建 Stream，也不发起入站请求。
+
+```ts
+import { createClient, type Tier0Client, type CloudSourceDocument } from '@tier0/sdk-v2';
+
+export async function createHttpServerSource(
+  name: string, intentKey: string, client: Tier0Client = createClient(),
+) {
+  const document: CloudSourceDocument = {
+    name, protocol: 'http-api',
+    config: { role: 'server', endpoint: 'http://managed', options: {} },
+  };
+  const saved = await client.source.documents.create({
+    dryRun: false, document, idempotencyKey: intentKey,
+  });
+  if (!('id' in saved.data)) throw new Error('未返回已保存的 Source');
+  return { receipt: saved, current: saved.data };
+}
+```
+
+Server 的固定前缀 `/ingest/v1/{workspaceId}/{sourceId}` 和 Bearer 要求由协议目录的 `x-tier0-http-in` 描述。Source 不接受业务路径配置；在 [Stream HTTPServer 示例](../../tier0-sdk-v2-stream/references/http-server.md)中注册 `onRequest` 的 method/path。响应时机属于 Stream。
+
+## 四类 inline 认证与 REQUEST 绑定
+
+单条创建可通过 `credentials` 提供以下只写材料；与已有 auth/TLS 引用互斥，并要求本次创建的 `idempotencyKey`。材料从调用方已授权的密钥提供者注入，不在示例中读取文件或环境中的秘密，不记录或返回材料。
+
+| kind | material | method |
+| --- | --- | --- |
+| basic | username、password | 省略时 REQUEST；可显式绑定受限 HTTP 方法 |
+| bearer | token | 省略时 REQUEST；上方 GET 示例保持明确的方法限制 |
+| apiKey | headerName、value | 省略或 REQUEST；不接受旧 name/key 形态 |
+| oauth2ClientCredentials | tokenUrl、clientId、clientSecret；可选 scope、clientAuthentication | 省略、REQUEST 或 GET |
+
+OAuth 的 `clientAuthentication` 支持 `client_secret_post`（默认）和 `client_secret_basic`。REQUEST 表示绑定 Source 基址，实际路径和方法仍由执行宿主逐次授权；显式方法的已有绑定不能解释成 REQUEST 的基址范围。vendor SESSION 合同独立保留，不是此 inline 创建的 method，也不新增独立公开凭据 API。
+
+```ts
+import { createClient, type Tier0Client, type CloudSourceCreateCredentials } from '@tier0/sdk-v2';
+
+export async function createHttpSourceWithCredentials(
+  endpoint: string, name: string, credentials: CloudSourceCreateCredentials, intentKey: string,
+  client: Tier0Client = createClient(),
+) {
+  const saved = await client.source.documents.create({
+    dryRun: false, idempotencyKey: intentKey,
+    document: { name, protocol: 'http-api',
+      config: { role: 'client', endpoint, options: {} } },
+    credentials,
+  });
+  if (!('id' in saved.data)) throw new Error('未返回已保存的 Source');
+  return { receipt: saved, current: saved.data };
+}
+```

package/skills/tier0-sdk-v2/tier0-sdk-v2-source/references/protocols.md

@@ -1,10 +1,10 @@
 # 协议与连接配置
 
-先调用 `source.protocols.list({})`。协议枚举存在不等于目标环境驱动或凭据解析器已就绪。原生 `protocol: 'http'` 与通用投影 `adapter: 'http-api'` 不可混用。
+先调用 `source.protocols.list({})`。协议枚举存在不等于目标环境驱动或凭据解析器已就绪。HTTP Source 统一使用 `protocol: 'http-api'`，通过文档的 `config.role: 'client' | 'server'` 区分主动请求和入站服务，与 Enterprise 的一协议两角色模型一致。角色和协议能力以目标环境目录为准；旧 `http` 不作为新建示例。
 
 | 配置字段 | 类型 | 必填 | 说明 |
 | --- | --- | --- | --- |
-| configVersion | 2 | 是 | 新架构配置快照 |
+| role | client / server | HTTP 示例显式指定 | 省略时为 client；Server 使用托管地址和空 options |
 | endpoint | string | 是 | 地址，不内嵌凭据 |
 | options | object | 是 | 协议专用选项 |
 | auth.kind | string | 有认证时 | basic/bearer/apiKey/usernamePassword/oauth2ClientCredentials |
@@ -19,18 +19,24 @@ import { createClient, type CloudSourceDocument } from '@tier0/sdk-v2';
 export async function inspectProtocolExamples() {
   const capabilities = await createClient().source.protocols.list({});
   const examples: CloudSourceDocument[] = [
-    { name: 'orders-http', protocol: 'http',
-      config: { configVersion: 2, endpoint: 'https://orders.example.com', options: {} } },
+    { name: 'orders-http', protocol: 'http-api',
+      config: { role: 'client', endpoint: 'https://orders.example.com', options: {} } },
     { name: 'line-plc', protocol: 'modbus',
-      config: { configVersion: 2, endpoint: 'tcp://plc.example.com:502', options: { unitId: 1 } } },
+      config: { endpoint: 'tcp://plc.example.com:502', options: { unitId: 1 } } },
     { name: 'line-mqtt', protocol: 'mqtt',
-      config: { configVersion: 2, endpoint: 'mqtt://broker.example.com:1883',
+      config: { endpoint: 'mqtt://broker.example.com:1883',
         options: { clientId: 'tier0-line-reader', subscriptions: { 'factory/line1/status': 1 } } } },
   ];
   return { capabilities: capabilities.data, examples };
 }
 ```
 
-HTTP 公开 headers 只允许 Accept/Content-Type，不能塞 Authorization/Cookie。Modbus 寄存器范围和轮询频率在 Stream acquisition 中定义；MQTT QoS 为 0/1/2。认证创建见[创建](create.md)，修改时保留原 auth/tls 引用。
+HTTP Client 的 options 支持 headers 和 parameters；headers 可包含目录允许的非秘密自定义头，Accept/Content-Type 保留 MIME 校验，认证及传输头保留给服务端，不能塞 Authorization/Cookie。Modbus 寄存器范围和轮询频率在 Stream acquisition 中定义；MQTT QoS 为 0/1/2。认证创建见[创建](create.md)，修改时保留原 auth/tls 引用。
 
 SQL options 包含 tlsMode（verify-full/disable）和 queries（资源名→固定 SQL）；脚本不能替换任意 SQL。OPC UA、SAP、Teamcenter 等按能力和服务端校验配置，不从 HTTP 模板生造字段。不要为通过校验自动移除认证或关闭 TLS。
+
+HTTP Client 示例不能用于 Server。HTTPServer 通过 `source.documents.*` 配置监听源，固定前缀为 `/ingest/v1/{workspaceId}/{sourceId}`；Stream 注册相对业务路由和处理函数，见 [HTTPServer Stream](../../tier0-sdk-v2-stream/references/http-server.md)。旧 `http_push` 不再作为独立模式创建；响应时机在 Stream 层处理。
+
+Cloud 的角色位于 `config.role`；Enterprise 投影的顶层 `role` 不能直接抄入 Cloud 管理文档。Server 配置见[创建](create.md)，以 `http://managed` 和空 options 保存，不从 Client 模板推导。
+
+HTTP Client 的单条 inline 认证支持 basic / bearer / apiKey / oauth2ClientCredentials，method 省略时由服务端按 REQUEST 绑定 Source 基址；显式方法限制保持不变。APIKey 材料为 headerName/value，OAuth 可提供 clientAuthentication。见[创建](create.md)。

package/skills/tier0-sdk-v2/tier0-sdk-v2-source/references/read.md

@@ -7,7 +7,7 @@
 | source.runtime.get | /openapi/v2/uns/sources/runtime/get | id（必填） | 运行状态 |
 | source.observations.get | /openapi/v2/uns/sources/observations/get | items：id、expectedRevision | 指定源和修订的观测 |
 
-page 从 1 开始，size 1–200。列表默认安全摘要。get 省略 view 保持旧的 full 行为；summary 需要 uns.source.view 或 uns.source.manage，full 需要 uns.source.manage；API Key 读取完整文档还必须是 full_access（includeDocument:true 同样适用）。未知 revision 时可读取 summary；要完整替换 document 或查看配置时读取 full。已持有写回执中的 ID/revision 时，可直接提交 patch，无需为了编辑再 get；服务端仍会检查版本冲突。摘要不能用于重建完整配置。
+page 从 1 开始，size 1–200。列表默认安全摘要。get 省略 view 保持旧的 full 行为；summary 需要 uns.source.view 或 uns.source.manage，full 需要 uns.source.manage；API Key 读取完整文档还必须是 full_access（includeDocument:true 同样适用）。未知 revision 时可读取 summary；要完整替换 document 或查看配置时读取 full。已持有写回执中的 ID/revision 时，可直接提交 patch，无需为了编辑再 get；服务端仍会检查版本冲突。摘要不能用于重建完整配置。 对已知旧版配置，安全读取投影可能移除退休的 configVersion 标记；这不代表历史已经迁移或可以运行。写入仍使用当前无版本配置，不向请求补回旧标记或协议别名。
 
 ```ts
 import { createClient, type Tier0Client } from '@tier0/sdk-v2';

package/skills/tier0-sdk-v2/tier0-sdk-v2-stream/SKILL.md

@@ -11,7 +11,8 @@ description: 使用 @tier0/sdk-v2 的 client.stream 创建、查询、修改和
 
 | 用户任务 | 参考 | 方法 |
 | --- | --- | --- |
-| 新建并绑定 HTTP Source | [创建](references/create.md) | documents.create({program}) |
+| 新建并绑定 HTTP Client Source | [创建](references/create.md) | documents.create({program}) |
+| HTTPServer 固定前缀与业务路由 | [HTTPServer](references/http-server.md) | documents.create({document})、api.stream.onRequest、ctx.reply |
 | 列表、完整文档、运行记录 | [查询](references/read.md) | programs.list、documents.get、observations.get、runs.list |
 | 修改草稿、脚本和绑定 | [修改](references/update.md) | documents.validate/update |
 | 发布、停用、版本回滚 | [部署](references/deploy.md) | programs.deploy/rollback、documents.disable |
@@ -22,10 +23,10 @@ description: 使用 @tier0/sdk-v2 的 client.stream 创建、查询、修改和
 
 | 形态 | 完整输入 | 适用入口 |
 | --- | --- | --- |
-| Runtime program | name、sdkVersion、script 字符串、sourceBindings、timeoutMs | documents.create/update/validate({program}) |
+| Runtime program | name、script 字符串、sourceBindings、timeoutMs | documents.create/update/validate({program}) |
 | 云端原生文档 | name、model、script 对象、sources、entries | documents.create/get/update/validate |
 
-程序必须是完整 `module.exports = api => { ... }`，执行器 API 是 api.sources/api.uns/api.stream，与 npm 包的 client.source 不同。Runtime sourceBindings 为 sourceId/configRevision/acquisition；原生 sources 还使用 alias/resources。连接凭据不进脚本或 acquisition。
+程序必须是完整 `module.exports = api => { ... }`，执行器 API 是 api.sources/api.uns/api.stream，与 npm 包的 client.source 不同。Runtime sourceBindings 为 sourceId/configRevision/acquisition；原生 sources 还使用 alias/resources。连接凭据不进脚本或 acquisition，秘密材料由 Source 执行宿主管理，不通过脚本读取、记录或返回。定时入口使用 api.stream.every，不传播旧注册别名；npm 的 client.controls 管理入口不作为 Goja 的 Stream 注册参数。
 
 ## 核心约束
 
@@ -34,7 +35,8 @@ description: 使用 @tier0/sdk-v2 的 client.stream 创建、查询、修改和
 3. 所有更新/部署/删除携带当前 expectedRevision。原生停用另需 expectedActiveRelease，避免停掉他人刚发布的版本。
 4. versionId 从 versions.list 取得，不把 release 序号当 ID。expectedSourceRevision 仅用于恰好一个依赖源，不代表多个源的修订。
 5. resources=[] 是空冻结资源集，不是通配符。写入本身由服务端校验，需要预览时单独 validate；当前云端程序 timeoutMs 上限 30000。旧 runtime.capabilities 查询已退役，不作为管理或执行前置检查，不为此增加 Control scope 或逐 Key 控制码授权。
-6. 仅执行用户要求的生命周期步骤；修改脚本不自动授予发布、停用或删除权限。
+6. HTTPServer 响应时机在 Stream：普通返回等处理/提交完成；HTTP onRequest 内 await ctx.reply 可先回复一次再继续，仍受超时/并发/权限约束，断线不取消但 shutdown 可取消，不保证崩溃重放。
+7. 仅执行用户要求的生命周期步骤；修改脚本不自动授予发布、停用或删除权限。
 
 ## 成功与异常
 

package/skills/tier0-sdk-v2/tier0-sdk-v2-stream/references/create.md

@@ -6,15 +6,14 @@
 | --- | --- | --- | --- |
 | dryRun | boolean | 是 | true 预检，false 保存草稿 |
 | program.name | string | 是 | 1–63 字符 |
-| program.sdkVersion | tier0-stream/v2 | 是 | 运行时脚本版本 |
 | program.script | string | 是 | 完整 module.exports 程序 |
 | program.timeoutMs | integer | 否 | 当前云端上限 30000 ms |
 | program.sourceBindings | array | 否 | sourceId、configRevision、acquisition |
 | idempotencyKey | string | 否 | 最多 128 字符，本次创建的固定意图键 |
 
-## HTTP Source 绑定示例
+## HTTP Client Source 绑定示例
 
-先按[Source 查询](../../tier0-sdk-v2-source/references/read.md)选定真实 HTTP Source。脚本的 api.sources 属于平台执行器，与应用中的 client.source 不同。sourceId 保持字符串，configRevision 从完整源读取。
+先按[Source 查询](../../tier0-sdk-v2-source/references/read.md)选定真实 HTTP Client Source。脚本的 api.sources 属于平台执行器，与应用中的 client.source 不同。sourceId 保持字符串，configRevision 从完整源读取。省略 `config.role` 时按正式协议目录默认为 client；Server 走入站语义，不能创建为主动请求程序。
 
 ```ts
 import { createClient, type Tier0Client, type RuntimeStreamDefinition } from '@tier0/sdk-v2';
@@ -25,14 +24,17 @@ export async function createHttpStream(
   if (!/^[1-9][0-9]*$/.test(sourceId)) throw new Error('Source ID 必须是正十进制字符串');
   const source = await client.source.documents.get({ id: sourceId, view: 'full' });
   if (!('document' in source.data)) throw new Error('需要完整 Source 文档');
-  if (source.data.document.protocol !== 'http') throw new Error('此示例需要 HTTP Source');
+  if (source.data.document.protocol !== 'http-api' || 'sourceType' in source.data.document.config ||
+      (source.data.document.config.role ?? 'client') !== 'client') {
+    throw new Error('此主动请求示例需要 HTTP API Client Source');
+  }
   const document: RuntimeStreamDefinition = {
-    name, sdkVersion: 'tier0-stream/v2', timeoutMs: 5000,
+    name, timeoutMs: 5000,
     sourceBindings: [{ sourceId, configRevision: source.data.revision, acquisition: {} }],
     script: [
       'module.exports = api => {',
       '  const upstream = api.sources.use({ id: ' + JSON.stringify(sourceId) + ', resources: [] });',
-      '  api.stream.onTimer({ id: "tick", intervalMs: 60000 }, async () => {',
+      '  api.stream.every({ id: "tick", intervalMs: 60000 }, async () => {',
       '    const response = await upstream.request({ method: "GET", path: "orders" });',
       '    return response.data;',
       '  });',
@@ -53,4 +55,4 @@ export async function createHttpStream(
 
 programs.create 已退役，创建统一使用 documents.create。历史创建结局未知时先按已知 ID 或业务标识核对状态，不能将旧请求或幂等键改投 documents.create 重做。
 
-原生编辑器形态 `documents.create({dryRun, document})` 的 document 为 name/model/script对象/sources/entries，script 为 `{sdkVersion,code,timeoutMs}`，sources 用 alias/sourceId/configRevision/resources/acquisition。不要把上面的 script 字符串直接塞入原生文档。
+原生编辑器形态 `documents.create({dryRun, document})` 的 document 为 name/model/script对象/sources/entries，script 为 `{code,timeoutMs}`，sources 用 alias/sourceId/configRevision/resources/acquisition。不要把上面的 script 字符串直接塞入原生文档。

package/skills/tier0-sdk-v2/tier0-sdk-v2-stream/references/http-server.md

@@ -0,0 +1,89 @@
+# HTTPServer 固定前缀与 Stream 路由
+
+先用 [Source 创建](../../tier0-sdk-v2-source/references/create.md)保存 `http-api` + `config.role: server`。Source 使用 `http://managed` 和空 options；业务路径在 Stream 注册。
+
+固定前缀为 `/ingest/v1/{workspaceId}/{sourceId}`。下例路由为 `POST /orders/:id`，完整请求路径为 `POST /ingest/v1/{workspaceId}/{sourceId}/orders/A-001`。前缀由部署环境和已认证的工作空间、Source 身份确定，不从请求 body 推断工作空间。Bearer 凭据由 Source 的既有管理合同取得并在调用时注入，不写入脚本。
+
+## 保存原生程序草稿
+
+使用完整原生 `document`：script 是 `{code,timeoutMs}`，sources 使用 alias。这与 `program` 的 script 字符串形态不同；不能把旧 Flow 脚本直接改名为新字段。
+
+```ts
+import { createClient, type Tier0Client, type CloudStreamDocument } from '@tier0/sdk-v2';
+
+/** Save an HTTPServer route draft using the existing native Stream document contract. */
+export async function createHttpServerStream(
+  sourceId: string, name: string, intentKey: string, client: Tier0Client = createClient(),
+) {
+  if (!/^[1-9][0-9]*$/.test(sourceId)) throw new Error('Source ID 必须是正十进制字符串');
+  const source = await client.source.documents.get({ id: sourceId, view: 'full' });
+  if (!('document' in source.data)) throw new Error('需要完整 Source 文档');
+  const config = source.data.document.config;
+  if (source.data.document.protocol !== 'http-api' || config.role !== 'server') {
+    throw new Error('此入站路由示例需要 HTTP API Server Source');
+  }
+  const document: CloudStreamDocument = {
+    name, model: 'program',
+    sources: [{ alias: 'incoming', sourceId, configRevision: source.data.revision, resources: [], acquisition: {} }],
+    script: { timeoutMs: 5000, code: [
+      'module.exports = api => {',
+      '  const server = api.sources.use("incoming");',
+      '  api.stream.onRequest({ id: "orders", source: server, method: "POST", path: "/orders/:id" }, ctx => {',
+      '    return { status: 200, body: { orderId: ctx.request.params.id, payload: ctx.request.body } };',
+      '  });',
+      '};',
+    ].join('\n') },
+  };
+  const saved = await client.stream.documents.create({ dryRun: false, document, idempotencyKey: intentKey });
+  if (!('id' in saved.data)) throw new Error('创建未返回已保存的草稿');
+  return { receipt: saved, current: saved.data };
+}
+```
+
+此函数只读取 Source 并保存草稿；发布按[部署](deploy.md)使用回执的 revision，只有实际发布运行后才可调用路由。示例返回请求的参数和 body，不写入 UNS。`ctx.request` 由执行宿主构造；`source` 引用限定 HTTPServer，不能换成 Client 主动请求。
+
+普通 handler 返回 `{status,headers?,body?}` 时，宿主等待处理和提交完成才发送响应。需要先回复再处理时，在 HTTP `onRequest` handler 中调用一次 `await ctx.reply({status,headers?,body?})`，随后继续执行；见下例。
+
+## 先回复，再写入集合
+
+目标环境必须部署支持 `ctx.reply` 的新 Stream 执行器。传入已有且允许当前 Stream 写入的 Collection ID；请求 body 必须符合其 Record schema。Source 仍是同一种 HTTPServer，不增加 Source 模式。
+
+```ts
+import { createClient, type Tier0Client, type CloudStreamDocument } from '@tier0/sdk-v2';
+
+/** Save an HTTPServer draft that acknowledges before its bounded Stream work. */
+export async function createHttpServerEarlyReplyStream(
+  sourceId: string, collectionId: string, name: string, intentKey: string,
+  client: Tier0Client = createClient(),
+) {
+  if (!/^[1-9][0-9]*$/.test(sourceId)) throw new Error('Source ID 必须是正十进制字符串');
+  if (!collectionId) throw new Error('需要实际 Collection ID');
+  const source = await client.source.documents.get({ id: sourceId, view: 'full' });
+  if (!('document' in source.data)) throw new Error('需要完整 Source 文档');
+  const config = source.data.document.config;
+  if (source.data.document.protocol !== 'http-api' || config.role !== 'server') {
+    throw new Error('此入站路由示例需要 HTTP API Server Source');
+  }
+  const document: CloudStreamDocument = {
+    name, model: 'program',
+    sources: [{ alias: 'incoming', sourceId, configRevision: source.data.revision, resources: [], acquisition: {} }],
+    script: { timeoutMs: 5000, code: [
+      'module.exports = api => {',
+      '  const server = api.sources.use("incoming");',
+      '  const output = api.uns.use({ collectionId: ' + JSON.stringify(collectionId) + ', access: "write" });',
+      '  api.stream.onRequest({ id: "orders", source: server, method: "POST", path: "/orders/:id" }, async ctx => {',
+      '    await ctx.reply({ status: 202, body: { accepted: true, orderId: ctx.request.params.id } });',
+      '    await output.write({ recordId: ctx.request.params.id, record: ctx.request.body });',
+      '  });',
+      '};',
+    ].join('\n') },
+  };
+  const saved = await client.stream.documents.create({ dryRun: false, document, idempotencyKey: intentKey });
+  if (!('id' in saved.data)) throw new Error('创建未返回已保存的草稿');
+  return { receipt: saved, current: saved.data };
+}
+```
+
+`ctx.reply` 只用于 HTTP `api.stream.onRequest`，一次执行只回复一次；不要在 `every`、Control 或普通事件 handler 中调用，也不增加 npm App API 或公开 HTTP endpoint。示例先发 202 再写 Record，202 表示已回复接受，不能报告写入或提交成功；失败通过 Stream 运行记录检查，不能再发送第二份响应。
+
+回复后的处理仍受 Stream timeout（本例 5000 ms）、并发上限和实时权限约束。客户端断线不会取消已回复后的执行，服务 shutdown 仍可取消。进程崩溃不保证重放；业务若需持久投递、去重或恢复，必须另行设计，不能把 `ctx.reply` 当作持久队列。凭据和权限均沿用现有 Source/Stream 合同。

package/skills/tier0-sdk-v2/tier0-sdk-v2-stream/references/update.md

@@ -29,6 +29,6 @@ export async function updateStreamDescription(
 }
 ```
 
-代码应用可直接用 documents.update({id, expectedRevision, program, dryRun:false, idempotencyKey})，由服务端编译入口和绑定。编辑完整文档时保留 sdkVersion/timeoutMs，并同步 entries/sources；写入本身执行校验，只有需要提前展示问题时才单独 validate。不要对documents.get 的 summary 做展开更新。
+代码应用可直接用 documents.update({id, expectedRevision, program, dryRun:false, idempotencyKey})，由服务端编译入口和绑定。编辑完整文档时保留 script.code/timeoutMs，并同步 entries/sources；写入本身执行校验，只有需要提前展示问题时才单独 validate。不要对documents.get 的 summary 做展开更新。
 
 响应是完整 CloudStreamDocumentView 或预检结果；把 saved.data 直接传给下一步[发布示例](deploy.md)，无需为了 revision 再读取。已有当前完整文档时可省去示例最初的 get。保存草稿不会自动部署，activeDocument 可能仍是旧发布版本。VERSION_CONFLICT 后重新读取、比较并决策；不无条件覆盖。

package/skills/tier0-sdk-v2/tier0-sdk-v2-system/SKILL.md

@@ -51,7 +51,7 @@ info 返回 name/version/mqttBroker/capabilities，字段可能省略。MQTT bro
 | disabled / not_supported / unavailable | 展示具体不可用原因，不强制调用 |
 | readiness_unknown | 保留未知状态，不能按成功处理 |
 
-能力目录当前识别 namespace.v2、source.v1、stream.v2、control.v1、control.invoke.v1。contractVersions、apiContractVersions、sdkContractVersions 是契约标签，不是 npm 包版本；productVersion 未配置时可缺省。
+能力目录当前识别 namespace.v2、source、stream、control.v1、control.invoke.v1。Source/Stream 的 contractVersions 使用 openapi/v2，不要求或返回解释器版本。contractVersions、apiContractVersions、sdkContractVersions 是契约标签，不是 npm 包版本；productVersion 未配置时可缺省。
 
 ## 定位问题
 

package/skills/tier0-sdk-v2/tier0-sdk-v2-uns/references/create.md

@@ -4,6 +4,8 @@
 
 集合 data 必须包含 name、recordSchema，可选 description、parentId、sampleSchema、indexes、semantics。parentId=null 表示根目录。索引创建后仍需确认状态为 ready。
 
+目录、集合和主题使用现有 name 填写易读的真实业务名称，语言遵循用户偏好和已有术语；不要用程序 alias、随机串或 ID 代替名称，也不新增展示名称字段。工业目录优先复用已有 ISA-95 设备层级，只创建业务已知的层级；修改既有名称须有用户授权，不借整理名称改写 ID、alias、权限或移动数据。
+
 ```ts
 import { createClient, type Tier0Client, type UnsV2Request } from '@tier0/sdk-v2';