# Soft Copyright

> Generate Chinese software copyright (软著) application materials — specification manual and source code document. Analyzes the project, draws SVG diagrams, and converts to formatted DOCX using academic template.

- Skill: `zephyr236/soft-copyright` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add zephyr236/soft-copyright`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zephyr236/soft-copyright/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: Zephyr236 (https://skillmd.com/u/zephyr236)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zephyr236/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/` 目录下：

| 脚本 | 用途 | 何时使用 |
|------|------|----------|
| `svg_to_png.py` | 将 SVG 文件批量转为 2x PNG | 写完所有 SVG 后一次性转换 |
| `source_code_extractor.py` | 提取项目源代码，按60行/页分页 | 生成源代码文档时 |
| `generate_docx.py` | 将 Markdown 转为 DOCX，可选封面 | 最后一步，生成最终 docx 文件 |

**注意：** 脚本需要 `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 模板：
```svg
<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

```bash
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：生成源代码文档

```bash
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 并验证页数

```bash
# 说明书（带封面）
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 实测页数：**

```powershell
$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：检查与修复

```bash
# 检查格式问题
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` 第十节的模板生成，各字段有严格的字符限制：

| 字段 | 限制 | 说明 |
|------|------|------|
| 开发的硬件环境 | ≤50字符 | 开发时使用的硬件配置 |
| 运行的硬件环境 | ≤50字符 | 软件运行的最低硬件要求 |
| 软件运行支撑环境 | ≤50字符 | 运行所需的外部依赖 |
| 开发目的 | ≤50字符 | 一句话说明开发目的 |
| 软件的主要功能 | 500-1300字符 | 最关键的字段，必须基于实际项目编写 |
| 软件的技术特点 | 1-3句话 | 核心技术亮点 |

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

### 步骤 8：检查与修复

```bash
# 检查格式问题
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），两行均有底部框线