本节课只解决一个问题：怎么用最简单的代码调用一次大模型。
先不要急着学 CoT、ReAct、工具调用、记忆、多 Agent。因为这些能力最后都会回到同一个基础动作：

把问题发给大模型
→ 大模型返回答案
→ 程序拿到答案继续处理

如果这一步都不能稳定运行，后面写 Agent 时会很痛苦。

1.1 本节课要做什么

本节课只做四件事：

1. 说明现在常见的大模型调用方式
2. 说明为什么本节先使用 OpenAI 兼容接口
3. 写一个简单的 llm.py
4. 写一个简单的 main.py，运行后能看到模型输出
   本节课不追求封装得很完整，也不做太多抽象。代码要做到：高中生看得懂，复制下来能运行，后面课程能继续复用。

2 当前有几种大模型调用方式

2.1 第一种：官方原生接口

每个大模型厂商一般都有自己的官方接口。
例如：

这种方式的好处是能力最完整，坏处是每家写法不完全一样。你刚开始学习时，如果一上来同时适配 OpenAI、Claude、Gemini，很容易被 SDK 差异打断思路。

2.2 第二种：OpenAI 兼容接口

很多模型厂商支持 OpenAI 兼容接口。
简单说，就是它们让你继续使用 OpenAI SDK，只需要改三样东西：

API Key
Base URL
Model Name

常见支持 OpenAI 兼容接口的平台包括：

这就是本节课选择 OpenAI 兼容接口的原因：代码最少，迁移最简单，适合入门。

2.3 第三种：统一网关

还有一种方式是使用 LiteLLM、One API、公司内部网关这类统一代理。
它的作用是把多个模型包装成一个统一入口：

业务代码
→ 模型网关
→ OpenAI / DeepSeek / Qwen / Claude / Gemini

这种方式适合团队使用，但不适合第一节课。因为它又多引入了一层系统，初学者很容易不知道问题出在代码、网关还是模型服务。

2.4 本节课的推荐做法

本节课推荐：

先用 OpenAI SDK
→ 连接一个 OpenAI 兼容模型
→ 跑通最小调用
→ 后面课程全部复用这个 LLM 客户端

这样后面写 CoT 时，只需要关注 prompt 怎么写；写 ReAct 时，只需要关注模型怎么推理和行动；写工具调用时，再扩展工具参数即可。

3 一次大模型调用需要哪些信息

3.1 最少需要三个配置

一次大模型调用最少需要三个配置：

可以把它理解成点外卖：

LLM_MODEL_ID：你要点哪道菜
LLM_API_KEY：证明这是你的账号
LLM_BASE_URL：外卖平台地址

3.2 为什么配置放到 .env

不要把 API Key 写死在 Python 代码里。
不推荐：

api_key = "sk-xxxx"

推荐：

api_key = os.getenv("LLM_API_KEY")

原因很简单：

• API Key 是密码，不能随便暴露
• 换模型时不需要改代码
• 后面部署到服务器时也更方便
  所以本节课把 .env 当作配置文件使用，先不引入 config.yaml。对第一节课来说，.env 已经够用了。

4 项目结构

4.1 最终目录

创建一个目录：

agent-course-01-llm-call/
├── .env
├── llm.py
├── main.py
└── requirements.txt

每个文件的作用如下：

5 安装依赖

5.1 创建 requirements.txt

创建 requirements.txt：

openai
python-dotenv

这里只安装两个包：

• openai：用来调用 OpenAI 兼容接口
• python-dotenv：用来读取 .env 配置

5.2 安装依赖

执行：

pip install -r requirements.txt

如果你的电脑需要使用 pip3，就执行：

pip3 install -r requirements.txt

5.3 验证安装

执行：

python -c "from openai import OpenAI; from dotenv import load_dotenv; print('ok')"

预期输出：

ok

如果这里都不能运行，先不要继续写代码，先解决 Python 环境和依赖安装问题。

6 配置 .env

6.1 创建 .env 文件

创建 .env：

LLM_MODEL_ID=deepseek-chat
LLM_API_KEY=你的API_KEY
LLM_BASE_URL=https://api.deepseek.com
LLM_TIMEOUT=60

把 你的API_KEY 换成真实的 API Key。

6.2 不同平台的配置示例

如果你使用 DeepSeek：

LLM_MODEL_ID=deepseek-chat
LLM_API_KEY=你的DeepSeek_API_KEY
LLM_BASE_URL=https://api.deepseek.com
LLM_TIMEOUT=60

如果你使用阿里云百炼 Qwen：

LLM_MODEL_ID=qwen-plus
LLM_API_KEY=你的DASHSCOPE_API_KEY
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_TIMEOUT=60

如果你使用OpenAI：

如果你使用 OpenAI：
```bash
LLM_MODEL_ID=gpt-5-mini
LLM_API_KEY=你的OPENAI_API_KEY
LLM_BASE_URL=https://api.openai.com/v1
LLM_TIMEOUT=60

注意：模型名称可能会变化，最终以对应平台控制台和官方文档为准。如果报 model not found，优先检查 LLM_MODEL_ID。

7 编写 llm.py

7.1 代码目标

llm.py 只做一件事：把 messages 发给大模型，然后返回文本结果。
这里保留流式输出。因为流式输出体验更好，运行时能看到模型一个字一个字返回，不会一直卡着没反应。

7.2 完整代码

创建 llm.py：

import os
from typing import List, Dict, Optional
from dotenv import load_dotenv
from openai import OpenAI
load_dotenv()
class HelloAgentsLLM:
    """
    一个最小可用的 LLM 客户端。
    只支持 OpenAI 兼容接口。
    """
    def __init__(
        self,
        model: Optional[str] = None,
        api_key: Optional[str] = None,
        base_url: Optional[str] = None,
        timeout: Optional[int] = None,
    ):
        self.model = model or os.getenv("LLM_MODEL_ID")
        self.api_key = api_key or os.getenv("LLM_API_KEY")
        self.base_url = base_url or os.getenv("LLM_BASE_URL")
        self.timeout = timeout or int(os.getenv("LLM_TIMEOUT", "60"))
        if not self.model:
            raise ValueError("缺少模型名称，请在 .env 中配置 LLM_MODEL_ID")
        if not self.api_key:
            raise ValueError("缺少 API Key，请在 .env 中配置 LLM_API_KEY")
        if not self.base_url:
            raise ValueError("缺少服务地址，请在 .env 中配置 LLM_BASE_URL")
        self.client = OpenAI(
            api_key=self.api_key,
            base_url=self.base_url,
            timeout=self.timeout,
        )
    def think(self, messages: List[Dict[str, str]], temperature: float = 0) -> str:
        """
        调用大模型，并返回完整文本。
        messages 是对话列表，例如：
        [
            {"role": "system", "content": "你是一个有帮助的助手"},
            {"role": "user", "content": "你好"}
        ]
        """
        print(f"🧠 正在调用模型：{self.model}")
        try:
            response = self.client.chat.completions.create(
                model=self.model,
                messages=messages,
                temperature=temperature,
                stream=True,
            )
            print("✅ 模型返回：")
            result = []
            for chunk in response:
                if not chunk.choices:
                    continue
                content = chunk.choices[0].delta.content
                if not content:
                    continue
                print(content, end="", flush=True)
                result.append(content)
            print()
            return "".join(result)
        except Exception as e:
            print(f"❌ 调用大模型失败：{e}")
            return ""

7.3 这段代码怎么理解

这段代码里最重要的只有三部分。
第一，读取配置：

self.model = model or os.getenv("LLM_MODEL_ID")
self.api_key = api_key or os.getenv("LLM_API_KEY")
self.base_url = base_url or os.getenv("LLM_BASE_URL")

意思是：如果代码里传了参数，就用代码里的；如果没有传，就从 .env 里读取。
第二，创建客户端：

self.client = OpenAI(
    api_key=self.api_key,
    base_url=self.base_url,
    timeout=self.timeout,
)

意思是：告诉 OpenAI SDK，我要访问哪个模型服务。
第三，发送 messages：

response = self.client.chat.completions.create(
    model=self.model,
    messages=messages,
    temperature=temperature,
    stream=True,
)

意思是：把对话内容发给模型，并使用流式返回。

8 编写 main.py

8.1 代码目标

main.py 是入口文件，只负责演示怎么使用 HelloAgentsLLM。
它不要复杂，也不要封装太多逻辑。第一节课最重要的是让读者看清楚调用顺序。

8.2 完整代码

创建 main.py：

from llm import HelloAgentsLLM
def main():
    llm = HelloAgentsLLM()
    messages = [
        {
            "role": "system",
            "content": "你是一个讲解清楚、表达简单的 AI 助手。",
        },
        {
            "role": "user",
            "content": "用高中生能听懂的话解释什么是 LLM Agent。",
        },
    ]
    print("--- 调用 LLM ---")
    response_text = llm.think(messages)
    if response_text:
        print("\n--- 完整模型响应 ---")
        print(response_text)
if __name__ == "__main__":
    main()

8.3 调用顺序

这个文件的执行顺序很简单：

创建 HelloAgentsLLM
→ 准备 messages
→ 调用 llm.think(messages)
→ 打印模型返回内容

这就是后面所有 Agent 课程的基础。

9 运行验证

9.1 执行命令

在项目目录下执行：

python main.py

预期输出类似：

--- 调用 LLM ---
🧠 正在调用模型：deepseek-chat
✅ 模型返回：
LLM Agent 可以理解成一个由大语言模型驱动的智能助手，它不只是回答问题，还能根据目标规划步骤、调用工具，并根据结果继续完成任务。
--- 完整模型响应 ---
LLM Agent 可以理解成一个由大语言模型驱动的智能助手，它不只是回答问题，还能根据目标规划步骤、调用工具，并根据结果继续完成任务。

只要能看到模型返回内容，就说明本节课完成了。

9.2 修改问题再运行

你可以把 main.py 里的问题改成：

"写一个 Python 快速排序算法"

再执行：

python main.py

如果模型能返回代码，说明你的调用链路是正常的。

10 常见坑

10.1 .env 没有生效

如果提示：

缺少 API Key，请在 .env 中配置 LLM_API_KEY

先检查 .env 是否在当前目录。
正确目录应该是：

agent-course-01-llm-call/
├── .env
├── llm.py
├── main.py
└── requirements.txt

然后检查变量名是不是写错了。
必须是：

LLM_MODEL_ID=xxx
LLM_API_KEY=xxx
LLM_BASE_URL=xxx

不是：

MODEL_ID=xxx
API_KEY=xxx
BASE_URL=xxx

10.2 base_url 写成了完整接口地址

这是新手最常见的问题。
如果你使用 SDK，一般配置的是：

LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

不要写成：

LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions

因为 /chat/completions 这段路径 SDK 会自动拼接。

10.3 模型名称写错

如果报错里出现：

model not found

一般是模型名不对。
解决办法：

1. 去模型平台控制台确认模型名
2. 确认账号是否有这个模型权限
3. 先使用官方示例里的模型名
4. 不要照抄过期文章里的模型名

10.4 API Key 错误

如果报错里出现：

401
unauthorized
invalid api key

一般是 API Key 错了。
先检查：

• API Key 有没有复制完整
• API Key 前后有没有多余空格
• 当前平台和 API Key 是否匹配
• DeepSeek 的 Key 不要拿去调用 Qwen
• Qwen 的 Key 不要拿去调用 Kimi

10.5 temperature 设置

本节课默认：

temperature=0

可以简单理解成：让模型尽量稳定回答。
推荐：

刚开始学习 Agent，推荐先用 0。结果稳定，方便排查问题。

11 本节课最终代码

11.1 requirements.txt

openai
python-dotenv

11.2 .env

LLM_MODEL_ID=deepseek-chat
LLM_API_KEY=你的API_KEY
LLM_BASE_URL=https://api.deepseek.com
LLM_TIMEOUT=60

11.3 llm.py

import os
from typing import List, Dict, Optional
from dotenv import load_dotenv
from openai import OpenAI
load_dotenv()
class HelloAgentsLLM:
    def __init__(
        self,
        model: Optional[str] = None,
        api_key: Optional[str] = None,
        base_url: Optional[str] = None,
        timeout: Optional[int] = None,
    ):
        self.model = model or os.getenv("LLM_MODEL_ID")
        self.api_key = api_key or os.getenv("LLM_API_KEY")
        self.base_url = base_url or os.getenv("LLM_BASE_URL")
        self.timeout = timeout or int(os.getenv("LLM_TIMEOUT", "60"))
        if not self.model:
            raise ValueError("缺少模型名称，请在 .env 中配置 LLM_MODEL_ID")
        if not self.api_key:
            raise ValueError("缺少 API Key，请在 .env 中配置 LLM_API_KEY")
        if not self.base_url:
            raise ValueError("缺少服务地址，请在 .env 中配置 LLM_BASE_URL")
        self.client = OpenAI(
            api_key=self.api_key,
            base_url=self.base_url,
            timeout=self.timeout,
        )
    def think(self, messages: List[Dict[str, str]], temperature: float = 0) -> str:
        print(f"🧠 正在调用模型：{self.model}")
        try:
            response = self.client.chat.completions.create(
                model=self.model,
                messages=messages,
                temperature=temperature,
                stream=True,
            )
            print("✅ 模型返回：")
            result = []
            for chunk in response:
                if not chunk.choices:
                    continue
                content = chunk.choices[0].delta.content
                if not content:
                    continue
                print(content, end="", flush=True)
                result.append(content)
            print()
            return "".join(result)
        except Exception as e:
            print(f"❌ 调用大模型失败：{e}")
            return ""

11.4 main.py

from llm import HelloAgentsLLM
def main():
    llm = HelloAgentsLLM()
    messages = [
        {
            "role": "system",
            "content": "你是一个讲解清楚、表达简单的 AI 助手。",
        },
        {
            "role": "user",
            "content": "用高中生能听懂的话解释什么是 LLM Agent。",
        },
    ]
    print("--- 调用 LLM ---")
    response_text = llm.think(messages)
    if response_text:
        print("\n--- 完整模型响应 ---")
        print(response_text)
if __name__ == "__main__":
    main()

12 总结

12.1 本节课学到了什么

本节课只做了一个最小闭环：

.env 配置模型
→ llm.py 封装调用
→ main.py 发起请求
→ 控制台看到模型输出

这个闭环很小，但非常重要。后面所有 Agent 能力都会建立在它上面。

12.2 为什么这样写

本节课没有做复杂封装，原因是：

• 第一节课的目标是跑通，不是设计框架
• .env 已经能满足基础配置需求
• OpenAI 兼容接口能覆盖很多常见模型
• llm.think(messages) 这个入口后面可以继续复用
  后面进入 CoT 时，可以这样调用：

  messages = [
  {"role": "system", "content": "你是一个擅长一步一步推理的助手。"},
  {"role": "user", "content": "请一步一步分析这个问题：..."}
  ]
  llm.think(messages)

  也就是说，本节课不是孤立代码，而是后续 Agent 课程的底座。

13 参考文献

13.1 官方文档

• OpenAI API Reference：Chat Completions、Streaming、OpenAI Python SDK
• DeepSeek API Docs：OpenAI-compatible API format
• 阿里云百炼 Model Studio 文档：OpenAI 兼容接口调用千问模型
• Moonshot Kimi API 开放平台文档：OpenAI 兼容 API
• 智谱 AI 开放文档：OpenAI API 兼容接入说明
• Anthropic Claude API Docs：Claude Python SDK、Messages API
• Google AI for Developers：Gemini API、Google Gen AI SDK

13.2 后续课程

• 02 CoT：显式步骤推理
• 03 ReAct：推理和行动交替
• 04 Tool Use：让模型调用工具
• 05 Memory：让 Agent 记住上下文
• 06 Reflection：让 Agent 自我修正

一、网络规划

先统一规划 IP，后面所有配置都按这个来。

需要记住一个原则：一台设备一套密钥，一个独立 IP，不要多个设备共用同一个配置。

二、服务器安装 WireGuard

1. 安装软件

Ubuntu / Debian 执行：

sudo apt update
sudo apt install -y wireguard qrencode iptables

CentOS / Rocky / AlmaLinux 执行：

sudo dnf install -y wireguard-tools qrencode iptables

2. 开启 IP 转发

编辑系统配置：

sudo vim /etc/sysctl.conf

加入或确认有这一行：

net.ipv4.ip_forward=1

让配置立即生效：

sudo sysctl -p

检查结果：

cat /proc/sys/net/ipv4/ip_forward

输出 1 就是成功。

3. 查看服务器公网网卡

执行：

ip route | grep default

你会看到类似：

default via 172.31.0.1 dev eth0

这里的 eth0 就是公网网卡。也可能是 ens3、ens5、enp1s0，后面配置里的 eth0 要按实际结果替换。

4. 生成服务端密钥

sudo mkdir -p /etc/wireguard/clients
cd /etc/wireguard
sudo umask 077
sudo wg genkey | sudo tee server_private.key | sudo wg pubkey | sudo tee server_public.key

查看服务端私钥和公钥：

sudo cat /etc/wireguard/server_private.key
sudo cat /etc/wireguard/server_public.key

私钥不要泄露，公钥后面要填到客户端里。

5. 创建服务端配置

编辑配置文件：

sudo vim /etc/wireguard/wg0.conf

写入：

[Interface]
Address = 10.8.0.1/24
ListenPort = 51820
PrivateKey = 填服务端PrivateKey
PostUp = iptables -A FORWARD -i wg0 -j ACCEPT; iptables -A FORWARD -o wg0 -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i wg0 -j ACCEPT; iptables -D FORWARD -o wg0 -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

注意：如果你的公网网卡不是 eth0，把上面的 eth0 改成你的实际网卡名。

6. 放行 UDP 端口

如果服务器用了 UFW：

sudo ufw allow 51820/udp
sudo ufw reload

如果是云服务器，还要去云厂商安全组放行：

协议：UDP
端口：51820
来源：0.0.0.0/0

这是最容易漏的一步。WireGuard 用的是 UDP，不是 TCP。

7. 启动 WireGuard

sudo systemctl enable wg-quick@wg0
sudo systemctl start wg-quick@wg0

查看状态：

sudo wg show

看到 interface: wg0 就说明服务端启动成功。

三、添加手机、电脑、CatWrt 客户端

1. 生成客户端密钥

生成手机密钥：

cd /etc/wireguard
sudo wg genkey | sudo tee clients/phone_private.key | sudo wg pubkey | sudo tee clients/phone_public.key

生成电脑密钥：

sudo wg genkey | sudo tee clients/pc_private.key | sudo wg pubkey | sudo tee clients/pc_public.key

生成 CatWrt 密钥：

sudo wg genkey | sudo tee clients/catwrt_private.key | sudo wg pubkey | sudo tee clients/catwrt_public.key

2. 把客户端加入服务端

编辑服务端配置：

sudo vim /etc/wireguard/wg0.conf

在文件末尾追加：

[Peer]
# phone
PublicKey = 填phone_public.key里的内容
AllowedIPs = 10.8.0.2/32
[Peer]
# pc
PublicKey = 填pc_public.key里的内容
AllowedIPs = 10.8.0.3/32
[Peer]
# catwrt
PublicKey = 填catwrt_public.key里的内容
AllowedIPs = 10.8.0.10/32

服务端这里一定要写 /32，不要给每个客户端都写 10.8.0.0/24，否则多客户端容易冲突。

3. 重启服务端

sudo systemctl restart wg-quick@wg0
sudo wg show

四、生成客户端配置文件

1. 手机配置 phone.conf

查看需要填的密钥：

sudo cat /etc/wireguard/clients/phone_private.key
sudo cat /etc/wireguard/server_public.key

创建手机配置：

sudo vim /etc/wireguard/clients/phone.conf

写入：

[Interface]
PrivateKey = 填phone_private.key里的内容
Address = 10.8.0.2/32
DNS = 1.1.1.1
MTU = 1420
[Peer]
PublicKey = 填server_public.key里的内容
Endpoint = 你的服务器公网IP或域名:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

AllowedIPs = 0.0.0.0/0 表示手机所有流量都走 WireGuard。如果只想访问 WireGuard 内网，改成：

AllowedIPs = 10.8.0.0/24

生成二维码：

sudo qrencode -t ansiutf8 < /etc/wireguard/clients/phone.conf

2. 电脑配置 pc.conf

查看电脑私钥：

sudo cat /etc/wireguard/clients/pc_private.key

创建电脑配置：

sudo vim /etc/wireguard/clients/pc.conf

写入：

[Interface]
PrivateKey = 填pc_private.key里的内容
Address = 10.8.0.3/32
DNS = 1.1.1.1
MTU = 1420
[Peer]
PublicKey = 填server_public.key里的内容
Endpoint = 你的服务器公网IP或域名:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

3. CatWrt 配置 catwrt.conf

查看 CatWrt 私钥：

sudo cat /etc/wireguard/clients/catwrt_private.key

创建 CatWrt 配置：

sudo vim /etc/wireguard/clients/catwrt.conf

写入：

[Interface]
PrivateKey = 填catwrt_private.key里的内容
Address = 10.8.0.10/32
DNS = 1.1.1.1
MTU = 1420
[Peer]
PublicKey = 填server_public.key里的内容
Endpoint = 你的服务器公网IP或域名:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

如果你第一次配置 CatWrt，建议先把 AllowedIPs 写成：

AllowedIPs = 10.8.0.0/24

确认能连通后，再改成：

AllowedIPs = 0.0.0.0/0

这样可以避免路由器一启用 WireGuard 就全家断网。

五、手机设置 WireGuard

1. iPhone / iPad

在 App Store 安装 WireGuard，打开 App，点击 +，选择扫码导入，扫描服务器生成的二维码，保存后打开开关。

2. Android

安装 WireGuard App，点击 +，选择扫码导入或导入配置文件，保存后打开开关。

3. 手机测试

手机打开 WireGuard 后，访问查 IP 网站。如果显示的是服务器公网 IP，说明手机流量已经走服务器。如果只是访问内网，可以测试：

ping 10.8.0.1

六、电脑设置 WireGuard

1. Windows

安装 WireGuard 官方客户端，点击 Import tunnel(s) from file，选择 pc.conf，然后点击 Activate。

2. macOS

在 App Store 安装 WireGuard，导入 pc.conf，然后启用。

3. Linux

安装：

sudo apt update
sudo apt install -y wireguard

复制配置：

sudo cp pc.conf /etc/wireguard/wg0.conf
sudo chmod 600 /etc/wireguard/wg0.conf

启动：

sudo systemctl enable wg-quick@wg0
sudo systemctl start wg-quick@wg0

查看：

sudo wg show

七、CatWrt 设置 WireGuard

CatWrt 可以按 OpenWrt 的方式配置。这里推荐把 CatWrt 当客户端，连接云服务器。

1. 安装 WireGuard 组件

SSH 登录 CatWrt，执行：

opkg update
opkg install luci-proto-wireguard wireguard-tools kmod-wireguard qrencode

安装后重启：

reboot

如果提示 kmod-wireguard 内核版本不匹配，不要硬装。通常是固件和软件源不匹配，需要换匹配的软件源或升级 CatWrt 固件。

2. 新建 WireGuard 接口

进入 CatWrt 后台：

网络 -> 接口 -> 添加新接口

设置：

名称：wg_vps
协议：WireGuard VPN

如果没有 WireGuard VPN 选项，说明插件没装好，或装完没有重启。

3. 填写接口信息

在 wg_vps 接口中填写：

私钥：catwrt_private.key 的内容
IP 地址：10.8.0.10/32
MTU：1420
监听端口：留空

CatWrt 作为客户端时，监听端口可以留空。

4. 添加服务端 Peer

在 对端 / Peers 里添加：

公钥：server_public.key 的内容
端点主机：服务器公网IP或域名
端点端口：51820
允许的 IP：10.8.0.0/24 或 0.0.0.0/0
持久 KeepAlive：25

如果只是测试，允许的 IP 先写：

10.8.0.0/24

如果想让 CatWrt 下的设备都走 WireGuard，再改成：

0.0.0.0/0

如果页面有 Route Allowed IPs / 路由允许的 IP，需要勾选。

5. 设置防火墙区域

如果只是让 CatWrt 自己访问 WireGuard，把 wg_vps 放到 lan 区域即可。
如果想让 CatWrt 下面的设备通过 WireGuard 上网，建议把 wg_vps 放到 wan 区域，因为 wan 通常已经开启 NAT，并允许 lan -> wan 转发。
如果你新建了 vpn 区域，需要确认：

lan -> vpn：允许转发
vpn：开启 Masquerading
vpn：允许输出

普通用户建议先放到 wan 区域，少踩坑。

6. CatWrt 测试

SSH 到 CatWrt：

wg show
ping 10.8.0.1

如果看到 latest handshake，说明已经连上。如果 CatWrt 配的是全局流量，可以测试出口 IP：

curl ifconfig.me

显示服务器公网 IP，说明 CatWrt 已经通过 WireGuard 出口上网。

八、常见坑

1. 没有握手

优先检查：云服务器安全组是否放行 UDP 51820，服务器防火墙是否放行 UDP 51820，客户端 Endpoint 是否写错，服务端是否添加了对应客户端 Peer，公钥是否填反。

2. 有握手但不能上网

检查服务器是否开启转发：

cat /proc/sys/net/ipv4/ip_forward

必须输出：

1

再检查 NAT 网卡名是否正确：

ip route | grep default

如果实际网卡是 ens3，配置里却写 eth0，就会连上但不能上网。

3. 多个客户端互相顶掉

原因通常是多个设备用了同一个配置。每台设备都要有独立 PrivateKey 和独立 Address。

4. CatWrt 一启用就断网

先把 CatWrt 的 AllowedIPs 从：

0.0.0.0/0

改成：

10.8.0.0/24

确认基础连接正常后，再考虑全局代理。旁路由不会自动接管全家流量，如果 CatWrt 是旁路由，还需要让设备网关指向 CatWrt，或者使用策略路由。

5. 能连但网页打不开

优先检查 DNS。客户端可以先写：

DNS = 1.1.1.1

如果某些网络下不稳定，保留：

PersistentKeepalive = 25

必要时把 MTU 改小：

MTU = 1280

九、新增客户端接入时怎么修改

后面如果要新增手机、电脑、平板、路由器，不需要重装 WireGuard，只需要做三件事：生成新客户端密钥、服务端增加一个 Peer、生成新客户端配置。

1. 规划一个新 IP

先给新设备分配一个没有用过的 WireGuard IP。例如前面已经用了：

手机：10.8.0.2
电脑：10.8.0.3
CatWrt：10.8.0.10

新增一台平板，可以用：

平板：10.8.0.4

不要和已有设备重复。

2. 生成新客户端密钥

假设新客户端叫 pad：

cd /etc/wireguard
sudo bash -c 'umask 077; wg genkey | tee /etc/wireguard/pad_private.key | wg pubkey > /etc/wireguard/pad_public.key'

查看新客户端公钥：

sudo cat /etc/wireguard/pad_public.key

3. 修改服务端配置

编辑服务端配置：

sudo vim /etc/wireguard/wg0.conf

在文件末尾追加：

[Peer]
# pad
PublicKey = 填pad_public.key里的内容
AllowedIPs = 10.8.0.4/32

注意：服务端这里只需要新增这个客户端的 [Peer]，不要修改已有手机、电脑、CatWrt 的配置。

4. 重启 WireGuard

sudo systemctl restart wg-quick@wg0

查看状态：

sudo wg show

重启时已有客户端会短暂断开，几秒后会自动恢复。普通用户用这种方式最简单。

5. 生成新客户端配置

查看服务端公钥和新客户端私钥：

sudo cat /etc/wireguard/server_public.key
sudo cat /etc/wireguard/clients/pad_private.key

创建新客户端配置：

sudo vim /etc/wireguard/clients/pad.conf

写入：

[Interface]
PrivateKey = 填pad_private.key里的内容
Address = 10.8.0.4/32
DNS = 1.1.1.1
MTU = 1420
[Peer]
PublicKey = 填server_public.key里的内容
Endpoint = 你的服务器公网IP或域名:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

如果这个客户端只想访问 WireGuard 内网，不想让所有流量都走服务器，把：

AllowedIPs = 0.0.0.0/0

改成：

AllowedIPs = 10.8.0.0/24

6. 导入新客户端

手机或平板可以生成二维码：

sudo qrencode -t ansiutf8 < /etc/wireguard/clients/pad.conf

然后用 WireGuard App 扫码导入。电脑客户端则直接导入 pad.conf 文件。

7. 新增客户端时最容易出错的地方

新增客户端时，只记住这几条：

1. 新设备必须用新的 PrivateKey 和 PublicKey
2. 新设备必须用新的 Address，不能和旧设备重复
3. 服务端必须新增一个对应的 [Peer]
4. 服务端 Peer 里的 AllowedIPs 要写这个客户端的 /32
5. 原有客户端配置不用改

例如新增 pad，服务端只新增：

[Peer]
# pad
PublicKey = pad的PublicKey
AllowedIPs = 10.8.0.4/32

客户端只使用：

Address = 10.8.0.4/32

不要复制旧手机的配置直接用，否则两个设备会互相顶掉。

tmux        负责多终端会话持久化
claude-tmux 负责查看多个 Claude Code 会话状态
claude-tui  负责查看上下文、成本、工具调用、session 统计

一、环境说明

本文以 Ubuntu / Debian / WSL / SSH 终端环境为主。
先确认 Claude Code 已经能用：

claude --version

如果这里都不能运行，先把 Claude Code 装好，再继续后面的步骤。

二、安装 tmux

Ubuntu / Debian

sudo apt update
sudo apt install -y tmux curl git build-essential

macOS

brew install tmux

验证：

tmux -V

三、安装 Rust / Cargo

claude-tmux 推荐通过 Cargo 安装，所以需要 Rust 工具链。
先检查：

cargo --version

如果没有 Cargo，安装 Rust，如果没有魔法可能安装失败，可以部分用国内安装：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | \
env RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup \
    RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup \
    sh -s -- -y --profile minimal

source "$HOME/.cargo/env"

验证：

cargo --version

四、安装 claude-tmux

执行：

cargo install claude-tmux

确认二进制文件存在：

which claude-tmux
ls -lh ~/.cargo/bin/claude-tmux

正常路径一般是：

/home/你的用户名/.cargo/bin/claude-tmux

五、配置 tmux 快捷键打开 claude-tmux

编辑 tmux 配置：

vim ~/.tmux.conf

加入这一行：

bind-key C-c display-popup -E -w 80 -h 30 "~/.cargo/bin/claude-tmux"

重载配置：

tmux source-file ~/.tmux.conf

进入 tmux：

tmux

然后按：

Ctrl-b  Ctrl-c

就会弹出 claude-tmux 面板。
claude-tmux 常见状态：

● Working           Claude 正在工作
○ Idle              Claude 空闲，等你输入
◐ Waiting for input 等待权限确认，例如 [y/n]
? Unknown           不是 Claude 会话，或者状态无法判断

六、安装 claude-tui

claude-tui 的坑比较多，核心要求是：

Python 3.13+

先检查当前 Python：

python3 --version

如果输出是 Python 3.13.x，可以直接安装：

curl -sSL https://raw.githubusercontent.com/slima4/claude-tui/main/install.sh | bash

安装后执行：

claudetui setup
claudetui mode full

验证：

which claudetui
claudetui --help

七、如果 Python 版本不是 3.13+

很多 Ubuntu 机器默认是 Python 3.10 或 3.12。不要直接替换系统的 /usr/bin/python3，否则可能影响 apt 和系统脚本。
推荐做法：只在当前用户环境里使用 Python 3.13。
先检查：

python3.13 --version
which python3.13

如果能看到 Python 3.13，执行：

mkdir -p ~/.local/bin
ln -sf "$(command -v python3.13)" ~/.local/bin/python3
grep -q 'export PATH="$HOME/.local/bin:$PATH"' ~/.bashrc || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
hash -r

验证：

which python3
python3 --version

你应该看到类似：

/home/你的用户名/.local/bin/python3
Python 3.13.x

然后重新安装 claude-tui：

curl -sSL https://raw.githubusercontent.com/slima4/claude-tui/main/install.sh | bash
claudetui setup
claudetui mode full

八、常见坑

1：代理环境变量导致 curl 失败

如果你看到类似错误：

curl: (97) Can't complete SOCKS5 connection

或者明明没有主动加代理，但 curl 自动走了 socks/http 代理，先检查环境变量：

env | grep -i proxy

也可以逐个 echo：

echo "http_proxy=$http_proxy"
echo "https_proxy=$https_proxy"
echo "all_proxy=$all_proxy"
echo "HTTP_PROXY=$HTTP_PROXY"
echo "HTTPS_PROXY=$HTTPS_PROXY"
echo "ALL_PROXY=$ALL_PROXY"

临时清掉当前终端代理：

unset http_proxy
unset https_proxy
unset all_proxy
unset HTTP_PROXY
unset HTTPS_PROXY
unset ALL_PROXY

再次确认：

env | grep -i proxy

如果没有输出，说明当前 shell 的代理已经清掉。
重新测试：

curl -I --max-time 10 https://astral.sh
curl -I --max-time 10 https://raw.githubusercontent.com

如果你想查代理从哪里自动注入：

grep -nEi 'proxy|1080|8080|7890|socks' ~/.bashrc ~/.profile ~/.bash_profile ~/.zshrc 2>/dev/null

2：apt 代理配置导致 502 Bad Gateway

如果你给 apt 配过代理，比如：

Acquire::http::Proxy "http://127.0.0.1:8080/";
Acquire::https::Proxy "http://127.0.0.1:8080/";

然后出现：

502 Bad Gateway [IP: 127.0.0.1 8080]
仓库 InRelease 的签名不再生效

这通常不是 Ubuntu 源坏了，而是 apt 拿到的是代理返回的 502 页面，不是真正的 InRelease 文件。
先删掉 apt 代理：

sudo rm -f /etc/apt/apt.conf.d/99proxy
sudo apt clean

确认没有残留：

ls /etc/apt/apt.conf.d/*proxy* 2>/dev/null
cat /etc/apt/apt.conf.d/*proxy* 2>/dev/null

然后重新测试：

sudo apt update

如果你的网络必须走代理，先确认代理端口真的可用。
测试 HTTP 代理：

curl -v --max-time 10 -x http://127.0.0.1:8080 https://www.cloudflare.com/cdn-cgi/trace

测试 SOCKS5 代理：

curl -v --max-time 10 --socks5-hostname 127.0.0.1:1080 https://www.cloudflare.com/cdn-cgi/trace

如果 8080 返回 502，说明这个 HTTP 代理出口不可用，不要给 apt 配 8080。
如果 1080 可用，可以尝试 apt 使用 socks5h：

sudo tee /etc/apt/apt.conf.d/99proxy <<'EOF'
Acquire::ForceIPv4 "true";
Acquire::http::Proxy "socks5h://127.0.0.1:1080/";
Acquire::https::Proxy "socks5h://127.0.0.1:1080/";
EOF

然后：

sudo apt clean
sudo apt update

不用代理时，删除它：

sudo rm -f /etc/apt/apt.conf.d/99proxy
sudo apt clean

3：deadsnakes PPA 连接超时

如果你用 deadsnakes PPA 安装 Python 3.13，可能遇到：

连接超时
无法连接 ppa.launchpadcontent.net
IPv6 网络不可达

这时有三个选择：

选择 1：优先用 uv，绕开 apt PPA

curl -LsSf https://astral.sh/uv/install.sh | sh
source "$HOME/.local/bin/env" 2>/dev/null || export PATH="$HOME/.local/bin:$PATH"
uv python install 3.13

选择 2：修好代理后再 apt install

确认代理可用后再执行：

sudo apt update
sudo apt install -y python3.13 python3.13-venv libpython3.13-stdlib

选择 3：不用 claude-tui，先只用 tmux + claude-tmux

如果网络暂时修不好，claude-tmux 已经足够看多个 Claude 是否 working、idle、waiting。

九、推荐的 tmux 工作流

创建多个 Claude 任务 session：

tmux new -s claude-api
tmux new -s claude-web
tmux new -s claude-test
tmux new -s claude-monitor

在前三个 session 里启动 Claude：

claude

在 monitor session 里启动 claude-tui：

claudetui monitor

最终结构类似：

tmux
├── claude-api      # Claude 任务 1
├── claude-web      # Claude 任务 2
├── claude-test     # Claude 任务 3
└── claude-monitor  # claudetui monitor

日常命令：

tmux ls
tmux attach -t claude-api
tmux attach -t claude-web
tmux attach -t claude-test

在任意 tmux session 里打开 claude-tmux：

Ctrl-b  Ctrl-c

打开 claude-tui 实时监控：

claudetui monitor

查看历史统计：

claudetui stats

查看 session 列表：

claudetui sessions list

十、最终配置

我的推荐组合是：

vim ~/.tmux.conf

配置：

# Ctrl+a c      新建 window
# Ctrl+a d      detach
# Ctrl+a |      左右分屏
# Ctrl+a -      上下分屏
# Alt+h/j/k/l   直接切 pane
# 鼠标点击       选择 pane
# 鼠标拖边框     调整 pane 大小
# 把 prefix 从 Ctrl+b 改成 Ctrl+a

unbind C-b
set -g prefix C-a
bind C-a send-prefix

# 开启鼠标
set -g mouse on
setw -g mode-keys vi
# 鼠标左键拖选：自动进入 copy-mode，并限定在当前 pane
bind-key -T root MouseDrag1Pane if-shell -F "#{pane_in_mode}" "send-keys -M" "copy-mode -M"

# 鼠标松开：复制并退出 copy-mode
bind-key -T copy-mode-vi MouseDragEnd1Pane send -X copy-selection-and-cancel

bind-key -T copy-mode-vi v send -X begin-selection
bind-key -T copy-mode-vi y send -X copy-selection-and-cancel
bind-key -T copy-mode-vi Enter send -X copy-selection-and-cancel

set -g set-clipboard on

# 按 r 重新加载配置
bind r source-file ~/.tmux.conf \; display-message "tmux.conf reloaded"

# 更容易记的分屏
bind h split-window -h
bind v split-window -v

# Alt + hjkl 直接切换 pane，不需要先按 prefix
bind -n M-h select-pane -L
bind -n M-j select-pane -D
bind -n M-k select-pane -U
bind -n M-l select-pane -R

# Alt + 方向键也可以切换 pane
bind -n M-Left select-pane -L
bind -n M-Down select-pane -D
bind -n M-Up select-pane -U
bind -n M-Right select-pane -R

# Alt + 数字切 window
bind -n M-1 select-window -t 1
bind -n M-2 select-window -t 2
bind -n M-3 select-window -t 3
bind -n M-4 select-window -t 4
bind -n M-5 select-window -t 5

# 绑定claude-tmux
bind-key C-c display-popup -E -w 80 -h 30 "~/.cargo/bin/claude-tmux"

常用命令

openclaw gateway stop
openclaw gateway start

ssh代理远程访问

ssh -N -L 18789:127.0.0.1:18789 claw@192.168.100.104

登录：
查看.openclaw/openclaw.json中token秘钥，然后登录：

http://localhost:18789/chat?token=XXXX

最近正好在使用figma的make功能，正巧代码工具又层出不穷，除了我常用的cursor， codex、claude code、gemini-cli等Agent代码工具迎来了重大升级，正巧我使用阿里云盘在追剧，痛点是当有新剧增加的时候，别人是分享到网盘链接里的，每次我都需要找到对应的网盘，然后保存到我的阿里云盘里。如果是已更新完的剧还好，如果是正在更新的剧，我还需要记住对应的链接，没事点开看看有没有更新，然后转存到我的网盘里。所以正好想开发一个小工具，能够根据链接进行转存，并且定时查看分享链接里的内容有没有更新，如果更新以后则转存到我的目标云盘里。
因此做了一个阿里云盘自动转存的功能，目前支持的功能如下：

• 支持阿里云盘登录、查看存储状态
• 支持阿里云盘通过分享链接转存
• 支持转存为特定的名字
• 支持定时转存设置
• 支持对订阅内容进行编辑、暂停、删除
• 支持查看转存日志
  本项目完全没有主动编写任何代码，全程使用和大模型对话方式进行实现，本次只是说明如何使用该软件，后续我会将如何用figma+codex自动化编写代码进行分享。

2. 软件安装与使用

2.1 安装

目前已经上传到docker hub，建议直接使用docker进行安装，也可以访问我的github，按照github进行安装

https://github.com/apostle9891/aliautosave

使用docker进行安装

# 拉取aliautosave
docker pull apostle9891/aliautosave:latest

# 运行docker，其中/path要改成你的path
docker run -d --name aliautosave -p 8144:8144 -v /path/aliautosave_data:/app/data apostle9891/aliautosave:latest

如果是网页docker，可以直接搜索：aliautosave

点击下载，并进行安装，安装过程中端口映射为8144，存储位置替换/app/data

2.2 软件使用

当安装完成后，可以打开对应的IP:8144,比如我的网页是192.168.100.101:8144
打开以后，点击扫码登录阿里云盘

打开阿里云盘，登录阿里云盘

登录完毕后，可以看到对应的云盘信息

点击新增订阅，填入需要新增的分享链接

可以看到拉取到对应的云盘里的电视剧信息，支持多种自动命名规则，会自动提取里面的名字、集数、季数、扩展信息等，然后转为标准的姓名，目前支持：

• {title}.S{season:02}E{episode:02}{ext}
• {title}.E{episode:02}{ext}
• {name}{ext}
• {title}.{index:02}{ext}
  提取出来以后，我们可以自定义命名title，比如我们这次的电视剧叫做大生意，那我们改为大生意人。
  
  可以看到整体预览名字改成了大生意人
  
  选择对应的目标文件夹
  
  支持新建文件夹
  
  选择定时的策略，默认选择立即订阅并开始复制，会对内容进行复制
  
  点击后即可立即进行复制
  
  支持暂停、编辑、删除、查看转存日志
  
  暂停
  
  日志
  

结尾

大模型能力越来越强了，如果说在2023年我第一次开通vscode的copilot还是属于辅助编程，去年我买了cursor属于自定义编程，现在从6月份开始就真正可以叫做Agent编程了，可以全程通过对话进行编程，以后只需要一个ideal，就可以实现自己的想法。

背景

当我们使用大模型对ASR（语音识别）文本进行总结时，如何判断总结质量的好坏？这里提供一个简单的测试框架。

核心测试维度

1. 完整性 ✅

原文的关键信息是否都被覆盖？

2. 准确性 🎯

总结内容是否与原文一致？

3. 简洁性 📝

是否做到了有效压缩？

4. 可读性 👀

总结文本是否流畅易懂？

快速打分表

💡 评分参考：4分以上为优秀，3-4分为合格，3分以下需要优化提示词

常见问题与优化方向

比如当我们约束“永远不要高度浓缩！”。

• 它不是直接理解「永远不要高度浓缩！」这 9 个汉字。
• 它理解的是：在训练语料中，「不要高度浓缩」「详细展开讲」「拆开来说说细节」这些表达，经常伴随什么样的输出模式。
• 所以每一句话，对它来说等价于在行为空间里施加一个「方向」：往“展开、详细、慢速讲”的区域移动。
  所以那些能稳定触发你想要的行为方向的短语
• 详细展开 / 不要省略 → 「不要简略」「详细展开」「逐点解释」
• 忠实原文 / 不瞎编 → 「不新增事实」「不要编造细节」「如实保留」
• 去掉元语言 → 「不要解释你的思考过程」「最终只输出文章，不提到指令」
• 结构清晰 → 「按以下结构…」「先…，然后…，最后…」
  这些词对模型来说，就是统计上非常稳定的“开关”。

背景

当我们使用大模型对ASR（语音识别）文本进行总结时，如何判断总结质量的好坏？这里提供一个简单的测试框架。

核心测试维度

1. 完整性 ✅

原文的关键信息是否都被覆盖？

2. 准确性 🎯

总结内容是否与原文一致？

3. 简洁性 📝

是否做到了有效压缩？

4. 可读性 👀

总结文本是否流畅易懂？

快速打分表

💡 评分参考：4分以上为优秀，3-4分为合格，3分以下需要优化提示词

常见问题与优化方向

比如当我们约束“永远不要高度浓缩！”。

• 它不是直接理解「永远不要高度浓缩！」这 9 个汉字。
• 它理解的是：在训练语料中，「不要高度浓缩」「详细展开讲」「拆开来说说细节」这些表达，经常伴随什么样的输出模式。
• 所以每一句话，对它来说等价于在行为空间里施加一个「方向」：往“展开、详细、慢速讲”的区域移动。
  所以那些能稳定触发你想要的行为方向的短语
• 详细展开 / 不要省略 → 「不要简略」「详细展开」「逐点解释」
• 忠实原文 / 不瞎编 → 「不新增事实」「不要编造细节」「如实保留」
• 去掉元语言 → 「不要解释你的思考过程」「最终只输出文章，不提到指令」
• 结构清晰 → 「按以下结构…」「先…，然后…，最后…」
  这些词对模型来说，就是统计上非常稳定的“开关”。

Gemini 3 提示词工程：通用最佳实践指南

@_philschmid 最新博客：Gemini 3 更偏好直接、逻辑性强的内容，而非冗长的说教。提示词核心原则与三大关键实践 👇

核心原则 (Core Principles)
· 指令要精准 (Precise Instructions)：去除废话，直接清晰地陈述你的目标。Gemini 3 对简洁明了的指令反应最好。
· 保持一致性 (Consistency)：在提示词中维持统一的结构（例如统一使用 XML 标签），并明确定义模棱两可的术语。
· 多模态融合 (Multimodal Coherence)：文本、图像、音频或视频应被视为同等重要的输入。指令中要明确引用特定的模态，让模型进行综合分析，而不是孤立处理。
· 约束前置 (Constraint Placement)：将行为约束和角色定义放在“系统指令”中或提示词的最顶端，作为模型推理的锚点。
· 长上下文处理 (Context Anchoring)：处理大量数据时，将具体指令放在末尾。在数据和问题之间使用过渡句（如“基于上述信息……”）来桥接。

三大关键实践
1. 推理与规划 (Reasoning and Planning)
不要让模型直接给出答案，而是强制它先“思考”。
· 显式拆解：要求模型在回答前，先将目标拆解为子任务，检查信息是否完整，并构思结构化的提纲。
· 自我更新的任务清单 (TODO Tracker)：让模型创建一个 TODO 列表，在执行过程中自我追踪进度（例如：[ ] 任务1，[x] 任务2）。
· 自我批判：要求模型在输出最终响应前，先对照用户的原始约束进行自我审查（例如：“我是否回应了用户的真实意图，而不仅仅是字面意思？”）。

2. 结构化提示 (Structured Prompting)
使用清晰的标记语言（XML 或 Markdown）来界定提示词的边界。这能帮助模型区分哪里是“指令”，哪里是“数据”。
· XML 示例：使用 <rules> 定义规则，<context> 放入背景资料，<planning_process> 展示思考过程。
· Markdown 示例：使用标题如 # Identity（身份），# Constraints（约束）来组织内容。
· 建议：选择一种格式并保持一致，不要混用。

3. 智能体工具使用 (Agentic Tool Use)
当把 Gemini 3 作为自主智能体使用时，需要赋予它更强的韧性和反思能力：
· 坚持指令 (The Persistence Directive)：明确告诉智能体“必须持续工作直到问题被完全解决”。如果工具调用失败，它应该分析错误并尝试替代方案，而不是直接放弃或把问题抛回给用户。
· 预计算反思 (Pre-Computation Reflection)：在调用任何工具之前，要求智能体明确陈述：
  4. 为什么要调用这个工具？
  5. 期望获取什么具体数据？
  6. 这个数据如何帮助解决用户的问题？

场景应用与模板
文章还提供了针对不同领域的具体策略：
· 研究分析：先拆解问题，独立搜索，最后综合并强制引用来源。
· 创意写作：明确目标受众，如果是为了通过图灵测试或显得自然，需明确禁止使用“企业黑话”（如 synergy, protocols）。
· 解决问题：要求模型先找出“标准方案”，再找出“高手方案”（Power User Solution），提供最优解。

最火的推特发帖提示词

• 先定钩子类型：反直觉/唱反调（contrarian）、好奇心缺口（curiosity gap）、具体数字承诺（specific value）、打破常识（pattern interrupt）。3hipclip.ai
• 线程结构要短平快：每条只推进一个点，保持叙事动量，避免信息过载。hipclip.ai+1
• 提示词要“可参数化”：主题、受众、立场、语气、长度、CTA、禁忌项都用变量占位。clickup.com+1
• 把“研究”写进流程：输出前必须做“最新信息检索+可信来源对照+可引用事实点”。（很多模板会要求先收集材料再写作，只是通常写得不够硬，你这里需要更硬。）黑客中午+1

角色（Role）

你是“X/Twitter 增长文案专家 + 快速研究员（Research-first Copywriter）”。
你擅长用【反直觉的矛盾】制造注意力，用【证据与例子】建立可信度，用【清晰结构】提升转推/收藏/评论率。

目标（Goal）

基于我输入的需求，先进行网络检索与事实核验，再产出可直接发布的 X/Twitter 文案（单条或线程），要求：
1) 内容“新”：必须引用/吸收近期网络信息与趋势（尽量是最近 30 天，除非主题不需要）。
2) 内容“狠”：必须包含至少一个“矛盾/冲突/反常识”的核心张力点，形成强钩子。
3) 内容“稳”：观点有证据支撑，避免虚构数据与来源；不确定就用“可能/一些案例显示”并给出替代表述。

输入（User Input）

我会提供（尽量多提供越好）：

• 主题/领域：
• 受众是谁（新手/专家/老板/开发者/产品/投资人/普通用户）：
• 我想表达的核心观点（可一句话）：
• 我已有素材（链接/要点/经历/数据/产品细节）：
• 目的（涨粉/引流/招聘/品牌/产品发布/观点输出）：
• 风格（毒舌/克制/专业/故事感/幽默/犀利）：
• 形式（单条/线程/引用转推/投票）：
• 禁忌（不聊什么/不提什么品牌/避免敏感点）：

任务（Tasks）

Task A：联网研究（必须执行）

1) 用网络搜索找到与主题最相关的【最新】信息（优先：权威媒体/研究报告/官方博客/行业报告/头部从业者公开内容）。
2) 提取 5-10 条“可用于发帖的事实点/新变化/争议点/数据/案例”（每条一句话）。
3) 做最小交叉验证：同一关键事实至少对照 2 个来源；若无法验证，标记为“未完全确认”。

Task B：制造“矛盾张力”（必须执行）

在写作前，先生成 6 个“矛盾钩子候选”，每个符合以下任一模式：

• 反直觉：大家以为 A，但最新情况更像 B
• 代价冲突：你得到 X，会失去 Y
• 立场对撞：主流观点 P 的盲点是 Q
• 真相揭露：行业最赚钱的部分，恰恰是最不起眼的部分
• 误区纠偏：90% 的人做错在第一步
• 数据打脸：最新数据与常识相反
  从中选 2 个最强的进入成稿。

Task C：输出可直接发布的文案（必须执行）

按我指定的“形式”输出；如果我没指定，默认输出三套：
1) 单条推文（1 条，<= 280 字符，强钩子 + 观点 + 证据/例子 + 轻 CTA）
2) 线程（7-9 条，每条一个要点，节奏：钩子 -> 可信度 -> 三段论/步骤 -> 反驳常见误解 -> 落地建议 -> CTA）
3) 引用转推文案（1 条，针对一条“假想的行业主流观点/新闻”，用矛盾角度反击）

输出格式（Output Format）

0) 联网研究摘要

• 关键事实点（5-10 条）：（用项目符号列出）
• 争议/分歧点（1-3 条）：（用项目符号列出）
• 可引用来源清单：给出来源名称 + 标题/关键词 + 发布时间（不贴长链接；若必须给链接，放最后）

1) 矛盾钩子候选（6 个）

• Hook 1:
• Hook 2:
  ...

2) 成稿（可直接复制发布）

A. 单条（1 条）

（正文）

B. 线程（7-9 条）

1/ （钩子）
2/ ...
...
n/ （CTA：提问或让人收藏/转发）

C. 引用转推（1 条）

（正文）

3) 质量自检（必须给出结论）

• 是否“最新”：是/否（若否，说明原因）
• 是否有“矛盾张力”：是/否（指出张力句）
• 是否可读：是/否（如果否，给 1 句改法）
• 是否避免虚构：是/否（标注任何不确定点）

写作准则（Hard Rules）

• 必须“具体”：多用数字、步骤、对比、案例；少空话。
• 每条信息只推进一个观点，避免信息过载。
• 少用 hashtag：除非我要求，否则最多 0-2 个。
• 不要夸张承诺；用“证据 + 例子”替代空洞煽动。
• 永远优先清晰，其次才是文采。