@dsh-ft/dsh-fft-plot 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +31 -8
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +18 -5
- package/skills/dsh-fft-plot/SKILL.md +167 -29
- package/skills/dsh-fft-plot/scripts/check_svg.py +131 -0
- package/skills/dsh-fft-plot/scripts/ftplot/canvas.py +136 -24
- package/skills/dsh-fft-plot/scripts/ftplot/charts.py +811 -103
- package/skills/dsh-fft-plot/scripts/ftplot/spec.py +2 -1
- package/skills/dsh-fft-plot/scripts/ftplot/theme.py +19 -1
- package/skills/dsh-fft-plot/scripts/plot.py +178 -79
- package/src/index.js +6 -4
package/README.md
CHANGED
|
@@ -11,17 +11,25 @@ SVG,图直接内联在对话里显示。
|
|
|
11
11
|
dsh-fft-plot/
|
|
12
12
|
├── src/index.js skill provider(纯 JS,无构建)
|
|
13
13
|
├── cordis.patch.yml 一行 insert
|
|
14
|
+
├── tests/
|
|
15
|
+
│ ├── fixtures/ 可重复渲染的 spec(含错误样例)
|
|
16
|
+
│ ├── plot.test.mjs 渲染/报错/哈希命名/check_svg 测试
|
|
17
|
+
│ └── generate-samples.mjs 把所有 fixture 渲染成 SVG 供人工查看
|
|
14
18
|
└── skills/dsh-fft-plot/
|
|
15
19
|
├── SKILL.md 给模型看:何时画、画哪种、字段怎么填
|
|
16
20
|
└── scripts/
|
|
17
|
-
├── plot.py CLI:spec(JSON) → SVG
|
|
21
|
+
├── plot.py CLI:spec(JSON) → SVG;--tokens 打配色/字号
|
|
22
|
+
├── check_svg.py 独立 SVG 校验
|
|
18
23
|
└── ftplot/
|
|
19
|
-
├── theme.py
|
|
24
|
+
├── theme.py 配色主题(含 6 色分类板、ashare)
|
|
20
25
|
├── canvas.py SVG 画布、坐标系、日期/数值格式
|
|
21
26
|
├── charts.py 图型注册表 @chart('名字')
|
|
22
27
|
└── spec.py spec 与数据加载
|
|
23
28
|
```
|
|
24
29
|
|
|
30
|
+
图型:`line`、`barh`、`table`(含 sparkline 列)、`heatmap`、`treemap`、`waterfall`、
|
|
31
|
+
`timeline`、`chain`。`chain` 是声明式产业链/传导链示意图,不消费数据行。
|
|
32
|
+
|
|
25
33
|
## 为什么不用 matplotlib
|
|
26
34
|
|
|
27
35
|
matplotlib 约 200MB,而 DSH 自带 Python 里没有它,装一个 skill 要拉这么大一坨不划算。
|
|
@@ -30,17 +38,19 @@ matplotlib 约 200MB,而 DSH 自带 Python 里没有它,装一个 skill 要
|
|
|
30
38
|
| | matplotlib | 本包 |
|
|
31
39
|
| --- | --- | --- |
|
|
32
40
|
| 依赖 | ~200MB | 0 |
|
|
33
|
-
| 单图体积 | 58KB | 3–20KB |
|
|
41
|
+
| 单图体积 | 58KB | 3–20KB(热力图约 50KB) |
|
|
34
42
|
| 文字 | 转成路径,不可搜索 | 真 `<text>`,可选中可搜索 |
|
|
35
43
|
|
|
36
|
-
代价是图元要自己维护(`canvas.py`
|
|
44
|
+
代价是图元要自己维护(`canvas.py` + `charts.py` 共约 2100 行),换来零依赖与样式完全可控。
|
|
37
45
|
|
|
38
46
|
## 加一种图
|
|
39
47
|
|
|
40
48
|
`charts.py` 里写一个函数加装饰器即可:
|
|
41
49
|
|
|
42
50
|
```python
|
|
43
|
-
@chart('curve')
|
|
51
|
+
@chart('curve') # 普通数据图
|
|
52
|
+
@chart('curve', x_axis=True) # 自己画横轴,plot.py 会预留高度
|
|
53
|
+
@chart('curve', needs_rows=False) # 示意图,spec 可以不写 rows
|
|
44
54
|
def curve(c, rect, cfg, rows):
|
|
45
55
|
"""期限结构曲线。字段:x, series"""
|
|
46
56
|
...
|
|
@@ -54,14 +64,27 @@ def curve(c, rect, cfg, rows):
|
|
|
54
64
|
## 本地验证
|
|
55
65
|
|
|
56
66
|
```bash
|
|
57
|
-
|
|
67
|
+
# 跑测试(渲染全部 fixture + 错误路径 + check_svg + 哈希命名)
|
|
68
|
+
pnpm test
|
|
69
|
+
|
|
70
|
+
# 把 fixture 渲染到 tests/tmp/samples/,用于人工看效果
|
|
71
|
+
pnpm samples
|
|
72
|
+
|
|
73
|
+
# 单张图
|
|
74
|
+
python3 skills/dsh-fft-plot/scripts/plot.py \
|
|
75
|
+
--spec tests/fixtures/heatmap.json --out-dir tests/tmp/samples --slug heatmap
|
|
58
76
|
```
|
|
59
77
|
|
|
60
78
|
产物是自包含 SVG(浅色底、无外链、无脚本),可直接写进 Markdown 图片语法。
|
|
79
|
+
`--out-dir` 按 spec + 数据内容哈希命名,同一张图重复生成会覆盖同一个文件;
|
|
80
|
+
需要具体色值/字号时用 `plot.py --tokens`。
|
|
61
81
|
|
|
62
|
-
##
|
|
82
|
+
## 三条设计约束
|
|
63
83
|
|
|
64
84
|
- **浅色底不透明**:SVG 作为 `<img>` 内联时是独立文档,读不到宿主的
|
|
65
85
|
`body[data-ds-dark-theme]`,深色模式下只有自带底色才不会黑底黑字。
|
|
66
|
-
-
|
|
86
|
+
- **先量后排**:头部、绘图区、说明、结论、页脚都先按画布宽度折行、算出真实高度,
|
|
87
|
+
再由 `plot.py` 倒推绘图区;图型通过 `x_axis` 元数据声明自己要不要横轴高度。
|
|
67
88
|
图型不得自己贴底边写字——那样必然和结论行重叠(已踩过)。
|
|
89
|
+
- **缺数据就失败**:NaN/Infinity、缺列、marks 指不到 x、示意图放不下都直接报错;
|
|
90
|
+
要表达“没有数据”的间隙,用 `null` 并在图型里显式支持。
|
package/locale/en.json
ADDED
package/locale/zh.json
ADDED
package/package.json
CHANGED
|
@@ -1,23 +1,37 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dsh-ft/dsh-fft-plot",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "FTShare data plotting for DeepSeek Harness: a bundled skill that renders query results into inline SVG charts with zero third-party dependencies.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"author": "Ben <ben@ft.tech>",
|
|
7
|
+
"homepage": "https://github.com/gigaflw/dsh-fft-base/tree/dev/packages/dsh-fft-plot#readme",
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "git+https://github.com/gigaflw/dsh-fft-base.git",
|
|
11
|
+
"directory": "packages/dsh-fft-plot"
|
|
12
|
+
},
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/gigaflw/dsh-fft-base/issues"
|
|
15
|
+
},
|
|
5
16
|
"type": "module",
|
|
6
17
|
"main": "src/index.js",
|
|
7
18
|
"exports": {
|
|
8
19
|
".": "./src/index.js",
|
|
9
20
|
"./cordis.patch.yml": "./cordis.patch.yml",
|
|
10
|
-
"./package.json": "./package.json"
|
|
21
|
+
"./package.json": "./package.json",
|
|
22
|
+
"./locale/*.json": "./locale/*.json"
|
|
11
23
|
},
|
|
12
24
|
"files": [
|
|
13
25
|
"src",
|
|
14
26
|
"skills",
|
|
15
27
|
"!skills/**/__pycache__",
|
|
28
|
+
"locale/*.json",
|
|
16
29
|
"cordis.patch.yml",
|
|
17
30
|
"README.md"
|
|
18
31
|
],
|
|
19
32
|
"scripts": {
|
|
20
|
-
"test": "node --test tests/*.test.mjs"
|
|
33
|
+
"test": "node --test tests/*.test.mjs",
|
|
34
|
+
"samples": "node tests/generate-samples.mjs"
|
|
21
35
|
},
|
|
22
36
|
"dsh": {
|
|
23
37
|
"bundle": {
|
|
@@ -29,6 +43,5 @@
|
|
|
29
43
|
},
|
|
30
44
|
"engines": {
|
|
31
45
|
"node": ">=22.19.0"
|
|
32
|
-
}
|
|
33
|
-
"license": "MIT"
|
|
46
|
+
}
|
|
34
47
|
}
|
|
@@ -1,41 +1,59 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: dsh-fft-plot
|
|
3
|
-
description: 把 FTShare 接口返回的数据渲染成图,图直接显示在聊天流里(内联 SVG
|
|
3
|
+
description: 把 FTShare 接口返回的数据渲染成图,图直接显示在聊天流里(内联 SVG,无需点开侧栏)。用于热榜、板块、资金流、估值、财报、宏观、指数等结果的趋势、排名、分布、对比,也支持热力图、构成图、瀑布图、事件时间轴与产业链示意图。用户要画图/出图/可视化时默认用本技能,直接在对话里出图。
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# dsh-fft-plot:数据 → 内联图
|
|
7
7
|
|
|
8
|
+
## 默认直接出图
|
|
9
|
+
|
|
10
|
+
用户要图时,默认直接在对话里出内联 SVG,不要打开侧栏,也不要先问“要不要出图”。
|
|
11
|
+
|
|
8
12
|
## 一句话流程
|
|
9
13
|
|
|
10
14
|
```
|
|
11
15
|
取到 rows(已经是扁平行数组)
|
|
12
16
|
→ 写一个 spec.json(选图型 + 映射列名)
|
|
13
|
-
→ plot.py --spec spec.json --out
|
|
14
|
-
→
|
|
17
|
+
→ plot.py --spec spec.json --out-dir "$(pwd)/.dsh/plots" --slug 图名
|
|
18
|
+
→ 把 stdout 打印的绝对路径写进 
|
|
15
19
|
```
|
|
16
20
|
|
|
21
|
+
`--out-dir` 会按 spec + 数据内容生成 `<slug>-<hash>.svg`:同一张图重复生成不会改名,
|
|
22
|
+
旧消息里的引用不会被后一次渲染覆盖。**产物路径以 stdout 为准**,不要自己猜文件名。
|
|
23
|
+
|
|
17
24
|
图会直接出现在聊天流中间。**不要**调用 `present`,也不要点开侧栏。
|
|
18
25
|
|
|
19
|
-
##
|
|
26
|
+
## 必守的八条
|
|
20
27
|
|
|
21
28
|
1. **产物路径必须是绝对路径**(`/` 开头)。Markdown 图片语法里的相对路径不会渲染。
|
|
22
29
|
2. **图直接内联,不要 present**。产物写进 ``,图会出现在回复中间;
|
|
23
30
|
不要调用 `present` 让用户另外点开侧栏——那多一次点击,而这里要的就是一眼看到。
|
|
24
31
|
3. **图前后要有文字**。图是论点的配图,不是答复本身——图前一句交代看什么,图后一句给结论。
|
|
25
|
-
|
|
32
|
+
但**不要在正文复述图上每个数字**,图已经显示了。
|
|
33
|
+
4. **同一回复不要重复画同一张图**。要改就重新生成一张并替换引用,不要叠加两张近似图。
|
|
34
|
+
5. **不适用的情形不画**:数据为空、只有一条记录、纯名录字段、或用户只要一个数字。
|
|
26
35
|
这时直接说结论,不要为了出图而出图。
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
36
|
+
6. **不编造数字**。图上每个数字都必须来自 `rows`。
|
|
37
|
+
7. **产物必须是带完整根属性的独立 SVG**:`xmlns`、`width`、`height`、`viewBox` 四者齐全。
|
|
38
|
+
`viewBox` 只定义坐标系,**不提供内在尺寸**;缺 `width`/`height` 时,`` 在多数
|
|
39
|
+
Markdown 渲染器里会塌成 0 高——对方只看到空白,而你自己用浏览器直接打开文件却是正常的,
|
|
40
|
+
所以这个错误**自测发现不了**。`plot.py` 会自动写全这四个属性;手写或二次加工 SVG 时
|
|
41
|
+
必须自己补,并且跑一次 `scripts/check_svg.py`。
|
|
42
|
+
8. **不要为了验证或显示把 SVG 转成 PNG**。`qlmanage`、`sips`、浏览器截图都不是必需步骤:
|
|
43
|
+
图由 Markdown 直接内联,渲染器会显示 SVG。需要校验产物时只用 `scripts/check_svg.py`;
|
|
44
|
+
不要启动系统看图/转换服务,也不要把临时 PNG 当成交付物。
|
|
45
|
+
|
|
46
|
+
## 四步
|
|
30
47
|
|
|
31
48
|
### 1. 判断该不该画
|
|
32
49
|
|
|
33
50
|
| 该画 | 不该画 |
|
|
34
51
|
|---|---|
|
|
35
52
|
| 有时间趋势(净值、热度、估值序列、宏观) | 纯名录/字典(基金列表、成分股清单) |
|
|
36
|
-
| 有横截面排名(热榜、板块涨幅、龙虎榜) | 只有 1
|
|
37
|
-
|
|
|
38
|
-
|
|
|
53
|
+
| 有横截面排名(热榜、板块涨幅、龙虎榜) | 只有 1 条记录 |
|
|
54
|
+
| 有多项构成/拆解(市值构成、资金流拆解) | 字段含义不明(不知道单位是元还是万元) |
|
|
55
|
+
| 有事件驱动的时点(政策、公告、数据) | 用户只要一个数字或一句话结论 |
|
|
56
|
+
| 用户明确说画图 | |
|
|
39
57
|
|
|
40
58
|
### 2. 选图型
|
|
41
59
|
|
|
@@ -43,15 +61,34 @@ description: 把 FTShare 接口返回的数据渲染成图,图直接显示在
|
|
|
43
61
|
|---|---|---|
|
|
44
62
|
| `line` | 时序趋势:热度衰减、净值曲线、估值分位、宏观指标 | `x`、`series` |
|
|
45
63
|
| `barh` | 横截面排名:热榜、板块涨幅、个股贡献 | `label`、`value` |
|
|
46
|
-
| `table` |
|
|
64
|
+
| `table` | 名录类数据,或作为图的补充(可带 sparkline 列) | `columns` |
|
|
65
|
+
| `heatmap` | 相关性矩阵、板块×时间热力、事件日历 | `x`、`y`、`value` |
|
|
66
|
+
| `treemap` | 市值/权重/板块构成,面积即占比 | `label`、`value`(必须为正) |
|
|
67
|
+
| `waterfall` | 资金流、营收/利润的逐项拆解与合计 | `label`、`value` |
|
|
68
|
+
| `timeline` | 政策/公告/数据等事件时点 | `x`、`label` |
|
|
69
|
+
| `chain` | 产业链、传导链等声明式分层示意图 | `layers`(+ `edges`) |
|
|
47
70
|
|
|
48
71
|
### 3. 写 spec 并渲染
|
|
49
72
|
|
|
50
73
|
```bash
|
|
51
|
-
python3 <skill目录>/scripts/plot.py --spec /abs/spec.json --out /
|
|
74
|
+
python3 <skill目录>/scripts/plot.py --spec /abs/spec.json --out-dir "$(pwd)/.dsh/plots" --slug 热榜
|
|
52
75
|
```
|
|
53
76
|
|
|
54
77
|
spec 是 **JSON**(不是 YAML)。数据少就内联 `rows`,多就写 `data` 指向 json 文件。
|
|
78
|
+
`chain` 不需要数据行,可以不写 `rows`/`data`。
|
|
79
|
+
|
|
80
|
+
需要具体色值/字号时先跑 `plot.py --tokens`(可加 `--theme ashare`),
|
|
81
|
+
打印当前主题的配色、分类色、字号与版心尺寸;**不要凭记忆写颜色**。
|
|
82
|
+
|
|
83
|
+
### 4. 校验产物
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
python3 <skill目录>/scripts/check_svg.py /abs/输出.svg
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
必须 PASS。它查:根元素四个属性是否齐全且为正、`viewBox` 与 `width`/`height` 宽高比是否一致、
|
|
90
|
+
是否为合法 XML、是否含 NaN/Infinity、是否含 `<script>`/内联事件/`<foreignObject>`/外部引用。
|
|
91
|
+
体积超过 200KB 会给告警。
|
|
55
92
|
|
|
56
93
|
## spec 结构
|
|
57
94
|
|
|
@@ -61,7 +98,7 @@ spec 是 **JSON**(不是 YAML)。数据少就内联 `rows`,多就写 `data
|
|
|
61
98
|
"width": 1200,
|
|
62
99
|
"height": 560,
|
|
63
100
|
"data": "rows.json",
|
|
64
|
-
"chart": { "type": "barh", "...": "
|
|
101
|
+
"chart": { "type": "barh", "...": "见下文" },
|
|
65
102
|
"legend": "条形长度=热度值;颜色=当日涨跌(红涨蓝跌)",
|
|
66
103
|
"notes": ["**主结论一行", "!强调色结论", "*小字口径说明"],
|
|
67
104
|
"sources": ["ft_v1_ths_hot_list"],
|
|
@@ -70,7 +107,7 @@ spec 是 **JSON**(不是 YAML)。数据少就内联 `rows`,多就写 `data
|
|
|
70
107
|
```
|
|
71
108
|
|
|
72
109
|
**页头全部可选**(`chip` / `title` / `subtitle`)。图在聊天流中间时,前后已有文字说明,
|
|
73
|
-
|
|
110
|
+
**默认不写标题**,绘图区会占满。`legend`/`notes`/`sources`/`sample` 会自动按画布宽度折行。
|
|
74
111
|
|
|
75
112
|
`notes` 前缀:`**` 加粗主结论、`!` 红字强调、`*` 小字注释、无前缀为普通灰字。
|
|
76
113
|
|
|
@@ -89,13 +126,18 @@ spec 是 **JSON**(不是 YAML)。数据少就内联 `rows`,多就写 `data
|
|
|
89
126
|
"y_fmt":"num","y_dec":0}
|
|
90
127
|
```
|
|
91
128
|
|
|
92
|
-
- `x_kind`:**日期列必须写 `"category"`**。日期若写成 `20260810`
|
|
129
|
+
- `x_kind`:**日期列必须写 `"category"`**。日期若写成 `20260810` 这类可解析整数,
|
|
93
130
|
按数值画会导致交易日间距忽宽忽窄(跨周末的间隔是 3 而不是 1)。
|
|
94
131
|
纯数值轴(天数、比率)才用 `"auto"`。
|
|
95
|
-
- `series[].color`:主题键 `up`/`down`/`neutral`/`accent`/`band`,或 `#RRGGBB
|
|
132
|
+
- `series[].color`:主题键 `up`/`down`/`neutral`/`accent`/`band`,或 `#RRGGBB`;
|
|
133
|
+
多序列不写 color 时按主题的 6 色分类板自动分配。
|
|
134
|
+
- `series`/`band` 的值允许 `null`:该点画成断开的间隙,不会连成假线。
|
|
135
|
+
- `include_zero`:**默认 false**。价格、指数、净值这类不应从 0 起画;
|
|
136
|
+
数量/资金/占比类图才显式写 `"include_zero": true`。
|
|
137
|
+
- `y_fmt`:`num` / `pct` / `compact`;`y_dec` 不够时会按刻度步长自动补足小数位。
|
|
96
138
|
- `band`:分布带,用于给出离散度而不是只有均值。
|
|
97
139
|
- `refs`:参考线(50%、0、基准值)。
|
|
98
|
-
- `marks`:要打点的 x
|
|
140
|
+
- `marks`:要打点的 x 值,会标出数值;**写了一个数据里不存在的 x 会直接报错**。
|
|
99
141
|
|
|
100
142
|
### barh
|
|
101
143
|
|
|
@@ -104,9 +146,10 @@ spec 是 **JSON**(不是 YAML)。数据少就内联 `rows`,多就写 `data
|
|
|
104
146
|
"rank":"rank","top":10,"fmt":"compact","dec":1}
|
|
105
147
|
```
|
|
106
148
|
|
|
107
|
-
- `sign
|
|
149
|
+
- `sign`:决定颜色的列(红色=正、蓝色=负;没有 sign 时整组同色)。
|
|
150
|
+
- 有负值时条形以 0 为基线向两侧展开;放不下时自动截断并在图内写“共 N 条,显示前 k 条”。
|
|
108
151
|
- `fmt`:`compact`(524.9万,**推荐**)、`num`(5,248,899)、`pct`(+4.2%)。
|
|
109
|
-
用 `compact`
|
|
152
|
+
用 `compact` 时把单位写进数值,就不必再单独加一行“单位是…”的说明。
|
|
110
153
|
|
|
111
154
|
### table
|
|
112
155
|
|
|
@@ -115,10 +158,73 @@ spec 是 **JSON**(不是 YAML)。数据少就内联 `rows`,多就写 `data
|
|
|
115
158
|
"columns":[
|
|
116
159
|
{"col":"rank","label":"名次","weight":0.5,"align":"right"},
|
|
117
160
|
{"col":"name","label":"名称","weight":1.1},
|
|
118
|
-
{"col":"hotValue","label":"热度值","weight":1.0,"align":"right","dec":0}
|
|
161
|
+
{"col":"hotValue","label":"热度值","weight":1.0,"align":"right","fmt":"compact","dec":0},
|
|
162
|
+
{"col":"trend","label":"近 5 日","type":"sparkline","weight":1.0}]}
|
|
119
163
|
```
|
|
120
164
|
|
|
121
|
-
- `weight`:列宽比例;`align`:`left`/`right`;`dec
|
|
165
|
+
- `weight`:列宽比例;`align`:`left`/`right`;`dec`:小数位;`fmt`:`num`/`pct`/`compact`。
|
|
166
|
+
- `type: "sparkline"` 的列,值必须是数字数组(如 `[1,2,1.5,3]`),画迷你走势线。
|
|
167
|
+
- 行数放不下时自动截断并写“共 N 条,显示前 k 条”;缺列会直接报错,不静默写 `—`。
|
|
168
|
+
|
|
169
|
+
### heatmap
|
|
170
|
+
|
|
171
|
+
```json
|
|
172
|
+
{"type":"heatmap","x":"trade_date","y":"name","value":"pct",
|
|
173
|
+
"fmt":"pct","dec":1,"show_value":true,"diverging":true,"top":20}
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
- 行是 `y` 的取值、列是 `x` 的取值,按行序/首次出现顺序排列;同一格重复取最后一行。
|
|
177
|
+
- `diverging` 默认按数据正负自动判断:红=正、蓝=负;全正/全负时用单色深浅。
|
|
178
|
+
- `show_value` 在格子里写数值;格子太小时不写。
|
|
179
|
+
- 行数按高度放不下会直接报错(提示调大 height、调小 top 或改用 table)。
|
|
180
|
+
|
|
181
|
+
### treemap
|
|
182
|
+
|
|
183
|
+
```json
|
|
184
|
+
{"type":"treemap","label":"name","value":"mktcap","group":"sector","fmt":"num","dec":0}
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
- 面积=数值;`group` 决定颜色(同一分组同色),不写则按顺序取分类色。
|
|
188
|
+
- 值必须为正数;块太小时只画色块不写标签。
|
|
189
|
+
- 数据单位不是元时用 `fmt: "num"`,把单位(亿元/万元)写进 `legend`,不要用 compact 误缩放。
|
|
190
|
+
|
|
191
|
+
### waterfall
|
|
192
|
+
|
|
193
|
+
```json
|
|
194
|
+
{"type":"waterfall","label":"item","value":"amount","fmt":"num","dec":1,
|
|
195
|
+
"type_col":"type","sort":false}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
- 每行是一个增量,从前一根终点起画;正增量红、负增量蓝。
|
|
199
|
+
- `type_col` 指向的列值为 `total`/`合计`/`汇总` 时,该行从 0 起画整根(用于合计)。
|
|
200
|
+
- 默认不排序(保持业务顺序);`sort: true` 按数值重排。
|
|
201
|
+
|
|
202
|
+
### timeline
|
|
203
|
+
|
|
204
|
+
```json
|
|
205
|
+
{"type":"timeline","x":"date","label":"event","sign":"impact","detail":"detail"}
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
- 按日期定位事件点;日期无法全部识别时保留行序。x 轴标签自动收敛与抽稀。
|
|
209
|
+
- `sign` 正负决定颜色(红=利多、蓝=利空);不给则用 `color`(默认 accent)。
|
|
210
|
+
- `detail` 是可选的事件说明小字。
|
|
211
|
+
- 事件标签最多三层交错;仍放不下的会省略,并在图内写明“N 个标签过密未显示”。
|
|
212
|
+
|
|
213
|
+
### chain
|
|
214
|
+
|
|
215
|
+
```json
|
|
216
|
+
{"type":"chain",
|
|
217
|
+
"layers":[{"name":"上游","nodes":["锂矿","正极材料"]},
|
|
218
|
+
{"name":"中游","nodes":["动力电池"]},
|
|
219
|
+
{"name":"下游","nodes":["新能源车","储能"]}],
|
|
220
|
+
"edges":[["锂矿","正极材料"],["正极材料","动力电池"],["动力电池","新能源车"]],
|
|
221
|
+
"highlight":["动力电池"]}
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
- 节点名同时是边的引用 id,必须全局唯一;`layers` 从左到右,层名可选。
|
|
225
|
+
- 边只能从靠前层指向靠后层,或同层节点之间(同层画竖箭头);反向边直接报错。
|
|
226
|
+
- `highlight` 的节点用强调色描边;放不下会先缩字号、再报错,不会画出压字的图。
|
|
227
|
+
- 更自由的架构图/泳道图用下面的“手写 SVG”。
|
|
122
228
|
|
|
123
229
|
## 数据形状的坑
|
|
124
230
|
|
|
@@ -126,19 +232,51 @@ spec 是 **JSON**(不是 YAML)。数据少就内联 `rows`,多就写 `data
|
|
|
126
232
|
|
|
127
233
|
- **比率二义**:`turnover_rate=0.0123` 是小数,`riseAndFall=15.07` 是百分数。
|
|
128
234
|
图上的 `y_fmt: "pct"` 只负责加 `%`,**不负责乘 100**——先看清原始量纲。
|
|
129
|
-
-
|
|
130
|
-
`2026
|
|
131
|
-
- **列集可能随行变化**:`y_30y`
|
|
235
|
+
- **时间有五种写法**:毫秒/秒/纳秒时间戳、`20260810`、`2026-08-10`、`2026-09-30 00:00:00`、
|
|
236
|
+
`2026年09月份`;`plot.py` 统一按上海时区解析,认不出的日期原样当标签。
|
|
237
|
+
- **列集可能随行变化**:`y_30y` 这类列只在部分行出现。数值列缺键或出现 `NaN/Infinity`
|
|
238
|
+
会直接报错(不会静默丢行);要表示“没有数据”的间隙,用 JSON `null`(仅 line 的 series/band 支持)。
|
|
132
239
|
- **分页**:很多接口默认只返回第一页。横截面分布用第一页画会系统性失真,
|
|
133
240
|
要么按全量取,要么在图里写明样本范围。
|
|
134
241
|
|
|
135
242
|
## 配色
|
|
136
243
|
|
|
137
|
-
`paper`(米白+朱红墨蓝,默认)、`
|
|
244
|
+
`paper`(米白+朱红墨蓝,默认)、`ashare`(米白+红涨绿跌,给 A 股读者看涨跌时用)、
|
|
245
|
+
`poster`(纯白+亮橙)、`slate`(冷灰+青红)。
|
|
138
246
|
所有主题都是浅色底:SVG 内联进聊天时读不到宿主的深色模式,浅色底保证永不错色。
|
|
247
|
+
具体色值/分类色/字号用 `plot.py --tokens` 取,不凭记忆写。
|
|
248
|
+
|
|
249
|
+
## 手写 SVG:允许,但必须补齐根属性
|
|
250
|
+
|
|
251
|
+
`plot.py` 覆盖不到的复合图——双 panel 对照、自定义标注层、非链式的架构/泳道图——
|
|
252
|
+
可以直接生成 SVG。根元素必须是:
|
|
253
|
+
|
|
254
|
+
```
|
|
255
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="960" height="540"
|
|
256
|
+
viewBox="0 0 960 540" role="img" aria-label="一句话把这张图读出来">
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
- **四个属性一个都不能少**:缺 `xmlns` → 独立文档解析失败;缺 `width`/`height` →
|
|
260
|
+
作为 `<img>` 引用塌成空白。两种症状不同,都只能靠校验抓。
|
|
261
|
+
- `width`/`height` 用纯数字,且与 `viewBox` 同比例,否则 `<img>` 里会被拉伸。
|
|
262
|
+
- 自绘也要用浅色底打底(`<rect fill>`),颜色用 `--tokens` 里的语义键值,不写随机色。
|
|
263
|
+
- 生成后**必须**过 `check_svg.py`;不要用“浏览器打开看着正常”代替校验。
|
|
264
|
+
- 图上每个数字同样受第 6 条约束:来自数据,不来自手写常量。
|
|
265
|
+
|
|
266
|
+
### 示意图几何速查
|
|
267
|
+
|
|
268
|
+
- 画布四边至少留 `24px`;节点圆角 `rx≈10`、描边 `1.25–1.5`。
|
|
269
|
+
- 节点宽度:ASCII 约 `字数×9+36`,中文约 `字数×15+36`;单行高 `≥44`,标题+副标题 `≥64`。
|
|
270
|
+
- 有连接的层之间至少留 `48px` 走线;连线绕开节点,标签压在线上时给文字加一块浅色底衬。
|
|
271
|
+
- 箭头用 `<marker>` 定义一次,`refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse"`。
|
|
272
|
+
- 泳道/分组用 `fill` 浅底 + 虚线描边 + 左上角 12px 分组名,不要用纯色块压过节点。
|
|
139
273
|
|
|
140
274
|
## 新增图型
|
|
141
275
|
|
|
142
|
-
`scripts/ftplot/charts.py`
|
|
143
|
-
|
|
144
|
-
|
|
276
|
+
`scripts/ftplot/charts.py` 里写一个函数并加装饰器,签名固定 `(c, rect, cfg, rows)`:
|
|
277
|
+
|
|
278
|
+
- `@chart('名字')`:普通数据图;
|
|
279
|
+
- `@chart('名字', x_axis=True)`:图型自己画横轴标签,`plot.py` 会自动预留横轴高度;
|
|
280
|
+
- `@chart('名字', needs_rows=False)`:示意图类,spec 可以不写 `rows`/`data`。
|
|
281
|
+
|
|
282
|
+
然后在本文的图型表里补一行字段说明。**不需要**改 `plot.py` 或任何布局代码。
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
# -*- coding: utf-8 -*-
|
|
3
|
+
"""校验独立 SVG 产物能否被 <img> 正确渲染。
|
|
4
|
+
|
|
5
|
+
背景:`viewBox` 只定义坐标系,不提供内在尺寸。HTML 里用
|
|
6
|
+
`<img src="chart.svg">` 引用时,浏览器按 SVG 的 width/height 决定布局盒子;
|
|
7
|
+
两者都缺失时会塌成 0 高 —— 表现就是「图发出去,对方只看到空白」。
|
|
8
|
+
同一份 SVG 直接拖进浏览器却能显示(独立文档模式按视口铺满),所以这个错误
|
|
9
|
+
在本地自测时**看不出来**,只能靠校验。
|
|
10
|
+
|
|
11
|
+
用法:
|
|
12
|
+
python3 check_svg.py chart.svg [chart2.svg ...]
|
|
13
|
+
python3 check_svg.py --quiet chart.svg # 只报失败
|
|
14
|
+
|
|
15
|
+
退出码:全部通过 0,有任一失败 1,无参数 2。
|
|
16
|
+
"""
|
|
17
|
+
import re
|
|
18
|
+
import sys
|
|
19
|
+
import xml.etree.ElementTree as ET
|
|
20
|
+
|
|
21
|
+
REQUIRED = ('xmlns', 'width', 'height', 'viewBox')
|
|
22
|
+
EXPECT_XMLNS = 'http://www.w3.org/2000/svg'
|
|
23
|
+
SIZE_WARN_BYTES = 200 * 1024
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def root_tag(src):
|
|
27
|
+
m = re.search(r'<svg\b[^>]*>', src[:4096])
|
|
28
|
+
return m.group(0) if m else None
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def attr(tag, name):
|
|
32
|
+
m = re.search(rf'\b{name}\s*=\s*"([^"]*)"', tag)
|
|
33
|
+
return m.group(1) if m else None
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def check(path):
|
|
37
|
+
"""返回 (ok, [问题描述], [告警描述])"""
|
|
38
|
+
problems, warnings = [], []
|
|
39
|
+
try:
|
|
40
|
+
with open(path, encoding='utf-8') as handle:
|
|
41
|
+
src = handle.read()
|
|
42
|
+
except OSError as e:
|
|
43
|
+
return False, [f'读不到文件:{e}'], []
|
|
44
|
+
|
|
45
|
+
tag = root_tag(src)
|
|
46
|
+
if tag is None:
|
|
47
|
+
return False, ['找不到 <svg> 根元素(文件可能不是 SVG,或为空)'], []
|
|
48
|
+
|
|
49
|
+
for name in REQUIRED:
|
|
50
|
+
val = attr(tag, name)
|
|
51
|
+
if val is None:
|
|
52
|
+
problems.append(f'根元素缺 {name}')
|
|
53
|
+
continue
|
|
54
|
+
if name in ('width', 'height'):
|
|
55
|
+
if not re.fullmatch(r'\d+(\.\d+)?', val):
|
|
56
|
+
problems.append(f'{name} 必须是纯数字像素值,实际是 "{val}"')
|
|
57
|
+
elif float(val) <= 0:
|
|
58
|
+
problems.append(f'{name} 必须为正,实际是 {val}')
|
|
59
|
+
|
|
60
|
+
ns = attr(tag, 'xmlns')
|
|
61
|
+
if ns is not None and ns != EXPECT_XMLNS:
|
|
62
|
+
problems.append(f'xmlns 应为 {EXPECT_XMLNS},实际 {ns}')
|
|
63
|
+
|
|
64
|
+
vb, w, h = attr(tag, 'viewBox'), attr(tag, 'width'), attr(tag, 'height')
|
|
65
|
+
if vb and w and h:
|
|
66
|
+
try:
|
|
67
|
+
_, _, vw, vh = [float(x) for x in re.split(r'[\s,]+', vb.strip())]
|
|
68
|
+
if vw > 0 and vh > 0 and abs(vw / vh - float(w) / float(h)) > 0.01:
|
|
69
|
+
problems.append(
|
|
70
|
+
f'viewBox 宽高比 {vw/vh:.3f} 与 width/height 比 {float(w)/float(h):.3f} 不一致,'
|
|
71
|
+
f'<img> 里会变形')
|
|
72
|
+
except ValueError:
|
|
73
|
+
problems.append(f'viewBox 无法解析:"{vb}"')
|
|
74
|
+
|
|
75
|
+
# 整份文件必须是合法 XML:控制字符、未闭合标签都只能靠解析抓,
|
|
76
|
+
# 浏览器打开时可能只是渲染异常,不会报错。
|
|
77
|
+
try:
|
|
78
|
+
ET.fromstring(src)
|
|
79
|
+
except ET.ParseError as exc:
|
|
80
|
+
problems.append(f'不是合法 XML:{exc}')
|
|
81
|
+
|
|
82
|
+
# 非有限坐标会让路径直接消失(NaN/Infinity 不是合法 SVG 数值)。
|
|
83
|
+
if re.search(r'(?i)(?<![\w-])(nan|infinity|inf)(?![\w-])', src):
|
|
84
|
+
problems.append('含 NaN/Infinity 或非有限坐标')
|
|
85
|
+
|
|
86
|
+
# 脚本与内联事件:自包含图片不允许(离线渲染会静默失败,也有注入风险)。
|
|
87
|
+
if re.search(r'<script\b', src, re.I):
|
|
88
|
+
problems.append('含 <script>')
|
|
89
|
+
if re.search(r'\son[a-z]+\s*=', src, re.I):
|
|
90
|
+
problems.append('含内联事件属性(on*)')
|
|
91
|
+
if re.search(r'<foreignObject\b', src, re.I):
|
|
92
|
+
problems.append('含 <foreignObject>(独立图片里不可靠)')
|
|
93
|
+
|
|
94
|
+
body = src[len(tag):] if tag else src
|
|
95
|
+
ext = [u for u in re.findall(r'(?:href|src|xlink:href)\s*=\s*"(?!#)([^"]+)"', body)
|
|
96
|
+
if u.startswith(('http://', 'https://', '//'))]
|
|
97
|
+
if ext:
|
|
98
|
+
problems.append(f'含外部引用(离线会加载失败):{ext[:3]}')
|
|
99
|
+
|
|
100
|
+
if len(src.encode('utf-8')) > SIZE_WARN_BYTES:
|
|
101
|
+
warnings.append(f'体积 {len(src.encode("utf-8")) / 1024:.0f}KB 偏大(> {SIZE_WARN_BYTES // 1024}KB)')
|
|
102
|
+
|
|
103
|
+
return (not problems), problems, warnings
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def main(argv):
|
|
107
|
+
quiet = '--quiet' in argv
|
|
108
|
+
files = [a for a in argv[1:] if not a.startswith('--')]
|
|
109
|
+
if not files:
|
|
110
|
+
print('用法:python3 check_svg.py chart.svg [chart2.svg ...]')
|
|
111
|
+
return 2
|
|
112
|
+
|
|
113
|
+
failed = 0
|
|
114
|
+
for f in files:
|
|
115
|
+
ok, problems, warnings = check(f)
|
|
116
|
+
if ok:
|
|
117
|
+
if not quiet:
|
|
118
|
+
print(f' OK {f}')
|
|
119
|
+
for warning in warnings:
|
|
120
|
+
print(f' ~ {warning}')
|
|
121
|
+
else:
|
|
122
|
+
failed += 1
|
|
123
|
+
print(f' FAIL {f}')
|
|
124
|
+
for problem in problems:
|
|
125
|
+
print(f' - {problem}')
|
|
126
|
+
print(f'\n{"PASS" if not failed else "FAIL"} ({len(files)-failed}/{len(files)})')
|
|
127
|
+
return 0 if not failed else 1
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
if __name__ == '__main__':
|
|
131
|
+
sys.exit(main(sys.argv))
|