docs: add text knowledge (#23)

knowledges/数据文本 - Vis Text.md

@@ -0,0 +1,83 @@
+## 图表属性
+
+- 名称：数据文本
+- 别名：解读文本，英文名 Text
+- 图表功能：数据解读，数据描述
+
+## 基础概念
+
+在数据分析全流程展示上，除了可视化图表外，通过文本描述数据现象、给出洞察结论辅助分析，也十分重要。
+然而，数据文本的表单有以下难点：
+
+1. 信息密度大：相较于图和表，文字在单位面积内的可描述的数据信息更多，通常一段文字就可能是 4-5 张可视化图表的内容；
+2. 内容依赖自动化生成：随着数据分析平民化以及 NLP 技术的成熟，越来越多的洞察结论将由机器自动生成；
+3. 基于文本继续分析：从看数到分析，不管在探索分析应用还是交互式分析报表中，都需要基于分析结果展示进行二次分析做相关交互如筛选、下钻、上卷等，而文本作为分析结果重要的形式也是需要交互辅助分析能力的。
+
+## 适用场景
+
+1. 提高可读性：通过使用可视化映射原理对数据元素做标记，帮助用户快速识别关键信息；通过增加行内小图，在感性层面提高用户对数据的感知；
+2. 结构标准化定义：面向 LLM 生成 markdown 扩展协议文本内容，可以实现结构标准化定义；
+3. 交互与自定义扩展：解读文本是含有数据绑定信息的，特别是短语作为数据元信息绑定的基础单元可以作为分析交互等触发控件，如基于日期描述做日期切换、基于拆分维度做维值切换等，可以通过自定义扩展实现。
+
+## 不适用场景
+
+暂无
+
+## 图表用法
+
+### markdown 扩展协议与自定义标签属性
+
+```markdown
+<vis-text type={type}>{children}</vis-text>
+```
+
+```typescript
+type Text = {
+  type?: string;
+  children: string;
+  origin?: any;
+};
+```
+
+### 数据要求
+
+<!-- 以下参考了中文语法结构给出实体识别描述：
+1. **主语**：是句子中执行动作或被描述的人或事物。一句话中，通常位于句首，用来说明“谁”或“什么”。例如，在句子“小明吃了苹果。”中，“小明”就是主语。
+2. **谓语**：是用来说明主语所做的动作或状态的词组，通常是动词或形容词等。在上面的例子“小明吃了苹果。”中，“吃了”就是谓语，表示了主语的行为。
+3. **宾语**：是指动作的对象或者是受到动作影响的人或事物。它通常跟在谓语后面，回答“谁”或“什么”的问题。还是以“小明吃了苹果。”为例，“苹果”就是宾语，表示了动作“吃”的对象。
+4. **定语**：是用来修饰名词或者代词，提供关于该名词或代词的信息的部分。它可以出现在所修饰词语之前也可以之后（使用“的”字连接）。比如，“红色的书包”，这里的“红色”就是定语，用来修饰“书包”。
+5. **状语**：是用来修饰动词、形容词或其他副词的成分，用来说明行为发生的方式、时间、地点、原因等。例如，“他快速地跑着。”这句话里，“快速地”作为状语修饰了动词“跑”，表达了跑步的速度。
+6. **补语**：是对谓语进行补充说明的部分，可以进一步说明动作的结果、程度等。补语往往放在谓语之后，并且经常通过特定的结构来表达，如“得+形容词/副词”。例如，“他高兴得很。”这里“得很”就构成了一个结果补语，强调了“高兴”的程度。 -->
+
+- type: 短语实体类型，现在内置的有：
+  1. **metric_name**: 指标名称，通常是句子的主语，数据分析中主指标的名称，例如：“单价”，“DAU”,"交易量"，“毛利率”等；
+  2. **dim_name**: 维度名称，通常是句子的主语或者宾语，表达数据分析中可以拆分下钻的维度，例如：“省份”，“城市”，“年龄”，“性别”等；
+  3. **dim_value**: 维度值，通常是句子的主语、宾语或者定语，例如：“北京”，“女性”，“中年”，“支付宝”等；
+  4. **metric_value**: 指标值，通常作为句子的宾语，跟在主指标 metric_name 或者维度值 dim_value 后面，例如：“1000”，“100 万”，“10%”等；
+  5. **time_desc**: 时间描述，通常在句子的最开始，限定数据结论的日期范围，比如"2022 年"，"去年"，"12 点 03 分"，"2023-01-23"等；
+  6. **trend_desc**: 趋势描述，通常作为句子的宾语，在主指标 metric_name 后面，例如："上涨", "下跌","下降"等；
+  7. **delta_value**: 变化差值，一种特殊的指标值，用于描述对比差值 a-b，如上涨 3000，此时 3000 属于变化差值。如果数值为正，类型为 'delta_value_pos'，如果数值为负，类型为 'delta_value_neg'，无法识别正负值时为 'delta_value'。同时文本内容（children）需要进行 abs 处理为绝对值；
+  8. **ratio_value**: 比率值，类似 delta_value，一种特殊的指标值，用于描述对比率 (a-b)/b，如上涨 30%，此时 30% 属于变化率。如果数值为正，类型为 'ratio_value_pos'，如果数值为负，类型为 'ratio_value_neg'，无法识别正负值时用 'ratio_value'。同时文本内容（children）需要进行 abs 处理为绝对值；
+  9. **proportion**: 占比，也是一种特殊的指标值，表示该指标占总体的比例，通常为百分比数值，跟在“占比”等语义后面的指标，例如："22%"；
+- children: 文本内容，必须是字符串类型；
+- origin: 可选，可以是任意类型，用于存储原始数据，比如未经格式化的指标值、占比、趋势详情等，如 1789.23, 0.34, [1, 2, 6, 18, 24, 48] 等；
+
+## 使用示例
+
+1. 原文“2023 年 1 月 1 日，支付宝交易量为 100 万，环比上涨 3000，同比去年上涨 10%”，通过文本实体识别增强，输出增强 markdown 内容为：
+
+```markdown
+<vis-text type="time_desc">2023 年 1 月 1 日</vis-text>，<vis-text type="metric_name">支付宝交易量</vis-text>为<vis-text type="metric_value">100 万</vis-text>，环比上涨<vis-text type="delta_value_pos">3000<vis-text>，同比去年上涨<vis-text type="radio_value_pos">10%<vis-text>
+```
+
+2. 原文“支付宝交易量占整体交易量的 22%，其中北京占比 10%，上海占比 20%”，通过文本实体识别增强，输出增强 markdown 内容为：
+
+```markdown
+<vis-text type="metric_name">支付宝交易量</vis-text>占整体交易量的<vis-text type="proportion">22%</vis-text>，其中<vis-text type="dim_name">北京</vis-text>占比<vis-text type="proportion">10%</vis-text>，<vis-text type="dim_name">上海</vis-text>占比<vis-text type="proportion">20%</vis-text>
+```
+
+3. 原文“基于 PROPHET 算法预测，未来预计截止至 2024-10-16，所有客户性别求除法的预测值处于平稳趋势，分别是：男-预测值为 374.12%，女-预测值为 367.33%”，通过文本实体识别增强，输出增强 markdown 内容为：
+
+```markdown
+基于 PROPHET 算法预测，未来预计截止至<vis-text type='time_desc'>2024-10-16</vis-text>，所有客户性别<vis-text type='metric_name'>求除法</vis-text>的预测值<vis-text type='trend_desc'>处于平稳趋势</vis-text>，分别是：<vis-text type='dim_value'>男</vis-text>-预测值为<vis-text type='metric_value' origin='3.7412'>374.12%</vis-text>，<vis-text type='dim_value'>女</vis-text>-预测值为<vis-text type='metric_value' origin='3.6733'>367.33%</vis-text>。
+```