# 研究档案抓取人工智能研究对话（ChatGPT、Gemini、Claude）和网页，使用 YAML frontmatter 将它们归档为 markdown 文件，并创建交叉引用的 GitHub 问题 - 每一步都进行强制身份验证。 ## 首先 - TodoWrite 任务模板 **强制**：在进行任何归档工作之前选择并加载适当的模板。 ### 模板 A - 完整存档（抓取 + 保存 + 发布） 1. 身份预检 — 验证 GH_ACCOUNT 或通过curl /user 解析 2. 抓取 URL — 根据 url-routing.md 路由到 Firecrawl 或 Jina 3. 保存到文件 — YYYY-MM-DD-{slug}-{source_type}.md 和 frontmatter 4. 调查标签 — gh 标签列表，重复使用现有的，最多 3-6 个 5. 创建 GitHub 问题 — 将 --body 与 heredoc 或 --body-file 一起使用 6. 更新 frontmatter — 添加 github_issue_url 和 github_issue_number 7. 在问题上发布规范的反向链接评论 ### 模板 B - 仅保存（没问题） 1.身份预检（仍需要一致性） 2. 抓取 URL — 根据 url-routing.md 路由到 Firecrawl 或 Jina 3. 保存到文件 — YYYY-MM-DD-{slug}-{source_type}.md 和 frontmatter ### 模板 C - 仅问题（文件已存在） 1. 身份预检 2.读取现有文件frontmatter 3.调查标签——gh标签列表，重复使用现有的，最多3-6个 4. 创建 GitHub 问题 — 将 --body 与 heredoc 或 --body-file 一起使用 5. 使用问题交叉引用更新文件 frontmatter 6. 在问题上发布规范的反向链接评论 ** ** ## 身份预检（强制 — 第 0 步） **必须在任何`gh`写入命令之前执行。不可协商。** `gh-repo-identity-guard.mjs` PreToolUse 挂钩提供了一个安全网，但该技能会执行自己的检查作为深度防御。 ### 决议顺序 1. **快速路径** — `GH_ACCOUNT` env var（由每个目录的 mise 设置） 2. **令牌文件名** — 扫描 `~/.claude/.secrets/gh-token-*` 进行单碱基匹配 3. **API调用** — `curl -sH "授权：令牌 $GH_TOKEN" https://api.github.com/user` ### 验证 /usr/bin/env bash << 'IDENTITY_EOF' # 解析已验证用户如果[-n“$GH_ACCOUNT”];然后 AUTH_USER="$GH_ACCOUNT" AUTH_SOURCE="GH_ACCOUNT" 否则 AUTH_USER=$(curl -sf --max-time 5 -H "授权：令牌 $GH_TOKEN" \ https://api.github.com/user 2>/dev/null | grep -o '"登录":"[^"]*"' | cut -d'"' -f4) AUTH_SOURCE="API /用户" 菲 # 解析目标仓库所有者 REPO_OWNER=$(git Remote get-url origin 2>/dev/null | sed -n 's|.*github\.com[:/]$[^/]*$/.*|\1|p') echo“身份验证为：$AUTH_USER（通过$AUTH_SOURCE）” echo "目标存储库所有者：$REPO_OWNER" if [ "$AUTH_USER" != "$REPO_OWNER" ];然后回声“” echo "MISMATCH — 不要继续执行 gh 写入命令" echo "修复：导出 GH_TOKEN=\$(cat ~/.claude/.secrets/gh-token-$REPO_OWNER)" 1号出口菲 echo“身份已验证 - 可以安全继续” IDENTITY_EOF **如果不匹配则阻止** — 显示诊断信息并且不继续任何“gh”写入操作。 ** ** ## 抓取工作流程根据 URL 模式路由抓取请求。有关完整详细信息，请参阅 [url-routing.md]()。 ### 决策树 URL 包含 chatgpt.com/share/ → 吉娜读者 (https://r.jina.ai/{URL}) → 使用curl（不是WebFetch——它是总结而不是返回原始数据）网址包含gemini.google.com/share/ → Firecrawl（JS-重 SPA） → 预检：ping -c1 -W2 172.25.236.1 URL 包含 claude.ai/artifacts/ 或者是静态网页 → 吉娜读者 (https://r.jina.ai/{URL}) → 使用WebFetch 或curl ### Firecrawl Scrape（带健康检查+自动复活） **关键**：当内部进程停止运行时，Firecrawl 容器可能会在 `docker ps` 中显示“Up”（RAM/CPU 过载导致容器内的工作线程崩溃）。刮痧前务必进行深度健康检查。 /usr/bin/env bash << 'SCRAPE_EOF' 设置-euo管道故障 # 第 1 步：检查 ZeroTier 连接如果！ ping -c1 -W2 172.25.236.1 >/dev/null 2>&1;然后 echo“错误：Firecrawl 主机无法访问。检查 ZeroTier：zerotier-cli 状态” 1号出口菲 # 第 2 步：深度健康检查 — 测试实际 API 响应，而不仅仅是容器状态 # 端口 3003（包装器）可以接受 TCP，但如果 Firecrawl API (3002) 内部已死，则返回空 HTTP_CODE=$(ssh Littleblack 'curl -sf -o /dev/null -w "%{http_code}" --max-time 10 \ -X POST http://localhost:3002/v1/scrape \ -H“内容类型：application/json”\ -d "{\"url\":\"https://example.com\",\"formats\":[\"markdown\"]}"' 2>/dev/null ||回显“000”） if [ "$HTTP_CODE" = "000" ] || [“$HTTP_CODE”=“502”]|| [“$HTTP_CODE”=“503”];然后 echo“警告：Firecrawl API 不健康（HTTP $HTTP_CODE）。正在尝试恢复...” # 步骤 2a：检查 docker 日志中是否有 WORKER STALLED（RAM/CPU 过载） ssh Littleblack 'docker 日志 firecrawl-api-1 --tail 20 2>&1 | grep -i“停滞\|错误\|退出”||真' # 步骤 2b：重新启动关键容器 ssh Littleblack 'docker restart firecrawl-api-1 firecrawl-playwright-service-1' 2>/dev/null echo“容器已重新启动。等待 API 初始化 20 秒...” 睡20 # 步骤 2c：验证恢复 HTTP_CODE=$(ssh Littleblack 'curl -sf -o /dev/null -w "%{http_code}" --max-time 10 \ -X POST http://localhost:3002/v1/scrape \ -H“内容类型：application/json”\ -d "{\"url\":\"https://example.com\",\"formats\":[\"markdown\"]}"' 2>/dev/null ||回显“000”） if [ "$HTTP_CODE" = "000" ] || [“$HTTP_CODE”=“502”]|| [“$HTTP_CODE”=“503”];然后 echo“错误：Firecrawl 重新启动后仍然不正常（HTTP $HTTP_CODE）。” echo“需要手动干预。尝试：ssh littleblack 'cd ~/firecrawl && docker compose up -d --force-recreate'” echo "回退到 Jina Reader: https://r.jina.ai/${URL}" 1号出口菲 echo "Firecrawl 恢复成功。" 菲 # 第三步：通过包装器刮掉内容=$(curl -s --max-time 120 "http://172.25.236.1:3003/scrape?url=${URL}&name=${SLUG}") 如果[-z“$内容”];然后 echo“错误：Scrape 返回空。尝试 Jina 后备：https://r.jina.ai/${URL}” 1号出口菲回显“$内容” SCRAPE_EOF ### 已知故障模式：容器“启动”但进程死机 **症状**：`docker ps` 显示状态为“Up 4 days”的容器，但 `curl localhost:3002` 返回连接重置。 **根本原因**：Firecrawl 工作线程耗尽 RAM/CPU（观察到：“cpuUsage=0.998，memoryUsage=0.858”）。内部 Node.js 进程退出，但 Docker 容器保持活动状态，因为入口点 shell 仍在运行。 **诊断**： ssh Littleblack 'docker 日志 firecrawl-api-1 --tail 50 2>&1 | grep -E "STALLED|cpuUsage|exit"' # 查找：WORKER STALLED {"cpuUsage":0.998,"memoryUsage":0.858} **修复**：“docker restart”（不是“docker compose restart”——可能需要撰写目录的权限）： ssh Littleblack 'docker restart firecrawl-api-1 firecrawl-playwright-service-1' sleep 20 # 等待API初始化 # 验证： ssh Littleblack 'curl -s -o /dev/null -w "%{http_code}" http://localhost:3002/v1/scrape' ** ** ## 文件保存 ### 命名约定 YYYY-MM-DD-{slug}-{source_type}.md * `slug` — kebab-case 摘要（最多 50 个字符） * `source_type` — 来自枚举：`chatgpt`、`gemini`、`claude`、`web` **默认位置**：当前项目中的`docs/research/`。 ### YAML Frontmatter 有关完整的字段合同，请参阅 [frontmatter-schema.md]()。 --- 来源网址：https://chatgpt.com/share/... source_type：chatgpt-共享 scraped_at：“2026-02-09T18:30:00Z” 型号名称：gpt-4o 自定义 gpt 名称：Cosmo claude_code_uuid：SESSION_UUID github_issue_url：“” github_issue_number：“” --- 将 `github_issue_url` 和 `github_issue_number` 留空 - 创建问题后更新。 ** ** ## GitHub 问题创建 ### 标签调查首先调查现有标签——优先重复使用，仅在概念真正新颖时才创建。 gh 标签列表 --repo 所有者/repo --limit 100 **政策**：每期最多 3-6 个标签。常见标签：“研究”、“ai-output”、“chatgpt”、“gemini”、“archival”。 ### 创建问题将“--body”与heredoc一起使用以进行内联组合，或将“--body-file”用于非常大的内容。 /usr/bin/env bash << 'ISSUE_EOF' # 将正文写入临时文件猫 > "/tmp/issue-body-${SLUG}.md" << 'BODY_EOF' ## 总结存档研究内容的简要描述。 ## 来源 - **URL**：SOURCE_URL - **类型**：源类型 - **型号**：型号名称 - **已刮擦**：scraped_at ## 主要发现 - 发现1 - 发现2 ## 存档文件 `文档/研究/FILENAME.md` BODY_EOF # 创建问题 gh 问题创建 \ --repo 所有者/repo \ --title“研究：此处的描述性标题”\ --body-file "/tmp/issue-body-${SLUG}.md" \ --标签“研究，人工智能输出” # 清理 rm -f“/tmp/issue-body-${SLUG}.md” 问题_EOF ### 更新 Frontmatter 创建问题后，使用问题 URL 和编号更新存档文件的 frontmatter。 ** ** ## 规范反向链接评论对链接回存档文件的问题发表评论： **存档**：`docs/research/YYYY-MM-DD-slug-source_type.md` 已删除：2026-02-09T18:30:00Z 来源：[chatgpt-share](https://chatgpt.com/share/...) 会话：SESSION_UUID ** ** ## 变更后清单修改此技能后： 1. YAML frontmatter 有效（描述中没有冒号） 2.描述中当前的触发关键字 3.所有`./references/`链接解析 4. 身份预检部分仍然是工作流程中的第一位 5. 将更改附加到 [evolution-log.md]() 6. 验证：`uv runplugins/plugin-dev/scripts/skill-creator/quick_validate.pyplugins/gh-tools/skills/research-archival` 7. 验证链接： `bun run plugins/plugin-dev/scripts/validate-links.ts plugins/gh-tools/skills/research-archival` ** ** ## 故障排除问题 |原因 |修复 ---|---|--- 错误的帐户发布 | GH_TOKEN 不匹配 |检查`mise env | grep GH_TOKEN`，验证`GH_ACCOUNT` 正文超过 65536 个字符 | GitHub API 限制 |跨问题正文+第一条评论分开 Firecrawl 无法到达 | ZeroTier 下降 | `ping 172.25.236.1`，检查 `zerotier-cli status` Firecrawl“向上”但死了|容器存活，进程崩溃 | `docker restart firecrawl-api-1 firecrawl-playwright-service-1`，等待 20 秒 Firecrawl 工人停滞不前| RAM/CPU 过载（>85% 内存）|同上；检查“docker 日志 firecrawl-api-1 --tail 50” 刮擦返回空 | JS-重页面超时|增加Firecrawl超时，尝试Jina后备 Jina 返回登录页面 shell | Gemini 登录墙（未渲染）|必须对“gemini.google.com/share/*”网址使用 Firecrawl 错误解析错误 |过时的 .mise.toml 语法 |运行 `mise doctor`，检查 `[hooks.enter]` 语法身份保护块 |非所有者帐户 | `导出 GH_TOKEN=$(cat ~/.claude/.secrets/gh-token-OWNER)` ## 参考文献 * [Frontmatter Schema]() — YAML 字段合约 * [URL 路由]() — Scraper 路由表 * [进化日志]() — 更改历史记录

研究档案

包含技能