pig/pig-farm-controller
1
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects Releases Wiki Activity

bmad初始化

Browse Source
This commit is contained in:
huang
2025-11-01 19:22:39 +08:00
parent 5b21dc0bd5
commit 426ae41f54
447 changed files with 80633 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

419
bmad/bmb/workflows/create-agent/agent-architecture.md Normal file
View File

@@ -0,0 +1,419 @@
# BMAD Agent Architecture Reference
_LLM-Optimized Technical Documentation for Agent Building_
## Core Agent Structure
### Minimal Valid Agent
```xml
<!-- Powered by BMAD-CORE™ -->
# Agent Name
<agent id="path/to/agent.md" name="Name" title="Title" icon="🤖">
<persona>
<role>My primary function</role>
<identity>My background and expertise</identity>
<communication_style>How I interact</communication_style>
<principles>My core beliefs and methodology</principles>
</persona>
<menu>
<item cmd="*help">Show numbered menu</item>
<item cmd="*exit">Exit with confirmation</item>
</menu>
</agent>
```
## Agent XML Schema
### Root Element: `<agent>`
**Required Attributes:**
- `id` - Unique path identifier (e.g., "bmad/bmm/agents/analyst.md")
- `name` - Agent's name (e.g., "Mary", "John", "Helper")
- `title` - Professional title (e.g., "Business Analyst", "Security Engineer")
- `icon` - Single emoji representing the agent
### Core Sections
#### 1. Persona Section (REQUIRED)
```xml
<persona>
<role>1-2 sentences: Professional title and primary expertise, use first-person voice</role>
<identity>2-5 sentences: Background, experience, specializations, use first-person voice</identity>
<communication_style>1-3 sentences: Interaction approach, tone, quirks, use first-person voice</communication_style>
<principles>2-5 sentences: Core beliefs, methodology, philosophy, use first-person voice</principles>
</persona>
```
**Best Practices:**
- Role: Be specific about expertise area
- Identity: Include experience indicators (years, depth)
- Communication: Describe HOW they interact, not just tone and quirks
- Principles: Start with "I believe" or "I operate" for first-person voice
#### 2. Critical Actions Section
```xml
<critical-actions>
<i>Load into memory {project-root}/bmad/{module}/config.yaml and set variables</i>
<i>Remember the users name is {user_name}</i>
<i>ALWAYS communicate in {communication_language}</i>
<!-- Custom initialization actions -->
</critical-actions>
```
**For Expert Agents with Sidecars (CRITICAL):**
```xml
<critical-actions>
<!-- CRITICAL: Load sidecar files FIRST -->
<i critical="MANDATORY">Load COMPLETE file {agent-folder}/instructions.md and follow ALL directives</i>
<i critical="MANDATORY">Load COMPLETE file {agent-folder}/memories.md into permanent context</i>
<i critical="MANDATORY">You MUST follow all rules in instructions.md on EVERY interaction</i>
<!-- Standard initialization -->
<i>Load into memory {project-root}/bmad/{module}/config.yaml and set variables</i>
<i>Remember the users name is {user_name}</i>
<i>ALWAYS communicate in {communication_language}</i>
<!-- Domain restrictions -->
<i>ONLY read/write files in {user-folder}/diary/ - NO OTHER FOLDERS</i>
</critical-actions>
```
**Common Patterns:**
- Config loading for module agents
- User context initialization
- Language preferences
- **Sidecar file loading (Expert agents) - MUST be explicit and CRITICAL**
- **Domain restrictions (Expert agents) - MUST be enforced**
#### 3. Menu Section (REQUIRED)
```xml
<menu>
<item cmd="*trigger" [attributes]>Description</item>
</menu>
```
**Command Attributes:**
- `run-workflow="{path}"` - Executes a workflow
- `exec="{path}"` - Executes a task
- `tmpl="{path}"` - Template reference
- `data="{path}"` - Data file reference
**Required Menu Items:**
- `*help` - Always first, shows command list
- `*exit` - Always last, exits agent
## Advanced Agent Patterns
### Activation Rules (OPTIONAL)
```xml
<activation critical="true">
<initialization critical="true" sequential="MANDATORY">
<step n="1">Load configuration</step>
<step n="2">Apply overrides</step>
<step n="3">Execute critical actions</step>
<step n="4" critical="BLOCKING">Show greeting with menu</step>
<step n="5" critical="BLOCKING">AWAIT user input</step>
</initialization>
<command-resolution critical="true">
<rule>Numeric input → Execute command at cmd_map[n]</rule>
<rule>Text input → Fuzzy match against commands</rule>
</command-resolution>
</activation>
```
### Expert Agent Sidecar Pattern
```xml
<!-- DO NOT use sidecar-resources tag - Instead use critical-actions -->
<!-- Sidecar files MUST be loaded explicitly in critical-actions -->
<!-- Example Expert Agent with Diary domain -->
<agent id="diary-keeper" name="Personal Assistant" title="Diary Keeper" icon="📔">
<critical-actions>
<!-- MANDATORY: Load all sidecar files -->
<i critical="MANDATORY">Load COMPLETE file {agent-folder}/diary-rules.md</i>
<i critical="MANDATORY">Load COMPLETE file {agent-folder}/user-memories.md</i>
<i critical="MANDATORY">Follow ALL rules from diary-rules.md</i>
<!-- Domain restriction -->
<i critical="MANDATORY">ONLY access files in {user-folder}/diary/</i>
<i critical="MANDATORY">NEVER access files outside diary folder</i>
</critical-actions>
<persona>...</persona>
<menu>...</menu>
</agent>
```
### Module Agent Integration
```xml
<module-integration>
<module-path>{project-root}/bmad/{module-code}</module-path>
<config-source>{module-path}/config.yaml</config-source>
<workflows-path>{project-root}/bmad/{module-code}/workflows</workflows-path>
</module-integration>
```
## Variable System
### System Variables
- `{project-root}` - Root directory of project
- `{user_name}` - User's name from config
- `{communication_language}` - Language preference
- `{date}` - Current date
- `{module}` - Current module code
### Config Variables
Format: `{config_source}:variable_name`
Example: `{config_source}:output_folder`
### Path Construction
```
Good: {project-root}/bmad/{module}/agents/
Bad: /absolute/path/to/agents/
Bad: ../../../relative/paths/
```
## Command Patterns
### Workflow Commands
```xml
<!-- Full path -->
<item cmd="*create-prd" run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
Create Product Requirements Document
</item>
<!-- Placeholder for future -->
<item cmd="*analyze" run-workflow="todo">
Perform analysis (workflow to be created)
</item>
```
### Task Commands
```xml
<item cmd="*validate" exec="{project-root}/bmad/core/tasks/validate-workflow.xml">
Validate document
</item>
```
### Template Commands
```xml
<item cmd="*brief"
exec="{project-root}/bmad/core/tasks/create-doc.md"
tmpl="{project-root}/bmad/bmm/templates/brief.md">
Create project brief
</item>
```
### Data-Driven Commands
```xml
<item cmd="*standup"
exec="{project-root}/bmad/bmm/tasks/daily-standup.xml"
data="{project-root}/bmad/_cfg/agent-manifest.csv">
Run daily standup
</item>
```
## Agent Type Specific Patterns
### Simple Agent
- Self-contained logic
- Minimal or no external dependencies
- May have embedded functions
- Good for utilities and converters
### Expert Agent
- Domain-specific with sidecar resources
- Restricted access patterns
- Memory/context files
- Good for specialized domains
### Module Agent
- Full integration with module
- Multiple workflows and tasks
- Config-driven behavior
- Good for professional tools
## Common Anti-Patterns to Avoid
### ❌ Bad Practices
```xml
<!-- Missing required persona elements -->
<persona>
<role>Helper</role>
<!-- Missing identity, style, principles -->
</persona>
<!-- Hard-coded paths -->
<item cmd="*run" exec="/Users/john/project/task.md">
<!-- No help command -->
<menu>
<item cmd="*do-something">Action</item>
<!-- Missing *help -->
</menu>
<!-- Duplicate command triggers -->
<item cmd="*analyze">First</item>
<item cmd="*analyze">Second</item>
```
### ✅ Good Practices
```xml
<!-- Complete persona -->
<persona>
<role>Data Analysis Expert</role>
<identity>Senior analyst with 10+ years...</identity>
<communication_style>Analytical and precise...</communication_style>
<principles>I believe in data-driven...</principles>
</persona>
<!-- Variable-based paths -->
<item cmd="*run" exec="{project-root}/bmad/module/task.md">
<!-- Required commands present -->
<menu>
<item cmd="*help">Show commands</item>
<item cmd="*analyze">Perform analysis</item>
<item cmd="*exit">Exit</item>
</menu>
```
## Agent Lifecycle
### 1. Initialization
1. Load agent file
2. Parse XML structure
3. Load critical-actions
4. Apply config overrides
5. Present greeting
### 2. Command Loop
1. Show numbered menu
2. Await user input
3. Resolve command
4. Execute action
5. Return to menu
### 3. Termination
1. User enters \*exit
2. Cleanup if needed
3. Exit persona
## Testing Checklist
Before deploying an agent:
- [ ] Valid XML structure
- [ ] All persona elements present
- [ ] *help and *exit commands exist
- [ ] All paths use variables
- [ ] No duplicate commands
- [ ] Config loading works
- [ ] Commands execute properly
## LLM Building Tips
When building agents:
1. Start with agent type (Simple/Expert/Module)
2. Define complete persona first
3. Add standard critical-actions
4. Include *help and *exit
5. Add domain commands
6. Test command execution
7. Validate with checklist
## Integration Points
### With Workflows
- Agents invoke workflows via run-workflow
- Workflows can be incomplete (marked "todo")
- Workflow paths must be valid or "todo"
**Workflow Interaction Styles** (BMAD v6 default):
- **Intent-based + Interactive**: Workflows adapt to user context and skill level
- Workflows collaborate with users, not just extract data
- See workflow-creation-guide.md "Instruction Styles" section for details
- When creating workflows for your agent, default to intent-based unless you need prescriptive control
### With Tasks
- Tasks are single operations
- Executed via exec attribute
- Can include data files
### With Templates
- Templates define document structure
- Used with create-doc task
- Variables passed through
## Quick Reference
### Minimal Commands
```xml
<menu>
<item cmd="*help">Show numbered cmd list</item>
<item cmd="*exit">Exit with confirmation</item>
</menu>
```
### Standard Critical Actions
```xml
<critical-actions>
<i>Load into memory {project-root}/bmad/{module}/config.yaml</i>
<i>Remember the users name is {user_name}</i>
<i>ALWAYS communicate in {communication_language}</i>
</critical-actions>
```
### Module Agent Pattern
```xml
<agent id="bmad/{module}/agents/{name}.md"
name="{Name}"
title="{Title}"
icon="{emoji}">
<persona>...</persona>
<critical-actions>...</critical-actions>
<menu>
<item cmd="*help">...</item>
<item cmd="*{command}" run-workflow="{path}">...</item>
<item cmd="*exit">...</item>
</menu>
</agent>
```