std-agent 类型速查

本项目的 AI 配置由 stdagent 管理，分为 5 种类型：

rules - 自动加载的编码 / 操作规范。AI 在 session 开始就遵守。
skills - 按需触发的能力包（遵循 Agent Skills 标准）。AI 看到 description 匹配用户意图时主动调用。
commands - 用户输入 /command-name 触发的模板。AI 不主动调用。
references - 背景参考资料。AI 仅在需要时查阅，不自动加载。
subagents - 隔离子代理定义。AI 通过 spawn 子进程或 CLI 调用执行。

源文件在 .stdai/standards/<type>/<name>.md。用 stdagent which <file> 查文件触发的规则集。用 stdagent explain 查类型详细语义。

std-agent

stdagent 是一个轻量纯 Go CLI 工具：把项目的 AI 配置维护在单一 .stdai/ 目录里，再扩散到 23 个 AI CLI 工具的原生格式（CLAUDE.md / AGENTS.md / .cursor/rules/ / .windsurf/rules/ 等）。本仓库是它的源码仓，同时用 stdagent 管理自己的 AI 助手规则（自举）。

模块结构

cmd/stdagent/                程序入口
internal/
├── cli/                     cobra 命令注册（init / pull / sync / status / clean / budget / intro / upgrade / version / fix）
├── config/                  config.toml 加载
├── parser/                  .md 源文件 + frontmatter 解析
├── source/                  本地 + git 源采集 + .stdaiignore
├── transformer/             23 个 target 各自的转换实现
├── writer/                  原子写盘 + plan + backup
├── runner/                  Sync 编排器
├── state/                   state.json 持久化
├── budget/                  字符/字节预算检查
└── util/                    通用工具
docs/                        spec / architecture / 各 target 调研

技术栈

Go 1.26（mise + go + golangci-lint + gofumpt + git-cliff）
spf13/cobra（CLI 框架）
BurntSushi/toml（config 解析）
goccy/go-yaml（frontmatter 解析）
bmatcuk/doublestar（glob 匹配）
goreleaser（发版）

铁律

已推送分支禁止改写历史。所有 amend / rebase / reset --hard + force-push 行为只允许在本人独占的 WIP 分支。修补已推送的 commit 用追加新 commit + fast-forward push。
改 transformer / runner / writer 必带 _test.go。新增 target 至少要有 plan + 关键 fanout 测试，破坏性变更要补充防回归用例。
frontmatter / target 字段不要乱删改，参考 docs/conversion-rules.md 和 docs/format-spec.md 的字段映射矩阵，每条改动都可能影响 23 个 target。
AI 配置维护流程：所有规则源在 .stdai/standards/。改了规则一定要跑 stdagent sync 让产物刷新（CLAUDE.md / AGENTS.md / .claude/rules/ 等），sync 默认会 prune 上次写过但本次不再产出的孤儿文件。
不要手改 stdagent 生成的根文件（CLAUDE.md / AGENTS.md 等）；改源 .stdai/standards/root.md 或具体 rule 后跑 sync。

维护流程

# 修改 AI 规则（项目说明 / 铁律 / 开发流程）
$EDITOR .stdai/standards/root.md
$EDITOR .stdai/standards/rules/<rule-name>.md
go run ./cmd/stdagent sync           # 用 in-tree 版本验证
go run ./cmd/stdagent status         # 查 drift

# 日常开发
mise run check                       # fmt + lint + test 一键
mise run build                       # 产 bin/stdagent

# 发版（patch / minor）
git tag v0.0.X
git push --tags                      # 触发 goreleaser

Reference Rules

下列条目由 stdagent 同步到 .qwen/rules/，AI 按 description / applyTo 判断是否相关后用 Read 工具读取具体内容：

.qwen/rules/commit-style.md -- Conventional Commits 1.0.0 风格
.qwen/rules/no-history-rewrite.md -- 已推送分支禁止改写历史
.qwen/rules/test-requirements.md -- 改 transformer / runner / writer / parser 必带 _test.go 防回归 (applyTo: internal/transformer/**/*.go, internal/runner/**/*.go, internal/writer/**/*.go, internal/parser/**/*.go)

FilesExpand file tree

QWEN.md

Latest commit

History