@xgent-ai/skills 0.3.0 → 0.5.0

package/skills/portal-backend-app/references/gate-and-tokens.md

@@ -1,93 +0,0 @@
-# 自省、四道闸与服务账号（资源服务器契约）
-
-> 提炼自门户仓库 `docs/SSO与App开发指引.md` §7/§9/§12（2026-08），响应形状对照 `apps/api/src/modules/token/index.ts` 实现核实。冲突时以门户仓库为准。
-
-## 1. 令牌自省（introspection）
-
-你的服务**不验 JWT 签名**（HS256 密钥只在 Portal），把 bearer TDT 发给自省端点换已解析声明：
-
-```
-POST {PORTAL}/api/tokens/introspect
-  Authorization: Basic base64(<saClientId>:<saSecret>)   # 服务账号凭证
-  body: { "token": "<待验证的 TDT>" }
-→ 200 { "ok": true, "data": {
-    "active": true, "kind": "user"|"service",
-    "aud": "<安装态 appKey>", "listingKey": "<稳定身份>", "azp": "<代表行事的来源App>"|null,
-    "tenant_id": "...", "user_id": "..."|null, "scopes": [...], "role": "admin"|"user"|null,
-    "isPlatformAdmin": true,
-    "bypass": false, "groups": [...]|null, "permissions": [{ "pid", "scope" }]|null,
-    "aclStamp": "..."|null, "exp": 1730003600
-  } }
-```
-
-硬规则：
-- **信封解包**：声明在 `data` 里，必须 `claims = body.data ?? body`。裸读顶层 `active` 会把一切有效 TDT 误判 401（真实事故）。
-- 无效/已撤销 TDT 也是**成功**的自省，只是 `active:false`——不要当传输错误。
-- `active:true` 始终返回布尔 `isPlatformAdmin`：Portal 每次自省都按 `user_id` 实时检查其是否为**平台租户的 active admin**，与当前 `tenant_id` / `role` / `bypass` 独立；服务态恒为 `false`。该字段是**自省派生信息，不在 TDT JWT claims 里**。
-- 结果缓存到 `exp` 前（上限 60s）；因此吊销和平台管理员身份变更可能有秒级延迟。
-- dev 通道 `x-resource-key` 仅 `DEV_MOCK_OAUTH=true` 时生效且只认门户侧 `FILES_RESOURCE_KEY` 一把；生产一律拒绝，必须走 Basic。
-
-## 2. 四道闸（每个受保护端点）
-
-1. **身份**：`(claims.listingKey ?? claims.aud) === 你的 listingKey`。按 **listingKey**（稳定身份）鉴权而非裸 aud——aud 是安装态 appKey。不匹配 → 401 `INVALID_TOKEN`。
-2. **scope**：所需 scope ∈ `claims.scopes` → 否则 403 `INSUFFICIENT_SCOPE`。
-3. **结构性管理操作**：`claims.role === "admin"`（角色来自 Portal 成员关系，非 TDT claim）→ 否则 403。
-4. **细粒度 ACL**：`claims.bypass || permissions 命中目标 PID`；数据范围取命中授予里**最宽**的（`own`<`team`<`all`）做行级过滤 → 否则 403 `INSUFFICIENT_PERMISSION`。
-
-外加两条恒规则：**租户隔离**一律按 `claims.tenant_id` 收口（永不信任请求体）；**限流**自建 `(aud, tenant)` 每分钟固定窗口。
-
-**平台级跨租户端点另加一道全局闸**：只认服务端自省的 `claims.isPlatformAdmin === true`。不能用 `role === "admin"` / `bypass` 代替（它们只表示 TDT 当前租户），也不能靠 `tenant_id === PLATFORM_TENANT_ID` 推导（平台管理员切到普通租户后仍有全局身份）。拒绝浏览器转发的 Cookie、`X-Is-Platform-Admin` 或 body 字段。
-
-`can(claims, pid)` 实现：`bypass || permissions.some(p => pidMatches(p.pid, pid))`；PID 通配 `app:*` ⊃ `app:page:*` ⊃ `app:page:x.*` ⊃ 精确。批量检查可用 `POST /api/v1/acl/check { token, pids[] }`（同服务账号鉴权）。
-
-## 3. 服务态令牌的授权姿势
-
-`kind:"service"`（client_credentials 签发）**无 `user_id`、整体绕过用户 ACL**：自省返回 `permissions` 空、`bypass=false`、`isPlatformAdmin=false`。对服务态调用**只按 scope 授权**，勿走 PID 门；涉及"用户拥有"的写操作应拒绝服务态。
-
-三种令牌来路对照：
-
-| 来路 | kind | user_id | 授权依据 |
-| --- | --- | --- | --- |
-| 自己前端（宿主注入 / callService） | user | 有 | scope + PID/ACL |
-| 其他 App 令牌交换 | user | 有 | 同上；scope 是交集；`azp`=发起方（出处归因） |
-| 服务账号 client_credentials | service | 无 | 只按 scope |
-
-## 4. 服务账号（M2M）
-
-平台管理员在控制台创建（`/api/console/service-accounts`），`clientId:secret` 走 HTTP Basic。能力：
-
-| capability | 含义 |
-| --- | --- |
-| `token.introspect` | 可调自省/批量检查——独立后端必需 |
-| `client_credentials` | 可自助签发服务态 TDT（受租户策略约束） |
-
-租户访问策略（针对 client_credentials）：`tenantAccess="all"`（任意租户，高风险）或 `"allowlist"`（仅名单内，否则 `TENANT_NOT_ALLOWED`）。新增该能力必须显式选策略，否则 `VALIDATION_FAILED`。
-
-签发服务态 TDT：
-
-```
-POST /api/tokens/service
-  Authorization: Basic base64(<clientId>:<secret>)
-  body: { "grant_type": "client_credentials", "tenant_id": "...", "scope?": "a b c" }
-→ 200 { access_token, token_type:"Bearer", expires_in, scope }
-```
-
-签发 scope = 请求 ∩ 服务账号 scopes（绝不扩张，SA 未授权时**不报错只返空 scope**——调用方必须检查返回的 scope 再用）。
-
-## 5. 宿主代理与管理直连
-
-- `sdk.callService` 只是转发便利层：你的后端仍必须完整四道闸，不要只因请求来自 Portal web 源就信任。
-- **管理控制面直连**（应用配置 tab 用）：门户为管理员铸短时 admin-TDT（`GET /api/admin/apps/:appKey/<svc>-token`，assertAdmin + signTdt，aud=appKey、按需 scope、600s），浏览器直连你的后端读写配置，Portal 不经手敏感配置。参照 files-token / llm-gateway-token。
-
-## 6. TDT 撤销（四把钥匙）
-
-网关每次校验比对四个版本维度，任一 bump 旧令牌立即失效：
-
-| 维度 | 触发 | 影响面 |
-| --- | --- | --- |
-| jti 黑名单 | `POST /oauth/revoke` | 单个 TDT |
-| app version | 应用停用/卸载、Secret 轮换/吊销 | 该应用全部 TDT |
-| user version | 管理员停用/移除用户 | 该用户全部应用 TDT |
-| (user,app) version | 用户撤销该应用授权 | 该用户对该应用的 TDT |
-
-你的自省缓存 ≤60s，所以吊销传导有秒级延迟——安全敏感操作可缩短缓存或直查。

package/skills/portal-backend-app/references/wiring-and-conventions.md

@@ -1,71 +0,0 @@
-# 注册布线、部署接线与平台规范（monorepo 后端 App）
-
-> 提炼自门户仓库 `docs/SSO与App开发指引.md` §3/§4/§7.5/附录 A、`docs/用量统计服务接入指引.md`、CLAUDE.md 及历史事故（2026-07）。冲突时以门户仓库为准。
-
-## 1. 注册链（单一事实源在代码）
-
-```
-①代码注册表                    ②市场清单                  ③安装快照         ④运行时
-acl/manifests.ts + LISTING_DEFS ─seed─► marketplace_listings ─install─► apps 行 ─► SDK init.acl / introspection
-```
-
-| 声明什么 | 写在哪 |
-| --- | --- |
-| ACL Manifest | `apps/api/src/modules/acl/manifests.ts`（按 listingKey 集中定义） |
-| listing（scopes/navItems/exchangeTargets/serviceBaseUrl/依赖…） | `apps/api/src/db/provisioning.ts` 的 `LISTING_DEFS` |
-| 服务账号 | 同文件 `SA_DEFS`；约定 `clientId = <key>-server`，capability `token.introspect` |
-| 跨应用交换 | 同文件 `EXCHANGE_WIRING`（`{ 发起方: [目标...] }`） |
-| 内容类型（如用内容服务） | `apps/api/src/modules/content/schemas.ts`，owner=listingKey |
-
-升级 Manifest = 改 `manifests.ts` 的 version+内容 → 重新 seed/发布清单 → 租户同步更新。`db:seed` 是 portal-only + **破坏性**（重生成 UUID、会话失效）；App 自己的种子写成独立**非破坏性**脚本。
-
-**scope 命名空间**（写时校验 `market/service.ts::validateScopes`）：一条清单只能声明 平台基础 scope ∪ 自己命名空间（`<listingKey>.` 前缀，连字符 key 接受下划线变体如 `llm_gateway.*`）∪ 已声明 `exchangeTargets` 的目标命名空间。App 命名空间 scope 随清单入库，**无需**改 `packages/shared/src/scopes.ts`；配 `scopeLabels` 三语文案。
-
-平台基础 scope 速查：`userinfo.read`、`directory.read`（+`directory.email.read` 含邮箱）、`notification.send`（+`.others` 跨用户）、`inbox.read`、`settings.read/write`、`widget.write`、`audit.write`、`scheduler.read/write`、`content.read/write`。
-
-## 2. 部署接线 checklist（新建 App 漏一项生产就出事）
-
-| 接线 | 位置 | 漏掉的症状 |
-| --- | --- | --- |
-| `/svc/<key>` 白名单 | `deploy/caddy/Caddyfile` | 生产 404（网关白名单 map 收口，未注册=路由不可达） |
-| **Caddy 全局配置两条不可逆** | 两份 Caddyfile 的 `admin localhost:2019` 不许改回 `admin off`；`ProcessDriver.reloadRouting` 必须是 `systemctl reload`（不是 `restart`），且与 `deploy.sh` 的 sudoers 授权**逐字一致** | 关 admin ⇒ 三个 flavor 的热重载全部**静默**失效（只剩一行 warn）；改回 restart ⇒ 请求处理器拆掉自己正在应答的那条连接，调用方在数据已落库之后拿到 GOAWAY + 无响应体（2026-08-19 事故）。门是 `verify-caddy-dynamic` |
-| compose profile | `deploy/docker-compose.yml` 加 `app-<key>`（同 runtime 镜像 + `command: bun --filter @xgent/<key>-server`） | 容器起不来 |
-| 按需部署注册表 | `apps/api/src/modules/deploy/registry.ts` 的 `DEPLOYABLE_APP_SERVICES` | 生产卡「服务正在部署」门 |
-| **Dockerfile COPY 新 workspace** | 根 `Dockerfile` | 本地全绿、镜像构建才炸（真实事故） |
-| 前端构建 | `build:apps` 保持**串行**（并行 OOM） | CI/构建机 OOM |
-| dev:all | 根 `package.json` concurrently 挂 server+app | 本地起不齐 |
-
-容器/生产统一监听 8080（本地 dev 各用自己的 4xxx）；反代通用规则 `/svc/<key>/* → <key>-server:8080`。宿主运行时按 listing `serviceBaseUrl` 解析服务地址（无烘焙注册表），新增后端无需重建门户前端。
-
-## 3. API 与数据规范（评审必查）
-
-- **HTTP 状态码只反映传输/路由层**：业务成功/失败一律 `200 + {ok, data|error}`；不用 201/204；数据不存在 = `200 + data:null` 不是 404；4xx/5xx 只留参数结构错/未登录/未授权/真故障。
-- **列表服务端分页**：复用 `Page<T>` 契约与现有 helpers（所有 admin/console 列表页同款）。
-- **字典表**（租户级可维护枚举/分类）：排序列固定 `sort integer NOT NULL DEFAULT 0`，查询 `orderBy(asc(sort), asc(name))`，创建 `sort: body.sort ?? 0`、更新 `if (body.sort !== undefined)`。**例外**：树/兄弟次序（章节树、子母题）保留 `seq`，语义是序号不是字典排序。
-- **迁移手写**：`drizzle-kit generate` 在本仓已知损坏——迁移 SQL 手写进 server 的 migrations 目录。
-- **审计**：不自建审计表/页，`POST /api/v1/audit`（scope `audit.write`，用当次用户 TDT），best-effort 不阻断业务。
-- **不做「同步通讯录」**：成员一律 `@xgent/portal-ui` 的 `UserPicker` curated 按需挑选。
-
-## 4. 用量上报（如需计量/计费）
-
-心智模型：**日桶（UTC 日切）+ 桶内绝对值幂等覆写**。上报的是整桶重算的绝对值不是增量（重试/补报天然幂等）；唯一键 `(tenantId, metricKey, day, dimsKey)`。
-
-1. **登记指标**：`packages/shared/src/usage.ts` 的 `USAGE_METRICS`（key 前缀必须=你的 listingKey；kind 选对：counter=流量求和 / gauge=水位取峰值，选错聚合口径灾难；dims 白名单防高基数——别放 userId/requestId）。这是**仓内 App** 的路径；manifest 注册的外部 App 改在自己 manifest 的 `usageMetrics` 里声明（治理档，见 portal-external-app skill），运行时注册表 = 内置 ∪ listing 声明。
-2. **服务账号三件套**：capabilities += `client_credentials`、scopes += `usage.report`、`ownerAppKey` = listingKey（`SA_DEFS` 加 `usageReporter: { ownerAppKey }`，`ensureServiceAccount` 幂等补齐）。`metricKey` 前缀必须等于令牌 `azp`——别的 SA 报你的指标整批拒收。
-3. **上报**：按租户铸服务态令牌（**检查返回 scope 含 `usage.report`**——SA 未授权时不报错只返空 scope，应视为可重试失败；`APP_NOT_INSTALLED`/`APP_DISABLED`/`TENANT_NOT_ALLOWED` 才是该租户永久跳过）→ `POST /api/v1/usage/report { records:[{tenantId, metricKey, day, dims?, value}] }`，单批 ≤500、all-or-nothing、`rejected` 非空响亮 log。
-4. 参考实现：counter+水位线 `apps/llm-gateway-server/src/lib/usage-report.ts`；gauge+快照 files。
-
-## 5. 应用配置 tab（租户级配置三件套）
-
-不在微应用里自建「设置」页；配置收口平台应用配置页：
-
-1. server 暴露 `GET/PUT /api/v1/settings`（四道闸，写操作落 ACL action）；
-2. `apps/api/src/modules/apps/index.ts` 加 `GET /api/admin/apps/:appKey/<key>-token`（assertAdmin，signTdt 铸 aud=appKey、按需 scope 的 600s admin-TDT，无 consent 门）；
-3. `apps/web/src/lib/<key>-config-api.ts` + `AppForm.tsx` 按 `form.scopes.includes("<key>.…")` 条件挂 Section（参照 `showStorage`/`showGateway`），浏览器直连你的后端。
-
-## 6. 本地 dev 要点
-
-- 一把起齐 `bun run dev:all`；绝不叠跑单个 dev 脚本（Vite 端口自增会抢相邻 App 端口，iframe 加载错应用）。重起先清干净旧监听。
-- 非生产下部署门自动视作 ready，本地不会卡「服务正在部署」。
-- 种子账号均 `@xgent.ai`：`rockie`（晨光 admin + 平台管理员）、`liming`（晨光 user/星网 admin，**无 2FA，脚本登录用它**）、`chenjing`（admin，开了 2FA）。
-- 验证脚本放 `apps/<key>-server/scripts/verify-*.ts` 并挂进 `apps/api/scripts/verify-all.ts`；交付标准 = 本服务 verify 全绿 + `bun run verify:all` 不回归。

package/skills/xgent-init/references/external-app-CLAUDE.template.md

@@ -1,249 +0,0 @@
-# CLAUDE.md
-
-行为准则，用来减少常见的 LLM 编码错误。与项目自身的规范合并使用。
-
-**取舍**：这些准则偏向审慎而非速度。琐碎任务自行判断。
-
-## 1. Think Before Coding
-
-**不要假设。不要藏起困惑。把取舍摆出来。**
-
-动手之前：
-- 明确说出你的假设。不确定就问。
-- 有多种解释时全部列出来——不要默默选一个。
-- 有更简单的做法就说出来。该反驳时反驳。
-- 有不清楚的地方就停下。指出困惑在哪。问。
-
-## 2. Simplicity First
-
-**用最少的代码解决问题。不做预留。**
-
-- 不做没被要求的功能。
-- 不为一次性代码造抽象。
-- 不加没被要求的「灵活性」「可配置性」。
-- 不为不可能发生的场景写错误处理。
-- 写了 200 行而它可以是 50 行，就重写。
-
-自问：「资深工程师会不会觉得这写复杂了？」会，就简化。
-
-## 3. Surgical Changes
-
-**只碰必须碰的。只清理自己造成的混乱。**
-
-改既有代码时：
-- 不「顺手改进」相邻代码、注释、格式。
-- 不重构没坏的东西。
-- 匹配既有风格，哪怕你会用别的写法。
-- 发现无关的死代码就说出来——不要删。
-
-自己的改动造成孤儿时：
-- 删掉**因你的改动**而不再被使用的 import / 变量 / 函数。
-- 不删既有的死代码，除非被要求。
-
-检验标准：每一行改动都能直接追溯到用户的诉求。
-
-## 4. Goal-Driven Execution
-
-**定义成功标准。循环到可验证为止。**
-
-把任务转成可验证的目标：
-- 「加校验」→「为非法输入写测试，然后让它们通过」
-- 「修 bug」→「写一个能复现它的测试，然后让它通过」
-- 「重构 X」→「保证重构前后测试都过」
-
-多步任务先说一句计划：
-```
-1. [步骤] → 验证：[检查点]
-2. [步骤] → 验证：[检查点]
-```
-
-## 5. Evidence & Quotation
-
-**凡引用必见原文。没读到的不写。**
-
-- 引用任何文件的措辞、编号、数值、状态、命令或日期前，先亲眼读到那段原文；不凭上下文推断补写，不把「大概如此」写成事实。
-- 工具回显被截断（长文件只给首尾）时，中段是**未知**：要引用就先用 offset / grep / obs_recall 回读定位，再引。
-- 正式产物（CR、计划、运维手册、commit message、给用户的事实陈述）里每一处「据 X 说 Y」，X（文件与段落）与 Y（内容）都要能当场指出。
-- 发现引用与原文不符：全仓搜出同一错误的所有副本一并修正，并向负责人说明，不留两处互相矛盾的版本。
-
----
-
-## Project Conventions
-
-本仓交付的是 XGENT.ai Portal 的一个 App：`<APP_KEY>`（<APP_NAME>，`type: [micro|service]`）。代码在本仓，**清单事实源也在本仓**（`app.manifest.json`）；门户仓里没有它的副本。
-
-### 本地开发
-
-[填：起本仓的命令、端口、依赖的基础设施容器、测试与 verify 的入口。写清「一把起齐」的那条命令，以及最容易踩的启动坑。]
-
-- **缺服务、缺容器就停下来问，不要擅自装。** 如果遇到本地开发环境缺少依赖的服务或容器，停下来要求用户协助或确认是否安装环境依赖，不要擅自下载镜像启动新的容器。
-
-### `key` 是四位一体的，永不改
-
-```
-listingKey == TDT 的 aud == 安装态 appKey == /svc/<APP_KEY> == scope 命名空间
-```
-
-改 key **等于换一个 App**：已安装租户、已授出的 scope、已签发的令牌、反代路由全部对不上。带连字符的 key，scope 命名空间用下划线（`<app_key>.read`），两种写法门户都认。
-
-### 清单事实源是本仓的 `app.manifest.json`
-
-> 字段全集、校验规则与注册路径：`portal-external-app` skill（`micro` 型的 navItems / dashboardWidgets / ACL 另见 `portal-micro-app`）。
-
-改了清单内容就 **bump `version`**——产物与清单版本漂了没有任何机制会发现。
-
-- **字段是安装期快照**：改清单对**已安装租户零影响**，必须显式同步（提案批准 / `register-app --prod` 都会做），而这件事**本地永远测不出来**（本地是全新安装）。
-- **只增不减**：`scopes` / `dependencies` / `exchangeTargets` 同步到已安装租户时只做**并集**。清单里删掉一个 scope，已安装租户会永远留着它——收回已授出的权限走显式下架/迁移。
-- **写了 `aclManifest` 必须逐租户 reconcile**（平台侧代做）：那是全平台唯一把 `defaultForMember` 种进 member 角色的地方。漏了的症状是新 PID 出现在角色矩阵里却从不进 member 基线（「配了不生效」），而且**只在普通成员身上现形**，管理员看不出来。
-- **`hostPort` / `embedUrl` / `descriptor.env` 的值不归你**（见下）。
-- 新增 manifest 字段前先确认门户认得它：未知字段一律落治理档等人审。
-- **展示字段只收纯字符串**（`tagline` / `desc` / `icon` / `color` / `cat` / `navItems[].label` / `dashboardWidgets[].title`）：给多语对象会被拼成字面量 `"[object Object]"` 存进 text 列，然后显示在**每个租户**的应用卡片上。多语只有 `name` 收对象。
-- 声明 `exchangeTargets`（要读别的 App 的数据）之前先过一遍 `portal-app-exchange` skill：`EXCHANGE_NOT_ALLOWED` / `EXCHANGE_CONSENT_REQUIRED` / 跨应用下拉莫名为空，三个症状都出在布线顺序而不是代码。
-
-### 发布 = 提案，先分清自动档与治理档
-
-> 打包、令牌、CI 写法与发布排错：`xgent-app-release` skill。别自己拼 `curl`。
-
-`npx @xgent/release-cli publish`（或 `POST /api/market/release/<APP_KEY>` + `xrel_` 令牌）每次落成一条**发布提案**：
-
-- **自动通过档**（当场生效）：`dist` 产物 · `version` · `deployDescriptor.image` · 展示字段（name / tagline / desc / icon / color / cat / navItems / dashboardWidgets）· `helpEntry` 当它是 App 内路由时。
-- **治理档**（进平台「发布审核」，批准前库里一字不动）：**其余一切**，包括看着像文案实则是权限面的两个——`scopeLabels`（同意屏正文）与 `embedUrl`（iframe 指向），以及 scopes / aclManifest / dependencies / exchangeTargets / serviceBaseUrl / seat* / `requiredEnv` 键集合 / 部署形态。
-- **同一 App 同时只允许一条待审提案**：待审期间任何新提交都被拒（`PROPOSAL_PENDING`，连纯 dist/version 也一样）。等审批，或先撤回。
-- **换镜像不是同步的**：产物是同步的（publish 打印成功即在线上），镜像只排了一条重部署任务、过一会儿才换、**且可能失败**。CI 里换镜像**必须带 `--wait`**，否则会在容器换上去之前就退出码 0，把「发布成功」当成「新版本在跑」。
-- manifest **永远不许携带密钥值**（SA secret / `descriptor.env` 有值，提交即拒）。
-
-### 后端运行时契约（六条，逐条都有症状）
-
-1. **验令牌**：`POST {PORTAL_INTROSPECT_URL}`，HTTP Basic = 服务账号 `clientId:secret`，body `{ token }`。
-2. **⚠️ 解信封**：自省响应是统一信封，声明在 `data` 里 —— **`claims = body.data ?? body`**。直接读顶层的 `active` 会把**每一个有效 TDT** 都判成无效。这是外部接入最常踩的一条。
-3. **四道闸**（自己实现，网关只是哑路由；顺序即错误面）：
-   - 身份：`active === true` 且 `(claims.listingKey ?? claims.aud) === "<APP_KEY>"` 且 `tenant_id` 非空 → 否则 **401 `INVALID_TOKEN`**
-   - scope：所需 scope ∈ `claims.scopes` → 否则 **403 `INSUFFICIENT_SCOPE`**
-   - 角色：结构性管理操作看 `claims.role === "admin"` → 否则 **403 `FORBIDDEN`**
-   - ACL：细粒度操作看 `claims.bypass || claims.permissions` 命中目标 PID
-   - 跨租户的服务端判据只认自省返回的 `claims.isPlatformAdmin === true`，**不接受前端自报**。
-4. **租户隔离**：每一条查询按 `claims.tenant_id` 收口，不信请求体里的租户字段。这是硬约束，出仓不降级。
-5. **自省失败必须 fail-closed**：传输失败 / 非 2xx → 503，**绝不放行**。`active:false` 是一次成功的自省 → 401。
-6. **`/health` 返 2xx 即视为健康**（健康体长什么样都行）；**限流自己做**，门户不替你做。
-
-### API：HTTP status code 只反映传输/路由层，不反映业务状态
-
-- 404 = endpoint 不存在（路由层）；「数据不存在」用 200 + 业务字段（如 `data: null`）。
-- 业务成功统一 200，含新建/更新/删除/覆写，不用 201/204。
-- 业务失败（校验不过 / 状态非法 / 资源冲突）也走 200 + 响应体错误结构。4xx/5xx 只留给参数不正确、未登录、未授权、真传输/服务层故障。
-- 越租户与不存在**统一返回同一种「不存在」**，不泄露存在性。
-
-### 端口与环境变量：键名归你，值和宿主口归平台
-
-| 字段 | 谁定 | 说明 |
-| --- | --- | --- |
-| `deployDescriptor.port` | 你 | 容器内监听口，**就听 8080**。别要求门户注入 `PORT` 才肯听；一盒**根本不读**这个字段（反代按 `<APP_KEY>-server:8080` 找你），听别的口在一盒里直接 502 |
-| `hostPort` | 平台 | 宿主机发布口。**只在首次注册当建议值**，此后清单里写什么都不生效（会回一条说明）。撞口是自动退让不是拒绝 |
-| `extraPorts[].host` | 你声明需求、平台定值 | **撞了直接拒**（对外契约口，静默挪走等于把 worker 全断掉）。有不经门户请求路径的连接面必须显式 `"bindAddress": "0.0.0.0"`——绑成 loopback 与漏填后果完全相同：接管当天那个面直接掉，而门户侧任何检查都测不到 |
-| `descriptor.env` 的**值** / `envFile` | 平台 | manifest 里出现任何**带值**的 `env` → **解析器直接拒收**（防生产密钥进 App 仓） |
-| `requiredEnv` | 你 | 只交**键名**。它是一道闸：批准前门户拿它比对 `descriptor.env ∪ envFile` 的键集合，**缺任何一个就拒绝生效** |
-
-- **改键名写成一条 `{ key, renamedFrom }`**，别写成一删一加——后者在门户眼里是两件不相干的事，值搬不过去。
-- **新增/改名不写进 `requiredEnv`**，提案会自动通过而运维**看不到新键名**，症状是发布方以为发失败了、实际服务已换版并崩着。
-- `PORT` 与 `<APP_KEY>_SERVER_PORT` 由控制器强制注入且覆盖 envFile，别指望在 envFile 里改这两个。
-- **服务账号密钥永不静默轮换**：`--prod` 注册 / 提案批准时，门户没从 `<PREFIX>_SA_CLIENT_SECRET` 拿到值就**随机签发并一次性回显**（抄进平台那份 envFile 即可）；已存在却给了个不一致的值 ⇒ 打印原因并**非零退出**，不会悄悄跳过——悄悄跳过的后果是自省 401 而现场看不出原因。
-
-### 数据库迁移：打进镜像，平台在换容器前替你跑
-
-声明 `deployDescriptor.migrateArgs`（追加在镜像 ENTRYPOINT 后面），控制器在**换容器之前**用同镜像同 env 跑一次性容器；失败则任务转红、**旧容器原封不动继续服务**。
-
-1. 迁移文件**打进镜像**（放在仓里的脚本 = 门户拿不到，只能回到手工运维）。
-2. **advisory lock 包住**——仍可能与旧副本或另一次并发部署撞上。
-3. **失败必须非零退出**，别自愈重试。吞掉错误的代价是门户以为成功、把新容器换上去，然后在运行期以各种方式碎掉。
-4. **expand-contract 前向兼容**：迁移跑在换容器之前，那一刻旧版本仍在服务（K8s 滚动期间新旧还并存）。先加列/加表，删旧列留到下一个版本。
-
-### 镜像交付（五条硬约定）
-
-> 仓库地址、robot 账号与推送前的预检：`xgent-image-push` skill（地址不写在本文件里）。
-
-1. **`deployDescriptor.image` 写相对名**：`<APP_KEY>:<tag>`，仓库前缀由门户在部署时拼上。写成 `<APP_KEY>-server:…` 拼出来的 repo **根本不存在**，而这件事只有在切换窗口里第一次 `docker pull` 才会发现。
-2. **tag 不可变**：新版本 = 新 tag。同 tag 覆盖推送在门户侧看不出变化（引用没变就不排任务）。
-3. **单 arch 必须是 amd64**；要多架构自己 `docker buildx --platform linux/amd64,linux/arm64 --push`。
-4. **不带 `-amd64` 后缀**。
-5. 常驻型（有匿名公开面 / 被别的服务随时调）必须 **`alwaysOn: true`**，否则会被缩容或挡在冷启动闸后面。
-
-### 依赖 `@xgent/*` 走平台私有 registry
-
-`@xgent/shared` · `@xgent/portal-sdk` · `@xgent/portal-ui` 从平台的私有 registry 装（地址与取 token 的方式在本仓的 `.npmrc` 与 CI 配置里，不写进本文件）。**授权 token 是短时效的**——每次构建现取，`bun install` 报 401/404 先想到它过期了，别去改版本号。
-
-- **三个包各自独立编号，不是一套齐版**；registry 上**缺号是常态**（仓里 bump 过但没推）。以 `npm view @xgent/<pkg> versions` 为准，**写范围不要精确 pin**。
-- **`^0.x` 只放行 patch**：`^0.1.0` 不会解析到 `0.2.x`。要用新 API 就显式把范围提上去，症状是 `sdk.<新方法> is not a function`。
-- **未经用户明确声明要升级该大版本，禁止升级 Major**（`x.y.z` 的 `x`，包括 `0.x` → `1.x`）。
-
-### 前端 UI 开发：设计用 impeccable，验证用 Chrome extension / kimi-webbridge / Playwright（`micro` 型才有；`service` 型删掉本节）
-
-涉及页面、组件、布局、交互或视觉的前端 UI 开发，强制走完两步：
-
-- **设计阶段**用 `impeccable` skill 提升设计质量，至少覆盖视觉层级、信息架构、间距与对齐、配色、动效、可访问性、空状态和错误状态；不要靠「凭感觉写 Tailwind」出 UI。如果当前环境没有安装 `impeccable` skill，提示用户运行 `npx impeccable install`。
-- **验证阶段**选择当前 coding agent 可用的真实浏览器通道：Claude Code 用 Chrome extension（`mcp__claude-in-chrome__*`）；Codex、Kimi Coder 及其他 coding agent 优先用 `kimi-webbridge` skill；不可用时回退到 `playwright`。必须看到改动生效，并走通主路径和关键边界后，才能报告完成。类型检查和单测只验证代码正确，不验证功能正确；UI 改动只看 diff 不算验证完成。
-- 如果本地环境跑不起来，先尝试解决；仍无法验证时，必须显式说明「未在浏览器中验证」、交代阻塞原因并请用户协助，不得默认声称已经完成。
-
-### 前端：版头归门户（`micro` 型才有；`service` 型删掉本节及以下三节）
-
-> SDK 全量速查（握手 / getToken / callService / routeSync / dashboard widget / iframe 已知坑）：`portal-micro-app` skill。
-
-- **不在 App 内自绘应用图标 / 应用名 / tagline**：版头最左那一级恒为它且可点回应用首页。再画一份就是同屏说两次，而且租户改过 App 名之后两处会说得不一样（`apps.name` 租户可改，你的 i18n 词条改不了）。可以留：角色 / 工作区 / 当前对象这类**运行期事实**，以及脱离门户直接打开时的 standalone 壳。
-- **页面层级用 `sdk.setBreadcrumbs(crumbs)` 上报**：挂在**视图驱动的 effect** 上（不要散在各个 `routeSync()` 调用点——宿主发起的路由变化只走 `onRoute`，挂错的症状是「侧栏切页后面包屑空着」）；首页推 `[]`；每次全量覆盖；label 用**当前语言**解析好（宿主不翻译）。
-- **路由双向**：内部路由变化 `sdk.routeSync(path)`，同时**必须**订阅 `sdk.onRoute` 处理宿主推回的路由。只写单向会出现「同一 App 两个菜单点了不切换」。
-- **调自己的后端一律 `sdk.callService("<APP_KEY>", path, opts)`**（宿主代转发、零跨域、401/403 自动重铸重试一次）。iframe 里直接跨域 `fetch` 自己的后端是错误姿势。
-- **不要自己存 TDT**、不写 localStorage：`sdk.getToken()` 自动缓存并在到期前续签。
-- **日常 `getToken` 不要传裁剪过的 scopes**：mint 会把本次签发的 scope 记为用户的**同意范围**，用子集 mint 会**收窄**已有同意，之后更宽的 mint 触发 `CONSENT_REQUIRED`。
-- **`sdk.acl.can(pid)` 只是隐藏按钮的 UX 门**，真正拦截靠后端。前端判过 ≠ 安全。
-- **低频入口（帮助 / 接入指引）用 `helpEntry` 挂版头**，不占侧栏。指向 App 内路由是自动档；指向外站是治理档（门户版头等于替那个域名背书）。
-- **`window.alert` / `confirm` / `prompt` 在跨源沙箱 iframe 里被静默忽略**——一律用 App 内的 DOM 模态框。
-
-### 下拉框：`<select>` 必须 `appearance-none` + 自绘 chevron
-
-把文本输入的类直接套在 `<select>` 上，留下的是**浏览器原生箭头**——位置/大小/颜色全归浏览器，`pr-*` 推不动它（padding 只影响文字），也不跟主题 token 走。这错误反复出现，因为类型检查 / lint / 单测**全绿**，只有人眼看得出来。
-
-```
-appearance-none                    ← 唯一硬要求：关掉原生箭头
-pr-8                               ← 给自绘箭头留位
-<ChevronDown size={14} className="pointer-events-none absolute right-2.5 top-1/2 -translate-y-1/2 text-fg-3" />
-```
-
-收在自己的 `Select` 原语里，视图里不写裸 `<select>`。宽度写在哪取决于 `className` 转发给谁：转发给 `<select>`（内部已有 `w-full`）⇒ 定宽要在外面套一层 `div`；转发给外层 wrapper ⇒ 直接写在组件上。
-
-### 字典表统一带 `sort` + `name_i18n`（本 App 有租户级可维护的枚举/分类表时）
-
-- 列名固定 `sort`，`integer NOT NULL DEFAULT 0`，**不要**叫 `seq`。列表统一 `ORDER BY sort, name`。前端字段也叫 `sort`。
-- 必带 `name_i18n jsonb`（可空）：`name` 是**缺省 locale(zh-CN) 槽位 + 唯一键 + 回退终点**，`name_i18n` 只存非缺省 locale 覆盖，键白名单只有 `en` / `zh-TW`。校验归一用 `@xgent/shared` 的 `normalizeNameI18n()`，前端解析用 `@xgent/portal-ui` 的 `resolveDictName(row, locale)`——别再写一份。
-- ⚠️ body schema 里 `nameI18n` 用 `t.Optional(t.Unknown())`：`t.Record(t.String(), t.String())` 会静默丢弃 `__proto__` 键，把「拒绝」变成「悄悄清空」。
-- **例外**：树 / 兄弟次序表不算字典表，保留 `seq`——语义是序号不是字典排序。
-
-### App 图标：必须意义契合，且必须在门户注册表里存在
-
-不要用「机器人 / AI」那类通用图标，挑一个和它干什么直接对应的 lucide 图标；**不要和已有 App 撞图标**。图标名必须是**门户宿主支持的 lucide 名**——宿主查不到时**静默回退**，写错的名字会一路走到生产（拿不准就问平台管理员要当前可用清单与占用情况）。改 `icon` 只对**新安装**生效（租户可自行改），存量对齐要找平台。
-
-### 本地联调：一盒（one-box）
-
-不 clone 门户、不改门户代码：拉门户镜像起一个真门户，注册你的 manifest，再把 `dist` 绝对路径挂进去（`APP_FRONTEND_DIST`）。**步骤、凭证与端口一律走 `portal-dev-setup` skill**，不要照着别处的命令手敲。
-
-- **一盒是 dev 底座，不是门户**：`DEV_MOCK_OAUTH=true` + 已知明文 SA 密钥。永远不要拿它当生产。dev 态 manifest 可以带 `serviceAccount.secret` 明文；`--prod` 下**给了就拒收**。
-- **先对齐一盒镜像的版本**：一盒镜像滞后于门户主干时会出现「文档说有、实际没有」的现象（真实案例：注册后自动授予租户的那段代码比某次发布的镜像新一天，症状是市场里没有卡片而没有任何报错）。**遇到「照文档做但行为不符」，先确认镜像版本，再怀疑自己**。
-- **一盒镜像与你自己的 App 镜像不在同一个 registry 项目下**：`init` 默认按你的项目名拼一盒镜像会 404，显式传镜像引用（值见 `portal-dev-setup` skill）。
-- **你自己的库不会被自动建**：一盒的 postgres 初始化脚本只建平台与内置 App 的库，先手工 `CREATE DATABASE "xgent-<APP_KEY>"`。
-- **生产镜像是 amd64、开发机多半是 arm64**：起一盒时要给你的 backend 容器显式 `platform: linux/amd64`（devkit 默认跟随本机架构，自己叠一层 override）。
-- **注册必须先于反代启动**，否则 `/svc/<APP_KEY>` 404；首次 404 的另一个常见原因是放行 map 写失败（权限），进反代容器补一行再 reload。
-- **注册完先看演示租户的市场里有没有卡片**：没有卡片就是授予行没写成，先解决它，别接着往下排查前端。
-- **首次打开有「授权并打开」的同意屏**（正常行为，自动化走查要把它算进步骤）；`install` 排出的部署任务在一盒里会一直停在 `deploying`——一盒没有部署控制器，不挡使用。
-
-### 完成标准
-
-- 后端改动至少自测到：无 token → 401；缺 scope → 403；换一个租户看隔离；`curl /svc/<APP_KEY>/health` 200。
-- 发布前：`release-cli whoami` 验令牌（别等构建完才发现过期），换镜像带 `--wait`。
-- 症状 → 原因先查 skill 里的排查表，别猜：`/svc` 404·502 / 自省 401 / `INSUFFICIENT_SCOPE` 看 `portal-external-app`；发布 401·404·`PROPOSAL_PENDING` / 发了没换版看 `xgent-app-release`；一盒起不来看 `portal-dev-setup`；`EXCHANGE_*` 看 `portal-app-exchange`。
-
-## Design Context
-
-本仓有专门的设计文档，任何前端 UI 工作之前都要读（`impeccable` skill 会自动加载）：
-
-- **[PRODUCT.md](./PRODUCT.md)** —— 战略上下文：register、用户、产品目的、品牌人格、反面参照、设计原则、可访问性。
-- **[DESIGN.md](./DESIGN.md)** —— 视觉系统：色彩、字体、投影、组件，以及从门户底座继承来的那部分 token。
-
-<!-- 填写指引：两份文档与 CLAUDE.md 同在仓根时链接就是上面这样；放到别处记得改路径。 -->

package/vendor/impeccable/bundle/blobs/800cf1c0392b24de7c0a1c6ea6778ecb433dec71c49a150bce96a98477527b2f

@@ -1 +0,0 @@
-0.1.5