AI 工具试用 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

注意事项

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 就是专门为你打造的“智能中转站” —— 一键轮换、格式转换、监控全都有，安装后几分钟就能用上。

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为例

软件工程的范式转移：基于 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 月）编写。技术持续演进，建议定期查阅官方资源获取最新功能与安全实践。

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！

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

百度自由画布

正在申请内测资格…

AI 工具试用 on 扎塔-Zata

everything-claude-code

安装和配置

注意事项

概念

cherry-studio

Cherry Studio 详细使用教程

注意事项

wrap.dev

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

ccNexus

核心功能亮点

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

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

最新版本信息（截至目前）

项目数据一览

cc-switch

cc-switch 使用

公开教程

安装

配置 claude 供应商

软件工程的范式转移：基于 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 指令文件

八、安全治理框架

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

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

参考资源

claude-code&codex&Gemini-cli

claude code

使用教程

安装

mac/linux/wsl

windows

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

使用技巧

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

codex

安装和配置

cursor使用教程

agent开发技巧

Tavily-搜索引擎api

Tavily API Python SDK 详细使用教程

目录

1. 简介

2. 安装

3. API 密钥设置

环境变量（推荐）

直接在代码中设置

4. 基本搜索

5. search 方法详解

常用参数

示例：使用不同参数

6. 理解返回结果

整体响应结构

结果条目 (results) 结构

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

获取特定主题信息

5. `search` 方法详解

结果条目 (`results`) 结构

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

结合 `include_domains` 和 `exclude_domains`