Skip to content

config-spec.md

Latest commit

 

History

History
163 lines (124 loc) · 6.56 KB

config-spec.md

File metadata and controls

163 lines (124 loc) · 6.56 KB
Raw

.stdai/config.toml 配置规范

设计目标

  • 极简：核心字段不超过 20 个
  • 默认即可用：MVP 默认 enable Claude Code + Codex
  • 显式优于隐式：每个 target 单独配置
  • 可读：toml 格式 + 注释友好

完整示例

version = "1.0"
name = "my-ai-standards"

# 注入控制
inject = true              # 是否在生成文件末尾追加 stdagent footer
inject_whatis = true       # footer 是否包含详细说明（来源、命令、文件作用）
inject_type_glossary = false # 是否在支持的 rendered rules 中注入类型速查

# 全局开关
dry_run = false            # true 时只 diff 不写盘
backup = true              # sync 前备份将被覆盖的扩散文件
backup_keep = 5            # 备份目录保留数量
auto_pull = true           # sync 自动 pull 远端
verbose = false            # 详细日志
gitignore = "generated"    # off | generated | portable；缺省等同 generated

# 目标平台开关。enabled=false 完全跳过
[targets]
claude-code = { enabled = true,  convert = true }
codex       = { enabled = true,  convert = true }
cursor      = { enabled = false, convert = true }
copilot     = { enabled = false, convert = true }
windsurf    = { enabled = false, convert = true }
gemini      = { enabled = false, convert = true }
aider       = { enabled = false, convert = true }
cline       = { enabled = false, convert = true }
opencode    = { enabled = false, convert = true }

# 远端源（多源合并优先级：内置 < 默认 source < 后续 source；同名文件后者覆盖前者）
[sources.default]
url = "https://github.com/yourname/ai-standards.git"
branch = "main"
enabled = true
paths = ["standards/"]
auth = "ssh"               # ssh | https-token | none；none 仅 public

# 可选额外源
# [sources.team]
# url = "git@github.com:org/team-rules.git"
# branch = "main"
# enabled = true
# paths = ["rules/", "skills/"]

# 字段级别覆盖（per-target 高级覆盖，可选）
# [overrides.claude-code]
# inject = false

重要约束：toml 文件中所有顶层标量字段（version name inject dry_run 等） 必须放在第一个 [section]（如 [targets]）之前。一旦进入某个 [section]， 后续标量赋值会被解析为该 section 的子字段。 Save() 序列化时由 schema 字段顺序保证此约束。

字段语义

顶层

字段 类型 默认 说明
version string "1.0" 配置 schema 版本，stdagent 用于兼容判断
name string 项目目录名 标识用，写入备份/日志
inject bool true 全局 footer 注入开关
inject_whatis bool true footer 包含详细说明
inject_type_glossary bool false 在支持的 rendered rules 中注入类型速查
dry_run bool false 全局 dry-run
backup bool true sync 前备份
backup_keep int 5 备份保留份数
auto_pull bool true sync 自动 pull
verbose bool false 详细日志
gitignore string "generated" 如何维护根 .gitignore：off / generated / portable；空值归一为 generated

[targets]

每个 target 是一张 inline table：{ enabled = bool, convert = bool }。

字段 类型 默认 说明
enabled bool varies true 时参与 sync
convert bool true schema 兼容字段；当前 sync 始终执行 target transformer，应保持 true

合法 target 名与 frontmatter targets 对齐，以 internal/config/schema.go 的 ValidTargets 为准。

gitignore

init 与 sync 只改根 .gitignore 里 # BEGIN stdagent / # END stdagent 块，块外条目不动。已跟踪文件不会因为新增 pattern 被 untrack。sync 在 plan 校验之后、写扩散文件之前更新该块，因此同一次 sync 新建的产物就会被忽略。

值 行为
generated（默认） 忽略运行时文件 + 当前启用 target 的全部可重建产物
portable 同 generated，但保留公约集合 AGENTS.md 与 .agents/
off 不改 .gitignore；已有 managed 块也不会删除

三种模式都会忽略（off 除外）：.stdai/{cache,backups,logs}/、.stdai/state.json，以及各家官方本机文件（CLAUDE.local.md、AGENTS.local.md、AGENTS.override.md、.claude/settings.local.json、.kimi-code/local.toml、.qwen/QWEN.local.md）。

crush.json 与 kilo.jsonc 是用户配置合并目标，不会写入 gitignore。.github/ 与 .vscode/ 只忽略 stdagent 实际写出的子路径，不会整目录忽略。

[sources.<name>]

字段 类型 默认 说明
url string 必填 git URL（https / ssh）
branch string "main" 分支名
enabled bool true 关闭后该源跳过
paths string[] ["standards/"] 仓库内要 sync 的子路径
auth string "none" ssh / https-token / none
token_env string "" https-token 模式下读取的环境变量名

多源合并：按字典序遍历 sources，后者覆盖前者；本地手写 .stdai/standards/ 始终最高优先级（不会被远端覆盖）。

[overrides.<target>]

per-target 字段覆盖（可选高级用法）。允许的 keys 与顶层全局开关同名子集 （如 inject / inject_whatis）。

默认 enable 策略

stdagent init 生成的默认配置中：

  • claude-code codex 默认 enabled = true（覆盖 P0 场景）
  • 其他 Tier 1 target 默认 enabled = false，需用户显式开启
  • 全部 target 默认 convert = true

校验规则

stdagent 启动时执行：

  1. version 必须存在且 stdagent 已知（否则报 schema 升级提示）
  2. 每个 target 必须是合法 target 名
  3. inject_whatis 仅当 inject = true 时才生效，否则忽略并 warn
  4. [sources.X] 的 url 必填，paths 至少一项
  5. auth = "https-token" 时 token_env 必填且对应环境变量必须存在
  6. backup_keep ≥ 1
  7. gitignore 只能是 off / generated / portable；缺省或空字符串视为 generated

与环境变量的交互

环境变量 作用
STDAI_CONFIG 覆盖 .stdai/config.toml 路径
STDAI_DRY_RUN=1 等价 dry_run = true
STDAI_VERBOSE=1 等价 verbose = true
STDAI_NO_PULL=1 等价 auto_pull = false
STDAI_<TOKEN_ENV_NAME> 由 token_env 字段引用

CLI flag > 环境变量 > config.toml。

per-subdir 配置（v1.1）

monorepo 场景下，子目录可有自己的 .stdai/config.toml，仅影响子目录扩散。 v1.0 不支持，v1.1 引入。