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.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/qfeius/make-platform-skills --skill make-app-observability

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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。
같은 저장소의 Skills

더 많은 Skills

모든 Skills
qfeius
커뮤니티

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

1시간 설치 수
1
GitHub Stars
0
업데이트
11월 10일
qfeius
커뮤니티

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

1시간 설치 수
1
GitHub Stars
0
업데이트
11월 10일
qfeius
커뮤니티

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

1시간 설치 수
1
GitHub Stars
0
업데이트
11월 10일
qfeius
커뮤니티

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

1시간 설치 수
1
GitHub Stars
0
업데이트
11월 10일