项目定位与目标

ZettelForge 是一个面向网络威胁情报（CTI, Cyber Threat Intelligence）分析场景的"卡片盒（Zettelkasten）"知识管理工具，专注于把分散的威胁报告、检测规则与外部情报合并进一个可检索、可推理的知识图谱。它以"MemoryNote"为最小语义单元，强调分析人员与自动化代理（agent）在同一份长期记忆上协作。资料来源：README.md:1-40

项目分为两个相互独立又可桥接的"半球"：左侧是面向人工分析的结构化笔记编辑与图谱浏览界面（Web GUI，RFC-015），右侧是面向 LLM 代理与管道的程序化 API；二者共享同一份存储与实体索引层。资料来源：docs/explanation/design-philosophy-dual-hemisphere.md:1-40

核心子系统

ZettelForge 的系统架构可以归纳为以下五个层次：

资料来源：ARCHITECTURE.md:1-80、docs/explanation/architecture.md:1-60。

实体抽取器是连通文本与图谱的关键通道。它已经从最初的 IPv4 提取，逐步扩展到 IPv6（issue #47）、YARA 规则引用（issue #46）以及 Sigma 规则 ID（issue #45），并计划通过 issue #71 为 MemoryNote.Metadata 引入类型化的 DetectionMeta 扩展，使每条规则的 CCCS 等级、来源等元数据不再只存在于 note 正文中。资料来源：README.md:60-120。

端到端数据流

flowchart LR
  A[CTI 报告 / YARA / Sigma] --> B[Ingest 解析]
  B --> C[Entity Indexer]
  C --> D[Knowledge Graph]
  D --> E[MemoryNote 写入]
  E --> F{MemSAD 治理}
  F -- audit --> G[持久化]
  F -- block/quarantine --> H[隔离队列]
  G --> I[RFC-015 Web GUI]
  G --> J[Agent / RFC-016 OSINT]
  J --> K[Collector Executor]
  K --> D

资料来源：SCOPING_DOC.md:1-80、ARCHITECTURE.md:40-120。

写入路径并非单向：RFC-016 Phase 1.5（issue #154）引入了 Collector Executor，把外部 OSINT 采集器（如 maigret）的输出经校验后写回为 CollectorTuple 行，再经 Resolver 写回知识图谱，从而形成"读取 → 富化 → 再写入"的闭环。资料来源：README.md:120-180。

治理、安全与演进

系统把"防御"作为一等公民设计。v2.7.0 引入了 MemSAD 写入期防御，提供 audit / block / quarantine 三种模式（governance.memory_defense 配置），并配套发布 RFC-017 威胁模型；v2.8.0 进一步叠加 AGE-127 提示注入与检索投毒防护，覆盖记忆管线全链路。资料来源：README.md:40-100。

演进路线上，ROADMAP 明确了 RFC-016（OSINT 富化）、RFC-017（威胁建模）、RFC-018（富化作业账本 Phase 0）三阶段的先后顺序；issue #36 提议在 docs/adr/ 下沉淀 ADR，使架构取舍可追溯，避免再次出现将治理覆盖率从 80% 退到 67% 的"反向漂移"（issue #51）。资料来源：ROADMAP.md:1-60。

一句话总结

ZettelForge = Zettelkasten 笔记 + CTI 实体索引 + 知识图谱 + 可治理的 LLM 代理记忆，专为威胁情报分析师与自动化代理在同一长期记忆上协作而设计。

ZettelForge 的核心记忆管线负责将外部情报（CTI 报告、YARA/Sigma 检测规则、OSINT 数据）转化为可检索、可推理的"原子笔记"（MemoryNote）并构建实体关系知识图谱。该管线由四个核心模块串联构成：memory_manager 协调生命周期、memory_store 提供持久化抽象、memory_updater 处理增量写入、memory_evolver 负责合并去重与演化。entity_indexer 从文本中抽取 IOC/检测规则实体，knowledge_graph 将实体与笔记的关系持久化为可查询的图结构。

架构概览

记忆管线采用"摄取 → 索引 → 持久化 → 演化"四段式流水线。memory_manager 作为入口编排器，统一调度写路径与读路径，并挂载安全防护钩子；memory_store 封装底层存储后端（向量库 + 文档库）；memory_updater 负责笔记的追加与字段更新；memory_evolver 在后台定期合并相似笔记、淘汰低价值记录。

flowchart LR
    A[CTI/Detection/OSINT] --> B[entity_indexer]
    B --> C[memory_manager]
    C --> D[memory_updater]
    D --> E[memory_store]
    E --> F[knowledge_graph]
    F --> G[memory_evolver]
    G -.回填.-> E
    C -.查询.-> E

资料来源：src/zettelforge/memory_manager.py:1-120, src/zettelforge/memory_store.py:1-80

核心组件

MemoryManager 与 MemoryNote

MemoryManager 是管线的总控类，持有 MemoryStore 实例并暴露 add_note、query、evolve 等高层 API。MemoryNote 是数据模型核心，包含 id、title、body、tags、metadata 等字段。其中 Metadata 在 issue #71 中被讨论扩展为支持 DetectionMeta 类型化扩展，用于承载 YARA 的 CCCS tier、Sigma 的 rule level 等结构化元数据。

资料来源：src/zettelforge/memory_manager.py:120-260, src/zettelforge/memory_updater.py:40-180

MemoryStore 与持久化层

MemoryStore 提供向量检索与元数据过滤的双索引能力。写路径经过 MemoryUpdater 包装，确保每条笔记在落盘前都经过 MemSAD 写入时校验（v2.7.0 引入的 governance.memory_defense 配置可设为 audit/block/quarantine 三种模式）。age127 模块（v2.8.0 引入）则在整个内存管线中提供 prompt injection 与检索投毒防护。

资料来源：src/zettelforge/memory_store.py:80-200, src/zettelforge/memsad.py:1-100, src/zettelforge/age127.py:1-90

EntityIndexer

EntityIndexer 从文本中抽取结构化实体。社区讨论显示该项目持续扩展抽取能力，包括 IPv4/IPv6 地址（issue #47）、YARA 规则引用（issue #46）、Sigma 规则 ID（issue #45），使得知识图谱节点覆盖更完整的威胁情报维度。抽取结果通过 rule_to_entities 函数返回实体与关系对象（issue #71 中讨论了这些对象目前为 transient，需借助 DetectionMeta 持久化）。

资料来源：src/zettelforge/entity_indexer.py:1-160

MemoryEvolver

MemoryEvolver 后台运行去重与合并任务，依据语义相似度合并重复笔记、生成超链接，并将演化结果回填到 MemoryStore。该机制与 issue #51 提到的治理覆盖率门槛挂钩——演化逻辑本身受 CI 中 67%→80% 的治理覆盖阈值约束。

资料来源：src/zettelforge/memory_evolver.py:1-140

概述

ZettelForge 通过三条外部集成路径把外部威胁情报纳入 Zettelkasten 知识图谱：检测规则解析（Sigma、YARA）、自由文本实体抽取（IPv4/IPv6、Sigma 规则 ID、YARA 规则名）以及 OSINT 主动/被动采集器（RFC-016、AGE-120）。这些模块共同保证 CTI 报告、检测签名仓库、外部世界中的 IOC 与攻击者画像可以被持续摄取、落盘并被召回管线使用。资料来源：src/zettelforge/sigma/__init__.py:1-40、资料来源：src/zettelforge/osint/__init__.py:1-40。

Sigma 检测规则摄取

sigma/parser.py 负责把 YAML 格式的 Sigma 规则解析为结构化对象；sigma/entities.py 进一步把 detection、logsource、tags 等字段映射到知识图谱可用的实体与关系；sigma/tags.py 维护 MITRE ATT&CK 等标签的归一化映射。sigma/ingest.py 提供批量摄取入口，将一组规则文件转换为可写入 MemoryNote 的实体集合；sigma/cli.py 暴露命令行入口，便于在 CI 或运维脚本中离线导入。资料来源：src/zettelforge/sigma/parser.py:1-200、资料来源：src/zettelforge/sigma/entities.py:1-200、资料来源：src/zettelforge/sigma/ingest.py:1-120、资料来源：src/zettelforge/sigma/tags.py:1-80、资料来源：src/zettelforge/sigma/cli.py:1-60。

需要注意的是：YARA 与 Sigma 在 rule_to_entities 的瞬态返回值上会携带 CCCS tier、来源标签等元数据，但默认仅写入 note body。issue #71 提出的 DetectionMeta 扩展计划把这些元数据提升为 MemoryNote.Metadata 的一等公民字段，从而在持久层直接参与过滤与召回。资料来源：src/zettelforge/sigma/entities.py:1-200。

文本实体抽取

entity_indexer.py 是面向自由文本的 IOC 抽取器，使用正则覆盖四类常见实体：IPv4、IPv6（issue #47 新增）、Sigma 规则 ID（issue #45，例如 sigma:apt28_cobalt_strike、Sigma Rule: win_susp_powershell_encoded_cmd）以及 YARA 规则名（issue #46，例如 rule apt28_beacon { ... }、YARA: win_cobalt_strike）。抽取结果会落入 MemoryNote.Metadata 并被后续召回路径消费，因此新增正则类别无需改动上层调用方。资料来源：src/zettelforge/entity_indexer.py:1-300。

OSINT 外部集成

OSINT 层在 v2.8.0 中从「可导入的采集器骨架」演化为端到端执行路径：

• RFC-016 Phase 1.5（issue #154）：osint/executor.py 以输入实体为起点，查询 osint/collectors.py 注册表，匹配命中的采集器，并产出校验后的 CollectorTuple 行；解析器随后把这些行写入知识图谱，并接入 BGP（背景治理协议）流程。
• AGE-120 实时 enrichers（issue #176）：live enrichers 作为可选的 [osint] 扩展提供；maigret 等采集器的事件循环健壮性与 OSINT→recall 可见性作为非阻塞跟进项被追踪，不阻塞安全合并，未安装该 extra 时不会触发任何出站请求。

资料来源：src/zettelforge/osint/collectors.py:1-200、资料来源：src/zettelforge/osint/executor.py:1-150。

取舍与已知限制

当前实现的几个权衡值得记住：

• 检测规则元数据仅部分持久化；DetectionMeta 提案尚未落地，临时数据仅存活于 note body。
• OSINT 网络路径为 opt-in [osint] extra，默认安装下是离线的，避免意外出站。
• IPv6 与 Sigma ID 抽取为近期扩展，旧报告的回填需要手动重跑摄取流程。
• OSINT→recall 可见性是已记录的跟进项，召回阶段目前无法直接看到 enricher 命中。

资料来源：src/zettelforge/entity_indexer.py:1-300、资料来源：src/zettelforge/osint/executor.py:1-150、资料来源：src/zettelforge/sigma/entities.py:1-200。

安全性、治理、部署与运维

概述与威胁模型

ZettelForge 作为长期记忆与知识图谱系统，主要威胁面覆盖摄入、写入、召回、输出四个阶段。RFC-017 威胁模型与 RFC-016 OSINT 防护共同构成了纵深防御链：摄入阶段的恶意 CTI 报告可能污染记忆库；召回阶段的检索结果可能携带提示注入载荷；写入阶段可能引入 PII 与凭据；治理规则随版本迭代可能被静默放宽。本页基于源码梳理 MemSAD、AGE-127、PII 校验、治理 ratchet、可观测性与遥测等模块如何协同应对上述威胁。

写入阶段：MemSAD 内存防御

memory_defense.py 在 v2.7.0 中落地，是写入路径上的 MemSAD（Memory Self-Defense）组件，提供三种工作模式：

• audit：放行可疑内容但记录事件，用于观察期
• block：直接拒绝高风险写入，立即生效
• quarantine：写入隔离区，等待人工或自动复核

模式由 governance.memory_defense 配置项控制，模块作为 MemoryNote 写入管道的中间件被调用 资料来源：src/zettelforge/memory_defense.py:1-80。所有进入长期记忆的内容都需经过风险评估，确保对抗性内容不会静默入库。

召回阶段：AGE-127 与 PII 双向过滤

v2.8.0 引入的 AGE-127 防护由 prompt_injection_guard.py 实现，针对检索投毒（retrieval poisoning）与提示注入攻击，在检索结果注入到 LLM 上下文之前进行清洗与标记 资料来源：src/zettelforge/prompt_injection_guard.py:1-60。

pii_validator.py 并行扫描召回内容中的敏感信息（邮箱、IP、凭据等），与 AGE-127 形成"双向过滤"——一个防御对抗性载荷，一个防御敏感泄露 资料来源：src/zettelforge/pii_validator.py:1-40。

治理与覆盖率 Ratchet

governance_validator.py 实施治理覆盖率阈值。issue #51 记录了一次治理漂移事件：外部评审发现覆盖率目标曾从 80% 退回到 67% 以匹配实际执行水平。当前策略为：

1. CI 持续强制 67% 阈值，不允许回退
2. 记录与 80% 目标的 delta
3. 随覆盖率提升逐步上调阈值（ratchet）

资料来源：src/zettelforge/governance_validator.py:1-120。该机制确保治理目标只能向更严格方向移动，防止漂移重现。

可观测性与遥测

observability.py 提供统一的指标、日志与追踪接口，覆盖记忆管道的写入/召回速率、YARA 与 Sigma 检测规则摄入吞吐量，以及 OSINT enricher 的执行时长与错误率 资料来源：src/zettelforge/observability.py:1-100。

telemetry.py 在 v2.7.0 增强了 actor/caller 兼容性，确保 CLI、HTTP、Agent 等不同调用源的遥测数据能够正确归因 资料来源：src/zettelforge/telemetry.py:1-80。

防御链路总览

flowchart LR
    A[CTI 摄入] --> B[memory_defense]
    B --> C[MemoryNote 存储]
    C --> D[recall 查询]
    D --> E[prompt_injection_guard]
    D --> F[pii_validator]
    E --> G[LLM 上下文]
    F --> G
    G --> H[governance_validator 持续监控]
    H --> I[CI 阈值 67% → 80%]

部署与运维要点

• OSINT 路径：v2.8.0 中的 live enricher 依赖 [osint] 可选 extra，默认关闭，启用时需评估网络策略与超时配置
• 配置编辑：v2.6.2 修复了 /config 页面的 Apply 按钮与枚举下拉，避免治理配置被静默忽略
• 遥测归因：v2.7.0 的 telemetry actor/caller 兼容无需手动迁移
• 数据迁移：v2.7.0 与 v2.8.0 均无需数据迁移即可升级，但建议在升级前备份 MemoryNote 存储

Pitfall Log / 踩坑日志

项目：ThreatRecall/zettelforge

摘要：发现 11 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Add typed DetectionMeta extension to MemoryNote.Metadata。

1. 安全/权限坑 · 来源证据：Add typed DetectionMeta extension to MemoryNote.Metadata

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add typed DetectionMeta extension to MemoryNote.Metadata
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/ThreatRecall/zettelforge/issues/71 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安全/权限坑 · 来源证据：OSINT enrichers (AGE-120) follow-ups: maigret event-loop robustness + OSINT→recall visibility

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OSINT enrichers (AGE-120) follow-ups: maigret event-loop robustness + OSINT→recall visibility
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/ThreatRecall/zettelforge/issues/176 | 来源类型 github_issue 暴露的待验证使用条件。

3. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/ThreatRecall/zettelforge | host_targets=mcp_host, claude_code, claude

4. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/ThreatRecall/zettelforge | README/documentation is current enough for a first validation pass.

5. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/ThreatRecall/zettelforge | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/ThreatRecall/zettelforge | no_demo; severity=medium

7. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/ThreatRecall/zettelforge | no_demo; severity=medium

8. 安全/权限坑 · 来源证据：Add architecture decision records (ADRs)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add architecture decision records (ADRs)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/ThreatRecall/zettelforge/issues/36 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

9. 安全/权限坑 · 来源证据：RFC-016 Phase 1.5: OSINT collector executor, KG ingest, resolver wiring, and BGP

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：RFC-016 Phase 1.5: OSINT collector executor, KG ingest, resolver wiring, and BGP
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/ThreatRecall/zettelforge/issues/154 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

10. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/ThreatRecall/zettelforge | issue_or_pr_quality=unknown

11. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/ThreatRecall/zettelforge | release_recency=unknown