@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 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` 283 行 + `charts.py` 454 行),换来零依赖与样式完全可控。
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
- python3 skills/dsh-fft-plot/scripts/plot.py --spec spec.json --out /abs/chart.svg
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
- - **布局单游标**:头部、绘图区、说明、结论、页脚全部由 `plot.py` 一个游标顺序排,
86
+ - **先量后排**:头部、绘图区、说明、结论、页脚都先按画布宽度折行、算出真实高度,
87
+ 再由 `plot.py` 倒推绘图区;图型通过 `x_axis` 元数据声明自己要不要横轴高度。
67
88
  图型不得自己贴底边写字——那样必然和结论行重叠(已踩过)。
89
+ - **缺数据就失败**:NaN/Infinity、缺列、marks 指不到 x、示意图放不下都直接报错;
90
+ 要表达“没有数据”的间隙,用 `null` 并在图型里显式支持。
package/locale/en.json ADDED
@@ -0,0 +1,6 @@
1
+ {
2
+ "meta": {
3
+ "title": "FT Plot",
4
+ "description": "Render FTShare query results as inline SVG charts."
5
+ }
6
+ }
package/locale/zh.json ADDED
@@ -0,0 +1,6 @@
1
+ {
2
+ "meta": {
3
+ "title": "FT 绘图",
4
+ "description": "把 FTShare 取数结果画成内联 SVG 图表。"
5
+ }
6
+ }
package/package.json CHANGED
@@ -1,23 +1,37 @@
1
1
  {
2
2
  "name": "@dsh-ft/dsh-fft-plot",
3
- "version": "0.1.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 /绝对路径/chart.svg
14
- → 在回复里写 ![说明](/绝对路径/chart.svg)
17
+ → plot.py --spec spec.json --out-dir "$(pwd)/.dsh/plots" --slug 图名
18
+ → 把 stdout 打印的绝对路径写进 ![说明](/abs/path.svg)
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**。产物写进 `![](/abs/path.svg)`,图会出现在回复中间;
23
30
  不要调用 `present` 让用户另外点开侧栏——那多一次点击,而这里要的就是一眼看到。
24
31
  3. **图前后要有文字**。图是论点的配图,不是答复本身——图前一句交代看什么,图后一句给结论。
25
- 4. **不适用的情形不画**:数据为空、只有一条记录、纯名录字段、或用户只要一个数字。
32
+ 但**不要在正文复述图上每个数字**,图已经显示了。
33
+ 4. **同一回复不要重复画同一张图**。要改就重新生成一张并替换引用,不要叠加两张近似图。
34
+ 5. **不适用的情形不画**:数据为空、只有一条记录、纯名录字段、或用户只要一个数字。
26
35
  这时直接说结论,不要为了出图而出图。
27
- 5. **不编造数字**。图上每个数字都必须来自 `rows`。
28
-
29
- ## 三步
36
+ 6. **不编造数字**。图上每个数字都必须来自 `rows`。
37
+ 7. **产物必须是带完整根属性的独立 SVG**:`xmlns`、`width`、`height`、`viewBox` 四者齐全。
38
+ `viewBox` 只定义坐标系,**不提供内在尺寸**;缺 `width`/`height` 时,`![](x.svg)` 在多数
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 条记录(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` | 名录类数据,或作为图的补充 | `columns` |
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 /abs/chart.svg
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
- - **时间有五种写法**:毫秒时间戳、纳秒时间戳、`20260810`、`2026-08-10`、
130
- `2026-09-30 00:00:00`。纳秒按毫秒解析会得到公元 5 万年。
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`(米白+朱红墨蓝,默认)、`poster`(纯白+亮橙)、`slate`(冷灰+青红)。
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` 里写一个函数加 `@chart('名字')` 即可,签名
143
- `(c, rect, cfg, rows)`。然后在本文的图型表里补一行字段说明。
144
- **不需要**改 `plot.py` 或任何布局代码。
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))