jq-bridge-skill

Claude Code Skill for JoinQuant (聚宽) 本地策略开发。

通过 WebSocket 桥接，让 Claude Code 可以直接用自然语言控制聚宽网页端的策略推送、回测触发、日志拉取等操作。

架构

+--------------+     WebSocket      +--------------+     WebSocket      +-------------+
| Claude Code  |  | jq-bridge    |  | Chrome 插件 |
| (本 Skill)   |                   | (端口19523)  |                   | (聚宽页面)  |
+--------------+                   +--------------+                   +-------------+

项目结构

jq-bridge-skill/
├── skill.md                    # Claude Code 指令文件（放入 ~/.claude/skills/）
├── README.md                   # 本文档
├── requirements.txt            # Python 依赖
├── bridge/
│   ├── jq_bridge.py            # WebSocket 桥接服务
│   └── jq_cli.py               # 命令行工具
└── chrome_plugin/              # Chrome 扩展源码
    ├── manifest.json
    ├── background.js
    ├── content_script.js       # 页面交互 + 日志捕获
    ├── page_bridge.js          # 编辑器/回测控制
    ├── popup.js
    └── sidebar/
        ├── sidebar.html
        └── sidebar.js          # 侧边栏 + 策略同步

安装

1. 安装 Skill

# 克隆到 Claude Code skills 目录
git clone https://github.com/youngyunxing/jq-bridge-skill.git ~/.claude/skills/jq-bridge

2. 安装依赖

pip install -r ~/.claude/skills/jq-bridge/requirements.txt

依赖：aiohttp, websockets

3. 安装 Chrome 插件

1. 打开 Chrome → chrome://extensions/ → 开启「开发者模式」
2. 点击「加载已解压的扩展程序」
3. 选择 ~/.claude/skills/jq-bridge/chrome_plugin/ 目录
4. 插件图标会出现在 Chrome 工具栏

4. 启动桥接服务

python ~/.claude/skills/jq-bridge/bridge/jq_bridge.py start

服务运行在 ws://127.0.0.1:19523/ws，同时提供 HTTP health 检查：http://127.0.0.1:19523/health

5. 使用

在 Claude Code 中打开策略项目目录，直接对话：

• “推送当前策略并运行回测”
• “看看回测结果”
• “报什么错了？”
• “设置回测时间为 2024 年全年”

CLI 命令参考

所有命令通过 python bridge/jq_cli.py 执行：

全局选项：所有命令支持 --name 或 --id 指定目标页面。不指定时按文件名自动匹配。

与策略项目协同

桥接服务会自动向上查找包含 strategies/ 目录的项目根目录，因此 CLI 可以在策略项目的任意子目录下运行。

标准工作流

1. 推送并运行回测

1. 确定策略文件路径
2. python bridge/jq_cli.py push  [--name ]
3. python bridge/jq_cli.py compile [--name ]
4. 等待 10-15 秒
5. python bridge/jq_cli.py pull logs [--name ]
   （自动同时拉取日志和错误信息）
6. 向用户汇报结果

2. 排查错误

当用户说"看看报什么错了"时：

1. pull logs 获取日志（自动包含错误信息）
2. 分析错误类型：
   • SyntaxError / IndentationError：Python 语法问题
   • NameError：变量/API 未定义（如 get_factor_values 不存在）
   • avoid_future_data 报错：盘中获取日线时 end_date 用了当天日期，应改为 context.previous_date
   • KeyError / IndexError：DataFrame 字段访问错误
3. 给出修复建议并重新推送

3. 设置回测参数

python bridge/jq_cli.py params \
  --start 2024-01-01 \
  --end 2024-12-31 \
  --cash 100000 \
  --benchmark 000300.XSHG \
  --name "羊驼策略"

常见问题

环境变量

• JQUAN_BRIDGE_URL — WebSocket 地址，默认 ws://127.0.0.1:19523/ws

License

MIT

研究环境支持（v1.0.54+）

插件扩展匹配 joinquant.com/research 与 /user//*（Jupyter Classic 研究环境），以「研究环境」身份注册到桥接：

• 文件操作（REST）：research list / read / push / rename / copy / mkdir / delete
• 运行与内核：research run （推送到聚宽运行、拉回文本/错误/图片）、research restart、research status
• 详见 skill.md 研究环境章节

日志 API 直连（v1.1.0+）

pull logs 通过聚宽内部接口分页全量拉取（滚动抓取已删除）：

• 后台标签页可完整拉取；自动附带回测统计与版本校验
• 完整日志自动保存到项目根 logs/，终端默认打印摘要（--full 完整）

插件自动更新（v1.1.16+）

• 提交插件代码 → post-commit hook 通知桥接 → 广播 → 所有页面自动重载
• 版本号自动递增（pre-commit hook）；版本检查兜底 + 30 秒策略名同步
• 详见 skill.md「插件自动更新」章节