Claude Code Plugin

@hasheeai/claude-code-plugin 是 Hashee 官方的 Claude Code 通道适配器：让你正在用的 Claude Code CLI 以一个 Agent 身份在 Hashee 里和真人 / 群组聊天，所有 E2EE 加解密由 @hasheeai/agent-sdk-ts 处理。

技术真源：docs/sdk/Hashee_Claude_Code_Plugin_Spec_v1.0.md + Plugin Channel Parity Rules。

工作模型

进程模型：Claude Code CLI 启动时按 .mcp.json spawn 本插件作为 stdio MCP server provider 子进程（JSON-RPC 2.0 over stdin/stdout）。
与 Hashee：插件内部通过 @hasheeai/agent-sdk-ts 维持到 Hashee 后端的 WebSocket 长连接（认证用 Agent Token）。
入站（Hashee → Claude Code）：用户消息 → SDK 解密 → 转换为 MCP notification 推到 Claude Code 会话窗口。
出站（Claude Code → Hashee）：Claude Code 调 plugin 的 MCP tool （如 hashee_send_message）→ plugin 通过 SDK 加密发回。
持久化：~/.hashee/<agent_id>/keystore.json (mode 0600) 存密钥
- 公钥同步状态。

安装

Step 1 — 在 Hashee app 创建 Agent

按在 Hashee app 里创建 Agent 拿到 agent_id 和 agent_token。

Step 2 — 装包

# 全局或项目级都可以
npm install -g @hasheeai/claude-code-plugin
# 或在项目里
pnpm add @hasheeai/claude-code-plugin

Step 3 — 在 `.mcp.json` 注册

在你的 Claude Code 项目根目录或 ~/.claude.json 添加：

{
  "mcpServers": {
    "hashee": {
      "command": "npx",
      "args": ["-y", "@hasheeai/claude-code-plugin"],
      "env": {
        "HASHEE_AGENT_ID": "<your-agent-uuid>",
        "HASHEE_AGENT_TOKEN": "hsk_xxxx...",
        "HASHEE_SERVER_URL": "https://api.hashee.ai",
        "HASHEE_ALLOWED_USERS": "<comma-separated user-uuid>",
        "HASHEE_CONNECTION_MODE": "websocket"
      }
    }
  }
}

字段说明：

env 变量	必填	说明
`HASHEE_AGENT_ID`	是	Agent UUID
`HASHEE_AGENT_TOKEN`	是	`hsk_...` token
`HASHEE_SERVER_URL`	否	默认 `https://api.hashee.ai`；staging 用 `https://staging-api.hashee.ai`
`HASHEE_ALLOWED_USERS`	否	逗号分隔的用户 UUID 白名单。填即生效——只有这些 user 的消息会被推到 Claude Code，其他静默丢弃。空字符串则后端 H2A 关系决定
`HASHEE_CONNECTION_MODE`	否	默认 `websocket`；可选 `polling`

Step 4 — 重启 Claude Code

完全退出 Claude Code 重启。在会话里输入 /mcp 查看连接状态：

hashee: ✓ Connected
Tools: hashee_send_message, hashee_get_messages, hashee_list_conversations,
       hashee_typing, hashee_send_artifact, hashee_stream_reply,
       hashee_send_file, hashee_download_attachment, hashee_react_message,
       hashee_plugin_event_log

或用 CLI：

claude mcp list
# hashee: ✓ Connected

Step 5 — 验证消息往来

让 Claude Code 调一个 tool：

User: 列出我当前在 Hashee 里的活跃会话
Claude: [calling hashee_list_conversations]
        { conversations: [...] }

然后从 Hashee app 给你 Agent 发一条消息，Claude Code 会话窗口应该出现：

[hashee channel] new message from <user_id>:
"你好"

至此配对完成。

10 个 MCP Tool 详解

Tool	入参关键字段	用途
`hashee_send_message`	`conversation_id`, `text`	发文本消息
`hashee_get_messages`	`conversation_id`, `limit` (≤50), `before`	拉历史消息
`hashee_list_conversations`	`limit`, `cursor`	列活跃会话
`hashee_typing`	`conversation_id`, `duration_ms`	发”正在输入”指示
`hashee_send_artifact`	`conversation_id`, `artifact` (subtype + payload)	发结构化卡片
`hashee_stream_reply`	`conversation_id`, `text`, `chunk_size`, `interval_ms`	流式输出（默认 100 字符 / 30ms）
`hashee_send_file`	`conversation_id`, `file_path`, `mime?`, `caption?`	上传本地文件并发送（≤ 100MB）
`hashee_download_attachment`	`attachment_id`, `conversation_id`, `dest_path`	下载收到的附件到本地
`hashee_react_message`	`message_id`, `emoji`	给消息加 reaction
`hashee_plugin_event_log`	`limit`	读 plugin 内部事件日志（debug 用）

入站方向（Hashee → Claude Code）

每条用户消息变成一个 MCP notification（notifications/claude/channel）推给 Claude Code 会话；Claude Code 在窗口顶部打印：

[hashee] from <user_id> (<user_display_name>):
  conversation_id: <uuid>
  payload: { type: "text", text: "你好" }

Claude Code 由用户决定如何回复——你可以让它直接调 hashee_send_message 回，也可以先做事再调 hashee_send_artifact / hashee_send_file。

HASHEE_ALLOWED_USERS 不为空时，仅这些用户的消息被推；其他被静默丢弃， plugin stderr 打印 skipped message from unlisted sender。

限制与已知踩坑

❌ 不要在 .mcp.json 里写 cwd——Claude Code 不 honor。把入口改用绝对路径或 npx -y。
❌ env 字段不能用 shell 占位符 $VAR——必须写字面量字符串。
❌ hashee_send_file 的 file_path 必须在 Claude Code 当前 cwd 内——../ 穿越被拒。
❌ 文件大小硬上限 100 MB。
❌ streaming 节奏写死：100 字符 / 30ms 不可改。
❌ 不支持 markdown + image inline 一起——文件和 artifact 是分开的 tool。
❌ HASHEE_ALLOWED_USERS 空字符串 ≠ 全开——空字符串等价于”全部丢弃”。正确”全开”配置是完全去掉这一条 env（让后端 H2A 关系决定）。

故障排查

1. `/mcp` 显示 `hashee: ✗ Failed`

# 在 Claude Code 项目目录手动跑插件看 stderr
HASHEE_AGENT_ID="..." HASHEE_AGENT_TOKEN="..." \
HASHEE_SERVER_URL="https://api.hashee.ai" \
HASHEE_ALLOWED_USERS="..." \
npx -y @hasheeai/claude-code-plugin

预期 stderr：

[hashee-claude-code-plugin] starting Claude Code Plugin...
[hashee-claude-code-plugin] agent connected
[hashee-claude-code-plugin] Claude Code Plugin listening on stdio MCP

如果看到 401 → token 错；404 → agent_id 错；ConfigError → env 漏字段。

2. 消息发不到 Claude Code

HASHEE_ALLOWED_USERS 是否包含该发件人？
Hashee app 看 Agent 是否显示”在线”
看 hashee_plugin_event_log 输出是否有 inbound 记录但没推

3. AGENT_KEYS_MISMATCH

# 删除本地 keystore，让 plugin 重新生成 + 注册
rm -rf ~/.hashee/<agent_id>/
# 重启 Claude Code

注意：删除 keystore 后对方公钥也变了，原对话方的设备可能要触发”重新建立加密通道”。 V1 透明处理，但偶有手动重新发起的需要。

安全注意

所有加密由 SDK 负责；plugin 内部不实现加密。
私钥永远不离开本地 ~/.hashee/<agent_id>/，且文件权限 0600。
HASHEE_ALLOWED_USERS 是额外白名单（窄于后端 H2A）。
Claude Code 调 tool 是它自己的决策——plugin 不会 forge tool call。

演示视频

视频文字版逐节描述

00:00 – 00:10 — 终端 Claude Code 启动，/mcp 命令显示 hashee: ✓ Connected
- 10 个 tool 列表。
00:10 – 00:25 — Hashee app 中创建一个名为 “ClaudeBot” 的 Agent，添加为联系人。在私聊里发”列出我最近 5 条会话”。Claude Code 终端显示 [hashee] from <user>: ...
- Claude 自动调用 hashee_list_conversations → 返回数组 → 调 hashee_send_message 回复。
00:25 – 00:40 — Hashee app 收到 Claude 的回复，列出 5 个会话名称与最后消息时间。
00:40 – 00:55 — 演示 artifact：用户问”做一张投票卡拉面披萨沙拉”。 Claude 决策调用 hashee_send_artifact → Hashee app 中显示三选项投票卡。
00:55 – 01:10 — 演示文件：用户发”画一张 SDK 架构图保存到桌面”。 Claude 调用本地 dot / mermaid 工具生成 PNG，再调 hashee_send_file 上传到 Hashee。Hashee app 中收到图片消息，可点击查看。

下一步

Codex Plugin — 另一个 plugin
OpenClaw Plugin — 另一个 plugin
三个 Plugin 怎么选 — 决策对比
Plugin Channel Parity Rules — plugin 设计原则