cognis-digital/docarchive

# docarchive **用于公开记录和文档集合的结构化归档索引器 + 全文搜索。** `docarchive` 可导入包含文本、markdown 或 JSON 文档的文件夹 （解密摘要、公告、分析报告），构建带有元数据（标题、日期、来源、标签）的 可搜索倒排索引，并通过 TF-IDF 评分、日期/标签过滤以及代码片段 高亮显示，来响应排序的全文查询。它完全在本地运行，**无需网络访问**， 且仅依赖 Python 标准库。 其范围侧重于防御和分析：整理、索引和搜索您已拥有的 文档集合。 ## 安装说明 要求 Python 3.10+。 ``` git clone docarchive cd docarchive pip install -e . ``` 此操作将安装 `docarchive` 控制台命令。用于开发/测试： ``` pip install -e ".[test]" ``` ## 使用说明 ### 1. 构建索引 ``` $ docarchive index examples --out examples.index.json Indexed 4 document(s), 187 unique term(s) -> examples.index.json ``` ### 2. 搜索 ``` $ docarchive search examples.index.json "grid resilience" 1. Advisory on Grid Resilience During Peak Demand (score 5.8124) id: advisory-power-grid.md [2026-03-14 | Cognis Digital Analytical Notes | tags: energy, infrastructure, resilience] ...Operators of regional transmission networks should review contingency plans ahead of sustained peak-demand windows... controlled load curtailment is preferable to uncontrolled cascading outages... ``` 按标签、日期过滤并输出 JSON： ``` $ docarchive search examples.index.json "minerals" --tag supply-chain 1. Critical Minerals Supply Chain Overview (score 2.6021) id: report-supply-chain.txt [2026-01-22 | Cognis Digital Analytical Notes | tags: economics, minerals, supply-chain] Critical **minerals** underpin modern manufacturing, from batteries to magnets... $ docarchive search examples.index.json "osint methods" --since 2026-02-01 --json [ { "id": "note-osint-methods.md", "title": "Open-Source Intelligence Methods for Analysts", "date": "2026-02-19", "source": "Cognis Digital Analytical Notes", "tags": ["methods", "osint", "research"], "score": 4.812345, "snippet": "Open-source intelligence relies only on publicly available information..." } ] ``` ### 3. 统计信息 ``` $ docarchive stats examples.index.json Documents: 4 Unique terms: 187 Total tokens: 263 Date range: 2025-11-08 .. 2026-03-14 Tags: atmosphere: 1 economics: 1 energy: 1 history: 1 infrastructure: 1 methods: 1 minerals: 1 osint: 1 research: 2 resilience: 1 supply-chain: 1 ``` ## 文档格式 * **`.txt` / `.md`** — 纯文本或 markdown 文本。文件顶部由 `---` 行分隔的可选 front matter 可提供元数据： --- title: My Report date: 2026-03-14 source: Cognis Digital Analytical Notes tags: energy, resilience --- 正文内容如下... 如果未提供 `title`，则使用第一个非空行（并移除开头的 `#`）。 * **`.json`** — 包含位于 `text`、`body` 或 `content` 下的正文，以及 可选的 `title`、`date`、`source` 和 `tags`（字符串或数组）的对象。 日期按原样存储；ISO-8601 (`YYYY-MM-DD`) 可正确进行排序和过滤。 ## 功能 - 递归导入带有元数据的 `.txt`、`.md` 和 `.json` 文档。 - 包含术语 postings、术语频率和文档频率的倒排索引。 - 从零开始实现的 TF-IDF 排序（公式如下）。 - 精心设计的 tokenizer，包含紧凑、项目原创的英语停用词列表以及对连字符术语的支持。 - 排序搜索包含评分、元数据以及以首个匹配项为中心的高亮代码片段。 - 提供 `--tag`、`--since`、`--limit` 和 `--json` 查询选项。 - `stats` 摘要：文档数、唯一术语、token 总数、日期范围、标签。 - 仅使用标准库。包含真实的 pytest 套件，覆盖 tokenizing、索引建立、排序顺序、过滤器、代码片段以及 CLI。 ## 排序公式 对于查询 `Q`（其唯一术语集合）和文档 `d`，相关性评分 是出现在 `d` 中的查询术语 `t` 的总和： ``` score(d, Q) = sum over t in Q of tf_weight(t, d) * idf(t) ``` 其中 `N` = 文档总数，且 `df(t)` = 包含术语 `t` 的文档 数量： ``` tf_weight(t, d) = 1 + log10( tf(t, d) ) # sublinear term frequency idf(t) = log10( (N + 1) / (df(t) + 1) ) + 1 # smoothed inverse document frequency ``` 次线性 `tf` 削弱了在单个文档中重复多次的术语的影响；平滑处理的 `idf`（在分子和分母中带有 `+1` 平滑）避免了除以零，保持非负，并奖励更罕见、更具 区分度的术语。仅返回包含至少一个查询术语的文档。评分在单个索引内具有可比性。平局通过文档 id 打破，以实现确定性排序。 ## 许可证 许可证：COCL 1.0 由 **Cognis Digital** 维护。

标签：Python, 代码示例, 全文检索, 幻觉缓解, 搜索引擎, 数据分析, 文档索引, 无后门, 逆向工具