doc: update quickguide

quick_guide.md

@@ -4,13 +4,19 @@
   - [写在前面](#写在前面)
   - [如何开始](#如何开始)
   - [框架核心能力](#框架核心能力)
+    - [关于“当前帧”的详细说明](#关于当前帧的详细说明)
+    - [关于is\_sure标记](#关于is_sure标记)
+    - [你需要做的](#你需要做的)
   - [可能遇到的问题](#可能遇到的问题)
     - [运行报错](#运行报错)
     - [运行完啥也没有](#运行完啥也没有)
     - [为啥信号会消失](#为啥信号会消失)
+    - [画图为啥不能交互](#画图为啥不能交互)
+    - [CChan类序列化/deepcopy时报递归溢出](#cchan类序列化deepcopy时报递归溢出)
+    - [其他问题](#其他问题)
   - [不可绕过的步骤](#不可绕过的步骤)
     - [CChanConfig重点关注配置](#cchanconfig重点关注配置)
-  - [取出缠论元素组织策略](#取出缠论元素组织策略)
+  - [取出缠论元素](#取出缠论元素)
     - [CKLine-合并K线](#ckline-合并k线)
       - [CKLine\_Unit-单根K线](#ckline_unit-单根k线)
     - [bi\_list-笔管理类](#bi_list-笔管理类)
@@ -32,6 +38,7 @@
   - [开源版本指标添加](#开源版本指标添加)
     - [指标画图](#指标画图)
   - [机器学习接入](#机器学习接入)
+  - [一致性](#一致性)
   - [打赏](#打赏)
 
 
@@ -89,11 +96,49 @@
 ## 框架核心能力
 一言以蔽之：
 - 根据给定范围的K线，算出当前静态范围下的缠论元素
+  - 框架对于各种元素都提供了不同的参数配置
 - 基于上述能力，提供增加K线时的增量更新缠论元素
 - 支持开发自己的数据源接入这个计算（参见[数据接入速成班](#数据接入速成班)）
 - 支持让你取出算好的元素组装你自己的策略（参见[取出缠论元素组织策略](#取出缠论元素组织策略)）
 
 
+### 关于“当前帧”的详细说明
+框架支持计算指定时间范围内K线所组成的缠论元素，也支持逐根K线投喂更新已有的缠论元素；
+
+任何时刻（比如每新增一根K线），都可以通过框架CChan这个类获得当下（到目前给定的K线为止）下所有缠论的元素（各种元素获取参见下文）；
+
+> 而对于最重要的买卖点，可以理解成每次计算出来的都是当下的“形态学”买卖点；只不过有些买卖点不是已经确定的，可能在将来消失；
+
+所以随着K线的新增，你可能会发现某个位置的买点突然消失的，或者一个买卖点的位置一直在变动；
+
+举个例子：
+- 在某下降线段尾部单边下跌的一笔中（即每根新增K线的低点都比上一根更低），那么每新增一根K线，这根K线都可能在“当下”被标识为一类买卖点，而上一根K线的标识被取消；
+- 如果某根K线之后开始反弹，那么在最低点这根K线被跌破之前，新投喂K线后这根最低点的K线会一直被**持续**标记为一买
+- 直到形态上认为这个一买不再成立
+
+<img src="./Image/frame.png" />
+
+### 关于is_sure标记
+框架会对所有元素都标明是否已经确定（或者说已经完成），可以参见各个类的is_sure属性；
+
+is_sure=False在画图结果中表现为虚线（虚笔，虚段，虚线中枢）；
+
+对于is_sure=True的元素，在后续K线新增的过程中，这些元素不会再被变更，也不可能会被标记为is_sure=False;
+
+而且is_sure=False的元素只可能出现在所有K线的头部或者尾部；
+
+### 你需要做的
+根据上面所言，框架会一直给你提示当下这一“帧”里面的缠论元素分别是什么样子；
+
+随着K线的投喂，可能很多K线都曾经在某个时候被标记为“当下”的买卖点（而且这些买卖点大部分is_sure=False）；
+
+对于那些不确定是否将来最终会成立的买卖点，你需要自己开发策略判断这些买卖点是否最终会成立，或者当下是否需要交易（比如考虑买卖点的背驰度，中枢数之类的）；
+
+> 其中需要特别说明的是，由于走势的多义性，而框架在任何一个时刻只能给出一种缠论元素的计算结果，所以必然存在某些将来成立的买卖点，在K线新增的全过程中，一次都不曾被标记为买卖点过；（当然破解方法也比较简单，每根K线进来后跑两组不同的缠论计算参数）
+
+> 而我比较偷懒，把这块策略判断的实现企图通过机器学习模型来解决；
+
+
 ## 可能遇到的问题
 ### 运行报错
 依赖最低版本为python3.11；由于本项目是高度计算密集型，鉴于python3.11发布且运算速度大幅提升，实测相比于python 3.8.5计算时间缩短约16%，故后续开发均基于python3.11；
@@ -110,6 +155,24 @@
 因为框架计算得永远都是“当前帧”下的缠论元素，随着K线的增加，原有的买卖点可能会被证明不成立（比如跌破一买），那么原本位置会被标记为买卖点的K线将不再被标记为bsp；
 
 
+### 画图为啥不能交互
+框架提供的默认画图能力其实是对接的matplotlib这个库，如果你希望在别的画图引擎上实现（比如某些web页面，或者ploty这种可交互的库），欢迎PR代码~
+
+框架提供了一个画图元素类PlotMeta，里面提供了各种元素在绘图时的坐标信息（比如已经完成了K线时间到X轴坐标的转化了），方便自行对接到不同的画图引擎上；
+
+
+### CChan类序列化/deepcopy时报递归溢出
+原因：框架里面很多缠论元素类都有一个next/pre成员指向了上一个/下一个元素，python到处是可能会遇到递归导致溢出问题；
+解决方法：加一行配置，增加系统递归深度
+
+```python
+sys.setrecursionlimit(0x100000)
+```
+
+### 其他问题
+如需作者排查，尽量提供可以直接运行的主函数文件和数据文件；
+
+
 ## 不可绕过的步骤
 很多用户使用，其实不需要细看整个代码是怎么实现了，假装相信框架没BUG，通过直接提取框架计算好的缠论元素来组装策略（具体内部元素结构的设计参见[B站视频](https://www.bilibili.com/video/BV1nu411c7oG/)）；
 
@@ -136,7 +199,7 @@ CChanConfig里面提供了很多的配置，其中很多人最容易被影响到
     - 注：如果是 1.0，那么相当于允许回测到1类买卖点的位置
 - zs_algo: 中枢算法，涉及到中枢是否允许跨段
 
-## 取出缠论元素组织策略
+## 取出缠论元素
 - CChan这个类里面有个变量`kl_datas`，这是一个字典，键是 KL_TYPE（即级别，具体取值参见Common/CEnum），值是 CKLine_List 类；
 - CKLine_List是所有元素取值的入口，关键成员是：
   - lst: List[CKLine]：所有的合并K线
@@ -402,6 +465,10 @@ def draw_rsi(self, meta: CChanPlotMeta, ax, color='b'):
 
 
 ## 机器学习接入
+缠论有个好处在于，基础元素的定义大多非常精确，包括买卖点，很容易用程序化语言来实现；
+
+带来的好处就是，策略可以接入机器学习，让机器学习来判断当下状态，框架也可以较方便的接入这些能力；
+
 机器学习相关演示参见项目`machinelearning`分支[strategy_demo5.py](./Debug/strategy_demo5.py)，里面演示了包括：
 - 如何在bsp各个地方增加特征计算
 - 如何在bsp里面增加通用特征
@@ -411,6 +478,16 @@ def draw_rsi(self, meta: CChanPlotMeta, ax, color='b'):
 - 如何训练 & 预测
 
 
+## 一致性
+上面提到框架支持两种计算模式：
+- 直接给定一批K线，计算出所有缠论元素
+- 在已有（可以为空）K线基础上，逐根K线投喂更新得到“当下为止”的缠论元素
+
+两种方法实现上略有区别，前者计算速度快于后者；
+
+但是可以保证（或者说目标是要保证）：如果给定同样范围的K线，那么两种模式最终计算状态应该是完全一致的！（如果不一致，说明有bug，联系作者排查）
+
+
 ## 打赏
 如果你觉得这个项目对你有帮助或有启发，可以请我喝一杯。。额。。咖啡和牛奶以外的东西，毕竟我喝这两种会拉肚子。。