@xgent-ai/skills 0.7.7 → 0.7.9

package/skills/phoenix-ui/SKILL.md

@@ -7,7 +7,7 @@ metadata:
   internal: true
   version: 0.1.0
   source: skills/phoenix-ui/src
-  source_sha256: 91409c0e7e0eb2e3b013f79a49bc0e897da22cd1adef8fb3eed370a834a79fc9
+  source_sha256: 3a90920fc0c5443a5a657a49d83dfc899503fe8f237b5f8272d4143195e62d63
 ---
 
 Phoenix UI provides local design tools for any UI project, including standalone sites, applications, and embedded interfaces. Follow the target project's product truth, accepted direction, and design rules; derive platform and host constraints from that project's own context. Use the command references to create complete, accessible interfaces with a clear visual direction.

package/skills/phoenix-ui/scripts/ENGINE.json

@@ -2,38 +2,38 @@
   "schemaVersion": 1,
   "distribution": "release",
   "toolVersion": "0.1.0",
-  "npmPackageVersion": "0.7.7",
-  "sourceCommit": "6a01c326c1f3dd0390151882e6e03205ea1dc6b8",
-  "sourceTree": "34fecf8ada60947a681e278760e30fd658211b91",
+  "npmPackageVersion": "0.7.9",
+  "sourceCommit": "7229a8ba08f7d37bc37530e00e4d933903f1b5cf",
+  "sourceTree": "8f59135bcd1e6ef1cb1db6974fae9dffac0ff0c7",
   "sourceState": "dirty",
-  "sourceInputSha256": "466dc76c552ee4b79049cbe41852d84dc010c25f31ecf3062b79605f5d557e31",
+  "sourceInputSha256": "3088d11390806058b527f5bbc4b0a4860f34c7cdd52a104d7806f8c46fccf310",
   "bundleSchema": 1,
-  "bundleSha256": "637ec2dbcaad98d0765bf0d73fd2fc5935004212288c69f3f5798a13fb584c78",
+  "bundleSha256": "edc5115dbdd52a5b834ae242ffd46c76d76e6c24ae10ec2dfc6a13cc0ac28921",
   "reviewSchema": 1,
   "engines": {
     "darwin-arm64": {
       "asset": "phoenix-ui-darwin-arm64",
-      "sha256": "b688b6d70b37270a451cfd8002c6139ade3197cc3458da54201d4764cf77fd95",
-      "size": 18350288,
-      "url": "https://download.xgent.ai/vendor/phoenix-ui/v0.7.6/darwin-arm64/phoenix-ui-darwin-arm64"
+      "size": 18366832,
+      "sha256": "b843dce661874b9ab7a4799c529193a6cdc7415e6a0a78a5a28e5c87072df0eb",
+      "url": "https://download.xgent.ai/vendor/phoenix-ui/v0.7.9/ci-41410951647/darwin-arm64/phoenix-ui-darwin-arm64"
     },
     "darwin-x64": {
       "asset": "phoenix-ui-darwin-x64",
-      "sha256": "f8b59faf9bda40347ce9fec8abd2001414aa22b705cddb01e6ed30df487bb15c",
-      "size": 20838208,
-      "url": "https://download.xgent.ai/vendor/phoenix-ui/v0.7.6/darwin-x64/phoenix-ui-darwin-x64"
-    },
-    "linux-x64": {
-      "asset": "phoenix-ui-linux-x64",
-      "sha256": "c233dd554bc033d339aa568704e136d6d0d949f8fc8e8ea0a3e3ab69d5cb329b",
-      "size": 22931072,
-      "url": "https://download.xgent.ai/vendor/phoenix-ui/v0.7.6/linux-x64/phoenix-ui-linux-x64"
+      "size": 20858712,
+      "sha256": "9af56bc51bdf6096228fe36ffe7096b85ce0653a21a29554938d94f596d48681",
+      "url": "https://download.xgent.ai/vendor/phoenix-ui/v0.7.9/ci-41410951647/darwin-x64/phoenix-ui-darwin-x64"
     },
     "linux-arm64": {
       "asset": "phoenix-ui-linux-arm64",
-      "sha256": "6f846f717e7403d419fcab253057ab35355fd00ee8b247235fe63c2fb2d65548",
       "size": 19768520,
-      "url": "https://download.xgent.ai/vendor/phoenix-ui/v0.7.6/linux-arm64/phoenix-ui-linux-arm64"
+      "sha256": "174507b2150985556544ba7cfb61613d054e9908750defb123b981c54b3ec297",
+      "url": "https://download.xgent.ai/vendor/phoenix-ui/v0.7.9/ci-41410951647/linux-arm64/phoenix-ui-linux-arm64"
+    },
+    "linux-x64": {
+      "asset": "phoenix-ui-linux-x64",
+      "size": 22950336,
+      "sha256": "ec268516406c0660116c9a1c912bad46580916e8645778dccea2942b8f4cb3a2",
+      "url": "https://download.xgent.ai/vendor/phoenix-ui/v0.7.9/ci-41410951647/linux-x64/phoenix-ui-linux-x64"
     }
   }
 }

package/skills/phoenix-ui/scripts/phoenix-bootstrap.cjs

@@ -67,25 +67,13 @@ function projectRoot(start) {
   const initial = fs.realpathSync(path.resolve(start));
   let dir = initial;
   for (;;) {
-    if (fs.existsSync(path.join(dir, '.phoenix-ui/install/active.json')) || fs.existsSync(path.join(dir, '.git'))) return dir;
+    if (['.agents', '.claude', '.cursor', '.gemini', '.github', '.grok'].some(provider => fs.existsSync(path.join(dir, provider, 'skills/phoenix-ui/scripts/ENGINE.json'))) || fs.existsSync(path.join(dir, '.git'))) return dir;
     const parent = path.dirname(dir);
     if (parent === dir) return initial;
     dir = parent;
   }
 }
 
-// The transactional installer writes this receipt last. It names the package and
-// bundle, not a platform, so one project serves every supported engine target.
-function verifyReceipt(project, manifest) {
-  const file = path.join(project, '.phoenix-ui/install/active.json');
-  if (!fs.existsSync(file)) return;
-  const receipt = JSON.parse(fs.readFileSync(file, 'utf8'));
-  if (receipt.schema_version !== 1 || receipt.manifest?.version !== manifest.data.npmPackageVersion
-      || receipt.manifest?.sha256 !== manifest.data.bundleSha256) {
-    throw failure(`Project receipt requires a different Phoenix package. Run @xgent-ai/skills@${receipt.manifest?.version || manifest.data.npmPackageVersion} for this project.`);
-  }
-}
-
 function verifyEngine(file, manifest, target, env = process.env) {
   const meta = manifest.data.engines[target];
   if (!meta) throw failure(`This development package has no verified engine for ${target}.`);
@@ -313,13 +301,10 @@ async function main(args, options = {}) {
         }
         else releaseDir = path.resolve(args[i]);
       }
-      verifyReceipt(project, manifest);
       const binary = await installEngine(manifest, target, project, releaseDir, env);
       process.stdout.write(json ? `${JSON.stringify({ status: 'installed', toolVersion: manifest.data.toolVersion, target, binary })}\n` : `Phoenix UI ${manifest.data.toolVersion} ready: ${binary}\n`);
       return 0;
     }
-    // Installer verbs replace or roll back the installed package themselves.
-    if (!['install', 'migrate'].includes(args[0])) verifyReceipt(project, manifest);
     const binary = verifyEngine(enginePath(manifest, target, env), manifest, target, env);
     clearReminders(project, manifest, env);
     const childEnv = { ...env, PHOENIX_UI_SELF: options.self || process.argv[1], PHOENIX_UI_SKILL_DIR: options.skillDir || path.resolve(__dirname, '..') };
@@ -365,5 +350,5 @@ async function main(args, options = {}) {
   }
 }
 
-module.exports = { TARGETS, platformTarget, manifestAt, enginePath, verifyEngine, verifyReceipt, setupCommand, shellQuote, proxyFor, installEngine, sha256, main };
+module.exports = { TARGETS, platformTarget, manifestAt, enginePath, verifyEngine, setupCommand, shellQuote, proxyFor, installEngine, sha256, main };
 if (require.main === module) main(process.argv.slice(2)).then(code => { process.exitCode = code; }).catch(error => { process.stderr.write(`${error.message}\n`); process.exitCode = 4; });

package/skills/portal-external-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: portal-external-app
-description: '用于把独立仓库、以 Docker 镜像交付的外部服务接入 XGENT 门户或评审交付物。覆盖 manifest、注册、鉴权、成员客户端与终端用户身份、/svc 路由、健康检查与一盒联调。'
+description: '用于把独立仓库、以 Docker 镜像交付的外部服务接入 XGENT 门户或评审交付物。覆盖 manifest、注册、鉴权、MCP OAuth 发现、成员客户端与终端用户身份、/svc 路由、健康检查与一盒联调。'
 when_to_use: "用户会说「把我们服务接进门户」「manifest 怎么填」「/svc 路由不通」时。"
 ---
 
@@ -25,7 +25,8 @@ when_to_use: "用户会说「把我们服务接进门户」「manifest 怎么填
 | 服务账号写进应用空间的文件，要让作者本人在文件管理里看得到 | [references/files-member-docs.md](references/files-member-docs.md)：`onBehalfOf` 署名、成员只读可见、成员内容隐私开关 |
 | 门户成员的原生客户端（iOS/Android/桌面）登录与刷新、设备凭证、停用后失效时效、服务端成员查询与事件 | [references/native-clients.md](references/native-clients.md) |
 | 顾客/学生等终端用户的完整能力、租户用户中心、托管注册登录、账号与隐私治理 | [references/end-users.md](references/end-users.md)：先区分成员与终端身份，再按任务读认证协议或生命周期接口 |
-| 用户以 CLI、MCP、个人自动化调用 App，或接入门户多服务用户密钥与服务发现 | [references/cli-user-keys.md](references/cli-user-keys.md)：受审 `cliAccess` 声明、标准绑定与通用目录；不改门户业务代码 |
+| CLI、MCP、个人自动化使用门户用户访问密钥，或接入多服务用户密钥目录 | [references/cli-user-keys.md](references/cli-user-keys.md)：受审 `cliAccess` 声明、标准绑定与通用目录 |
+| MCP/OAuth 客户端发现元数据，或标准 `/.well-known/…/svc/<key>` 返回 HTML/404 | [references/oauth-discovery.md](references/oauth-discovery.md)：`oauthDiscovery` 声明、匿名元数据、审批、固定提案交付与撤销 |
 | 为外部服务写/审对接契约文档 | [references/contract-doc-template.md](references/contract-doc-template.md) |
 | 有「每租户最多几个 X」的配额诉求（选模型、数值谁配、已用怎么来） | [references/quota-and-seats.md](references/quota-and-seats.md) |
 | 一个配置项该放哪（环境变量 / 平台级或租户级管理页 / 应用内设置 / 用户偏好），`requiredEnvNotes`、`adminPages` 与 service `tenantConfig` 怎么写 | [references/config-placement.md](references/config-placement.md) |

package/skills/portal-external-app/references/oauth-discovery.md

@@ -0,0 +1,94 @@
+# MCP / OAuth 标准发现接入
+
+适用于 App 自己提供 OAuth 元数据，客户端从门户 origin 查找标准发现地址的场景。
+`oauthDiscovery` 只配置路由；门户透明转发，不生成 JSON，不实现 App 的授权、token、scope 或客户端回调。
+门户用户访问密钥与多服务目录使用 `cliAccess`，见 [CLI 用户密钥](cli-user-keys.md)，两者不能互相替代。
+
+## 前置与声明
+
+目标门户须已部署 OAuth 发现迁移、API/controller 和统一 v2 网关模板（container/process 均支持）。
+不支持 v1；不依赖 `PUBLIC_SITES_ENABLED`、Sites 权益或 CSP strict 开关。安装新版 SDK、
+whoami 成功、后端 healthy 都不能证明这些平台前置已满足；能力未部署时交平台升级，不逐 App 手改 Caddy。
+需要 TypeScript 契约时，`@xgent/shared` 从 0.11.1 提供 `OAuthDiscovery`。
+
+将以下片段合入 App 自己的完整 `app.manifest.json`，递增 `version`：
+
+```json
+{
+  "oauthDiscovery": {
+    "authorizationServer": true,
+    "protectedResources": ["/mcp"]
+  }
+}
+```
+
+- 非空声明要求最终清单有 `deployDescriptor` 或 `serviceBaseUrl`，服务须可用。需要常驻时在既有 descriptor 设置 `alwaysOn: true`。
+- 只接受 `authorizationServer`（布尔值，省略为 false）与 `protectedResources`（路径数组，省略为空）。仅资源服务器可以只声明后者。
+- 路径从 App 服务根起算，填 `/mcp`，不填 `/svc/<key>/mcp`。`/` 表示根资源；其他路径由非空的字母、数字、`.`、`_`、`~`、`-` 段组成。单独的 `.`/`..` 段、空段、尾斜线、URL、百分号编码、query、fragment、空白、通配符均拒绝。
+- 路径去重并排序；声明中不能指定 issuer、resource、域名或 upstream。这些元数据值由 App 的响应提供。
+
+## 路径与元数据
+
+下表标准入口位于门户 origin；后端路径是不带 `/svc/<key>` 的 App 内部路径。
+
+| 声明 | 标准入口 | 后端匿名 GET/HEAD 路径 |
+| --- | --- | --- |
+| `authorizationServer: true` | `/.well-known/oauth-authorization-server/svc/<key>` | `/.well-known/oauth-authorization-server` |
+| 资源 `/mcp` | `/.well-known/oauth-protected-resource/svc/<key>/mcp` | `/.well-known/oauth-protected-resource/mcp` |
+| 资源 `/` | `/.well-known/oauth-protected-resource/svc/<key>` | `/.well-known/oauth-protected-resource` |
+
+设门户 origin 为 `$PORTAL_ORIGIN`（无尾斜线），App key 为 `$LISTING_KEY`：issuer 应为
+`$PORTAL_ORIGIN/svc/$LISTING_KEY`；根资源的 resource 与之相同，`/mcp` 资源在其后加 `/mcp`。
+OAuth authorize/token/register 等端点继续使用 App 既有外部地址。原 `/svc/<key>/.well-known/…`
+嵌套地址继续可用；网关保留方法、query、Host、响应内容与状态，App 错误不会被修补为有效元数据。
+
+## 提交、审批与生效
+
+1. 使用 App 的发布令牌及目标配置；已有 `.xgent-registry.env` 时让 CLI 自行读取，不打印令牌。缺少配置时从目标门户「开发者应用 → 本 App → 凭证 → 生成配置文件」取得，确认含 LISTING_KEY、TARGET_XGENT_PLATFORM、XGENT_RELEASE_TOKEN，chmod 600 并加入 gitignore。按 [注册与一盒](registration-and-onebox.md) 准备完整清单，再提交：
+
+   ```bash
+   npx @xgent/release-cli publish --manifest app.manifest.json
+   ```
+
+   HTTP 发布也只能通过 `manifest` 字段携带完整清单，不能提交独立 `oauthDiscovery` 表单字段。
+2. 保存 `proposalId`。新增、修改和撤销均按实际差异进治理审核；等价重排/去重不制造差异。待审不改变已批准路由，由平台管理员核对并批准；发布令牌不能代替管理员审批。
+3. 用 release-cli ≥0.7.0 查询这一次提案：
+
+   ```bash
+   npx @xgent/release-cli status --proposal-id <proposalId> --wait
+   ```
+
+   `delivery.state=applied` 才表示本次后端与网关目标已确认。`pending` 等待，`failed` 按失败阶段交平台处理，`superseded` 追踪取代它的新提案；`unknown` 或缺少 delivery 均不能报生效。`publish --wait` 不等待人工审批；需要连审批一起等时用 `--wait-review`。
+4. 再做真实 HTTP 与客户端验收。发布成功、清单 applied、后端 ready 均不能代替此步骤。
+
+仅改发现声明不触发后端重部署；网关失败由平台管理员重试网关并核对本提案 revision，不用重发相同镜像。完整发布命令及凭据准备可使用 `xgent-app-release` skill；本参考的契约不要求访问门户源码。
+
+## 验收与排错
+
+从可信的目标配置取得 `PORTAL_ORIGIN`、`LISTING_KEY`，以下请求不携带登录 cookie 或 Bearer token。
+按实际声明替换资源路径；`/mcp` 示例：
+
+```bash
+curl -i "$PORTAL_ORIGIN/.well-known/oauth-authorization-server/svc/$LISTING_KEY"
+curl -I "$PORTAL_ORIGIN/.well-known/oauth-authorization-server/svc/$LISTING_KEY"
+curl -i "$PORTAL_ORIGIN/.well-known/oauth-protected-resource/svc/$LISTING_KEY/mcp"
+curl -I "$PORTAL_ORIGIN/.well-known/oauth-protected-resource/svc/$LISTING_KEY/mcp"
+curl -i "$PORTAL_ORIGIN/svc/$LISTING_KEY/.well-known/oauth-authorization-server"
+curl -i "$PORTAL_ORIGIN/svc/$LISTING_KEY/.well-known/oauth-protected-resource/mcp"
+```
+
+- 标准与原嵌套地址 GET 均为 200 JSON，字段相同；HEAD 同状态、JSON Content-Type、无正文。核对 issuer/resource 和既有 OAuth 端点，不只检查 HTTP 200。
+- 已声明标准入口的 POST/PUT/OPTIONS 为 405，含 `Allow: GET, HEAD`；未声明、撤销、额外尾段为 404。使用门户 origin，站点域名继续走自己的站点上下文。
+- 标准地址 404：先查实际获批声明、本次 delivery、服务是否已停止/下架；文件已保存或平台已升级不等于声明已批准。返回 Portal HTML：核对目标 v2 模板及实际加载版本。旧嵌套地址也失败、或返回非 JSON：检查 App 元数据端点。
+- MCP 原匿名请求应继续返回约定的 401 与 `WWW-Authenticate`。元数据 HTTP 通过后，还须用目标客户端走通授权页与回调；WorkBuddy / WorkBuddy AI 等不同回调由 App 负责，不能用网关或夹具检查冒称客户端验收。
+
+交付记录包含目标环境、版本、proposalId、delivery、标准/旧路径 HTTP 和客户端结果；不提供凭据或内部 upstream。
+
+## 替换、撤销与生命周期
+
+省略整个 `oauthDiscovery` 保留已批准值；`null` 或 `{}` 明确清空；对象整体替换，未列出的资源被撤销。
+递增版本、提交完整清单并批准，等待本次 delivery applied，再确认被撤销的标准 URL 为 404。
+撤销发现不删除 App 原元数据端点；移除后端配置时须同时撤销声明。恢复旧声明也须新版本和审批。
+
+声明属于全局 listing，单租户卸载不撤销它。停止服务、下架或删除 listing 会随新网关代撤销路由；
+恢复服务后可恢复获批声明。后端换址时发现与 `/svc` 使用同一运行上游，无需在 App 清单硬编码主机或端口。

package/skills/portal-external-app/references/public-entrypoints.md

@@ -9,11 +9,13 @@
 | 匿名 SPA、分享页面 | `/apps/<listingKey>/…` | 匿名页不先强制 SDK 登录；读取的数据仍需业务授权 |
 | 后端直接返回 HTML、公开回调 | `/svc/<listingKey>/…` | 平台去掉服务前缀；App 自己区分匿名与受保护路由，公开服务应常驻 |
 | 租户站点、独立域名 | `publicEntrypoints` + Sites 服务 | 入口声明、服务特权、平台站点配置、租户权益及路由就绪 |
+| MCP/OAuth 标准元数据发现 | `oauthDiscovery` → 门户 origin 的精确 `/.well-known/…/svc/<key>` | 已部署发现能力的 v2 网关、获批声明及匿名后端元数据；见 [OAuth 发现](oauth-discovery.md) |
 
 前两条已经是正式接入方式，不需要为了每个新 App 请求门户增加根级路径。
 `publicEntrypoints` 是**站点可以绑定的后端入口目录**，不是“在门户根路径新增一条代理”。
 仅声明它，不会让门户根级 `/v`、`/share` 等路径指向你的服务。
 历史根路径属于兼容契约，需要与平台约定数据迁移和切换，不可自行复用或覆盖。
+OAuth 发现只开放声明生成的精确 GET/HEAD 路径，不提供任意根路径代理，也不要求打开 `PUBLIC_SITES_ENABLED`。
 
 ## 2. 后端直出页必须认识外部路径
 

package/skills/portal-external-app/references/registration-and-onebox.md

@@ -14,6 +14,7 @@
     `privilegedServiceScopes` 里的，租户面**一条也勾不到**（见 integration-contract.md §3.1）。
     `scopeLabels` 同时是那个勾选列表的正文——不写就只显示裸 scope 串。
 - 关系：`dependencies`、`exchangeTargets`、`serviceBaseUrl`（`/svc/<listingKey>`）
+- OAuth 标准发现：`oauthDiscovery`（`authorizationServer` 与 `protectedResources`），非空声明要求后端；新增、修改及撤销经治理审批。路径映射、省略/null 语义与真实 HTTP 验收见 [OAuth 发现](oauth-discovery.md)。
 - 终端身份：`endUserRealms:{"mode":"fixed","siteKeys":["customers"]}` 或 `{"mode":"dynamic"}`，
   声明本 App 的身份空间范围；不创建托管 profile/client、不授额度，也不是成员的 publicClient。
   顾客/学生认证与生命周期按 [终端用户接入](end-users.md) 配置；endusers.* 等服务权限经特权审批申请。
@@ -47,6 +48,8 @@
 
 CLI / MCP / 个人自动化使用用户访问密钥时，还须声明独立的 `cliAccess`，不能把整份 `scopes` 当作用户密钥上限。新增、修改和撤回经过发布审批；绑定与发现按 [CLI 用户密钥契约](cli-user-keys.md)，无需在门户登记 App 专属权限分支。先确认目标门户已部署此能力。
 
+MCP 客户端通过 App 自有 OAuth 授权服务器发现元数据时，使用独立的 `oauthDiscovery`；它只声明标准发现路由，不配置用户密钥、OAuth 身份或客户端回调。不能用 `cliAccess`、`publicEntrypoints` 或 `publicClient` 代替。
+
 ⚠️ 规则 3 **读写不分**：背书的是整个命名空间，`files.write` 与 `files.read` 同一条待遇，
 没有「写要额外批一次」这回事。别人的 App 只声明了读，那是它自己的业务选择（它的写面不
 代表用户），不是平台对你的限制 —— 照抄别人的清单当规矩用，会把一个本来合法的功能砍掉。