### Setup Development Environment

Source: https://github.com/kweaver-ai/dolphin/blob/main/README.md

Installs and configures the necessary dependencies for development.

```bash
make dev-setup
```

--------------------------------

### Configuration File Example

Source: https://github.com/kweaver-ai/dolphin/blob/main/README.zh-CN.md

Example YAML structure for advanced model and cloud configuration.

```yaml
clouds:
  openai:
    api: "https://api.openai.com/v1/chat/completions"
    api_key: "sk-your-actual-key"  # ← 替换这里

llms:
  default:  # 自定义配置名（不是模型名）
    cloud: "openai"
    model_name: "gpt-4o"  # 实际的 OpenAI 模型名
    temperature: 0.0
```

--------------------------------

### Install Dolphin SDK

Source: https://context7.com/kweaver-ai/dolphin/llms.txt

Methods for setting up the development environment or installing the package.

```bash
# Clone and setup with automated installation
git clone https://github.com/kweaver-ai/dolphin.git
cd dolphin
make dev-setup

# Or manual installation with pip
pip install -e ".[dev]"

# Or using uv package manager
uv sync --all-groups
```

--------------------------------

### Installation Commands

Source: https://github.com/kweaver-ai/dolphin/blob/main/README.zh-CN.md

Methods for installing the Dolphin SDK using automated or manual approaches.

```bash
git clone https://github.com/kweaver-ai/dolphin.git
cd dolphin
make dev-setup
```

```bash
# 安装依赖
uv sync --all-groups

# 或使用 pip 以可编辑模式安装
pip install -e ".[dev]"
```

```bash
make build-only
# 或者
uv run python -m build
```

--------------------------------

### Chat with Agent Example

Source: https://github.com/kweaver-ai/dolphin/blob/main/bin/README.md

Starts a continuous conversation with an agent. Use --system-prompt for custom instructions or --max-turns to limit conversation length.

```bash
dolphin chat --agent chatbot --folder ./agents
```

```bash
dolphin chat --agent my_agent --folder ./agents --system-prompt "You are a data analyst"
```

```bash
dolphin chat --agent my_agent --folder ./agents --max-turns 10
```

--------------------------------

### End-to-End Automation with /explore/

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/usage/quick_start/quickstart.md

Use the /explore/ block to define a goal, and Dolphin will determine the steps. This example creates a daily briefing by getting the date, calculating time until year-end and next Friday, generating a quote, and writing it to a markdown file.

```dolphin
/explore/(
    tools=[_date, _python, _write_file]
) 
Create a personalized daily briefing for me:

1. Get today's date
2. Calculate: days until end of year, days until next Friday
3. Generate a motivational quote
4. Write everything to a file called 'daily_briefing.md'

Format the file nicely with markdown.
-> result
```

--------------------------------

### Install Dolphin with Development Dependencies

Source: https://github.com/kweaver-ai/dolphin/blob/main/README.md

Use this command to clone the repository and set up the development environment, including installing all dependencies with uv.

```bash
git clone https://github.com/kweaver-ai/dolphin.git
cd dolphin
make dev-setup
```

--------------------------------

### Setup Configuration

Source: https://github.com/kweaver-ai/dolphin/blob/main/examples/README.md

Steps to initialize the configuration file from the provided template.

```bash
# Copy template to create your configuration
cp examples/deepsearch/config/global.template.yaml examples/deepsearch/config/global.yaml

# Edit with your API keys and preferences
vim examples/deepsearch/config/global.yaml
```

--------------------------------

### Run Chat BI Example Script

Source: https://github.com/kweaver-ai/dolphin/blob/main/README.md

Executes the Chat BI example script. Ensure the script is executable.

```bash
./examples/bin/chatbi.sh
```

--------------------------------

### Install Dolphin with uv

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/usage/quick_start/installation.md

Use this method for a faster installation process. It sets up and synchronizes all dependency groups within a virtual environment.

```bash
git clone https://github.com/kweaver-ai/dolphin.git
cd dolphin

# Create and sync ".venv/" with all dependency groups
make dev-setup

# Verify
make test
```

--------------------------------

### Example Configuration for OpenAI

Source: https://github.com/kweaver-ai/dolphin/blob/main/README.md

An example YAML configuration snippet showing how to set up the OpenAI cloud, API endpoint, API key, and default model.

```yaml
clouds:
  openai:
    api: "https://api.openai.com/v1/chat/completions"
    api_key: "sk-your-actual-key"  # ← Replace this

llms:
  default:  # Custom config name (not a model name)
    cloud: "openai"
    model_name: "gpt-4o"  # Actual OpenAI model
    temperature: 0.0
```

--------------------------------

### Quick Start Execution

Source: https://github.com/kweaver-ai/dolphin/blob/main/README.zh-CN.md

Running an initial data analysis task using the CLI.

```bash
# 1. 创建示例数据文件
echo "name,age,city
Alice,30,New York
Bob,25,San Francisco
Charlie,35,Los Angeles" > /tmp/test_data.csv

# 2. 运行您的第一个分析
dolphin run --agent tabular_analyst \
  --folder ./examples/tabular_analyst \
  --query "/tmp/test_data.csv"
```

--------------------------------

### Run Deep Search Example Script

Source: https://github.com/kweaver-ai/dolphin/blob/main/README.md

Executes the deep search example script. Ensure the script is executable.

```bash
./examples/bin/deepsearch.sh
```

--------------------------------

### Install Dolphin Dependencies Manually

Source: https://github.com/kweaver-ai/dolphin/blob/main/README.md

Manually install dependencies using uv or pip. The uv sync command installs all groups, while pip install -e "'.[dev]'" installs in editable mode with development dependencies.

```bash
# Install dependencies
uv sync --all-groups

# Or using pip in editable mode
pip install -e ".[dev]"
```

--------------------------------

### Install Rich for Enhanced Visualization

Source: https://github.com/kweaver-ai/dolphin/blob/main/tools/README.md

Install the 'rich' library to improve the visualization of agent trajectories with colored output and better formatting. This is an optional step.

```bash
# Optional: install rich for better visualization
pip install rich
```

--------------------------------

### File System Directory Structure Example

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/design/context/long_term_memory_design.md

An example illustrating a user-isolated file system directory structure for storing memory data, including versioned knowledge files.

```shell
data/memory/
├── user_alice123/
│   ├── versions/
│   │   ├── 20231027100000/
│   │   │   └── knowledge.jsonl
│   │   └── 20231028120000/
│   │       └── knowledge.jsonl
│   └── latest.txt (内容: "20231028120000")
├── user_bob456/
│   ├── versions/
│   │   └── 20231027140000/
│   │       └── knowledge.jsonl
│   └── latest.txt (内容: "20231027140000")
└── user_charlie789/
    ├── versions/
    └── latest.txt
```

--------------------------------

### Install MCP Python SDK

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/design/skill/mcp_integration_design.md

Command to install the official MCP Python SDK. Ensure you have pip installed and a version greater than or equal to 1.0.0.

```bash
# 安装官方 MCP Python SDK
pip install "mcp>=1.0.0"
```

--------------------------------

### SKILL.md Frontmatter Example

Source: https://github.com/kweaver-ai/dolphin/blob/main/tests/fixtures/skills/anthropic/skill-creator.md

Example of the required YAML frontmatter for a SKILL.md file. The 'name' and 'description' fields are crucial for Claude to determine when to use the skill.

```yaml
name: skill-creator
description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
license: Complete terms in LICENSE.txt
```

--------------------------------

### CLI Parameter Examples

Source: https://github.com/kweaver-ai/dolphin/blob/main/README.zh-CN.md

Commonly used flags for running, debugging, and interacting with agents.

```bash
# 基础运行
dolphin run --agent my_agent --folder ./agents --query "你的查询"

# 详细输出
dolphin run --agent my_agent --folder ./agents -v --query "任务"

# 调试级别日志
dolphin run --agent my_agent --folder ./agents -vv --query "调试"

# 调试模式（设置断点）
dolphin debug --agent my_agent --folder ./agents --break-at 3 --break-at 7

# 交互对话（限制轮数）
dolphin chat --agent my_agent --folder ./agents --max-turns 10

# 查看版本
dolphin --version

# 查看帮助
dolphin --help
dolphin run --help
dolphin debug --help
dolphin chat --help
```

--------------------------------

### Quick Start Commands

Source: https://github.com/kweaver-ai/dolphin/blob/main/bin/README.md

Basic commands to quickly run, debug, or chat with an agent using the Dolphin CLI.

```bash
dolphin run --agent my_agent --folder ./agents --query "your query"
```

```bash
dolphin debug --agent my_agent --folder ./agents
```

```bash
dolphin chat --agent my_agent --folder ./agents
```

--------------------------------

### Basic 'Hello, World!' Agent

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/usage/quick_start/quickstart.md

A simple Dolphin agent that outputs 'Hello, World!'. This is useful for testing installation.

```dolphin
"Hello, World!" -> message
```

--------------------------------

### Debug Agent Example

Source: https://github.com/kweaver-ai/dolphin/blob/main/bin/README.md

Launches an interactive debugger for an agent. Use --break-on-start to pause at the beginning or --break-at N for specific breakpoints.

```bash
dolphin debug --agent my_agent --folder ./agents --break-on-start
```

```bash
dolphin debug --agent my_agent --folder ./agents --break-at 3 --break-at 7
```

```bash
dolphin debug --agent my_agent --folder ./agents --snapshot-on-pause
```

```bash
dolphin debug --agent my_agent --folder ./agents --commands ./debug_commands.txt
```

--------------------------------

### Delta Mode Streaming Implementation

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/usage/guides/dolphin-agent-integration.md

Complete example demonstrating how to consume streaming output using delta mode for both initial runs and multi-turn chat.

```python
async def stream_with_delta():
    """Complete example using delta mode"""

    # First execution
    print("User: Hello\nAI: ", end="", flush=True)
    async for result in agent.arun(query="Hello", stream_mode="delta"):
        if "_progress" in result:
            for prog in result["_progress"]:
                if prog.get("stage") == "llm":
                    delta = prog.get("delta", "")
                    print(delta, end="", flush=True)
    print()

    # Multi-turn chat
    print("User: Continue\nAI: ", end="", flush=True)
    async for result in agent.continue_chat(message="Continue", stream_mode="delta"):
        if "_progress" in result:
            for prog in result["_progress"]:
                if prog.get("stage") == "llm":
                    delta = prog.get("delta", "")
                    print(delta, end="", flush=True)
    print()
```

--------------------------------

### Run First Dolphin Analysis

Source: https://github.com/kweaver-ai/dolphin/blob/main/README.md

Execute your first analysis using the Dolphin CLI. This example creates a sample CSV file and then runs the tabular_analyst agent to analyze it.

```bash
# 1. Create a sample data file
echo "name,age,city
Alice,30,New York
Bob,25,San Francisco
Charlie,35,Los Angeles" > /tmp/test_data.csv

# 2. Run your first analysis
dolphin run --agent tabular_analyst \
  --folder ./examples/tabular_analyst \
  --query "/tmp/test_data.csv"
```

--------------------------------

### Run Agent Example

Source: https://github.com/kweaver-ai/dolphin/blob/main/bin/README.md

Executes an agent for a specific query. Use --dry-run to validate configuration without execution.

```bash
dolphin run --agent faq_extract --folder ./examples/dolphins --query "Extract FAQ"
```

```bash
dolphin run --agent my_agent --folder ./agents --query "task" --timeout 300
```

```bash
dolphin run --agent my_agent --folder ./agents --dry-run
```

```bash
dolphin run --agent my_agent --folder ./agents -i
```

--------------------------------

### Resource Skill Directory Structure

Source: https://github.com/kweaver-ai/dolphin/blob/main/examples/README.md

The file layout for the resource_skill example project.

```text
resource_skill/
├── bin/
│   └── skill_guided_coding.sh   # Convenience launch script
├── config/
│   ├── global.yaml              # Configuration (create from template)
│   └── global.template.yaml     # Configuration template
├── skill_guided_assistant.dph   # Main skill-guided agent
└── skills/                      # Self-contained skills directory
    ├── brainstorming/
    │   └── SKILL.md             # Brainstorming methodology
    └── cto-advisor/
        └── SKILL.md             # CTO advisory framework
```

--------------------------------

### Analyze Technical Debt

Source: https://github.com/kweaver-ai/dolphin/blob/main/examples/resource_skill/skills/cto-advisor/SKILL.md

Run this script to analyze system architecture and get a prioritized plan for debt reduction.

```bash
python scripts/tech_debt_analyzer.py
```

--------------------------------

### Multi-layer System Diagnostic Script

Source: https://github.com/kweaver-ai/dolphin/blob/main/tests/fixtures/skills/superpowers/systematic-debugging.md

A bash script example for tracing environment variables and signing states across different layers of a build process.

```bash
# Layer 1: Workflow
echo "=== Secrets available in workflow: ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"

# Layer 2: Build script
echo "=== Env vars in build script: ==="
env | grep IDENTITY || echo "IDENTITY not in environment"

# Layer 3: Signing script
echo "=== Keychain state: ==="
security list-keychains
security find-identity -v

# Layer 4: Actual signing
codesign --sign "$IDENTITY" --verbose=4 "$APP"
```

--------------------------------

### Get Dolphin Version

Source: https://github.com/kweaver-ai/dolphin/blob/main/bin/README.md

Displays the installed version of the Dolphin CLI. This is useful for checking compatibility or reporting issues.

```bash
dolphin --version
```

--------------------------------

### Initialize Project Directory

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/usage/quick_start/quickstart.md

Create the necessary folder structure for agents and configuration files.

```bash
mkdir -p my_agents config
```

--------------------------------

### Start Dolphin Chat

Source: https://github.com/kweaver-ai/dolphin/blob/main/bin/README.md

Initiates a chat session with a specified agent, providing an initial message to guide the conversation. Ensure the agent and its folder are correctly specified.

```bash
dolphin chat --agent my_agent --folder ./agents --init-message "Analyze recent sales data"
```

--------------------------------

### Quick Start: Initialize and Assemble Context

Source: https://github.com/kweaver-ai/dolphin/blob/main/src/dolphin/core/context_engineer/README.md

Demonstrates initializing ContextEngineer components, configuring buckets, defining content sections, allocating budget based on scores, and assembling the final context for an LLM. Ensure all necessary components are imported before use.

```python
from context_engineer import BudgetManager, ContextAssembler, TokenizerService, Compressor
from context_engineer.config.settings import get_default_config

# Load default configuration
config = get_default_config()

# Initialize components
tokenizer = TokenizerService()
budget_manager = BudgetManager(tokenizer)
compressor = Compressor(tokenizer)
assembler = ContextAssembler(tokenizer, compressor)

# Configure buckets from config
budget_manager.configure_buckets(config.buckets)

# Define content sections
content_sections = {
    "system": "You are a helpful AI assistant.",
    "task": "Help the user with their question.",
    "history": "Previous conversation about weather patterns.",
    "rag": "Retrieved information about current weather conditions."
}

# Allocate budget
allocations = budget_manager.allocate_budget(
    model_context_limit=8000,
    output_budget=1200,
    content_scores={"system": 1.0, "task": 0.9, "history": 0.6, "rag": 0.8}
)

# Assemble context
result = assembler.assemble_context(
    content_sections=content_sections,
    budget_allocations=allocations,
    placement_policy=config.get_default_policy().placement,
    bucket_configs=config.buckets
)

print(f"Assembled context: {result.total_tokens} tokens")
print(f"Sections: {[s.name for s in result.sections]}")
```

--------------------------------

### Debug Logging for Tool Call Detection and Execution

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/design/core/multiple-tool-calls.md

Provides example debug log messages for detecting multiple tool calls, indicating the start of execution for each tool call, and confirming completion with response length.

```python
# 检测到多个 tool calls
logger.debug(
    f"explore[{self.output_var}] detected {len(tool_calls)} tool calls: "
    f"{ [tc.name for tc in tool_calls]}"
)

# 开始执行
logger.debug(f"Executing tool call {i+1}/{len(tool_calls)}: {tool_call.name}")

# 执行完成
logger.debug(
    f"Tool call {tool_call.name} completed, "
    f"response length: {len(response)}"
)
```

--------------------------------

### Configure Agent Initialization

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/usage/guides/dolphin-agent-integration.zh-CN.md

Demonstrates the recommended lazy-loading initialization versus the traditional explicit initialization.

```python
agent = DolphinAgent(...)
# ✅ 无需显式初始化，首次执行时自动初始化
async for result in agent.arun(...):
    ...
```

```python
agent = DolphinAgent(...)
await agent.initialize()  # 显式初始化
async for result in agent.arun(...):
    ...
```

--------------------------------

### Python SDK: Basic Agent Execution

Source: https://context7.com/kweaver-ai/dolphin/llms.txt

Demonstrates how to load configuration, initialize global skills, and create/execute a DolphinAgent from a file or content string using the Python SDK. Includes streaming output.

```python
import asyncio
from dolphin.sdk.agent.dolphin_agent import DolphinAgent
from dolphin.core.config.global_config import GlobalConfig
from dolphin.sdk.skill.global_skills import GlobalSkills
from dolphin.core import flags

# Disable EXPLORE_BLOCK_V2 for multi-turn chat support
flags.set_flag(flags.EXPLORE_BLOCK_V2, False)

async def main():
    # Load configuration
    config = GlobalConfig.from_yaml("config/global.yaml")
    skills = GlobalSkills(config)

    # Create agent from file
    agent = DolphinAgent(
        name="my_agent",
        file_path="path/to/agent.dph",
        global_config=config,
        global_skills=skills,
        variables={"model_name": "gpt-4o"}
    )

    # Or create agent from content string
    agent = DolphinAgent(
        name="inline_agent",
        content="@print('Hello, Dolphin!') -> result",
        global_config=config,
        global_skills=skills
    )

    # Execute with streaming output (lazy initialization, no explicit init needed)
    print("AI: ", end="", flush=True)
    async for result in agent.arun(query="Hello", stream_mode="delta"):
        if "_progress" in result:
            for prog in result["_progress"]:
                if prog.get("stage") == "llm":
                    delta = prog.get("delta", "")
                    if delta:
                        print(delta, end="", flush=True)
    print()

asyncio.run(main())
```

--------------------------------

### Start Coroutine Execution

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/design/architecture/coroutine_execution_design.md

Initializes the DolphinExecutor and starts the execution of a coroutine script, printing the resulting frame ID.

```python
from DolphinLanguageSDK.dolphin_language import DolphinExecutor

executor = DolphinExecutor()

# Dolphin脚本
content = """
/assign/ result: \"Hello World\"
/assign/ count: 42
"""

# 启动协程执行
frame = await executor.start_coroutine(content)
print(f"Frame ID: {frame.frame_id}")
```

--------------------------------

### Quick Checklist - v2.0+ Recommended Configuration

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/usage/guides/dolphin-agent-integration.md

A checklist for recommended configurations when using DolphinAgent v2.0+.

```APIDOC
## Quick Checklist - v2.0+ Recommended Configuration

- [ ] Disabled `EXPLORE_BLOCK_V2` flag (required for multi-turn chat)
- [ ] First request uses `arun()`
- [ ] Subsequent requests use `continue_chat()` (don't use deprecated `achat`)
- [ ] Use `stream_mode="delta"` for automatic delta calculation (recommended)
- [ ] Leverage lazy loading, no need to explicitly call `initialize()`
- [ ] Handle tool call events
- [ ] Add error handling and logging
```

--------------------------------

### Install Playwright MCP Server

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/design/skill/mcp_integration_design.md

Commands to install the Playwright browser automation tool and its MCP server component. This is an optional step.

```bash
# 安装 MCP 服务器（可选）
npm install -g @playwright/mcp  # Playwright 浏览器自动化
npx playwright install
```

--------------------------------

### Initialize and Execute DolphinAgent

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/usage/guides/dolphin-agent-integration.md

Demonstrates loading configuration, initializing the agent, and performing both initial execution and multi-turn chat using streaming deltas.

```python
import asyncio
from dolphin.sdk.agent.dolphin_agent import DolphinAgent
from dolphin.core.config.global_config import GlobalConfig
from dolphin.sdk.skill.global_skills import GlobalSkills
from dolphin.core import flags

# Disable EXPLORE_BLOCK_V2 (required for multi-turn chat)
flags.set_flag(flags.EXPLORE_BLOCK_V2, False)

async def main():
    # 1. Load configuration
    config = GlobalConfig.from_yaml("config/dolphin.yaml")
    skills = GlobalSkills(config)

    # 2. Create Agent
    agent = DolphinAgent(
        name="my_agent",
        file_path="path/to/agent.dph",
        global_config=config,
        global_skills=skills,
        variables={"model_name": "qwen-plus"}
    )

    # 3. Initialization happens automatically (lazy loading, no need to call initialize())

    # 4. First execution - use arun
    print("AI: ", end="", flush=True)

    async for result in agent.arun(query="Hello", stream_mode="delta"):
        # stream_mode="delta" lets the framework calculate deltas automatically
        if "_progress" in result:
            for prog in result["_progress"]:
                if prog.get("stage") == "llm":
                    delta = prog.get("delta", "")  # Use delta directly!
                    if delta:
                        print(delta, end="", flush=True)

    print()  # Newline

    # 5. Multi-turn chat - use continue_chat (recommended) or achat (deprecated)
    print("AI: ", end="", flush=True)

    async for result in agent.continue_chat(message="Continue chatting", stream_mode="delta"):
        # continue_chat returns the same format as arun!
        if "_progress" in result:
            for prog in result["_progress"]:
                if prog.get("stage") == "llm":
                    delta = prog.get("delta", "")
                    if delta:
                        print(delta, end="", flush=True)

    print()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Database Verification Agent Example

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/design/core/verify-proposal.md

An example of a verifier agent written in DPH that uses the `executeSQL` tool to verify data written to a database.

```dph
# verifier.dph - 数据库验证
@DESC
验证智能体：检查数据是否正确写入数据库
@DESC

$_hook_context.answer -> result
$datasources -> ds

# ✅ 需要 executeSQL 工具
@executeSQL($ds, "SELECT COUNT(*) FROM orders WHERE status='completed'") -> count

/if/ $count.value == $result.expected_count:
    {"score": 1.0, "passed": true, "feedback": "数据验证通过"} -> output
else:
    {"score": 0.0, "passed": false, "feedback": "数据不匹配"} -> output
/end/
```

--------------------------------

### Install Dolphin with pip and venv

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/usage/quick_start/installation.md

This option uses standard Python virtual environments and pip for installation. Ensure you have Python 3.11 or a compatible version.

```bash
git clone https://github.com/kweaver-ai/dolphin.git
cd dolphin

# Create a clean venv under "env/"
python3.11 -m venv env/quick_start
source env/quick_start/bin/activate

# Install Dolphin (editable) + CLI dependencies
pip install -e ".[cli]"

# Verify
dolphin --version
dolphin --help
```

--------------------------------

### Plan vs. Search Skillkit Comparison

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/design/core/plan-support-architecture.md

Compares the Plan Skillkit to the Search Skillkit, highlighting their similar roles as toolkits that extend Agent capabilities. Both involve a set of tools, inject capabilities via context, store state in context, and utilize the ExploreBlock.

```text
Explore 提供什么？
├── ReAct 循环 (Think → Act → Observe)
├── Tool 调用机制
├── 中断处理 (check_user_interrupt)
├── 消息管理 (Context buckets)
└── Trace 记录 (Recorder)

Task orchestration needs what?
├── 任务编排工具 (_plan_tasks, _check_progress, ...)
├── 任务状态存储 (TaskRegistry)
├── 子任务执行 (复用 ExploreBlock)
└── 上下文隔离 (COW Context)

结论：Plan = Explore + PlanSkillkit + Context 状态扩展
```

```text
| 方面                 | Search Skillkit                      | Plan Skillkit                                 |
| -------------------- | ------------------------------------ | --------------------------------------------- |
| **本质**       | 一组工具（_search, _summarize, ...） | 一组工具（_plan_tasks, _check_progress, ...） |
| **能力**       | 赋予 Agent 搜索能力                  | 赋予 Agent 任务编排能力                       |
| **注入方式**   | context.add_skillkit(SearchSkillkit) | context.add_skillkit(PlanSkillkit)            |
| **状态存储**   | 搜索结果缓存在 Context               | 任务状态存储在 Context.task_registry          |
| **Block 类型** | 使用 ExploreBlock                    | 使用 ExploreBlock                             |
```

--------------------------------

### Initialize p5.js Canvas

Source: https://github.com/kweaver-ai/dolphin/blob/main/tests/fixtures/skills/anthropic/algorithmic-art.md

Standard boilerplate for setting up the p5.js environment and the main execution loop.

```javascript
function setup() {
  createCanvas(1200, 1200);
  // Initialize your system
}

function draw() {
  // Your generative algorithm
  // Can be static (noLoop) or animated
}
```

--------------------------------

### Intelligent Data Analysis Workflow Example

Source: https://github.com/kweaver-ai/dolphin/blob/main/README.md

Example of defining an agent for data analysis using Dolphin Language. Requires 'query' variable and 'sql_query' tool.

```dph
# Data analysis example
AGENT data_analyst:
  PROMPT analyze_data:
    Please analyze the following dataset: {{query}}
    
  TOOL sql_query:
    Query relevant data from database
    
  JUDGE validate_results:
    Check the reasonability of analysis results
```

--------------------------------

### External API Verification Agent Example

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/design/core/verify-proposal.md

An example of a verifier agent that calls an external API to fetch a standard answer and then uses an LLM to compare it with the provided answer.

```dph
# verifier.dph - 外部 API 验证
@DESC
验证智能体：调用标准答案 API 比较结果
@DESC

$_hook_context.answer -> answer

# 调用外部 API 获取标准答案
@_http_get("https://api.example.com/standard-answer?q=$question") -> standard

# 使用 LLM 比对相似度
/explore/(
    model="v3-mini",
    output="json"
)
请比对以下两个答案的相似度，返回 0-1 的分数：

答案A：【$answer】
答案B：【$standard.answer】

请返回 JSON 格式：{"similarity": 分数}
-> result

{
    "score": $result.answer.similarity,
    "passed": $result.answer.similarity > 0.8
} -> output
```

--------------------------------

### GET _get_task_output

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/design/core/plan-support-architecture.md

Retrieves the output of a specific completed subtask.

```APIDOC
## GET _get_task_output

### Description
Fetches the output of a completed task by its ID.

### Method
GET

### Endpoint
_get_task_output

### Parameters
#### Query Parameters
- **task_id** (string) - Required - The unique identifier of the task.

### Response
#### Success Response (200)
- **output** (string) - The answer or output content of the completed task.
```

--------------------------------

### Environment Configuration

Source: https://github.com/kweaver-ai/dolphin/blob/main/README.zh-CN.md

Setting up API credentials via environment variables or configuration files.

```bash
# 设置您的 OpenAI API 密钥
export OPENAI_API_KEY="sk-your-key-here"

# 或添加到 shell 配置文件以持久化
echo 'export OPENAI_API_KEY="sk-your-key-here"' >> ~/.bashrc  # 或 ~/.zshrc
```

```bash
# 1. 复制模板
cp config/global.template.yaml config/global.yaml

# 2. 编辑并填入您的 API 密钥
vim config/global.yaml
# 将 "********" 替换为您的实际 API 密钥
```

--------------------------------

### GET _check_progress

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/design/core/plan-support-architecture.md

Retrieves the current status summary of all subtasks.

```APIDOC
## GET _check_progress

### Description
Returns a formatted summary of all subtask statuses, including counts of completed, running, and failed tasks.

### Method
GET

### Endpoint
_check_progress

### Response
#### Success Response (200)
- **status_summary** (string) - A formatted string containing the status of all tasks and a summary count.
```

--------------------------------

### Deepsearch Directory Structure

Source: https://github.com/kweaver-ai/dolphin/blob/main/examples/README.md

The file layout for the deepsearch example project.

```text
deepsearch/
├── bin/
│   └── deepsearch.sh        # Convenience launch script
├── config/
│   ├── global.yaml          # Configuration (create from template)
│   └── global.template.yaml # Configuration template
├── deepsearch.dph           # Main research agent
├── deepersearch.dph         # Multi-perspective research agent
├── web_search.dph           # Web search with query expansion
└── web_query.dph            # Direct web query agent
```

--------------------------------

### Execute Skill-Guided Assistant

Source: https://github.com/kweaver-ai/dolphin/blob/main/examples/README.md

Run the skill-guided assistant using the provided convenience script or the manual dolphin run command.

```bash
./examples/resource_skill/bin/skill_guided_coding.sh "I have a new mobile app idea, help me brainstorm"

./examples/resource_skill/bin/skill_guided_coding.sh "As CTO, how should I assess our tech debt?"

./examples/resource_skill/bin/skill_guided_coding.sh "Help me design a notification system for my app"
```

```bash
dolphin run --folder examples/resource_skill/ \
    --agent skill_guided_assistant \
    --config examples/resource_skill/config/global.yaml \
    --query "Help me brainstorm a new feature"
```

--------------------------------

### Define Tool Schema

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/usage/guides/output_format_usage_guide.md

Example of a JSON schema definition for a tool function.

```python
[{
    "type": "function",
    "function": {
        "name": "UserProfile",
        "description": "用户档案信息",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "用户姓名"},
                "age": {"type": "integer", "description": "用户年龄"}
            },
            "required": ["name", "age"]
        }
    }
}]
```

--------------------------------

### POST _plan_tasks

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/design/core/plan-support-architecture.md

Plans and starts a list of subtasks within the current context.

```APIDOC
## POST _plan_tasks

### Description
Plans and starts subtasks. If a plan is not enabled, it enables it lazily; if a plan exists, it treats the request as a replan. It registers tasks into the TaskRegistry and starts them based on the execution mode.

### Method
POST

### Endpoint
_plan_tasks

### Parameters
#### Request Body
- **tasks** (List[Dict[str, Any]]) - Required - A list of task dictionaries, each containing 'id', 'name', and 'prompt'.

### Response
#### Success Response (200)
- **result** (string) - A summary string indicating the number of tasks planned and the execution mode.
```

--------------------------------

### Backward Compatibility Example

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/usage/configuration/feature_flags_management_design.md

Demonstrates backward compatibility for flags, showing that both old and new flag names and short options work correctly. The Python code snippet shows how flags are read in code.

```bash
# 以下命令都能正常工作
dolphin --folder ./agents --agent test --debug
dolphin --folder ./agents --agent test -d
```

```python
# 在 Python 代码中也能正确读取
# flags.is_enabled(flags.DEBUG_MODE) -> True
```

--------------------------------

### Delta Mode Data Structure

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/usage/guides/dolphin-agent-integration.md

Example of the JSON structure returned when using stream_mode='delta'.

```python
{
    "_progress": [
        {
            "stage": "llm",
            "answer": "Hello, I am an AI assistant",  # Full text (still retained)
            "delta": "assistant"  # ✅ New field: delta text
        }
    ]
}
```

--------------------------------

### Run Basic Agent

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/usage/quick_start/quickstart.md

Execute a simple Dolphin agent from the command line.

```bash
dolphin run --agent hello --folder ./my_agents
```

--------------------------------

### Initialize New Skill

Source: https://github.com/kweaver-ai/dolphin/blob/main/tests/fixtures/skills/anthropic/skill-creator.md

Use this script to generate a new skill template. It creates the necessary directory structure and placeholder files for scripts, references, and assets.

```bash
scripts/init_skill.py <skill-name> --path <output-directory>
```

--------------------------------

### Initialize Global Skills

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/usage/guides/dolphin-agent-integration.md

Initializes the GlobalSkills object, which requires a GlobalConfig instance during setup.

```python
class GlobalSkills:
    """Global skills management"""

    def __init__(self, global_config: GlobalConfig):
        """
        Initialize global skills

        Args:
            global_config: Global configuration object
        """
        pass
```

--------------------------------

### Prompt Block

Source: https://context7.com/kweaver-ai/dolphin/llms.txt

Examples of using the prompt block with different output formats and system prompts.

```APIDOC
## POST /prompt

### Description
Used to send prompts to the AI model with specified parameters.

### Method
POST

### Endpoint
/prompt

### Parameters
#### Query Parameters
- **system_prompt** (string) - Optional - The system prompt to guide the AI's behavior.
- **model** (string) - Optional - The AI model to use for generation.
- **output** (string) - Optional - The desired output format (e.g., 'json', 'jsonl').

### Request Example
```json
{
  "prompt": "Write a poem about technology",
  "parameters": {
    "system_prompt": "You are an AI assistant",
    "model": "qwen-plus"
  }
}
```

### Request Example (JSON Output)
```json
{
  "prompt": "Generate user information",
  "parameters": {
    "output": "json"
  }
}
```

### Request Example (JSONL Output)
```json
{
  "prompt": "Generate three user records",
  "parameters": {
    "output": "jsonl"
  }
}
```

### Response
#### Success Response (200)
- **poem** (string) - The generated poem.
- **user_info** (object) - The generated user information in JSON format.
- **users** (array) - The generated user records in JSONL format.
```

--------------------------------

### Create MCP Integration Files

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/design/skill/mcp_integration_design.md

Commands to create the necessary Python files for MCP adapter and skill kit implementation. These files serve as the foundation for integrating MCP functionalities.

```bash
# 创建 MCP 适配器和技能套件文件
touch src/DolphinLanguageSDK/skill/installed/mcp_adapter.py
touch src/DolphinLanguageSDK/skill/installed/mcp_skillkit.py
```

--------------------------------

### Streaming Response Handler Example

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/usage/guides/dolphin-agent-integration.md

Implementation of a streaming response handler using the unified processing logic.

```python
async def stream_agent_response(agent, is_first_run=True):
    """Stream Agent response"""
    last_text = ""

    if is_first_run:
        # First execution
        async for result in agent.arun(stream_variables=True):
            delta, last_text = process_streaming_output(result, last_text)
            if delta:
                print(delta, end="", flush=True)
    else:
        # Subsequent chat
        async for result in agent.continue_chat(message="Continue..."):
            delta, last_text = process_streaming_output(result, last_text)
            if delta:
                print(delta, end="", flush=True)
```

--------------------------------

### 快速开始

Source: https://github.com/kweaver-ai/dolphin/blob/main/bin/README.zh-CN.md

运行、调试或与 Agent 进行交互的基本命令。

```bash
# 运行 Agent
dolphin run --agent my_agent --folder ./agents --query "你的查询"

# 调试模式
dolphin debug --agent my_agent --folder ./agents

# 交互式对话
dolphin chat --agent my_agent --folder ./agents
```

--------------------------------

### 定义技能函数的结果处理策略

Source: https://github.com/kweaver-ai/dolphin/blob/main/docs/usage/guides/skillkit_hook_guide.md

在 Skillkit 中为技能函数配置结果处理策略，包括 'summary' 和 'preview'。适用于需要对不同场景下的技能结果进行预处理的情况。

```python
from typing import List
from DolphinLanguageSDK.skill.skill_function import SkillFunction
from DolphinLanguageSDK.skill.skillkit import Skillkit

class NoopSkillkit(Skillkit):
    def getName(self) -> str:
        return "noop_skillkit"

    def noop_calling(self, **kwargs) -> str:
        """
        不做任何事情, 用于测试
        """
        print("do nothing")
        return "do nothing"
        
    def getSkills(self) -> List[SkillFunction]:
        # 为技能函数定义结果处理策略
        result_process_strategies = [
            {
                "strategy": "summary",
                "category": "llm",
            },
                    {
            "strategy": "preview",
            "category": "app",
        },
        ]
        
        skillfunc1 = SkillFunction(
            func=self.noop_calling,
            result_process_strategies=result_process_strategies,
        )
        return [skillfunc1]
```