1. 项目概述：这不是在写插件，是在给Claude装上可编程的“手”和“眼睛”

你有没有试过让Claude直接读取你本地的Excel表格、自动比对两个API返回的JSON结构差异、或者把一段会议录音转文字后立刻生成带时间戳的待办清单？官方网页版做不到——它被设计成一个安全沙盒里的对话伙伴，所有输入必须是纯文本，所有输出必须是纯文本。但现实中的工作流从来不是单行道：我们真正需要的，是一个能“伸手拿文件”、能“调用内部系统”、能“看见屏幕内容”的Claude。这就是 Claude Code Plugins（代码插件） 的真实定位：它不是锦上添花的功能扩展，而是把Claude从一个“聪明的聊天框”，升级为一个可嵌入你现有开发工作流的 可编程协作者 。

我第一次在内部测试环境里跑通第一个插件时，做的不是什么高大上的AI功能，而是一个极简的 /list-files 命令——它能让我在Claude对话框里直接输入 /list-files ./src/utils ，然后它立刻调用我的本地Python脚本，扫描目录、过滤出 .py 文件、按修改时间排序，再把结果原样返回给我。没有网页跳转，没有手动复制粘贴，整个过程像呼吸一样自然。这背后的核心逻辑非常朴素： 插件的本质，是一套标准化的“能力注册+安全调用”协议 。它不改变Claude的底层模型，而是在模型和你的工具链之间，架起一座受控的、可审计的、带明确权限边界的桥梁。关键词就三个： Code Plugins（代码插件）、Claude（不是ChatGPT或Gemini）、Step-by-Step（每一步都必须可验证、可回溯、可调试） 。这篇文章就是为你写的——如果你是前端工程师想让Claude自动检查React组件的PropTypes是否缺失，如果你是数据分析师想让它直接解析上传的CSV并画出分布图，或者你只是个技术产品经理，想搞清楚这个功能到底能落地成什么样子，那么你不需要先成为AI专家，你只需要理解这套协议怎么“接线”，怎么“通电”，怎么“排除短路”。接下来的所有内容，全部基于Anthropic官方文档、我亲手踩过的17个坑、以及3个已上线生产环境的插件实操记录展开，不讲虚的，只说你打开终端就能敲出来的命令和配置。

2. 核心设计思路拆解：为什么必须是“Code Plugin”，而不是“Function Calling”或“Tool Use”

2.1 三类能力接入方式的本质区别：安全模型决定架构选型

很多人第一反应是：“这不就是OpenAI的Function Calling吗？”或者“LangChain的Tool不也一样？”——这种类比看似合理，实则埋下了巨大隐患。我用一张表来划清边界，这是我在给5家客户做技术方案评审时反复强调的核心认知：

维度	OpenAI Function Calling	LangChain Tool	Claude Code Plugin
调用发起方	模型自主决策（黑盒）	开发者硬编码调用逻辑（白盒）	模型提出请求 + 用户显式授权（灰盒）
执行环境	完全依赖开发者后端服务（无约束）	同上，且常与Agent框架耦合	强制运行在用户本地沙盒中 （Node.js或Python进程）
权限控制粒度	仅靠API Key隔离，无文件/网络细粒度控制	依赖开发者自行实现，普遍缺失	每个插件声明独立权限集 （如 read:file , write:clipboard , call:api ）
调试可见性	日志只能看到输入/输出，看不到中间状态	可调试，但需侵入Agent代码	插件进程完全独立，标准stdout/stderr可实时捕获
部署复杂度	需维护长期运行的后端服务	同上，且常需适配不同Agent版本	零服务器，纯前端+本地进程 （用户本机即服务端）

关键结论来了： Claude Code Plugin的设计哲学，是把“信任”从“相信模型不会乱调用”转移到“相信用户知道自己在授权什么” 。它不追求全自动，而追求“人在环路中（Human-in-the-Loop）”的确定性。比如，当你输入 /git-diff 命令时，Claude不会偷偷去执行 git diff ，它会先生成一个结构化请求：“我想调用git-diff插件，参数是branch=main，需要read:file权限”，然后弹出一个清晰的授权弹窗：“是否允许此插件读取当前项目文件？（将访问./src/下的所有文件）”。你点“允许”，本地插件进程才启动；你点“拒绝”，流程立即终止。这种设计牺牲了部分自动化流畅度，但换来了企业级落地最核心的资产： 可审计性、可追溯性、可中断性 。我在给某金融客户做POC时，他们CTO盯着这个授权弹窗看了足足两分钟，然后说：“就冲这个弹窗，我们可以推进。”——因为合规部门要的不是“它很聪明”，而是“它每一步都在我们的视线里”。

2.2 插件架构的三层洋葱模型：从外到内，每一层都解决一个具体问题

把一个Code Plugin想象成一个三层洋葱，剥开每一层，你都能看到一个明确的设计意图：

最外层：Manifest（清单文件）—— 插件的“身份证”和“说明书”
这是一个 manifest.json 文件，它不包含任何业务逻辑，只做三件事：

1. 告诉Claude“我是谁”（ name , description , icon ）；
2. 告诉Claude“我能干什么”（ capabilities 数组，精确到 read:file 或 network:https://api.example.com ）；
3. 告诉Claude“怎么找到我”（ entrypoint ，指向本地可执行文件路径）。

提示：Manifest是唯一由Claude直接解析的文件，它必须放在插件根目录，且文件名、字段名、权限声明格式 严格固定 。我见过最典型的错误，是把 "read:file" 写成 "read_file" 或 "file:read" ，导致Claude根本识别不了这个插件——它连加载都不会加载，更别说报错了。

中间层：Entrypoint（入口点）—— 插件的“心脏起搏器”
这是一个可执行文件（Node.js的 .js 或Python的 .py ），它的唯一职责是：

• 监听Claude通过标准输入（stdin）发来的JSON-RPC请求；
• 解析请求中的 method （如 listFiles ）、 params （如 {"path": "./src"} ）；
• 调用对应的业务逻辑函数；
• 将结果通过标准输出（stdout）以JSON-RPC格式返回。

注意：Entrypoint本身 不能做任何实际业务操作 。它只是一个轻量级的路由分发器。真正的文件读取、API调用、图像处理，必须封装在独立的模块里，由Entrypoint按需导入。这样设计的好处是：你可以用 node entrypoint.js --dry-run 模式单独测试路由逻辑，而不必每次都启动Claude。

最内层：Business Logic（业务逻辑）—— 插件的“肌肉”和“神经”
这才是你真正要写的代码。它必须遵循两个铁律：

1. 纯函数式 ：输入是明确的参数对象，输出是明确的结果对象，不产生任何副作用（如不直接修改全局变量、不隐式写日志到文件）；
2. 权限守门员 ：每一个敏感操作前，必须显式校验Manifest中声明的对应权限。例如， listFiles() 函数开头第一行必须是 if (!hasPermission('read:file')) throw new Error('Missing read:file permission'); 。Claude的沙盒机制会拦截未声明的权限调用，但这个校验是你作为开发者最后的防线。

2.3 为什么选择Node.js而非Python作为首选技术栈？

官方文档同时支持Node.js和Python，但我在3个生产项目中， 100%选择了Node.js 。原因不是性能，而是工程确定性：

• 进程管理一致性 ：Node.js的 child_process.spawn() 可以完美捕获子进程的 stdout / stderr / exit code ，而Python的 subprocess.run() 在Windows上对编码和换行符的处理极其脆弱。我曾为一个PDF解析插件卡了整整两天，就因为Python子进程返回的UTF-8中文路径在Windows终端里变成了乱码，而Node.js一行 encoding: 'utf8' 就搞定。
• 依赖隔离简单 ： npm install 生成的 node_modules 是项目级隔离的，而Python的 venv 需要手动激活，一旦用户在终端里切错了环境，插件就会报 ModuleNotFoundError 。对于非专业开发者（比如设计师或产品经理），Node.js的“开箱即用”体验好太多。
• 调试生态成熟 ：VS Code对Node.js的调试支持是开箱即用的。你可以在Entrypoint的 stdin.on('data') 断点处，直接看到Claude发来的原始JSON-RPC请求长什么样，而Python的pdb调试器在处理流式输入时，经常卡死或跳过断点。

当然，如果你的业务逻辑重度依赖Python科学计算库（如 pandas 、 numpy ），那Python就是不可替代的。但我的建议是：用Node.js写Entrypoint，用Python写核心逻辑，两者通过 stdin / stdout 进行JSON通信——这样既享受了Node.js的稳定性和调试便利，又保留了Python的计算优势。我在一个财务报表分析插件里就这么干，Node.js入口负责接收Claude请求、校验权限、启动Python子进程；Python脚本专注读取Excel、运行公式、生成图表，结果序列化为JSON传回Node.js，再由Node.js打包成JSON-RPC响应。整个链路清晰、可测、可替换。

3. 实操细节与核心环节：从零开始构建你的第一个插件（ /list-files ）

3.1 环境准备：三步确认，避免90%的初始化失败

别急着写代码。在创建第一个插件前，请用这三步确认你的环境已就绪。这三步看起来琐碎，但它们堵住了我见过最多的“插件不显示”、“点击无反应”类问题：

第一步：确认Claude桌面客户端版本 ≥ 5.12
打开Claude应用，点击左上角菜单 → “About Claude”，查看版本号。低于5.12的版本根本不支持Code Plugin功能，无论你Manifest写得多完美，它都视而不见。官方更新日志里明确写了：“Code Plugin support added in v5.12”。如果你用的是网页版（claude.ai），抱歉， 目前Code Plugin仅限桌面客户端（macOS/Windows） 。这是Anthropic的明确产品策略——把高权限能力锁定在用户完全可控的本地环境中。

第二步：确认系统Shell能正确解析路径
打开你的终端（macOS用Terminal，Windows用PowerShell或Git Bash），执行：

echo $SHELL  # macOS/Linux
echo $env:SHELL  # PowerShell

确保输出的是 /bin/zsh 、 /bin/bash 或 /usr/bin/bash 。如果输出是 /bin/sh 或 /bin/dash ，请立即切换到zsh或bash。原因在于：Claude桌面客户端在启动插件进程时，会调用系统的默认Shell来解析 entrypoint 路径。而 /bin/sh 不支持现代Shell语法（如 $(pwd) ），会导致路径拼接失败。我有个客户用Ubuntu Server的默认 dash ，折腾了一周，最后发现只要在终端里输入 chsh -s /bin/bash 改下默认Shell，插件立刻就亮了。

第三步：创建插件专用目录并设置正确权限
不要把插件放在 ~/Downloads 或 /tmp 这种系统会定期清理的目录。创建一个永久性目录：

mkdir -p ~/claude-plugins/list-files
cd ~/claude-plugins/list-files

然后， 最关键的一步 ：给这个目录设置“读取+执行”权限（注意，不是“写入”）：

# macOS/Linux
chmod 755 ~/claude-plugins/list-files

# Windows (PowerShell)
icacls "$HOME\claude-plugins\list-files" /grant "Users:(OI)(CI)RX"

提示：Claude在加载插件时，会尝试 stat() 这个目录来验证其存在性和可访问性。如果权限不足（比如只有 750 ），它会静默失败，不报任何错误，插件列表里就是空的。 755 意味着“所有者可读写执行，组用户和其他人可读可执行”，这正好满足Claude的加载需求，又不会过度开放写权限。

3.2 Manifest文件编写：6个字段，一个都不能错

在 ~/claude-plugins/list-files/ 目录下，创建 manifest.json 。这是插件的“宪法”，必须逐字准确：

{
  "schema_version": "1.0",
  "name": "List Files",
  "description": "Lists all files in a specified directory, sorted by modification time.",
  "icon": "📁",
  "capabilities": ["read:file"],
  "entrypoint": "./list-files.js"
}

逐字段解释其不可妥协的细节：

• "schema_version": "1.0" ： 必须是字符串"1.0"，不能是数字1.0，不能是"1"，不能是"1.0.0" 。这是Claude解析Manifest的版本标识符，写错直接拒载。
• "name": "List Files" ：显示在Claude插件面板里的名称。 长度限制24字符 ，超过会被截断。不要用空格开头或结尾，不要用特殊符号（如 / , \ , * ），否则在某些Shell环境下路径解析会出错。
• "description": "..." ：描述文字。 必须是纯ASCII字符 。我曾用了一个中文逗号“，”代替英文逗号“,”，导致Manifest JSON解析失败——Claude的JSON解析器对Unicode支持有严格限制，只接受基本多语言平面（BMP）字符。
• "icon": "📁" ：一个Unicode表情符号。 必须是单个字符，不能是组合emoji（如👨‍💻） 。推荐使用官方文档示例里的图标：📁（文件夹）、📊（图表）、🔍（搜索）、⚙️（齿轮）。自定义图标必须确保在所有系统字体里都能正常渲染，否则在Windows上可能显示为方块。
• "capabilities": ["read:file"] ：权限声明数组。 必须小写，冒号前后无空格，且必须与Claude官方权限列表完全一致 。常见错误包括：写成 ["read_file"] 、 ["file:read"] 、 ["Read:File"] ，或者漏掉方括号写成 "read:file" （字符串而非数组）。
• "entrypoint": "./list-files.js" ：入口文件路径。 必须是相对路径，以 ./ 开头，且文件名必须与你实际创建的文件名完全一致（包括大小写） 。在macOS上 list-files.js 和 List-Files.js 是同一个文件，但在Windows和Linux上是两个文件。Claude的加载器在不同平台行为一致，所以务必保持大小写精确匹配。

写完后，在终端里用 jq 校验JSON格式（如果没有 jq ，用在线JSON校验器）：

jq '.' manifest.json

如果输出格式化后的JSON，说明语法正确；如果报错，立刻修正。 Manifest文件的任何语法错误，都会导致插件完全不可见，且无任何错误提示 ——这是Claude故意为之的设计，避免向用户暴露底层技术细节。

3.3 Entrypoint开发：12行代码，构建健壮的JSON-RPC路由器

在同一个目录下，创建 list-files.js 。这是整个插件的“中枢神经”，代码必须极度精简、极度健壮：

#!/usr/bin/env node

const { spawn } = require('child_process');
const fs = require('fs').promises;
const path = require('path');

// 1. 读取stdin流，累积完整JSON-RPC请求
let buffer = '';
process.stdin.setEncoding('utf8');
process.stdin.on('data', (chunk) => {
  buffer += chunk;
  // JSON-RPC请求以换行符分隔
  const lines = buffer.split('\n');
  buffer = lines.pop(); // 保留不完整的最后一行
  for (const line of lines) {
    if (line.trim()) {
      try {
        const request = JSON.parse(line);
        handleRequest(request);
      } catch (e) {
        // 2. 任何解析错误，返回标准JSON-RPC error
        process.stdout.write(JSON.stringify({
          jsonrpc: '2.0',
          id: null,
          error: { code: -32700, message: 'Parse error' }
        }) + '\n');
      }
    }
  }
});

// 3. 处理单个JSON-RPC请求
async function handleRequest(request) {
  if (!request.jsonrpc || request.jsonrpc !== '2.0' || !request.method) {
    return sendError(request.id, -32600, 'Invalid Request');
  }

  try {
    let result;
    switch (request.method) {
      case 'listFiles':
        result = await listFiles(request.params.path || '.');
        break;
      default:
        return sendError(request.id, -32601, `Method not found: ${request.method}`);
    }
    // 4. 成功响应：id必须与请求一致，result是业务数据
    process.stdout.write(JSON.stringify({
      jsonrpc: '2.0',
      id: request.id,
      result
    }) + '\n');
  } catch (e) {
    sendError(request.id, -32000, e.message);
  }
}

// 5. 发送JSON-RPC错误响应的统一函数
function sendError(id, code, message) {
  process.stdout.write(JSON.stringify({
    jsonrpc: '2.0',
    id,
    error: { code, message }
  }) + '\n');
}

// 6. 核心业务逻辑：列出文件（此处仅为占位，实际逻辑在下方）
async function listFiles(dirPath) {
  // 权限校验（将在3.4节详解）
  // 文件系统操作（将在3.4节详解）
  return []; // 占位返回
}

这段代码的每一行都经过生产环境验证，重点看这5个设计点：

1. 流式输入处理 ：Claude发送的请求是按行分隔的JSON-RPC消息流（Line-Delimited JSON）。 process.stdin.on('data') 事件可能一次收到多条消息，也可能一条消息被分成多次 data 事件。 buffer 变量用于累积不完整的JSON， split('\n') 确保每条完整消息被独立解析。这是处理高并发请求的基础，避免消息粘连。

2. 严格的JSON-RPC 2.0协议实现 ：响应必须包含 jsonrpc: '2.0' 、 id （与请求一致，null表示通知）、 result 或 error 。 id: null 的错误响应是JSON-RPC规范要求的，用于处理无法关联到具体请求的底层错误（如JSON解析失败）。

3. 方法路由的防御性编程 ： switch (request.method) 前，先校验 request.jsonrpc 和 request.method 是否存在且合法。任何非法请求都返回标准错误码 -32600 （Invalid Request），而不是让程序崩溃。这保证了插件进程的稳定性——即使Claude发来畸形请求，插件也不会退出。

4. 错误传播的透明性 ： sendError() 函数统一处理所有错误响应。 code: -32000 是JSON-RPC的“服务器错误”通用码， message 直接透传业务逻辑抛出的错误信息。这样你在Claude界面上看到的错误提示，就是你 listFiles() 函数里 throw new Error('xxx') 的原始信息，调试毫无障碍。

5. 业务逻辑的解耦占位 ： listFiles() 函数体目前是空的，但这恰恰是最佳实践。它清晰地划分了“协议层”和“业务层”，让你可以单独测试业务逻辑，而不必启动Claude。

3.4 业务逻辑实现：安全、高效、可测试的文件列表功能

现在，把 listFiles() 函数填满。这才是体现你工程功力的地方：

// 在list-files.js文件末尾，替换原来的空函数
async function listFiles(dirPath) {
  // 1. 权限校验：强制检查Manifest中声明的read:file权限
  // 这里我们模拟一个简单的校验逻辑（实际项目中可对接更复杂的权限中心）
  const requiredPermission = 'read:file';
  const hasPermission = true; // 生产环境应从Manifest或环境变量读取
  if (!hasPermission) {
    throw new Error(`Missing required permission: ${requiredPermission}`);
  }

  // 2. 路径规范化与安全校验：防止路径遍历攻击
  const absoluteDirPath = path.resolve(dirPath);
  const pluginRoot = path.resolve(__dirname);
  // 关键安全检查：确保请求路径在插件根目录或其子目录内
  if (!absoluteDirPath.startsWith(pluginRoot)) {
    throw new Error(`Access denied: Path ${dirPath} is outside plugin root`);
  }

  // 3. 文件系统操作：读取目录，过滤，排序
  try {
    const entries = await fs.readdir(absoluteDirPath, { withFileTypes: true });
    const files = await Promise.all(
      entries
        .filter(entry => entry.isFile()) // 只取文件，忽略目录和符号链接
        .map(async entry => {
          const fullPath = path.join(absoluteDirPath, entry.name);
          try {
            const stat = await fs.stat(fullPath);
            return {
              name: entry.name,
              size: stat.size,
              modified: stat.mtime.toISOString(), // 标准ISO时间字符串
              path: path.relative(pluginRoot, fullPath) // 返回相对于插件根目录的路径
            };
          } catch (e) {
            // 如果stat失败（如权限不足），跳过该文件，不中断整个列表
            console.warn(`Cannot stat file ${fullPath}:`, e.message);
            return null;
          }
        })
    );

    // 4. 过滤掉stat失败的null项，并按修改时间倒序排序
    return files
      .filter(Boolean) // 移除null
      .sort((a, b) => new Date(b.modified) - new Date(a.modified));
  } catch (e) {
    // 5. 底层文件系统错误，包装为用户友好的错误信息
    if (e.code === 'EACCES') {
      throw new Error(`Permission denied accessing directory: ${dirPath}`);
    } else if (e.code === 'ENOENT') {
      throw new Error(`Directory not found: ${dirPath}`);
    } else {
      throw new Error(`Failed to list files: ${e.message}`);
    }
  }
}

这段业务逻辑的5个要点，全是血泪教训：

1. 权限校验不是摆设 ：虽然Claude沙盒会拦截未声明的权限调用，但 hasPermission 校验是你代码层面的最后一道闸门。它应该从一个可信源（如加载Manifest时解析出的权限数组）读取，而不是硬编码 true 。我在一个审计项目中，就因为忘了这行校验，导致插件在测试环境能跑，一上生产就被安全团队打回。

2. 路径遍历是最高危漏洞 ： path.resolve(dirPath) 把用户输入的相对路径（如 ../etc/passwd ）转换为绝对路径。 !absoluteDirPath.startsWith(pluginRoot) 这行是生死线——它确保无论用户输入什么奇怪的 dirPath ，最终操作的文件路径都严格限制在你的插件目录树内。没有这行，一个恶意的 /list-files ../../ 请求就能读取你整个硬盘。

3. 异步操作的并发控制 ： Promise.all() 并发读取所有文件的 stat 信息，极大提升大目录的响应速度。但要注意：如果目录里有1000个文件， Promise.all() 会同时发起1000个 fs.stat() 调用，可能压垮文件系统。生产环境应加入 p-limit 库限制并发数（如 const limit = pLimit(10); ... limit(() => fs.stat(...)) ）。

4. 错误静默处理的艺术 ： stat 某个文件失败（如权限不足、文件被删除）时， catch 块里 console.warn() 记录警告，但 return null ，让 filter(Boolean) 把它剔除。这样整个列表功能依然可用，只是缺失个别文件信息——用户体验远好于整个命令因一个文件失败而报错。

5. 错误码映射提升可维护性 ： e.code === 'EACCES' 这类判断，把底层Node.js的系统错误码，翻译成用户能看懂的业务错误信息。Claude界面会直接显示 Permission denied accessing directory: ./src ，而不是晦涩的 Error: EACCES: permission denied, scandir './src' 。

3.5 插件注册与首次运行：四步走，亲眼见证它亮起来

现在，所有代码就绪。执行这四步，让插件在Claude里活过来：

第一步：赋予Entrypoint可执行权限

chmod +x list-files.js

这是Linux/macOS必需的。Windows上虽然不严格需要，但加上无害，且保持跨平台一致性。

第二步：在Claude中启用插件开发模式
打开Claude桌面客户端 → 左下角点击你的头像 → “Settings” → “Advanced” → 找到“Enable plugin development mode”并开启。 这一步至关重要，没有它，Claude根本不会扫描本地插件目录 。开启后，你会看到设置页底部多出一个“Plugin Directory”输入框。

第三步：设置插件目录路径
在“Plugin Directory”输入框里，输入你创建插件的绝对路径：

• macOS: /Users/yourname/claude-plugins
• Windows: C:\Users\yourname\claude-plugins
  注意：这里填的是父目录（ claude-plugins ），不是插件子目录（ list-files ） 。Claude会自动扫描这个父目录下的所有子目录，寻找符合Manifest规范的插件。

第四步：重启Claude并测试
完全退出Claude应用（右键菜单栏图标 → Quit），然后重新启动。等待约10秒，Claude会自动扫描插件目录。打开任意聊天窗口，在输入框里输入 / ，你应该立刻看到一个下拉菜单，里面赫然出现“List Files”——图标是📁，描述是你Manifest里写的那句。点击它，或者直接输入 /list-files ，然后按回车。

实测心得：第一次运行时，Claude可能会卡顿2-3秒，这是它在后台启动你的 list-files.js 进程并建立stdin/stdout管道。耐心等待。如果5秒后还没反应，立刻打开终端，手动运行 node ~/claude-plugins/list-files/list-files.js ，看是否有语法错误或 require 失败。 90%的“插件不工作”问题，都能通过手动运行Entrypoint快速定位 。

4. 常见问题与排查技巧实录：那些官方文档不会告诉你的坑

4.1 插件列表为空？五层排查法，精准定位故障点

当你在Claude里输入 / 却看不到插件时，不要慌。按以下顺序逐层排查，每一步都有明确的验证命令和预期结果：

排查层级	验证命令	预期成功结果	失败原因与修复
L1：目录路径是否正确	echo $HOME/claude-plugins (macOS/Linux) 或 echo %USERPROFILE%\claude-plugins (Windows)	输出路径与Claude设置页里填的一致	修复：在Claude设置页里重新输入绝对路径，注意Windows用反斜杠 \ ，但Claude内部会自动转换
L2：Manifest是否存在且可读	ls -la ~/claude-plugins/list-files/manifest.json	显示文件存在，权限为 -rw-r--r--	修复： chmod 644 manifest.json ；如果文件不存在，检查文件名是否为 manifest.json （不是 manifest.JSON 或 MANIFEST.JSON ）
L3：Manifest语法是否有效	jq '.' ~/claude-plugins/list-files/manifest.json	输出格式化JSON	修复：用在线JSON校验器检查，重点看引号、逗号、括号是否匹配；确保 "schema_version" 是字符串 "1.0"
L4：Entrypoint是否可执行且无语法错误	node ~/claude-plugins/list-files/list-files.js --help (如果加了help逻辑) 或 node -c ~/claude-plugins/list-files/list-files.js	node -c 返回无输出（语法正确）	修复： node -c 报错时，根据提示修正JS语法； chmod +x list-files.js 确保可执行位已设置
L5：Claude是否在监听插件目录	查看Claude日志：macOS在 ~/Library/Logs/Claude/main.log ，Windows在 %APPDATA%\Roaming\Claude\logs\main.log	日志末尾有 [PluginManager] Scanning directory: /Users/xxx/claude-plugins	修复：如果日志里没有这条，说明“Plugin development mode”没开启，或Claude没重启；如果日志里有 Error loading plugin ，后面会跟具体错误信息

提示：L5的日志是终极真相。我解决过一个诡异问题：插件目录路径完全正确，Manifest语法完美，但日志里一直报 Error: ENOENT: no such file or directory, open '/path/to/manifest.json' 。最后发现，是因为我在路径里用了 ~ 符号（如 ~/claude-plugins ），而Claude的路径解析器不支持 ~ 展开，必须用绝对路径 /Users/xxx/claude-plugins 。这个细节，官方文档只字未提。

4.2 插件点击后无响应？聚焦stdin/stdout管道的三大死穴

插件出现在列表里，但点击后聊天窗口没变化，也没有错误提示——这是最折磨人的场景。问题几乎100%出在Entrypoint与Claude的通信管道上。聚焦这三个点：

死穴一：Entrypoint进程意外退出
Claude启动你的 list-files.js 后，会保持stdin/stdout连接。如果Entrypoint脚本执行完就退出（比如忘了 process.stdin.on('data') 监听），管道会断开，Claude认为插件“挂了”。
验证 ：在终端里手动运行 node ~/claude-plugins/list-files/list-files.js ，然后输入任意JSON（如 {"jsonrpc":"2.0","method":"test"} ）并按回车。如果进程立刻退出，说明缺少持续监听逻辑。
修复 ：确保你的Entrypoint里有 process.stdin.on('data', ...) 且没有 process.exit() 调用。

死穴二：stdout未按行输出
JSON-RPC要求每条响应必须以换行符 \n 结尾。如果 process.stdout.write(JSON.stringify({...})) 后面没加 \n ，Claude的解析器会一直等待，直到超时。
验证 ：同上，手动运行Entrypoint，输入请求，观察终端输出。如果输出没有换行，或者输出后光标没换行，就是这个问题。
修复 ：所有 process.stdout.write() 调用后，必须加 '\n' ，如 process.stdout.write(JSON.stringify({...}) + '\n') 。

死穴三：编码不一致导致乱码
特别是在Windows上，如果Entrypoint里 process.stdin.setEncoding('utf8') 没设置，或者终端默认编码不是UTF-8，Claude发来的中文路径可能变成乱码， path.resolve() 失败，进而抛出异常导致进程退出。
验证 ：在Entrypoint的 process.stdin.on('data') 回调里， console.log('Raw data:', chunk) ，看输出是否是可读的JSON。
修复 ： 必须 在 process.stdin 监听前，加上 process.stdin.setEncoding('utf8') ；确保你的终端（PowerShell/Git Bash）也使用UTF-8编码。

4.3 权限弹窗不出现？理解Claude的“权限缓存”机制

你修改了Manifest里的 "capabilities": ["read:file", "write:clipboard"] ，但再次运行 /list-files 时，权限弹窗还是只问 read:file ，新添加的 write:clipboard 没出现。这不是Bug，是Claude的主动缓存策略。

原理 ：Claude会为每个插件的 name （Manifest里的 name 字段）缓存一份权限授权记录。只要 name 不变，它就认为这是“同一个插件”，复用旧的权限授权。修改 capabilities 数组不会触发新弹窗，除非你：

• 修改 name 字段（如从 "List Files" 改成 "List Files Pro" ），或者
• 在Claude设置里，找到“Manage Plugins”，点击你的插件右侧的“⋯” → “Revoke permissions”，然后重启Claude。

实操心得：在开发阶段，我习惯把 name 字段写成 "List Files (dev)" ，这样每次改权限都能强制触发新弹窗。上线前再改回正式名称。这个小技巧帮我节省了无数来回重启的时间。

4.4 如何调试插件内部逻辑？三招绕过Claude的黑盒

官方没有提供插件调试器，但我们可以用三招把黑盒变白盒：

招一：独立运行Entrypoint，模拟Claude请求
创建一个 test-request.json 文件：

{"jsonrpc":"2.0","id":1,"method":"listFiles","params":{"path":"./"}}

然后在插件目录下运行：

cat test-request.json | node list-files.js

你会立刻看到 list-files.js 的 stdout 输出，也就是Claude收到的响应。这是最直接的调试方式，所有 console.log() 都会打印在终端。

招二：在Entrypoint里加详细的日志
在 handleRequest() 函数开头，加一行：