finta-debug-bundle

用途

Finta Debug Bundle 用于在集成失败时收集最小的诊断信息包，以便提交给 Finta 支持团队进行排查。其核心目标是在保留投资者和财务数据边界的前提下，收集足以复现问题的证据。触发方式为包含“finta debug”或“finta support”等短语。

主要能力

该技能能够收集以下诊断信息：

时间戳、服务版本、配置引用、聚合计数器和脱敏后的错误类别。
Finta API 连通性状态（HTTP 状态码）。
融资轮次数据（rounds）。
投资者记录样本（限制数量）。
已连接集成的状态。
速率限制响应头信息。

最终输出一个经过脱敏的事件包索引，包含关联 ID、工件、访问负责人、保留日期、复现结果和后续操作。敏感原始证据应保存在索引之外经批准的安全位置。

使用方式

前置条件

指定事件负责人、经批准的安全证据存放位置以及保留期限。
可复现的症状和不透明的关联标识符。
针对凭据、联系方式、财务条款、文档链接和提供商负载的脱敏规则。

操作步骤

捕获时间戳、服务版本、配置引用、聚合计数器和脱敏错误类别。
在收集实时数据之前，先使用合成记录或只读探针进行复现。
检查诊断包中是否包含密钥和敏感字段，在批准位置加密，并限制仅事件响应人员访问。
问题解决后，根据保留决策删除或退役该诊断包。

调试收集脚本

技能提供了一段 Bash 脚本，用于自动收集诊断信息。脚本会创建以时间戳命名的目录，执行环境检查、API 连通性测试、获取融资轮次、投资者样本、集成状态和速率限制头，最后打包为 tar.gz 文件。脚本内容如下：

#!/bin/bash
set -euo pipefail
BUNDLE="debug-finta-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"

# Environment check
echo "=== Finta Debug Bundle ===" | tee "$BUNDLE/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE/summary.txt"
echo "FINTA_API_KEY: ${FINTA_API_KEY:+[SET]}" >> "$BUNDLE/summary.txt"

# API connectivity
HTTP=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer ${FINTA_API_KEY}" \
  https://api.finta.io/v1/rounds 2>/dev/null || echo "000")
echo "API Status: HTTP $HTTP" >> "$BUNDLE/summary.txt"

# Fundraising rounds summary
curl -s -H "Authorization: Bearer ${FINTA_API_KEY}" \
  "https://api.finta.io/v1/rounds" \
  > "$BUNDLE/rounds.json" 2>&1 || true

# Investor records (limited)
curl -s -H "Authorization: Bearer ${FINTA_API_KEY}" \
  "https://api.finta.io/v1/investors?limit=10" \
  > "$BUNDLE/investors-sample.json" 2>&1 || true

# Connected integrations status
curl -s -H "Authorization: Bearer ${FINTA_API_KEY}" \
  "https://api.finta.io/v1/integrations" \
  > "$BUNDLE/integrations.json" 2>&1 || true

# Rate limit headers
curl -s -D "$BUNDLE/rate-headers.txt" -o /dev/null \
  -H "Authorization: Bearer ${FINTA_API_KEY}" \
  https://api.finta.io/v1/rounds 2>/dev/null || true

tar -czf "$BUNDLE.tar.gz" "$BUNDLE" && rm -rf "$BUNDLE"
echo "Bundle: $BUNDLE.tar.gz"

分析诊断包

解压后可使用以下命令分析：

tar -xzf debug-finta-*.tar.gz
cat debug-finta-*/summary.txt                  # Auth + connectivity overview
jq '.[] | {id, name, status}' debug-finta-*/rounds.json  # Active rounds
jq 'length' debug-finta-*/investors-sample.json          # Investor count check
grep -i "ratelimit\|retry" debug-finta-*/rate-headers.txt

自动化健康检查

技能还提供了一段 TypeScript 异步函数用于检查 Finta API 状态：

async function checkFinta(): Promise<void> {
  const key = process.env.FINTA_API_KEY;
  if (!key) { console.error("[FAIL] FINTA_API_KEY not set"); return; }

  const res = await fetch("https://api.finta.io/v1/rounds", {
    headers: { Authorization: `Bearer ${key}` },
  });
  console.log(`[${res.ok ? "OK" : "FAIL"}] API: HTTP ${res.status}`);

  if (res.ok) {
    const data = await res.json();
    console.log(`[INFO] Active rounds: ${Array.isArray(data) ? data.length : 0}`);
  }
}
checkFinta();

适用场景

排查 CRM 同步失败。
排查投资者记录缺失。
排查轮次更新错误。
排查认证问题。
将输出附加到 Finta 支持工单以加速融资工作流问题的解决。

常见问题与排查

症状	诊断包中检查项	修复方法
API 返回 401	summary.txt 显示 HTTP 401	在 Finta Settings > API Keys 中重新生成 API 密钥
轮次列表为空	rounds.json 返回空数组	在 Finta 仪表板中确认轮次存在；检查工作区权限
投资者同步缺失	investors-sample.json 记录数少于预期	检查 integrations.json 中的 CRM 集成；重新授权连接
集成断开	integrations.json 显示错误状态	从 Finta Settings > Integrations 重新认证集成
速率限制（429）	rate-headers.txt 显示 Retry-After	降低轮询频率；批量处理投资者查询

错误处理

如果检测到密钥、未脱敏导出或未经授权的接收者，立即停止收集；如果可能已暴露，轮换凭据。
将缺失的诊断信息记录为缺口，而不是无差别地扩大收集范围。
如果怀疑数据暴露，先通过事件流程上报，再继续常规故障排查。

限制

需要事件负责人、经批准的安全证据位置和保留期限等前置条件。
收集前需定义脱敏规则。
敏感原始证据必须存放在索引之外的安全位置。
诊断包需按保留决策删除或退役。
关于收费、价格、平台支持等具体信息暂未提供。