plugin-dev

Prismer Plugin 开发指南

本文档是插件开发的完整参考。涵盖环境搭建、快速迭代、调试排查、测试、发布全流程。

---

1. 快速开始 — Dev Mode

不要用 npm publish + /plugin install 的循环。 使用本地开发模式：

cd sdk/prismer-cloud/claude-code-plugin
./scripts/dev.sh

这做了什么：

• 用 claude --plugin-dir . 直接加载本地文件（不走 npm）
• 使用独立的 .dev-cache/ 目录（不污染生产 cache）
• 自动设 PRISMER_LOG_LEVEL=debug

修改 hook 后怎么生效：

你改了什么	怎么生效
hook script (scripts/*.mjs)	在 Claude Code 里输入 /clear（2 秒）
skill 内容 (skills/*/SKILL.md)	/clear 或 /reload-plugins
hooks.json (新增/删除 hook)	退出 Claude Code 重新运行 ./scripts/dev.sh
.mcp.json	不影响（dev mode 不加载 .mcp.json）

迭代循环： 改代码 → /clear → 测试 → 看日志 → 再改。每次 2 秒，不需要装卸。

---

2. Hook 隔离测试

不需要启动完整 Claude Code 就能测试单个 hook：

# 测试 SessionStart (模拟 startup 事件)
node scripts/test-hook.mjs session-start.mjs

# 测试 SessionStart (模拟 resume 事件)
node scripts/test-hook.mjs session-start.mjs --event resume

# 测试 PostToolUse (模拟 Bash 工具完成)
echo '{"tool_name":"Bash","tool_input":{"command":"npm run build"},"tool_result":{"stdout":"error TS2345"}}' | \
  node scripts/test-hook.mjs post-bash-journal.mjs

# 测试 PreToolUse stuck detection (模拟重复错误)
echo '{"tool_name":"Bash","tool_input":{"command":"npm run build"}}' | \
  node scripts/test-hook.mjs pre-bash-suggest.mjs

# 带自定义环境变量
node scripts/test-hook.mjs session-start.mjs --env PRISMER_API_KEY=sk-prismer-test-xxx

# 详细输出（含环境变量）
node scripts/test-hook.mjs session-start.mjs --verbose

输出说明：

• [STDOUT] — 会注入到 Claude 上下文的内容
• [STDERR] — 调试日志（不显示给 Claude）
• [Exit: N] — 退出码（0 = 正常）
• [Cache files] — 测试后生成的缓存文件

---

3. 日志与调试

3.1 查看调试日志

# Dev mode 日志
tail -f .dev-cache/prismer-debug.log

# 格式化输出（更可读）
tail -20 .dev-cache/prismer-debug.log | while IFS= read -r line; do
  echo "$line" | node -e "
    const l=JSON.parse(require('fs').readFileSync(0,'utf8').trim());
    console.log(\`[\${l.ts.slice(11,19)}] \${l.lvl.toUpperCase()} [\${l.hook}] \${l.msg}\`,
      Object.fromEntries(Object.entries(l).filter(([k])=>!['ts','lvl','hook','msg'].includes(k))))
  " 2>/dev/null
done