企业官网建设流程全解析

Headroom 文件系统契约解析：HEADROOM_WORKSPACE_DIR 状态目录全路径说明

【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom

Headroom是面向 LLM 智能体的 Token 压缩工具——在工具输出、日志、文件与 RAG 分块进入大模型前进行压缩，为编程智能体节省 20% Token、为 JSON 节省 60–95% Token。而所有这些压缩统计、日志、内存数据库等运行数据，都统一存放在一个受契约约束的状态目录里。本文将完整解析 Headroom 文件系统契约（Filesystem Contract），逐一说明HEADROOM_WORKSPACE_DIR环境变量如何控制状态目录的全路径。

双根模型：一个配置根 + 一个状态根

Headroom 采用"双根"文件系统模型，全部路径都从这两个根目录派生：

两个变量被 Python 代理/CLI 与 npm SDK 同时识别（TypeScript 侧的契约镜像见 sdk/typescript/src/paths.ts）。契约的唯一事实来源是 headroom/paths.py，官方文档见 docs/content/docs/filesystem-contract.mdx。

💡 关键联动：当你只设置HEADROOM_WORKSPACE_DIR时，配置根会自动派生为$HEADROOM_WORKSPACE_DIR/config——一次覆盖即可整体迁移两个根，非常便于备份。

路径解析优先级：4 级解析规则

工作区内每一份资源的路径，都按以下顺序解析（定义于 headroom/paths.py 的_resolve函数）：

显式参数（函数入参） ▼ 未传时 资源级环境变量（如 HEADROOM_SAVINGS_PATH） ▼ 未设置时 由规范根派生（如 $HEADROOM_WORKSPACE_DIR/proxy_savings.json） ▼ 未设置时 默认值（如 ~/.headroom/proxy_savings.json）

举例：

• HEADROOM_WORKSPACE_DIR=/mnt/state→ 节省台账落到/mnt/state/proxy_savings.json；
• 同时设了HEADROOM_SAVINGS_PATH=/custom/savings.json→ 后者永远优先；
• 都不设 → 走默认~/.headroom/proxy_savings.json。

工作区桶：状态目录里的全部资源清单

设置HEADROOM_WORKSPACE_DIR后，以下资源全部跟随迁移。下表是工作区桶（Workspace Bucket）的完整路径清单：

这些台账最终都会呈现在仪表盘上，例如历史压缩视图读取的正是工作区桶中的持久化数据：

而社区累计节省视图，则展示了savings_events.jsonl这类只追加台账的长期价值：

配置桶与插件目录：只读为主的一侧

配置桶（HEADROOM_CONFIG_DIR）下主要存放：

• models.json—— 模型目录（旧版位于~/.headroom/models.json，Python 侧会按"新位置 → 旧位置"顺序双读，保证平滑迁移）；
• plugins/<插件名>/...—— 各插件的独立配置。

插件作者可通过两个受沙箱保护的助手获取隔离目录（拒绝含/或\的名称，防止路径逃逸）：

• plugin_config_dir("my-plugin")→~/.headroom/config/plugins/my-plugin
• plugin_workspace_dir("my-plugin")→~/.headroom/plugins/my-plugin

Docker 场景：别混淆两个"WORKSPACE"

Docker 部署中有一个高频混淆点：HEADROOM_WORKSPACE与HEADROOM_WORKSPACE_DIR是两个不同的变量：

官方 docker-compose.yml 会自动在容器内设置HEADROOM_WORKSPACE_DIR和HEADROOM_CONFIG_DIR，状态落盘到headroom_workspace命名卷，容器重建后数据不丢。详见 wiki/persistent-installs.md 与 wiki/filesystem-contract.md。

进阶：无状态模式（HEADROOM_STATELESS）

如果你的环境不允许写盘（如只读容器），可设置HEADROOM_STATELESS=true——代理启动时会通过set_process_stateless()记录该模式，所有写入器（台账、TOIN、遥测等）将跳过对状态目录的写入，路径解析逻辑本身不受影响。

快速上手：三步迁移状态目录

1. 创建目标目录，如mkdir -p /mnt/headroom-state；
2. 在启动代理前导出export HEADROOM_WORKSPACE_DIR=/mnt/headroom-state（配置根会随之自动指向/mnt/headroom-state/config）；
3. 将旧的~/.headroom内容拷贝过去即可无缝续用——旧环境变量与旧路径的语义完全保留，向后逐字节兼容。

小结

HEADROOM_WORKSPACE_DIR是 Headroom 状态目录的"总开关"：一个变量即可整体迁移节省台账、TOIN 遥测、内存数据库、日志与插件状态，同时保持与全部旧版资源级环境变量的兼容。完整规范可参阅 docs/content/docs/filesystem-contract.mdx，路径契约实现见 headroom/paths.py。

【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom