Docx Tools

Word文档处理工具集 - 支持DOCX/Markdown互转、文档读取写入、多章节整合。纯本地操作，无需网络，安全可靠。

Security Scan

The code and instructions implement local DOCX/Markdown read/write/convert features as claimed; nothing in the bundle requests secrets or network access, though a few documentation claims (sandboxing, version) are not enforced in code.

Purpose & Capability

Name/description match the included Python modules (read_docx, write_docx, docx_to_md, md_to_docx, integrate_proposal). The files implement the documented features using python-docx and simple Markdown parsing. Minor metadata mismatch: SKILL.md states '技能版本: v2.0' while registry lists 1.0.0.

Instruction Scope

SKILL.md describes only local file operations and gives explicit examples; the code performs only local file I/O and uses python-docx. However the SKILL.md claims '沙盒限制 只在指定目录操作' and '只读默认 / 写操作需要显式路径' as security guarantees — these are documentation statements only and are not enforced by the code (functions accept arbitrary file paths). The documentation also directs pip install (network) for dependencies, which is normal but contradicts the '无需网络' phrasing for runtime behavior.

Install Mechanism

No install spec; this is instruction+code only. Dependencies are standard Python packages (python-docx, markdown) installed via pip according to SKILL.md. No downloads from arbitrary URLs or archive extraction present in the bundle.

Credentials

The skill requests no environment variables, credentials, or config paths. The code does not access network libraries or external credentials. Dependency installation via pip will fetch packages from the network if run, but this is expected and proportional.

Persistence & Privilege

always is false, skill is user-invocable and can be invoked autonomously (platform default). The skill does not modify other skills or agent-wide config and does not request persistent elevated privileges.

Assessment

This skill appears to be what it says: local DOCX/Markdown read/write/merge tools implemented in plain Python using python-docx. Before installing or running: 1) Review and test in a safe folder because the functions accept arbitrary file paths and can overwrite files — the claimed 'sandbox / only operate in specified directory' is not enforced by the code. 2) Install dependencies with pip in a controlled environment (virtualenv) — pip will download packages from the network even though runtime operations are local. 3) Note small metadata inconsistencies (SKILL.md lists v2.0 while registry shows v1.0.0); consider pulling the files and inspecting them yourself if you need absolute assurance. Overall the bundle is coherent and low-risk, but exercise the usual caution around file paths and dependency installation.

docx-tools - Word文档处理工具集

安全、本地、高效的Word文档处理工具集。纯本地操作，无需网络连接。

---

🎯 一句话定义

提供Word文档(DOCX)与Markdown的互转、内容读取/写入、多章节整合等功能，支持基金申请书、论文等学术文档的自动化处理。

---

📥 如何调用 (How to use me)

触发语句：

• "读取Word文档"
• "将Markdown转成Word"
• "合并多个Word章节"
• "提取文档内容"

需要提供的信息：

1. 必需： 操作类型（读/写/转换/整合）、文件路径
2. 可选： 输出格式、样式要求

---

🔄 执行逻辑 (What I do)

Step 1: 任务识别

• 📖 读取 → 进入 Step 2A
• ✍️ 写入 → 进入 Step 2B
• 🔄 转换 → 进入 Step 2C
• 📦 整合 → 进入 Step 2D

Step 2A: 读取流程

1. 验证文件存在性和格式
2. 使用 python-docx 读取文档
3. 提取段落文本和格式信息
4. 返回结构化数据

Step 2B: 写入流程

1. 创建新文档或打开现有文档
2. 根据输入添加段落/表格
3. 应用格式设置
4. 保存到指定路径

Step 2C: 转换流程

• DOCX → Markdown：提取文本，保留标题层级
• Markdown → DOCX：解析MD，生成对应样式段落

Step 2D: 整合流程

1. 读取多个章节文件
2. 按顺序合并内容
3. 统一格式和样式
4. 生成完整文档

---

🛠️ 工具详解

1. read_docx - 读取Word文档

功能： 提取Word文档的文本内容和基本格式

使用示例：

from docx_tools.read_docx import read_docx

# 读取文档
content = read_docx("D:/docs/申请书.docx")

# 返回结构
{
    "paragraphs": [
        {"text": "段落文本", "style": "Heading 1"},
        {"text": "正文内容", "style": "Normal"}
    ],
    "tables": [...],  # 表格数据
    "metadata": {...} # 文档属性
}

参数说明：

参数	类型	必需	说明
file_path	str	✅	Word文档路径
include_styles	bool	❌	是否包含样式信息，默认True
extract_tables	bool	❌	是否提取表格，默认True

---

2. write_docx - 写入Word文档

功能： 创建新Word文档或修改现有文档

使用示例：

from docx_tools.write_docx import write_docx

# 创建新文档
doc = write_docx.create_document()

# 添加标题
write_docx.add_heading(doc, "第一章 立项依据", level=1)

# 添加段落
write_docx.add_paragraph(doc, "这是正文内容...")

# 保存
write_docx.save(doc, "D:/output/新文档.docx")

参数说明：

参数	类型	必需	说明
document	Document	✅	docx文档对象
text	str	✅	要添加的文本
style	str	❌	段落样式，默认"Normal"
font_name	str	❌	字体名称，如"宋体"
font_size	int	❌	字号，如12

---

3. docx_to_md - DOCX转Markdown

功能： 将Word文档转换为Markdown格式

使用示例：

from docx_tools.docx_to_md import convert

# 转换文档
markdown_text = convert(
    input_path="D:/docs/论文.docx",
    output_path="D:/output/论文.md"
)

# 或仅获取文本不保存
md_text = convert("D:/docs/论文.docx", save=False)

参数说明：

参数	类型	必需	说明
input_path	str	✅	输入DOCX路径
output_path	str	❌	输出MD路径，默认不保存
save	bool	❌	是否保存文件，默认True

---

4. md_to_docx - Markdown转DOCX

功能： 将Markdown文件转换为Word文档

使用示例：

from docx_tools.md_to_docx import convert

# 转换
convert(
    input_path="D:/docs/内容.md",
    output_path="D:/output/文档.docx",
    template="D:/templates/基金模板.docx"  # 可选：使用模板
)

支持的Markdown语法：

• 标题（# ## ###）
• 粗体、斜体
• 列表（有序/无序）
• 表格
• 代码块（作为普通文本）

---

5. integrate_proposal - 整合申请书章节

功能： 将多个章节文件合并为完整的申请书

使用示例：

from docx_tools.integrate_proposal import integrate

# 定义章节顺序
sections = [
    {"file": "D:/chapters/摘要.docx", "title": "摘要"},
    {"file": "D:/chapters/立项依据.docx", "title": "一、立项依据"},
    {"file": "D:/chapters/研究内容.docx", "title": "二、研究内容"},
    {"file": "D:/chapters/研究基础.docx", "title": "三、研究基础"}
]

# 整合
integrate(
    sections=sections,
    output_path="D:/output/完整申请书.docx",
    add_page_breaks=True,  # 章节间添加分页
    unify_styles=True      # 统一格式
)

参数说明：

参数	类型	必需	说明
sections	list	✅	章节文件列表
output_path	str	✅	输出路径
add_page_breaks	bool	❌	章节间分页，默认True
unify_styles	bool	❌	统一样式，默认True

---

💡 典型使用场景

场景1: 基金申请书整合

# 整合分散撰写的各章节
integrate(
    sections=[
        {"file": "摘要.docx", "title": "摘要"},
        {"file": "立项依据.docx", "title": "一、立项依据与研究内容"},
        {"file": "研究方案.docx", "title": "二、研究方案"},
        {"file": "创新点.docx", "title": "三、创新点"},
        {"file": "研究基础.docx", "title": "四、研究基础与工作条件"}
    ],
    output_path="NSFC申请书_完整版.docx"
)

场景2: 批量读取多个文档

import os
from docx_tools.read_docx import read_docx

# 批量读取文件夹内所有文档
folder = "D:/papers"
contents = []

for file in os.listdir(folder):
    if file.endswith('.docx'):
        path = os.path.join(folder, file)
        content = read_docx(path)
        contents.append({"file": file, "content": content})

场景3: Markdown转Word提交

# 用Markdown写作，最终转为Word提交
md_to_docx(
    input_path="论文.md",
    output_path="论文_提交版.docx",
    template="期刊格式模板.docx"
)

---

⚙️ 配置与依赖

安装依赖

pip install python-docx markdown

系统要求

• Python 3.8+
• Windows/Linux/macOS
• 无需安装Microsoft Word

---

🔒 安全特性

特性	说明
✅ 纯本地操作	不连接网络，不上传文件
✅ 无外部依赖	仅使用 python-docx 库
✅ 沙盒限制	只在指定目录操作
✅ 只读默认	写操作需要显式路径

---

🐛 故障排除

问题："ModuleNotFoundError: No module named 'docx'"

解决： 安装依赖 pip install python-docx

问题："Package not found at 'xxx.docx'"

解决： 检查文件路径是否正确，文件是否存在

问题：中文显示为方框或乱码

解决： 指定中文字体

write_docx.add_paragraph(doc, "中文内容", font_name="宋体")

问题：表格格式丢失

解决： 复杂表格建议手动调整，简单表格转换正常

问题：Markdown中的公式未正确转换

解决： docx-tools 不支持LaTeX公式转换，建议保留为文本或截图

---

📊 与 word-vba 技能的区别

特性	docx-tools	word-vba
依赖	python-docx (纯Python)	Microsoft Word
平台	跨平台	仅Windows
速度	快	较慢（需启动Word）
格式保留	基本格式	完整格式（包括复杂样式）
适用场景	批量处理、简单操作	精确格式控制

建议：

• 批量处理、简单读写 → docx-tools
• 复杂格式、精确控制 → word-vba

---

技能版本: v2.0
更新日期: 2026-03-04
更新说明: 完善文档，添加详细使用示例和参数说明