软件试用 on 扎塔-Zata

everything-claude-code

Tue, 17 Mar 2026 10:53:29 +0800

安装和配置

注意事项

概念

更准确地说，它是把一整套 AI 开发工作流打包成仓库和插件，主要包括：

agents：子代理角色，比如规划、架构、代码审查、安全审查
skills：可复用工作流，比如 TDD、持续学习、搜索优先、安全检查、前后端模式
commands：斜杠命令，比如 /plan、/verify、/code-review、/multi-execute
hooks / rules / mcp-configs：自动化钩子、规范规则、MCP 外部工具接入

它的核心目标是把 AI 编码助手从“会聊天的工具”变成“更像工程团队的系统”：更会规划、记忆上下文、做验证循环、自动审查、安全扫描和多代理协作。

如果你问“适合拿来干嘛”，答案是：

搭一套更强的 Claude Code/Codex 开发环境
复用现成的 agent/skill/rule
给团队统一 AI 编码规范和自动化流程如果你问“它是不是一个能直接运行的产品”，答案是否。它更像一个 AI coding workflow toolkit，不是 SaaS/后端/前端业务项目。

补充一点：截至 2026-03-17，GitHub 页面显示它已经定位成 “AI agent harness performance optimization system”，英文 README 写的是 21 agents / 102 skills / 52 commands；我看到中文 README 里还是较早的 13 / 43 / 31，推测中文文档有些滞后。

来源： GitHub 仓库 (https://github.com/affaan-m/everything-claude-code) README.md (https://github.com/affaan-m/everything-claude-code/blob/main/README.md) package.json (https://raw.githubusercontent.com/affaan-m/everything-claude-code/main/package.json)

cherry-studio

Mon, 09 Mar 2026 10:16:47 +0800

Cherry Studio 详细使用教程

Cherry Studio 是一款备受推崇的桌面端跨平台 AI 客户端，被誉为"AI 领域的瑞士军刀”[1]。它本身不提供大模型算力，而是作为一个统一的图形界面，让你能够将各大云端 API（如 DeepSeek、OpenAI、Claude、Gemini）以及本地模型（如 Ollama）汇聚在一起使用 [1]。

它主打隐私安全（数据保存在本地）、多模型对比、内置 300+ 智能助手以及强大的**知识库和代码助手（Code Agent）**功能 [2][3][4][5]。

以下是一份从零开始的 Cherry Studio 详细使用教程：

第一步：下载与安装

支持系统：Windows (64 位)、macOS (10.15+)、Linux[1][6]。
下载途径：
- 前往官方网站 (cherry-ai.com) 或 GitHub 仓库 (CherryHQ/cherry-studio) 的 Releases 页面下载对应的安装包 [3][6][7]。
安装：双击下载的安装包，按提示“下一步”即可完成，开箱即用 [6]。

第二步：核心配置——接入 AI 模型

因为 Cherry Studio 是一个“客户端”，你需要为它配置 API 密钥（API Key）或连接本地模型才能开始对话 [6][8]。

接入云端模型（以 DeepSeek 或第三方 API 为例） 如果你有官方的 API Key，或者使用中转平台（如硅基流动、海鲸 AI 等）的 API：
- 打开 Cherry Studio，点击左下角的“设置”（齿轮图标 ⚙️）[6][9]。
- 在左侧菜单中选择“模型服务” (Providers)[9]。
- 你会看到许多内置的服务商列表。你可以直接点击对应的服务商（如 OpenAI、Anthropic），或者点击“添加”创建一个**“自定义服务商” (Custom)**[9]。
- 填写关键参数（以自定义 OpenAI 兼容接口为例）：
  - API 地址 (Base URL)：填入服务商提供的地址（例如 https://api.deepseek.com/v1 或你的中转 API 地址）。注意通常需以 /v1 结尾。
  - API 密钥 (API Key)：填入你的 sk-xxxxxx 密钥 [9]。
- 添加模型：
  - 在配置界面的下方，找到“模型列表”或“管理模型”[6]。
  - 手动输入需要使用的模型 ID（例如 deepseek-chat, gpt-4o, claude-3-5-sonnet），点击添加或回车 [6][9]。
  - 勾选这些模型使其生效，并可以将最常用的设为“默认模型”[6]。
接入本地模型（通过 Ollama 或 LM Studio） 如果你的电脑配置较好，想免费且断网使用 AI：
- 确保电脑上已安装并运行 Ollama，并且已经拉取了模型（如 ollama run qwen2.5）。
- 在 Cherry Studio 设置 -> 模型服务中，找到 Ollama。
- 默认 API 地址通常为 http://127.0.0.1:11434。
- 软件会自动拉取你本地已安装的模型列表，勾选即可使用 [4][6]。

第三步：日常基础使用

基础对话与多模型同开（对比模式）
- 基础对话：回到主界面，点击左侧导航栏的“聊天”图标，在顶部下拉菜单选择你刚才配置好的模型，即可在下方输入框提问。
- 多模型同开（强烈推荐）：如果你想看同一问题不同 AI 的回答哪个更好。在聊天界面，点击聊天框顶部的"+“号或模型图标，可以同时勾选 2 个或更多的模型（比如同时勾选 GPT-4o 和 Claude 3.5）。发送一句话，屏幕会分栏同时展示不同模型的回答 [1][6][7]。
文件解析与多模态对话
- 如果你选择的模型支持多模态（如 gpt-4o 或 claude-3-5-sonnet 等），你可以直接将 PDF、Word、Excel 文档或图片拖拽到输入框中 [3][6]。
- 软件会自动解析文档内容，你可以针对文档进行提问、总结和提取信息 [3][6]。
使用内置的 300+ 智能助手（Agent）
- 不想每次都写长长的 Prompt（提示词）？
- 点击左侧导航栏的“助手” (Assistants/Agents) 模块 [8]。
- 里面内置了涵盖编程、写作、翻译、学术、营销等领域的 300 多种设定好的助手 [4]。
- 找到你需要的助手（例如“小红书爆款文案生成器”或"Python 专家”），点击它并选择对应的运行模型，即可直接进入专用对话流 [4]。
- 自定义助手：你也可以点击“新建助手”，输入你自己的系统提示词（System Prompt），为其设置特定图标并保存，打造专属助理 [6][7]。

第四步：进阶功能探索

构建个人本地知识库 (Knowledge Base) Cherry Studio 最受欢迎的特性之一是其本地知识库功能，适合处理超大型私人文档集，不会把你的机密数据随意传给第三方云端：
- 在左侧菜单找到“知识库”[2][9]。
- 新建一个知识库，选择一个用于进行向量化的 Embedding 模型（通常各 API 服务商都有提供，如 OpenAI 的 text-embedding-3-small）。
- 导入你的文件夹、PDF 论文库或纯文本 [2]。
- 处理完成后，在聊天界面可以关联该知识库，AI 的回答就会基于你的文档进行检索和生成，实现完美的私有知识问答 [2][9]。
Code Tools（AI 编程助手 Agent） 自 1.5.7 版本起，Cherry Studio 深度整合了 AI 程序员工具：
- 点击界面左侧或顶部的"Code Tool”[5]。
- 你可以在这里直接调用像 Claude Code、Gemini CLI、Qwen Code 等原生终端 AI 编程工具 [5]。
- 指定你的本地代码项目文件夹，授予权限后，AI 可以直接读取你的项目代码，甚至帮你自动修改文件和执行终端命令（相当于拥有了类似 Cursor 的项目级编辑能力）[5]。
MCP 服务器接入 (Model Context Protocol) MCP 是一种让大模型能够使用外部工具的协议。
- 在设置中找到 MCP 服务器 [9]。
- 你可以配置并启动不同的 MCP 插件，比如让 AI 具备联网搜索网页、查询本地数据库、或者调用外部 API 的能力 [9]。
WebDAV 云端同步与备份 因为 Cherry Studio 是本地客户端，更换电脑时聊天记录不在云端。
- 在“设置 -> 数据同步”中，你可以配置 WebDAV（如坚果云，或自带 NAS 的 WebDAV）。配置后，你的所有配置、助手和聊天记录都可以安全地加密备份并多端同步 [6]。

💡 实用小贴士 (Tips)

显示 Token 消耗：在“设置 -> 界面/显示”中，可以开启“显示预估 Token 数”，这能帮你清楚地知道每次提问花费了多少 API 额度 [8]。
快捷唤醒全局搜索：可以使用快捷键唤出全局搜索或全局翻译小窗口，不打断你当前在其他软件（如浏览器、Word）中的工作流 [3]。
快捷键换行：通常 Enter 是发送，Shift + Enter 是换行（可在设置中修改）。

总结

Cherry Studio 的使用逻辑是：“下载软件” -> “填好 API Key" -> “选择模型开始聊天或建知识库”[6][8]。当你把基础配置跑通后，它将是你提高生产力的最强桌面工具 [7][9]。

资料来源

help
skywork.ai
jimmysong.io
cherry-ai.com
medium.com
cherry-ai.com
github.io
github.com
wanjiedata.com
atalk-ai.com

注意事项

alist

Sat, 07 Mar 2026 17:50:08 +0800

AList V3 详细使用教程：安装、配置与 WebDAV 挂载

AList 是一款支持多种存储（阿里云盘、百度网盘、OneDrive、Google Drive 等）的文件列表程序。它可以把你的各种网盘聚合在一起，不仅可以直接在网页端预览、下载文件，还能通过 WebDAV 协议挂载到本地电脑或第三方播放器（如 Infuse、PotPlayer）上直接看原画视频。

以下是一份保姆级的 AList V3 版本详细使用教程，分为安装、初始化、添加网盘和 WebDAV 挂载四个主要部分。

一、安装 AList

AList 支持全平台安装。这里提供最常用的两种安装方式：Docker（推荐给 NAS/Linux 用户） 和 Windows（适合小白和普通电脑）。

1. 使用 Docker 安装（最推荐，稳定且干净）

如果你有云服务器、NAS 或安装了 Docker 的电脑，直接在终端运行以下命令：

docker run -d --restart=always -v /etc/alist:/opt/alist/data -p 5244:5244 --name="alist" xhofe/alist:latest

5244 是默认端口，如果你想换成别的，可以把前一个 5244 改掉（例如 -p 8080:5244）。

2. 在 Windows 上安装

前往 AList 的 GitHub Releases 页面。
下载名为 alist-windows-amd64.zip 的文件。
解压到一个文件夹（例如 D:\AList\）。
在文件夹路径栏输入 cmd 并回车，打开命令提示符。
输入运行命令：alist.exe server，看到 start server @ 0.0.0.0:5244 就代表运行成功了。（注意：这个 CMD 窗口不能关，关了 AList 就停了）。

二、初始化与登录

AList 第一次运行会生成默认密码（或需要你自己设置）。

1. 获取/设置管理员密码

Docker 用户：在终端输入以下命令随机生成一个密码，或者手动设置。
手动设置密码（推荐，把 YOUR_PASSWORD 换成你的密码）： docker exec -it alist ./alist admin set YOUR_PASSWORD
Windows 用户：在刚刚那个没关的 CMD 窗口按 Ctrl+C 停止运行，然后输入：
alist.exe admin set YOUR_PASSWORD（设置好后，再重新输入 alist.exe server 启动服务）。

2. 登录后台

在浏览器输入：http://你的 IP 地址:5244（如果你是在本机安装的，就是 http://127.0.0.1:5244）。
点击底部的 “登录”（或者管理）。
账号输入 admin，密码输入你刚刚设置的密码。

三、添加网盘（以阿里云盘为例）

进入后台管理后，你就可以把各大网盘“装”进 AList 了。

在左侧菜单点击 存储 (Storage) -> 添加 (Add)。
驱动 (Driver) 选择你要添加的网盘（例如：阿里云盘 Open）。
挂载路径 (Mount Path)：输入你想要在首页显示的文件夹名字，比如 /阿里云盘。
填写网盘授权信息 (Token)：

由于大部分网盘需要授权，你需要获取 Token 或 Refresh Token。
AList 官方提供了一个非常方便的获取工具：访问 https://alist.nn.ci/zh/guide/drivers/aliyundrive_open.html（官方文档），里面有获取 Token 的二维码或按钮。
用阿里云盘 App 扫码后，网页会显示一串 Refresh Token。
把这串 Token 复制，回到 AList 后台，粘贴到 刷新令牌 (Refresh Token) 这一栏。

其他选项保持默认即可，点击底部 保存 (Save)。
回到“存储”列表，如果状态显示为 work，说明挂载成功！点击左侧的“主页”，你就能看到你的网盘文件了。

四、进阶玩法：使用 WebDAV 挂载到播放器/电脑

这是 AList 最强大的功能。你可以把云盘当成本地硬盘用，直接看高清电影，不占用本地空间。

WebDAV 连接信息：

服务器地址：http://你的 IP:5244/dav （注意后面一定要加 /dav）
账号：你的 AList 登录账号（例如 admin）
密码：你的 AList 登录密码

应用场景：

手机/平板看剧 (Infuse / nPlayer / Fileball)：在播放器里添加网络服务器，选择 WebDAV 协议，填入上面的连接信息，你网盘里的电影立刻变成精美的海报墙，并且可以直接原画播放。
电脑看剧 (PotPlayer / VLC)：在播放器里打开“打开链接”或“添加 FTP/WebDAV"，填入信息即可无缝播放。
挂载为电脑本地磁盘：Windows 用户可以使用 RaiDrive 软件，Mac 用户可以使用系统自带的“连接服务器”或 CloudMounter，将 AList 映射为一个电脑的本地盘符（比如 Z: 盘），像操作本地文件一样操作网盘。

你想先从哪个网盘开始挂载呢？如果需要获取特定网盘（如百度网盘、OneDrive、夸克网盘）的具体配置方法，我可以为你提供详细步骤。

wrap.dev

Tue, 03 Mar 2026 21:40:54 +0800

Warp 终端使用教程与功能详解

warp.dev（官方名称为 Warp）是一款基于 Rust 编写、GPU 加速的现代终端工具。它不仅是一个更快的命令行界面，更被定位为"Agentic Development Environment" (ADE)，即集成了 AI 智能体（Agents）和 IDE 功能的下一代开发环境。

以下是 Warp 的详细使用教程，涵盖从基础安装到高级 AI 工作流的操作。

一、安装与环境准备 [1]

下载安装：
- 官网下载：访问 warp.dev 点击下载。
- MacOS (Homebrew)：brew install --cask warp[1]
- Windows (WinGet)：winget install Warp.Warp[1]
- Linux：支持 .deb、.rpm 以及 AppImage 格式。
账号登录：Warp 需要登录（支持 GitHub/Google 登录），这主要是为了云端同步你的工作流（Workflows）和 AI 偏好。
Shell 支持：Warp 默认支持 zsh、bash、fish 和 PowerShell。它会自动读取你现有的 shell 配置（如 .zshrc），无缝迁移。

二、核心概念：块（Blocks）[2][3]

不同于传统终端那种“流式”的纯文本，Warp 引入了 Blocks（块）的概念：

独立性：每一条命令及其输出都被封装成一个独立的方块。[3]
操作：你可以单独对某个 Block 进行操作（点击右上角），例如：
- Copy Output：只复制该命令的输出结果。
- Share Block：生成一个永久链接，直接把出错的日志分享给同事。
- AI Explain：让 AI 解释为什么这条命令报错了。

三、核心功能与 AI 操作指南

Warp 的精髓在于它将 AI 深度集成到了命令行中。[4]

AI 命令搜寻（Natural Language to Shell）
- 快捷键：输入 # 或按下 Ctrl + `（反引号）。[5]
- 用法：直接输入中文或英文需求，例如 # 查找所有大于 100MB 的文件。
- 效果：Warp 会实时生成对应的 shell 命令（如 find . -type f -size +100M），按回车即可填入输入框。
Warp AI 聊天（上下文感知的 AI 助手）
- 快捷键：Ctrl + Space（或点击侧边栏 AI 图标）。
- 用法：它不同于网页版 ChatGPT，它知道你的终端上下文（当前目录、上个命令的错误、文件结构）。
- 场景：你可以问“为什么刚才的 build 失败了？”或“在这个项目里如何配置 Redis？”
Agentic Development（智能体开发模式） 这是 Warp 最新的方向，利用内置的 Oz 智能体处理复杂任务。
- Warp Dispatch (Ctrl + Shift + I)：你可以下达一个宏观指令（如：“将这个项目所有的图片压缩并移动到 assets 文件夹”）。AI 会制定计划，请求你授权运行一系列终端命令，并自动完成。
- Warp Pair (Ctrl + I)：类似结对编程，AI 会读取你的代码和报错，辅助你实时调试。
Warp Drive（工作流同步）
- 功能：你可以将常用的、难记的命令（带参数）保存为 Workflows。[3][5]
- 团队协作：你可以创建团队文件夹，将常用的部署脚本、数据库迁移命令共享给全组人使用，大家直接搜关键词就能运行。

四、像 IDE 一样编辑命令

Warp 的输入框（Input Area）不是简单的文本行，而是一个功能完备的编辑器：

光标操作：支持鼠标点击定位。
多行编辑：按 Shift + Enter 换行，支持语法高亮。
补全系统：基于历史记录和 AI 预测的智能补全。输入命令时，按 Tab 键可以快速选择建议。

五、必备快捷键清单

功能	快捷键 (Mac)	快捷键 (Win/Linux)
打开命令面板	`Cmd` + `P`	`Ctrl` + `Shift` + `P`
AI 自然语言搜寻	`#`	`#` 或 `Ctrl` + `
侧边栏 AI 聊天	`Ctrl` + `Space`	`Ctrl` + `Space`
Agent 智能体模式	`Ctrl` + `Shift` + `I`	`Ctrl` + `Shift` + `I`
向上/下跳转 Block	`Cmd` + `Up` / `Down`	`Ctrl` + `Up` / `Down`
清理屏幕	`Cmd` + `K`	`Ctrl` + `L`
新建标签页	`Cmd` + `T`	`Ctrl` + `T`

六、进阶技巧

分屏（Split Panes）：Cmd + D (垂直分屏)，Cmd + Shift + D (水平分屏)。方便一边看日志，一边运行命令。
主题自定义：输入 Cmd + P 搜索 “Themes”，Warp 内置了非常多精美的渐变色和极客风格主题。
SSH 增强：当你 SSH 到远程服务器时，Warp 依然能保持 Block 功能和部分 AI 特性（通过 Warpify 功能）。
MCP 支持：最新版 Warp 支持 Model Context Protocol (MCP)，允许你连接外部工具（如 Linear、Figma、Slack）作为 AI 的背景上下文。

总结

Warp 适合那些觉得传统终端（如 iTerm2 或 CMD）太“简陋”、不想死记硬背复杂 Shell 语法的开发者。它将“查文档 -> 复制命令 -> 粘贴执行 -> 出错搜报错”的循环，直接缩减成了在终端里“问 AI -> 执行”的极简流程。

资料来源

warp.dev
thenewstack.io
youtube.com
medium.com

ccNexus

Mon, 02 Mar 2026 17:43:36 +0800

ccNexus 下载地址

ccNexus 项目介绍
（基于 GitHub 仓库 https://github.com/lich0821/ccNexus 官方描述与 README 整理）

项目全称：ccNexus
官方描述：Intelligent API gateway for Claude Code and Codex CLI —— 一个专为 Claude Code 和 Codex CLI 打造的智能 API 网关。
它能实现端点自动轮换、API 格式转换、实时使用量监控，并无缝对接 OpenAI、Gemini 等多种平台。

核心功能亮点

多端点智能轮换：添加多个 API 地址，自动故障转移（一个挂了立刻切下一个）
API 格式转换：支持 Claude / OpenAI / Gemini 之间相互转换
实时统计面板：请求数、错误数、Token 消耗一目了然
WebDAV 多设备同步：配置和数据跨电脑、手机同步
纯后端 + Docker 支持：可作为 HTTP 服务运行，也支持容器化部署
跨平台原生支持：Windows、macOS、Linux 均有对应可执行文件

支持平台与安装方式（超简单）

去 Releases 页面 下载最新版本（你直接点的就是这个页面）：
https://github.com/lich0821/ccNexus/releases
解压后运行即可：
- Windows：直接双击 ccNexus.exe
- macOS：拖到「应用程序」文件夹，第一次右键 →「打开」
- Linux：tar -xzf ccNexus-linux-amd64.tar.gz && ./ccNexus

快速配置（两步搞定 Claude Code / Codex CLI）

启动 ccNexus（默认监听 http://127.0.0.1:3000）
添加端点（填 API 地址 + Key + 选择转换器）

Claude Code 配置（~/.claude/settings.json）：

{
 "anthropic": {
 "base_url": "http://127.0.0.1:3000"
 }
}

Codex CLI 配置（~/.codex/config.toml）：

model_provider = "ccNexus"
base_url = "http://localhost:3000/v1"

项目数据一览

语言：主要 Go + 前端（JavaScript/CSS）
开源协议：MIT
Star：743+｜Fork：89+
标签：ai-coding、claude-code-proxy、claude-code-router

一句话总结：
如果你在用 Claude Code 或 Codex CLI，但苦于 API 限流、地区限制、多账号切换麻烦，ccNexus 就是专门为你打造的“智能中转站” —— 一键轮换、格式转换、监控全都有，安装后几分钟就能用上。

Coolify vs Dokploy

Sun, 22 Feb 2026 15:37:12 +0800

Coolify vs Dokploy 深度对比

个人来说用Dokploy可能会更加好一点

参考

[中英熟肉] Coolify vs Dokploy：我为何选择其中一个而不是另一个 | Dreams of Code

我将从12个关键维度进行全面对比，让你彻底了解两者的差异和适用场景。

架构与技术栈对比

Coolify 采用单体应用结合微服务组件的架构，后端基于 PHP 8.1+ 和 Laravel 框架，前端使用 Livewire、Alpine.js 和 Blade 模板，数据库为 PostgreSQL，实时通信依赖 Laravel Echo 与 Pusher，部署方式为 Docker 容器 + Docker Compose，安装复杂度为中等。

Dokploy 采用纯粹的微服务架构，后端由 Go（Gin 框架）主导并辅以部分 Node.js 服务，前端基于 React 18、TypeScript 和 Tailwind CSS，数据库同样为 PostgreSQL，实时通信使用 Server-Sent Events（SSE），部署方式为 Docker 容器 + Docker Compose，安装复杂度极简。

在技术层面，Go 相较于 PHP 具有先天性能优势；SSE 虽比 WebSocket 轻量，但 Coolify 的 WebSocket 实现提供更强的双向通信能力；Dokploy 的前端技术栈更现代化，开发体验更流畅；而微服务架构使 Dokploy 更具扩展潜力，Coolify 的单体结构则更易维护和调试。

资源消耗对比（基于 1GB RAM VPS）

资源类型	Coolify（空闲时）	Dokploy（空闲时）	Coolify（部署时）	Dokploy（部署时）
内存占用	450–600 MB	120–200 MB	800 MB+	300–400 MB
CPU 使用	2–5%	1–3%	15–30%	5–15%
磁盘占用	1.5–2 GB	300–500 MB	随应用增长	随应用增长
启动时间	30–45 秒	8–12 秒	N/A	N/A

Dokploy 在资源效率上表现显著优异，尤其适合内存和 CPU 资源有限的低配服务器，而 Coolify 的资源开销较大，更适合拥有充足资源的生产环境。

功能特性详细对比

部署能力

静态站点：Coolify 支持完整部署，Dokploy 仅基础支持 → Coolify 胜出
Node.js、Python、PHP、Go/Rust、Dockerfile：两者均支持，但 Dokploy 在 Go 应用部署上更具原生优势
Java 应用：Coolify 支持，Dokploy 有限支持 → Coolify 胜出
docker-compose.yml：Coolify 完全支持，Dokploy 仅部分支持 → Coolify 胜出
构建缓存：Dokploy 优化更好 → Dokploy 胜出

数据库与服务

PostgreSQL、MySQL/MariaDB、Redis、MongoDB：两者均支持，但 Coolify 提供更完整的管理界面
CouchDB、MinIO：仅 Coolify 支持
WordPress、Ghost：仅 Coolify 支持一键部署
监控服务：Coolify 内置更全面，支持 Prometheus 集成

Git 集成

GitHub、GitLab、Bitbucket：两者均完整支持
Gitea：仅 Coolify 支持
预览部署（PR 部署）：仅 Coolify 支持
部署历史记录：Coolify 记录更完整
自动部署与钩子：两者功能相当

网络与安全

自动 SSL（Let’s Encrypt）、自定义域名、HTTP/2：两者均支持
端口映射：Coolify 更灵活
IP 限制、基础认证：仅 Coolify 支持
防火墙规则、DDoS 防护：两者均不支持

用户体验对比

Coolify 的控制面板功能组织清晰，左侧导航结构成熟，状态指示明确，适合复杂场景，但界面稍显臃肿，操作步骤较多，响应速度有时较慢，新手需要一定学习成本。

Dokploy 的界面极简、响应迅捷、动画流畅，移动端体验优秀，几乎无学习曲线，但高级功能入口较隐蔽，信息展示不够详尽，适合追求“开箱即用”的用户。

部署流程体验

Coolify 的部署流程包括：添加资源 → 选择类型 → 连接 Git → 自动检测 → 配置构建 → 设置环境变量 → 配置域名/SSL → 部署 → 查看日志，首次配置通常需 2–3 分钟，流程透明可控，适合需要精细调整的用户。

Dokploy 仅需：点击“New Application” → 连接 Git → 自动识别 → 一键部署 → 查看日志，1 分钟内即可启动，流程高度自动化，更像“魔法”操作。

多服务器管理对比

Coolify 支持中心化管理，一个主实例可统一管理多个远程服务器，支持分组、标签、资源调度、集中监控、统一证书和跨服务器网络通信，是多服务器运维的理想选择。

Dokploy 为分布式架构，每个实例独立运行，无集中控制能力，需分别登录管理，更适合单服务器或孤立环境。

监控与日志

Coolify 提供企业级监控：实时资源图表（CPU、内存、磁盘、网络）、容器状态、健康检查、报警机制、部署历史、访问日志，并支持 Prometheus 集成。

Dokploy 仅提供基础监控：资源使用概览、容器状态、简单健康检查、实时日志查看，缺乏历史趋势图和深入分析能力。

备份与恢复

Coolify 支持应用与数据库的自动/手动备份、本地或 S3 存储、一键恢复、加密备份、保留策略管理，适合对数据安全要求高的场景。

Dokploy 仅支持手动备份应用和基础数据库备份，无计划任务、无云端存储、无加密机制，备份能力有限。

团队协作

Coolify 提供多用户账户、角色权限管理（管理员、开发者等）、项目共享、操作审计日志、团队邀请系统，是团队协作的首选。

Dokploy 仅支持基础多账户，权限控制极其有限，无团队管理功能，不适合协作场景。

社区与生态

GitHub Stars：Coolify 约 7k+，Dokploy 约 2k+
首次发布：Coolify 2021 年，Dokploy 2023 年
活跃度：Coolify 极高，Dokploy 高
Discord 成员：Coolify 10k+，Dokploy 2k+
问题响应：Coolify 数小时内，Dokploy 1–2 天
文档完整度：Coolify 85%，Dokploy 60%
教程与插件：Coolify 丰富，Dokploy 极少
第三方集成：Coolify 更多

未来发展

Coolify 路线图聚焦企业级功能：Kubernetes 集成、高级 CI/CD、应用市场、集群支持、增强监控。

Dokploy 路线图聚焦核心体验：完善多服务器管理、增补服务支持、性能优化、UI/UX 改进、API 增强。

故障恢复与稳定性

Coolify 经过大量生产验证，错误处理完善，日志详尽，社区有大量解决方案，可自动修复部分问题，但复杂系统偶发难排查问题。

Dokploy 架构简单，错误信息清晰，重启恢复快，但因较新，可能存在未知缺陷，修复依赖社区或自行排查。

使用场景建议

选择 Coolify 如果：

需要团队协作与权限管理
用于企业级生产环境
部署复杂应用（含多种数据库、MinIO、WordPress 等）
管理多台服务器或集群
重视数据备份与恢复机制
需要扩展性与第三方集成
要求稳定可靠与长期维护

选择 Dokploy 如果：

服务器资源有限（<2GB RAM）
追求极速部署与极简体验
个人项目或小型实验
主要部署标准 Web 应用
喜欢现代化技术栈（Go/React）
频繁创建/销毁测试环境
经常通过移动设备管理
偏好轻量、无负担的工具

综合评分（满分10分）

维度	Coolify	Dokploy	说明
功能完整性	9.0	6.5	Coolify 功能全面深入
性能效率	7.0	9.5	Dokploy 明显更轻量
易用性	8.0	9.0	Dokploy 更直观
稳定性	8.5	7.0	Coolify 更成熟可靠
扩展性	9.0	7.0	Coolify 生态更强
团队协作	9.5	5.0	Coolify 完胜
学习曲线	7.0	9.0	Dokploy 更易上手
社区支持	9.0	7.0	Coolify 社区更大
文档质量	8.5	7.0	Coolify 更完善
适合初学者	7.5	8.5	Dokploy 更友好
适合生产	9.0	7.5	Coolify 更可靠
总分	8.6	7.4

最终建议

两者均支持 Docker 安装，推荐在同一台服务器上并行测试：

# Dokploy（端口 3000）
git clone https://github.com/dokploy/dokploy
cd dokploy
docker-compose up -d # 访问 http://server:3000

# Coolify（端口 8000）
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash # 访问 https://server:8000

决策树：

你的主要需求是什么？
- 团队使用、多服务器、企业功能 → Coolify
- 个人项目、追求性能、简单快速 → Dokploy
- 不确定，两者需求都有：
  - 服务器资源充足（>2GB） → Coolify
  - 服务器资源有限（<2GB） → Dokploy
  - 长期项目 → Coolify，短期实验 → Dokploy
- 特别需求：
  - 需要 MinIO、WordPress → Coolify
  - 重视 Go/React 技术栈 → Dokploy
  - 已使用且满意 → 无需切换

我的观点：

对于大多数生产项目：选择 Coolify，功能全面、生态成熟、稳定可靠
对于个人项目或实验：选择 Dokploy，体验流畅、启动飞快、无负担
如果只能选一个长期方案：选择 Coolify，功能与生态决定长远价值
如果你极度在意资源占用：选择 Dokploy，尤其适用于 1GB VPS

发展趋势上，Dokploy 正在快速追赶 Coolify 的功能边界，而 Coolify 也在持续优化性能和轻量化

新电脑快速配置-scoop

Tue, 10 Feb 2026 11:59:09 +0800

windows (注意要最好打开clash的TUN模式)

必备开发工具安装：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

irm get.scoop.sh | iex

scoop install git uv just nvm

安装wsl,执行命令,然后重启电脑,使用管理员打开powershell,输入wsl —- 官方教程

wsl --install

进入wsl后必须安装

sudo apt update
sudo apt install git just -y
curl -LsSf https://astral.sh/uv/install.sh | sh
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

必安装软件
额外插件安装

智能桌面助手–主要功能是查看当前输入法是中/英文

ImTip 智能桌面助手

多台电脑环境变量(.env)同步方案

Sat, 07 Feb 2026 15:06:19 +0800

多台电脑环境变量(.env)同步方案

在多台电脑之间同步环境变量（.env）确实是一个痛点，因为我们既要保证方便（换台电脑就能跑），又要保证安全（不上传到 Git）。

以下是目前行业内主流的几种管理方案，按推荐程度排序：

方案一：手动同步 + 密码管理器（最安全、最通用）

这是最基础也最稳妥的做法，适合个人或小型项目。

操作：在 Git 中只保留 .env.example。
同步：将真实的 .env 内容存放在 1Password、Bitwarden 或飞书文档/Notion 的加密笔记中。
流程：在新电脑上：

git clone 项目。
从密码管理器复制配置。
vi .env 粘贴进去。

方案二：使用 1Password / Doppler 等专业工具（最优雅）

如果你不想手动复制粘贴，现在有很多专业的 Secrets Management (秘密管理) 工具。

Doppler (推荐)：它像是一个云端的 .env 管理器。
你在云端配置变量。
在不同电脑上安装 Doppler CLI。
运行 doppler run -- python main.py，它会自动把云端的变量注入到进程中，本地根本不需要 .env 文件。
1Password CLI：如果你用 1Password，它支持直接将变量注入到本地环境。

方案三：私有的"配置仓库"（进阶方案）

如果你有很多项目，每个项目都有 .env，你可以创建一个私有的 Git 仓库（比如叫 my-secrets）专门存这些文件。

创建一个私有仓库（只有你自己能访问）。
按照项目名存放文件：

/my-secrets
 /project-a/.env
 /project-b/.env

在不同电脑上拉取这个私有仓库。
使用软链接（Symbolic Link）把文件连过去： ln -s ~/my-secrets/project-a/.env ~/projects/project-a/.env

方案四：云端网盘同步（最简单但有风险）

使用 iCloud、Dropbox 或 Google Drive 同步一个专门的配置文件夹。

注意：千万不要直接同步整个项目文件夹（会导致 node_modules 或 git 冲突）。
做法：只同步一个 EnvBackups 文件夹。换电脑时，从网盘拷贝到项目目录下。

核心逻辑对比表

为了帮你决定，参考下表：

方案	便捷性	安全性	适用场景
密码管理器	⭐⭐⭐	⭐⭐⭐⭐⭐	个人项目、密钥不频繁变动
Doppler/Vault	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	自动化要求高、多服务、团队协作
私有配置库	⭐⭐⭐	⭐⭐⭐⭐	深度 Git 用户、多项目管理
云网盘	⭐⭐⭐⭐	⭐⭐	个人开发者、非极其敏感数据

我的建议

首选：使用 .env.example 记录结构，真实内容存在 密码管理器。这能养成良好的安全习惯。
次选：如果你项目非常多，尝试 Doppler。它可以跨平台（Windows/Mac/Linux）同步，且免费额度对个人开发者非常友好。
禁止：绝对不要为了图方便把 .env 传到公共仓库，哪怕是私有仓库，也要确保没有包含生产环境的最核心密钥（如银行支付接口等）。

你想尝试配置一下 Doppler 这种云端同步方案，还是想看如何写一个脚本自动从私有目录同步配置？

nvm

Thu, 05 Feb 2026 16:53:23 +0800

安装使用

cd ~ # Switch to Linux Home Directory

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash # Install Node.js via NVM (Recommended)

#或者如果网络不行，使用下面的国内镜像去拉取
# curl -o- https://cdn.jsdelivr.net/gh/nvm-sh/nvm@v0.40.3/install.sh | bash

# 如果还是不行，应该是解析的问题
# 查看raw.githubusercontent.com的解析地址，如果是0.0.0.0就是有问题的，使用sudo apt install dnsutils 安装nslookup
#nslookup raw.githubusercontent.com

# 如果是解析问题，使用 Google DNS（8.8.8.8）, 修改好解析之后在进行上一步
#echo "nameserver 8.8.8.8" | tee /etc/resolv.conf 

. "$HOME/.nvm/nvm.sh" # Activate NVM without restarting:

nvm install 20 # Install Node.js version 20 (LTS):

node --version && npm --version # Verify Installation

cc-switch

Tue, 03 Feb 2026 10:27:23 +0800

cc-switch 使用

公开教程

bili

github issue — vscode里面使用claude code for vscode免登录

zhihu

安装

入到仓库,这里以wsl-ubuntu为例,下载deb包

cc-switch github地址

2. 使用sudo apt install ./… 命令去安装

配置

创建统一供应商
一键同步
把设置里面的一些东西打开, 但是不需要开代理

配置 claude 供应商

配置支持Anthropic协议的提供商

1.1 配置kimi模型

kimi 有两种供应方式,需要注意一下

配置只支持openai协议的提供商

2.1 需要设置里面开启本地代理

2.2 需要将api格式改成openai,当然api接口也是openai格式对应的接口,这里也是以kimi为例

homebrew

Sun, 01 Feb 2026 19:57:49 +0800

Homebrew 完全指南：从安装到高效使用（2026 最新版）

本文全面介绍 macOS 和 Linux 下最流行的包管理器 Homebrew，涵盖安装、配置、常用命令、实战技巧及常见问题排查，助你成为命令行效率大师。

Homebrew（昵称 brew）是 macOS 和 Linux 上开源的包管理器，被誉为 “The Missing Package Manager for macOS”。它允许你用一行命令安装数千款开发工具、应用和库，无需手动编译或处理依赖。

# 传统方式（繁琐）
./configure && make && sudo make install

# Homebrew（优雅）
brew install node

Homebrew 的优势在于其简单直观的操作方式，无需管理员权限即可安装软件，能够自动解决软件依赖关系，支持大量可用软件包（formulae），同时还能支持 macOS 和 Linux 平台。此外，它还提供了 Cask 来安装图形界面应用，以及 Bottles 来使用预编译二进制文件。

从 Homebrew 4.0 起，官方在 brew.sh 首页主推 .pkg 安装方式，更适合新手。

安装步骤：

访问 GitHub Releases： 👉 https://github.com/Homebrew/brew/releases/latest
下载最新 .pkg 文件（如 homebrew-4.6.1.pkg）
双击安装包，按向导完成安装（需输入密码）
自动配置 PATH（4.6.0+ 版本已内置，无需手动操作）

验证安装：

brew --version
# 输出示例：Homebrew 4.6.1

💡 安装路径自动选择：

Apple Silicon (M1/M2/M3/M4) → /opt/homebrew

Intel Mac → /usr/local

如果需要，也可以使用传统脚本方法进行安装：

# 安装前确保已安装 Xcode 命令行工具
xcode-select --install

# 执行官方安装脚本
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

⚠️ 安装后若 brew 命令不可用，请按终端提示配置 PATH：
# Apple Silicon
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

为了进一步提升 Homebrew 的使用体验，可进行一些基础配置和优化。例如，配置国内镜像源以大幅提升下载速度：

# 替换 brew.git 仓库
git -C "$(brew --repo)" remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git

# 替换 formulae 源（Apple Silicon）
git -C "$(brew --repo homebrew/core)" remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git

# Intel Mac 额外替换：
# git -C "$(brew --repo homebrew/cask)" remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-cask.git

# 重置并更新
brew update-reset
brew update

🌐 常用镜像源：

清华大学：https://mirrors.tuna.tsinghua.edu.cn

中科大：https://mirrors.ustc.edu.cn

阿里云：https://mirrors.aliyun.com

此外，启用自动补全功能可以让你更高效地使用 Homebrew：

# Zsh（macOS Catalina 及以上默认）
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
brew shellenv >> ~/.zshrc
source ~/.zshrc

# Bash
brew shellenv >> ~/.bash_profile
source ~/.bash_profile

Homebrew 提供了一些核心命令来管理软件包。以下是常用的命令速查表：

命令	说明	示例
`brew install <pkg>`	安装软件	`brew install git`
`brew uninstall <pkg>`	卸载软件	`brew uninstall node`
`brew reinstall <pkg>`	重装软件	`brew reinstall python@3.12`
`brew upgrade <pkg>`	升级指定软件	`brew upgrade curl`
`brew upgrade`	升级所有软件	—
`brew cleanup`	清理旧版本	—
`brew list`	列出已安装软件	—
`brew info <pkg>`	查看软件信息	`brew info nginx`
`brew search <keyword>`	搜索软件包	`brew search postgres`

对于 GUI 应用管理，使用 brew install --cask 命令可以安装图形界面应用：

# 安装图形界面应用
brew install --cask google-chrome
brew install --cask visual-studio-code

# 卸载
brew uninstall --cask iterm2

# 查看所有已安装 Cask
brew list --cask

💡 Cask 支持的应用包括：Chrome、VS Code、Docker、Obsidian、Raycast 等。

使用 brew search 和 brew deps 可以进行软件包的搜索及查看依赖关系：

# 搜索软件
brew search python

# 查看可安装的版本
brew search /python@/

# 查看软件依赖树
brew deps --tree node

在实际使用中，Homebrew 可以帮助你快速搭建开发环境。例如，以下命令可以用于配置一个前端开发环境：

# 1. 安装核心工具链
brew install node yarn pnpm git coreutils

# 2. 安装 GUI 工具
brew install --cask visual-studio-code iterm2 docker

# 3. 安装数据库
brew install postgresql redis

# 4. 启动服务（后台运行）
brew services start postgresql
brew services start redis

# 5. 验证安装
node -v && npm -v && psql --version

对于需要管理多个版本 Python 的场景，可以安装特定版本并切换路径：

# 安装特定版本
brew install python@3.11 python@3.12

# 切换版本（通过 PATH 优先级）
echo 'export PATH="/opt/homebrew/opt/python@3.11/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

python3 --version # 输出 3.11.x

Homebrew 还提供了一些高级技巧，例如使用 brew bundle 管理项目依赖：

在项目根目录创建 Brewfile：

# Brewfile
brew "git"
brew "node"
brew "redis"
cask "visual-studio-code"

一键安装/同步环境：

brew bundle # 安装所有依赖
brew bundle cleanup # 卸载未在 Brewfile 中声明的软件

✅ 适合团队协作、新机器快速配置、云开发环境复现

同时还可查看软件安装位置与配置：

# 查看安装路径
brew --prefix node

# 查看配置文件位置
brew --prefix redis
# 输出：/opt/homebrew/opt/redis
# 配置文件通常在：/opt/homebrew/etc/redis.conf

遇到问题时，可使用以下命令进行诊断与修复：

# 检查环境健康状态
brew doctor

# 修复常见问题（如权限、PATH 错误）
brew cleanup
sudo chown -R $(whoami) $(brew --prefix)/*

在实际使用过程中，可能会遇到一些常见问题。以下是一些问题及其解决方案的汇总：

问题	解决方案
`command not found: brew`	重启终端，或执行 `eval "$(/opt/homebrew/bin/brew shellenv)"`
权限错误 `/opt/homebrew`	`sudo chown -R $(whoami):admin /opt/homebrew`
安装卡在 `Updating Homebrew...`	按 `Ctrl+C` 取消，配置国内镜像源后重试
`Error: Cannot install under Rosetta 2`	确保终端以原生 ARM 模式运行（非 Rosetta）
卸载 Homebrew	`/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"`

为了更好地使用 Homebrew，建议遵循以下最佳实践：

✅ 推荐做法：

优先使用 .pkg 安装器，减少配置烦恼
定期执行 brew update && brew upgrade && brew cleanup
用 Brewfile 管理个人/团队开发环境
遇到问题先运行 brew doctor 诊断

❌ 避免做法：

不要混用 sudo brew（Homebrew 设计为无 sudo 运行）
不要手动修改 /opt/homebrew 下的文件结构
不要同时使用多个镜像源（易导致冲突）

如需了解更多 Homebrew 的信息，可以参考以下资源：

官方文档：https://docs.brew.sh
公式仓库：https://github.com/Homebrew/homebrew-core
Cask 仓库：https://github.com/Homebrew/homebrew-cask
社区论坛：https://github.com/Homebrew/discussions

Homebrew 不仅是软件安装工具，更是现代开发者的工作流基石。掌握它，意味着你能在几分钟内搭建起完整的开发环境，告别繁琐的手动配置。

🚀 行动建议：现在就打开终端，执行 brew install just，用 justfile 管理你的常用命令，体验效率飞跃！

# 创建你的第一个 justfile
echo 'hello:
 echo "Hello from Homebrew!"' > justfile
just hello

Happy Brewing! 🍻

Homebrew 为什么它是 macOS 上的必备工具

Homebrew 是一款 macOS（现在也支持 Linux）的包管理器（Package Manager），它的口号是“macOS 缺失的软件包的管理器”。对于任何想要深度掌握 macOS 的用户（尤其是开发者、设计师或极客）来说，Homebrew 几乎是“必装”的神器。

你可以把 Homebrew 理解为 macOS 上的“软件管家”或“应用商店”，但它是通过**命令行（Terminal）**来运作的，而且比普通的 App Store 强大得多。以下是关于 Homebrew 的全方位解读，包括你提到的一系列问题，以及我认为你需要知道的额外信息。

Homebrew 的特点包括：

极简操作： 不需要去浏览器搜索官网、下载 .dmg 文件、拖拽到 Applications 文件夹。一行命令搞定一切。
依赖管理（杀手级特性）： 很多软件需要依赖其他的小程序库才能运行。如果你手动安装，经常会遇到“缺少 xxx 库”的报错。Homebrew 会自动把这些“依赖包”全部帮你下载并配置好。
沙盒安装： Homebrew 会将软件包安装到独立目录（Apple Silicon 芯片在 /opt/homebrew，Intel 芯片在 /usr/local/Cellar），然后通过“软链接”整合到系统里。这意味着它不会弄乱你的系统核心文件，删除时也能删得很干净。
开源免费： 它完全由社区驱动，配方（Formulae）更新速度极快。

如果你只是偶尔装个微信或 Word，可能不需要它。但如果你有以下需求，它是必须的：

安装开发者工具： 比如 Python, Node.js, Git, MySQL 等。这些工具在 App Store 里找不到，去官网下载配置环境变量又非常麻烦，Homebrew 能一键搞定。
统一管理与更新： 你的电脑里装了50个软件，怎么更新？一个一个打开检查更新吗？用 Homebrew，只需要输入 brew upgrade，所有通过它安装的软件都会自动升级到最新版。
脚本化部署： 如果你换了新 Mac，不需要花一天时间重新下载软件。你可以导出一个 Homebrew 列表文件，在新电脑上运行一行命令，所有软件自动装好。

虽然 Homebrew 是目前 macOS 上最主流的选择，但也有其他替代品：

替代品	特点	评价
MacPorts	历史悠久，模仿 FreeBSD 的 Ports 系统。	更严谨。它在完全独立的目录中编译和安装软件，不依赖 macOS 自带的库。这使得它更稳定，但占用空间更大，编译时间更长。
Nix	跨平台，基于纯函数式语言的包管理器。	更极客。它非常强大，支持回滚版本、多版本共存，能保证环境绝对一致。但学习曲线极陡峭，适合高级开发者。
App Store	苹果官方商店。	更安全但受限。适合普通用户下载日常 App，但不仅没有开发工具，且很多开源软件因为审核原因无法上架。
手动安装	下载 DMG/PKG 文件。	最原始。难以管理更新，卸载往往残留垃圾文件。

结论： 对于 95% 的 macOS 用户，Homebrew 是最佳选择，因为它的社区最活跃，软件库最全。

除了基础功能，Homebrew 还有几个关键概念，理解它们能让你成为真正的“高阶用户”。

什么是 Cask？（Homebrew 的 GUI 扩展）

很多人以为 Homebrew 只能装黑底白字的命令行工具（如 Git）。其实不是！Homebrew 有一个扩展叫 Homebrew Cask。

brew install python -> 安装的是命令行工具（配方 Formula）。
brew install --cask google-chrome -> 安装的是图形界面软件（比如 Chrome, VS Code, IINA, Discord, 微信等）。 这意味着你可以用 Homebrew 管理你电脑上几乎所有的软件。

如何维护和清理？

Homebrew 下载安装包后，默认会保留旧版本的缓存。时间久了会占用几十 GB 空间。

常用命令： brew cleanup
这个命令会删除所有过期的下载缓存和旧版本软件，瞬间释放大量磁盘空间。
常用命令： brew doctor
如果你发现 Homebrew 报错，运行这个命令，它会像医生一样自动诊断问题并告诉你怎么修复。

Apple Silicon (M1/M2/M3) 的路径变化

如果你使用的是新款 Mac（M系列芯片），Homebrew 的安装路径发生了变化：

旧款 Intel Mac: /usr/local
新款 M 芯片 Mac: /opt/homebrew 这主要是为了避免与 macOS 自带的 Rosetta 转译机制冲突。虽然使用上没区别，但在配置环境变量时需要注意。

Brewfile (备份你的 Mac)

这是最酷的功能。你可以创建一个名为 Brewfile 的文本文件，里面写上：

brew "git"
brew "node"
cask "google-chrome"
cask "visual-studio-code"

然后运行 brew bundle。Homebrew 就会按照这个清单自动把所有软件装好。这被称为 “Infrastructure as Code” (基础设施即代码)，是很多工程师配置新电脑的秘诀。

Homebrew 是 macOS 的外挂级装备。它让软件安装变得像手机应用商店一样简单，同时又保留了极高的可控性和专业性。

想现在尝试一下吗？ 你只需要打开你的终端（Terminal），粘贴官方的一行安装代码即可开始。

软件工程的范式转移：基于 Claude Code 与智能体协作的高效编程实践

Sun, 01 Feb 2026 18:23:03 +0800

一人开发，文档何去何从？AI 时代，我用 4 份文档搞定整个项目

曾经，我对着国标“十三类文档”头皮发麻；如今，一个 README + 3 份轻量文档，撑起年更 5 个项目的开发节奏。AI 不是替代文档，而是帮我们找回文档的本质：为解决问题而生，而非为流程而写。

刚入行时，我曾花 3 天写《详细设计说明书》，结果上线前需求一改，文档直接报废。更讽刺的是——没人看它。开发同事直接翻代码，产品经理盯着原型图，测试同学只关心用例。

传统软件工程推崇的“十三类文档”（需求规格、概要设计、详细设计……），诞生于瀑布模型时代，核心假设是：

✅ 需求稳定 ✅ 团队分工明确 ✅ 文档是交付物

但今天的现实是：

❌ 需求周周变 ❌ 一人身兼数职 ❌ 代码才是唯一真相

当文档沦为“流程合规”的仪式，它就从资产变成了负债。

经过 3 年独立开发实践 + AI 工具深度使用，我将文档体系压缩为 4 份核心文档。它们不是“简化版传统文档”，而是重构了文档的存在形式：

文档	传统对应	核心价值	存储位置
`README.md`	需求+用户手册	5 分钟让任何人跑起来	代码库根目录
`DESIGN.md`	概要+详细设计	回答“为什么这样设计”	代码库 `/docs`
可执行文档	接口文档+数据库设计	代码即文档，永不脱节	嵌入代码/配置文件
`DEPLOY.md`	部署+运维手册	一键恢复服务	代码库根目录

💡 关键转变：从“写文档”到“让系统自动生成文档”

README.md —— 项目的“电梯演讲”

# TodoFlow 🚀
极简任务流工具，3 命令启动，无数据库依赖

## ✨ 为什么需要它？
- 现有工具太重（Notion/Jira）→ 本项目单文件 200 行 Python
- 需要可视化流程 → 内置 Mermaid 流程图渲染

⚡ 快速开始
```bash
git clone https://github.com/xxx/todoflow
pip install -r requirements.txt
python app.py # 访问 http://localhost:8000

📡 核心 API

curl -X POST /tasks -d '{"title":"写博客"}' # 创建任务
curl /flow # 生成 Mermaid 流程图

❓ 常见问题 Q: 如何持久化数据？ A: 默认内存存储，加 --persist file.json 启用 JSON 持久化


> ✅ 价值：新协作者/未来的你，5 分钟内理解项目价值并跑起来

**`DESIGN.md`** —— 决策的“时间胶囊”

```markdown
# 架构设计决策

## 为什么不用数据库？
- 需求：单机使用，数据量 < 1000 条
- 决策：JSON 文件持久化，避免 Docker 部署复杂度
- 代价：不支持并发写入 → 接受，本项目为个人工具

## 为什么选 FastAPI 而非 Flask？
- 需求：需要自动生成 OpenAPI 文档
- 决策：FastAPI 内置 Swagger UI，省去手写 API 文档
- 验证：`/docs` 路径直接访问交互式文档

✅ 价值：3 个月后回看，秒懂“当初为啥这么设计”，避免重复踩坑

可执行文档 —— 永不过期的“活文档”

API 文档：用 FastAPI 写代码 → 自动生成 /docs Swagger UI
数据库 Schema：SQLAlchemy 模型 + 注释 → alembic 自动生成迁移脚本

环境变量：.env.example 文件即文档：

# 必填：邮件服务配置
SMTP_HOST=smtp.example.com
SMTP_PORT=587
# 选填：调试模式（默认 false）
DEBUG=true

✅ 价值：文档与代码同生命周期，改代码即改文档

DEPLOY.md —— 运维的“急救包”

# 部署指南


## 云服务器部署（Ubuntu 22.04）
```bash
# 1. 安装依赖
sudo apt install python3-pip nginx

# 2. 配置 systemd 服务
sudo cp todoflow.service /etc/systemd/system/
sudo systemctl start todoflow

# 3. 配置 Nginx 反向代理（见 nginx.conf）
sudo nginx -s reload

故障恢复

服务挂了：sudo systemctl restart todoflow
磁盘满：rm -rf /var/log/todoflow/*.log


> ✅ 价值：半夜报警时，照着步骤 5 分钟恢复服务

---

文档整合的核心不是“少写”，而是 **“让机器生成，人只校对”**。我的工作流：

| 场景 | 传统做法 | AI 增强做法 |
|------|----------|-------------|
| 写 API 文档 | 手写 Markdown 表格 | 用 Copilot 从函数签名生成 OpenAPI YAML |
| 写 Changelog | 翻 Git Log 人工总结 | `git log --oneline v1.0..v1.1 \| cursor "生成用户友好的更新日志"` |
| 写部署步骤 | 回忆上次操作 | 让 AI 分析 Dockerfile + docker-compose.yml 生成部署命令 |
| 写设计决策 | 事后补文档 | 开发时对 Cursor 说：“解释为什么用 Redis 而不用 Memcached”，直接生成 DESIGN.md 片段 |

> 🌰 案例：我让 Cursor 分析一段异步队列代码，10 秒生成：
```markdown
> ## 为什么用 asyncio.Queue 而非 Celery？
> - 项目规模：单进程任务调度，无需分布式
> - 依赖成本：避免引入 RabbitMQ/Redis
> - 性能需求：任务量 < 1000/天，内存队列足够
> - 代价：进程重启丢失队列 → 接受，任务可重试

给独立开发者的 3 条建议：

起步期（<1 周项目） → 只维护 README.md，包含：核心功能 + 3 条启动命令 + 1 个 curl 示例
成长期（持续维护项目） → 拆出 DESIGN.md（记录关键决策） + DEPLOY.md（记录部署细节）
拒绝“文档洁癖” → 不追求格式精美，追求关键时刻能救命。一段能复制粘贴的命令，胜过 10 页精美 PDF

最高级的文档，是“无需文档”

代码自解释 + 系统自描述：

用 --help 输出清晰的 CLI 帮助
用 /health 提供服务状态自检
用 OpenAPI 让前端直接调试后端
用 .env.example 告诉用户需要哪些配置

当工具链足够智能，文档将退化为“异常路径的注解”——只在人类需要理解“为什么”时出现。

AI 时代，我们不再为流程写文档，而是为“未来的自己”留线索。 4 份文档，不是妥协，而是聚焦：把时间留给创造，把记忆交给工具。

延伸阅读

我的开源项目文档模板（含 DESIGN.md / DEPLOY.md 实例）
《Software Engineering at Google》Chapter 19: Documentation
工具推荐：MkDocs（轻量文档站）、Mermaid（代码画图）、Docusaurus（React 驱动文档）

本文首发于个人博客，欢迎转发。独立开发不易，文档减负，从今天开始。 ✨

软件工程的范式转移：基于 Claude Code 与智能体协作的高效编程实践

在软件开发工具演进的十年周期中，我们正见证一场深刻的范式转移：人工智能的角色从“行内补全助手”跃迁为“具备工具调用能力的协作智能体”。GitHub Copilot 等早期工具聚焦于提升单行代码的编写速度，而 Anthropic 推出的 Claude Code 则重新定义了人机协作的边界——它不再局限于预测下一个 token，而是能够理解整个代码库、规划多步任务、并在人类监督下执行具有真实副作用的操作。

本文将基于 Anthropic 官方文档与经验证的工程实践，系统阐述如何构建一套安全、高效、可扩展的智能体协作编程体系，并重点探讨如何将文档维护无缝融入开发工作流。

一、Claude Code：终端原生的协作智能体

Claude Code 是 Anthropic 官方推出的命令行工具，其设计哲学根植于 Unix 的“组合性”原则：每个工具做好一件事，通过管道组合解决复杂问题。与 IDE 插件不同，Claude Code 以终端为第一交互界面，天然支持文件系统操作、Shell 命令执行与 Git 集成。

核心能力矩阵

能力维度	具体表现	安全约束
代码库理解	通过 200K+ tokens 上下文窗口分析整个项目结构	仅访问用户授权的目录
工具调用	在批准后执行文件编辑、Shell 命令、Git 操作	默认需人工批准，无静默执行
任务规划	将模糊需求拆解为可验证的原子步骤	关键节点自动暂停等待审查
持续对话	会话中保持对项目状态的长期记忆	企业版支持 Zero-Retention（不保留对话用于训练）

💡 关键认知：Claude Code 是 human-in-the-loop 的增强型代理，而非全自动机器人。所有修改操作默认需用户显式批准，这是 Anthropic 安全架构的基石。

性能基准：真实世界表现

在 SWE-bench Verified（评估真实 GitHub issue 修复能力的权威基准）中，Claude Sonnet 4.5（2025 年 9 月发布）达到 77.2%–80.9% 的解决率，显著超越前代模型。在 OSWorld 基准（评估操作系统级多步任务）中，其得分从 Sonnet 3.5 的 42.2% 提升至 61.4%，证明其在复杂工作流中的实用性。

二、规则系统：CLAUDE.md 的工程化实践

CLAUDE.md 是 Claude Code 的核心配置机制——一个位于项目根目录的 Markdown 文件，会在会话启动时自动加载为系统提示词。它将团队的架构决策、编码规范与工作流知识转化为 AI 可理解的指令。

2.1 文件加载逻辑

位置	行为	说明
`./CLAUDE.md`	✅ 官方原生支持，自动加载	项目级规范的唯一标准位置
`./subdir/CLAUDE.md`	✅ 当工作目录进入子目录时自动激活	适用于 Monorepo 的模块级规范
`~/.claude/CLAUDE.md`	⚠️ 非官方标准，需社区工具支持	个人全局偏好（如 claude-flow）

⚠️ 重要澄清：不存在 .clauderules 文件格式。所有规则应通过 CLAUDE.md 表达，或通过 Skills 机制封装为可复用工作流。

2.2 内容设计原则：简洁、可操作、聚焦

Anthropic 官方建议 CLAUDE.md 保持在 500 行以内，社区实践共识为 100–300 行。关键在于传递“必须知道”的规则，而非复制完整技术文档。

# 项目概览
电商平台后端服务，基于 FastAPI + PostgreSQL，遵循领域驱动设计（DDD）

## 技术栈
- 语言：Python 3.11+
- 依赖管理：Poetry
- 数据库迁移：Alembic
- 测试：pytest + factory_boy
- 文档：MkDocs + mkdocstrings（自动从 docstrings 生成 API 参考）

## 代码规范
- 类型注解：所有函数必须包含完整类型提示（含返回值）
- 异常处理：业务异常继承自 `DomainError` 基类
- 日志：使用 structlog，禁止使用 print()
- 测试：新功能必须附带单元测试（覆盖率 ≥80%）
- 文档：公共 API 必须包含 Google 风格 docstrings，变更后同步更新用户指南

## 关键命令
- 启动开发服务器：`poetry run uvicorn app.main:app --reload`
- 运行测试：`poetry run pytest tests/ -xvs`
- 生成数据库迁移：`poetry run alembic revision --autogenerate -m "描述"`
- 构建文档站点：`poetry run mkdocs build`
- 本地预览文档：`poetry run mkdocs serve`

三、文档即代码：MkDocs 与 AI 协作的工程实践

文档滞后于代码是技术债的主要来源。通过将 MkDocs 与 Claude Code 深度集成，我们可以构建“代码变更即触发文档更新”的闭环工作流，实现文档与实现的实时对齐。

3.1 自动化参考文档：mkdocstrings + 动态生成

mkdocstrings 插件可自动从 Python docstrings 提取 API 文档，但需配合生成脚本实现模块级页面的自动创建：

# scripts/gen_ref_pages.py
"""自动生成 MkDocs 参考文档页面"""
from pathlib import Path
import mkdocs_gen_files

nav = mkdocs_gen_files.Nav()

# 递归遍历源代码
for path in sorted(Path("src").rglob("*.py")):
 # 跳过 __init__.py 和测试文件
 if path.name.startswith("__") or "test" in path.parts:
 continue

 module_path = path.relative_to("src").with_suffix("")
 doc_path = path.relative_to("src").with_suffix(".md")
 full_doc_path = Path("reference") / doc_path

 # 构建导航层级
 parts = list(module_path.parts)
 nav[parts] = full_doc_path.as_posix()

 # 为每个模块创建引用页面
 with mkdocs_gen_files.open(full_doc_path, "w") as fd:
 identifier = ".".join(module_path.parts)
 fd.write(f"# `{identifier}`\n\n")
 fd.write(f"::: {identifier}\n")
 fd.write(" options:\n")
 fd.write(" show_root_heading: false\n")
 fd.write(" show_source: true\n")

# 生成 SUMMARY.md 导航
with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
 nav_file.writelines(nav.build_literate_nav())

mkdocs.yml 配置示例：

plugins:
 - search
 - gen-files:
 scripts:
 - scripts/gen_ref_pages.py
 - literate-nav:
 nav_file: SUMMARY.md
 - mkdocstrings:
 handlers:
 python:
 options:
 docstring_style: google
 show_signature: true
 show_source: true
 merge_init_into_class: true

nav:
 - 概览: index.md
 - 用户指南: guides/
 - API 参考: reference/
 - 架构设计: architecture/

3.2 Claude Code 驱动的文档维护工作流

Claude Code 无法“自动”维护文档，但可通过 Hooks + Git 集成构建半自动化工作流：

步骤 1：检测代码变更并触发文档任务

// ~/.claude/settings.json
{
 "hooks": {
 "postToolUse": [
 {
 "command": "bash .github/scripts/check-doc-impact.sh {file}",
 "onTool": "edit"
 }
 ]
 }
}

#!/bin/bash
# .github/scripts/check-doc-impact.sh
FILE=$1

# 检测是否修改了公共 API
if git diff HEAD -- "$FILE" | grep -q "^+.*def \|^-.*def \|^\+.*class \|^-.*class "; then
 echo "⚠️ 检测到公共 API 变更，请同步更新文档："
 echo " 1. 检查 docstrings 是否完整"
 echo " 2. 运行: poetry run python scripts/gen_ref_pages.py"
 echo " 3. 如需更新用户指南，运行: claude code '根据新功能更新 guides/ 目录下的相关文档'"
fi

步骤 2：AI 辅助生成用户指南内容

当开发者执行：

claude code "根据新添加的 PaymentService.refund() 方法，更新 guides/payments.md 中的退款流程说明"

Claude Code 将：

读取 src/services/payment.py 中的实现与 docstrings
分析现有 guides/payments.md 结构
生成包含以下要素的更新建议：
- 新方法的使用场景与参数说明
- 与现有流程的集成点（Mermaid 序列图）
- 常见错误处理示例
在应用前请求人工审查（默认 ask 模式）

步骤 3：文档质量保障

# .github/workflows/docs.yml
name: Documentation Quality Gate

on:
 pull_request:
 paths:
 - 'src/**'
 - 'docs/**'
 - 'mkdocs.yml'

jobs:
 validate-docs:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - name: Set up Python
 uses: actions/setup-python@v5
 with:
 python-version: "3.11"

 - name: Install dependencies
 run: |
 pip install poetry
 poetry install --with docs

 - name: Build documentation (strict mode)
 run: poetry run mkdocs build --strict
 # --strict 会在发现 broken links 或 warnings 时失败

 - name: Check for stale docstrings
 run: |
 # 检测有实现但无 docstrings 的公共函数
 poetry run pylint --load-plugins pylint.extensions.docparams \
 --disable=all --enable=missing-param-doc,missing-return-doc \
 src/ || true

3.3 AI 生成架构可视化：Mermaid 集成

现代 MkDocs（配合 mkdocs-material 主题）原生支持 Mermaid，Claude Code 可生成精确的架构图：

## 认证流程

```mermaid
sequenceDiagram
 participant U as User
 participant F as Frontend
 participant A as AuthService
 participant T as TokenService
 participant DB as PostgreSQL

 U->>F: POST /login (email, password)
 F->>A: validate_credentials(email, password)
 A->>DB: SELECT password_hash FROM users WHERE email=?
 DB-->>A: password_hash
 A->>A: bcrypt.verify(password, password_hash)
 alt valid
 A->>T: generate_jwt(user_id, roles)
 T-->>A: access_token, refresh_token
 A-->>F: {access_token, refresh_token}
 F-->>U: 200 OK
 else invalid
 A-->>F: 401 Unauthorized
 F-->>U: 错误提示
 end


开发者只需提示：
```bash
claude code "为新实现的 OAuth2 授权码流程生成 Mermaid 序列图，放入 docs/guides/auth.md"

Claude Code 将基于代码实现生成符合 Mermaid 语法的图表，并在插入前展示预览供审查。

四、能力扩展：Skills 机制与按需加载

Skills 是 Claude Code 官方支持的模块化扩展系统，用于封装重复性工作流（如代码解释、测试生成、文档更新）。其独特价值在于支持真正的按需加载——这是整个生态中唯一实现“渐进式披露”的机制。

4.1 目录结构

~/.claude/skills/
├── update-docs/ # 文档更新专用技能
│ ├── SKILL.md
│ ├── templates/
│ │ ├── guide-template.md
│ │ └── api-changelog.md
│ └── examples/
│ └── payment-refund-doc.md
└── explain-code/
 └── SKILL.md

4.2 文档更新技能示例

---
name: update-docs
description: "根据代码变更同步更新 MkDocs 文档，包括 API 参考与用户指南"
disable-model-invocation: false
---
# 适用场景
- 新增/修改公共 API 后更新参考文档
- 功能迭代后更新用户指南
- 重构后更新架构图

# 工作流程
1. 分析变更文件的 diff，识别影响范围
2. 检查相关模块的 docstrings 完整性
3. 更新或创建对应的 MkDocs Markdown 页面
4. 如涉及流程变更，生成 Mermaid 序列图/流程图
5. 在提交前运行 `mkdocs build --strict` 验证

# 禁止行为
- 不得删除现有文档内容（除非确认已废弃）
- 不得修改未受影响的文档章节
- 所有图表必须基于实际代码逻辑生成

五、自动化防护：Hooks 与权限模式

5.1 Hooks：确定性生命周期脚本

Hooks 是运行在 AI 智能体循环之外的确定性脚本，用于在关键节点执行强制性操作：

事件	触发时机	典型用途
`PreToolUse`	工具执行前	拦截危险命令（如 `rm -rf`）、验证权限
`PostToolUse`	工具执行后	运行 linter、格式化、单元测试、文档影响检测
`UserPromptSubmit`	用户提交请求前	自动附加上下文（如当前 Git 分支）

5.2 权限模式：三重安全护栏

模式	行为	适用场景
`ask`（默认）	每次操作前请求用户批准	日常开发，平衡效率与安全
`auto`	自动执行（生产环境禁用）	受控的 CI/CD 流水线
`plan`	仅生成操作计划，不执行修改	代码审查、安全审计、文档更新预览

# 预览文档更新计划（无副作用）
claude code --permission-mode plan "根据新 PaymentService.refund() 方法更新用户指南"

# 执行文档更新（需人工批准每步操作）
claude code "更新 guides/payments.md 中的退款流程说明，包含 Mermaid 序列图"

六、外部系统集成：MCP 协议

Model Context Protocol (MCP) 是 Anthropic 于 2024 年 11 月推出的开放标准，用于安全地连接 AI 与外部工具（数据库、API、私有文档库）。

典型集成场景

工具类型	MCP 服务器	能力示例
代码托管	`github-mcp`	查询 issue 状态、拉取 PR 历史
数据库	`pg-mcp`	安全查询 schema、执行只读诊断 SQL
浏览器自动化	`playwright-mcp`	在真实浏览器中运行端到端测试
文档系统	`notion-mcp`	同步技术设计文档至 Notion 知识库

⚠️ 安全提示：使用第三方 MCP 服务器需自行评估风险。Anthropic 不验证所有社区服务器的安全性，建议在隔离环境中测试。

七、跨工具协作：GitHub Copilot 指令文件

.github/copilot-instructions.md 是 GitHub 官方标准，被 Copilot Chat/Agents/CLI 自动识别。在混合工具环境中，建议分工如下：

CLAUDE.md：聚焦架构级规范、复杂工作流与文档维护策略
.github/copilot-instructions.md：聚焦行内补全相关的微观约束

# 项目规范（Copilot 专用）

## 架构约束
- 所有 API 路由必须通过 `@auth_required` 装饰器
- 数据库查询必须使用 SQLAlchemy ORM，禁止原生 SQL

## 文档要求
- 公共函数必须包含 Google 风格 docstrings
- 参数描述需包含类型与业务含义（如 "user_id: int - 已认证用户的唯一标识"）

八、安全治理框架

随着 AI 获得工具调用能力，安全风险从“数据泄露”扩展至“操作风险”。企业应实施分层防御：

风险类型	缓解措施
代码/文档泄露	选择企业版（Zero-Retention 策略），禁用内容用于模型训练
包幻觉	Hooks 集成依赖验证（`poetry check`），禁止直接 `pip install` 未知包
权限过载	始终使用 `--permission-mode ask`，关键操作要求二次确认
文档失真	所有 AI 生成文档必须经人工审核，CI 中启用 `mkdocs build --strict`
审计缺失	启用 `claude code --log-to-file` 记录所有操作，满足合规要求

🌍 合规提示：根据 2025 年生效的《欧盟 AI 法案》，高风险决策必须保留 human-in-the-loop 覆盖权，所有 AI 生成内容（包括文档）需标记来源（如 Git commit message 包含 [AI-assisted]）。

九、实战工作流：从代码变更到文档更新

# 步骤 1：实现新功能（支付退款）
claude code "在 PaymentService 中实现 refund(transaction_id, reason) 方法，包含完整类型注解与 Google 风格 docstrings"

# 步骤 2：运行测试验证功能
poetry run pytest tests/services/test_payment.py -xvs

# 步骤 3：检测文档影响（Hooks 自动触发）
# 输出: "⚠️ 检测到公共 API 变更，请同步更新文档"

# 步骤 4：预览文档更新计划
claude code --permission-mode plan "根据新 refund() 方法更新 guides/payments.md 中的退款流程"

# 步骤 5：执行文档更新（人工批准每步）
claude code "更新 guides/payments.md：1) 添加 refund() 使用示例 2) 生成退款流程 Mermaid 序列图 3) 补充错误处理说明"

# 步骤 6：验证文档构建
poetry run mkdocs build --strict

# 步骤 7：提交变更（标记 AI 参与）
git add src/services/payment.py docs/guides/payments.md
git commit -m "[AI-assisted] 实现 PaymentService.refund() 并同步更新用户指南"

十、结语：文档作为一等公民

在智能体协作时代，文档不应是开发完成后的“补作业”，而应成为与代码、测试同等重要的一等公民。通过将 MkDocs 深度融入开发工作流，配合 Claude Code 的辅助能力，我们能够构建：

自动化参考文档：通过 mkdocstrings + 动态生成脚本，确保 API 参考与代码实现零延迟同步
AI 辅助用户指南：在功能迭代时，由 Claude Code 生成初稿并插入精确的架构可视化
质量门禁：通过 mkdocs build --strict 与 CI 集成，将文档完整性纳入合并门槛

这一实践的核心哲学是：AI 负责执行重复性文档任务，人类负责审核与价值判断。当文档维护的成本显著降低，团队才能真正践行“文档即代码”的工程文化，将知识沉淀转化为可持续的竞争优势。

参考资源

本文基于 Anthropic 官方文档与 MkDocs 社区实践（截至 2026 年 2 月）编写。技术持续演进，建议定期查阅官方资源获取最新功能与安全实践。

数据集标注工具

Mon, 29 Dec 2025 15:05:31 +0800

ubiai

LabelStudio

install

docker run -it -p 8080:8080 -v %cd%/mydata:/label-studio/data heartexlabs/label-studio:latest label-studio --log-level DEBUG

-v %cd%/mydata:/label-studio/data 挂载本地目录到容器中，实现数据持久化。 %cd%：这是 Windows 命令行中的变量，表示当前目录（在 Linux/macOS 中应写作 $(pwd)）。所以 %cd%/mydata 指的是你当前文件夹下的 mydata 子目录。它被挂载到容器内的 /label-studio/data 路径。

实用软件工具｜好用软件推荐

Fri, 11 Jul 2025 15:07:54 +0800

IDE插件

Material Icon Theme 好看的图标主题

浏览器插件

飞书文档下载为md文件 Cloud Document Converter

注意：只能下载飞书文档，飞书表格不行

macOS 工具

Clipy - 剪贴板管理器

官网： https://clipy-app.com/

免费开源的 macOS 剪贴板历史管理工具，支持：

📋 自动保存剪贴板历史记录
✂️ 快捷文本片段管理
⌨️ 快捷键快速访问（默认 ⌘ + Shift + V）
🖼️ 支持文本和图像格式

安装方式：

brew install --cask clipy

使用场景： 开发者复制代码片段、办公人员管理常用文本、提高复制粘贴效率

wsl使用教程

Mon, 30 Jun 2025 15:04:11 +0800

基础知识

安装

配置

配置中文字体

sudo apt update
sudo apt install fonts-noto-cjk fonts-wqy-microhei fonts-wqy-zenhei
sudo locale-gen zh_CN.UTF-8

如果从windows复制过来的.sh需要修改字符

sed -i 's/\r$//' ./zata.sh

问题解决

wsl和docker冲突表现为wsl无法联网 — 把docker关了，或者使用docker里面的linux容器

下面不要用了，会把网络设置搞乱

~~使用下面命令之后重启可以恢复，但是当再次打开docker又会出现问题,主要就是关了docker就行~~

wsl --shutdown
netsh winsock reset

claude-code&codex&Gemini-cli

Mon, 23 Jun 2025 19:57:52 +0800

注意 : 不可或缺的一个工具是 cc-switch 可以查看cc-switch教程

claude code

使用教程

"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" # agent teams

# 无需确认
# 如果用户是root
IS_SANDBOX=1 claude --dangerously-skip-permissions
# 如果用户不是root
claude --dangerously-skip-permissions

# 别名，方便使用，加入到zshrc中
alias clauded="claude --dangerously-skip-permissions"

安装

mac/linux/wsl

安装

 # 注意，要吧下面的端口设置成你自己的vpn端口，为什么先要设置代理环境变量？ 因为curl默认不会走代理

 # 设置代理环境变量，这个是socks5代理
 export all_proxy="socks5://127.0.0.1:7897"
 或者
 export https_proxy=http://127.0.0.1:7897 http_proxy=http://127.0.0.1:7897


 curl -fsSL https://claude.ai/install.sh | bash

卸载

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

windows

推荐通过wsl安装

安装参考

wsl –install # 如果出现问题就要去 https://blog.csdn.net/no1xium/article/details/131285182
wsl –list –online # 查看有哪些可用的镜像,如果没有Ubuntu-24.04进行第三步
wsl –install -d Ubuntu-24.04

进入到wsl里面

sudo apt update sudo apt full-upgrade -y

目前claude支持原生安装（2026/02） claude code

curl -fsSL https://claude.ai/install.sh | bash

安装cc-switch，参考本网站的 cc-switch 教程

Install Additional Dependencies

sudo apt install python3 python3-pip -y # Install Python (if needed)

sudo apt install git ripgrep -y # Install Git and Ripgrep (Recommended)


mkdir -p ~/.npm-global

配置其他模型api以使用claude_code — 20260228

参考cc-swith

使用技巧

CLAUDE.md 文件管理

claude code 使用git worktree 开启多线程工作

1. 创建 Git Worktree 为每个任务创建独立工作目录和分支。例如，开发 feature-auth 和 feature-ui：

git worktree add ../my-project-auth -b feature-auth
git worktree add ../my-project-ui -b feature-ui

验证：

git worktree list

1. 配置环境复制配置文件（如 .env）并设置不同端口以避免冲突：

cp .env ../my-project-auth/.env
cp .env ../my-project-ui/.env

my-project-auth/.env：PORT=3000
my-project-ui/.env：PORT=3001

安装依赖：

cd ../my-project-auth && npm install
cd ../my-project-ui && npm install

启动 Claude Code

在每个 Worktree 中运行 Claude Code：

终端 1：

cd ../my-project-auth
claude "Implement JWT-based authentication with refresh tokens"

终端 2：

cd ../my-project-ui
claude "Redesign UI with responsive Tailwind CSS layout"

1. 提交和合并提交代码：

cd ../my_search-project-auth
git add .
git commit -m "Add JWT authentication"
cd ../my-project-ui
git add .
git commit -m "Update UI with Tailwind CSS"

合并到主分支：

cd ../my-project
git checkout main
git merge feature-auth
git merge feature-ui

1. 清理删除 Worktree 和分支：

git worktree remove ../my-project-auth
git worktree remove ../my-project-ui
git branch -d feature-auth
git branch -d feature-ui

优化技巧

自动化脚本：

function wt() {
 git worktree add ../worktrees/$1 -b $1
 cd ../worktrees/$1
 cp ../my-project/.env .env
 npm install
 claude
}

使用：wt feature-auth

任务文件：在每个 Worktree 创建 CLAUDE.md 记录指令，调用 claude @CLAUDE.md。
IDE 集成：使用 VS Code 的 Git Worktrees 扩展切换 Worktree。
注意事项
确保不同 Worktree 使用不同分支。
为数据库任务配置独立实例（如 Docker 容器）。
监控资源使用，避免并行任务过多导致过载。

The Permission System Hack That Changes Everything

Tips: --dangerously-skip-permissions 这个参数只能执行在非root用户下执行，因此如果只有root用户需要创建一个账户

sudo useradd -m -s /bin/bash username # 创建新用户

su - username # 切换用户

curl --resolve raw.githubusercontent.com:443:185.199.108.133 -fsSL https://raw.githubusercontent.com/mklement0/n-install/stable/bin/n-install | bash -s 22 # 安装 node 其中--resolve表示自动去找可用的地址， 也可以安装nvm

npm install -g https://gaccode.com/claudecode/install --registry=https://registry.npmmirror.com # 安装gac站的claude code

claude --dangerously-skip-permissions

在容器中开发时–dangerously-skip-permissions指令让它自动执行

# 如果用户是root
IS_SANDBOX=1 claude --dangerously-skip-permissions

# 如果用户不是root
claude --dangerously-skip-permissions

Claude Code Plugin 系统终极指南 (最新版) — 20260228

Claude Code 是 Anthropic 官方推出的 AI 编码助手（CLI + IDE 集成）。其 Plugin（插件）系统 是最强大的扩展机制，允许通过 Skills、Agents、Hooks、MCP Servers、LSP 等组件扩展功能，实现一键安装、版本管理和团队共享，告别手动复制 .claude/ 配置。

本教程结合官方文档与最佳实践，覆盖 环境搭建 → 发现使用 → 管理维护 → 开发创建 全流程。

一、环境搭建：安装 Claude Code

在使用插件前，需确保已安装最新版本的 Claude Code。

1.1 安装 CLI 工具

适用于 macOS / Linux / WSL（推荐）：

curl -fsSL https://claude.ai/install.sh | bash

适用于 Windows PowerShell：

irm https://claude.ai/install.ps1 | iex

验证安装 (建议版本 1.0.33+)：

claude --version

首次运行 claude 需登录 Anthropic 账号（需要 Claude Pro / Team / Max 订阅）。

1.2 安装 IDE 插件（可选但推荐）

插件系统在 IDE 中同样可用，且体验更佳：

VS Code：扩展市场搜索 “Claude Code” 安装官方插件。
JetBrains：市场搜索 “Claude Code [Beta]” 安装。
效果：编辑器右侧可直接聊天，支持 Diff 查看、自动打开文件，所有插件命令无缝集成。

二、核心概念：插件由什么组成？

插件不仅仅是命令，它是一个功能包。理解组件有助于你选择合适的插件。

组件	功能描述	调用方式	典型用途
Skills / Commands	自定义 slash 命令	`/plugin-name:command`	快捷操作（如 `/commit:commit`）
Agents	专用子代理	`/agents` 列表中选择	特定任务专家（如安全审查员）
Hooks	自动化钩子	自动触发	文件保存后自动 lint/format
MCP Servers	连接外部工具	自动出现在工具列表	连接 GitHub、Slack、数据库
LSP Servers	代码智能服务	自动启用	代码跳转、类型提示、诊断

注意：安装插件后，命令通常带有 命名空间 以避免冲突，例如 /commit-commands:commit。

三、用户指南：发现与安装插件

3.1 打开插件管理器

在 Claude Code 会话中输入：

/plugin

进入交互式界面，包含四个 Tab：

发现 (Discover)：浏览所有可用插件。
已安装 (Installed)：管理已装插件。
市场 (Marketplaces)：添加/删除插件源。
错误 (Errors)：查看加载失败详情。

操作提示：使用 Tab 切换选项卡，方向键选择，Enter 确认。

3.2 添加插件市场

官方市场 claude-plugins-official 通常自动可用。如需添加第三方市场：

添加 Anthropic 演示市场：

/plugin marketplace add anthropics/claude-code

添加 GitHub 仓库市场：

/plugin marketplace add owner/repo

添加本地路径：

/plugin marketplace add ./my-marketplace

3.3 安装插件（三种方式）

方式 A：交互式（最简单）

输入 /plugin → 切换到“发现”Tab。
找到插件 → Enter。
选择安装范围（关键步骤）：
- user：仅当前用户，所有项目可用（默认）。
- project：写入 .claude/settings.json，团队共享（推荐）。
- local：写入 .claude/settings.local.json，不提交 git。

方式 B：命令行一键安装

官方市场安装：

/plugin install typescript-lsp@claude-plugins-official

指定范围安装（团队共享）：

claude plugin install pr-review-toolkit@anthropics-claude-code --scope project

方式 C：热门插件推荐

插件名	功能	推荐场景
`typescript-lsp` / `pyright-lsp`	代码智能	所有开发项目
`commit-commands`	智能提交	Git 工作流
`pr-review-toolkit`	PR 审查	代码合并前
`security-guidance`	安全审查	敏感代码处理
`context7`	API 文档	查阅最新文档

四、管理插件：更新与维护

操作	命令 / 路径	说明
查看已安装	`/plugin` → 已安装 Tab	查看版本与状态
禁用/启用	`/plugin disable <name>`	暂时停用但不卸载
卸载	`/plugin uninstall <name>`	完全移除
更新单个	`/plugin update <name>`	升级到最新版本
更新市场	`/plugin marketplace update <name>`	刷新插件列表
配置文件	`.claude/settings.json`	手动编辑项目级配置

自动更新配置

可通过环境变量控制更新行为：

禁用所有自动更新：

export DISABLE_AUTOUPDATER=true

仅保留插件更新，禁用 CLI 更新：

export FORCE_AUTOUPDATE_PLUGINS=true

五、开发者指南：创建自己的插件

5.1 标准目录结构

创建一个文件夹，结构如下：

my-awesome-plugin/
├── .claude-plugin/ # 元数据目录
│ └── plugin.json # 插件清单（必需）
├── skills/ # 技能命令
│ └── greet/
│ └── SKILL.md
├── agents/ # 子代理
│ └── security-reviewer.md
├── hooks/ # 钩子配置
│ └── hooks.json
├── .mcp.json # MCP 服务器定义
├── .lsp.json # LSP 服务器配置
└── scripts/ # 可执行脚本
 └── format.sh

5.2 编写 plugin.json

{
 "name": "my-awesome-plugin",
 "version": "1.0.0",
 "description": "我的第一个插件",
 "author": { "name": "Your Name", "email": "you@example.com" },
 "license": "MIT",
 "skills": "./skills/",
 "agents": "./agents/",
 "hooks": "./hooks/hooks.json"
}

5.3 创建 Skill 示例

skills/greet/SKILL.md:

---
description: 向用户问好
---
你好！我是你的专属助手，今天有什么可以帮你的吗？

5.4 配置 Hooks 示例

hooks/hooks.json (实现保存后自动格式化):

{
 "hooks": {
 "PostToolUse": [
 {
 "matcher": "Write|Edit",
 "hooks": [
 {
 "type": "command",
 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
 }
 ]
 }
 ]
 }
}

5.5 本地调试与测试

无需发布即可测试插件：

指定插件目录启动：

claude --plugin-dir ./my-awesome-plugin

调试模式查看加载详情：

claude --debug

进入会话后输入 /my-awesome-plugin:greet 验证功能。

5.6 发布到市场

将代码上传至 GitHub 公共仓库。
创建 marketplace.json 索引文件。
通过 Claude.ai 设置 → Plugins → Submit 提交至官方市场，或分享给团队直接使用 Git URL 安装。

六、故障排除 (Troubleshooting)

问题现象	可能原因	解决方案
`/plugin` 命令不识别	版本过低	升级 CLI：`curl -fsSL https://claude.ai/install.sh
插件未加载	缓存问题	删除缓存：`rm -rf ~/.claude/plugins/cache` 后重启
命令未出现	目录结构错误	确保 `skills/` 或 `commands/` 在插件根目录
Hooks 未触发	脚本无权限	运行 `chmod +x scripts/*.sh`
LSP 报错	语言服务器缺失	安装对应二进制（如 `npm i -g typescript-language-server`）
安装失败	网络/权限问题	检查 GitHub 仓库是否公开，或切换网络环境
命令冲突	命名空间重复	使用完整命名空间 `/plugin-name:cmd` 调用

七、最佳实践与建议

版本管理：遵循语义版本控制（MAJOR.MINOR.PATCH），便于回滚。
团队共享：使用 --scope project 将插件配置提交到 .claude/settings.json，确保团队成员环境一致。
安全优先：安装第三方插件前，检查其 plugin.json 和脚本内容，确认来源可信。
路径规范：插件内部所有路径必须相对于插件根目录，以 ./ 开头，或使用 ${CLAUDE_PLUGIN_ROOT} 变量。
结合规范：在项目根目录放置 CLAUDE.md 定义编码规范，插件会自动遵守。

八、官方资源

官方文档 (中文)： https://code.claude.com/docs/zh-CN/
插件开发文档： https://code.claude.com/docs/zh-CN/plugins
官方演示仓库： https://github.com/anthropics/claude-code
社区讨论：Claude 官方 Discord 频道

掌握插件系统后，Claude Code 的生产力将显著提升。通过团队统一安装核心插件（如 LSP、Commit、Security），可实现「一键 PR 审查 + 自动部署 + 安全扫描」的现代化开发全流程。

codex

codex 官方

安装和配置

｀安装｀

npm i -g @openai/codex

｀配置｀

设置默认agent full模式

设置$env:PYTHONUTF8 = “1”

不设置的话会出现乱码,因为python代码默认是utf8但是命令行默认是ascii

cursor使用教程

Wed, 04 Jun 2025 10:16:56 +0800

参考：

cursor1.0版本来袭 cursor二次大项目开发

agent开发技巧

1.先让AI熟悉代码，生成项目文档

请分析整个代码库，生成一份项目结构文档，包括：
1. 项目架构概览
2. 主要目录结构及其职责
3. 关键模块的依赖关系图
4. 核心类和接口的功能说明
5. 数据流向图
6. API接口清单
7. 常见的代码模式和约定

2.一个chat只开发一个功能

我现在要开发一个新功能：给商品添加批量导入功能。
以下是项目的结构文档，请先阅读以熟悉代码库：

[粘贴前面生成的项目文档]

功能开发后总结成Guide文档

请总结一下我们刚才添加新接口的过程，生成一个"如何添加新接口"的指南文档，包括：
1. 需要修改哪些文件
2. 代码结构和注意事项
3. 测试方法
4. 潜在的坑和解决方案

持续维护和更新文档

我们刚才解决了权限系统的几个问题，请将以下内容更新到权限系统指南文档中：
1. 修改角色权限时需要同步更新缓存
2. 权限检查顺序应该是：特殊权限 -> 角色权限 -> 默认权限
3. 前端权限组件需要处理异步加载状态

Tavily-搜索引擎api

Tue, 20 May 2025 15:34:00 +0800

Tavily API Python SDK 详细使用教程

Tavily API 旨在为 AI 应用和开发者提供一个强大、快速且相关的搜索引擎。它可以直接返回针对查询的总结性答案，并附带相关的源信息。本教程将引导你完成 Tavily Python SDK 的安装和使用。

简介
安装
API 密钥设置
- 环境变量（推荐）
- 直接在代码中设置
基本搜索
search 方法详解
- 常用参数
- 示例：使用不同参数
理解返回结果
- 整体响应结构
- 结果条目 (results) 结构
高级搜索功能 (基于 search 方法的参数组合)
- 获取特定主题信息
- 结合 include_domains 和 exclude_domains
错误处理
完整示例代码
使用技巧

1. 简介

Tavily API 通过其 Python SDK tavily-python，可以轻松集成到你的 Python 项目中。它不仅返回传统的搜索结果列表，还能提供一个由 AI 生成的、针对用户查询的直接答案，这对于构建 RAG (Retrieval Augmented Generation) 系统或需要快速获取信息的 AI 应用非常有用。

2. 安装

你可以使用 pip 来安装 Tavily Python SDK：

pip install tavily-python

3. API 密钥设置

要使用 Tavily API，你需要一个 API 密钥。你可以从 Tavily AI 官网注册并获取。

获取密钥后，有两种主要方式进行设置：

环境变量（推荐）

将 API 密钥设置为环境变量 TAVILY_API_KEY。SDK 会自动检测并使用它。

Linux/macOS:
```
export TAVILY_API_KEY="你的API密钥"
```
为了永久生效，可以将这行代码添加到你的 .bashrc, .zshrc 或其他 shell 配置文件中。
Windows: 在系统环境变量中添加一个新变量，名称为 TAVILY_API_KEY，值为你的 API 密钥。或者在 PowerShell 中：
```
$env:TAVILY_API_KEY="你的API密钥"
```

直接在代码中设置

你也可以在初始化 TavilyClient 时直接传入 API 密钥：

from tavily import TavilyClient

tavily_client = TavilyClient(api_key="你的API密钥")

如果同时设置了环境变量并显式传入密钥，则代码中显式传入的密钥会优先使用。

4. 基本搜索

进行一次基本搜索非常简单：

from tavily import TavilyClient

# 假设 TAVILY_API_KEY 环境变量已设置
# 如果没有设置环境变量，则使用: client = TavilyClient(api_key="YOUR_API_KEY")
client = TavilyClient()

try:
 response = client.search(query="2024年人工智能的最新进展是什么？")

 # 打印总结性答案 (如果请求并获得)
 if "answer" in response and response["answer"]:
 print("总结性回答:")
 print(response["answer"])
 print("-" * 30)

 # 打印搜索结果
 if "results" in response and response["results"]:
 print("\n搜索结果:")
 for result in response["results"]:
 print(f"标题: {result['title']}")
 print(f"链接: {result['url']}")
 print(f"内容摘要: {result['content'][:200]}...") # 打印内容的前200个字符
 print("-" * 20)

except Exception as e:
 print(f"搜索过程中发生错误: {e}")

5. `search` 方法详解

TavilyClient.search() 是核心方法，它接受多个参数来定制你的搜索请求。

常用参数

query (str, 必需): 你的搜索查询语句。
search_depth (str, 可选): 搜索深度。
- "basic": 速度更快，结果可能不那么全面。适用于需要快速获取初步信息的场景。（默认值）
- "advanced": 进行更深入的搜索，可能会检索更多信息并进行更复杂的分析，结果更全面，但耗时和消耗的信用点数可能更多。
include_answer (bool, 可选): 是否在结果中包含一个由 AI 生成的总结性答案。默认为 False（但通常建议设为 True 以充分利用 Tavily 的特性）。
include_raw_content (bool, 可选): 是否在每个搜索结果中包含原始的、未经处理的网页文本内容。默认为 False。如果为 True，结果中的 raw_content 字段将被填充。
max_results (int, 可选): 返回的最大搜索结果数量。默认通常是 5 个左右。你可以根据需要调整。
time_range （[none,‘day’,‘week’,‘month’,‘year’],可选），默认是none
include_domains (list[str], 可选): 一个域名列表。Tavily 会尝试优先从这些域名中查找结果。例如：["wikipedia.org", "github.com"]。
exclude_domains (list[str], 可选): 一个域名列表。Tavily 会尝试排除这些域名中的结果。例如：["pinterest.com"]。
topic (str, 可选): 指定搜索的主题领域，帮助Tavily更好地聚焦结果。可选值包括 (但不限于，具体请参考Tavily官方文档是否有更新)：
- "general" (默认)
- "news"
- "finance"
- "tech"
- "academic" (或 "research_paper") - 尤其适合查找学术论文
- "code" - 专注于代码相关的结果
- 注意：topic 的具体可用值和效果可能会随 API 更新而变化，请查阅最新的 Tavily 文档。

示例：使用不同参数

from tavily import TavilyClient

client = TavilyClient() # 假设API密钥已通过环境变量设置

try:
 # 示例 1: 高级搜索，包含答案和原始内容，限定结果数量
 response_advanced = client.search(
 query="什么是量子计算及其潜在应用？",
 search_depth="advanced",
 include_answer=True,
 include_raw_content=True,
 max_results=3
 )
 print("\n--- 高级搜索示例 ---")
 if response_advanced.get("answer"):
 print(f"AI 回答: {response_advanced['answer']}")
 for res in response_advanced.get("results", []):
 print(f" 标题: {res['title']}")
 print(f" 链接: {res['url']}")
 if res.get("raw_content"):
 print(f" 原始内容片段: {res['raw_content'][:100]}...") # 截取前100字符

 # 示例 2: 搜索特定主题（例如，新闻）并指定域名
 response_news = client.search(
 query="最新的AI芯片发布",
 topic="news", # 或 "tech"
 include_domains=["theverge.com", "techcrunch.com"],
 max_results=2,
 include_answer=True
 )
 print("\n--- 新闻主题与域名限定搜索示例 ---")
 if response_news.get("answer"):
 print(f"AI 回答: {response_news['answer']}")
 for res in response_news.get("results", []):
 print(f" 标题: {res['title']}")
 print(f" 链接: {res['url']}")

except Exception as e:
 print(f"发生错误: {e}")

6. 理解返回结果

Tavily API 的 search 方法返回一个 JSON 对象 (在 Python SDK 中是字典)。

整体响应结构

一个典型的响应字典可能包含以下键：

query (str): 你原始的搜索查询。
answer (str, 可选): 如果 include_answer=True 并且 API 能够生成一个总结性答案，这里会包含该答案。
results (list[dict]): 一个包含搜索结果条目的列表。每个条目都是一个字典。
images (list[str], 可选): 如果搜索与图片相关且Tavily找到图片，可能会包含图片URL列表 (较少见于主要文本搜索场景，更多特定于图片搜索功能，如果Tavily支持)。
response_time (float, 可选): API 处理请求所用的时间（秒）。
error (str, 可选): 如果发生错误，这里可能包含错误信息。

结果条目 (`results`) 结构

results 列表中的每个字典代表一个搜索结果，通常包含：

title (str): 搜索结果的标题。
url (str): 结果的来源 URL。
content (str): Tavily 提取或生成的与查询相关的该页面的内容摘要或片段。这是非常有用的字段，通常比传统的搜索引擎片段更丰富。
score (float, 可选): 一个表示结果与查询相关性的分数。分数越高，相关性越强。
raw_content (str, 可选): 如果请求了 include_raw_content=True 并且 Tavily 成功提取，这里会包含来自源 URL 的原始（或接近原始）文本内容。

7. 高级搜索功能 (基于 `search` 方法的参数组合)

通过组合 search 方法的不同参数，可以实现更高级的搜索策略。

获取特定主题信息

使用 topic 参数可以帮助Tavily更好地理解你的意图并返回更相关的结果。

response = client.search(
 query="最新的Python异步编程库有哪些？",
 topic="code", # 或者 "tech"
 include_answer=True,
 max_results=5
)
# 处理 response...

结合 `include_domains` 和 `exclude_domains`

这对于从特定权威来源获取信息或排除已知低质量来源非常有用。

response = client.search(
 query="气候变化对农业的影响 site:gov OR site:edu", # 也可以在query中使用高级搜索操作符
 search_depth="advanced",
 include_domains=["nasa.gov", "epa.gov", "nature.com"], # 进一步强调优先域名
 exclude_domains=["personalblog.com"], # 排除不想要的域名
 include_answer=True,
 max_results=5
)
# 处理 response...

注意: site: 操作符在 query 字符串中是许多搜索引擎支持的标准语法，Tavily 也可能支持。与 include_domains 结合使用可以增强效果。

8. 错误处理

在使用 API 时，进行适当的错误处理非常重要。Tavily SDK 可能会因为网络问题、无效的 API 密钥、请求超限等原因抛出异常。

from tavily import TavilyClient
from tavily.errors import TavilyApiError # 可以捕获特定的Tavily错误

client = TavilyClient()

try:
 response = client.search(query="一个可能会失败的查询")
 # ...处理响应...
except TavilyApiError as e:
 print(f"Tavily API 错误: {e}")
 # 例如，处理API密钥无效、超出配额等特定错误
except requests.exceptions.RequestException as e: # requests库是底层依赖
 print(f"网络请求错误: {e}")
except Exception as e:
 print(f"发生了未知错误: {e}")

9. 完整示例代码

下面是一个结合了多个特性的完整示例：

import os
from tavily import TavilyClient
from tavily.errors import TavilyApiError
import json # 用于美化打印JSON

def perform_tavily_search(query_text, num_results=3, depth="basic", include_ans=True, include_raw=False):
 """
 执行 Tavily 搜索并打印结果。
 """
 try:
 # 推荐从环境变量获取 API 密钥
 # api_key = os.getenv("TAVILY_API_KEY")
 # if not api_key:
 # print("错误: TAVILY_API_KEY 环境变量未设置。")
 # return
 # client = TavilyClient(api_key=api_key)

 # 或者，如果你在脚本开头设置了全局的 client 实例：
 client = TavilyClient() # 确保API密钥已通过某种方式提供

 print(f"\n正在搜索 (深度: {depth}, 结果数: {num_results}): '{query_text}'")

 response_data = client.search(
 query=query_text,
 search_depth=depth,
 include_answer=include_ans,
 include_raw_content=include_raw,
 max_results=num_results
 )

 print("\n--- API 响应 (JSON 格式) ---")
 print(json.dumps(response_data, indent=2, ensure_ascii=False)) # 美化打印

 if response_data.get("answer"):
 print(f"\n--- 总结性回答 ---")
 print(response_data["answer"])

 print(f"\n--- 搜索结果 ({len(response_data.get('results', []))} 条) ---")
 for i, result in enumerate(response_data.get("results", [])):
 print(f"\n结果 {i+1}:")
 print(f" 标题: {result.get('title', 'N/A')}")
 print(f" URL: {result.get('url', 'N/A')}")
 print(f" Tavily 内容摘要:\n {result.get('content', 'N/A')[:300]}...") # 摘要的前300字符
 if result.get("raw_content"):
 print(f" 原始页面内容 (片段):\n {result['raw_content'][:200]}...") # 原始内容的前200字符
 print(f" 相关性分数: {result.get('score', 'N/A')}")

 print("\n" + "="*50)

 except TavilyApiError as e:
 print(f"Tavily API 错误: {e}")
 except Exception as e:
 print(f"执行搜索时发生意外错误: {e}")

if __name__ == "__main__":
 # 确保你已经设置了 TAVILY_API_KEY 环境变量，或者在 TavilyClient() 中直接提供
 # 例如: TavilyClient(api_key="YOUR_TAVILY_API_KEY")

 if not os.getenv("TAVILY_API_KEY") and "YOUR_TAVILY_API_KEY" == "YOUR_TAVILY_API_KEY": # 检查是否已设置
 print("请设置 TAVILY_API_KEY 环境变量或在代码中直接提供 API 密钥。")
 else:
 perform_tavily_search(
 query_text="Python在数据科学中的应用",
 num_results=3,
 depth="basic",
 include_ans=True
 )

 perform_tavily_search(
 query_text="解释一下Transformer模型的工作原理",
 num_results=2,
 depth="advanced",
 include_ans=True,
 include_raw=True # 请求原始文本内容
 )

 perform_tavily_search(
 query_text="最新发布的宇宙学研究论文",
 num_results=4,
 topic="academic", # 尝试使用主题参数
 depth="advanced",
 include_ans=True
 )

10. 使用技巧

明确的查询: 查询语句越明确，Tavily 返回的结果就越相关。
利用 search_depth: 对于快速概览，"basic" 可能足够；对于需要深入信息的研究，"advanced" 更佳。
include_answer: 这个参数是 Tavily 的核心优势之一，尽量使用它来获取直接的答案。
include_raw_content 与自定义抓取: 如果 include_raw_content=True 能满足需求，可以减少你自己编写网页抓取逻辑的需要。但如果需要非常特定的元素或有复杂的网站结构，你可能仍需要结合你自己的抓取工具（如教程开头提到的 get_page_content 函数）。
迭代和优化: 根据返回结果调整你的查询和参数，以获得最佳效果。
查阅官方文档: API 和 SDK 可能会更新，定期查阅 Tavily 官方文档以获取最新信息、参数和最佳实践。
管理信用点数: 注意不同类型的查询（特别是 search_depth="advanced" 或请求大量结果）可能会消耗不同的信用点数。

希望这篇教程能帮助你有效地使用 Tavily API Python SDK！

tmux简易使用

Fri, 09 May 2025 11:32:28 +0800

安装

macOS

# 用 Homebrew（推荐）
brew install tmux

# 用 MacPorts
sudo port install tmux

Ubuntu / Debian

sudo apt update
sudo apt install tmux

Ubuntu 自带的 tmux 版本通常较老（1.8），功能受限。需要新版（如 3.x 的 true color 支持等）可以加 PPA：
sudo add-apt-repository ppa:tmux-stable/ppa
sudo apt update
sudo apt install tmux

Windows

Windows 原生没有 tmux，常见方案：

WSL（推荐）：在 WSL（Ubuntu 等发行版）里 sudo apt install tmux，然后通过 Windows Terminal 使用。
MSYS2：自带包管理器：
```
pacman -S tmux
```
不愿用 Linux 子系统的话，可考虑 Windows Terminal 自带的 panes/tabs 作为替代。

验证安装

tmux -V

输出形如 tmux 3.4 即安装成功。

什么是 tmux

tmux（Terminal Multiplexer）是一个终端复用器。它允许你在一个终端窗口里运行多个会话（session），每个会话里又能打开多个窗口（window）和窗格（pane）。最实用的好处是：关闭 SSH 连接或终端窗口后，tmux 会话里的程序仍在后台运行，下次可以原样恢复。

为什么用 tmux

会话持久化：远程服务器上跑长任务，断开 SSH 也不会中断。
一屏多用：把屏幕拆成多个窗格，同时看日志、跑测试、编辑代码。
环境快速恢复：一套窗口/窗格布局保存后，下次一键还原。
协作/演示：多人 attach 到同一会话，方便结对调试。

常用命令速查

最常用的几条命令，记住它们就能应付日常 80% 的场景：

# 创建并进入会话
tmux new -s mysession

# 列出所有会话
tmux ls

# 重新进入会话
tmux attach -t mysession

# 临时退出会话（后台运行）
# 快捷键：Ctrl-b 松开后按 d

# 重命名当前会话
tmux rename-session 新名字

# 重命名指定会话
tmux rename-session -t 旧名字 新名字

# 彻底关闭某个会话
tmux kill-session -t mysession

快捷键速记：

快捷键	作用
`Ctrl-b d`	退出会话（ detach，程序继续在后台跑）
`Ctrl-b $`	重命名当前会话
`Ctrl-b c`	新建窗口
`Ctrl-b n` / `Ctrl-b p`	下一个 / 上一个窗口
`Ctrl-b %`	垂直分屏
`Ctrl-b "`	水平分屏
`Ctrl-b o`	切换到下一个窗格
`Ctrl-b x`	关闭当前窗格

基础概念

概念	说明
会话（session）	最高级容器，通常对应一个完整的工作场景，例如“前端开发”“服务器运维”。
窗口（window）	会话内的标签页，类似浏览器标签。
窗格（pane）	窗口内的分屏区域，一个窗口可分成多个窗格。

默认**前缀键（prefix）**是 Ctrl-b，所有快捷键都要先按 prefix，松开后按功能键。

会话管理

# 创建无名称会话
tmux

# 创建带名称的会话
tmux new -s mysession

# 在创建时直接执行命令（命令结束会话不关闭）
tmux new -s build -d "npm run build"

# 列出所有会话
tmux ls

# 附加到已有会话
tmux attach -t mysession
# 简写
tmux a -t mysession

# 从外部重命名会话
tmux rename-session -t oldname newname

# 分离当前会话（后台运行，不关闭）
# 快捷键：prefix + d
tmux detach

# 杀死指定会话
tmux kill-session -t mysession

# 杀死所有会话
tmux kill-server

会话快捷键

快捷键	作用
`prefix d`	分离当前会话
`prefix $`	重命名当前会话
`prefix s`	列出所有会话，用方向键选择切换
`prefix (`	切换到上一个会话
`prefix )`	切换到下一个会话

窗口管理

快捷键	作用
`prefix c`	新建窗口
`prefix ,`	重命名当前窗口
`prefix n`	切换到下一窗口
`prefix p`	切换到上一窗口
`prefix 0~9`	切换到对应编号窗口
`prefix w`	可视化选择窗口
`prefix &`	关闭当前窗口
`prefix .`	修改当前窗口编号

命令行操作：

# 创建窗口
tmux new-window -t mysession -n "logs"

# 关闭窗口
tmux kill-window -t mysession:1

窗格管理

快捷键	作用
`prefix %`	垂直分割窗格
`prefix "`	水平分割窗格
`prefix o`	切换到下一个窗格
`prefix 方向键`	切换到对应方向窗格
`prefix x`	关闭当前窗格
`prefix z`	最大化/还原当前窗格
`prefix 空格`	切换窗格布局
`prefix {` / `prefix }`	移动当前窗格位置
`prefix !`	把当前窗格拆成独立窗口

调整窗格大小：

快捷键	作用
`prefix Ctrl+方向键`	以 1 格为单位调整
`prefix Alt+方向键`	以 5 格为单位调整

复制模式

tmux 自带复制/滚动模式，方便查看历史输出。

快捷键	作用
`prefix [`	进入复制模式
`prefix ]`	粘贴缓冲区内容
`prefix =`	列出粘贴历史

复制模式下常用操作：

按键	作用
`Ctrl-c` / `q`	退出复制模式
`Ctrl-f` / `Ctrl-b`	向下/向上翻页
`/`	向下搜索
`?`	向上搜索
`v`	开始选区（vi 模式下）
`y`	复制选区（vi 模式下）

让 tmux 使用 vi 风格键位：

# ~/.tmux.conf
setw -g mode-keys vi

常用配置

创建或编辑 ~/.tmux.conf：

# 重新加载配置的快捷键
bind r source-file ~/.tmux.conf \; display-message "Config reloaded!"

# 启用鼠标支持（滚轮、拖拽调整窗格、点击选择窗格）
set -g mouse on

# 把前缀键改成 Ctrl-a（更接近 GNU Screen 习惯）
unbind C-b
set -g prefix C-a
bind C-a send-prefix

# 使用 vi 风格复制模式
setw -g mode-keys vi

# 窗口编号从 1 开始
set -g base-index 1
setw -g pane-base-index 1

# 重新编号窗口（删除中间窗口后自动补齐）
set -g renumber-windows on

# 状态栏显示时间
set -g status-right '%Y-%m-%d %H:%M'

# 窗格边框颜色
set -g pane-border-style fg=colour240
set -g pane-active-border-style fg=colour33

配置修改后，可以在 tmux 里按 prefix r 重新加载，或执行：

tmux source-file ~/.tmux.conf

插件	作用
`tmux-sensible`	一组合理的默认配置
`tmux-resurrect`	保存和恢复会话、窗口、窗格布局及运行程序
`tmux-continuum`	自动定时保存，开机后自动恢复
`tmux-yank`	把 tmux 选区复制到系统剪贴板
`tmux-prefix-highlight`	在状态栏高亮显示前缀键状态

实用工作流示例

1. 远程跑长任务

ssh server
tmux new -s training
# 在会话里执行训练脚本
python train.py
# 按 prefix d 分离，关闭 SSH 即可

下次恢复：

ssh server
tmux attach -t training

2. 本地开发多面板

tmux new -s dev

然后按 prefix % 把窗口分成左右两部分：左边跑编辑器/服务器，右边跑测试或日志。

3. 快速保存与恢复环境

安装 tmux-resurrect 后：

快捷键	作用
`prefix Ctrl-s`	保存当前环境
`prefix Ctrl-r`	恢复保存的环境

进阶技巧

1. 同步输入到所有窗格

需要在多台机器或同一组窗口里执行相同命令时，可以打开输入同步：

# 在 tmux 命令行执行
setw synchronize-panes on

快捷键绑定（加入 ~/.tmux.conf）：

bind S setw synchronize-panes \; display-message "Sync panes: #{?synchronize-panes,ON,OFF}"

然后按 prefix S 即可切换同步状态。再次关闭：setw synchronize-panes off。

2. 用脚本一键搭建开发环境

把常用布局写成脚本，避免每次手动分屏：

#!/bin/bash
# start-dev.sh
SESSION="dev"

tmux has-session -t $SESSION 2>/dev/null
if [ $? != 0 ]; then
 tmux new-session -d -s $SESSION -n editor
 tmux send-keys -t $SESSION:editor 'vim .' C-m
 tmux split-window -h -t $SESSION:editor
 tmux send-keys -t $SESSION:editor.right 'npm run dev' C-m
 tmux split-window -v -t $SESSION:editor.right
 tmux send-keys -t $SESSION:editor.bottom 'git status' C-m
fi

tmux attach -t $SESSION

3. 嵌套 tmux（本地 + 远程）

如果你本地开了 tmux，SSH 到远程服务器后又开了 tmux，两个 Ctrl-b 会冲突。常见解决办法：

本地用 Ctrl-b，远程用 Ctrl-a：

# 远程服务器的 ~/.tmux.conf
set -g prefix C-a
unbind C-b
bind C-a send-prefix

或者在本地 tmux 里按 Ctrl-b b，把 prefix 透传给远程 tmux。

4. 查看并重新连接 detached 的会话

# 列出 detached 的会话
tmux ls

# 如果只有一个 detached 会话，直接 attach
tmux attach

5. 调整颜色与终端兼容

如果 vim/neovim 在 tmux 里颜色显示异常，加这几行：

# ~/.tmux.conf
set -g default-terminal "screen-256color"
set -ag terminal-overrides ",xterm-256color:RGB"

并确保外部终端也支持 256 色 / true color。

命令速查表

# 会话
tmux new -s <name> # 新建会话
tmux ls # 列出会话
tmux attach -t <name> # 接入会话
tmux detach # 退出当前会话（后台运行）
tmux rename-session -t <old> <new> # 重命名会话
tmux kill-session -t <name> # 结束会话
tmux kill-server # 结束所有会话

# 窗口（在 tmux 内）
prefix c # 新建窗口
prefix , # 重命名窗口
prefix n # 下一个窗口
prefix p # 上一个窗口
prefix w # 可视化选择窗口
prefix 0-9 # 切换到对应编号窗口
prefix & # 关闭窗口

# 窗格（在 tmux 内）
prefix % # 垂直分割
prefix " # 水平分割
prefix o # 切换窗格
prefix 方向键 # 按方向切换窗格
prefix x # 关闭窗格
prefix z # 最大化/还原窗格
prefix 空格 # 切换窗格布局
prefix ! # 把当前窗格拆成独立窗口

# 复制模式
prefix [ # 进入复制/滚动模式
prefix ] # 粘贴

常见问题

问题	原因 / 解决
滚轮不能翻历史	按 `prefix [` 进入复制模式后再滚；或开启 `set -g mouse on`。
`Ctrl-b` 没反应	先松开 `Ctrl-b` 再按功能键；或者 prefix 被改成了 `Ctrl-a`。
中文显示乱码	检查终端编码为 UTF-8，并在 `~/.tmux.conf` 里加 `setw -g utf8 on`（较新版本已默认支持）。
vim 里按 ESC 有延迟	加 `set -sg escape-time 10` 到 `~/.tmux.conf`。
关闭终端后程序被杀死	确保程序是跑在 tmux 会话里，并且你是按 `prefix d` 分离，而不是直接关窗口。
状态栏不显示	确认配置文件没有语法错误，执行 `tmux source-file ~/.tmux.conf` 查看报错。

小贴士

先松 prefix 再按功能键：例如 Ctrl-b 松开后按 c。
善用 prefix ?：随时查看所有快捷键列表。
调整终端大小后，tmux 会自动适配；如果显示异常，可以按 prefix r 刷新。
tmux 默认不共享系统剪贴板，需要 tmux-yank 或配合 xclip/pbcopy 等工具。
鼠标支持开启后，可以像普通终端一样滚屏、拖拽调整窗格大小，适合新手过渡。

生成api文档工具的简易使用

Sat, 03 May 2025 10:42:53 +0800

api文档的必要性

虽然我一直在写python项目，也并没有前后端的区别，但是随着项目越变越大，越发感觉没有api文档，对于我的回顾来说是非常麻烦的，因此还是需要一个用于生成api的python插件或者说一个用于书写api文档的在线或离线工具，之前是有用过Sphinx来自动生成api文档，但是感觉存在使用太麻烦的问题，如果是小项目，可能配置都感觉很麻烦，书写格式，似乎有md格式可以使用，但是我还没有去尝试，使用了它默认的格式，头都昏了

那些api文档工具可以使用

我只是做了简单的了解，太具体的深度还没有做。

Sphinx 也就是我上面说到了，我只使用了python版本的，感觉并不是特别好用的
MkDocs 这个是一个比较新的框架，也是比较现代的版本
fastopenapi 这个是专门用于生成fastapi后端的项目项目地址

具体工具使用

Sphinx

以我的fainigleam项目为例

mkdir docs && cd docs

sphinx-quickstart # 第一个选y，后面看着填

vim source/conf.py # 具体怎么改看下面

vim source/index.rst # 具体怎么改看下面

sphinx-apidoc -o ./source ../src

make html

创建docs文件夹，并cd进去

2.sphinx-quickstart

3.修改 source/conf.py文件

# conf.py
import os
import sys
sys.path.insert(0, os.path.abspath('../../')) # 添加项目根目录到路径
sys.path.insert(0, os.path.abspath('../../src/')) # 添加src目录到路径


#######################################
project = 'XXXXX'
copyright = 'XXXXXX'
author = 'XXXXX'
release = 'X.X.X'
#######################################


extensions = [
 'sphinx.ext.autodoc', # 自动从docstrings生成文档
 'sphinx.ext.viewcode', # 添加查看源码的链接
 'sphinx.ext.napoleon', # 支持Google风格的文档字符串
]

# 配置autodoc扩展
autodoc_member_order = 'bysource' # 按源码顺序记录成员
add_module_names = False # 不在API文档中添加模块名

templates_path = ['_templates']
exclude_patterns = []

language = 'zh'


html_theme = 'sphinx_rtd_theme' # 使用ReadTheDocs主题
html_static_path = ['_static']

修改 source/index.rst文件

########################################################
fainitgleam documentation
=============
.. toctree::
 :maxdepth: 2
 :caption: Contents:
#########################################################

# 前面都不变的，就这里增加一个modules
 modules

执行
```
sphinx-apidoc -o ./source ../src
```
make html

7.就可以打开静态页面查看了

MkDocs

在为Python项目选择一个可以长期使用的文档工具时，我们追求的是易用性、专业外观和强大功能的最佳平衡。综合考量，2025年的最佳选择是 MkDocs 配合 Material for MkDocs 主题及 mkdocstrings 插件。这个组合将成为你未来所有项目的首选。

为什么是这个组合？

现代且极其易用：你只需使用最熟悉的 Markdown 语言来编写文档，几乎没有学习成本。通过mkdocs serve命令即可开启实时预览，大大提升了编写效率和体验。
专业且外观精美：Material for MkDocs 是一个功能极其强大的主题，能让你用最简单的配置，生成世界级的、响应式的现代化文档网站。内置搜索、深/浅色模式切换、代码高亮等功能一应俱全。
功能强大，足以应对未来需求：通过 mkdocstrings 插件，它可以直接读取你代码中的文档字符串（docstrings），自动生成清晰、美观的API参考文档，完美解决了API文档的需求。

简单来说，这个组合让你用最简单的方式，获得专业级的输出，是兼顾了现在与未来的理想选择。

快速上手指南

只需四步，即可搭建并运行你的专业文档网站。

1. 安装必要的库

在你的终端中运行以下命令：

uv install mkdocs mkdocs-material mkdocstrings-python

2. 创建新项目 （如果还没有软件项目）

mkdocs new my-project
cd my-project

如果已有软件项目

# 创建 docs 文件夹，用于存放所有 .md 文档文件
mkdir docs

# 创建 mkdocs.yml 配置文件，它将位于项目根目录
touch mkdocs.yml

# 创建一个首页文档
touch docs/index.md

这会创建一个名为 my-project 的新目录，包含一个基础的 mkdocs.yml 配置文件和一个 docs 目录（用于存放你的Markdown文档）。

3. 配置 mkdocs.yml 文件

这是最关键的一步。用以下内容替换 mkdocs.yml 文件的全部内容，这是一个包含了主题、API文档生成和中文支持的黄金配置：

# 网站名称
site_name: "我的项目名称"
site_description: "项目的简短描述"

# 主题配置
theme:
 name: material
 language: zh # 设置语言为中文
 features:
 - navigation.tabs # 导航栏使用标签页
 - navigation.sections # 左侧导航支持章节收起
 - content.code.copy # 代码块支持一键复制
 - content.code.annotate # 支持代码块注释
 - search.suggest # 搜索时提供建议
 - search.highlight # 高亮搜索结果
 palette: # 调色盘，用于实现深/浅色模式切换
 - scheme: default
 toggle:
 icon: material/brightness-7
 name: 切换到深色模式
 - scheme: slate
 toggle:
 icon: material/brightness-4
 name: 切换到浅色模式

# 插件配置
plugins:
 - search # 内置搜索插件
 - mkdocstrings: # API文档生成插件
 handlers:
 python: # 指定处理Python代码
 options:
 show_root_heading: true # 为模块显示一个顶层标题

# 导航栏配置
nav:
 - 首页: index.md
 - API 参考:
 - '模块A': 'api/module_a.md'
 - '模块B': 'api/module_b.md'
 - 指南:
 - '安装指南': 'guides/installation.md'

4. 编写内容并运行

在 docs/ 目录下创建和编辑你的 .md 文件。
例如，在 docs/api/module_a.md 文件中，你只需写入以下一行代码，mkdocstrings就会自动为你生成整个模块的API文档：
```
::: my_project.module_a
```
(请将 my_project.module_a 替换为你的实际Python模块路径)
在项目根目录下运行服务：
```
mkdocs serve
```

现在，打开浏览器访问 http://127.0.0.1:8000，即可看到你专业、美观且功能强大的文档网站。

其他选择（何时考虑？）

Sphinx：当你需要为一个极其庞大、复杂的传统开源库（如Python官方文档本身）构建文档，且需要PDF/ePub等多种输出格式时，可以考虑它。但请准备好应对其更陡峭的学习曲线（reStructuredText语法）。
pdoc：当你的需求仅仅是快速、零配置地从代码生成一个纯API参考页面，而不需要任何额外的教程或指南时，pdoc是一个轻量级的选择。

网页内容变化监控项目

Tue, 22 Apr 2025 22:21:15 +0800

项目名： checkchan-dist

Sphinx-快速生成python项目的api文档

Tue, 18 Mar 2025 00:16:22 +0800

# 初始化一个新的 Sphinx 项目
sphinx-quickstart

# 生成 HTML 文档
make html

# 清空构建目录
make clean

# 生成 PDF 文档（需要安装 LaTeX）
make latexpdf

# 生成单页 HTML 文档
make singlehtml

# 检查 reStructuredText 格式
make rst

# 启动本地服务器预览文档（需安装 sphinx-autobuild）
sphinx-autobuild source build/html

# 生成 API 文档（需配置 sphinx-apidoc）
sphinx-apidoc -o source/ <module_path>

# 构建并检查链接有效性
make linkcheck

下面是conf.py文件的参考配置，此外你还需要在index.rst文件的最后一行增加文字即modules

# conf.py 

import os
import sys
sys.path.insert(0, os.path.abspath('../../')) # 添加项目根目录到路径
sys.path.insert(0, os.path.abspath('../../src/')) # 添加src目录到路径


project = 'fainitgleam'
copyright = '2025, zata'
author = 'zata'
release = '1.3.0'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration


extensions = [
 'sphinx.ext.autodoc', # 自动从docstrings生成文档
 'sphinx.ext.viewcode', # 添加查看源码的链接
 'sphinx.ext.napoleon', # 支持Google风格的文档字符串
]

# 配置autodoc扩展
autodoc_member_order = 'bysource' # 按源码顺序记录成员
add_module_names = False # 不在API文档中添加模块名

templates_path = ['_templates']
exclude_patterns = []

language = 'zh'


html_theme = 'sphinx_rtd_theme' # 使用ReadTheDocs主题
html_static_path = ['_static']

Sphinx 使用教程

Sphinx 是一个功能强大的 Python 文档生成工具，广泛用于生成 Python 项目的技术文档、API 文档以及其他类型的文档。它支持 reStructuredText（reST）格式，并可以输出 HTML、PDF、ePub 等多种格式。本教程将详细介绍如何安装、配置和使用 Sphinx 生成专业文档。

1. 安装 Sphinx

1.1 前提条件

确保已安装 Python（建议使用 Python 3.6 或更高版本）。
安装 pip，Python 的包管理工具。

1.2 安装 Sphinx

在终端运行以下命令安装 Sphinx：

pip install sphinx

1.3 验证安装

安装完成后，检查 Sphinx 是否正确安装：

sphinx-build --version

输出类似 sphinx-build 4.x.x，表示安装成功。

1.4 可选：安装主题

Sphinx 默认主题较为简单，可以安装更现代化的主题，如 Read the Docs 风格的主题：

pip install sphinx-rtd-theme

2. 创建 Sphinx 项目

2.1 初始化项目

创建一个项目目录（例如 my-docs）：
```
mkdir my-docs
cd my-docs
```
运行 sphinx-quickstart 初始化 Sphinx 项目：
```
sphinx-quickstart
```
回答交互式问题：
- Separate source and build directories: 推荐选择 y，将源文件和构建输出分开。
- Project name: 输入项目名称，例如 My Project。
- Author name(s): 输入作者姓名。
- Project release: 输入版本号，例如 1.0。
- Language: 输入文档语言（默认 en，中文可输入 zh_CN）。

完成后，Sphinx 会生成以下文件结构：

my-docs/
├── build/ # 构建输出目录
├── source/ # 源文件目录
│ ├── conf.py # Sphinx 配置文件
│ ├── index.rst # 主文档文件
│ └── _static/ # 静态文件（如 CSS、图片）
│ └── _templates/ # 模板文件
└── Makefile # 用于 Linux/Mac 的构建脚本
└── make.bat # 用于 Windows 的构建脚本

3. 配置 Sphinx

3.1 编辑 `conf.py`

conf.py 是 Sphinx 的核心配置文件，位于 source/ 目录下。以下是一些常用配置项：

项目信息：

project = 'My Project'
author = 'Your Name'
release = '1.0'

语言设置（中文文档）：
```
language = 'zh_CN'
```
主题设置（使用 Read the Docs 主题）：
```
html_theme = 'sphinx_rtd_theme'
```
扩展启用： Sphinx 支持多种扩展，常用扩展包括：
- sphinx.ext.autodoc: 自动生成 Python 代码的 API 文档。
- sphinx.ext.napoleon: 支持 Google/Numpy 风格的文档字符串。
- sphinx.ext.viewcode: 显示源代码链接。
在 conf.py 中启用扩展：
```
extensions = [
 'sphinx.ext.autodoc',
 'sphinx.ext.napoleon',
 'sphinx.ext.viewcode',
]
```
静态文件路径：默认情况下，_static 和 _templates 路径已配置好，确保不要修改：
```
html_static_path = ['_static']
```

3.2 设置中文支持

如果文档使用中文，确保 language = 'zh_CN'，并安装支持中文的主题（如 sphinx-rtd-theme）。此外，推荐使用 UTF-8 编码保存所有 .rst 文件。

4. 编写文档

Sphinx 使用 reStructuredText（reST）作为默认标记语言，类似于 Markdown 但更适合技术文档。

4.1 编辑 `index.rst`

index.rst 是文档的入口文件。默认内容如下：

.. My Project documentation master file

Welcome to My Project's documentation!
=====================================

.. toctree::
 :maxdepth: 2
 :caption: Contents:

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

标题：使用 =、-、~ 等符号创建标题层级。
目录树（toctree）：使用 .. toctree:: 指令添加子页面，例如：
```
.. toctree::
 :maxdepth: 2
 :caption: Contents:

 intro
 api
```
这里 intro 和 api 对应 intro.rst 和 api.rst 文件。

4.2 创建新页面

在 source/ 目录下创建新的 .rst 文件，例如 intro.rst：

Introduction
============

This is the introduction to My Project.

.. note::
 This is a note directive to highlight important information.

将新文件添加到 index.rst 的 toctree 中。

4.3 常用 reST 语法

粗体/斜体：
```
**bold text** *italic text*
```

代码块：

.. code-block:: python

 def hello():
 print("Hello, Sphinx!")

链接：

`Sphinx 官网 <https://www.sphinx-doc.org>`_

列表：
```
- Item 1
- Item 2
 - Subitem
```

5. 生成文档

5.1 构建 HTML 文档

在项目根目录运行：

make html

输出文件将生成在 build/html/ 目录下。
打开 build/html/index.html 查看生成的文档。

5.2 清理构建

如果需要重新构建，清理旧输出：

make clean

5.3 其他格式

Sphinx 支持多种输出格式，例如 PDF（需要安装 latexmk 和 TeX 环境）：

make latexpdf

6. 自动生成 API 文档

如果你的项目包含 Python 代码，可以使用 sphinx.ext.autodoc 自动生成 API 文档。

6.1 配置 autodoc

确保 conf.py 已启用 sphinx.ext.autodoc 和 sphinx.ext.napoleon。

6.2 创建 Python 模块

假设你的项目有一个 Python 模块 my_module.py：

def greet(name):
 """Greet someone.

 Args:
 name (str): The name of the person to greet.

 Returns:
 str: A greeting message.
 """
 return f"Hello, {name}!"

6.3 生成 API 文档

创建 api.rst 文件：

API Documentation
=================

.. automodule:: my_module
 :members:
 :undoc-members:
 :show-inheritance:

将 api.rst 添加到 index.rst 的 toctree。
确保 my_module.py 在 Python 路径中，可以通过修改 conf.py 添加模块路径：
```
import os
import sys
sys.path.insert(0, os.path.abspath('../'))
```
重新构建文档：
```
make html
```

7. 发布文档

7.1 本地查看

直接打开 build/html/index.html 查看生成的文档。

7.2 托管到 Read the Docs

将项目推送到 GitHub/GitLab。
登录 Read the Docs，导入你的项目。

配置 Read the Docs 自动构建，需在项目根目录添加 .readthedocs.yml：

version: 2
build:
 os: ubuntu-22.04
 tools:
 python: "3.10"
python:
 install:
 - requirements: requirements.txt

在 requirements.txt 中列出依赖：
```
sphinx
sphinx-rtd-theme
```

7.3 其他托管方式

GitHub Pages：将 build/html/ 内容部署到 GitHub Pages。
Netlify：配置 Netlify 自动构建 make html。

8. 实用技巧

8.1 自定义主题

在 _static/ 目录下添加自定义 CSS 文件，并在 conf.py 中启用：

html_static_path = ['_static']
html_css_files = ['custom.css']

8.2 使用 Markdown

如果更习惯 Markdown，可以安装 myst-parser：

pip install myst-parser

在 conf.py 中启用：

extensions.append('myst_parser')

然后可以使用 .md 文件代替 .rst。

8.3 自动构建

使用 sphinx-autobuild 实现文档实时预览：

pip install sphinx-autobuild
sphinx-autobuild source/ build/html/

9. 常见问题

Q: 文档没有更新？ A: 运行 make clean 清理旧构建，然后重新运行 make html。
Q: 中文显示乱码？ A: 确保 language = 'zh_CN'，并使用支持中文的主题。
Q: 模块未找到？ A: 检查 sys.path 是否包含模块路径。

10. 进一步学习

官方文档：https://www.sphinx-doc.org
reStructuredText 入门：http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
Read the Docs 教程：https://docs.readthedocs.io

补充：使用 `sphinx-apidoc` 自动生成 API 文档

Sphinx 提供了 sphinx-apidoc 工具，可以自动扫描 Python 项目中的模块、类和函数，生成对应的 reStructuredText（reST）文档框架。以下是详细步骤：

1. 确保启用必要扩展

在 source/conf.py 中确保已启用以下扩展：

extensions = [
 'sphinx.ext.autodoc', # 自动提取文档字符串
 'sphinx.ext.napoleon', # 支持 Google/Numpy 风格文档字符串
 'sphinx.ext.viewcode', # 添加源代码链接
]

2. 项目结构示例

假设你的 Python 项目结构如下：

my-docs/
├── my_project/
│ ├── __init__.py
│ ├── module1.py
│ └── module2/
│ ├── __init__.py
│ └── submodule.py
├── source/
│ ├── conf.py
│ ├── index.rst
│ └── _static/
└── Makefile

其中 module1.py 包含以下代码：

def greet(name):
 """Greet someone.

 Args:
 name (str): The name of the person to greet.

 Returns:
 str: A greeting message.
 """
 return f"Hello, {name}!"

3. 运行 `sphinx-apidoc`

在项目根目录（my-docs/）运行以下命令：

sphinx-apidoc -o source/ my_project/

参数说明：

-o source/: 指定生成的 .rst 文件输出到 source/ 目录。
my_project/: 要扫描的 Python 模块或包的路径。
可选参数：
- -f: 强制覆盖已存在的 .rst 文件。
- -M: 将模块文档放在子模块之前（默认子模块优先）。
- -e: 为每个模块生成单独的页面。
- --private: 包含私有成员（以 _ 开头的成员）。
- --no-toc: 不生成目录树文件（modules.rst）。

示例命令（强制覆盖并包含私有成员）：

sphinx-apidoc -f -e --private -o source/ my_project/

4. 检查生成的文件

运行后，source/ 目录下会生成类似以下文件：

source/
├── conf.py
├── index.rst
├── my_project.rst
├── my_project.module1.rst
├── my_project.module2.rst
├── my_project.module2.submodule.rst
└── modules.rst

my_project.rst 和 modules.rst 是模块的索引文件。
每个 .rst 文件对应一个模块，包含 .. automodule:: 指令，自动引用模块中的文档字符串。

5. 更新 `index.rst`

将生成的模块索引添加到 index.rst 的 toctree 中，例如：

.. toctree::
 :maxdepth: 2
 :caption: Contents:

 modules
 intro

这里 modules 指向 modules.rst，它会自动包含所有生成的 API 文档。

6. 配置 Python 路径

为了让 Sphinx 找到你的 Python 模块，需在 conf.py 中添加模块路径：

import os
import sys
sys.path.insert(0, os.path.abspath('../my_project'))

7. 构建文档

运行以下命令生成 HTML 文档：

make html

打开 build/html/index.html，你将看到自动生成的 API 文档，包含 module1.py 中 greet 函数的文档字符串。

8. 实用技巧

过滤成员：在 .rst 文件中，可以通过 :members:、:undoc-members:、:private-members: 等控制显示的成员。例如：
```
.. automodule:: my_project.module1
 :members:
 :private-members:
 :undoc-members:
 :show-inheritance:
```
忽略文件：如果不想为某些模块生成文档，可以在 sphinx-apidoc 命令后添加忽略路径：
```
sphinx-apidoc -o source/ my_project/ my_project/module2/*
```
自动化脚本：将 sphinx-apidoc 集成到构建流程中，例如在 Makefile 中添加：
```
apidoc:
 sphinx-apidoc -f -o source/ my_project/
```
然后运行 make apidoc && make html。

9. 注意事项

文档字符串：确保你的 Python 代码中有清晰的文档字符串（docstring），否则生成的文档会缺少内容。
模块路径：如果模块未正确导入，检查 sys.path 配置。
更新文档：每次修改 Python 代码后，需重新运行 sphinx-apidoc（加 -f 覆盖）或手动更新 .rst 文件。

10. 进一步优化

自定义模板：在 source/_templates/ 中创建自定义模板，修改 sphinx-apidoc 生成的 .rst 文件格式。
持续集成：在 CI/CD 流程中自动运行 sphinx-apidoc 和 make html，确保文档始终与代码同步。

通过 sphinx-apidoc，你可以快速为大型 Python 项目生成 API 文档，大大提高效率！

示例项目：一个简单的计算器

假设我们有一个小项目 calculator，结构如下：

calculator/
├── calc.py # 主代码文件
└── docs/ # 文档文件夹（稍后创建）

1. 创建项目代码

先在 calculator 文件夹下创建 calc.py，内容如下：

"""这是一个简单的计算器模块。"""

def add(a, b):
 """将两个数相加。

 参数:
 a (int): 第一个数
 b (int): 第二个数

 返回:
 int: 两数之和
 """
 return a + b

def subtract(a, b):
 """将两个数相减。

 参数:
 a (int): 被减数
 b (int): 减数

 返回:
 int: 两数之差
 """
 return a - b

这个文件有模块级 docstring 和函数级 docstring，Sphinx 可以利用这些生成文档。

2. 设置 Sphinx

安装 Sphinx

确保你有 Python 环境，然后在终端运行：

pip install sphinx

初始化文档

进入 calculator 文件夹，运行：

mkdir docs
cd docs
sphinx-quickstart

系统会问你一些问题，按以下方式回答（其他可以默认回车）：

Separate source and build directories (y/n)：输入 n（简单起见，放在一起）。
Project name：输入 Calculator。
Author name(s)：输入你的名字，比如 张三。
Project release：输入 1.0。

完成后，docs 文件夹会变成这样：

calculator/
├── calc.py
└── docs/
 ├── conf.py # 配置文件
 ├── index.rst # 主文档文件
 ├── Makefile # Linux/Mac 生成工具
 └── make.bat # Windows 生成工具

3. 配置 Sphinx

修改 `conf.py`

打开 docs/conf.py，做两处调整：

添加项目路径，让 Sphinx 能找到 calc.py：在文件顶部添加：

import os
import sys
sys.path.insert(0, os.path.abspath('..')) # 指向 calculator 目录

启用 autodoc 扩展，支持自动生成代码文档：找到 extensions 列表，改成：
```
extensions = ['sphinx.ext.autodoc']
```

检查 `index.rst`

默认的 index.rst 可能是：

Welcome to Calculator's documentation!
======================================

.. toctree::
 :maxdepth: 2

暂时不用改，后面会加内容。

4. 自动生成代码文档

用 `sphinx-apidoc`

在 docs 目录下运行：

sphinx-apidoc -o . ..

-o .：输出到当前目录（docs）。
..：扫描上级目录（calculator）。

这会生成：

modules.rst：模块总览。
calc.rst：针对 calc.py 的文档。

看看 calc.rst，内容大概是：

calc
====

.. automodule:: calc
 :members:
 :undoc-members:
 :show-inheritance:

整合到 `index.rst`

编辑 index.rst，加入模块链接：

Welcome to Calculator's documentation!
======================================

这是一个简单的计算器项目，提供加法和减法功能。

.. toctree::
 :maxdepth: 2

 modules

这里手动加了句介绍文字，modules 指向自动生成的模块文档。

5. 手动添加使用说明

新建一个文件 docs/usage.rst，写点教程：

使用说明
========

这是一个计算器的使用方法。

步骤
----
1. 导入模块：
 .. code-block:: python

 from calc import add, subtract

2. 调用函数：
 .. code-block:: python

 print(add(3, 5)) # 输出 8
 print(subtract(10, 2)) # 输出 8

然后在 index.rst 的 toctree 里加一行：

.. toctree::
 :maxdepth: 2

 modules
 usage

6. 生成文档

在 docs 目录下运行：

make html # Linux/Mac

或

make.bat html # Windows

完成后，打开 docs/_build/html/index.html，你会看到：

首页有欢迎文字和目录。
点击 “modules” -> “calc”，显示 add 和 subtract 的自动文档（从 docstring 生成）。
点击 “使用说明”，显示手动写的教程。

结果预览

网页大概长这样：

首页：

Welcome to Calculator's documentation!
这是一个简单的计算器项目，提供加法和减法功能。
- modules
- usage

calc 页面：

calc
这是一个简单的计算器模块。
add(a, b)
 将两个数相加。
 参数: a (int) - 第一个数, b (int) - 第二个数
 返回: int - 两数之和
subtract(a, b)
 将两个数相减。
 ...

usage 页面：

使用说明
这是一个计算器的使用方法。
步骤
1. 导入模块：
 from calc import add, subtract
2. 调用函数：
 print(add(3, 5)) # 输出 8
 ...

总结流程

写代码+注释：calc.py 里加 docstring。
初始化：sphinx-quickstart 创建文档框架。
配置：改 conf.py 加路径和扩展。
自动生成：用 sphinx-apidoc 提取代码文档。
手动补充：写 usage.rst 加说明。
生成网页：make html。

内网文件传输工具LocalSend

Sun, 16 Mar 2025 18:47:30 +0800

https://localsend.org/zh-CN/download

下载

有很多种下载方法，我这里下载exe

传输

如果都是连接的wifi

如果都是连接的都是wifi，那么直接传输即可

如果一个连接的wifi，另一个连接的网线

使用链接分享

那么可能找不到，这个时候发送端选择设置

可以看到出来几个链接，一般选择第一个，到另一个电脑上面去

点击文件就能下载了

尝试使用手动输入

前提先把双方的vpn关掉

然后可以保存到收藏夹

github项目newsnow部署

Thu, 13 Mar 2025 22:25:19 +0800

项目介绍

项目地址：

https://github.com/ourongxing/newsnow

newsnow是一个新闻聚合平台，用户可以关注自己感兴趣的新闻，并查看新闻内容。

使用docker部署 – windows

安装好docker desktop

具体的部署方式就不介绍了

下载项目文件

在当前项目下执行docker compose up 命令

使用docker部署 – linux服务器

安装好docker，可以使用1panel或者是宝塔面板

curl -sSL https://resource.fit2cloud.com/1panel/package/quick_start.sh -o quick_start.sh && sudo bash quick_start.sh

使用docker编排进行部署

version: '3'

services:
 newsnow:
 image: ghcr.io/ourongxing/newsnow:latest
 container_name: newsnow
 restart: always
 ports:
 - '4444:4444'
 environment:
 - G_CLIENT_ID=
 - G_CLIENT_SECRET=
 - JWT_SECRET=
 - INIT_TABLE=true
 - ENABLE_CACHE=true

打开你的ip地址:4444

IObit Unlocker解除文件占用

Tue, 11 Mar 2025 16:28:53 +0800

下载地址：

https://www.iobit.com/en/iobit-unlocker.php

postman

Wed, 05 Mar 2025 10:00:47 +0800

postman介绍

如今，Postman的开发者已超过1000万(来自官网)，选择使用Postman的原因如下:
简单易用 - 要使用Postman，你只需登录自己的账户，只要在电脑上安装了Postman应用程序，就可以方便地随时随地访问文件。使用集合 - Postman允许用户为他们的API调用创建集合。每个集合可以创建子文件夹和多个请求。这有助于组织测试结构。多人协作 - 可以导入或导出集合和环境，从而方便共享文件。直接使用链接还可以用于共享集合。创建环境 - 创建多个环境有助于减少测试重复(DEV/QA/STG/UAT/PROD)，因为可以为不同的环境使用相同的集合。这是参数化发生的地方，将在后续介绍。创建测试 - 测试检查点(如验证HTTP响应状态是否成功)可以添加到每个API调用中，这有助于确保测试覆盖率。自动化测试 - 通过使用集合Runner或Newman，可以在多个迭代中运行测试，节省了重复测试的时间。调试 - Postman控制台有助于检查已检索到的数据，从而易于调试测试。持续集成——通过其支持持续集成的能力，可以维护开发实践。

polar-DB

Tue, 04 Mar 2025 13:59:34 +0800

简介

Alibaba 的 PolarDB 是一款云原生关系型数据库服务，性能高、可扩展性强，与MySQL 和 PostgreSQL完全兼容。
它采用计算与存储分离架构，支持高达 500 TB 的存储容量，并提供多区域部署以确保高可用性。
安全功能包括 IP 白名单和虚拟专用云（VPC），全球数据库网络（GDN）支持跨区域数据复制和灾难恢复。
意外细节：PolarDB 还提供免费实例，适合开发者测试，规格为 2 核 8 GB，50 GB 存储，每个月可参与一次。

什么是 PolarDB？
PolarDB 是阿里巴巴云开发的一款云原生数据库服务，旨在为现代应用程序提供高性能和可扩展性。它与 MySQL 和 PostgreSQL 完全兼容，适合需要快速响应和高并发场景的企业。

主要特点

高性能：比传统数据库快得多，支持数百万次每秒查询（QPS）。
可扩展性：支持自动扩展，计算和存储可独立调整，最大支持 500 TB 存储。
高可用性：通过多区域部署和自动故障转移，确保最小停机时间。
安全性：包括 IP 白名单、VPC 等措施保护数据。
全球数据库网络（GDN）：支持跨区域数据同步，灾难恢复时间小于 2 秒。

开发者福利
PolarDB 提供免费实例，规格为 2 核 8 GB，50 GB 存储，适合开发者测试，每个月可参与一次，区域包括中国香港、德国法兰克福等。详情请访问官方产品页面和文档中心。

详细报告

Alibaba 的 PolarDB 是一款云原生关系型数据库服务，由阿里巴巴云开发，旨在为企业提供高性能、可扩展和可靠的数据库解决方案。以下是其详细特点和功能的全面分析，基于官方资料和相关审查。

概述与背景

PolarDB 是为云环境优化的下一代关系型数据库，采用计算与存储分离架构，整合了软件和硬件资源，确保高性能和灵活性。它完全兼容 MySQL 和 PostgreSQL，并高度兼容 Oracle 语法，适合需要快速迁移和扩展的企业应用。PolarDB 已在阿里巴巴的“双十一”全球购物节等超大规模事件中得到验证，体现了其在高并发和大规模存储场景下的稳定性。

主要特点与功能

1. 架构与性能

计算与存储分离：PolarDB 的核心设计是将计算和存储解耦，允许独立扩展计算节点和存储容量。这种架构通过共享分布式存储确保数据一致性，避免传统异步复制带来的延迟问题。
高性能：官方数据表明，PolarDB for MySQL 在事务处理上比开源 MySQL 快 5 倍，在分析查询上快 400 倍，总拥有成本（TCO）降低 50%。对于 PostgreSQL，优化后查询和事务处理速度比标准 PostgreSQL 快 6 倍。
并行查询（MySQL 8.0）：通过在存储层分配数据到多个线程并行计算，复杂 SQL 和报告查询的响应时间可减少高达 30 倍（在 100 GB 数据、88 CPU 核心、710 GB 内存的配置下）。
快速 DDL 操作（MySQL）：通过物理复制优化，添加列或索引可在并行处理下瞬间完成，1 TB 数据、16 CPU 核心、128 GB 内存的场景下，添加列仅需 1 秒，比开源 MySQL 快 10 倍。

2. 可扩展性与存储

PolarDB 支持高达 500 TB 的存储容量（MySQL 和 PostgreSQL 版本），每个集群最多 16 个节点，每个节点最多 88 vCPUs。
自动扩展：存储和计算资源可根据数据量自动调整，无需停机。PolarDB-X 版本可扩展至拍字节级，适合超大规模数据场景。
弹性扩展（MySQL）：支持垂直扩展（升级/降级规格）和水平扩展（添加/移除只读节点，最多 16 个），存储可自动扩展至 500 TB，调整在几分钟内生效。

3. 高可用性与灾难恢复

多区域架构：PolarDB 在多个可用区部署数据副本，确保数据库灾难恢复和备份。支持在同一区域的 3 个数据中心或跨 3 个区域的 5 个数据中心部署。
全球数据库网络（GDN）：通过异步复制和物理日志并行处理，数据在全球多个集群间同步时间小于 2 秒，支持跨区域读写分离，数据从最近的集群读取，提升性能。
高可用性：主节点故障时自动切换到备用节点，无数据丢失，解决异步复制问题，确保全球数据一致性。

4. 安全与管理

安全措施：包括 IP 白名单、虚拟专用云（VPC）和多数据副本，确保数据在访问、存储和管理中的安全性。
运维功能（MySQL）：提供 24/7 机器学习驱动的异常检测，细粒度监控和诊断工具，包括自治中心、会话管理、实时监控、存储分析、死锁分析、诊断报告和性能洞察。SQL Explorer 可保留日志长达 5 年，支持慢 SQL 查询分析。
自动扩展：可配置阈值、节点规格和只读节点，动态调整资源。

5. 兼容性与迁移

兼容性：PolarDB for MySQL 和 PostgreSQL 与其生态系统 100% 兼容，PostgreSQL 版本高度兼容 Oracle 语法，支持 DBLINK、分区表、PL/SQL 等功能，逻辑概念（如用户、角色、模式、权限）与 Oracle 相似。
迁移支持：提供 ADAM 工具进行免费迁移评估，覆盖兼容性、关联性、性能、风险和修改方法，并提供优化和转换建议。PostgreSQL 版本还包括数据库专家服务，涵盖模式/数据迁移、一致性验证、SQL 模拟/回放/切换/优化。

6. 特定版本功能

PolarDB for PostgreSQL：
- 集成 GanosBase，支持时空数据存储和管理，包括向量、网格、轨迹、点云、网格、路径、3D 模型等。提供多级并行运算符，高效处理，兼容商业和开源空间数据服务，可构建城市级空间数据仓库。
- 完全托管，减少 TCO，支持手动次要版本升级以获取性能提升、新功能和修复。
PolarDB for Xscale：
- 分布式无共享架构，高吞吐量、低延迟、高可扩展性和高可用性，完全兼容 MySQL 生态，支持二进制日志和开源分区/分片工具。
- 标准版基于 Paxos 协议（主节点、备用节点、日志节点），成本效益高，可迁移至企业版。企业版支持在线扩展至拍字节级，适合高并发和大规模数据处理。
- 自动分区（AUTO 模式，无需分区键，使用标准 MySQL 语法），混合负载（并行计算、自动扩展、读写分离、只读副本支持 OLTP/OLAP），金融级一致性（RPO=0，RC/RR 隔离级别）。
- 企业级功能包括多区域/多区域灾难恢复，符合金融分布式事务数据库标准，通过长期稳定性测试，监控（计算/存储/数据库，定制警报，概览）和诊断/优化（识别问题 SQL，实时分析，报告中心）。

7. 开发者福利

免费实例：提供 Always Free 实例，适合开发者测试。规格为 2 核 8 GB，50 GB 存储，每个月可参与一次，区域包括中国（香港）、德国（法兰克福）、印度尼西亚（雅加达）、日本（东京）、新加坡、泰国（曼谷）、英国（伦敦）。参与后有效期为当月，未使用则过期，可切换区域或转为付费计划。详情请访问获取免费资源指南和条款与条件。

计费与成本效益

计费方式（MySQL）：支持按量付费（根据实例规格和存储使用扣费，自动扩展，适合短期使用）和订阅（预付费，长期使用，更具成本效益，提供更长有效期和更大容量计划）。
成本效益：比传统 MySQL/PostgreSQL 快 100 倍以上，共享存储减少扩展成本，仅按实际使用存储付费，降低总拥有成本。

对比与用户反馈

根据审查和用户反馈，PolarDB 特别适合需要高并发、大规模存储和复杂查询的业务场景。Sourceforge 的描述指出，其在阿里巴巴“双十一”购物节中得到验证，支持百万级 QPS 和 100 TB 集群，成本仅为传统商业数据库的 1/10。Gartner Peer Insights 和其他平台的用户评论强调其性能和扩展性，但也建议关注特定版本的文档以了解差异。

表格：PolarDB 主要版本对比

版本	架构	存储容量	主要特点	适用场景
PolarDB for MySQL	共享存储	500 TB	高事务性能，快速 DDL，IMCI 支持 HTAP	高并发 OLTP/OLAP 混合负载
PolarDB for PostgreSQL	共享存储	500 TB	Oracle 兼容，时空数据支持，托管服务	空间数据分析，Oracle 迁移
PolarDB for Xscale	分布式无共享	拍字节级	高吞吐量，自动分区，金融级一致性	大规模分布式事务，金融行业

结论

PolarDB 提供了一套全面的云原生数据库解决方案，涵盖高性能、可扩展性、安全性和兼容性，适合各种企业级应用。开发者可通过免费实例快速上手，具体功能根据版本（如 MySQL、PostgreSQL、Xscale）有所不同，建议参考官方文档获取详细信息。

关键引用：

coze

Tue, 04 Mar 2025 11:46:49 +0800

参考：

https://www.coze.cn/open/docs/guides/welcome
https://www.coze.cn/open/docs/guides/quickstart

使用说明

创建一个智能体

可以设置智能体的行为

效果

调用插件

插件可以调用一些api

flora无限画布

Tue, 04 Mar 2025 11:04:28 +0800

网址

https://www.florafauna.ai/

使用简介

当前可以免费使用，可以google账户登录

导入个人的资源文件，由于后续的风格生成

点击加号，设置生成方式并输入提示词

点击生成按钮，等待生成结果其中的数字表示同时生成几个（因为往往ai的效果不稳定，可能生成很多个才能找到适合自己的一个）

可以多个生成内容传入一个输入中，不过只支持文本

可以让它做总结

总结的内容可以再用于生成视频或图片

使用感受

flora我主要是用于设计方面，可以提供它一些风格的图片，让它学习，然后让它生成，这样就可以快速生成想要的风格。主要使用的方式是工作流的方式，每一个下级的框都会接收上一级的输出，总体来说使用成本比较低，支持文本、图片和视频三种输入和输出。

使用简单，基本上效果也还可以。

缺点：

感觉界面有点卡顿
可以选择的模型比较少
提示词还是需要自己写，有现成的提示词的话，就好了

百度自由画布

Tue, 04 Mar 2025 10:59:39 +0800

百度自由画布

正在申请内测资格…

软件试用 on 扎塔-Zata

everything-claude-code

安装和配置

注意事项

概念

cherry-studio

Cherry Studio 详细使用教程

注意事项

alist

AList V3 详细使用教程：安装、配置与 WebDAV 挂载

wrap.dev

Warp 终端使用教程与功能详解

ccNexus

核心功能亮点

支持平台与安装方式（超简单）

快速配置（两步搞定 Claude Code / Codex CLI）

最新版本信息（截至目前）

项目数据一览

Coolify vs Dokploy

Coolify vs Dokploy 深度对比

新电脑快速配置-scoop

windows (注意要最好打开clash的TUN模式)

多台电脑环境变量(.env)同步方案

多台电脑环境变量(.env)同步方案

nvm

安装使用

cc-switch

cc-switch 使用

公开教程

安装

配置 claude 供应商

homebrew

Homebrew 完全指南：从安装到高效使用（2026 最新版）

Homebrew 为什么它是 macOS 上的必备工具

软件工程的范式转移：基于 Claude Code 与智能体协作的高效编程实践

一人开发，文档何去何从？AI 时代，我用 4 份文档搞定整个项目

软件工程的范式转移：基于 Claude Code 与智能体协作的高效编程实践

一、Claude Code：终端原生的协作智能体

核心能力矩阵

性能基准：真实世界表现

二、规则系统：CLAUDE.md 的工程化实践

2.1 文件加载逻辑

2.2 内容设计原则：简洁、可操作、聚焦

三、文档即代码：MkDocs 与 AI 协作的工程实践

3.1 自动化参考文档：mkdocstrings + 动态生成

3.2 Claude Code 驱动的文档维护工作流

步骤 1：检测代码变更并触发文档任务

步骤 2：AI 辅助生成用户指南内容

步骤 3：文档质量保障

3.3 AI 生成架构可视化：Mermaid 集成

四、能力扩展：Skills 机制与按需加载

4.1 目录结构

4.2 文档更新技能示例

五、自动化防护：Hooks 与权限模式

5.1 Hooks：确定性生命周期脚本

5.2 权限模式：三重安全护栏

六、外部系统集成：MCP 协议

典型集成场景

七、跨工具协作：GitHub Copilot 指令文件

八、安全治理框架

九、实战工作流：从代码变更到文档更新

十、结语：文档作为一等公民

参考资源

数据集标注工具

ubiai

LabelStudio

install

实用软件工具｜好用软件推荐

IDE插件

Material Icon Theme 好看的图标主题

浏览器插件

飞书文档下载为md文件 Cloud Document Converter

macOS 工具

Clipy - 剪贴板管理器

wsl使用教程

基础知识

安装

配置

问题解决

wsl和docker冲突 表现为wsl无法联网 — 把docker关了，或者使用docker里面的linux容器

wsl和docker冲突表现为wsl无法联网 — 把docker关了，或者使用docker里面的linux容器

5. `search` 方法详解

结果条目 (`results`) 结构

7. 高级搜索功能 (基于 `search` 方法的参数组合)

结合 `include_domains` 和 `exclude_domains`