Claude Code 的学习笔记

郑同学zxc2026-04-02 9:28

Claude Code 的使用笔记

基础概念

下面给你一次性列全 + 极简解释 ，学完这些，你就能高效使用 Claude Code / Cursor / CodeLlama / GitHub Copilot 这类 AI 编程助手，而不是只会"让它写代码"。

一、基础概念（必须懂）

1. LLM（大语言模型）

  • 解释：能理解自然语言、代码、上下文的深度学习模型。
  • 作用：AI 写代码、改 Bug、解释逻辑全靠它。

2. Context Window（上下文窗口）

  • 解释：AI 能"记住"的总字符/Token 上限。
  • 作用：超过就会遗忘前面代码 → 导致改错、漏逻辑。

3. Token（令牌）

  • 解释：文字/代码的最小单位（≈4 英文 ≈1 中文）。
  • 作用：决定你一次能贴多少代码、上下文能多长。

4. Prompt（提示词）

  • 解释：你给 AI 的指令 + 上下文 + 约束。
  • 作用：Prompt 质量 = 代码质量。

5. Few-shot / 示例学习

  • 解释：给 AI 1--3 个正确示例，它会模仿格式/风格。
  • 作用：让 AI 输出更规范、更符合你的习惯。

二、使用 AI 写代码的核心概念

6. Intent（意图明确）

  • 解释：你要做什么、为什么、输入输出是什么。
  • 坏：帮我写登录。
  • 好：用 JS 写登录表单，验证邮箱密码，错误提示，提交禁用。

7. Constraints（约束条件）

  • 解释：技术栈、风格、禁止事项、依赖限制。
  • 例：只用原生JS、不要jQuery、兼容ES6、注释简洁。

8. Context（上下文）

  • 解释：已有的代码、结构、函数、变量。
  • AI 必须看上下文才不会乱写。

9. Step-by-Step（分步思考）

  • 解释：让 AI 先想步骤再写代码。
  • 作用：减少 Bug、逻辑更清晰。

10. One-task-one-prompt（单任务原则）

  • 解释：一次只让 AI 做一件事。
  • 不要：写登录+注册+验证码+加密+存储。

三、AI 代码助手特有的概念

11. Code Context（代码上下文）

  • 解释：AI 能读取的当前文件/依赖文件/项目结构。
  • Claude Code / Cursor 都支持多文件上下文。

12. Retrieval / RAG（检索增强）

  • 解释：AI 从你的代码库里检索相关函数/类。
  • 作用：不会瞎编接口、不会重复造轮子。

13. Tool Use（工具调用）

  • 解释：AI 能调用：
    • 终端
    • 搜索
    • 浏览器
    • 代码解释器
  • 作用：自动调试、查文档、跑代码。

14. Edit Mode（编辑模式）

  • 解释：AI 直接修改你现有代码，不是重写。
  • 关键指令：
    • 修改这里
    • 优化这里
    • 修复这里
    • 只改逻辑，不改结构

15. Diff Mode（差异输出）

  • 解释：AI 只输出改动部分，不输出全量代码。
  • 作用：干净、快、不污染。

四、调试与纠错概念

16. Hallucination（幻觉）

  • 解释：AI 编造不存在的函数/库/API。
  • 防范：要求 AI 标注来源、查文档、验证。

17. Self-Correction（自我修正）

  • 解释：让 AI 先检查自己的代码，再给你。
  • 指令：先检查错误，再输出。

18. Test Case（测试用例）

  • 解释：输入 → 预期输出。
  • 作用：AI 写的代码能直接验证。

五、工程化与规范（高级但非常有用）

19. Code Style（代码风格）

  • 解释：命名、缩进、注释、结构。
  • 指令：遵循ESLint、驼峰、简洁注释。

20. Interface First（接口优先）

  • 解释：先定义函数名、参数、返回值，再写逻辑。
  • AI 最擅长这种结构。

21. Modularity（模块化）

  • 解释：分函数、分文件、单一职责。
  • 指令：拆小函数，不要大段逻辑。

22. Readability（可读性）

  • 解释：代码要让人看懂，不是只让机器看懂。

六、效率类概念（真正高手差距）

23. Zero-shot（零示例）

  • 解释：不给示例，直接描述任务。
  • 适合简单任务。

24. Role Prompt（角色设定）

  • 解释：给 AI 设定身份：
    • 资深前端
    • 架构师
    • 调试专家
  • 输出更专业。

25. Chain-of-Thought（思维链）

  • 解释：让 AI 先写思路 → 再写代码 → 再解释。
  • 代码正确率提升非常明显。

你真正需要掌握的最小核心清单（最精简）

  1. Context Window（上下文长度）
  2. Token（计费/长度单位）
  3. Prompt（指令）
  4. Context（代码上下文）
  5. Constraints（约束）
  6. Hallucination（幻觉）
  7. Edit Mode（修改而非重写）
  8. Step-by-Step（分步思考）
  9. One-task-one-prompt（一次一个任务）
  10. Test Case（测试用例）

环境搭建与基础交互

安装Claude Code

官网：https://claude.com/product/claude-code

复制到终端，windows使用powershell

可能看起来卡主了，因为梯子网速限制需要等久一点（当然很快当我没说）

输入claude --version ，验证安装版本

然后创建测试目录，进入到目录下载命令行中输入claude

如果出现以下报错

最后发现这个解决方案对我有用：

在主文件夹中打开.claude.json；

将以下行添加到 json 中并保存；

json 复制代码 
"hasCompletedOnboarding": true

重启claude

至此claude已经安装成功

登录与授权

可以输入 /login 进行登录。

Claude Code 提供了三种不同的身份验证和计费模式，分别对应不同的用户群体和付费习惯：

  1. Claude 个人/团队订阅模式 (Claude Account)
  • 适用人群：已经购买了 Claude Pro、Max、Team 或 Enterprise 会员的普通用户或企业员工。
  • 计费方式：包含在你的月费/年费订阅中。
  • 特点：
  • 直接使用你在 claude.ai 网站上的账户登录。
    • 受到订阅计划的"消息配额"限制（如果用得太猛，可能会触发限额）。
    • 适合日常对话频繁、不想额外支付 API 账单的用户。
  1. Anthropic 控制台开发者模式 (Anthropic Console)
  • 适用人群：开发者、技术团队。
  • 计费方式：按量计费 (Pay-as-you-go)。
  • 特点：
  • 使用 API Key 进行连接。
    • 用多少付多少，没有月费门槛。
    • 适合需要更高并发、更稳定调用，或者没有 Pro 订阅但想按需付费的用户。
    • 不占用 claude.ai 网页端的配额。
  1. 第三方云平台模式 (3rd-party Platform)
  • 适用人群：已经在 AWS (Bedrock)、Google Cloud (Vertex AI) 或 Azure (Foundry) 部署了企业级服务的用户。
  • 计费方式：通过这些云服务商的账单进行结算。
  • 特点：
  • 数据合规性更高，通常用于企业内部环境。
    • 不需要直接向 Anthropic 付费，而是消耗云平台的资源额度。
    • 适合对数据隐私有极高要求的公司或已经在这些云平台深度集成的团队。

总结建议：

  • 如果你有 Claude Pro 会员，选 1。
  • 如果你只想尝试一下或平时写代码不多，选 2（充多少用多少）。
  • 如果你是大公司员工且公司在用 AWS/Google Cloud，选 3。

配置自定义 API 接口和 Key

这是很多国内用户最关心的部分------如何让 Claude Code 使用自己的 API Key 或第三方代理接口。

使用 Anthropic 官方 API Key

如果你有 Anthropic Console 的 API Key：

bash 复制代码 
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"

运行项目并下载源码

把它加到你的 shell 配置文件中永久生效：

bash 复制代码 
# Bash 用户
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

# Zsh 用户
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

运行项目并下载源码

然后运行 claude，就会直接使用你的 API Key，不需要浏览器登录。

使用自定义 API 端点（第三方代理/中转）

很多国内用户无法直接访问 Anthropic API，需要使用代理服务。国内有相当多的平台，这里推荐使用 https://claude-code.com.cn

bash 复制代码 
# 设置你的代理地址（替换为你的实际地址）
export ANTHROPIC_BASE_URL="https://claude-code.com.cn"
 
# 设置你的 API Key（代理服务商提供的 Key）
export ANTHROPIC_API_KEY="sk-your-proxy-key"
  • 关键点：代理服务必须兼容 Anthropic Messages API 格式（/v1/messages 端点），并且要正确转发 anthropic-beta 和 anthropic-version 请求头。
    永久配置：
bash 复制代码 
# 加到 .bashrc 或 .zshrc
cat >> ~/.bashrc << 'EOF'
# Claude Code 自定义 API
export ANTHROPIC_BASE_URL="https://claude-code.com.cn"
export ANTHROPIC_API_KEY="sk-your-proxy-key"
EOF
source ~/.bashrc

windows端可以通过配置文件来配置~/.claude/settings.json（全局生效）

json 复制代码 
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://claude-code.com.cn",
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  },
  "model": "sonnet",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)"
    ]
  }
}

我只添加了

json 复制代码 
  "env": {
    "ANTHROPIC_BASE_URL": "https://claude-code.com.cn",
    "ANTHROPIC_API_KEY": "sk-your-key"
  },

就可以使用，不过要注意费用，不然很容易就花钱如流水

配置的优先级（从高到低）：

Managed（组织管理配置，不可覆盖）

命令行参数（临时会话覆盖）

Local（.claude/settings.local.json，仅本项目本人）

Project（.claude/settings.json，团队共享）

User（~/.claude/settings.json，全局个人）

使用 apiKeyHelper 动态获取 Key

如果你的 Key 需要动态生成（比如从 Vault 获取），可以配置一个脚本：

json 复制代码 
{
  "apiKeyHelper": "/path/to/your/get-key.sh"
}

脚本示例：

bash 复制代码 
#!/bin/bash
# get-key.sh
# 从密钥管理工具获取 key
vault kv get -field=api_key secret/claude-code

默认每 5 分钟或遇到 401 错误时刷新。可以自定义刷新间隔：

bash 复制代码 
export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000  # 1 小时

实战例子

进入自己创建的个人目录后，让他写一个个人博客网站，使用html实现。

执行过程中会向你索要一定权限

这是问你要创建文件权限。

  • 1.是同意
  • 2.是此次对话中都同意，后续不在询问
  • 3.是拒绝

选2就会自动执行，如果后悔想要换个模式使用shift+Tab切换模式

模式详解

1️⃣ 默认模式（Default Mode）

  • 触发标识 ：? for shortcuts（快捷键提示）
  • 核心规则 ：修改文件前一定询问用户
  • 特点标签：最稳妥
  • 详细说明 ：
    • AI 每次要修改、删除、新增文件时，都会弹出确认框，你必须手动点「同意」才会执行修改。
    • 完全可控，不会误改代码，是日常开发、改 Bug、小功能迭代的首选。
    • 适合：新手、核心项目、需要严格审核每一次修改的场景。

2️⃣ 自动模式（Accept Edits On）

  • 触发标识 ：▶▶ accept edits on（自动接受编辑开启）
  • 核心规则 ：自动修改文件，无需手动确认
  • 特点标签：最方便
  • 详细说明 ：
    • 开启后，AI 会直接执行所有文件修改、新增、删除操作，全程不弹窗、不询问。
    • 适合：你完全信任 AI 的修改、批量重构、快速迭代、已知安全的场景。
    • ⚠️ 风险提示：一旦开启，AI 可能会直接覆盖你本地代码，核心项目、未备份代码不建议长期开。

3️⃣ 规划模式（Plan Mode）

  • 触发标识 ：⏸ plan mode on（规划模式开启）
  • 核心规则 ：只讨论、不修改文件
  • 特点标签：适合构思
  • 详细说明 ：
    • 开启后，AI 只会输出方案、思路、代码逻辑、架构设计，绝对不会触碰你本地的任何文件。
    • 适合：项目前期构思、架构设计、需求讨论、方案评审，完全零风险。
    • 你可以让 AI 先出完整方案，确认没问题后，再切回默认/自动模式执行修改。

负责任务处理与终端控制

执行终端命令

输入!

可以运行终端命令

使用规划模式

使用ctrl+enter进行提示词换行，不能直接换行不然会直接提交。

Ctrl+g，会进入你指定的编辑软件。

🎯 Claude Code Ctrl+G 编辑器配置全指南（Windows/Linux/Mac 全覆盖）

Claude Code 中 Ctrl+G 的核心作用是：打开外部编辑器，编辑多行 Prompt （比如写复杂需求、长代码、架构方案）。默认会用系统默认编辑器，你可以通过以下步骤完全自定义为指定编辑器（VS Code/Cursor/Qt Creator等）。

一、核心原理

Claude Code 的 Ctrl+G 遵循 Unix 标准：

  • 优先读取 VISUAL 环境变量（图形界面编辑器）
  • 其次读取 EDITOR 环境变量（终端编辑器）
  • 最新版 Claude Code 也支持在 settings.json 中直接配置 promptEditor
二、分系统配置步骤（直接复制执行）
✅ Windows 系统（最常用，适配 VS Code/Cursor）
  • 方法1：临时生效（当前终端会话）
    打开 PowerShell，执行以下命令（以 VS Code 为例）：
powershell 复制代码 
# 1. 先验证 VS Code 命令是否可用（执行后会打开 VS Code 即为正常）
code --version

# 2. 设置环境变量（临时生效，关闭终端失效）
$env:VISUAL = "code --wait"
$env:EDITOR = "code --wait"

关键参数 --wait：必须加，让 Claude Code 等待你关闭编辑器后再继续执行，否则会直接提交空内容。

  • 方法2：永久生效（所有终端会话）
  1. 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」
  2. 在「用户变量」中点击「新建」：
    • 变量名：VISUAL
    • 变量值：code --wait（VS Code）/ cursor --wait（Cursor）/ qtcreator --wait（Qt Creator）
  3. 再新建一个变量：
    • 变量名：EDITOR
    • 变量值：code --wait
  4. 重启终端/ Claude Code 即可生效。
  • 方法3：settings.json 直接配置（最新版 Claude Code 推荐）
    在 Claude Code 中执行 /config 打开全局配置文件 ~/.claude/settings.json，添加：
json 复制代码 
{
  "promptEditor": "code --wait"
}

保存后立即生效，无需重启，适合不想改系统环境变量的场景。

✅ Linux / macOS 系统
  • 方法1：临时生效（当前终端会话）
bash 复制代码 
# VS Code
export VISUAL="code --wait"
export EDITOR="code --wait"

# Cursor
export VISUAL="cursor --wait"
export EDITOR="cursor --wait"

# Vim/Neovim（终端党）
export VISUAL="nvim"
export EDITOR="nvim"
  • 方法2：永久生效（所有终端会话）
    编辑你的 shell 配置文件（~/.zshrc / ~/.bashrc / ~/.bash_profile），添加：
bash 复制代码 
# VS Code
export VISUAL="code --wait"
export EDITOR="code --wait"

# Cursor
# export VISUAL="cursor --wait"
# export EDITOR="cursor --wait"

执行 source ~/.zshrc 立即生效，重启终端也会保留。

  • 方法3：settings.json 配置
json 复制代码 
{
  "promptEditor": "code --wait"
}
三、常见编辑器配置对照表（直接复制）
编辑器 配置命令（Windows/Linux/Mac 通用） 关键说明
VS Code code --wait 必须加 --wait，否则不等待编辑
Cursor cursor --wait 完全兼容 VS Code 命令，--wait 必加
Qt Creator qtcreator --wait 适合 Qt 开发，直接打开项目文件
Neovim nvim 终端编辑器，无需 --wait
Vim vim 终端编辑器，无需 --wait
Notepad++ "C:\Program Files\Notepad++\notepad++.exe" -multiInst -notabbar -nosession -noPlugin Windows 专用，路径加引号避免空格问题
四、验证配置是否生效
  1. 打开 Claude Code，直接按 Ctrl+G
  2. 会自动打开你配置的编辑器，生成一个临时 Prompt 文件
  3. 在编辑器中输入内容，保存并关闭
  4. Claude Code 会自动读取你编辑的内容，提交对话
  5. 若直接打开了默认编辑器（如记事本/vi），说明环境变量配置未生效，检查：
    • 环境变量是否正确（echo $VISUAL / $env:VISUAL 验证）
    • 编辑器命令是否在系统 PATH 中（执行 code --version 验证）
    • 是否加了 --wait 参数（图形编辑器必须）
五、进阶技巧（工业视觉/Qt 开发专属）
1. 绑定 Ctrl+G 直接打开 Qt Creator
powershell 复制代码 
# Windows 永久配置
$env:VISUAL = "qtcreator --wait"
$env:EDITOR = "qtcreator --wait"

适合你写 Qt 相关长 Prompt，直接在熟悉的 Qt Creator 中编辑。

2. 解决 Cursor 与 VS Code 冲突

若安装 Cursor 后 code 命令失效，直接用 Cursor 命令：

powershell 复制代码 
$env:VISUAL = "cursor --wait"
$env:EDITOR = "cursor --wait"
3. 多编辑器快速切换

在 Claude Code 中执行 /keybindings 打开快捷键配置，添加：

json 复制代码 
{
  "ctrl+g": "/env VISUAL=code --wait",
  "ctrl+alt+g": "/env VISUAL=cursor --wait"
}

实现 Ctrl+G 开 VS Code，Ctrl+Alt+G 开 Cursor，一键切换。

六、常见问题排查
  1. 按 Ctrl+G 没反应/直接提交空内容
    • 原因：未加 --wait 参数，编辑器打开后 Claude 直接继续执行
    • 解决：在环境变量中添加 --wait，重启终端
  2. 提示找不到编辑器命令
    • 原因：编辑器未添加到系统 PATH
    • 解决：VS Code 安装时勾选「添加到 PATH」，Cursor 同理
  3. Windows 路径带空格报错
    • 原因：路径包含空格（如 Program Files）
    • 解决：用引号包裹路径，如 "C:\Program Files\Notepad++\notepad++.exe" --wait

跳过所有检测权限

编辑完成后关掉编辑框，会自动把编辑器内容加载到终端，会将计划以及完成计划的一些要求列到终端并给出选项

这三个选项是你在规划模式下确认方案后 ，Claude 提供的「方案落地执行方式」，核心区别在于文件修改的权限控制，完全对应你之前了解的三种工作模式。

1️⃣ Yes, and auto-accept edits (shift+tab)

翻译：确认方案，并且自动接受所有修改（快捷键 Shift+Tab）

  • 核心行为 ：直接开启自动模式（Accept Edits On）
    • Claude 会完全自动执行方案，直接修改、新增、删除文件，全程不弹窗、不询问你确认
    • 相当于「一键执行完整方案」，效率拉满
  • 适用场景 ：
    • 你完全信任方案，没有风险点
    • 批量重构、快速迭代、已知安全的小改动
    • 不想手动点确认，追求极致效率
  • 风险提示：⚠️ 核心项目、未备份代码不建议用，避免误改关键逻辑

2️⃣ Yes, and manually approve edits

翻译：确认方案，并且手动审核每一次修改

  • 核心行为 ：保持默认模式（Default Mode）
    • Claude 会按方案执行修改，但每一次文件改动都会弹出确认框，你必须手动点「同意」才会生效
    • 完全可控，每一步都能检查
  • 适用场景 ：
    • 日常开发、核心项目、改 Bug、加新功能
    • 方案复杂、有风险点，需要逐行审核改动
    • 90% 工业视觉/Qt 开发的首选，最稳妥
  • 优势：零误改风险，完全掌控代码改动

3️⃣ Type here to tell Claude what to change

翻译：在这里输入，告诉 Claude 需要调整的内容

  • 核心行为 ：不执行任何修改 ，回到对话模式
    • 你可以直接输入指令，让 Claude 调整方案、修改细节、补充逻辑
    • 比如：「把相机采集部分改成海康 MVS SDK 实现」「优化错误处理逻辑」「拆分这个大函数」
  • 适用场景 ：
    • 方案有瑕疵、需要调整
    • 想补充需求、优化细节
    • 不确定方案是否完全符合预期，先调整再执行
  • 优势：零风险，灵活调整方案，避免走弯路

三个选项对比速查表

选项 对应模式 核心权限 适用场景 风险等级
1. 自动接受修改 自动模式 全自动改文件，无需确认 信任方案、批量重构、快速迭代 ⭐⭐⭐ 高（需谨慎）
2. 手动审核修改 默认模式 改前必问，逐次确认 日常开发、核心项目、复杂方案 ⭐ 最低（最安全）
3. 输入调整方案 规划模式 只聊不改，灵活调整 方案优化、需求补充、细节调整 ⭐ 零风险
  • 给你（工业视觉/Qt 开发）的最佳选择建议
  1. 90% 场景选 2（手动审核）：改 Bug、加功能、优化代码，每一步都可控，避免误改相机采集、AI 推理等核心逻辑
  2. 批量重构/大版本迭代选 1（自动接受） ：比如统一改命名、批量加日志，开自动模式效率拉满，改完记得用 git diff 检查
  3. 方案有问题/想调整选 3（输入调整）：先让 Claude 优化方案，确认完全符合需求后，再切手动/自动模式执行
  • 📊 三种模式对比速查表
模式 核心权限 适用场景 风险等级
默认模式 改前必问 日常开发、改 Bug、小功能 ⭐ 最低（最安全）
自动模式 自动改文件 批量重构、快速迭代、信任AI ⭐⭐⭐ 高（需谨慎）
规划模式 只聊不改 方案构思、架构设计、需求讨论 ⭐ 零风险

（工业视觉/Qt开发）的最佳使用建议

  1. 日常开发 90% 用「默认模式」：改 Bug、加功能、优化代码，每一步都可控，避免误改核心逻辑。
  2. 批量重构/大版本迭代用「自动模式」：比如统一改命名、批量加日志，开自动模式效率拉满，改完记得 git diff 检查。
  3. 项目重构/新功能设计用「规划模式」：先让 AI 出完整方案、架构图、代码框架，确认没问题再切默认模式落地，避免走弯路。
  4. 快捷键切换 ：Claude Code 里可以用快捷键快速切换（默认 ? 看快捷键列表），不用手动点按钮。

确认执行计划后，执行计划中会有以下提示

这个询问提示是对终端命令的执行询问，与前面询问claude本身操作不同,可能下次执行不同命令也会询问。也可以配置他自己执行，不在询问。

--dangerously-skip-permissions 是 Claude Code 的最高权限模式（Bypass / YOLO 模式） ，会完全跳过所有权限确认，让 AI 自动执行所有读写、删改、命令操作。下面给你完整解释 + 所有安全/灵活的配置方式。

一、--dangerously-skip-permissions 到底是什么

1. 核心含义
  • 字面：危险地跳过权限检查
  • 行为 ：
    • 所有文件读写、编辑、删除 → 自动执行，不弹窗
    • 所有 Bash/Shell 命令 → 自动执行，不确认
    • 网络、Git、构建等工具 → 无限制使用
  • 视觉提示 ：启动后显示 WARNING: Claude Code running in Bypass Permissions mode
  • 官方定位 ：仅用于隔离环境 （Docker、沙箱、无外网 CI），不建议在本地开发机长期使用
2. 适用场景（仅这些情况用）
  • 批量重构、全量代码替换（已备份）
  • 自动化脚本、CI/CD 无人值守
  • 沙箱/容器内的原型开发
  • 完全信任 AI、无敏感代码的临时任务
3. 风险（必须牢记）
  • 静默删除关键文件（如 .git、CMakeLists.txt、main.cpp）
  • 误执行高危命令（rm -rf、sudo、ssh）
  • 泄露 .env、密钥、API 凭证
  • 覆盖未提交的本地修改

二、启动方式（3 种）

1. 命令行单次启动（最常用）
bash 复制代码 
# Linux/macOS
claude --dangerously-skip-permissions

# Windows PowerShell
claude --dangerously-skip-permissions
  • 仅当前会话生效，关闭终端即失效
2. 会话内切换（无需重启）

在 Claude Code 聊天框输入：

复制代码 
/yolo
  • 立即进入免确认模式（YOLO = You Only Live Once）
  • 输入 /mode 可查看当前模式
3. 永久别名（快速调用）
Linux/macOS（~/.zshrc / ~/.bashrc）
bash 复制代码 
# 别名：clauded = dangerously mode
alias clauded="claude --dangerously-skip-permissions"

执行 source ~/.zshrc 后，直接用 clauded 启动免确认模式

Windows（PowerShell 配置文件）
powershell 复制代码 
# 编辑 $PROFILE
notepad $PROFILE

# 添加
function clauded { claude --dangerously-skip-permissions @args }

重启 PowerShell 后，clauded 生效

三、更安全的替代方案（推荐）

1. Auto 模式（智能自动，比 YOLO 安全）

  • 自动执行安全操作 （如小范围编辑、git status）

  • 拦截高危操作（批量删除、敏感文件、未知命令）

  • 仅风险操作才弹窗确认

  • 启动方式：

    bash 复制代码 
    claude --permission-mode auto

    或会话内输入 /auto

2. Accept Edits 模式（手动审核，默认安全）

  • 每一次文件修改、命令执行都必须手动确认

  • 工业视觉/Qt 开发首选，零误改风险

  • 启动：

    bash 复制代码 
    claude --permission-mode acceptEdits

    或按 Shift+Tab 切换

3. Plan 模式（先规划再执行，最稳妥）

  • 先输出完整方案，你确认后再执行

  • 适合复杂重构、架构调整

  • 启动：

    bash 复制代码 
    claude --permission-mode plan

四、精细化权限配置（settings.json，最灵活）

1. 配置文件路径
  • 全局（所有项目）：~/.claude/settings.json（Linux/macOS）/ %USERPROFILE%\.claude\settings.json（Windows）
  • 项目级（仅当前项目）：./.claude/settings.json
2. 核心配置示例（直接复制）
方案A：安全自动（推荐日常开发）
json 复制代码 
{
  "permissions": {
    "initialPermissionMode": "acceptEdits",
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Glob",
      "Grep",
      "Bash(git:*)",
      "Bash(make:*)",
      "Bash(qmake:*)",
      "Bash(cmake:*)"
    ],
    "deny": [
      "Rm",
      "Ssh",
      "Sudo",
      "Read(./.env)",
      "Read(./secrets/**)",
      "Read(./build/**)"
    ]
  }
}
  • 允许：读写编辑、搜索、Git、Make、CMake、Qt 构建
  • 拒绝：删除、远程、管理员、敏感文件、构建目录
方案B：完全免确认（仅沙箱用）
json 复制代码 
{
  "permissions": {
    "initialPermissionMode": "bypassPermissions",
    "skipDangerousModePermissionPrompt": true
  }
}
  • 永久开启 YOLO 模式，启动不提示风险
方案C：仅允许读取（最安全）
json 复制代码 
{
  "permissions": {
    "initialPermissionMode": "acceptEdits",
    "allow": ["Read", "Glob", "Grep"],
    "deny": ["Write", "Edit", "Bash"]
  }
}
  • 只能看，不能改，适合代码审查、文档生成
3. 常用权限规则
  • Read(path)：允许读取指定路径
  • Write(path)：允许写入
  • Edit(path)：允许编辑
  • Bash(cmd:*)：允许执行某类命令（如 Bash(git:*)）
  • deny：黑名单，优先级最高

五、模式对比速查表

模式 命令/配置 权限 风险 适用场景
Bypass/YOLO --dangerously-skip-permissions / /yolo 全自动，无确认 ⭐⭐⭐⭐⭐ 极高 沙箱、批量重构、CI
Auto --permission-mode auto / /auto 智能自动，拦截高危 ⭐⭐ 中 日常开发、中等复杂度
Accept Edits --permission-mode acceptEdits / Shift+Tab 手动审核每一步 ⭐ 最低 工业视觉/Qt 核心开发
Plan --permission-mode plan 先规划再执行 ⭐ 最低 复杂重构、架构调整

六、给你的最佳实践（工业视觉/Qt 开发）

  1. 日常开发 ：用 Accept Edits（Shift+Tab），每一步手动确认
  2. 批量修改 ：先备份 → 临时用 /yolo → 改完立即 git diff 检查
  3. 敏感项目 ：用 settings.json 精细化配置，禁用 rm、sudo、.env 访问
  4. 绝对不推荐 ：在本地开发机永久开启 --dangerously-skip-permissions

后台任务管理

主要命令完成后，claude code想运行程序查看效果，并询问你，这里先拒绝。

他会问你接下来应该做什么

可以让他先完成计划

完成后可以在命令行状态下自行运行程序，但此时claude是阻塞状态，无法处理新的请求

按住ctrl+b，转后台

输入/tasks 可以查看这个任务，按K可以关掉这个程序，Esc回到对话终端

多模态与上下文管理

版本回滚

我们可以添加一个新功能也会实时更新程序中去。

如果此时你发现此功能没有用，可以回滚此任务。使用/rewind命令，或者按两下Esc，进入回滚页面，每发布一个任务claude会创建一个回滚点

按上下键选择回滚点，选好按回车确认，会出现下面选项

选择你想回滚的选项

影响范围说明

  • The conversation will be forked.：对话会被「分叉」
    • 回滚后会生成一个全新的对话分支，原对话历史会被保留，不会丢失，方便你随时切回去。
  • The code will be restored +17 -65 in Header.tsx and 6 other files.：代码回滚详情
    • +17：恢复 17 行新增的代码（撤销删除）
    • -65：删除 65 行新增的代码（撤销新增）
    • 涉及文件：Header.tsx 以及另外 6 个文件（比如多语言配置、组件逻辑等）
    • 本质：把这些文件完全恢复到你发指令前的版本，相当于没改过。

4 个选项的详细区别（核心）

选项 核心作用 代码是否回滚 对话是否回滚 适用场景
1. Restore code and conversation（默认选中） 「代码+对话」双回滚 ✅ 完全恢复到发指令前 ✅ 对话回到发指令前，分叉新分支 90% 场景首选：AI 改崩了代码，想完全撤销，回到之前的状态
2. Restore conversation 仅回滚对话 ❌ 代码保持当前修改 ✅ 对话回滚，分叉新分支 你觉得代码改得还行，但对话上下文乱了，想重新基于当前代码聊新需求
3. Restore code 仅回滚代码 ✅ 代码完全恢复 ❌ 对话保持当前历史 你想保留对话记录（比如后续参考），但代码必须还原，不影响聊天上下文
4. Never mind 取消回滚 ❌ 不做任何操作 ❌ 不做任何操作 手滑点了回滚，不想撤销，直接退出

给你（前端/多语言开发）的最佳选择建议

  1. AI 改崩了代码，想完全重来 ：选 1（双回滚）
    • 直接把代码和对话都还原，相当于「这条指令没发过」，最干净、最稳妥。
  2. 代码改得还行，但对话上下文乱了 ：选 2（仅回滚对话）
    • 保留你已经改好的多语言切换功能，只是把对话重置，重新基于当前代码聊新需求。
  3. 想保留对话记录，只还原代码 ：选 3（仅回滚代码）
    • 比如你想对比改前改后，或者后续再基于原对话优化，只把代码还原，不丢聊天记录。
  4. 手滑误触 ：选 4（取消）

1. 「对话分叉」是什么意思？

  • 回滚后，Claude 会把当前对话复制一份，在新分支里执行回滚操作。
  • 原对话会完整保留在历史中，你随时可以切回去看之前的修改，不会丢失任何内容，完全安全。

2. 回滚的本质

  • 不是删除文件，而是把文件的内容恢复到指定时间点 ，和 Git 的 git reset --hard 效果类似，但只针对 Claude 自己做的修改，不会影响你手动改的代码。
  • 回滚前会自动备份，不用担心误操作找不回来。

当你回滚到最原始版本时会发现项目目录下还存在执行任务存在的文件，因为claude只会回滚自己的操作，不会回滚命令行执行命令产生的文件，建议不要过于依赖回滚操作，精确回滚可以使用git。

需要手动删除残留文件

图片处理

关于程序的界面设计可以使用图片进行处理。将设计好的UI界面导出为图片传给claude.

一、核心原理

Claude Code 会先解析图片中的 UI 布局、组件、配色、交互逻辑，再结合你指定的技术栈（React/Vue/Qt/QML/Flutter 等），生成符合工程规范的可运行代码，同时自动适配响应式、多语言、组件化等要求。

二、完整操作流程（4 步走）

步骤 1：准备高质量设计图

  • 要求：清晰、无遮挡、完整展示 UI 布局 ，包含：
    • 整体结构（导航栏、内容区、侧边栏、按钮位置）
    • 组件样式（按钮、输入框、卡片、图标）
    • 配色方案（主色、辅助色、文字颜色）
    • 交互标注（hover 效果、点击反馈、弹窗逻辑，可选）
  • 推荐：Figma 导出的高清图、UI 设计稿截图、原型图，避免模糊/裁剪的图片。
步骤 2：在 Claude Code 中上传图片
  • 直接在 Claude Code 聊天框拖拽图片 ，或用 /image 命令上传
  • 上传后 Claude 会自动解析图片内容，你只需要补充指令即可
步骤 3：发送专属 Prompt（核心！直接复制用）

下面是为你定制的工业视觉/前端 UI 专属 Prompt，适配 React/Qt/QML 等技术栈，直接粘贴在图片后发送：

复制代码 
根据我提供的 UI 设计图，生成完整可运行的代码。
【技术栈】：请指定（如 React + TypeScript + Tailwind CSS / Qt 5.15 QML / Vue 3 + Element Plus）
【要求】：
1. 1:1 还原设计图的布局、组件、配色、字体、间距，像素级对齐
2. 代码模块化、组件化，单一职责，可直接编译运行
3. 完整的交互逻辑：按钮点击、输入框验证、hover 效果、响应式适配
4. 多语言支持（中文/英文切换，默认中文），符合国际化规范
5. 错误处理完整，无冗余代码，无幻觉，不编造不存在的 API
6. 输出完整代码 + 关键说明（组件结构、样式说明、运行方法）
7. 若涉及 Qt，需符合 Qt 开发规范，使用 Qt Quick Controls 2，适配桌面端
8. 附带 1 个可直接运行的示例入口文件

现在根据图片生成代码：
步骤 4：迭代优化

  • 第一次生成后，若有细节偏差（如按钮位置不对、配色不准），直接发送：

    复制代码 
    对比设计图，修正以下问题：
1. 导航栏高度调整为 64px，图标间距 16px
2. 主按钮主色改为 #1677ff，hover 效果 #4096ff
3. 补充响应式适配，移动端自动折叠侧边栏

  • Claude 会自动修正代码，保持结构不变，只改细节

三、分技术栈专属 Prompt 模板（直接复制）

1. 前端 React/TypeScript + Tailwind（最常用）
复制代码 
根据 UI 设计图，生成 React + TypeScript + Tailwind CSS 代码，1:1 还原布局、配色、组件。
要求：
- 组件化拆分，可直接在 Vite/Create React App 中运行
- 完整的交互逻辑，响应式适配桌面/移动端
- 多语言切换功能（i18next 实现）
- 代码规范，注释简洁，无冗余
- 输出完整代码 + 依赖安装命令 + 运行说明
2. Qt QML（工业视觉桌面端 UI 专属）
复制代码 
根据 UI 设计图，生成 Qt 5.15 QML 代码，适配 Windows 桌面端，1:1 还原设计。
要求：
- 使用 Qt Quick Controls 2，符合 Qt 开发规范
- 完整的界面布局、组件样式、交互逻辑（按钮点击、弹窗、数据绑定）
- 多语言支持（Qt Linguist 国际化）
- 代码可直接编译运行，附带 main.cpp 入口文件
- 模块化拆分，便于后续维护
3. Vue 3 + Element Plus（后台管理 UI）
复制代码 
根据 UI 设计图，生成 Vue 3 + Element Plus 代码，1:1 还原设计。
要求：
- 组件化，符合 Vue 3 组合式 API 规范
- 完整的路由、状态管理（Pinia 可选）
- 响应式适配，多语言切换
- 可直接在 Vite 项目中运行，附带依赖说明

四、进阶技巧（提升还原度）

1. 补充设计细节（避免 AI 脑补）

在 Prompt 中补充图片中不明显的细节，比如：

  • 「导航栏固定在顶部，滚动不消失」
  • 「按钮点击有波纹效果，弹窗从右侧滑入」
  • 「表格支持排序、筛选，分页每页 10 条」
  • 「主色 #2563eb，辅助色 #10b981，文字色 #1f2937」
2. 先出方案再写代码（规划模式）

先开启规划模式，让 AI 先输出 UI 架构方案，再生成代码：

复制代码 
先分析设计图的 UI 结构、组件、交互，输出详细的实现方案（分层、组件拆分、技术选型），确认后再生成代码。

避免直接生成代码出现结构错误，适合复杂 UI。

3. 分模块生成（大界面）

若 UI 非常复杂（如工业视觉检测系统主界面），分模块生成：

  • 第一步：生成导航栏 + 侧边栏
  • 第二步：生成内容区 + 表格
  • 第三步：生成弹窗 + 交互逻辑
  • 最后让 AI 整合为完整项目，避免上下文溢出
4. 用 diff 模式修改

生成代码后，用diff 模式修改细节，避免全量重写：

复制代码 
对比设计图，修正以下问题，只输出 diff 格式，不要全量代码：
1. 调整按钮位置
2. 修改配色
3. 补充交互

五、避坑指南（关键！）

  1. 避免模糊/裁剪的图片：会导致 AI 解析错误，还原度大幅下降
  2. 必须指定技术栈：否则 AI 会随机生成，不符合你的项目要求
  3. 加「像素级对齐」约束：强制 AI 严格还原设计，避免自由发挥
  4. 开启默认模式：生成代码前手动确认，避免误改现有项目
  5. 用规划模式先出方案：复杂 UI 先确认架构，再写代码，避免返工
  6. 补充多语言/响应式要求：工业视觉项目常用，提前在 Prompt 中指定

六、实际应用示例（工业视觉 UI）

场景：根据设计图生成「工业缺陷检测系统主界面」

  • 上传设计图（包含：导航栏、相机控制区、图像显示区、检测结果区、参数设置区）

  • 发送 Prompt：

    复制代码 
    根据设计图，生成 Qt 5.15 QML 代码，1:1 还原工业缺陷检测系统主界面。
要求：
- 模块化拆分，CameraControl.qml、ImageDisplay.qml、ResultPanel.qml 等
- 完整的交互逻辑：相机启动/停止、图像缩放、检测按钮点击、结果显示
- 多语言支持（中文/英文切换）
- 可直接编译运行，附带 main.cpp 和 CMakeLists.txt
- 符合 Qt 工业视觉开发规范，适配 1920*1080 分辨率

  • Claude 会直接生成完整的 Qt 项目代码，包含所有组件、交互、国际化，直接编译运行。

七、配套工具推荐

  • Figma：导出高清设计图，标注交互细节
  • Mermaid：让 AI 生成 UI 架构图，先确认结构再写代码
  • Git：生成代码前提交当前版本，方便回滚
  • Claude Code 回滚功能：若生成代码不符合预期，一键回滚，重新生成

安装MCP Server

claude很难通过图片精确还原设计的UI，这里就会用到 MCP Server来还原Figma设计

在终端执行这个命令: claude mcp add --transport http figma https://mcp.figma.com/mcp

安装完成后再重新打开claude 终端对话框

但是此时是一个新的会话，之前的历史会话没有了

MCP Server 全称 Model Context Protocol Server （模型上下文协议服务端），是 Anthropic 推出的标准化服务端组件，核心作用是作为 AI 模型（客户端）与外部系统之间的桥梁，统一封装并暴露工具、资源与提示模板，让大模型能安全、标准化地访问外部能力。

一、核心定位与原理

  • 协议基础：基于 JSON-RPC 2.0 实现，是 MCP 协议体系的服务端实现。
  • 角色：被动响应式能力工具箱，不具备推理能力，仅负责接收客户端请求、转发至外部并返回结果。
  • 类比：如同 AI 生态的"USB 接口"，让大模型像外接设备一样快速接入文件、数据库、API 等外部资源。
  • 通信方式：支持 STDIO（标准输入输出）、SSE（Server-Sent Events）等传输层，实现双向 JSON-RPC 消息通信。

二、核心功能（三大能力）

功能 说明 典型场景
工具调用 封装外部可执行操作，提供统一接口 调用天气 API、发送邮件、执行数据库查询、控制设备
资源访问 标准化读取/写入外部资源（URI 模式） 访问本地文件、企业内部数据库、云存储、知识库
提示模板 管理与分发预定义提示词，提升任务效率 代码补全、数据分析、UI 设计生成的标准化提示
能力协商 与客户端声明支持的工具/资源，确保兼容性 动态适配不同 AI 客户端的功能需求

三、典型应用场景

  1. 智能办公：连接邮件、日历、文档系统，自动生成会议纪要、分类邮件、编辑文档。
  2. 企业系统集成：对接 CRM、ERP、OA 等内部系统，让 AI 查询订单、更新状态，无需上传敏感数据。
  3. 开发工具增强：在 VS Code、Cursor 中访问 Git 历史、运行测试、调用 CI/CD 管道。
  4. 工业/物联网：连接工业相机、传感器、检测系统，让 AI 监控设备状态、分析检测结果。
  5. 实时信息检索：调用新闻 API、物流接口，获取最新资讯、查询快递状态。

四、与传统 API 调用的区别

  • 标准化：统一协议与接口，无需为每个工具开发专属 API。
  • 安全可控：支持权限管理与授权机制，限制外部操作范围。
  • 轻量化：独立部署，不侵入 AI 模型内核，便于扩展与维护。
  • 双向通信：支持主动推送通知（如日志、事件），提升交互实时性。

五、开发与部署要点

  1. 技术栈：支持 Python、Java、Node.js 等，提供官方 SDK 快速开发。
  2. 核心步骤 ：
    • 定义工具/资源接口（遵循 MCP 规范）。
    • 实现业务逻辑（对接外部系统）。
    • 配置传输层（STDIO/SSE）与启动服务。
    • 与 AI 客户端（如 Claude）建立连接。
  3. 安全实践：严格控制权限范围、输入校验、日志审计，避免越权操作。

六、对你的实际价值

作为工业视觉/AI 开发者，MCP Server 可帮你：

  • 快速集成海康相机 SDK、检测算法等工具，让 AI 直接控制相机、触发检测。
  • 暴露本地检测结果数据库、配置文件，让 AI 辅助分析数据、生成报告。
  • 封装 UI 设计生成、代码调试等工具，提升开发效率。

总结

MCP Server 是连接 AI 与现实世界的标准化枢纽，通过统一协议解决了外部工具对接碎片化问题，是 AI Agent、智能助手落地的核心基础设施。

恢复历史会话

使用/resume命令 ，来选择历史会话

或者在进入claude时 带上参数-c

bash 复制代码 
claude -c

Claude（主要指 Claude Code/CLI 版本）恢复历史会话主要有 3 种常用方式，分别对应快速续聊、选特定会话和网页版场景，能覆盖终端中断、多任务切换等需求。

🔧 核心恢复方式（按场景选）

场景 命令/操作 效果 适用
快速续最近会话 claude -c 或 claude --continue 自动恢复最近一次会话的完整上下文，直接续聊 刚关终端、短暂中断，不想选列表
选历史会话 claude -r 或 claude --resume 弹出交互式列表，用上下键选会话后恢复 终端重启、跨天任务、需选特定会话
网页/桌面端 左侧会话列表直接点击；或输入指令如"继续之前关于XX的会话" 加载对应会话历史 网页/桌面版，无需命令行

📝 详细操作步骤

  1. 快速续最近会话（CLI）

    打开终端，进入原工作目录，执行：

    bash 复制代码 
    claude -c  # 简写
# 或
claude --continue  # 完整写法

    Claude 会自动加载最近会话的上下文（含文件状态、对话历史），直接续聊。

  2. 选历史会话（CLI，最常用）

    终端执行：

    bash 复制代码 
    claude -r  # 简写
# 或
claude --resume  # 完整写法

    终端会列出历史会话（含标题、时间戳、消息数），用 ⬆️/⬇️ 键选中，按 Enter 即可恢复。

    小技巧：可加关键词过滤，如 claude -r Qt 快速筛选相关会话。

  3. 网页/桌面端恢复

    • 打开 Claude 网页/桌面应用，左侧边栏会显示所有历史会话，直接点击即可恢复。
    • 若会话较多，可在输入框自然提问搜索，如："继续之前关于工业视觉UI设计的会话"。

⚠️ 注意事项

  1. 存储位置：Claude Code 会话历史默认保存在本地，不会丢失；终端重启/电脑断电后仍可恢复。
  2. 会话隔离：不同任务建议用独立会话，避免上下文混乱。
  3. 恢复范围：恢复时会加载完整对话历史和文件状态，无需重新解释需求。
  4. 网页版限制：付费版（Pro/Team/Enterprise）支持搜索历史会话，免费版需手动在列表查找。

🚀 进阶技巧

  • /rewind 指令 ：在会话中输入 /rewind，可回退到对话任意节点，恢复对应文件状态和上下文，适合调试回滚。
  • 会话命名 ：用 /rename 新标题 给会话命名，方便 --resume 时快速识别。

Claude 会话本地存储路径 或 如何清理 / 备份历史会话

1. Claude 会话本地存储路径（Windows）

Claude Code（CLI 版）的历史会话、配置、缓存全部在这里：

复制代码 
%USERPROFILE%\.claude\

复制到文件管理器地址栏直接打开：

复制代码 
C:\Users\你的用户名\.claude\

里面关键目录：

  • sessions/ → 所有历史会话（最重要）
  • settings.json → 权限、编辑器、快捷键配置
  • cache/ → 缓存

2. 备份会话（超级简单）

直接复制整个 .claude 文件夹 即可备份所有：

  • 所有会话历史
  • 所有配置
  • 所有快捷键/编辑器设置

备份命令（PowerShell）：

powershell 复制代码 
Copy-Item -Recurse "$env:USERPROFILE\.claude" "D:\backup\claude-backup-$(Get-Date -Format 'yyyyMMdd')"

3. 恢复会话（从备份还原）

把备份的 .claude 覆盖回去即可：

powershell 复制代码 
Copy-Item -Recurse "D:\backup\claude-backup-xxx\.claude" "$env:USERPROFILE\" -Force

覆盖后：

  • claude -r → 能看到所有历史会话
  • 所有配置恢复如初

4. 列出/恢复历史会话（CLI 命令）

列出所有会话
bash 复制代码 
claude --list
恢复最近一次
bash 复制代码 
claude -c
# 或
claude --continue
选择历史会话恢复（最常用）
bash 复制代码 
claude -r
# 或
claude --resume

会弹出列表，方向键选择 → 回车恢复。

按关键词筛选恢复
bash 复制代码 
claude -r Qt
claude -r UI
claude -r 缺陷检测

5. 清理会话（不想要的删掉）

删除所有会话（谨慎）
powershell 复制代码 
Remove-Item "$env:USERPROFILE\.claude\sessions\*" -Recurse
删除单个会话

进入 sessions/ 文件夹，删除对应时间戳目录即可。

🔥 精简总结（记这 3 句就够）

  1. 会话存在：%USERPROFILE%\.claude\sessions
  2. 备份：复制整个 .claude
  3. 恢复：claude -r 选会话

使用MCP工具还原设计稿

恢复会话后，输入/mcp命令查看目前安装的MCP工具

按照指导提示进行授权完成后，就是可用状态了，有些工具可以自己用（需要学习）也可以让claude自行判断。

回到对话界面，输入新需求要求claude完成与figma稿件对齐，此时需要你的figma稿件连接

执行过程中claude就会发现可以使用MCP，完成任务，同意等待完成即可。

上下文压缩与清除

/compact 命令

Claude（主要是 Claude Code CLI 版 ）的上下文压缩与清除，核心靠 /compact（压缩） 、/clear（清空） 两个命令，配合 /context（查看占用） 管理，能精准控制 token 消耗、避免上下文溢出、提升响应速度。

一、核心命令速览（直接用）

命令 作用 适用场景
/context 查看当前上下文占用（可视化） 不确定是否该压缩/清空时先查
/compact 自动压缩对话为摘要，保留关键信息 对话长、token 高、不想开新会话
/compact 保留XX 带聚焦的压缩，指定重点保留内容 需保留特定模块/代码/决策
/clear 清空当前会话所有历史，从头开始 切换完全无关任务、彻底重置

二、详细用法与实操

1. 查看上下文占用（先看再操作）

在 Claude 会话内输入：

bash 复制代码 
/context

会显示：

  • 对话历史占用
  • 引用文件占用
  • 工具结果占用
  • 整体 token 百分比（直观判断是否需要压缩）
2. 上下文压缩 /compact（最常用）
（1）基础压缩（自动）
bash 复制代码 
/compact
  • 效果：把长对话自动压缩成精简摘要，保留核心代码、决策、文件状态，删掉调试细节、重复讨论、无效输出。
  • 特点：不删除原始会话记录 （仍在 .claude/sessions），只压缩内存中的上下文，释放 token 空间。
（2）带聚焦的压缩（精准保留）
bash 复制代码 
# 示例1：保留数据库相关代码与配置
/compact 重点保留数据库连接、SQL 语句与配置文件修改

# 示例2：保留 API 接口定义
/compact 只保留 RESTful API 路由、参数与返回格式

# 示例3：保留核心文件改动
/compact 保留所有修改过的文件列表与关键代码块
  • 作用：让 Claude 压缩时不丢你指定的关键信息，避免自动压缩误删重要内容。
（3）局部压缩（从某节点开始）
  • 先输入 /rewind 或按 Esc+Esc，选择要回退的消息节点
  • 选择 Summarize from here
  • 效果：只压缩该节点之后的内容，之前的上下文完整保留。
3. 上下文清除 /clear（彻底重置）
bash 复制代码 
/clear
  • 效果：立即清空当前会话所有对话历史，内存上下文归零，相当于新开一个干净会话。
  • 适用：
    • 切换到完全无关的新任务（如从后端开发切到 UI 设计）
    • 之前上下文混乱、干扰新任务
    • 彻底释放所有 token 空间

三、最佳实践（避免踩坑）

  1. 主动压缩，别等自动
    • 上下文占用 > 70% 时，主动 /compact，避免自动压缩丢失关键信息。
  2. 压缩+聚焦，更可控
    • 长对话后，用 /compact 保留XX 明确重点，比默认压缩更稳。
  3. 任务切换用 /clear
    • 不同任务（如开发→调试→文档），先 /clear 再开始，避免上下文污染。
  4. 大任务拆分会话
    • 把长任务拆成多个独立会话（如"需求→设计→编码→测试"），每个会话 /clear 后开始，彻底避免上下文膨胀。
  5. 压缩后可查看
    • 按 Ctrl+O 可查看压缩后的上下文摘要，确认关键信息是否保留。

四、常见问题

  • 压缩后还能恢复原始对话吗？
    可以。/compact 只压缩内存上下文，原始会话文件仍在 .claude/sessions ，用 claude -r 恢复即可看到完整历史。
  • /clear 会删除本地会话吗？
    不会。/clear 只清空当前内存会话，本地 .claude/sessions 里的记录依然存在。
  • 自动压缩 vs 手动 /compact？
    • 自动：上下文快满时触发，可能丢失细节
    • 手动：可控、可指定保留内容，推荐优先用

五、极简工作流（记这3步）

  1. 查占用：/context
  2. 长对话：/compact 保留XX
  3. 换任务：/clear

Claude 上下文管理命令速查表

一、核心基础命令（必记）

命令 简写/补充 核心效果 适用场景
/context 无 查看当前上下文占用（token、文件、对话占比，可视化显示） 不确定是否需要压缩/清空，先查占用
/compact 无 自动压缩对话为摘要，保留核心代码、决策、文件状态，释放 token 对话较长、token 偏高，不想开新会话
/clear 无 清空当前会话内存上下文，从头开始（不删本地会话文件） 切换无关任务、上下文混乱、彻底重置
/rewind 快捷键：Esc+Esc 回退到对话任意节点，可选择"从该节点总结"或"重置到该节点" 想撤销某几步操作、局部压缩上下文

二、进阶压缩命令（精准可控）

命令示例 核心效果 适配场景（工业视觉/Qt 开发）
/compact 保留 Qt 代码与相机配置 压缩时优先保留指定内容，删除无关调试、冗余讨论 开发 Qt 界面、相机控制逻辑，避免压缩误删核心代码
/compact 只保留缺陷检测算法代码 聚焦核心业务代码，压缩掉无关的文档、交互讨论 工业视觉算法开发，专注代码逻辑，减少 token 消耗
/rewind → 选节点 → Summarize from here 只压缩该节点之后的内容，之前上下文完整保留 前面的代码/方案无误，只想压缩后续的调试、修改记录

三、会话恢复与上下文关联命令

命令 简写 核心效果 关联上下文说明
claude --continue claude -c 恢复最近会话，加载完整上下文（对话+文件状态） 恢复后上下文直接可用，无需重新输入需求
claude --resume claude -r 弹出历史会话列表，选择后恢复对应上下文 可筛选关键词（如 claude -r Qt），精准恢复目标会话
/rename 会话标题 无 给当前会话命名，方便后续 resume 时识别 命名建议：Qt 相机界面开发、缺陷检测算法调试

四、常用组合用法（高效工作流）

  • 查看占用 → 压缩（聚焦）：/context → /compact 保留 Qt 代码

  • 回退纠错 → 压缩：/rewind（选节点）→ Summarize from here

  • 切换任务：/clear → 新需求（彻底避免上下文污染）

  • 恢复会话 → 清理冗余：claude -r（选会话）→ /compact

五、关键注意事项（避坑）

  1. /compact 仅压缩内存上下文，原始会话记录仍在 ~/.claude/sessions，可恢复；

  2. /clear 仅清空当前内存会话，不删除本地会话文件，用 claude -r 可重新加载；

  3. 上下文占用＞70% 时，建议主动压缩，避免自动压缩丢失关键代码/配置。

（注： Claude 上下文管理命令速查表 此部分内容由 AI 生成）

项目记忆文件

/init 创建CLAUDE.md文件

Claude（尤其是 Claude Code）的项目记忆文件是实现「跨会话长期记忆」的核心工具，通过本地 Markdown 文件持久化存储项目规则、技术栈、业务逻辑等关键信息，让 AI 无需重复沟通就能精准适配项目需求。以下是从文件类型、配置、使用到维护的完整指南，新手也能快速上手。

一、核心概念：项目记忆文件的本质与分类

Claude 的记忆文件本质是「结构化的 Markdown 配置文件」，按存储位置和用途分为两类核心文件，同时支持多层级优先级加载，确保信息精准生效：

1. 手动维护文件（用户编写，主动控制）
文件名称 存储位置 作用范围 核心用途
CLAUDE.md 项目根目录或 .claude/claude.md 团队共享（可提交 Git） 记录项目公共规则：架构概览、技术栈版本、编码规范、核心工作流等
CLAUDE.local.md 项目根目录 个人专用（自动入 Git 忽略） 存储私人配置：测试环境地址、个人编码习惯、隐私信息（如沙箱 URL）
*.md（规则文件） .claude/rules/ 目录下（支持多文件） 项目模块化规则 按主题拆分指令：语言特定规范、API 调用规则、测试 conventions 等
全局 claude.md ～/.claude/claude.md（用户主目录） 所有项目通用 个人跨项目偏好：统一代码风格、交互习惯（如"解释代码简洁化"）
2. 自动维护文件（Claude 生成，被动记录）
文件名称 存储位置 作用范围 核心用途
MEMORY.md ～/.claude/projects/<项目路径>/memory/ 当前项目 自动记录会话中关键信息：项目决策、代码变更、遗留问题（索引文件，启动时加载）
*.md（主题文件） 同 MEMORY.md 目录下 当前项目 按主题拆分自动记忆内容，按需加载（如"数据库配置记忆""接口设计记忆"）
3. 加载优先级（从高到低，避免冲突）
  1. 企业级策略文件（如 Windows：C:\Program Files\Claude Code\claude.md）→ 组织强制规范
  2. 全局用户文件（～/.claude/claude.md）→ 个人跨项目偏好
  3. 项目共享文件（项目根目录 CLAUDE.md 或 .claude/claude.md）→ 团队公共规则
  4. 模块化规则文件（.claude/rules/*.md）→ 项目细分规则
  5. 个人本地文件（CLAUDE.local.md）→ 私人覆盖配置
  6. 子目录文件（子目录下 CLAUDE.md）→ 局部场景规则

二、快速上手：3步配置项目记忆文件

1. 第一步：创建基础记忆文件（项目级）

在项目根目录执行以下操作，快速搭建核心记忆文件：

bash 复制代码 
# 1. 创建项目共享记忆文件（团队协作用）
touch CLAUDE.md

# 2. 创建个人本地记忆文件（私人配置用）
touch CLAUDE.local.md

# 3. 创建模块化规则目录（大型项目用）
mkdir -p .claude/rules && touch .claude/rules/coding-style.md .claude/rules/security.md
2. 第二步：写入核心内容（示例模板）

根据文件用途填写关键信息，确保 AI 快速理解项目核心：

示例1：CLAUDE.md（项目共享）
markdown 复制代码 
## 项目核心信息
- 业务目标：开发一套工业视觉缺陷检测的 API 服务，支持模型调用、结果存储与统计分析
- 技术栈：后端 Node.js v18 + Express，数据库 PostgreSQL 16，前端 React v18
- 核心路径：入口文件 src/index.js，配置文件 config/*.env，模型调用模块 src/services/model.js

## 编码规范
- 命名规则：变量用 camelCase，常量用 UPPER_SNAKE_CASE，组件用 PascalCase
- 注释要求：函数必须写 JSDoc 注释，关键业务逻辑加中文说明
- 代码风格：遵循 ESLint 规则，禁止使用 any 类型，优先使用 TypeScript 类型定义

## 工作流约定
- 开发分支：feature/xxx 分支开发，合并前需通过单元测试（npm run test）
- 部署命令：构建 npm run build，测试环境部署 npm run deploy:test
- 日志规范：所有接口请求/响应需记录日志，禁止打印用户敏感信息
示例2：CLAUDE.local.md（个人本地）
markdown 复制代码 
## 个人偏好
- 交互习惯：解释代码时先给完整示例，再补充原理说明
- 测试配置：本地测试环境 URL：http://localhost:3000/api，测试账号 admin/123456
- 工具偏好：生成代码时优先使用 async/await 语法，避免回调函数

## 隐私信息（不提交 Git）
- 数据库本地连接串：postgresql://user:password@localhost:5432/vision-db
- 第三方 API 密钥：sk_test_xxxxxxx（仅本地开发用）
示例3：.claude/rules/security.md（模块化规则）
markdown 复制代码 
## 安全红线（强制遵守）
1. 所有用户输入必须经过参数校验，防止 SQL 注入和 XSS 攻击
2. 接口访问需通过 JWT 认证，敏感接口额外校验权限角色
3. 密码存储必须使用 bcrypt 加盐哈希，严禁明文或 MD5 存储
4. 外部 API 调用必须添加超时处理（默认 5 秒）和签名验证
5. 日志禁止打印明文密码、Token 等敏感信息，敏感字段需脱敏
3. 第三步：生效记忆文件

无需额外配置，Claude 启动时会自动加载所有符合路径规则的记忆文件：

  • 验证加载：启动 Claude 后输入命令 /memory show，查看当前加载的记忆内容
  • 手动追加：无需编辑文件，直接在对话中输入 /memory add "新规则：接口返回格式必须包含 code/message/data 字段"，实时添加记忆

三、高级用法：让记忆文件更高效

1. 导入外部文件（模块化管理）

当记忆内容较多时，可通过 @ 路径 语法导入其他文件，避免单个文件过大：

markdown 复制代码 
# 在 CLAUDE.md 中导入其他规则文件
@ .claude/rules/coding-style.md  # 导入编码规范
@ .claude/rules/security.md      # 导入安全规则
@ ~/.claude/common-api.md        # 导入全局通用接口规范

# 引用说明
- 项目架构详情见 @ docs/architecture.md
- 依赖包说明见 @ package.json（Claude 会自动读取文件内容）
  • 支持相对路径（如 @ ./docs/xxx.md）和绝对路径（如 @ ~/.claude/xxx.md）
  • 导入支持递归（最大深度 5 层），可嵌套导入
2. 动态管理记忆（命令行操作）

在 Claude 会话中使用 /memory 系列命令，实时管理记忆内容，无需手动编辑文件：

命令 作用 示例
/memory show 查看当前加载的所有记忆内容 /memory show
/memory add "内容" 追加记忆（写入项目自动记忆文件） /memory add "新增规则：所有 API 支持 CORS"
/memory clear 清空当前会话加载的记忆（慎用） /memory clear
/memory edit "旧内容" "新内容" 修改记忆内容 /memory edit "Node.js v18" "Node.js v20"
3. 结合自动记忆（减少手动维护）

Claude 会自动记录会话中的关键信息到 MEMORY.md，例如：

  • 你提到的"弃用 Redux 改用 Zustand"的决策
  • 调试过程中确认的"数据库索引优化方案"
  • 团队约定的"接口版本控制规则"

查看自动记忆文件：

bash 复制代码 
# 进入自动记忆目录
cd ~/.claude/projects/$(pwd | sed 's/\//_/g')/memory/

# 查看自动记录的记忆
cat MEMORY.md

四、维护技巧：让记忆文件长期有效

1. 定期"修剪"记忆（避免信息过期）

记忆文件并非越大越好，过时信息会干扰 AI 判断，建议每 Sprint 结束后清理：

  • 删除已废弃的技术栈描述（如"原计划使用 Vue，后改为 React"需删除 Vue 相关内容）
  • 移除已完成的临时规则（如"开发阶段允许跨域，生产环境禁用"需明确当前阶段）
  • 合并重复规则（如分散在多个文件中的编码规范，统一整合到 coding-style.md）

快速清理命令：

bash 复制代码 
# 查看自动记忆文件，筛选过时信息
claude -c "请检查 ~/.claude/projects/<项目路径>/memory/MEMORY.md，列出过时信息并建议删除"
2. 避免记忆污染（关键避坑）

记忆污染是常见问题（如 AI 坚持错误的技术栈或业务规则），解决方案：

  1. 手动修正：打开对应的记忆文件（如 CLAUDE.md 或自动记忆 MEMORY.md），删除错误内容

  2. 明确告知：在对话中说明"已更新项目记忆，之前关于 XX 的描述作废，以新记忆为准"

  3. 权限保护：将核心规则文件（如 CLAUDE.md）设为只读，避免误编辑：

    bash 复制代码 
    chmod 444 CLAUDE.md  # 只读权限，需修改时用 chmod 644 恢复

  4. 交叉验证：在记忆文件中添加"验证规则"，如"回答前需核对 project_context.md 中的技术栈版本"

3. 团队协作规范
  • 共享文件（CLAUDE.md、.claude/rules/*.md）需提交 Git，供团队统一使用
  • 个人配置（CLAUDE.local.md）必须加入 .gitignore，避免隐私信息泄露
  • 新增规则时需在文件中注明修改人及日期，便于追溯（如 # 2026-03-31 新增：支持 OpenAPI 文档自动生成）

五、常见问题与解决方案

问题现象 原因分析 解决方案
AI 总是忘记项目规则（如编码规范） 规则仅在对话中提及，未写入记忆文件；或文件路径不正确 将规则写入 CLAUDE.md 或 .claude/claude.md，确保文件在项目根目录
记忆文件冲突（如全局规则与项目规则矛盾） 加载优先级导致高层级文件覆盖低层级文件 检查文件优先级，在低层级文件（如 CLAUDE.local.md）中重写规则覆盖
自动记忆文件写入错误信息（如错误技术栈） 会话中误输入信息被自动记录 手动编辑 MEMORY.md 删除错误内容，用 /memory add 写入正确信息
Token 消耗过快（记忆文件过大） 记忆文件包含重复内容或无关信息（如完整代码） 删除无关内容，仅保留核心规则；用导入语法拆分文件，避免全量加载
子目录操作时记忆不生效 子目录未创建 CLAUDE.md，父目录记忆未覆盖子场景 在子目录创建 CLAUDE.md，写入局部规则；或用导入语法引用父目录记忆

六、最佳实践总结

  1. 内容原则：只存"从文件中推断不出来的关键信息"，避免存储代码结构、Git 历史等冗余内容
  2. 结构建议 ：大型项目采用"核心文件+模块化规则"架构，小型项目直接用单一 CLAUDE.md
  3. 更新频率：技术栈变更、业务规则调整时，第一时间同步更新记忆文件，避免 AI 基于旧信息决策
  4. 验证方法：新会话启动后，先问 AI"本项目的技术栈和核心安全规则是什么？"，验证记忆是否生效
  5. 容量控制 ：自动记忆的 MEMORY.md 建议不超过 200 行，超量后及时清理，避免截断

高级功能扩展与定制

Hook

Claude（主要是 Claude Code ）中的 Hook 是一套事件驱动的本地自动化机制 ，在 AI 会话/工具调用的关键节点自动执行你预设的脚本/命令，强制、稳定、不受模型遗忘影响。

一、一句话核心定义

Hook = 你写的脚本 + 触发时机 + 匹配规则

在 Claude Code 执行特定动作（如写文件、跑 Bash、提交 Prompt）的前/后，自动执行你的命令，实现：

  • 拦截危险操作
  • 自动格式化/校验
  • 自动提交/通知
  • 强制项目规范

本质：把"靠 AI 自觉执行"变成"靠系统强制执行"。

二、核心价值（为什么要用 Hook）

  1. 稳定自动化：不受模型切换、上下文压缩、AI 遗忘影响，流程必执行。
  2. 强制规范 ：AI 必须遵守你的规则（如禁止改 .env、必须跑 Lint）。
  3. 减少重复：自动格式化、自动测试、自动提交、自动通知。
  4. 安全守卫：拦截危险命令、敏感文件操作。
  5. 审计与集成：日志、CI/CD、外部通知（企微/Slack）。

三、Hook 配置位置

Hook 写在 JSON 配置文件中，优先级同记忆文件：

  • 全局：~/.claude/settings.json
  • 项目：项目根目录 .claude/settings.json
基础配置结构
json 复制代码 
{
  "hooks": {
    "事件名": [
      {
        "matcher": "工具名/路径正则", // 匹配触发条件
        "type": "command", // 类型：command/prompt/http
        "command": "你的脚本/命令", // 要执行的内容
        "timeout": 10, // 超时（秒）
        "description": "用途说明"
      }
    ]
  }
}

四、核心事件（触发时机）

覆盖 Claude Code 全生命周期，最常用 6 种：

事件名 触发时机 典型用途
PreToolUse 调用工具前（最常用） 拦截危险命令、参数校验、权限检查
PostToolUse 工具执行成功后 自动格式化、跑测试、Git 提交、通知
PermissionRequest 弹出权限确认前 自动批准安全命令、阻止敏感操作
UserPromptSubmit 你发送 Prompt 后 注入上下文、预处理指令
Stop 会话/回复结束前 发通知、更新文档、清理环境
SessionStart 会话启动/恢复 加载环境、初始化状态

五、Hook 类型（执行方式）

1. command（默认，最常用）

执行本地 Shell/Bash 命令/脚本，适合自动化、校验、通知。

json 复制代码 
{
  "type": "command",
  "command": "prettier --write $FILE_PATH",
  "timeout": 10
}
2. prompt

让 LLM 做一次判断（Yes/No），用于智能决策。

json 复制代码 
{
  "type": "prompt",
  "prompt": "代码是否符合规范？回答 yes/no"
}
3. http

发送 HTTP 请求到外部服务（Webhook、审计、通知）。

json 复制代码 
{
  "type": "http",
  "url": "https://your-server.com/webhook",
  "method": "POST"
}

六、实战示例（直接可用）

示例1：PreToolUse ------ 禁止修改 .env 文件（安全）

json 复制代码 
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "grep -q '.env' $FILE_PATH && exit 1 || exit 0",
        "description": "禁止修改 .env 文件"
      }
    ]
  }
}
  • 规则：AI 要写/改 .env → 命令返回非 0 → 操作被拦截。
示例2：PostToolUse ------ 自动格式化代码（Write/Edit 后）
json 复制代码 
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "prettier --write $FILE_PATH",
        "timeout": 10,
        "description": "自动格式化"
      }
    ]
  }
}
示例3：PostToolUse ------ 自动 Git 提交
json 复制代码 
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "git add . && git commit -m 'auto: $FILE_PATH updated'",
        "description": "自动提交"
      }
    ]
  }
}
示例4：PermissionRequest ------ 自动批准测试命令
json 复制代码 
{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "npm test|pytest",
        "command": "exit 0", // 0=自动批准
        "description": "自动批准测试"
      }
    ]
  }
}

七、关键变量（脚本中可用）

Hook 执行时会注入环境变量，方便脚本获取上下文：

  • $EVENT：事件名（PreToolUse/PostToolUse）
  • $TOOL：工具名（Write/Edit/Bash）
  • $FILE_PATH：操作的文件路径
  • $COMMAND：执行的命令（Bash 场景）

八、最佳实践

  1. 最小权限：只给必要权限，避免危险命令。
  2. 先拦截后放行：PreToolUse 做安全校验，非 0 则拦截。
  3. 项目级配置 ：.claude/settings.json 提交 Git，团队共享规范。
  4. 组合使用：PreToolUse 拦截 + PostToolUse 自动化 = 完整门禁。
  5. 日志与调试：脚本中加日志，便于排查 Hook 执行问题。

九、与记忆文件（CLAUDE.md）的区别

  • CLAUDE.md ：给 AI 看的规则说明，靠 AI 自觉遵守。
  • Hook ：强制执行的脚本，系统层面保证必运行，不受 AI 遗忘影响。

Claude Code Hook 配置模板

说明：该模板适配 Claude Code，包含「安全拦截、自动格式化、自动 Git 提交、权限自动批准、操作通知」5大核心场景，可直接复制到对应配置文件，无需额外修改（需确保本地安装 prettier、git 等依赖）。

配置位置选择（二选一）：

  • 全局生效（所有项目）：~/.claude/settings.json

  • 项目生效（仅当前项目）：项目根目录/.claude/settings.json（需先创建 .claude 文件夹）

复制以下完整内容，替换原有 settings.json 即可（无该文件则新建）：

json 复制代码 
{
  "hooks": {
    // 一、PreToolUse：工具调用前（安全拦截，核心防护）
    "PreToolUse": [
      {
        "matcher": "Write|Edit|Delete",
        "type": "command",
        "command": "grep -q -E '(.env|.env.*|.gitignore|package.json)' $FILE_PATH && exit 1 || exit 0",
        "timeout": 5,
        "description": "禁止修改/删除敏感文件（.env、package.json、.gitignore），拦截危险操作"
      },
      {
        "matcher": "Bash|Shell",
        "type": "command",
        "command": "grep -q -E '(rm -rf|sudo|chmod 777|rm \\*)' $COMMAND && exit 1 || exit 0",
        "timeout": 5,
        "description": "拦截高危 Bash 命令（删除、提权、全局权限开放），避免误操作"
      }
    ],

    // 二、PostToolUse：工具执行后（自动化操作，提升效率）
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "type": "command",
        "command": "prettier --write $FILE_PATH",
        "timeout": 10,
        "description": "自动格式化代码（支持 JS/TS/HTML/CSS/Markdown 等，需本地安装 prettier）"
      },
      {
        "matcher": "Write|Edit",
        "type": "command",
        "command": "git add $FILE_PATH && git commit -m 'auto: update $FILE_PATH by Claude Code' || exit 0",
        "timeout": 10,
        "description": "自动将修改的文件提交到 Git（无需手动 git add/commit，失败不阻断流程）"
      },
      {
        "matcher": "Bash|Shell",
        "type": "command",
        "command": "echo 'Claude 执行命令：$COMMAND，执行时间：$(date)' >> .claude/hook_logs.txt",
        "timeout": 5,
        "description": "记录 Bash 命令执行日志，便于审计和排查问题"
      }
    ],

    // 三、PermissionRequest：权限请求时（自动批准安全操作，减少手动确认）
    "PermissionRequest": [
      {
        "matcher": "npm test|pytest|yarn test|go test",
        "type": "command",
        "command": "exit 0",
        "timeout": 3,
        "description": "自动批准测试命令（npm test/pytest 等），无需手动确认"
      },
      {
        "matcher": "prettier|eslint|lint",
        "type": "command",
        "command": "exit 0",
        "timeout": 3,
        "description": "自动批准代码格式化、校验命令，提升效率"
      }
    ],

    // 四、SessionStart：会话启动时（初始化环境，确保配置生效）
    "SessionStart": [
      {
        "type": "command",
        "command": "mkdir -p .claude && touch .claude/hook_logs.txt",
        "timeout": 5,
        "description": "初始化 .claude 目录和日志文件，避免 Hook 执行报错"
      },
      {
        "type": "command",
        "command": "echo 'Claude 会话启动：$(date)' >> .claude/hook_logs.txt",
        "timeout": 3,
        "description": "记录会话启动日志，便于追溯"
      }
    ],

    // 五、Stop：会话结束时（清理+通知，完善流程）
    "Stop": [
      {
        "type": "command",
        "command": "git pull && git push || exit 0",
        "timeout": 15,
        "description": "会话结束后自动拉取、推送 Git 代码（同步最新修改，失败不阻断）"
      },
      {
        "type": "http",
        "url": "https://your-server.com/webhook", // 替换为你的企业微信/钉钉/Slack Webhook
        "method": "POST",
        "headers": {
          "Content-Type": "application/json"
        },
        "body": "{\"msg\": \"Claude Code 会话结束，已自动提交代码，日志路径：.claude/hook_logs.txt\"}",
        "timeout": 10,
        "description": "会话结束后发送通知到外部服务（可替换 Webhook 地址，无需则删除该 Hook）"
      }
    ]
  },
  // 补充：Hook 全局配置（可选，无需修改）
  "hookConfig": {
    "timeout": 15, // 全局超时时间（秒）
    "failAction": "abort", // 钩子执行失败时：abort（阻断原操作）/ ignore（忽略，继续执行）
    "logLevel": "info" // 日志级别：info/debug/error
  }
}

使用说明（必看）

  1. 依赖准备：确保本地安装 prettier（自动格式化）、git（自动提交），执行命令安装：npm install -g prettier

  2. Webhook 替换：若不需要外部通知（企微/钉钉），可删除 Stop 事件中的 http 类型 Hook，避免报错

  3. 敏感文件调整：若需允许修改某类敏感文件，删除 PreToolUse 中对应正则（如删除 .env 相关匹配）

  4. 日志查看：Hook 执行日志保存在 .claude/hook_logs.txt，可随时查看执行情况

  5. 生效方式：配置保存后，重启 Claude Code 即可生效，无需额外操作

可自定义调整的地方

  • PreToolUse：添加/删除需要拦截的文件/命令（如禁止修改 .git 目录，可添加 .git 到正则）

  • PostToolUse：替换格式化工具（如用 eslint 替代 prettier，修改 command 为 eslint --fix $FILE_PATH）

  • PermissionRequest：添加需要自动批准的命令（如 docker 相关命令，添加 matcher 为 "docker.*"）

（注：Claude Code Hook 配置模板 部分内容由 AI 生成）

Agent Skill

一、核心定义

Agent Skill 是 Claude 基于文件系统的模块化扩展机制，以独立目录形式封装指令、元数据与可选资源（脚本/模板） ，在任务匹配时由 Claude 自动调用，实现专业化能力闭环。

与单次对话的 Prompt 不同，Skills 采用渐进式加载，仅在需要时读取内容，避免上下文溢出，同时支持一次创建、全局复用与组合调用。

二、底层原理

1. 三层加载机制（核心）
层级 加载时机 内容类型 Token 成本 作用
1. 元数据 启动时常驻 YAML frontmatter（name/description） 约 100 token/个 让 Claude 感知技能存在与触发条件
2. 指令 技能触发时 SKILL.md 主体（流程/指引） 通常 < 5k token 提供具体执行逻辑
3. 资源 按需引用 脚本（.py/.sh）、参考文档（.md） 无额外 token（仅输出入上下文） 扩展能力边界（如执行脚本、查参考资料）
2. 运行环境

Claude 在**带文件系统访问的虚拟机（VM）**中运行 Skills，通过 bash 命令浏览/读取/执行目录内内容，类似"新人入职按手册操作"的逻辑，实现安全隔离与确定性执行。

3. 关键特性
  • 动态触发：通过元数据描述，Claude 自动匹配用户请求（如提及"PDF 提取"则调用 pdf-processing 技能）；
  • 低上下文开销：未触发的技能仅加载元数据，不占用核心上下文，支持同时启用多个技能；
  • 可组合性：多个 Skill 可协同完成复杂任务（如先调用 PDF 提取，再用 Excel 技能生成报表）。

三、完整使用指南

1. 结构规范（必遵守）

每个 Skill 必须是独立目录，核心文件为 SKILL.md（含 YAML 元数据），可选包含脚本/参考文档，示例结构：

复制代码 
my-skill/                  # 技能目录（名称即技能 ID）
├── SKILL.md               # 必选：核心指令+元数据
├── scripts/               # 可选：可执行脚本（.py/.sh）
│   └── handler.py        # 具体处理逻辑
└── REFERENCE.md           # 可选：参考资料（API 文档/规范）
2. SKILL.md 模板（可直接复制）
yaml 复制代码 
---
# 必选：技能名称（与目录名完全一致，小写字母/数字/连字符，最长 64 字符）
name: data-analysis-helper
# 必选：技能描述（需明确"做什么+何时用"，最长 1024 字符，触发核心）
description: 处理 CSV/Excel 数据，完成清洗、统计、可视化与报告生成。当用户提到"数据统计""CSV 分析""生成报表"时调用。
---

# 数据分析助手（技能名称，与目录名一致）
## 核心指令（Claude 必须遵循的流程）
1. 先通过 bash 执行 scripts/handler.py，传入用户问题与文件路径；
2. 接收脚本输出结果，用自然语言整理成清晰报告；
3. 若需可视化，调用内置图表能力，生成可复制的图表代码。

## 示例（用户触发场景）
- 用户："分析 sales.csv 中的月度销售额，生成柱状图"
- 执行逻辑：bash scripts/handler.py "月度销售额统计" sales.csv → 接收输出 → 生成报告+图表代码

## 依赖说明
- 依赖 Python 3.8+，需提前安装 pandas（执行 pip install pandas）；
- 仅支持 UTF-8 编码的 CSV/Excel 文件，不处理加密文件。
3. 脚本示例（handler.py，可直接复制）
python 复制代码 
# scripts/handler.py
import sys
import pandas as pd

def process_data(task: str, file_path: str) -> str:
    """处理数据任务，返回整理后的结果"""
    try:
        # 读取文件（支持 CSV/Excel）
        if file_path.endswith(".csv"):
            df = pd.read_csv(file_path)
        elif file_path.endswith((".xlsx", ".xls")):
            df = pd.read_excel(file_path)
        else:
            return "❌ 仅支持 CSV/Excel 文件"

        # 执行任务（示例：统计/清洗）
        if "月度销售额" in task:
            df['月份'] = pd.to_datetime(df['日期']).dt.to_period('M')
            monthly_sales = df.groupby('月份')['销售额'].sum()
            return f"📊 月度销售额统计：\n{monthly_sales.to_string()}"
        elif "数据清洗" in task:
            df_clean = df.dropna().drop_duplicates()
            return f"✅ 数据清洗完成：原始 {len(df)} 行 → 清洗后 {len(df_clean)} 行"
        else:
            return f"ℹ️ 已处理数据（前 5 行）：\n{df.head().to_string()}"
    except Exception as e:
        return f"❌ 处理失败：{str(e)}"

if __name__ == "__main__":
    # 接收 Claude 传入的参数（任务+文件路径）
    if len(sys.argv) < 3:
        print("❌ 参数不足：需要任务与文件路径")
        sys.exit(1)
    task = sys.argv[1]
    file_path = sys.argv[2]
    # 输出结果（仅输出内容入上下文，代码本身不泄露）
    print(process_data(task, file_path))
4. 部署方式（按平台选择）
（1）Claude Code（本地/项目级，推荐）
  • 个人全局：创建 ~/.claude/skills/我的技能目录（如 ~/.claude/skills/data-analysis-helper）；
  • 项目级：在项目根目录创建 .claude/skills/我的技能目录，仅当前项目生效；
  • 生效：保存后重启 Claude Code，自动识别技能。
（2）Claude.ai（网页端）
  • 路径：Settings → Features → 上传技能 ZIP 包（需 Pro/Max/Team/Enterprise 计划，开启代码执行）；
  • 限制：按用户隔离，不支持组织级统一共享。
（3）Claude API（开发者）
  • 前置：需添加 3 个 beta 头（code-execution-2025-08-25、skills-2025-10-02、files-api-2025-04-01）；
  • 调用：在 container 参数中指定 skill_id（技能目录名），组织内可共享。
5. 触发与执行流程
  1. 用户提问匹配元数据描述（如"分析 data.csv 的数据"）；
  2. Claude 加载该技能的 SKILL.md 指令；
  3. 按指令执行 bash 命令调用脚本（如 bash scripts/handler.py "分析数据" data.csv）；
  4. 接收脚本输出，整理成自然语言/可视化结果，返回给用户。

四、实战示例（直接可用）

场景：工业数据统计助手（适配你的技术场景）
  1. 创建目录：~/.claude/skills/industrial-data-stats；
  2. 新建 SKILL.md（复制下方内容）：
yaml 复制代码 
---
name: industrial-data-stats
description: 处理工业设备 CSV 数据，完成缺陷统计、时序分析与巡检报告生成。当用户提到"工业数据""缺陷统计""巡检报告"时调用。
---

# 工业数据统计助手
## 核心指令
1. 校验文件格式（必须为 UTF-8 编码的 CSV，包含设备 ID、时间戳、缺陷类型字段）；
2. 执行 scripts/industrial_handler.py，传入任务与文件路径；
3. 输出统计结果与巡检建议，格式要求：分点清晰，标注缺陷率与异常设备。

## 示例
- 用户："分析 weld_defects.csv 中的焊后缺陷，生成巡检报告"
- 执行：bash scripts/industrial_handler.py "焊后缺陷统计" weld_defects.csv → 输出报告
  1. 新建 scripts/industrial_handler.py（复制下方内容）：
python 复制代码 
import sys
import pandas as pd

def analyze_industrial_data(task: str, file_path: str) -> str:
    try:
        df = pd.read_csv(file_path)
        # 校验必填字段
        required = ["设备ID", "时间戳", "缺陷类型"]
        if not all(col in df.columns for col in required):
            return "❌ 缺少必填字段：设备ID、时间戳、缺陷类型"

        if "焊后缺陷统计" in task:
            total = len(df)
            defect_rate = len(df[df["缺陷类型"] != "无"]) / total * 100
            top_defect = df["缺陷类型"].value_counts().idxmax()
            return f"""
📊 焊后缺陷统计报告
- 总检测设备：{total} 台
- 缺陷率：{defect_rate:.2f}%
- 高发缺陷类型：{top_defect}
- 异常设备列表：{', '.join(df[df['缺陷类型'] != '无']['设备ID'].unique())}
"""
        else:
            return f"ℹ️ 数据概览（前 10 条）：\n{df.head(10).to_string()}"
    except Exception as e:
        return f"❌ 处理失败：{str(e)}"

if __name__ == "__main__":
    if len(sys.argv) < 3:
        print("❌ 参数不足：任务+文件路径")
        sys.exit(1)
    print(analyze_industrial_data(sys.argv[1], sys.argv[2]))
  1. 重启 Claude Code，提问"分析 weld_defects.csv 的焊后缺陷"，即可自动执行统计并生成报告。

五、安全与最佳实践

1. 安全要点
  • 仅使用可信技能（自建/官方），避免未知来源脚本（防止恶意代码执行）；
  • 技能目录权限设为只读，禁止写入敏感文件；
  • 脚本中过滤危险命令（如 rm -rf、sudo），避免误操作。
2. 开发建议
  • 元数据描述要精准（明确"触发条件"），提高匹配准确率；
  • 脚本逻辑尽量简单，复杂逻辑拆分为多个小技能，便于维护；
  • 优先复用官方预置技能（如 PDF/Excel 处理），减少重复开发。

六、常见问题

  1. 技能不触发？
    检查 3 点：① 目录名与 name 完全一致；② description 明确包含触发关键词；③ 重启 Claude 客户端/服务端。
  2. 脚本执行失败？
    查看 Claude 日志，确认依赖已安装（如 pandas），文件路径是否正确。
  3. 上下文溢出？
    确认技能采用渐进式加载，未将大文件内容直接写入 SKILL.md，而是通过脚本输出结果。

（工业视觉、AI 检测）场景定制专属 Skill 模板

一、技能目录结构（规范版）

在你的项目根目录或 .claude/skills 下创建以下结构：

复制代码 
industrial-vision-detector/          # 技能根目录（名称即技能 ID）
├── SKILL.md                         # 必选：核心指令+元数据
├── REFERENCE.md                      # 可选：项目规范/API 文档
├── config/                           # 可选：配置目录
│   └── detection_config.yaml           # 检测参数配置
├── scripts/                          # 必选：处理脚本
│   ├── detector_handler.py           # 核心检测逻辑处理
│   ├── camera_mvs_control.py         # MVS 相机控制脚本（如需要）
│   └── model_inference.py            # AI 模型推理脚本
└── data/                             # 可选：存放测试数据/样本
    └── sample_defect.jpg             # 测试缺陷样本

二、SKILL.md 模板（核心配置，直接复制）

yaml 复制代码 
---
# 必须：技能名称（与目录名完全一致）
name: industrial-vision-detector
# 必须：技能描述（精准描述触发场景，让 Claude 自动识别）
description: 工业视觉缺陷检测与AI分析助手。处理工业相机图像、缺陷检测、模型训练、MVS相机控制、产线质检、焊后检测、表面缺陷分析等任务。当用户提到"缺陷检测"、"AI检测"、"MVS相机"、"图像分析"、"产线质检"、"焊后检测"、"表面缺陷"时自动调用。
# 可选：标签（用于分类）
tags: [工业视觉, 缺陷检测, AI模型, MVS相机, 产线质检]
---

# 工业视觉 & AI 检测专业助手
## 🔧 技能核心能力
本技能提供以下专业能力，可根据用户请求自动调用对应脚本：

1. **图像缺陷检测分析**
   - 接收工业图像（JPG/PNG/BMP），自动识别缺陷类型
   - 分析缺陷位置、面积、严重程度
   - 生成可视化检测结果与统计报告

2. **MVS 相机控制与图像采集**
   - 控制海康/MVS 相机（触发拍摄、参数调整）
   - 采集图像并保存到指定目录
   - 支持相机参数优化（曝光、增益、快门速度）

3. **AI 模型训练与微调**
   - 处理小样本数据集，执行迁移学习
   - 训练 YOLO/CNN 等模型用于缺陷检测
   - 评估模型性能，生成训练报告

4. **产线质检数据分析**
   - 统计检测结果：缺陷率、良品率
   - 分析产线异常趋势
   - 生成质检报告与优化建议

## 🎯 触发规则（重要）
当用户请求包含以下关键词时，立即调用本技能：
- 缺陷检测、表面缺陷、焊后检测、裂纹检测、划痕检测
- 工业视觉、AI检测、图像分析、图像处理
- MVS相机、海康相机、相机控制、图像采集
- 产线质检、质检分析、缺陷统计
- 模型训练、模型推理、AI模型微调

## 📋 执行流程规范
### 场景 A：图像缺陷检测分析
1. 确认用户提供的图像文件路径或上传的图像
2. 执行 `scripts/detector_handler.py`，传入任务与图像路径
3. 接收检测结果，生成可视化报告与缺陷分析
4. 提供优化建议（如相机参数调整、光照改进）

### 场景 B：MVS 相机控制
1. 询问用户需要执行的操作（采集/参数调整）
2. 执行 `scripts/camera_mvs_control.py`，执行对应操作
3. 返回操作结果与采集的图像路径

### 场景 C：AI 模型训练
1. 确认训练数据路径与任务类型
2. 执行 `scripts/model_inference.py` 或训练脚本
3. 返回模型性能指标与训练日志

## ⚠️ 安全与依赖说明
- 必须安装 OpenCV、PyTorch、MVS 相机 SDK 等依赖
- 禁止执行高危系统命令（rm -rf、sudo 等）
- 所有操作结果仅输出到日志，不修改系统配置

三、核心脚本模板（直接复制使用）

1. 通用缺陷检测处理脚本：scripts/detector_handler.py
python 复制代码 
import sys
import cv2
import numpy as np
import json
from datetime import datetime
from pathlib import Path

def analyze_defect_image(task: str, image_path: str, output_dir: str = "detection_results"):
    """
    工业图像缺陷检测处理主函数
    支持：划痕、裂纹、缺料、脏污、变形、色差等常见缺陷
    """
    try:
        # 创建输出目录
        Path(output_dir).mkdir(exist_ok=True)
        
        # 读取图像
        img = cv2.imread(image_path)
        if img is None:
            return f"❌ 无法读取图像: {image_path}"
        
        height, width = img.shape[:2]
        result = {
            "image_path": image_path,
            "analysis_time": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
            "image_size": f"{width}x{height}",
            "defects": []
        }
        
        # 根据任务执行不同检测逻辑
        if "划痕" in task or "裂纹" in task:
            # 边缘检测+轮廓分析
            gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
            edges = cv2.Canny(gray, 50, 150)
            contours, _ = cv2.findContours(edges, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
            
            for i, cnt in enumerate(contours):
                area = cv2.contourArea(cnt)
                if area > 100:  # 过滤小噪声
                    perimeter = cv2.arcLength(cnt, True)
                    x, y, w, h = cv2.boundingRect(cnt)
                    
                    defect_type = "裂纹" if perimeter/area > 8 else "划痕"
                    result["defects"].append({
                        "id": i+1,
                        "type": defect_type,
                        "position": (x, y, w, h),
                        "area": float(area),
                        "confidence": 0.85 + min(area/10000, 0.1)
                    })
                    
                    # 绘制检测框
                    cv2.rectangle(img, (x, y), (x+w, y+h), (0, 0, 255), 2)
                    cv2.putText(img, f"{defect_type} {area:.0f}", 
                                (x, y-10), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 0, 255), 1)
        
        elif "脏污" in task or "斑点" in task:
            # 颜色分割检测脏污
            hsv = cv2.cvtColor(img, cv2.COLOR_BGR2HSV)
            # 提取深色区域（脏污）
            mask = cv2.inRange(hsv, (0, 0, 0), (180, 255, 40))
            contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
            
            for i, cnt in enumerate(contours):
                area = cv2.contourArea(cnt)
                if area > 200:
                    x, y, w, h = cv2.boundingRect(cnt)
                    result["defects"].append({
                        "id": i+1,
                        "type": "脏污斑点",
                        "position": (x, y, w, h),
                        "area": float(area),
                        "confidence": 0.9
                    })
                    cv2.rectangle(img, (x, y), (x+w, y+h), (0, 255, 255), 2)
        
        elif "缺料" in task or "变形" in task:
            # 模板匹配检测缺料/变形
            # 这里简化为检测区域是否有明显缺失
            gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
            # 二值化
            _, thresh = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY_INV)
            contours, _ = cv2.findContours(thresh, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
            
            for i, cnt in enumerate(contours):
                area = cv2.contourArea(cnt)
                if area > 500:
                    x, y, w, h = cv2.boundingRect(cnt)
                    result["defects"].append({
                        "id": i+1,
                        "type": "缺料/变形",
                        "position": (x, y, w, h),
                        "area": float(area),
                        "confidence": 0.88
                    })
                    cv2.rectangle(img, (x, y), (x+w, y+h), (255, 0, 0), 2)
        
        # 保存结果图像
        result_image_path = f"{output_dir}/result_{Path(image_path).stem}.jpg"
        cv2.imwrite(result_image_path, img)
        
        # 生成统计信息
        total_defects = len(result["defects"])
        defect_rate = total_defects / 100  # 简化计算，实际根据产线标准
        
        # 构建最终报告
        report = f"""
# 🏭 工业视觉缺陷检测报告
## 📊 基本信息
- 分析时间: {result['analysis_time']}
- 图像路径: {result['image_path']}
- 图像尺寸: {result['image_size']}
- 总缺陷数: {total_defects}

## 🚨 缺陷详情
"""
        if total_defects > 0:
            for defect in result["defects"]:
                report += f"- 缺陷 #{defect['id']}: {defect['type']}\n"
                report += f"  - 位置: ({defect['position'][0]}, {defect['position'][1]}) 尺寸: {defect['position'][2]}x{defect['position'][3]}\n"
                report += f"  - 面积: {defect['area']:.0f} 像素\n"
                report += f"  - 置信度: {defect['confidence']:.2f}\n\n"
        else:
            report += "✅ 未检测到明显缺陷\n"
        
        report += f"""
## 📈 统计分析
- 缺陷率: {defect_rate:.2%}
- 建议: 根据缺陷类型和数量，检查产线设备状态或工艺参数

## 📁 结果文件
- 标注图像: {result_image_path}
- 详细数据: {output_dir}/detection_results.json
"""
        # 保存详细数据
        with open(f"{output_dir}/detection_results.json", 'w', encoding='utf-8') as f:
            json.dump(result, f, ensure_ascii=False, indent=2)
        
        return report
        
    except Exception as e:
        return f"❌ 处理失败: {str(e)}\n请检查图像路径和依赖是否正确安装"

if __name__ == "__main__":
    if len(sys.argv) < 3:
        print("用法: python detector_handler.py <任务描述> <图像路径> [输出目录]")
        print("示例: python detector_handler.py '检测划痕' test.jpg")
        sys.exit(1)
    
    task = sys.argv[1]
    image_path = sys.argv[2]
    output_dir = sys.argv[3] if len(sys.argv) > 3 else "detection_results"
    
    result = analyze_defect_image(task, image_path, output_dir)
    print(result)
2. MVS 相机控制脚本：scripts/camera_mvs_control.py
python 复制代码 
import sys
import cv2
import numpy as np
from datetime import datetime
from pathlib import Path

try:
    # 尝试导入MVS相机SDK（根据实际安装路径调整）
    # 注意：实际使用时需要根据MVS SDK安装路径导入
    # from MVS import *
    MVS_AVAILABLE = False
except ImportError:
    MVS_AVAILABLE = False

def control_mvs_camera(task: str, save_dir: str = "camera_captures"):
    """
    MVS相机控制模拟脚本（实际使用需替换为真实MVS SDK调用）
    """
    if not MVS_AVAILABLE:
        return """⚠️  MVS相机SDK未安装，无法执行真实相机控制
        本脚本为模拟版本，返回示例数据。
        实际使用请安装MVS SDK并导入对应库。"""
    
    try:
        # 创建保存目录
        Path(save_dir).mkdir(exist_ok=True)
        
        # 模拟相机操作
        if "采集" in task or "拍照" in task:
            # 模拟采集图像（实际替换为相机触发采集）
            capture_time = datetime.now().strftime("%Y%m%d_%H%M%S")
            image_path = f"{save_dir}/capture_{capture_time}.jpg"
            
            # 生成模拟图像（白色背景+随机噪声）
            img = np.ones((1080, 1920, 3), dtype=np.uint8) * 255
            # 添加一些模拟缺陷
            for _ in range(5):
                x, y = np.random.randint(100, 900), np.random.randint(100, 900)
                cv2.circle(img, (x, y), np.random.randint(5, 20), (0, 0, 255), -1)
            
            cv2.imwrite(image_path, img)
            
            return f"""
📷 MVS相机采集完成
- 采集时间: {capture_time}
- 保存路径: {image_path}
- 图像尺寸: 1920x1080
- 建议后续使用工业视觉检测技能分析图像
"""
        
        elif "参数" in task:
            return """
⚙️ 相机参数调整建议
- 曝光时间: 10000-20000 μs
- 增益: 10-20 dB
- 快门速度: 1/1000 s
- 触发模式: 外部触发
参数调整依据: 根据产线光照条件和产品材质优化
"""
        
        else:
            return "ℹ️ 支持的操作: 采集/拍照、参数调整、相机状态检查"
            
    except Exception as e:
        return f"❌ 相机控制失败: {str(e)}"

def simulate_image_capture(save_dir: str = "camera_captures"):
    """模拟图像采集，用于没有真实相机的情况"""
    Path(save_dir).mkdir(exist_ok=True)
    capture_time = datetime.now().strftime("%Y%m%d_%H%M%S")
    image_path = f"{save_dir}/sim_capture_{capture_time}.jpg"
    
    # 生成模拟工业图像
    img = np.ones((1080, 1920, 3), dtype=np.uint8) * 240
    
    # 添加一些模拟缺陷
    defects = [
        ((300, 400), 15, (0, 0, 255), "划痕"),
        ((600, 700), 25, (0, 255, 255), "脏污"),
        ((800, 300), 20, (255, 0, 0), "缺料")
    ]
    
    for (x, y), r, color, dtype in defects:
        if dtype == "划痕":
            cv2.line(img, (x-r, y), (x+r, y), color, 3)
        elif dtype == "脏污":
            cv2.circle(img, (x, y), r, color, -1)
        elif dtype == "缺料":
            cv2.rectangle(img, (x-r, y-r), (x+r, y+r), color, -1)
    
    cv2.imwrite(image_path, img)
    
    return {
        "image_path": image_path,
        "defects": ["划痕", "脏污", "缺料"],
        "capture_time": capture_time
    }

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("用法: python camera_mvs_control.py <任务描述> [保存目录]")
        print("示例: python camera_mvs_control.py '采集图像'")
        sys.exit(1)
    
    task = sys.argv[1]
    save_dir = sys.argv[2] if len(sys.argv) > 2 else "camera_capt

SubAgent

SubAgent 是 Claude Code 中的专业化独立 AI 助手 ，拥有独立上下文、专属系统提示与工具权限，主对话可自动/手动委托任务，实现上下文隔离、并行执行、专业分工，解决复杂任务的上下文溢出与效率问题。

一、核心原理

1. 本质与定位

  • 独立专家模型：每个 SubAgent 是一个"专项专家"，专注单一领域（如代码审查、安全检测、工业视觉分析）。

  • 三层隔离架构

    维度 隔离特性 作用
    上下文 独立上下文窗口 不污染主对话，避免上下文溢出
    权限 专属工具/模型配置 最小权限原则，提升安全性
    执行 独立会话/后台运行 主对话可继续交互，支持并行

  • 调度规则 ：仅支持主对话 → SubAgent 一层调用，不允许嵌套，保证调度简洁。

2. 核心机制
  1. 任务委托 ：主对话分析请求，匹配 SubAgent 的 description，自动/手动启动。
  2. 独立执行：SubAgent 在专属上下文执行，调用授权工具，生成结果。
  3. 结果返回 ：仅返回结果摘要给主对话，不传递全量上下文，保护主对话空间。
  4. 状态持久化 ：会话历史保存为 agent-{id}.jsonl，支持 resume 续跑。
3. 关键优势
  • 上下文保护：主对话始终聚焦顶层目标，不被子任务细节干扰。
  • 并行效率：多 SubAgent 同时处理独立子任务，大幅提速。
  • 专业聚焦：每个 SubAgent 深度专精单一领域，结果更精准。
  • 安全可控：细粒度工具权限，降低风险。

二、完整使用流程（可直接复制）

1. 创建 SubAgent（两种方式）
方式1：文件系统定义（推荐，全局/项目级）

  • 目录规范

    复制代码 
    # 全局（所有项目可用）
~/.claude/agents/
# 项目级（仅当前项目）
项目根目录/.claude/agents/

  • 文件格式 ：{agent-name}.md，YAML 前置元数据 + Markdown 系统提示。

方式2：代码定义（SDK/API）

在 agents 参数中直接配置，适合程序化调用。

2. 配置模板（可直接复制）
通用 SubAgent 模板
yaml 复制代码 
---
# 必选：唯一名称（小写字母/数字/连字符）
name: industrial-vision-analyzer
# 必选：触发描述（清晰说明"做什么+何时用"）
description: 工业视觉缺陷检测专家，处理图像分析、MVS相机控制、AI模型推理、产线质检报告生成。当用户提及"缺陷检测""MVS相机""焊后检测""图像分析""产线质检"时自动调用。
# 可选：指定模型（sonnet/haiku，默认sonnet）
model: sonnet
# 可选：工具权限（默认继承主对话所有工具）
tools: [Read, Write, Bash, Glob, Grep, Python]
# 可选：标签（分类）
tags: [工业视觉, 缺陷检测, MVS相机, AI质检]
---

# 工业视觉缺陷检测专家
## 角色定位
你是专业工业视觉AI工程师，专注于工业产品缺陷检测、MVS相机控制、AI模型推理与产线质检数据分析。

## 核心能力
1. **图像缺陷分析**：识别划痕、裂纹、脏污、缺料、变形等缺陷，输出位置、面积、严重程度
2. **MVS相机控制**：模拟/真实控制海康MVS相机，完成图像采集与参数优化
3. **AI模型推理**：调用检测模型，输出缺陷分类与置信度
4. **质检报告生成**：统计缺陷率、良品率，生成可视化报告与优化建议

## 执行流程
1. 接收任务与输入（图像路径/相机指令/模型参数）
2. 调用对应工具（Python脚本/Bash命令）执行处理
3. 分析结果，生成结构化报告
4. 提供 actionable 优化建议

## 约束规则
- 仅处理工业视觉相关任务，不越权操作
- 严格遵循工具权限，不执行高危命令（rm -rf、sudo等）
- 结果必须包含数据支撑，不主观臆断
工业视觉专属 SubAgent（适配你的场景）
yaml 复制代码 
---
name: weld-defect-detector
description: 焊后缺陷检测专家，专注焊接质量分析，处理焊缝图像、识别气孔/夹渣/裂纹/未焊透，生成质检报告与工艺优化建议。当用户提及"焊后检测""焊缝缺陷""焊接质量""气孔检测"时自动调用。
model: sonnet
tools: [Read, Write, Bash, Python, Glob]
tags: [工业视觉, 焊后检测, 缺陷分析, 焊接质检]
---

# 焊后缺陷检测专家
## 核心职责
专注工业焊接产品缺陷检测，提供专业分析与解决方案。

## 检测能力
- 识别焊缝缺陷类型：气孔、夹渣、裂纹、未焊透、咬边、焊瘤
- 测量缺陷尺寸、位置、面积，评估严重程度
- 分析缺陷产生原因，提供工艺优化建议
- 生成标准化质检报告与统计分析

## 工作流程
1. 读取焊缝图像（支持JPG/PNG/BMP）
2. 执行scripts/weld_detector.py进行缺陷检测
3. 输出缺陷详情、统计数据与可视化结果
4. 提供焊接工艺参数优化建议

## 输出要求
- 缺陷分类清晰，标注置信度
- 数据量化，包含缺陷率、严重等级
- 建议具体，可直接应用于产线优化
3. 触发与调用（三种方式）
方式1：自动委托（推荐）

Claude 自动匹配 description，无需手动指定。

复制代码 
分析这张焊缝图像的缺陷，生成质检报告
方式2：手动指定（强制调用）
复制代码 
使用 weld-defect-detector 分析 weld_image.jpg 的焊后缺陷
方式3：@提及（快速调用）
复制代码 
@weld-defect-detector 帮我检测这批焊接产品的缺陷
4. 管理与调试
  • 查看 SubAgent ：/agents 命令列出所有可用 SubAgent。
  • 续跑 SubAgent ：通过 agentId 恢复会话，保留完整历史。
  • 后台执行：长任务自动后台运行，主对话可继续交互。
  • 停止任务 ：Esc 键或 /stop 命令终止执行。

三、工业视觉场景实战（完整示例）

1. 目录结构
复制代码 
industrial-vision-agents/
├── .claude/
│   └── agents/
│       ├── industrial-vision-analyzer.md  # 通用视觉分析
│       └── weld-defect-detector.md        # 焊后检测专项
└── scripts/
    ├── vision_analyzer.py                 # 通用分析脚本
    └── weld_detector.py                   # 焊后检测脚本
2. 核心脚本（weld_detector.py，可直接复制）
python 复制代码 
import sys
import cv2
import numpy as np
import json
from pathlib import Path
from datetime import datetime

def detect_weld_defects(image_path: str, output_dir: str = "weld_results"):
    """焊后缺陷检测主函数"""
    try:
        Path(output_dir).mkdir(exist_ok=True)
        img = cv2.imread(image_path)
        if img is None:
            return f"❌ 无法读取图像: {image_path}"
        
        gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
        result = {
            "image": image_path,
            "time": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
            "defects": [],
            "stats": {}
        }
        
        # 缺陷检测逻辑（简化示例）
        edges = cv2.Canny(gray, 50, 150)
        contours, _ = cv2.findContours(edges, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
        
        defect_types = {
            "气孔": 0.85,
            "夹渣": 0.88,
            "裂纹": 0.92,
            "未焊透": 0.90
        }
        
        for i, cnt in enumerate(contours):
            area = cv2.contourArea(cnt)
            if area > 50:
                x, y, w, h = cv2.boundingRect(cnt)
                defect_type = min(defect_types.items(), key=lambda x: abs(x[1]-0.9))[0]
                result["defects"].append({
                    "id": i+1,
                    "type": defect_type,
                    "bbox": [x, y, w, h],
                    "area": area,
                    "confidence": defect_types[defect_type]
                })
                cv2.rectangle(img, (x, y), (x+w, y+h), (0, 0, 255), 2)
        
        # 统计分析
        total = len(result["defects"])
        result["stats"] = {
            "total_defects": total,
            "defect_rate": f"{total/100:.2%}",
            "severity": "高" if total > 5 else "中" if total > 2 else "低"
        }
        
        # 保存结果
        cv2.imwrite(f"{output_dir}/result_{Path(image_path).stem}.jpg", img)
        with open(f"{output_dir}/report.json", "w") as f:
            json.dump(result, f, indent=2)
        
        return f"""
# 焊后缺陷检测报告
## 📊 基本信息
- 分析时间: {result['time']}
- 图像: {image_path}
- 总缺陷数: {total}
- 缺陷率: {result['stats']['defect_rate']}
- 严重等级: {result['stats']['severity']}

## 🚨 缺陷详情
""" + "\n".join([f"- {d['type']} (置信度: {d['confidence']:.2f})" for d in result["defects"]])
        
    except Exception as e:
        return f"❌ 检测失败: {str(e)}"

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("用法: python weld_detector.py <图像路径> [输出目录]")
        sys.exit(1)
    print(detect_weld_defects(sys.argv[1], sys.argv[2] if len(sys.argv) > 2 else "weld_results"))
3. 调用示例
复制代码 
使用 weld-defect-detector 分析 weld_image.jpg 的焊后缺陷，生成详细报告

四、最佳实践与注意事项

1. 开发规范
  • 名称规范 ：小写字母+连字符，清晰表达功能（如 weld-defect-detector）。
  • 描述精准 ：description 明确触发关键词，提升匹配准确率。
  • 权限最小化：仅授予必要工具，降低安全风险。
  • 模型选择 ：简单任务用 haiku（低成本），复杂任务用 sonnet（高精度）。
2. 安全要点
  • 禁止 SubAgent 执行高危命令（rm -rf、sudo、chmod 777 等）。
  • 敏感操作添加二次确认，避免误执行。
  • 定期审计 SubAgent 权限与执行日志。
3. 性能优化
  • 复杂任务拆分多个小 SubAgent，避免单一 SubAgent 过载。
  • 长任务使用后台执行，不阻塞主对话。
  • 结果返回精简摘要，减少主对话上下文占用。

五、常见问题

  1. SubAgent 不触发？

    • 检查 name 与文件名一致，description 包含触发关键词。
    • 确认 SubAgent 存放路径正确（~/.claude/agents/ 或项目 .claude/agents/）。
    • 重启 Claude Code 重新加载。

  2. 工具权限不足？

    • 在 tools 字段添加所需工具（如 Bash、Python、Write）。
    • 主对话需拥有对应工具权限，SubAgent 才能继承。

  3. 上下文溢出？

    • 拆分任务到多个 SubAgent，避免单一 SubAgent 处理过多信息。
    • 使用 resume 续跑，分阶段处理复杂任务。

Skill与SubAgent区别

一句话核心：Skill 是"可复用的专业规则包"，在主会话内执行；SubAgent 是"独立上下文的专业分身"，隔离运行并可并行。

一、核心区别总表

对比维度 Skill（技能包） SubAgent（子代理）
本质定位 场景化能力封装，自动触发的"工作流模板" 独立专业助手，主对话可委派的"分身"
执行环境 与主会话共享上下文 拥有独立上下文窗口，完全隔离
触发方式 自动识别（匹配描述关键词）或 /skill 手动 自动委派、手动指定（/use 名称）、@提及
工具权限 继承主对话权限，精细度低 可精确配置工具（如仅 Read+Python）
模型选择 通常继承主模型 可单独选 Haiku/Sonnet/Opus
并发能力 不支持，串行执行 支持并行（最多49个）
典型场景 代码格式化、规范检查、单测生成 焊后缺陷专项分析、MVS相机控制、复杂缺陷报告
配置文件 SKILL.md（必需）+ scripts/ {name}.md（YAML+Markdown）
主对话影响 占用主上下文，易被中间结果污染 不污染主对话，仅返回结果摘要

二、关键差异详解（结合你的工业视觉项目）

1. 执行环境与上下文隔离
  • Skill：在主会话内运行，所有代码、图像、日志都会堆进主上下文。适合轻量、低噪声任务（如检查代码规范）。
  • SubAgent ：完全独立 的上下文窗口，处理高噪声任务（如批量焊缝图像分析、MVS相机参数调优），避免主对话被大量中间结果"淹没"。你的工业视觉项目中，焊后缺陷专项检测、MVS相机控制强烈建议用 SubAgent，避免与通用视觉分析的上下文相互干扰。
2. 权限与模型控制
  • Skill：权限与主会话一致，无法精细限制（如既不能禁止 Write，也不能单独给 Bash）。
  • SubAgent ：可最小权限配置 。例如：
    • 安全审查 SubAgent：仅 Read+Grep，禁止 Write/Bash
    • 焊后检测 SubAgent：Read+Write+Python，用于图像分析与报告生成
      同时可单独选择模型（用 Haiku 做快速图像采集，用 Sonnet 做复杂缺陷分析），兼顾成本与精度。
3. 触发与调用方式
  • Skill ：自动触发（如输入"分析代码"自动调用 code_review）或 /skill-name 手动。
  • SubAgent ：三种方式：
    1. 自动委派：匹配 description 关键词（如"焊后检测"自动调用 weld-defect-special）
    2. 手动指定：/use weld-defect-special 分析 weld.jpg
    3. @提及：@weld-defect-special 检测这批焊缝
4. 适用场景选型（工业视觉项目实战）
任务类型 推荐选型 原因
表面缺陷通用检测（划痕/脏污） Skill 轻量、低噪声，自动触发更高效
焊后缺陷专项分析（气孔/裂纹） SubAgent 需独立上下文、专属权限、专业提示词
MVS相机控制（采集/参数调整） SubAgent 需隔离执行，避免误操作影响主会话
批量图像分析+报告生成 SubAgent 支持并行，大幅提升处理效率
代码规范检查（Qt/ C# 项目） Skill 简单复用，无需复杂上下文

三、工业视觉项目最佳组合用法

1. 组合架构（推荐）
复制代码 
你的工业视觉项目/
├── .claude/
│   ├── skills/          # Skill 目录
│   │   └── code-format/ # 轻量技能（如代码格式化）
│   └── agents/          # SubAgent 目录
│       ├── industrial-vision-global.md # 通用视觉检测
│       └── weld-defect-special.md      # 焊后专项
└── scripts/
    ├── vision_detector.py
    └── weld_detector.py
2. 典型工作流
  1. 通用任务 ：输入"分析 test.jpg 的表面缺陷" → 自动触发 Skill（轻量处理）。
  2. 专项任务 ：输入"分析 weld.jpg 的焊后缺陷，生成报告" → 自动委派 SubAgent（独立执行，返回摘要）。
  3. 复杂任务 ：输入"控制MVS相机采集焊缝图像并检测缺陷" → 手动指定 SubAgent 并行执行，主对话继续其他任务。
3. 选型口诀
  • 轻量、自动、低噪声 → Skill
  • 复杂、隔离、需并行 → SubAgent
  • 工业视觉专项（焊后/MVS）→ 优先 SubAgent
  • 通用工具（格式化/规范）→ 优先 Skill

四、快速配置对比（可直接复制）

Skill 配置（SKILL.md）
markdown 复制代码 
# 工业视觉代码规范检查 Skill
name: vision-code-format
description: 工业视觉项目代码格式化与规范检查，适配Qt/C++、C#、Python。自动触发于"代码格式化""规范检查""Qt代码整理"。

## 工作流程
1. 识别代码语言（Qt/C++/C#/Python）
2. 应用工业视觉项目代码规范（命名、注释、缩进）
3. 格式化代码，输出修改对比
SubAgent 配置（weld-defect-special.md）
markdown 复制代码 
---
name: weld-defect-special
description: 焊后缺陷检测专项，处理焊缝图像、识别气孔/夹渣/裂纹，生成质检报告与工艺建议。自动触发于"焊后检测""焊缝分析"。
model: sonnet
tools: [Read, Write, Python, Glob]
---
# 焊后缺陷检测专项专家
## 核心职责
专注焊缝缺陷检测，输出量化报告与工艺优化建议。
## 执行流程
1. 接收焊缝图像与任务
2. 调用 weld_detector.py 检测
3. 分析缺陷与工艺问题
4. 生成结构化报告

五、总结

  • Skill 是"一次配置，多次自动调用"的轻量能力包，适合简单、重复任务。
  • SubAgent 是"独立上下文、专属权限、可并行"的专业分身，适合复杂、高噪声、需隔离的任务。
  • 在你的工业视觉项目中：通用轻量任务用 Skill，复杂专项（焊后/MVS）用 SubAgent，两者结合可最大化效率与安全性。

需要我按你的项目目录，生成一套可直接部署的"Skill + SubAgent"混合配置包吗？

Plugin

Claude Plugin（插件）是 Claude Code 生态中「可分发、可复用、可扩展」的能力封装包，核心作用是将 Skills、SubAgent、Hooks 等组件打包整合，实现"一键安装、全局/项目级复用"，解决单独配置组件不便分享、版本难管理的痛点，类比手机"APP"------Claude Code 是基础平台，Plugin 是扩展功能的应用，适配工业视觉等各类专业场景。

一、核心原理（底层逻辑拆解）

1. 本质定位

Plugin 并非独立运行的程序，而是「组件集合的标准化封装包」，核心价值是解决组件的分发、安装与版本管理问题。不同于单独配置的 Skill 或 SubAgent，Plugin 可将多个相关能力（如工业视觉检测的 Skill、专项 SubAgent、自动化 Hooks）打包，支持跨项目、跨团队分享，一键安装即可启用所有关联功能，无需手动配置目录与依赖。

简单来说：Skill 是"单一功能原子"，SubAgent 是"独立专业分身"，而 Plugin 是"能力工具箱"，可将多个 Skill、SubAgent 及配置整合，方便分发与使用，这也是 Plugin 与前两者最核心的区别之一。

2. 核心运行机制

Plugin 遵循"清单驱动、自动发现、组件协同"的运行逻辑，全程无需手动干预组件调用，具体流程如下：

  1. 清单解析 ：Plugin 安装后，Claude Code 会优先读取根目录下 .claude-plugin/plugin.json 清单文件，获取插件名称、版本、组件路径等核心配置，这是插件能被识别的关键。

  2. 组件自动发现：根据清单配置，自动扫描插件内的 commands、agents、skills、hooks 等目录，加载所有组件（无需手动注册），例如自动识别插件内的工业视觉 SubAgent 和检测 Skill。

  3. 协同执行：用户触发相关指令时，Claude Code 会调用插件内的对应组件（如输入"焊后检测"，触发插件内的 weld-defect-special SubAgent），组件执行完成后，将结果返回给用户，插件本身不直接执行任务，仅负责组件的整合与调度。

  4. 版本与权限管控：插件支持版本管理，可通过命令更新/卸载；同时继承 Claude Code 的权限体系，可在清单中配置插件的整体权限，也可给内部组件单独分配权限（如仅给检测 Skill 授予 Read+Python 权限），遵循最小权限原则。

3. 核心优势（对比单独配置组件）

  • 可分发：打包后的插件可上传至插件市场，或分享给团队成员，一键安装即可复用，无需复制多个配置文件与脚本，解决单独配置组件的分享痛点。

  • 可管理：支持版本控制，可随时更新、回滚、卸载，避免组件版本混乱（如工业视觉检测脚本更新后，无需手动替换每个项目的文件，仅更新插件即可）。

  • 高整合：可将多个关联组件（如工业视觉的通用检测 Skill、焊后专项 SubAgent、MVS 相机控制脚本、自动化 Hooks）整合，形成完整的能力闭环，无需单独调用多个组件。

  • 易适配：插件可适配不同场景，例如工业视觉插件可整合所有相关检测能力，安装后直接用于产线质检，无需额外配置上下文。

二、Plugin 结构规范（必看，避免踩坑）

Claude Plugin 有严格的目录结构规范，必须遵循以下格式（否则无法被 Claude Code 识别），所有目录与文件需使用 kebab-case（小写字母+连字符）命名，禁止使用空格或特殊字符：

1. 标准目录结构（以工业视觉插件为例）
bash 复制代码 
industrial-vision-plugin/  # 插件根目录（kebab-case命名）
├─ .claude-plugin/        # 插件核心配置目录（必需）
│  └─ plugin.json         # 插件清单（必需，核心配置文件）
├─ commands/              # 命令组件（可选，slash命令，.md文件）
├─ agents/                # SubAgent 目录（可选，.md文件）
│  ├─ industrial-vision-global.md  # 通用视觉检测SubAgent
│  └─ weld-defect-special.md       # 焊后缺陷专项SubAgent
├─ skills/                # Skill 目录（可选，子目录+SKILL.md）
│  ├─ vision-code-format/  # 代码规范检查Skill
│  │  └─ SKILL.md         # Skill核心配置（必需）
│  └─ image-preprocess/   # 图像预处理Skill
│     └─ SKILL.md
├─ hooks/                 # 自动化钩子（可选，hooks.json）
│  └─ hooks.json          # 事件触发配置（如文件变化时自动检测）
├─ .mcp.json              # MCP服务器配置（可选，适配远程设备）
└─ scripts/               # 辅助脚本（可选，插件内组件调用的脚本）
   ├─ vision_detector.py  # 通用缺陷检测脚本
   ├─ weld_detector.py    # 焊后缺陷检测脚本
   └─ common_utils.py     # 通用工具类脚本
2. 核心配置文件（plugin.json 清单）

清单文件是插件的"身份证"，位于.claude-plugin/plugin.json，必需包含必填字段，推荐补充元数据方便管理，格式如下（可直接复制修改）：

json 复制代码 
// 必需字段：name（唯一标识，kebab-case格式）
{
  "name": "industrial-vision-plugin",  // 插件名称，唯一，小写+连字符
  "version": "1.0.0",                 // 推荐：版本号（遵循语义化版本）
  "description": "工业视觉缺陷检测插件，整合通用视觉检测、焊后专项检测、MVS相机控制能力，支持自动缺陷检测与质检报告生成。", // 推荐：插件功能描述
  "author": {                         // 推荐：作者信息
    "name": "工业视觉团队",
    "email": "vision-team@example.com"
  },
  "keywords": ["工业视觉", "缺陷检测", "焊后检测", "MVS相机"], // 推荐：关键词，方便搜索
  "permissions": ["Read", "Write", "Python", "Glob"] // 可选：插件全局权限，内部组件可继承/单独配置
}

关键规则：name 必须唯一，不能与已安装的插件重复；permissions 可配置插件的全局权限，内部组件（如SubAgent）可单独配置权限，优先级高于全局权限；插件内仅需创建实际用到的组件目录，无需冗余创建未使用的文件夹（如无命令组件，可删除commands目录）。

3. 组件关联逻辑

Plugin 内的组件并非孤立存在，而是可协同工作：

  • SubAgent 可调用插件内的 Skill（如焊后检测 SubAgent 调用图像预处理 Skill），实现复杂任务的流程化执行；

  • Hooks 可触发 SubAgent/Skill（如监测到图像文件新增时，自动触发缺陷检测 Skill）；

  • scripts 目录下的脚本，可被插件内的 SubAgent/Skill 调用，无需额外配置路径，直接通过插件根路径引用（可使用 ${claude_plugin_root} 引用插件根目录，避免路径错误）。

三、Plugin 完整使用流程（3步搞定，可直接实操）

1. 准备工作（前置条件）

  • 确保已安装 Claude Code（最新版本，旧版本可能不支持插件功能）；

  • 安装插件依赖：若插件包含 Python 脚本（如工业视觉检测脚本），需提前安装相关依赖（如 opencv-python、numpy），执行命令：pip install opencv-python numpy；

  • （可选）注册插件市场：若需安装官方/第三方插件，需先添加插件市场，执行命令：/plugin marketplace add anthropics/claude-code（官方市场），也可添加团队内部市场或本地目录。

2. 插件安装（3种方式，按需选择）
方式1：从官方市场安装（推荐，无需手动配置）

适用于安装官方或第三方已发布的插件（如工业视觉、代码评审类插件），步骤：

  1. 查看市场内可用插件：执行命令 /plugin marketplace list，查看已添加市场的插件列表；

  2. 安装插件：执行命令 /plugin install 插件名称，例如安装工业视觉插件：/plugin install industrial-vision-plugin；

  3. 指定安装范围（可选）：

    • 全局安装（所有项目可用）：/plugin install industrial-vision-plugin（默认）；

    • 项目级安装（仅当前项目可用，团队成员可共享）：/plugin install industrial-vision-plugin --scope project；

    • 本地安装（仅当前项目、仅自己可用，会被gitignore）：/plugin install industrial-vision-plugin --scope local。

方式2：本地插件安装（自定义插件，工业视觉场景常用）

适用于自己开发的插件（如整合工业视觉组件的自定义插件），步骤：

  1. 按上述"标准目录结构"，创建插件目录（如 industrial-vision-plugin），完善 plugin.json 清单和相关组件、脚本；

  2. 执行安装命令：/plugin install 插件根目录路径，例如：/plugin install ./industrial-vision-plugin；

  3. 验证安装：执行命令 /plugin list，查看已安装的插件，若出现目标插件，说明安装成功。

方式3：从Git仓库安装（团队共享插件）

适用于团队内部共享的插件（如团队定制的工业视觉插件），步骤：

执行命令：/plugin install git@github.com:xxx/industrial-vision-plugin.git（替换为实际Git仓库地址），支持指定分支/版本，例如：/plugin install git@github.com:xxx/industrial-vision-plugin.git#v1.0.0。

3. 插件使用与管理（核心操作）
（1）插件调用

插件安装后，无需手动启动，直接输入相关指令，即可自动触发插件内的组件，例如：

  • 调用插件内的 SubAgent：@weld-defect-special 分析 weld.jpg 的焊后缺陷；

  • 调用插件内的 Skill：/skill image-preprocess 预处理 test.jpg；

  • 触发插件内的 Hooks：当监测到图像文件新增时，自动触发缺陷检测组件（需提前在 hooks.json 中配置）。

（2）插件管理命令（常用）
bash 复制代码 
# 查看已安装的插件
/plugin list

# 更新插件（更新到最新版本）
/plugin update 插件名称（如 industrial-vision-plugin）

# 卸载插件
/plugin uninstall 插件名称

# 查看插件详情（包含组件、版本、权限）
/plugin info 插件名称

# 查看插件市场列表
/plugin marketplace list

# 删除插件市场
/plugin marketplace remove 市场地址
（3）插件调试与排错

  • 插件无法识别：检查目录结构是否规范、plugin.json 清单是否存在、name 字段是否唯一；

  • 组件无法触发：检查组件目录路径是否正确、组件配置（如 SubAgent 的 description 关键词）是否准确；

  • 脚本调用失败：检查脚本路径是否正确、依赖是否安装、权限是否足够（如是否授予 Python 权限）；

  • 响应超时：检查插件内脚本的执行效率，避免冗余逻辑，确保 API 响应时间不超过 8 秒（官方阈值），非核心逻辑可异步处理。

四、工业视觉场景实战（自定义插件示例）

以"工业视觉缺陷检测插件"为例，完整展示插件的开发、安装与使用，可直接复制部署。

1. 插件目录与文件（完整可复制）
bash 复制代码 
industrial-vision-plugin/
├─ .claude-plugin/
│  └─ plugin.json
├─ agents/
│  ├─ industrial-vision-global.md
│  └─ weld-defect-special.md
├─ skills/
│  ├─ image-preprocess/
│  │  └─ SKILL.md
│  └─ code-format/
│     └─ SKILL.md
├─ scripts/
│  ├─ vision_detector.py
│  ├─ weld_detector.py
│  └─ common_utils.py
└─ hooks/
   └─ hooks.json
2. 核心文件内容（关键配置）
（1）plugin.json（清单）
json 复制代码 
{
  "name": "industrial-vision-plugin",
  "version": "1.0.0",
  "description": "工业视觉缺陷检测插件，整合通用表面缺陷检测、焊后缺陷专项检测、图像预处理、MVS相机控制能力，支持自动触发检测、生成质检报告与工艺优化建议。",
  "author": {
    "name": "工业视觉团队",
    "email": "vision-team@example.com"
  },
  "keywords": ["工业视觉", "缺陷检测", "焊后检测", "MVS相机", "质检报告"],
  "permissions": ["Read", "Write", "Python", "Glob", "Bash"]
}
（2）hooks.json（自动化触发）
json 复制代码 
{
  "hooks": [
    {
      "event": "file_created",
      "pattern": "*.jpg,*.png",
      "action": "call_agent",
      "agent": "industrial-vision-global",
      "args": ["检测图像缺陷", "${file_path}"]
    }
  ]
}

功能：当有 JPG/PNG 图像文件新增时，自动触发插件内的 industrial-vision-global SubAgent，检测图像缺陷。

3. 插件安装与使用演示

  1. 创建上述目录与文件，确保所有组件配置正确；

  2. 执行安装命令：/plugin install ./industrial-vision-plugin；

  3. 验证安装：/plugin list，确认 industrial-vision-plugin 已安装；

  4. 使用插件：

    • 手动调用：@weld-defect-special 分析 weld.jpg 的焊后缺陷，生成工艺建议；

    • 自动触发：新增一张 test.jpg 图像文件，插件自动触发缺陷检测，返回检测报告；

    • 调用 Skill：/skill image-preprocess 预处理 test.jpg，完成图像降噪、灰度化。

五、Plugin 与 Skill、SubAgent 区别（避坑关键）

很多人会混淆三者的关系，核心区别在于"定位与作用范围"，结合工业视觉场景总结如下，清晰区分选型边界：

对比维度 Plugin（插件） Skill（技能） SubAgent（子代理）
本质定位 组件集合的分发封装包（工具箱） 单一功能原子（工具） 独立专业分身（专家）
核心作用 整合、分发、管理多个组件，支持一键安装与分享 执行单一轻量任务（如图像预处理、代码格式化） 执行复杂专项任务（如焊后缺陷全流程检测）
执行环境 不直接执行任务，调度内部组件执行 共享主会话上下文 独立上下文，隔离运行
复用性 可跨项目、跨团队复用，支持版本管理 可被 SubAgent/Plugin 调用，通用型强 领域专属，复用性低（如焊后检测仅适配焊接场景）
工业视觉场景示例 industrial-vision-plugin（整合所有检测相关组件） 图像预处理、代码规范检查 焊后缺陷专项检测、MVS相机控制
核心逻辑：Skill 是基础工具，SubAgent 是用工具完成复杂任务的专家，Plugin 是将专家和工具打包的工具箱，方便分发与复用，三者协同构成 Claude Code 的扩展体系。

六、开发与使用注意事项

  • 目录与命名规范：严格遵循 kebab-case 命名，plugin.json 必须位于 .claude-plugin 目录下，组件目录（agents/skills 等）必须在插件根目录，不可嵌套在 .claude-plugin 内，否则无法被自动发现。

  • 权限管控：遵循最小权限原则，插件全局权限仅授予必要权限（如工业视觉插件无需授予 SSH 权限），内部组件可单独配置权限，避免权限越界；所有用户输入必须做严格校验，防止注入攻击等安全风险，这是官方审核的一票否决项。

  • 响应格式：插件内组件返回的结果需为标准 JSON 格式，必须包含"result"和"error"两个核心字段，方便 Claude Code 解析，避免直接返回纯文本或 HTML。

  • 版本管理：插件版本遵循语义化版本（如 1.0.0），更新插件时，需同步更新 plugin.json 中的 version 字段，方便团队成员识别版本差异。

  • 兼容性：插件开发需适配 Claude Code 最新版本，旧版本可能不支持部分组件（如 Hooks 自动化触发）；脚本依赖需明确，避免因依赖缺失导致插件无法使用。

  • 组件冗余：插件内仅保留必要的组件，无需添加未使用的目录（如无命令组件，可删除 commands 目录），减少插件体积，提升加载速度。

（注：Plugin 部分内容由 AI 生成）

Claude Code 万能模板 + 最佳实践（直接复制用）

一、万能基础模板（所有任务通用）

复制代码 
你是资深专业工程师，只输出可直接运行、简洁、无冗余代码。
任务：【一句话写清楚要做什么】
技术栈：【语言/框架/版本】
约束：
- 只改逻辑，不破坏原有结构
- 变量命名规范，注释简洁
- 无幻觉，不编造不存在API
- 输出diff格式，只给改动部分
步骤：先说明思路 → 再给代码 → 最后简要解释

二、写新功能（最常用）

复制代码 
你是资深工程师，写可生产环境使用的代码。
功能：【功能描述】
输入：【输入参数/格式】
输出：【返回值/格式】
要求：
- 模块化，单一职责
- 错误处理完整
- 代码可读，无多余注释
- 附带1个示例调用

三、修复Bug（最强）

复制代码 
帮我定位并修复Bug。
问题：【现象】
报错：【贴报错】
代码：【贴代码】
上下文：【相关逻辑】
期望行为：【应该怎样】
要求：
- 只修复问题，不改无关代码
- 输出diff
- 解释根因

四、重构/优化（必用）

复制代码 
帮我重构以下代码，保持功能完全不变。
优化目标：
- 可读性提升
- 减少重复
- 性能更好
- 符合规范
规则：
- 不改接口
- 不改逻辑
- 只输出diff

五、解释代码（快速理解）

复制代码 
帮我逐段解释这段代码：
【贴代码】
要求：
- 结构清晰
- 讲清逻辑流向
- 标出关键点/风险点
- 不用废话

六、让AI只输出改动（diff模式）

加这句，AI不会输出全量代码，效率翻倍：

复制代码 
只输出diff格式，不要全量文件，不要多余解释。

七、防止AI幻觉（关键）

每次不确定API时加：

复制代码 
禁止编造不存在函数/库/API。
不确定请查文档，不要瞎编。

八、最高效工作流（记住这4步）

  1. 贴上下文（相关代码/结构）
  2. 给明确任务（一句话）
  3. 加约束（技术栈、格式、禁止）
  4. 要diff（只看改动）

九、你要我直接给你定制模板吗？

告诉我你常用：

  • 语言（JS/TS/C++/Python？）
  • 场景（写工具？小游戏？Qt？Steam？）

我的万能 Prompt

直接问AI（豆包）

适配：工业视觉 / Qt / C++ / JS / .NET / 算法/缺陷检测 / 工程化

风格：直接可跑、少废话、diff 优先、防幻觉、强工程化

复制整段 → 每次发问题前直接粘贴，AI 输出质量会大幅稳定。

🚀 你的专属终极 Prompt（复制即用）

复制代码 
你是资深工业视觉 & 跨平台软件开发专家，熟悉 Qt/C++、C#/.NET、JavaScript、Python、深度学习缺陷检测。
我需要**生产级、可直接编译运行、无冗余、无幻觉、不编造不存在API**的代码。

【我的开发习惯与硬性约束】
- 代码风格：清晰、紧凑、工程化，变量/函数命名规范，注释只写关键逻辑
- 架构：模块化、单一职责、尽量低耦合，避免大函数
- 错误处理：必须完整，不吞异常，给出可定位的日志/返回
- 输出优先：**只给 diff 格式改动，不要全量文件**，除非我明确要完整代码
- 禁止：空话、示例占位、伪代码、编造函数/库/SDK接口
- 若涉及 Qt/海康MVS/Halcon/深度学习，必须符合真实SDK用法

【任务执行格式（严格遵守）】
1. 先给：根因/思路（1-3行）
2. 再给：代码（diff 或完整）
3. 最后给：关键说明（风险点/注意事项）

现在处理我的需求：

🔥 极简极速版（更短、一样强）

如果你不想每次发太长，用这个：

复制代码 
资深工业视觉开发专家。只输出可运行、无幻觉、真实API代码。
风格：紧凑工程化，错误处理完整。优先 diff。
思路→代码→说明。处理需求：

怎么用最爽（1 秒模板）

粘贴上面任意一段 → 后面直接写你的需求，例如：

复制代码 
（粘贴Prompt）
修复这段Qt QPoint坐标计算偏移bug，只改逻辑不改结构。
代码：...

4 个是超短、强约束、直接复制即用的场景专用 Prompt

超短、强约束、直接复制即用 的场景专用Prompt，完全贴合我：工业视觉 + Qt/C#/JS + 工程化 + 防幻觉。

1️⃣ 写新功能（极速版）

复制代码 
资深工业视觉开发。写可直接运行、真实API、无幻觉。
规范命名、错误处理、模块化。输出完整代码。
需求：

2️⃣ 改 Bug（最强定位）

复制代码 
只修Bug，不改结构，真实API。
先给根因，再给diff，最后关键点。
问题：
代码：

3️⃣ 重构优化（保逻辑）

复制代码 
重构：功能完全不变，提升可读性/性能。
不改接口，低耦合，精简。只输出diff。
代码：

4️⃣ 解释代码（工程师视角）

复制代码 
逐段解释逻辑、流向、风险点。
简洁专业，不废话，工程师视角总结。
代码：

用法（直接套）

复制任意一段 → 粘贴 → 后面写你的内容即可，质量极高。

梳理项目架构

项目结构

下面这个是专门给 Claude Code / Cursor 读整个项目 的超级 Prompt，
一次性贴进去，AI 就能理解你的工程结构、文件关系、技术栈、命名习惯 ，

之后你让它改代码、加功能、查 Bug 都会极度精准、不瞎改、不幻觉。

🔥 项目结构超级 Prompt（复制即用）

复制代码 
你现在是我的项目全局开发助手。
我会提供项目结构、关键文件、技术栈、业务逻辑。
请完整理解整个项目架构、模块关系、命名规范、依赖链路。

规则：
1. 只基于我提供的真实代码/结构，**绝对不编造不存在文件、函数、类、API**。
2. 理解跨文件调用关系，不破坏原有架构。
3. 修改优先输出 **diff**，不输出全量文件，除非我明确要求。
4. 错误处理、日志、边界条件必须完整。
5. 回答简洁专业，只给关键思路 + 代码 + 注意点。

现在请记住项目结构，等待我后续指令。

🔥 配合你项目使用的完整格式（直接这样发）

复制代码 
（粘贴上面超级Prompt）

【项目结构】
src/
  main.cpp
  utils/
    config.cpp
    log.cpp
  vision/
    detector.cpp
    camera.cpp  # 海康MVS相机
  ui/
    mainwindow.cpp  # Qt UI

【技术栈】
Qt 5.15.2 C++, CMake, OpenCV, 海康MVS, Halcon

【核心业务】
工业视觉缺陷检测：相机采集 → 图像处理 → AI推理 → 结果显示

然后你就可以直接说：

  • 给我优化 detector.cpp
  • 帮我修复 camera.cpp 掉线重连
  • 帮我加一个保存配置功能
  • 解释 mainwindow 流程

AI 都会基于整个项目结构来回答，不会乱改、不会断上下文。

下面这个是专门给 Claude Code / Cursor 用：自动梳理项目依赖 + 输出架构图（Mermaid）超级 Prompt

复制即用，AI 会自动分析结构、调用关系、数据流，直接生成可渲染架构图。

🧠 项目依赖 & 架构图 超级 Prompt（复制即用）

复制代码 
你是资深架构师，擅长分析工业视觉/Qt/C++项目结构与依赖关系。
请根据我提供的项目文件/代码，完成以下任务：

1. 梳理：
   - 模块划分
   - 文件依赖关系（谁引用谁）
   - 核心类/函数职责
   - 数据流走向
2. 输出：
   - 简洁文字总结（3--6 条）
   - 依赖关系树
   - **Mermaid 架构图（ flowchart 或 graph TD）**
     可直接复制到 Mermaid 工具渲染
3. 规则：
   - 不编造不存在的类/函数
   - 不废话，工程师视角
   - 图要清晰、分层、可维护

现在分析我的项目：

📌 使用示例（你这样发）

复制代码 
（粘贴上面 Prompt）

【项目结构】
main.cpp
Camera.cpp (MVS)
ImageProc.cpp (OpenCV)
Infer.cpp (AI缺陷检测)
MainWindow.cpp (Qt UI)
Config.cpp

AI 会返回：

  • 依赖树
  • 文字总结
  • 可直接渲染的 Mermaid 架构图

进阶超强版（自动画分层架构）

如果你想要更专业、分层清晰的架构图，用这个：

复制代码 
分析项目结构，输出：
1. 模块职责
2. 依赖关系
3. 分层架构图（Mermaid graph TD）
分为：UI层 → 业务层 → 视觉算法层 → 硬件驱动层 → 配置层
线条标注调用关系，简洁专业，不编造。

项目 README + 架构文档

📘 自动生成 README + 架构文档 超级 Prompt

复制代码 
你是资深工业视觉软件开发工程师，擅长撰写规范、清晰、可维护的项目文档。
根据我提供的项目结构、代码、功能，自动生成**完整项目 README.md + 架构说明**。

输出必须包含以下固定章节：

# 项目名称
## 1. 项目简介
## 2. 技术栈
## 3. 系统架构（分层 + 数据流）
## 4. 模块说明（每个模块职责）
## 5. 核心流程
## 6. 编译运行环境
## 7. 使用说明
## 8. 注意事项（坑点/兼容性/权限）
## 9. 目录结构

规则：
- 语言：简洁专业，工程师视角
- 不编造不存在功能、类、API
- 架构部分输出 **Mermaid 流程图**
- 结构清晰，可直接作为项目 README 使用

现在根据以下内容生成完整文档：

🔥 极简超强版（更短、输出更干净）

复制代码 
根据项目信息生成标准 README.md，包含：简介、技术栈、架构图(Mermaid)、模块、流程、环境、目录。
专业简洁，不废话，不编造。
生成：

使用方式（直接这样发）

复制代码 
（粘贴上面 Prompt）

【项目结构】
src/
  main.cpp
  ui/
    MainWindow.cpp
  vision/
    Camera.cpp (MVS)
    ImageProc.cpp
    Infer.cpp (缺陷检测)
  utils/
    Config.cpp
    Log.cpp

【技术栈】
Qt 5.15.2 C++、CMake、OpenCV、海康MVS、Halcon、TensorRT

【功能】
工业视觉缺陷检测系统：相机采集 → 图像处理 → AI推理 → 结果显示与保存

AI 会直接返回：
可直接保存为 README.md 的完整文档 + Mermaid 架构图。

相关推荐
夜郎king2 小时前
【码动四季】Trae + 腾讯地图 MCP 实战：让 AI 直接调用地图能力，一步到位
人工智能·trae实战·trae接入腾讯地图mcp·atomgit 码动四季
东离与糖宝2 小时前
Java 干掉 Python 垄断！LangChain4j + PgVector 本地知识库开发全流程
java·人工智能
适应规律2 小时前
深度学习第四版
人工智能·深度学习
东离与糖宝2 小时前
OpenClaw 企业级实战：Java 微服务集成 AI 智能体，自动处理业务流
java·人工智能
nap-joker2 小时前
使用Image - To - image条件生成对抗网络评估乳腺癌新辅助化疗反应的动态对比增强MRI血管渗透性映射
人工智能·神经网络·生成对抗网络
超级AI_mes2 小时前
智慧卤味，一码追溯：万界星空MES方案
人工智能·经验分享·5g·信息可视化·创业创新·制造·可视化ai
大囚长2 小时前
AI技术对VR发展的核心促进作用
人工智能·vr
xingyuzhisuan2 小时前
怎么快速在云上部署一个Stable Diffusion环境？（实操落地版）
人工智能·stable diffusion·ai绘画·gpu算力
Daydream.V2 小时前
OpenCV——人脸识别
人工智能·opencv·计算机视觉·人脸识别·人脸识别的三种算法·附代码实现
热门推荐
012026年3月AI领域大事件：DeepSeek引领开源风暴02GitHub 镜像站点03Qwen3.5-Omni与Qwen3.6模型全面解析（含测评/案例/使用教程）04Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services05UV安装并设置国内源06让 Trae IDE 智能体 “读懂”文档 Excel+PDF+DOCX ：mcp-documents-reader 工具使用指南07“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）08围棋-html版本09AI 编程效率翻倍：Superpowers Skills 上手清单 + 完整指南10纯 HTML/CSS/JS 实现的高颜值登录页，还会眨眼睛！少女心爆棚！