项目定位与组成

Fortress 是基于 Chromium 引擎构建的隐身浏览器项目，通过直接修改 Chromium C++ 源码而非注入 JavaScript 的方式实现反指纹检测能力。仓库根目录的 CHROMIUM_VERSION 文件记录当前 rebase 的上游版本，稳定版对应 Chromium 149.0.7827.232，引擎刷新版对应 151.0.7908.0 资料来源：[CHROMIUM_VERSION]。

项目包含四大组成部分：

• 隐身引擎二进制：以 tilion-fortress-<platform>.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、AGENTS.md

核心架构：Persona 引擎

Fortress 的核心创新在于"每次启动都是一台完全自洽的真实设备"的 Persona 引擎。该引擎在 C++ 层随机化一组紧密耦合的浏览器标识字段，包括 UA 字符串、navigator.platform、navigator.keyboard.getLayoutMap() 返回的键盘布局、屏幕尺寸、字体指纹、WebGL 渲染器等。

关键设计要点：

• 跨字段一致性：键盘布局会随 locale 联动变化，确保任意字段单独取出都符合该"设备"画像，避免被关联性检测穿透 资料来源：[docs/PERSONA_ENGINE.md]。
• C++ 级注入：隐身逻辑在 Chromium 源码中被编译进二进制，不依赖运行时 JS 注入，因此更难被检测脚本发现 资料来源：[docs/PERSONA_ENGINE.md]。
• 35 补丁隐身套件：151 与 149 版本共享同一套 35 个 patch，仅 rebase 至不同 Chromium 上游版本。

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、sdk/node/index.js]。

社区已识别出 SDK 缺少端到端一致性校验的问题：当前 SDK 信任发布端的 SHA256SUMS 但无法验证该清单自身是否完整、是否与实际资产一一对应——这正是 #14 号 issue 提出新增 verify_release.py 的背景 资料来源：[#14]。Node SDK 同样缺少单元测试，#10 号 issue 提议镜像 Python SDK 的 21 个测试用例 资料来源：[#10]。

工具链与质量保障

tools/check_patches.py 在 PR 流水线中充当 patch-set 完整性闸门，但其自身尚无测试覆盖，#11 号 issue 提议补齐 pytest 套件以防 lint 回归 资料来源：[#11]。

tools/gauntlet.py 通过原生 CDP 对运行中的 bundle 实施隐身不变量校验，覆盖 webdriver、platform、UA 是否为 Windows、mp4 编解码、emoji 字体、WebGL 渲染器等关键字段；社区已建议增加 --json 输出与更广覆盖范围，使其可作为 CI 闸门与面板输入 资料来源：[#12、tools/gauntlet.py]。当前稳定版 v149.0.7827.232 与 v151.0.7908.0 均已通过 Gauntlet 校验，相关结果详见 docs/GAUNTLET_RESULTS.md 资料来源：[docs/GAUNTLET_RESULTS.md]。

已知约束

预编译 Linux 二进制在 Intel Xeon E5-2640（Sandy Bridge-E）等老旧 CPU 上启动即崩溃（SIGTRAP），原因是二进制要求的 CPU 特性在旧硬件上不存在——使用老硬件的用户需要自行从源码构建 资料来源：[#20]。此外，README.md 末尾的 Star History 图表目前无法渲染，需替换为可用的 star-history 服务源 资料来源：[#3]。

系统概览与设计理念

Fortress 将"隐身"(stealth)能力直接编译进 Chromium 的 C++ 层，而不是在 JavaScript 之上做叠加。这样可以避免被检测脚本通过 JS 堆栈、注入痕迹或 DevTools 协议异常识别为自动化浏览器。整套隐身能力由仓库根目录下 patches/ 中的 35 个独立补丁实现，覆盖构建系统、Blink 渲染层、第三方库与平台调用等多个维度。

资料来源：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 校验

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

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 资料来源:sdk/node/index.js:1-1

两个 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 资料来源:sdk/python/tilion_fortress/__main__.py:1-1

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

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 资料来源:sdk/node/cli.js:1-1

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 各自的关键职责与已知测试状态:

社区关切:issue #14 指出"两个 SDK 下载平台包并对照 SHA256SUMS 校验,但目前没有自动检查发布的 release 在内部是否自洽 —— 缺失资产或校验和不匹配将不会被 CI 捕获"。该 issue 直接以两个 SDK 源码路径作为引用对象。

5. 数据流小结

flowchart LR
  A[SDK 调用方] --> B[SDK 入口<br/>Python __init__ / Node index.js]
  B --> C{平台 & tag 解析}
  C --> D[GitHub Release<br/>下载 bundle + SHA256SUMS]
  D --> E[本地 SHA256 校验]
  E --> F[解压 & 启动<br/>tilion-fortress 二进制]
  F --> G[CDP 端点<br/>ws://127.0.0.1:...]
  G --> H[上层驱动<br/>Playwright / Puppeteer / Agent]

整条链路中,SHA256 校验是唯一可以同时在 CI 与客户端两侧执行的可验证关卡。这也是社区推动 issue #14(发布自洽性检查)与 issue #10(Node SDK 测试)共同指向的核心目标:把 SDK 的"决定性逻辑"从"信任 GitHub"升级为"信任可独立验证的清单"。

资料来源:sdk/python/tilion_fortress/__init__.py:1-1 资料来源:sdk/node/index.js:1-1

概述

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

发行与打包流程

下表把发布路径上每一道闸门与其负责的失败模式对应起来，便于新贡献者快速定位"问题该归哪一类工具"。

资料来源：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 侧防下载链路被劫持。任何一层缺失都意味着隐身保证在该层之上失效，这正是社区当前讨论的焦点所在。

Pitfall Log / 踩坑日志

项目：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