std-agent

# std-agent  [](https://github.com/StringKe/std-agent/releases) [](https://go.dev/) [](https://goreportcard.com/report/github.com/StringKe/std-agent) [](LICENSE) [](https://github.com/StringKe/std-agent/actions/workflows/ci.yml) **English** | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Русский](README.ru.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Español](README.es.md) | [Português](README.pt-BR.md) --- `stdagent` 是一个轻量级、纯 Go 的命令行工具，它将一个 `.stdai/` 目录作为项目 AI 配置的单一来源，然后将其扩展到 **22 个 AI CLI 工具**，并处理它们原生文件格式、前端语法和特殊功能。 停止手动维护 `CLAUDE.md`、`AGENTS.md`、`GEMINI.md`、`.cursor/rules/`、`.windsurf/rules/`、`.clinerules/`、`.github/copilot-instructions.md` 等文件。通过一次编辑，实现所有目标的同步。 ## 为什么选择 std-agent？ - **单一来源** — 在 YAML 前端 + Markdown 中编写 `rules` / `skills` / `commands` / `references` / `subagents`，仅需一次。 - **二十两个目标** — 支持 Claude Code、Codex、Cursor、GitHub Copilot、Windsurf/Devin、Gemini CLI、Aider、Cline、OpenCode、Roo Code、Crush、Amp、Warp、Factory、Continue.dev、Antigravity、Qwen Code、Pi、Kilo Code、Augment Code、Jules、Grok Build。 - **精确规范** — 每个输出路径、前端语法和大小限制都根据工具的官方文档进行验证（最近一次完整审计：2026-07）。 - **零锁定** — 写入者仅需关注一个小型白名单路径；每次同步前都会备份；`clean` 命令可逆转所有更改。 - **漂移检测** — `status` 显示文件修改时间；`fix` 重新应用源。 - **MCP** — 单个 `.stdai/standards/mcp.json` 扩展到 `.mcp.json` / `.cursor/mcp.json` / `.vscode/mcp.json`。 - **Monorepo 感知** — 配置查找从 `cwd` 开始；支持从任何子目录工作。 - **自我升级** — `stdagent upgrade` 从 GitHub Releases 拉取签名版本，并进行 sha256 验证和原子替换。 ## 支持的工具 ### 一级（14） | 目标 | 主要输出 | |---|---| | Claude Code (Anthropic) | `CLAUDE.md` + `.claude/{rules,skills,commands,agents}/` + `.mcp.json` | | Codex (OpenAI) | `AGENTS.md` + `.agents/skills/` + `.codex/agents/*.toml`（原生子代理） | | Cursor | `.cursor/{rules/*.mdc,skills,commands,agents}/` + `.cursor/mcp.json` | | GitHub Copilot | `.github/{copilot-instructions,instructions,prompts,agents,skills}/` + `.vscode/mcp.json` | | Windsurf / Devin (Cognition) | `.windsurf/{rules,skills,workflows}/` + `.devin/rules/` 镜像 | | Gemini CLI (Google) | `GEMINI.md` + `.gemini/skills/` + `.gemini/commands/*.toml` | | Aider | 重用 `AGENTS.md`（无操作） | | Cline | `.clinerules/`（100/500/900 数字前缀） | | OpenCode | `.opencode/{skills,commands}/` | | Roo Code | `.roo/{rules,skills,commands}/` | | Crush (Charmbracelet) | `CRUSH.md` + `.crush/skills/` + `crush.json` 技能注册 | | Amp (Sourcegraph) | `AGENTS.md`（内联） + `.agents/skills/` | | Warp | `AGENTS.md`（内联 + 嵌套） + `.agents/skills/` | | Factory (Factory.ai) | `.factory/{rules,skills,commands,droids}/` | ### 二级（8） | 目标 | 主要输出 | |---|---| | Continue.dev | `.continue/{rules,skills,prompts}/` + 嵌套 `rules.md` | | Antigravity (Google) | `.agents/{rules,skills,workflows}/` | | Qwen Code (Alibaba) | `QWEN.md` + `.qwen/{rules,skills,commands}/` | | Pi | `.pi/skills/` + `.pi/prompts/` | | Kilo Code (kilo.ai) | `.kilo/{rules,skills,command}/` + `kilo.jsonc` 指令注册 | | Augment Code | `.augment/{rules,skills}/` | | Jules (Google) | `AGENTS.md` | | Grok Build (xAI) | `AGENTS.md` + `.grok/skills/` | 每个集成都在 [docs/targets/](docs/targets/) 下有文档。 ## 快速开始 ```bash # 安装（macOS / Linux） curl -fsSL https://raw.githubusercontent.com/StringKe/std-agent/main/install.sh | sh # 安装（Windows PowerShell） irm https://raw.githubusercontent.com/StringKe/std-agent/main/install.ps1 | iex # 在项目中初始化 cd your-project stdagent init # 编辑 .stdai/standards/rules/example.md，然后同步到所有启用的目标 stdagent sync # 检查 / 修复漂移 stdagent status stdagent fix ``` ## 将现有项目迁移到 std-agent 项目已经散布着 `CLAUDE.md` / `AGENTS.md` / `.cursor/rules/` / `.clinerules/` / `.github/copilot-instructions.md`？将下面的提示粘贴到 Claude Code / Codex / Cursor / Gemini CLI 中，它将为您重新组织所有内容到 `.stdai/standards/` 中。 ````text 帮助我将这个项目从分散的 AI 配置迁移到 std-agent。请执行： 1. 使用 Glob / Read 扫描所有现有的 AI 规则文件： - 根目录：CLAUDE.md AGENTS.md GEMINI.md .cursorrules .windsurfrules .clinerules - 子目录：.claude/rules/ .claude/skills/ .claude/commands/ .claude/agents/ .cursor/rules/ .windsurf/rules/ .clinerules/ .continue/rules/ .github/copilot-instructions.md .github/instructions/ .rulesync/rules/ .codex/AGENTS.md - 仓库内嵌套 CLAUDE.md（查找 . -name CLAUDE.md -not -path './.stdai/*'） 2. 报告库存：X 条规则 / Y 个技能 / Z 个命令 / N 个嵌套 CLAUDE.md， 并标记哪些文件包含“项目概述”内容。 3. 提出一个分割计划，等待我的批准，然后编写文件： - 项目概述（定义 / 堆栈 / 铁规则 / 维护流程） -> .stdai/standards/root.md - 每个聚焦规则 -> .stdai/standards/rules/<kebab-name>.md - 技能包 -> .stdai/standards/skills/<name>/SKILL.md（带有脚本/引用/子目录） - 斜杠命令 -> .stdai/standards/commands/<name>.md - 嵌套 CLAUDE.md -> .stdai/standards/nested/<relative-path>/root.md - 每个文件都添加一个前端：type / name / description / priority / applyTo 4. 不“重构”原始内容。保留每个可执行命令、API 端点、 错误字符串、文件路径、行号。允许的“优化”：删除填充词、 合并重复项、分割超大文件、重命名过时的工具名称。 5. 完成后，告诉我运行 `stdagent sync` 并删除遗留工件 （.rulesync/、.cursorrules 单个文件等）。不要删除 stdagent 自己生成的文件（CLAUDE.md / AGENTS.md / .claude/rules/）。 完整的规范（前端字段表、root.md 模板、嵌套布局、rulesync 映射） 在 `stdagent intro` 命令输出中。 ```` 也可以直接输送到 LLM CLI： ```bash stdagent intro | pbcopy # macOS: 粘贴到 AI 聊天 stdagent intro --json # 用于代理 / 自动化集成 ``` ## 命令 | 命令 | 目的 | |---|---| | `stdagent init` | 初始化 `.stdai/` + `config.toml` + `.stdaiignore` + 示例标准 | | `stdagent pull` | 更新 `.stdai/cache/` 中缓存的 git 源 | | `stdagent sync` | 核心：拉取 → 解析 → 转换 → 扩展 | | `stdagent fix` | 重新同步以修复漂移（`sync` 的别名） | | `stdagent status` | 每个目标的漂移 + 最后一次同步时间 | | `stdagent clean` | 删除生成的文件（保留 `.stdai/`） | | `stdagent budget` | LLM 上下文预算检查（字符 + token 估计） | | `stdagent which <path>` | 列出适用于文件的规则 / 引用（按需上下文路由到 AI） | | `stdagent explain` | 打印 std-agent 5 种类型语义（规则/技能/命令/引用/子代理）供 AI 使用 | | `stdagent intro` | 为 LLM 打印迁移提示，以转换现有配置 | | `stdagent upgrade` | 从 GitHub Releases 自我升级（sha256 + 原子替换） | | `stdagent version` | 构建信息 | 每个命令都支持 `--help`。完整的参考资料：[docs/commands.md](docs/commands.md)。 ## 基于协议的架构 v0.0.4 引入了三层转换器架构：每个目标的 `Plan()` 都委托给 6 个协议之一（AgentsMD / ClaudeMD / Cursor / Clinerules / WindsurfStyle / Copilot），由 `protocol.Adapter` 结构体字面量参数化。添加新工具现在只需 ~25-35 行代码，而不是 145 行（60-70% 代码重复）。 温和降级：当目标原生不支持 std-agent 类型（例如 everywhere 中的引用，amp / windsurf 中的子代理）时，stdagent 降级到子目录隔离路径（`<FallbackDir>/references/<name>.md`）带有前端 `std-agent-type: <type>` + HTML 注释解释，无 std-agent 私有前缀。 ## 源格式 完整的模式位于 [docs/spec.md](docs/spec.md) 第 1 部分。最小形状： ```markdown --- type: rules # rules | skills | commands | references name: coding-style description: General coding style priority: high # high | normal | low targets: [claude-code, codex] # opt-in（或使用 exclude_targets 退出） applyTo: ["**/*.go"] alwaysApply: false --- # Coding Style Always use meaningful variable names... ``` MCP 服务器（`.stdai/standards/mcp.json`）： ```json { "version": "1.0", "servers": { "github": { "type": "stdio", "command": "gh", "args": ["api"] }, "linear": { "type": "http", "url": "https://mcp.linear.app/sse" } } } ``` ## 配置 `.stdai/config.toml`： ```toml version = "1.0" inject = true # 在输出中注入“Generated by stdagent”页脚 inject_whatis = true # 在技能中添加一行来源注释 auto_pull = true # 每次同步时拉取 git 源 backup = true backup_keep = 5 [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 } continue-dev = { enabled = false, convert = true } antigravity = { enabled = false, convert = true } [sources.default] url = "https://github.com/your-org/ai-standards.git" branch = "main" enabled = true paths = ["standards/"] ``` 完整参考资料：[docs/config-spec.md](docs/config-spec.md)。 ## 项目布局 ``` your-project/ ├── .stdai/ 内部管理区域（单一真实来源） │ ├── config.toml 一个配置文件 │ ├── standards/ 作者根目录 │ │ ├── rules/ │ │ ├── skills/ │ │ ├── commands/ │ │ ├── references/ │ │ └── mcp.json MCP 服务器（可选） │ ├── cache/ git 源缓存 │ ├── backups/ 自动快照（每次同步前） │ └── state.json 运行时状态 ├── .stdaiignore gitignore 样式的 glob 模式，用于排除源文件 ├── CLAUDE.md 扩展输出：Claude Code ├── AGENTS.md 扩展输出：Codex / Cursor 备用 / Copilot 代理 / OpenCode / Antigravity ├── GEMINI.md 扩展输出：Gemini CLI ├── .mcp.json MCP 用于 Claude └── .claude/ .codex/ .cursor/ .github/ .windsurf/ .gemini/ .clinerules/ .opencode/ .continue/ .agents/ ``` 详情：[docs/file-structure.md](docs/file-structure.md)。 ## Monorepo 支持 当省略 `--config` 时，`stdagent` 从 `cwd` 开始向上查找最近的 `.stdai/config.toml`。从任何子目录运行它，它将自动定位 monorepo 根目录。 ## 开发 ```bash # 工具链（mise + go + golangci-lint + gofumpt + git-cliff） mise install # 常见任务 mise run fmt # gofumpt + goimports mise run lint # golangci-lint mise run test # go test -race -cover mise run check # fmt + lint + test 一步到位 mise run build # 生成 bin/stdagent mise run run # go run ./cmd/stdagent ``` ## 文档 - **[docs/spec.md](docs/spec.md)** — 完整规范：std-agent 标准 + 22 个工具差异 + 转换策略 - [docs/prd.md](docs/prd.md) — 产品需求 - [docs/architecture.md](docs/architecture.md) — 模块布局 + 数据流 - [docs/commands.md](docs/commands.md) — CLI 命令参考 - [docs/conversion-rules.md](docs/conversion-rules.md) — 转换矩阵 + 前端映射 - [docs/format-spec.md](docs/format-spec.md) — 前端模式详情 - [docs/file-structure.md](docs/file-structure.md) — 目录约定 - [docs/roadmap.md](docs/roadmap.md) — 路线图 - [docs/targets/](docs/targets/) — 每个工具的研究笔记 ## 许可证 MIT — 见 [LICENSE](LICENSE)。