fz-mirrors/AstrBot
1
0
Fork 0
mirror of https://github.com/AstrBotDevs/AstrBot synced 2026-07-16 01:40:15 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
5303e40931da27d8f631a553d5b4994decc4a03c
AstrBot/openspec/path.md
LIghtJUNction 14a1e37261 docs: 更新 openspec 规范文档 
- 添加实现状态表格
- 更新配置规范
- 添加新的协议规范
2026-03-27 19:10:49 +08:00

12 KiB
Raw Blame History

路径规范

概述

AstrBot 遵循 XDG Base Directory Specification，定义标准化的目录结构。

跨平台支持：

  • Linux/macOS 桌面：遵循 XDG 规范
  • Linux 服务器：使用 /var/lib/astrbot（systemd 服务场景）
  • Windows：不遵循 XDG，使用 %APPDATA% / %LOCALAPPDATA% / %USERPROFILE%

相关: config.md（配置规范）, env.md（环境变量）

  • BSD/Unix：遵循 XDG 规范

Linux 服务器场景

为什么使用 /var/lib/astrbot

原因 说明
FHS 合规 /var/lib 用于存储可变的状态信息，符合文件系统层次结构标准
systemd 服务 服务以系统用户运行，无用户目录访问权限
系统级目录 所有用户共享，适合守护进程部署
持久化 /var 分区通常有足够空间存储数据

场景说明：

  • systemd 服务以 astrbot 系统用户运行
  • 系统用户没有 ~/.local/share 等用户目录
  • 必须使用系统级目录 /var/lib/astrbot

Linux 服务器路径

类型 路径 说明
配置 /var/lib/astrbot/config/ 配置文件
数据 /var/lib/astrbot/ 主数据目录
缓存 /var/cache/astrbot/ 临时文件
状态 /var/lib/astrbot/state/ 会话状态
日志 /var/log/astrbot/ 日志文件
运行时 /run/astrbot/ PID 文件、socket

目录结构：

/var/lib/astrbot/
├── config/                    # 配置文件
│   └── mcp_servers.json        # MCP 服务器配置
├── data/                      # 插件、skills 等
│   ├── plugins/
│   ├── plugin_data/
│   ├── skills/
│   ├── knowledge_base/
│   ├── backups/
│   └── webchat/
├── state/                     # 会话状态
│   └── sessions/
└── .env                       # 环境变量

/var/cache/astrbot/
├── temp/                      # 临时文件
└── t2i_templates/             # 文转图模板

/run/astrbot/                  # 运行时文件
├── astrbot.sock               # Unix Socket
└── pid                        # PID 文件

MCP 服务器配置

MCP 服务器配置位于 config/mcp_servers.json：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
      "env": {}
    },
    "http-server": {
      "url": "http://localhost:3000/mcp",
      "transport": "sse"
    }
  }
}

配置字段：

字段 类型 说明
command string 启动命令（stdio 传输）
args array 命令参数
env object 环境变量
url string 服务器 URL（HTTP 传输）
transport string 传输类型：stdio / sse / streamable_http

平台差异

平台 配置目录 数据目录 缓存目录 运行时目录
Linux 桌面 $XDG_CONFIG_HOME/astrbot/ $XDG_DATA_HOME/astrbot/ $XDG_CACHE_HOME/astrbot/ $XDG_RUNTIME_DIR/astrbot/
Linux 服务器 /var/lib/astrbot/config/ /var/lib/astrbot/ /var/cache/astrbot/ /run/astrbot/
macOS $XDG_CONFIG_HOME/astrbot/ $XDG_DATA_HOME/astrbot/ $XDG_CACHE_HOME/astrbot/ $XDG_RUNTIME_DIR/astrbot/
Windows %APPDATA%/AstrBot/ %LOCALAPPDATA%/AstrBot/ %TEMP%/AstrBot/ %LOCALAPPDATA%/AstrBot/runtime/

XDG 基础变量（Linux/macOS）

变量 默认值 说明
XDG_CONFIG_HOME ~/.config 用户配置文件目录
XDG_DATA_HOME ~/.local/share 用户数据目录
XDG_CACHE_HOME ~/.cache 用户缓存目录
XDG_STATE_HOME ~/.local/state 用户状态目录
XDG_RUNTIME_DIR /run/user/<UID> 运行时目录

AstrBot 目录结构

$XDG_DATA_HOME/astrbot/
├── data/                      # 应用数据
│   ├── plugins/              # 插件目录
│   ├── plugin_data/          # 插件数据
│   ├── skills/               # Skills 目录
│   ├── knowledge_base/       # 知识库
│   ├── backups/              # 备份
│   └── webchat/              # WebChat 数据
├── cache/                     # 缓存
│   ├── temp/                 # 临时文件
│   └── t2i_templates/        # 文转图模板
└── state/                     # 状态
    └── sessions/              # 会话状态

$XDG_CONFIG_HOME/astrbot/
├── .env                      # 环境变量
├── config.yaml               # 主配置文件
└── mcp_servers.json          # MCP 服务器配置

路径映射

配置目录 (XDG_CONFIG_HOME/astrbot/)

路径 说明 环境变量
$XDG_CONFIG_HOME/astrbot/ AstrBot 配置根目录 ASTRBOT_CONFIG_DIR
$XDG_CONFIG_HOME/astrbot/.env 环境变量文件 -
$XDG_CONFIG_HOME/astrbot/config.yaml 主配置文件 -

数据目录 (XDG_DATA_HOME/astrbot/)

路径 说明 环境变量
$XDG_DATA_HOME/astrbot/ AstrBot 数据根目录 ASTRBOT_DATA_DIR
$XDG_DATA_HOME/astrbot/plugins/ 插件目录 ASTRBOT_PLUGIN_DIR
$XDG_DATA_HOME/astrbot/plugin_data/ 插件数据 ASTRBOT_PLUGIN_DATA_DIR
$XDG_DATA_HOME/astrbot/skills/ Skills 目录 ASTRBOT_SKILLS_DIR
$XDG_DATA_HOME/astrbot/knowledge_base/ 知识库 ASTRBOT_KB_DIR
$XDG_DATA_HOME/astrbot/backups/ 备份目录 ASTRBOT_BACKUPS_DIR
$XDG_DATA_HOME/astrbot/webchat/ WebChat 数据 ASTRBOT_WEBCHAT_DIR

缓存目录 (XDG_CACHE_HOME/astrbot/)

路径 说明 环境变量
$XDG_CACHE_HOME/astrbot/ AstrBot 缓存根目录 ASTRBOT_CACHE_DIR
$XDG_CACHE_HOME/astrbot/temp/ 临时文件 ASTRBOT_TEMP_DIR
$XDG_CACHE_HOME/astrbot/t2i_templates/ 文转图模板 -

状态目录 (XDG_STATE_HOME/astrbot/)

路径 说明 环境变量
$XDG_STATE_HOME/astrbot/ AstrBot 状态根目录 ASTRBOT_STATE_DIR
$XDG_STATE_HOME/astrbot/sessions/ 会话状态 -

运行时目录

路径 说明 环境变量
/run/user/<UID>/astrbot/ 运行时目录 ASTRBOT_RUNTIME_DIR

项目目录

路径 说明 备注
<source_root>/ 源码目录 固定，指向 astrbot 包位置
<source_root>/dashboard/dist/ 前端资源 固定

环境变量覆盖

根目录覆盖

变量 说明 优先级
ASTRBOT_ROOT 覆盖整个 AstrBot 数据根目录 最高
ASTRBOT_DATA_DIR 覆盖数据目录 次高
ASTRBOT_CONFIG_DIR 覆盖配置目录 次高

子目录覆盖

变量 说明
ASTRBOT_PLUGIN_DIR 插件目录
ASTRBOT_PLUGIN_DATA_DIR 插件数据目录
ASTRBOT_SKILLS_DIR Skills 目录
ASTRBOT_KB_DIR 知识库目录
ASTRBOT_BACKUPS_DIR 备份目录
ASTRBOT_WEBCHAT_DIR WebChat 目录
ASTRBOT_TEMP_DIR 临时文件目录
ASTRBOT_CACHE_DIR 缓存根目录
ASTRBOT_STATE_DIR 状态根目录
ASTRBOT_RUNTIME_DIR 运行时目录

覆盖优先级

ASTRBOT_ROOT > ASTRBOT_DATA_DIR > 子目录变量

目录用途

目录 内容 是否持久化
config/ 配置文件、.env 是
plugins/ 插件代码 是
plugin_data/ 插件运行时数据 是
skills/ Skills 配置 是
knowledge_base/ 知识库文件 是
backups/ 备份文件 是
webchat/ WebChat 数据 是
temp/ 临时文件 否（可清理）
t2i_templates/ 文转图模板缓存 否（可清理）
sessions/ 会话状态 是

兼容性别名

以下路径函数保留用于向后兼容：

# 旧路径 → 新路径
get_astrbot_root()        → $XDG_DATA_HOME/astrbot/
get_astrbot_data_path()   → $XDG_DATA_HOME/astrbot/
get_astrbot_config_path() → $XDG_CONFIG_HOME/astrbot/
get_astrbot_plugin_path() → $XDG_DATA_HOME/astrbot/plugins/
get_astrbot_plugin_data_path() → $XDG_DATA_HOME/astrbot/plugin_data/
get_astrbot_skills_path() → $XDG_DATA_HOME/astrbot/skills/
get_astrbot_knowledge_base_path() → $XDG_DATA_HOME/astrbot/knowledge_base/
get_astrbot_backups_path() → $XDG_DATA_HOME/astrbot/backups/
get_astrbot_webchat_path() → $XDG_DATA_HOME/astrbot/webchat/
get_astrbot_temp_path() → $XDG_CACHE_HOME/astrbot/temp/
get_astrbot_t2i_templates_path() → $XDG_CACHE_HOME/astrbot/t2i_templates/

目录创建

AstrBot 启动时自动创建以下目录（如不存在）：

$XDG_CONFIG_HOME/astrbot/
$XDG_DATA_HOME/astrbot/
$XDG_DATA_HOME/astrbot/plugins/
$XDG_DATA_HOME/astrbot/plugin_data/
$XDG_DATA_HOME/astrbot/skills/
$XDG_DATA_HOME/astrbot/knowledge_base/
$XDG_DATA_HOME/astrbot/backups/
$XDG_DATA_HOME/astrbot/webchat/
$XDG_CACHE_HOME/astrbot/
$XDG_CACHE_HOME/astrbot/temp/
$XDG_CACHE_HOME/astrbot/t2i_templates/
$XDG_STATE_HOME/astrbot/
$XDG_STATE_HOME/astrbot/sessions/

多实例支持

通过 ASTRBOT_INSTANCE_NAME 支持多实例：

$XDG_DATA_HOME/astrbot/<instance_name>/
├── data/
├── cache/
└── state/

路径规范总结

Linux 服务器（systemd 部署）

类型 路径
配置 /var/lib/astrbot/config/
数据 /var/lib/astrbot/
缓存 /var/cache/astrbot/
状态 /var/lib/astrbot/state/
运行时 /run/astrbot/

Linux/macOS 桌面

类型 XDG 路径
配置 $XDG_CONFIG_HOME/astrbot/
数据 $XDG_DATA_HOME/astrbot/
缓存 $XDG_CACHE_HOME/astrbot/
状态 $XDG_STATE_HOME/astrbot/

Windows

类型 Windows 路径
配置 %APPDATA%/AstrBot/
数据 %LOCALAPPDATA%/AstrBot/
缓存 %TEMP%/AstrBot/

环境变量

所有平台统一使用 ASTRBOT_* 环境变量覆盖默认路径，优先级最高。

与 Claude Code 目录对比

Claude Code 使用 ~/.claude/ 作为根目录，不遵循 XDG 规范：

~/.claude/                          # Claude Code 根目录
├── backups/                        # 备份
├── cache/                          # 缓存
├── downloads/                       # 下载
├── file-history/                   # 文件历史
├── paste-cache/                    # 粘贴缓存
├── plans/                          # 计划
├── plugins/                        # 插件
├── projects/                       # 项目会话
├── session-env/                    # 会话环境
├── sessions/                       # 会话
├── shell-snapshots/                # Shell 快照
├── skills/                         # Skills
├── tasks/                          # 任务
├── teams/                          # 团队
├── history.jsonl                   # 对话历史
├── settings.json                   # 设置
└── settings.local.json             # 本地设置

关键差异

维度 Claude Code AstrBot
规范 非标准（固定 ~/.claude/） XDG 规范
配置 根目录直接放配置文件 分离到 $XDG_CONFIG_HOME/
缓存 根目录下 cache/ $XDG_CACHE_HOME/
数据 根目录直接放数据文件 分离到 $XDG_DATA_HOME/
会话 sessions/, session-env/ $XDG_STATE_HOME/
项目 projects/ 内嵌在数据目录

设计哲学

  • Claude Code：简单直接，所有内容在 ~/.claude/ 下
  • AstrBot：遵循 XDG，数据分类清晰（配置/数据/缓存/状态分离）

已知限制

  • Windows 平台不遵循 XDG 规范，使用 Windows 标准路径
  • 桌面客户端（packaged desktop runtime）使用 ~/.astrbot/ 作为数据根目录

相关: config.md（配置规范）, env.md（环境变量）

Reference in New Issue View Git Blame Copy Permalink