Agent Persona

代理人角色

立即切换AI代理行为。应用角色默认值和策略（严格执行可选）。

为AI编码代理定义可重用的指令配置文件。跨仓库共享它们，动态切换角色，并锁定代理可以做什么。与Claude、Codex、Gemini和OpenCode配合使用。

为什么使用这个？

快速开始

# Install
git clone https://github.com/GoodFarming/agent-persona.git
cd agent-persona && ./install.sh

# Launch Claude with the "blank" persona
agent-persona claude blank

# See what personas are available
agent-persona --list

# Check everything is working
agent-persona doctor

核心概念

什么是Persona？

角色是一个包含AI代理指令（和可选配置）的文件夹：

.personas/
  my-persona/
    AGENTS.md       # Instructions the agent sees (required)
    CLAUDE.md       # Claude-specific instructions (optional)
    GEMINI.md       # Gemini-specific instructions (optional)
    persona.json    # Defaults, MCP servers, policy (optional)

当你奔跑时 agent-persona claude my-persona，启动器：

1. 找到你的角色
2. 将指令叠加到目标文件上(CLAUDE.md)
3. 注入任何MCP服务器和默认值
4. 启动Claude并配置所有内容

叠加是如何工作的

┌─────────────────────────────────────────────────────────────────┐
│                         agent-persona                           │
├─────────────────────────────────────────────────────────────────┤
│  1. Find persona (repo → home → system)                         │
│  2. Merge repo-wide meta instructions                           │
│  3. Expand include directives                                   │
│  4. Inject MCP servers from persona.json                        │
│  5. Translate policy to tool-specific flags                     │
│  6. If `--strict-policy`, filter user args that conflict        │
│  7. Overlay composed file onto working directory                │
│  8. Launch tool with: defaults + policy + user_args             │
└─────────────────────────────────────────────────────────────────┘

• 正常模式：用户参数覆盖策略。
• 严格模式(--strict-policy)：policy覆盖用户参数。

在Linux上：使用绑定挂载方式 unshare --你的实际 AGENTS.md 永远不会被修改。

别处：交换文件，运行工具，退出时恢复。如果发生碰撞，请运行 agent-persona recover.

______________________________________________________________________

创建人物角色

选项1：复制本地人物

最适合与您的仓库一起使用的项目特定说明：

cd your-project
agent-persona init                     # Creates .personas/ scaffold
mkdir .personas/dev
cat > .personas/dev/AGENTS.md  ~/.personas/reviewer/AGENTS.md 

## Additional Guidelines
...

模板变量

使用 {{persona}} 在共享块或元文件中引用当前角色名称：

# .personas/.shared/planning-rules.md

## Planning
Save your plans to `.persona/{{persona}}/PLAN.md`.
Update `.persona/{{persona}}/SPEC.md` with requirements.

当扩展为人物角色时 dev-agent，这变成了：

## Planning
Save your plans to `.persona/dev-agent/PLAN.md`.
Update `.persona/dev-agent/SPEC.md` with requirements.

无法识别 {{...}} 模式会发出警告，但不会阻止执行。

继承其他角色

# Extended Persona

## My Additions
...

撰写政策片段

persona.json 支持还包括：

{
  "include": [
    { "file": "policy-base.json" },
    { "persona": "secure-base" }
  ],
  "policy": {
    "tools": {
      "deny": ["task"]
    }
  }
}

包括加法合并。冲突（例如，允许和拒绝的工具相同）会导致错误。

______________________________________________________________________

回购范围元指令

添加适用于的上下文 全部 repo中的人物角色：

# .personas/.shared/meta.AGENTS.md

## Project Context
This is a TypeScript monorepo using pnpm workspaces.

## Conventions
- Use vitest for tests
- Run `pnpm lint` before committing

## Off-Limits
- Don't modify `packages/legacy/`

Meta被合并在每个角色的顶部（或底部） --meta-position=bottom).

由创建的模板 agent-persona init 是 在编辑之前忽略它.

______________________________________________________________________

MCP服务器注入

在中定义MCP服务器 persona.json 并且它们是自动配置的：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-filesystem"],
      "env": { "ALLOWED_PATHS": "/home/user/projects" }
    },
    "database": {
      "command": "mcp-postgres",
      "args": ["--connection-string", "postgres://..."]
    }
  }
}

• 克劳德：生成温度 --mcp-config JSON 文件
• 法典：排放 -c mcp_servers.*=... 覆盖
• 禁用 --no-mcp 或 AGENT_PERSONA_MCP=0

______________________________________________________________________

默认值和覆盖

每个工具默认值

{
  "defaults": {
    "*": ["--verbose"],
    "codex": ["--model", "o3"],
    "claude": ["--model", "sonnet"]
  }
}

全局默认值(*)先申请；工具特定的默认值附加在后面。

内置默认值

除非策略存在，否则代理角色会添加合理的默认值：

• 法典: --full-auto （自动批准安全操作）
• 克劳德: --permission-mode bypassPermissions （跳过提示）

当存在策略时，这些将被抑制（策略控制权限）。

用户Args总是赢

# persona.json: "claude": ["--model", "opus"]
agent-persona claude my-persona --model sonnet
# Result: only --model sonnet is passed

禁用默认值

agent-persona claude my-persona --no-defaults

______________________________________________________________________

Persona探索

决议顺序（第一场比赛获胜）：

1. Repo本地: .personas// 在当前目录或父目录中
2. 额外路径: AGENT_PERSONA_PATHS 环境变量（以冒号分隔）
3. 家: ~/.personas//
4. 用户: ~/.local/share/agent-persona/.personas//
5. 系统: /usr/local/share/agent-persona/.personas//

agent-persona which my-persona  # Show where persona resolves from

集 AGENT_PERSONA_PREFER_REPO=0 在repo之前检查home/user。

______________________________________________________________________

命令

刀具垫片

Symlinks允许您跳过指定工具：

claude-persona my-agent    # same as: agent-persona claude my-agent
codex-persona my-agent
gemini-persona my-agent
opencode-persona my-agent

______________________________________________________________________

旗帜

______________________________________________________________________

环境变量

输入（配置代理角色）

输出（导出到工具流程）

适用于钩子、脚本、内存和日志记录：

______________________________________________________________________

用例

任务特定代理

agent-persona claude researcher  # Deep research, thorough exploration
agent-persona codex fixer        # Quick fixes, minimal changes
agent-persona claude reviewer    # Code review, security focus

安全沙盒开发

{
  "policy": {
    "tools": { "allow": ["bash", "read", "edit", "write", "glob", "grep"] },
    "paths": { "allow": ["./src", "./tests"] },
    "network": { "deny": ["*"] }
  }
}

多工具工作流

相同的角色，不同的工具：

agent-persona codex architect   # Planning with Codex
agent-persona claude architect  # Implementation with Claude

团队标准

通过点文件或团队仓库共享角色：

export AGENT_PERSONA_PATHS="$HOME/team-personas:$AGENT_PERSONA_PATHS"

根据项目MCP配置

// frontend/.personas/dev/persona.json
{
  "mcpServers": {
    "browser": { "command": "mcp-browser-tools" }
  }
}

// backend/.personas/dev/persona.json
{
  "mcpServers": {
    "postgres": { "command": "mcp-postgres", "args": ["--local"] }
  }
}

______________________________________________________________________

覆盖安全

如果会话在交换模式下意外终止（SIGKILL、崩溃、断电）：

agent-persona recover  # Restores from backup
agent-persona doctor   # Shows any orphaned backups

______________________________________________________________________

安装

看 安装.md 详细说明。

git clone https://github.com/GoodFarming/agent-persona.git
cd agent-persona && ./install.sh
agent-persona doctor

需求

• Linux （在Ubuntu上测试，应该适用于大多数发行版）
• Bash 4.0+ （策略功能需要）
• Python 3 （策略执行、persona.json解析、包括扩展所需）
• 一个或多个AI工具： codex, claude, gemini, opencode

卸载

./uninstall.sh
# or manually:
rm -f ~/.local/bin/agent-persona ~/.local/bin/*-persona
rm -rf ~/.local/share/agent-persona

______________________________________________________________________

测试

# Core functionality
bash tests/smoke.sh

# CLI argument/env translation (no model calls)
bash tests/integration-cli-parse.sh

# Real CLI tests (requires credentials, may incur cost)
AGENT_PERSONA_RUN_REAL_TESTS=1 bash tests/integration-real.sh

有关完整的测试选项和手动测试程序，请参阅 tests/MANUAL-TESTS.md.

______________________________________________________________________

支持的工具

______________________________________________________________________

贡献

欢迎在 .

许可证

麻省理工学院