概述

Dify 的 API 让你将 AI 能力集成到现有应用程序中，而无需从零开始构建 AI 基础设施。你可以获得大型语言模型的全部功能，同时拥有创建自定义用户体验的灵活性。

为什么使用 Dify API

核心优势

API 集成的工作原理

1. 构建应用
   └─ 在 Dify Studio 中构建具有所需 AI 能力的应用

2. 生成 API 凭据
   └─ 安全访问应用功能

3. 调用 API
   └─ 从你的应用程序调用 API 获取 AI 驱动的响应

4. 用户交互
   └─ 用户通过你的自定义界面交互，Dify 处理 AI 处理过程

功能继承

你的 API 会自动继承 Dify 应用的所有功能：

• 提示词
• 知识库
• 工具
• 模型配置

API 访问设置

访问 API 设置页面

1. 进入你的应用
2. 在左侧边栏找到 API Access
3. 进入 API 设置页面

创建 API 凭据

步骤：

1. 点击 创建凭据
2. 输入凭据名称（可选）
3. 选择环境（开发、测试、生产）
4. 点击 创建
5. 保存生成的 API Key

重要提示：

• 永远不要在前端代码或客户端请求中暴露 API 密钥
• 始终从后端调用 Dify API
• 定期轮换密钥

查看 API 文档

Dify 会自动生成针对你应用配置的完整 API 文档，包括：

• 端点 URL
• 请求方法
• 请求参数
• 响应格式
• 示例代码

API 安全

凭据管理

最佳实践：

凭据管理:
  environment:
    - name: "development"
      api_key: "${DIFY_DEV_API_KEY}"
    - name: "testing"
      api_key: "${DIFY_TEST_API_KEY}"
    - name: "production"
      api_key: "${DIFY_PROD_API_KEY}"
  
  lifecycle:
    rotate: true
    rotation_period: "90days"
    revoke_unused: true

定期轮换：

• 每 90 天轮换一次密钥
• 撤销未使用的凭据
• 监控 API 使用情况

安全措施

后端存储：

# 使用环境变量存储 API 密钥
import os

DIFY_API_KEY = os.getenv("DIFY_API_KEY")

速率限制：

from flask_limiter import Limiter

limiter = Limiter(
    app=app,
    key_func=get_remote_address,
    default_limits=["100 per hour"]
)

@app.route("/api/chat")
@limiter.limit("20 per minute")
def chat():
    pass

请求验证：

def validate_request(request):
    # 验证请求来源
    if not verify_origin(request):
        return False
    
    # 验证请求格式
    if not validate_format(request.json):
        return False
    
    return True

日志记录：

import logging

logging.basicConfig(level=logging.INFO)

def log_api_call(endpoint, user_id, status):
    logging.info(f"API Call: {endpoint} by {user_id} - Status: {status}")

文本生成应用 API

端点信息

URL：POST https://api.dify.ai/v1/completion-messages

请求参数

cURL 示例

curl --location --request POST 'https://api.dify.ai/v1/completion-messages' \
  --header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "inputs": {
      "text": "Hello, how are you?"
    },
    "response_mode": "streaming",
    "user": "abc-123"
  }'

Python 示例

import requests
import json

url = "https://api.dify.ai/v1/completion-messages"
headers = {
    'Authorization': 'Bearer ENTER-YOUR-SECRET-KEY',
    'Content-Type': 'application/json',
}
data = {
    "inputs": {
        "text": 'Hello, how are you?'
    },
    "response_mode": "streaming",
    "user": "abc-123"
}
response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.text)

响应格式

{
  "result": "Hello! I'm doing well, thank you for asking. How can I assist you today?",
  "message_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": 1678901234,
  "metadata": {
    "usage": {
      "prompt_tokens": 10,
      "prompt_unit_price": "0.00001",
      "prompt_price_unit": "1K tokens",
      "prompt_price": "0.0001",
      "completion_tokens": 20,
      "completion_unit_price": "0.00002",
      "completion_price_unit": "1K tokens",
      "completion_price": "0.0004",
      "total_tokens": 30,
      "total_price": "0.0005",
      "currency": "USD",
      "latency": 1.5
    }
  }
}

对话应用 API

端点信息

URL：POST https://api.dify.ai/v1/chat-messages

conversation_id 的关键注意事项

重要说明：

• API 不会共享 WebApp 创建的对话
• 通过 API 创建的对话与在 WebApp 界面中创建的对话是隔离的

生成 conversation_id：

# 开始新对话时，将 conversation_id 字段留空
data = {
    "inputs": {},
    "query": "Hello",
    "response_mode": "streaming",
    "user": "abc-123"
    # conversation_id 不设置，系统将生成新的
}

在现有会话中处理 conversation_id：

# 一旦生成 conversation_id，后续调用应包含此 ID
data = {
    "inputs": {},  # 会被忽略
    "query": "How are you?",
    "response_mode": "streaming",
    "conversation_id": "1c7e55fb-1ba2-4e10-81b5-30addcea2276",
    "user": "abc-123"
}

管理动态变量：

# 使用会话变量调整机器人行为
data = {
    "query": "Change your language to Chinese",
    "response_mode": "streaming",
    "conversation_id": "1c7e55fb-1ba2-4e10-81b5-30addcea2276",
    "user": "abc-123",
    "variables": {
        "language": "Chinese"
    }
}

请求参数

cURL 示例

curl --location --request POST 'https://api.dify.ai/v1/chat-messages' \
  --header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "inputs": {},
    "query": "Hello",
    "response_mode": "streaming",
    "conversation_id": "1c7e55fb-1ba2-4e10-81b5-30addcea2276",
    "user": "abc-123"
  }'

Python 示例

import requests
import json

url = 'https://api.dify.ai/v1/chat-messages'
headers = {
    'Authorization': 'Bearer ENTER-YOUR-SECRET-KEY',
    'Content-Type': 'application/json',
}
data = {
    "inputs": {},
    "query": "Hello",
    "response_mode": "streaming",
    "conversation_id": "1c7e55fb-1ba2-4e10-81b5-30addcea2276",
    "user": "abc-123"
}
response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.text)

响应格式

{
  "result": "Hello! I'm doing well, thank you for asking. How can I assist you today?",
  "conversation_id": "1c7e55fb-1ba2-4e10-81b5-30addcea2276",
  "message_id": "550e8400-e29b-41d4-a716-446655440001",
  "created_at": 1678901234,
  "metadata": {
    "usage": {
      "prompt_tokens": 15,
      "prompt_unit_price": "0.00001",
      "prompt_price_unit": "1K tokens",
      "prompt_price": "0.00015",
      "completion_tokens": 25,
      "completion_unit_price": "0.00002",
      "completion_price_unit": "1K tokens",
      "completion_price": "0.0005",
      "total_tokens": 40,
      "total_price": "0.00065",
      "currency": "USD",
      "latency": 2.0
    }
  }
}

流式响应处理

流式响应格式

流式响应以 Server-Sent Events (SSE) 格式返回：

data: {"event": "message", "task_id": "xxx", "id": "xxx", "answer": "Hello"}

data: {"event": "message", "task_id": "xxx", "id": "xxx", "answer": "Hello, how"}

data: {"event": "message", "task_id": "xxx", "id": "xxx", "answer": "Hello, how are"}

data: {"event": "message_end", "task_id": "xxx", "id": "xxx", "metadata": {...}}

Python 流式处理示例

import requests
import json

def stream_chat():
    url = 'https://api.dify.ai/v1/chat-messages'
    headers = {
        'Authorization': 'Bearer ENTER-YOUR-SECRET-KEY',
        'Content-Type': 'application/json',
    }
    data = {
        "inputs": {},
        "query": "Tell me a story",
        "response_mode": "streaming",
        "user": "abc-123"
    }
    
    response = requests.post(url, headers=headers, json=data, stream=True)
    
    for line in response.iter_lines():
        if line:
            line = line.decode('utf-8')
            if line.startswith('data: '):
                data = json.loads(line[6:])
                if data.get('event') == 'message':
                    print(data.get('answer'), end='', flush=True)
                elif data.get('event') == 'message_end':
                    print('\n\nResponse completed!')
                    print(f"Metadata: {data.get('metadata')}")

stream_chat()

JavaScript 流式处理示例

async function streamChat() {
    const response = await fetch('https://api.dify.ai/v1/chat-messages', {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer ENTER-YOUR-SECRET-KEY',
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            inputs: {},
            query: "Tell me a story",
            response_mode: "streaming",
            user: "abc-123"
        })
    });

    const reader = response.body.getReader();
    const decoder = new TextDecoder();

    while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        const chunk = decoder.decode(value);
        const lines = chunk.split('\n');

        for (const line of lines) {
            if (line.startsWith('data: ')) {
                const data = JSON.parse(line.substring(6));
                if (data.event === 'message') {
                    process.stdout.write(data.answer);
                } else if (data.event === 'message_end') {
                    console.log('\n\nResponse completed!');
                    console.log('Metadata:', data.metadata);
                }
            }
        }
    }
}

streamChat();

错误处理

常见错误代码

错误处理示例

import requests
from requests.exceptions import RequestException

def chat_with_retry(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, headers=headers, json=data)
            response.raise_for_status()
            return response.json()
        except RequestException as e:
            if response.status_code == 429:
                wait_time = 2 ** attempt  # 指数退避
                time.sleep(wait_time)
                continue
            elif response.status_code >= 500:
                if attempt < max_retries - 1:
                    time.sleep(wait_time)
                    continue
            raise e
    return None

最佳实践

性能优化

批量请求：

def batch_chat(messages):
    # 批量处理多个请求
    results = []
    for message in messages:
        result = chat_with_retry(url, headers, {
            "inputs": {},
            "query": message,
            "response_mode": "blocking",
            "user": "abc-123"
        })
        results.append(result)
    return results

缓存响应：

from functools import lru_cache

@lru_cache(maxsize=100)
def cached_chat(query):
    return chat_with_retry(url, headers, {
        "inputs": {},
        "query": query,
        "response_mode": "blocking",
        "user": "abc-123"
    })

监控和日志

监控 API 使用：

import logging

def log_api_call(endpoint, status, response_time):
    logging.info(f"API: {endpoint} | Status: {status} | Time: {response_time}ms")

def monitor_chat():
    start_time = time.time()
    response = chat_with_retry(url, headers, data)
    response_time = (time.time() - start_time) * 1000
    log_api_call('chat', response.status_code, response_time)
    return response

测试策略

单元测试：

import unittest

class TestDifyAPI(unittest.TestCase):
    def test_chat(self):
        response = chat_with_retry(url, headers, {
            "inputs": {},
            "query": "Hello",
            "response_mode": "blocking",
            "user": "test"
        })
        self.assertIsNotNone(response)
        self.assertIn('result', response)

集成测试：

def test_conversation_flow():
    # 开始对话
    response1 = chat_with_retry(url, headers, {
        "inputs": {},
        "query": "Hello",
        "response_mode": "blocking",
        "user": "test"
    })
    conversation_id = response1['conversation_id']
    
    # 继续对话
    response2 = chat_with_retry(url, headers, {
        "inputs": {},
        "query": "How are you?",
        "response_mode": "blocking",
        "conversation_id": conversation_id,
        "user": "test"
    })
    
    self.assertIsNotNone(response2)

资源链接

• API 文档: https://docs.dify.ai/zh/use-dify/publish/developing-with-apis
• API 参考: https://docs.dify.ai/zh/reference/api
• 示例代码: https://github.com/langgenius/dify-api-examples

最后更新: 2026-03-12 作者: EchoHaoRan

本文详解NextCloud的部署配置，打造功能完善的私有云存储服务。

前言

百度网盘限速、iCloud空间贵、Google Drive国内用不了…

不如自建一个私有云盘：

• 数据完全自己掌控
• 不限速、不限容量
• 功能比网盘还多

NextCloud是最流行的开源私有云方案。

NextCloud简介

功能特点

核心功能：
- 文件存储与同步
- 多设备同步
- 文件分享
- 版本历史

扩展功能：
- 在线Office（Collabora/OnlyOffice）
- 日历、联系人
- 笔记、任务
- 视频通话
- 邮件客户端

对比其他方案

Docker部署

目录结构

nextcloud/
├── docker-compose.yml
├── db/            # 数据库数据
├── html/          # NextCloud数据
└── config/        # 配置文件

Docker Compose配置

# docker-compose.yml
version: '3.8'

services:
  db:
    image: mariadb:10.11
    container_name: nextcloud-db
    restart: unless-stopped
    command: --transaction-isolation=READ-COMMITTED --binlog-format=ROW
    volumes:
      - ./db:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=nextcloud_root_password
      - MYSQL_PASSWORD=nextcloud_password
      - MYSQL_DATABASE=nextcloud
      - MYSQL_USER=nextcloud

  redis:
    image: redis:alpine
    container_name: nextcloud-redis
    restart: unless-stopped

  app:
    image: nextcloud:latest
    container_name: nextcloud
    restart: unless-stopped
    ports:
      - "8080:80"
    links:
      - db
      - redis
    volumes:
      - ./html:/var/www/html
      - ./config:/var/www/html/config
      - /path/to/data:/var/www/html/data  # 数据目录，建议用大硬盘
    environment:
      - MYSQL_HOST=db
      - MYSQL_DATABASE=nextcloud
      - MYSQL_USER=nextcloud
      - MYSQL_PASSWORD=nextcloud_password
      - REDIS_HOST=redis
      - NEXTCLOUD_TRUSTED_DOMAINS=your.domain.com 192.168.1.100
    depends_on:
      - db
      - redis

启动服务

# 创建目录
mkdir -p db html config

# 启动
docker compose up -d

# 查看日志
docker compose logs -f app

初始设置

浏览器访问：http://服务器IP:8080

1. 创建管理员账户
2. 数据库已自动配置（Docker环境变量）
3. 完成安装

性能优化

配置PHP

# 进入容器
docker exec -it nextcloud bash

# 编辑php配置
# /usr/local/etc/php/conf.d/nextcloud.ini
memory_limit=512M
upload_max_filesize=16G
post_max_size=16G
max_execution_time=3600
max_input_time=3600

Redis缓存配置

// config/config.php 添加
'memcache.local' => '\\OC\\Memcache\\APCu',
'memcache.distributed' => '\\OC\\Memcache\\Redis',
'memcache.locking' => '\\OC\\Memcache\\Redis',
'redis' => [
    'host' => 'redis',
    'port' => 6379,
],

后台任务

# 使用cron替代AJAX（推荐）
# 宿主机添加定时任务
crontab -e

# 添加：
*/5 * * * * docker exec -u www-data nextcloud php cron.php

# NextCloud设置
设置 → 管理 → 基本设置 → 后台任务 → Cron

数据库优化

-- 连接数据库
docker exec -it nextcloud-db mysql -u root -p

-- 优化表
USE nextcloud;
OPTIMIZE TABLE oc_filecache;
OPTIMIZE TABLE oc_files_trash;

HTTPS配置

Nginx反向代理

# /etc/nginx/conf.d/nextcloud.conf
server {
    listen 80;
    server_name cloud.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name cloud.example.com;

    ssl_certificate /etc/letsencrypt/live/cloud.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/cloud.example.com/privkey.pem;

    client_max_body_size 16G;
    client_body_timeout 3600s;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        proxy_connect_timeout 3600;
        proxy_send_timeout 3600;
        proxy_read_timeout 3600;
    }

    location /.well-known/carddav {
        return 301 $scheme://$host/remote.php/dav;
    }
    
    location /.well-known/caldav {
        return 301 $scheme://$host/remote.php/dav;
    }
}

更新配置

// config/config.php
'trusted_domains' => [
    0 => 'cloud.example.com',
    1 => '192.168.1.100',
],
'trusted_proxies' => ['127.0.0.1'],
'overwrite.cli.url' => 'https://cloud.example.com',
'overwriteprotocol' => 'https',

客户端配置

桌面客户端

下载：https://nextcloud.com/install/#install-clients

支持：Windows、macOS、Linux

配置：
1. 服务器地址：https://cloud.example.com
2. 登录账号
3. 选择同步文件夹

移动客户端

iOS：App Store搜索"Nextcloud"
Android：Play商店或F-Droid

功能：
- 文件浏览/上传/下载
- 照片自动上传
- 离线文件

WebDAV访问

地址：https://cloud.example.com/remote.php/dav/files/用户名/

可用于：
- Windows映射网络驱动器
- macOS连接服务器
- 第三方文件管理器

远程访问方案

问题

NextCloud部署在家里/公司内网
如何从外网访问？

方案对比

---

## 数据迁移

### 从其他网盘迁移

```bash
# 将文件复制到NextCloud数据目录
cp -r /old/data/* /path/to/nextcloud/data/username/files/

# 修复权限
docker exec -u www-data nextcloud php occ files:scan --all

备份

# 备份脚本
#!/bin/bash
DATE=$(date +%Y%m%d)

# 停止服务
docker compose down

# 备份数据库
docker run --rm -v nextcloud_db:/db -v $(pwd):/backup alpine tar czf /backup/db_$DATE.tar.gz /db

# 备份数据
tar czf data_$DATE.tar.gz html config

# 启动服务
docker compose up -d

常见问题

Q1：上传大文件失败

// config/config.php
'upload_max_filesize' => '16G',

// Nginx配置
client_max_body_size 16G;
client_body_timeout 3600s;

Q2：同步慢

1. 检查服务器性能
2. 启用Redis缓存
3. 检查网络带宽
4. 使用组网软件获得更稳定连接

Q3：内存不足

# 增加PHP内存限制
# php.ini
memory_limit=1024M

总结

NextCloud部署要点：

1. 安装：Docker Compose最简单
2. 性能：Redis缓存必配
3. 安全：生产环境用HTTPS
4. 远程：组网方案最简单安全
5. 备份：定期备份数据

我的配置：

服务器：群晖NAS Docker
存储：4TB硬盘
访问：星空组网（手机电脑都能访问）
用途：
- 文件同步
- 照片备份
- 文档协作

参考资料

1. NextCloud官方文档：https://docs.nextcloud.com/
2. NextCloud GitHub：https://github.com/nextcloud

Config.php

<?php
$CONFIG = array (
  'htaccess.RewriteBase' => '/',
  'memcache.local' => '\\OC\\Memcache\\APCu',
  'apps_paths' => 
  array (
    0 => 
    array (
      'path' => '/var/www/html/apps',
      'url' => '/apps',
      'writable' => false,
    ),
    1 => 
    array (
      'path' => '/var/www/html/custom_apps',
      'url' => '/custom_apps',
      'writable' => true,
    ),
  ),
  'memcache.distributed' => '\\OC\\Memcache\\Redis',
  'memcache.locking' => '\\OC\\Memcache\\Redis',
  'redis' => 
  array (
    'host' => 'redis',
    'password' => '',
    'port' => 6379,
  ),
  'upgrade.disable-web' => true,
  'instanceid' => 'oc5y7gg2aq78',
  'passwordsalt' => '4b7To1m8pcakUc60j/BYlJ9ItxCfxv',
  'secret' => '00rTZjZwqadjToyu+26yM6OzcC8VlZfaKGtDFVKKuc05fdkx',
  'trusted_domains' => 
  array (
    0 => '100.118.251.62:8080',
    1 => '154.222.24.65:38080',
    2 => 'nc.echospace.top',
  ),
  'datadirectory' => '/var/www/html/data',
  'dbtype' => 'mysql',
  'version' => '33.0.3.2',
  'overwrite.cli.url' => 'https://nc.echospace.top',
  'overwriteprotocol' => 'https',
  'overwritehost' => 'nc.echospace.top',
  'trusted_proxies' => 
  array (
    0 => '192.168.1.201',
    1 => '100.118.251.62',
    2 => '154.222.24.65',
),
  'dbname' => 'nextcloud',
  'dbhost' => 'db',
  'dbtableprefix' => 'oc_',
  'mysql.utf8mb4' => true,
  'dbuser' => 'nextcloud',
  'dbpassword' => 'Wanghr1130',
  'installed' => true,
);

本文记录如何利用 Docker 在境外服务器（香港）部署 Xray + VLESS + WebSocket + TLS 代理服务，配合 Nginx 反向代理实现流量伪装，并通过 Clash 客户端连接使用。

部署架构

┌─────────────────────────────────────────────────────────────┐
│                        用户设备                               │
│                    (Clash / FlClash)                         │
│                         │                                    │
│                         │ HTTPS + WebSocket                   │
└─────────────────────────┼───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    香港服务器 (154.222.24.65)                  │
│                                                             │
│   ┌─────────────┐         ┌─────────────┐                  │
│   │  Nginx      │  proxy  │  Xray       │                  │
│   │  :80 :443   │◄────────│  :10086     │                  │
│   └─────────────┘  ws     └─────────────┘                  │
│         │                                         │          │
│         │ HTTPS 加密                             │ VLESS    │
│         ▼                                         ▼          │
│   ┌─────────────┐                       ┌─────────────┐    │
│   │  伪装网站    │                       │  Xray 核心   │    │
│   │  (HTML)     │                       │  (Docker)   │    │
│   └─────────────┘                       └─────────────┘    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

关键技术选型

服务器准备

环境要求

端口占用说明

⚠️ 本次部署中服务器已运行 1Panel，openresty 容器占用了 80/443 端口。 解决方案：停止 1Panel 的 openresty 容器，将端口让给 Nginx。

# 查看端口占用
ss -tlnp | grep -E ':80 |:443 '

# 停止占用端口的容器（如 openresty）
docker stop 1Panel-openresty-fMgR
docker rm 1Panel-openresty-fMgR

创建工作目录

mkdir -p /opt/xray/{certs,html,config}
cd /opt/xray

生成 TLS 证书

使用自签证书，仅支持客户端开启「跳过证书验证」。如需正式证书，可使用 Let’s Encrypt。

cd /opt/xray

openssl req -x509 -nodes -newkey rsa:2048 \
  -keyout certs/key.pem \
  -out certs/cert.pem \
  -days 365 \
  -subj '/C=US/ST=NY/L=NYC/O=CloudService/CN=cloud.example.com'

配置文件

Xray 配置

路径：/opt/xray/config/config.json

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [{
    "port": 10086,
    "listen": "127.0.0.1",
    "protocol": "vless",
    "settings": {
      "clients": [{
        "id": "60b3f6e5-1227-4487-8084-4bbb6503b923",
        "level": 0
      }],
      "decryption": "none"
    },
    "streamSettings": {
      "network": "ws",
      "wsSettings": {
        "path": "/vless"
      }
    },
    "sniffing": {
      "enabled": true,
      "destOverride": ["http", "tls"]
    }
  }],
  "outbounds": [
    {"protocol": "freedom", "settings": {}, "tag": "direct"},
    {"protocol": "blackhole", "settings": {}, "tag": "block"}
  ]
}

💡 关键配置说明：

• listen: "127.0.0.1"：仅监听本地，外部无法直接访问 Xray
• network: "ws"：WebSocket 传输，伪装成 HTTP 请求
• sniffing：自动识别流量类型，提升兼容性

Nginx 配置

路径：/opt/xray/nginx.conf

server {
    listen 80;
    server_name _;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name _;

    ssl_certificate /etc/ssl/certs/cert.pem;
    ssl_certificate_key /etc/ssl/private/key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5:!RC4;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # 伪装网站
    location / {
        root /usr/share/nginx/html;
        index index.html;
    }

    # Xray WebSocket 代理
    location /vless {
        proxy_pass http://127.0.0.1:10086;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}

💡 关键配置说明：

• 80 → 443：HTTP 自动重定向到 HTTPS
• location /vless：将 WebSocket 请求转发给 Xray
• Upgrade $http_upgrade：支持 WebSocket 协议升级

伪装网站

路径：/opt/xray/html/index.html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>Welcome to Nginx</title>
<style>
body{font-family:Arial;margin:0;padding:0;display:flex;justify-content:center;align-items:center;height:100vh;background:linear-gradient(135deg,#667eea 0%,#764ba2 100%);color:white;}
.container{text-align:center;background:rgba(0,0,0,0.3);padding:60px;border-radius:20px;}
h1{font-size:48px;margin-bottom:20px;}
p{font-size:18px;opacity:0.9;}
.status{margin-top:30px;padding:10px 30px;background:rgba(255,255,255,0.2);border-radius:50px;display:inline-block;}
</style>
</head>
<body>
<div class="container">
    <h1>Welcome</h1>
    <p>Server is running.</p>
    <div class="status">Online</div>
</div>
</body>
</html>

Docker Compose 配置

路径：/opt/xray/docker-compose.yml

version: '3.8'
services:
  xray-core:
    image: teddysun/xray:latest
    container_name: xray-core
    volumes:
      - ./config/config.json:/etc/xray/config.json
    restart: unless-stopped
    network_mode: host
    healthcheck:
      test: ["CMD", "cat", "/etc/xray/config.json"]
      interval: 30s
      timeout: 10s
      retries: 3

  nginx:
    image: nginx:alpine
    container_name: xray-nginx
    volumes:
      - ./html:/usr/share/nginx/html
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
      - ./certs/cert.pem:/etc/ssl/certs/cert.pem
      - ./certs/key.pem:/etc/ssl/private/key.pem
    restart: unless-stopped
    network_mode: host

💡 network_mode: host 的优势：

• 容器直接使用宿主机网络，避免端口冲突
• Nginx 可直接绑定 80/443 端口

部署命令

一键启动

cd /opt/xray

# 拉取镜像并启动
docker-compose pull
docker-compose up -d

# 查看状态
docker ps

# 查看日志
docker logs xray-core --tail 20
docker logs xray-nginx --tail 20

常用管理命令

# 重启服务
docker-compose restart

# 停止服务
docker-compose down

# 重新加载配置
docker-compose exec xray-core xray reload

# 更新 Xray
docker-compose pull xray-core && docker-compose up -d xray-core

客户端配置

Clash / FlClash 配置

port: 7890
socks-port: 7891
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

proxies:
  - name: HK-VLESS
    type: vless
    server: 154.222.24.65
    port: 443
    uuid: 60b3f6e5-1227-4487-8084-4bbb6503b923
    network: ws
    tls: true
    udp: true
    sni: 154.222.24.65
    skip-cert-verify: true
    ws-opts:
      path: /vless
      headers:
        Host: 154.222.24.65

proxy-groups:
  - name: 🚀 代理
    type: select
    proxies:
      - HK-VLESS

rules:
  - GEOIP,CN,DIRECT
  - MATCH,🚀 代理

FlClash 使用步骤

1. 导入配置

   • 方式一：扫描二维码
   • 方式二：上传 YAML 文件
   • 方式三：复制粘贴配置内容

2. 关键设置

   • TLS：✅ 必须开启
   • 跳过证书验证：✅ 必须开启（自签证书）
   • TUN 模式：✅ 需要开启

3. 测试连接

   • 选择节点 → 点击测试
   • 超时说明连接失败，检查上述设置

安全加固

更换 UUID

定期更换 UUID 可提升安全性。

# 生成新 UUID
uuidgen

# 编辑配置
nano /opt/xray/config/config.json
# 将 "id" 字段替换为新 UUID

# 重载 Xray
docker-compose exec xray-core xray reload

防火墙设置

# 仅开放必要端口
ufw allow 22   # SSH
ufw allow 80    # HTTP
ufw allow 443   # HTTPS
ufw enable

定期更新

# 更新 Docker 镜像
docker-compose pull
docker-compose up -d

# 检查 Xray 更新
docker pull teddysun/xray:latest
docker-compose up -d xray-core

故障排查

常见问题

日志查看

# Xray 日志
docker logs xray-core --tail 50 -f

# Nginx 日志
docker logs xray-nginx --tail 50 -f

# 系统日志
journalctl -u docker -f

连通性测试

# 服务器内部测试
curl http://127.0.0.1/           # HTTP
curl https://127.0.0.1/         # HTTPS（自签证书）

# 外部测试
curl https://你的服务器IP/       # 伪装网站

相关文件路径

总结

本部署方案实现了：

• ✅ 流量加密：TLS 1.3 全程加密
• ✅ 流量伪装：模拟正常 HTTPS 网站
• ✅ 抗封锁：VLESS + WebSocket 难以识别
• ✅ 易于管理：Docker 一键部署
• ✅ 高可用：自动重启，故障自愈

📅 部署日期：2026-04-19
🌐 服务器：香港 154.222.24.65
🔐 协议：VLESS + WebSocket + TLS
🐳 容器：xray-core + xray-nginx

• 大家好，我是Echo。
• 很多人一听linux就想到密密麻麻的命令搞得头都大，又听那些使用过linux的人说系统容易滚炸。但我今天我推荐这个AnduinOS，简直就是想要尝试Linux的小白福音，安装简单，界面友好，日常使用几乎完全可以丢掉终端，真正做到了“Windows用户无痛转型”。
• AnduinOS 是一个基于 Ubuntu 开发的发行版。你可以把它理解为 Ubuntu 的萌新小白定制版。它安装过程简单，界面和windows类似，自带中文输入法！！！开箱即用。我为大家准备好了需要使用的所有文件，在我的链接自取。

BalenaEtcher:https://s.fnnas.net/s/bb59d12606074d1d89

AnduinOS:https://s.fnnas.net/s/a4518710e44c49d18e

-安装教程： https://www.bilibili.com/video/BV18DJizXEbd/?vd_source=6fda2572441be88741317636c9274c2b

当AI公司开始对军事应用说"不"，美国政府会用怎样的手段回应？Anthropic用一场诉讼给出了答案。

被"拉黑"的来龙去脉

3月初，美国国防部将AI公司Anthropic正式列入"供应链风险"名单，同时特朗普总统下令所有政府机构在六个月内停止使用Anthropic的技术产品。这一决定引发了罕见的跨党派争议——一家美国本土AI公司，仅因表达不同政见，就面临被整个联邦政府封杀的命运，这在科技行业史无前例。

Anthropic方面随后证实，公司确实曾收到五角大楼的合作邀请，但明确划定了两条"红线"：**不接受用于大规模国内监控的项目，也不参与全自动武器系统的开发。**正是这一立场，被认为触怒了本届政府。

诉讼的核心指控

Anthropic于本周在加州联邦地区法院提起诉讼，将矛头直指特朗普政府。诉状措辞罕见地严厉，声称：

“联邦政府报复了一家前沿AI开发商，因为它坚持对AI安全及其模型局限性这一重大公共议题的受保护立场，这违反了美国宪法和法律。”

公司具体提出了三项法律主张：

• 第一修正案违宪：政府惩罚Anthropic的言论立场，属于对受保护言论的报复性惩罚
• 第五修正案违宪：未经正当程序剥夺公司财产和商业利益
• 行政越权：总统无权直接下令所有政府机构全面切断与特定私营企业的合作

诉状还特别强调，政府正在"摧毁世界上增长最快的私营公司之一的经济价值"，这家公司是"负责任地开发对国家至关重要的新兴技术的领导者"。

罕见的"黑名单"

"供应链风险"这一认定，通常针对的是可能构成网络安全威胁或国家安全风险的外国公司，很少公开针对美国本土科技企业。Anthropic被列入名单后，包括美国国务院、国财政部和总务管理局（GSA）在内的多个联邦机构，已宣布或传出计划切断与Anthropic的合作。

其中GSA已正式终止了"OneGov合同"，导致Anthropic的服务从联邦政府三权分支全面撤出。

微软的态度：微妙而关键

值得注意的是，Anthropic的最大客户之一微软明确表示，将继续与Anthropic合作，但同时建立了内部防火墙，确保与Anthropic相关的业务不涉及任何五角大楼项目。这种"两边下注"的姿态，折射出科技巨头在中美AI竞争与国内政治风暴之间的两难处境。

等待裁决

据报道，负责审理此案的Rita Lin法官预计将在未来几天内做出初步裁决。诉讼结果不仅关乎一家公司的命运，更可能成为AI时代政府监管权力边界的重要判例。

Anthropic的遭遇，也让整个AI行业都在关注：当技术公司试图在商业利益与安全伦理之间划定底线时，政府的手究竟能伸多远？

来源链接

• https://www.theverge.com/ai-artificial-intelligence/891377/anthropic-dod-lawsuit

数据来源于网络，由多多来报整理编写，仅供参考。

今天推荐的软件是Bitwarden，一款开源安全的自部署密码管理工具。

为什么要自建密码管理器？

1. 省钱：类似于1password这种全平台软件价格很贵。
2. 全平台同步：各个手机品牌，不同的浏览器都有自己的密码管理，要么是不能全平台同步，要么就是不能所有软件都可以调用。
3. 隐私保护：除了自己搭建的密码管理器，其他所有的密码管理都是存在云端，有很大的安全风险。
4. 无限制：没有设备限制，没有同步数量限制，没有密码数量限制。

准备工作：安装1Panel

我推荐使用1Panel进行部署，这是一款现代化的Linux运维管理面板，可以通过它来轻松部署Bitwarden。

第一步：安装1Panel

在我的博客中找到这个位置，进行复制安装。

# 一键安装1Panel
bash -c "$(curl -sSL https://resource.fit2cloud.com/1panel/package/v2/quick_start.sh)"

1. 选择你需要的语言，输入对应数字按回车
2. 建议使用默认安装位置，继续回车
3. 如果没有Docker，输入y回车进行安装,他会自行部署Docker容器环境。
4. 给1panel一个访问的端口号，我这里使用700。
5. 再给一个安全入口口令，这个一定要记住，我这里使用echospace。
6. 设置登录的用户名。
7. 再设置密码，输入完成后直接按回车即可。

安装完成后，记录下显示的访问地址、用户名和密码。

第二步：登录1Panel

1. 在浏览器中访问1Panel管理界面https://你的服务器IP:端口/安全口令
2. 使用自己设置的用户名和密码进行登录

通过1Panel部署Bitwarden

第一步：进入应用商店

1. 在1Panel左侧菜单中点击"应用商店"
2. 在搜索框中输入"Bitwarden"
3. 找到Bitwarden应用并点击"安装"

第二步：配置应用参数

在安装页面中修改以下几个选项：

• 端口：默认为40031，建议你设置一个自己容易记住的端口，我这里测试使用默认的。
• 勾选端口外部访问
• 点击安装等待部署完成即可。

第三步：完成安装

1. 完成安装后，再浏览器中访问对应==ip:端口==。

第四步：管理应用

在1Panel中，你可以：

• 查看 Bitwarden 运行状态
• 启动/停止/重启服务
• 查看资源使用情况
• 查看应用日志
• 修改应用配置

第三步：创建管理员账户

1. 打开浏览器访问：http://你的服务器IP:8080
2. 点击"创建账户"
3. 填写邮箱和密码：
   • 邮箱：使用真实邮箱，用于接收通知
   • 密码：设置强密码（至少12位，包含大小写字母、数字和特殊字符）
   • 密码提示：设置一个容易记住但他人不易猜到的提示
4. 点击"创建账户"完成注册

第四步：配置客户端

电脑端配置：

1. 下载并安装Bitwarden桌面客户端
2. 打开客户端，点击登录按钮
3. 点击齿轮图标进入设置
4. 选择"自托管环境"
5. 服务器地址填写：http://你的服务器IP:8080
6. 保存设置，返回登录页面
7. 使用刚才创建的账户登录

手机端配置：

1. 在应用商店搜索并安装"Bitwarden"
2. 打开应用，点击登录
3. 点击右上角菜单，选择"设置"
4. 选择"自托管环境"
5. 输入服务器地址：http://你的服务器IP:8080
6. 返回登录页面完成登录

浏览器插件配置：

1. 在浏览器扩展商店搜索"Bitwarden"
2. 安装扩展程序
3. 点击扩展图标，选择"自托管环境"
4. 输入服务器地址并保存
5. 使用账户登录

第五步：安全配置

用户注册完成后，建议关闭新用户注册功能以提高安全性：

1. 登录1Panel管理界面
2. 在左侧菜单中点击"应用"
3. 找到已安装的Bitwarden应用，点击"设置"
4. 在"环境变量"部分找到SIGNUPS_ALLOWED
5. 将值从true修改为false
6. 点击"保存"按钮
7. 在应用管理页面点击"重启"应用配置生效

第六步：启用两步验证

1. 登录Web端：http://你的服务器IP:8080
2. 点击右上角用户名，选择"设置"
3. 选择"安全"选项卡
4. 找到"两步登录"部分
5. 选择"验证器应用"
6. 使用手机扫描二维码（需要安装认证应用如Google Authenticator）
7. 输入验证码完成设置
8. 保存恢复代码，妥善保管

使用技巧

密码生成

1. 在密码输入框右键选择"Bitwarden"
2. 选择"生成密码"
3. 设置密码长度和字符类型
4. 点击"复制密码"或"填充密码"

导入现有密码

1. 登录Web端
2. 选择"工具"
3. 选择"导入数据"
4. 选择密码管理器类型
5. 上传导出的密码文件

定期备份

通过1Panel可以轻松进行数据备份：

1. 登录1Panel管理界面
2. 在左侧菜单中点击"备份"
3. 创建新的备份计划：
   • 备份类型：应用数据
   • 应用：选择Bitwarden
   • 备份路径：/opt/1panel/backup（或自定义）
   • 备份周期：建议设置为每日或每周
   • 保留数量：根据需求设置保留的备份文件数量
4. 点击"创建"完成备份计划设置

或者手动备份：

1. 在左侧菜单中点击"应用"
2. 找到Bitwarden应用，点击"备份"
3. 点击"立即备份"创建当前数据的完整备份
4. 备份完成后可以在备份列表中下载备份文件

总结

恭喜你！现在你拥有了自己的密码管理器！再也不用：

• 支付密码管理器年费
• 担心密码数据泄露
• 受限于设备数量限制

快去体验吧！如果遇到问题，欢迎在评论区交流~

关于我

全平台同名"汪多多是只猫"，专注分享实用开源工具，让你的数字生活更自由！

关注我，发现更多自建服务的乐趣与技巧！

#密码管理 #Bitwarden #1Panel #自建服务 #网络安全

采集时间： 2026年03月29日 08:00（周日）

核心产品

Attie — Bluesky团队推出的全新独立AI应用

• 定位：AI助手，让用户通过自然语言指令构建个性化社交信息流、推荐帖子和内容
• 底层模型：基于 Anthropic 的 Claude
• 协议基础：运行在 Bluesky 开放社交协议 atproto（Atmosphere）之上
• 负责人：前CEO Jay Graber（现任首席创新官）

核心功能

1. 自然语言构建信息流：像与普通AI聊天一样，用自然语言命令构建自己的定制信息流
2. 个性化推荐：Attie能理解用户关注的话题和喜好
3. 未来愿景：支持用户「vibe-code」自己的社交应用

产品定位

「AI should serve people, not platforms.」 （AI应该服务于用户，而非平台）

Bluesky认为，当前大平台用AI服务于自身——增加用户停留时间、数据收割、控制算法。而Attie将权力直接交到用户手中。

Bluesky融资动态

Bluesky同时宣布获得1亿美元B轮融资追加资金，目前拥有超过43个月的资金储备（3年+ runway），为整个生态系统的稳定性和安全性提供保障。

商业模式探索

Bluesky暂不考虑加密货币整合（尽管有加密货币背景投资者）。可能的变现方式：

• Attie可能最终需要付费
• 订阅服务
• 为想在协议上托管自己社区的用户提供托管服务

原文链接

https://techcrunch.com/2026/03/28/bluesky-leans-into-ai-with-attie-an-app-for-building-custom-feeds/

来源：TechCrunch | 多多来报整理

原创声明：本文内容综合编译自 AIbase 及布鲁塞尔自由大学（VUB）公开研究成果，原始链接：https://www.aibase.com/news/26710

2026年3月，AI 发展史上又一个里程碑事件诞生：商业大模型首次独立完成了一个数学猜想的证明。

布鲁塞尔自由大学（VUB）发布的一项研究显示，OpenAI 开发的 ChatGPT-5.2（Thinking 版本）成功解决了数学家 Ran 和 Teng 于2024年提出的一个长期悬而未决的数学猜想。这一成果的发布，让"Vibe-Proving"这个词迅速进入科技界的视野。

从"计算器"到"证明者"

长期以来，AI 在数学领域的角色被限定为"辅助工具"——帮助验证证明步骤、处理大规模计算、搜索反例。但在理论数学的核心地带——原创猜想证明——人类数学家认为 AI 无法胜任，理由是：AI 只有归纳能力，缺乏演绎创造力。

ChatGPT-5.2 打破了这个偏见。

在 VUB 的实验中，ChatGPT-5.2 全程独立探索证明路径，构建核心逻辑框架，历经 7 轮对话交互和 4 轮自我迭代，最终形成了一套严谨的数学论证。虽然最终的形式验证仍由人类研究者完成，但 AI 在探索阶段的推演效率，已经远超人类数学家的预期。

研究团队将这一范式命名为 “Vibe-Proving”（情境证明）。“Vibe"一词借自近年科技圈流行的"vibe coding”——指开发者通过自然语言对话引导 AI 生成代码，强调直觉驱动和迭代探索，而非按部就班的传统编程。将"vibe"引入数学证明，意味着 AI 开始具备"探索者"的自主角色，而不仅仅是执行指令的计算工具。

数学界的连锁反应

VUB 教授 Vincent Ginis 在评论这一成果时表示：“这打破了’AI 只有归纳能力、没有创造力’的长期偏见。”

这个打破的影响是深远的：

证明效率的量级跃升。 一个困扰数学界数月的猜想，ChatGPT-5.2 在数小时内就探索出了可行的证明路径。如果这一能力被系统化地引入数学研究流程，理论数学的产出速度将迎来指数级增长。

跨学科的边界消融。 AI 辅助证明不再只属于纯数学领域，它正在向理论物理、计算机科学、密码学等依赖严格逻辑推理的学科渗透。可以预见，未来的重大科学突破将越来越多地出现"AI 提出猜想—AI 探索证明—人类验证意义"的协作模式。

学术规则面临重构。 当一个证明主要由 AI 独立完成时，谁应该署名？如何在同行评审中界定"AI 辅助"与"AI 独立"的边界？这些新的学术伦理问题，已经摆在了数学界的面前。

一个时代的开始

1996年，深蓝击败国际象棋冠军卡斯帕罗夫，那是 AI 在策略游戏领域登顶的时刻。2026年，ChatGPT-5.2 独立证明数学猜想，是 AI 进入人类知识生产核心领域的标志性事件。

证明的意义不同于下棋。棋局是封闭系统，有明确的胜负规则；数学猜想是开放的知识边界，每一步推理都可能通向全新的领域。AI 能在这个领域独立运作，意味着它的能力已经超出了对训练数据的简单组合，走向了某种意义上的"创造性推理"。

当然，争议与兴奋并存。有人认为这只是"高级的模式匹配"，而非真正的数学理解；也有人认为，这次证明的细节仍有待同行评审的严格检验。但无论如何，VUB 的这项研究至少提出了一个无法回避的问题：

如果 AI 可以独立探索未知，那么人类知识生产的规则，该如何重新定义？

（编译来源：AIbase / VUB 研究团队，2026年3月）

采集时间： 2026年03月28日 08:00（周六）

核心数据

关键特点

用户体验保障：

• 广告内容与ChatGPT回答完全隔离，绝不干扰AI输出结果
• 用户与AI的对话绝对私密，不会与营销部门共享
• 广告推荐不会侵入个人交流

商业逻辑：

• 对话式AI成为新的流量入口
• 精准「意图营销」可能比传统搜索广告更具爆发力

市场意义

OpenAI再次证明它不仅有改变世界的技术，还有可怕的吸金能力。

从依靠订阅费到掘金广告，OpenAI正在多元化收入结构。当对话式AI成为新流量入口时，如何在商业利益与用户信任之间取得平衡将是长期挑战。

原文链接

https://www.aibase.com/news/26626

来源：AIbase | 多多来报整理

作者：多多来报 日期：2026-04-02

一个Bug，让Claude Code的源码"裸奔"了

2026年3月的某一天，AI开发者社区发现了一件大事：Anthropic旗下最受欢迎的产品之一Claude Code的源代码，被意外泄露在了最新版本发布包中。

消息一出，开发者社区沸腾了。Claude Code是Anthropic推出的AI编程辅助工具，因其强大的代码生成与调试能力，在开发者圈层中拥有极高口碑。如今源码意外流出，GitHub上迅速涌现出大量包含泄露代码的仓库，开发者们如获至宝，疯狂研究Anthropic究竟是如何训练和调优驱动Claude Code的底层大模型（LLM）。

Anthropic很快意识到了问题的严重性，迅速采取行动。

紧急维权：一次DMCA takedown，误伤了8100个仓库

Anthropic依据美国**《数字千年版权法》（DMCA）**，向GitHub发出了正式的下架通知（takedown notice），要求GitHub移除所有包含泄露源码的仓库。

然而，这一次紧急维权行动，成了一场"误伤"事件。

据GitHub的公开记录，Anthropic的这份DMCA通知最终执行到了约8100个代码仓库——包括大量与泄露源码无关的合法项目。许多开发者愤怒地发现自己辛苦维护的开源项目，仅仅因为某种关联性（可能是fork关系或关键词匹配），被一并移除。

受影响的开发者纷纷在X（原Twitter）上发声，表达不满。

Anthropic道歉：这是个"意外"

Anthropic Claude Code负责人Boris Cherny随后在X上公开承认：这次大规模下架并非有意为之，已撤回除原始泄露仓库之外的所有通知。

Anthropic发言人也对TechCrunch表示：“被下架的仓库是原始泄露仓库的fork网络的一部分，因此下架通知的影响范围超出了预期。我们已撤回除原始仓库之外的所有通知，GitHub也已恢复了受影响fork的访问权限。”

简言之：Anthropic的本意是精准打击一个泄露源头，但由于GitHub的fork网络高度关联，DMCA通知沿着"fork链"自动扩散，最终伤及了大量无辜项目。

开源社区的"次生灾害"：信任裂痕

这起事件引发了开源社区的广泛讨论。核心争议点在于：

DMCA作为版权保护工具，是否适用于AI时代的新型代码分发模式？

Claude Code作为Anthropic的商业产品，其底层模型的训练方法、Prompt设计、工具调用框架等，对竞争对手和研究者具有极高的商业价值。当源码意外泄露，Anthropic有权通过法律手段维权——这一点没有争议。

但问题在于：AI产品的源码与开源社区的fork生态高度交织，一次"精准打击"的技术失误，就可能让大量合法开发者受到牵连。

更微妙的是，Anthropic目前正在筹备IPO。这类"源码泄露+维权失误"的组合拳，对公司声誉和合规形象而言，无疑是一记重击。正如TechCrunch在报道中所言：“Leaking your source code as a public company? You better believe there’s a shareholder lawsuit coming.”（在准备上市期间源码泄露？等着吃股东诉讼吧。）

事件时间线

结语：AI时代的版权困局

Claude Code源码泄露事件，折射出AI时代一个尚未被充分讨论的命题：当AI产品的边界越来越模糊（代码=产品=工具=开源生态），传统的版权保护机制能否适应新的现实？

Anthropic的这次"误伤"，或许将成为AI行业完善DMCA执行流程的一个重要节点——毕竟，在AI代码生态日益繁荣的今天，谁也不希望下一次"精准打击"，变成另一场8100个仓库的"无差别伤害"。

原文链接：https://techcrunch.com/2026/04/01/anthropic-took-down-thousands-of-github-repos-trying-to-yank-its-leaked-source-code-a-move-the-company-says-was-an-accident/

本文适合人群：希望在本地使用 Claude Code CLI 工具，并希望通过第三方模型（如 MiniMax）降低使用成本的开发者。

前言

Claude Code 是 Anthropic 官方推出的命令行交互工具，支持通过终端与 Claude 大模型进行对话。与网页版相比，CLI 工具更适合深度代码开发、自动化任务和工作流集成。

本文将手把手完成以下目标：

1. 通过官方包管理器安装 Claude Code
2. 安装并配置 CC-SWITCH（开源模型切换工具）
3. 添加 MiniMax 等第三方模型
4. 完成本地测试验证

官方安装 Claude Code

环境要求

使用 winget 安装（Windows）

Claude Code 支持通过 Windows 包管理器 winget 一键安装。打开命令提示符（CMD）或 PowerShell，执行以下命令：

winget install Anthropic.ClaudeCode

提示：如果你使用的是 PowerShell，命令完全相同，直接粘贴执行即可。

安装过程示意：

• 系统会弹出安装确认提示，输入 y 后按回车继续
• 等待下载与安装自动完成，通常无需人工干预
• 安装成功后，会看到类似 “Successfully installed” 的确认信息

验证安装

安装完成后，重新打开一个新的命令行窗口，输入以下命令验证是否安装成功：

claude --version

如果输出版本号（如 v1.x.x），则说明安装成功。

安装 CC-SWITCH 模型切换工具

什么是 CC-SWITCH？

CC-SWITCH（全称 Claude Code Switch）是一款开源的模型切换与管理工具，由社区开发者 farion1231 维护。它的主要功能包括：

• 多模型管理：在多个 AI 模型供应商之间快速切换
• 统一配置界面：通过 GUI 界面添加、编辑、删除模型配置，无需手动编辑配置文件
• 支持多种供应商：OpenAI、Anthropic、MiniMax、OpenRouter、Ollama 等主流模型供应商均支持
• 热切换：切换模型后无需重启 Claude Code，对话中即可切换供应商

为什么需要 CC-SWITCH？ 虽然 Claude Code 原生支持配置第三方 API 端点，但手动编辑配置文件容易出错。CC-SWITCH 提供了可视化的配置界面，大幅降低了配置复杂度。

项目地址

• GitHub 仓库：https://github.com/farion1231/cc-switch
• Releases 下载页：https://github.com/farion1231/cc-switch/releases/tag/v3.12.3

下载与安装

前往 Releases 页面，根据你的操作系统下载对应的安装包（Windows 用户下载 .exe 安装包）。

安装步骤

第一步：双击下载好的安装包，启动安装向导。

第二步：阅读许可协议，点击 “I Agree” 继续。

第三步：选择安装位置（使用默认位置即可），点击 “Install”。

第四步：等待安装进度完成。

第五步：安装完成，点击 “Finish” 退出向导。CC-SWITCH 会自动启动。

配置第三方模型

下面以 MiniMax 为例，演示如何添加一个第三方模型供应商。其他模型（如 OpenAI、Azure OpenAI 等）的配置方式类似。

启动 CC-SWITCH

安装完成后，CC-SWITCH 会自动打开主界面。如果未自动启动，可以在开始菜单中找到 “CC-SWITCH” 并手动打开。

添加供应商

1. 点击界面中的 “添加供应商” 按钮（或 “Add Provider”）

   

2. 在下拉列表中找到并选择你的模型供应商。以 MiniMax 为例，选择对应的选项：

   

3. 填写供应商的 API 地址（Base URL）。MiniMax 的 API 地址格式通常为：

   https://api.minimax.chat/v1
   

   注意：不同供应商的 API 地址格式可能不同，请参考对应供应商的官方文档。

   

4. 填写你为该供应商设置的 名称（可以自定义，如 MiniMax-2.7），然后点击 “添加” 保存配置。

   

配置 API Key

添加完供应商后，你需要在 CC-SWITCH 中配置对应的 API Key（密钥）。具体的 API Key 输入位置通常在供应商配置详情页或设置面板中。

安全提示：API Key 是访问你账户的重要凭证，请勿泄露给他人，也不要将 API Key 直接提交到公开的代码仓库中。建议在后续步骤中确认 CC-SWITCH 是否会将 Key 持久化存储在本地。

测试验证

启动 Claude Code

1. 按 Win + R，输入 cmd，回车打开命令提示符

   

2. 在 CMD 中输入 claude 并回车，启动 Claude Code：

   claude
   

   

首次配置向导

Claude Code 在首次启动时会引导你完成几个基本配置：

• TUI 主题选择：选择终端内对话界面的显示主题（深色/浅色等），使用方向键选择后回车确认

  

• 项目目录信任：选择当前目录是否受信任。直接回车使用默认选项

  

• 信任确认：选择 “Yes, I trust this directory”（我信任此目录）以继续

  

验证模型

现在你应该已经进入了 Claude Code 的交互式对话界面。输入以下问题来确认当前使用的模型：

你现在是什么模型？

如果返回了 MiniMax 相关的模型名称（如 MiniMax-2.7 或类似标识），则说明配置成功，Claude Code 正在通过 CC-SWITCH 使用第三方模型。

切换模型：后续如果需要切换到其他模型，只需在 CC-SWITCH 中切换供应商配置即可，无需重启 Claude Code 或修改任何配置文件。

常见问题（FAQ）

Q1：winget 安装失败怎么办？

确保你的 winget 是最新版本。在 PowerShell 中执行以下命令更新 winget：

winget upgrade --id Anthropic.ClaudeCode

如果网络受限，可以尝试使用代理或直接前往 Anthropic 官网下载安装包。

Q2：CC-SWITCH 支持哪些模型供应商？

截至目前，CC-SWITCH 已支持：

• Anthropic（官方 Claude）
• OpenAI（GPT 系列）
• MiniMax
• OpenRouter
• Ollama（本地模型）
• Groq
• Cloudflare Workers AI
• 以及其他兼容 OpenAI API 格式的供应商

Q3：如何查看当前使用的是哪个模型？

在 Claude Code 对话中直接发送 你现在使用的是什么模型？ 或 /model 命令（如果支持），即可查看当前模型信息。

Q4：API Key 应该填在哪里？

在 CC-SWITCH 的供应商配置页面中，找到 “API Key” 输入框并填入你的密钥。具体位置可能因版本不同而略有差异，请参考 CC-SWITCH 的 GitHub 文档。

总结

本文完成了以下内容的详细介绍：

借助 CC-SWITCH，你可以方便地在多个模型供应商之间切换，既能使用官方 Claude 模型处理复杂任务，也能在成本更低或特定场景下切换到 MiniMax 等第三方模型，实现成本与效果的最佳平衡。

关于我

全平台同名"汪多多是只猫"，专注分享实用技术教程，让你的IT学习之路更轻松！

数据来源于开发手册和网络，由EchoSpace多多智能体编写，仅供参考。

概述

CoPaw 的 Agent 架构是一个完全模块化的系统，所有核心组件均为解耦模块。这种设计使得 CoPaw 具有高度的可扩展性和可定制性。

Agent 核心架构

架构概览

┌─────────────────────────────────────────┐
│           用户交互层                      │
│  (多渠道接入：钉钉、飞书、QQ等)          │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│           消息队列层                      │
│  (消息缓冲、优先级调度、可靠投递)         │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│           Agent 核心                     │
│  ┌─────────────────────────────────┐   │
│  │  Prompt 系统                    │   │
│  └─────────────────────────────────┘   │
│  ┌─────────────────────────────────┐   │
│  │  Hooks 系统                     │   │
│  └─────────────────────────────────┘   │
│  ┌─────────────────────────────────┐   │
│  │  Tools 系统                    │   │
│  └─────────────────────────────────┘   │
│  ┌─────────────────────────────────┐   │
│  │  Memory 系统                   │   │
│  └─────────────────────────────────┘   │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│           模型层                         │
│  (云端API、本地模型、推理服务)          │
└─────────────────────────────────────────┘

核心组件

Prompt 系统

Prompt 系统架构

组件：

Prompt 系统
├── Prompt Loader (加载器)
├── Prompt Builder (构建器)
├── Prompt Renderer (渲染器)
└── Prompt Cache (缓存)

Prompt 加载

加载顺序：

# Prompt 加载顺序
FILE_ORDER = [
    ("AGENTS.md", True),    # 必需，Agent 角色定义
    ("SOUL.md", True),      # 必需，核心个性
    ("PROFILE.md", False),  # 可选，用户档案
    ("SKILLS.md", False),   # 可选，技能定义
]

示例文件：

AGENTS.md：

# Agent 角色定义

你是 CoPaw，一个智能 AI 助手。

## 角色
- 个人助理
- 信息助手
- 创意助手

## 目标
- 帮助用户解决问题
- 提供准确信息
- 生成创意内容

## 原则
- 友好
- 专业
- 准确
- 有帮助

SOUL.md：

# 核心 Soul

你是一个温暖、友善的 AI 助手。

## 性格
- 温暖：对用户充满关怀
- 友善：总是乐于助人
- 专业：提供高质量服务
- 幽默：适度使用幽默

## 价值观
- 用户至上
- 隐私保护
- 持续学习

PROFILE.md：

# 用户档案

## 基本信息
姓名：用户
语言：中文
时区：Asia/Shanghai

## 偏好
- 回答风格：简洁明了
- 详细程度：适中
- 语气：友好

## 习惯
- 工作时间：9:00-18:00
- 休息时间：12:00-13:00

Prompt 构建

构建过程：

class PromptBuilder:
    """Prompt 构建器"""
    
    def __init__(self, workspace: str):
        self.workspace = workspace
        self.prompts = {}
    
    def load_prompts(self) -> Dict[str, str]:
        """加载所有 Prompt 文件"""
        for filename, required in FILE_ORDER:
            path = os.path.join(self.workspace, filename)
            if os.path.exists(path):
                with open(path, 'r', encoding='utf-8') as f:
                    self.prompts[filename] = f.read()
            elif required:
                raise FileNotFoundError(f"必需的 Prompt 文件缺失: {filename}")
        return self.prompts
    
    def build_system_prompt(self) -> str:
        """构建系统提示词"""
        parts = []
        for filename in FILE_ORDER:
            if filename[0] in self.prompts:
                parts.append(self.prompts[filename[0]])
        return "\n\n".join(parts)

Prompt 渲染

变量替换：

class PromptRenderer:
    """Prompt 渲染器"""
    
    def render(self, template: str, variables: Dict[str, Any]) -> str:
        """渲染 Prompt"""
        from jinja2 import Template
        
        # 使用 Jinja2 模板
        template_obj = Template(template)
        return template_obj.render(**variables)

示例：

template = """
你好 {{ user_name }}！

今天是 {{ date }}，有什么可以帮你的吗？
"""

variables = {
    'user_name': '张三',
    'date': '2026-03-12'
}

result = renderer.render(template, variables)
# 输出：你好 张三！
# 今天是 2026-03-12，有什么可以帮你的吗？

Hooks 系统

Hooks 系统架构

组件：

Hooks 系统
├── Hook Registry (注册表)
├── Hook Executor (执行器)
├── Hook Middleware (中间件)
└── Hook Context (上下文)

Hook 类型

Pre-LLM Hooks（LLM 调用前）：

• pre_reasoning：推理前处理
• pre_compaction：压缩前处理
• pre_validation：验证前处理

Post-LLM Hooks（LLM 调用后）：

• post_compaction：压缩后处理
• post_validation：验证后处理
• post_processing：后处理

Hook 示例

自定义 Hook：

from copaw.hooks import Hook, HookContext

class CustomHook(Hook):
    """自定义 Hook"""
    
    def __init__(self, config: Dict[str, Any]):
        super().__init__(config)
        self.enabled = config.get('enabled', True)
    
    async def before_llm_call(self, context: HookContext) -> None:
        """LLM 调用前"""
        if not self.enabled:
            return
        
        # 自定义逻辑
        context.data['custom_value'] = 'custom'
        self.log("Pre-LLM hook executed")
    
    async def after_llm_call(self, context: HookContext) -> None:
        """LLM 调用后"""
        if not self.enabled:
            return
        
        # 自定义逻辑
        result = context.data.get('result')
        self.log(f"Post-LLM hook executed: {result}")
    
    def log(self, message: str) -> None:
        """记录日志"""
        print(f"[CustomHook] {message}")

注册 Hook：

from copaw.hooks import HookRegistry

# 注册 Hook
registry = HookRegistry()
registry.register('custom', CustomHook)

# 使用 Hook
hook = registry.get('custom')
await hook.before_llm_call(context)

Hook 链

Hook 链执行：

class HookChain:
    """Hook 链"""
    
    def __init__(self, hooks: List[Hook]):
        self.hooks = hooks
    
    async def execute_before(self, context: HookContext) -> None:
        """执行所有 Pre-Hooks"""
        for hook in self.hooks:
            await hook.before_llm_call(context)
    
    async def execute_after(self, context: HookContext) -> None:
        """执行所有 Post-Hooks"""
        for hook in reversed(self.hooks):
            await hook.after_llm_call(context)

Tools 系统

Tools 系统架构

组件：

Tools 系统
├── Tool Registry (注册表)
├── Tool Manager (管理器)
├── Tool Executor (执行器)
└── Tool Cache (缓存)

内置工具

文件操作工具：

class ReadFileTool(Tool):
    """读取文件工具"""
    
    name = "read_file"
    description = "读取文件内容"
    
    async def execute(self, file_path: str) -> str:
        """执行工具"""
        with open(file_path, 'r', encoding='utf-8') as f:
            return f.read()

网络搜索工具：

class WebSearchTool(Tool):
    """网络搜索工具"""
    
    name = "web_search"
    description = "搜索网络信息"
    
    async def execute(self, query: str) -> List[Dict[str, Any]]:
        """执行工具"""
        # 调用搜索 API
        results = await self.search_api.search(query)
        return results

计算器工具：

class CalculatorTool(Tool):
    """计算器工具"""
    
    name = "calculator"
    description = "数学计算"
    
    async def execute(self, expression: str) -> float:
        """执行工具"""
        # 安全计算
        result = eval(expression, {'__builtins__': {}}, {})
        return result

自定义工具

创建自定义工具：

from copaw.tools import Tool

class CustomTool(Tool):
    """自定义工具"""
    
    name = "custom_tool"
    description = "自定义工具描述"
    
    def __init__(self, config: Dict[str, Any]):
        super().__init__(config)
        self.param1 = config.get('param1', 'default')
    
    async def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
        """执行工具"""
        try:
            result = self.process(input_data)
            return {
                'success': True,
                'result': result
            }
        except Exception as e:
            return {
                'success': False,
                'error': str(e)
            }
    
    def process(self, input_data: Dict[str, Any]) -> Any:
        """处理输入数据"""
        # 处理逻辑
        return processed_result

注册工具：

from copaw.tools import ToolRegistry

# 注册工具
registry = ToolRegistry()
registry.register('custom', CustomTool)

# 使用工具
tool = registry.get('custom')
result = await tool.execute({'param': 'value'})

工具链

工具链执行：

class ToolChain:
    """工具链"""
    
    def __init__(self, tools: List[Tool]):
        self.tools = tools
    
    async def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
        """执行工具链"""
        current_data = input_data
        
        for tool in self.tools:
            result = await tool.execute(current_data)
            if result.get('success'):
                current_data = result.get('result')
            else:
                return {
                    'success': False,
                    'error': result.get('error'),
                    'failed_at': tool.name
                }
        
        return {
            'success': True,
            'result': current_data
        }

Memory 系统

Memory 系统架构

组件：

Memory 系统
├── Memory Manager (管理器)
├── Memory Storage (存储)
├── Memory Retriever (检索器)
└── Memory Index (索引)

记忆存储

文件存储：

class FileMemoryStorage:
    """文件存储"""
    
    def __init__(self, path: str):
        self.path = path
        os.makedirs(path, exist_ok=True)
    
    async def save(self, key: str, value: Any) -> None:
        """保存记忆"""
        file_path = os.path.join(self.path, f"{key}.json")
        with open(file_path, 'w', encoding='utf-8') as f:
            json.dump(value, f, ensure_ascii=False)
    
    async def load(self, key: str) -> Optional[Any]:
        """加载记忆"""
        file_path = os.path.join(self.path, f"{key}.json")
        if os.path.exists(file_path):
            with open(file_path, 'r', encoding='utf-8') as f:
                return json.load(f)
        return None

数据库存储：

class DatabaseMemoryStorage:
    """数据库存储"""
    
    def __init__(self, connection_string: str):
        self.connection_string = connection_string
        self.pool = await self.create_pool()
    
    async def save(self, key: str, value: Any) -> None:
        """保存记忆"""
        async with self.pool.acquire() as conn:
            await conn.execute(
                "INSERT INTO memories (key, value) VALUES ($1, $2)",
                key, json.dumps(value)
            )
    
    async def load(self, key: str) -> Optional[Any]:
        """加载记忆"""
        async with self.pool.acquire() as conn:
            record = await conn.fetchrow(
                "SELECT value FROM memories WHERE key = $1",
                key
            )
            return json.loads(record['value']) if record else None

记忆检索

语义检索：

class SemanticMemoryRetriever:
    """语义检索"""
    
    def __init__(self, index: Any):
        self.index = index
    
    async def search(self, query: str, top_k: int = 5) -> List[Dict[str, Any]]:
        """语义搜索"""
        # 向量化查询
        query_vector = self.embed(query)
        
        # 搜索最相似的
        results = self.index.search(query_vector, top_k)
        
        return results
    
    def embed(self, text: str) -> List[float]:
        """文本向量化"""
        # 调用嵌入模型
        return self.embedding_model.embed(text)

记忆整合

记忆整合：

class MemoryConsolidator:
    """记忆整合"""
    
    async def consolidate(self, memories: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
        """整合记忆"""
        # 按相似度分组
        groups = self.group_by_similarity(memories)
        
        # 合并相似记忆
        consolidated = []
        for group in groups:
            if len(group) > 1:
                merged = self.merge_group(group)
                consolidated.append(merged)
            else:
                consolidated.append(group[0])
        
        return consolidated
    
    def group_by_similarity(self, memories: List[Dict[str, Any]]) -> List[List[Dict[str, Any]]]:
        """按相似度分组"""
        # 实现分组逻辑
        pass
    
    def merge_group(self, group: List[Dict[str, Any]]) -> Dict[str, Any]:
        """合并记忆组"""
        # 实现合并逻辑
        pass

Agent 循环

ReAct 循环

循环流程：

开始
  │
  ├─→ 接收用户消息
  │
  ├─→ Pre-Hooks
  │
  ├─→ 构建 Prompt
  │
  ├─→ 调用 LLM
  │
  ├─→ Post-Hooks
  │
  ├─→ 判断是否需要工具
  │   ├─ 是 → 执行工具 → 更新上下文 → 继续
  │   └─ 否 → 继续下一步
  │
  ├─→ 压缩上下文（如果需要）
  │
  ├─→ 判断是否完成
  │   ├─ 否 → 返回构建 Prompt 步骤
  │   └─ 是 → 继续下一步
  │
  └─→ 返回结果

上下文压缩

压缩策略：

class ContextCompactor:
    """上下文压缩器"""
    
    def __init__(self, config: Dict[str, Any]):
        self.threshold = config.get('threshold', 0.8)
        self.keep_recent = config.get('keep_recent', 5)
    
    async def compact(self, messages: List[Dict[str, Any]], max_length: int) -> List[Dict[str, Any]]:
        """压缩上下文"""
        current_length = self.calculate_length(messages)
        
        if current_length <= max_length:
            return messages
        
        # 压缩策略
        compressed = []
        
        # 保留最近的 N 条消息
        recent = messages[-self.keep_recent:]
        compressed.extend(recent)
        
        # 压缩中间部分
        middle = messages[self.keep_recent:-self.keep_recent]
        if middle:
            summary = await self.summarize(middle)
            compressed.insert(0, {
                'role': 'system',
                'content': f"[摘要] {summary}"
            })
        
        return compressed
    
    def calculate_length(self, messages: List[Dict[str, Any]]) -> int:
        """计算上下文长度"""
        length = 0
        for msg in messages:
            length += len(msg.get('content', ''))
        return length
    
    async def summarize(self, messages: List[Dict[str, Any]]) -> str:
        """总结消息"""
        # 调用 LLM 总结
        pass

最佳实践

模块化设计

原则：

• 单一职责：每个组件只做一件事
• 低耦合：组件之间依赖最小化
• 高内聚：相关功能集中在一起
• 可测试：每个组件都可独立测试

性能优化

优化策略：

• 异步处理：使用异步 I/O
• 缓存机制：缓存频繁访问的数据
• 批处理：批量处理相似请求
• 资源池：使用连接池和线程池

错误处理

错误处理策略：

• 优雅降级：失败时提供备用方案
• 错误恢复：自动恢复机制
• 日志记录：详细记录错误信息
• 用户反馈：及时向用户反馈错误

资源链接

• CoPaw 架构文档: https://copaw.bot/docs/architecture
• AgentScope 文档: https://github.com/modelscope/agentscope
• 架构设计模式: https://copaw.bot/docs/patterns

最后更新: 2026-03-12 作者: EchoHaoRan

概述

CoPaw（协作个人智能体工作站）是基于 AgentScope 框架构建的开源个人 AI 助手。支持本地或云端部署，连接你常用的聊天应用，运行本地大模型，完全掌控隐私。

CoPaw 是什么

产品定位

CoPaw 是一个协作个人智能体工作站，让你完全掌控你的 AI 助手 —— 从运行的模型到连接的渠道。

核心理念：

• 一只温暖的小"爪"，随时准备帮助你
• 你的数字生活好帮手
• 完全用户掌控与隐私保护

核心特性

CoPaw 的强大之处

多渠道聊天集成

原生连接钉钉、飞书、QQ、Discord、iMessage 等平台。

优势：

• 一个助手，多个渠道
• 在你沟通的任何地方使用 AI
• 统一的渠道协议确保一致行为

支持的平台：

• 钉钉
• 飞书
• QQ
• Discord
• iMessage
• 可扩展：自定义渠道插件

本地大模型运行

在本地完整运行大语言模型，无需 API 密钥，无需云依赖。

支持的后端：

• llama.cpp（跨平台）：macOS、Linux、Windows
• MLX（Apple Silicon）：M1、M2、M3、M4 优化

优势：

• 完全隐私保护
• 无网络依赖
• 无 API 费用
• 数据不上传

模块化 Agent 架构

CoPaw 的 Agent 核心完全模块化，所有组件均为解耦组件。

核心模块：

• Prompt：提示词管理
• Hooks：钩子系统
• Tools：工具集
• Memory：记忆系统

优势：

• 可独立替换或扩展任何模块
• 组装你自己的 Agent
• 高度可定制化
• 无厂商锁定

可扩展技能系统

内置定时调度和自定义技能，从工作区自动加载。

技能特点：

• CoPaw 开箱即用提供实用技能
• 开发者可通过 CLI 创建、安装或移除技能
• 无厂商锁定
• 技能是一等公民 —— 可发现、可组合、可独立部署

长期记忆与心跳

CoPaw 通过长期记忆系统主动记住你的决策、偏好和待办事项。

创新机制：

• 心跳机制：自主执行定时任务
• 查收邮件
• 汇编报告
• 整理待办
• 无需你主动开口

完全用户掌控与隐私

你拥有每一份数据。

部署选择：

• 本地部署
• 云端部署
• 自托管推理
• Ollama 集成
• Apple Silicon 本地运行

掌控范围：

• 模型选择
• 数据存储
• 渠道配置
• 技能管理

基于 AgentScope 框架构建

AgentScope 简介

CoPaw 是 AgentScope 生态系统中的关键应用 —— 一个面向生产环境、以开发者为中心的智能体构建与运行框架。

技术栈：

• Python（72.8%）：后端逻辑
• TypeScript（22.2%）：Console 前端

核心组件

模型管理

统一模型层，支持：

• 云端 API（Qwen 系列及主流模型）
• 自托管推理服务
• Ollama
• llama.cpp
• MLX 本地运行（Apple Silicon）

Agent 核心

解耦模块，可独立替换或扩展：

• Prompt
• Hooks
• Tools
• Memory

开发者从可互换的构建块组装 Agent。

渠道层

所有消息平台统一协议和类型：

• 渠道注册机制
• CLI 命令管理
• 像管理插件一样管理渠道

CLI 命令：

• list：列出已安装渠道
• install：安装新渠道
• remove：移除渠道
• config：配置渠道

消息队列

内置消费和队列机制，确保：

• 跨多个并发渠道的可靠消息处理
• 即使在高负载下也不会丢失消息

技能引擎

从用户工作区自动加载技能，内置定时调度。

技能特性：

• 一等公民
• 可发现
• 可组合
• 可独立部署

记忆系统

持久化长期记忆，主动从对话中捕获：

• 决策
• 偏好
• 待办事项

你使用 CoPaw 越久，它就越了解你。

一个 CoPaw 助手，随需连接

多平台集成

CoPaw 原生集成你已在使用的消息平台：

• 钉钉
• 飞书
• QQ
• Discord
• iMessage

统一渠道协议

统一的渠道协议确保：

• 跨每个连接平台的一致行为
• 可靠的消息投递

自定义渠道

开发者可使用渠道注册机制构建自定义渠道插件。

CLI 管理：

• 安装新渠道
• 移除现有渠道
• 配置渠道参数

像管理包一样管理你的消息集成。

你的数字生活好帮手

社交与资讯聚合

功能：

• 自动汇编小红书、知乎、Reddit 每日热门帖子
• 总结 Bilibili 和 YouTube 视频
• 不再信息过载，轻松保持信息灵通

工作效率

功能：

• 聚合并总结大量邮件
• 一键生成和整理周报
• 从邮件和日历事件中提取联系人
• 简化你的工作流

创意工作流

功能：

• 描述你的创作目标
• 让 CoPaw 通宵工作
• 第二天早上收到精心打磨的草稿
• 从视频脚本到社交媒体内容 —— 大规模创意生成

研究与知识

功能：

• 自动追踪科技和 AI 新闻
• 构建随你成长的个人知识库
• 从网络中爬取、整理和总结信息

桌面助手

功能：

• 整理文件
• 阅读和总结文档
• 通过聊天界面请求文件
• CoPaw 连接你的桌面和消息应用

健康与生活

功能：

• 追踪和分析你的日常饮食和健身数据
• 记录习惯
• 设置日常提醒
• 让 CoPaw 帮助你坚持个人目标

CoPaw 对比分析

核心优势：

• 唯一同时支持多渠道聊天 + 本地模型 + 完全隐私控制的个人 AI 助手
• 基于开源框架，无厂商锁定
• 模块化架构，高度可定制

CoPaw 与 AgentScope 的关系

AgentScope 框架

AgentScope 是一个面向生产环境、以开发者为中心的智能体构建与运行框架，内置工具和模型集成支持。

CoPaw 的角色

CoPaw 是 AgentScope 生态系统中的：

• 参考实现：展示框架的最佳实践
• 关键应用：基于框架构建的实际应用
• 能力展示：利用框架抽象和能力提供个人 AI 助手功能

学术背景

AgentScope 生态系统已在学术出版物中被引用，包括 arXiv 上的 “AgentScope 1.0: A Developer-Centric Framework for Building Agentic Applications”，展示了：

• 学术严谨性
• 生产就绪性
• 持续创新

开源且不断壮大

社区数据

维护团队

CoPaw 由 AgentScope AI 团队构建和维护，积极欢迎社区贡献。

社区参与

无论你想：

• 提交 Pull Request
• 报告问题
• 构建自定义技能
• 构建渠道插件

CoPaw 社区都是开放且不断壮大的。

文档支持

文档同时提供：

• 英文版本
• 中文版本

支持全球开发者。

CoPaw 路线图

大小模型协作

目标：平衡安全性、性能和能力

实现：

• 轻量级本地模型处理隐私和敏感数据
• 强大的云端模型负责规划、编程和复杂推理

多模态交互

目标：更丰富、更自然的交互方式

实现：

• 与 CoPaw 个人助手进行语音通话
• 与 CoPaw 个人助手进行视频通话
• 超越文本的交互方式

生态扩展

目标：打造更强大的个人 Agent

实现：

• 发展技能市场
• 拓宽渠道支持
• 深化 AgentScope 框架集成

资源链接

• 官方网站: https://copaw.bot
• 官方文档: https://copaw.bot/docs
• GitHub 仓库: https://github.com/modelscope/agentscope
• AgentScope 文档: https://github.com/modelscope/agentscope

最后更新: 2026-03-12 作者: EchoHaoRan

概述

CoPaw 原生支持多种聊天平台，让你可以在你沟通的任何地方使用 AI。统一的渠道协议确保跨每个连接平台的一致行为和可靠投递。

支持的渠道

渠道管理

渠道 CLI 命令

查看可用渠道：

copaw channels list

安装渠道：

copaw channels install <channel-name>

移除渠道：

copaw channels remove <channel-name>

配置渠道：

copaw channels config <channel-name>

查看渠道状态：

copaw channels status

渠道配置文件

channels.yaml：

# ~/.copaw/config/channels.yaml

# 钉钉
dingtalk:
  enabled: true
  app_key: "your-app-key"
  app_secret: "your-app-secret"
  callback_url: "https://your-domain.com/callback/dingtalk"

# 飞书
feishu:
  enabled: true
  app_id: "your-app-id"
  app_secret: "your-app-secret"
  encrypt_key: "your-encrypt-key"
  verification_token: "your-verification-token"

# QQ
qq:
  enabled: true
  bot_id: "your-bot-id"
  bot_token: "your-bot-token"

# Discord
discord:
  enabled: true
  bot_token: "your-bot-token"
  guild_id: "your-guild-id"

# iMessage
imessage:
  enabled: true
  phone_number: "your-phone-number"

钉钉配置

创建钉钉应用

步骤：

1. 访问钉钉开放平台：https://open.dingtalk.com/
2. 登录账户
3. 点击"创建应用"
4. 选择"企业内部应用"
5. 填写应用信息：
   • 应用名称：CoPaw 助手
   • 应用图标：上传图片
   • 应用描述：AI 智能助手

获取凭证

获取 App Key 和 App Secret：

1. 进入应用详情页
2. 点击左侧"凭证与基础信息"
3. 复制 App Key 和 App Secret

配置机器人

步骤：

1. 在应用详情页，点击左侧"添加应用能力"
2. 找到"机器人"卡片，点击"添加"
3. 打开"机器人配置"开关
4. 配置消息接收模式：
   • Stream 模式（推荐）：实时流式响应
   • HTTP 模式：传统请求-响应
5. 配置机器人消息预览
6. 点击"发布"

发布应用版本

步骤：

1. 点击左侧"版本管理与发布"
2. 点击"创建新版本"
3. 填写版本信息：
   • 版本号：1.0.0
   • 版本描述：初始版本
   • 应用可见范围：选择"全员可用"
4. 点击"保存"和"确认发布"

配置 CoPaw

配置文件：

# channels.yaml
dingtalk:
  enabled: true
  app_key: "YOUR_APP_KEY"
  app_secret: "YOUR_APP_SECRET"
  callback_url: "https://your-domain.com/callback/dingtalk"
  features:
    stream_mode: true
    message_preview: true

CLI 配置：

# 安装钉钉渠道
copaw channels install dingtalk

# 配置钉钉
copaw channels config dingtalk

测试连接：

# 测试钉钉连接
copaw channels test dingtalk

使用钉钉机器人

在钉钉中：

1. 创建群聊
2. 进入群设置 → 机器人管理
3. 点击"添加机器人"
4. 搜索你创建的机器人
5. 添加机器人到群
6. 在群中 @机器人 进行对话

飞书配置

创建飞书应用

步骤：

1. 访问飞书开放平台：https://open.feishu.cn/
2. 登录账户
3. 点击"创建企业自建应用"
4. 填写应用信息：
   • 应用名称：CoPaw 助手
   • 应用描述：AI 智能助手

配置应用权限

必需权限：

• im:message
• im:message.group_at_msg
• im:message:send_as_bot

步骤：

1. 进入应用详情页
2. 点击左侧"权限管理"
3. 添加必需权限
4. 申请权限审核

配置事件订阅

步骤：

1. 在飞书开放平台配置事件订阅
2. 设置加密 Key 和验证 Token
3. 启用需要的事件类型

配置 CoPaw

配置文件：

# channels.yaml
feishu:
  enabled: true
  app_id: "YOUR_APP_ID"
  app_secret: "YOUR_APP_SECRET"
  encrypt_key: "YOUR_ENCRYPT_KEY"
  verification_token: "YOUR_VERIFICATION_TOKEN"
  features:
    messages:
      text: true
      post: true
      interactive: true
    cards: true
    buttons: true

CLI 配置：

# 安装飞书渠道
copaw channels install feishu

# 配置飞书
copaw channels config feishu

QQ 配置

创建 QQ 机器人

步骤：

1. 访问 QQ 机器人开放平台
2. 创建机器人应用
3. 获取 Bot ID 和 Bot Token

配置 CoPaw

配置文件：

# channels.yaml
qq:
  enabled: true
  bot_id: "YOUR_BOT_ID"
  bot_token: "YOUR_BOT_TOKEN"
  features:
    group_chat: true
    private_chat: true

CLI 配置：

# 安装 QQ 渠道
copaw channels install qq

# 配置 QQ
copaw channels config qq

Discord 配置

创建 Discord 应用

步骤：

1. 访问 Discord Developer Portal：https://discord.com/developers/applications
2. 点击 “New Application” 创建应用
3. 进入 “Bot” 标签页，点击 “Add Bot”
4. 复制 Bot Token

配置 Bot 权限

必需权限：

• Send Messages
• Read Message History
• Embed Links
• Attach Files

步骤：

1. 在应用设置中配置 OAuth2
2. 设置 Scopes 和 Bot Permissions
3. 生成邀请链接

邀请 Bot 到服务器

邀请 URL 格式：

https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=8&scope=bot%20applications.commands

配置 CoPaw

配置文件：

# channels.yaml
discord:
  enabled: true
  bot_token: "YOUR_BOT_TOKEN"
  guild_id: "YOUR_GUILD_ID"
  features:
    slash_commands: true
    message_commands: true
    embeds: true
    reactions: true

CLI 配置：

# 安装 Discord 渠道
copaw channels install discord

# 配置 Discord
copaw channels config discord

iMessage 配置

前提条件

系统要求：

• macOS 10.15+
• Python 3.10+
• iMessage 访问权限

配置 CoPaw

配置文件：

# channels.yaml
imessage:
  enabled: true
  phone_number: "YOUR_PHONE_NUMBER"
  features:
    group_chat: true
    private_chat: true
    send_files: true

CLI 配置：

# 安装 iMessage 渠道
copaw channels install imessage

# 配置 iMessage
copaw channels config imessage

使用 iMessage

发送消息：

在 iMessage 中向 CoPaw 发送消息

接收回复：

CoPaw 会直接在 iMessage 中回复

自定义渠道

创建自定义渠道

步骤：

1. 创建渠道插件目录
2. 实现渠道接口
3. 注册渠道
4. 配置渠道

渠道接口

BaseChannel 类：

from abc import ABC, abstractmethod
from typing import List, Dict, Any

class BaseChannel(ABC):
    """渠道基类"""
    
    @abstractmethod
    def initialize(self, config: Dict[str, Any]) -> bool:
        """初始化渠道"""
        pass
    
    @abstractmethod
    def send_message(self, recipient: str, message: str) -> bool:
        """发送消息"""
        pass
    
    @abstractmethod
    def receive_message(self) -> List[Dict[str, Any]]:
        """接收消息"""
        pass
    
    @abstractmethod
    def cleanup(self) -> bool:
        """清理资源"""
        pass

注册渠道

注册渠道：

# channels/custom_channel.py
from copaw.channels import BaseChannel
from copaw.channels.registry import register_channel

@register_channel("custom")
class CustomChannel(BaseChannel):
    """自定义渠道"""
    
    def initialize(self, config: Dict[str, Any]) -> bool:
        """初始化渠道"""
        self.config = config
        # 初始化逻辑
        return True
    
    def send_message(self, recipient: str, message: str) -> bool:
        """发送消息"""
        # 发送逻辑
        return True
    
    def receive_message(self) -> List[Dict[str, Any]]:
        """接收消息"""
        # 接收逻辑
        return []
    
    def cleanup(self) -> bool:
        """清理资源"""
        # 清理逻辑
        return True

使用自定义渠道

配置文件：

# channels.yaml
custom:
  enabled: true
  config:
    param1: "value1"
    param2: "value2"

CLI 命令：

# 安装自定义渠道
copaw channels install custom

# 配置自定义渠道
copaw channels config custom

渠道同步

消息同步

同步配置：

# config/sync.yaml
sync:
  enabled: true
  rules:
    - from: "dingtalk"
      to: ["feishu", "qq"]
      filter: "important"
    - from: "discord"
      to: ["qq"]
      filter: "all"

状态同步

状态同步配置：

# config/sync.yaml
status_sync:
  enabled: true
  sync_presence: true  # 同步在线状态
  sync_typing: true  # 同步输入状态

渠道安全

访问控制

用户白名单：

# channels.yaml
dingtalk:
  enabled: true
  allowed_users:
    - "user1@example.com"
    - "user2@example.com"
  allowed_groups:
    - "group1"
    - "group2"

消息过滤

过滤配置：

# config/filters.yaml
filters:
  enabled: true
  rules:
    - type: "spam"
      action: "block"
    - type: "malicious"
      action: "quarantine"
    - type: "sensitive"
      action: "redact"

故障排查

钉钉连接失败

检查项：

• App Key 和 App Secret 是否正确
• 应用是否已发布
• 机器人是否已添加到群
• 网络连接是否正常

解决方案：

# 测试连接
copaw channels test dingtalk

# 查看日志
copaw logs | grep dingtalk

# 重新配置
copaw channels config dingtalk

飞书无响应

检查项：

• App ID 和 App Secret 是否正确
• 权限是否已申请
• 事件订阅是否正确配置

解决方案：

# 测试连接
copaw channels test feishu

# 查看日志
copaw logs | grep feishu

# 重新配置
copaw channels config feishu

Discord Bot 无响应

检查项：

• Bot Token 是否正确
• Bot 权限是否正确
• Bot 是否已邀请到服务器

解决方案：

# 测试连接
copaw channels test discord

# 查看日志
copaw logs | grep discord

# 重新配置
copaw channels config discord

最佳实践

渠道选择

性能优化

• 批量处理：启用批量消息处理
• 消息队列：使用消息队列处理高并发
• 缓存机制：缓存频繁查询的数据
• 限流控制：配置适当的限流策略

安全建议

• 保护凭证：不要在代码中硬编码凭证
• 使用环境变量：敏感信息使用环境变量存储
• 定期轮换密钥：定期更换 Bot Token
• 监控异常行为：监控异常访问和行为

资源链接

• 钉钉开放平台: https://open.dingtalk.com/
• 飞书开放平台: https://open.feishu.cn/
• Discord 开发者门户: https://discord.com/developers/applications
• CoPaw 渠道文档: https://copaw.bot/docs/channels

最后更新: 2026-03-12 作者: EchoHaoRan

概述

本指南详细介绍 CoPaw 的各种安装和部署方式，帮助你根据自己的需求选择最适合的方案。

部署方式概览

系统要求

硬件要求

软件要求

本地模型硬件要求

pip 安装

安装步骤

步骤 1：检查 Python 版本

python --version
# 确保版本 >= 3.10

步骤 2：升级 pip

pip install --upgrade pip

步骤 3：安装 CoPaw

pip install copaw

步骤 4：初始化配置

copaw init --defaults

步骤 5：启动应用

copaw app

步骤 6：访问控制台

在浏览器中打开: http://127.0.0.1:8088/

高级安装选项

从源码安装：

git clone https://github.com/modelscope/agentscope.git
cd agentscope
pip install -e .

使用镜像源：

pip install copaw -i https://pypi.tuna.tsinghua.edu.cn/simple

指定版本：

pip install copaw==1.0.0

环境变量配置

# 设置模型 API 密钥
export OPENAI_API_KEY="your-api-key"
export ANTHROPIC_API_KEY="your-api-key"

# 设置 CoPaw 配置
export COPAW_PORT=8088
export COPAW_LOG_LEVEL=INFO
export COPAW_WORK_DIR=~/.copaw

一键安装脚本

macOS / Linux

安装脚本：

curl -fsSL https://copaw.agentscope.io/install.sh | bash

脚本功能：

• 自动检查 Python 版本
• 安装 Python 依赖
• 配置环境变量
• 初始化 CoPaw

Windows PowerShell

安装脚本：

# 请参阅官方文档了解详细的 PowerShell 安装方式
# https://copaw.bot/docs/install/windows.html

验证安装

# 检查 CoPaw 版本
copaw --version

# 检查配置
copaw config show

# 启动应用
copaw app

Docker 部署

基础部署

步骤 1：拉取镜像

docker pull agentscope/copaw:latest

步骤 2：运行容器

docker run -d \
  --name copaw \
  -p 8088:8088 \
  -v copaw-data:/app/working \
  agentscope/copaw:latest

步骤 3：访问控制台

在浏览器中打开: http://127.0.0.1:8088/

Docker Compose 部署

docker-compose.yml：

version: '3.8'

services:
  copaw:
    image: agentscope/copaw:latest
    container_name: copaw
    ports:
      - "8088:8088"
    volumes:
      - copaw-data:/app/working
      - copaw-config:/app/config
      - copaw-logs:/app/logs
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - COPAW_LOG_LEVEL=INFO
    restart: unless-stopped

volumes:
  copaw-data:
  copaw-config:
  copaw-logs:

启动服务：

docker-compose up -d

高级 Docker 配置

自定义配置：

docker run -d \
  --name copaw \
  -p 8088:8088 \
  -v copaw-data:/app/working \
  -v ./config:/app/config \
  -v ./skills:/app/skills \
  -e OPENAI_API_KEY="your-api-key" \
  -e COPAW_PORT=8088 \
  --restart unless-stopped \
  agentscope/copaw:latest

资源限制：

docker run -d \
  --name copaw \
  --cpus="2.0" \
  --memory="4g" \
  -p 8088:8088 \
  -v copaw-data:/app/working \
  agentscope/copaw:latest

Docker 管理

查看日志：

docker logs -f copaw

重启容器：

docker restart copaw

停止容器：

docker stop copaw

删除容器：

docker rm copaw

云端部署

ModelScope Studio 部署

步骤：

1. 访问 ModelScope Studio
2. 登录账户
3. 搜索 CoPaw
4. 点击一键部署
5. 配置参数
6. 等待部署完成

配置参数：

• 选择实例类型
• 设置存储容量
• 配置环境变量
• 设置访问权限

阿里云计算巢部署

步骤：

1. 登录阿里云控制台
2. 进入计算巢服务
3. 搜索 CoPaw
4. 点击创建服务实例
5. 配置参数
6. 提交创建

其他云平台

支持的平台：

• 阿里云
• 腾讯云
• AWS
• Google Cloud
• Azure

源码部署

克隆仓库

git clone https://github.com/modelscope/agentscope.git
cd agentscope

创建虚拟环境

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# macOS / Linux
source venv/bin/activate
# Windows
venv\Scripts\activate

安装依赖

# 安装 CoPaw
pip install -e .

# 或安装开发依赖
pip install -e ".[dev]"

配置环境

# 初始化配置
python -m copaw.cli init --defaults

# 设置环境变量
export COPAW_ROOT_DIR=$(pwd)
export COPAW_CONFIG_DIR=$(pwd)/config

运行 CoPaw

# 开发模式运行
python -m copaw.cli app

# 或使用 CLI
copaw app

开发工具

代码格式化：

black copaw/
isort copaw/

运行测试：

pytest tests/

检查类型：

mypy copaw/

配置管理

配置文件位置

主配置文件

config.yaml：

# CoPaw 主配置文件

# 应用配置
app:
  name: "CoPaw"
  version: "1.0.0"
  port: 8088
  host: "0.0.0.0"

# 日志配置
logging:
  level: "INFO"
  file: "logs/copaw.log"
  max_size: "10M"
  max_files: 10

# 模型配置
models:
  default: "gpt-4o-mini"
  providers:
    - name: "openai"
      api_key: "${OPENAI_API_KEY}"
    - name: "anthropic"
      api_key: "${ANTHROPIC_API_KEY}"

# 渠道配置
channels:
  enabled:
    - "dingtalk"
    - "feishu"
    - "qq"

# 技能配置
skills:
  enabled: true
  auto_load: true
  directory: "workspace/skills"

# 记忆配置
memory:
  enabled: true
  max_entries: 1000
  retention_days: 365

模型配置

models.yaml：

# 模型配置文件

# 云端模型
providers:
  openai:
    base_url: "https://api.openai.com/v1"
    api_key: "${OPENAI_API_KEY}"
    models:
      - id: "gpt-4o"
        name: "GPT-4o"
      - id: "gpt-4o-mini"
        name: "GPT-4o Mini"

  anthropic:
    base_url: "https://api.anthropic.com"
    api_key: "${ANTHROPIC_API_KEY}"
    models:
      - id: "claude-opus-4"
        name: "Claude Opus 4"
      - id: "claude-sonnet-4"
        name: "Claude Sonnet 4"

# 本地模型
local:
  llama_cpp:
    enabled: false
    model_path: "~/.local/models/llama.cpp"
  
  mlx:
    enabled: false
    model_path: "~/.local/models/mlx"

渠道配置

channels.yaml：

# 渠道配置文件

# 钉钉
dingtalk:
  enabled: true
  app_key: "your-app-key"
  app_secret: "your-app-secret"

# 飞书
feishu:
  enabled: true
  app_id: "your-app-id"
  app_secret: "your-app-secret"

# QQ
qq:
  enabled: true
  bot_id: "your-bot-id"
  bot_token: "your-bot-token"

# Discord
discord:
  enabled: false
  bot_token: "your-bot-token"

# iMessage
imessage:
  enabled: false
  phone_number: "your-phone-number"

升级和维护

升级 CoPaw

pip 安装：

# 检查更新
pip list --outdated | grep copaw

# 升级到最新版本
pip install --upgrade copaw

# 升级到指定版本
pip install copaw==1.1.0

Docker 部署：

# 拉取最新镜像
docker pull agentscope/copaw:latest

# 重新创建容器
docker-compose up -d --force-recreate

源码部署：

# 拉取最新代码
git pull origin main

# 重新安装
pip install -e .

备份和恢复

备份配置和数据：

# 创建备份目录
mkdir -p ~/copaw-backup

# 备份配置
cp -r ~/.copaw/config ~/copaw-backup/

# 备份数据
cp -r ~/.copaw/workspace ~/copaw-backup/

# 备份记忆
cp -r ~/.copaw/memory ~/copaw-backup/

# 打包备份
tar -czf copaw-backup-$(date +%Y%m%d).tar.gz ~/copaw-backup

恢复配置和数据：

# 解压备份
tar -xzf copaw-backup-20260312.tar.gz -C ~/

# 恢复配置
cp -r ~/copaw-backup/config ~/.copaw/

# 恢复数据
cp -r ~/copaw-backup/workspace ~/.copaw/

# 恢复记忆
cp -r ~/copaw-backup/memory ~/.copaw/

日志管理

查看日志：

# 实时查看日志
tail -f ~/.copaw/logs/copaw.log

# 查看错误日志
grep ERROR ~/.copaw/logs/copaw.log

# 查看最近 100 行日志
tail -n 100 ~/.copaw/logs/copaw.log

清理日志：

# 清理 7 天前的日志
find ~/.copaw/logs -name "*.log" -mtime +7 -delete

# 压缩旧日志
find ~/.copaw/logs -name "*.log" -mtime +1 -exec gzip {} \;

故障排查

安装问题

问题：pip 安装失败

解决方案：

# 升级 pip
pip install --upgrade pip

# 使用镜像源
pip install copaw -i https://pypi.tuna.tsinghua.edu.cn/simple

# 清理缓存
pip cache purge

问题：Python 版本不兼容

解决方案：

# 检查 Python 版本
python --version

# 安装正确版本
# 使用 pyenv 安装 Python 3.11
pyenv install 3.11.0
pyenv global 3.11.0

启动问题

问题：端口被占用

解决方案：

# 查找占用端口的进程
netstat -ano | findstr :8088  # Windows
lsof -i :8088  # macOS / Linux

# 终止进程
taskkill /PID <PID> /F  # Windows
kill -9 <PID>  # macOS / Linux

# 或更改端口
copaw config set port 8089

问题：配置文件错误

解决方案：

# 验证配置
copaw config validate

# 重置配置
copaw config reset

# 重新初始化
copaw init --defaults

Docker 问题

问题：容器无法启动

解决方案：

# 查看容器日志
docker logs copaw

# 检查容器状态
docker ps -a

# 重新创建容器
docker-compose up -d --force-recreate

问题：数据卷权限问题

解决方案：

# 修复权限
sudo chown -R $USER:$USER ~/.copaw

# 或在 Docker Compose 中指定用户
services:
  copaw:
    user: "1000:1000"

性能优化

系统优化

内存优化：

# config.yaml
memory:
  max_usage: 80  # 最大内存使用 80%
  gc_interval: 300  # GC 间隔 5 分钟

CPU 优化：

# config.yaml
cpu:
  max_threads: 4  # 最大线程数
  thread_pool_size: 8  # 线程池大小

应用优化

缓存配置：

# config.yaml
cache:
  enabled: true
  size: 1000  # 缓存大小
  ttl: 3600  # 缓存过期时间（秒）

并发配置：

# config.yaml
concurrency:
  max_concurrent_tasks: 10  # 最大并发任务数
  max_concurrent_channels: 5  # 最大并发渠道数

安全配置

API 密钥管理

环境变量：

# 不要在配置文件中硬编码密钥
export OPENAI_API_KEY="your-api-key"
export ANTHROPIC_API_KEY="your-api-key"

密钥轮换：

# 定期更换密钥
export OPENAI_API_KEY="new-api-key"

# 更新配置
copaw config reload

访问控制

IP 白名单：

# config.yaml
security:
  ip_whitelist:
    - "192.168.1.0/24"
    - "10.0.0.0/8"

认证配置：

# config.yaml
auth:
  enabled: true
  method: "token"  # token, basic, oauth
  tokens:
    - "your-token-1"
    - "your-token-2"

监控和日志

监控指标

关键指标：

# config.yaml
monitoring:
  enabled: true
  metrics:
    - "cpu_usage"
    - "memory_usage"
    - "api_calls"
    - "response_time"
    - "error_rate"

日志配置

日志级别：

# config.yaml
logging:
  level: "INFO"  # DEBUG, INFO, WARN, ERROR
  format: "json"
  outputs:
    - type: "console"
      enabled: true
    - type: "file"
      enabled: true
      path: "logs/copaw.log"

最佳实践

部署建议

• 生产环境：使用 Docker 或云端部署
• 开发环境：使用 pip 安装
• 测试环境：使用独立配置和数据
• 定期备份：定期备份配置和数据

安全建议

• 保护密钥：使用环境变量存储密钥
• 定期更新：定期更新 CoPaw 和依赖
• 监控日志：定期查看日志，及时发现异常
• 限制访问：配置适当的访问控制

性能建议

• 使用缓存：启用缓存减少重复调用
• 优化配置：根据实际需求优化配置
• 监控资源：持续监控资源使用情况
• 定期清理：定期清理日志和缓存

资源链接

• 官方网站: https://copaw.bot
• 官方文档: https://copaw.bot/docs
• GitHub 仓库: https://github.com/modelscope/agentscope
• Docker Hub: https://hub.docker.com/r/agentscope/copaw

最后更新: 2026-03-12 作者: EchoHaoRan

概述

本文档收集了 CoPaw 使用过程中常见的问题及其解决方案，帮助你快速定位和解决问题。

安装和配置问题

Q1: pip 安装失败怎么办？

问题：执行 pip install copaw 时出现错误

解决方案：

# 升级 pip
pip install --upgrade pip

# 使用镜像源
pip install copaw -i https://pypi.tuna.tsinghua.edu.cn/simple

# 清理缓存
pip cache purge

# 重新安装
pip install copaw

Q2: 初始化配置失败？

问题：执行 copaw init --defaults 时出现错误

解决方案：

# 检查 Python 版本
python --version  # 确保 >= 3.10

# 手动创建配置目录
mkdir -p ~/.copaw/{workspace,config,memory,logs}

# 重新初始化
copaw init --defaults

Q3: 启动应用失败？

问题：执行 copaw app 时无法启动

解决方案：

# 查看详细错误
copaw app --verbose

# 检查端口占用
netstat -ano | findstr :8088  # Windows
lsof -i :8088  # macOS / Linux

# 更改端口
copaw config set port 8089

# 重新启动
copaw app

模型相关问题

Q4: 本地模型无法加载？

问题：配置了本地模型但无法加载

解决方案：

# 检查模型文件
ls -lh ~/.local/models/llama.cpp/

# 验证模型
copaw models validate llama.cpp

# 重新下载模型
copaw models download llama2-7b --force

# 检查模型配置
copaw models config llama.cpp

Q5: 云端模型调用失败？

问题：调用云端模型 API 失败

解决方案：

# 检查 API 密钥
echo $OPENAI_API_KEY

# 测试网络连接
curl -I https://api.openai.com

# 验证 API 密钥
copaw models test openai

# 重新配置
copaw models config openai

Q6: 模型推理速度慢？

问题：模型推理速度很慢

解决方案：

# 启用 GPU 加速
copaw models config llama.cpp --n-gpu-layers 35

# 使用量化模型
copaw models download llama2-7b-q4

# 减少上下文长度
copaw models config llama.cpp --n-ctx 1024

# 切换到更快的模型
copaw models set llama.cpp-q4

渠道相关问题

Q7: 钉钉机器人无响应？

问题：在钉钉中 @ 机器人没有回复

解决方案：

# 检查渠道配置
copaw channels config dingtalk

# 测试渠道连接
copaw channels test dingtalk

# 查看渠道日志
copaw logs | grep dingtalk

# 检查 App Key 和 App Secret
copaw channels info dingtalk

Q8: 飞书机器人无法添加？

问题：无法将飞书机器人添加到群聊

解决方案：

1. 检查应用是否已发布
2. 确认应用权限已申请
3. 验证 Encrypt Key 和 Verification Token
4. 重新发布应用

Q9: Discord Bot 不在线？

问题：Discord Bot 显示离线

解决方案：

# 检查 Bot Token
copaw channels config discord

# 测试连接
copaw channels test discord

# 重启服务
copaw restart

# 查看日志
copaw logs | grep discord

技能相关问题

Q10: 技能无法加载？

问题：安装的技能无法加载

解决方案：

# 检查技能状态
copaw skills status skill-name

# 验证技能
copaw skills validate skill-name

# 重新安装技能
copaw skills reinstall skill-name

# 查看技能日志
copaw logs | grep skill-name

Q11: 技能执行失败？

问题：技能执行时出现错误

解决方案：

# 测试技能
copaw skills test skill-name

# 查看技能依赖
copaw skills dependencies skill-name

# 检查技能配置
copaw skills config skill-name

# 查看详细日志
copaw logs --level DEBUG | grep skill-name

Q12: 如何创建自定义技能？

解决方案：

# 创建技能目录
mkdir -p ~/.copaw/workspace/skills/customized/my-skill

# 创建 SKILL.md
cat > ~/.copaw/workspace/skills/customized/my-skill/SKILL.md << EOF
# 我的技能

## 描述
这是一个示例技能

## 使用方法

用户：使用我的技能 CoPaw：[调用我的技能] 执行完成

EOF

# 创建 main.py
cat > ~/.copaw/workspace/skills/customized/my-skill/main.py << EOF
from copaw.skills import Skill

class MySkill(Skill):
    """我的技能"""
    
    async def execute(self, input_data):
        return {'success': True, 'result': '执行完成'}
EOF

# 安装技能
copaw skills install ~/.copaw/workspace/skills/customized/my-skill

# 激活技能
copaw skills activate my-skill

记忆相关问题

Q13: 记忆无法保存？

问题：CoPaw 无法保存记忆

解决方案：

# 检查记忆目录权限
ls -la ~/.copaw/memory/

# 修复权限
chmod 755 ~/.copaw/memory/

# 检查磁盘空间
df -h

# 验证配置
copaw memory config validate

Q14: 记忆检索不准确？

问题：记忆检索结果不相关

解决方案：

# 调整检索阈值
copaw memory config set retrieval.threshold 0.8

# 增加检索数量
copaw memory config set retrieval.top_k 10

# 重建索引
copaw memory rebuild-index

# 测试检索
copaw memory search "关键词"

Q15: 如何清理过期记忆？

解决方案：

# 清理 30 天前的记忆
copaw memory cleanup --days 30

# 清理重复记忆
copaw memory cleanup --duplicates

# 清理无用记忆
copaw memory cleanup --unused

# 查看清理结果
copaw memory stats

性能问题

Q16: CoPaw 响应慢？

问题：CoPaw 响应速度慢

解决方案：

# 检查系统资源
copaw stats

# 启用缓存
copaw config set cache.enabled true

# 优化模型配置
copaw models config set temperature 0.7

# 查看性能日志
copaw logs | grep performance

Q17: 内存占用过高？

问题：CoPaw 占用大量内存

解决方案：

# 清理缓存
copaw cache clear

# 限制记忆数量
copaw memory config set limits.max_entries 500

# 优化上下文长度
copaw models config set n_ctx 1024

# 重启服务
copaw restart

Q18: CPU 使用率高？

问题：CoPaw CPU 使用率高

解决方案：

# 限制并发数
copaw config set concurrency.max_concurrent_tasks 5

# 优化线程池
copaw config set resources.cpu.max_threads 2

# 使用量化模型
copaw models download llama2-7b-q4

# 查看性能日志
copaw logs | grep performance

Docker 相关问题

Q19: Docker 容器无法启动？

问题：Docker 容器启动失败

解决方案：

# 查看容器日志
docker logs copaw

# 检查容器状态
docker ps -a

# 重新创建容器
docker-compose up -d --force-recreate

# 检查 Docker 资源
docker stats

Q20: Docker 数据丢失？

问题：Docker 容器重启后数据丢失

解决方案：

# 检查卷挂载
docker inspect copaw | grep -A 10 Mounts

# 备份数据
docker cp copaw:/app/working ./backup

# 重新创建容器并挂载卷
docker run -d \
  --name copaw \
  -p 8088:8088 \
  -v copaw-data:/app/working \
  agentscope/copaw:latest

安全相关问题

Q21: API 密钥如何安全存储？

解决方案：

# 使用环境变量
export OPENAI_API_KEY="your-api-key"

# 或在配置文件中使用变量引用
# ~/.copaw/config/models.yaml
models:
  openai:
    api_key: "${OPENAI_API_KEY}"

# 不要在代码中硬编码密钥
# 不要提交密钥到版本控制

Q22: 如何限制访问权限？

解决方案：

# ~/.copaw/config/access.yaml
access:
  enabled: true
  
  users:
    - username: "admin"
      roles: ["admin"]
    - username: "user"
      roles: ["user"]
  
  ip_whitelist:
    - "192.168.1.0/24"

升级和维护问题

Q23: 如何升级 CoPaw？

解决方案：

# 检查更新
pip list --outdated | grep copaw

# 升级到最新版本
pip install --upgrade copaw

# 或升级到指定版本
pip install copaw==1.1.0

# 重启服务
copaw restart

Q24: 如何备份数据？

解决方案：

# 备份所有数据
tar -czf copaw-backup-$(date +%Y%m%d).tar.gz ~/.copaw

# 或使用备份命令
copaw backup --output backup-$(date +%Y%m%d).json

# 验证备份
tar -tzf copaw-backup-20260312.tar.gz

Q25: 如何恢复数据？

解决方案：

# 解压备份
tar -xzf copaw-backup-20260312.tar.gz -C ~/

# 或使用恢复命令
copaw restore --source backup-20260312.json

# 验证数据
copaw memory stats

使用技巧

Q26: 如何提高 CoPaw 的准确性？

解决方案：

• 优化提示词：使用清晰、具体的提示词
• 提供上下文：提供足够的背景信息
• 使用示例：提供示例引导 CoPaw
• 持续反馈：根据反馈调整 CoPaw 的行为

Q27: 如何减少 Token 消耗？

解决方案：

• 使用本地模型：本地模型无 API 费用
• 优化上下文：减少上下文长度
• 启用缓存：缓存常见查询
• 选择合适模型：根据任务选择合适的模型

Q28: 如何自定义 CoPaw 的行为？

解决方案：

• 编辑 SOUL.md：修改 CoPaw 的核心个性
• 编辑 PROFILE.md：添加用户偏好
• 添加技能：安装自定义技能
• 配置渠道：添加或修改渠道

故障排查流程

标准故障排查流程

1. 查看日志
   └─ copaw logs -f

2. 验证配置
   └─ copaw config validate

3. 检查服务状态
   └─ copaw status

4. 测试网络连接
   └─ curl -I https://api.openai.com

5. 检查资源使用
   └─ copaw stats

6. 重启服务
   └─ copaw restart

7. 如果问题持续
   └─ 生成诊断报告并联系支持

生成诊断报告

# 生成诊断报告
copaw diagnose --output diagnosis-report.txt

# 查看报告
cat diagnosis-report.txt

获取帮助

官方资源

• 官方网站: https://copaw.bot
• 官方文档: https://copaw.bot/docs
• GitHub 仓库: https://github.com/modelscope/agentscope
• 社区论坛: https://github.com/modelscope/agentscope/discussions

提交问题

提交问题时请包含：

• CoPaw 版本
• 操作系统信息
• 完整的错误日志
• 相关配置文件
• 复现步骤

联系支持

如果你无法通过以上资源解决问题，可以通过以下方式获取帮助：

1. 在 GitHub 上提交 Issue
2. 在社区论坛提问
3. 加入 Discord 社区讨论

最佳实践

日常使用建议

1. 定期更新：保持 CoPaw 最新版本
2. 定期备份：定期备份配置和数据
3. 监控日志：定期查看日志，及时发现异常
4. 合理使用：避免过度调用 API，控制成本

安全建议

1. 保护密钥：使用环境变量存储密钥
2. 定期更换：定期更换 API 密钥
3. 限制访问：配置适当的访问控制
4. 监控异常：监控异常访问和行为

性能建议

1. 使用缓存：启用缓存减少重复调用
2. 优化配置：根据实际需求优化配置
3. 监控资源：持续监控资源使用情况
4. 定期清理：定期清理日志和缓存

资源链接

• CoPaw 官方文档: https://copaw.bot/docs
• 常见问题: https://copaw.bot/docs/faq
• 故障排查指南: https://copaw.bot/docs/troubleshooting
• 社区支持: https://github.com/modelscope/agentscope/discussions

最后更新: 2026-03-12 作者: EchoHaoRan

概述

本教程将带你快速了解如何安装、配置和使用 CoPaw 个人 AI 助手。从零开始，在几分钟内拥有你自己的智能助手。

安装前准备

系统要求

可选依赖

本地模型运行：

• Apple Silicon：MLX（自动安装）
• 其他平台：llama.cpp（可选）

云端模型：

• API 密钥（OpenAI、Anthropic、Qwen 等）

安装方式

方式一：pip 安装（推荐）

适用场景：Python 开发环境，快速上手

步骤：

1. 安装 CoPaw

pip install copaw

1. 初始化配置

copaw init --defaults

1. 启动应用

copaw app

1. 访问控制台

在浏览器中打开: http://127.0.0.1:8088/

优势：

• 最快的上手方式
• 自动配置 Python 环境
• 适用于 Python 3.10+ 环境

方式二：一键安装脚本

适用场景：首次使用，自动配置环境

macOS / Linux：

curl -fsSL https://copaw.agentscope.io/install.sh | bash

Windows PowerShell：

# 请参阅官方文档了解 PowerShell 安装方式

优势：

• 一键安装
• 自动配置 Python 环境
• 适合首次使用的用户

方式三：Docker 部署

适用场景：容器化部署，持久数据卷

步骤：

1. 拉取镜像

docker pull agentscope/copaw:latest

1. 运行容器

docker run -p 8088:8088 \
  -v copaw-data:/app/working \
  agentscope/copaw:latest

1. 访问控制台

在浏览器中打开: http://127.0.0.1:8088/

优势：

• 容器化部署
• 持久数据卷
• 两条命令即可运行

方式四：云端部署

适用场景：无需本地环境，一键部署

平台：

• ModelScope Studio
• 阿里云计算巢

步骤：

1. 访问 ModelScope Studio
2. 选择 CoPaw 应用
3. 点击一键部署
4. 等待部署完成

优势：

• 无需本地环境
• 一键部署
• 自动配置

首次配置

初始化配置

运行 copaw init --defaults 后，CoPaw 将创建默认配置：

# 工作目录结构
~/.copaw/
├── workspace/          # 工作区
│   ├── skills/        # 技能目录
│   ├── prompts/       # 提示词目录
│   └── data/          # 数据目录
├── config/            # 配置文件
├── memory/            # 记忆存储
└── logs/              # 日志文件

配置模型

云端模型：

# 设置 OpenAI API 密钥
export OPENAI_API_KEY="your-api-key"

# 或在配置文件中设置
# ~/.copaw/config/models.yaml

本地模型：

# 下载本地模型
copaw models download

# 查看可用模型
copaw models list

配置渠道

查看可用渠道：

copaw channels list

安装渠道：

# 安装钉钉渠道
copaw channels install dingtalk

# 配置钉钉
copaw channels config dingtalk

基础使用

启动 CoPaw

方式一：控制台模式

copaw app

访问：http://127.0.0.1:8088/

方式二：渠道模式

# 通过已配置的渠道使用
# CoPaw 将在后台运行

与 CoPaw 对话

控制台对话：

1. 打开浏览器访问 http://127.0.0.1:8088/
2. 在聊天框中输入消息
3. 点击发送
4. 等待 CoPaw 回复

渠道对话：

• 钉钉：在钉钉中搜索 CoPaw 机器人
• 飞书：在飞书中添加 CoPaw 应用
• 其他渠道：根据渠道配置使用

常用命令

斜杠命令：

/new         # 开始新对话
/compact     # 压缩对话历史
/clear       # 清除所有历史
/history     # 查看对话历史

CLI 命令：

# 查看状态
copaw status

# 查看日志
copaw logs

# 重启服务
copaw restart

示例场景

场景一：快速问答

用户输入：

什么是人工智能？

CoPaw 回复：

人工智能（Artificial Intelligence，简称 AI）是计算机科学的一个分支，旨在创建能够执行通常需要人类智能的任务的智能系统。这些任务包括：
- 学习和推理
- 理解语言
- 识别图像
- 决策和规划

AI 主要分为：
1. 弱人工智能（Narrow AI）：专注于特定任务，如图像识别
2. 强人工智能（General AI）：具有像人类一样的通用智能能力

场景二：邮件摘要

用户输入：

帮我总结今天的邮件

CoPaw 回复：

今天收到 5 封邮件：

1. 来自张三（工作）
   - 主题：项目进度更新
   - 内容：项目已完成 80%，预计下周完成

2. 来自李四（工作）
   - 主题：会议邀请
   - 内容：周五下午 2 点开会讨论新功能

3. 来自王五（个人）
   - 主题：周末聚会
   - 内容：周六晚上聚餐，地点待定

4. 来自系统（通知）
   - 主题：安全提醒
   - 内容：请及时更新密码

5. 来自客服（服务）
   - 主题：订单确认
   - 内容：订单 #12345 已发货

需要我进一步处理吗？

场景三：创意生成

用户输入：

帮我写一篇关于 AI 未来发展的博客文章

CoPaw 回复：

# AI 的未来：从工具到伙伴

人工智能正在以前所未有的速度改变我们的世界。从最初的简单算法到今天的复杂神经网络，AI 已经从一个概念变成了我们日常生活中不可或缺的一部分。

## 当前的 AI 能力

今天的 AI 已经能够：
- 理解和生成自然语言
- 识别和分析图像
- 进行复杂的推理和决策
- 创作音乐和艺术
- 辅助编程和开发

## 未来的发展方向

### 更强的推理能力
未来的 AI 将具备更强大的推理和规划能力，能够处理更复杂的任务和问题。

### 多模态融合
AI 将更好地整合文本、图像、音频、视频等多种模态，提供更丰富的交互体验。

### 个性化定制
AI 将能够根据个人偏好和需求进行深度定制，成为真正的个人助手。

### 人机协作
AI 将与人类形成更紧密的协作关系，共同解决复杂问题。

## 挑战与机遇

虽然 AI 的发展前景广阔，但我们仍面临诸多挑战：
- 数据隐私和安全
- 算法偏见和公平性
- 就业市场的影响
- 伦理和监管问题

然而，这些挑战也是机遇。通过积极应对，我们可以确保 AI 的发展造福全人类。

## 结语

AI 的未来不仅仅是技术的进步，更是人机关系的新篇章。让我们拥抱这个充满可能性的未来，共同创造更美好的世界。

---

*本文由 CoPaw AI 助手生成*

进阶配置

自定义提示词

创建提示词文件：

# ~/.copaw/workspace/prompts/SOUL.md
# 你是 CoPaw，一个智能助手
# 你的目标是帮助用户解决问题
# 你的风格：友好、专业、准确

重新加载配置：

copaw reload

安装技能

查看可用技能：

copaw skills list

安装技能：

copaw skills install weather

使用技能：

帮我查询北京今天的天气

配置记忆

启用记忆：

# ~/.copaw/config/memory.yaml
enabled: true
max_entries: 1000
retention_days: 365

记忆示例：

用户：我明天要去北京出差
CoPaw：好的，我记住了。需要我帮你准备什么吗？

用户：我明天去北京有什么行程建议？
CoPaw：根据你之前说的出差，我建议：
- 提前查看天气
- 准备会议材料
- 了解交通路线

故障排查

安装失败

问题：pip 安装失败

解决方案：

# 升级 pip
pip install --upgrade pip

# 使用清华镜像
pip install copaw -i https://pypi.tuna.tsinghua.edu.cn/simple

启动失败

问题：copaw app 启动失败

解决方案：

# 查看日志
copaw logs

# 检查端口占用
netstat -ano | findstr :8088

# 更改端口
copaw config set port 8089

模型调用失败

问题：模型无响应

解决方案：

# 检查 API 密钥
echo $OPENAI_API_KEY

# 测试模型连接
copaw models test

# 切换到本地模型
copaw models set llama.cpp

最佳实践

日常使用建议

1. 定期更新：保持 CoPaw 最新版本
2. 备份配置：定期备份配置文件
3. 监控日志：定期查看日志，及时发现问题
4. 合理使用：避免过度调用 API，控制成本

安全建议

1. 保护密钥：不要将 API 密钥提交到版本控制
2. 使用环境变量：敏感信息使用环境变量存储
3. 限制访问：配置适当的权限和访问控制
4. 定期更换密钥：定期更换 API 密钥

性能优化

1. 使用缓存：启用缓存减少重复调用
2. 选择合适模型：根据任务选择合适的模型
3. 优化提示词：简洁明了的提示词提高效率
4. 监控资源：定期检查资源使用情况

下一步

学习资源

• 官方文档: https://copaw.bot/docs
• GitHub 仓库: https://github.com/modelscope/agentscope
• 社区论坛: https://github.com/modelscope/agentscope/discussions

进阶主题

• CoPaw 技能系统详解
• CoPaw 渠道配置
• CoPaw 记忆系统
• CoPaw Agent 架构
• CoPaw 本地模型配置

实践项目

• 搭建个人知识库
• 自动化工作流程
• 创建自定义技能
• 集成更多渠道

常见问题

Q: CoPaw 是免费的吗？

A: 是的，CoPaw 基于 Apache 2.0 许可证开源，完全免费。但使用云端模型可能产生费用。

Q: 可以在没有网络的情况下使用 CoPaw 吗？

A: 可以，如果配置了本地模型，CoPaw 可以完全离线运行。

Q: CoPaw 支持哪些编程语言？

A: CoPaw 主要使用 Python 开发，技能可以使用 Python 编写。

Q: 如何卸载 CoPaw？

A:

pip uninstall copaw
rm -rf ~/.copaw

资源链接

• 官方网站: https://copaw.bot
• 官方文档: https://copaw.bot/docs
• GitHub 仓库: https://github.com/modelscope/agentscope
• AgentScope 文档: https://github.com/modelscope/agentscope

最后更新: 2026-03-12 作者: EchoHaoRan

概述

CoPaw 的技能系统是一个可扩展的插件系统，允许你为 CoPaw 添加各种功能。技能从工作区自动加载，内置定时调度，是一等公民 —— 可发现、可组合、可独立部署。

技能系统概述

什么是技能

技能是 CoPaw 的功能扩展模块，可以为 CoPaw 添加新的能力。

技能特点：

• 可发现：可以通过 CLI 命令发现和安装
• 可组合：多个技能可以组合使用
• 可独立部署：技能可以独立开发和部署
• 无厂商锁定：完全开源，无厂商限制

技能类型

技能目录结构

~/.copaw/workspace/skills/
├── builtin/              # 内置技能
│   ├── weather/
│   │   └── SKILL.md
│   ├── calculator/
│   │   └── SKILL.md
│   └── ...
├── customized/           # 自定义技能
│   ├── my-skill/
│   │   ├── SKILL.md
│   │   ├── main.py
│   │   └── config.yaml
│   └── ...
└── active/               # 激活的技能
    ├── weather -> ../builtin/weather
    ├── calculator -> ../builtin/calculator
    └── my-skill -> ../customized/my-skill

技能管理

技能 CLI 命令

查看可用技能：

# 列出所有可用技能
copaw skills list

# 列出已安装技能
copaw skills installed

# 列出激活的技能
copaw skills active

安装技能：

# 从本地安装
copaw skills install path/to/skill

# 从 Git 仓库安装
copaw skills install git+https://github.com/user/skill.git

# 从 PyPI 安装
copaw skills install skill-name

移除技能：

# 移除技能
copaw skills remove skill-name

# 强制移除
copaw skills remove skill-name --force

更新技能：

# 更新技能
copaw skills update skill-name

# 更新所有技能
copaw skills update --all

激活/停用技能：

# 激活技能
copaw skills activate skill-name

# 停用技能
copaw skills deactivate skill-name

技能搜索

搜索技能：

# 搜索技能
copaw skills search keyword

# 搜索天气相关技能
copaw skills search weather

# 搜索计算相关技能
copaw skills search calculator

技能信息

查看技能详情：

# 查看技能详情
copaw skills info skill-name

# 查看技能配置
copaw skills config skill-name

# 查看技能依赖
copaw skills dependencies skill-name

技能结构

SKILL.md 文件

基础结构：

# 技能名称

## 描述
简要描述技能的功能和用途。

## 版本
1.0.0

## 作者
Your Name

## 依赖
- numpy >= 1.20.0
- requests >= 2.25.0

## 配置
```yaml
param1: value1
param2: value2

使用方法

说明如何使用该技能。

示例

用户：查询北京的天气
CoPaw：[调用天气技能] 北京今天天气晴朗，温度 25°C

**高级结构**：
```markdown
# 高级数据分析技能

## 描述
提供强大的数据分析功能，包括统计分析、数据可视化和报告生成。

## 版本
2.1.0

## 作者
Data Team

## 依赖
- pandas >= 1.5.0
- numpy >= 1.23.0
- matplotlib >= 3.5.0
- plotly >= 5.0.0

## 配置
```yaml
output_format: "markdown"
chart_theme: "plotly"
max_rows: 1000
cache_enabled: true
cache_ttl: 3600

功能

• 数据加载和清洗
• 统计分析
• 数据可视化
• 报告生成

使用方法

用户：分析销售数据
CoPaw：[调用数据分析技能] 正在分析销售数据...

示例

用户：分析今年的销售数据并生成报告
CoPaw：[调用数据分析技能]
- 加载数据：sales_2024.csv
- 数据清洗：完成
- 统计分析：
  * 总销售额：¥1,234,567
  * 同比增长：15.3%
  * 月均销售额：¥102,880
- 数据可视化：生成图表
- 报告生成：完成

权限

• read: 读取文件
• write: 写入文件
• network: 网络访问

限制

• 最大文件大小：100MB
• 最大处理行数：10,000 行

### main.py 文件

**基础结构**：
```python
# main.py
from typing import Dict, Any
from copaw.skills import Skill

class MySkill(Skill):
    """自定义技能"""
    
    def __init__(self, config: Dict[str, Any]):
        super().__init__(config)
        self.param1 = config.get('param1', 'default_value')
    
    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
        """执行技能"""
        result = self.process(input_data)
        return {
            'success': True,
            'result': result
        }
    
    def process(self, input_data: Dict[str, Any]) -> Any:
        """处理输入数据"""
        # 处理逻辑
        return processed_result

高级结构：

# main.py
import pandas as pd
import matplotlib.pyplot as plt
from typing import Dict, Any, List
from copaw.skills import Skill

class DataAnalysisSkill(Skill):
    """数据分析技能"""
    
    def __init__(self, config: Dict[str, Any]):
        super().__init__(config)
        self.output_format = config.get('output_format', 'markdown')
        self.chart_theme = config.get('chart_theme', 'plotly')
        self.max_rows = config.get('max_rows', 1000)
        self.cache_enabled = config.get('cache_enabled', True)
        self.cache_ttl = config.get('cache_ttl', 3600)
    
    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
        """执行数据分析"""
        try:
            # 加载数据
            data = self.load_data(input_data)
            
            # 数据清洗
            cleaned_data = self.clean_data(data)
            
            # 统计分析
            stats = self.analyze(cleaned_data)
            
            # 数据可视化
            charts = self.visualize(cleaned_data)
            
            # 生成报告
            report = self.generate_report(stats, charts)
            
            return {
                'success': True,
                'result': report,
                'stats': stats,
                'charts': charts
            }
        except Exception as e:
            return {
                'success': False,
                'error': str(e)
            }
    
    def load_data(self, input_data: Dict[str, Any]) -> pd.DataFrame:
        """加载数据"""
        file_path = input_data.get('file_path')
        if file_path.endswith('.csv'):
            return pd.read_csv(file_path)
        elif file_path.endswith('.xlsx'):
            return pd.read_excel(file_path)
        else:
            raise ValueError("不支持的文件格式")
    
    def clean_data(self, data: pd.DataFrame) -> pd.DataFrame:
        """清洗数据"""
        # 去除重复
        data = data.drop_duplicates()
        
        # 处理缺失值
        data = data.fillna(data.mean())
        
        # 限制行数
        if len(data) > self.max_rows:
            data = data.head(self.max_rows)
        
        return data
    
    def analyze(self, data: pd.DataFrame) -> Dict[str, Any]:
        """统计分析"""
        stats = {
            'count': len(data),
            'mean': data.mean().to_dict(),
            'std': data.std().to_dict(),
            'min': data.min().to_dict(),
            'max': data.max().to_dict(),
            'median': data.median().to_dict()
        }
        return stats
    
    def visualize(self, data: pd.DataFrame) -> List[str]:
        """数据可视化"""
        charts = []
        # 生成图表
        fig, ax = plt.subplots(figsize=(10, 6))
        data.plot(kind='bar', ax=ax)
        plt.savefig('chart.png')
        charts.append('chart.png')
        return charts
    
    def generate_report(self, stats: Dict[str, Any], charts: List[str]) -> str:
        """生成报告"""
        report = f"# 数据分析报告\n\n"
        report += f"## 统计摘要\n\n"
        report += f"- 数据量：{stats['count']}\n"
        report += f"- 平均值：{stats['mean']}\n"
        report += f"- 标准差：{stats['std']}\n"
        report += f"\n## 图表\n\n"
        for chart in charts:
            report += f"![图表]({chart})\n\n"
        return report

config.yaml 文件

配置示例：

# config.yaml
name: "data-analysis"
version: "2.1.0"
author: "Data Team"

# 功能配置
features:
  data_loading: true
  data_cleaning: true
  statistical_analysis: true
  data_visualization: true
  report_generation: true

# 性能配置
performance:
  max_rows: 1000
  max_file_size: 104857600  # 100MB
  cache_enabled: true
  cache_ttl: 3600

# 输出配置
output:
  format: "markdown"
  include_charts: true
  include_stats: true

# 权限配置
permissions:
  read: true
  write: true
  network: false

创建自定义技能

创建技能目录

步骤：

# 创建技能目录
mkdir -p ~/.copaw/workspace/skills/customized/my-skill

# 进入技能目录
cd ~/.copaw/workspace/skills/customized/my-skill

创建 SKILL.md

示例：

# 我的自定义技能

## 描述
这是一个示例自定义技能，用于演示如何创建 CoPaw 技能。

## 版本
1.0.0

## 作者
Your Name

## 依赖
- requests >= 2.25.0

## 配置
```yaml
api_url: "https://api.example.com"
timeout: 30

使用方法

用户：执行我的技能
CoPaw：[调用我的技能] 执行完成

### 创建 main.py

**示例**：
```python
# main.py
import requests
from typing import Dict, Any
from copaw.skills import Skill

class MySkill(Skill):
    """我的自定义技能"""
    
    def __init__(self, config: Dict[str, Any]):
        super().__init__(config)
        self.api_url = config.get('api_url', 'https://api.example.com')
        self.timeout = config.get('timeout', 30)
    
    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
        """执行技能"""
        try:
            # 调用 API
            response = requests.get(
                self.api_url,
                params=input_data,
                timeout=self.timeout
            )
            
            # 处理响应
            result = response.json()
            
            return {
                'success': True,
                'result': result
            }
        except Exception as e:
            return {
                'success': False,
                'error': str(e)
            }

创建 config.yaml

示例：

# config.yaml
name: "my-skill"
version: "1.0.0"
author: "Your Name"

# API 配置
api:
  url: "https://api.example.com"
  timeout: 30
  retry: 3

# 功能配置
features:
  feature1: true
  feature2: false

安装和测试技能

安装技能：

# 安装技能
copaw skills install ~/.copaw/workspace/skills/customized/my-skill

# 激活技能
copaw skills activate my-skill

测试技能：

# 测试技能
copaw skills test my-skill

# 测试技能功能
echo '{"param1": "value1"}' | copaw skills run my-skill

技能开发最佳实践

技能设计原则

单一职责：

• 每个技能只做一件事
• 保持简单和专注
• 便于维护和测试

可组合性：

• 技能可以组合使用
• 提供清晰的接口
• 支持管道操作

可扩展性：

• 易于添加新功能
• 支持配置扩展
• 预留扩展点

错误处理

基础错误处理：

def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
    """执行技能"""
    try:
        result = self.process(input_data)
        return {
            'success': True,
            'result': result
        }
    except Exception as e:
        return {
            'success': False,
            'error': str(e),
            'error_type': type(e).__name__
        }

高级错误处理：

import logging
from typing import Dict, Any

class MySkill(Skill):
    """我的自定义技能"""
    
    def __init__(self, config: Dict[str, Any]):
        super().__init__(config)
        self.logger = logging.getLogger(__name__)
    
    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
        """执行技能"""
        try:
            # 验证输入
            self.validate_input(input_data)
            
            # 处理数据
            result = self.process(input_data)
            
            # 验证输出
            self.validate_output(result)
            
            return {
                'success': True,
                'result': result
            }
        except ValueError as e:
            self.logger.error(f"验证错误: {e}")
            return {
                'success': False,
                'error': str(e),
                'error_type': 'ValidationError'
            }
        except RuntimeError as e:
            self.logger.error(f"运行时错误: {e}")
            return {
                'success': False,
                'error': str(e),
                'error_type': 'RuntimeError'
            }
        except Exception as e:
            self.logger.error(f"未知错误: {e}")
            return {
                'success': False,
                'error': str(e),
                'error_type': 'UnknownError'
            }
    
    def validate_input(self, input_data: Dict[str, Any]) -> None:
        """验证输入"""
        if not isinstance(input_data, dict):
            raise ValueError("输入必须是字典")
        # 更多验证逻辑
    
    def validate_output(self, output: Any) -> None:
        """验证输出"""
        if output is None:
            raise ValueError("输出不能为空")
        # 更多验证逻辑

性能优化

缓存机制：

from functools import lru_cache
import hashlib
import json

class MySkill(Skill):
    """我的自定义技能"""
    
    def __init__(self, config: Dict[str, Any]):
        super().__init__(config)
        self.cache_enabled = config.get('cache_enabled', True)
        self.cache_ttl = config.get('cache_ttl', 3600)
        self.cache = {}
    
    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
        """执行技能"""
        # 生成缓存键
        cache_key = self.generate_cache_key(input_data)
        
        # 检查缓存
        if self.cache_enabled and cache_key in self.cache:
            cached_result, cached_time = self.cache[cache_key]
            if time.time() - cached_time < self.cache_ttl:
                return cached_result
        
        # 处理数据
        result = self.process(input_data)
        
        # 更新缓存
        if self.cache_enabled:
            self.cache[cache_key] = (result, time.time())
        
        return result
    
    def generate_cache_key(self, input_data: Dict[str, Any]) -> str:
        """生成缓存键"""
        data_str = json.dumps(input_data, sort_keys=True)
        return hashlib.md5(data_str.encode()).hexdigest()

批处理：

def process_batch(self, inputs: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
    """批处理"""
    results = []
    for input_data in inputs:
        try:
            result = self.execute(input_data)
            results.append(result)
        except Exception as e:
            results.append({
                'success': False,
                'error': str(e)
            })
    return results

技能发布和共享

打包技能

创建 setup.py：

# setup.py
from setuptools import setup, find_packages

setup(
    name="copaw-my-skill",
    version="1.0.0",
    packages=find_packages(),
    install_requires=[
        "copaw>=1.0.0",
        "requests>=2.25.0",
    ],
    author="Your Name",
    description="My CoPaw Skill",
    python_requires=">=3.10",
)

打包技能：

# 构建 distribution
python setup.py sdist bdist_wheel

# 安装本地包
pip install dist/copaw_my_skill-1.0.0-py3-none-any.whl

发布到 PyPI

注册 PyPI 账户：

1. 访问 https://pypi.org/
2. 注册账户
3. 创建 API Token

发布技能：

# 安装发布工具
pip install twine

# 发布到 PyPI
twine upload dist/*

# 或发布到 TestPyPI
twine upload --repository testpypi dist/*

共享技能

Git 仓库：

# 创建 Git 仓库
git init
git add .
git commit -m "Initial commit"

# 推送到 GitHub
git remote add origin https://github.com/yourusername/copaw-my-skill.git
git push -u origin main

通过 URL 安装：

# 从 Git 仓库安装
copaw skills install git+https://github.com/yourusername/copaw-my-skill.git

常见问题

Q1: 技能无法加载？

解决方案：

# 检查技能配置
copaw skills validate my-skill

# 查看技能日志
copaw logs | grep my-skill

# 重新加载技能
copaw skills reload my-skill

Q2: 技能执行失败？

解决方案：

# 查看技能详情
copaw skills info my-skill

# 检查技能依赖
copaw skills dependencies my-skill

# 测试技能
copaw skills test my-skill

Q3: 如何调试技能？

解决方案：

# 启用调试日志
import logging
logging.basicConfig(level=logging.DEBUG)

# 添加调试信息
self.logger.debug(f"输入数据: {input_data}")
self.logger.debug(f"处理结果: {result}")

资源链接

• CoPaw 技能文档: https://copaw.bot/docs/skills
• 技能示例: https://github.com/modelscope/agentscope/tree/main/skills
• 技能开发指南: https://copaw.bot/docs/skills/development

最后更新: 2026-03-12 作者: EchoHaoRan

概述

CoPaw 支持在本地运行大语言模型，无需 API 密钥，无需云依赖。支持 llama.cpp（跨平台）和 MLX（Apple Silicon）两种本地模型运行方式。

本地模型概述

为什么使用本地模型

支持的本地模型后端

硬件要求

llama.cpp 配置

安装 llama.cpp

方式一：通过包管理器安装

# macOS
brew install llama.cpp

# Linux
# 使用包管理器安装
sudo apt install llama-cpp-python

# Windows
# 下载预编译二进制文件
# https://github.com/ggerganov/llama.cpp/releases

方式二：从源码编译

# 克隆仓库
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

# 编译
make

# 安装 Python 绑定
pip install llama-cpp-python

下载模型

查看可用模型：

copaw models list

下载模型：

# 下载 7B 模型
copaw models download llama2-7b

# 下载 13B 模型
copaw models download llama2-13b

# 下载量化模型
copaw models download llama2-7b-q4

手动下载模型：

# 从 Hugging Face 下载
# https://huggingface.co/TheBloke/Llama-2-7B-GGUF

# 下载模型文件
wget https://huggingface.co/TheBloke/Llama-2-7B-GGUF/resolve/main/llama-2-7b.Q4_K_M.gguf

# 保存到模型目录
mv llama-2-7b.Q4_K_M.gguf ~/.local/models/llama.cpp/

配置 CoPaw

配置文件：

# ~/.copaw/config/models.yaml
local:
  llama_cpp:
    enabled: true
    model_path: "~/.local/models/llama.cpp/llama-2-7b.Q4_K_M.gguf"
    n_ctx: 2048  # 上下文长度
    n_gpu_layers: 35  # GPU 层数
    n_threads: 4  # 线程数
    temperature: 0.7
    top_p: 0.9
    top_k: 40

CLI 配置：

# 设置本地模型为默认
copaw models set llama.cpp

# 配置模型参数
copaw models config llama.cpp

测试本地模型

测试连接：

# 测试模型连接
copaw models test llama.cpp

# 测试推理
copaw models chat llama.cpp

性能测试：

# 运行性能测试
copaw models benchmark llama.cpp

MLX 配置（Apple Silicon）

安装 MLX

前提条件：

• Apple Silicon M1、M2、M3 或 M4
• macOS 12.0+
• Python 3.10+

安装步骤：

# 安装 MLX
pip install mlx mlx-lm

# 安装依赖
pip install transformers

下载模型

下载模型：

# 下载 7B 模型
copaw models download mlx-7b

# 下载 13B 模型
copaw models download mlx-13b

手动下载模型：

# 从 Hugging Face 下载
# https://huggingface.co/mlx-community

# 下载模型文件
git lfs install
git clone https://huggingface.co/mlx-community/Llama-3.2-3B-Instruct-4bit ~/.local/models/mlx/

配置 CoPaw

配置文件：

# ~/.copaw/config/models.yaml
local:
  mlx:
    enabled: true
    model_path: "~/.local/models/mlx/Llama-3.2-3B-Instruct-4bit"
    max_tokens: 2048
    temperature: 0.7
    top_p: 0.9
    gpu_memory_limit: 4  # GB

CLI 配置：

# 设置 MLX 为默认
copaw models set mlx

# 配置 MLX 参数
copaw models config mlx

测试 MLX 模型

测试连接：

# 测试模型连接
copaw models test mlx

# 测试推理
copaw models chat mlx

性能测试：

# 运行性能测试
copaw models benchmark mlx

模型管理

模型列表

查看已安装模型：

# 列出所有已安装的模型
copaw models list

# 列出特定类型的模型
copaw models list --type local

模型信息

查看模型详情：

# 查看模型详情
copaw models info llama.cpp

# 查看模型参数
copaw models parameters llama.cpp

模型切换

切换模型：

# 切换到本地模型
copaw models set llama.cpp

# 切换到云端模型
copaw models set openai

# 查看当前模型
copaw models current

模型删除

删除模型：

# 删除模型
copaw models remove llama.cpp

# 清理未使用的模型
copaw models cleanup

模型优化

量化模型

什么是量化： 量化是一种模型压缩技术，通过降低模型参数的精度来减少模型大小和提高推理速度。

量化级别：

量化模型：

# 下载量化模型
copaw models download llama2-7b-q4

# 或自己量化
# 需要原始模型和量化工具
python quantize.py llama-2-7b-f16.gguf llama-2-7b-q4.gguf q4_k_m

参数调优

常用参数：

# ~/.copaw/config/models.yaml
parameters:
  # 上下文长度
  n_ctx: 2048  # 根据需要调整
  
  # 温度参数（0.0-1.0）
  temperature: 0.7  # 0.0=确定性，1.0=创造性
  
  # Top P（0.0-1.0）
  top_p: 0.9  # 核采样
  
  # Top K（0+）
  top_k: 40  # 限制候选词数量
  
  # 频率惩罚（-2.0-2.0）
  frequency_penalty: 0.0  # 减少重复
  
  # 存在惩罚（-2.0-2.0）
  presence_penalty: 0.0  # 鼓励新话题
  
  # 重复惩罚（0.0-2.0）
  repeat_penalty: 1.1  # 减少重复
  
  # 线程数
  n_threads: 4  # 根据 CPU 核心数调整
  
  # GPU 层数
  n_gpu_layers: 35  # 根据 GPU 显存调整

性能优化

GPU 加速：

# 启用 GPU 加速
local:
  llama_cpp:
    n_gpu_layers: 35  # 将所有层放到 GPU
    use_mmap: true  # 使用内存映射
    use_mlock: false  # 不锁定内存

内存优化：

# 优化内存使用
local:
  llama_cpp:
    use_mmap: true  # 使用内存映射
    use_mlock: false  # 不锁定内存
    n_batch: 512  # 批处理大小

常见问题

模型加载失败

问题：模型无法加载

解决方案：

# 检查模型文件
ls -lh ~/.local/models/llama.cpp/

# 验证模型文件
copaw models validate llama.cpp

# 重新下载模型
copaw models download llama2-7b --force

推理速度慢

问题：模型推理速度慢

解决方案：

# 启用 GPU 加速
local:
  llama_cpp:
    n_gpu_layers: 35

# 减少上下文长度
n_ctx: 1024

# 使用量化模型
model_path: "~/.local/models/llama.cpp/llama-2-7b-q4.gguf"

内存不足

问题：内存不足

解决方案：

# 优化内存使用
local:
  llama_cpp:
    use_mmap: true
    use_mlock: false
    n_batch: 512

# 减少上下文长度
n_ctx: 1024

# 使用更小的模型
model_path: "~/.local/models/llama.cpp/llama-2-3b-q4.gguf"

最佳实践

模型选择

参数调优

创造性任务：

parameters:
  temperature: 0.9
  top_p: 0.95
  top_k: 50

确定性任务：

parameters:
  temperature: 0.2
  top_p: 0.8
  top_k: 30

平衡任务：

parameters:
  temperature: 0.7
  top_p: 0.9
  top_k: 40

性能建议

• 使用量化模型：大幅减少模型大小
• 启用 GPU 加速：显著提高推理速度
• 优化上下文长度：根据需要调整
• 监控资源使用：定期检查 CPU 和内存使用

资源链接

• llama.cpp: https://github.com/ggerganov/llama.cpp
• MLX: https://github.com/ml-explore/mlx
• Hugging Face: https://huggingface.co/
• CoPaw 模型文档: https://copaw.bot/docs/models

最后更新: 2026-03-12 作者: EchoHaoRan

• 语法:
  • h1 {color:red; font-size:25px;}:h1^选择器color:^属性red:^值
    • 需要写在头文件的<style>标签内
  • 紧凑格式:h1 {color:red; font-size:25px;}
  • 展开格式: h1 { color:red; font-size:25px; }```
    • 都是用小写
    • 属性值前面,冒号和后面保留空格
    • 选择器,如 p h1 后面也需要保留一个空格
• 选择器:
  • 基础选择器:
    • 标签选择器:使用标签名选择,如p h1 div等,将整个选择类型都进行修改
    • 类选择器:单独指定某个或者某几个

      /*头文件head内
      	#指定一个属性并命名为sample*/
       <style>
      	.sample {
      		color: blue;
      	}
      /* body内
      	#在标签中使用class调用类选择器sample的属性
      		#可用于不同的标签类型*/
      <ul>
      	<li class="sample">冰雨</li>
      </ul>
      
      <div class="sample">陈楚生</div>
      

      • 多类名:给一个标签贴上多个类名
        • 类名之间需要用空格隔开

            <head> 
              <style>
                  .font-red {
                      color: red;
                  }
                  .font35 {
                      font-size: 55px;
                  }
              </style>
          </head>
          <body>
              <div class="font-red font35">刘德华</div>
          </body>
          </html>
          

    • id选择器:

      /*定义*/
      	<head>
      		<style>
      		#id名 {
      			属性1: 值1;
      			...
      			}
      		#pink {
      			color: pink;
      			}
      		</style>
      	</head>
      	/*使用*/
      	<body>
      		<div id="pink">迈克尔·杰克逊</div>
      

      • 每个id都是唯一的,只能调用一次
    • 通配符选择器:
      • 使用*定义,*表示所有,将所有标签都定义为其值

        <sylte>
        	* {
        	color: red;
        	}
        </style>
        

• 复合选择器:
  • 复合选择器是建立在基础选择器之上,由基础选择器组合而来
    • 后代选择器:
      • 可以选择父元素里面的子元素
      • 从父到子依此书写,用空格隔开父元素 空格 子元素 {样式}
      • ul li { }即可选择到ul元素下的li元素
    • 子选择器
      • 只选择最近一级的子元素"亲儿子",不影响之下层级的元素
    • 并集选择器
      • 可以选择多组标签,同时定义样式,通过,英文逗号连接多个标签
      • 并集选择器每一个选中的选择都会竖相排列
    • 伪类选择器
      • 用于添加效果
      • 用:进行标识
        • 链接伪类:
          • a:link:选择所有未被访问的链接
          • a:visited选择所有已经被访问的链接
          • a:hover选择鼠标指针聚焦的链接
          • a:active选择活动链接^{鼠标点击后还未弹起的链接}
            • *TIPS:
              • *必须按照link visited hover active顺序编写
              • 链接都有默认颜色,所以要单独指定样式
              • 最常用的👇

               /*a是标签选择器 所有的链接*/
              a {
              color:gray;
              }
              /* :hover是连接伪选择器,鼠标经过*/
              a:hover {
              color: red;/*鼠标经过,链接由灰变红*/
              }
              

        • focus伪类选择器
          • 用于获取焦点

字体属性

• 字体系列

  • font-family:"微软雅黑"

    	<head>
    	    <style>
    	        h2 {
    	            font-family: '黑体';
    	            font-size: 30px;
    	        }
    	        p {
    	            font-family: 'Microsoft Yahei' 'Herago Sans GB';
    	            font-size: 20px;
    	            font-weight: bold;
    	        }
    	    </style>
    	</head>
    	
    	<body>
    	   <h2>蜜桃成熟时</h2>
    	    <p>那一抹最漂亮的粉</p>
    	    <p>优雅,淡然,纯净</p>
    	    <p>上吧,在不上人家就走啦!</p>
    	```
    

  • font-size: 20px:设定文字大小
  • font-weight:文字粗细normal bold bolder loghter 也可由100~900指定粗细如:font-weight: 700,提倡使用数字标记粗细
    • normal=400
    • bold = 700
  • font-style:文字样式
    • normal 默认显示
    • italic 倾斜显示

• 复合属性:

  • font: font-style font-weight font-size/font-height font-family

  div { font: font-style font-weight font-size/line-height font-family } /必须严格按照 风格|粗细|字号|字体 顺序排列/

  /案例/         h2 {             font-style: normal;             font-weight: bold;             font-size: 30px;             font-family: ‘Microsoft YaHei’;         } /可以写为/ h2{ font: normal bold 30px ‘Microsoft Yahei’ } ```

文本属性

• 文本颜色
  • color: red;
    • 可以用颜色词如:pink blue gray
    • 可以用十六进制#F3F3F3
    • 可以用RGB代码rgb(255,0,0)括号中的值分别对应三原色
• 对齐文本
  • text-align:只能用于水平对齐
    • text-align: left 左对齐 right右对齐 center居中
• 装饰文本
  • text-decoration:给文字添加下划线 删除线 下划线 等装饰
    • none默认’无’
    • underline下划线
    • overline上划线
    • line-through删除线
• 文本缩进
  • text-indent:首段落缩进

    	div {
    	text-indent: 32px;/*缩进多少用值表示*/
    	}
    	```
    - `px`像素
    - `em`文字的大小
    

• 行间距
  • line-height:文字与文字之间的距离
    • line-height: 25px使用像素为值,行高是包含文字大小的

CSS引入方式

• 样式表
  • 行内样式表(行内式)
    • <div style="font-size: 20px"?>直接在标签中加入style属性,且使用" 双引号包含需要设置的样式
  • 内部样式表(嵌入式)
    • 将所有需要的css都放在<style>标签中
    • <style>标签于html文件中,一般于<head>标头中
    • 清晰直观,但是未与html分开不便管理
  • 外部样式表(链入式)
    • 单独制作一个css文件 ,然后将css引入html页面
    • 在html页面使用<link rel="stylesheet" href="css文件路径">的方式引入css配置文件

Emmet语法

• HTML快速生成
  • 标签直接输入标签名后tab即可,如div后tab,可直接生成`
  • 标签后添加*＋数字则可以快速生成多个,如div*3可生成3个div
  • 父子级关系,可以直接用>,比如ui>li
  • 兄弟级关系,可以用加号+,例如div + p
  • 如果生成有类名字或者ID名字的
    • 直接写.demo,对应默认生成<div class="demo"
    • 直接写#demo,对应默认生成<div id="demo">
    • 也可以使用p.one,则会生成 <p class="one"
  • 如果想要生成有顺序的,.demo$5会生成从<div class="demo">一直到<div class="demo5">
  • 想要在生成标签内写内容可以直接使用{},div{demo这是一个demo}会生成<div>demo这是一个demo</div>
• CSS快速生成
  • text-align: center;可以简写为tac,为各个单词首字母
  • text-indent: 2em;可以简写为ti2em
  • width: 100px=w100
  • height: 20px=h20

元素的显示模式

• 就是元素<标签>以什么方式显示
  • 块元素
    • 独占一行 高度\宽度\内外\边距可修改 默认与父级宽度一致 可以内置其他元素 文字类标签不允许放置块级元素
  • 行内元素
    • 一行多个 高宽无法直接修改 默认宽度就是内容宽度 只能容纳文字和行内元素
      • 链接内无法再放链接,可以把链接转换为块级元素
  • 行内块元素
    • 如 <img /> <input /> <td>等元素,同时具有块元素和行内元素的特点
      • 一行可显多个 中间会有空隙 默认宽度为内容的宽度 宽高\内外边距都可修改
• 元素模式转换
  • *display:
    • inline 行内元素
    • *block 块级元素
    • *inline-block 行内块元素

文字居中

• 行高设置为盒子元素高度即可^{行高是包含文字本身高度的}

CSS背景

• 背景颜色background-color
  • 可以设置透明transparent 或者颜色'color'属性
• 背景图片background-image
  1. 和插入图片相比,好控制位置
     • background-image:url(#)
     • none值则没有备件图片
  2. 图片平铺background-repeat
     • 默认平铺
     • repeat no-repeat repeat-x repeat-y
  3. 图片位置background-position
     • background-position: x y
     • x y 可以用值确认精确位置,必须先x位置再y位置,也可也指令某一个值为方位名词
     • 也可以用 top center bottom left center right方位名词
  4. 图像固定background-attachment
     • scroll:滚动
     • fixed:固定
• 背景复合写法:
  • background:颜色 图片地址 平铺 是否滚动 位置
  • background:white url(#) no-repeat fixed top
• 背景颜色半透明
  • background: rgba(0,0,0,0.3)^{设置alpha不透明度}
  • 只更改背景色,不调整元素中的内容

三大特性

• 层叠行
  • 样式冲突的情况下,多个样式按照顺序选择最后一个值
  • 样式不冲突的不会层叠,直接多个样式同时执行
• 继承性
  • 子标签会继承父标签的某些样式: 字号 字符大小 字体风格 行高 行间距 `等
  • 可以通过这个特性,直接修改body样式,达到整个页面文字样式统一
• 优先级
  • 指定多个选择器
    • 选择器相同,样式层叠
    • 选择器不同,根据选择器权重
      • !important重要的 > 行内样式 style="" > ID选择器 > 类选择器,伪类选择器 > 元素选择器 > 继承或者*
  • 复合选择器会有权重叠加
    • 选择更加精确会有更大的权重 div ul li > ul li > li
    • 继承的权重为0!!!

盒子模型^{利用盒子摆样式}

1. 分析并准备好网页元素
2. 利用CSS设置号每个盒子的样式,摆放到相应位置
3. 填充盒子中的内容

• 组成部分
  • border- 边框
    • width :粗细,单位 px
    • style :样式
      • None无
      • hidden隐藏
      • dotted点线
      • dashed虚线
      • solid实线
      • double双实线,两台先与其间隔的和等于指定的border-width
      • groove根据border-color值画凹槽
      • ridge根据~画菱形边框
      • inset根据~画3D凹边
      • outset根据~画3D凸边
    • color: 颜色
    • 一般写为: border : border-width border-style border-color
    • border: 25px solid black没有顺序要求
    • collapse : 控制绘制表格的边框collapse^合并
    • *使用外边框,将会将盒子的空间扩展
  • content 内容
    • padding- 内容和盒边距
      • top:20px 顶部距离边框20像素
      • left :20px 左侧距离边框20像素
      • bottom:20px 底部距离边框20像素
      • right:20px 右侧距离边框20像素
      • padding:'上' '下' padding:10px 10px
      • padding : 上 左右 下 padding:10px 5px 10px
      • padding: '上' '右' '下' '左' padding: 10px 5px 10px 5px
• padding内边距
  • 如果盒子本身没有指定宽高,此时Padding的值则不会撑开盒子大小
• margin 外边距
  • 盒与盒的间距
    • 以上内外边距二级参数均为left right top bottom
    • margin: 5px 10px 15px 20px; 复写顺序为 上右下左
  • 外边距可以使盒子水平居中
    • 只能给块元素使用
    • 其余元素需要给父元素添加 text-align:center 来达成居中
    1. 盒子必须指定的宽度width
    2. 左右边距必须是auto 默认
       1. 常用居中设置 margin: 0 auto;
  • 嵌套元素的塌陷问题
    • 嵌套的块元素,父子同时有上外边距时,会导致父元素``上外边距塌陷
    1. 为父元素定义上边框
       • border: 1px solid transparent;使用``transparent`添加一个透明边框
       • 会导致此盒子多出像素
    2. 为父元素定义上内边距
       • padding: 1px 或者 padding-top:1px
       • 会导致此盒子多出像素
    3. 为父元素添加 *overflow:hidden
       • 此方���不会导致盒子有大小变化

清除内外边距

• 每个不同的元素都带了不同的内外边距
• #必须写在 style 中使用 *{padding:0; margin:0;} 来清除所有默认边框

圆角边框

• border-radius:length值为半径,可以是 值 也可以是百分比
• 圆形:正方形元素,把这个值设置为边长的一半
  • 简写规则:
    • 4个值:border:左上 右上 右下 左下 值与上方规则一致
    • 2个值: border:左上 右上会按照对角线生成圆角
    • 指定某一个角,border-top-left指定左上角

盒子阴影

• box-shadow :
  • h-shadow :水平阴影的位置.允许负数
  • v-shadow:垂直阴影的位置.允许负数
  • blur:模糊距离
  • spread:阴影的大小
  • color:阴影颜色
  • inset:内部阴影
    • 阴影不影响盒子像素大小

文字阴影

• text-shadow:
  • h-shadow :水平阴影的位置.允许负数
  • v-shadow:垂直阴影的位置.允许负数
  • blur:模糊距离
  • color`:阴影颜色

CSS浮动

• 属性:
  1. 可以改变标签默认的排列模式
  2. 可以让多个块级元素同行显示
  3. 竖向排列基本都是默认标签排列,浮动基本用于横向排列
  4. 贴近到相近元素的边缘
• load : none left right 对应 不浮动 左浮动 右浮动
• 特性
  1. 浮动元素会脱离标准流
     • 浮动的盒子不再保留原先的位置
     • 原本的位置会被相邻标签元素替代
     • 如果父元素无法包含浮动元素,剩下的元素会另起一行
  2. 浮动元素会具有行内块元素的特性
  3. 浮动元素经常和``标准流``父级搭配使用
     • 为了约束浮动的元素,先采用标准流父级排列上下,在用浮动排列左右
• 注意:同一个方块中的元素,只要有一个标签浮动,那都需要浮动,不然会出问题
  • 浮动的盒子指挥影响后面代码的标准流,不会影响到前面的标准流
• 清除浮动
  1. 本质是为了清除浮动所带来的其他影响
  2. 如果父盒子本身有高度就不需要清除浮动
  3. 清除浮动之后,父级就会根据子级的高度自动调整高度
  • clear:
    1. left:清除左侧
    2. right:清除右侧
    3. both:都清除
• 如何使用:
  1. 额外标签法称之为隔墙法,是W3C推荐的做法
     1. 在浮动标签的末尾添加一个空标签

        <div style=" clear:both" > </div>
        /*或者*/
        <br />
        /*只要是空标签皆可*/
        

     2. 优点:通俗易懂,书写简单.
     3. 缺点:添加许多无意义标签,结构差
     4. 要求添加的空元素必须是一个块级元素
  2. 父级添加overflow属性
     1. 添加overflow元素,属性值设置为 hidden auto scrll皆可
        1. auto 自动
        2. hidden 删除浮动,无法查看溢出部分
        3. scrll 删除浮动,显示拖动条
     2. 优点:代码简洁
     3. 缺点:无法显示出溢出的部分
  3. 父级添加after伪元素
     1. :after

        .clearfix:after{
        	content:"";
        	display:block;
        	height:0;
        	clear:both;
        	visibolity:hidden;
        }
        .clearfix{ /* IE6 IE8专用*/
        *zoom: 1;
        }
        

  4. 父级添加双伪元素

     .clearfix:before, .clearfix:after {
     	content:"";
     	display:table;
     	}
     .clearfix:after{
     	clear:both;
     	}
     .clearfix {
     	*zoom:1;*
     	}
     

CSS书写顺序

1. 布局定位: display position float clar visibility overflow (建议display第一个写,关系到整个页面的模式)
2. 自身属性: width height margin padding border background
3. 文本属性: color font text-decoration text-align vertical-align white-space break-word
4. 其他属性: content cursor border-radius box-shadow text-shadow background:linear-geadient...

• 数学顺序: 整体布局 元素自身属性 元素内文本属性 美化属性

“国产化”，近几年被提到的次数越来越堵。 但真正开始落地时，很多人会面对一个现实问题：

国产化不是简单的换一个系统， 而是整个使用习惯推翻重来的过程。

真正的难点，从来不在于技术本身，
而在于老百姓是否愿意尝试，和能否持续使用下去。

在全面国产化的前提下，操作系统是普通人参与其中最实际的选择。

为什么推荐deepin?

迄今为止，常见的国产操作系统有

• 统信UOS,是为“信创体系下的大规模单位部署”而设计的操作系统。基于Linux内核，但主要设计理念是面对政府及机关单位，个人使用会有大量的权限问题。
• 麒麟系统，以kylinServer和openKylin为代表，前者是为全面国产化的单位和服务器使用，后者是面向普通人、国产开发者和学习者使用。但因历史遗留问题，存在基于FreeBSD，Debian，redhat等多个发行版本，对于普通用户首次接触国产化并不友好，很容易因上手难度而放弃。
• deepin深度操作系统，单纯为普通人日常使用而开发的国产系统，使用Debian进行开发，自研的DDE桌面环境也可以使Windows用户和MAC用户大大降低上手难度，把大家印象中的Linux做成了普通人能用的样子。可以看作专为不会使用Linux的用户而开发设计。 本期全程无广，从安装到使用，站在普通消费者的层面告诉你，面对国产化转型，deepin为什么是最优的选择。

安装便捷|中文友好

首先，是安装便捷，全程图形化界面安装，没有任何一处需要使用命令行，直接下一步下一步就可以完成系统的安装。 进入系统后，不需要自己配置输入法，系统已经部署好了中文输入法以及搜狗输入法，不用额外折腾。

安装软件

第二个就是软件的安装方便，这点和其他的国产系统一样，类似MacOS的appstore，可以直接搜索到应用，点击鼠标直接下载，全程无需配置环境或者编译。 相比其他国产系统，deepin完整开放了apt包管理器，你可以安装所有.deb的软件包，以及通过flatpak安装其余应用，大大的扩展了软件生态。

• 面对普通用户，其自带的软件商店，已经可以满足大部分的办公需求，如微信、QQ、企业微信、钉钉、飞书等办公通讯软件都可以直接一键下载。
  • 文档表格处理，也可以使用wps或onlyoffce等软件完全替代微软OFFICE生态。在国产Linux高速发展的今天，xmind、腾讯文档、映像笔记等软件也有了Linux原生版本，不需要再折腾虚拟化。
• 面对开发者，软件商店也支持VsCode，JetBrains等大部分IDE的一键下载，可以免环境配置，开箱即用。
• 面对音视频处理，这是Linux系统最大的短板。想要在没有性能损失，原生运行的前提条件下，能选择的软件相当有限。
  • 图片处理，我推荐GIMP
  • 音频处理，可以选择Audacity
  • 视频处理现在的选择相较前几年比较丰富，可以在应用商店安装剪映或者必剪。专业视频工作者也可以使用达芬奇。这里只进行软件分享，如何使用可以自行搜索学习。
• 面对游戏，虽然原生支持Linux的游戏数量较少，但现在Steam的proton已经可以完美且流畅的运行大部分3A，且据Linux玩家反馈，同样的游戏相较于Windows反而可以获得更高的帧率，以及更稳定的Low帧。但是这一切都是基于虚拟层运行，游玩带小蓝熊等反作弊的游戏，暂时没有解决方案。

易上手

第三个就是易上手，大部分的民用消费级的电脑，在Linux的内核中已经集成了驱动，安装即用，不用再去折腾驱动或者.Net dx等环境。

• 所有的文本文件处理快捷键和windows一致，例如：复制、粘贴、剪切、全选、查找等都是一样的。常用的系统快捷键也一致，显示桌面win+d，锁屏win+l，打开资源管理器win+e，切换视图win+tab，系统搜索win+s，从使用习惯上来说没有任何困难。
• 同样可以像windows一样，通过win键呼出开始菜单，从中可以打开所有已经安装的软件。 桌面的图标同样可以删除，或者通过开始菜单添加快捷方式，还保留了大部分Windows用户的一个习惯刷新按钮。
• 在桌面设置中和windows的右键类似，同样可以设置是否自动化排列，图标大小，也可以选择是否打开应用的自动分类。
• 显示设置也和windows的显示设置功能基本一致。
• 通过开始菜单进入控制中心，这里可以设置系统所有可自定义的选项，不存在其余Linux中汉化不完整的情况，也不存在Windows中找不到对应设置和窗口不统一，这种割裂的情况。整个设置面板清晰统一，面对第一次尝试国产Linux系统的用户非常友好。

劝退

当然除开这些优势，国产Linux依然有很多问题存在。 比如：

• 在面对普通个人用户来说，应用商店中依然未收录很多支持Linux的软件，导致有软件但找不到的情况在小白群体经常发生，且找不到能用的软件成为了劝退的一大原因。
• 且国产系统普遍都存在一个问题臃肿，为了照顾到Windows以及mac用户的使用习惯，国产系统中包含了大量的主题、动画、以及非必要的第一方软件，导致想要使用虚拟机体验的用户因动画卡顿放弃使用。又或者是在老电脑使用时，发现和社区其他发行版Linux的性能差距极大，导致选择其他发行版。 这里不提及兼容性问题，因为是软件厂商不对Linux系统进行针对性开发，这并非系统层面的问题，而是需要更多的软件厂商参与进来。

总结

国产系统，相较于其他发行版来说，社区的活跃度是最能体现问题的地方。 部分使用者在遭遇问题时，因该系统使用人数较少，根本找不到对应问题的解决方案。 而且因为Linux的用户基数相较于Windows、MacOS少很多，导致很多软件的厂商根本不会考虑针对Linux的开发。 所以，想要Linux可以更加普及，需要我们每个人都参与进来，壮大Linux的队伍，这样软件厂商也会开始考虑针对Linux进行软件开发。 同时，想要国产系统可以更加快速，更加普及，更加强大、我们每个人的参与是必不可少的。 我们所遇到的每一个问题，所提交的每一个BUG，都将帮助国产化进程更稳定的发展。 在社区中反馈的问题，都会推进国产系统厂商进行优化、整改，从而让更多人原意尝试使用国产系统，实现良性循环。

结语

欢迎在评论区留下属于你的看法，也欢迎讨论你在使用Linux时所遇到的问题。我是汪多多它爹，一个失业的运维工程师，我们下期再见。

Dify Agent 节点使用指南

概述

Agent 节点是 Dify 中高度封装的智能单元，具备自主思考和规划能力。你只需要给它设定目标（Goal）并提供工具（Tools），它就能在内部自主地思考、规划、执行任务。

Agent 节点基础

什么是 Agent 节点

Agent 节点是一个高度封装的智能单元，可以：

• 自主思考任务目标
• 规划执行步骤
• 选择合适的工具
• 处理复杂任务
• 适应不同场景

与 LLM 节点的区别

适用场景

创建 Agent 节点

添加 Agent 节点

步骤：

1. 在工作流画布中点击 + 按钮
2. 选择 Agent 节点
3. 将节点添加到画布

基础配置

目标设置：

Agent 节点配置:
  goal: "帮助用户完成特定任务"
  instruction: |
    你是一个智能助手，可以：
    1. 搜索网络信息
    2. 读取文件内容
    3. 调用 API 接口
    4. 分析数据
    
    根据用户需求，自主规划并执行任务。

提示词模板：

提示词配置:
  role: "智能助手"
  expertise:
    - "信息检索"
    - "数据分析"
    - "任务规划"
  personality: "专业、高效、可靠"

工具配置

可用工具

Dify 支持多种工具类型：

配置工具

启用工具：

工具配置:
  enabled_tools:
    - name: "web_search"
      description: "搜索网络信息"
      provider: "google"
      max_results: 10
    
    - name: "file_read"
      description: "读取文件内容"
      allowed_paths:
        - "/data/documents"
        - "/data/reports"
    
    - name: "api_call"
      description: "调用 API 接口"
      endpoints:
        - name: "weather"
          url: "https://api.weather.com/v1/current"
          method: "GET"
        - name: "stock"
          url: "https://api.stock.com/v1/quote"
          method: "GET"
    
    - name: "calculator"
      description: "数学计算"
      operations:
        - "addition"
        - "subtraction"
        - "multiplication"
        - "division"
        - "statistics"

工具权限：

工具权限:
  web_search:
    max_results: 10
    timeout: 30
  
  file_read:
    allowed_paths:
      - "/data/documents"
      - "/data/reports"
    max_file_size: 10485760  # 10MB
  
  api_call:
    rate_limit: 60  # 每分钟 60 次
    timeout: 10

自定义工具

创建自定义工具：

自定义工具:
  name: "custom_analysis"
  description: "自定义数据分析工具"
  type: "api"
  endpoint: "https://api.example.com/analyze"
  method: "POST"
  headers:
    Authorization: "Bearer ${API_KEY}"
  parameters:
    - name: "data"
      type: "object"
      required: true
    - name: "options"
      type: "object"
      required: false

推理配置

推理策略

Dify 支持多种推理策略：

配置推理

推理设置：

推理配置:
  enabled: true
  strategy: "tree_of_thought"  # chain_of_thought, tree_of_thought, react
  max_iterations: 5
  max_thought_depth: 3
  timeout: 300

推理参数：

推理参数:
  thought_budget: 1000  # 思考预算（token 数）
  action_budget: 10  # 动作预算（最多执行 10 次工具调用）
  confidence_threshold: 0.7  # 置信度阈值

推理示例

任务：搜索并分析某个主题

推理过程：

1. 思考：用户想要了解 AI 的发展趋势
2. 规划：搜索相关信息 → 分析内容 → 总结结论
3. 执行：
   • 调用 web_search 搜索"AI 发展趋势"
   • 读取搜索结果
   • 分析关键信息
   • 生成总结
4. 输出：提供详细的趋势分析报告

记忆管理

短期记忆

短期记忆配置：

短期记忆:
  enabled: true
  max_messages: 20
  strategy: "recent"  # recent, summary
  retain_period: 3600  # 保留 1 小时

长期记忆

长期记忆配置：

长期记忆:
  enabled: true
  storage: "vector_db"  # vector_db, file, database
  retrieval:
    top_k: 5
    threshold: 0.7

上下文管理

上下文配置：

上下文管理:
  enabled: true
  context_window: 8000  # 上下文窗口大小
  retain_strategy: "hybrid"  # recent, summary, hybrid
  compression:
    enabled: true
    threshold: 0.8

使用示例

研究助手

目标：自动检索和总结信息

配置：

Agent 节点配置:
  goal: "帮助用户研究特定主题"
  instruction: |
    你是一个研究助手，可以：
    1. 搜索网络信息
    2. 读取学术文献
    3. 分析数据
    4. 生成研究报告
    
    研究步骤：
    1. 理解研究主题
    2. 搜索相关资料
    3. 分析关键信息
    4. 生成结构化报告
  tools:
    - "web_search"
    - "file_read"
    - "calculator"
  reasoning:
    strategy: "tree_of_thought"
    max_iterations: 5

数据分析助手

目标：自动收集和分析数据

配置：

Agent 节点配置:
  goal: "帮助用户分析数据"
  instruction: |
    你是一个数据分析助手，可以：
    1. 读取数据文件
    2. 执行统计分析
    3. 生成可视化报告
    4. 提供洞察和建议
    
    分析步骤：
    1. 理解数据结构
    2. 执行统计分析
    3. 识别模式和趋势
    4. 生成报告和建议
  tools:
    - "file_read"
    - "calculator"
    - "database"
  reasoning:
    strategy: "react"
    max_iterations: 10

任务自动化助手

目标：自动完成多步骤任务

配置：

Agent 节点配置:
  goal: "帮助用户完成自动化任务"
  instruction: |
    你是一个任务自动化助手，可以：
    1. 读取任务描述
    2. 分解任务步骤
    3. 执行每个步骤
    4. 汇总结果
    
    自动化流程：
    1. 理解任务需求
    2. 规划执行步骤
    3. 调用相应工具
    4. 监控执行过程
    5. 生成执行报告
  tools:
    - "file_read"
    - "api_call"
    - "web_search"
  reasoning:
    strategy: "chain_of_thought"
    max_iterations: 8

高级功能

任务分解

任务分解配置：

任务分解:
  enabled: true
  max_subtasks: 10
  parallel_execution: true
  dependency_resolution: true

错误处理

错误处理配置：

错误处理:
  enabled: true
  strategy: "retry"  # retry, skip, stop
  max_retries: 3
  retry_delay: 5
  fallback_to_human: true

协作能力

多 Agent 协作：

多 Agent 配置:
  enabled: true
  agents:
    - id: "researcher"
      role: "信息收集"
      tools:
        - "web_search"
        - "file_read"
    - id: "analyst"
      role: "数据分析"
      tools:
        - "calculator"
        - "database"
    - id: "writer"
      role: "报告撰写"
      tools:
        - "file_write"
  collaboration:
    mode: "sequential"  # sequential, parallel, hybrid

性能优化

推理优化

减少推理次数：

推理优化:
  enabled: true
  thought_pruning: true  # 剪枝不重要的思考
  action_caching: true  # 缓存工具调用结果
  early_stopping: true  # 提前停止

工具优化

工具调用优化：

工具优化:
  enabled: true
  parallel_execution: true
  batch_size: 5
  timeout: 30

记忆优化

记忆压缩：

记忆压缩:
  enabled: true
  compression_ratio: 0.5  # 压缩到 50%
  strategy: "summary"  # summary, keyword

监控和调试

监控指标

关键指标：

监控指标:
  - name: "推理次数"
    target: "< 10"
  - name: "工具调用次数"
    target: "< 20"
  - name: "执行时间"
    target: "< 300s"
  - name: "成功率"
    target: "> 90%"

调试工具

查看推理过程：

1. 点击 Agent 节点
2. 查看 推理日志
3. 分析思考过程
4. 识别问题

查看工具调用：

1. 查看 工具调用日志
2. 检查输入输出
3. 验证结果
4. 优化配置

日志分析

日志类型：

• 思考日志
• 行动日志
• 工具调用日志
• 错误日志

最佳实践

设计原则

• 明确目标：清晰定义 Agent 的目标
• 合理工具：提供必要的工具，避免过多
• 优化推理：选择合适的推理策略
• 监控性能：持续监控和优化

工具选择

工具选择原则：

• 选择最相关的工具
• 避免冗余工具
• 优化工具配置
• 测试工具性能

推理优化

推理优化建议：

• 选择合适的推理策略
• 设置合理的迭代次数
• 优化思考预算
• 监控推理过程

常见问题

Q1: Agent 执行时间过长怎么办？

解决方案：

• 减少 max_iterations
• 优化工具调用
• 启用 early_stopping
• 优化推理策略

Q2: Agent 选择错误的工具怎么办？

解决方案：

• 优化工具描述
• 调整推理策略
• 增加工具权限限制
• 提供更多示例

Q3: 如何提高 Agent 的准确性？

解决方案：

• 优化提示词
• 改进工具配置
• 增加推理迭代
• 收集反馈优化

资源链接

• Agent 节点文档: https://docs.dify.ai/zh/use-dify/tutorials/workflow-101/lesson-08
• 工具文档: https://docs.dify.ai/zh/use-dify/tools
• 推理策略文档: https://docs.dify.ai/zh/use-dify/reasoning

最后更新: 2026-03-12 作者: EchoHaoRan

Dify 介绍和核心概念

概述

Dify 是一个用于构建 AI 工作流的开源平台。通过在可视化画布上编排 AI 模型、连接数据源、定义处理流程，直接将你的领域知识转化为可运行的软件。Dify 融合了后端即服务（Backend as Service）和 LLMOps 的理念，使开发者可以快速搭建生产级的生成式 AI 应用。

Dify 是什么

产品定位

Dify 是一款开源的大语言模型（LLM）应用开发平台，旨在帮助开发者：

• 快速构建生产级的生成式 AI 应用
• 可视化编排 AI 工作流
• 集成自定义知识和数据源
• 部署和管理 AI 应用

核心价值

核心概念

应用类型

Dify 提供多种应用类型，适用于不同的场景：

节点类型

Dify 工作流由多种节点组成，每个节点承担特定功能：

输入节点

• 用户输入节点：定义从用户收集的信息
• 开始节点：工作流的入口点

处理节点

• LLM 节点：调用大语言模型处理文本
• 参数提取器节点：从文本中提取结构化参数
• 代码节点：执行自定义代码逻辑
• IF/ELSE 节点：条件分支逻辑
• 迭代节点：循环处理列表数据
• 列表操作器节点：过滤、映射、操作数组
• 文档提取器节点：从文档中提取文本
• 模板节点：使用 Jinja2 模板格式化输出

输出节点

• 答案节点：向用户返回格式化内容
• 输出节点：工作流的出口点

Agent 节点

• Agent 节点：高度封装的智能单元，具备自主思考能力

核心组件

知识库

知识库允许将自有数据集成到 AI 应用中，通过检索增强生成（RAG）技术提升回答准确性。

工作原理：

1. 检索：从知识库中检索相关信息
2. 增强：将检索信息与用户问题结合
3. 生成：基于增强上下文生成答案

应用场景：

• 智能客服机器人
• 企业内部知识门户
• 内容生成工具
• 科研与分析应用

模型供应商

支持多种 LLM 提供商：

• OpenAI（GPT 系列）
• Anthropic（Claude 系列）
• Google（Gemini 系列）
• 国产模型（通义千问、智谱、DeepSeek 等）
• 本地模型（Ollama、LocalAI、Xinference）

工具

扩展 AI 能力的插件，包括：

• 网络搜索
• 文件操作
• API 调用
• 数据库查询

工作流概念

工作流 ID

工作流 ID 记录当前工作流应用中所有节点的信息，可用于：

• 跟踪和记录工作流执行
• 调试和监控
• 日志关联

系统变量：sys.workflow_run_id

执行模式

串行执行

节点一个接一个连接，按顺序执行，每个节点等待前一个节点完成。

并行执行

多个节点同时执行，缩短任务处理时间。

流程逻辑

Dify 提供丰富的逻辑节点：

• 条件分支（IF/ELSE）
• 循环迭代
• 错误处理
• 变量传递

应用生命周期

创建阶段

1. 选择应用类型
2. 配置提示词和流程
3. 集成知识库和工具
4. 选择模型提供商

开发阶段

1. 测试节点功能
2. 调试工作流
3. 优化性能
4. 添加日志和监控

发布阶段

1. 生成 API 凭据
2. 配置 Web 应用
3. 设置访问权限
4. 部署到生产环境

运维阶段

1. 监控应用性能
2. 查看执行日志
3. 优化资源使用
4. 更新应用版本

关键特性

检索增强生成（RAG）

通过将自定义知识集成到 LLM 中，实现：

• 减少幻觉
• 提高回答准确性
• 支持特定领域知识

结构化输出

强制模型返回特定格式（如 JSON），便于程序化处理。

多模态支持

支持处理多种数据类型：

• 文本
• 图像
• 文档
• 音频

记忆管理

支持对话上下文的记忆，实现：

• 多轮对话
• 会话持续
• 上下文保留

变量系统

使用双花括号语法引用变量：

{{variable_name}}

支持：

• 用户输入变量
• 系统变量
• 环境变量
• 节点输出变量

部署选项

Dify Cloud

• 优点：无需维护，快速上手
• 适用：个人用户、小团队、快速原型

自部署

支持多种部署方式：

• Docker

• Docker Compose

• Kubernetes

• 源码部署

• 优点：数据隐私、完全控制、成本可控

• 适用：企业用户、数据敏感场景

API 能力

文本生成 API

适用于单次文本生成场景。

对话 API

支持多轮对话，自动管理会话状态。

工作流 API

执行工作流应用，返回结构化结果。

API 安全

• 密钥管理
• 速率限制
• 请求验证
• 日志记录

最佳实践

设计原则

• 模块化：将复杂流程分解为可复用的小组件
• 可测试性：每个节点应可独立测试
• 错误处理：完善的异常处理机制
• 性能优化：合理使用并行和缓存

开发建议

• 从简单应用开始，逐步增加复杂度
• 充分利用模板和示例
• 定期测试和优化
• 关注日志和监控

安全建议

• 保护 API 密钥
• 实施访问控制
• 定期审查权限
• 监控异常行为

资源链接

• Dify 官方网站: https://dify.ai
• Dify 官方文档: https://docs.dify.ai
• GitHub 仓库: https://github.com/langgenius/dify
• 社区论坛: https://community.dify.ai

最后更新: 2026-03-12 作者: EchoHaoRan

Dify 大语言模型配置

概述

在使用大型语言模型节点之前，需要在 系统设置 → 模型供应商 中配置至少一个模型供应商。本文将详细介绍如何在 Dify 中配置和使用各种大语言模型。

模型选择和参数

配置模型供应商

步骤：

1. 进入 系统设置
2. 选择 模型供应商
3. 点击 添加供应商
4. 配置 API 密钥
5. 测试连接

支持的模型提供商

模型选择建议

LLM 节点配置

模型选择

从已配置的任何模型供应商中进行选择。

配置示例：

LLM 节点配置:
  model:
    provider: "openai"
    name: "gpt-4o"
    mode: "chat"  # chat, completion

温度参数

温度控制输出的随机性和创造性：

配置示例：

LLM 节点配置:
  model:
    temperature: 0.7

核采样（Top P）

通过概率限制词汇选择，通常设置在 0.8-1.0。

配置示例：

LLM 节点配置:
  model:
    top_p: 0.95

频率惩罚

减少重复内容，范围 -2.0 到 2.0。

配置示例：

LLM 节点配置:
  model:
    frequency_penalty: 0.5

存在惩罚

鼓励讨论新话题，范围 -2.0 到 2.0。

配置示例：

LLM 节点配置:
  model:
    presence_penalty: 0.3

预设选项

Dify 提供三种预设配置：

提示词配置

提示词类型

聊天模型

使用消息角色：

• 系统（System）：定义 AI 的行为和角色
• 用户（User）：用户的输入
• 助手（Assistant）：AI 的回复示例

配置示例：

LLM 节点配置:
  prompt:
    system: "你是一个专业的 {{role}}，专注于 {{expertise}}。"
    user: "请处理以下内容：{{input}}"
    assistant: "这是一个示例回复。"

完成模型

使用简单的文本续写。

配置示例：

LLM 节点配置:
  prompt:
    completion: "以下是一段文本：{{text}}\n\n请继续："

变量引用

使用双花括号语法引用工作流变量：

LLM 节点配置:
  prompt:
    system: "你是 {{User Input/role}}"
    user: "处理：{{Previous Node/output}}"

Jinja2 模板支持

使用 Jinja2 模板进行高级变量处理：

LLM 节点配置:
  prompt:
    system: |
      你是一个 {{role|default('助手')}}。
      {% if language %}
      请使用 {{language}} 回答。
      {% endif %}

支持的 Jinja2 功能：

• 变量替换
• 条件判断
• 循环
• 过滤器

上下文变量

知识库上下文

将知识库内容注入到 LLM 节点中。

配置示例：

LLM 节点配置:
  context:
    knowledge_base: "product_docs"
    retrieval:
      top_k: 5
      similarity_threshold: 0.7
    variable_name: "context"
  prompt:
    system: "你是一个客服助手。"
    user: |
      基于以下上下文回答问题：
      {{context}}
      
      问题：{{query}}

文件上下文

处理上传的文件，包括图像和文档。

配置示例：

LLM 节点配置:
  context:
    files:
      variable: "User Input/user_file"
      vision:
        enabled: true
        detail: "high"  # high, low
      document:
        extract_text: true

变量来源

结构化输出

配置结构化输出

强制模型返回特定数据格式（如 JSON）以便程序化使用。

配置方法：

1. 可视化编辑器
2. JSON Schema
3. AI 生成

可视化编辑器

配置示例：

LLM 节点配置:
  structured_output:
    enabled: true
    schema:
      type: "object"
      properties:
        title:
          type: "string"
          description: "标题"
        content:
          type: "string"
          description: "内容"
        tags:
          type: "array"
          items:
            type: "string"
          description: "标签列表"
      required:
        - "title"
        - "content"

JSON Schema

直接粘贴 JSON Schema 定义。

配置示例：

{
  "type": "object",
  "properties": {
    "platform_name": {
      "type": "string",
      "description": "平台名称"
    },
    "post_content": {
      "type": "string",
      "description": "帖子内容"
    },
    "hashtags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "标签列表"
    },
    "character_count": {
      "type": "number",
      "description": "字符数"
    }
  },
  "required": ["platform_name", "post_content"]
}

AI 生成

让 AI 自动生成适合的 Schema。

步骤：

1. 点击 AI 生成
2. 描述需要的数据结构
3. AI 自动生成 Schema
4. 手动调整和优化

记忆和文件处理

记忆管理

记忆是节点特定的，不会在不同对话之间持续存在。

配置示例：

LLM 节点配置:
  memory:
    enabled: true
    max_messages: 10
    strategy: "recent"  # recent, summary

文件处理

支持处理多种文件类型：

图像处理：

LLM 节点配置:
  files:
    vision:
      enabled: true
      detail: "high"  # 高细节，更准确但使用更多 token
      # 或 "low" - 低细节，更快但准确性较低

文档处理：

LLM 节点配置:
  files:
    document:
      extract_text: true
      max_pages: 10

自动获取文件：

LLM 节点配置:
  files:
    variable: "User Input/user_file"  # 自动从用户输入节点获取

流式结果返回

流式响应

大型语言模型节点默认支持流式结果返回。

配置示例：

LLM 节点配置:
  streaming:
    enabled: true
    chunk_size: 100

流式事件

每个文本块都作为 RunStreamChunkEvent 产生，实现实时响应显示。

事件类型：

• message：文本块
• message_end：消息结束
• error：错误信息

不同场景的配置

创意写作

LLM 节点配置:
  model:
    temperature: 0.9
    top_p: 0.95
    frequency_penalty: 0.5
    presence_penalty: 0.3
  prompt:
    system: "你是一个创意写作专家。"
    user: "请创作一个关于 {{topic}} 的故事。"

代码生成

LLM 节点配置:
  model:
    temperature: 0.2
    top_p: 0.95
    frequency_penalty: 0.0
    presence_penalty: 0.0
  prompt:
    system: "你是一个专业的程序员。"
    user: "请编写一个 {{language}} 函数来 {{task}}。"
  structured_output:
    enabled: true
    schema:
      type: "object"
      properties:
        code:
          type: "string"
        explanation:
          type: "string"

文档摘要

LLM 节点配置:
  model:
    temperature: 0.3
    top_p: 0.9
    frequency_penalty: 0.1
    presence_penalty: 0.1
  prompt:
    system: "你是一个文档摘要专家。"
    user: |
      请总结以下文档：
      {{context}}
      
      摘要要求：
      1. 提取关键信息
      2. 保持简洁（不超过 500 字）
      3. 使用要点列表

问答系统

LLM 节点配置:
  model:
    temperature: 0.1
    top_p: 0.85
    frequency_penalty: 0.0
    presence_penalty: 0.0
  context:
    knowledge_base: "faq"
    retrieval:
      top_k: 3
  prompt:
    system: "你是一个客服助手。"
    user: |
      基于以下信息回答问题：
      {{context}}
      
      问题：{{query}}
      
      如果信息不足，请诚实告知。

性能优化

Token 优化

控制上下文长度：

LLM 节点配置:
  model:
    max_tokens: 2000

使用缓存：

LLM 节点配置:
  cache:
    enabled: true
    ttl: 3600

批处理

批量处理相似请求：

迭代节点:
  parallel_mode: true
  max_parallelism: 10

模型选择

根据任务复杂度选择合适的模型：

路由配置:
  rules:
    - condition: "task.complexity < 3"
      model: "gpt-4o-mini"
    - condition: "task.complexity >= 3"
      model: "gpt-4o"

故障排查

连接问题

症状：无法连接到模型 API

解决方案：

# 测试网络连接
curl -I https://api.openai.com

# 检查 API 密钥
echo $OPENAI_API_KEY

# 测试模型连接
openclaw model test <model-id>

认证问题

症状：401 Unauthorized 错误

解决方案：

# 验证 API 密钥
echo $OPENAI_API_KEY

# 重新设置 API 密钥
export OPENAI_API_KEY="new-key"

# 测试连接
openclaw model test <model-id>

限流问题

症状：429 Too Many Requests 错误

解决方案：

# 降低请求频率
rate_limit:
  enabled: true
  requests_per_minute: 60

# 使用多个 API 密钥
providers:
  - name: "openai"
    api_keys:
      - "${OPENAI_API_KEY_1}"
      - "${OPENAI_API_KEY_2}"

资源链接

• OpenAI 文档: https://platform.openai.com/docs
• Anthropic 文档: https://docs.anthropic.com
• Dify 模型文档: https://docs.dify.ai/zh/use-dify/nodes/llm

最后更新: 2026-03-12 作者: EchoHaoRan

Dify 工作流详解

概述

工作流是 Dify 中用于构建复杂 AI 应用的核心功能。通过可视化画布编排多个节点，你可以创建强大的自动化流程。本文将详细介绍工作流的各种节点类型、执行模式和最佳实践。

工作流基础

工作流 ID

工作流 ID 是一个唯一标识符，记录当前工作流应用中所有节点的信息。

用途：

• 跟踪和记录工作流执行
• 调试和监控
• 日志关联

系统变量：

sys.workflow_run_id

执行模式

串行执行

节点一个接一个连接，按顺序执行。每个节点等待前一个节点完成后再开始。

适用场景：

• 有依赖关系的任务
• 需要顺序处理的流程
• 数据转换和清洗

并行执行

多个节点同时执行，缩短任务处理时间。

适用场景：

• 独立任务
• 批量处理
• 多渠道数据获取

配置示例：

# 迭代节点并行配置
iteration:
  enabled: true
  parallel_mode: true
  max_parallelism: 10

节点类型详解

输入节点

用户输入节点

定义从用户收集的信息作为应用程序的输入。

配置选项：

• 字段类型：短文本、段落、选择、文件列表等
• 变量名：用于引用的变量名称
• 标签名：显示给用户的标签
• 最大长度：文本长度限制
• 必填：是否必填

示例配置：

用户输入节点配置:
  - field: "platform"
    type: "短文本"
    variable: "platform"
    label: "目标平台"
    max_length: 256
    required: true

开始节点

工作流的入口点，定义应用的起始条件。

处理节点

LLM 节点

调用大语言模型处理文本、图像和文档。

核心功能：

• 文本生成和处理
• 多模态输入支持
• 结构化输出
• 上下文变量

配置参数：

LLM 节点配置:
  model: "gpt-4o"
  temperature: 0.7
  top_p: 0.95
  max_tokens: 2000
  frequency_penalty: 0
  presence_penalty: 0

温度参数：

• 0：确定性输出
• 0.5：平衡输出
• 1：创造性输出

预设选项：

• 精确（Precise）：温度 0.3
• 平衡（Balanced）：温度 0.7
• 创意（Creative）：温度 1.0

提示词配置：

提示词模板:
  system: "你是一个 {{role}}，专注于 {{expertise}}。"
  user: "请处理以下内容：{{input}}"

结构化输出：

结构化输出配置:
  type: "json"
  schema:
    type: "object"
    properties:
      title:
        type: "string"
      content:
        type: "string"
      tags:
        type: "array"
        items:
          type: "string"

参数提取器节点

从自然语言中提取结构化参数。

使用场景：

• 解析用户意图
• 提取关键信息
• 标准化输入

配置示例：

参数提取器配置:
  input_variable: "User Input/platform"
  extraction_parameters:
    - name: "platform"
      type: "Array[String]"
      description: "提取的社交媒体平台列表"
      required: true
  instruction: |
    提取文本中提到的所有社交媒体平台。
    有效平台：Twitter, LinkedIn, Facebook, Instagram, TikTok
    返回 JSON 数组格式。

代码节点

执行自定义代码逻辑。

支持语言：

• Python
• JavaScript

配置示例：

代码节点配置:
  language: "python"
  code: |
    def process_data(data):
        # 处理逻辑
        return {
            "result": data.upper(),
            "count": len(data)
        }
  input_variables:
    - name: "data"
      type: "string"
  output_variables:
    - name: "result"
      type: "object"

IF/ELSE 节点

基于条件创建分支逻辑。

配置示例：

IF/ELSE 节点配置:
  condition:
    field: "Parameter Extractor/platform"
    operator: "contains"
    value: "error message"
  branches:
    if:
      - 输出错误消息
    else:
      - 继续正常流程

支持的操作符：

• 等于（equals）
• 不等于（not equals）
• 包含（contains）
• 不包含（not contains）
• 大于（greater than）
• 小于（less than）

迭代节点

循环处理列表数据。

配置示例：

迭代节点配置:
  input_variable: "Parameter Extractor/platform"
  output_variable: "Create Content/structured_output"
  parallel_mode: true
  max_parallelism: 10
  internal_nodes:
    - LLM 节点
    - 代码节点

内部节点：

• 使用 {{Current Iteration/item}} 引用当前项
• 使用 {{Current Iteration/index}} 引用索引

列表操作器节点

过滤、映射、操作数组。

操作类型：

• 过滤（Filter）
• 映射（Map）
• 排序（Sort）
• 去重（Unique）

配置示例：

列表操作器配置:
  input_variable: "User Input/user_file"
  operation: "filter"
  condition: "{x}type == 'Image'"
  output_variable: "Image"

文档提取器节点

从文档中提取文本。

支持格式：

• PDF
• DOCX
• TXT
• MD

配置示例：

文档提取器配置:
  input_variable: "Document/result"
  output_variable: "text"
  options:
    extract_images: false
    preserve_formatting: true

模板节点

使用 Jinja2 模板格式化输出。

配置示例：

模板节点配置:
  input_variable: "Iteration/output"
  template: |
    {% for item in output %}
    # {{ item.title }}
    {{ item.content }}
    {% endfor %}
  output_variable: "formatted_output"

Jinja2 语法：

{% for item in items %}
  {{ item.name }}
{% endfor %}

{% if condition %}
  显示内容
{% endif %}

{{ variable | filter }}

输出节点

答案节点

定义在对话流应用中向用户传递的内容。

配置示例：

答案节点配置:
  content: "{{formatted_output}}"
  format: "markdown"
  streaming: true

输出节点

工作流的出口点，返回最终结果。

Agent 节点

高度封装的智能单元，具备自主思考能力。

配置示例：

Agent 节点配置:
  goal: "帮助用户完成特定任务"
  tools:
    - "web_search"
    - "file_read"
    - "api_call"
  reasoning:
    enabled: true
    max_iterations: 5

变量系统

变量类型

变量引用

使用双花括号语法引用变量：

{{variable_name}}

变量转换

支持 Jinja2 过滤器：

{{variable | upper}}
{{variable | length}}
{{variable | join(', ')}}

上下文变量

知识库上下文

将知识库内容注入到 LLM 节点中。

配置示例：

上下文变量配置:
  knowledge_base: "product_docs"
  retrieval:
    top_k: 5
    similarity_threshold: 0.7
  variable_name: "context"

文件处理

处理上传的文件，包括图像和文档。

配置示例：

文件处理配置:
  input_variable: "User Input/user_file"
  vision:
    detail: "high"  # high 或 low
  document:
    extract_text: true

调试和测试

单节点测试

单独测试任何节点而无需运行整个工作流。

步骤：

1. 选择节点
2. 在设置面板中提供测试输入
3. 点击运行
4. 查看输出

查看日志

查看每个节点的执行日志和错误信息。

性能分析

分析工作流的执行时间和资源使用。

最佳实践

设计原则

• 模块化：将复杂流程分解为可复用的小组件
• 可测试性：每个节点应可独立测试
• 错误处理：完善的异常处理机制
• 性能优化：合理使用并行和缓存

性能优化

并行执行：

迭代节点:
  parallel_mode: true
  max_parallelism: 10

缓存策略：

LLM 节点:
  cache_enabled: true
  cache_ttl: 3600

批量处理：

列表操作器:
  batch_size: 100

错误处理

IF/ELSE 节点:
  error_handling:
    strategy: "continue"  # continue, stop, retry
    max_retries: 3
    error_message: "处理失败，请重试"

高级功能

事件触发

支持定时触发和事件触发。

触发器配置:
  type: "schedule"
  cron: "0 9 * * *"  # 每天 9:00

Webhook

支持通过 Webhook 触发工作流。

子工作流

将工作流作为子流程调用。

子工作流节点:
  workflow_id: "sub-workflow-id"
  input_mapping:
    input1: "{{parent_output}}"
  output_mapping:
    result: "child_output"

资源链接

• 工作流文档: https://docs.dify.ai/zh/use-dify/build/orchestrate-node
• 节点文档: https://docs.dify.ai/zh/use-dify/nodes
• 教程系列: https://docs.dify.ai/zh/use-dify/tutorials/workflow-101

最后更新: 2026-03-12 作者: EchoHaoRan

Dify 应用发布和部署

概述

Dify 提供多种发布和部署方式，让你可以将创建的 AI 应用快速推向用户。本文将详细介绍如何将应用发布为 Web 站点、API 工具，以及如何进行私有化部署。

发布方式概览

发布为 Web 应用

快速发布

步骤：

1. 进入应用详情页
2. 点击 发布
3. 选择 发布更新
4. 等待发布完成

访问地址：

https://cloud.dify.ai/chatbot/xxx

Web 应用设置

基础设置：

Web 应用配置:
  enabled: true
  site_name: "我的应用"
  site_title: "AI 助手"
  description: "这是一个智能 AI 助手"
  icon: "https://example.com/icon.png"

主题配置：

主题配置:
  primary_color: "#007AFF"
  background_color: "#F5F5F5"
  text_color: "#333333"
  font_family: "Inter, sans-serif"
  border_radius: 8

高级设置：

高级配置:
  custom_domain: "app.example.com"
  ssl_enabled: true
  analytics:
    enabled: true
    provider: "google_analytics"
    tracking_id: "UA-XXXXXXXXX"

功能配置

对话设置：

对话配置:
  opening_statement: "您好！有什么可以帮您的吗？"
  suggested_questions:
    - "如何使用产品？"
    - "产品有哪些功能？"
    - "常见问题有哪些？"
  voice_input:
    enabled: true
    language: "zh-CN"
  voice_output:
    enabled: true
    voice: "female"

显示设置：

显示配置:
  show_branding: false  # 隐藏 Dify 品牌信息
  show_footer: true
  show_header: true
  show_share_button: true

访问控制

公开访问：

访问控制:
  type: "public"
  authentication: false

私有访问：

访问控制:
  type: "private"
  authentication: true
  allowed_users:
    - "user@example.com"
    - "user2@example.com"

密码保护：

访问控制:
  type: "password"
  password: "your_password"

API 集成

生成 API 凭据

步骤：

1. 进入应用详情页
2. 点击 API Access
3. 点击 创建凭据
4. 输入凭据名称
5. 点击 创建
6. 保存 API Key

API 文档

Dify 会自动生成完整的 API 文档，包括：

• 端点 URL
• 请求方法
• 请求参数
• 响应格式
• 示例代码

查看文档：

1. 进入 API Access 页面
2. 点击 查看文档
3. 查看详细的 API 说明

文本生成 API

端点：POST https://api.dify.ai/v1/completion-messages

请求示例：

curl --location --request POST 'https://api.dify.ai/v1/completion-messages' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "inputs": {
      "text": "Hello, how are you?"
    },
    "response_mode": "streaming",
    "user": "abc-123"
  }'

Python 示例：

import requests
import json

url = "https://api.dify.ai/v1/completion-messages"
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
}
data = {
    "inputs": {
        "text": "Hello, how are you?"
    },
    "response_mode": "streaming",
    "user": "abc-123"
}
response = requests.post(url, headers=headers, json=data)
print(response.text)

对话 API

端点：POST https://api.dify.ai/v1/chat-messages

请求示例：

curl --location --request POST 'https://api.dify.ai/v1/chat-messages' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "inputs": {},
    "query": "Hello",
    "response_mode": "streaming",
    "conversation_id": "",
    "user": "abc-123"
  }'

Python 示例：

import requests
import json

url = 'https://api.dify.ai/v1/chat-messages'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
}
data = {
    "inputs": {},
    "query": "Hello",
    "response_mode": "streaming",
    "conversation_id": "",
    "user": "abc-123"
}
response = requests.post(url, headers=headers, json=data)
print(response.text)

API 安全

最佳实践：

安全配置:
  credentials:
    development:
      api_key: "${DIFY_DEV_API_KEY}"
    testing:
      api_key: "${DIFY_TEST_API_KEY}"
    production:
      api_key: "${DIFY_PROD_API_KEY}"
  
  security:
    rate_limit: 100  # 每小时 100 次
    ip_whitelist: true
    allowed_ips:
      - "192.168.1.0/24"
      - "10.0.0.0/8"

发布为 MCP 服务器

什么是 MCP

MCP（Model Context Protocol）是一种让 AI 工具之间相互通信的标准协议。通过 MCP，你可以将 Dify 应用集成到 Claude Desktop 等 AI 工具中。

发布步骤

步骤：

1. 进入应用详情页
2. 点击 发布
3. 选择 发布为 MCP 服务器
4. 配置 MCP 参数
5. 点击 发布

MCP 配置

基础配置：

MCP 配置:
  enabled: true
  server_name: "my-dify-app"
  description: "我的 Dify 应用"
  version: "1.0.0"

工具配置：

工具配置:
  tools:
    - name: "generate_content"
      description: "生成内容"
      input_schema:
        type: "object"
        properties:
          topic:
            type: "string"
            description: "主题"
          style:
            type: "string"
            description: "风格"
        required:
          - "topic"

使用 MCP

在 Claude Desktop 中使用：

1. 打开 Claude Desktop
2. 进入设置
3. 添加 MCP 服务器
4. 输入 Dify 提供的 MCP URL
5. 开始使用

私有化部署

部署方式

Dify 支持多种私有化部署方式：

Docker 部署

步骤：

# 拉取镜像
docker pull langgenius/dify:latest

# 运行容器
docker run -d \
  --name dify \
  -p 80:80 \
  -e DATABASE_URL="postgresql://user:password@host:5432/dify" \
  -e REDIS_URL="redis://host:6379" \
  langgenius/dify:latest

Docker Compose 部署

docker-compose.yml：

version: '3.8'

services:
  dify-web:
    image: langgenius/dify-web:latest
    ports:
      - "3000:3000"
    depends_on:
      - dify-api
    environment:
      - API_URL=http://dify-api:5001

  dify-api:
    image: langgenius/dify-api:latest
    ports:
      - "5001:5001"
    depends_on:
      - db
      - redis
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/dify
      - REDIS_URL=redis://redis:6379/0

  db:
    image: postgres:15-alpine
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=dify
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres

  redis:
    image: redis:7-alpine
    volumes:
      - ./data/redis:/data

启动服务：

docker-compose up -d

Kubernetes 部署

deployment.yaml：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: dify-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: dify-api
  template:
    metadata:
      labels:
        app: dify-api
    spec:
      containers:
      - name: dify-api
        image: langgenius/dify-api:latest
        ports:
        - containerPort: 5001
        env:
        - name: DATABASE_URL
          value: "postgresql://postgres:postgres@db:5432/dify"
        - name: REDIS_URL
          value: "redis://redis:6379/0"

启动服务：

kubectl apply -f deployment.yaml

监控和维护

监控指标

关键指标：

监控指标:
  - name: "API 响应时间"
    target: "< 1s"
  - name: "成功率"
    target: "> 99%"
  - name: "并发用户数"
    target: "< 1000"
  - name: "错误率"
    target: "< 1%"

日志管理

日志配置：

日志配置:
  level: "info"  # debug, info, warn, error
  format: "json"
  outputs:
    - type: "console"
      enabled: true
    - type: "file"
      enabled: true
      path: "/var/log/dify"
      max_size: "100M"
      max_files: 10

备份策略

备份配置：

备份配置:
  enabled: true
  schedule: "0 2 * * *"  # 每天 2:00
  retention:
    daily: 7
    weekly: 4
    monthly: 12
  storage:
    type: "s3"
    bucket: "dify-backups"
    region: "us-east-1"

安全配置

认证和授权

认证配置：

认证配置:
  enabled: true
  method: "jwt"  # jwt, oauth2, saml
  jwt:
    secret: "${JWT_SECRET}"
    expiration: "24h"
    refresh_expiration: "7d"

授权配置：

授权配置:
  enabled: true
  strategy: "rbac"  # rbac, abac
  roles:
    - name: "admin"
      permissions:
        - "app:*"
        - "user:*"
    - name: "user"
      permissions:
        - "app:read"
        - "app:execute"

数据加密

加密配置：

加密配置:
  enabled: true
  at_rest:
    algorithm: "AES-256"
    key_source: "env"
  in_transit:
    tls:
      enabled: true
      min_version: "1.2"

访问控制

IP 白名单：

IP 白名单:
  enabled: true
  allowed_ips:
    - "192.168.1.0/24"
    - "10.0.0.0/8"

性能优化

缓存策略

缓存配置：

缓存配置:
  enabled: true
  provider: "redis"  # redis, memory
  ttl: 3600  # 1 小时
  max_size: 10000

负载均衡

负载均衡配置：

负载均衡:
  enabled: true
  strategy: "round_robin"  # round_robin, least_connections
  health_check:
    enabled: true
    interval: 30
    timeout: 10

数据库优化

数据库配置：

数据库配置:
  pool:
    min: 5
    max: 20
    idle_timeout: 300
  query_cache:
    enabled: true
    size: 1000

故障排查

常见问题

发布失败：

# 检查日志
docker logs dify-api

# 检查配置
docker exec dify-api env | grep DATABASE_URL

API 调用失败：

# 测试连接
curl -I https://api.dify.ai/v1

# 检查 API 密钥
echo $DIFY_API_KEY

性能问题：

# 检查资源使用
docker stats dify-api

# 检查数据库连接
docker exec dify-api pg_isready

调试工具

日志查看：

# 查看应用日志
docker logs -f dify-api

# 查看错误日志
docker logs dify-api | grep ERROR

性能分析：

# 分析 API 响应时间
curl -w "@curl-format.txt" -o /dev/null -s "https://api.dify.ai/v1/completion-messages"

最佳实践

发布建议

• 分阶段发布：先发布到测试环境，再发布到生产环境
• 版本控制：使用版本号管理发布
• 灰度发布：逐步放量，监控效果
• 回滚准备：准备回滚方案

安全建议

• 保护密钥：使用环境变量存储密钥
• 定期轮换：定期更换 API 密钥
• 监控异常：监控异常访问和行为
• 权限最小化：最小权限原则

性能建议

• 使用缓存：合理使用缓存减少请求
• 优化数据库：优化查询和索引
• 负载均衡：使用负载均衡分散流量
• 监控指标：持续监控性能指标

资源链接

• 发布文档: https://docs.dify.ai/zh/use-dify/publish
• 部署文档: https://docs.dify.ai/zh/use-dify/deploy
• MCP 文档: https://docs.dify.ai/zh/use-dify/publish/mcp

最后更新: 2026-03-12 作者: EchoHaoRan

概述

Dify 提供多种应用类型，适用于不同的场景和需求。本文将详细介绍每种应用类型的特点、适用场景和配置方法。

应用类型概览

聊天机器人

特点

• 基于对话的交互模式
• 支持多轮对话
• 自动管理上下文
• 简单易用，快速上手

适用场景

配置步骤

创建聊天机器人：

1. 进入 工作室
2. 选择 从空白创建 > 聊天机器人
3. 配置提示词
4. 选择模型
5. 发布应用

提示词配置：

提示词配置:
  role: "客服助手"
  system_prompt: |
    你是一个专业的客服助手。
    回答问题时：
    1. 友好礼貌
    2. 准确专业
    3. 简洁明了
    4. 必要时提供详细解释
  first_message: "您好！有什么可以帮您的吗？"

模型配置：

模型配置:
  provider: "openai"
  model: "gpt-4o-mini"
  temperature: 0.7
  max_tokens: 1000

高级功能

知识库集成：

知识库配置:
  enabled: true
  knowledge_bases:
    - "product_docs"
    - "faq"
  retrieval:
    top_k: 3
    threshold: 0.8

对话设置：

对话配置:
  opening_statement: "您好！有什么可以帮您的吗？"
  suggested_questions:
    - "如何使用产品？"
    - "产品价格是多少？"
    - "支持哪些功能？"
  voice_input: true
  voice_output: true

智能代理

特点

• 具备自主规划能力
• 可以使用多种工具
• 支持复杂任务分解
• 自主思考和决策

适用场景

配置步骤

创建智能代理：

1. 进入 工作室
2. 选择 从空白创建 > 智能代理
3. 设置目标和指令
4. 配置工具
5. 选择模型
6. 发布应用

目标设置：

目标配置:
  goal: "帮助用户完成特定任务"
  instruction: |
    你是一个智能助手，可以：
    1. 搜索网络信息
    2. 读取文件内容
    3. 调用 API 接口
    4. 分析数据
    
    根据用户需求，自主规划并执行任务。

工具配置：

工具配置:
  enabled_tools:
    - "web_search"
    - "file_read"
    - "api_call"
    - "calculator"
  tool_permissions:
    web_search:
      max_results: 10
    file_read:
      allowed_paths:
        - "/data/documents"

推理配置：

推理配置:
  enabled: true
  max_iterations: 5
  strategy: "tree_of_thought"  # chain_of_thought, tree_of_thought
  timeout: 300

高级功能

记忆管理：

记忆配置:
  short_term:
    enabled: true
    max_messages: 20
  long_term:
    enabled: true
    storage: "vector_db"

任务分解：

任务分解:
  enabled: true
  max_subtasks: 10
  parallel_execution: true

文本生成器

特点

• 单次文本生成
• 输入明确，输出确定
• 适合批量处理
• 集成简单

适用场景

配置步骤

创建文本生成器：

1. 进入 工作室
2. 选择 从空白创建 > 文本生成器
3. 配置输入变量
4. 设置提示词
5. 选择模型
6. 发布应用

输入变量配置：

输入变量:
  - name: "topic"
    type: "paragraph"
    label: "主题"
    required: true
    max_length: 500
  - name: "style"
    type: "select"
    label: "风格"
    options:
      - "正式"
      - "轻松"
      - "幽默"
    required: false
  - name: "length"
    type: "select"
    label: "长度"
    options:
      - "短（100-200字）"
      - "中（200-500字）"
      - "长（500-1000字）"
    required: false

提示词配置：

提示词配置:
  system_prompt: |
    你是一个内容创作专家。
    根据用户提供的信息生成高质量内容。
  user_prompt: |
    主题：{{topic}}
    风格：{{style}}
    长度要求：{{length}}
    
    请创作一篇内容。

高级功能

结构化输出：

结构化输出:
  enabled: true
  schema:
    type: "object"
    properties:
      title:
        type: "string"
      content:
        type: "string"
      tags:
        type: "array"
        items:
          type: "string"

模板支持：

模板配置:
  enabled: true
  templates:
    - name: "博客文章"
      template: |
        # {{title}}
        
        {{content}}
        
        ---
        标签：{{tags | join(', ')}}

工作流

特点

• 可视化编排
• 支持复杂逻辑
• 灵活强大
• 易于维护

适用场景

配置步骤

创建工作流：

1. 进入 工作室
2. 选择 从空白创建 > 工作流
3. 添加起始节点
4. 编排流程节点
5. 配置节点参数
6. 添加结束节点
7. 测试工作流
8. 发布应用

节点类型：

• 用户输入节点
• LLM 节点
• 参数提取器节点
• 代码节点
• IF/ELSE 节点
• 迭代节点
• 模板节点
• 输出节点

工作流示例：

工作流配置:
  nodes:
    - id: "start"
      type: "user_input"
      fields:
        - name: "query"
          type: "paragraph"
    
    - id: "search"
      type: "llm"
      model: "gpt-4o"
      prompt:
        system: "你是一个搜索专家。"
        user: "搜索：{{start.query}}"
    
    - id: "format"
      type: "template"
      template: "搜索结果：{{search.text}}"
    
    - id: "end"
      type: "output"
      output: "{{format.text}}"

高级功能

触发器：

触发器配置:
  schedule:
    enabled: true
    cron: "0 9 * * *"  # 每天 9:00
  
  webhook:
    enabled: true
    url: "https://api.example.com/webhook"

子工作流：

子工作流配置:
  enabled: true
  workflows:
    - id: "sub_workflow_1"
      input_mapping:
        input1: "{{parent_output}}"
      output_mapping:
        result: "child_output"

对话流

特点

• 结合对话和流程
• 支持复杂交互
• 灵活的流程控制
• 丰富的节点类型

适用场景

配置步骤

创建对话流：

1. 进入 工作室
2. 选择 从空白创建 > 对话流
3. 添加开始节点
4. 配置对话流程
5. 添加分支和条件
6. 配置答案节点
7. 测试对话流
8. 发布应用

对话流示例：

对话流配置:
  start_node:
    message: "您好！请问需要什么帮助？"
    options:
      - label: "查询订单"
        next_node: "order_query"
      - label: "退换货"
        next_node: "return_policy"
      - label: "其他问题"
        next_node: "other_questions"
  
  order_query:
    message: "请输入您的订单号："
    input_type: "text"
    next_node: "order_result"
  
  order_result:
    message: "您的订单信息：{{order_info}}"
    options:
      - label: "返回首页"
        next_node: "start_node"

高级功能

条件分支：

条件分支:
  - condition: "{{order_status}} == 'completed'"
    next_node: "order_success"
  - condition: "{{order_status}} == 'pending'"
    next_node: "order_pending"
  - condition: "{{order_status}} == 'cancelled'"
    next_node: "order_cancelled"

循环：

循环配置:
  enabled: true
  max_iterations: 3
  exit_condition: "{{user_satisfied}}"

应用类型对比

选择建议

根据需求选择

混合使用

可以结合多种应用类型：

聊天机器人 + 知识库：

组合配置:
  type: "chatbot"
  features:
    - "knowledge_base_integration"
    - "multi_turn_dialog"

工作流 + 智能代理：

组合配置:
  type: "workflow"
  nodes:
    - type: "agent"
      enabled: true
    - type: "llm"
      enabled: true

最佳实践

设计原则

• 从简单开始：先选择简单的应用类型，逐步增加复杂度
• 明确目标：清楚知道应用要解决的问题
• 用户中心：以用户体验为中心设计交互
• 持续优化：根据反馈不断改进

性能优化

缓存策略：

缓存配置:
  enabled: true
  ttl: 3600
  max_size: 1000

批处理：

批处理配置:
  enabled: true
  batch_size: 100

安全建议

访问控制：

访问控制:
  enabled: true
  authentication: true
  authorization:
    roles:
      - "admin"
      - "user"

数据隐私：

数据隐私:
  enabled: true
  encryption: true
  data_retention: 90

资源链接

• 应用类型文档: https://docs.dify.ai/zh/use-dify/getting-started/key-concepts
• 应用创建教程: https://docs.dify.ai/zh/use-dify/getting-started/quick-start
• 最佳实践: https://docs.dify.ai/zh/use-dify/best-practices

最后更新: 2026-03-12 作者: EchoHaoRan

概述

本教程将带你从零开始，在 30 分钟内创建一个多平台内容生成器。你将学习如何使用 Dify 的核心功能，包括工作流编排、节点配置、模型调用等。

开始之前

注册 Dify Cloud

1. 访问 https://cloud.dify.ai
2. 免费注册账户
3. Sandbox 计划的新账户包含 200 条消息额度
4. 额度可用于调用 OpenAI、Anthropic 和 Gemini 等提供商的模型

注意：消息额度为一次性分配，不会按月续费。

设置模型供应商

1. 前往 设置 > 模型供应商
2. 安装 OpenAI 插件
3. 本教程使用 gpt-4o 作为示例
4. 如果使用 Sandbox 额度，无需 API 密钥
5. 也可以配置自己的 API 密钥

创建新工作流

创建应用

1. 前往 工作室
2. 选择 从空白创建 > 工作流
3. 将工作流命名为 多平台内容生成器
4. 点击 创建
5. 自动进入工作流画布

选择起始节点

选择 用户输入节点 作为工作流的起点。

编排与配置

收集用户输入：用户输入节点

用户输入节点用于定义从用户收集的信息。

配置字段

草稿

• 字段类型：段落
• 变量名：draft
• 标签名：草稿
• 最大长度：2048
• 必填：是

上传文件

• 字段类型：文件列表
• 变量名：user_file
• 标签名：上传文件 (≤ 10)
• 支持文件类型：文档、图片
• 上传文件类型：两者
• 最大上传数量：10
• 必填：否

语音与语调

• 字段类型：段落
• 变量名：voice_and_tone
• 标签名：语音与语调
• 最大长度：2048
• 必填：否

目标平台

• 字段类型：短文本
• 变量名：platform
• 标签名：目标平台 (≤ 10)
• 最大长度：256
• 必填：是

语言

• 字段类型：选择
• 变量名：language
• 标签名：语言
• 选项：
  • English
  • 日本語
  • 简体中文
• 必填：是

识别目标平台：参数提取器节点

参数提取器节点使用 LLM 将自由格式的文本转换为结构化数据。

配置步骤

1. 添加参数提取器节点
2. 配置 输入变量：选择 User Input/platform
3. 添加提取参数：
   • 名称：platform
   • 类型：Array[String]
   • 描述：The platform(s) for which the user wants to create tailored content.
   • 必填：是
4. 配置 指令：

Extract all social media platforms mentioned in the input. Return them as a JSON array of strings. Only include valid platform names like "Twitter", "LinkedIn", "Facebook", "Instagram", "TikTok". If no valid platform is identified, return: ["No platforms identified. Please enter a valid platform name."]

验证平台提取结果：IF/ELSE 节点

使用 IF/ELSE 节点处理无效输入。

配置步骤

1. 添加 IF/ELSE 节点
2. 定义 IF 条件：
   • IF Parameter Extractor/platform 包含 No platforms identified. Please enter a valid platform name.
3. 向 IF 分支添加输出节点
4. 在输出节点中，将 Parameter Extractor/platform 设置为输出变量

按类型分离上传的文件：列表操作器节点

使用两个列表操作器节点分离图像和文档。

图像节点配置

• 输入变量：User Input/user_file
• 启用过滤条件：{x}type 在 Image
• 输出变量：Image

文档节点配置

• 输入变量：User Input/user_file
• 启用过滤条件：{x}type 在 Doc
• 输出变量：Document