gbrain archive-crawler 技能解析：在个人归档中挖掘高价值内容的安全爬取协议

人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载本指南围绕 gbrain 仓库中的 archive-crawler 技能 展开讲解如何让 Agent 在本地挂载盘、Dropbox、Backblaze B2、Gmail 导出.mbox等个人档案树中遵循一条强制安全围栏gbrain.yml显式白名单完成「盘点 → 爬取 → 摄入」三阶段流程过滤出用户自己的写作、想法与关系网络并沉淀为大脑页面brain page。读完本文你将掌握安全门禁的配置与失败行为、manifest 状态页的设计、黄金内容过滤器gold filter的判定表、分文件类型文本 /.mbox/.doc/.pst/ 压缩包 / 图片的处理方案以及 schema-generic 归档规则与反模式清单。技能定位一个通用档案管理员而非一次性脚本archive-crawler 是 gbrain 技能体系skills 目录中的一个「抓取类」技能。它的定位不是把某个固定目录搬进大脑而是提供一个通用引擎在显式白名单内探索任意一棵个人内容树过滤出「金子」用户自己的写作、想法、人际关系并以交互方式呈现给用户复核。从技能元数据skills/archive-crawler/SKILL.md 的 frontmatter可以看到它的关键声明mutating: true、writes_pages: true——这是一个会写入大脑页面的技能writes_to声明了它允许写入的目录originals/、personal/、ideas/triggers定义了路由触发词例如 crawl my archive、find gold in my archive、scan my dropbox for、mine my old files for。这些触发词与路由评测数据一致skills/archive-crawler/routing-eval.jsonl 中每条 intent 都至少包含一个触发子串如Please crawl my archive and surface the writing worth keeping→expected_skill: archive-crawler保证技能路由是可评测、可回归的。技能在 skills/manifest.json 中登记路径为archive-crawler/SKILL.md。安全门禁REQUIRED无例外没有白名单就拒绝运行这是本技能最重要的契约也是理解其设计哲学的入口。门禁规则archive-crawler拒绝运行除非在gbrain.yml中显式设置archive-crawler.scan_paths:。这是一道刻意的安全围栏防止 Agent 把扫描范围无限外扩进而摄入敏感内容税务 PDF、医疗记录、凭据文件# gbrain.yml — allow-list 是强制项 archive-crawler: scan_paths: - ~/Documents/writing/ - ~/Dropbox/Archive/ - /mnt/backup/old-letters/ # allow-list 内部的可选 deny-list # deny_paths: # - ~/Documents/finances/ # - ~/Documents/medical/若scan_paths缺失或为空技能将以明确信息退出archive-crawler: refusing to run. No archive-crawler.scan_paths: allow-list in gbrain.yml. Add explicit paths the agent is permitted to scan, then re-run. This is a safety fence — the agent will not infer whats safe to read.注意最后一句的立场Agent 不会自行推断什么是安全的。这与传统「模型自主判断」的思路相反——凡是敏感边界问题一律交由用户在配置中显式声明。源码级的门禁实现该契约由 src/core/archive-crawler-config.ts 强制实施其解析模式与 src/core/storage-config.tsv0.22.11 存储分层中的db_tracked/db_only白名单模式保持一致。本仓库根目录的 gbrain.yml 恰好展示了同源模式storage.db_tracked列出人工维护的目录people/、companies/、ideas/等storage.db_only列出批量机器生成内容——archive-crawler 的scan_paths正是这套「显式白名单」哲学的又一实例。从源码看门禁的实现细节远超一个简单的「非空检查」缺失即报错loadArchiveCrawlerConfig()在以下情况抛出ArchiveCrawlerConfigError且携带可区分的错误码missing_section——gbrain.yml不存在、无 brain repo 路径、或存在但没有archive-crawler小节empty_scan_paths——小节存在但scan_paths为空或[]invalid_path——路径形状违规相对路径、含..路径穿越parse_error——YAML 解析失败。 错误码的存在让 CLI / 技能消费方可以区分「需要配置」与「配置坏了」两类问题。路径必须绝对化相对路径被拒绝相对路径依赖 cwd而 cwd 不受 Agent 控制~/会展开为主目录。路径穿越拒绝凡字面包含..的路径一律拒绝——即使resolve()后它「安全地」落在白名单内也要拒绝因为拦截的是意图本身。测试明确覆盖了~/Documents/../../../etc/passwd这类逃逸尝试。目录边界前缀匹配每个路径在规范化后都会补上平台自身的结尾分隔符Windows 为\POSIX 为/保证/a/b/不会匹配/a/bc/。比较时统一经由toComparablePrefix()Windows 上折叠分隔符并小写NTFS 大小写不敏感否则...\writing\Private\拼作private时会漏掉敏感文件形成 fail-openPOSIX 上保持原样\是合法文件名大小写敏感折叠反而会碰撞。isPathAllowed(candidate, config)候选路径必须落入至少一个scan_paths且不得落入任何deny_paths——双层判定。这些行为全部被 test/archive-crawler-config.test.ts 钉死包括missing_section三种触发方式、empty_scan_paths、相对路径与遍历拒绝、~/展开、deny_paths可选项、目录边界不误匹配/writing/不匹配/writing-stuff/、遍历折叠后的拒绝、以及 Windows 上的大小写不敏感与 POSIX 上的大小写敏感对照测试。对 Windows 上「\与/混用导致前缀永不匹配」的历史 bug测试也做了回归钉死。这意味着门禁不是文档建议而是可验证的强制行为。概念模型Source源源是任何待探索的文件树。每个源具备type类型local|dropbox|backblaze|gmail-takeout|mbox|pstroot根文件系统路径、Dropbox 路径、B2 前缀或 mbox 路径manifest清单一张跟踪进度的脑页位于projects/archive-slug/STATUS.mdManifest清单每次归档探索都会获得一张 manifest 脑页跟踪五类信息树盘点Tree inventory——文件夹 / 文件 / 大小 / 类型分流状态Triage status——每个条目的状态⬜ unseen未看/ reviewed已复核/✅ ingested已摄入/⏭️ skip跳过/ high-signal高信号用户反应User reactions——用户反馈时记录原话遵循 skills/conventions/quality.md 的 exact-phrasing 规则优先级队列Priority queue——下一步探索什么按序排列会话日志Session log——每会话展示了什么的时间戳记录。manifest 的存在让整个爬取过程可断点续跑任何条目在展示前都要先查 manifest绝不重复展示。Gold filter黄金内容过滤器在向用户展示任何内容之前必须先过过滤器保留展示跳过记录存在不展示个人写作日记、信件、反思、随笔系统文件、配置、package.json、node_modules对话IM 日志、有实质内容的邮件线程二进制大块图片 / 视频想法、论点、框架收据、发票、税务文档关系材料与重要人物的往来信件垃圾邮件、简报、邮件列表批量内容创意作品诗歌、故事、有灵魂的代码损坏 / 空文件起源故事重要事物的第一版情绪内容愤怒、爱、悲伤、发现这张表是爬取阶段的「判据」也是产品哲学的核心档案的价值密度极不均匀Agent 的职责是替用户做第一轮价值筛选。三阶段协议Phase 1Inventory盘点面对一个新源时确认scan_paths已设置安全门禁未设置则退出绘制树结构——列出文件夹 文件 大小 日期范围分类文件夹——按可能的内容类型分组写作、邮件、代码、照片、文档、系统创建 manifest——写入projects/archive-slug/STATUS.md含完整清单提出优先级队列——按黄金密度给文件夹排序呈现给用户——展示地图和建议顺序允许用户推翻。Phase 2Crawl爬取按优先级顺序逐个文件夹推进先读后展示——打开每个候选文件应用黄金过滤器跳过噪音一次只展示一件——黄金项目逐条呈现供复核捕获原话反应——用用户的原话记录在 manifest 中遵循 quality 公约值得保留即摄入——立即创建脑页更新 manifest——每次交互后标记条目状态绝不重播——展示任何内容前先查 manifest。Phase 3Ingest摄入当某条值得保留时按primary subject首要主题归档依据 skills/_brain-filing-rules.md用户自己的写作 / 想法 / 起源故事内容 →originals/slug.md反思 / 个人生活内容 →personal/slug.md产品 / 商业想法 →ideas/slug.md关于某个具体人物的信件或线程 →people/person/timeline反向链接信件本体落在personal/slug.md或originals/slug.md技能是 schema-generic 的它不硬编码任何时代文件夹结构例如「pre-2003 放originals/archive/」「post-2019 放originals/yc-era/」。用户的归档规则从 skills/_brain-filing-rules.json 在运行时读取Agent 在这些受认可目录内逐页决定内容落点。值得注意_brain-filing-rules.json中originals/与ideas/两个目录的说明都显式点名了 archive-crawlervoice-note-ingest, archive-crawler, signal-detector route content here when the user is the originatorarchive-crawler ... file here when content is something to potentially act on且配套说明_brain-filing-rules.md定义了「按首要主题归档」决策协议、Notability Gate拿不准就不建页、以及Iron Law 反向链接任何提到已有脑页人物/公司的条目都必须从该实体页回链到新页。这三者共同约束了摄入阶段的行为。Brain page 格式摄入产出--- title: [Title or first line] type: original source_type: [local|dropbox|backblaze|gmail-takeout|mbox|pst] source_path: [path within the allow-listed scan_paths] date: YYYY-MM-DD # date from the file metadata or content people: [person-1, person-2] tags: [tag-1, tag-2] --- # [Title] [Summary: what it is, when its from, why it matters] **Users reaction:** [exact quote, no paraphrasing] ## Context [Cross-links to people, concepts, projects.] --- [Raw source material below the line — full text]注意 frontmatter 中source_type与source_path的存在每个摄入页都保留来源可追溯性与_brain-filing-rules.md中「原始来源保留」gbrain files upload-raw大文件云端化 .redirect.yaml指针共同构成溯源链路。文件类型处理器纯文本 / HTML / Markdown直接读取HTML 展示时剥离标签。.mbox邮件归档import mailbox mbox mailbox.mbox(/path/to/file.mbox) for msg in mbox: body if msg.is_multipart(): for part in msg.walk(): if part.get_content_type() text/plain: body part.get_payload(decodeTrue).decode(utf-8, errorsreplace) break else: body msg.get_payload(decodeTrue).decode(utf-8, errorsreplace) # Apply gold filter要点decodeTrue处理 MIME 编码errorsreplace兜底乱码多部件邮件只取第一个text/plain部分解析结果仍要过黄金过滤器。.doc/.docx# .docx (modern) python3 -c import zipfile, xml.etree.ElementTree as ET with zipfile.ZipFile(/path/to/file.docx) as z: tree ET.parse(z.open(word/document.xml)) print(.join(t.text or for t in tree.iter({http://schemas.openxmlformats.org/wordprocessingml/2006/main}t))) # .doc (legacy, requires antiword or catdoc) antiword /path/to/file.doc 2/dev/null || catdoc /path/to/file.doc 2/dev/null.docx本质是 zip 包提取word/document.xml中所有w:t节点文本即可.doc依赖antiword或catdoc外部工具2/dev/null静默失败并尝试备选。.pstOutlook 归档# Validate first; many PSTs are null bytes python3 -c with open(/path/to/file.pst, rb) as f: print(Valid PST if f.read(4) b!BDN else CORRUPT/NULL) # If valid: readpst -o /tmp/pst-output /path/to/file.pst先做魔数校验!BDN——大量 PST 是空字节损坏文件避免白跑工具有效后再用readpst解出。.zip/.tar/.tar.gz解压到临时目录然后递归遍历解出的树——压缩包被视为嵌套源。图片记录存在性 元数据文件名、大小、日期。除非用户要求否则不展示。将扫描件 / 肖像照标记为潜在个人内容。Manifest 模板--- title: [Archive Name] — Ingestion Status type: project created: YYYY-MM-DD updated: YYYY-MM-DD source_type: [local|dropbox|...] scan_paths: [paths from gbrain.yml] --- # [Archive Name] — Ingestion Status ## Source - **Type:** [local|dropbox|...] - **Allow-listed paths:** [from gbrain.yml] - **Total files:** [N] - **Total size:** [X GB] - **Date range:** [earliest] — [latest] ## Inventory ### [Folder 1] | Item | Type | Size | Status | Reaction | |------|------|------|--------|----------| | file1.txt | text | 2KB | ✅ ingested | exact quote | | file2.doc | doc | 15KB | ⏭️ skip | — | | file3.html | html | 4KB | ⬜ unseen | — | ### [Folder 2] ... ## Priority Queue 1. [Highest priority — why] 2. [Next — why] ... ## Session Log ### YYYY-MM-DD — [Session topic] - Reviewed: [list] - Reactions: [exact quotes] - Ingested: [brain pages created] - Next: [whats queued]这个模板把「进度可审计」落到了实处scan_paths回填自 gbrain.yml配置与事实对账Inventory 表格即分流状态看板Session Log 让多会话爬取有完整的可追溯历史。反模式清单❌ 在未设置archive-crawler.scan_paths:的情况下运行。硬性拒绝这是安全契约绝不绕过。❌ 硬编码时代化归档路径如originals/archive/、originals/yc-era/。应在运行时读取归档规则。❌ 重播 manifest 中已标记的条目。用户的时间是最稀缺的资源。❌ 转述用户反应。只用原话。❌ 把找到的内容包裹进「经验教训 / 要点」里。让故事自己呼吸。❌ 内容提到已有脑页的人物 / 公司时跳过反向链接。这是 skills/conventions/quality.md 中的 Iron Law。最后一条值得展开quality 公约把「每条写入脑页的事实必须带[Source: ...]内联引用」与「反向链接」列为强制项archive-crawler 的摄入页含Users reaction原话与## Context交叉链接区正是这两个规则的直接消费者——爬取不只是把文件变成页面而是把内容接进大脑的知识图谱。相关技能skills/voice-note-ingest/SKILL.md——音频捕获使用相同的原话记录模式skills/idea-ingest/SKILL.md——单链接 / 单文章摄入使用相同的按首要主题归档规则skills/conventions/quality.md——引用、反向链接与声音风格的统一公约。另外_brain-filing-rules.md与_brain-filing-rules.json是「人类可读 机器可审计」双形态的典范JSON 的 description 明确说 The .md companion is the human explainer; this JSON is whatgbrain check-resolvableaudits against. Keep both in sync.archive-crawler 是这套规则的主要运行时消费者之一。契约与输出格式技能的「Contract」小节承诺路由与 frontmatter 中的触发器一致输出只落在writes_to:声明的目录下引用的公约quality.md、brain-first.md、_brain-filing-rules.md得到遵守隐私契约被保留无真实姓名、无 fork 特定文件系统路径字面量、无上游 fork 引用。该小节与「Output Format」小节的字面标题都是为了 conformance 测试test/skills-conformance.test.ts而存在——技能的可验证性本身就是仓库的工程要求。小结archive-crawler 展示了 gbrain 技能体系的一个关键模式把「敢于扫描用户私密档案」这类高风险操作用三层机制约束起来——配置层的显式白名单src/core/archive-crawler-config.ts 的 normalize validate prefix-match、行为层的三阶段协议盘点 / 爬取 / 摄入与黄金过滤器、以及输出层的 manifest 追踪与 quality 公约原话引用、反向链接、按首要主题归档。它的 schema-generic 设计运行时读取 skills/_brain-filing-rules.json让技能不随某个人的归档布局而腐化而测试套件test/archive-crawler-config.test.ts保证安全门禁在任何平台、任何拼写变体、任何历史回归面前都稳如磐石。赞分享人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载相关推荐GPT-Crawler与人工智能预测爬取内容价值GPT Crawler与人工智能预测爬取内容价值 内容价值评估的行业痛点与解决方案 企业在构建自定义GPTGenerative Pre trained TrAI 应用RAG人工智能网页爬虫如何利用GPT-Crawler挖掘数据价值从网站爬取到智能分析的完整指南如何利用GPT Crawler挖掘数据价值从网站爬取到智能分析的完整指南 GPT Crawler是一款强大的开源工具能够从指定URL爬取网站数据并生成知识文AI 应用RAG人工智能网页爬虫gbrain archive-crawler 技能实战为个人档案库构建安全的淘金爬虫与知识入库流水线gbrain archive crawler 技能实战为个人档案库构建安全的淘金爬虫与知识入库流水线 导读 本文围绕 gbrain 仓库中的 archiv人工智能RAGAgent 记忆MCP 服务知识管理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考