项目定位与核心价值

Headroom 是面向 AI 编码代理（coding agent） 与大模型调用链路的"上下文压缩层"。项目自述强调 "60–95% 更少 token · library · proxy · MCP · 6 algorithms · local-first · reversible"，目标是在不改变上层应用代码的前提下，把进入 LLM 上下文的载荷显著压缩，从而降低费用、扩大有效上下文窗口，并保持可逆回查能力。

README 中将 Headroom 描述为一个可以"透明接入"的中间层：用户既可以把任意 agent（如 Claude Code、OpenCode、Codex、Copilot CLI）包在 headroom wrap 之下，也可以让 Headroom 作为反向代理独立部署，还可以直接 from headroom import compress 作为 Python 库内联使用。社区中关于 OpenCode 包装、OpenCode 插件、Copilot CLI 订阅模式（无 BYOK）等请求（Issue #74、#76、#488）都围绕"不改动 agent 即可享受压缩"这一核心价值。

资料来源：README.md

系统架构与数据流

Headroom 的请求路径由 ContentRouter 统一调度，匹配到下游多个压缩器之一，再由 CacheAligner 稳定前缀以提高 LLM 端的 KV cache 命中率。原始载荷如果被高比例压缩，会以可逆形式写入本地 CompressionStore，并以占位符（marker）+ headroom_retrieve 工具的形式暴露给 LLM——这就是 README 中提到的 CCR（Compressed Context Records） 机制。LangChain 演示结果显示：在 5 类工具输出上，token 总量从 75,347 压缩到 19,401，平均节省 74%，同时 100% 的 ERROR 条目被保留。

flowchart LR
    A[AI Agent<br/>Claude Code / OpenCode / Codex / Copilot] --> B[Headroom Proxy<br/>headroom wrap / headroom proxy]
    B --> C[ContentRouter]
    C --> D[SmartCrusher / CodeCompressor / Kompress-base]
    D --> E[CacheAligner<br/>稳定前缀]
    E --> F{压缩比是否超过阈值?}
    F -- 是 --> G[CCR 本地存储<br/>CompressionStore]
    F -- 否 --> H[直接发送]
    G --> I[LLM Provider<br/>Anthropic / OpenAI / Bedrock]
    H --> I
    I -. 需要原文时调用 .-> J[headroom_retrieve MCP 工具]
    J --> G

资料来源：README.md、examples/langchain_demo/README.md

三种使用模式

README 给出 "60 秒上手" 的三选一路径：

headroom/cli/wrap.py 实现了 wrap 子命令，针对每个目标 agent（claude、codex、copilot 等）维护专门的 TOML/JSON 注入与回滚逻辑。Codex 路径在写入 ~/.codex/config.toml 前会先做 .headroom-backup 快照，以便 headroom unwrap 字节级还原。headroom/cli/init.py 进一步承担了"init hook ensure"类的环境初始化（CLI 上下文工具选择、MCP 注册、provider 注入）。社区 Issue #527 反馈当前安装步骤对新手不友好（是否需要 Docker、4 条命令是否必需），这也是 wrap/init 设计持续精简的背景。

scripts/repro_codex_replay.py 等工具脚本还提供多 agent 冷启动风暴复现能力，用于回归 /livez 延迟和上游并发参数。

资料来源：README.md、headroom/cli/wrap.py、headroom/cli/init.py、scripts/README.md

多语言生态与扩展点

Headroom 采用 Rust 核心 + Python/TypeScript 双 SDK 的布局。crates/headroom-py/src/lib.rs 通过 PyO3 把 Rust 实现的 KeywordRegistry、SearchCompressor、LogCompressionResult 等暴露给 Python，使得性能敏感的压缩逻辑可以在不重写 Python 路径的前提下享受 Rust 加速。

TypeScript SDK（sdk/typescript）在 src/utils/format.ts 中以"结构特征"识别 4 种消息格式（OpenAI、Anthropic、Vercel AI SDK、Gemini），并统一转换为 OpenAI 格式作为代理侧 lingua franca；src/errors.ts 镜像了 Python 端的异常层级（HeadroomError、HeadroomCompressError、ConfigurationError 等），方便上层统一捕获。examples 目录覆盖了 Vercel AI SDK、tool-calling agent、流式响应、跨 provider 等典型用法。

发布侧，headroom/cli/toin_publish.py 把运行时学到的 (auth_mode, model_family, structure_hash) 推荐策略离线导出为 recommendations.toml，由 Rust 代理在启动时一次性加载（$HEADROOM_RECOMMENDATIONS_PATH）。这一设计明确把"在线学习"和"启动时配置"解耦，避免每次请求的运行时突变。

资料来源：crates/headroom-py/src/lib.rs、sdk/typescript/src/errors.ts、sdk/typescript/src/utils/format.ts、sdk/typescript/examples/README.md、headroom/cli/toin_publish.py

参见

• 架构总览：Architecture
• 可逆压缩（CCR）：CCR reversible compression
• Kompress-base 模型卡：HuggingFace
• 项目主页：GitHub: chopratejas/headroom

概述

Src 模块在仓库中指代两类源码根：一是 npm 包 headroom-ai 的 TypeScript 源码目录 sdk/typescript/src/，二是 Python 端通过 PyO3 暴露的 Rust 核心绑定 crates/headroom-py/src/lib.rs。前者面向 Node.js / 浏览器侧的多 Provider 适配与 HTTP 客户端，后者把 Rust 实现的高性能算法（KeywordRegistry、SearchCompressor、RustLogConfig 等）注入到 Python 运行时中。两者在 CLI 与代理服务器层交汇，构成 Headroom "60–95% 上下文压缩" 的实现基础。 资料来源：sdk/typescript/package.json:2-3、crates/headroom-py/src/lib.rs:1-40。

flowchart LR
    A[TS 应用] --> B[headroom-ai SDK<br/>sdk/typescript/src]
    B -->|HTTP/JSON| C[Headroom Proxy<br/>headroom/cli]
    C --> D[Rust Core<br/>crates/headroom-py/src/lib.rs]
    D -->|PyO3 绑定| C
    C --> E[LLM Provider<br/>Anthropic · OpenAI · Bedrock]
    B -.压缩钩子.-> F[hooks.ts]
    B -.格式转换.-> G[utils/format.ts]

核心源码组成

TypeScript SDK 入口与多适配器导出

package.json 使用条件导出同时支持 ESM 与 CJS，主入口为 ./dist/index.cjs，模块入口为 ./dist/index.js，并对外暴露四条子路径：./vercel-ai、./openai、./anthropic 与默认根入口。版本号 0.23.0 与 PyPI 同步发布。 资料来源：sdk/typescript/package.json:2-37。

错误体系（errors.ts）

HeadroomError 作为基类，附带可选 details 字典；其下派生出 HeadroomConnectionError、HeadroomAuthError、HeadroomCompressError（额外携带 statusCode 与 errorType）、ConfigurationError、ProviderError、StorageError，与 Python 端 headroom.exceptions 形成镜像。这种层次化错误命名使得上层调用方可以按类型分支处理，而不必依赖字符串匹配。 资料来源：sdk/typescript/src/errors.ts:4-55。

文件系统契约（paths.ts）

paths.ts 显式声明 SDK 是 HTTP-only 客户端，不直接落盘，但仍以 TypeScript 常量镜像 Python 的 headroom/paths 模块，包括 HEADROOM_CONFIG_DIR_ENV、HEADROOM_WORKSPACE_DIR_ENV、HEADROOM_SAVINGS_PATH_ENV、HEADROOM_TOIN_PATH_ENV、HEADROOM_SUBSCRIPTION_STATE_PATH_ENV。isNode() 在浏览器环境下（typeof process === "undefined"）短路返回空字符串，保证 SSR / 浏览器调用安全。 资料来源：sdk/typescript/src/paths.ts:18-36。

压缩钩子（hooks.ts）

CompressionHooks 抽象类暴露三个生命周期方法：preCompress(messages, ctx) 在压缩前修改消息；computeBiases(messages, ctx) 返回每条消息的偏置映射（>1 表示保留更多，<1 表示更激进压缩）；postCompress(event) 为只读回调，CompressEvent 中包含 tokensBefore/After/Saved、compressionRatio 与 transformsApplied 等关键指标，便于自定义埋点。 资料来源：sdk/typescript/src/hooks.ts:3-58。

多格式消息转换（utils/format.ts）

detectFormat(messages) 通过结构特征区分四种 Provider 格式：OpenAI（tool_calls 字段）、Anthropic（tool_use / tool_result 下划线块）、Vercel AI SDK（tool-call / tool-result 中划线 Part）、Google Gemini（顶层 parts 字段）。所有消息最终统一转换为 OpenAI 形态（代理的 lingua franca），避免在代理层维护多份解码器。 资料来源：sdk/typescript/src/utils/format.ts:14-32。

配套 CLI 与 Rust 核心

Python 端 wrap / init CLI

headroom/cli/wrap.py 负责把 Codex / Claude / Copilot 等编码代理与 Headroom 代理桥接：先快照 ~/.codex/config.toml，再按 _selected_context_tool() 选择 RTK 或 lean-ctx 注入到 AGENTS.md，最后通过 CodexRegistrar 注册 headroom_retrieve MCP 子进程。init.py 维护 _SUPPORTED_TARGETS = ("claude", "copilot", "codex", "openclaw") 与本地 / 全局目标集合，并在幂等的 _enable_verbose_logging() 中以单一 stderr 句柄输出 DEBUG 日志，避免污染 stdout 管道。 资料来源：headroom/cli/wrap.py:1-80、headroom/cli/init.py:1-30。

TOIN 推荐发布与 Rust 算法桥

headroom/cli/toin_publish.py 解释 PR-B5 之后，TOIN 推荐改走离线发布：按 (auth_mode, model_family, structure_hash) 聚合 TOIN 落盘条目，序列化为 recommendations.toml 由 Rust 代理在启动时一次性加载。crates/headroom-py/src/lib.rs 则把 KeywordRegistry::default_set() 暴露为 Python 字典，把 SearchCompressor 用 LineImportanceDetector 重写并修正了 Windows 路径与带连字符文件名的解析缺陷；RustLogConfig 通过 pyo3 签名把 12 个调参字段（max_errors、enable_ccr、min_compression_ratio_for_ccr 等）原样透出。 资料来源：headroom/cli/toin_publish.py:1-60、crates/headroom-py/src/lib.rs:1-80。

常见使用模式

1. 零代码接入：headroom proxy --port 8787 启动代理，将 OPENAI_BASE_URL 或 ANTHROPIC_BASE_URL 指过去即可；TS SDK 无需任何修改。 资料来源：README.md:1-30。
2. 适配器方式：在 Node 端 import { openai } from "headroom-ai/openai" 拿到带压缩能力的客户端，配合 CompressionHooks 子类做埋点。 资料来源：sdk/typescript/package.json:18-37。
3. 编码代理 wrap：headroom wrap codex --no-serena --port 9999 在自定义端口启动 Codex 同时挂上 headroom_retrieve MCP 工具。 资料来源：headroom/cli/wrap.py:1-50。
4. 多 Provider 互通：detectFormat 自动把 Anthropic、Vercel、Gemini 的会话转为 OpenAI 形态发送到代理，再由代理路由到任意上游；这一抽象也是社区 Issue #74 提出的 OpenCode CLI 包装得以低成本复用的原因。 资料来源：sdk/typescript/src/utils/format.ts:20-32。

已知约束与社区关切

• Issue #74、#76 提议的 OpenCode CLI / npm 插件尚未合入主干，目前只能借助通用 headroom wrap 模式接入。 资料来源：README.md:1-20。
• Issue #488（Copilot 订阅模式）催生了 v0.23.0 的新特性 copilot: GitHub Copilot subscription mode，但 Crates 层的 subscription_state 路径仍要求用户设置 HEADROOM_SUBSCRIPTION_STATE_PATH，否则回退到默认。 资料来源：sdk/typescript/src/paths.ts:24-28。
• compressionRatio 在 hooks.ts 中以浮点暴露，但 Rust 端 min_compression_ratio_for_ccr 的默认值是 0.5（资料来源：crates/headroom-py/src/lib.rs:40-70），因此低于该阈值的工具输出不会进入 CCR 可逆存储。

See Also

• 架构总览
• CCR 可逆压缩
• Kompress-base 模型卡
• CONTRIBUTING.md

模块定位与总体职责

Sdk 模块是 Headroom 项目的多语言客户端层，承担"贴近应用、与代理解耦"的角色。它把核心压缩能力以两种形式暴露给下游：

• TypeScript SDK（sdk/typescript/）：面向 Node.js / Vercel AI SDK / OpenAI / Anthropic 原生 SDK 的 HTTP 客户端与中间件，通过 withHeadroom() 一行式接入；
• Python SDK 绑定（crates/headroom-py/）：通过 PyO3 将 Rust 实现的高性能关键字检测与搜索压缩器暴露给 Python 代理，避免 Python 侧重复声明关键字集合。

两者均围绕同一个原则：核心压缩由 Rust 代理执行，SDK 只负责"格式归一化 → 调用 → 还原"。资料来源：README.md:1-30

flowchart LR
  A[应用 / Agent] --> B[SDK 客户端]
  B --> C[格式归一化<br/>format.ts]
  B --> D[路径解析<br/>paths.ts]
  B --> E[HTTP 调用]
  E --> F[Rust 代理<br/>headroom proxy]
  F --> G[LLM 提供方]
  F -. CCR 回写 .-> H[CompressionStore]
  B -. PyO3 .-> I[Python SDK 绑定<br/>headroom-py]
  I --> F

TypeScript SDK

支持的消息格式

format.ts 实现了 4 种主流格式的结构化检测与向 OpenAI 格式的转换，作为代理的"通用语"（sdk/typescript/src/utils/format.ts:1-22）：

检测基于"每种格式独有的结构标记"而非启发式规则，因此对伪装格式具备较强抗干扰能力。资料来源：sdk/typescript/src/utils/format.ts:30-50

路径与配置契约

sdk/typescript/src/paths.ts 是 Python headroom/paths.py 的同构镜像，定义两个规范根：

• HEADROOM_CONFIG_DIR（默认 ~/.headroom/config）—— 只读配置；
• HEADROOM_WORKSPACE_DIR（默认 ~/.headroom）—— 读写状态。

每个具体资源（savings、toin、subscription state）的解析优先级均为：显式参数 > 资源专属环境变量 > 从规范根派生 > 默认值。浏览器环境下 typeof process === "undefined" 时所有辅助函数返回空串，提示消费者不要在浏览器中调用这些工具。资料来源：sdk/typescript/src/paths.ts:1-50

示例矩阵

sdk/typescript/examples/ 提供了三类可运行示例：Vercel AI SDK 集成（with-headroom-vercel.ts、streaming-chat.ts、tool-calling-agent.ts、middleware-composition.ts）、核心 SDK（basic-compress.ts、simulation-dry-run.ts、hooks-custom-compression.ts、shared-context-multi-agent.ts、ccr-retrieve.ts）以及原生 SDK 适配器（openai-anthropic-adapters.ts）。运行前置条件为 Node.js 18+、已启动代理进程与 OPENAI_API_KEY。资料来源：sdk/typescript/examples/README.md:1-50

Python SDK 绑定（PyO3）

crates/headroom-py/src/lib.rs 通过 PyO3 把 Rust 实现的关键能力下沉到 Python 侧：

• content_has_error_indicators(text)：直接调用共享关键字检测器，Python 代理无需重复声明关键字正则；
• keyword_registry_snapshot()：以字典形式导出默认关键字集，Python shim 据此重新编译遗留的 re.Pattern 对象；
• search_compressor 桥：与 headroom.transforms.search_compressor.SearchCompressor 对齐，使用 signals::LineImportanceDetector trait 评分（而非 Python 原版的正则注册表），并修复了 Windows 路径与文件名带连字符的解析缺陷。

CCR 持久化通过回调钩子暴露给 Python 侧的 CompressionStore——Rust crate 不持有长生命周期存储引用，由调用方在请求时注入。资料来源：crates/headroom-py/src/lib.rs:1-60

周边 CLI 工具

虽然不属 SDK 本体，但与 SDK 调用紧密相关的两个 CLI 也由该模块承载：

• headroom/cli/wrap.py 提供 headroom wrap <agent> 入口，负责向各 agent 注入 RTK / lean-ctx 提示、注册 Headroom MCP 服务器，并在卸载时清理代码块标记（如 <!-- headroom:rtk-instructions -->）。该逻辑通过 _inject_rtk_instructions() 等幂等助手实现，便于多次重入。资料来源：headroom/cli/wrap.py:1-80
• headroom/cli/toin_publish.py 把离线 TOIN 推荐聚合为 recommendations.toml，供 Rust 代理在启动时一次性加载，避开"请求期内变更状态"的耦合。资料来源：headroom/cli/toin_publish.py:1-40

社区关注点

社区请求集中在代理侧对更多 agent 的封装（OpenCode CLI wrapper #74、headroom-opencode 插件 #76、Hermes 支持 #526、Copilot 订阅模式 #488）以及 Homebrew 安装 #527。这些都依赖 SDK 暴露的 HTTP / 格式归一化能力——例如 Copilot 订阅模式需要在客户端侧先压缩再交给 Copilot CLI 打包，正是 format.ts 的结构化检测与 paths.ts 的工作区隔离所能支撑的场景。

See Also

• 代理核心（Rust / crates/headroom-core/）
• RTK 与 CLI 上下文工具（README.md:1-30）
• TOIN 推荐发布流程（headroom/cli/toin_publish.py:1-40）

概述

Cli 模块（位于 headroom/cli/ 目录）是 headroom 项目的命令行入口，负责把上下文压缩、CCR（Compress-Cache-Retrieve）、MCP 服务、持久化部署以及工具透传等子能力以子命令的形式暴露给用户。所有 CLI 入口都基于 click 构建，注册到主命令 main 上，根模块的导入与 __main__ 启动也由该目录承担。CLI 的设计目标是把"使用 headroom"和"安装 headroom"统一在同一个二进制中，开发者既能用 headroom wrap <client> 一键启动带压缩代理的 AI 客户端，也能在生产环境用 headroom install ... 长期部署。

资料来源：headroom/cli/wrap.py:1-10（headroom.wrap 子命令的 docstring 描述了代理启动 + 上下文工具注入 + MCP 注册的职责分工）

核心子命令

CLI 模块目前暴露以下主要子命令分组：

资料来源：headroom/cli/wrap.py:38-54、headroom/cli/install.py:23-46、headroom/cli/mcp.py:18-24、headroom/cli/tools.py:1-15、headroom/cli/toin_publish.py:1-19

`wrap` 子命令架构

wrap 是 CLI 模块最复杂的部分，它以"启动代理 + 修改目标客户端配置 + 注入上下文工具 + 注册 MCP"四步流程包装任何受支持的 AI 客户端。下图展示了一次 headroom wrap codex 调用的数据流：

flowchart TD
    A["用户执行 headroom wrap codex"] --> B["备份 ~/.codex/config.toml"]
    B --> C{"是否 --no-context-tool?"}
    C -- 否 --> D["安装 RTK / lean-ctx 并写入 AGENTS.md"]
    C -- 是 --> E["跳过 CLI 上下文工具"]
    D --> F
    E --> F{"是否 --no-mcp?"}
    F -- 否 --> G["通过 CodexRegistrar 注册 headroom MCP"]
    F -- 是 --> H["跳过 MCP 注册"]
    G --> I["启动 headroom 代理 (127.0.0.1:port)"]
    H --> I
    I --> J["设置 openai_base_url 指向代理 /v1"]
    J --> K["exec codex 子进程"]

wrap 在写入任何配置前都会先调用 _snapshot_codex_config_if_unwrapped，把原始 ~/.codex/config.toml 备份到本地，以便后续 headroom unwrap 字节级回滚。Codex 子命令还会在 MCP 注册时强制使用 force=True，因为 Codex 会从 config.toml 启动一个长生命周期 MCP 子进程，端口漂移会让模型流量和 retrieve 流量指向不同代理。资料来源：headroom/cli/wrap.py:1-37、headroom/cli/wrap.py:104-137。

针对 Continue 这种 IDE 插件，CLI 在 docstring 中明确指出其 JSON 配置只能手工写入，并且会同时修改顶层 systemMessage 与每个 models[i].systemMessage，因为 Continue 的 per-model 配置会覆盖顶层值。资料来源：headroom/cli/wrap.py:24-37`。

上下文工具与 MCP 集成

CLI 模块在 wrap 阶段会根据 HEADROOM_CONTEXT_TOOL 环境变量选择 CLI 上下文工具：默认使用 RTK 二进制（git show --short、范围 ls、安装器摘要），也可通过 HEADROOM_CONTEXT_TOOL=lean-ctx 切换到 lean-ctx。RTK 的指引会同时写入项目级 AGENTS.md 和全局 ~/.codex/AGENTS.md，保证 Codex 在任意目录下都能读取到。资料来源：README.md:48-52、headroom/cli/wrap.py:10-22`。

MCP 部分由 headroom mcp 子命令族提供，mcp serve 启动子进程，mcp 父命令把执行命令写入 ~/.claude/mcp.json（默认 ["headroom", "mcp", "serve"]），并把默认代理 URL 设为 http://127.0.0.1:8787。这使得 Claude Code 订阅用户无需 BYOK 即可使用 CCR。资料来源：headroom/cli/mcp.py:18-42、headroom/cli/mcp.py:88-115（save_mcp_config 与 get_headroom_command` 实现）。

持久化部署与离线工具

headroom install 把"长期运行的 headroom 代理"建模为 DeploymentManifest，支持 persistent_docker 预设与 service 监督进程，并能调用 start_detached_agent 把代理作为后台进程拉起。probe_json / probe_ready / wait_ready 三个健康检查函数确保部署真正进入就绪状态后才返回，45 秒超时由 _start_deployment 强制执行。资料来源：headroom/cli/install.py:23-46、headroom/cli/install.py:60-70`。

headroom tools 则是面向本地工作流的"工具透传"层：它直接 exec 由 headroom.binaries.resolve 解析出的二进制（ast-grep、difftastic、scc），把 stdin/stdout/stderr 和退出码原样转发，因此 AI agent 可以在自己的 shell 工具中按原协议调用这些工具而无需适配层。headroom tools install 在网络可达时预取所有二进制，headroom tools doctor 输出注册表状态。资料来源：headroom/cli/tools.py:1-30、headroom/cli/tools.py:40-60`。

See Also

• README.md — 顶层概览与安装方式
• examples/README.md — 配合 CLI 使用的示例脚本
• community issue #74 — 关于 headroom wrap opencode 的需求讨论
• community issue #488 — Copilot CLI 订阅模式（已在 v0.23.0 落地）

Pitfall Log / 踩坑日志

项目：chopratejas/headroom

摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:1129940957 | https://github.com/chopratejas/headroom | host_targets=mcp_host, claude, claude_code, cursor

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1129940957 | https://github.com/chopratejas/headroom | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1129940957 | https://github.com/chopratejas/headroom | last_activity_observed missing

4. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1129940957 | https://github.com/chopratejas/headroom | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1129940957 | https://github.com/chopratejas/headroom | no_demo; severity=medium

6. 安全/权限坑 · 来源证据：[BUG] MCP/direct compression hangs on larger JSON payloads on Windows; proxy `/mcp` does not behave as documented

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] MCP/direct compression hangs on larger JSON payloads on Windows; proxy /mcp does not behave as documented
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6944f8dfa67c4b77a3b8f195b6c26116 | https://github.com/chopratejas/headroom/issues/600 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

7. 安全/权限坑 · 来源证据：[FEATURE] Export Compression Analytics and Savings Report

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Export Compression Analytics and Savings Report
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_03edfd5764e74ad9acceb660448845a6 | https://github.com/chopratejas/headroom/issues/599 | 来源类型 github_issue 暴露的待验证使用条件。

8. 安全/权限坑 · 来源证据：[FEATURE] Strands SDK Integration

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Strands SDK Integration
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_5af57029e46046fbb7cb73bc2f563a38 | https://github.com/chopratejas/headroom/issues/14 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

9. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1129940957 | https://github.com/chopratejas/headroom | issue_or_pr_quality=unknown

10. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1129940957 | https://github.com/chopratejas/headroom | release_recency=unknown