1. 先把需求看清楚这个案例到底解决什么问题1.1 从“手动写报告”到“自动出报告”的转变这个案例我前前后后折腾了大概三天核心就一件事让 Claude Code 在收到一堆原始素材之后自动产出排版规范、结构完整、可以直接交付的 Word 报告。可能有人会问直接用 ChatGPT 网页版生成一段 Markdown 再手动复制到 Word 不行吗行但如果报告每周都要出、格式要求还特别死板比如固定的一级标题黑体三号、二级标题黑体四号、正文宋体小四、表格三线表样式、页码位置固定那你就会发现靠人工搬运的每一分钟都是浪费。这个案例里Claude Code 做的事情不是“生成一段文字”而是“调用我预先定义好的技能”把原始数据、会议纪要、测试日志甚至图片整理成一份带目录、带样式、带自动编号的 Word 文件。先说结论这套方案的实测效果是把原本手工需要 1 到 2 小时的报告整理工作压缩到了 3 到 5 分钟。中间踩过的坑不少尤其是 Word 表格列宽、公式图片、空白页这类经典问题后面我会逐条展开。1.2 为什么选 Claude Code 而不是别的自动化方案市面上做自动化的工具很多脚本、Excel 宏、Python 模板、低代码平台都能做报告生成。但这个案例选 Claude Code是因为它的“智能体”模式天然适合处理非结构化输入。手动写脚本方案的问题是报告的内容结构稍微一变脚本就要跟着改。比如这个月多了一个“风险项”章节下个月的报告需要把“结论”提到前面模板脚本维护成本立刻就上来了。Claude Code 的优势在于它本身是一个运行在终端里的 AI 智能体你可以用自然语言给它分配任务它自己会决定先读哪个目录、调用哪个函数、检查哪份材料再按照你定义的技能规范输出结果。这里需要特别提一下“技能”这个概念。在 Claude Code 的机制里技能不是一段简单的 Prompt而是一个带目录结构、带说明文件、附带可执行脚本的完整工具包。你可以在项目里通过SKILL.md文件来描述这个技能做什么、有哪些约束、需要调用哪些脚本。Claude Code 读到这个技能之后会把技能里的规则当作“工作手册”来执行。这跟 CTFHub 技能树那种“知识地图”完全是两种东西——CTFHub 技能树是给人学习用的体系化知识索引而这里的技能是给 AI 智能体用的工作流程定义。两者名字里都带“技能”但面向对象和用途完全不同。2. 环境准备与技能设计Claude Code 侧的核心配置2.1 安装 Claude Code 与模型接入安装 Claude Code 本身不难如果你用过 npm那基本就是一条命令的事npm install -g anthropic-ai/claude-code装完先跑一下claude --version确认版本号正常然后直接输入claude进入交互终端。首次启动会让你登录授权这里要注意服务的可用性跟区域有关。如果你在启动时看到类似“might not be available in your country”的提示说明当前网络环境不在官方支持范围内。这种情况下最稳妥的做法是确认官方支持地区列表或者等待服务覆盖范围扩展后再试。安全提示先放最前面不要为了绕过地区限制去折腾代理连接服务器、虚拟机镜像绕行、DNS 解析调整之类的手段。这类操作既不稳定也容易踩法律和合规的线解决问题的正路是选一个官方支持的区域或等待服务扩展。配置完成后还可以在~/.claude/settings.json里做个性化调整比如默认模型、输出风格、是否需要自动接受工具调用等。我的建议是新手期不要开启全自动工具调用先让它每一步都问你一遍确认它的行为习惯之后再放权。2.2 技能的设计思路把“算报告”变成“工厂流水线”技能设计是这个案例里最核心的环节。我的思路是把报告生成拆成四个阶段——素材解析、框架搭建、内容填充、格式渲染。素材解析读取用户指定的文件夹或文件识别出里面的数据表、文本记录、图片素材。框架搭建根据报告类型生成固定的章节结构比如背景、数据概览、问题分析、结论建议。内容填充把解析出来的数据放进去调用图表生成脚本把图表路径写进报告框架。格式渲染最后统一调用定制好的 Word 生成脚本保证每个标题、每个表格都符合规范。这四步如果不拆分全部塞进一个 Prompt 里让 Claude Code 自由发挥效果会非常不稳定。它可能这次生成的 Markdown 结构很好下次就输出一堆不规范的内容。拆分成技能之后每个环节都有明确输入输出任何一步出错都能单独排查。2.3 技能目录结构与 SKILL.md 的写法技能的本质其实是一个约定目录。我在项目里建了这样的结构skills/ report-generator/ SKILL.md scripts/ generate_docx.py chart_render.py data_parser.py templates/ report_template.docx cover_page.docx assets/ example_output.docxSKILL.md是给 Claude Code 看的说明书一定要写得像“给新员工看的操作手册”不能太抽象。以下是我实际在用的缩减版# 技能名称报告生成器 ## 技能目标 根据用户提供的素材目录自动生成一份符合 XX 企业标准的 Word 周报。 ## 触发条件 当用户提到“生成周报”“出报告”“自动报告”时使用本技能。 ## 工作流程 1. 首先调用 scripts/data_parser.py 解析输入目录下的所有 .xlsx / .csv / .txt 文件。 2. 如果解析失败立即返回错误信息不要继续后续步骤。 3. 根据解析结果调用 scripts/chart_render.py 生成图表保存到临时目录。 4. 最后调用 scripts/generate_docx.py 生成 Word 报告。 ## 格式规范 - 一级标题黑体三号居中 - 二级标题黑体四号左对齐 - 正文宋体小四1.5 倍行距 - 表格标准三线表 - 页脚页码居中 ## 关键约束 - 不允许修改模板文件 templates/report_template.docx - 生成的报告必须包含封面、目录页、正文、附录四个部分 - 遇到任何数据缺失请在报告“风险项”章节中明确标注写完这个文件之后每次在 Claude Code 对话里提到“生成周报”它就会自动读取该技能并按照里面的约束执行。这里有一个非常值得记录的细节如果技能文件写得像“作文提纲”Claude Code 就会自由发挥但如果写得像“SOP 操作流程”它的输出质量会稳定得多。跟人共事的道理是一样的规则越清晰产出越可控。3. 实操让 Claude Code 真正生成带格式 Word 报告3.1 用 python-docx 控制样式、表格与分页技能里的核心脚本是generate_docx.py基于 python-docx 实现。用这个库而不是直接让 Claude Code 自己拼 XML是因为它抽象层次合适既能控制样式又不像底层操作那样容易出错。先看如何控制标题样式。python-docx 默认模板的样式名跟 Word 中文版不完全一致所以最直接的方式是先加载已有的模板再修改样式from docx import Document from docx.shared import Pt from docx.enum.text import WD_ALIGN_PARAGRAPH doc Document(templates/report_template.docx) styles doc.styles # 修改一级标题样式 h1 styles[Heading 1] h1.font.name 黑体 h1.font.size Pt(16) # 三号约等于16pt h1.font.color.rgb RGBColor(0, 0, 0) h1.paragraph_format.alignment WD_ALIGN_PARAGRAPH.CENTER # 修改正文样式 normal styles[Normal] normal.font.name 宋体 normal.font.size Pt(12) # 小四约等于12pt normal.paragraph_format.line_spacing 1.5这里有一个容易踩坑的点font.name 黑体只设置了西文字体中文字体需要在rPr元素里额外指定w:eastAsia否则生成的 Word 文档里中文仍然显示默认字体。from docx.oxml.ns import qn def set_font(run, name_cn, name_en, size, boldFalse): run.font.name name_en run._element.rPr.rFonts.set(qn(w:eastAsia), name_cn) run.font.size size run.font.bold bold这个函数是我写完整套脚本之后总结出来的通用工具后面的标题、正文、表格单元格文字都靠它来统一设置字体。3.2 表格列宽设置poi 是 Java 的标准答案有朋友在评论区问过“Java POI 能生成图表吗”答案是能POI 完全可以操作 Word 文档里的图表对象但开发周期比 Python 长很多。如果你已经在用 Claude Code 做自动化脚本语言选 Python 会顺手得多。不过涉及 Word 表格列宽问题的时候Python 和 Java 的思路是通用的。python-docx 里设置表格列宽不能只设置column.width因为 Word 表格的宽度同时受单元格、表格布局、网格列三个因素影响。正确写法是这样table doc.add_table(rowslen(data), cols3) table.style Table Grid # 关闭自动调整 table.autofit False # 设置每个单元格的宽度 widths [C