@microi.net/cli 5.4.0 → 5.4.2

package/skills/microi-sso/references/inbound.md

@@ -46,7 +46,7 @@
 5. 重新读取 `sys_user`，确认未删除、未停用。
 6. 签发 DiyToken，写不含凭据的 SSO 审计。
 
-步骤 2–5 固定由 `sso_resolve_federated_identity` 执行；协议 Controller 只把已经验签、归一化且不含原始 Token/断言的 Claim 交给该引擎。步骤 6 由 `sso_complete_login` 编排并调用一次性票据/DiyToken 原子。不要在 OIDC、SAML、CAS 三个 Controller 中各复制一套用户查询、JIT 和角色映射。
+步骤 2–5 固定由 `sso_resolve_federated_identity` 执行；`sso_http_oidc_callback`、`sso_http_saml_acs`、`sso_http_cas_callback` 只通过 `RunSsoProtocol` 取得已经验签、归一化且不含原始 Token/断言的 Claim。步骤 6 由 `sso_complete_login` 编排并调用一次性票据/DiyToken 原子。禁止为 OIDC、SAML、CAS 恢复 Controller 或各复制一套用户查询、JIT 和角色映射。
 
 ## 浏览器回调
 

package/skills/microi-sso/references/outbound.md

@@ -18,7 +18,7 @@
 
 Client Secret 轮换动作只显示一次明文，持久化 PBKDF2-SHA256 哈希。签名 Key 必须有 `kid`，轮换时保留验证重叠窗口。
 
-对外 Claim 固定由 `sso_outbound_claims` 从启用用户与连接白名单生成；OIDC/SAML/CAS 协议网关只负责把同一投影编码成对应协议。Client Secret 轮换由 `sso_rotate_client_secret` 编排，并调用精确受限的可信原子生成一次性明文与持久哈希，不能恢复为 Controller 定制动作。
+对外 Claim 固定由 `sso_outbound_claims` 从启用用户与连接白名单生成；24 个 `sso_http_*` Managed 端点通过 `RunSsoProtocol` 把同一投影编码成 OIDC/SAML/CAS 响应。Client Secret 轮换由 `sso_rotate_client_secret` 编排，并调用精确受限的可信原子生成一次性明文与持久哈希，不能恢复为 Controller 定制动作。
 
 ## SAML IdP
 

package/skills/v8-api-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: v8-api-config
-description: Microi V8 接口引擎配置指南。用于设置 ApiEngineKey、ApiAddress、StopHttp、AllowAnonymous、ResponseFile、锁、日志、超时和 HTTP 暴露。
+description: Microi V8 接口引擎配置指南。用于设置 ApiEngineKey、ApiAddress、StopHttp、AllowAnonymous、ResponseFile、ResponseType=HTTP、锁、日志、超时和 HTTP 暴露。
 ---
 
 > **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
@@ -13,20 +13,36 @@ description: Microi V8 接口引擎配置指南。用于设置 ApiEngineKey、Ap
 
 | 字段 | 说明 | 默认 |
 |------|------|------|
-| `ApiEngineKey` | 接口唯一标识（URL 路径） | 必填 |
-| `ApiAddress` | 自定义接口地址（覆盖默认 `/apiengine/{Key}`） | 空 |
+| `ApiEngineKey` | 接口唯一标识（URL 路径） | 必填 |
+| `ApiAddress` | 自定义接口地址（覆盖默认 `/apiengine/{Key}`） | 空 |
+| `ApiRoutes`（多路由） | 同一接口的兼容地址，多个绝对路径用英文分号分隔 | 空 |
 | `RequestType` | `Get` / `Post` / `Both` | `Both` |
 | `ParamType` | `form` / `json` / `url` —— 但 V8.Param 都能统一接收 | `Both` |
 | `IsAnonymous` | 允许匿名调用（无 Token） | `false` |
 | `StopHttp` | 禁止外部 HTTP 调用（仅允许 V8.ApiEngine.Run 内部调用） | `false` |
 | `IsResponseFile` | 是否响应文件（开启后 Data 必须是文件结构） | `false` |
-| `ResponseType` | `JSON/String/File/HTML/Stream`；`Stream` 开启 SSE/NDJSON | 自动识别 |
+| `ResponseType` | `JSON/String/File/HTML/Stream/HTTP`；`HTTP` 返回受控状态码、响应头和正文 | 自动识别 |
 | `LockKey` | 分布式锁 Key（同一时刻全集群只能执行一次） | 空 |
 | `LockTimeout` | 锁超时秒数 | `30` |
 | `LockMsg` | 加锁失败时返回提示 | `操作过于频繁` |
 | `RateLimit` | 频率限制（如 `60/m` 每分钟60次） | 空 |
 | `LogParam` | 是否记录请求参数到 `sys_log` | `false` |
-| `LogResult` | 是否记录返回值到 `sys_log` | `false` |
+| `LogResult` | 是否记录返回值到 `sys_log` | `false` |
+
+### 多路由（ApiRoutes）
+
+`ApiAddress` 是唯一主路由；`ApiRoutes` 只用于让同一接口引擎继续接收多个历史地址，例如：
+
+```text
+ApiAddress: /apiengine/platform-sys-menu
+ApiRoutes: /api/SysMenu/GetSysMenuModel;/api/SysMenu/GetSysMenuStep
+```
+
+- 多个地址必须用英文分号 `;` 分隔；每项都必须是 `/` 开头的绝对路径，保存时按不区分大小写去重，最多 128 项。
+- `Id`、`ApiEngineKey`、`ApiAddress` 与每一项 `ApiRoutes` 都会成为同一接口的缓存别名。路由只做完整路径精确匹配，不把 Query 计入地址。
+- 主路由与多路由不得重复，也不得与其它启用接口的主路由/多路由冲突；保存、启动闭包和缓存初始化都必须失败关闭并指出冲突 Key，禁止后写覆盖先写。
+- 新客户端仍使用 `/apiengine/{ApiEngineKey}` 或主 `ApiAddress`。多路由用于 Controller 迁移、旧移动端和第三方已登记回调的兼容，不得拿它复制多份相同接口代码。
+- MCP 创建接口时传 `apiRoutes: ['/api/Old/A', '/api/Old/B']`；更新时省略表示保留，传空字符串/空数组表示清空。官方应用包必须同时携带 `ApiRoutes`、醒目 Managed 提示与 `ResourcePolicies.ApiEngines`。
 
 ### 资源预算与嵌套调用（强制理解）
 
@@ -54,6 +70,30 @@ return { Code: 1, Data: { Count: rows.length } };
 - 当前租户在 `sys_osclients` 配置单分片、累计响应和心跳：`ApiEngineStreamMaxChunkKB` 默认 256（4–1024）、`ApiEngineStreamMaxTotalMB` 默认 16（1–256）、`ApiEngineStreamHeartbeatSeconds` 默认 15（5–60）。
 - 流式传输用于在线增量反馈；大型文件走 HDFS/文件响应，可靠长任务走后台任务 + Checkpoint，广播状态走提交后 SignalR。禁止用流式响应绕过这些边界。
 
+### 受控原始 HTTP 响应（ResponseType=HTTP）
+
+标准协议需要非 200 状态、重定向、XML/纯文本或指定 Content-Type 时，不要新建 Controller。设置 `ResponseType=HTTP`，并返回统一契约：
+
+```javascript
+return {
+  Code: 1,
+  DataAppend: { HttpResponse: {
+    StatusCode: 302,
+    ContentType: 'text/plain; charset=utf-8',
+    Body: '',
+    Headers: {
+      Location: 'https://identity.example.com/login',
+      'Cache-Control': 'no-store'
+    }
+  } }
+};
+```
+
+- 普通接口引擎可设置 `Cache-Control`、`Pragma`、`Location`、`WWW-Authenticate`、下载/语言/CSP 等安全白名单响应头；禁止 Host、Content-Length、Transfer-Encoding、Connection 等逐跳或宿主管理头。
+- `Location` 只允许站内绝对路径、HTTPS 地址或本机开发地址，禁止 CRLF、协议相对地址、非本机 HTTP 和带用户信息 URL。
+- `Set-Cookie` 等高风险头只允许由受限 `V8.Method` 可信原子生成并签名，租户 V8 无法自行伪造签名。SSO 使用 `V8.Method.RunSsoProtocol`；不要把 Secret、Cookie 值或签名密钥暴露给 V8。
+- `204/304` 不得带正文；状态码限制为 100–599，正文和响应头有大小/数量限制。HTTP 契约校验失败时宿主返回标准错误，不写出半截协议响应。
+
 ### 通用实时事件（SignalR）
 
 订单、协作、设备、审批或多人房间需要实时刷新时，业务写命令仍由接口引擎执行并提交事务；成功结果通过 `DataAppend.RealtimeEvent` 声明提交后事件。新业务统一使用通用 v2 Hub `/api-engine-realtime`，不要再新建业务专用 Hub 或把权威状态放进 C# 进程内字典。
@@ -154,13 +194,22 @@ return { Code: 1 };
 
 分布式锁不是“业务只执行一次”的最终保证。扣款、库存、积分、流水、对账等副作用还必须使用稳定幂等键、数据库唯一约束/条件更新、状态机或 outbox/inbox；锁 Key 至少包含 `OsClient + 业务唯一标识`，超时必须大于正常执行时间。所需唯一索引必须写入 Manifest `tables[].indexes` 并通过 `microi_create_table_index` 创建、`microi_get_table_indexes` 回读，接口引擎本身禁止执行索引 DDL。
 
-## 4. 自定义路径（ApiAddress）
+## 4. 自定义路径（ApiAddress）
 
 让接口暴露为 `/wechat/notify` 而非 `/apiengine/wechat_notify`，对接第三方时常用：
 
 ```
-ApiAddress: /wechat/notify
-```
+ApiAddress: /wechat/notify
+```
+
+标准协议还可声明逐段模板，例如：
+
+```text
+ApiAddress: /sso/{OsClient}/.well-known/openid-configuration
+ApiAddress: /saml/{OsClient}/sp/{ConnectionKey}/metadata
+```
+
+模板只匹配完整路径段，不支持贪婪通配符。命中的路由值会写入 `V8.Param._RouteValues`，并以权威路径值覆盖同名 Query/Form/JSON 参数，防止调用者伪造另一租户或连接。包含 `{OsClient}` 时租户由该路径段解析；同一路径匹配多个模板视为配置冲突并拒绝执行。
 
 ## 5. 响应文件（IsResponseFile）
 
@@ -241,7 +290,7 @@ Body: {"ApiEngineKey":"your_key","Action":"Bootstrap"}
 - `ApiAddress` 不能为空字符串；空字符串可能导致 404。
 - 响应不能是空 body、字符串 `null`、非 JSON；业务接口必须返回标准 DosResult。
 - 普通 `POST/PUT/PATCH/DELETE` 必须使用稳定路径 `/apiengine/{ApiEngineKey}`，租户放在唯一的 `osclient` Header，并可在 JSON/Form Body 中冗余传入；禁止无脑给路径追加 `--OsClient--...--`。普通 GET 优先 Header 或 `?OsClient=`。只有微信/支付等第三方回调（包括 POST）、浏览器直接下载等调用方确实无法设置 Header 或 Query 的场景，才使用 `--OsClient--{OsClient}--` 特殊路径；Query 参数名固定为 `OsClient`，禁止 `o` 等缩写。
-- 需要 C# 验签/AES 解密或隐藏 SaaS 密钥的回调，使用“最小协议网关 + `Managed` 核心接口 + `CreateIfMissing` 租户 Hook”。网关不得承载日志、写表、通知等业务逻辑；传给 V8 的事件必须脱敏，并包含稳定 `EventId` 供 Hook 幂等。
+- 需要 C# 验签/AES 解密、协议编解码或隐藏 SaaS 密钥的回调，使用“`Managed` HTTP 接口引擎 + 精确 Key 可调用的最小 `V8.Method` 可信原子 + `CreateIfMissing` 租户 Hook”。公开地址仍归接口引擎，禁止为此恢复 Controller；传给 Hook 的事件必须脱敏，并包含稳定 `EventId` 供幂等。
 - 更新接口代码时保留 HTTP 元数据，避免只覆盖 JS 代码却把匿名、启用、自定义地址等配置冲掉。
 
 ### 路由冷缓存与客户端直达头（强制）

package/skills/v8-security/SKILL.md

@@ -65,7 +65,7 @@ Secret 只通过租户管理员专用端点写入租户绑定的认证密文。
 - 多节点保存连接使用按 `OsClient + DbKey` 隔离的分布式锁，并由数据库唯一索引兜底；同步数据和附件仍必须使用业务幂等键，锁不能替代唯一约束、状态机或 inbox/outbox。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-security-001 sha256=aad35b2c3e1876d98ead7e604307bcb7d39fe8c480d72f102ae956972580a35b -->
+<!-- microi-progressive:chunk id=v8-security-001 sha256=bcb95a6c33b3abb6bfce13589e21ce56ff2aea8578d05180f2f2538cc5117fb8 -->
 ## 0.5 接口引擎配置安全
 
 代码以外，接口本身的配置项也是安全防线（详见 `v8-api-config/SKILL.md`）：
@@ -75,8 +75,13 @@ Secret 只通过租户管理员专用端点写入租户绑定的认证密文。
 | `IsAnonymous = false` | 非公开接口默认关闭，防止匿名调用越权 |
 | `StopHttp = true` | 内部接口（核心扣款、内部计算）防止外部直接 HTTP 调用 |
 | `LockKey = ...` | 写操作类接口（对账、补单）防止并发执行 |
-| `RateLimit = 60/m` | 公开接口（验证码、登录）防爬虫 |
+| `RateLimit = 60/m` | 公开接口（验证码、登录）防爬虫 |
 | `LogParam = true` | 支付/审计类接口记录请求 |
+| `ResponseType = HTTP` | 标准协议需要状态码、重定向、XML/纯文本或特定响应头 |
+
+`ResponseType=HTTP` 不是任意响应头旁路。普通 V8 只能返回安全白名单头，`Location` 经过站内/HTTPS 校验；Host、Content-Length、逐跳头始终禁止。`Set-Cookie` 等高风险头只接受平台可信原子的进程内签名结果，V8 不能获得或伪造签名密钥。需要协议编解码、签名验签或密钥隔离时，公开地址仍由 Managed 接口引擎拥有，C# 只实现精确 Key 可调用的最小 `V8.Method` 原子，禁止恢复业务 Controller。
+
+`ApiAddress` 使用 `{OsClient}`、`{ConnectionKey}` 路径模板时，模板值是权威值并覆盖同名 Query/Form/JSON 参数；多模板歧义必须失败关闭，防止跨租户或跨连接参数混淆。
 
 ### 表单上传的防篡改边界
 

package/skills/v8-workflow/SKILL.md

@@ -7,7 +7,15 @@ description: Microi V8 工作流事件指南。用于编写审批流条件、节
 
 # Microi V8 工作流事件开发
 
-你正在开发 Microi 吾码平台的工作流（审批流程）V8 事件。流程引擎基于表单引擎，通过 V8 事件控制审批逻辑。
+你正在开发 Microi 吾码平台的工作流（审批流程）V8 事件。流程引擎基于表单引擎，通过 V8 事件控制审批逻辑。
+
+## 后端类库与接口边界
+
+- 工作流运行时固定属于独立 `Microi.WorkFlow` 类库；`Microi.net.Api` 只注册 `AddMicroiWorkFlow()`，不得恢复 `WorkFlowController` 或把流程业务写回 `Program.cs`。
+- 对外与旧移动端路由统一由官方 Managed `platform-workflow` 接口引擎承载，历史 `/api/WorkFlow/*` 地址写入同一记录的 `ApiRoutes`。租户个性化逻辑写在 CreateIfMissing `platform-workflow-custom-hook`，默认只返回 `{ Code: 1 }`。
+- `Microi.Core` 只保留避免循环引用所需的 `IWFEngine`、模型和最小运行时合同；发起、审批、撤回、移交、退回及审批人计算实现在 `Microi.WorkFlow`，并按职责拆分 partial 文件。
+- 新业务规则仍优先写工作流 V8/接口引擎。只有事务、流程状态机、可信当前用户和运行时内核缺少不可伪造的底层原子时，才扩展 `Microi.WorkFlow`。
+- 官方发布时 `Microi.WorkFlow` 必须生成 NuGet 包，并与 `Microi.AI` 使用同一 Obfuscar 配置加密后替换包内 DLL；不得推送未加密的 WorkFlow 包。开源安装只消费 NuGet，不要求存在私有源码。
 
 <!-- microi-progressive:begin -->
 <!-- microi-progressive:chunk id=v8-workflow-000 sha256=9030cd2de9f1febfb9a749c82cf83e97ccb8fb972a3f8f0ff11067488e14cd8e -->