back
loading skill details...
Download, configure, run, verify, and troubleshoot Insight Claw, an A-share self-selected stock analysis pipeline.
---
name: insight-claw-hermes
description: Download, configure, run, verify, and troubleshoot Insight Claw, an A-share self-selected stock analysis pipeline.
version: 0.3.1
author: GeraltJc
license: MIT
platforms: [macos, linux]
metadata:
hermes:
tags: [Finance, A-Share, CLI, Analysis, Automation]
related_skills: []
config:
- key: insight-claw.repo_dir
description: Local directory where the Insight Claw repository should be cloned or reused.
default: "~/insight-claw"
prompt: Insight Claw repository directory
- key: insight-claw.default_stocks
description: Default self-selected stocks for first validation runs.
default: "000001,600519"
prompt: Default stock codes for Insight Claw validation
required_environment_variables:
- name: AIHUBMIX_KEY
prompt: AIHubMix API key
help: Configure this when using the recommended OpenAI-compatible AIHubMix path.
required_for: LLM structured analysis
- name: OPENAI_API_KEY
prompt: OpenAI-compatible API key
help: Configure this as the primary key or as fallback when AIHUBMIX_KEY is not available.
required_for: LLM structured analysis
---
# Insight Claw
Insight Claw 是面向 A 股自选股的自动化自选股分析流水线。它围绕一组自选股收集行情数据、筹码分布和搜索情报，调用模型生成结构化分析，最终产出可保存或推送的决策结果。
## When to Use
Use this skill when a user wants Hermes Agent to download, configure, run, verify, or troubleshoot Insight Claw.
## Quick Reference
Insight Claw is an A-share self-selected stock analysis pipeline.
For expanded commands, environment examples, GitHub Actions setup, and troubleshooting details, read:
- `references/quickstart.md`
- `references/troubleshooting.md`
| Task | Command |
| --- | --- |
| Download | `git clone https://github.com/GeraltJc/insight-claw.git insight-claw` |
| Create environment | `python -m venv .venv` |
| Install dependencies | Download-probe default PyPI and the Tsinghua mirror, then install with the faster successful index for this run only. |
| First validation | `.venv/bin/python -m justice_plutus run --stocks 000001,600519 --workers 1 --no-notify` |
If the user is already inside an Insight Claw checkout, reuse it instead of cloning a duplicate repository.
## Execution Contract
Hermes should not clone and reinstall on every request. Use this decision flow:
### First-time setup
Run this setup flow only when the Insight Claw repository or `.venv` environment is missing:
```bash
git clone https://github.com/GeraltJc/insight-claw.git insight-claw
cd insight-claw
python -m venv .venv
.venv/bin/python -m pip download --no-cache-dir --no-deps --dest /tmp/insight-claw-pip-probe-pypi --index-url https://pypi.org/simple requests==2.32.5
.venv/bin/python -m pip download --no-cache-dir --no-deps --dest /tmp/insight-claw-pip-probe-tuna --index-url https://pypi.tuna.tsinghua.edu.cn/simple requests==2.32.5
```
Then run exactly one dependency install command: default PyPI if it is faster, or the Tsinghua mirror if it is faster/default PyPI fails. After dependencies are installed, run the first validation:
```bash
.venv/bin/python -m justice_plutus run --stocks 000001,600519 --workers 1 --no-notify
```
Before installing dependencies, always compare default PyPI and the Tsinghua mirror with an actual package download probe, not only index metadata:
```bash
.venv/bin/python -m pip download --no-cache-dir --no-deps --dest /tmp/insight-claw-pip-probe-pypi --index-url https://pypi.org/simple requests==2.32.5
.venv/bin/python -m pip download --no-cache-dir --no-deps --dest /tmp/insight-claw-pip-probe-tuna --index-url https://pypi.tuna.tsinghua.edu.cn/simple requests==2.32.5
```
If default PyPI is faster or the mirror fails, install normally:
```bash
.venv/bin/python -m pip install -r requirements.txt
```
If the Tsinghua mirror is faster or default PyPI fails, use the mirror only for the current install command:
```bash
.venv/bin/python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```
Do not write global `pip.conf`, `pip.ini`, or persistent pip index settings from this skill.
### Subsequent runs
When the repository and `.venv` already exist, run only the analysis command:
```bash
cd insight-claw
.venv/bin/python -m justice_plutus run --stocks 000001,600519 --workers 1 --no-notify
```
Do not automatically run `git pull` in an existing checkout. Reuse the local repository as-is unless the user explicitly asks for an update, or a failed run is traced to version or dependency drift. Before updating, inspect the local worktree state and ask for user approval.
Reinstall dependencies only after approved project updates, `requirements.txt` changes, or virtual environment failure.
## Runtime Requirements
Before running Insight Claw, confirm these requirements:
- Python 3.11+
- `git`
- `pip`
- `venv`
- Network access for dependency installation and configured data, search, LLM, or notification providers.
- Require at least one local LLM credential reference for real structured analysis. Prefer an existing `AIHUBMIX_KEY`; use `OPENAI_API_KEY` as fallback or primary key when appropriate. Secrets must stay local to the user's checkout or Hermes secret handling.
## Procedure
Follow the common local setup path first.
1. Locate an existing checkout by looking for `justice_plutus/`, `src/`, and `requirements.txt` in the working tree.
2. If no checkout exists, confirm the user wants to use the canonical repository `https://github.com/GeraltJc/insight-claw`, ask where the project should be stored, then download it with `git clone`.
3. Change into the repository directory.
4. Create an isolated Python environment with `python -m venv .venv`.
5. Before installing dependencies, compare default PyPI with `https://pypi.tuna.tsinghua.edu.cn/simple` using `pip download --no-cache-dir --no-deps`, then install with the faster successful index for this command only. Do not persist the selected index in pip configuration.
6. Before the first real analysis run, verify that a usable LLM credential is available through Hermes secret handling, the user's shell environment, or a user-approved local `.env` merge. If `.env` is missing and the user chooses local persistence, first create it from `.env.example` with `[ -f .env ] || cp .env.example .env`; then merge only missing keys or keys the user explicitly authorizes replacing. Prefer `AIHUBMIX_KEY` with OpenAI-compatible settings, or use `OPENAI_API_KEY` as fallback. Do not overwrite the whole `.env`. Do not collect, display, transmit, upload, or commit raw secret values.
7. Run the first validation without notifications:
```bash
.venv/bin/python -m justice_plutus run --stocks 000001,600519 --workers 1 --no-notify
```
Equivalent command after activating the virtual environment:
```bash
python -m justice_plutus run --stocks 000001,600519 --workers 1 --no-notify
```
Use `--stocks` for a temporary self-selected stock override. It does not mutate the persistent `STOCK_LIST` configuration.
## Configuration
Keep configuration layered so the first run stays small:
| Layer | Variables | Purpose |
| --- | --- | --- |
| Required LLM path | `AIHUBMIX_KEY`, `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL` | Enables structured analysis and decision result generation. At least one usable key path is needed for real analysis. |
| Search enhancement | `BOCHA_API_KEYS`, `TAVILY_API_KEYS`, `SERPAPI_API_KEYS` | Adds search intelligence for risks, news, performance expectations, and industry context. Missing providers should degrade rather than block the whole pipeline. |
| Market data enhancement | `TUSHARE_TOKEN` | Improves行情数据 coverage. If unavailable, Insight Claw can continue through its data-source degradation chain where supported. |
| Chip distribution | `ENABLE_CHIP_DISTRIBUTION`, `WENCAI_COOKIE`, `HSCLOUD_AUTH_TOKEN` | Enables optional 筹码分布. Missing chip data should not stop the self-selected stock analysis pipeline. |
| TongHuaShun professional mode | `IFIND_REFRESH_TOKEN`, `ENABLE_THS_PRO_DATA`, `ENABLE_IFIND_ANALYSIS_ENHANCEMENT` | Enables optional 同花顺专业数据模式 for richer professional data. |
| Notification channels | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, `FEISHU_WEBHOOK_URL` | Sends notification messages after reports are generated. Configure only after local no-notification validation passes. |
Use project terms consistently when explaining results:
- `行情数据`: historical daily bars and real-time quote facts.
- `搜索情报`: open search context used to enrich model input.
- `结构化分析`: model output in a parseable decision schema.
- `决策结果`: user-facing conclusion, risk, and action context.
- `分析报告`: local persisted report files.
- `批次汇总`: overview across all self-selected stocks in one run.
- `通知消息`: Telegram, Feishu, or another outbound message shape.
- `降级链`: the ordered fallback behavior for data sources, model routes, and notification outputs.
## Verification
Confirm that a no-notification validation run completes and produces reports:
- `reports/YYYY-MM-DD/stocks/<code>.md`
- `reports/YYYY-MM-DD/stocks/<code>.json`
- `reports/YYYY-MM-DD/summary.md`
- `reports/YYYY-MM-DD/summary.json`
- `reports/YYYY-MM-DD/run_meta.json`
## GitHub Actions
Use GitHub Actions only after the local flow is understood.
1. Configure GitHub Actions Secrets for secret values such as `AIHUBMIX_KEY`, `OPENAI_API_KEY`, `BOCHA_API_KEYS`, `TAVILY_API_KEYS`, `SERPAPI_API_KEYS`, `TUSHARE_TOKEN`, `TELEGRAM_BOT_TOKEN`, and optional provider tokens.
2. Configure GitHub Actions Variables for non-secret values such as `STOCK_LIST`, `OPENAI_BASE_URL`, `OPENAI_MODEL`, `MAX_WORKERS`, `REPORT_TYPE`, and `TELEGRAM_CHAT_ID` if the repository treats that chat id as non-secret.
3. Trigger `.github/workflows/justice_plutus_analysis.yml` with `workflow_dispatch`.
4. Use the `workflow_dispatch.stocks` input for a temporary self-selected stock override. This should not change the persistent `STOCK_LIST` variable.
5. Inspect the run status, generated artifacts, and notification channel separately. A notification failure does not necessarily mean analysis reports were not generated.
## Pitfalls
- Missing LLM credentials block real structured analysis. Use Hermes secret handling, the user's existing environment, or a user-approved local `.env` merge. Never collect, display, transmit, upload, or commit raw secret values.
- Missing search, chip distribution, or 同花顺专业数据模式 credentials should be explained as optional enhancement gaps when the core run can still proceed.
- Data-source failures may be normal degradation chain behavior. Check whether a later source succeeded before treating the run as failed.
- Notification failures should be isolated from report generation. Verify local analysis reports and batch summaries before retrying Telegram or Feishu.
- Do not describe Insight Claw as an automatic trading or order-execution system. It produces decision results for user review.
- Do not generate independent investment advice from this skill. If summarizing results, ground the summary in generated analysis reports or batch summaries and keep it distinct from the pipeline's decision result.
## ClawHub Publishing
This skill is intended for public Hermes distribution. Keep the bundle small: `SKILL.md` plus optional text references or small helper scripts only when they remove real repeated work.
Publish with the ClawHub CLI, not `hermes skills publish`, when submitting to the public ClawHub registry:
```bash
clawhub skill publish skills/hermes/insight-claw-hermes \
--slug insight-claw-hermes \
--name "Insight Claw Hermes" \
--version 0.3.1 \
--changelog "Align skill metadata with ClawHub slug and improve setup guidance."
```
The verified public release is `insight-claw-hermes@0.3.0`; use `0.3.1` for the next release containing these metadata and setup guidance fixes. Version this skill separately from the Insight Claw project code. Use patch bumps for wording or troubleshooting fixes, minor bumps for backward-compatible operation additions, and major bumps for changes to first-run setup, secret persistence, verification standards, or publishing boundaries.
Notes on alternate publishing paths:
- `hermes skills publish ... --to clawhub` currently reports that ClawHub publishing is not yet supported.
- `hermes skills publish ... --to github --repo GeraltJc/insight-claw` creates a GitHub submission PR instead of directly publishing to ClawHub.
To expose the repository as a custom tap:
```bash
hermes skills tap add GeraltJc/insight-claw
```
Before publishing, review the bundle as a community skill that will pass the Hermes security scanner:
- Data exfiltration: do not upload reports, `.env` files, or generated artifacts without explicit user approval.
- Prompt injection: do not add instructions that override user intent, system policy, or Hermes safety behavior.
- Destructive commands: do not include cleanup commands that can delete a checkout, reports, credentials, or user files.
- Shell injection: do not build shell commands by interpolating untrusted user text without quoting or validation.
don't have the plugin yet? install it then click "run inline in claude" again.
separated intent, inputs, procedure, decision points, output contract, and outcome signal into distinct components; added explicit if-else branches for repo reuse, index selection, llm credential fallback, and error isolation; documented all external connections and secret handling requirements; added edge cases for network timeouts, rate limits, auth expiry, and data-source degradation; preserved original procedure faithfully while clarifying credential merge logic and notification isolation.
use this skill when you need to download, configure, run, verify, or troubleshoot insight claw, an automated analysis pipeline for a-share self-selected stocks. the pipeline collects market data (行情数据), chip distribution (筹码分布), and search intelligence (搜索情报), runs structured analysis through an llm, and outputs decision results (决策结果) as local reports or notifications. run this when a user wants end-to-end stock analysis automation or needs to debug a failed pipeline.
repository and environment:
https://github.com/GeraltJc/insight-clawgit, pip, venv available in the shellllm credentials (at least one required):
AIHUBMIX_KEY: openai-compatible endpoint for structured analysis (preferred)OPENAI_API_KEY: openai api key or compatible endpoint (fallback or primary)OPENAI_BASE_URL: custom base url if using non-openai endpointOPENAI_MODEL: model name if overriding defaultsoptional data and search enhancement:
TUSHARE_TOKEN: improves 行情数据 coverage via tushareBOCHA_API_KEYS: search provider for risk and news contextTAVILY_API_KEYS: search provider for market contextSERPAPI_API_KEYS: search provider for research contextWENCAI_COOKIE: for optional 筹码分布 (chip distribution)HSCLOUD_AUTH_TOKEN: alternative chip distribution sourceIFIND_REFRESH_TOKEN: for optional 同花顺 professional data modeENABLE_THS_PRO_DATA: boolean to enable tonghushun pro dataENABLE_IFIND_ANALYSIS_ENHANCEMENT: boolean to enable ifind analysisnotification channels (post-analysis only):
TELEGRAM_BOT_TOKEN: bot token for telegram notificationsTELEGRAM_CHAT_ID: telegram chat id for messagesFEISHU_WEBHOOK_URL: feishu (lark) webhook for messagesuser approvals and state:
.env file locallylocate or create the repository. check the current working directory and parent directories for justice_plutus/, src/, and requirements.txt files. if found, ask the user whether to reuse the existing checkout. if not found or user declines reuse, confirm the user wants to clone from https://github.com/GeraltJc/insight-claw, ask where to store it (default ~/insight-claw), and run git clone https://github.com/GeraltJc/insight-claw.git <target-dir>.
enter the repository directory. change working directory to the cloned or reused repository root.
create isolated python environment. check if .venv directory exists. if not, run python -m venv .venv to create a virtual environment.
probe and select pip index. before installing dependencies, compare default pypi with the tsinghua mirror by running two parallel download probes (not index metadata checks):
python -m pip download --no-cache-dir --no-deps --dest /tmp/insight-claw-pip-probe-pypi --index-url https://pypi.org/simple requests==2.32.5python -m pip download --no-cache-dir --no-deps --dest /tmp/insight-claw-pip-probe-tuna --index-url https://pypi.tuna.tsinghua.edu.cn/simple requests==2.32.5time both downloads and record which completes faster. do not write global pip.conf or pip.ini files.
install dependencies with the faster index. if default pypi is faster or the mirror fails, run .venv/bin/python -m pip install -r requirements.txt. if the tsinghua mirror is faster, run .venv/bin/python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple. index selection is per-run only; do not persist it in pip config.
acquire and merge llm credentials. before the first real analysis run, confirm at least one llm credential is available:
AIHUBMIX_KEY or OPENAI_API_KEY.env exists; if not, copy .env.example to .env with [ -f .env ] || cp .env.example .env.env fileAIHUBMIX_KEY with openai-compatible settings; use OPENAI_API_KEY as fallbackrun first validation without notifications. execute .venv/bin/python -m justice_plutus run --stocks 000001,600519 --workers 1 --no-notify. this command validates the environment, llm connection, and local analysis flow without triggering external notifications. wait for completion and check for report files in reports/YYYY-MM-DD/.
run subsequent analysis with user stock list. after validation passes, run .venv/bin/python -m justice_plutus run --stocks <user-stocks> --workers 1 --no-notify (or without --no-notify once notifications are configured). use --stocks to override the default list on a single run without mutating persistent STOCK_LIST configuration.
if the user is already inside an existing insight claw checkout: reuse the repository as-is instead of cloning a duplicate. ask for confirmation before running git pull or reinstalling dependencies, unless a failed run is traced to version or dependency drift.
if the user has no llm credential: do not proceed past step 6. explain that structured analysis requires at least one of AIHUBMIX_KEY or OPENAI_API_KEY in hermes secrets, shell environment, or a user-approved local .env file.
if default pypi download probe times out or fails: fall back to the tsinghua mirror.
if the tsinghua mirror download probe times out or fails: fall back to default pypi.
if both index probes fail: stop and report the network or mirror issue. do not attempt to install dependencies.
if the first validation run fails with a data-source error (e.g., tushare unavailable): check whether later sources in the degradation chain succeeded. explain that missing optional providers (search, chip distribution, professional data) are enhancements, not blockers, and the core analysis may continue.
if the first validation run fails with an llm error (e.g., invalid key, rate limit, auth expired): stop. ask the user to verify the llm credential, check api quota and rate limits, and confirm the endpoint is reachable.
if the first validation run fails with a file permissions or directory error: stop. ask the user to check directory ownership, umask, and disk space.
if the user requests github actions setup: explain that github actions is only supported after the local flow has been validated successfully. guide them to configure secrets and variables in the github repository settings, then trigger the workflow manually.
if a notification fails after reports are generated: isolate the failure. verify that local reports exist in reports/YYYY-MM-DD/ before retrying notifications. do not treat notification errors as analysis failures.
if the user asks for independent investment advice based on the results: decline. explain that insight claw produces decision results for user review only, and summarize only what the generated reports state. do not generate independent recommendations.
a successful run produces the following files in the reports/ directory:
reports/YYYY-MM-DD/stocks/<code>.md: individual stock markdown analysis report for each stock analyzedreports/YYYY-MM-DD/stocks/<code>.json: individual stock json decision schema for each stock analyzedreports/YYYY-MM-DD/summary.md: batch summary markdown across all stocks in the runreports/YYYY-MM-DD/summary.json: batch summary json (批次汇总) with aggregated findingsreports/YYYY-MM-DD/run_meta.json: metadata about the run (execution time, worker count, provider status, degradation flags)if notifications are enabled:
TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID are set)FEISHU_WEBHOOK_URL is set)all reports remain local until the user explicitly shares, uploads, or commits them. the skill does not automatically upload generated files, credentials, or artifacts to any remote service.
the skill worked if:
reports/YYYY-MM-DD/ and see stock-by-stock analysis and a summarythe skill did not work if:
if any step fails, stop and report the error. do not attempt to skip steps or mask failures by running partial analysis.
credits: original skill by geraltjc, published to clawhub. enriched to implexa standards with explicit decision points, edge cases, and secret handling guidance.