# https://github.com/tiliondev/fortress 项目说明书 生成时间：2026-07-07 08:39:57 UTC ## 目录 - [Fortress 概览与核心能力](#page-1) - [C++ 补丁系统与隐身表面](#page-2) - [Python/Node SDK 与 MCP 服务器](#page-3) - [工具、验证、打包与发行流程](#page-4) ## Fortress 概览与核心能力 ### 相关页面 相关主题：[C++ 补丁系统与隐身表面](#page-2), [Python/Node SDK 与 MCP 服务器](#page-3), [工具、验证、打包与发行流程](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/tiliondev/fortress/blob/main/README.md) - [CHROMIUM_VERSION](https://github.com/tiliondev/fortress/blob/main/CHROMIUM_VERSION) - [AGENTS.md](https://github.com/tiliondev/fortress/blob/main/AGENTS.md) - [docs/PERSONA_ENGINE.md](https://github.com/tiliondev/fortress/blob/main/docs/PERSONA_ENGINE.md) - [docs/GAUNTLET_RESULTS.md](https://github.com/tiliondev/fortress/blob/main/docs/GAUNTLET_RESULTS.md) - [sdk/python/tilion_fortress/__init__.py](https://github.com/tiliondev/fortress/blob/main/sdk/python/tilion_fortress/__init__.py) - [sdk/node/index.js](https://github.com/tiliondev/fortress/blob/main/sdk/node/index.js) - [tools/gauntlet.py](https://github.com/tiliondev/fortress/blob/main/tools/gauntlet.py) - [tools/check_patches.py](https://github.com/tiliondev/fortress/blob/main/tools/check_patches.py)
# Fortress 概览与核心能力 ## 项目定位与组成 Fortress 是基于 Chromium 引擎构建的隐身浏览器项目，通过**直接修改 Chromium C++ 源码**而非注入 JavaScript 的方式实现反指纹检测能力。仓库根目录的 `CHROMIUM_VERSION` 文件记录当前 rebase 的上游版本，稳定版对应 Chromium 149.0.7827.232，引擎刷新版对应 151.0.7908.0 [资料来源：[CHROMIUM_VERSION](https://github.com/tiliondev/fortress/blob/main/CHROMIUM_VERSION)]。 项目包含四大组成部分： - **隐身引擎二进制**：以 `tilion-fortress-.tar.gz` 形式发布，运行时暴露 CDP（Chrome DevTools Protocol），便于外部程序化控制。 - **双语言 SDK**：Python（`sdk/python/tilion_fortress/__init__.py`）与 Node.js（`sdk/node/index.js`），负责按平台拉取对应 bundle 并校验 `SHA256SUMS`。 - **隐身补丁集**：以 patch 文件形式驻留于 `patches/` 目录，由 `tools/check_patches.py` 在 CI 中进行完整性把关。 - **QA 与工具链**：以 `tools/gauntlet.py` 为核心，对运行中的 bundle 进行隐身不变量校验。 资料来源：[README.md](https://github.com/tiliondev/fortress/blob/main/README.md)、[AGENTS.md](https://github.com/tiliondev/fortress/blob/main/AGENTS.md) ## 核心架构：Persona 引擎 Fortress 的核心创新在于"每次启动都是一台完全自洽的真实设备"的 **Persona 引擎**。该引擎在 C++ 层随机化一组紧密耦合的浏览器标识字段，包括 UA 字符串、`navigator.platform`、`navigator.keyboard.getLayoutMap()` 返回的键盘布局、屏幕尺寸、字体指纹、WebGL 渲染器等。 关键设计要点： - **跨字段一致性**：键盘布局会随 locale 联动变化，确保任意字段单独取出都符合该"设备"画像，避免被关联性检测穿透 [资料来源：[docs/PERSONA_ENGINE.md](https://github.com/tiliondev/fortress/blob/main/docs/PERSONA_ENGINE.md)]。 - **C++ 级注入**：隐身逻辑在 Chromium 源码中被编译进二进制，不依赖运行时 JS 注入，因此更难被检测脚本发现 [资料来源：[docs/PERSONA_ENGINE.md](https://github.com/tiliondev/fortress/blob/main/docs/PERSONA_ENGINE.md)]。 - **35 补丁隐身套件**：151 与 149 版本共享同一套 35 个 patch，仅 rebase 至不同 Chromium 上游版本。 ```mermaid flowchart LR A[SDK 启动] --> B[下载对应平台 bundle] B --> C{校验 SHA256SUMS} C -->|通过| D[解压并启动 tilion-fortress] D --> E[Persona 引擎生成随机画像] E --> F[暴露 CDP 端口] F --> G[调用方通过 CDP 控制] C -->|失败| H[抛出校验异常] ``` ## SDK 与发布资产 两个 SDK 在功能上对等：解析当前平台、查询 GitHub Release、下载匹配资产、验证 `SHA256SUMS`、解压并暴露可执行路径 [资料来源：[sdk/python/tilion_fortress/__init__.py](https://github.com/tiliondev/fortress/blob/main/sdk/python/tilion_fortress/__init__.py)、[sdk/node/index.js](https://github.com/tiliondev/fortress/blob/main/sdk/node/index.js)]。 社区已识别出 SDK 缺少端到端一致性校验的问题：当前 SDK 信任发布端的 `SHA256SUMS` 但无法验证该清单自身是否完整、是否与实际资产一一对应——这正是 #14 号 issue 提出新增 `verify_release.py` 的背景 [资料来源：[#14](https://github.com/tiliondev/fortress/issues/14)]。Node SDK 同样缺少单元测试，#10 号 issue 提议镜像 Python SDK 的 21 个测试用例 [资料来源：[#10](https://github.com/tiliondev/fortress/issues/10)]。 ## 工具链与质量保障 `tools/check_patches.py` 在 PR 流水线中充当 patch-set 完整性闸门，但其自身尚无测试覆盖，#11 号 issue 提议补齐 pytest 套件以防 lint 回归 [资料来源：[#11](https://github.com/tiliondev/fortress/issues/11)]。 `tools/gauntlet.py` 通过原生 CDP 对运行中的 bundle 实施隐身不变量校验，覆盖 `webdriver`、`platform`、UA 是否为 Windows、mp4 编解码、emoji 字体、WebGL 渲染器等关键字段；社区已建议增加 `--json` 输出与更广覆盖范围，使其可作为 CI 闸门与面板输入 [资料来源：[#12](https://github.com/tiliondev/fortress/issues/12)、[tools/gauntlet.py](https://github.com/tiliondev/fortress/blob/main/tools/gauntlet.py)]。当前稳定版 v149.0.7827.232 与 v151.0.7908.0 均已通过 Gauntlet 校验，相关结果详见 `docs/GAUNTLET_RESULTS.md` [资料来源：[docs/GAUNTLET_RESULTS.md](https://github.com/tiliondev/fortress/blob/main/docs/GAUNTLET_RESULTS.md)]。 ## 已知约束 预编译 Linux 二进制在 Intel Xeon E5-2640（Sandy Bridge-E）等老旧 CPU 上启动即崩溃（SIGTRAP），原因是二进制要求的 CPU 特性在旧硬件上不存在——使用老硬件的用户需要自行从源码构建 [资料来源：[#20](https://github.com/tiliondev/fortress/issues/20)]。此外，`README.md` 末尾的 Star History 图表目前无法渲染，需替换为可用的 star-history 服务源 [资料来源：[#3](https://github.com/tiliondev/fortress/issues/3)]。 --- ## C++ 补丁系统与隐身表面 ### 相关页面 相关主题：[Fortress 概览与核心能力](#page-1), [工具、验证、打包与发行流程](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [patches/README.md](https://github.com/tiliondev/fortress/blob/main/patches/README.md) - [patches/series](https://github.com/tiliondev/fortress/blob/main/patches/series) - [patches/0001-base-BUILD-gn.patch](https://github.com/tiliondev/fortress/blob/main/patches/0001-base-BUILD-gn.patch) - [patches/0011-third_party-blink-renderer-core-execution_context-navigator_base-cc.patch](https://github.com/tiliondev/fortress/blob/main/patches/0011-third_party-blink-renderer-core-execution_context-navigator_base-cc.patch) - [patches/0020-third_party-blink-renderer-modules-canvas-canvas2d-base_rendering_context_2d-cc.patch](https://github.com/tiliondev/fortress/blob/main/patches/0020-third_party-blink-renderer-modules-canvas-canvas2d-base_rendering_context_2d-cc.patch) - [patches/0021-third_party-blink-renderer-modules-keyboard-keyboard_layout-cc.patch](https://github.com/tiliondev/fortress/blob/main/patches/0021-third_party-blink-renderer-modules-keyboard-keyboard_layout-cc.patch)
# C++ 补丁系统与隐身表面 ## 系统概览与设计理念 Fortress 将"隐身"(stealth)能力直接编译进 Chromium 的 C++ 层，而不是在 JavaScript 之上做叠加。这样可以避免被检测脚本通过 JS 堆栈、注入痕迹或 DevTools 协议异常识别为自动化浏览器。整套隐身能力由仓库根目录下 `patches/` 中的 35 个独立补丁实现，覆盖构建系统、Blink 渲染层、第三方库与平台调用等多个维度。 | 维度 | 实现位置 | 隐身作用 | | --- | --- | --- | | 构建配置 | `patches/0001-base-BUILD-gn.patch` | 注入隐身相关的 GN 编译开关与源文件清单 | | Navigator 元数据 | `patches/0011-…navigator_base-cc.patch` | 重写 `navigator` 对象的 `webdriver`、`platform`、`userAgent` 等读取路径 | | Canvas 指纹 | `patches/0020-…base_rendering_context_2d-cc.patch` | 调整 2D 画布底层渲染常量，破坏指纹哈希 | | 键盘布局 | `patches/0021-…keyboard_layout-cc.patch` | 提供按 locale 变化的 `navigator.keyboard.getLayoutMap()` 结果 | 资料来源：[patches/README.md:1-40](), [patches/0001-base-BUILD-gn.patch:1-40]() ## 补丁组织与 series 序列 `patches/series` 是补丁的应用顺序清单，每行一个补丁文件名，按 `git am` 可消费的递增编号排列。命名规范为： ``` NNNN-<子系统>-<路径片段>.patch ``` 其中 `NNNN` 为四位序列号，决定了补丁应用到 Chromium 源码树时的先后顺序。BUILD 层补丁（`0001`）必须最先施加，因为后续补丁可能引用由它新增的源文件或宏。`patches/README.md` 记录了补丁索引、目录约定、重新打补丁与重基（rebase）的流程，并指出 `tools/check_patches.py` 是 PR 合并前的强制门禁。 资料来源：[patches/series:1-20](), [patches/README.md:5-30]() ## 隐身表面实现 ### Navigator 与执行上下文 `0011` 补丁改写了 Blink 的 `NavigatorBase`，使其读取用户代理、平台、硬件并发数等字段时不再返回默认的 Chromium 字面量，而是从启动期注入的"persona"(中文：人格画像) 中取值。该补丁的关键 hunk 位于 `navigator_base.cc` 中 `userAgent()`、`platform()`、`hardwareConcurrency()` 等 getter 的实现段落，并在相邻位置加入对 persona 表的查询调用，使得 JS 端通过 `navigator.userAgent` 读取到的字符串与启动时声明的 Windows/macOS/Linux 设备画像一致。 资料来源：[patches/0011-third_party-blink-renderer-core-execution_context-navigator_base-cc.patch:30-120]() ### Canvas 2D 渲染指纹 `0020` 补丁作用于 `BaseRenderingContext2D`，修改文本抗锯齿、子像素定位与图像合成路径中的若干浮点常量与舍入分支。由于不同 GPU 驱动、字体引擎在画布数据 URL 上会产生不同哈希，这些细微偏差会让真实设备与 Fortress 渲染同一段文本时产生肉眼不可见但指纹哈希可区分的差异。补丁通过在固定点插入 `kStealthNoiseXxx` 常量来统一这些偏差，从而让指纹采集器得到的哈希落入与真实设备一致的分布区间。 资料来源：[patches/0020-third_party-blink-renderer-modules-canvas-canvas2d-base_rendering_context_2d-cc.patch:25-90]() ### 键盘布局与区域 `0021` 补丁位于 `keyboard_layout.cc`，重写了 `KeyboardLayout::GetLayoutMap()` 的查询分支，使其根据 persona 声明的 locale 返回对应的物理键码到字符串映射。社区上下文显示，该特性是 v151.0.7908.0 "Engine Refresh" 的核心卖点之一，验证脚本 `tools/gauntlet.py` 会通过 CDP 读取 `navigator.keyboard.getLayoutMap()` 并与 persona 声明的 locale 比对。 资料来源：[patches/0021-third_party-blink-renderer-modules-keyboard-keyboard_layout-cc.patch:20-80]() ## 补丁治理与 CI 校验 ```mermaid flowchart LR A[开发者提交补丁] --> B[PR 触发 CI] B --> C{check_patches.py} C -- 格式/序号/路径合规 --> D[构建二进制] C -- 不合规 --> E[阻断合并] D --> F[gauntlet.py CDP 验证] F -- 隐身字段全部一致 --> G[合并入主分支] F -- 任意字段不匹配 --> H[标记为回归] ``` `tools/check_patches.py` 会在每次 PR 时校验补丁的 diff 是否落在 `patches/series` 列出的范围内、序号是否单调、文件路径是否与 Chromium 实际目录对齐，避免有补丁把隐身代码改到无关文件中。社区 Issue #11 进一步建议为该工具补充 pytest 套件以防回归。校验通过后二进制由 SDK 下载并经 `SHA256SUMS` 验证（参见 Issue #14），最终通过 `tools/gauntlet.py` 在真实 CDP 会话中核对 `webdriver`、`platform`、UA、mp4 codec、emoji 字体、WebGL renderer 等隐身字段。 资料来源：[patches/README.md:30-60](), [patches/series:1-20]() --- ## Python/Node SDK 与 MCP 服务器 ### 相关页面 相关主题：[Fortress 概览与核心能力](#page-1), [工具、验证、打包与发行流程](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [sdk/python/tilion_fortress/__init__.py](https://github.com/tiliondev/fortress/blob/main/sdk/python/tilion_fortress/__init__.py) - [sdk/python/tilion_fortress/__main__.py](https://github.com/tiliondev/fortress/blob/main/sdk/python/tilion_fortress/__main__.py) - [sdk/python/pyproject.toml](https://github.com/tiliondev/fortress/blob/main/sdk/python/pyproject.toml) - [sdk/python/README.md](https://github.com/tiliondev/fortress/blob/main/sdk/python/README.md) - [sdk/node/index.js](https://github.com/tiliondev/fortress/blob/main/sdk/node/index.js) - [sdk/node/cli.js](https://github.com/tiliondev/fortress/blob/main/sdk/node/cli.js)
# Python/Node SDK 与 MCP 服务器 ## 1. 定位与设计目标 Fortress 是一个基于 Chromium 149/151 的隐身浏览器二进制发行项目,而 Python/Node SDK 是它面向自动化与集成场景的官方客户端层。两个 SDK 共享同一组契约:从 GitHub Release 拉取对应平台的压缩包(`tilion-fortress-{linux|macos|windows}-x64.tar.gz` 等),用 `SHA256SUMS` 校验其完整性,解压后在本地启动一个暴露 CDP(Chrome DevTools Protocol)端点的进程,并把它交给上层调用方使用。社区上下文显示,这种"下载-校验-启动"链路目前已经被识别为发布关键路径 —— 社区曾在 issue #14 中指出"两个 SDK 都从 GitHub Release 下载平台包并对照 `SHA256SUMS` 校验"。 资料来源:[sdk/python/tilion_fortress/__init__.py:1-1](https://github.com/tiliondev/fortress/blob/main/sdk/python/tilion_fortress/__init__.py) 资料来源:[sdk/node/index.js:1-1](https://github.com/tiliondev/fortress/blob/main/sdk/node/index.js) 两个 SDK 都是**纯包装层**,并不重新实现 Chromium 启动逻辑 —— 它们的唯一职责是:把"哪个 bundle 适用于当前平台 / 当前架构"以及"该 bundle 是否可信"这两个决定做到可移植、可测试、可在 CI 中复现。 ## 2. Python SDK ### 2.1 包结构与可执行入口 `sdk/python/` 目录遵循标准的可打包布局:`pyproject.toml` 描述项目元数据,`tilion_fortress/` 子包内放置 `__init__.py`(对外 API 主体)与 `__main__.py`(`python -m tilion_fortress` 入口)。这意味着使用者既可以 `import tilion_fortress` 在脚本/Agent 中调用,也可以直接在终端以模块方式运行 CLI 子命令。 资料来源:[sdk/python/pyproject.toml:1-1](https://github.com/tiliondev/fortress/blob/main/sdk/python/pyproject.toml) 资料来源:[sdk/python/tilion_fortress/__main__.py:1-1](https://github.com/tiliondev/fortress/blob/main/sdk/python/tilion_fortress/__main__.py) ### 2.2 测试覆盖现状 社区上下文显示 Python SDK 已有 `sdk/python/tests/test_sdk.py` 共 21 个测试,并在 CI 中由 `sdk-python` 任务门控执行。这是相对成熟的覆盖状态;与之对应,Node SDK 尚未获得同等水平的单元测试 —— 社区在 issue #10 中明确提出"为 Node SDK 添加单元测试,镜像 Python 测试套件",并强调其内部的平台选择与 SHA256 校验逻辑属于"发布关键纯逻辑"。 ### 2.3 集成形态 Python SDK 的目标消费方是任何用 Python 编排自动化的用户(例如基于 MCP 的 Agent、Playwright/Pyppeteer 的替代驱动、数据采集管线等)。README 中说明了从环境变量配置 token、到 `import` 后返回一个可与浏览器交互的对象这一典型流程。 资料来源:[sdk/python/README.md:1-1](https://github.com/tiliondev/fortress/blob/main/sdk/python/README.md) ## 3. Node SDK ### 3.1 模块边界 `sdk/node/index.js` 是 SDK 主入口,负责平台探测(OS、arch)、Release tag 解析、bundle URL 拼接、SHA256 校验、缓存目录管理;`sdk/node/cli.js` 则在它之上提供命令行封装。两者解耦使得 SDK 既能被 `require`/`import` 嵌入到任意 Node 工具链(例如 Puppeteer、Playwright、自动化测试),也能以 `npx` 方式独立运行。 资料来源:[sdk/node/index.js:1-1](https://github.com/tiliondev/fortress/blob/main/sdk/node/index.js) 资料来源:[sdk/node/cli.js:1-1](https://github.com/tiliondev/fortress/blob/main/sdk/node/cli.js) ### 3.2 与 Python SDK 的行为对等 两个 SDK 必须对同一组输入产生相同结果:同一 `tag`、同一 OS/arch 必须解析到同一份 `SHA256SUMS` 中同一行。这意味着 bundle 命名、平台三元组映射、校验算法都属于"两 SDK 必须保持对等"的契约部分 —— 任何只在一边修改都会造成发布资产漂移,这也是 issue #14 提议 `verify_release.py` 的动机之一(用发布后的元数据反查两个 SDK 的解析是否一致)。 ## 4. MCP 服务器(消费方视角) Fortress 仓库本体并未包含一个独立的"MCP server"子模块,但在 README 与发布说明中,Python/Node SDK 被设计为 **任何 LLM 工具运行时**(包括基于 Model Context Protocol 的 Agent)都能调用的浏览器后端。常见消费模式是:Agent 进程通过 SDK 拉起 Fortress → 拿到 CDP 端点 → 用 `playwright`/`puppeteer-core` 这类已有桥接库与浏览器对话。下表概括 SDK 各自的关键职责与已知测试状态: | 维度 | Python SDK | Node SDK | |------|-----------|----------| | 包/模块入口 | `tilion_fortress` 包 + `__main__` | `sdk/node/index.js` + `cli.js` | | 平台探测 | 内部逻辑 | 内部逻辑 | | SHA256 校验 | `SHA256SUMS` 对比 | `SHA256SUMS` 对比 | | 单元测试 | 21 个(`sdk-python` CI) | 暂无(issue #10 提议补齐) | | 校验工具 | `verify_release.py` 提议中(issue #14) | 同上 | > 社区关切:issue #14 指出"两个 SDK 下载平台包并对照 `SHA256SUMS` 校验,但目前没有自动检查发布的 release 在内部是否自洽 —— 缺失资产或校验和不匹配将不会被 CI 捕获"。该 issue 直接以两个 SDK 源码路径作为引用对象。 ## 5. 数据流小结 ```mermaid flowchart LR A[SDK 调用方] --> B[SDK 入口
Python __init__ / Node index.js] B --> C{平台 & tag 解析} C --> D[GitHub Release
下载 bundle + SHA256SUMS] D --> E[本地 SHA256 校验] E --> F[解压 & 启动
tilion-fortress 二进制] F --> G[CDP 端点
ws://127.0.0.1:...] G --> H[上层驱动
Playwright / Puppeteer / Agent] ``` 整条链路中,**SHA256 校验是唯一可以同时在 CI 与客户端两侧执行的可验证关卡**。这也是社区推动 issue #14(发布自洽性检查)与 issue #10(Node SDK 测试)共同指向的核心目标:把 SDK 的"决定性逻辑"从"信任 GitHub"升级为"信任可独立验证的清单"。 资料来源:[sdk/python/tilion_fortress/__init__.py:1-1](https://github.com/tiliondev/fortress/blob/main/sdk/python/tilion_fortress/__init__.py) 资料来源:[sdk/node/index.js:1-1](https://github.com/tiliondev/fortress/blob/main/sdk/node/index.js) --- ## 工具、验证、打包与发行流程 ### 相关页面 相关主题：[Fortress 概览与核心能力](#page-1), [C++ 补丁系统与隐身表面](#page-2), [Python/Node SDK 与 MCP 服务器](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [tools/gauntlet.py](https://github.com/tiliondev/fortress/blob/main/tools/gauntlet.py) - [tools/verify_release.py](https://github.com/tiliondev/fortress/blob/main/tools/verify_release.py) - [tools/check_patches.py](https://github.com/tiliondev/fortress/blob/main/tools/check_patches.py) - [docs/gauntlet-sample.json](https://github.com/tiliondev/fortress/blob/main/docs/gauntlet-sample.json) - [docs/GAUNTLET_RESULTS.md](https://github.com/tiliondev/fortress/blob/main/docs/GAUNTLET_RESULTS.md) - [docs/BUILD_NATIVE.md](https://github.com/tiliondev/fortress/blob/main/docs/BUILD_NATIVE.md) - [sdk/python/tilion_fortress/__init__.py](https://github.com/tiliondev/fortress/blob/main/sdk/python/tilion_fortress/__init__.py) - [sdk/node/index.js](https://github.com/tiliondev/fortress/blob/main/sdk/node/index.js) - [sdk/python/tests/test_sdk.py](https://github.com/tiliondev/fortress/blob/main/sdk/python/tests/test_sdk.py)
# 工具、验证、打包与发行流程 ## 概述 Fortress 的工具链围绕"隐身 Chromium 发行版"的端到端可信度而构建：`tools/` 目录下的脚本与 `docs/` 中的构建/校验文档共同承担三件事 —— 拦截不合格的补丁（PR 闸门）、运行时回放隐身不变量（CDP 探测）、以及验证 GitHub Release 的资产完整性（SHA256SUMS 核对）。SDK 层则把这些离线工具产出的资产再次下发到终端用户，并在用户侧复算校验和。整个体系形成一个"补丁 → 构建 → 运行态探测 → 发布资产 → SDK 下载"的闭环。 ## 核心工具集 ### `tools/check_patches.py` —— 补丁闸门 该脚本是每个 PR 必经的静态检查，确保 `patches/` 目录中提交的隐身补丁结构完整、可被 Chromium 构建系统正确消费。社区关注的一个明确空白点是它本身没有单元测试 —— 一旦该脚本回归，可能会"误判通过"，让不合格的 stealth 补丁流入主线，因此社区已提议新增 `tools/tests/test_check_patches.py`（参见 issue #11）。`资料来源：[tools/check_patches.py:1-1]()` ### `tools/gauntlet.py` —— 运行时隐身探测 `gauntlet.py` 通过原始 CDP（Chrome DevTools Protocol）连接到一个已运行的 Fortress 进程，回放一组"浏览器指纹是否还像真人"的不变量检查。当前覆盖的不变量集包括：`navigator.webdriver` 应为 `undefined`、`navigator.platform` 与 UA 声明的 Windows 一致、MP4 编解码可用、emoji 字体就绪、GPU/WebGL 渲染器字符串合理。社区路线图（issue #12）建议为其增加 `--json` 输出与更广泛的不变量覆盖，使其可作为 CI 闸门和仪表盘数据源。`资料来源：[tools/gauntlet.py:1-1]()` ### `tools/verify_release.py` —— 发布资产一致性 两个 SDK（Python 与 Node）都会从 GitHub Release 下载对应平台的压缩包，并在本地用 `SHA256SUMS` 文件核验。但截至当前，仓库缺少一个自动化的"自检"工具来保证 *发布本身* 的内部一致性：是否存在缺失资产、校验和文件是否与资产对应。issue #14 提出新增 `verify_release.py` 完成这一步，构成发布侧的反向闸门。`资料来源：[tools/verify_release.py:1-1]()` ## SDK 侧的校验链路 Python 与 Node SDK 共享同一条"按平台挑包 → 下载 → SHA256 校验"的下载路径，这是终端用户在 `pip install` 或 `npm install` 后实际触发的代码路径，因此它的正确性直接影响"发行版是否真的像 release 页宣称的那样被分发出去"。 - `sdk/python/tilion_fortress/__init__.py`：负责选择当前平台对应的 tarball，并对 `SHA256SUMS` 进行校验。 - `sdk/node/index.js`：用同构的逻辑为 Node 用户服务。 - `sdk/python/tests/test_sdk.py`：Python SDK 的 21 个单元测试由 `sdk-python` CI 任务门禁，但 Node SDK 尚无对应测试（issue #10）。 `资料来源：[sdk/python/tilion_fortress/__init__.py:1-1]()` ## 发行与打包流程 下表把发布路径上每一道闸门与其负责的失败模式对应起来，便于新贡献者快速定位"问题该归哪一类工具"。 | 阶段 | 工具 / 文档 | 拦截的失败模式 | | --- | --- | --- | | 补丁审阅 | `tools/check_patches.py` | 补丁集结构损坏、无法被 Chromium 消费 | | 原生构建 | `docs/BUILD_NATIVE.md` | 文档化的本地构建步骤，避免误用错误的 toolchain | | 运行时隐身 | `tools/gauntlet.py` | 隐身不变量回归（`webdriver` 漏出、UA/平台不一致等） | | 资产发布 | `tools/verify_release.py`（计划中） | Release 中缺失资产、`SHA256SUMS` 与资产不一致 | | 用户侧下载 | `sdk/python/tilion_fortress/__init__.py`、`sdk/node/index.js` | 篡改或损坏的压缩包被静默安装 | | 文档完整性 | 计划中的 Markdown 链接/badges 检查器（issue #13） | README 与 `docs/` 中死链、失效 badges | `资料来源：[docs/BUILD_NATIVE.md:1-1]()` ## 已知风险与社区关注点 - **旧硬件兼容性**：issue #20 报告预编译 `tilion-fortress` Linux 二进制在 Intel Xeon E5-2640（Sandy Bridge-E）上启动即触发 `SIGTRAP`，提示发布流水线可能默认启用了目标机器不具备的 CPU 特性集（如某条 AVX/BMI 指令或一段 `ud2` 占位）。这条线索直接影响"打包"环节的编译选项基线。 - **工具链覆盖率不均**：`check_patches.py` 与 Node SDK 缺少测试（issues #11、#10）；`gauntlet.py` 缺少结构化输出（#12）；发布资产缺少自检（#14）；README 与文档缺少链接健康度门禁（#13）。这些都是 CI "门"上的缺口，而非"门"本身缺失。 - **示例与结果文档**：`docs/gauntlet-sample.json` 提供了一个可复用的 JSON 输出样例，可与未来 `--json` 行为对照；`docs/GAUNTLET_RESULTS.md` 记录了历史隐身巡检结果。`资料来源：[docs/gauntlet-sample.json:1-1]()` 整体而言，Fortress 的工具与发行体系是一组围绕"隐身可信度"的多层闸门：补丁侧防回归、运行态防指纹泄漏、发布侧防资产被篡改、SDK 侧防下载链路被劫持。任何一层缺失都意味着隐身保证在该层之上失效，这正是社区当前讨论的焦点所在。 --- --- ## Doramagic 踩坑日志 项目：tiliondev/fortress 摘要：发现 12 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：bug: SIGTRAP on startup on Intel Xeon E5-2640 (Sandy Bridge-E); prebuilt Linux binary appears to require CPU features n…。 ## 1. 安装坑 · 来源证据：bug: SIGTRAP on startup on Intel Xeon E5-2640 (Sandy Bridge-E); prebuilt Linux binary appears to require CPU features n… - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: SIGTRAP on startup on Intel Xeon E5-2640 (Sandy Bridge-E); prebuilt Linux binary appears to require CPU features not present on older hardware - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/tiliondev/fortress/issues/20 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 2. 安装坑 · 来源证据：ci: add a markdown link + badge checker for README and docs/ - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ci: add a markdown link + badge checker for README and docs/ - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/tiliondev/fortress/issues/13 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 3. 安装坑 · 来源证据：feat(tools): add --json output and expand invariant coverage in gauntlet.py - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(tools): add --json output and expand invariant coverage in gauntlet.py - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/tiliondev/fortress/issues/12 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。 ## 4. 安装坑 · 来源证据：feat(tools): add verify_release.py to validate release assets + SHA256SUMS - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(tools): add verify_release.py to validate release assets + SHA256SUMS - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/tiliondev/fortress/issues/14 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 5. 安装坑 · 来源证据：test(sdk/node): add unit tests for the Node SDK (mirror the Python suite) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：test(sdk/node): add unit tests for the Node SDK (mirror the Python suite) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/tiliondev/fortress/issues/10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 6. 能力坑 · 来源证据：README: Star History chart at the end isn't showing - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：README: Star History chart at the end isn't showing - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/tiliondev/fortress/issues/3 | 来源类型 github_issue 暴露的待验证使用条件。 ## 7. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/tiliondev/fortress | README/documentation is current enough for a first validation pass. ## 8. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/tiliondev/fortress | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/tiliondev/fortress | no_demo; severity=medium ## 10. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/tiliondev/fortress | no_demo; severity=medium ## 11. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/tiliondev/fortress | issue_or_pr_quality=unknown ## 12. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/tiliondev/fortress | release_recency=unknown