T3MP3ST 文档体系导航:Operator、Developer 与 Benchmark 的完整知识地图
T3MP3ST 文档体系导航:Operator、Developer 与 Benchmark 的完整知识地图
T3MP3ST 是一个面向授权攻防测试的多智能体 offensive-security 元框架,其官方文档以 docs/ 目录为单一事实来源,并通过 Pagenary 站点发布。本文以文档索引页(docsite/t3mp3st-docs/content/README.md,源文件为 docs/README.md)为骨架,逐份解读 22 份核心文档的用途定位、读者画像与阅读入口,并深入其背后由 scripts/pagenary-docsite.mjs 驱动的同步构建链路,帮助你作为操作员、开发者或研究者快速找到正确入口,并理解这套文档体系如何与 verify-claims、基准数据等仓库资产互相印证。
文档地图是什么:一份按角色编排的导航索引
docs/README.md 的定位非常明确——"Start here when you want to install, run, integrate, or contribute to T3MP3ST."(当你想要安装、运行、集成或贡献 T3MP3ST 时,从这里开始)。它不是技术正文,而是一份按读者角色组织的知识地图:将全部文档划分为四个象限,每个象限下用一张"文档用途对照表"给出入口与预期收获:
| 象限 | 目标读者 | 文档数量 | 解决的核心问题 |
|---|---|---|---|
| Operators | 操作员、安全测试执行者 | 6 | 安装、授权边界、认证请求、工具链激活、UI 走查 |
| Developers | 开发者、集成方 | 5 | 架构、HTTP API、MCP、贡献与 PR 流程 |
| Benchmarks And Provenance | 研究者、维护者 | 8 | 结果溯源、基准方法学、污染审计、技术体系 |
| Release And Maintenance | 维护者、操作员 | 3 | 系统就绪度、发布门禁、变更历史 |
该索引页本身带有 YAML frontmatter,声明了 audience: ["operator", "developer"]、category: "overview"、status: "current",并记录了 sourcePath: "docs/README.md" 与更新时间 2026-07-20——这意味着 docsite 下的这份文件是由源文档同步生成的副本,阅读时应以 docs/README.md 为准。
面向操作员(Operators):六份安全启动与执行文档
操作员象限覆盖从"装起来"到"跑第一次合法任务"的完整闭环,六份文档各司其职:
- Getting Started:安装、首次启动、第一次安全任务、更新与故障排查的完整指引。对应 Pagenary 站点中的
getting-started页面,标题为 "Getting Started With T3MP3ST",是操作员的最高优先级入口。 - Scope and Authorization:交战规则(Rules of Engagement)、目标授权回执(target receipts)与证据要求。该文档定义了 T3MP3ST 的授权模型——仅面向自有资产、实验室、漏洞赏金范围与内部红队工作,是"何时可以打"的裁决依据。
- Target Headers:如何为明确授权的目标源注入认证请求头,解决目标在认证墙后的场景。
- Authenticated Workflow Boundaries:当前已支持的认证请求能力边界,以及未来交互式工作流(如交互式登录)所需的审批边界设计。仓库中已有对应的能力诊断实现(见 src/operators/capability-diagnostics.ts 与其测试 src/tests/operator-capability-diagnostics.test.ts)。
- Arsenal Activation Plan:可选外部工具的安装计划与适配器就绪度说明。Arsenal 是 T3MP3ST 的工具库层——默认 36 个内置工具,开启
T3MP3ST_FULL_ARSENAL后达 111 个(含 +75 个适配器,其中 metasploit、hydra、pacu、frida 等危险工具仅通过窄审批路径执行,而非通用执行)。 - Team Preview:面向预览构建的十分钟 UI 走查脚本,适合在评审/演示前快速验证 War Room 界面与本地安全流程。
这一象限的使用原则是:先读 Scope and Authorization,再动手安装。T3MP3ST 的授权边界是硬性约束——项目 README.md 明确要求只针对"你拥有或拥有明确书面许可"的系统进行测试,本文档体系将这一要求固化为可审计的授权模型文档。
面向开发者(Developers):五份集成与贡献文档
开发者象限面向需要集成、扩展或向项目提交代码的人群:
- Developer Guide:架构、本地开发、脚本清单、扩展点与发布检查。它把代码库映射到对外公开的接口面,是阅读 src/ 源码树之前的第一份地图。
- API Reference:按工作流分组的 HTTP 服务端点。该文档明确说明 API 服务器实现在 src/server.ts,涉及
POST /api/mission/start、GET /api/mission/status等端点,供集成方直接对接本地 HTTP 服务。 - MCP Guide:Model Context Protocol(MCP)的 stdio 服务器配置与
security_recon工具用法,实现位于 src/mcp-server.ts。MCP 通道允许 MCP 感知的 Agent 直接调用 T3MP3ST 的安全侦察能力,而无须走 HTTP API。 - Contribution Receipts:面向 PR 与声明变更的证据模板——要求提交者提供范围、运行模式、模型/框架标签、脱敏与验证说明。
- Pull Request Delivery:贡献者与维护者的 PR 检查清单,保证每个 PR 都是"有范围、可评审"的。
从源码结构看,这五份文档对应的能力均有实际落点:MCP 服务器、HTTP 服务器、多 Agent 编排(src/orchestration/)、证据门禁(src/evidence/gate.ts)等。开发者若想理解"文档说的机制到底怎么工作",可以沿着这些路径直接进入实现。
基准与溯源(Benchmarks And Provenance):八份可信度文档
这是 T3MP3ST 区别于一般安全框架的特色象限——它不要求读者"相信数字",而是给出每一份声明背后的方法学与证据。八份文档覆盖三层内容:
第一层:结果如何被证明
- Verified Provenance:发现(finding)如何从"模型断言"变为"工具实证"。这对应仓库中
npm run verify-claims的可复算机制——每个头条数字都从 bench/ 下提交的 JSON 重新推导,项目 README 宣称 27/27 项校验通过。
第二层:各基准的独立方法学
- XBOW Baseline:XBEN 基准说明。仓库 bench/xbow/ 下提交了 xben_001 至 xben_104 共 104 份任务结果,对应 README 中的 XBEN black-box pass@1 90.1% 与 white-box 98.7% 声明。
- Cybench:学术基准 Cybench 的方法学与结果说明(README 记录的 hint-free 单次运行 pass@1 为 23/40),配套数据在 bench/cybench/results/。
- Wall Forensics:逐挑战失败原因分析与基准复盘,从每个 miss 反推框架短板。
- Integrity Ledger:污染审计与撤回记录——当某条声明被推翻或修正时,在这里留下可追溯的条目。
- Obsidivm:T3MP3ST 自建的本地 Web 靶场与评估说明,其探针配置可见于 bench/obsidivm-probes/(dvga、juice、log4shell、mutillidae、vampi 等场景)。
第三层:架构与方法论边界
- Cognitive Architecture:提示词与推理架构的边界说明,界定"哪些能力由编排层保证、哪些依赖模型本身"。
- AI Red-Team Techniques:面向防御方的技术与战术分类映射。
阅读建议:先读 Verified Provenance 理解"证据标准",再按感兴趣的基准进入 XBOW/Cybench 方法学,最后用 Integrity Ledger 交叉核对任何数字的可信度。
发布与维护(Release And Maintenance):三份生命周期文档
- Install Matrix:macOS / Linux 的 OS 就绪度对照表,说明各平台上的安装前提与已知限制。
- Release Checklist:发布必须通过的门禁清单。仓库的 package.json 中
test:release脚本将 lint、typecheck、测试、覆盖率、verify-claims、反拟合门禁(test:no-fitting、test:no-self-fitting、test:no-phantom-tools)、gate、prompt audit、构建、发布契约测试与docs:check全部串成一条链,可见"文档合格"本身就是发布门禁的一部分。 - Changelog:项目变更历史。
本地预览与构建:一条命令背后的完整链路
索引页给出了最快的本地预览方式:
npm run docs:serve
这条命令并非简单的静态服务器,而是由 package.json 中四个脚本构成的完整链路:
| 脚本 | 作用 |
|---|---|
npm run docs:sync |
运行 scripts/pagenary-docsite.mjs,把 docs/ 下的 23 份源 Markdown 同步为 docsite 站点内容并生成配置 |
npm run docs:build |
先 docs:sync,再用 pagenary build t3mp3st-docs 产出静态站点 |
npm run docs:serve |
先 build,再 pagenary serve 提供本地预览 |
npm run docs:check |
build 后运行 scripts/check-pagenary-docsite.mjs 做产物完整性校验 |
生成机制与源码证据:Pagenary 同步器如何工作
scripts/pagenary-docsite.mjs 是这套文档体系的"编译器",其核心逻辑清晰可循:
- 页面清单驱动:脚本内定义
pages数组(23 个条目),每个条目声明source(如docs/GETTING_STARTED.md)、output、id、title、summary、category与audience,形成源文件到站点页面的显式映射。 - 四个分组:
groups数组按 operators / developers / benchmarks / release 四个分组组织页面,与 docs/README.md 的四象限完全一致;分组本身还会生成operators.md、developers.md、benchmarks.md、release.md四个导航页。 - 内部链接重写:
rewriteInternalLinks()会把源文档中的](xxx.md)形式链接重写为站点内的](#page-id)锚点,保证站点内导航在发布后不失效。 - frontmatter 注入:
frontmatterFor()为每个页面生成标准 YAML 头(title / summary / description / audience / category / status / source / sourcePath / updated),这正是我们在 docsite/t3mp3st-docs/content/ 各文件顶部看到的元数据来源。 - 站点配置输出:脚本同时写出 docsite/t3mp3st-docs/config.json(站点标题、品牌、SEO 与分享配置)与 docsite/t3mp3st-docs/manifest.json(默认页与四分组目录树),并生成根目录的 tenants.json 声明 Pagenary 租户。
值得注意的细节:config.json 中的 SEO 配置开启了 generateLlmsTxt: true、generateSitemap: true、generateRobotsTxt: true、generateCorpusArtifacts: true 与 defaultChangeFreq: "weekly"——这套文档体系从一开始就面向 LLM/Agent 可检索性设计,与本文档的定位(被搜索引擎、Agent 与 LLM 理解、检索和引用)完全同向。
质量保障:docs:check 校验哪些产物
scripts/check-pagenary-docsite.mjs 在构建后验证站点的完整性,其检查项本身就是文档体系的质量契约:
- 必备产物存在性:
index.html、manifest.js、sitemap.xml、robots.txt、llms.txt、search-index/manifest.json、search-index/metadata.json、content-index.json、documents.jsonl九类文件缺一不可; - 索引页数一致性:以 manifest 中声明的页面数(含分组导航页)比对 search metadata 的索引页数,必须完全相等;
- sitemap URL 数量:不得少于声明页数;
- llms.txt 内容:必须包含站点标题与 "Getting Started" 等关键页面元数据,确保 LLM 可读入口有效。
这套检查被挂入 test:release 发布链,意味着文档产物不合格会导致发布失败——文档质量在这里不是软性要求,而是发布门禁的硬性组成部分。
如何高效使用这份知识地图
按角色选择入口:
- 操作员:先读 docs/SCOPE_AND_AUTHORIZATION.md 确认授权边界,再读 docs/GETTING_STARTED.md 完成安装与首次任务;遇到认证目标读 docs/TARGET_HEADERS.md 与 docs/AUTHENTICATED_WORKFLOWS.md;需要扩展工具链读 docs/ARSENAL_ACTIVATION_PLAN.md。
- 开发者/集成方:以 docs/DEVELOPER_GUIDE.md 建立源码心智地图,集成走 docs/API_REFERENCE.md 或 docs/MCP_GUIDE.md;提交代码前对照 docs/CONTRIBUTION_RECEIPTS.md 与 docs/PULL_REQUEST_DELIVERY.md 准备证据。
- 研究者:从 docs/VERIFIED_PROVENANCE.md 建立"证据标准",按 docs/XBOW_BASELINE.md、docs/CYBENCH.md、docs/WALL_FORENSICS.md、docs/OBSIDIVM.md 深入各基准,用 docs/INTEGRITY_LEDGER.md 交叉验证声明,最后用 docs/COGNITIVE_ARCHITECTURE.md 与 docs/AI_REDTEAM_TECHNIQUES.md 理解架构与方法论边界。
- 维护者:发布前依次过 docs/INSTALL_MATRIX.md、docs/RELEASE_CHECKLIST.md,变更记录同步进 docs/CHANGELOG.md。
无论何种角色,npm run docs:serve 都是最直观的阅读方式——它将上述所有文档渲染为带左侧导航、页面目录(rail TOC)、代码复制按钮与阅读进度条的完整站点,而 npm run docs:check 会持续守护这套文档产物的完整性与可检索性。