a-share-trader

name	a-share-trader
description	Use when the user wants A-share market intelligence, pre-open trading plans, intraday anomaly alerts, or specific buy/sell sizing suggestions for mainland China equities. This skill acts as an advisory trading assistant for A-shares, generates structured trade ideas, applies balanced risk limits, and supports daily open reports plus hourly monitoring alerts without placing orders automatically.

A-Share Trader

Use this skill for mainland China equity analysis and alerting. It is advisory only: never place orders, never claim guaranteed returns, and never bypass the configured risk limits.

Scope

• A-share market intelligence for Shanghai, Shenzhen, ChiNext, and STAR Market
• Pre-open daily report with market overview and candidate trade plan
• Hourly market checks during regular trading hours
• Structured buy/sell/watch recommendations with sizing

Do not use this skill for:

• automatic brokerage execution
• Hong Kong, US, futures, or options coverage
• minute-level continuous monitoring

Required configuration

Read the configured trader YAML first. By default the helper script uses:

• A_SHARE_TRADER_CONFIG, if set
• otherwise ~/.config/a-share-trader/a_share_trader.yaml

Then load the local portfolio ledger from the configured portfolio_file. This config also provides the QQ SMTP settings for sending true HTML mail.

If the config file is missing or invalid, run:

python3 "$CODEX_HOME/skills/a-share-trader/scripts/a_share_trader.py" validate-config

Return the actionable validation error to the user instead of continuing.

Workflow

1. Validate config and load state:

python3 "$CODEX_HOME/skills/a-share-trader/scripts/a_share_trader.py" validate-config

Inspect the local holdings ledger when sell, hold, or add-position advice may be generated:

python3 "$CODEX_HOME/skills/a-share-trader/scripts/a_share_trader.py" show-portfolio

2. Prefer direct mainland-China network routes first.

The default is market_data.proxy_url: null, which means:

• do not force a US proxy
• use direct China-network access first
• only set proxy_url when a specific upstream requires it

3. Run the built-in V1 quant scanner.

python3 "$CODEX_HOME/skills/a-share-trader/scripts/a_share_trader.py" scan-candidates \
  --mode daily \
  --candidates-output /tmp/a_share_candidates.json \
  --ideas-output /tmp/a_share_ideas.json

The scanner will:

• pull the fixed AKShare market snapshot
• run sector rotation scoring
• scan limit-up, broken-board, abnormal-flow, and 龙虎榜 style triggers when available
• score earnings and announcement events
• produce short_term_candidates and swing_candidates
• write /tmp/a_share_candidates.json
• build /tmp/a_share_ideas.json automatically

Use AKShare as the primary source for:

• last_close
• historical daily bars
• index snapshot and market overview

Do not hand-write price ranges before the market snapshot exists.

V2 multi-agent path

The skill supports a V2 pseudo-multi-agent pipeline. V1 remains available as a fallback, but V2 is the preferred path for richer evidence and explainability. V2 uses:

• MacroPolicyAgent
• MarketRegimeAgent
• SectorRotationAgent
• ThemePropagationAgent
• EventAgent
• FundamentalDepthAgent
• SentimentMicrostructureAgent
• ExecutionAgent
• PortfolioRiskAgent
• DecisionAgent

Only DecisionAgent is allowed to emit final BUY / SELL / HOLD / WATCH.

Run V2 with:

python3 "$CODEX_HOME/skills/a-share-trader/scripts/a_share_trader.py" scan-candidates-v2 \
  --mode daily \
  --candidates-output /tmp/a_share_candidates_v2.json \
  --ideas-output /tmp/a_share_ideas_v2.json

Optional webpage/news enhancement can be injected with:

python3 "$CODEX_HOME/skills/a-share-trader/scripts/a_share_trader.py" scan-candidates-v2 \
  --mode intraday \
  --web-events-file /tmp/a_share_web_events.json \
  --candidates-output /tmp/a_share_candidates_v2.json \
  --ideas-output /tmp/a_share_ideas_v2.json

V2 writes stable intermediate reports under:

• A_SHARE_TRADER_STATE_DIR, if set
• otherwise ~/.local/state/a-share-trader/v2_reports/<timestamp>/

These reports include:

• macro_policy_report
• market_regime_report
• sector_report
• theme_report
• event_report
• fundamental_report
• sentiment_microstructure_report
• execution_report
• position_monitor_report
• portfolio_risk_report
• feedback_backtest_report
• decision_report

You can rebuild V2 ideas from existing files with:

python3 "$CODEX_HOME/skills/a-share-trader/scripts/a_share_trader.py" build-ideas-v2 \
  --snapshot-file "$CODEX_HOME/skills/a-share-trader/state/market_snapshot.json" \
  --candidates-file /tmp/a_share_candidates_v2.json \
  --output /tmp/a_share_ideas_v2.json

And reuse the same rendering or alerting chain with:

python3 "$CODEX_HOME/skills/a-share-trader/scripts/a_share_trader.py" build-summary-v2 --mode daily --ideas-file /tmp/a_share_ideas_v2.json
python3 "$CODEX_HOME/skills/a-share-trader/scripts/a_share_trader.py" should-alert-v2 --ideas-file /tmp/a_share_ideas_v2.json
python3 "$CODEX_HOME/skills/a-share-trader/scripts/a_share_trader.py" send-email-v2 --mode daily --ideas-file /tmp/a_share_ideas_v2.json

Recommended profiles:

• full_preopen for the full pre-open baseline scan
• full_reprice for call-auction/opening repricing
• light_preopen for lightweight pre-open confirmation
• light_intraday for holdings-first intraday alerts
• light_postclose for lightweight post-close review

4. Gather fresh intelligence with current sources only when you need to enrich the scan output. Use browsing for latest policy, company, or news claims only after market data has been fetched. Prefer primary or authoritative Chinese market sources when available, and clearly distinguish sourced facts from inference.

5. The built-in V1 model scores each candidate on:

• event strength
• time sensitivity
• price and volume confirmation
• downside and uncertainty penalty

6. The scanner outputs two pools:

• short_term_candidates for 1-3 day setups
• swing_candidates for 1-3 week setups

Each candidate includes:

• ticker
• name
• strategy_bucket
• desired_action
• trigger_type
• factor_score
• event_score
• technical_score
• composite_score
• reasons

7. Convert scored candidates into normalized actions:

• BUY when conviction is high and a concrete entry/exit plan exists
• SELL only when there is a clear reduction or exit thesis
• WATCH when the setup is interesting but not actionable enough
• HOLD when an existing thesis remains intact but no trade change is warranted

8. If you need to rebuild ideas manually from an existing snapshot and candidate file:

python3 "$CODEX_HOME/skills/a-share-trader/scripts/a_share_trader.py" build-ideas \
  --snapshot-file "$CODEX_HOME/skills/a-share-trader/state/market_snapshot.json" \
  --candidates-file /tmp/a_share_candidates.json \
  --output /tmp/a_share_ideas.json

The candidate file may contain catalysts, desired action, reasons, and fallback market data metadata, but it must not replace AKShare prices when AKShare has valid prices.

9. Validate the resulting ideas:

python3 "$CODEX_HOME/skills/a-share-trader/scripts/a_share_trader.py" validate-ideas --ideas-file /tmp/a_share_ideas.json

10. Apply balanced risk rules with the helper script. After the ideas file exists, run:

python3 "$CODEX_HOME/skills/a-share-trader/scripts/a_share_trader.py" build-report --mode daily --ideas-file /tmp/a_share_ideas.json

Use --mode intraday for hourly checks. The script will:

• enforce exposure caps
• round share counts to A-share board lots
• derive suggested_lots = suggested_shares / 100
• carry reference_price from entry_range
• require last_close and recent_bars_summary for actionable ideas
• enforce local portfolio context for sell, hold, reduce, exit, and add-position suggestions
• downgrade low-confidence ideas to WATCH
• suppress SELL without a clear sell thesis
• downgrade invalid price ranges to WATCH
• generate a dedupe signature for alerting

11. Before sending an urgent alert, check dedupe state:

python3 "$CODEX_HOME/skills/a-share-trader/scripts/a_share_trader.py" should-alert --ideas-file /tmp/a_share_ideas.json

Alert immediately only when:

• at least one idea reaches medium-or-higher alert severity
• the alert is not a recent duplicate

12. When an alert should be sent, email the rendered report to the configured recipient and also post a concise thread update in the current conversation. Use the full HTML email template for mail through QQ SMTP and build-summary for the shorter thread summary.

Output contract

The final recommendation table must include these columns for each idea:

• ticker
• name
• action
• suggested_lots
• suggested_capital_cny
• suggested_shares
• reference_price
• position_context
• current_holding_shares
• current_avg_cost
• entry_range
• stop_loss
• take_profit
• last_close
• data_provider
• data_mode
• source_timestamp
• recent_bars_summary
• confidence
• reasons
• trigger_type
• expiry

If there is no high-quality opportunity, explicitly say 今日无高质量机会.

Daily open report

The daily report must contain:

• decision summary at the top
• actionable buy/sell cards before market analysis
• stock name, code, lots, shares, reference price, and suggested capital for every BUY/SELL
• last close and legal limit-up/limit-down price band for every BUY/SELL
• whether the action is a new position, add, reduce, or exit
• broad market overview sourced from the fixed market snapshot below the action blocks
• risk warnings and no-trade conditions

Use:

python3 "$CODEX_HOME/skills/a-share-trader/scripts/a_share_trader.py" build-report --mode daily --format html --ideas-file /tmp/a_share_ideas.json

Also generate the shorter thread summary with:

python3 "$CODEX_HOME/skills/a-share-trader/scripts/a_share_trader.py" build-summary --mode daily --ideas-file /tmp/a_share_ideas.json

Send the final daily email with:

python3 "$CODEX_HOME/skills/a-share-trader/scripts/a_share_trader.py" send-email --mode daily --ideas-file /tmp/a_share_ideas.json

Use true HTML mail via QQ SMTP. Use red emphasis for bullish or rising signals and green emphasis for bearish or falling signals.

Hourly checks

The hourly report must contain:

• check timestamp
• triggered stock name and code
• reasons, suggested action, lots, shares, reference price, and invalidation
• local holding context when the suggestion is add, reduce, or exit
• a short urgent format rather than a long report

Only send immediate email + thread notification when should-alert returns send_alert: true.

Alerting thresholds

This implementation is fixed to medium threshold by default.

Immediate alert examples:

• material regulatory or policy news with clear sector impact
• earnings or announcement shock with strong price/volume confirmation
• limit-up/limit-down or breakout/breakdown with unusual volume
• sector-wide linkage with tradable confirmation

Non-urgent examples:

• weak headlines without confirmation
• purely speculative momentum with unclear exit plan
• duplicate signals already alerted recently

References

Read only what you need:

• Signal rubric
• Output schema
• Automation prompts