float-optimizer

Name: float-optimizer
Author: OpenRaiser

331stars19forks

How to install float-optimizer?

openraiser/paperfit/float-optimizer

$npx -y skills add OpenRaiser/PaperFit --skill float-optimizer

Installs into the current project.

Summary

本技能专门处理 Category B：浮动体缺陷，包括：

Files · 1

View on GitHub

SKILL.md

1	# Float Optimizer Skill
2
3	## 概述
4
5	本技能专门处理 Category B：浮动体缺陷，包括：
6
7	- B1：浮动体远离首次引用（Float-Reference Distance）
8	- B2：浮动体大小不适配栏宽（Float Width Mismatch）
9	- B3：连续多个浮动体堆叠无正文间隔（Float Clustering）
10	- B4：浮动体跨页分裂（Float Page Orphaning）
11
12	该技能由 `code-surgeon-agent` 调用，通过对浮动体位置参数、尺寸设置和周围正文结构的精确调整，实现图表与正文的和谐共处。浮动体优化是视觉排版中最具挑战性的环节之一，必须结合页图反馈迭代验证。
13
14	---
15
16	## 适用场景
17
18	当 `layout-detective-agent` 报告中出现以下缺陷 ID 时，路由至本技能：
19
20	\| 缺陷 ID \| 描述 \| 优先级 \|
21	\|---------\|------\|--------\|
22	\| B1 \| 浮动体远离首次引用 \| High \|
23	\| B2 \| 浮动体大小不适配栏宽 \| High \|
24	\| B3 \| 浮动体连续堆叠 \| Medium \|
25	\| B4 \| 浮动体跨页分裂 \| Medium \|
26
27	---
28
29	## 输入规范
30
31	\| 输入项 \| 来源 \| 说明 \|
32	\|--------\|------\|------\|
33	\| 主 `.tex` 文件路径 \| 项目上下文 \| 需修改的源文件 \|
34	\| 排版侦探报告 \| `layout-detective-agent` 输出 \| 包含缺陷对象（图表标签）、页码、描述 \|
35	\| 源码交叉引用报告 \| `extract_crossrefs.py` 输出 (`data/crossrefs.json`) \| 提供每个图表的首次引用行号、定义行号、行距离、节距离 \|
36	\| 当前 PDF 页图 \| `visual-inspector` 输出 \| 用于验证修复后视觉效果 \|
37	\| 模板类型 \| 用户上下文或 `templates.yaml` \| 单栏/双栏，影响浮动体宽度策略 \|
38
39	输入使用说明：
40	- 从 `crossrefs.json` 的 `distances[]` 数组中提取 `ref_line` 和 `figure_line`，计算源码距离
41	- 若源码距离近（`line_distance < 50` 且 `section_distance = 0`）但视觉距离远 → 典型 LaTeX 浮动体放置问题，使用本技能的浮动体参数调整策略
42	- 若源码距离本身远 → 优先建议移动源码位置（策略 3），而非调整浮动体参数
43
44	---
45
46	## 输出规范
47
48	修改完成后，必须返回以下信息：
49
50	```json
51	{
52	"skill": "float-optimizer",
53	"status": "success \| partial \| failed",
54	"modified_files": ["main.tex"],
55	"changes": [
56	{
57	"defect_id": "B1",
58	"object": "Figure 3",
59	"action": "调整浮动体位置参数为 [ht]",
60	"before": "\\begin{figure}[t]",
61	"after": "\\begin{figure}[ht]"
62	},
63	{
64	"defect_id": "B2",
65	"object": "Table 1",
66	"action": "将 tabular 宽度设为 \\linewidth",
67	"before": "\\begin{tabular}{\|l\|c\|c\|}",
68	"after": "\\begin{tabularx}{\\linewidth}{\|l\|X\|X\|}"
69	}
70	],
71	"unresolved": []
72	}
73	```
74
75	---
76
77	## 修复策略
78
79	### 通用原则
80
81	1. 浮动体是“浮动”的：LaTeX 的浮动体放置算法具有不确定性，同一份源码在不同编译中可能产生不同输出。因此，修复后必须多次编译以验证稳定性。
82	2. 最小侵入：优先调整位置参数 `[ht]`，其次调整尺寸，最后才考虑移动浮动体在源码中的位置。
83	3. Endmatter 硬约束：正文浮动体不得进入 `Acknowledgements`、`References`、`Bibliography` 所在页；若发生，按失败处理，并优先在 endmatter 前插入 `\FloatBarrier`。
84	4. 视觉验证必须：浮动体修复的效果必须在页图上肉眼确认，不能仅凭日志判断。
85
86	---
87
88	### B1：浮动体远离首次引用
89
90	问题特征：
91	- 图表出现在距离其首次引用页码 ≥ 2 页的位置。
92	- 读者需翻页才能找到对应图表，打断阅读流。
93	- 源码分析：从 `data/crossrefs.json` 读取 `ref_line` 和 `figure_line`：
94	- 若 `line_distance < 50` 且 `section_distance = 0` → 源码组织良好，问题出在 LaTeX 浮动体放置算法
95	- 若 `line_distance > 100` 或 `section_distance ≥ 1` → 源码层面的引用与定义相距较远
96
97	诊断流程（新增）：
98	```bash
99	# 第一步：运行源码交叉引用分析
100	paperfit run scripts/extract_crossrefs.py main.tex --output data/crossrefs.json
101
102	# 第二步：解读输出
103	# {
104	# "distances": [
105	# {"label": "fig:result", "ref_line": 245, "figure_line": 260, "line_distance": 15, "section_distance": 0, "severity": "none"}
106	# ]
107	# }
108	# 若源码距离近但视觉距离远 → 浮动体参数调整
109	# 若源码距离远 → 移动源码位置
110	```
111
112	修复策略（按优先级）：
113
114	1. 调整位置参数
115	将浮动体环境的参数优先改为 `[ht]`。禁止将正文浮动体修成 `[p]` 或 `[!p]`；只有模板机制明确限制的跨栏场景才保留页顶策略。
116	```latex
117	% 修改前
118	\begin{figure}[t]
119	% 修改后
120	\begin{figure}[ht]
121	```
122	参数含义：`h` = here（尽可能在此处），`t` = top（页顶）。`p` = float page（独立浮动页）对正文浮动体视为禁用策略。
123
124	2. 使用 `\FloatBarrier` 强制放置
125	在引用点之后、期望图表出现的位置之前插入 `\FloatBarrier`（需 `placeins` 宏包），并在 `Acknowledgements` / `References` / `\bibliography` 之前再加一道 endmatter barrier，阻止正文浮动体漂入参考文献区域。
126	```latex
127	\usepackage{placeins}
128	...
129	As shown in Figure~\ref{fig:result}, ...
130	\FloatBarrier % 确保图不会漂到更后
131	```
132
133	3. 移动浮动体源码位置
134	将整个 `figure` 或 `table` 环境在 `.tex` 源码中向上移动，使其更接近首次引用点。
135	注意：移动源码可能改变上下文，需确保不影响前后文语义。
136
137	4. 拆分大型浮动体
138	若一个浮动体包含多个子图且过大，考虑拆分为两个独立的浮动体，或将其部分内容移至附录。
139
140	5. 调整前后正文数量
141	在浮动体前后增删少量文本（由 `semantic-polish-agent` 协助），改变分页位置，使浮动体自然落在引用附近。
142
143	---
144
145	### B2：浮动体大小不适配栏宽
146
147	问题特征：
148	- 过窄：图表宽度明显小于栏宽，两侧留白过多。
149	- 超宽：图表超出栏宽，内容被截断或溢出到页边。
150
151	修复策略（按优先级）：
152
153	1. 图片宽度标准化
154	将所有图片的 `\includegraphics` 宽度设为 `\linewidth`（单栏）或 `\textwidth`（跨栏）。
155	```latex
156	% 修改前
157	\includegraphics[width=0.6\textwidth]{figure.pdf}
158	% 修改后
159	\includegraphics[width=\linewidth]{figure.pdf}
160	```
161
162	2. 区分单栏与跨栏图表
163	- 单栏模板：所有图表默认使用 `\linewidth`。
164	- 双栏模板：单栏图表用 `\columnwidth` 或 `\linewidth`；跨栏图表使用 `figure` / `table` 环境，宽度用 `\textwidth`。
165	```latex
166	% 双栏中的跨栏图
167	\begin{figure*}
168	\includegraphics[width=\textwidth]{wide_figure.pdf}
169	\end{figure*}
170	```
171
172	3. 表格宽度自适应
173	使用 `tabularx` 将表格宽度设为 `\linewidth`，并由 `X` 列自动分配多余空间。
174	```latex
175	\begin{tabularx}{\linewidth}{\|l\|X\|X\|}
176	```
177
178	4. 旋转超宽表格
179	对于列数过多的宽表，使用 `sidewaystable` 环境旋转 90 度展示。
180	```latex
181	\usepackage{rotating}
182	...
183	\begin{sidewaystable}
184	\centering
185	\begin{tabular}{...}
186	...
187	\end{tabular}
188	\end{sidewaystable}
189	```
190
191	5. 缩小超大图片
192	若原图本身尺寸过大，可使用 `width=\linewidth` 自动缩放；若仍需保持比例，可同时设置 `height` 和 `keepaspectratio`。
193	```latex
194	\includegraphics[width=\linewidth,height=0.3\textheight,keepaspectratio]{figure.pdf}
195	```
196
197	---
198
199	### B3：浮动体连续堆叠
200
201	问题特征：
202	- 同一页或连续两页出现 ≥ 3 个图表，且中间正文极少（≤ 2 行）。
203
204	修复策略（按优先级）：
205
206	1. 分散浮动体位置参数
207	为不同浮动体分配非 `p` 的位置偏好，优先 `[ht]` / `[t]`，避免它们挤在同一页。
208	```latex
209	\begin{figure}[t] ... \end{figure}
210	\begin{table}[b] ... \end{table}
211	\begin{figure}[ht] ... \end{figure}
212	```
213
214	2. **在浮

People who liked this also viewed

6 picks

Type

grill-with-docsA relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.SkillsJul 2026537k182k
lark-minutes飞书妙记：搜索妙记、查看妙记基础信息、下载/上传音视频、读取或编辑妙记的产物内容、改标题、替换说话人/关键词、申请妙记查看/编辑权限。当给出minute_token、本地音视频文件，要查/改/转妙记产物，或用户明确要主动申请妙记权限时使用；本地音视频转纪要/逐字稿优先走本 skill，不要用 ffmpeg/whisper 本地转写。不负责：获取会议关联妙记，或仅按自然语言标题定位纪要SkillsJul 2026379k16k
lark-markdown飞书 Markdown：查看、创建、上传、编辑和比较 Markdown 文件。当用户需要创建或编辑 Markdown 文件、读取、修改、局部 patch 或比较差异时使用。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。SkillsJul 2026295k16k
docxUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', SkillsJul 2026157k163k
edit-articleSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026154k181k
lark-note飞书会议纪要（Note）直查：已知 note_id 时查询纪要详情、展示类型、关联文档 token，并读取 unified 原始逐字记录。当用户已持有 note_id，或从文档显式 vc-node-id 获得 note_id 时使用。不负责会议/日程/妙记定位、文档标题搜索或 Docx 正文读取。SkillsJul 2026154k16k

float-optimizer

331stars19forks

View on GitHub

How to install float-optimizer?

openraiser/paperfit/float-optimizer

$npx -y skills add OpenRaiser/PaperFit --skill float-optimizer

Installs into the current project.

Summary

本技能专门处理 Category B：浮动体缺陷，包括：

Files · 1

View on GitHub

SKILL.md

1	# Float Optimizer Skill
2
3	## 概述
4
5	本技能专门处理 Category B：浮动体缺陷，包括：
6
7	- B1：浮动体远离首次引用（Float-Reference Distance）
8	- B2：浮动体大小不适配栏宽（Float Width Mismatch）
9	- B3：连续多个浮动体堆叠无正文间隔（Float Clustering）
10	- B4：浮动体跨页分裂（Float Page Orphaning）
11
12	该技能由 `code-surgeon-agent` 调用，通过对浮动体位置参数、尺寸设置和周围正文结构的精确调整，实现图表与正文的和谐共处。浮动体优化是视觉排版中最具挑战性的环节之一，必须结合页图反馈迭代验证。
13
14	---
15
16	## 适用场景
17
18	当 `layout-detective-agent` 报告中出现以下缺陷 ID 时，路由至本技能：
19
20	\| 缺陷 ID \| 描述 \| 优先级 \|
21	\|---------\|------\|--------\|
22	\| B1 \| 浮动体远离首次引用 \| High \|
23	\| B2 \| 浮动体大小不适配栏宽 \| High \|
24	\| B3 \| 浮动体连续堆叠 \| Medium \|
25	\| B4 \| 浮动体跨页分裂 \| Medium \|
26
27	---
28
29	## 输入规范
30
31	\| 输入项 \| 来源 \| 说明 \|
32	\|--------\|------\|------\|
33	\| 主 `.tex` 文件路径 \| 项目上下文 \| 需修改的源文件 \|
34	\| 排版侦探报告 \| `layout-detective-agent` 输出 \| 包含缺陷对象（图表标签）、页码、描述 \|
35	\| 源码交叉引用报告 \| `extract_crossrefs.py` 输出 (`data/crossrefs.json`) \| 提供每个图表的首次引用行号、定义行号、行距离、节距离 \|
36	\| 当前 PDF 页图 \| `visual-inspector` 输出 \| 用于验证修复后视觉效果 \|
37	\| 模板类型 \| 用户上下文或 `templates.yaml` \| 单栏/双栏，影响浮动体宽度策略 \|
38
39	输入使用说明：
40	- 从 `crossrefs.json` 的 `distances[]` 数组中提取 `ref_line` 和 `figure_line`，计算源码距离
41	- 若源码距离近（`line_distance < 50` 且 `section_distance = 0`）但视觉距离远 → 典型 LaTeX 浮动体放置问题，使用本技能的浮动体参数调整策略
42	- 若源码距离本身远 → 优先建议移动源码位置（策略 3），而非调整浮动体参数
43
44	---
45
46	## 输出规范
47
48	修改完成后，必须返回以下信息：
49
50	```json
51	{
52	"skill": "float-optimizer",
53	"status": "success \| partial \| failed",
54	"modified_files": ["main.tex"],
55	"changes": [
56	{
57	"defect_id": "B1",
58	"object": "Figure 3",
59	"action": "调整浮动体位置参数为 [ht]",
60	"before": "\\begin{figure}[t]",
61	"after": "\\begin{figure}[ht]"
62	},
63	{
64	"defect_id": "B2",
65	"object": "Table 1",
66	"action": "将 tabular 宽度设为 \\linewidth",
67	"before": "\\begin{tabular}{\|l\|c\|c\|}",
68	"after": "\\begin{tabularx}{\\linewidth}{\|l\|X\|X\|}"
69	}
70	],
71	"unresolved": []
72	}
73	```
74
75	---
76
77	## 修复策略
78
79	### 通用原则
80
81	1. 浮动体是“浮动”的：LaTeX 的浮动体放置算法具有不确定性，同一份源码在不同编译中可能产生不同输出。因此，修复后必须多次编译以验证稳定性。
82	2. 最小侵入：优先调整位置参数 `[ht]`，其次调整尺寸，最后才考虑移动浮动体在源码中的位置。
83	3. Endmatter 硬约束：正文浮动体不得进入 `Acknowledgements`、`References`、`Bibliography` 所在页；若发生，按失败处理，并优先在 endmatter 前插入 `\FloatBarrier`。
84	4. 视觉验证必须：浮动体修复的效果必须在页图上肉眼确认，不能仅凭日志判断。
85
86	---
87
88	### B1：浮动体远离首次引用
89
90	问题特征：
91	- 图表出现在距离其首次引用页码 ≥ 2 页的位置。
92	- 读者需翻页才能找到对应图表，打断阅读流。
93	- 源码分析：从 `data/crossrefs.json` 读取 `ref_line` 和 `figure_line`：
94	- 若 `line_distance < 50` 且 `section_distance = 0` → 源码组织良好，问题出在 LaTeX 浮动体放置算法
95	- 若 `line_distance > 100` 或 `section_distance ≥ 1` → 源码层面的引用与定义相距较远
96
97	诊断流程（新增）：
98	```bash
99	# 第一步：运行源码交叉引用分析
100	paperfit run scripts/extract_crossrefs.py main.tex --output data/crossrefs.json
101
102	# 第二步：解读输出
103	# {
104	# "distances": [
105	# {"label": "fig:result", "ref_line": 245, "figure_line": 260, "line_distance": 15, "section_distance": 0, "severity": "none"}
106	# ]
107	# }
108	# 若源码距离近但视觉距离远 → 浮动体参数调整
109	# 若源码距离远 → 移动源码位置
110	```
111
112	修复策略（按优先级）：
113
114	1. 调整位置参数
115	将浮动体环境的参数优先改为 `[ht]`。禁止将正文浮动体修成 `[p]` 或 `[!p]`；只有模板机制明确限制的跨栏场景才保留页顶策略。
116	```latex
117	% 修改前
118	\begin{figure}[t]
119	% 修改后
120	\begin{figure}[ht]
121	```
122	参数含义：`h` = here（尽可能在此处），`t` = top（页顶）。`p` = float page（独立浮动页）对正文浮动体视为禁用策略。
123
124	2. 使用 `\FloatBarrier` 强制放置
125	在引用点之后、期望图表出现的位置之前插入 `\FloatBarrier`（需 `placeins` 宏包），并在 `Acknowledgements` / `References` / `\bibliography` 之前再加一道 endmatter barrier，阻止正文浮动体漂入参考文献区域。
126	```latex
127	\usepackage{placeins}
128	...
129	As shown in Figure~\ref{fig:result}, ...
130	\FloatBarrier % 确保图不会漂到更后
131	```
132
133	3. 移动浮动体源码位置
134	将整个 `figure` 或 `table` 环境在 `.tex` 源码中向上移动，使其更接近首次引用点。
135	注意：移动源码可能改变上下文，需确保不影响前后文语义。
136
137	4. 拆分大型浮动体
138	若一个浮动体包含多个子图且过大，考虑拆分为两个独立的浮动体，或将其部分内容移至附录。
139
140	5. 调整前后正文数量
141	在浮动体前后增删少量文本（由 `semantic-polish-agent` 协助），改变分页位置，使浮动体自然落在引用附近。
142
143	---
144
145	### B2：浮动体大小不适配栏宽
146
147	问题特征：
148	- 过窄：图表宽度明显小于栏宽，两侧留白过多。
149	- 超宽：图表超出栏宽，内容被截断或溢出到页边。
150
151	修复策略（按优先级）：
152
153	1. 图片宽度标准化
154	将所有图片的 `\includegraphics` 宽度设为 `\linewidth`（单栏）或 `\textwidth`（跨栏）。
155	```latex
156	% 修改前
157	\includegraphics[width=0.6\textwidth]{figure.pdf}
158	% 修改后
159	\includegraphics[width=\linewidth]{figure.pdf}
160	```
161
162	2. 区分单栏与跨栏图表
163	- 单栏模板：所有图表默认使用 `\linewidth`。
164	- 双栏模板：单栏图表用 `\columnwidth` 或 `\linewidth`；跨栏图表使用 `figure` / `table` 环境，宽度用 `\textwidth`。
165	```latex
166	% 双栏中的跨栏图
167	\begin{figure*}
168	\includegraphics[width=\textwidth]{wide_figure.pdf}
169	\end{figure*}
170	```
171
172	3. 表格宽度自适应
173	使用 `tabularx` 将表格宽度设为 `\linewidth`，并由 `X` 列自动分配多余空间。
174	```latex
175	\begin{tabularx}{\linewidth}{\|l\|X\|X\|}
176	```
177
178	4. 旋转超宽表格
179	对于列数过多的宽表，使用 `sidewaystable` 环境旋转 90 度展示。
180	```latex
181	\usepackage{rotating}
182	...
183	\begin{sidewaystable}
184	\centering
185	\begin{tabular}{...}
186	...
187	\end{tabular}
188	\end{sidewaystable}
189	```
190
191	5. 缩小超大图片
192	若原图本身尺寸过大，可使用 `width=\linewidth` 自动缩放；若仍需保持比例，可同时设置 `height` 和 `keepaspectratio`。
193	```latex
194	\includegraphics[width=\linewidth,height=0.3\textheight,keepaspectratio]{figure.pdf}
195	```
196
197	---
198
199	### B3：浮动体连续堆叠
200
201	问题特征：
202	- 同一页或连续两页出现 ≥ 3 个图表，且中间正文极少（≤ 2 行）。
203
204	修复策略（按优先级）：
205
206	1. 分散浮动体位置参数
207	为不同浮动体分配非 `p` 的位置偏好，优先 `[ht]` / `[t]`，避免它们挤在同一页。
208	```latex
209	\begin{figure}[t] ... \end{figure}
210	\begin{table}[b] ... \end{table}
211	\begin{figure}[ht] ... \end{figure}
212	```
213
214	2. **在浮

People who liked this also viewed

6 picks

Type