qfeius/make-platform-skills

make-app-observability

Use when creating, integrating, reviewing, or debugging a Make App's default Trace ID chain, traceparent and X-Log-Id propagation, safe correlated logs, or @qfei-design/make-app-observability error notices.

Ver código-fonte

Como usar

  1. Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
  2. Consulte no original as ferramentas, credenciais e ambientes necessários.
  3. Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/qfeius/make-platform-skills --skill make-app-observability

Antes de começar

  • A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
  • Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Documento original do Skill

Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.

make-app-observability

所有新建 Make App 默认接入 Trace ID。存量 App 的本次任务涉及业务请求、AI transport、错误出口或发布门禁时,应核对相关 Trace 链路并补齐缺失环节;无关改动只报告发现的缺失,不擅自扩大本次任务范围。Trace ID 的默认范围是 App 的业务请求及其错误出口,包括启用时的 AI JSON、SSE 和二进制传输。静态资源和 OAuth 回调不属于 UI 业务请求适配器的范围。

主责与边界

本 Skill 负责跨 UI、可选 Service 和 Make Gateway 的 Trace ID 生成、传递、关联日志、错误分类与统一展示。@qfei-design/make-app-observability 提供错误呈现模型及 React 组件;它不会发请求、创建 Span、传 Header、记录日志或配置导出器。不能把安装该包等同于完成 Trace 链路,也不能把仅有 Trace ID 关联宣称为已接入集中式 Trace 后端。

  • 认证请求与 cookie/session 机制交给 make-app-auth;在其共享已认证请求适配器中注入追踪 Header,不另写裸请求或浏览器 token 逻辑。
  • Service 路由、UI-Service 业务合同和 Make adapter 交给 make-app-service;本 Skill 定义跨这些边界的 Trace 不变量。
  • AI 路由、流式事件和取消语义交给 make-ai-assistant;其已认证 JSON、SSE、二进制传输沿用同一追踪合同。
  • 发布脚本和交付门禁交给 make-app-runtime;该 Skill 调用本 Skill 的审计器。
  • 全局错误出口在持久应用根层的挂载、与宿主 overlay 的层级协调及真实 Shell 可见性验收交给 makeui;本 Skill 负责把安全的结构化请求错误交给该出口。0.1.9+ 公共包负责桌面与手机 viewport 的默认定位、错误卡片和 Trace ID 展示规则,宿主不重写默认定位。
  • 权限提示也复用此包的 React 入口;按 makeui/references/permission-feedback.md 验证实际安装版的 MakeAppPermissionNotice、CSS 和发布状态。权限范围与联系人仍分别归 make-app-permission、make-app-auth;不要把已知权限拒绝重复送入普通错误卡。

默认接入流程

  1. 判定 App 的请求拓扑:UI 直连 Make Gateway,或 UI -> Service -> Make Gateway。两种拓扑都必须经过一个共享、已认证的 UI 请求适配器。
  2. 在 UI 的每次业务请求开始时创建有效的 W3C Trace 上下文,保存本次 128-bit 非零 Trace ID。请求 Header 同时写入 traceparent 和等于其中 trace-id 的 X-Log-Id;同一次请求的成功或失败使用创建时保存的 ID,重试作为新的网络尝试重新创建并保留对应 ID。不要通过 URL query 传 Trace 信息。
  3. Service-fronted App 在请求入口校验入站 Header,缺失或非法时生成安全 Trace ID;所有响应返回 X-Log-Id。向 Make Gateway 转发时只使用已校验且一致的追踪 Header,Service 安全日志带同一个 traceId。直连模式则由共享 UI 适配器把 Header 送到 Gateway。
  4. 统一错误出口区分 HTTP 非 2xx、网络异常和 HTTP 2xx 业务码异常。收到响应时在 Span 记录实际 HTTP 状态码;业务码失败和 HTTP 非 2xx 标记为错误,网络异常不虚构状态码。请求层及权限、Schema 等 Provider 到错误出口之间保留安全的 kind/status/title/description/traceId,不得降级成只有文案的字符串。使用公共包的 MakeAppErrorNotice,全局错误队列须由一个 MakeAppErrorNoticeViewport 包裹,页面内嵌错误卡片可单独使用。三类真实请求失败只要携带合法 Trace ID 都显示可复制的 ID。失败时优先保留本次请求创建的 ID,避免无响应的网络错误丢失关联信息。
  5. 当 App 使用 AI transport 时,JSON、SSE、文件和二进制请求也发送这两个 Header;HTTP 非 2xx 即使有响应体也要标记 Span 为错误。不能恢复通过 __traceparent 等 query 参数传递 Trace 的旧做法。
  6. 新建或本次改造反馈出口的 App 使用实际安装的 @qfei-design/make-app-observability@0.1.11+,默认安装范围为 ^0.1.11;包负责 Toast 计时与隐藏,宿主通过 noticeKey 标识事件、onClose 清理队列,不另加计时器。未涉及反馈改造的存量 App 保留锁定版本,不因包发布自动升级。先补行为测试,再运行 scripts/audit-trace-contract.mjs 和 App 原有测试。审计检查声明版本与源代码接线,不能代替实际安装版本核对、计时行为、真实请求及真实 AppShell 下错误卡片可见性的断言。
  1. 本次明确改造请求错误反馈时,按 存量错误出口迁移 清点并迁移全部相关入口,将请求错误 Toast 收敛到根层同一队列;删除旧卡片工厂,保留常驻内嵌态和本地校验。将新增出口审计及正反向测试纳入项目门禁,不能仅凭存在一个 viewport 或给旧容器补时长宣称迁移完成。

Toast 自动关闭与宿主队列清理按 生命周期合同 接入;目标产物须验证公开 API 与实际计时行为。

业务失败的用户文案按 公共错误文案合同 提取:优先保留有效 msg,按接口兼容 message;无可用公共原因才兜底。不要把安全边界误解为按错误码或固定白名单覆盖后端原因;文案不决定重试、权限或落库结果。

按需阅读

工作读取
安装公共包、公开入口、错误状态与桌面/移动全局出口references/package-integration.md
UI、Service、Gateway 和 AI 的 Trace 链路及安全边界references/trace-chain.md
后端 msg/message、兜底、安全边界与宿主行为验证公共错误文案合同
行为测试、静态审计、发布检查和排障references/testing-and-audit.md
存量请求错误出口清点、统一迁移与重复出口门禁references/error-outlet-migration.md

安装或升级时,先从目标 App 已安装包的 package.ai.json 读取 readOrder,按声明顺序阅读公开文档;不要从包内 src 或 dist 深层导入,也不要把本 Skill 写的示例当成高于目标安装版本的公开 API。

交付条件

  • 新建 Make App 的项目级发布检查包含 trace:audit;发布前同时通过适用的行为测试和审计。已有 App 使用自身的兼容运行时及发布命令,不为接入追踪强制迁移包管理器。
  • 审计命令:node skills/make-app-observability/scripts/audit-trace-contract.mjs <project-root> --mode auto。复制到 App 项目本地的脚本才可写入项目 package.json,不要引用开发者机器上的 Skill 绝对路径。
  • 不记录或传给 UI Authorization、Cookie、token、业务请求正文、AI 提示词或原始内部错误。日志只写安全的路由、方法、状态、错误类别及 traceId。
do mesmo repositório

Mais Skills

Todos os Skills
qfeius
Comunidade

make-app-filter

Use when generating, integrating, reviewing, or debugging Make App record-list keyword search through Service filter.expression or advanced/conditional/table/header filtering with @qfei-design/make-app-filter. Triggered by 列表搜索, 关键词搜索, 筛选, 高级筛选, 条件筛选, 表格/表头/列头/按字段筛选, CEL/DNF, field-type operators, candidate values, and filter Preset save/echo. In search-only mode, use the package compiler without a filter panel or Preset lifecycle. In advanced-filter mode, use the package panel, permission-aware

Instalações / 1h
1
GitHub Stars
0
Atualizado
10 de nov.
qfeius
Comunidade

make-app-runtime

Use when generating, refactoring, reviewing, or debugging Make App project runtime structure, workspace manifests, Service runtime, local/dev scripts, build outputs, Docker/K8s image entrypoints, publish readiness, or packaging errors such as missing apps/service/dist/server.js. Covers apps/ workspace contracts, apps/ui/dist, apps/service port/build/start contracts, runtime config file location, runtime artifact tests, forwarded host/proto header preservation, and publish gates that include auth

Instalações / 1h
1
GitHub Stars
0
Atualizado
10 de nov.
qfeius
Comunidade

make-app-service

Use when generating, refactoring, reviewing, or debugging Make App apps/service APIs and UI-Service contracts, including server-side aggregation for dashboards, charts and 统计/汇总. Covers route design, apps/docs/api.md, layered structure, Make adapters, direct Make response passthrough, schema normalization including independent fields/createFields collections, record CRUD, record-write-permission and records/bulk, list filter/sort/groupFilter parsing, record groups, Entity Preset, candidate/looku

Instalações / 1h
1
GitHub Stars
0
Atualizado
10 de nov.
qfeius
Comunidade

make-app-sort

Use when integrating, generating, refactoring, reviewing, or debugging Make App record-list sorting with @qfei-design/make-app-sort. Triggered by 排序, 高级排序, 多字段排序, 排序优先级, 升序/降序, 排序条件拖拽, 表格/表头/列头排序, openWithField, sortable capabilities, Entity Preset sort save/load/echo, records sort payloads, or sorting tests. Covers one integrated toolbar, CanvasTable header, Entity Preset, and Service sorting flow. When make-app-actions is present, a successfully applied sort must clear its selection and invali

Instalações / 1h
1
GitHub Stars
0
Atualizado
10 de nov.