Shadowell · Shadowell · Aug 10, 2026 · Aug 10, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml 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
@@ -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
@@ -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
@@ -0,0 +1,21 @@
+## Summary
+
+<!-- Why this change is needed (1–3 bullets). -->
+
+-
+
+## Changes
+
+<!-- What you changed. -->
+
+-
+
+## Test plan
+
+- [ ] Relevant unit / API tests pass (`pytest …`)
+- [ ] Manual check (describe): 
+- [ ] Docs updated if install / API behavior changed
+
+## Notes
+
+<!-- Screenshots, breaking changes, follow-ups. -->
diff --git 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
@@ -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
@@ -1,16 +1,58 @@
-# Alpha — 自进化量化选股系统
+# Alpha — Self-Evolving Quantitative Stock Screening
 
 <p align="center">
-  <strong>A 股量化选股 · Kronos K线预测模型 · Hermes Agent 自进化闭环</strong>
+  <strong>A-share quant screening · Kronos K-line foundation model · Hermes Agent self-evolution loop</strong><br>
+  <em>A 股量化选股 · Kronos K线预测模型 · Hermes Agent 自进化闭环</em>
 </p>
 
 <p align="center">
+  <a href="https://github.com/Shadowell/Alpha/stargazers"><img alt="GitHub Stars" src="https://img.shields.io/github/stars/Shadowell/Alpha?style=social"></a>
+  <a href="https://github.com/Shadowell/Alpha/network/members"><img alt="GitHub Forks" src="https://img.shields.io/github/forks/Shadowell/Alpha?style=social"></a>
+  <a href="https://github.com/Shadowell/Alpha/actions/workflows/tests.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/Shadowell/Alpha/tests.yml?branch=main&label=CI"></a>
   <a href="https://github.com/Shadowell/Alpha/releases/latest"><img alt="GitHub Release" src="https://img.shields.io/github/v/release/Shadowell/Alpha"></a>
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
+  <img alt="Python" src="https://img.shields.io/badge/Python-3.10%2B-blue">
 </p>
 
+<p align="center">
+  <a href="#english-overview">English</a> ·
+  <a href="#中文简介">中文</a> ·
+  <a href="#快速开始">Quick Start</a> ·
+  <a href="CONTRIBUTING.md">Contributing</a> ·
+  <a href="SECURITY.md">Security</a> ·
+  <a href="https://github.com/Shadowell/Alpha/issues/new/choose">Report Issue</a>
+</p>
+
+## 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
@@ -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