If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ArvinLovegood/go-stock shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit today
• 2 active contributors
• GPL-3.0 licensed
• CI configured
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 99% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ArvinLovegood/go-stock repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ArvinLovegood/go-stock.

What it runs against: a local clone of ArvinLovegood/go-stock — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ArvinLovegood/go-stock | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch dev exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ArvinLovegood/go-stock. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ArvinLovegood/go-stock.git
#   cd go-stock
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ArvinLovegood/go-stock and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ArvinLovegood/go-stock(\\.git)?\\b" \\
  && ok "origin remote is ArvinLovegood/go-stock" \\
  || miss "origin remote is not ArvinLovegood/go-stock (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify dev >/dev/null 2>&1 \\
  && ok "default branch dev exists" \\
  || miss "default branch dev no longer exists"

# 4. Critical files exist
test -f "app.go" \\
  && ok "app.go" \\
  || miss "missing critical file: app.go"
test -f "backend/agent/agent.go" \\
  && ok "backend/agent/agent.go" \\
  || miss "missing critical file: backend/agent/agent.go"
test -f "backend/data/crawler_api.go" \\
  && ok "backend/data/crawler_api.go" \\
  || miss "missing critical file: backend/data/crawler_api.go"
test -f "ai-assistant-web/frontend/src/App.vue" \\
  && ok "ai-assistant-web/frontend/src/App.vue" \\
  || miss "missing critical file: ai-assistant-web/frontend/src/App.vue"
test -f "backend/agent/tools/tool_groups.go" \\
  && ok "backend/agent/tools/tool_groups.go" \\
  || miss "missing critical file: backend/agent/tools/tool_groups.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ArvinLovegood/go-stock"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

go-stock is a desktop application (built with Wails + Vue 3) that combines real-time stock market data aggregation (A-stock, Hong Kong stocks, US stocks) with AI-powered analysis using multiple LLM backends (OpenAI, DeepSeek, Ollama, LMStudio, etc.). It performs sentiment analysis on market trends, AI-assisted stock selection via technical indicators, and financial analysis—all stored locally without external data dependency. Desktop app monorepo: backend Go code in backend/ (agent/, tools/ for LLM orchestration and financial tools), frontend Vue 3 + TypeScript in ai-assistant-web/frontend/ with Vite bundler, shared server logic in ai-assistant-web/server.go. Platform-specific launchers (app.go, app_windows.go, app_darwin.go, app_linux.go) use Wails to bridge Go runtime with web UI.

Retail investors and traders in Chinese, Hong Kong, and US stock markets who want AI-assisted portfolio analysis without relying on cloud-based services; developers interested in building cross-platform financial analysis tools combining Go backends with Vue frontends.

Actively developed with public releases and star activity, but primarily tested on Windows 10+. The codebase shows CI/CD pipelines (.github/workflows/main.yml) and platform-specific entry points (app_windows.go, app_darwin.go, app_linux.go), indicating multi-platform intent. No indication of v1.0 stability; current README explicitly states 'for entertainment only' and recommends careful use.

Single maintainer (ArvinLovegood) with no visible team contributions; dependency on multiple LLM providers means breaking API changes from OpenAI/DeepSeek/etc could block functionality. The codebase is young (no maturity indicators like semantic versioning or deprecation policies visible). Frontend dependencies are well-maintained (Vue 3.5.22, NaiveUI 2.43.1), but backend Go dependencies are not listed—potential hidden dependency bloat.

Active feature development in LLM integrations (chat_model_factory.go, agent.go show agentic patterns) and stock analysis tools (choice_stock_by_indicators_tool.go, data_tools_wrapper.go). The codebase structure suggests ongoing expansion of market coverage and AI provider support; no recent commit data visible but README references latest GitHub releases.

git clone https://github.com/ArvinLovegood/go-stock.git
cd go-stock
cd ai-assistant-web/frontend && npm install && npm run build
cd .. && go run ./cmd/ai-assistant-web/main.go

Requires Go 1.18+ and Node 18+ for frontend builds.

Daily commands: Dev: cd ai-assistant-web/frontend && npm run dev (Vite dev server on :5173), then go run ./cmd/ai-assistant-web/main.go (Go backend + Wails). Prod: npm run build → generates static assets in ai-assistant-web/static/, then binary embeds them (see ai-assistant-web/server.go for static serving).

• app.go — Main application entry point and initialization logic for the desktop/native app wrapper across platforms.
• backend/agent/agent.go — Core AI agent orchestration engine that coordinates LLM interactions, tool selection, and response generation for stock analysis.
• backend/data/crawler_api.go — Primary data acquisition layer that fetches stock market data, news, and financial information from external sources.
• ai-assistant-web/frontend/src/App.vue — Root Vue 3 component for the web UI that orchestrates the user interface and integrates with backend APIs.
• backend/agent/tools/tool_groups.go — Factory and registry for all available AI tools (stock data, news analysis, financial reports) that agents can invoke.
• ai-assistant-web/cmd/ai-assistant-web/main.go — Web server entry point that sets up the API routes and serves both frontend assets and backend endpoints.
• backend/agent/chat_model_factory.go — LLM provider abstraction and factory supporting DeepSeek, OpenAI, Ollama, LMStudio, and other platforms.

Add a New AI Tool/Skill

1. Create a new tool struct and implement the tool interface in backend/agent/tools/ directory (backend/agent/tools/new_tool_name.go)
2. Register the tool in the tool group factory to make it available to agents (backend/agent/tools/tool_groups.go)
3. Add a corresponding data API method in backend/data/ if tool needs external data fetching (backend/data/data_source_api.go)
4. Test the tool with standalone unit tests to verify tool schema and execution (backend/agent/tools/new_tool_name_test.go)

Add a New Data Source or API Integration

1. Implement data fetching logic in new file under backend/data/ following naming convention (e.g., source_api.go) (backend/data/new_source_api.go)
2. Add data structs and parsing logic to handle responses from the external API (backend/data/new_source_api.go)
3. Create a corresponding AI tool wrapper in backend/agent/tools/ to expose the data to agents (backend/agent/tools/data_tools_wrapper.go)
4. Add unit tests covering network calls and data parsing (use mock HTTP for reproducibility) (backend/data/new_source_api_test.go)

Add a New UI Page or Feature

1. Create a new Vue component in frontend/src/ directory (ai-assistant-web/frontend/src/NewFeature.vue)
2. Add route or tab reference in the main App.vue component (ai-assistant-web/frontend/src/App.vue)
3. Implement API calls via the existing api.ts client if backend endpoint exists, or add new endpoint (ai-assistant-web/frontend/src/api.ts)
4. Add corresponding backend API handler in ai-assistant-web/server.go or agent_api.go (ai-assistant-web/server.go)

Support a New LLM Provider

1. Extend chat_model_factory.go to recognize the new provider type and instantiate the correct client (backend/agent/chat_model_factory.go)
2. Implement a new LLM client struct that conforms to the LLM interface (call, stream, token counting) (backend/agent/chat_model_provider.go)
3. Add configuration validation and authentication handling for the new provider (backend/agent/chat_model_factory.go)
4. Test end-to-end with mock responses and live API calls if credentials available (backend/agent/agent_test.go)

LLM API keys: Requires environment variables or config file for LLM provider credentials (OpenAI API key, DeepSeek token, etc.)—missing setup will silently fail at chat time. Frontend build artifact caching: npm run build outputs to ai-assistant-web/static/assets; Go binary must be rebuilt after frontend changes for Wails to pick up new assets. Stock data sources: Code assumes specific data provider APIs (not visible in file list)—changes to data source endpoints could break data fetching silently. Platform differences: app_linux.go, app_windows.go, app_darwin.go have platform-specific code—bugs may only manifest on non-Windows platforms. Go mod not listed: No go.mod visible, suggesting it exists at repo root but dependencies are unknown risk.

• LLM Agent with Tool Use — backend/agent/agent.go implements agentic loops where the LLM decides which tools (stock data, indicators, sentiment analysis) to call—fundamental to how go-stock reasons about stocks
• Provider Abstraction / Factory Pattern — chat_model_factory.go abstracts different LLM providers (OpenAI, DeepSeek, Ollama) behind a common interface—essential for understanding how go-stock supports multiple AI backends without rewriting agent code
• Desktop App IPC (Inter-Process Communication) — Wails bridges Go runtime ↔ JavaScript/Vue via IPC; understanding message passing between frontend and backend is critical for modifying go-stock's architecture
• Token Management / Rate Limiting — backend/agent/token_utils.go suggests token counting logic for LLM cost control across multiple API calls—relevant for managing expensive API quotas
• Chat Memory / Conversation Context — backend/agent/chat_memory.go maintains multi-turn conversation state—essential for understanding how go-stock preserves analysis context across user interactions
• Technical Indicators (TA-Lib style) — backend/agent/tools/choice_stock_by_indicators_tool.go references financial indicators for stock selection—understanding RSI, MACD, Bollinger Bands is prerequisite for extending analysis tools
• Sentiment Analysis for Market Data — README mentions 'market sentiment analysis' and 'individual stock sentiment'—likely uses LLM to classify market news/trends as bullish/bearish, core to go-stock's decision-making

• finrl-meta/finrl-meta — Similar Python-based AI stock analysis framework; could inspire feature backport or multi-language comparison studies
• openai/gpt-4-vision-examples — Official examples for vision + LLM integrations; relevant if go-stock plans to analyze stock charts via vision models
• langchain-ai/langchain-go — Go port of LangChain framework—likely used or could be leveraged for more sophisticated agentic workflows in go-stock
• deepseek-ai/DeepSeek-VL — DeepSeek's vision model (mentioned in supported providers); relevant for chart analysis features
• wailsapp/wails — The desktop framework go-stock is built on; critical for understanding Wails lifecycle, IPC, and embedding patterns

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for backend/agent/tools with mocking framework

The tools directory contains critical stock data processing logic (stock_price_info_tool.go, stock_k_line_data_tool.go, financial_reports_tool.go, etc.) but only 2 test files exist (data_tools_wrapper_test.go and holiday_tool_test.go). Most tools lack test coverage. This is high-value because: (1) data accuracy is critical for financial tools, (2) multiple LLM platform integrations (DeepSeek, OpenAI, Ollama) need reliable tool outputs, (3) missing tests make refactoring risky. Add tests using testify/mock or similar to mock external API calls.

• [ ] Create backend/agent/tools/stock_price_info_tool_test.go with mock data sources
• [ ] Create backend/agent/tools/stock_k_line_data_tool_test.go testing data validation and transformations
• [ ] Create backend/agent/tools/financial_reports_tool_test.go with edge cases (missing data, API failures)
• [ ] Create backend/agent/tools/market_news_tool_test.go and stock_news_tool_test.go
• [ ] Ensure tests cover error handling for the multiple stock markets (A股, 港股, 美股)
• [ ] Run 'go test ./backend/agent/tools/...' and aim for >80% coverage

Add GitHub Actions CI workflow for frontend TypeScript type checking and Vue component validation

The frontend (ai-assistant-web/frontend/) uses TypeScript and Vue 3 with vite, but .github/workflows/main.yml likely doesn't include frontend-specific checks. The build script runs 'vue-tsc --noEmit' locally but there's no automated CI enforcement. This prevents regressions in: (1) component type safety, (2) Vue 3 compatibility, (3) build failures before merge. Current setup supports multiple UI-heavy features (md-editor-v3, naive-ui charts for stock data visualization).

• [ ] Open .github/workflows/main.yml and examine current jobs
• [ ] Add job 'frontend-lint-and-type-check' that: runs 'cd ai-assistant-web/frontend && npm install && npm run build' on Node 18+
• [ ] Ensure job fails if 'vue-tsc --noEmit' reports errors (exit code != 0)
• [ ] Add separate lint job using ESLint or Biome for ai-assistant-web/frontend/src/**/*.{ts,vue}
• [ ] Configure to run on PR and main branch pushes
• [ ] Test locally: 'cd ai-assistant-web/frontend && npm run build' should pass

Document and add integration tests for chat_model_factory.go supporting multiple LLM platforms

Backend supports 6+ LLM platforms (DeepSeek, OpenAI, Ollama, LMStudio, AnythingLLM, 硅基流动, 火山方舟, 阿里云百炼) via chat_model_factory.go, but no integration tests verify the factory correctly instantiates models or that chat_memory.go works across platform APIs. This is high-value because: (1) factory pattern complexity with multiple providers, (2) users rely on platform switching, (3) memory/context management is critical for agent reasoning. Add tests with mocked HTTP servers.

• [ ] Create backend/agent/chat_model_factory_test.go testing factory.CreateChatModel() for each supported platform
• [ ] Mock HTTP servers (httptest) for each LLM provider's API contract
• [ ] Create backend/agent/chat_memory_test.go testing message persistence and token counting across model types
• [ ] Test edge case: switching LLM mid-conversation and memory retention
• [ ] Verify token_utils.go correctly counts tokens for different model providers (GPT vs Ollama encoding differences)
• [ ] Document supported platforms

• Add unit tests for backend/agent/tools/ (choice_stock_by_indicators_tool.go, bk_dict_tool.go have no visible tests)—extend the pattern from agent_tools_test.go to cover all tools.
• Document LLM provider setup in CONTRIBUTING.md—add concrete examples for obtaining API keys for OpenAI, DeepSeek, Ollama, and siliconflow with working config templates.
• Add TypeScript type definitions for stock market data models in ai-assistant-web/frontend/src/—create types for stock quote, technical indicator, sentiment score, and sentiment data structures returned by backend.

• High · Hardcoded Email Address for Security Reports — SECURITY.md - Section 2.1. The SECURITY.md file contains a hardcoded email address (sparkmemory@163.com) for security vulnerability reporting. This email is publicly visible and could be targeted for spam, phishing attempts, or abuse. Fix: Use a dedicated security reporting channel such as GitHub Security Advisory, a contact form on the project website, or a PGP-encrypted contact method. Remove the plaintext email address from the repository.
• High · Missing Environment Variable Configuration Validation — ai-assistant-web/frontend/.env.example and ai-assistant-web/frontend/src/api.ts. The frontend includes .env.example file but lacks documented validation of critical environment variables. The api.ts file likely contains API endpoints that could be exposed if environment variables are misconfigured. Fix: Implement runtime validation for environment variables, document all required environment variables with security implications, and add checks to prevent missing or invalid configurations from reaching production.
• High · Potential Sensitive Data Exposure in Frontend — ai-assistant-web/frontend/src/api.ts. The application handles stock market data and financial information. Frontend code in api.ts likely contains API endpoints and authentication logic. If not properly secured, this could expose financial data or API credentials. Fix: Ensure all API calls use HTTPS, implement proper authentication tokens (JWT with short expiry), never store sensitive credentials in frontend code, implement CORS properly, and use secure HTTP-only cookies for session management.
• High · Outdated or Potentially Vulnerable Frontend Dependencies — ai-assistant-web/frontend/package.json. Several dependencies have version constraints that may allow outdated versions: naive-ui (^2.43.1), md-editor-v3 (^5.8.4), and others use caret versioning which may not pull in critical security patches. Fix: Run 'npm audit' to identify vulnerabilities, update all dependencies to their latest secure versions, consider using npm lockfile (package-lock.json) in version control, and implement automated dependency scanning in CI/CD pipeline.
• High · Missing Vue.js XSS Protection Configuration — ai-assistant-web/frontend/src/App.vue and md-editor-v3 dependency. The application uses Vue 3 and md-editor-v3 for markdown editing. Markdown editors can be vectors for XSS attacks if not properly configured, especially when displaying user-generated or external content. Fix: Implement HTML sanitization using libraries like DOMPurify, disable dangerous HTML rendering in markdown, validate and sanitize all user inputs, and implement Content Security Policy (CSP) headers.
• Medium · Unclear Backend API Security Implementation — backend/data/ and backend/agent/ directories. Multiple backend API files (ai_assistant_api.go, crawler_api.go, etc.) suggest external API integrations for stock data and news. The security of API communication and credential storage is not visible from the provided structure. Fix: Implement API authentication securely (OAuth 2.0 or similar), use environment variables for API keys (never hardcode), implement rate limiting, validate all external API responses, and log security events without exposing sensitive data.
• Medium · Missing Security Headers Configuration — ai-assistant-web/server.go and static file serving. No visible configuration for security headers (CSP, X-Frame-Options, X-Content-Type-Options, etc.) in the Go backend or frontend served by ai-assistant-web/server.go. Fix: Implement security headers in the Go server: set Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Strict-Transport-Security, and X-XSS-Protection headers.
• Medium · SQL Injection Risk in Data Access Layer — backend/data/ directory - various *_api.go files. Multiple data API files (custom_strategy_api.go, financial_reports_tool.go, etc.) suggest database access. Without seeing the actual code, there's risk of SQL injection if string concatenation is used for queries. Fix: Use parameterized queries or ORM frameworks exclusively, never concatenate user input into SQL queries, implement input validation and sanitization, and use principle

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.