From b5792b540209b0b4a91e36f9c0f42e294ed84544 Mon Sep 17 00:00:00 2001 From: shadowell Date: Mon, 10 Aug 2026 19:45:28 +0800 Subject: [PATCH] docs: polish Alpha for Codex OSS application readiness Add bilingual README overview, contributing/security docs, and GitHub Issue/PR templates so maintainership and adoption are clearer. Co-authored-by: Cursor --- .github/ISSUE_TEMPLATE/bug_report.yml | 57 +++++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 52 ++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 21 ++++ CHANGELOG.md | 7 ++ CONTRIBUTING.md | 110 +++++++++++++++++++++ README.md | 55 ++++++++++- SECURITY.md | 32 ++++++ docs/oss-application-draft.md | 46 +++++++++ 9 files changed, 385 insertions(+), 3 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md create mode 100644 docs/oss-application-draft.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..fccf10f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,57 @@ +name: Bug report +description: Report a reproducible bug in Alpha +title: "[bug] " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for helping improve Alpha. Please fill in as much as you can. + - type: textarea + id: summary + attributes: + label: Summary + description: What went wrong in one or two sentences? + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: Steps to reproduce + description: Minimal steps starting from a clean checkout if possible. + placeholder: | + 1. cp .env.example .env + 2. ./start.sh + 3. Call GET /api/... + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + description: Include logs / traceback snippets (redact secrets). + validations: + required: true + - type: input + id: environment + attributes: + label: Environment + description: OS / Python version / install profile (base, ci, full) + placeholder: macOS 15, Python 3.12, requirements-base.txt + validations: + required: true + - type: checkboxes + id: checklist + attributes: + label: Checklist + options: + - label: I searched existing issues and did not find a duplicate + required: true + - label: I redacted tokens / `.env` secrets from logs + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..f6437d6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Documentation / README + url: https://github.com/Shadowell/Alpha#english-overview + about: Check Quick Start, architecture, and API docs before filing an issue. + - name: Security vulnerability + url: https://github.com/Shadowell/Alpha/security/advisories/new + about: Privately report security issues (do not file a public issue). diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..882403a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,52 @@ +name: Feature request +description: Propose a feature or improvement for Alpha +title: "[feat] " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Feature ideas that fit A-share screening, Kronos, Hermes Agent, or maintainability are most likely to be accepted. + - type: textarea + id: problem + attributes: + label: Problem / motivation + description: What user or maintainer pain does this solve? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: Describe the desired behavior and any API / UI touchpoints. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Other approaches you thought about (optional). + - type: dropdown + id: scope + attributes: + label: Primary area + options: + - Screening / funnel + - Kronos prediction + - Hermes Agent / MCP + - Data pipeline / cache + - Paper trading + - Frontend / UX + - Docs / DX / CI + - Other + validations: + required: true + - type: checkboxes + id: checklist + attributes: + label: Checklist + options: + - label: This is in scope for an open-source A-share research toolkit (not a request for private trading signals) + required: true + - label: I am willing to help implement or test if accepted + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..b45f8f6 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,21 @@ +## Summary + + + +- + +## Changes + + + +- + +## Test plan + +- [ ] Relevant unit / API tests pass (`pytest …`) +- [ ] Manual check (describe): +- [ ] Docs updated if install / API behavior changed + +## Notes + + diff --git a/CHANGELOG.md b/CHANGELOG.md index b0c0f60..a39ca59 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,13 @@ 本文件记录 Alpha 的重要版本变化。版本号遵循 [Semantic Versioning](https://semver.org/)。 +## [Unreleased] + +### Added + +- Bilingual README overview (English + 中文) with contribution / security entry points. +- CONTRIBUTING.md, SECURITY.md, GitHub Issue templates, and PR template for OSS maintainership. + ## [0.1.0] - 2026-07-22 ### Added diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..76c3beb --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,110 @@ +# Contributing to Alpha + +Thanks for your interest in improving Alpha. This guide covers how to report issues, propose changes, and keep PRs reviewable. + +中文说明见下方 [中文贡献指南](#中文贡献指南)。 + +## Ways to contribute + +- Bug reports and reproducible failures +- Documentation / README / translation improvements +- Tests for uncovered API or data-path edge cases +- Features that fit the A-share screening / Kronos / Hermes Agent scope + +Please open an issue first for large design changes so we can align before coding. + +## Development setup + +```bash +git clone https://github.com/Shadowell/Alpha.git +cd Alpha +python3 -m venv .venv +source .venv/bin/activate + +# Minimal local runtime +pip install -r requirements-base.txt + +# CI / offline test profile (recommended before opening a PR) +pip install -r requirements-ci.txt + +cp .env.example .env +# Fill TUSHARE_TOKEN / LLM settings only if you need live data or agent features +``` + +Run the API locally: + +```bash +./start.sh +# UI: http://127.0.0.1:18888 +``` + +## Tests + +```bash +# Offline API regression (preferred for PRs) +pytest tests/test_api_regression.py tests/test_dependency_profiles.py -q + +# Broader suite when your change touches data / cache / Kronos paths +pytest -q +``` + +Do not commit secrets (`.env`, tokens, cookies). Prefer fixtures and mocks for network-dependent tests. + +## Pull request checklist + +1. Branch from `main`, keep the PR focused on one concern +2. Update docs if behavior or install steps change +3. Add / update tests when fixing bugs or changing APIs +4. Ensure CI-relevant tests pass locally +5. Fill the PR template with summary + test plan + +## Code style + +- Prefer clear names and small functions over clever abstractions +- Match existing patterns in `app/services/` and `app/routers/` +- Keep Chinese UI copy consistent with the current dashboard tone +- Avoid drive-by refactors unrelated to the PR goal + +## Security + +If you believe you found a vulnerability, see [SECURITY.md](SECURITY.md). Do not open a public issue for sensitive reports. + +## License + +By contributing, you agree that your contributions are licensed under the MIT License (see [LICENSE](LICENSE)). + +--- + +## 中文贡献指南 + +欢迎通过 Issue / PR 参与 Alpha。 + +### 贡献类型 + +- Bug 复现与修复 +- 文档、README、翻译 +- 测试补强 +- 与 A 股选股 / Kronos / Hermes Agent 相关的功能增强 + +较大设计变更请先开 Issue 讨论。 + +### 本地开发 + +```bash +python3 -m venv .venv && source .venv/bin/activate +pip install -r requirements-base.txt +# 提 PR 前建议再装： +pip install -r requirements-ci.txt +cp .env.example .env +./start.sh +``` + +### 提 PR 前请确认 + +1. 基于最新 `main` +2. 改动范围聚焦 +3. 行为变更同步文档 +4. 相关测试通过 +5. 不要提交 `.env` / Token 等密钥 + +安全问题请按 [SECURITY.md](SECURITY.md) 私下报告。 diff --git a/README.md b/README.md index 9f4e1af..9e929ad 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,58 @@ -# Alpha — 自进化量化选股系统 +# Alpha — Self-Evolving Quantitative Stock Screening

- A 股量化选股 · Kronos K线预测模型 · Hermes Agent 自进化闭环 + A-share quant screening · Kronos K-line foundation model · Hermes Agent self-evolution loop
+ A 股量化选股 · Kronos K线预测模型 · Hermes Agent 自进化闭环

+ GitHub Stars + GitHub Forks + CI GitHub Release License: MIT + Python

+

+ English · + 中文 · + Quick Start · + Contributing · + Security · + Report Issue +

+ +## English Overview + +**Alpha** is an open-source, self-evolving quantitative stock screening system for the Chinese A-share market. It combines the **[Kronos](https://arxiv.org/abs/2508.02739) financial K-line foundation model** with a **Hermes Agent** loop so the system can observe the market, reason about themes, validate signals, and improve over time. + +| Capability | What you get | +|---|---| +| Three-pool funnel screening | Intraday scoring + promotion / demotion rules for candidate stocks | +| Kronos prediction | K-line forecast inference integrated into the research UI and APIs | +| Hermes Agent + MCP | Scheduled post-market review, announcement review, and live monitoring | +| Paper trading | Simulated execution for strategy validation without live capital | +| FastAPI + Web UI | 50+ REST endpoints, WebSocket snapshots, and an 8-tab dark dashboard | + +**Why it matters for the OSS ecosystem:** most open quant stacks are US/crypto-centric. Alpha fills a practical gap for A-share research—local data pipelines, LLM-agent workflows, and reproducible screening loops that researchers and builders can fork, audit, and extend under MIT. + +```bash +# Quick start (API / data runtime) +python3 -m venv .venv && source .venv/bin/activate +pip install -r requirements-base.txt +cp .env.example .env # add Tushare / LLM keys as needed +./start.sh # http://127.0.0.1:18888 +``` + +Full install options, API map, and architecture details are below. Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). + +## 中文简介 + Alpha 是一个面向 A 股市场的**自进化量化选股系统**。它不只是一个筛选工具——通过集成 **[Kronos](https://arxiv.org/abs/2508.02739) 金融 K 线基础模型**和 **Hermes Agent 自进化智能体**，Alpha 能够自主观察市场、分析主线、输出结构化诊断与交易建议，形成**观察 → 思考 → 校验 → 进化**的持续优化闭环。 +欢迎通过 [Issue](https://github.com/Shadowell/Alpha/issues/new/choose) / [PR](https://github.com/Shadowell/Alpha/pulls) 参与贡献，详见 [CONTRIBUTING.md](CONTRIBUTING.md)。 + --- ## 系统架构 @@ -765,4 +807,11 @@ npx playwright test 本项目采用 [MIT License](LICENSE) 开源许可。 -版本发布与持续维护记录见 [GitHub Releases](https://github.com/Shadowell/Alpha/releases) 和 [CHANGELOG.md](CHANGELOG.md)。 +- 贡献指南：[CONTRIBUTING.md](CONTRIBUTING.md) +- 安全报告：[SECURITY.md](SECURITY.md) +- 版本发布与维护记录：[GitHub Releases](https://github.com/Shadowell/Alpha/releases) · [CHANGELOG.md](CHANGELOG.md) + +## Maintainers + +- Primary maintainer: [@Shadowell](https://github.com/Shadowell) (Jie Feng) + diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..b68bdbb --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,32 @@ +# Security Policy + +## Supported versions + +| Version | Supported | +|---------|-----------| +| `main` / latest release | Yes | +| Older tagged releases | Best effort | + +## Reporting a vulnerability + +Please **do not** open a public GitHub issue for security-sensitive reports (credential leaks, remote code paths, auth bypasses, unsafe deserialization, etc.). + +Prefer one of: + +1. GitHub Security Advisory: [Report a vulnerability](https://github.com/Shadowell/Alpha/security/advisories/new) +2. Email the maintainer via the address on the [GitHub profile](https://github.com/Shadowell) + +Include: + +- Affected component / file path if known +- Steps to reproduce +- Impact assessment +- Whether a patch / PoC is available + +We aim to acknowledge reports within 7 days and coordinate a fix + disclosure timeline. + +## Safe contribution notes + +- Never commit `.env`, API tokens, cookies, or private market-data credentials +- Prefer mocked / fixture-based tests over live network calls in CI +- Treat LLM / MCP tool surfaces as untrusted input boundaries diff --git a/docs/oss-application-draft.md b/docs/oss-application-draft.md new file mode 100644 index 0000000..7918ead --- /dev/null +++ b/docs/oss-application-draft.md @@ -0,0 +1,46 @@ +# Codex for OSS — Alpha application draft + +Paste-ready answers for https://openai.com/zh-Hans-CN/form/codex-for-oss/ +Keep each free-text field ≤ 500 characters. + +## Form fields + +| Field | Value | +|---|---| +| GitHub username | `Shadowell` | +| GitHub repository URL | `https://github.com/Shadowell/Alpha` | +| Role | **Primary maintainer**（主要维护者） | + +### Why does this repository qualify?（为什么这个代码仓库符合要求？） + +``` +Alpha is an MIT-licensed, actively maintained A-share quantitative screening system combining the Kronos K-line foundation model with a Hermes Agent self-evolution loop (funnel scoring, paper trading, FastAPI + Web UI). I’m the primary maintainer. Public traction: ~18 GitHub stars and 14 forks, with ongoing CI (pytest) and recent dependency/data-pipeline maintenance. It fills a niche most open quant stacks miss—practical Chinese-market research tooling that others can fork, audit, and extend. +``` + +(~430 chars) + +### How will you use API credits for the project?（你将如何针对自己的项目使用 API 额度？） + +``` +Use Codex/API credits for maintainer workflows: PR review & refactoring, expanding offline pytest coverage for data/cache/Kronos paths, generating release notes/changelog drafts, dependency & CI hardening, and drafting security/docs improvements. Goal: reduce review latency and keep Alpha sustainable as forks/contributors grow—not for private trading signal generation. +``` + +(~360 chars) + +### Interests + +- Codex Security（建议勾选） +- 项目的 API 额度（建议勾选） + +### Anything else? + +``` +Happy to share maintainer workflows publicly if useful to the Codex for OSS program. Repo docs now include bilingual README overview, CONTRIBUTING, SECURITY, and GitHub Issue/PR templates to make contribution and review smoother. +``` + +## Before submit checklist + +- [ ] GitHub profile visibility = **Public**（Settings → Public profile / Appearances；确保个人页可被未登录访问） +- [ ] Repo visibility = **Public**（已是） +- [ ] Email on the form = ChatGPT account email +- [ ] This polish PR merged to `main` so reviewers see CONTRIBUTING / templates