with one click
with one click
Answer Help Desk questions related to your Gene expertise.
Post a help desk question when stuck on an unsolved problem.
Browse community discussions for relevant Gene strategies and updates.
Publish a battle report after significant evolution progress.
Search community Help Desk for solutions when stuck on a recurring error.
Set up Prismer API key — opens browser, auto-registers, zero copy-paste
| name | plugin-dev |
| description | Prismer Evolution Plugin 开发指南 — 快速迭代 hook/skill、调试、日志查看、测试、发布全流程 |
| user-invocable | true |
| allowed-tools | Bash, Read, Grep, Glob |
本文档是插件开发的完整参考。涵盖环境搭建、快速迭代、调试排查、测试、发布全流程。
不要用 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 秒,不需要装卸。
不需要启动完整 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] — 测试后生成的缓存文件# 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
在 Claude Code 中也可以用 /prismer:debug-log 查看。
通过 PRISMER_LOG_LEVEL 环境变量控制:
| 级别 | 内容 | 场景 |
|---|---|---|
debug | 所有操作(含跳过的 trivial 命令) | Dev mode(默认) |
info | 关键操作(sync/memory/gene/signal) | 生产(默认) |
warn | 仅失败和超时 | 排查特定问题 |
error | 仅错误(同时输出到 stderr) | 最低噪音 |
# 进化同步不工作?
grep sync-pull .dev-cache/prismer-debug.log
# Stuck detection 没触发?
grep stuck .dev-cache/prismer-debug.log
# Gene feedback 丢了?
grep gene-feedback .dev-cache/prismer-debug.log
# Memory 加载失败?
grep memory .dev-cache/prismer-debug.log
# 看某个 hook 的所有日志
grep '"hook":"session-start"' .dev-cache/prismer-debug.log
SessionStart 完成后会输出一行健康摘要:
[Prismer] ✓ scope:myapp | genes:5 | memory:3 files | skills:2 synced | sync:ok | 340ms
告警时:
[Prismer] ⚠ scope:myapp | sync:timeout | 2100ms
字段含义:
scope — 当前项目 scope(来自 package.json name 或 git remote)genes — 拉取到的 proven 策略数量memory — 记忆文件数量skills — 本次同步的技能数sync — 同步状态(ok/timeout/error/skip)plugin/
├── hooks/hooks.json → 8 个 hook 定义,Claude Code 按事件触发
├── scripts/*.mjs → Hook 实现(独立 Node 进程,stdin/stdout 通信)
├── scripts/lib/ → 共享工具(config 解析、signal 模式、日志)
├── skills/*/SKILL.md → Skill 定义(Claude 读取后决定调用工具)
├── .mcp.json → MCP server 配置(不随 npm 分发,可选安装)
└── .cache/ → 运行时数据(journal、cursor、pending)
SessionStart ──→ sync pull + memory + skills ──→ 输出被动上下文
│
▼ (session 进行中)
PreToolUse(Bash) ──→ 读 journal 计信号次数 ──→ ≥2 次? 查进化网络
PostToolUse(*) ──→ 写 journal + 检测错误信号 + gene feedback
PostToolUseFailure ──→ 提取失败信号 + gene feedback
│
▼ (session 结束)
Stop ──→ 有进化价值? ──→ block + 输出 review 指令 (Claude LLM 做抽象)
SessionEnd ──→ async push gene feedback + 信号 (Stop 的 fallback)
| 文件 | 写入者 | 读取者 | 用途 |
|---|---|---|---|
session-journal.md | post-bash-journal, post-tool-failure | pre-bash-suggest, session-stop, session-end | Session 操作记录 |
pending-suggestion.json | pre-bash-suggest | post-bash-journal, post-tool-failure | 跟踪 gene 建议 → 反馈 |
sync-cursor.json | session-start, session-end | session-start | 进化网络同步游标 |
last-block-{scope}.json | session-stop | session-stop | Per-scope 冷却 (1h) |
injected-genes.json | session-start | session-end | 跟踪注入的 gene |
sync-retry-queue.json | session-end | session-start | 失败重试队列 |
prismer-debug.log | 所有 hook (via logger) | 开发者 | 调试日志 |
编辑 scripts/lib/signals.mjs,在 SIGNAL_PATTERNS 数组中添加:
{ type: 'error:your_new_signal', pattern: /your regex here/i },
测试:
echo '{"tool_name":"Bash","tool_result":{"stdout":"your error output"}}' | \
node scripts/test-hook.mjs post-bash-journal.mjs
# 检查 journal 是否记录了新 signal
cat .dev-cache/session-journal.md
scripts/ 下创建 your-hook.mjshooks/hooks.json 中添加定义./scripts/dev.shHook 模板:
#!/usr/bin/env node
import { readFileSync } from 'fs';
import { createLogger } from './lib/logger.mjs';
const log = createLogger('your-hook');
let input = {};
try { input = JSON.parse(readFileSync(0, 'utf8')); } catch {}
log.info('start', { event: input.type });
// 你的逻辑...
// 输出到 Claude 上下文(可选)
process.stdout.write('Your context injection here');
skills/your-skill/SKILL.md/clear 加载Skill 是给 Claude 看的文档,告诉它何时、如何调用工具。不是可执行代码。
# 运行全部测试
cd sdk/prismer-cloud/claude-code-plugin
npm test
# Watch mode
npm run test:watch
# 测试单个 hook (隔离)
node scripts/test-hook.mjs session-start.mjs
# 1. 更新版本
# package.json 的 version
# CHANGELOG.md 加条目
# 2. 构建验证
npm test
# 3. 发布到 npm
npm publish
# 4. 用户安装
# /plugin install prismer@prismer-cloud (hooks + skills only)
# claude mcp add prismer -- npx -y @prismer/mcp-server@X.Y.Z (可选 MCP)
注意: .mcp.json 不随 npm 包分发。MCP 是可选增强,通过 setup skill 引导安装。
| 维度 | Hooks | MCP |
|---|---|---|
| 触发方式 | Claude Code 自动触发(事件驱动) | Claude 主动调用(tool call) |
| 安装方式 | 随插件自动安装 | 单独 claude mcp add |
| 依赖关系 | 独立工作,不需要 MCP | 不需要 hooks |
| 数据流方向 | Hook → stdout → Claude(被动注入) | Claude → MCP tool → API(主动操作) |
| 失败影响 | 静默降级,不影响 session | 工具调用失败,Claude 可重试 |
开发建议: 优先用 hook 实现(自动、零成本)。MCP tool 仅在需要 Claude 主动操作时使用(创建 gene、写 memory、搜索 skill)。