Code with Solo - ruledoc 项目开发纪实
一、摘要
使用 Trae IDE 的 Solo 模式，从零开始打造了一个规则驱动的论文格式化工具 ruledoc。该项目经过初版formatter脚本的更新，采用插件化架构设计，将格式规范与核心处理逻辑完全解耦，用户只需添加规则文件即可支持新的高校论文格式，无需修改核心代码。支持 Markdown 和 DOCX 输入格式，实现了标题智能编号、图表自动编号、三线表格式化、公式排版、文献上标、交叉引用、页面、段落、字体等用论文核心排版要求。
核心亮点：原本需要数周开发的专业级论文格式化工具，在 Trae Solo 模式下仅用 3 天完成从设计到发布的全流程，代码质量达到生产级标准，测试覆盖率超过 80%。
反响：在抖音、小红书等社交软件分享经验共收获点赞1800+
链接：
1.76 复制打开抖音，看看【yuu86112的图文作品】还在为改论文格式苦恼吗 还在因为ai生成的md文档… https://v.douyin.com/EEqVTZfwed4/ 06/25 tRk:/ l@p.dn
二、背景
职业角色
我是大三非科班学生，同时也是一名开源爱好者。我深刻体会到论文格式调整的痛苦——每次修改内容后都要重新调整字体、字号、行距、页边距等格式，稍有不慎就会违反学校格式规范。
面临的挑战
- 格式调整耗时：每次论文修改后，手动调整格式需要 1-2 小时
- 格式规范复杂：高校论文格式规范包含数十项细节要求（标题层级、图表编号、参考文献格式等）
- 工具缺失：现有工具要么功能单一，要么不支持中国高校格式规范，要么收费不合理
- 可扩展性差：不同学校格式规范不同，缺乏统一的扩展机制
解决方案构想
我希望开发一个工具，能够：
- 将 Markdown 文档，自动转换为符合规范的 Word 文档
- 检查修改好的word文档是否存在待修改细节
- 支持多种高校格式规范，通过"规则文件"配置
- 提供完整的 Python API 和命令行工具
- 开源发布，让更多人受益
三、实践过程
3.1 任务拆解
在 Trae Solo 模式下，我将项目拆分为以下核心模块：
ruledoc/
├── ruledoc/ # 主包
│ ├── cli.py # 命令行接口
│ ├── formatter.py # 核心格式化器
│ ├── config.py # 配置管理
│ ├── context.py # 处理上下文
│ ├── exceptions.py # 异常体系
│ ├── rules/ # 格式规则（插件化）
│ │ ├── base.py # 规则基类
│ │ └── yzu/ # 扬州大学规则集
│ └── processors/ # 文档处理器
│ ├── heading_processor.py # 标题处理
│ ├── caption_processor.py # 图表题注
│ ├── list_processor.py # 列表处理
│ └── style_processor.py # 样式处理
├── tests/ # 测试套件
└── docs/ # 文档
3.2 Trae Solo 能力应用
1. 架构设计阶段
使用 Trae 的spec进行架构设计：
用户: 帮我设计一个论文格式化工具的架构
Trae: 建议采用"规则驱动"架构，核心思想是：
- FormatRule: 抽象基类，定义规则接口
- Formatter: 流程编排器，不包含格式细节
- Processor: 处理器链，负责具体转换
这样设计的好处：
- 新增学校支持只需添加规则文件
- 核心代码稳定，无需频繁修改
- 符合开闭原则（对扩展开放，对修改关闭）
#### 2. 核心代码生成
使用 Trae 的 **Code_Synthesis skill** 生成核心代码：
**规则基类设计**：
```python
class FormatRule(ABC):
"""格式规则抽象基类
所有学校格式规则必须继承此类并实现抽象方法。
规则定义了论文格式的所有可配置项。
"""
@property
@abstractmethod
def name(self) -> str:
"""规则名称 (唯一标识)"""
pass
@abstractmethod
def get_page_settings(self) -> Dict[str, float]:
"""获取页面设置（边距、装订线等）"""
pass
@abstractmethod
def detect_paragraph_type(self, para, ctx) -> str:
"""检测段落类型（标题、题注、正文等）"""
pass
@abstractmethod
def format_paragraph(self, para, para_type: str, ctx) -> None:
"""格式化段落"""
pass
处理器链设计：
class Formatter:
"""核心格式化器 - 纯流程编排器"""
def process(self) -> None:
"""执行格式化流程
完整流程:
1. 加载文档
2. 创建处理上下文
3. 执行处理器链
4. 应用规则格式化
5. 保存文档
"""
self.doc = self._load_document()
self._context = ProcessingContext(doc=self.doc, rule=self.rule)
self._run_processor_chain(self._context)
self._apply_rule_formatting(self._context)
self._save_document()
3. 复杂问题解决
问题：Word 公式编号右对齐
Pandoc 转换后的公式段落无法正确实现"公式居中、编号右对齐"的学术论文标准格式。
Trae 的解决方案：
Trae 分析：
Word OOXML 中 <m:oMathPara> 是块元素，会吞掉外部制表符。
解决方案：将 oMathPara 转换为行内 oMath，然后使用制表位实现布局。
最终段落结构：
<w:p>
<w:bookmarkStart/>
<w:r><w:t>\t</w:t></w:r> ← 居中制表符
<m:oMath>...</m:oMath> ← 行内公式
<w:r><w:t>\t(1-1)</w:t></w:r> ← 右对齐制表符+编号
<w:bookmarkEnd/>
</w:p>
问题：三线表格式
学术论文要求使用三线表（顶线、栏目线、底线），但 python-docx 默认不支持。
Trae 的解决方案：
def _set_cell_level_three_line_borders(self, table) -> None:
"""使用单元格级边框设置三线表格式
三线表结构：
- 首行：top=粗线(1.5pt) + bottom=细线(0.5pt)
- 中间行：无边框
- 末行：bottom=粗线(1.5pt)
- 所有单元格：无竖线
"""
for row_idx, row in enumerate(table.rows):
for cell in row.cells:
tcBorders = OxmlElement("w:tcBorders")
if row_idx == 0: # 首行
top = OxmlElement("w:top")
top.set(qn("w:sz"), "12") # 1.5pt
tcBorders.append(top)
# ...栏目线
elif row_idx == last_row_idx: # 末行
bottom = OxmlElement("w:bottom")
bottom.set(qn("w:sz"), "12")
tcBorders.append(bottom)
4. 测试与质量保证
使用 Trae 生成完整的测试套件：
# tests/test_processors.py
def test_heading_processor_removes_manual_numbering():
"""测试标题处理器删除手打编号"""
processor = HeadingProcessor(remove_manual_numbering=True)
# ...测试逻辑
def test_caption_processor_generates_chapter_numbers():
"""测试图表题注生成章节化编号"""
processor = CaptionProcessor()
# ...测试逻辑
3.3 Trae solo踩过的坑和使用经验（可复用）
有效的使用模式
| 模式 | 说明 | 示例 |
|---|---|---|
| 先思考后提问 | 自己先构思方案，让 Trae 完善 | “我想用策略模式实现规则系统，请帮我设计接口” |
| 提供上下文 | 让 Trae 读取相关文件 | “请读取 ruledoc/rules/base.py 后，帮我实现 YZU 规则” |
| 分步验证 | 复杂功能分步骤实现 | 先实现检测逻辑，再实现格式化逻辑 |
| 要求解释 | 不仅要知道怎么做，还要知道为什么 | “请解释为什么选择处理器链模式” |
| 善用任务模式 | 不要在一个对话框下死磕，开多任务处理低耦合需求，提高效率的同时可以通过总结子任务来给下一步开发提供上下文（很重要） | “总结当前任务：目标、成果、方法” |
多任务示例图
需要避免的做法
一次性要求生成过多代码- 不提供上下文就让 Trae 盲目修改，会影响回归率
- 完全依赖 Trae，自己不验证逻辑正确性
- 跨文件修改时不确认 Trae 是否看到了最新代码
- 在一个任务窗口从头到尾，任务不清晰，上下文爆炸
四、成果展示
4.1 项目已发布
- GitHub 地址：https://github.com/xiaoyu-778/ruledoc
- 版本：v1.0.0
- 许可证：MIT
示例图：
4.2 核心功能
| 功能 | 说明 |
|---|---|
| 标题智能编号 | 支持 1.、1.1、1.1.1 多级编号 |
| 图表自动编号 | 章节-序号格式（图 3-1、表 2-2） |
| 三线表格式化 | 学术论文标准三线表 |
| 公式编号 | 居中公式 + 右对齐编号 |
| 交叉引用 | REF 域实现动态引用 |
| 参考文献格式化 | GB/T 7714 标准 |
五、效果与总结
5.1 提效数据
| 指标 | 传统方式 | 使用 RuleDoc | 提升比例 |
|---|---|---|---|
| 格式调整时间 | 1-2 小时/次 | 30 秒/次 | 90%+ |
| 格式错误率 | 约 10% | <1% | 显著降低 |
| 新增学校支持 | 需修改核心代码 | 仅添加规则文件 | 零侵入 |
5.2 Trae Solo 在流程中的作用
- 架构设计：帮助确定"规则驱动"的核心架构
- 代码生成：生成约 90% 以上的核心代码，包括复杂的 OMML 处理逻辑，效率惊人。
- 问题解决：解决了公式编号、三线表、交叉引用等技术难点
- 文档生成：润色并生成 README、用户指南、贡献指南等文档
- 测试辅助：生成测试用例，确保代码质量
5.3 未来规划
- 支持更多高校格式规范（欢迎社区贡献）
- 添加 GUI 界面
- 支持在线使用（Web 版）
- 集成更多学术写作辅助功能
六、致谢
感谢 Trae IDE 的 Solo 模式，让这个项目从想法到发布仅用了 3 天时间。Trae 不仅是代码生成工具，更是架构设计和问题解决的得力助手。特别感谢 Trae 提供的专业解决方案，这些细节问题如果手动解决可能需要数周时间，让我体验从0到1的创造过程，并取得了一定反响。
感兴趣的朋友可以交流、点赞和投票让本帖被更多人看见，ruledoc欢迎一切贡献和建议，谢谢大家！
