@xgent-ai/skills 0.1.0 → 0.3.0

package/skills/portal-logging/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: portal-logging
+description: '把一个 App 的日志/遥测接进门户的「日志与监控」服务：采集器布线（容器 stdout / 文件 tail / 应用内直打）、写入身份（服务账号换令牌 或 长期访问密钥）、`observability.ingest` scope、`/svc/observability/v1/ingest/…` 写入面、`app_你的key_流名` 的流命名与跨 App 统一的日志字段口径。凡任务涉及「让我的服务的日志能在日志与监控里看到」「接采集器 / fluent-bit / docker 日志驱动」「日志写入 401 / 403 / scope 为空」「写进去了但界面查不到 / stream not found」「一次报错被拆成几十条 / 分不出哪条是错误」时，务必先用本 skill 再动手——即使用户只说「把日志接上」。Use when wiring an app''s logs or telemetry into the portal observability service: collector setup, ingest credentials and scope, stream naming, log field conventions, and the classic failures (empty scope, 403 on write, 401 on query, records that never show up).'
+---
+
+# portal-logging · 把 App 的日志接进「日志与监控」
+
+一条链路四段，**两种身份**：
+
+```
+你的进程  →  采集器  →  POST /svc/observability/v1/ingest/<stream>  →  在「日志与监控」App 里看
+（产生）     （搬运）    ↑ 服务身份（机器的钥匙）                        ↑ 用户身份（人的票）
+```
+
+两种身份不能互换，这是整条链路最常见的困惑来源：**采集器只能写、不能查；人只能查、不能写**。拿服务密钥去查会得到 401，那不是配置错。
+
+> **路径约定**：本 skill 里的 `apps/…` `deploy/…` `docs/…` 都在**门户仓**。在你自己的 App repo 里它们不存在——它们标注的是「门户侧的事实在哪」，不是让你去打开的文件。你需要的一切在本 skill 的 `references/` 与 `scripts/`（自包含，路径相对于本 `SKILL.md` 所在目录）。运行脚本前，在 App repo 根目录按实际加载位置设置 `SKILL_DIR="<本 SKILL.md 所在目录>"`。
+
+## 按任务读
+
+| 任务 | 读 |
+| --- | --- |
+| 配采集器（容器 stdout / 文件 tail / 应用内直打），含多行合并与级别判定 | [references/collectors.md](references/collectors.md) |
+| 端点、凭据、请求/响应形状、查询 API、错误码矩阵、计量 | [references/contract.md](references/contract.md) |
+| 只想先打通一条，验证链路是活的 | `"$SKILL_DIR/scripts/smoke-ingest.sh"`（改环境变量直接跑） |
+
+## 0. 先判断：你要接的真的是「日志」吗
+
+日志流是**给人排障看的时间序列文本**。下面这些各有专用面，塞进日志流会同时失去两边的能力：
+
+- **审计**（谁在什么时候改了什么，要可追溯、不可篡改、要留存）→ 门户审计面（`audit.write`），不是日志。
+- **用量/计费**（要精确、要对账）→ 平台计量面。日志会被采样、会过期。
+- **给用户看的消息**（提醒、待办、通知）→ 门户通知域。
+- **指标与链路**（数值时间序列 / trace）→ 同一个服务的 OTLP 入口，形状与日志不同，见 contract.md。
+
+判据：这条记录**丢了会不会有人要赔钱或说不清责任**。会 → 不是日志。
+
+## 1. 三个前提（不成立时，每一步都会以「看起来成功」的方式失败）
+
+1. **平台把「日志与监控」登记为平台基础服务应用，且默认授予里含 `observability.ingest`。**
+   这是平台管理员在门户控制台做的一次登记。没有它：你换令牌拿到 HTTP 200、`scope` 字段却是**空的**，直到第一次写入才 403。——第一天接日志的团队九成栽在这里，先查它。
+2. **你的 App 在目标租户已安装且可用。** 令牌里的 `azp` 绑着你的 App key，签发时会检查「这个租户装没装你」。没装 ⇒ `APP_NOT_INSTALLED`。语义是对的：你没在这个租户里跑，就不该有这个租户的日志。
+3. **你有自己的服务账号凭据。** 平台部署你的服务时注入 `<PREFIX>_SA_CLIENT_ID` / `<PREFIX>_SA_CLIENT_SECRET`（`<PREFIX>` = 你的 appKey 大写、`-` 换 `_`），另有 `API_BASE_URL`（门户内部源，换令牌用）与 `PORTAL_BASE_URL`（门户公开源，`/svc/...` 用）。
+   与门户同仓的后端没有「平台注入」这一步，同名的键在部署环境的 env 文件里——**键名与用法完全一样**，下文不再分叉。
+
+**不要为日志新建一套密钥**，也**不要**把 `observability.ingest` 写进自己 manifest 的 `serviceScopes`：那是别人命名空间的 scope，写进去反而要求你把对方列进依赖；这条 scope 由平台在**签发那一刻**并进来，manifest 一个字都不用改。
+
+## 2. 选写入身份
+
+| | 短期服务态令牌 | 长期访问密钥（`xsak_` 开头） |
+| --- | --- | --- |
+| 怎么拿 | `POST {API_BASE_URL}/api/tokens/service`，HTTP Basic = `client_id:secret`，body `grant_type=client_credentials` + `tenant_id` + `scope` | 门户控制台 › 服务账号 › 访问密钥（平台管理员签；租户自助建的服务账号同理） |
+| 有效期 | 分钟级，要缓存 + 到期前续 | 可无期限 |
+| 谁用 | **你的应用代码**自己打点 | **采集器进程**（fluent-bit 这类不会自己换令牌的） |
+| 代价 | 每次要一次 HTTP | 明文长期存在盘上，泄漏面大 ⇒ 只给 `observability.ingest` 这一条 scope，别多给 |
+
+拿短期令牌时把它缓存到 `expires_in - 10s`，别每条日志换一次令牌——那是把日志量乘进了门户的负载。
+
+## 3. 写入
+
+```
+POST {PORTAL_BASE_URL}/svc/observability/v1/ingest/<stream>
+Authorization: Bearer <服务令牌 或 xsak_…>
+Content-Type: application/json
+
+[ {…记录1…}, {…记录2…} ]      ← 一次一批，别一条一个请求
+```
+
+**成功判据要看两层**：HTTP 200 **且** 响应体 `code:200` 且 `status[]` 里 `failed:0`。只看 HTTP 状态码会把「收下了但没落库」当成功——这正是「写入一直 200、界面永远查不到」的来源。
+
+⚠️ **采集器代发（形态 A/B）时你根本看不到这个响应**：采集器只在自己的日志里留一行 `HTTP status=200`，`failed>0` 那种「收下了没落库」它不会告诉你，401/403 也只是按重试上限丢掉——**采集器不报错 ≠ 接通了**。所以这两种形态的验收落在 §8 冒烟那一条 curl（那里你拿得到响应体）加上界面真的搜到；排障时再临时打开采集器的响应打印（见 collectors.md）。
+
+**流名**：你写 `<stream>`，实际落在 `app_<你的 appKey>_<stream>`——前缀由令牌里的 `azp` 决定，你写不进别人的命名空间，也**别在 `<stream>` 里再重复一遍自己的 key**（会得到 `app_foo_foo_console`）。一个 App 按用途分流即可：`console`（进程标准输出）、`access`、`job`。
+
+## 4. 字段口径（跨 App 一致，界面和排障才有共同语言）
+
+| 字段 | 必要性 | 说明 |
+| --- | --- | --- |
+| `message` | 必备 | 正文，一条一行 |
+| `level` | 强烈建议 | `info` / `warn` / `error`；**产生方给的最准**，采集器只能猜 |
+| `service` | 强烈建议 | 进程/子服务名，一个 App 有多个进程时靠它分 |
+| `host` | 建议 | 实例/主机名，多副本时靠它分 |
+| `fd` | 采集器填 | `stdout` / `stderr` |
+
+**时间**：落库的时间轴是**到达时间**，日志自带的时间只是一个普通字段。要让时间轴等于事件时间，就在记录里带上 `_timestamp`（微秒 epoch），并**先用一条冒烟记录验证**这个版本认不认——别假设。
+
+**级别**：如果你的日志是文本行、由采集器搬运，采集器只能靠 `stderr` 和关键词猜，而 `console.warn` 一类在多数运行时也走 stderr ⇒ 例行 warn 会整批被判成 error。解法是**产生方把级别写进正文**（例如正文尾部的 JSON 里 `"lvl":"error"`），采集器优先取它。判定次序与可直接抄的实现见 collectors.md。
+
+**永远不要写进日志**：令牌 / 密钥 / 密码、完整 query string（授权码与令牌常在里面）、用户个人信息与租户业务正文、大 blob。排障要的是**能定位的 ID**，不是内容本身——日志会被转发、留存、被平台管理员看到。
+
+## 5. 选采集形态
+
+| 形态 | 适合 | 代价 |
+| --- | --- | --- |
+| A 容器 stdout → 日志驱动 → 采集器 | 容器化交付、应用零改动 | 多一个采集器进程 |
+| B 采集器 tail 日志文件 | 进程管理器把 stdout 写成文件的部署 | 要处理轮转 |
+| C 应用内直接批量 POST | 想要结构化字段与精确级别、日志量小 | 自己管批量/重试/背压 |
+
+共性的四条（三种形态都适用，任一漏掉都会在生产上现形）：**批量发**、**异步发**（不许在请求热路径上同步等远端）、**失败丢弃而不是无限重试**（日志不值得拖垮主流程）、**多行合并**（一个栈是一条记录，不是四十条）。
+
+⚠️ 多行合并按 tag/流分缓冲。**多个日志源共用一个 tag 时，A 源的栈会把 B 源随后那行吸进同一条记录**——每个源（每个文件 / 每个容器 × stdout|stderr）一个 tag。
+
+配置照抄 [references/collectors.md](references/collectors.md)。
+
+## 6. 查
+
+正常路径是人打开「日志与监控」App 查（需要 `observability.read`，由租户管理员同意授权）。程序化查询要**用户身份的令牌**，服务密钥打查询面是 `401`——先确认你是不是拿错了钥匙，再怀疑数据没进去。
+
+## 7. 排错矩阵
+
+| 症状 | 多半是 | 动作 |
+| --- | --- | --- |
+| 换令牌 200，但响应里 `scope` 是空的 | 平台没登记基础服务应用 / 默认授予里没有 ingest | 找平台管理员登记，§1.1 |
+| 写入 `403` | 身份类型不对（拿用户票写）或 scope 里没有 ingest | 用服务身份；查签出来的 scope |
+| 写入 `401` | 凭证缺失 / 伪造 / 已撤销 / 已过期 | 重签；轮换过的旧密钥立刻失效 |
+| 换令牌报 `APP_NOT_INSTALLED` | 你的 App 没装在这个租户 | 这是设计，不是 bug；换租户或先装 |
+| 写入 200，但查不到 | ① 只看了 HTTP 没看 `status[]`；② 流名前缀猜错（是 `app_<key>_<stream>`）；③ 时间范围——时间轴是**到达时间** | 按序查这三条 |
+| 查询报 `stream not found` | 这个流一条都没写进去过 | 回到上一行 |
+| 查询 401、但写入 200 | 拿服务密钥查 | 换用户身份 |
+| 只看到零星几条 | 时间范围太窄；或你的进程本来就几乎不打日志 | 先确认源头有没有行 |
+| 一次报错被拆成几十条 | 采集器没配多行合并 | collectors.md |
+| 一条记录里混了两个进程的行 | 多个源共用一个 tag | 每源一个 tag |
+| 界面里只有别的 App 的流 | 你的令牌 `azp` 不是你以为的那个 | 自省一下令牌 |
+
+## 8. 冒烟验收（接完逐条走一遍，都过才算接上）
+
+1. 换出来的令牌 `scope` **确实含** `observability.ingest`（不是空）。
+2. 写一条带标记的记录，响应 HTTP 200 且 `status[]` 里 `failed:0`。
+3. 在「日志与监控」App 里按这个标记**搜到了**它，流名是 `app_<你的 key>_<stream>`。
+4. 故意打一个多行栈，界面里它是**一条**记录。
+5. 打一条 error 和一条 info，界面里级别**分得开**。
+6. 把采集器停掉再起来，不重放历史、也不丢新行。
+
+## 别做的事
+
+- 别为日志自建一套网关/存储/密钥体系——这条链路已经存在，重造的那份不会有人运维。
+- 别把审计、用量、通知塞进日志流（§0）。
+- 别在生产刷 debug 级别：写入是**计量项**（按字节），也会把有用的行淹掉。
+- 别把别的 App 的日志代写进自己的流：`azp` 决定前缀，代写要么被拒，要么污染自己的命名空间。

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