PythonWoods/zenzic

访问[文档门户][docs-home]获取交互式截图和丰富的示例。 ## 📖 文档地图 — Quartz Promise Zenzic 的文档由托管在同一域名下的**两个独立的 Docusaurus 实例**组成。 每个实例都有自己的侧边栏、搜索功能和目标受众 — 绝不混淆。 ``` zenzic.dev/ ├── docs/ → User Area — install, configure, CI/CD, finding codes ├── developers/ → Dev Area — plugins, adapters, ADRs, tech debt ledger ├── blog/ → Release notes & engineering post-mortems └── community/ → Brand kit, FAQs, governance ``` **Quartz Promise。** 两个实例，一个 Sentinel。这种隔离由 [ADR 011: Cross-Instance Allowlist][docs-adr-011] 强制执行 — 每一个跨边界链接 都是一项记录在案的契约，而非静默忽略。隐性债务会破坏信任； 显式债务才是工程。请参阅 [技术债务分类账][docs-tech-debt] 了解我们推迟了什么及其原因。 **入口点：** | 你是... | 从这里开始 | | :--- | :--- | | 👤 集成 Zenzic 的用户 | `uvx zenzic lab` · [用户指南][docs-home] | | 🔧 贡献者 / 插件开发者 | [开发者门户][docs-developers] · [ADR 存储库][docs-adr-vault] | | 🛡️ 安全审查员 | [工程分类账][docs-eng-ledger] · [SECURITY.md][security] | ## 🧱 工程分类账 Zenzic 受三个不可协商的运维契约所约束 — 每一项 均可由机器强制执行，而非依赖人为约定。 源自 NASA Power of 10 的三大设计公理 — 无一例外地严格执行： - **规则 1 / 规则 4 — 纯粹、确定性的控制流。** 分析引擎拥有零全局 状态。给定相同的输入，Zenzic 必定产生相同的输出。每项发现都映射到 唯一的源文件和行号。没有随机组件；在 `pyproject.toml` 中也没有声明任何推断 依赖。 - **规则 2 — 禁止动态执行。** `subprocess.Popen`、`os.system` 以及所有 Shell 调用被永久禁止出现在 `src/` 目录中。Docusaurus 的 TypeScript 配置作为 纯文本解析。绝不调用 Node.js。Zero Subprocess 不变式由 ruff 强制执行，并在每次推送时接受审计。 这些不是约定 — 它们是由机器强制执行的契约。

**零假设** — 每个适配器均在 `mypy --strict` 下运行。没有 `Any`，没有静默的类型转换。 类型系统就是编译时的契约 — 而非可有可无的建议。 ``` # mypy: strict = true # 零未类型化定义，零忽略错误。 ```

**无子进程** — `subprocess.Popen` 被永久禁止出现在 `src/` 中。Docusaurus `.ts` 配置作为纯文本解析。绝不调用 Node.js。 ``` # ruff: ban = ["subprocess"] # 仅限确定性静态分析。 ```

**确定性合规** — 每个源文件均包含 SPDX 头部。REUSE 3.x 在 CI 中被严格执行。 没有模棱两可的授权 — 在每个 PR 上实现机器可验证。 ``` # REUSE-IgnoreStart / REUSE-IgnoreEnd # SPDX-License-Identifier: Apache-2.0 ``` >

有关 Two-Pass Reference Pipeline 和 VSM 深入解析，请参阅 [架构指南][docs-arch]。 ## 🙋 常见问题 **为什么不使用 `grep`？** Grep 对结构一无所知。Zenzic 理解 Docusaurus 版本控制、 MkDocs i18n 回退机制以及 Ghost Routes — 即那些不作为文件存在但却是有效 URL 的页面。 **它会运行我的构建引擎吗？** 不会。100% 无子进程。仅对纯文本进行静态分析。 **它能处理成千上万的文件吗？** 是的。自适应并行发现；每次链接查找均为 O(1) VSM； 内容可寻址缓存 (`SHA256(content + config + vsm_snapshot)`) 会跳过未更改的文件。 **Shield 与 Blood Sentinel 的区别？** Shield = 内容内部的机密 (退出码 2)。Blood Sentinel = 指向 OS 系统路径的链接 (退出码 3)。两者均不可绕过。 **不需要 `zenzic.toml` 吗？** 正确。Zenzic 会根据现有的配置文件识别引擎并应用安全的默认值。随时 运行 `zenzic init` 以生成一个预填充的配置文件。 **什么是 `zenzic lab`？** 一个涵盖每种引擎和错误类别的 9 幕交互式展示。 在将 Zenzic 集成到任何项目之前，请运行一次。 ## 🛠️ 开发 ``` uv sync --all-groups nox -s tests # pytest + coverage nox -s lint # ruff nox -s typecheck # mypy --strict nox -s preflight # lint + format + typecheck + pytest + reuse just verify # preflight + zenzic check all --strict (self-dogfood) ``` 有关 Zenzic Way 检查表和 PR 约定，请参阅 [贡献指南][contributing]。 ## 🤝 贡献 1. 开启一个 [issue][issues] 以讨论更改内容。 2. 阅读 [贡献指南][contributing] — Zenzic Way 检查表，纯函数，禁止使用 子进程，源码优先。 3. 每个 PR 都必须通过 `nox -s preflight`，并在新文件中包含 REUSE/SPDX 头部。 另请参阅：[行为准则][coc] · [安全策略][security] ## 📎 引用 根目录下提供了一个 [`CITATION.cff`][citation-cff] 文件。在 GitHub 上点击 **"Cite this repository"** 即可获取 APA 或 BibTeX 格式的引用信息。 ## 📄 许可证 Apache-2.0 — 详见 [LICENSE][license]。 ## 📚 Zenzic 记事 Zenzic 诞生于一段探索现代文档生态系统脆弱性的技术旅程中。欢迎在官方博客的 [**工程纪事**](https://zenzic.dev/blog/tags/chronicles)中探索其背后的哲学、安全攻防战，以及 Sentinel 底层的工程故事。 v0.7.1 版本的故事 — AI 驱动的红蓝对抗攻防战、关闭 4 个绕过漏洞，以及 迈向引擎无关一致性的道路 — 记录在 [**攻防之外：Zenzic v0.7.1**](https://zenzic.dev/blog/beyond-the-siege-zenzic-v070-quartz) 中。

标签：Docs-as-Code, Docusaurus, IP 地址批量处理, Linter, Markdown, MkDocs, pptx, Python, Python安全, StruQ, Zensical, 云安全监控, 凭据保护, 图数据库, 威胁情报, 安全网关, 安全防护, 并行处理, 开发者工具, 性能优化, 数据泄露, 文档工程, 文档生成, 断链检测, 无后门, 机密信息泄露防护, 检测绕过, 自动化审查, 逆向工具, 静态分析