规则优先的股票观察清单监控与交易计划 Agent，面向日线到周线级别的辅助决策。
StockOps 从 YAML 观察清单读取标的，通过确定性规则计算指标、识别入场与风险信号，并生成结构化的 Decision Card。LLM 只负责解释和风险复核，不负责决定交易动作。
Warning
StockOps 不是自动交易系统，不会连接券商或执行订单。项目输出仅用于研究、学习和人工复核，不构成任何投资建议。
- 使用 YAML 维护固定观察清单和单票交易计划；
- 支持本地 CSV，以及基于 AkShare 的 A 股实时行情和日线；
- 计算 MA、成交量均线、MACD、ATR、BOLL、KDJ 和突破区间等指标；
- 使用确定性规则识别突破、回踩、右侧确认、减仓和退出信号；
- 通过显式状态机校验
WATCHING、ENTRY_READY、HOLDING、REDUCE和EXIT的单次分析结果； - 使用 LangGraph 编排分析流程，并通过 Harness 限制不同运行模式的权限；
- 生成包含信号、风险、入场区间、止损位和后续观察项的 Decision Card；
- 支持交互式 CLI 和周期扫描 daemon；
- 可选接入通义千问，对规则结果进行解释和风险复核；
- 将分析记录和 Harness 审计日志保存为本地 JSONL。
YAML 观察清单
↓
获取日线行情
↓
计算技术指标
↓
确定性规则评估
↓
状态机检查状态转换
↓
生成 Decision Card ← 实时行情仅用于展示
↓
可选 LLM 复核、记录与通知
规则引擎负责信号、状态转换和风险边界。LLM 无法跳过这些步骤，也不能覆盖规则结论。当前状态转换结果只写入 Decision Card，不会自动回写 YAML；下一轮仍以观察清单中的 state 为起点。
- Python 3.11 或更高版本；
- 推荐使用 uv 管理依赖；
- 使用实时 A 股行情时，需要能够访问对应的新浪或腾讯行情接口。
git clone https://github.com/chacha923/StockOps.git
cd StockOps
uv sync --extra dev仓库内置一只示例标的和对应 CSV 行情，可以直接运行：
uv run stockops chat \
--watchlist data/watchlist/example.yaml \
--prices examples/prices进入交互模式后：
/watchlist
/quote 600000
/analyze 600000
/help
/exit
也可以直接输入观察清单中的股票代码，等价于 /analyze <symbol>。
当前版本使用 plans 数组维护观察标的。symbol 必须使用字符串，支持六位 A 股代码（如 600000），也支持带市场前缀的形式（如 sh600000、sz000001、bj430047）。系统会统一归一化为六位代码，避免观察清单、CSV 文件名和行情 Provider 使用不同标识。简称、拼音缩写或其他业务名称不能作为标的标识。
plans:
- symbol: "600000"
name: "示例观察标的"
state: "WATCHING"
thesis: "关注放量突破后的持续性。"
timeframe: "days_to_weeks"
entry_type: "breakout"
entry_zone_low: 10.80
entry_zone_high: 11.20
stop_loss: 10.40
take_profit_rule: "分批止盈，跌破 MA10 降低风险。"
holding_price: null
position_ratio: null
notes:
- "示例配置，不代表真实交易观点。"核心字段：
| 字段 | 必填 | 说明 |
|---|---|---|
symbol |
是 | 唯一标识；六位 A 股代码或带 sh、sz、bj 前缀的代码 |
name |
否 | 展示名称 |
state |
否 | 初始状态，默认为 WATCHING |
thesis |
否 | 人工维护的关注逻辑 |
entry_zone_low/high |
否 | 人工指定的入场区间，优先于规则生成值 |
stop_loss |
否 | 人工指定的硬止损位 |
holding_price |
否 | 持仓成本，供后续持仓风险功能使用 |
position_ratio |
否 | 仓位比例，供后续持仓风险功能使用 |
StockOps 只分析观察清单中的标的。Chat 模式每次分析一只；daemon 模式会逐项扫描清单中的全部标的。
加载观察清单时会先规范化代码，再校验唯一性。因此 600000 与 sh600000 会被视为同一个标的，同时配置会直接报错。
当前 AkShare Provider 的默认策略是：
- 实时行情：新浪单票接口，失败后使用腾讯单票接口；
- 日线：新浪
stock_zh_a_daily，失败后使用腾讯stock_zh_a_hist_tx； - 底层 Provider 提供新浪
stock_zh_a_minute分钟线能力，但当前 CLI、workflow 和 daemon 尚未使用分钟线；当前 AkShare 版本也没有可用的腾讯分钟线回退。
直接通过命令行启用：
uv run stockops chat --market-data akshare也可以复制配置模板：
cp config/providers.example.yaml config/providers.local.yaml
uv run stockops chatconfig/providers.local.yaml 已被 Git 忽略，适合保存本地 Provider 配置。常用行情参数如下：
market_data:
provider: akshare
akshare:
primary_source: sina
fallback_enabled: true
fallback_source: tencent
adjust: qfq
quote_ttl_seconds: 3
min_request_interval_seconds: 1
request_timeout_seconds: 10实时请求具有按股票代码缓存和最小请求间隔保护。相同代码在 TTL 内会复用缓存，以降低上游压力。
不配置 LLM 时，StockOps 仍可完成全部规则分析。启用通义千问后，LLM 只会解释和复核 Decision Card。
export DASHSCOPE_API_KEY="your-api-key"
uv run stockops chat --llm qwen --qwen-model qwen3.7-max默认使用 OpenAI-compatible Responses API。如需改为 Chat Completions：
uv run stockops chat \
--llm qwen \
--qwen-api chat_completions也可以在本地配置文件中指定 Base URL 和密钥环境变量；运行时模型请通过 --qwen-model 选择。请勿提交真实 API Key。
执行一次完整扫描后退出：
uv run stockops daemon --once --market-data akshare每 300 秒扫描一次：
uv run stockops daemon \
--market-data akshare \
--interval-seconds 300daemon 会分析观察清单，并对 ENTRY_READY、REDUCE 和 EXIT 状态调用通知接口。当前默认通知渠道是终端输出，尚未实现状态变化去重及飞书、邮件等外部通知渠道。
每次分析都会生成结构化结果，主要包含：
Decision Card: 600000 示例观察标的
状态：ENTRY_READY
结论：进入待执行观察
形态：breakout
置信度：0.62
收盘价：11.80
实时价：11.80
入场区间：[...]
止损位：...
Signals
- 已命中的确定性规则
Risks
- 计划失效条件与风险提示
Next Watch
- 下一轮需要继续确认的条件
分析记录默认写入 .stockops/reviews/，Harness 审计日志默认写入 .stockops/harness/。这两个目录均不会提交到 Git。
uv run stockops --help
uv run stockops chat --help
uv run stockops daemon --help如果没有安装 console script，也可以使用模块入口：
uv run python -m stockops chat
uv run python -m stockops daemon --onceStockOps/
├── agent.md # Harness 行为策略的唯一来源
├── config/ # Provider 配置模板
├── data/watchlist/ # YAML 观察清单
├── examples/prices/ # 本地 CSV 示例行情
├── stockops/
│ ├── app/ # CLI、Chat、daemon、Harness 与通知
│ ├── data/ # 观察清单、行情 Provider 与记录仓库
│ ├── domain/ # Pydantic 领域模型
│ ├── engine/ # 信号规则、状态机和风险计划
│ ├── indicators/ # 技术指标
│ ├── llm/ # 可替换的 LLM Provider
│ ├── report/ # Decision Card 构建与 Markdown 渲染
│ └── workflow/ # LangGraph 分析流程
├── tests/ # pytest 测试
└── pyproject.toml
- 规则负责决策：指标、信号、状态转换和风险边界全部由确定性代码负责。
- LLM 只做复核：LLM 可以解释和质疑结果，但不能生成最终交易动作。
- Provider 可替换：业务流程只依赖统一行情接口，不直接依赖 AkShare 字段。
- 行为显式授权：Chat 与 daemon 的允许动作由
agent.md控制。 - 保留人工确认：项目不下单，入场区间和止损位也必须由使用者复核。
安装开发依赖并运行测试：
uv sync --extra dev
uv run pytest提交改动前建议至少确认：
uv run pytest
uv run stockops --help
uv run stockops daemon --once新增行情源时，请实现 PriceDataProvider 或 MarketDataClient 抽象，不要让上游字段泄漏到 workflow。新增规则时，请保持指标计算、信号判断、状态转换和报告渲染之间的边界，并补充相应测试。
- 持久化每只股票的最近状态，作为下一轮状态转换和变更检测的基线；
- 只在状态发生变化时通知，并支持通知去重；
- 接入飞书、邮件或系统通知；
- 完善持仓风险检查和历史复盘；
- 为港股、美股和更多行情 Provider 预留规范化标的模型；
- 在任何真实交易集成前，优先提供独立的模拟交易与人工确认机制。
欢迎通过 Issue 提交问题、需求和设计建议，也欢迎发送 Pull Request。开始较大改动前，建议先创建 Issue 对齐功能边界。
请确保：
- 新功能有清晰的用户场景，而不是只增加指标或模型调用；
- 不绕过 Harness、规则引擎和人工确认边界；
- 不提交 API Key、个人观察清单、交易记录或其他敏感数据；
- 行为变化包含对应测试和文档更新。
- API Key 应通过环境变量或被 Git 忽略的本地配置提供；
.stockops/中可能包含分析历史，请勿直接公开；- 外部行情接口可能限流、延迟、停服或返回错误数据，所有结果都需要人工复核；
- 请勿将本项目直接用于无人值守的真实交易。
仓库当前尚未包含开源许可证。在许可证补充前，代码的使用、复制和分发权利并未被明确授予。