@microi.net/cli 6.1.1 → 6.1.3

package/skills/microi-solution-quotation/SKILL.md

@@ -1,78 +1,78 @@
----
-name: microi-solution-quotation
-description: Create or revise compact professional Microi吾码 system solution and quotation Word documents. Use when a user asks for a Microi吾码 解决方案、项目建议书、技术路线、实施周期、市场预估价、优惠报价或一页式 DOCX 报价，尤其适用于低代码、V8引擎、PC/UniApp/微信小程序、物联网和系统集成项目。
----
-
-> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
-
-# Microi吾码解决方案与报价
-
-生成客户可直接查看或发送的 `.docx` 方案报价。先基于真实需求和资料确定技术边界，再用紧凑商务版式呈现价值、技术路线、总价、周期和限制条件。
-
-## 工作流程
-
-1. 读取需求、PDF、截图、现有 Word 和项目资料；不把尚未确认的硬件协议、第三方接口或平台能力写成已具备。
-2. 提炼项目目标、核心范围、Microi吾码实现方式、关键技术路线、交付物、风险与前置条件。
-3. 确定项目名称、版本、日期、开发周期、市场预估价、优惠报价和报价有效期。用户已给值时必须原样采用。
-4. 使用 `scripts/build_solution_quote.py` 生成 Word；复杂项目可按同一视觉规范扩展。
-5. 把 DOCX 渲染为 PNG，检查页数、字体、表格、换行和溢出；修正后再交付。缺少 LibreOffice/soffice 时做结构检查，并在交付说明中明确未完成视觉渲染。
-
-## 固定版式
-
-- 页面：A4 纵向。
-- 页边距：Word“窄”，上、下、左、右均为 `0.5 in / 1.27 cm / 720 DXA`。
-- 布局：紧凑、商务、可快速扫读。小项目默认一页；不要用缩小到 9pt 以下正文的方式硬塞内容。
-- 字体：中文优先 `Microsoft YaHei`，正文 9-10pt；标题 20-22pt；章节标题 10.5-12pt。
-- 大标题：`Microi吾码 {系统名称} 解决方案与报价`。
-- 副标题必须为：`AI 深度融合 V8引擎 的低代码平台，官网：https://microi.net`。
-- 标题下方放置版本、日期、开发周期、报价有效期；默认版本 `v1.0.0`，默认有效期 15 天。
-- 使用克制的吾码蓝色系；表格必须固定 DXA 宽度并设置单元格内边距，禁止依赖自动调整。
-- 页脚可放版本、日期和官网，不重复正文报价。
-
-## 内容结构
-
-按项目规模裁剪，但至少包含：
-
-1. 项目目标：1 段说明客户要解决的问题和最终结果。
-2. 解决方案：3-5 个具体范围，明确 Microi 表单引擎、V8 接口/事件、权限、PC 或移动端、第三方/硬件集成的分工。
-3. 技术路线：用一行可读链路表达核心数据流；物联网项目必须区分“手机本地直连”和“公网云控”。
-4. 交付范围：源代码/低代码元数据、接口、部署配置、联调、测试和简要操作说明。
-5. 总价与周期：只展示市场预估总价、优惠总价和开发周期，不列模块价格明细。
-6. 商务与技术边界：列出需求变更、第三方费用、硬件/云资源、协议资料、样机、账号资质等前置条件。
-
-## 报价规则
-
-- 不生成模块级价格表，不把各功能拆分报价。
-- 同时展示：`市场预估价`、`优惠报价`、`开发周期`。
-- 优惠报价应比市场预估价低；所有金额使用人民币并明确“总价”。
-- 用户未提供价格时，可根据范围给出合理市场预估并标注为参考；硬件改造、协议逆向和第三方服务等不确定成本必须排除或写为“另行评估”。
-- 不猜测含税状态、付款比例、质保年限或合同条款；用户未指定时写“以正式合同/确认需求清单为准”。
-
-## Microi吾码技术表达
-
-- 后台管理：优先使用表单引擎、菜单/权限和低代码元数据。
-- 业务逻辑：使用 V8 接口引擎、表单事件、定时任务和缓存，不把项目专属逻辑写入平台通用层。
-- 移动端：根据需求选择 UniApp/H5/微信小程序，并通过 HTTPS 调用后端接口。
-- 物联网：推荐 `小程序 -> HTTPS -> Microi V8 API -> MQTT/TLS -> 网关 -> 设备协议`；保留设备本地安全联锁、离线保护和操作审计。
-- 权限：菜单权限与接口业务权限同时设计；设备/客户数据必须做归属与行级校验。
-
-## 生成脚本
-
-准备 UTF-8 JSON 配置并运行：
-
-```powershell
-uv run --with python-docx -- python microi.skills/microi-solution-quotation/scripts/build_solution_quote.py `
-  --input .tmp/solution-quote.json `
-  --output "AI-Project/客户/项目/Microi吾码系统解决方案与报价.docx"
-```
-
-JSON 常用字段：`system_name`、`project_goal`、`solution_items`、`technical_route`、`deliverables`、`market_price`、`preferential_price`、`development_cycle`、`version`、`date`、`validity_days`、`boundary_note`。
-
-## 工作区与交付检查
-
-- 临时脚本、JSON、渲染图和 QA 产物必须写入仓库根目录 `.tmp/`，禁止创建根目录 `tmp/`。
-- 用户认为提取结果有长期价值时，将其整理到用户指定的项目目录，不留在临时目录。
-- 大标题、副标题、版本、日期、周期、市场预估价和优惠报价全部存在。
-- 没有模块明细价格，没有占位符，没有把未确认能力写成已交付。
-- 小项目只有一页；无截断、重叠、孤行、超宽表格和过小字体。
-- 最终回复仅链接正式 DOCX，不链接临时 JSON、生成脚本、PNG 或 PDF QA 文件。
+---
+name: microi-solution-quotation
+description: Create or revise compact professional Microi吾码 system solution and quotation Word documents. Use when a user asks for a Microi吾码 解决方案、项目建议书、技术路线、实施周期、市场预估价、优惠报价或一页式 DOCX 报价，尤其适用于低代码、V8引擎、PC/UniApp/微信小程序、物联网和系统集成项目。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# Microi吾码解决方案与报价
+
+生成客户可直接查看或发送的 `.docx` 方案报价。先基于真实需求和资料确定技术边界，再用紧凑商务版式呈现价值、技术路线、总价、周期和限制条件。
+
+## 工作流程
+
+1. 读取需求、PDF、截图、现有 Word 和项目资料；不把尚未确认的硬件协议、第三方接口或平台能力写成已具备。
+2. 提炼项目目标、核心范围、Microi吾码实现方式、关键技术路线、交付物、风险与前置条件。
+3. 确定项目名称、版本、日期、开发周期、市场预估价、优惠报价和报价有效期。用户已给值时必须原样采用。
+4. 使用 `scripts/build_solution_quote.py` 生成 Word；复杂项目可按同一视觉规范扩展。
+5. 把 DOCX 渲染为 PNG，检查页数、字体、表格、换行和溢出；修正后再交付。缺少 LibreOffice/soffice 时做结构检查，并在交付说明中明确未完成视觉渲染。
+
+## 固定版式
+
+- 页面：A4 纵向。
+- 页边距：Word“窄”，上、下、左、右均为 `0.5 in / 1.27 cm / 720 DXA`。
+- 布局：紧凑、商务、可快速扫读。小项目默认一页；不要用缩小到 9pt 以下正文的方式硬塞内容。
+- 字体：中文优先 `Microsoft YaHei`，正文 9-10pt；标题 20-22pt；章节标题 10.5-12pt。
+- 大标题：`Microi吾码 {系统名称} 解决方案与报价`。
+- 副标题必须为：`AI 深度融合 V8引擎 的低代码平台，官网：https://microi.net`。
+- 标题下方放置版本、日期、开发周期、报价有效期；默认版本 `v1.0.0`，默认有效期 15 天。
+- 使用克制的吾码蓝色系；表格必须固定 DXA 宽度并设置单元格内边距，禁止依赖自动调整。
+- 页脚可放版本、日期和官网，不重复正文报价。
+
+## 内容结构
+
+按项目规模裁剪，但至少包含：
+
+1. 项目目标：1 段说明客户要解决的问题和最终结果。
+2. 解决方案：3-5 个具体范围，明确 Microi 表单引擎、V8 接口/事件、权限、PC 或移动端、第三方/硬件集成的分工。
+3. 技术路线：用一行可读链路表达核心数据流；物联网项目必须区分“手机本地直连”和“公网云控”。
+4. 交付范围：源代码/低代码元数据、接口、部署配置、联调、测试和简要操作说明。
+5. 总价与周期：只展示市场预估总价、优惠总价和开发周期，不列模块价格明细。
+6. 商务与技术边界：列出需求变更、第三方费用、硬件/云资源、协议资料、样机、账号资质等前置条件。
+
+## 报价规则
+
+- 不生成模块级价格表，不把各功能拆分报价。
+- 同时展示：`市场预估价`、`优惠报价`、`开发周期`。
+- 优惠报价应比市场预估价低；所有金额使用人民币并明确“总价”。
+- 用户未提供价格时，可根据范围给出合理市场预估并标注为参考；硬件改造、协议逆向和第三方服务等不确定成本必须排除或写为“另行评估”。
+- 不猜测含税状态、付款比例、质保年限或合同条款；用户未指定时写“以正式合同/确认需求清单为准”。
+
+## Microi吾码技术表达
+
+- 后台管理：优先使用表单引擎、菜单/权限和低代码元数据。
+- 业务逻辑：使用 V8 接口引擎、表单事件、定时任务和缓存，不把项目专属逻辑写入平台通用层。
+- 移动端：根据需求选择 UniApp/H5/微信小程序，并通过 HTTPS 调用后端接口。
+- 物联网：推荐 `小程序 -> HTTPS -> Microi V8 API -> MQTT/TLS -> 网关 -> 设备协议`；保留设备本地安全联锁、离线保护和操作审计。
+- 权限：菜单权限与接口业务权限同时设计；设备/客户数据必须做归属与行级校验。
+
+## 生成脚本
+
+准备 UTF-8 JSON 配置并运行：
+
+```powershell
+uv run --with python-docx -- python microi.skills/microi-solution-quotation/scripts/build_solution_quote.py `
+  --input .tmp/solution-quote.json `
+  --output "AI-Project/客户/项目/Microi吾码系统解决方案与报价.docx"
+```
+
+JSON 常用字段：`system_name`、`project_goal`、`solution_items`、`technical_route`、`deliverables`、`market_price`、`preferential_price`、`development_cycle`、`version`、`date`、`validity_days`、`boundary_note`。
+
+## 工作区与交付检查
+
+- 临时脚本、JSON、渲染图和 QA 产物必须写入仓库根目录 `.tmp/`，禁止创建根目录 `tmp/`。
+- 用户认为提取结果有长期价值时，将其整理到用户指定的项目目录，不留在临时目录。
+- 大标题、副标题、版本、日期、周期、市场预估价和优惠报价全部存在。
+- 没有模块明细价格，没有占位符，没有把未确认能力写成已交付。
+- 小项目只有一页；无截断、重叠、孤行、超宽表格和过小字体。
+- 最终回复仅链接正式 DOCX，不链接临时 JSON、生成脚本、PNG 或 PDF QA 文件。

package/skills/microi-sso/SKILL.md

@@ -1,102 +1,102 @@
----
-name: microi-sso
-description: 设计、实现、配置、迁移、发布和验收 Microi 吾码双向 SSO 身份联邦。用于外部系统通过 OIDC、SAML2、CAS 登录吾码，或吾码作为 OIDC OP、SAML IdP、CAS Server 集成其它系统，以及 diy_sso、账号/角色映射、Secret/证书、官方应用 app.microi.sso 和真实伙伴联调。
----
-
-> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
-
-# Microi SSO 身份联邦
-
-## 何时使用
-
-以下任务必须使用本 Skill：
-
-- Keycloak、Entra ID、ADFS、CAS Server、企业统一身份中心登录吾码。
-- 吾码账号登录 ERP、OA、BI、门户或其它第三方系统。
-- 修改 `diy_sso`、SSO 登录页、OIDC/SAML/CAS 接口引擎端点、Claim/角色映射或旧 Token SSO。
-- 发布、安装、升级或验收官方商城应用 `app.microi.sso`。
-
-固定 Microi、Gitee、微信、GitHub 登录与 Passkey/TOTP 仍以 `v8-security` 为主；当需求是可配置企业身份联邦时转到本 Skill。
-Microi 登录调用官方 OIDC 身份服务：官方端按每个部署登记独立公共客户端、`ClientAuthMethod=none`、
-精确回调、PKCE S256 与 nonce；客户端侧不创建普通 `diy_sso` 连接或共享 ClientSecret。
-官方客户端实例与用户绑定不是平台应用包种子，登记和真实授权验收须独立记录。
-公共客户端逐次确认、`prompt=none` 错误与不消费请求的 Preview 规则见 [references/outbound.md](references/outbound.md)。
-
-## 先读取什么
-
-按任务读取，不要一次加载全部参考：
-
-- 外部身份源登录吾码：读 [references/inbound.md](references/inbound.md)。
-- 吾码给第三方提供登录：读 [references/outbound.md](references/outbound.md)。
-- 表字段、Secret、证书、安全与存量迁移：读 [references/configuration-and-security.md](references/configuration-and-security.md)。
-- 测试、商城发布、目标安装与交付结论：读 [references/acceptance.md](references/acceptance.md)。
-
-源码修改前同时完整读取 `workspace-conventions/SKILL.md`；认证、DiyToken、秘密或权限任务再读 `v8-security/SKILL.md`；商城任务再读 `app-store/SKILL.md`。
-
-## 不可破坏的事实
-
-1. DiyToken 是进入吾码后的唯一平台会话入口。SSO 认证成功后签发 DiyToken，不创建第二套用户/权限 Token。
-2. 吾码向外提供的 OIDC/SAML/CAS 协议票据独立、短期、可撤销，绝不把 DiyToken 给第三方。
-3. `OsClient + ConnectionKey + Subject` 是外部主体隔离边界；所有回调、票据、缓存和审计都绑定租户。
-4. 新连接只用 OIDC、SAML2、CAS；URL Token 是迁移兼容项，不是推荐协议。
-5. Redirect URI、ACS、Destination、Audience 和 CAS service 必须精确匹配；生产端点必须 HTTPS。
-6. Secret/私钥只存 `mci_system_setting` 的受控值；`diy_sso` 只存 Setting Key。匿名接口只返回登录入口白名单投影。
-7. 外部角色、邮箱或昵称不能直接获得管理员权限。默认 `BoundOnly`，JIT 必须显式默认角色、唯一性、回收和审计。
-8. HTTP 200、构建成功、商城任务入队或包可下载都不是完整 SSO 验收。
-9. SSO 公开 HTTP 路由和业务逻辑都必须由接口引擎承载：连接投影、绑定/JIT、角色与 Claim 映射、审计、登录完成、租户扩展以及 OIDC/SAML/CAS 路由不得重新写进 Controller。只有协议编解码、签名验签、Secret/私钥隔离、一次性票据与 DiyToken 等可信原子可以保留在独立 `Microi.SSO` 类库，并且只能由精确官方 Managed Key 调用。
-10. 客户端调用固定应用接口必须优先使用 `/apiengine/{ApiEngineKey}?OsClient=`，让系统日志/监控按真实接口引擎归因；新版宿主即使接口尚未安装也会返回结构化缺失错误。`/api/ApiEngine/Run` 只保留给无法预知 Key 的旧版兼容调用，禁止新增固定业务依赖；同样禁止调用已删除的 `/api/Sso/Capabilities` 等定制路由。
-
-## 标准工作流
-
-### 存量 TokenLogin 与深链接兼容
-
-- 已启用且精确配置 `ClientSsoApi=/api/SysUser/TokenLogin` 的旧连接使用平台原生 DiyToken 验证；不能错误过滤掉，也不能改走外部身份源的 `sso_legacy_token_login`。未配置、已停用、任意 URL 或非法 Token 必须继续拒绝。
-- SSO 成功后优先保留用户指定的站内深链接及业务参数（如 `ShowClassicLeft/ShowClassicTop`）；只有没有指定目标页才采用用户/系统默认首页。菜单/数据权限仍由正常路由守卫与后端校验。
-- URL Token 使用后从地址栏和下一次 Router 导航对象同时清除，包括 hash query；单独 `history.replaceState` 不够，动态路由重匹配会把旧 query 带回。验收必须检查 TokenLogin 成功、目标页真实可见、URL 无凭据、布局参数保留；不能仅断言 HTTP 302 或 Code=1。
-
-1. 识别方向、协议、租户、身份伙伴、用户生命周期、退出和密钥/证书责任人。
-2. 读取当前 `diy_sso` Schema、菜单、真实连接和已部署 Server/Client 版本；不要从旧截图猜测。
-3. 先选标准协议和安全 profile，再配置字段、Secret/证书 Key、Claim/角色映射。
-4. 先把业务编排写成可随应用发布的接口引擎；仅当现有 V8 无法安全完成底层原子能力时，才扩展最小 `V8.Method`，并把调用权限制到精确官方接口 Key。禁止把整个流程放进新 Controller，也禁止让原子方法接受任意租户、回调地址或 Secret。
-5. 分别验证源码/单测、后端构建、前端构建、运行时端点、浏览器 UI、真实伙伴和多节点。
-6. 平台级资源通过官方应用包发布；官方源用 `microi_itdos` 更新并发布，普通目标租户走商城安装/升级任务。
-7. 最终明确已验证与未验证边界，尤其是“配置包已发布”与“运行时代码已部署”的区别。
-
-### 签名异常排查
-
-- 先区分 DiyToken 的 HS256、OIDC 的 RS256、SAML XML 签名和接口引擎 HTTP 响应内部签名，保留脱敏异常类型、TraceId、运行版本与失败请求顺序；截图中的“签名异常”不能直接判定为密钥错误。
-- OIDC 第一次成功、第二次登录或退出失败且异常链包含已释放 RSA 时，检查请求级 RSA 与 IdentityModel 缓存签名器的生命周期。平台请求密钥统一使用 `SsoSecurity.CreateRequestScopedRsaKey`，禁用该密钥的签名器缓存；不能修改全局 `CryptoProviderFactory.Default`、取消验签、轮换 `AuthSecret` 或删除租户证书来掩盖错误。
-- 回归须用实际发布依赖重复加载同一私钥，先复现旧缓存路径失败，再验证连续/并发签名、旧 `id_token_hint` 验签和篡改/错误密钥/issuer/audience 拒绝。后端原子修复没有声明式资源变化时，无需为空升版官方 SSO 应用，但必须独立核对后端渠道与客户部署边界。
-
-## 官方应用合同
-
-- AppId：`app.microi.sso`
-- 名称：`SSO 身份联邦`
-- 资源：`diy_sso`、`/system/sso`、字段/布局/视图、34 个 Managed 核心接口引擎和 1 个 CreateIfMissing 租户 Hook；其中 24 个 `sso_http_*` 接管原 SSO Controller 的全部公开路由，不发布用户绑定、连接实例、Secret、证书或示例账号。
-- `ResourcePolicies.ApiEngines` 必须逐 Key 显式声明。核心使用 `Managed/Platform`；`sso_event_hook` 使用 `CreateIfMissing/Tenant`，安装后永不被官方覆盖。
-- 官方 `iTdos` 是发布源，保护性拒绝安装属于正确行为；普通租户安装才必须轮询到 `Succeeded`。
-
-## C# 与接口引擎责任线
-
-接口引擎固定承载：
-
-- `sso_capabilities`、`sso_legacy_capabilities` 的匿名白名单投影；
-- `sso_connection_runtime`、`sso_user_runtime` 的内部最小投影；
-- `sso_resolve_federated_identity` 的绑定、JIT 与角色映射；
-- `sso_outbound_claims`、`sso_protocol_event`、`sso_event_hook`；
-- `sso_complete_login`、`sso_rotate_client_secret`、`sso_legacy_token_login` 的业务编排。
-- 24 个 `sso_http_*` Managed 端点：`/api/Sso/Begin`、`/api/Sso/CompleteAuthorization`、OIDC 回调/Discovery/JWKS/Authorize/Token/UserInfo/Introspect/Revoke/Logout、CAS 回调/Login/Validate/Logout、SAML Begin/ACS/Login/Complete/Metadata/Logout。
-- 历史兼容路由 `/api/Sso/CompleteLogin`、`/api/Sso/LegacyCapabilities`、`/api/Sso/RotateClientSecret` 和 `/api/Sso/SamlBegin` 只用于识别旧客户端并返回受控兼容结果；新宿主优先使用上面的接口引擎地址，不能因旧路由存在而恢复通用 SSO Controller。
-
-C# 只保留：
-
-- `Microi.SSO` 的 `SsoProtocolRuntime` 中 OIDC/SAML/CAS 报文编解码、签名验签和协议响应构造；该类型不是 MVC Controller、没有 Route/Http 特性，不直接拥有公开地址；
-- Secret、私钥、证书和协议 Token 的可信隔离；
-- 高熵一次性 code/ticket、重放保护和 DiyToken 签发；
-- 仅允许精确 Managed Key 调用的 `RunSsoProtocol`、`CreateFederatedUser`、`CreateSsoLoginTicket`、`CompleteSsoLogin`、`RotateSsoClientSecret` 原子。
-
-公开协议路由使用 `ApiAddress`（包括 `{OsClient}`、`{ConnectionKey}` 路径模板）和 `ResponseType=HTTP`。接口引擎可以返回状态码、Content-Type、XML/纯文本、重定向和安全响应头；`Set-Cookie` 等高风险响应头只能来自 `RunSsoProtocol` 签名的可信响应。不得因为协议需要原始 HTTP 而恢复任何 `Sso*Controller`。
-
-新增 SSO 需求先判断是否只需修改上述接口引擎。只有缺少不可伪造、不可泄露的底层原子时才增加 V8 方法；增加后同时更新应用 `RequiredPlatformCapabilities`、后端文档、测试与最低版本。
-
-详细用户文档：`microi.doc/docs/doc/more/sso.md`。
+---
+name: microi-sso
+description: 设计、实现、配置、迁移、发布和验收 Microi 吾码双向 SSO 身份联邦。用于外部系统通过 OIDC、SAML2、CAS 登录吾码，或吾码作为 OIDC OP、SAML IdP、CAS Server 集成其它系统，以及 diy_sso、账号/角色映射、Secret/证书、官方应用 app.microi.sso 和真实伙伴联调。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# Microi SSO 身份联邦
+
+## 何时使用
+
+以下任务必须使用本 Skill：
+
+- Keycloak、Entra ID、ADFS、CAS Server、企业统一身份中心登录吾码。
+- 吾码账号登录 ERP、OA、BI、门户或其它第三方系统。
+- 修改 `diy_sso`、SSO 登录页、OIDC/SAML/CAS 接口引擎端点、Claim/角色映射或旧 Token SSO。
+- 发布、安装、升级或验收官方商城应用 `app.microi.sso`。
+
+固定 Microi、Gitee、微信、GitHub 登录与 Passkey/TOTP 仍以 `v8-security` 为主；当需求是可配置企业身份联邦时转到本 Skill。
+Microi 登录调用官方 OIDC 身份服务：官方端按每个部署登记独立公共客户端、`ClientAuthMethod=none`、
+精确回调、PKCE S256 与 nonce；客户端侧不创建普通 `diy_sso` 连接或共享 ClientSecret。
+官方客户端实例与用户绑定不是平台应用包种子，登记和真实授权验收须独立记录。
+公共客户端逐次确认、`prompt=none` 错误与不消费请求的 Preview 规则见 [references/outbound.md](references/outbound.md)。
+
+## 先读取什么
+
+按任务读取，不要一次加载全部参考：
+
+- 外部身份源登录吾码：读 [references/inbound.md](references/inbound.md)。
+- 吾码给第三方提供登录：读 [references/outbound.md](references/outbound.md)。
+- 表字段、Secret、证书、安全与存量迁移：读 [references/configuration-and-security.md](references/configuration-and-security.md)。
+- 测试、商城发布、目标安装与交付结论：读 [references/acceptance.md](references/acceptance.md)。
+
+源码修改前同时完整读取 `workspace-conventions/SKILL.md`；认证、DiyToken、秘密或权限任务再读 `v8-security/SKILL.md`；商城任务再读 `app-store/SKILL.md`。
+
+## 不可破坏的事实
+
+1. DiyToken 是进入吾码后的唯一平台会话入口。SSO 认证成功后签发 DiyToken，不创建第二套用户/权限 Token。
+2. 吾码向外提供的 OIDC/SAML/CAS 协议票据独立、短期、可撤销，绝不把 DiyToken 给第三方。
+3. `OsClient + ConnectionKey + Subject` 是外部主体隔离边界；所有回调、票据、缓存和审计都绑定租户。
+4. 新连接只用 OIDC、SAML2、CAS；URL Token 是迁移兼容项，不是推荐协议。
+5. Redirect URI、ACS、Destination、Audience 和 CAS service 必须精确匹配；生产端点必须 HTTPS。
+6. Secret/私钥只存 `mci_system_setting` 的受控值；`diy_sso` 只存 Setting Key。匿名接口只返回登录入口白名单投影。
+7. 外部角色、邮箱或昵称不能直接获得管理员权限。默认 `BoundOnly`，JIT 必须显式默认角色、唯一性、回收和审计。
+8. HTTP 200、构建成功、商城任务入队或包可下载都不是完整 SSO 验收。
+9. SSO 公开 HTTP 路由和业务逻辑都必须由接口引擎承载：连接投影、绑定/JIT、角色与 Claim 映射、审计、登录完成、租户扩展以及 OIDC/SAML/CAS 路由不得重新写进 Controller。只有协议编解码、签名验签、Secret/私钥隔离、一次性票据与 DiyToken 等可信原子可以保留在独立 `Microi.SSO` 类库，并且只能由精确官方 Managed Key 调用。
+10. 客户端调用固定应用接口必须优先使用 `/apiengine/{ApiEngineKey}?OsClient=`，让系统日志/监控按真实接口引擎归因；新版宿主即使接口尚未安装也会返回结构化缺失错误。`/api/ApiEngine/Run` 只保留给无法预知 Key 的旧版兼容调用，禁止新增固定业务依赖；同样禁止调用已删除的 `/api/Sso/Capabilities` 等定制路由。
+
+## 标准工作流
+
+### 存量 TokenLogin 与深链接兼容
+
+- 已启用且精确配置 `ClientSsoApi=/api/SysUser/TokenLogin` 的旧连接使用平台原生 DiyToken 验证；不能错误过滤掉，也不能改走外部身份源的 `sso_legacy_token_login`。未配置、已停用、任意 URL 或非法 Token 必须继续拒绝。
+- SSO 成功后优先保留用户指定的站内深链接及业务参数（如 `ShowClassicLeft/ShowClassicTop`）；只有没有指定目标页才采用用户/系统默认首页。菜单/数据权限仍由正常路由守卫与后端校验。
+- URL Token 使用后从地址栏和下一次 Router 导航对象同时清除，包括 hash query；单独 `history.replaceState` 不够，动态路由重匹配会把旧 query 带回。验收必须检查 TokenLogin 成功、目标页真实可见、URL 无凭据、布局参数保留；不能仅断言 HTTP 302 或 Code=1。
+
+1. 识别方向、协议、租户、身份伙伴、用户生命周期、退出和密钥/证书责任人。
+2. 读取当前 `diy_sso` Schema、菜单、真实连接和已部署 Server/Client 版本；不要从旧截图猜测。
+3. 先选标准协议和安全 profile，再配置字段、Secret/证书 Key、Claim/角色映射。
+4. 先把业务编排写成可随应用发布的接口引擎；仅当现有 V8 无法安全完成底层原子能力时，才扩展最小 `V8.Method`，并把调用权限制到精确官方接口 Key。禁止把整个流程放进新 Controller，也禁止让原子方法接受任意租户、回调地址或 Secret。
+5. 分别验证源码/单测、后端构建、前端构建、运行时端点、浏览器 UI、真实伙伴和多节点。
+6. 平台级资源通过官方应用包发布；官方源用 `microi_itdos` 更新并发布，普通目标租户走商城安装/升级任务。
+7. 最终明确已验证与未验证边界，尤其是“配置包已发布”与“运行时代码已部署”的区别。
+
+### 签名异常排查
+
+- 先区分 DiyToken 的 HS256、OIDC 的 RS256、SAML XML 签名和接口引擎 HTTP 响应内部签名，保留脱敏异常类型、TraceId、运行版本与失败请求顺序；截图中的“签名异常”不能直接判定为密钥错误。
+- OIDC 第一次成功、第二次登录或退出失败且异常链包含已释放 RSA 时，检查请求级 RSA 与 IdentityModel 缓存签名器的生命周期。平台请求密钥统一使用 `SsoSecurity.CreateRequestScopedRsaKey`，禁用该密钥的签名器缓存；不能修改全局 `CryptoProviderFactory.Default`、取消验签、轮换 `AuthSecret` 或删除租户证书来掩盖错误。
+- 回归须用实际发布依赖重复加载同一私钥，先复现旧缓存路径失败，再验证连续/并发签名、旧 `id_token_hint` 验签和篡改/错误密钥/issuer/audience 拒绝。后端原子修复没有声明式资源变化时，无需为空升版官方 SSO 应用，但必须独立核对后端渠道与客户部署边界。
+
+## 官方应用合同
+
+- AppId：`app.microi.sso`
+- 名称：`SSO 身份联邦`
+- 资源：`diy_sso`、`/system/sso`、字段/布局/视图、34 个 Managed 核心接口引擎和 1 个 CreateIfMissing 租户 Hook；其中 24 个 `sso_http_*` 接管原 SSO Controller 的全部公开路由，不发布用户绑定、连接实例、Secret、证书或示例账号。
+- `ResourcePolicies.ApiEngines` 必须逐 Key 显式声明。核心使用 `Managed/Platform`；`sso_event_hook` 使用 `CreateIfMissing/Tenant`，安装后永不被官方覆盖。
+- 官方 `iTdos` 是发布源，保护性拒绝安装属于正确行为；普通租户安装才必须轮询到 `Succeeded`。
+
+## C# 与接口引擎责任线
+
+接口引擎固定承载：
+
+- `sso_capabilities`、`sso_legacy_capabilities` 的匿名白名单投影；
+- `sso_connection_runtime`、`sso_user_runtime` 的内部最小投影；
+- `sso_resolve_federated_identity` 的绑定、JIT 与角色映射；
+- `sso_outbound_claims`、`sso_protocol_event`、`sso_event_hook`；
+- `sso_complete_login`、`sso_rotate_client_secret`、`sso_legacy_token_login` 的业务编排。
+- 24 个 `sso_http_*` Managed 端点：`/api/Sso/Begin`、`/api/Sso/CompleteAuthorization`、OIDC 回调/Discovery/JWKS/Authorize/Token/UserInfo/Introspect/Revoke/Logout、CAS 回调/Login/Validate/Logout、SAML Begin/ACS/Login/Complete/Metadata/Logout。
+- 历史兼容路由 `/api/Sso/CompleteLogin`、`/api/Sso/LegacyCapabilities`、`/api/Sso/RotateClientSecret` 和 `/api/Sso/SamlBegin` 只用于识别旧客户端并返回受控兼容结果；新宿主优先使用上面的接口引擎地址，不能因旧路由存在而恢复通用 SSO Controller。
+
+C# 只保留：
+
+- `Microi.SSO` 的 `SsoProtocolRuntime` 中 OIDC/SAML/CAS 报文编解码、签名验签和协议响应构造；该类型不是 MVC Controller、没有 Route/Http 特性，不直接拥有公开地址；
+- Secret、私钥、证书和协议 Token 的可信隔离；
+- 高熵一次性 code/ticket、重放保护和 DiyToken 签发；
+- 仅允许精确 Managed Key 调用的 `RunSsoProtocol`、`CreateFederatedUser`、`CreateSsoLoginTicket`、`CompleteSsoLogin`、`RotateSsoClientSecret` 原子。
+
+公开协议路由使用 `ApiAddress`（包括 `{OsClient}`、`{ConnectionKey}` 路径模板）和 `ResponseType=HTTP`。接口引擎可以返回状态码、Content-Type、XML/纯文本、重定向和安全响应头；`Set-Cookie` 等高风险响应头只能来自 `RunSsoProtocol` 签名的可信响应。不得因为协议需要原始 HTTP 而恢复任何 `Sso*Controller`。
+
+新增 SSO 需求先判断是否只需修改上述接口引擎。只有缺少不可伪造、不可泄露的底层原子时才增加 V8 方法；增加后同时更新应用 `RequiredPlatformCapabilities`、后端文档、测试与最低版本。
+
+详细用户文档：`microi.doc/docs/doc/more/sso.md`。

package/skills/microi-sso/references/configuration-and-security.md

@@ -1,53 +1,53 @@
-# 配置、Secret、安全与迁移
-
-## diy_sso 分组
-
-- `basic`：Key、名称、方向、协议、启用、排序。
-- `oidc`：Issuer/Discovery/端点、Client、Scope、精确 Redirect URI。
-- `saml`：Entity ID、Metadata、SSO/SLO、ACS。
-- `cas`：Server URL、版本。
-- `mapping`：Subject/Account/Name/Email/Role Claim、JSON 映射、JIT。
-- `security`：Secret/证书设置 Key、签名/加密、PKCE/nonce、生命周期、私网开关。
-- `legacy`：旧 Server/Client API、TokenName、GetTokenType。
-
-`diy_sso` 是管理员专用平台表。匿名能力接口只投影 ConnectionKey、名称、协议、图标、说明和发起地址；旧兼容投影只允许同源 `/api/` 路径与安全 Token 参数名。
-
-匿名投影由 `sso_capabilities` / `sso_legacy_capabilities` 接口引擎提供；任何 Controller 都不得直接查询并返回 `diy_sso`。公开协议地址由 `sso_http_*` Managed 接口引擎拥有，可信原子再通过 StopHttp 的 `sso_connection_runtime` 取得最小运行投影。客户端能力类接口统一调用 `/apiengine/{ApiEngineKey}?OsClient=`；标准伙伴协议使用应用声明的 `ApiAddress`，其中 `{OsClient}`、`{ConnectionKey}` 由动态路由安全提取并覆盖同名外部参数。
-
-## Secret 与证书
-
-- `ClientSecretSettingKey` 等字段只存 `mci_system_setting` Key。
-- 第三方 Client Secret 和私钥证书使用后端 Secret 存储，不出现在日志、导出、包、浏览器或 MCP 回读。
-- 吾码对外 OIDC Client Secret 只存专用密码哈希；不能用 AES/DES 代替验证哈希。
-- SAML 验签/加密公开证书与签名/解密私钥严格区分用途。
-- 证书/签名 Key 轮换要有新旧重叠、伙伴确认、撤销和回滚窗口。
-
-## 网络和 URL
-
-所有外部 Discovery、JWKS、Metadata、Token、UserInfo 地址先过 HTTPS/SSRF 检查。默认拒绝回环、私网、链路本地、带用户信息 URL 和 DNS 重绑定；内网 IdP 只能由管理员显式开启并用网络出口白名单补强。
-
-Redirect/Logout/ACS/CAS service 使用规范化后的绝对 URL 精确比较。不要允许通配符、子域后缀、前缀或 fragment。反向代理下使用可信外部 Origin，不能根据任意 Host/Header 构造安全回调。
-
-## 账号与角色
-
-默认 `BoundOnly`。JIT 需要：
-
-- 稳定 Subject 与账号唯一性。
-- 非管理员默认角色。
-- 外部角色到 RoleId 的显式 allowlist。
-- 离职、禁用、角色收回与冲突处理。
-- 创建、匹配、拒绝和变更审计。
-
-这些规则由 Managed `sso_resolve_federated_identity` 编排。JIT 创建最终调用精确受限的 `V8.Method.CreateFederatedUser` 原子，并用平台专用带盐密码哈希写入不可登录的随机初始密码；不得回退到 DES，也不得把外部角色名直接写成平台 RoleId。
-
-不能把外部 `admin` 字符串、邮箱域或昵称直接解释为平台管理员。
-
-## LegacyToken 迁移
-
-1. 盘点旧 `ClientSsoApi/ServerSsoApi/TokenName` 和使用系统。
-2. 为每个系统选择 OIDC、SAML2 或 CAS 并建立新连接。
-3. 并行验证登录/退出和账号映射；新入口默认标准协议。
-4. URL 中的旧 Token 读取后立即清理，不写 Referer、日志或分析平台。
-5. 迁移完成后停用旧行；不要继续给新系统复制 LegacyToken。
-
-旧兼容只允许调用同源 `/api/`，绝不把 DiyToken POST 到管理员配置的任意绝对 URL。浏览器只处理 `LegacyCapabilities` 已返回连接中明确登记的 `TokenName`；不得恢复“只要 URL 出现 `?token=` 就自动登录”的无配置旁路。
+# 配置、Secret、安全与迁移
+
+## diy_sso 分组
+
+- `basic`：Key、名称、方向、协议、启用、排序。
+- `oidc`：Issuer/Discovery/端点、Client、Scope、精确 Redirect URI。
+- `saml`：Entity ID、Metadata、SSO/SLO、ACS。
+- `cas`：Server URL、版本。
+- `mapping`：Subject/Account/Name/Email/Role Claim、JSON 映射、JIT。
+- `security`：Secret/证书设置 Key、签名/加密、PKCE/nonce、生命周期、私网开关。
+- `legacy`：旧 Server/Client API、TokenName、GetTokenType。
+
+`diy_sso` 是管理员专用平台表。匿名能力接口只投影 ConnectionKey、名称、协议、图标、说明和发起地址；旧兼容投影只允许同源 `/api/` 路径与安全 Token 参数名。
+
+匿名投影由 `sso_capabilities` / `sso_legacy_capabilities` 接口引擎提供；任何 Controller 都不得直接查询并返回 `diy_sso`。公开协议地址由 `sso_http_*` Managed 接口引擎拥有，可信原子再通过 StopHttp 的 `sso_connection_runtime` 取得最小运行投影。客户端能力类接口统一调用 `/apiengine/{ApiEngineKey}?OsClient=`；标准伙伴协议使用应用声明的 `ApiAddress`，其中 `{OsClient}`、`{ConnectionKey}` 由动态路由安全提取并覆盖同名外部参数。
+
+## Secret 与证书
+
+- `ClientSecretSettingKey` 等字段只存 `mci_system_setting` Key。
+- 第三方 Client Secret 和私钥证书使用后端 Secret 存储，不出现在日志、导出、包、浏览器或 MCP 回读。
+- 吾码对外 OIDC Client Secret 只存专用密码哈希；不能用 AES/DES 代替验证哈希。
+- SAML 验签/加密公开证书与签名/解密私钥严格区分用途。
+- 证书/签名 Key 轮换要有新旧重叠、伙伴确认、撤销和回滚窗口。
+
+## 网络和 URL
+
+所有外部 Discovery、JWKS、Metadata、Token、UserInfo 地址先过 HTTPS/SSRF 检查。默认拒绝回环、私网、链路本地、带用户信息 URL 和 DNS 重绑定；内网 IdP 只能由管理员显式开启并用网络出口白名单补强。
+
+Redirect/Logout/ACS/CAS service 使用规范化后的绝对 URL 精确比较。不要允许通配符、子域后缀、前缀或 fragment。反向代理下使用可信外部 Origin，不能根据任意 Host/Header 构造安全回调。
+
+## 账号与角色
+
+默认 `BoundOnly`。JIT 需要：
+
+- 稳定 Subject 与账号唯一性。
+- 非管理员默认角色。
+- 外部角色到 RoleId 的显式 allowlist。
+- 离职、禁用、角色收回与冲突处理。
+- 创建、匹配、拒绝和变更审计。
+
+这些规则由 Managed `sso_resolve_federated_identity` 编排。JIT 创建最终调用精确受限的 `V8.Method.CreateFederatedUser` 原子，并用平台专用带盐密码哈希写入不可登录的随机初始密码；不得回退到 DES，也不得把外部角色名直接写成平台 RoleId。
+
+不能把外部 `admin` 字符串、邮箱域或昵称直接解释为平台管理员。
+
+## LegacyToken 迁移
+
+1. 盘点旧 `ClientSsoApi/ServerSsoApi/TokenName` 和使用系统。
+2. 为每个系统选择 OIDC、SAML2 或 CAS 并建立新连接。
+3. 并行验证登录/退出和账号映射；新入口默认标准协议。
+4. URL 中的旧 Token 读取后立即清理，不写 Referer、日志或分析平台。
+5. 迁移完成后停用旧行；不要继续给新系统复制 LegacyToken。
+
+旧兼容只允许调用同源 `/api/`，绝不把 DiyToken POST 到管理员配置的任意绝对 URL。浏览器只处理 `LegacyCapabilities` 已返回连接中明确登记的 `TokenName`；不得恢复“只要 URL 出现 `?token=` 就自动登录”的无配置旁路。

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

@@ -1,53 +1,53 @@
-# 外部身份源登录吾码
-
-## 目标流程
-
-外部身份源只证明主体身份。回调完成后按当前租户查找绑定/受控 JIT 用户，重新确认 `sys_user` 仍启用，再签发 DiyToken。菜单、表、字段、角色、部门与数据范围不从外部 Token 直接继承。
-
-## OIDC RP
-
-必须覆盖：
-
-- Authorization Code；公共客户端使用 PKCE S256。
-- 随机 state、nonce、短时效、一次性消费和原始 Origin 绑定。
-- Discovery 与 JWKS 的 HTTPS、SSRF、issuer 一致性和缓存更新。
-- id_token 签名、算法、issuer、audience、有效期、nonce；必要时再请求 UserInfo。
-- code 不能写日志、URL 清理、回调错误不泄露 Token/Secret。
-- `client_secret_basic`、`client_secret_post` 或 `none` 与伙伴注册一致。
-
-禁止 Implicit、Password Grant、宽松回调前缀、关闭签名或仅解码 JWT 不验签。
-
-## SAML SP
-
-必须覆盖：
-
-- SP Metadata、AuthnRequest、RelayState、ACS 与可选 SLO。
-- 浏览器回调使用 `/api/Sso/SamlCallback`，Assertion Consumer Service 使用 `/api/Sso/SamlAcs`。
-- Response/Assertion 签名、Destination、Issuer、Audience、时间窗口、InResponseTo。
-- Request ID 与 Assertion/Response 重放保护。
-- 加密断言时使用本租户解密私钥；验签只用伙伴公开证书。
-- NameID/Claim 到稳定 Subject 的明确规则。
-
-不能因为伙伴证书配置困难而在生产关闭签名校验。
-
-## CAS Client
-
-- service 必须是精确、受控的吾码回调 URL。
-- CAS 1.0 `/validate`、2.0 `/serviceValidate`、3.0 `/p3/serviceValidate` 按配置解析。
-- Service Ticket 单次使用、短时效、绑定 service；失败响应不能当作用户属性。
-- CAS 根地址生产使用 HTTPS，并经过 SSRF 检查。
-
-## 用户解析顺序
-
-1. 规范化 `OsClient`、连接方向和协议。
-2. 提取稳定 Subject；拒绝空值、控制字符和不稳定昵称。
-3. 先查 `mci_user_external_identity` 的精确绑定。
-4. `BoundOnly` 未绑定即拒绝；`JitMatch/JitCreate` 仅按已审核映射运行。
-5. 重新读取 `sys_user`，确认未删除、未停用。
-6. 签发 DiyToken，写不含凭据的 SSO 审计。
-
-步骤 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 和角色映射。
-
-## 浏览器回调
-
-弹窗消息必须同时校验 `event.source`、精确 `event.origin`、消息类型和 ConnectionKey。回调只传 90 秒左右的一次性票据；登录页再用该票据换 DiyToken。不要通过 `postMessage('*')`、URL fragment 或 Query 传 DiyToken。
+# 外部身份源登录吾码
+
+## 目标流程
+
+外部身份源只证明主体身份。回调完成后按当前租户查找绑定/受控 JIT 用户，重新确认 `sys_user` 仍启用，再签发 DiyToken。菜单、表、字段、角色、部门与数据范围不从外部 Token 直接继承。
+
+## OIDC RP
+
+必须覆盖：
+
+- Authorization Code；公共客户端使用 PKCE S256。
+- 随机 state、nonce、短时效、一次性消费和原始 Origin 绑定。
+- Discovery 与 JWKS 的 HTTPS、SSRF、issuer 一致性和缓存更新。
+- id_token 签名、算法、issuer、audience、有效期、nonce；必要时再请求 UserInfo。
+- code 不能写日志、URL 清理、回调错误不泄露 Token/Secret。
+- `client_secret_basic`、`client_secret_post` 或 `none` 与伙伴注册一致。
+
+禁止 Implicit、Password Grant、宽松回调前缀、关闭签名或仅解码 JWT 不验签。
+
+## SAML SP
+
+必须覆盖：
+
+- SP Metadata、AuthnRequest、RelayState、ACS 与可选 SLO。
+- 浏览器回调使用 `/api/Sso/SamlCallback`，Assertion Consumer Service 使用 `/api/Sso/SamlAcs`。
+- Response/Assertion 签名、Destination、Issuer、Audience、时间窗口、InResponseTo。
+- Request ID 与 Assertion/Response 重放保护。
+- 加密断言时使用本租户解密私钥；验签只用伙伴公开证书。
+- NameID/Claim 到稳定 Subject 的明确规则。
+
+不能因为伙伴证书配置困难而在生产关闭签名校验。
+
+## CAS Client
+
+- service 必须是精确、受控的吾码回调 URL。
+- CAS 1.0 `/validate`、2.0 `/serviceValidate`、3.0 `/p3/serviceValidate` 按配置解析。
+- Service Ticket 单次使用、短时效、绑定 service；失败响应不能当作用户属性。
+- CAS 根地址生产使用 HTTPS，并经过 SSRF 检查。
+
+## 用户解析顺序
+
+1. 规范化 `OsClient`、连接方向和协议。
+2. 提取稳定 Subject；拒绝空值、控制字符和不稳定昵称。
+3. 先查 `mci_user_external_identity` 的精确绑定。
+4. `BoundOnly` 未绑定即拒绝；`JitMatch/JitCreate` 仅按已审核映射运行。
+5. 重新读取 `sys_user`，确认未删除、未停用。
+6. 签发 DiyToken，写不含凭据的 SSO 审计。
+
+步骤 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 和角色映射。
+
+## 浏览器回调
+
+弹窗消息必须同时校验 `event.source`、精确 `event.origin`、消息类型和 ConnectionKey。回调只传 90 秒左右的一次性票据；登录页再用该票据换 DiyToken。不要通过 `postMessage('*')`、URL fragment 或 Query 传 DiyToken。