mickywin22/azimuth

# 方位角 [](https://github.com/mickywin22/azimuth/actions/workflows/ci.yml) [](https://github.com/mickywin22/azimuth/actions/workflows/ingest.yml) [](https://github.com/mickywin22/azimuth/actions/workflows/synthesis-freshness.yml) [](LICENSE) [](LICENSE-CONTENT.md) [](https://azimuth.emi-factory.dev/autonomy.html) [](https://azimuth.emi-factory.dev/autonomy.html) [](https://azimuth.emi-factory.dev/autonomy.html) HemySphere L1/L2/L3 知识库原则的公开演示项目，由 Worldmonitor 开源情报数据驱动。 **在线站点: ** — [每周简报](https://azimuth.emi-factory.dev/) · [探询世界数据](https://azimuth.emi-factory.dev/answers.html) · [知识图谱](https://azimuth.emi-factory.dev/graph.html) · [事实与预测基准](https://azimuth.emi-factory.dev/benchmark.html) · [自治计数器](https://azimuth.emi-factory.dev/autonomy.html) 

静态截图（各个独立场景）

 

## 它是什么 —— 公开运行的 HemySphere 原则 这是一个公开的只读知识库，将 HemySphere 的 **L1 源数据 → L2 综合 → L3 规则** wiki 模式应用于从 [Worldmonitor](https://worldmonitor.app) 公共 API 获取的开放全球情报数据。它在一个活跃的、非个人领域的真实场景中验证了这套原则组合 —— 展示了整体架构，而不会暴露任何私有知识库的内容。 该原则是建立在一个 Markdown 语料库之上的三层契约： | 层级 | 存储内容 | 规则 | |-------|---------------|----------| | **L1 — 源数据** | 带有日期的、原封不动的 API 转换结果 (`vault/01 Sources/`) | 只能追加的基准事实；**创建后绝不修改** (由 CI 强制执行) | | **L2 — 综合** | 每个主题一个不断演进的简报 (`vault/02 Briefs/`) | 一位 LLM 策展人**原地深化每条笔记** —— 绝不另起炉灶创建新文件 —— 并且每个论断都带有 `[[wikilink]]` 回溯至其所依据的 L1 笔记 | | **L3 — 规则** | 编辑方针 + 综合契约 (`vault/00 Rules/`) | 规模小、由人类掌控，且**由机器强制执行**：每个条款都对应 CI 中的一道阻断式 lint | **它的定位。** 这个理念与 [Andrej Karpathy 的 *LLM Wiki*](https://github.com/karpathy) 属于同一体系 —— 一个由 LLM 维护的、不断复利增值的知识库，每次对数据的新一轮处理都能解锁新的投影 —— 并且其格式采用了 [Google 的 **Open Knowledge Format (OKF)**](docs/strategy/okf-and-knowledge-graph.md)：azimuth 的 `vault/` 是一个符合 Tier-1 标准的 OKF 知识包（每条笔记都有 frontmatter `type`，预留了 `index.md`/`log.md`，可作为 git 仓库分发），并通过 [Vault-LD OKF 兼容配置](docs/linked-data.md) 提升为带类型的 RDF。HemySphere 原则在这两者之上增加的是**你可以检验的治理机制**：一个不可变的源数据层，针对每个综合论断的出处契约，具有强制力的编辑方针（阻断式 lint，而非指导方针），以及能够从提交的源数据逐字节重建的派生构件（图谱、索引、计数器）。LLM 负责编写简报；而契约决定最终发布什么。 ## 快速开始 ``` # Clone git clone https://github.com/mickywin22/azimuth.git cd azimuth # 安装 dev tooling (pure-stdlib runtime — 无 server，无 third-party deps) uv pip install -e ".[dev]" # 运行 L1 ingest (拉取 WorldMonitor subsets -> 带日期的 L1 notes) python scripts/run_ingest.py ``` ## 复用契约引擎 该原则的执行层以一个可复用的、纯标准库的包形式发布： [`vault_contract/`](vault_contract/__init__.py)。将它指向**你自己的** Markdown 知识库， 在一个 TOML 文件中声明你的契约，每个条款就会变成一道阻断式检查 —— 没有来源的论断、悬空的来源链接、缺失的更新日志、列入黑名单的框架、泄露的 LLM 工具构件，以及 diff 上的 L1 不可变性： ``` pip install "azimuth @ git+https://github.com/mickywin22/azimuth" vault-contract "my-vault/notes" --rules my-rules.toml --sources-root "my-vault/sources" ``` 规则格式记录在[包的 docstring](vault_contract/__init__.py)中； [`rules/azimuth.toml`](rules/azimuth.toml) 是真实的示例 —— CI 在每次 push 时都会 针对此仓库自身的知识库运行通用引擎（azimuth 在 [`synthesis/lint.py`](synthesis/lint.py) 中更为丰富的、具备主题感知能力的 lint 仍然是参考部署）。 ## 可复现性挑战 ``` python scripts/build_graph.py --check # knowledge graph is byte-identical python scripts/build_brief_index.py --check # brief index is byte-identical python scripts/build_autonomy.py --check # autonomy counters are byte-identical ``` 每一个命令只有在从已提交的 `vault/` 重新生成构件，并且能够逐比特完美复现已检入的文件时，才会返回退出代码 `0` —— 正是这同样的保证，让公共读者能够信任这些数字和图谱。渲染整个只读站点的过程同样是确定性的： 在相同的 `vault/` 下运行 `python scripts/build_site.py` 会产生字节完全一致的输出。 **亲自运行活跃引擎**（获取新数据 —— 这是引擎本身，而非可复现性 证明）：`python scripts/run_ingest.py` 会从免费的 WorldMonitor API 拉取新一天的 L1 数据 （匿名会话，无需密钥），而每周执行一次的 `azimuth-curator` 角色会据此演进 L2 简报 的叙述。上述确定性构件随后将从这新的一天数据中重新推导得出。 ## 开发 ``` # 运行 tests pytest tests/ -v # Lint + format ruff check guardrail/ ingest/ tests/ --fix ruff format guardrail/ ingest/ tests/ # Type check mypy guardrail/ ingest/ # Pre-commit hooks pre-commit install ``` ## 公共站点与部署 可供浏览的只读站点（每周的 L2 简报 → L1 源数据 → L3 编辑方针，以及 跨频道知识图谱）通过 `python scripts/build_site.py` 构建，并且**已上线于 **，通过 [`.github/workflows/deploy-cloudflare.yml`](.github/workflows/deploy-cloudflare.yml) 在每次 push 到 `main` 分支时发布至 **Cloudflare Pages**（直接上传 —— 发布过程与仓库可见性解耦；完整说明： [docs/deploy-cloudflare.md](docs/deploy-cloudflare.md))。还存在一个次要的 GitHub Pages 通道 ([`.github/workflows/pages.yml`](.github/workflows/pages.yml))，但这并非 正式的部署方式。 知识图谱既是**可视化的** (`site/graph.html` —— 选择任意两个频道并**追踪**它们是如何连接的)，也 支持通过 [`scripts/query_graph.py`](scripts/query_graph.py) 在命令行中 基于相同的 `site/graph.json` 进行查询： ``` python scripts/query_graph.py connect energy geophysical # the cross-channel answer python scripts/query_graph.py provenance "Greece" # the L1 notes backing an entity python scripts/query_graph.py path "Greece" "Energy Supply" python scripts/query_graph.py bridges # all cross-channel bridges python scripts/query_graph.py hubs --top 8 --json ``` 每一条边都是有类型的 (`has-brief`, `rests-on`, `mentioned-in`, `named-in`, `reported-in`, `located-in`)。该图谱直达 **L1 源数据，而不仅仅是简报**：一条 `mentioned-in` 边包含一个 `weight` (有多少条 L1 笔记提及了该实体)，并且该计数由每个实际源笔记对应的一条 `named-in` 边提供支撑 —— `provenance` 会逐个频道将其重新展开为确切的带日期的 L1 笔记。 除了链接*拓扑结构*之外，该知识库还能提升为一个**类型化 RDF 图谱**。这个 OKF 风格的 Markdown 知识库包加上一个已提交的组合上下文 ([`vault/context.jsonld`](vault/context.jsonld)) 已经是有效的链接数据 —— 即 **Vault-LD OKF 兼容配置** (SPEC 附录 B)。 [`scripts/build_rdf.py`](scripts/build_rdf.py) 会在站点旁导出 `schema.ttl` (本体) + `data.ttl` (作为类型化主体的每条笔记)；`rdflib` 是一个**仅在 CI 中使用**的依赖项，因此 运行时环境依然保持纯粹的标准库。完整说明：[docs/linked-data.md](docs/linked-data.md)。 完整的构建步骤、准备就绪的翻转门禁，以及本地验证命令位于 [docs/deploy.md](docs/deploy.md)。 ## 运维 —— 引擎活跃状态 双轨引擎的健康状态是可观测的，而非假设的 —— 每条轨道都有各自计划的 GitHub Actions 心跳检测，如果停止运行，就会抛出一个去重的跟踪 issue。完整的值班 操作手册 —— 涵盖所有计划任务、触发的警报，以及当徽章变红时的具体响应措施 —— 位于 **[docs/operations.md](docs/operations.md)**。 **L1 摄入** ([`.github/workflows/ingest.yml`](.github/workflows/ingest.yml), 每日) —— 每份简报所依赖的核心引擎： - **工作流内门禁** —— 每次拉取数据后，运行程序都会断言最新提交的 L1 日数据 处于容差范围内 (`scripts/check_ingest_liveness.py --check`)；如果结果过期，任务将失败。 - **故障警报** —— 失败的每日运行会开启（或追加到）一个单独的 `ingest-alarm` 跟踪 issue，从而确保引擎绝不会悄无声息地停止运作。 - **在任何地方** —— 手动检查运行状态： ``` python scripts/check_ingest_liveness.py # alive / STALE, with the latest L1 day + age python scripts/check_ingest_liveness.py --check # exit 1 if the latest L1 day is stale ``` **L2 综合** ([`.github/workflows/synthesis-freshness.yml`](.github/workflows/synthesis-freshness.yml), 每周) —— 与 L1 不同，每周简报由集群策展人（脱离 GitHub 基础设施运行的 LLM 任务）撰写， 因此不能假定在断电情况下它仍能继续运行。此工作流为 L2 轨道提供了同样可见的心跳：每周一，它会对照 最新的 L1 日数据检查每个纯净主题的简报，如果任何一个确实**已逾期**（滞后超过一个每周 周期 —— 即综合任务实际未能运行），就会开启一个单独的 `synthesis-alarm` issue。 仅仅是*过时*（等待下一次预定的策展人处理）的状态则保持静默。 ``` python scripts/check_synthesis_freshness.py # per-theme table: fresh / stale / OVERDUE python scripts/check_synthesis_freshness.py --overdue # exit 1 only if a brief genuinely failed to run ``` ## 自治性 —— 自主运行的证明 azimuth 的重点不在于任何单一的简报 —— 而在于整个流水线能够*自主 运转*：每日的摄入、每周的综合，以及 CI 原则门禁全部自动运行， 每周仅需花费几美分。这一声明是以**确凿的、可核查的计数器**形式展现的，而不是 一句营销口号 —— 运行天数、已提交的每日 L1 摄入量、已编写的 L1 源笔记数、 已维护的 L2 简报数、已呈现的数据通道数，以及一个明确标注的 LLM 花费 估算： - **实时计数器页面:** (源码: [`site/autonomy.html`](site/autonomy.html)) —— 机器可读的配套文件 [`site/autonomy.json`](site/autonomy.json)。 - 每一个计数器都**纯粹从已提交的知识库数据中推导得出，绝不依赖挂钟时间**，因此 它是可逐字节复现的，并受到 CI 的保护 (`build_autonomy.py --check`)。这些计数器 在每次每日摄入时都会重新推导 —— 就像知识图谱和简报索引一样 —— 因此 它们每次只会推进一天，绝不会与底层数据产生偏差。 - 花费是一个诚实的**数量级估算**（运行周数 × 每周少量的 综合成本），并被明确标记为估算值 —— 而非虚假精确的计量账单。 ``` python scripts/build_autonomy.py # rebuild site/autonomy.json + autonomy.html python scripts/build_autonomy.py --check # exit 1 if the committed counters are stale ``` ## 仓库布局 | 路径 | 存储内容 | |------|---------------| | `ingest/` | L1 拉取 —— 注册表驱动的 WorldMonitor 数据抓取 → 带有日期的源笔记 (标准库) | | `guardrail/` | L3 针对单个来源的许可证 / 署名 / 编辑护栏 | | `synthesis/` | L2 策展人逻辑，综合 lint，跨主题关联 | | `scripts/` CLI 工具 —— 摄入、站点 + 图谱 + 索引构建器、查询引擎、活跃状态与密钥扫描 (完整参考: [docs/cli.md](docs/cli.md)) | | `vault/` | 已发布的知识库 —— `00 Rules` (L3) · `01 Sources` (L1) · `02 Briefs` (L2) | | `site/` | 构建好的只读站点 + `graph.json` / `graph.html` 知识图谱 + `autonomy.json` / `autonomy.html` 计数器 | | `sources/registry.json` | 唯一事实来源 —— 每一个 WorldMonitor 子集及其许可证/主题 | | `docs/` | 规范、计划、架构、部署、安全以及各功能文档 | | `.github/workflows/` | CI · 每日 L1 摄入 · 每周 L2 时效性门禁 · Pages 部署 · 密钥与隐私扫描 | | `.github/dependabot.yml` | 每周运行的 `github-actions` 供应链更新器 —— 保持 CI 工具链已打补丁 | ## 文档 关于 `docs/` 下所有内容的完整导图 —— 涵盖概念与设计、引擎、发布/运维、安全以及演示项目验证 —— 位于 **[docs/README.md](docs/README.md)**。 想深入了解请从这里开始；[docs/architecture.md](docs/architecture.md) 是设计决策的 入口，而 [docs/faq.md](docs/faq.md) 解答了首次访问者的疑问（数据是否 真实、时效性如何、是否可以信任、许可证、为什么是私有的）。 ## 贡献与安全 ## 许可证 拆分式许可证： - **代码** (`ingest/`, `guardrail/`, `synthesis/`, `scripts/`, `.github/`): **MIT** —— 见 [`LICENSE`](LICENSE)。 - **知识库内容** (`vault/` 下派生的 L1/L2/L3 笔记): **CC BY 4.0** —— 见 [`LICENSE-CONTENT.md`](LICENSE-CONTENT.md)。 Worldmonitor 的源数据通过其公开的 API 使用（路径 A，非 fork → 不触发 AGPL）；针对各个来源的署名信息包含在 [`CREDITS.md`](CREDITS.md) 中，并由针对单个来源的护栏 (`scripts/check_sources.py`) 强制执行。 ## 引用 azimuth 机器可读的引用元数据位于 [`CITATION.cff`](CITATION.cff) 中 —— GitHub 会据此渲染出一个 **“引用此仓库”**按钮。请优先使用该按钮，而不是手动复制参考资料。

标签：DLL 劫持, Python安全, Ruby, 大语言模型, 安全规则引擎, 知识库, 自动化数据采集, 逆向工具, 防御加固, 静态网站