JoinQuant Skill
產生可在聚寬平台無修改直接執行的量化策略程式碼。
何時使用此技能
適合：
- 在聚寬進行股票回測 / 模擬交易 / 實盤交易
- ETF 輪動、多因子選股、動能、均值回歸策略
- 聚寬期貨策略
- 融資融券策略
- 策略程式碼審查 / Lint 以捕捉幻覺 API 與未來函數違規
- 將策略構想轉換為聚寬 API 呼叫
不適合：
- 不涉及聚寬的本地數據分析（請直接使用
jqdatasdk，或 pandas/numpy） - 在其他平台（vectorbt、backtrader、vn.py）進行策略回測（請改用那些平台的技能）
- 純機器學習模型訓練（不需使用聚寬特定 API）
- 透過非聚寬模擬交易的其他券商 API（CTP、Interactive Brokers 等需使用不同技能）進行實盤交易
預設模式
大多數使用者請求可歸為以下三種模式之一。請先辨識模式，再路由處理：
| 模式 | 觸發條件 | 動作 |
|---|---|---|
| 快速生成程式碼 | "幫我寫一個 X 策略" / "用聚寬實現 Y" | 選取模板，填寫使用者特定部分，回傳可直接貼上的程式碼 |
| API 問題 | "聚寬裡 get_price 的 fq 參數是什麼意思" / "set_option 有哪些選項" | 載入對應的 references/XX-*.md 並根據內容回答 |
| 程式碼審查 | "幫我 Review 一下我這段聚寬程式碼" / 貼上現有程式碼 | 對其進行心智 strategy_lint.py 檢查（或實際呼叫），指出幻覺 API 與遺漏的保護措施 |
漸進式資訊揭露：14 個 API 類別
請勿一次載入所有參考文件（總共 294KB，會消耗過多上下文）。根據使用者請求進行模式匹配，只載入相關類別的檔案：
| 類別 | 參考檔案 | 由關鍵字觸發 |
|---|---|---|
| 策略設定 | references/01-strategy-setup.md | initialize, set_benchmark, set_option, set_order_cost, set_slippage, run_daily, run_weekly, run_monthly |
| 數據獲取 | references/02-data-getters.md | get_price, attribute_history, history, get_current_data, get_fundamentals, get_money_flow, get_concept, get_industry |
| jqlib 因子庫 | references/03-jqlib.md | alpha101, alpha191, technical_analysis, jqfactor |
| 數據處理 | references/04-data-processing.md | get_factor_values, calc_factor_history, neutralize, winsorize, standardlize |
| 組合優化 | references/05-portfolio-optimization.md | optimizer, max_sharpe, min_variance, target_return, mean_variance |
| 交易函數 | references/06-trading.md | order, order_value, order_target, order_target_value, cancel_order, get_open_orders |
| 物件 | references/07-objects.md | Order, Position, Portfolio, OrderCost, OrderStyle, MarketOrderStyle, LimitOrderStyle |
| 其他函數 | references/08-misc-functions.md | record, log, write_file, send_message |
| 多投資組合 | references/09-multi-portfolio.md | set_subportfolios, SubPortfolioConfig, transfer_cash |
| Tick 級 | references/10-tick-strategy.md | tick, get_ticks, every_tick |
| 融資融券 | references/11-margin-trading.md | margincash_open, margincash_close, marginsec_open, marginsec_close, set_margin_rate |
| 期貨 | references/12-futures.md | get_dominant_future, futures, set_future_commission |
| 歸因分析 | references/13-attribution-analysis.md | brinson, factor analysis, attribution |
| 引擎機制 | references/14-strategy-engine.md | 撮合, 復權, 滑點, 稅費, 風險指標, alpha, beta, sharpe, max drawdown |
如果使用者提到一個不在任何關鍵字清單中的函數名稱，請使用 scripts/api_search.py <keyword> 在所有參考文件中搜尋。
模板
5 個生產級模板位於 templates/ 目錄：
| 模板 | 使用時機 |
|---|---|
01-basic-single-stock.py | 初次使用者，單一股票，簡單的均線交叉策略。聚寬的「Hello World」。 |
02-multi-factor.py | 多因子選股（PE / 市值 / 動能），每月再平衡。最常見的「實際」策略結構。 |
03-etf-rotation.py | 根據動能排行進行 ETF 輪動。散戶投資者間很受歡迎。 |
04-momentum-stock.py | 股票池的橫斷面動能策略，每週再平衡。 |
05-mean-reversion.py | 布林通道 / RSI 均值回歸策略。考慮波動率。 |
生成程式碼時，從模板開始，進行修改，不要從頭撰寫。原因如下：
- 模板已包含樣板程式碼（set_benchmark、set_option、set_order_cost、set_slippage）
- 模板具有正確的時機設定（run_daily / run_weekly 搭配正確的 time 參數）
- 模板避免了未來函數陷阱（使用基於計數而非基於日期的切片）
Lint 工具
在回傳生成的程式碼給使用者之前，請以心智（或實際）方式執行 strategy_lint.py：
python scripts/strategy_lint.py <user_strategy.py>
關鍵檢查項目：
- ❌ 幻覺 API 呼叫（例如
jqdata.get_stock_data()不存在） - ❌ 未來函數：使用非計數的
get_price或attribute_history並硬編碼未來日期 - ❌ 缺少
set_option('use_real_price', True)（準確回測所必需） - ❌ 缺少
set_order_cost(...)和set_slippage(...) - ❌ 在
before_trading_start/after_trading_end內下單（不允許，會被拒絕） - ❌ 使用已棄用的 API（例如
update_universe） - ⚠️ 建議使用
g.全域變數來跨 bar 保存狀態，而非模組層級的全域變數 - ⚠️ 建議對高相關性資產使用叢集感知的倉位管理
生成時必須保留的重點
給出策略建議時，絕對不能遺漏：
- 務必設定
use_real_price=True。傳統的前復權價格會有未來函數偏差。這點沒得商量。 set_order_cost和set_slippage是強制性的。沒有它們，回測就不符合現實，會誤導使用者。run_daily的 time 參數很重要。'open'在 09:30 執行，'every_bar'在每個 Bar（分鐘或日線）執行。選擇錯誤會導致執行時機不正確。g.是唯一安全的全域狀態。模組層級的全域變數在某些聚寬環境中會跨執行序泄漏。- 資金管理方面
order_value優於order。手動計算股數在股票分割時容易出錯。 - 再平衡時使用
order_target_value，不要自己計算「當前市值 - 目標市值」。 - 不要在聚寬內部執行
pip install。平台是沙盒環境，只能使用其預裝的函式庫。
工作流程
一個典型的端到端策略會話：
1. 使用者以自然語言描述策略構想
2. AI：選取匹配的模板（例如 03-etf-rotation.py）
3. AI：提出 2-3 個澄清問題：
- 標的池範圍（指數成分 / 自訂列表）
- 調倉頻率（日 / 週 / 月）
- 風險控制（停損 / 倉位上限 / 行業中性化）
4. AI：修改模板生成策略程式碼
5. AI：執行心智 Lint 檢查（或實際執行）— 修復問題
6. 使用者：將程式碼貼入聚寬線上編輯器，點擊「編譯運行」
7. 如有錯誤：重新載入相關的 references/XX-*.md，進行修復
8. 使用者：檢視回測曲線，反覆迭代
對於高風險（實盤交易）策略，另外需要：
- 參考
references/14-strategy-engine.md了解滑點、手續費、風險指標 - 如果涉及槓桿，參考
references/11-margin-trading.md - 明確討論模型風險（過度擬合、市場機制轉變、交易成本的真實性）
檔案列表
| 檔案 | 角色 |
|---|---|
README.md | 專案簡介 |
WORKFLOW.md | 策略開發的端到端流程（✅ 完成） |
INSTALL_CN.md | 中文安裝指南（✅ 完成） |
api文档/api.txt | 原始 294KB API 文件（原始備份） |
references/01-14-*.md | 14 個漸進式資訊揭露類別檔案（✅ 全部完成） |
templates/01-05-*.py | 5 個生產級模板（✅ 完成） |
scripts/strategy_lint.py | Lint 工具 — 黑/白名單混合（✅ 可運作） |
scripts/strategy_scaffold.py | 根據描述生成策略骨架（✅ 可運作） |
scripts/api_search.py | 根據關鍵字搜尋 API（✅ 可運作） |
examples/case-mean-reversion/ | 端到端案例：RSI 均值回歸（✅） |
examples/case-etf-rotation/ | 端到端案例：ETF 月度輪動（✅） |
examples/bad-strategy-for-lint-test.py | 用於 Lint 迴歸測試的負面案例（✅） |
factors/ | (v2) Barra 風格因子庫，7 個類別 |
factor_lab/ | (v2) 單因子 IC / 分組 / 衰減分析 |
research_importer/ | (v2) 券商研究報告 PDF 轉換為聚寬程式碼 |
jqskill_mcp/ | (v2) MCP 伺服器，暴露所有技能能力 |
tests/ | pytest 測試（v2 後超過 50 個測試通過） |
此技能目前版本為 0.5.0（2026-04-19）。所有 14 個參考文件 + 5 個模板 + 3 個腳本 + 13 個測試 + WORKFLOW + 2 個範例已完成。