Soft Copyright

soft-copyright 软著材料生成

重要：在开始任何工作前，必须先阅读 soft-copyright-lessons.md，其中记录了所有格式化规范、常见错误和验证方法。关键教训包括：

• 软件说明书内容必须详尽丰富（不少于 7 章，7-10 张图，每个模块深入分析）
• 表格必须使用三线表（无竖线、无底色、无交替行色）
• 字体：正文 TNR+SimSun，标题 SimHei 不加 bold
• 所有正文段落统一首行缩进 0.74cm
• 禁止使用 - 无序列表、带圈数字 ①②③
• 禁止残留 **text** Markdown 语法
• 源代码文档页数必须用 Word COM 实测，不能凭计算判断

为指定项目生成中国计算机软件著作权（软著）登记所需的核心材料：

1. 软件说明书 — 含封面、架构图、流程图、模块说明等
2. 源代码文档 — 按规范分页（前30页+后30页，每页60行）
3. 软件功能与特点.txt — 软著申请必填信息表，各字段有严格字符限制

重要：必读经验文档

在开始任何工作之前，必须先阅读 soft-copyright-lessons.md。该文档记录了所有关键问题和解决方案：

• 三线表（三线表）的正确实现方式
• 字体规范（TNR + SimSun 正文，SimHei 不加 bold 标题）
• 段落缩进规则（所有正文段落统一首行缩进 0.74cm）
• 列表格式规范（禁止 - 无序列表，使用 （1） 或 1. 编号）
• 带圈数字等不常见符号的禁止使用
• 图题和表题自动编号
• 残留 Markdown 语法的处理
• 源代码文档的 60 页精确控制
• 封面学术风格规范

soft-copyright-lessons.md 是强制阅读材料，违反其中任何规则都会导致返工。

工具脚本

本 Skill 提供以下脚本，均位于 scripts/ 目录下：

注意： 脚本需要 python-docx 依赖。由于 _vendor/ 目录不可用，使用 uv run --with python-docx python <script> 运行。SVG 转 PNG 使用 uv run --with cairosvg python 调用 cairosvg。

工作流程

步骤 1：阅读并理解项目

使用 Glob、Grep、Read 等工具全面了解项目：

• 目录结构、主要模块
• 技术栈（语言、框架、数据库）
• 入口点和核心流程
• 关键依赖

步骤 2：编写 SVG 图表

根据对项目的深入理解，自行决定需要绘制哪些图表以及绘制多少张。图表应当充分展示项目的架构、模块、流程、数据流、类关系等。数量不限，根据项目复杂度灵活决定。

选择图表的思路（根据项目特点灵活选择，以下仅为参考）：

• 项目有明确分层架构 → 系统架构图（分层展示）
• 项目有多个模块/包 → 模块关系图（依赖关系）
• 项目有核心业务流程 → 流程图（处理流程、数据流）
• 项目涉及数据存储 → 数据模型图（ER图、数据流图）
• 面向对象项目 → 类图（核心类及关系）
• 项目有多个组件交互 → 时序图（交互顺序）、组件交互图
• 项目有时序/状态逻辑 → 状态机图
• 项目有部署需求 → 部署架构图
• 任何你认为有助于说明项目的图

SVG 编写指引：

• viewBox 根据图表内容灵活设置（如 0 0 800 600 或 0 0 1000 800）
• 中文字体：font-family="SimHei, Microsoft YaHei, sans-serif"
• 配色建议：主色 #2c5f8a、浅蓝 #4a90d9、背景 #e8f0fe、白色填充 #ffffff、成功绿 #27ae60、警告橙 #f39c12
• 箭头定义在 <defs> 中，通过 marker-end="url(#arrow)" 引用
• 保存到指定的输出目录下（如 output/diagrams/），文件按内容命名（如 architecture.svg、module-relations.svg、data-flow.svg 等）

SVG 箭头 marker 模板：

<defs>
  <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5"
          markerWidth="6" markerHeight="6" orient="auto-start-reverse">
    <path d="M 0 0 L 10 5 L 0 10 z" fill="#666"/>
  </marker>
</defs>

步骤 3：SVG 转 PNG

uv run --with cairosvg python -c "
import cairosvg, os, glob
for svg in sorted(glob.glob('output/diagrams/*.svg')):
    png = svg.replace('.svg', '.png')
    cairosvg.svg2png(url=svg, write_to=png, scale=2)
    print(f'{os.path.basename(svg)} -> {os.path.basename(png)}')
"

scale=2 生成 2x 分辨率 PNG 确保在 DOCX 中清晰。

步骤 4：编写说明书 Markdown

内容必须详尽丰富。 初次生成容易过于简略，必须深入阅读源码后编写。

根据对项目的理解，用中文编写软件说明书 Markdown。章节结构由你决定，内容深度要求：

• 不少于 7 章，每章 2-5 节
• 每个核心模块独立成节，详细说明设计目的、数据结构、关键算法、对外接口
• 每个关键流程独立成节，包含流程图和分步骤详解
• 数据模型需包含 ER 图和每个实体逐一定义
• 完整的环境变量和配置参数表
• 硬件/软件要求、依赖库版本表
• Docker、二进制、源码编译三种部署方式及客户端接入示例
• 图片不少于 5 张：架构图、模块关系图、流程图、数据模型图、算法流程图等

常见内容结构：

• 软件概述（名称、版本、开发语言、主要功能）
• 技术架构（架构模式、技术选型表、架构图）
• 功能模块说明（模块划分、各模块职责、模块关系图）
• 核心流程（业务流程描述、流程图）
• 运行环境（硬件/软件要求、依赖库）
• 使用说明（安装、配置、运行方法）

要点：

• 图表引用使用相对路径（相对于 CWD），如 ![架构图](output/diagrams/architecture.png)
• 表格使用 Markdown 表格语法
• 文档保存为 软件说明书.md
• 禁止在文档末尾添加"本文档由 XX 工具自动生成"等尾注或免责声明

格式规范（详见 soft-copyright-lessons.md）：

• 分点使用 （1）、1. 等编号格式，禁止使用 - 无序列表
• 禁止使用带圈数字（①②③）、特殊箭头（▸）、全角装饰线（━）等不常见符号
• 步骤编号使用"步骤 1"、"步骤 2"等文字描述
• 标题后编号列表项前添加引言段落，确保所有编号项缩进一致

步骤 5：生成源代码文档

uv run python soft-copyright-skill/scripts/source_code_extractor.py <项目目录> <软件名称> <版本号> > 源代码文档.md

该脚本自动：

• 收集所有源文件，按文件名排序
• 每个文件开头自动插入文件路径标记（如 # File: src/main.go）
• 每 60 行代码为 1 页，使用 ## 第 N 页 + ```text 代码块格式
• 前 30 页 + 后 30 页分页（不足 60 页则提交全部）
• 每页带页头（软件名称 + 版本号 + 页码）
• 输出仅包含源代码页，无标题、无说明、无尾注

步骤 6：转换为 DOCX 并验证页数

# 说明书（带封面）
uv run --with python-docx python soft-copyright-skill/scripts/generate_docx.py cover <软件名称> 软件说明书.md 软件说明书.docx

# 源代码文档（无封面）
uv run --with python-docx python soft-copyright-skill/scripts/generate_docx.py plain 源代码文档.md 源代码文档.docx

源代码文档生成后必须用 Word COM 实测页数：

$word = New-Object -ComObject Word.Application
$word.Visible = $false
$doc = $word.Documents.Open("C:\path\to\源代码文档.docx")
$doc.Repaginate()
$pages = $doc.ComputeStatistics(2)  # 2 = wdStatisticPages
Write-Host "Pages: $pages"
$doc.Close($false)
$word.Quit()

如果页数不是 60，根据实测结果反推行数后重新生成。 不能凭计算判断页数——Word 的实际分页行为受字体度量、文档网格、兼容模式等多种因素影响，计算结果不可靠。

注意： 运行 generate_docx.py 时 CWD 必须与 Markdown 中图片路径的基准目录一致。如果 Markdown 中图片路径为 output/diagrams/xxx.png，则 CWD 应为包含 output/ 目录的父目录。

步骤 7：检查与修复

# 检查格式问题
officecli view 软件说明书.docx issues --type format

# 检查残留 Markdown 语法
officecli view 软件说明书.docx annotated | grep '\*\*'

# 检查残留带圈数字
officecli view 软件说明书.docx annotated | grep '[①②③④⑤⑥⑦⑧⑨⑩]'

# 检查是否有 List Bullet 样式
officecli query 软件说明书.docx 'paragraph[style="List Bullet"]'

步骤 7：生成软件功能与特点.txt

根据 soft-copyright-lessons.md 第十节的模板生成，各字段有严格的字符限制：

核心原则：必须根据项目实际代码编写，禁止编造功能。 生成后必须用 Python 验证各字段字符数是否在限制内。

步骤 8：检查与修复

# 检查格式问题
officecli view 软件说明书.docx issues --type format

# 检查残留 Markdown 语法
officecli view 软件说明书.docx annotated | grep '\*\*'

# 检查残留带圈数字
officecli view 软件说明书.docx annotated | grep '[①②③④⑤⑥⑦⑧⑨⑩]'

# 检查是否有 List Bullet 样式
officecli query 软件说明书.docx 'paragraph[style="List Bullet"]'

# 验证软件功能与特点.txt 各字段字符数
python -c "
import re
with open('软件功能与特点.txt','r',encoding='utf-8') as f:
    content=f.read()
m=re.search(r'软件的主要功能.*?\n(.*?)\n\n',content,re.DOTALL)
if m:
    text=m.group(1).strip().replace('\n','')
    print(f'主要功能: {len(text)} 字符, 在范围内: {500<=len(text)<=1300}')
"
- 所有正文段落统一首行缩进 0.74cm（Body Text）
- 标题：keep_with_next = True

### 列表
- 禁止 `- ` 无序列表
- 使用 `（1）`、`1. ` 等编号格式
- 列表项使用 Body Text 样式，编号保留在文本中

### 代码块
- 单格表格，四边实线框，无背景色
- 消除空首行

### 封面
- 简洁学术风格，SimHei 28pt 居中
- 无彩色装饰线

## 依赖说明

本 Skill 脚本需要 `python-docx` 库。由于 `_vendor/` 预装依赖不可用，使用 `uv run --with python-docx` 运行脚本。SVG 转 PNG 使用 `cairosvg`（`uv run --with cairosvg`）。

## 注意事项

- 所有 Markdown 文件使用 UTF-8 编码
- 图片路径在 Markdown 中使用从 CWD 出发的相对路径
- 输出目录建议为 `soft-copyright-output/`
- **生成 DOCX 后必须用 officecli 检查：残留 `**` 语法、带圈数字、List Bullet 样式、格式问题**
- **Markdown 编写阶段即避免使用 `- ` 无序列表和带圈数字等不常见符号**
- 源代码文档使用 Times New Roman 10.5pt + 宋体，单倍行距，不是 Consolas
- 源代码文档页眉格式：左对齐"软件名 源代码"（宋体 9pt）+ 右对齐 PAGE 字段（TNR 9pt），两行均有底部框线