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/headroomHeadroom是面向 LLM 智能体的 Token 压缩工具——在工具输出、日志、文件与 RAG 分块进入大模型前进行压缩为编程智能体节省 20% Token、为 JSON 节省 60–95% Token。而所有这些压缩统计、日志、内存数据库等运行数据都统一存放在一个受契约约束的状态目录里。本文将完整解析 Headroom 文件系统契约Filesystem Contract逐一说明HEADROOM_WORKSPACE_DIR环境变量如何控制状态目录的全路径。双根模型一个配置根 一个状态根Headroom 采用双根文件系统模型全部路径都从这两个根目录派生环境变量默认值用途访问特征HEADROOM_CONFIG_DIR~/.headroom/config用户/管理员编写的配置模型目录、插件设置只读为主HEADROOM_WORKSPACE_DIR~/.headroom代理与 CLI 写入的运行时状态节省台账、日志、内存库、遥测、缓存可读写两个变量被 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的完整路径清单资源默认路径兼容的旧环境变量代理节省台账${WORKSPACE_DIR}/proxy_savings.jsonHEADROOM_SAVINGS_PATH节省事件流水只追加${WORKSPACE_DIR}/savings_events.jsonlHEADROOM_SAVINGS_EVENTS_PATHTOIN 压缩反馈遥测${WORKSPACE_DIR}/toin.jsonHEADROOM_TOIN_PATH订阅追踪状态${WORKSPACE_DIR}/subscription_state.jsonHEADROOM_SUBSCRIPTION_STATE_PATH内存 SQLite 数据库${WORKSPACE_DIR}/memory.dbCLI--memory-db-path原生记忆目录${WORKSPACE_DIR}/memories/MemoryConfig.native_memory_dir许可证缓存${WORKSPACE_DIR}/license_cache.json—会话统计 JSONL${WORKSPACE_DIR}/session_stats.jsonl—内存同步 / 桥接状态${WORKSPACE_DIR}/sync_state.json、bridge_state.json—代理日志目录${WORKSPACE_DIR}/logs/含proxy.log—HTTP 400 调试转储${WORKSPACE_DIR}/logs/debug_400/—部署配置档${WORKSPACE_DIR}/deploy/—插件状态目录${WORKSPACE_DIR}/plugins/插件名/—端口锁文件${WORKSPACE_DIR}/.beacon_lock_port、.proxy_start_port.lock—这些台账最终都会呈现在仪表盘上例如历史压缩视图读取的正是工作区桶中的持久化数据而社区累计节省视图则展示了savings_events.jsonl这类只追加台账的长期价值配置桶与插件目录只读为主的一侧配置桶HEADROOM_CONFIG_DIR下主要存放models.json—— 模型目录旧版位于~/.headroom/models.jsonPython 侧会按新位置 → 旧位置顺序双读保证平滑迁移plugins/插件名/...—— 各插件的独立配置。插件作者可通过两个受沙箱保护的助手获取隔离目录拒绝含/或\的名称防止路径逃逸plugin_config_dir(my-plugin)→~/.headroom/config/plugins/my-pluginplugin_workspace_dir(my-plugin)→~/.headroom/plugins/my-pluginDocker 场景别混淆两个WORKSPACEDocker 部署中有一个高频混淆点HEADROOM_WORKSPACE与HEADROOM_WORKSPACE_DIR是两个不同的变量变量作用域含义HEADROOM_WORKSPACE宿主机侧要绑定挂载进容器/workspace的项目目录HEADROOM_WORKSPACE_DIR容器内Headroom 状态根官方 compose 中设为/home/nonroot/.headroom并挂载到命名卷官方 docker-compose.yml 会自动在容器内设置HEADROOM_WORKSPACE_DIR和HEADROOM_CONFIG_DIR状态落盘到headroom_workspace命名卷容器重建后数据不丢。详见 wiki/persistent-installs.md 与 wiki/filesystem-contract.md。进阶无状态模式HEADROOM_STATELESS如果你的环境不允许写盘如只读容器可设置HEADROOM_STATELESStrue——代理启动时会通过set_process_stateless()记录该模式所有写入器台账、TOIN、遥测等将跳过对状态目录的写入路径解析逻辑本身不受影响。快速上手三步迁移状态目录创建目标目录如mkdir -p /mnt/headroom-state在启动代理前导出export HEADROOM_WORKSPACE_DIR/mnt/headroom-state配置根会随之自动指向/mnt/headroom-state/config将旧的~/.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Headroom 文件系统契约解析：HEADROOM_WORKSPACE_DIR 状态目录全路径说明
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/headroomHeadroom是面向 LLM 智能体的 Token 压缩工具——在工具输出、日志、文件与 RAG 分块进入大模型前进行压缩为编程智能体节省 20% Token、为 JSON 节省 60–95% Token。而所有这些压缩统计、日志、内存数据库等运行数据都统一存放在一个受契约约束的状态目录里。本文将完整解析 Headroom 文件系统契约Filesystem Contract逐一说明HEADROOM_WORKSPACE_DIR环境变量如何控制状态目录的全路径。双根模型一个配置根 一个状态根Headroom 采用双根文件系统模型全部路径都从这两个根目录派生环境变量默认值用途访问特征HEADROOM_CONFIG_DIR~/.headroom/config用户/管理员编写的配置模型目录、插件设置只读为主HEADROOM_WORKSPACE_DIR~/.headroom代理与 CLI 写入的运行时状态节省台账、日志、内存库、遥测、缓存可读写两个变量被 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的完整路径清单资源默认路径兼容的旧环境变量代理节省台账${WORKSPACE_DIR}/proxy_savings.jsonHEADROOM_SAVINGS_PATH节省事件流水只追加${WORKSPACE_DIR}/savings_events.jsonlHEADROOM_SAVINGS_EVENTS_PATHTOIN 压缩反馈遥测${WORKSPACE_DIR}/toin.jsonHEADROOM_TOIN_PATH订阅追踪状态${WORKSPACE_DIR}/subscription_state.jsonHEADROOM_SUBSCRIPTION_STATE_PATH内存 SQLite 数据库${WORKSPACE_DIR}/memory.dbCLI--memory-db-path原生记忆目录${WORKSPACE_DIR}/memories/MemoryConfig.native_memory_dir许可证缓存${WORKSPACE_DIR}/license_cache.json—会话统计 JSONL${WORKSPACE_DIR}/session_stats.jsonl—内存同步 / 桥接状态${WORKSPACE_DIR}/sync_state.json、bridge_state.json—代理日志目录${WORKSPACE_DIR}/logs/含proxy.log—HTTP 400 调试转储${WORKSPACE_DIR}/logs/debug_400/—部署配置档${WORKSPACE_DIR}/deploy/—插件状态目录${WORKSPACE_DIR}/plugins/插件名/—端口锁文件${WORKSPACE_DIR}/.beacon_lock_port、.proxy_start_port.lock—这些台账最终都会呈现在仪表盘上例如历史压缩视图读取的正是工作区桶中的持久化数据而社区累计节省视图则展示了savings_events.jsonl这类只追加台账的长期价值配置桶与插件目录只读为主的一侧配置桶HEADROOM_CONFIG_DIR下主要存放models.json—— 模型目录旧版位于~/.headroom/models.jsonPython 侧会按新位置 → 旧位置顺序双读保证平滑迁移plugins/插件名/...—— 各插件的独立配置。插件作者可通过两个受沙箱保护的助手获取隔离目录拒绝含/或\的名称防止路径逃逸plugin_config_dir(my-plugin)→~/.headroom/config/plugins/my-pluginplugin_workspace_dir(my-plugin)→~/.headroom/plugins/my-pluginDocker 场景别混淆两个WORKSPACEDocker 部署中有一个高频混淆点HEADROOM_WORKSPACE与HEADROOM_WORKSPACE_DIR是两个不同的变量变量作用域含义HEADROOM_WORKSPACE宿主机侧要绑定挂载进容器/workspace的项目目录HEADROOM_WORKSPACE_DIR容器内Headroom 状态根官方 compose 中设为/home/nonroot/.headroom并挂载到命名卷官方 docker-compose.yml 会自动在容器内设置HEADROOM_WORKSPACE_DIR和HEADROOM_CONFIG_DIR状态落盘到headroom_workspace命名卷容器重建后数据不丢。详见 wiki/persistent-installs.md 与 wiki/filesystem-contract.md。进阶无状态模式HEADROOM_STATELESS如果你的环境不允许写盘如只读容器可设置HEADROOM_STATELESStrue——代理启动时会通过set_process_stateless()记录该模式所有写入器台账、TOIN、遥测等将跳过对状态目录的写入路径解析逻辑本身不受影响。快速上手三步迁移状态目录创建目标目录如mkdir -p /mnt/headroom-state在启动代理前导出export HEADROOM_WORKSPACE_DIR/mnt/headroom-state配置根会随之自动指向/mnt/headroom-state/config将旧的~/.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考