charlie (Henriquemoody)

Charlie-通用代理配置生成器

在YAML/Markdown中定义一次。生成特定于代理的命令、MCP配置和规则。

Charlie是一个通用的代理配置生成器，它从单个YAML/Markdown规范中生成特定于代理的命令、MCP配置和规则。

  

特性

• ✨ 单一定义：在YAML或Markdown中写入一次设置
• 🤖 多代理支持：为不同的AI代理生成（支持Claude、Cursor、GitHub Copilot和OpenCode）
• ⚙️ Slash命令集成：从单个定义生成斜线命令。
• 🔌 MCP集成：使用工具模式生成MCP服务器配置
• 📋 规则生成：创建具有手动保存功能的特定于代理的规则文件
• 🕵️ 子代理支持：定义一次专门的AI子助理
• 🧠 技能支持：将领域知识打包为可重用的技能代理自动调用
• 🎯 自动检测：自动查找 charlie.yaml 或 .charlie/ 目录
• ⚡ 运行时定位：选择在运行时为哪些代理生成
• 📦 库和CLI：用作CLI工具或作为Python库导入
• 🔗 配置继承：从外部Git存储库扩展配置

快速开始

安装

通过pip安装

pip install charlie-agents

使用Docker

Charlie可以作为Docker镜像使用，因此您不需要安装Python依赖项：

# Pull the image from GitHub Container Registry
docker pull ghcr.io/henriquemoody/charlie:latest

# Run charlie commands (mount your project directory)
docker run --rm -v $(pwd):/workspace ghcr.io/henriquemoody/charlie list-agents

# Generate configuration
docker run --rm -v $(pwd):/workspace ghcr.io/henriquemoody/charlie generate claude

为方便起见，请创建别名：

添加到您的 .bashrc 或 .zshrc:

alias charlie='docker run --rm -v $(pwd):/workspace ghcr.io/henriquemoody/charlie'

然后像使用本机CLI一样使用它：

charlie generate claude
charlie validate
charlie list-agents

配置

对于高级功能，Charlie支持两种配置方法：

1. 整体的 -单个YAML文件（适用于小型项目）
2. 基于目录 -模块化文件 .charlie/ 目录（适用于大型项目）

单片配置

对于高级功能，请创建 charlie.yaml 在您的项目中：

version: "1.0" # Optional: Schema version (defaults to "1.0")

extends: # Optional: Define it when you want to extend another repository's configuration
  - git@github.com:MyOrg/team-config.git#v1.0

project:
  name: "My project" # Optional: Inferred from directory name if omitted
  namespace: "my" # Optional: Used to prefix commands, rules, and MCP servers.

variables:
  mcp_api_token: ~ # It will ask the user to provide an API token, if the environment variable is not set

# Command definitions
commands:
  - name: "commit"
    description: "Analyze changes and create a high-quality git commit"
    prompt: "Check what changed, and commit your changes. The body of the message explains WHY it changed"

  - name: "command-handler"
    description: "Creates a command handler"
    prompt: "Create a command handler using src/examples/handler.py as an reference"

# MCP server definitions
mcp_servers:
  - name: "local_server"
    type: "stdio"
    command: "node"
    args: ["server.js"]
    env:
      KEY: "value"

  - name: "remote_server"
    url: "https://example.com/mcp"
    headers:
      Authorization: "Bearer {{var:mcp_api_token}}"
      Content-Type: "application/json"

# Rules configuration (rules)
rules:
  - description: "Commit message standards"
    prompt: "Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)"

  - description: "Coding standards"
    prompt: "All code should follow PEP 8"

# Subagent definitions (optional)
subagents:
  - name: "code-reviewer"
    description: "Expert code reviewer. Use proactively after code changes."
    prompt: |
      You are a senior code reviewer. When invoked:
      1. Run git diff to see recent changes
      2. Review for quality, security, and best practices
      3. Provide feedback organized by priority
    metadata:
      tools: "Read, Grep, Glob, Bash"
      model: sonnet

# Skill definitions (optional)
skills:
  - name: "explain-code"
    description: "Explains code with visual diagrams and analogies. Use when explaining how code works."
    prompt: |
      When explaining code, always include:
      1. An analogy from everyday life
      2. An ASCII diagram showing the flow
      3. A step-by-step walkthrough
      4. A common gotcha or misconception

  - name: "deploy"
    description: "Deploy the application to production"
    prompt: |
      Deploy the application:
      1. Run the test suite
      2. Build the application
      3. Push to the deployment target
      4. Verify the deployment succeeded
    metadata:
      disable-model-invocation: true

# Ignore patterns (optional) -- will be added to agent-specific ignore files
ignore_patterns:
  - "*.log"
  - "tmp/"
  - "node_modules/"

查理也会读 charlie.dist.yaml除非你有 charlie.yaml 在目录中。

看 examples/ 完整示例目录：

• examples/simple/ -基本配置
• examples/speckit/ -受规范套件启发的配置

配置继承(extends)

Charlie支持从外部Git仓库继承配置。这允许您在多个项目或组织之间共享通用配置：

extends:
  - https://github.com/MyOrg/shared-agent-config
  - git@github.com:MyOrg/team-config.git#v1.0

# Local commands, rules, etc. will be merged with extended configs
commands:
  - name: "local-command"
    description: "A project-specific command"
    prompt: "Do something specific to this project"

它是如何工作的：

1. Charlie在 extends 列表（按顺序）
2. 配置按顺序合并——后面的条目会覆盖前面的条目
3. 您的本地配置最后合并，具有最高优先级
4. 重复项（命令、规则、MCP服务器、变量）将被警告覆盖

当检测到重复项时，Charlie会显示警告：

⚠ Overwriting command 'init' from https://github.com/MyOrg/shared-config
⚠ Overwriting rule 'coding-standards' from https://github.com/MyOrg/shared-config

版本/分支支持：

使用URL片段指定分支或标记：

• https://github.com/Org/Config#main -使用 main 分支
• https://github.com/Org/Config#v1.0.0 -使用 v1.0.0 标签
• git@github.com:Org/Config.git#feature-branch -使用特定分支

基于目录的配置

为了更好地组织和协作，请使用基于目录的方法。这 charlie.yaml 文件是 可选的 -如果你只有一个 .charlie/ 目录，Charlie将从目录中推断出项目名称：

project/
├── charlie.yaml                  # Optional: Project metadata (name inferred if omitted)
├── .charlieignore                # Optional: Patterns to exclude from AI agents
└── .charlie/
    ├── commands/
    │   ├── init.yaml             # One file per command (Markdown or YAML supported)
    │   └── deploy.md
    ├── rules/
    │   ├── commit-messages.yaml  # One file per rule (Markdown or YAML supported)
    │   └── code-style.md
    ├── agents/
    │   ├── code-reviewer.md      # One file per subagent (Markdown with YAML frontmatter)
    │   └── debugger.md
    ├── skills/
    │   ├── explain-code.md       # Flat file skill (Markdown with YAML frontmatter)
    │   └── deploy/               # Directory-based skill
    │       ├── SKILL.md          # Skill definition (required)
    │       ├── deploy.sh         # Companion files (copied to output)
    │       └── templates/
    │           └── config.yaml
    └── mcp-servers/
        └── local-tools.yaml      # MCP servers in YAML

看 examples/directory-based/ 举一个完整的例子。

优点：

• 清晰的组织（每个命令/规则一个文件）
• 单个文件上没有合并冲突
• 易于添加/删除组件
• 更适合版本控制差异
• 对丰富文档的原生markdown支持

生成特定于代理的配置

# Generate configuration files for a specific agent (generates commands, MCP, and rules by default)
charlie generate claude

占位符

Charlie在命令、规则和MCP配置中支持这些通用占位符：

项目负责人：

• {{project_dir}} → 解析到项目根目录
• {{project_name}} → 替换为项目名称（例如。， My Project)
• {{project_namespace}} → 替换为项目名称空间（例如。， my)

代理人持股人：

• {{agent_name}} → 替换为代理人的全名（例如。， Claude Code, Cursor)
• {{agent_shortname}} → 替换为代理的短标识符（例如。， claude, cursor)
• {{agent_dir}} → 解析到代理的基本目录（例如。， .claude, .cursor)
• {{commands_shorthand_injection}} → 代理特定命令简写（例如。， $ARGUMENTS 支持的代理）

代理路径占位符：

• {{commands_dir}} → 解析到代理的命令目录（例如。， .claude/skills, .cursor/commands)
• {{rules_dir}} → 解析到代理的规则目录（例如。， .claude/rules/)
• {{rules_file}} → 解析到代理的规则文件路径（例如。， CLAUDE.md, .cursor/rules)
• {{subagents_dir}} → 解析到代理的子代理目录（例如。， .claude/agents)
• {{skills_dir}} → 解析到代理的技能目录（例如。， .claude/skills)
• {{mcp_file}} → 解析为代理的MCP配置文件名（例如。， mcp.json)
• {{assets_dir}} → 解析到代理的资产目录（例如。， .claude/assets)

可变占位符：

• {{var:VARIABLE_NAME}} → 替换为在您的 charlie.yaml

- 变量可以在 variables: 部分 - 使用 ~ 如果未设置为环境变量，则作为提示用户输入的值 - 例子： {{var:mcp_api_token}} - 若变量未设置，Charlie将提示用户输入。

环境变量占位符：

• {{env:VAR_NAME}} → 替换为环境变量的值

- 来自系统环境的负载或 .env 根目录中的文件 - 提高 EnvironmentVariableNotFoundError 如果变量不存在 - 系统环境变量优先于 .env 文件

自定义替换：

• 可以使用以下命令或规则定义自定义占位符 replacements 领域
• 有关示例，请参见库API部分

这些占位符用于命令、规则和MCP服务器配置（命令、参数、URL和标头字段）。

用法

CLI命令

charlie generate

设置特定于代理的配置（默认情况下生成命令、MCP配置和规则）：

# Auto-detect charlie.yaml (generates all artifacts)
charlie generate claude

# Setup without MCP config
charlie generate cursor --no-mcp

# Setup without rules (rules)
charlie generate claude --no-rules

# Setup without commands
charlie generate claude --no-commands

# Setup without subagents
charlie generate claude --no-subagents

# Setup without skills
charlie generate claude --no-skills

# Explicit config file
charlie generate cursor --config my-config.yaml

# Custom output directory
charlie generate cursor --output ./build

charlie validate

验证YAML配置：

# Auto-detect charlie.yaml
charlie validate

# Specific file
charlie validate my-config.yaml

charlie list-agents

列出所有支持的AI代理：

charlie list-agents

charlie info

显示有关代理的详细信息：

charlie info claude
charlie info cursor

库API

在Python中以编程方式使用Charlie：

from charlie import AgentRegistry, AgentConfiguratorFactory, Tracker
from charlie.schema import Project, Command, Rule, Skill, Subagent, HttpMCPServer, StdioMCPServer, ValueReplacement
from charlie.enums import RuleMode

# Initialize registry and get agent
registry = AgentRegistry()
agent = registry.get("claude")

# Create project configuration
project = Project(
    name="My Project",
    namespace="my",
    dir="/path/to/project",
)

# Create configurator
configurator = AgentConfiguratorFactory.create(
    agent=agent,
    project=project,
    tracker=Tracker()
)

# Generate commands
configurator.commands([
    Command(
        name="commit",
        description="Analyze changes and create a high-quality git commit",
        prompt="Check what changed, and commit your changes. The body of the message explains WHY it changed",
        metadata={
            "allowed-tools": "Bash(git add:*), Bash(git status:*), Bash(git commit:*)"
        },
        replacements={}
    ),
    Command(
        name="deploy",
        description="Deploy the application",
        prompt="Run {{script}}",
        metadata={},
        replacements={
            "script": ValueReplacement(
                type="value",
                value=".claude/assets/deploy.sh"
            )
        }
    )
])

# Generate MCP configuration
configurator.mcp_servers([
    HttpMCPServer(
        name="my-http-server",
        type="http",
        url="https://example.com/mcp",
        headers={
            "Authorization": "Bearer F8417EA8-94F3-447C-A108-B0AD7E428BE6",
            "Content-Type": "application/json"
        },
    ),
    StdioMCPServer(
        name="my-stdio-server",
        type="stdio",
        command="node",
        args=["server.js"],
        env={
            "API_TOKEN": "84EBB71B-0FF8-49D8-84C8-55FF9550CA2C"
        },
    ),
])

# Generate rules (rules)
configurator.rules(
    [
        Rule(
            name="commit-messages",
            description="Commit message standards",
            prompt="Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)",
            metadata={
                "alwaysApply": True,
            },
            replacements={}
        ),
        Rule(
            name="coding-standards",
            description="Coding standards",
            prompt="All code should follow {{standard}}",
            metadata={},
            replacements={
                "standard": ValueReplacement(
                    type="value",
                    value="PEP 8"
                )
            }
        )
    ],
    RuleMode.MERGED
)

# Generate subagents
configurator.subagents([
    Subagent(
        name="code-reviewer",
        description="Expert code reviewer. Use proactively after code changes.",
        prompt="You are a senior code reviewer. Analyze code for quality, security, and best practices.",
        metadata={
            "tools": "Read, Grep, Glob, Bash",
            "model": "sonnet",
        },
    )
])

# Generate skills
configurator.skills([
    Skill(
        name="explain-code",
        description="Explains code with visual diagrams and analogies. Use when explaining how code works.",
        prompt="When explaining code, always include an analogy, an ASCII diagram, and a step-by-step walkthrough.",
    ),
    Skill(
        name="deploy",
        description="Deploy the application to production",
        prompt="Deploy the application: run tests, build, push, verify.",
        metadata={
            "disable-model-invocation": True,
            "allowed-tools": "Bash(./deploy.sh)",
        },
    ),
])

# Copy assets to the agent's directory
configurator.assets([
    ".charlie/assets/deploy.sh",
])

支持的代理

Charlie目前支持以下AI代理：

• 克劳德代码 (claude)Claude的AI编码助手
• 光标 (cursor)-AI驱动的代码编辑器
• GitHub Copilot (copilot)GitHub的AI结对程序员
• 开源代码 (opencode)-开源AI编码代理

跑 charlie list-agents 查看所有可用的代理。

注： 克劳德代码已经 将自定义命令合并为技能Charlie生成Claude命令如下 .claude/skills/{name}/SKILL.md （格式与技能相同）。OpenCode还将命令视为技能，将其生成为 .opencode/skills/{name}/SKILL.md。对于Cursor，命令仍按以下方式生成 .cursor/commands/{name}.md.

元数据支持

查理使用 传递元数据 -将任何特定于代理的元数据添加到您的命令或规则中，Charlie将在生成的输出中包含它们：

Charlie提取这些字段并将其包含在特定于代理的输出中（Markdown代理的YAML frontmatter，TOML代理的TOML字段）。看 AGENT_FIELDS.md 有关哪些代理支持哪些字段的详细信息。

规则生成模式

规则（Rules）可以通过两种方式生成：

合并模式 （默认）-包含所有部分的单个文件：

charlie generate cursor --rules-mode merged

分离模式 -每节一个文件：

charlie generate cursor --rules-mode separate

对于简单的项目使用合并模式，对于复杂的项目使用单独模式进行更好的组织。

子代理

Subgents是专门处理特定类型任务的AI子助手。Charlie允许您定义它们一次，并为每个支持的工具生成相应的文件。

定义子代理

基于目录 --创建 .charlie/agents/.md:

---
description: Expert code reviewer. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. When invoked:

1. Run git diff to see recent changes
2. Review for quality, security, and best practices
3. Provide feedback organized by priority: Critical / Warnings / Suggestions

文件名成为子代理名称（例如。， code-reviewer.md → code-reviewer).用a覆盖它 name: 前线的田野。

YAML内联 --添加a subagents: 部分到 charlie.yaml:

subagents:
  - name: code-reviewer
    description: Expert code reviewer. Use proactively after code changes.
    prompt: |
      You are a senior code reviewer...
    metadata:
      tools: "Read, Grep, Glob, Bash"
      model: sonnet

生成的输出

看 AGENT_FIELDS.md 以获取完整的元数据字段参考。

命名空间支持

当一 namespace 如果已设置，子代理文件名将作为前缀：

• 克劳德： .claude/agents/myapp-code-reviewer.md
• 光标： .cursor/agents/myapp.code-reviewer.md

技能

技能是可移植的、版本控制的包，它教代理如何执行特定于域的任务。与命令（用户显式调用）不同，当与对话相关时，代理可以自动加载技能。

定义技能

Charlie支持三种定义技能的方法：

平面文件 --创建 .charlie/skills/.md:

---
description: Explains code with visual diagrams and analogies. Use when explaining how code works.
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

文件名变为技能名称（例如。， explain-code.md → explain-code).用a覆盖它 name: 前线的田野。

基于目录 --创建 .charlie/skills//SKILL.md:

.charlie/skills/deploy/
├── SKILL.md              # Skill definition (required)
├── deploy.sh             # Companion files (copied to output)
└── templates/
    └── config.yaml

---
description: Deploy the application to production
disable-model-invocation: true
---

Deploy the application:

1. Run the test suite
2. Build using the template at `{{skills_dir}}/deploy/templates/config.yaml`
3. Execute `{{skills_dir}}/deploy/deploy.sh`
4. Verify the deployment succeeded

目录名称变为技能名称（例如。， deploy/ → deploy).旁边的任何文件 SKILL.md 自动复制到输出技能目录，保留相对路径结构。这使得技能可以捆绑代理可以在运行时访问的脚本、模板或参考资料。

YAML内联 --添加a skills: 部分到 charlie.yaml:

skills:
  - name: explain-code
    description: Explains code with visual diagrams and analogies. Use when explaining how code works.
    prompt: |
      When explaining code, always include an analogy, an ASCII diagram, and a step-by-step walkthrough.
  - name: deploy
    description: Deploy the application to production
    prompt: |
      Deploy the application:
      1. Run the test suite
      2. Build the application
      3. Push to the deployment target
    metadata:
      disable-model-invocation: true

平面技能和基于目录的技能可以共存 .charlie/skills/ 文件夹。

生成的输出

每个技能都会输出为一个目录，其中包含 SKILL.md 文件，遵循 代理技能 开放标准。基于目录的技能中的伴随文件会一起复制 SKILL.md 在输出中。

命名空间支持

当一 namespace 已设置，技能目录名称前缀为：

• 克劳德： .claude/skills/myapp-explain-code/SKILL.md
• 光标： .cursor/skills/myapp.explain-code/SKILL.md

调用控制

使用 disable-model-invocation: true 在元数据中，防止代理自动加载技能，这对于具有副作用（部署、提交等）的工作流非常有用，您可以手动触发这些副作用 /skill-name.

发展

使用开发容器（可选）

使用以下命令在VS Code中打开项目 开发容器扩展:

1. 在VS Code中打开项目
2. 按 F1 然后选择“开发容器：在容器中重新打开”
3. 等待容器构建（仅限第一次）
4. 使用预先配置的所有工具（pytest、mypy、ruff）开始编码

Dev容器提供了一个一致的开发环境，其中预装了所有依赖项和VS代码扩展。

开发人员命令

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest # or `make test`

# Run with coverage
pytest --cov=charlie # or `make test-coverage`

# Run ruff
ruff check . # or `make lint` (`make format` to format the code)

# Run mypy
mypy --install-types --non-interactive src/charlie # or `make analyze`

贡献

欢迎投稿！关键领域：

• 添加对新AI代理的支持
• 改进文件
• 添加更多示例
• Bug修复和测试

许可证

麻省理工学院

致谢

Charlie的灵感来自于需要在多个AI代理之间保持一致的命令定义 规格套件 项目。