WorkBuddy PandaData MCP 强制覆盖
本节优先于本 Skill 后续所有数据源、依赖安装和命令示例。WorkBuddy 版只允许使用已连接的
pandadata Connector:先调用 auth_status,再按共享 Runtime Skill 中的已登记路由调用
call_pandadata。本地 PandaData SDK、直接 HTTP、凭证文件和历史下载脚本在此版本中均
已禁用。必须执行空数据复查并在最终答案附完整调用回执;未打开 DATA_GATE 不得分析。
WorkBuddy PandaData MCP 强制覆盖
本节优先于本 Skill 后续所有数据源、依赖安装和命令示例。WorkBuddy 版只允许使用已连接的
pandadata Connector:先调用 auth_status,再按共享 Runtime Skill 中的已登记路由调用
call_pandadata。本地 PandaData SDK、直接 HTTP、凭证文件和历史下载脚本在此版本中均
已禁用。必须执行空数据复查并在最终答案附完整调用回执;未打开 DATA_GATE 不得分析。
WorkBuddy PandaData MCP 强制覆盖
本节优先于本 Skill 后续所有数据源、依赖安装和命令示例。WorkBuddy 版只允许使用已连接的
pandadata Connector:先调用 auth_status,再按共享 Runtime Skill 中的已登记路由调用
call_pandadata。本地 PandaData SDK、直接 HTTP、凭证文件和历史下载脚本在此版本中均
已禁用。必须执行空数据复查并在最终答案附完整调用回执;未打开 DATA_GATE 不得分析。
{
"version": 1,
"task": {
"placeholder": "请提供量化研报、论文、PDF、网页或文本,并说明期望复现范围",
"required": true
},
"fields": [
{
"key": "focus",
"label": "复现重点",
"type": "text",
"placeholder": "如:全文翻译、某个因子、有效性验证或回测策略"
}
],
"prompt_template": "{{#task}}任务与材料:\n{{task}}\n\n{{/task}}{{#attachments}}用户上传的材料(已放入工作区):\n{{attachments}}\n\n{{/attachments}}请端到端复现所给量化报告或论文{{#focus}},重点关注 {{focus}}{{/focus}}:完成中文全文翻译、研究摘要与因子公式重构、真实可溯源数据验证、无前视偏差的 BACKTEST 策略及本地回测、中文可读报告和最终交付摘要;无法执行的环节须如实记录,输出中文报告。"
}
Report Replication BACKTEST
Purpose
Turn a quant report, paper, PDF, webpage, or text source into a complete research delivery package under /home/coder/project/replication/report-replication:
- Full Chinese translation of the original report or paper.
- Chinese AI summary plus factor formula reconstruction in Markdown.
- Chinese factor validation report as standalone HTML, with charts, metrics, audit notes, and plain-language explanations for users who do not know quantitative jargon.
- BACKTEST strategy code plus a Chinese backtest explanation HTML. Preserve raw BACKTEST engine output separately when needed.
- Chinese final delivery summary.
This skill is self-contained for translation, factor reconstruction, factor validation, bundled local BACKTEST execution, optional external BACKTEST execution, and final delivery. Do not call any legacy framework-specific skills, scripts, data layers, examples, or assumptions.
Pandadata is the default production market-data source. Use WorkBuddy call_pandadata to download daily stock, index, futures, Hong Kong, or US market data into 03_factor_validation/data_cache/ before factor validation or BACKTEST. User-provided or report-supplied files may be used only when Pandadata does not cover the required dataset, and the fallback must be documented in manifest.json, the validation report, and the final summary.
Credentials must come from WorkBuddy-managed authentication, WorkBuddy-managed authentication, WorkBuddy-managed authentication, or WorkBuddy-managed authentication. Never write usernames, passwords, tokens, or raw credential files into generated artifacts, logs, commits, or reports. Record only that credential values were not persisted.
Language And Readability Rules
- All user-facing deliverables must use Chinese as the primary language:
full_translation.md, ai_summary_and_factor_formula.md, factor_validation_report.html, backtest_report.html, final_delivery_summary.md, and explanatory comments/docstrings in generated strategy code.
- English may appear only when unavoidable: original paper titles, proper names, formulas, code identifiers, CSV column names, API names, ticker/symbol names, metric abbreviations, and short parenthetical glossary labels such as
IC or Sharpe.
- Do not deliver English narrative sections, English-only reports, or mojibake/garbled Chinese. If a tool generates English or garbled HTML, wrap or rewrite it into a Chinese reader-facing artifact and preserve the raw file separately for audit.
- Before final delivery, spot-check the main readable files for Chinese readability rather than relying only on automated quality gates.
- Explain quant concepts as if the reader is smart but new to quant research. Prefer restrained science writing: concise, concrete, and evidence-led.
Chart Image Text Rules
- Text rendered inside generated chart image files must be English ASCII only. This includes PNG/SVG titles, subtitles, axis labels, legends, colorbar labels, annotation text, heatmap labels, in-image table headers, and watermarks.
- Keep Chinese explanations outside the image in the HTML/Markdown captions and chart explanation blocks. The report can remain Chinese-readable while the chart pixels stay font-compatible.
- When using Matplotlib, Seaborn, Plotly static export, or another image renderer, use broadly available Latin fonts such as
DejaVu Sans or Arial. Do not set CJK chart fonts such as SimHei, SimSun, Microsoft YaHei, Noto Sans CJK, or Source Han Sans.
- Prefer English chart labels from
references/factor_validation_checklist.md, for example Benchmark NAV Comparison, not Chinese translations. If the original factor/report name is Chinese, draw an ASCII-safe display label in the chart and keep the original Chinese name in the surrounding report text.
Required Output Contract
Create one project directory per report:
/home/coder/project/replication/report-replication/{report_id}/
01_translation/full_translation.md
02_factor_reproduction/ai_summary_and_factor_formula.md
02_factor_reproduction/reference_implementation.py
03_factor_validation/factor_validation_report.html
03_factor_validation/data/
03_factor_validation/data/ie_factor_matrix.csv
03_factor_validation/data/direction_matrix_from_strategy.csv
03_factor_validation/data/portfolio_returns_ew_full.csv
03_factor_validation/data/portfolio_returns_ew_is.csv
03_factor_validation/data/portfolio_returns_ew_oos.csv
03_factor_validation/data/portfolio_returns_dir_full.csv
03_factor_validation/data/portfolio_returns_dir_is.csv
03_factor_validation/data/portfolio_returns_dir_oos.csv
03_factor_validation/data/ic_series.csv
03_factor_validation/data/factor_diagnostics.csv
03_factor_validation/data/coverage_by_date.csv
03_factor_validation/data/missing_by_asset.csv
03_factor_validation/data/quantile_returns.csv
03_factor_validation/data/rolling_metrics.csv
03_factor_validation/data/yearly_performance.csv
03_factor_validation/data/turnover_series.csv
03_factor_validation/data/benchmark_comparison.csv
03_factor_validation/data/backtest_alignment_audit.csv
03_factor_validation/charts/
03_factor_validation/charts/01_ie_distribution.png
03_factor_validation/charts/02_ic_series.png
03_factor_validation/charts/03_is_oos_ic_comparison.png
03_factor_validation/charts/04_cumulative_nav_equal_weight.png
03_factor_validation/charts/05_cumulative_nav_strategy_direction.png
03_factor_validation/charts/06_drawdown.png
03_factor_validation/charts/07_ic_distribution.png
03_factor_validation/charts/08_rolling_ic.png
03_factor_validation/charts/09_quantile_nav.png
03_factor_validation/charts/10_quantile_return_bar.png
03_factor_validation/charts/11_yearly_return_heatmap.png
03_factor_validation/charts/12_turnover_series.png
03_factor_validation/charts/13_data_coverage_heatmap.png
03_factor_validation/charts/14_missing_value_heatmap.png
03_factor_validation/charts/15_benchmark_nav_comparison.png
03_factor_validation/charts/16_backtest_alignment_nav.png
03_factor_validation/charts/17_parameter_stability_heatmap.png
03_factor_validation/charts/18_cost_sensitivity.png
03_factor_validation/charts/19_walkforward.png
03_factor_validation/data_cache/
03_factor_validation/data_cache/pandadata_market_data.csv
03_factor_validation/data_cache/pandadata_market_data.csv.metadata.json
04_backtest_strategy/strategy.py
04_backtest_strategy/config.json
04_backtest_strategy/backtest_report.html
04_backtest_strategy/backtest_report_raw.html (optional raw BACKTEST engine report)
04_backtest_strategy/backtest_logs/signal_log.jsonl
04_backtest_strategy/backtest_logs/equity_curve.csv
04_backtest_strategy/backtest_logs/performance_metrics.csv
04_backtest_strategy/backtest_logs/trades.csv
04_backtest_strategy/backtest_logs/position_return_detail.csv
06_delivery/final_delivery_summary.md
failure_report.md
manifest.json
Read references/output_contract.md before writing final artifacts.
Honesty Rules
- Say exactly what was done. If a step was not run, state that it was not run.
- Do not fabricate walk-forward results, cost-sensitivity results, IC series, charts, backtest reports, or BACKTEST logs.
- If BACKTEST cannot run, or if data is unavailable or insufficient, document the blocker and mark the conclusion as inconclusive.
- Every chart, table, and metric in the HTML report must be traceable to a file under
03_factor_validation/data/, a chart under 03_factor_validation/charts/, or a BACKTEST artifact.
- Every chart and key metric in the HTML report must also be explained in plain language: what it means, how to read it, what the current result implies, and which data/artifact it came from.
Subagent Governance
This skill does not require subagents. Default to a single main-agent workflow unless the current task is too large and a subagent would materially reduce risk or time.
If a subagent/background agent is used:
- The main agent remains fully responsible for correctness and final delivery.
- Subagent outputs are drafts only. They must never be copied into final artifacts without main-agent review.
- Subagents must write only under
/home/coder/project/replication/report-replication/{report_id}/.agent_work/ or another explicitly isolated scratch directory.
- Subagents must not overwrite final artifacts such as
factor_validation_report.html, strategy.py, signal_log.jsonl, manifest.json, or delivery summaries.
- The main agent must independently verify formulas, data provenance, leakage checks, generated CSVs, charts, BACKTEST reports, and conclusions before promotion into final artifacts.
- The main agent must rerun the relevant step checks and final
quality_gate_check.py after integrating any subagent work.
- If any required stage fails, create
failure_report.md with the failed command, error, partial artifacts, likely cause, and next repair step.
Workflow
1. Initialize
Before creating or running the project, verify the local runtime dependencies:
python scripts/check_dependencies.py --install
Use Python 3.10 or newer for Pandadata. The default WorkBuddy pandadata Connector runtime reads local credentials from the current environment or WorkBuddy-managed authentication; it also requires requests at runtime.
Use scripts/create_project.py to create the output structure and manifest.json. The default root is /home/coder/project/replication/report-replication.
Download real Pandadata market data before validation and BACKTEST:
python WorkBuddy call_pandadata \
--asset-type stock \
--symbols 000001.SZ 600000.SH \
--start-date 20250101 \
--end-date 20250131 \
--output /home/coder/project/replication/report-replication/{report_id}/03_factor_validation/data_cache/pandadata_market_data.csv \
--project-dir /home/coder/project/replication/report-replication/{report_id}
Then use the bundled local BACKTEST engine by default:
python scripts/local_backtest.py /home/coder/project/replication/report-replication/{report_id} --market-data /home/coder/project/replication/report-replication/{report_id}/03_factor_validation/data_cache/pandadata_market_data.csv
The bundled engine reads real market data plus 04_backtest_strategy/backtest_logs/signal_log.jsonl, applies a configurable execution lag, estimates fees/slippage, and writes equity, trade, metric, alignment, raw, and Chinese HTML report artifacts. If the user explicitly supplies an external BACKTEST runner, use it only after documenting the entrypoint, command, config, and output mapping in manifest.json.
Record:
- Original input path or URL.
- Report title if known.
- Run date.
- Python executable and dependency report.
- BACKTEST engine entrypoint, version if known, command, config, and output files. For the bundled engine, record
scripts/local_backtest.py.
- Pandadata method, symbols/universe, sample period, frequency, adjustment rule, local cache path, metadata path, missing-value handling, assumptions, parameters, code hashes, and run history.
2. Extract And Translate
Deliver 01_translation/full_translation.md.
Requirements:
- It must be a full Chinese translation, not only English extraction.
- Preserve the original structure, page markers, section markers, table notes, chart captions, and formula explanations when extractable.
- Mark uncertain OCR/PDF extraction regions as
pending verification / 待核验.
- Do not invent missing formulas, table values, or chart notes.
After Step 2, run:
python scripts/check_step2_translation.py /home/coder/project/replication/report-replication/{report_id}
Do not move to Step 3 until the gate passes or the blocker is documented.
3. Reconstruct Factors
Deliver:
02_factor_reproduction/ai_summary_and_factor_formula.md
02_factor_reproduction/reference_implementation.py
The Markdown file must include the research question, conclusion, asset universe, sample period, rebalance frequency, data source, benchmark, factor formula, variable definitions, portfolio construction rules, assumptions, and bias checks.
The reference implementation must include factor calculation functions precise enough to audit the formula, including missing-value rules, standardization, ranking or grouping, regression model details when relevant, and rebalance timing.
After Step 3, run:
python scripts/check_step3_factor_reconstruction.py /home/coder/project/replication/report-replication/{report_id}
Do not move to factor validation until the gate passes or the blocker is documented.
4. Validate Factor Effectiveness
Use real, traceable market or research data. Default to Pandadata daily data downloaded with WorkBuddy call_pandadata when validating market-price factors or running BACKTEST. Prefer the Pandadata dataset that matches the report universe and BACKTEST configuration. Do not use synthetic, mock, or randomly generated market data to prove effectiveness. A fixed-seed random factor may only be used as a negative-control baseline on the same real return data as the target factor.
Validation is two-phase:
Step 3: factor reconstruction
-> Phase A: independent theoretical factor validation
Step 5: BACKTEST strategy and backtest
-> Phase B: alignment validation that consumes backtest_logs/signal_log.jsonl
At minimum evaluate:
- Data coverage, missingness, outliers, and factor distribution.
- IC, Rank IC, ICIR, IC t-statistic, positive IC ratio, IC distribution, yearly/quarterly IC, cumulative IC, and rolling IC.
- Quantile/group monotonicity, equal-weight portfolio returns, long-short returns, long-only/short-only legs when applicable, and strategy-direction portfolio returns.
- Full sample, in-sample, out-of-sample, and walk-forward when data allows.
- Drawdown, annual return, volatility, downside volatility, Sharpe, Sortino, Calmar, max drawdown, max drawdown duration, win rate, profit/loss ratio, skewness, kurtosis, VaR/CVaR, turnover, capacity/liquidity proxy when data allows, and yearly/monthly performance.
- Look-ahead, price leakage, data availability time, signal lag, execution price, cost assumptions, sample split, and overfitting controls.
- Parameter stability, cost sensitivity, reverse-factor baseline, fixed-seed random-factor baseline, equal-weight buy-and-hold baseline, zero-return/always-flat baseline, leave-one-asset-out or leave-one-sector-out robustness when data allows, and BACKTEST alignment.
Report readability requirements:
- Write the report in Chinese. English terms may appear only as short labels, metric abbreviations, formulas, or artifact names.
- Render every chart image with English ASCII text only; keep Chinese reader-facing explanations in the HTML below each image.
- Add a
How To Read This Report / 阅读指南 section near the top that explains the evidence chain from factor definition, bias audit, IC, portfolio test, OOS result, and BACKTEST result.
- Add a metric dictionary explaining at least IE, IC, Rank IC, ICIR, Positive IC Ratio, Annual Return, Annual Volatility, Sharpe, Calmar, Max DD, Win Rate, NAV, IS, and OOS.
- Under every chart, include a Chinese beginner-facing explanation block. It must be specific to that chart and contain:
这张图回答什么问题
怎么看
我们看到了什么
这意味着什么
数据来源
- Explain clearly that factor-validation NAV curves are not automatically BACKTEST actual account/equity curves:
04_cumulative_nav_equal_weight.png is a theoretical equal-weight factor-validation curve.
05_cumulative_nav_strategy_direction.png is a strategy-direction validation curve reconstructed from directions and return data.
- BACKTEST actual account/equity curves come from BACKTEST artifacts such as
04_backtest_strategy/backtest_report_raw.html, exported equity files, or log files.
- For futures, explain equal-weight vs equal-lot, contract multipliers, next-bar execution, fees, slippage, margin/capital allocation, and daily mark-to-market.
- Add a red/yellow/green (RAG) judgement table and conclusion scorecard. It must use objective metrics, not model opinion. At minimum score formula confidence, data coverage, leakage audit, IC direction, OOS portfolio result, full-sample portfolio risk/return, cost robustness, and BACKTEST actual result alignment.
- Add benchmark comparison against at least: reverse factor, fixed-seed random factor, equal-weight buy-and-hold, and zero-return / always-flat baseline. Save the benchmark returns or metrics under
03_factor_validation/data/.
- Add a BACKTEST alignment audit table comparing factor-validation curves with BACKTEST actual equity curves: data source, time range, frequency, weighting/execution assumptions, final NAV, max drawdown, and whether divergence is expected/explained.
- Produce the expanded factor-validation visual pack when data allows: IC distribution, rolling IC, quantile NAV, quantile return monotonicity bar chart, yearly/monthly performance heatmap, turnover series, data coverage heatmap, missing-value heatmap, benchmark NAV comparison, BACKTEST alignment NAV comparison, parameter stability heatmap, cost sensitivity chart, and walk-forward chart.
- If an expanded chart or metric cannot be produced, keep the section and state the exact blocker in Chinese.
- The report must be useful to a non-quant user without requiring them to inspect CSV files or BACKTEST internals.
Final conclusion must be one of: effective, weakly effective, ineffective, regime-dependent, or inconclusive.
Read references/factor_validation_checklist.md and references/factor_audit_and_robustness.md before judging effectiveness.
Use scripts/build_factor_report.py when a deterministic HTML scaffold is useful. The generated HTML must still satisfy references/output_contract.md and scripts/quality_gate_check.py.
5. Generate And Run BACKTEST Strategy
Generate BACKTEST strategy code only after factor logic is reconstructed and Phase A validation has been attempted.
Required behavior:
- Read
references/backtest_engine.md before writing or running Step 5.
- Convert the validated factor signal into executable strategy logic that writes
04_backtest_strategy/backtest_logs/signal_log.jsonl.
- Keep parameters clear: symbols, frequency, factor window, rebalance frequency, entry/exit rules, risk controls, fees, slippage, margin, and capital constraints.
- Run the bundled local BACKTEST engine with
scripts/local_backtest.py unless the user explicitly provides an external BACKTEST runner.
- Save or preserve BACKTEST's raw output as
04_backtest_strategy/backtest_report_raw.html.
- Deliver
04_backtest_strategy/backtest_report.html as a Chinese reader-facing backtest explanation report. It must summarize strategy logic, data, run artifacts, signal log, relationship to factor validation curves, known differences from theoretical validation, and link or point to the raw BACKTEST report if one exists.
- Save strategy logs under
04_backtest_strategy/backtest_logs/.
- Output
04_backtest_strategy/backtest_logs/signal_log.jsonl for Phase B alignment validation. Each line should be JSON: {"date": "YYYY-MM-DD", "signals": {"SYM": {"factor": float, "direction": 1|-1|0}}}.
- The bundled engine also writes
equity_curve.csv, performance_metrics.csv, trades.csv, and position_return_detail.csv.
After Step 5, run:
python scripts/check_step5_strategy.py /home/coder/project/replication/report-replication/{report_id}
Then update 03_factor_validation/factor_validation_report.html with Phase B alignment results.
6. Final Delivery Summary
Generate 06_delivery/final_delivery_summary.md after all available artifacts are complete. Keep it concise and decision-oriented:
- What the report says.
- Whether the factor is effective.
- Whether BACKTEST ran successfully.
- Where the reports, strategy, logs, and validation artifacts are.
- Key assumptions, risks, blockers, and next steps.
If any required stage fails, also create failure_report.md.
7. Run Quality Gate
Before final delivery, run:
python scripts/quality_gate_check.py /home/coder/project/replication/report-replication/{report_id}
If the command reports errors, do not deliver as complete. Fix the errors and rerun, or provide failure_report.md and state that the project is blocked rather than complete.
Quality Gates
Before final delivery, verify:
- All required artifact paths exist, or blockers are documented.
- The translation is complete enough to preserve the report structure.
- Every reconstructed formula has variables and assumptions.
02_factor_reproduction/reference_implementation.py exists and contains function-level reference code.
- Data preparation records Pandadata provider/method, cache path, metadata path, symbols, period, adjustment type, frequency, missing-value handling, and data availability assumptions. If a non-Pandadata source is used, the report must explain why Pandadata was insufficient.
- No credential values are written into
manifest.json, HTML/Markdown reports, logs, CSVs, or committed files.
- Factor validation uses real traceable data; no synthetic, mock, or random market data is used to prove effectiveness.
- If validation data is insufficient, the conclusion is inconclusive.
- Factor validation includes audit controls, IS/OOS or documented blocker, parameter stability, cost sensitivity or documented blocker, and baseline comparisons.
- The HTML report includes the required sections, charts, metrics, and traceable source captions.
- Chart explanation blocks are beginner-readable, chart-specific, non-mechanical, and include the five required parts.
04_backtest_strategy/backtest_report.html is a Chinese reader-facing explanation when the BACKTEST engine output is not Chinese-readable; any raw engine HTML is preserved separately and referenced.
- BACKTEST was actually run through
scripts/local_backtest.py or a documented external runner, or failure logs are saved.
06_delivery/final_delivery_summary.md exists, or failure_report.md explains why completion was blocked.
References
references/output_contract.md: required files and acceptance criteria.
references/factor_validation_checklist.md: factor validation metrics, charts, and conclusion standards.
references/factor_audit_and_robustness.md: leakage, look-ahead, overfitting, sample split, and robustness rules.
references/backtest_engine.md: BACKTEST strategy generation and execution rules.
references/data_sources.md: data source and provenance rules.
references/replication_lessons_learned.md: historical failure cases and guardrails.
1---
2name: report-replication
3description: "Reproduce quantitative research reports and papers end to end: full Chinese translation, AI summary, factor formula reconstruction, factor effectiveness validation, standalone beginner-readable HTML factor report, BACKTEST strategy generation and local backtest execution, Chinese backtest explanation report, and final delivery summary. Use when the user provides a quant report/PDF/link/text and asks for report replication, factor replication, factor validation, BACKTEST strategy code, or a beginner-readable research replication package."
4license: GPL-3.0-only
5metadata:
6 source: https://skillmd.com/skills/ahang1598/report-replication
7 organization: QuantSkills
8 organization_url: https://github.com/quantskills
9 repository: skill-report-replication
10 repository_url: https://github.com/quantskills/skill-report-replication
11 project_type: skill
12 collection: report-replication
13 creator: abgyjaguo
14 maintainer: abgyjaguo
15quantSkills:
16 project_type: skill
17 category: replication
18 tags:
19 - report-replication
20 - factor-research
21 - backtest
22 - pandadata
23 - html-report
24 - chinese
25 platforms:
26 - claude-code
27 - codex
28 - hermes
29 - openclaw
30 - cursor
31 status: stable
32 validation_level: runnable
33 maintainer_type: official
34 summary_zh: "把一篇量化研报、论文、PDF、网页或文本材料,转化为 Pandadata 真实数据驱动的研究复现交付包:全文翻译 → 因子公式复现 → 有效性验证 → 策略代码 → 真实本地回测 → 交付摘要。"
35 summary_en: "Quant report replication skill that turns papers or reports into Chinese translations, factor formulas, Pandadata-backed validation reports, and strategy assets."
36 license: GPL-3.0
37---
38
39## WorkBuddy PandaData MCP 强制覆盖
40
41本节优先于本 Skill 后续所有数据源、依赖安装和命令示例。WorkBuddy 版只允许使用已连接的
42`pandadata` Connector:先调用 `auth_status`,再按共享 Runtime Skill 中的已登记路由调用
43`call_pandadata`。本地 PandaData SDK、直接 HTTP、凭证文件和历史下载脚本在此版本中均
44已禁用。必须执行空数据复查并在最终答案附完整调用回执;未打开 `DATA_GATE` 不得分析。
45
46## WorkBuddy PandaData MCP 强制覆盖
47
48本节优先于本 Skill 后续所有数据源、依赖安装和命令示例。WorkBuddy 版只允许使用已连接的
49`pandadata` Connector:先调用 `auth_status`,再按共享 Runtime Skill 中的已登记路由调用
50`call_pandadata`。本地 PandaData SDK、直接 HTTP、凭证文件和历史下载脚本在此版本中均
51已禁用。必须执行空数据复查并在最终答案附完整调用回执;未打开 `DATA_GATE` 不得分析。
52
53## WorkBuddy PandaData MCP 强制覆盖
54
55本节优先于本 Skill 后续所有数据源、依赖安装和命令示例。WorkBuddy 版只允许使用已连接的
56`pandadata` Connector:先调用 `auth_status`,再按共享 Runtime Skill 中的已登记路由调用
57`call_pandadata`。本地 PandaData SDK、直接 HTTP、凭证文件和历史下载脚本在此版本中均
58已禁用。必须执行空数据复查并在最终答案附完整调用回执;未打开 `DATA_GATE` 不得分析。
59
60```json qsh-form
61{
62 "version": 1,
63 "task": {
64 "placeholder": "请提供量化研报、论文、PDF、网页或文本,并说明期望复现范围",
65 "required": true
66 },
67 "fields": [
68 {
69 "key": "focus",
70 "label": "复现重点",
71 "type": "text",
72 "placeholder": "如:全文翻译、某个因子、有效性验证或回测策略"
73 }
74 ],
75 "prompt_template": "{{#task}}任务与材料:\n{{task}}\n\n{{/task}}{{#attachments}}用户上传的材料(已放入工作区):\n{{attachments}}\n\n{{/attachments}}请端到端复现所给量化报告或论文{{#focus}},重点关注 {{focus}}{{/focus}}:完成中文全文翻译、研究摘要与因子公式重构、真实可溯源数据验证、无前视偏差的 BACKTEST 策略及本地回测、中文可读报告和最终交付摘要;无法执行的环节须如实记录,输出中文报告。"
76}
77```
78
79# Report Replication BACKTEST
80
81## Purpose
82
83Turn a quant report, paper, PDF, webpage, or text source into a complete research delivery package under `/home/coder/project/replication/report-replication`:
84
851. Full Chinese translation of the original report or paper.
862. Chinese AI summary plus factor formula reconstruction in Markdown.
873. Chinese factor validation report as standalone HTML, with charts, metrics, audit notes, and plain-language explanations for users who do not know quantitative jargon.
884. BACKTEST strategy code plus a Chinese backtest explanation HTML. Preserve raw BACKTEST engine output separately when needed.
895. Chinese final delivery summary.
90
91This skill is self-contained for translation, factor reconstruction, factor validation, bundled local BACKTEST execution, optional external BACKTEST execution, and final delivery. Do not call any legacy framework-specific skills, scripts, data layers, examples, or assumptions.
92
93Pandadata is the default production market-data source. Use WorkBuddy `call_pandadata` to download daily stock, index, futures, Hong Kong, or US market data into `03_factor_validation/data_cache/` before factor validation or BACKTEST. User-provided or report-supplied files may be used only when Pandadata does not cover the required dataset, and the fallback must be documented in `manifest.json`, the validation report, and the final summary.
94
95Credentials must come from `WorkBuddy-managed authentication`, `WorkBuddy-managed authentication`, `WorkBuddy-managed authentication`, or `WorkBuddy-managed authentication`. Never write usernames, passwords, tokens, or raw credential files into generated artifacts, logs, commits, or reports. Record only that credential values were not persisted.
96
97## Language And Readability Rules
98
99- All user-facing deliverables must use Chinese as the primary language: `full_translation.md`, `ai_summary_and_factor_formula.md`, `factor_validation_report.html`, `backtest_report.html`, `final_delivery_summary.md`, and explanatory comments/docstrings in generated strategy code.
100- English may appear only when unavoidable: original paper titles, proper names, formulas, code identifiers, CSV column names, API names, ticker/symbol names, metric abbreviations, and short parenthetical glossary labels such as `IC` or `Sharpe`.
101- Do not deliver English narrative sections, English-only reports, or mojibake/garbled Chinese. If a tool generates English or garbled HTML, wrap or rewrite it into a Chinese reader-facing artifact and preserve the raw file separately for audit.
102- Before final delivery, spot-check the main readable files for Chinese readability rather than relying only on automated quality gates.
103- Explain quant concepts as if the reader is smart but new to quant research. Prefer restrained science writing: concise, concrete, and evidence-led.
104
105## Chart Image Text Rules
106
107- Text rendered inside generated chart image files must be English ASCII only. This includes PNG/SVG titles, subtitles, axis labels, legends, colorbar labels, annotation text, heatmap labels, in-image table headers, and watermarks.
108- Keep Chinese explanations outside the image in the HTML/Markdown captions and chart explanation blocks. The report can remain Chinese-readable while the chart pixels stay font-compatible.
109- When using Matplotlib, Seaborn, Plotly static export, or another image renderer, use broadly available Latin fonts such as `DejaVu Sans` or `Arial`. Do not set CJK chart fonts such as `SimHei`, `SimSun`, `Microsoft YaHei`, `Noto Sans CJK`, or `Source Han Sans`.
110- Prefer English chart labels from `references/factor_validation_checklist.md`, for example `Benchmark NAV Comparison`, not Chinese translations. If the original factor/report name is Chinese, draw an ASCII-safe display label in the chart and keep the original Chinese name in the surrounding report text.
111
112## Required Output Contract
113
114Create one project directory per report:
115
116```text
117/home/coder/project/replication/report-replication/{report_id}/
118 01_translation/full_translation.md
119 02_factor_reproduction/ai_summary_and_factor_formula.md
120 02_factor_reproduction/reference_implementation.py
121 03_factor_validation/factor_validation_report.html
122 03_factor_validation/data/
123 03_factor_validation/data/ie_factor_matrix.csv
124 03_factor_validation/data/direction_matrix_from_strategy.csv
125 03_factor_validation/data/portfolio_returns_ew_full.csv
126 03_factor_validation/data/portfolio_returns_ew_is.csv
127 03_factor_validation/data/portfolio_returns_ew_oos.csv
128 03_factor_validation/data/portfolio_returns_dir_full.csv
129 03_factor_validation/data/portfolio_returns_dir_is.csv
130 03_factor_validation/data/portfolio_returns_dir_oos.csv
131 03_factor_validation/data/ic_series.csv
132 03_factor_validation/data/factor_diagnostics.csv
133 03_factor_validation/data/coverage_by_date.csv
134 03_factor_validation/data/missing_by_asset.csv
135 03_factor_validation/data/quantile_returns.csv
136 03_factor_validation/data/rolling_metrics.csv
137 03_factor_validation/data/yearly_performance.csv
138 03_factor_validation/data/turnover_series.csv
139 03_factor_validation/data/benchmark_comparison.csv
140 03_factor_validation/data/backtest_alignment_audit.csv
141 03_factor_validation/charts/
142 03_factor_validation/charts/01_ie_distribution.png
143 03_factor_validation/charts/02_ic_series.png
144 03_factor_validation/charts/03_is_oos_ic_comparison.png
145 03_factor_validation/charts/04_cumulative_nav_equal_weight.png
146 03_factor_validation/charts/05_cumulative_nav_strategy_direction.png
147 03_factor_validation/charts/06_drawdown.png
148 03_factor_validation/charts/07_ic_distribution.png
149 03_factor_validation/charts/08_rolling_ic.png
150 03_factor_validation/charts/09_quantile_nav.png
151 03_factor_validation/charts/10_quantile_return_bar.png
152 03_factor_validation/charts/11_yearly_return_heatmap.png
153 03_factor_validation/charts/12_turnover_series.png
154 03_factor_validation/charts/13_data_coverage_heatmap.png
155 03_factor_validation/charts/14_missing_value_heatmap.png
156 03_factor_validation/charts/15_benchmark_nav_comparison.png
157 03_factor_validation/charts/16_backtest_alignment_nav.png
158 03_factor_validation/charts/17_parameter_stability_heatmap.png
159 03_factor_validation/charts/18_cost_sensitivity.png
160 03_factor_validation/charts/19_walkforward.png
161 03_factor_validation/data_cache/
162 03_factor_validation/data_cache/pandadata_market_data.csv
163 03_factor_validation/data_cache/pandadata_market_data.csv.metadata.json
164 04_backtest_strategy/strategy.py
165 04_backtest_strategy/config.json
166 04_backtest_strategy/backtest_report.html
167 04_backtest_strategy/backtest_report_raw.html (optional raw BACKTEST engine report)
168 04_backtest_strategy/backtest_logs/signal_log.jsonl
169 04_backtest_strategy/backtest_logs/equity_curve.csv
170 04_backtest_strategy/backtest_logs/performance_metrics.csv
171 04_backtest_strategy/backtest_logs/trades.csv
172 04_backtest_strategy/backtest_logs/position_return_detail.csv
173 06_delivery/final_delivery_summary.md
174 failure_report.md
175 manifest.json
176```
177
178Read `references/output_contract.md` before writing final artifacts.
179
180## Honesty Rules
181
182- Say exactly what was done. If a step was not run, state that it was not run.
183- Do not fabricate walk-forward results, cost-sensitivity results, IC series, charts, backtest reports, or BACKTEST logs.
184- If BACKTEST cannot run, or if data is unavailable or insufficient, document the blocker and mark the conclusion as inconclusive.
185- Every chart, table, and metric in the HTML report must be traceable to a file under `03_factor_validation/data/`, a chart under `03_factor_validation/charts/`, or a BACKTEST artifact.
186- Every chart and key metric in the HTML report must also be explained in plain language: what it means, how to read it, what the current result implies, and which data/artifact it came from.
187
188## Subagent Governance
189
190This skill does not require subagents. Default to a single main-agent workflow unless the current task is too large and a subagent would materially reduce risk or time.
191
192If a subagent/background agent is used:
193
194- The main agent remains fully responsible for correctness and final delivery.
195- Subagent outputs are drafts only. They must never be copied into final artifacts without main-agent review.
196- Subagents must write only under `/home/coder/project/replication/report-replication/{report_id}/.agent_work/` or another explicitly isolated scratch directory.
197- Subagents must not overwrite final artifacts such as `factor_validation_report.html`, `strategy.py`, `signal_log.jsonl`, `manifest.json`, or delivery summaries.
198- The main agent must independently verify formulas, data provenance, leakage checks, generated CSVs, charts, BACKTEST reports, and conclusions before promotion into final artifacts.
199- The main agent must rerun the relevant step checks and final `quality_gate_check.py` after integrating any subagent work.
200- If any required stage fails, create `failure_report.md` with the failed command, error, partial artifacts, likely cause, and next repair step.
201
202## Workflow
203
204### 1. Initialize
205
206Before creating or running the project, verify the local runtime dependencies:
207
208```bash
209python scripts/check_dependencies.py --install
210```
211
212Use Python 3.10 or newer for Pandadata. The default WorkBuddy `pandadata` Connector runtime reads local credentials from the current environment or `WorkBuddy-managed authentication`; it also requires `requests` at runtime.
213
214Use `scripts/create_project.py` to create the output structure and `manifest.json`. The default root is `/home/coder/project/replication/report-replication`.
215
216Download real Pandadata market data before validation and BACKTEST:
217
218```bash
219python WorkBuddy call_pandadata \
220 --asset-type stock \
221 --symbols 000001.SZ 600000.SH \
222 --start-date 20250101 \
223 --end-date 20250131 \
224 --output /home/coder/project/replication/report-replication/{report_id}/03_factor_validation/data_cache/pandadata_market_data.csv \
225 --project-dir /home/coder/project/replication/report-replication/{report_id}
226```
227
228Then use the bundled local BACKTEST engine by default:
229
230```bash
231python scripts/local_backtest.py /home/coder/project/replication/report-replication/{report_id} --market-data /home/coder/project/replication/report-replication/{report_id}/03_factor_validation/data_cache/pandadata_market_data.csv
232```
233
234The bundled engine reads real market data plus `04_backtest_strategy/backtest_logs/signal_log.jsonl`, applies a configurable execution lag, estimates fees/slippage, and writes equity, trade, metric, alignment, raw, and Chinese HTML report artifacts. If the user explicitly supplies an external BACKTEST runner, use it only after documenting the entrypoint, command, config, and output mapping in `manifest.json`.
235
236Record:
237
238- Original input path or URL.
239- Report title if known.
240- Run date.
241- Python executable and dependency report.
242- BACKTEST engine entrypoint, version if known, command, config, and output files. For the bundled engine, record `scripts/local_backtest.py`.
243- Pandadata method, symbols/universe, sample period, frequency, adjustment rule, local cache path, metadata path, missing-value handling, assumptions, parameters, code hashes, and run history.
244
245### 2. Extract And Translate
246
247Deliver `01_translation/full_translation.md`.
248
249Requirements:
250
251- It must be a full Chinese translation, not only English extraction.
252- Preserve the original structure, page markers, section markers, table notes, chart captions, and formula explanations when extractable.
253- Mark uncertain OCR/PDF extraction regions as `pending verification` / `待核验`.
254- Do not invent missing formulas, table values, or chart notes.
255
256After Step 2, run:
257
258```bash
259python scripts/check_step2_translation.py /home/coder/project/replication/report-replication/{report_id}
260```
261
262Do not move to Step 3 until the gate passes or the blocker is documented.
263
264### 3. Reconstruct Factors
265
266Deliver:
267
268- `02_factor_reproduction/ai_summary_and_factor_formula.md`
269- `02_factor_reproduction/reference_implementation.py`
270
271The Markdown file must include the research question, conclusion, asset universe, sample period, rebalance frequency, data source, benchmark, factor formula, variable definitions, portfolio construction rules, assumptions, and bias checks.
272
273The reference implementation must include factor calculation functions precise enough to audit the formula, including missing-value rules, standardization, ranking or grouping, regression model details when relevant, and rebalance timing.
274
275After Step 3, run:
276
277```bash
278python scripts/check_step3_factor_reconstruction.py /home/coder/project/replication/report-replication/{report_id}
279```
280
281Do not move to factor validation until the gate passes or the blocker is documented.
282
283### 4. Validate Factor Effectiveness
284
285Use real, traceable market or research data. Default to Pandadata daily data downloaded with WorkBuddy `call_pandadata` when validating market-price factors or running BACKTEST. Prefer the Pandadata dataset that matches the report universe and BACKTEST configuration. Do not use synthetic, mock, or randomly generated market data to prove effectiveness. A fixed-seed random factor may only be used as a negative-control baseline on the same real return data as the target factor.
286
287Validation is two-phase:
288
289```text
290Step 3: factor reconstruction
291 -> Phase A: independent theoretical factor validation
292Step 5: BACKTEST strategy and backtest
293 -> Phase B: alignment validation that consumes backtest_logs/signal_log.jsonl
294```
295
296At minimum evaluate:
297
298- Data coverage, missingness, outliers, and factor distribution.
299- IC, Rank IC, ICIR, IC t-statistic, positive IC ratio, IC distribution, yearly/quarterly IC, cumulative IC, and rolling IC.
300- Quantile/group monotonicity, equal-weight portfolio returns, long-short returns, long-only/short-only legs when applicable, and strategy-direction portfolio returns.
301- Full sample, in-sample, out-of-sample, and walk-forward when data allows.
302- Drawdown, annual return, volatility, downside volatility, Sharpe, Sortino, Calmar, max drawdown, max drawdown duration, win rate, profit/loss ratio, skewness, kurtosis, VaR/CVaR, turnover, capacity/liquidity proxy when data allows, and yearly/monthly performance.
303- Look-ahead, price leakage, data availability time, signal lag, execution price, cost assumptions, sample split, and overfitting controls.
304- Parameter stability, cost sensitivity, reverse-factor baseline, fixed-seed random-factor baseline, equal-weight buy-and-hold baseline, zero-return/always-flat baseline, leave-one-asset-out or leave-one-sector-out robustness when data allows, and BACKTEST alignment.
305
306Report readability requirements:
307
308- Write the report in Chinese. English terms may appear only as short labels, metric abbreviations, formulas, or artifact names.
309- Render every chart image with English ASCII text only; keep Chinese reader-facing explanations in the HTML below each image.
310- Add a `How To Read This Report` / `阅读指南` section near the top that explains the evidence chain from factor definition, bias audit, IC, portfolio test, OOS result, and BACKTEST result.
311- Add a metric dictionary explaining at least IE, IC, Rank IC, ICIR, Positive IC Ratio, Annual Return, Annual Volatility, Sharpe, Calmar, Max DD, Win Rate, NAV, IS, and OOS.
312- Under every chart, include a Chinese beginner-facing explanation block. It must be specific to that chart and contain:
313 - `这张图回答什么问题`
314 - `怎么看`
315 - `我们看到了什么`
316 - `这意味着什么`
317 - `数据来源`
318- Explain clearly that factor-validation NAV curves are not automatically BACKTEST actual account/equity curves:
319 - `04_cumulative_nav_equal_weight.png` is a theoretical equal-weight factor-validation curve.
320 - `05_cumulative_nav_strategy_direction.png` is a strategy-direction validation curve reconstructed from directions and return data.
321 - BACKTEST actual account/equity curves come from BACKTEST artifacts such as `04_backtest_strategy/backtest_report_raw.html`, exported equity files, or log files.
322 - For futures, explain equal-weight vs equal-lot, contract multipliers, next-bar execution, fees, slippage, margin/capital allocation, and daily mark-to-market.
323- Add a red/yellow/green (RAG) judgement table and conclusion scorecard. It must use objective metrics, not model opinion. At minimum score formula confidence, data coverage, leakage audit, IC direction, OOS portfolio result, full-sample portfolio risk/return, cost robustness, and BACKTEST actual result alignment.
324- Add benchmark comparison against at least: reverse factor, fixed-seed random factor, equal-weight buy-and-hold, and zero-return / always-flat baseline. Save the benchmark returns or metrics under `03_factor_validation/data/`.
325- Add a BACKTEST alignment audit table comparing factor-validation curves with BACKTEST actual equity curves: data source, time range, frequency, weighting/execution assumptions, final NAV, max drawdown, and whether divergence is expected/explained.
326- Produce the expanded factor-validation visual pack when data allows: IC distribution, rolling IC, quantile NAV, quantile return monotonicity bar chart, yearly/monthly performance heatmap, turnover series, data coverage heatmap, missing-value heatmap, benchmark NAV comparison, BACKTEST alignment NAV comparison, parameter stability heatmap, cost sensitivity chart, and walk-forward chart.
327- If an expanded chart or metric cannot be produced, keep the section and state the exact blocker in Chinese.
328- The report must be useful to a non-quant user without requiring them to inspect CSV files or BACKTEST internals.
329
330Final conclusion must be one of: effective, weakly effective, ineffective, regime-dependent, or inconclusive.
331
332Read `references/factor_validation_checklist.md` and `references/factor_audit_and_robustness.md` before judging effectiveness.
333
334Use `scripts/build_factor_report.py` when a deterministic HTML scaffold is useful. The generated HTML must still satisfy `references/output_contract.md` and `scripts/quality_gate_check.py`.
335
336### 5. Generate And Run BACKTEST Strategy
337
338Generate BACKTEST strategy code only after factor logic is reconstructed and Phase A validation has been attempted.
339
340Required behavior:
341
342- Read `references/backtest_engine.md` before writing or running Step 5.
343- Convert the validated factor signal into executable strategy logic that writes `04_backtest_strategy/backtest_logs/signal_log.jsonl`.
344- Keep parameters clear: symbols, frequency, factor window, rebalance frequency, entry/exit rules, risk controls, fees, slippage, margin, and capital constraints.
345- Run the bundled local BACKTEST engine with `scripts/local_backtest.py` unless the user explicitly provides an external BACKTEST runner.
346- Save or preserve BACKTEST's raw output as `04_backtest_strategy/backtest_report_raw.html`.
347- Deliver `04_backtest_strategy/backtest_report.html` as a Chinese reader-facing backtest explanation report. It must summarize strategy logic, data, run artifacts, signal log, relationship to factor validation curves, known differences from theoretical validation, and link or point to the raw BACKTEST report if one exists.
348- Save strategy logs under `04_backtest_strategy/backtest_logs/`.
349- Output `04_backtest_strategy/backtest_logs/signal_log.jsonl` for Phase B alignment validation. Each line should be JSON: `{"date": "YYYY-MM-DD", "signals": {"SYM": {"factor": float, "direction": 1|-1|0}}}`.
350- The bundled engine also writes `equity_curve.csv`, `performance_metrics.csv`, `trades.csv`, and `position_return_detail.csv`.
351
352After Step 5, run:
353
354```bash
355python scripts/check_step5_strategy.py /home/coder/project/replication/report-replication/{report_id}
356```
357
358Then update `03_factor_validation/factor_validation_report.html` with Phase B alignment results.
359
360### 6. Final Delivery Summary
361
362Generate `06_delivery/final_delivery_summary.md` after all available artifacts are complete. Keep it concise and decision-oriented:
363
364- What the report says.
365- Whether the factor is effective.
366- Whether BACKTEST ran successfully.
367- Where the reports, strategy, logs, and validation artifacts are.
368- Key assumptions, risks, blockers, and next steps.
369
370If any required stage fails, also create `failure_report.md`.
371
372### 7. Run Quality Gate
373
374Before final delivery, run:
375
376```bash
377python scripts/quality_gate_check.py /home/coder/project/replication/report-replication/{report_id}
378```
379
380If the command reports errors, do not deliver as complete. Fix the errors and rerun, or provide `failure_report.md` and state that the project is blocked rather than complete.
381
382## Quality Gates
383
384Before final delivery, verify:
385
386- All required artifact paths exist, or blockers are documented.
387- The translation is complete enough to preserve the report structure.
388- Every reconstructed formula has variables and assumptions.
389- `02_factor_reproduction/reference_implementation.py` exists and contains function-level reference code.
390- Data preparation records Pandadata provider/method, cache path, metadata path, symbols, period, adjustment type, frequency, missing-value handling, and data availability assumptions. If a non-Pandadata source is used, the report must explain why Pandadata was insufficient.
391- No credential values are written into `manifest.json`, HTML/Markdown reports, logs, CSVs, or committed files.
392- Factor validation uses real traceable data; no synthetic, mock, or random market data is used to prove effectiveness.
393- If validation data is insufficient, the conclusion is inconclusive.
394- Factor validation includes audit controls, IS/OOS or documented blocker, parameter stability, cost sensitivity or documented blocker, and baseline comparisons.
395- The HTML report includes the required sections, charts, metrics, and traceable source captions.
396- Chart explanation blocks are beginner-readable, chart-specific, non-mechanical, and include the five required parts.
397- `04_backtest_strategy/backtest_report.html` is a Chinese reader-facing explanation when the BACKTEST engine output is not Chinese-readable; any raw engine HTML is preserved separately and referenced.
398- BACKTEST was actually run through `scripts/local_backtest.py` or a documented external runner, or failure logs are saved.
399- `06_delivery/final_delivery_summary.md` exists, or `failure_report.md` explains why completion was blocked.
400
401## References
402
403- `references/output_contract.md`: required files and acceptance criteria.
404- `references/factor_validation_checklist.md`: factor validation metrics, charts, and conclusion standards.
405- `references/factor_audit_and_robustness.md`: leakage, look-ahead, overfitting, sample split, and robustness rules.
406- `references/backtest_engine.md`: BACKTEST strategy generation and execution rules.
407- `references/data_sources.md`: data source and provenance rules.
408- `references/replication_lessons_learned.md`: historical failure cases and guardrails.