SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsstock-earnings-review

stock-earnings-review

Data & analytics

View repository

Updated 10-16 09:45

About this skill

Listed company earnings review (stock-earnings-review)

Accomplished through the user's query sentenceEntity recognition → reporting period matching → earnings review API generation, and save the PDF/Word attachment locally (base64 decoded and saved).JSON The process log is only written to disk in debug mode. Finally, return to the user the title, the API content text organization result, the attachment local path, the source tracing explanation, and the sharing link.

Upper-layer orchestration protocol (supports step-by-step invocation)

This skill usesstep-by-step invocation: the large model calls them in sequence according to the process

  1. scripts/validate_entity.py to obtain entities
  2. scripts/normalize_report_period.py to obtain reporting period candidates
  3. The large model selects based on user semantics reportDate
  4. scripts/call_review_api.py to generate the review and save the attachment

Regardless of which method is used,it is prohibitedfor the large model alone to "fabricate" the entire earnings review based on its knowledge base and pass it off as the skill result.

Output directory and file structure (default)

Same as mx_macro_data the same convention:default root directoryis miaoxiang/stock-earnings-review/under the current working directory (no need to create manually; the script will automatically mkdir）。

Each execution will create anotheronce-run subdirectory（run_idunder this root directory, containing a timestamp and a short UUID), with the following structure:

Path (relative to this run's root directory) Description
01_entity.json Entity recognition result (only --debug）
02_report_period.json Reporting period list and matching result (only --debug）
03_comment_raw.json Earnings review API raw response (only --debug）
04_review_result.json Parsed review result and section information (only --debug）
05_final_result.json Summary and finalOutput(only --debug）
attachments/review.pdf File decoded from the pdfBase64 returned by the API (if the API returns one)
attachments/review.doc File decoded from the wordBase64 returned by the API (if the API returns one)

Description: If the API does not return the corresponding base64, the corresponding file will not be generated. Non- debug mode will not generate 01~05.json, but the attachment will still be saved.

Environment variables

Variable name Description Default
STOCK_EARNINGS_REVIEW_OUTPUT_DIR Root directory for logs and attachmentsRoot directory(under which subdirectories are still created per run) miaoxiang/stock-earnings-review(relative to the current working directory)
EARNINGS_REVIEW_LOG_DIR Synonymous with the previous item, compatible with old configurations Same as above

Quick start

Step-by-step invocation (adapted to outer-layer large model orchestration)

# 第一步：实体识别
python3 {baseDir}/stock-earnings-review/scripts/validate_entity.py --query "东方财富 业绩点评"

# 第二步：获取报告期候选
python3 {baseDir}/stock-earnings-review/scripts/normalize_report_period.py \
  --secu-code 300059 --market-char SZ --class-code 002001

# 第三步：外层大模型选择 reportDate 后调用点评
python3 {baseDir}/stock-earnings-review/scripts/call_review_api.py \
  --secu-code 300059 --market-char SZ --class-code 002001 \
  --report-date 2025-12-31 --secu-name 东方财富

Optional parameters:

Parameter Description Required
validate_entity.py --query The user's original query sentence (must contain company/stock information) ✅
normalize_report_period.py --selected-report-date Optional, passed in when the upper-layer model has already made a decision; the passed-in value must be in the candidate list No
call_review_api.py --attachment-dir Attachment save directory; if not provided, defaults to miaoxiang/stock-earnings-review/<run_id>/attachments No
call_review_api.py --debug Output complete intermediate fields and write debug logs to disk No

Note:It is forbidden to run this script in any "background execution, report later" manner. You can only wait synchronously in the current session until the command completes, and continue only after obtaining the stdout result; otherwise this Skill will fail.

Processing flow (summary)

The overall flow is divided into three steps: entity recognition and market validation → reporting period matching → generating commentary and writing to disk.

Step 1: Entity recognition and market validation

Call scripts/validate_entity.py, pass the user'soriginal questionto the entity recognition interface, which returns secuCode、marketChar、classCode、secuName , etc.; when there are multiple entities, take the first one.

Step 2: Reporting period matching

Call scripts/normalize_report_period.py to obtain the reporting period list; theupper-layer modelselects reportDateaccording to the user's intent (or passes it in via --report-date ). If the user does not specify a reporting period, by default take thelatest periodin the list (subject to the script implementation).

/assistant/write/choice/reportList The interface returns the entity'spublishedreporting period list, and does not include unpublished reporting periods. For example, when requesting {"emCode":"NVDA.O"} , the returned result is the set of NVIDIA's published reporting periods.

Step 3: Performance commentary and writing to disk

Call scripts/call_review_api.py, request the performance commentary interface, parse the title and body content, and write the PDF/Word base64 to attachments/. JSON logs for each stage are written only in debug mode.

Output format to the user (logic)

  • Title: the title returned by the interface.
  • Body: output directly after organizing based on the content text returned by the interface.
  • Share link: the shareUrl。
  • File pathreturned by the interface: return files.pdf / files.word / files.dataSheet(if generated).

Step 3 call_review_api.py output uses only the following fields:title、content、shareUrl、files。

Output format template (Markdown illustration)

# {title}

{content}

如需查看详细信息，请查看附件 PDF 或 DOC.......
- **附件**：{files}
- **分享链接**：{shareUrl}

Key constraints (must be followed)

  • Do not attempt to read, parse, or summarize the file contents of review.pdf / review.doc .
  • Do not go through the "read attachment contents" process again just because the PDF text is truncated or the DOC is binary.
  • Organize and reply to the user based only on the structured fields returned by call_review_api.py (especially summary/content).

Pre-validation failure constraints (must be followed)

  • If any of the following situations occurs, the flow must stop immediately; subsequent interfaces must not continue to be called, and results must not be fabricated:
    • Entity recognition is empty or the entity is not within the supported range;
    • The reporting period list is empty;
    • The selected_report_date specified by the user is not in the candidate list (strict mode).
  • When the script returns ok=false or the response body contains the message field, messagemust be output as-is, and must not be rewritten or replaced.
  • When report period matching fails and running in non-strict mode, it may fall back to the latest period, but it must explicitly prompt “Fell back to the latest available report period.”

Format requirements

Mathematical formula format in responses:

  • Inline formulas use \(...\) format (do not use $...$）
  • Display formulas use \[...\] format
  • The content inside display formula blocks remains unchanged

Error handling summary

Error scenario Handling method
No entity in the question Ask the user to confirm the company name to be reviewed
Entity recognition failed Prompt the user to confirm the company name or stock code
Entity is not in a supported market Return “Currently only performance reviews for entities in Shanghai, Shenzhen, Beijing, Hong Kong, and U.S. markets are supported”
Report period list is empty Prompt “No available report period data for this entity for now”
Report period API call failed Prompt “Unable to obtain report period information temporarily, please try again later”
Performance review API call failed Prompt “Performance review generation failed, please try again later”
User requests to see the full body text Directly return API content text; if the original file is needed, the attachment path may be provided, but the attachment content is not read

Scripts and documentation

Script/file Function
scripts/validate_entity.py Entity recognition
scripts/normalize_report_period.py Report period list and matching
scripts/call_review_api.py Performance review API and attachment persistence
BUSINESS_LOGIC.md Detailed business logic version: pre-checks, report period A-share/Hong Kong and U.S. stock rules, delivery template, complete error table, and script strict mode description

When implementing the complete rules in the orchestration layer, please also read BUSINESS_LOGIC.md。