ShanClaw：macOS 智能交互式 AI Agent CLI 指南

# ~/.shanclaw/config.yaml
mcp:
  servers:
    github:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-github"]
      env:
        GITHUB_TOKEN: "your-token-here"
    slack:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-slack"]

// Agent Engine 核心流程（伪代码）
func (a *Agent) Run(ctx context.Context, input string) error {
    // 1. 加载 Agent 指令
    instructions := a.LoadInstructions()
    
    // 2. 获取对话历史
    history := a.Session.GetHistory()
    
    // 3. 构建 Prompt
    prompt := BuildPrompt(instructions, history, input)
    
    // 4. 调用 LLM
    response, err := a.client.Complete(ctx, prompt)
    if err != nil {
        return err
    }
    
    // 5. 处理工具调用
    for _, toolCall := range response.ToolCalls {
        result, err := a.tools.Execute(ctx, toolCall)
        // 将工具结果追加到对话历史
        history.AddToolResult(toolCall, result)
    }
    
    // 6. 返回最终响应
    return a.tui.Render(response.Content)
}

// 工具接口定义
type Tool interface {
    Name() string           // 工具名称
    Description() string    // 工具描述
    Schema() InputSchema    // 输入参数 schema
    Execute(ctx context.Context, input json.RawMessage) (json.RawMessage, error)
}

// 工具注册表
type ToolRegistry struct {
    tools map[string]Tool
}

func (r *ToolRegistry) Register(tool Tool) error
func (r *ToolRegistry) Get(name string) (Tool, error)
func (r *ToolRegistry) List() []Tool

// MCP 客户端核心
type MCPClient struct {
    servers  map[string]*MCPConnection
    session  *MCPSession
}

func (c *MCPClient) Connect(ctx context.Context, server Config) error {
    // 1. 启动 MCP 服务器进程
    // 2. 建立 stdio 通信
    // 3. 协议握手
    // 4. 获取可用工具列表
}

func (c *MCPClient) CallTool(ctx context.Context, server, tool string, args json.RawMessage) (json.RawMessage, error)

# ~/.shanclaw/config.yaml
gateway:
  url: "http://localhost:8080"  # Shannon Gateway 地址
  api_key: "your-gateway-api-key"  # Gateway API Key

# LLM 提供商配置
providers:
  openai:
    api_key: "sk-..."
    model: "gpt-4o"
  anthropic:
    api_key: "sk-ant-..."
    model: "claude-sonnet-4-20250514"
  google:
    api_key: "..."
    model: "gemini-2.0-flash"

# ~/.shanclaw/config.yaml
mcp:
  servers:
    # GitHub 集成
    github:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-github"]
      env:
        GITHUB_TOKEN: "${GITHUB_TOKEN}"  # 支持环境变量

    # Slack 集成
    slack:
      command: npx  
      args: ["-y", "@modelcontextprotocol/server-slack"]
      env:
        SLACK_BOT_TOKEN: "${SLACK_BOT_TOKEN}"
        SLACK_TEAM_ID: "${SLACK_TEAM_ID}"

    # 数据库（以 PostgreSQL 为例）
    postgres:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-postgres"]
      env:
        DATABASE_URL: "postgresql://user:pass@localhost:5432/mydb"

# ~/.shanclaw/config.yaml
permissions:
  # Agent 工具权限控制
  agents:
    default:
      allow:
        - file_read
        - file_write
        - bash
        - notify
      deny:
        - screenshot
        - applescript

    dev:
      allow:
        - "*"  # 允许所有工具

# 1. 确保 Shannon Gateway 运行中
shan gateway status

# 2. 创建第一个 Agent
shan agent create myagent "我的助手，可以帮我处理日常任务"

# 3. 启动交互式会话
shan

# 在 TUI 中输入：
# /myagent
# 你好，帮我查看当前目录下的所有 Go 文件

# 创建代码助手
shan agent create coder \
  "资深 Go 开发者，擅长高并发系统设计，熟悉 Kubernetes" \
  --tools "file,grep,glob,bash" \
  --mcp "github,postgres"

# 创建写作助手
shan agent create writer \
  "专业技术写手，擅长写清晰的技术文档和博客" \
  --no-mcp  # 不启用 MCP

# 创建全栈助手
shan agent create fullstack \
  "全栈工程师，精通前后端开发和 DevOps" \
  --tools "*"  # 所有工具

<!-- ~/.shanclaw/agents/coder/instructions.md -->

# {{agent_name}}

## 角色
你是一名资深软件工程师，专注于 {{language}} 开发。

## 能力范围
- 编写高质量、可维护的代码
- 设计可扩展的系统架构
- Code Review 和性能优化
- 编写测试和文档

## 工作原则
1. 代码优先：先生成代码，再解释
2. 测试驱动：关键逻辑必须有测试
3. 文档完善：公共 API 必须有注释

## 限制
- 不生成可能有安全漏洞的代码
- 不执行破坏性的数据库操作
- 重大决策先询问用户

// 示例：创建自定义天气工具
package tools

import (
    "context"
    "encoding/json"
    "net/http"
)

type WeatherTool struct{}

func (t *WeatherTool) Name() string {
    return "weather"
}

func (t *WeatherTool) Description() string {
    return "获取指定城市的天气预报"
}

func (t *WeatherTool) Schema() InputSchema {
    return InputSchema{
        Type: "object",
        Properties: map[string]SchemaProperty{
            "city": {
                Type:        "string",
                Description: "城市名称（中文或英文）",
            },
            "days": {
                Type:        "integer",
                Description: "预报天数（1-7）",
                Default:     3,
            },
        },
        Required: []string{"city"},
    }
}

func (t *WeatherTool) Execute(ctx context.Context, input json.RawMessage) (json.RawMessage, error) {
    var args struct {
        City string `json:"city"`
        Days int    `json:"days"`
    }
    if err := json.Unmarshal(input, &args); err != nil {
        return nil, err
    }
    
    // 调用天气 API
    url := fmt.Sprintf("https://api.weather.com/v3/forecast?city=%s&days=%d", args.City, args.Days)
    resp, err := http.Get(url)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    
    return json.Marshal(result)
}

// 示例：简单的自定义 MCP 服务器
package main

import (
    "context"
    "github.com/modelcontextprotocol/sdk/go/server"
)

func main() {
    s := server.NewStdioServer("my-custom-server")
    
    // 注册工具
    s.RegisterTool("custom_tool", "我的自定义工具", handleCustomTool)
    
    // 运行
    s.Serve()
}

func handleCustomTool(ctx context.Context, args map[string]interface{}) (interface{}, error) {
    // 实现工具逻辑
    return map[string]string{"result": "success"}, nil
}

<!-- ~/.shanclaw/skills/my-skill/SKILL.md -->

# My Skill

## 描述
这是一个自定义 Skill，用于...

## 使用场景
- 场景 1
- 场景 2

## 使用方法

# ~/.shanclaw/config.yaml
security:
  # 禁止危险操作
  deny_patterns:
    - "rm -rf /"
    - "DROP TABLE *"
    - "format.*drive"
  
  # 文件访问限制
  allowed_paths:
    - "~/workspace"
    - "~/projects"
  
  # API Key 保护
  env_vars_strict: true

# ~/.shanclaw/config.yaml
performance:
  # 上下文窗口大小
  context_window: 128000
  
  # 历史会话保留数
  max_history: 100
  
  # 工具并行执行
  parallel_tools: true
  max_parallel: 5
  
  # 缓存配置
  cache:
    enabled: true
    ttl: 3600

# 1. 使用 launchd 管理 Daemon
cat > ~/Library/LaunchAgents/com.kocoro.shanclaw.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "...">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.kocoro.shanclaw</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/shan</string>
        <string>daemon</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>
EOF

# 2. 加载服务
launchctl load ~/Library/LaunchAgents/com.kocoro.shanclaw.plist

# 3. 设置开机自启
launchctl enable gui/$(id -u)/com.kocoro.shanclaw