@xgent-ai/skills 0.1.0 → 0.4.0

package/skills/portal-logging/references/collectors.md

@@ -0,0 +1,285 @@
+# 采集器：三种形态 + 可直接抄的配置
+
+三种形态写入面完全一样（[contract.md](contract.md)），差别只在「从哪儿把行读出来」。下面的 fluent-bit 配置在真镜像上跑通过，**照抄再改路径/环境变量**比自己重写省一整天——尤其是多行合并那一段，它有两个静默坑。
+
+- [A 容器 stdout → 日志驱动 → 采集器](#a-容器-stdout)
+- [B 采集器 tail 日志文件](#b-文件-tail)
+- [C 应用内直接批量 POST](#c-应用内直接打点)
+- [采集器怎么知道自己写成功了](#采集器怎么知道自己写成功了)
+- [级别判定（两种形态共用）](#级别判定)
+- [多行合并的两个坑](#多行合并的两个坑)
+
+---
+
+## A 容器 stdout
+
+应用零改动：容器的 stdout/stderr 由 docker 的日志驱动转给采集器。适合容器化交付。
+
+```yaml
+# 你的服务：把日志转给采集器（fluentd-async 让采集器没起来时容器照常启动）
+services:
+  my-service:
+    logging:
+      driver: fluentd
+      options:
+        fluentd-address: 127.0.0.1:24224
+        fluentd-async: "true"
+        fluentd-async-reconnect-interval: 5s
+        tag: my-service          # ⚠️ 不要带点，见下面 rewrite_tag 那段
+
+  log-collector:
+    image: fluent/fluent-bit:3.2.10
+    restart: unless-stopped
+    environment:
+      OBS_HOST: ${PORTAL_HOST}              # 门户公开源的主机名（不带 scheme）
+      OBS_STREAM: console
+      OBS_SOURCE_HOST: ${HOSTNAME}
+    env_file: [./collector.env]             # 只放 OBS_ACCESS_KEY，权限 600
+    ports: ["127.0.0.1:24224:24224"]
+    volumes:
+      - ./fluent-bit:/fluent-bit/etc:ro
+      - collector-state:/var/lib/fluent-bit
+volumes: { collector-state: {} }
+```
+
+```ini
+# fluent-bit/fluent-bit.conf
+[SERVICE]
+    Flush            5
+    Grace            5
+    Log_Level        info
+    Parsers_File     parsers.conf
+    storage.path     /var/lib/fluent-bit/storage
+    storage.sync     normal
+    HTTP_Server      Off
+
+[INPUT]
+    Name             forward
+    Listen           0.0.0.0
+    Port             24224
+    storage.type     filesystem
+
+# ⚠️ docker 的日志驱动给 stdout 与 stderr 【同一个 tag】，而多行合并按 tag 缓冲：
+# 不先拆开，stderr 那条栈的续行会被接到上一条 stdout 记录屁股后面（实测如此）。
+# Match_Regex 挑「还没拆过的 tag」——日志驱动的 tag 不含点、拆出来的含点，所以重新入链的
+# 记录不会再次命中这条规则（否则就是死循环）。新接进来的容器 tag 也不能带点。
+[FILTER]
+    Name                  rewrite_tag
+    Match_Regex           ^[^.]+$
+    Rule                  $source ^(stdout|stderr)$ console.$TAG.$1 false
+    Emitter_Name          console_split
+
+[FILTER]
+    Name                  multiline
+    Match                 console.*
+    multiline.key_content log
+    multiline.parser      js_stack
+
+[FILTER]
+    Name             lua
+    Match            console.*
+    script           enrich.lua
+    call             enrich
+
+[OUTPUT]
+    Name             http
+    Match            console.*
+    Host             ${OBS_HOST}
+    Port             443
+    tls              On
+    tls.verify       On
+    URI              /svc/observability/v1/ingest/${OBS_STREAM}
+    Format           json
+    Json_date_key    timestamp
+    Json_date_format iso8601
+    Header           Authorization Bearer ${OBS_ACCESS_KEY}
+    Header           Content-Type application/json
+    Retry_Limit      8
+    Log_response_payload Off
+    storage.total_limit_size 64M
+```
+
+```lua
+-- fluent-bit/enrich.lua —— docker 驱动的记录 {log, source, container_name} → 统一字段
+local host = os.getenv("OBS_SOURCE_HOST") or "unknown"
+
+function enrich(tag, ts, record)
+  local name = string.gsub(record["container_name"] or tag or "unknown", "^/", "")
+  record["service"] = string.match(name, "^[%w]+%-(.-)%-%d+$") or name   -- compose 容器名 → 服务名
+  record["fd"] = record["source"] or "stdout"
+  record["host"] = host
+  record["message"] = record["log"]
+  record["level"] = level_of(record["fd"], record["log"] or "")          -- 见「级别判定」
+  record["log"] = nil; record["source"] = nil
+  record["container_id"] = nil; record["container_name"] = nil
+  return 2, ts, record
+end
+```
+
+---
+
+## B 文件 tail
+
+进程管理器把 stdout 写成文件时用这条。与 A 的差别只在 INPUT 与 service 的来源。
+
+```ini
+[INPUT]
+    Name             tail
+    # ⚠️ 每个文件一个 tag（`*` 展开成文件路径）：多行合并按 tag 缓冲，
+    # 多个文件共用一个 tag 时 A 进程的栈会把 B 进程随后那行吸进来。
+    Tag              console.*
+    Path             /logs/app.out.log,/logs/app.err.log
+    Path_Key         file
+    Parser           line
+    DB               /var/lib/fluent-bit/tail.db
+    Refresh_Interval 10
+    Rotate_Wait      30
+    Skip_Long_Lines  On
+    storage.type     filesystem
+    # Read_from_Head 默认 Off：首次启动不回灌历史几万行。要补历史再临时打开。
+```
+
+```lua
+-- 从被跟随的文件名派生 service / fd：/logs/<service>.<out|err>.log
+function enrich(tag, ts, record)
+  local service, fd = string.match(record["file"] or "", "([%w%-]+)%.(%a+)%.log$")
+  record["service"] = service or "unknown"
+  record["fd"] = (fd == "err") and "stderr" or "stdout"
+  record["host"] = os.getenv("OBS_SOURCE_HOST") or "unknown"
+  record["level"] = level_of(record["fd"], record["message"] or "")
+  record["file"] = nil
+  return 2, ts, record
+end
+```
+
+如果进程管理器给每行加了时间戳前缀（很多都会），用一个正则 parser 把它切掉，正文才干净：
+
+```ini
+[PARSER]
+    Name         line
+    Format       regex
+    Regex        ^(?<time>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}): (?<message>.*)$
+    Time_Key     time
+    Time_Format  %Y-%m-%dT%H:%M:%S
+    Time_Offset  +0800          # 前缀不带时区就得固定一个，按机器时区填
+    Time_Keep    Off
+    # ⚠️ 空行也要带上空的 message：缺了这个键，多行合并器认不出它是续行、直接放行，
+    # 一条错误转储会被中间那个空行劈成两半，后半截还丢了 Path_Key ⇒ service 变成 unknown。
+    Skip_Empty_Values Off
+```
+
+---
+
+## C 应用内直接打点
+
+日志量小、想要结构化字段与精确级别时最省事。要点：**批量、异步、丢得起**。
+
+```ts
+const BUF: Record<string, unknown>[] = [];
+
+export function log(level: "info" | "warn" | "error", message: string, ctx: Record<string, unknown> = {}) {
+  BUF.push({ level, message, service: SERVICE, host: HOST, ...ctx });
+  if (BUF.length >= 200) void flush();          // 满一批就走
+}
+
+async function flush() {
+  if (!BUF.length) return;
+  const batch = BUF.splice(0, BUF.length);      // 先摘出来：flush 期间新来的行不阻塞
+  try {
+    const token = await serviceToken();         // 缓存到 expires_in - 10s，见 contract.md §2
+    const r = await fetch(`${PORTAL_BASE_URL}/svc/observability/v1/ingest/console`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+      body: JSON.stringify(batch),
+      signal: AbortSignal.timeout(5000),
+    });
+    // 只看 HTTP 200 会把「收下了但没落库」当成功
+    const body = await r.json().catch(() => null);
+    if (!r.ok || body?.code !== 200) console.error("[log] ingest rejected", r.status, body?.status);
+  } catch (e) {
+    // 丢弃。日志不值得把主流程拖垮，也不值得无限重试堆成内存泄漏。
+    console.error("[log] ingest failed", (e as Error).message);
+  }
+}
+
+setInterval(() => void flush(), 5000).unref();  // 定时兜底
+process.on("beforeExit", () => void flush());   // 退出前冲一次
+```
+
+**不要**在请求处理路径上 `await flush()`：远端抖一下，你的接口就跟着抖。
+
+---
+
+## 采集器怎么知道自己写成功了
+
+这是形态 A/B 最容易漏的一环：**写入的响应体不在你眼前**。fluent-bit 只会在自己的日志里留一行
+
+```
+[2026-01-01 00:00:00] [ info] [output:http:http.0] <host>:443, HTTP status=200
+```
+
+而「HTTP 200 但 `status[].failed>0`」——记录被判拒、根本没落库——在这行里**看起来一模一样**。401/403 也只是按 `Retry_Limit` 重试几次后丢弃：日志静静地没了，采集器一切正常。
+
+所以：
+
+- **验收不要看采集器的日志**，看冒烟那一条 curl（你拿得到响应体，能判两层）+ 界面真的搜到。`scripts/smoke-ingest.sh` 就是干这个的。
+- **排障时**临时把响应打印打开，看完再关掉（响应体会一直进采集器日志）：
+
+  ```ini
+  [OUTPUT]
+      Log_response_payload On
+  ```
+
+- **长期监控**：采集器进程本身要有人看（重启、`[error]` 行、积压）。日志链路断了不会有人来告诉你——它的症状就是「最近怎么没日志了」，而那通常是很久以后才有人注意到。
+
+## 级别判定
+
+产生方给的级别最准。搬运方只能猜，猜的次序要**先精确后启发式**，否则会把例行 warn 整批判成 error：
+
+```lua
+-- ① 正文 JSON 里的 "lvl"/"level" —— 产生方给的，直接用
+-- ② warn 标记 —— 必须排在 fd 之前：console.warn 一类也走 stderr
+-- ③ fd == stderr ⇒ error
+-- ④ stdout 上的错误标记 —— 第三方库（连接失败那种）并不按 fd 分级
+-- ⑤ 其余 info
+function level_of(fd, msg)
+  local lvl = msg:match('"lvl"%s*:%s*"(%a+)"') or msg:match('"level"%s*:%s*"(%a+)"')
+  if lvl == "error" or lvl == "warn" or lvl == "info" or lvl == "debug" then return lvl end
+  local head = msg:match("^[^{]*") or msg            -- 只看 JSON 之前那截，见下
+  if head:match("⚠") or head:match("[Ww]arn") or head:match("WARN") then return "warn" end
+  if fd == "stderr" then return "error" end
+  if head:match("✗") or head:match("❌") or head:match("[Ee]rror") or head:match("ERROR")
+    or head:match("[Ff]ail") or head:match("FAIL") or head:match("失败") or head:match("异常") then return "error" end
+  if msg:match('"error"%s*:%s*"') then return "error" end
+  return "info"
+end
+```
+
+④ 只看 `{` 之前那一截，是因为正文里的 JSON 常含 `delivery_failed` 这类**字段名/事件名**，整条搜关键词会把一条 info 判成 error；JSON 部分只认 `"error":"…"`（有内容的错误字段）。
+
+产生方那边对应地做一件事就够：打错误行时把级别写进正文的 JSON。例如 `[api] request failed {"lvl":"error","path":"/x","status":500}`，采集器走 ① 直接命中，不再需要猜。
+
+---
+
+## 多行合并的两个坑
+
+```ini
+[MULTILINE_PARSER]
+    Name         js_stack
+    Type         regex
+    Flush        2
+    rule         "start_state"   "/^.*$/"                                  "cont"
+    rule         "cont"          "/^(\s|\d+ \||error: |\w+Error: |$)/"     "cont"
+```
+
+start_state 收下任意一行；下一行**看着像续行**就并进去，否则冲出上一条、另起一条。续行的四种形状：前导空白（`    at …` / `   errno:`）、代码帧（`262 |  …`）、`error:` / `SyntaxError:` 抬头、空行。
+
+1. **按 tag 缓冲**：一个 tag 一条流。多个日志源共用一个 tag ⇒ A 的栈吸走 B 的下一行。tail 用 `Tag console.*`（每文件一个），docker 驱动用 `rewrite_tag` 按 `source` 拆。
+2. **空行必须带着 `message` 键进来**（`Skip_Empty_Values Off`）：解析器丢掉空值时，合并器认不出它是续行而直接放行，一条转储被劈成两半，后半截还丢了文件名派生的字段。
+
+验证方式：拿一段**真的**崩溃输出（不是自己编的三行）喂进去，看它是不是**一条**记录、级别是不是 error。本机跑一遍就知道：
+
+```bash
+docker run --rm -v "$PWD/etc:/fluent-bit/etc:ro" -v "$PWD/logs:/logs:ro" \
+  fluent/fluent-bit:3.2.10          # 把 OUTPUT 换成 Name stdout / Format json_lines 再跑
+```

package/skills/portal-logging/references/contract.md

@@ -0,0 +1,95 @@
+# 契约：端点、凭据、响应、查询、计量
+
+本文件是「写代码时要查的那几行」。判断与流程在 [SKILL.md](../SKILL.md)。
+
+## 1. 地址
+
+| 用途 | 地址 | 从哪来 |
+| --- | --- | --- |
+| 换服务令牌 | `{API_BASE_URL}/api/tokens/service` | 平台注入 `API_BASE_URL`（门户内部源） |
+| 写入日志 | `{PORTAL_BASE_URL}/svc/observability/v1/ingest/<stream>` | 平台注入 `PORTAL_BASE_URL`（门户公开源） |
+| 写入指标/链路（OTLP） | `{PORTAL_BASE_URL}/svc/observability/v1/ingest/otlp/{logs,metrics,traces}` | 同上 |
+| 查询（人用） | 「日志与监控」App 界面 | — |
+| 查询（程序，需用户身份） | `{PORTAL_BASE_URL}/svc/observability/api/t<租户UUID去掉横线>/_search?type=logs` | — |
+
+`/svc/<key>/…` 是**所有部署形态都通**的那条路（门户反代按 key 转发）。同机直连对方容器是优化，不是默认——换个部署形态就断。
+
+⚠️ OTLP 三条入口的协议细节与日志入口不同，接之前先跟服务方确认版本行为；本 skill 只保证 `/v1/ingest/<stream>` 这条 JSON 路径。
+
+## 2. 换服务令牌
+
+```bash
+curl -sS -X POST "$API_BASE_URL/api/tokens/service" \
+  -u "$MY_SA_CLIENT_ID:$MY_SA_CLIENT_SECRET" \
+  -H 'content-type: application/json' \
+  -d '{"grant_type":"client_credentials","tenant_id":"<租户 UUID>","scope":"observability.ingest"}'
+```
+
+响应是门户统一信封：
+
+```json
+{ "ok": true, "data": { "access_token": "…", "token_type": "Bearer", "expires_in": 900, "scope": "observability.ingest" } }
+```
+
+- **先看 `ok`，再看 `data`**；失败时是 `{"ok":false,"error":{"code":"…"}}`，HTTP 仍可能是 200（业务失败不用状态码表达）。
+- **`scope` 为空 = 没拿到写入权**：往下写一定 403。回 SKILL.md §1.1。
+- `scope` 省略时给的是这把钥匙**当前全部**权限；显式写 `observability.ingest` 更窄、更好排查。
+- 缓存到 `expires_in - 10s`。别每条日志换一次。
+
+## 3. 长期访问密钥（采集器用）
+
+门户控制台 › 服务账号 › 访问密钥：选目标租户、**只勾 `observability.ingest`**、起个能认出用途的名字、按需设到期。明文**只显示一次**。
+
+- 一个服务账号最多 10 把活跃密钥。
+- 撤销/轮换后旧密钥立刻 401（采集器会按重试上限丢弃，重签后重启即可）。
+- 落盘权限收紧到只有采集器进程能读；**别进仓库、别进镜像、别打进日志**。
+- 密钥能签出来的 scope 不会超过它所属服务账号当下能拿到的——签发时报「无法授予」就是前提没成立，不是名字写错。
+
+## 4. 写入
+
+```bash
+curl -sS -X POST "$PORTAL_BASE_URL/svc/observability/v1/ingest/console" \
+  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
+  -d '[{"message":"hello","level":"info","service":"my-service","host":"node-1"}]'
+```
+
+成功响应形如 `{"code":200,"status":[{"successful":1,"failed":0,…}]}`。**两层都要判**：HTTP 2xx 且 `code:200` 且 `failed:0`。
+
+- 请求体是**记录数组**；一次一批，别一条一个请求。
+- 字段是随写随建的：你发什么字段，流里就有什么列。所以字段名一旦定下就别改来改去（改名 = 老数据查不到）。
+- 实际流名 `app_<azp>_<stream>`，`azp` 来自令牌，等于你的 appKey。**响应体里的 `status[].name` 就是实际落点**——不用猜，也不用回头查。
+- ⚠️ **key 里的 `-` 在流名里会被归一成 `__`**：`llm-gateway` 的流是 `app_llm__gateway_console`。写入端不用管，**查询时要用归一后的名字**，否则得到的是 `stream not found`（HTTP 400），看着像数据没进去。
+- 时间轴用的是**到达时间**；日志自带时间是普通字段。要对齐就带 `_timestamp`（微秒 epoch），并先冒烟验证这个版本认不认。
+
+## 5. 查询（程序化）
+
+只认**用户身份的令牌**（`aud` = 日志与监控、scope 含 `observability.read`）。服务密钥打查询面是 `401` —— 按设计如此，不是坏了。
+
+```
+POST {PORTAL_BASE_URL}/svc/observability/api/t<租户UUID去横线>/_search?type=logs
+{ "query": { "sql": "SELECT service, level, message FROM \"app_<key>_console\" ORDER BY _timestamp DESC",
+             "from": 0, "size": 20, "start_time": <微秒>, "end_time": <微秒> } }
+```
+
+- 时间范围是**微秒** epoch——不传或范围写窄了，结果就是「什么都没有」。这是「明明写进去了却查不到」的头号原因。
+- 流名要带前缀：`app_<key>_<stream>`。
+- `GET …/api/t<租户>/streams` 列出有哪些流：查不到自己那条，说明一条都没写进去过。
+
+## 6. 错误码矩阵
+
+| HTTP / code | 含义 | 下一步 |
+| --- | --- | --- |
+| 换令牌 `ok:false` + `APP_NOT_INSTALLED` | 你的 App 没装在这个租户 | 设计如此；换租户或先装 |
+| 换令牌 200 但 `scope` 空 | 平台没把日志与监控登记为基础服务应用 / 默认授予没有 ingest | 找平台管理员登记 |
+| 写入 `401` | 凭证缺失 / 伪造 / 已撤销 / 已过期 | 重签；轮换过的旧密钥立刻失效 |
+| 写入 `403` | 身份类型不对（用户身份写入）或 scope 不含 ingest | 换服务身份；核对签出的 scope |
+| 写入 200 但 `failed>0` | 记录被拒（形状/大小） | 看 `status[]` 里的原因，别忽略 |
+| 查询 `401` | 拿服务密钥查 | 换用户身份 |
+| 查询 `stream not found` | 这个流从没写进过东西 | 回到写入那一层，先看成功判据 |
+| 查询 `stream not found`，但你确信写成功了 | key 里有 `-`，流名被归一成 `__` | 用 `…/streams` 列一下真实流名 |
+
+## 7. 计量与留存
+
+写入按字节计量（平台的用量面能看到），存储占用同理。两条实践：**生产不开 debug**（一条 debug 的成本和一条 error 一样）、**正文里别塞大 blob**（要看的是能定位的 ID）。
+
+留存期由平台/租户在日志与监控里配置：**日志不是归档**。要长期留证的东西走审计面。

package/skills/portal-logging/scripts/smoke-ingest.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# 冒烟：换令牌 → 写一条带标记的记录 → 告诉你怎么在界面里找到它。
+# 接日志的第一步跑它，比读文档快：三个前提里哪个不成立，它会直接说出来。
+#
+#   PORTAL_BASE_URL=https://<门户域名> TENANT_ID=<租户UUID> APP_KEY=<你的key> \
+#   SA_CLIENT_ID=… SA_CLIENT_SECRET=… ./smoke-ingest.sh
+#
+# 已有长期密钥就跳过换令牌：ACCESS_KEY=xsak_… ./smoke-ingest.sh
+# 令牌/密钥永远不打印。
+set -euo pipefail
+
+: "${PORTAL_BASE_URL:?缺 PORTAL_BASE_URL（门户公开源，形如 https://portal.example.com）}"
+: "${TENANT_ID:?缺 TENANT_ID（目标租户 UUID）}"
+: "${APP_KEY:?缺 APP_KEY（你的 App key，用来拼期望的流名）}"
+API_BASE_URL="${API_BASE_URL:-$PORTAL_BASE_URL}"
+STREAM="${STREAM:-console}"
+MARKER="portal-logging-smoke-$(date +%s)"
+
+jget() { python3 -c 'import json,sys;d=json.load(sys.stdin);print(eval("d"+sys.argv[1]) if d else "")' "$1" 2>/dev/null || true; }
+
+if [ -n "${ACCESS_KEY:-}" ]; then
+  TOKEN="$ACCESS_KEY"
+  echo "① 用长期访问密钥（跳过换令牌）"
+else
+  : "${SA_CLIENT_ID:?缺 SA_CLIENT_ID（平台注入 <PREFIX>_SA_CLIENT_ID）}"
+  : "${SA_CLIENT_SECRET:?缺 SA_CLIENT_SECRET}"
+  RESP=$(curl -sS -X POST "$API_BASE_URL/api/tokens/service" \
+    -u "$SA_CLIENT_ID:$SA_CLIENT_SECRET" -H 'content-type: application/json' \
+    -d "{\"grant_type\":\"client_credentials\",\"tenant_id\":\"$TENANT_ID\",\"scope\":\"observability.ingest\"}")
+  OK=$(printf '%s' "$RESP" | jget '["ok"]')
+  if [ "$OK" != "True" ]; then
+    echo "✗ 换令牌失败：$(printf '%s' "$RESP" | jget '["error"]["code"]')"
+    echo "  APP_NOT_INSTALLED ⇒ 你的 App 没装在这个租户（设计如此）。其余见 references/contract.md §6。"
+    exit 1
+  fi
+  SCOPE=$(printf '%s' "$RESP" | jget '["data"]["scope"]')
+  TOKEN=$(printf '%s' "$RESP" | jget '["data"]["access_token"]')
+  if [ -z "$SCOPE" ]; then
+    echo "✗ 令牌签出来了，但 scope 是空的 —— 平台还没把「日志与监控」登记为平台基础服务应用"
+    echo "  （或默认授予里没有 observability.ingest）。往下写一定 403，先找平台管理员登记。"
+    exit 1
+  fi
+  echo "① 换到服务令牌，scope=$SCOPE"
+fi
+
+echo "② 写一条：stream=$STREAM marker=$MARKER"
+W=$(curl -sS -o /tmp/pl-smoke.json -w '%{http_code}' -X POST \
+  "$PORTAL_BASE_URL/svc/observability/v1/ingest/$STREAM" \
+  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
+  -d "[{\"message\":\"$MARKER hello from smoke\",\"level\":\"info\",\"service\":\"$APP_KEY\",\"host\":\"$(hostname)\"}]")
+BODY=$(cat /tmp/pl-smoke.json); rm -f /tmp/pl-smoke.json
+CODE=$(printf '%s' "$BODY" | jget '["code"]')
+FAILED=$(printf '%s' "$BODY" | jget '["status"][0]["failed"]')
+
+if [ "$W" != "200" ]; then
+  echo "✗ HTTP $W —— 401=凭证无效/已撤销；403=身份类型不对或 scope 不含 ingest。见 contract.md §6"
+  echo "  $BODY"; exit 1
+fi
+if [ "$CODE" != "200" ] || [ "${FAILED:-1}" != "0" ]; then
+  echo "✗ HTTP 200 但没落库（这正是「一直 200、界面查不到」的来源）：$BODY"; exit 1
+fi
+
+echo "③ 写入成功（HTTP 200 + code:200 + failed:0）"
+cat <<TIP
+
+下一步，在「日志与监控」App 里核对（用你自己的账号，不是这把密钥）：
+  · 流名应为  app_${APP_KEY}_${STREAM}
+  · 搜        $MARKER
+  · 时间范围选【最近 15 分钟】—— 时间轴是到达时间，范围写窄了就是"什么都没有"
+
+搜不到就按这个次序查：流名前缀 → 时间范围 → 令牌的 azp 是不是你以为的那个。
+TIP

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

@@ -0,0 +1,73 @@
+---
+name: portal-micro-app
+description: '开发/修改 XGENT Portal 的嵌入式微应用前端（micro 型 App，iframe + @xgent/portal-sdk，独立前端项目）。凡任务涉及新建一个 App 前端、给某 App 加页面/导航项/Dashboard Widget、SDK 握手/getToken/callService、consent 授权屏、或 iframe 内的 UI 异常（弹窗无效/菜单点不动/主题/路由同步/全屏/剪贴板）时，务必先用本 skill——即使用户没提"微应用"三个字。Use when building or changing any micro-app frontend embedded in the portal, the portal SDK handshake, navItems, dashboard widgets, or iframe-specific UI issues.'
+---
+
+# portal-micro-app · 嵌入式微应用（iframe + SDK）开发
+
+微应用是被 Portal 以沙箱 iframe 嵌入的普通 Web 页面：**不自己实现登录、不持有 App Secret**，身份由宿主经 postMessage 握手注入。本文件是工作流与红线；具体契约按需读 `references/`（可整目录拷到任何 App repo 使用）。
+
+
+`/apps/<key>/` 是线上前端挂载 URL；本文的 `references/` 相对于本 skill 目录。
+
+## 按任务读参考
+
+| 任务 | 读 |
+| --- | --- |
+| 握手 / SDK API / 令牌与 consent / callService | [references/sdk-reference.md](references/sdk-reference.md) |
+| 声明导航、scope、ACL、Widget、依赖 | [references/manifest-and-acl.md](references/manifest-and-acl.md) |
+| 调 Open API / Widget 推送 / 通知 / 内容 / 计划任务 / 审计 / 错误码 | [references/open-api-and-extensions.md](references/open-api-and-extensions.md) |
+
+## 新建一个 micro App 前端的最小闭环
+
+1. 在 App 自己的仓库新建 Vite + React 前端，配置固定空闲端口并开启 `strictPort`，避免自动换端口后加载错应用。
+2. 安装下述公开分发的 SDK/UI 包，按本地 [SDK 参考](references/sdk-reference.md) 接入握手与路由。
+3. 在自己的 `app.manifest.json` 声明 `navItems` / `scopes` / `aclManifest` / `dashboard.widgets`；租户管理员不能代填开发者声明。
+4. Vite `base` 设为 `/apps/<key>/`，构建 `dist/`，用 `xgent-app-release` skill 的 `publish --dist` / `publish --manifest` 提交；涉及治理字段等待审批，按本次 proposal 的交付状态核对结果。
+5. 本地联调用 `portal-dev-setup` 的一盒环境。生产优先 `sdk.callService` 与同源托管；需要开发 CORS 白名单时交平台管理员处理。
+6. 在真实浏览器从宿主进入并走通主路径、路由往返与权限边界；不以构建通过代替 UI 验证。
+
+`@xgent/portal-sdk` / `@xgent/portal-ui` / `@xgent/shared` 在你的 repo 里**照常作为 npm 依赖安装**，
+来源是平台的私有包仓（公共 npm 上没有，直接 `bun add` 会 E404）。配法见 `xgent-app-release`
+skill 的「第 0 步」。仓里还没有 `.xgent-registry.env` ⇒ 停下，请开发者先去门户「开发者应用」生成
+配置文件。**不许 vendor**：不把 SDK 的产物或源码拷进仓，也不用 `file:` / `link:` / tar 依赖顶替。
+
+## SDK 硬规则
+
+- 私有页面从 `const sdk = createPortalClient(); const init = await sdk.ready();` 开始。SDK 0.4.0 支持 iframe 与同源 standalone 共用自举；声明 `openModes` 后从 `/open/<key>` 进入。顶层必须处理 `ready()` typed error 和 `onContextChanged()`，失效时卸载私有视图与应用缓存，并提供显式 `openGate()`；不要自动跳登录。匿名页可不调用 `ready()`。生产从 `/apps/<key>/` 推导 key，开发的 appKey/host/apiBase 来自构建配置，不能读 URL 配认证主机。详见 [SDK 参考](references/sdk-reference.md)。
+- `sdk.getToken()` 自动缓存、到期前 30s 续签——**不要**自己存 TDT、不要写 localStorage。
+- 用户长期凭证由本 App 后端委托门户签发。前端只将新建/迁移响应保存在当前一次性展示组件；不要用 Query/Mutation 缓存保存含 secret/token 的响应。关闭后清除，复制失败提供选中文本和重试。门户集中管理入口是 `/me?tab=keys`；App 保留项目/能力/路由配置、旧密钥停用与远端撤销重试。
+- 全局平台管理员不在 TDT JWT / `InitPayload` 里；`sdk.acl.bypass` 和 `sdk.userinfo().role` 只表示当前租户。前端即使拿到 session-only `/auth/me.isPlatformAdmin` 也只能做展示，不能转发给后端授权；跨租户后端只认 TDT 自省返回的 `isPlatformAdmin`。
+- 调自己的独立后端一律 `sdk.callService("<listingKey>", path, opts)`（宿主代转发、零跨域、401/403 自动重铸重试一次）。iframe 直接跨域 `fetch` 独立后端是错误姿势。
+- 权限：`sdk.acl.can(pid)` / `sdk.acl.scope(pid)` 只做**隐藏按钮/入口**的 UX 门；真正拦截靠后端。前端判过 ≠ 安全。
+- 路由：内部路由变化调 `sdk.routeSync(path)` 同步到 `?r=`；同时**必须**订阅 `sdk.onRoute` 处理宿主推回的路由（浏览器后退、同 App 多导航项切换）。只写单向 routeSync 会出现"同一 App 两个菜单点了不切换"的 bug。二级详情页把完整路径（如 `/items/<id>`）routeSync 出去，刷新/分享才能还原。
+- 版头面包屑：调 `sdk.setBreadcrumbs(crumbs)` 上报页面层级（宿主最左恒为「应用图标 + 应用名」= 应用首页，你报的是其后那几级；首页推 `[]`，每次是整条 trail 的**全量覆盖**）。四条规矩：① 挂在**视图驱动的 effect** 上，**不要**散在各个 `routeSync()` 调用点——宿主发起的路由变化只走 `onRoute`，挂错的症状是"侧栏切页后面包屑空着"；② `onRoute("")`（空路由）必须落到首页视图，版头最左那一级靠它工作；③ 标签要异步查询才知道时**宁可少一级**，不推 id 占位、不推"加载中…"，数据回来再整条覆盖（`FR-12` 这种展示 key 可以推，内部 UUID 不可以）；④ `label` 用**自己当前的语言**解析好（宿主不翻译），切语言在 `onLocale` 里重推。上限 6 级 / label 120 字符 / route 512 字符且必须 `/` 开头（不得以 `//` 开头），超限被静默截断；末级不带 `route`。
+- **App 内不要自绘图标与名称**：版头最左那一级恒为「应用图标 + 应用名」且可点回应用首页，App 再画一份就是同屏说两次，而且租户改过 App 名之后两处会说得不一样（`apps.name` 租户可改、i18n 词条改不了）。tagline / 副标题同理（应用中心已展示过）。可以留：角色 / 工作区 / 当前对象这类**运行期事实**，以及 `main.tsx` 里脱离门户打开时的 standalone 壳。浏览器验收时检查版头与 App 内容没有重复标题。
+- **帮助页入口 `helpEntry`**：清单里声明一个可空字符串，版头工具条最右侧（全屏与刷新的**左边**）就多一枚帮助按钮；不声明就不出按钮。两种形态：`"/help"` = App 内路由（宿主置 `?r=`，不离开门户，**自动档**）、`"https://docs.example.com"` = 外站文档（新标签 + `noopener`，**走治理审核**，因为门户版头等于替这个域名背书）。`/…` 与 crumb `route` 同一条规则；外站必须 https（`http://` 连回环也拒）、无 fragment。它是**安装期快照**，改了要 bump 自己的 `version`；**租户不可覆盖**（想指向自家知识库去知识库 App 建条目）。门户不托管、不渲染、不翻译帮助正文。
+- **低频入口放版头、不占侧栏**：帮助中心 / 接入指引这类低频页别长期占着侧栏一个位置 —— 用 `helpEntry` 挂到版头，并把这一级显式推进面包屑。
+- 主题/语言：订阅 `sdk.onTheme` / `sdk.onLocale`；高度用 `sdk.resize`；未保存更改 `sdk.setDirty(true)` 让宿主拦离开。
+
+## Consent 硬规则
+
+- 宿主挂 iframe 前有 consent 门；mint 会把**本次签发的 scope 记为用户的同意范围**。用子集 scope mint 会**收窄**已有同意，之后更宽的 mint 触发 `CONSENT_REQUIRED`。日常 getToken 不要传裁剪过的 scopes。
+- 声明了 `exchangeTargets` 的 App，用户首次进入时 consent 门会**共授**跨应用交换同意——跨应用读数据为空时先想到这个（详见 portal-app-exchange skill）。
+
+## iframe 已知坑（都真实踩过）
+
+- `window.prompt` / `window.confirm` / `window.alert` 在跨源沙箱 iframe 里**被静默忽略**——一律用应用内 DOM 模态框。
+- Tailwind 的 `/alpha` 颜色修饰符（如 `bg-primary/50`）在主题的普通 `var()` 颜色上**静默失效**——用 `opacity-NN` 或预算好的色值。
+- Radix 菜单/Popover 触发器放在模态 Dialog 里"点了没反应"：触发器组件必须 `forwardRef`，且弹层 z-index 要高于 dialog overlay。
+- 跨源 iframe 里剪贴板 API 受限；Chrome extension 也看不进跨源 iframe（验证时从宿主页面操作）。
+- `.xg-md` markdown 渲染若用 `@xgent/file-preview` 的 `./markdown` 子路径，宿主需映射 hsl 通道 CSS 变量。
+
+## 设计红线（平台一致性）
+
+- **不自建**「设置」页/导航（租户配置走平台应用配置页）、**不自建**审计页（写 `POST /api/v1/audit`）。
+- **不做**「同步通讯录」：成员选择一律用 `@xgent/portal-ui` 的 `UserPicker` 按需 curated。
+- 列表页服务端分页，复用 `Page<T>` 契约与现有 helpers。
+- 复用 `@xgent/portal-ui` 已有组件再造新轮子。
+- **页面铺满客户区，上限 1600**：iframe 就是客户区（14" 笔记本上约 1272px，App 自带侧栏再减 ~200px）。页面框架写 `mx-auto w-full max-w-[1600px]` + 页边距，**不要**把整页收成 `max-w-3xl` / `max-w-[880px]` 居中——笔记本上会左右各空 150–200px。窄只加在内容块上且**左对齐**：表单 / 设置列 ≤ 720px、Markdown 文档列 ≤ 880px、段落正文 ≤ 72ch；多个设置分区 `lg:` 并排两栏、卡片网格 `xl:` 加一列。允许居中窄列的只有：对话流（≤ 800px）、多步向导、授权 / 无权限卡片、空状态、纸面预览、弹窗 / 抽屉。
+
+## 完成标准
+
+类型检查/单测只证明代码对，不证明功能对。微应用改动必须在真浏览器（Chrome extension）里从宿主进入、走通主路径与关键边界后才算完成；环境起不来就显式说明"未在浏览器中验证"。

package/skills/portal-micro-app/references/manifest-and-acl.md

@@ -0,0 +1,97 @@
+# Manifest 与 ACL 声明（微应用视角）
+
+> 本文是可在 App 仓库独立使用的契约参考；能力以目标平台已发布版本和管理员配置为准。
+
+## 1. 模型：开发者字段快照
+
+Manifest 的权威载体是一条**市场清单（marketplace listing）**。安装 = 把开发者字段快照复制进该租户的 `apps` 行；清单升级后租户「同步更新」重拷开发者字段（运营字段不动）。`listingKey` 就是 TDT 的 `aud`，不可改。
+
+⚠️ **ACL Manifest 和 navItems 只能由应用自身声明**（自己的 `app.manifest.json`），租户管理员不能在注册表单手填。修改后提交完整清单发布提案，按治理要求审批，并核对已安装租户的同步结果。
+
+## 2. 微应用相关的开发者字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `listingKey` | `^[a-z0-9-]+$`，2–40。= TDT `aud`，不可改 |
+| `name` / `tagline` / `desc` / `icon` / `color` / `cat` | 展示信息 |
+| `type` | `micro`（iframe 嵌入，本 skill 场景）/ `link` / `native` / `service` |
+| `embedUrl` | iframe 源。生产同源托管为 `/apps/<key>/` |
+| `allowedOrigins` | postMessage 握手来源白名单 |
+| `scopes` | 申请的权限范围（最小够用——授权屏逐条展示，越多越劝退） |
+| `scopeLabels` | App 命名空间 scope 的同意页三语文案 |
+| `navItems` | `{ id, label, icon, path }[]` 贡献到左侧导航 |
+| `helpEntry` | 版头帮助按钮的入口，可空字符串。`"/help"` = App 内路由（宿主置 `?r=`，自动通过档）／`"https://…"` = 外站文档（新标签 + `noopener`，治理档）。不声明就不出这枚按钮 |
+| `dashboard.widgets` | 可展示的 Dashboard Widget 声明 |
+| `extPoints` | 仅 `settings.section` |
+| `dependencies` | 依赖的其他清单（安装按拓扑序补装；卸载被依赖会拦截） |
+| `exchangeTargets` | 经令牌交换读取哪些 App（安装时自动建交换白名单 + consent 共授） |
+| `embedCsp` | 托管前端的精确来源声明；开发版本支持 connectSrc/scriptSrc/styleSrc/fontSrc/imgSrc/mediaSrc，须正式发布并启用 strict/v2 后使用，旧门户只支持 connectSrc |
+| `tdtTtl` | TDT 有效期秒数，60–86400，默认 3600 |
+
+运营字段（租户管理员设，非 Manifest）：`visibility` / `showInCenter` / `pinned` / `enabledNavItemIds` / `webhookUrl` / `allowExchange` / `exchangeWhitelist`。
+
+## 3. ACL Manifest schema
+
+匿名页面可以位于 `/apps/<key>/…`，不应在该路由先强制 SDK 登录；数据授权仍归 App。
+后端直出 HTML 可以正式使用 `/svc/<key>/…`，但其 cookie Path、表单、资源、fetch、
+Location 和受保护预览必须适配外部 base。独立域名复用 `publicEntrypoints` + Sites，
+声明本身不创建门户根级路径。详见 portal-external-app 的公开入口参考；发布与 CSP
+实际验收见 xgent-app-release。改 listingKey 是身份/资源迁移，不是显示名修改。
+
+```ts
+interface AclManifest {
+  version: string;          // reconcile 基准
+  landingPageKey?: string;  // 应用可见性判定页（缺省第一个 page）
+  groups?: AclGroup[];
+  pages: AclPage[];
+  actions: AclAction[];
+  roleTemplates?: AclRoleTemplate[]; // 管理员可"从模板克隆"角色（克隆后脱钩）
+}
+interface AclPage {
+  key: string;               // 稳定 id，进 PID
+  path: string;              // 路由 pattern，匹配运行时 ?r=
+  label: I18nText;           // 字符串或 { "zh-CN", "en" }
+  parentKey?: string;        // 页面树（矩阵分组 + 前缀通配）
+  navItemId?: string;        // 关联 navItems[].id
+  supportedScopes?: DataScope[]; // 缺省 ["all"]
+  defaultForMember?: boolean;    // 授予内置 member 基线
+}
+interface AclAction {
+  key: string; label: I18nText; pageKey?: string;
+  supportedScopes?: DataScope[]; dangerous?: boolean; defaultForMember?: boolean;
+}
+```
+
+**PID 语法** `<appKey>:<kind>:<key>`，`kind ∈ {page, action}`；通配由粗到细：
+
+```
+<appKey>:*  >  <appKey>:page:*  >  <appKey>:page:projects.*  >  <appKey>:page:projects
+```
+
+**DataScope（ABAC-lite）** `own` < `team` < `all`：`own` 行的 ownerUserId==当前用户；`team` 行属于用户所在组；`all` 无行级过滤。同一 PID 命中多条授予时最宽范围胜出。
+
+**模型**：纯加法 RBAC——角色只授予不拒绝、有效权限=所有角色授予并集、默认拒绝、租户 `admin` bypass 一切、`member` 基线自动获得各应用的 `defaultForMember` 项。
+
+## 4. 运行时两道门
+
+1. **前端 UX 门**：握手注入 `init.acl` → `sdk.acl.can(pid)` / `sdk.acl.scope(pid)` 隐藏入口/按钮。**仅 UX，不可信。**
+2. **后端安全门**：独立后端从自省结果拿 `bypass`/`permissions`/`groups` 真正拦截。前端判过 ≠ 安全。
+
+## 5. navItems 生命周期
+
+- 市场安装时 `navItems` 快照到 `apps.navItems`，默认全部启用（`enabledNavItemIds`）；管理员之后只能启停声明项，不能手填新项。
+- Shell 经 `GET /api/apps/nav` 聚合可见应用的已启用项；点击打开 `/app/:appKey?r=<path>`，SDK 握手时 `init.route` 就是这个 path。
+- `navItems[].id` 绑定 `AclPage.navItemId` 后，侧栏按用户 ACL 隐藏无权入口——但应用前端仍要 `sdk.acl` 做 UX 门、后端仍做安全门。
+- 约定：`id` 应用内稳定（改 id = 删旧菜单加新菜单，租户启用状态受影响）；`path` 用应用内部路由（`/` 开头）；`icon` 用 Portal 支持的图标名。
+
+## CSP 与发布确认的版本边界
+
+新增扩展能力尚未因本文更新而上线；strict 默认关闭，需平台盘点来源并受控启用 v2。六类来源
+使用 HTTPS origin（connectSrc 另允许 WSS 及原样 `blob:`/`data:`），禁止通配、路径、凭据和 unsafe-inline/unsafe-eval；
+platformSources 仅 scriptSrc/styleSrc/fontSrc/connectSrc 可声明 ["jsCdn"]，跟随平台 CDN。
+省略整个 embedCsp 沿用，null 清空，对象是完整替换；来源增删均治理，排序去重不算变更。
+
+新版 delivery 追踪本次 proposalId 的审批、清单/产物、后端和网关四阶段。纯前端 backend 为
+not_applicable 仍须等网关；unknown 不当成功，superseded 表示目标被后续取代。旧门户无 delivery
+不能确认网关。CSP 只扩展本 App 的 /apps 前端，不更改门户壳、沙箱或 /svc 后端公开页策略；
+公开数据授权与真实浏览器主路径仍需单独验证。