交接文档

接手者必读：本文档记录一个 ZCode Skill 的开发进度与剩余计划。前一位 AI 因 token 紧张无法完成端到端验证，把工作交接给你。请先通读「项目背景」与「已完成清单」，然后按「剩余计划」逐步推进，最后用「验收目标」自查。

一、项目背景

用户需求

用户要做一个 ZCode Skill，功能是：

输入：用户一大堆杂乱的课设材料（草稿、笔记、聊天记录、代码片段等）
处理：AI 分析材料、按指定格式归类到章节骨架、把关键代码渲染成 Carbon 风格截图插入文档
输出：一份符合中原工学院 2026 版《面向对象程序设计课程设计》格式规范的 .docx

用户的硬性要求（务必遵守）

不改原文：仅做格式整理与归类，绝不润色、改写、扩写、删减用户原话
多则容纳、缺则跳过：用户材料多于骨架→新增子节；少于骨架→跳过不留空占位
代码转图片：选定的代码以 Carbon 截图插入，原文字代码不再出现
每张代码图 ≤30 行：超长则拆分
缺封面信息让 AI 主动问（用 AskUserQuestion）
类图/ER图/运行截图：插入占位 + 反馈清单等用户补图

关键技术决策（用户已拍板）

截图方案：启动 carbon 本地服务（yarn dev）+ puppeteer 截图（不用 carbon-now CLI、不用纯 Python）
语言高亮：自动识别（detect_language.py）
Carbon 配置：无背景边框（透明）、mac 窗口控件、水印 user、白色主题
Skill 触发关键词：仅 「课程设计 / 课设报告 / 面向对象课设」 这一组

关键路径

Skill 目录：E:\AI\zcode\object\skills\course-design-report\
carbon 项目（用户提供，作为截图引擎）：E:\AI\antigravity\stady-code\supplement\carbon
原格式参考 doc：C:\Users\user\Documents\WXWork\1688856071809634\Cache\File\2026-06\课程设计格式2026---指导教师2026.6.12.doc（前一位 AI 已用 Word COM 提取过完整内容与格式参数，结果见 references/format-spec.md）

carbon 项目踩过的坑（重要）

carbon 的 wm URL 参数是开关不是水印文本。源码 components/svg/Watermark.js 里的水印是硬编码的 “carbon” 商标 SVG，不能通过 URL 改成 “user”。
解决方案已写入 references/carbon-setup.md：URL 里 wm=false 关掉 carbon 商标，截图后用 PIL 在 PNG 右下角叠加 “user” 文字水印。
carbon 的 URL 参数清单见 lib/routing.js 的 readMappings（已在 carbon-setup.md 列出本项目用到的全部参数）。

二、已完成清单（10/11，已写入磁盘）

所有文件均已创建，内容完整。接手者应通读这些文件后再动手，不要凭直觉重写。

E:\AI\zcode\object\skills\course-design-report\
├── SKILL.md                              ✅ 触发规则 + 6 步工作流
├── references/
│   ├── format-spec.md                    ✅ 全部字体/字号/边距/页眉页脚规格
│   ├── chapter-outline.md                ✅ 章节骨架 + 每节内容指南 + 归类规则
│   ├── carbon-setup.md                   ✅ carbon 服务启动 + URL 参数 + 水印方案 + 故障排查
│   └── code-chunking.md                  ✅ 代码选段优先级 + ≤30行拆分规则
├── scripts/
│   ├── detect_language.py                ✅ 代码语言识别（已测 java/sql 正确）
│   ├── build_docx.py                     ✅ docx 装配（未测试）
│   ├── screenshot.js                     ✅ puppeteer 截图（未测试）
│   ├── requirements.txt                  ✅ python-docx, Pillow
│   └── package.json                      ✅ puppeteer 依赖声明
└── assets/
    └── content.schema.json               ✅ content.json 结构定义 + 完整示例

各文件要点速览

SKILL.md：description 触发词、6 步工作流（收集封面→归类→选代码→截图→装配→反馈）、重要约束表。

references/format-spec.md：A4、边距上下 2.54/左右 3.18 cm、页眉「面向对象程序设计课程设计班级姓名」、页脚「- N -」、封面隶书 42pt、章标题黑体 16pt 居中、正文宋体五号首行缩进 2 字符等。

references/chapter-outline.md：完整章节树（1 概述 / 第2章设计与实现 / 第3章总结），每节内容指南，“多则容纳缺则跳过”规则。

references/carbon-setup.md：一次性环境准备（yarn install + npm install puppeteer + pip install pillow）、URL 参数表、水印后处理、故障排查。

references/code-chunking.md：选段优先级（DB 工具类 > DAO > 实体 > Service > main）、≤30 行拆分策略、决策示例。

scripts/detect_language.py：基于扩展名 + 文本指纹打分，输出语言代码或 carbon 兼容代码。已测：echo 'public class Test...' | python detect_language.py --in - 输出 java；SQL 输出 sql。

scripts/build_docx.py：读 content.json → 复制 template（或新建）→ 写封面/TOC/章节/代码图/表格/图占位 → 设置页眉页脚 → 让 Word 打开时更新域。核心函数：write_cover、write_toc、write_heading、write_body_paragraph、write_code_image、write_table（含三线表 _apply_three_line_borders）、add_page_number_field、add_toc_field。

scripts/screenshot.js：Node 脚本。读代码→构造 carbon URL→puppeteer 打开 localhost:3000→等 .export-container→元素截图→PIL 加 user 水印。含行数硬上限 50、URL 长度上限 7500、ECONNREFUSED 友好报错。

assets/content.schema.json：JSON Schema 定义 + 一个完整的最小示例 example_full_minimal，AI 产出 content.json 时照此结构。

三、剩余计划（接手者执行）

当前卡点

前一位 AI 在做端到端自测时发现 python-docx 装错了 Python 环境：

pip install python-docx 装到了 C:\Users\user\AppData\Local\Programs\Python\Python313\ （Python 3.13）
但默认 python 命令走的是 venv：E:\AI\hermes-agent\data\hermes-agent\venv\Scripts\python.exe，该 venv 里没有 docx
Pillow 12.2.0 在两个环境都有

接手者第一步要解决这个 Python 环境统一问题，然后跑通端到端。

步骤 1：统一 Python 环境（5 分钟）

确认所有脚本用同一个 Python。推荐：让 skill 脚本明确用 Python 3.13 的全路径，因为 docx 在那里。

# 验证：
"C:\Users\user\AppData\Local\Programs\Python\Python313\python.exe" -c "import docx, PIL; print('both OK')"

若要让默认 python 也能用，把 docx 装到 venv：

"E:\AI\hermes-agent\data\hermes-agent\venv\Scripts\pip.exe" install python-docx

决策建议：在 SKILL.md 和 references 里把所有 python 调用统一改成显式路径或说明”用装了 python-docx 的那个 Python”。最稳妥是让 AI 触发时先探测：python -c "import docx" 失败就 fallback 到 py313 路径。

步骤 2：端到端自测 build_docx.py（核心，30 分钟）

目标：验证 build_docx.py 能正确生成一份格式规范的 docx。这一步不需要 carbon 服务，先用占位 PNG 测图片插入逻辑。

2.1 准备测试 content.json

从原 doc 提取的真实内容，做一份精简测试 content.json（建议放到 E:\AI\zcode\object\skills\course-design-report\test\ 目录）。结构按 assets/content.schema.json 的 example_full_minimal 扩展。关键测试点：

cover 字段填一部分、留一部分空（测默认值与占位）
sections 覆盖 level 1/2/3
至少一个 codeImages（先用占位图）、一个 tables、一个 figures
故意省略一个章节（如 2.6 Bug），验证”缺则跳过”

测试 content.json 模板（接手者直接用）：

{
  "cover": {
    "title": "面向对象程序设计",
    "department": "计算机学院",
    "class": "软件 2201",
    "studentId": "20220808XXXX",
    "name": "学生丙",
    "teacher": "指导教师",
    "date": "2026 年 6 月"
  },
  "sections": [
    {
      "id": "1", "title": "课程设计概述", "level": 1,
      "children": [
        {"id": "1.1", "title": "课程设计目的", "level": 2,
         "paragraphs": ["《面向对象程序设计课程设计》是计算机类、物联网工程专业的一门设计性实践课……"]},
        {"id": "1.4", "title": "开发环境", "level": 2,
         "paragraphs": ["编程语言：Java JDK 1.8", "数据库：MySQL 8.0", "开发工具：IDEA"]}
      ]
    },
    {
      "id": "2", "title": "第2章  设计与实现", "level": 1,
      "children": [
        {"id": "2.1", "title": "题目要求", "level": 2,
         "paragraphs": ["本任务要求开发一款单机版 Java 知识在线测试系统……"],
         "children": [
           {"id": "2.1.1", "title": "核心任务内容", "level": 3,
            "paragraphs": ["实现管理员题库管理、学生在线测试、自动判分等核心功能……"]}
         ]},
        {"id": "2.3", "title": "数据库表结构设计", "level": 2,
         "paragraphs": ["共设计 3 张核心数据表……"]},
        {"id": "2.5", "title": "系统实现", "level": 2,
         "paragraphs": ["（1）编写数据库连接工具类……"],
         "children": [
           {"id": "2.5.1", "title": "DbUtils 数据库连接工具类", "level": 3,
            "paragraphs": ["DbUtils 类负责完成连接数据库……"]}
         ]}
      ]
    },
    {
      "id": "3", "title": "第3章  总结", "level": 1,
      "children": [
        {"id": "3.1", "title": "整体编码思路", "level": 2,
         "paragraphs": ["采用分层思路先行，先设计 3 张数据表……"]}
      ]
    }
  ],
  "codeImages": [
    {"section": "2.5.1", "path": "test/placeholder.png", "caption": "图 2-1 DbUtils 数据库连接工具类"}
  ],
  "figures": [
    {"section": "2.3", "caption": "图 2-2 数据库 ER 图", "desc": "user/question/score 三表的 ER 图，体现外键关系"}
  ],
  "tables": [
    {"section": "2.3", "caption": "表 2-1 user 用户表",
     "rows": [
       ["字段名", "数据类型", "字段用途"],
       ["user_id", "VARCHAR(20)", "用户唯一编号"],
       ["user_name", "VARCHAR(30)", "用户姓名"],
       ["user_pwd", "VARCHAR(50)", "加密后的登录密码"],
       ["user_type", "TINYINT", "1=管理员，2=学生"]
     ]}
  ]
}

2.2 生成占位 PNG（测图片插入）

python -c "from PIL import Image; Image.new('RGB',(800,400),'white').save('test/placeholder.png')"

2.3 跑 build_docx

python scripts/build_docx.py --content test/content.json --out test/报告测试.docx

（不传 —template，让脚本走”新建 Document”分支，避免 template.docx 还没生成的问题）

2.4 打开生成的 docx 检查（用 Word 或 python -c "from docx import Document; d=Document('test/报告测试.docx'); [print(p.style.name, p.text[:50]) for p in d.paragraphs]"）

重点核对：

封面：隶书大标题两行、黑体信息块、宋体日期
目录页有「目录」标题 + TOC 域占位
章标题居中、节标题左对齐、字号字体正确
正文首行缩进 2 字符
表格是三线表（顶/底粗线、表头下细线、无竖线）
代码图居中、图注在图下方居中
图占位是灰色文字
页眉有「面向对象程序设计课程设计软件2201 学生丙」
页脚有 - N - 页码（Word 打开会显示）

2.5 修复 build_docx.py 发现的问题。可能的问题：

三线表边框没生效（检查 _apply_three_line_borders 的 sz 单位，1/8 pt）
TOC 域占位文字乱码（检查 add_toc_field 的 xml:space）
页眉没出现（检查 update_header 是否被 sections 的 sectPr 覆盖）
图片插入失败（检查路径与 width=Cm）

步骤 3：端到端自测 screenshot.js（需要 carbon 服务，30–60 分钟）

前置：

cd E:\AI\antigravity\stady-code\supplement\carbon
yarn install          # 首次 5–10 分钟
yarn dev              # 保持运行，等到 "ready - started server"

另开终端：

cd E:\AI\zcode\object\skills\course-design-report\scripts
npm install           # 装 puppeteer，首次下载 Chromium 约 150MB

测试一段 Java 代码：

# 准备测试代码文件
echo 'public class DbUtils {
    public static Connection getConnection() {
        return DriverManager.getConnection(url, user, pwd);
    }
}' > test_dbutils.java

node scripts/screenshot.js --code test_dbutils.java --lang java --out test/dbutils.png --caption "图 2-1 DbUtils"

预期：生成 test/dbutils.png，是 mac 窗口风格的浅色代码图，右下角有半透明 “user” 水印。

故障排查（按 references/carbon-setup.md 的表格）：

ECONNREFUSED → carbon dev 没起
.export-container 未出现 → 服务还在编译，等 30 秒
Chromium 启动失败 → 设 PUPPETEER_EXECUTABLE_PATH 指向系统 Chrome
中文注释乱码 → carbon 字体 Hack 不含中文，考虑改 fm 参数或截图前处理

修复 screenshot.js 发现的问题。可能的问题：

omitBackground: true 配合 bg=rgba(255,255,255,0) 可能得到透明背景，但 carbon 编辑器外层有 padding，截图范围要对（已用元素截图，应该没问题）
水印 Python 子进程在 Windows 下路径转义（spawnSync 的 -c 脚本里反斜杠路径可能出问题，建议改用独立 watermark.py 文件）
carbon 的 .export-container 选择器版本变了（查 carbon 源码确认）

步骤 4：跑通完整流程（可选，验证 SKILL.md 工作流）

模拟一次完整的 AI 触发：把原 doc 的纯文本内容（前一位 AI 已提取，在历史会话的 artifacts 里）当作”用户材料”丢给加载了这个 skill 的 AI，看它能否：

识别触发词
问封面（或自动填）
归类章节
选代码段（从原 doc 里的 DbUtils/Stu/StuDaoImpl/TestStu 代码挑 5–6 段）
调 detect_language + screenshot 生成图
产出 content.json
调 build_docx 生成最终 docx
反馈缺哪些章节、需要哪些图

这一步主要是验证 SKILL.md 的指引够不够清晰，如果 AI 卡壳，回来改 SKILL.md / references。

步骤 5：补充 assets/template.docx（可选优化）

当前 build_docx.py 不依赖 template.docx（不传 —template 时直接 Document() 新建）。如果想生成一个预设好样式的 template.docx 让文档更稳：

python scripts/build_template.py    # 这个脚本还没写，需要时再补

或者直接跳过——目前 build_docx.py 内联了所有样式，已经够用。

四、验收目标（Definition of Done）

接手者完成下列全部检查项后，这个 skill 算交付：

A. 脚本能跑（功能验收）

python scripts/detect_language.py --in <java文件> 输出 java
python scripts/build_docx.py --content test/content.json --out test/报告.docx 成功生成文件
node scripts/screenshot.js --code <java文件> --lang java --out test/code.png 成功生成图片（需 carbon 服务）
生成的 docx 用 Word/WPS 打开不报错，页眉页脚正常

B. 格式正确（视觉验收，对照 references/format-spec.md）

封面：隶书 42pt 大标题居中、黑体 16pt 信息块、宋体 14pt 日期
目录页有「目录」+ TOC 域
章标题黑体 16pt 居中、节标题黑体 16pt 左对齐、小节宋体 14pt 加粗
正文宋体五号、首行缩进 2 字符、两端对齐
表格是三线表
代码图居中、有图注
页眉「面向对象程序设计课程设计班级姓名」、页脚「- N -」页码

C. 业务规则（内容验收）

用户原文一字未改（用 diff 对比 content.json 的 paragraphs 与用户原话）
用户多出的内容有新增子节承载
缺失章节直接跳过，文档里无「待补充」空占位
类图/ER图/运行截图有灰色占位段
代码图 ≤30 行，每张有图注，超长有「(续)」

D. Skill 触发与指引（行为验收）

用户说「帮我把这些整理成课设报告」能触发本 skill
SKILL.md 的工作流步骤清晰，AI 不会卡壳
4 个 reference 文件参数准确（字体字号、URL 参数）

E. 文档完整（交付物）

11 个文件（及新扩展文件）全部存在且内容非空
SKILL.md 的目录结构速查与实际目录一致
content.schema.json 的示例能被 build_docx.py 正确解析

五、风险与注意事项

carbon 项目依赖庞大（next + puppeteer-core + cypress + firebase 等），yarn install 可能 10 分钟+，首次跑要耐心。如果用户机器装不上，备选方案是用纯 Python（imgkit + HTML 模板）仿制 Carbon，前一位 AI 在 carbon-setup.md 末尾留了降级路径但未实现。
puppeteer 的 Chromium 下载在中国网络可能失败。备选：设 PUPPETEER_EXECUTABLE_PATH 指向系统已装的 Chrome（C:\Program Files\Google\Chrome\Application\chrome.exe）。
carbon 编辑器加载较慢，screenshot.js 里已经 waitForSelector + 额外等 1.5 秒，但首次访问可能要更久。如果截图是空白，把等待时间从 1500ms 调到 3000ms。
carbon 的中文注释：Hack 字体不含中文，代码里的中文注释会显示成方框。如果用户材料代码中文多，考虑：
- 截图前把中文注释翻译成英文（违反”不改原文”原则，不可取）
- 或在 screenshot.js 里把 fm 参数改成包含中文 fallback 的字体（carbon 的 FONTS 列表见 carbon lib/constants.js 第 3 行）
- 或接受方框（最忠实于原文）
python-docx 与页眉页脚：python-docx 对页眉页脚的支持有限，复杂页眉（带 tab 对齐）可能要用 oxml 直接写 XML。前一位 AI 的 update_header 用的是简单文本，如果对齐不美观，需要改进。
TOC 自动更新：python-docx 不能强制 Word 更新 TOC，只能插域 + 设 updateFields=true。Word 打开时会弹窗问是否更新，用户点”是”即可。WPS 行为可能不同。

六、关键文件路径速查

用途	路径
Skill 根目录	`E:\AI\zcode\object\skills\course-design-report\`
Skill 主文件	`E:\AI\zcode\object\skills\course-design-report\SKILL.md`
格式规格	`E:\AI\zcode\object\skills\course-design-report\references\format-spec.md`
docx 装配脚本	`E:\AI\zcode\object\skills\course-design-report\scripts\build_docx.py`
截图脚本	`E:\AI\zcode\object\skills\course-design-report\scripts\screenshot.js`
content.json 结构	`E:\AI\zcode\object\skills\course-design-report\assets\content.schema.json`
carbon 项目（截图引擎）	`E:\AI\antigravity\stady-code\supplement\carbon`
原格式参考 doc	`C:\Users\user\Documents\WXWork\1688856071809634\Cache\File\2026-06\课程设计格式2026---指导教师2026.6.12.doc`
Python 3.13（有 docx）	`C:\Users\user\AppData\Local\Programs\Python\Python313\python.exe`
默认 python（venv，无 docx）	`E:\AI\hermes-agent\data\hermes-agent\venv\Scripts\python.exe`

七、给接手 AI 的话

先读 SKILL.md 和 4 个 reference，理解整体设计。不要跳过。
先用上面的测试 content.json 跑通 build_docx.py（步骤 2），这是最快验证核心功能的方式，不需要 carbon 服务。
截图子系统（步骤 3）较重，如果时间紧，可以先交付”不带代码截图”的版本（让 AI 在选代码段时插入文字占位 ［代码图：待 carbon 服务就绪后渲染］），后续再补。
修改任何文件前先读它，前一位 AI 的实现可能有 bug 但思路是对的，优先小修不要重写。
用户原话不可改是铁律，自测时一定要 diff 检查。
完成后把这份 HANDOFF.md 更新上”实际验收结果”，或删除。

祝顺利。