配置参考

AgentStash 配置文件、目录和 Provider 定义的完整参考。

AgentStash 将其配置和数据存储在 ~/.config/agentstash/ 目录中。

目录结构

~/.config/agentstash/
├── state.json              # 应用状态和偏好设置
├── dotagents.yaml          # Dotagents (Hub) 配置
├── providers/              # 自定义 Provider 定义
│   └── my-tool.yaml
├── backups/                # 同步前的自动备份
├── cas/                    # 内容寻址存储
└── staging/                # 临时暂存区

配置文件

state.json

存储应用状态，包括：

同步目录路径
Provider 启用/禁用状态
资源启用/禁用状态
UI 偏好设置

dotagents.yaml

配置 Dotagents (Hub) 功能，通过符号链接将技能分发到所有 AI 工具。

# 启用/禁用 Dotagents 分发
enabled: true

# 规范源的基础路径
base_path: "~/.agents"

字段	类型	默认值	描述
`enabled`	boolean	`true`	启用 Dotagents 分发
`base_path`	string	`~/.agents`	包含规范技能的目录

启用后，AgentStash 会从每个 Provider 的技能目录创建符号链接到 ~/.agents/skills/，让所有工具共享相同的技能定义。

自定义 Provider

你可以通过在 ~/.config/agentstash/providers/ 中创建 YAML 文件来添加对其他 AI 工具的支持。

Provider YAML 模式

# yaml-language-server: $schema=https://agentstash.dev/provider.schema.json

id: my-tool
name: "My Tool"

discovery:
  base_path: "~/.my-tool"
  exists_check: true

resources:
  - glob: "skills/**"
    handler: directory_bundle
    description: "My Tool skills"

hub_capabilities:
  - skills

必填字段

字段	类型	描述
`id`	string	唯一标识符（小写，字母数字和连字符）
`name`	string	人类可读的显示名称
`discovery.base_path`	string	工具存储配置的路径
`resources`	array	要同步的资源配置列表

Discovery 配置

字段	类型	默认值	描述
`base_path`	string	必填	Provider 的基础路径（支持 `~`）
`exists_check`	boolean	`true`	同步前验证路径是否存在

Resource 配置

每个资源定义要同步的文件：

字段	类型	默认值	描述
`glob`	string	必填	匹配文件的 glob 模式
`handler`	string	必填	如何处理匹配的文件
`description`	string	`""`	人类可读的描述
`default_enabled`	boolean	`true`	是否默认启用
`exclude`	array	`[]`	要排除的 glob 模式

Handler 类型

Handler	用途
`file_copy`	单个文件（如 `rules.md`、`config.json`）
`directory_bundle`	目录作为原子单位（如 `skills/**`）
`json_normalize`	JSON 文件（比较前规范化）
`yaml_normalize`	YAML 文件（比较前规范化）

Hub 能力

为特定资源类型启用 Dotagents 分发：

hub_capabilities:
  - skills      # 通过符号链接分发技能
  - commands    # 通过符号链接分发命令

可用能力：skills、commands、hooks、agents、rules、prompts

Provider 配置路径

每个 AI 工具将其配置存储在特定位置。AgentStash 从这些路径读取和同步：

Provider	配置路径
Claude Code	`~/.claude`
Cursor	`~/.cursor`
Windsurf	`~/.codeium/windsurf`
OpenCode	`~/.config/opencode`
Cline	`~/.cline`
Continue	`~/.continue`
Roo Code	`~/.roo`
Goose	`~/.config/goose`
Codex	`~/.codex`
Gemini CLI	`~/.gemini`
GitHub Copilot	`~/.copilot`
Amp	`~/.config/agents`
Trae	`~/.trae`
Trae CN	`~/.trae-cn`

环境变量

AgentStash 支持以下环境变量：

变量	描述
`HOME`	用户主目录（用于 `~` 扩展）
`XDG_CONFIG_HOME`	替代配置目录（默认为 `~/.config`）

备份行为

在每次同步操作之前，AgentStash 会自动将受影响的文件备份到 ~/.config/agentstash/backups/。备份带有时间戳，可在需要时恢复。