fix Skills public imports

docs/skills-import-optimization-report.md

@@ -0,0 +1,219 @@
+# python-office Skills 导入优化对比报告
+
+## 1. 对比基线
+
+- 项目目录：`E:\项目\python-office`
+- 分支基线：`develop`
+- 原项目基线提交：`2b1996b557c76a233642e261ae62da92b5dfa73e`
+- 基线提交说明：`fix: 修复拆分Excel缺少tqdm导入、废弃API及抠图颜色提取引发的程序崩溃问题 (#161)`
+- 对比方式：优化分支与上述 Git 提交进行比较。
+
+## 2. 原项目存在的问题
+
+项目 README 推荐如下用法：
+
+```python
+from skills.pdf import pdf2docx
+from skills.image import compress_image
+from skills.tools import qrcodetools
+```
+
+但各分类包的 `__init__.py` 实际引用了不存在的 `office.skills`：
+
+```python
+from office.skills.pdf.pdf2docx import pdf2docx
+```
+
+仓库中没有 `office/skills` 包，因此按 README 操作会出现：
+
+```text
+ModuleNotFoundError: No module named 'office.skills'
+```
+
+这会导致 Skills 功能虽然已经编写，但用户无法通过项目公开入口导入。
+
+## 3. 本次优化内容
+
+### 3.1 修复分类包导入方式
+
+将分类入口由不存在的绝对路径改成包内相对导入。
+
+修改前：
+
+```python
+from office.skills.pdf.pdf2docx import pdf2docx
+```
+
+修改后：
+
+```python
+from .pdf2docx import pdf2docx
+```
+
+这样分类入口会调用仓库中真实存在的 `skills/<分类>/<功能>/__init__.py`，再由功能入口连接到 `office.api`。
+
+### 3.2 统一 Skills 文档
+
+将 Skills 文档里的错误示例：
+
+```python
+from office.skills.pdf import pdf2docx
+```
+
+统一改为项目真实可用的公开入口：
+
+```python
+from skills.pdf import pdf2docx
+```
+
+### 3.3 新增回归测试
+
+新增 `tests/test_code/test_skills_imports.py`，自动检查：
+
+- 13 个 Skills 分类都能导入；
+- 每个分类都有公开导出列表 `__all__`；
+- 73 个公开导出对象都存在且可以调用；
+- 后续修改不会再次引入同类导入错误。
+
+## 4. 修改文件统计
+
+| 类型 | 数量 | 说明 |
+|---|---:|---|
+| 已修改 Python 文件 | 14 | Skills 根说明及 13 个分类入口 |
+| 已修改 Markdown 文件 | 74 | Skills 总索引及 73 个功能文档 |
+| 新增测试文件 | 1 | Skills 公共导入回归测试 |
+| 新增报告文件 | 1 | 本优化对比报告 |
+| 合计涉及文件 | 90 | 88 个已有文件加 2 个新文件 |
+
+已有文件的 Git 文本差异为 228 行新增、228 行删除，全部属于导入路径替换；另新增回归测试和本报告。
+
+## 5. Python 代码文件清单
+
+以下 14 个已有 Python 文件被修改：
+
+1. `skills/__init__.py`：修正文档字符串中的示例导入路径。
+2. `skills/excel/__init__.py`：Excel 分类改用相对导入。
+3. `skills/file/__init__.py`：文件处理分类改用相对导入。
+4. `skills/finance/__init__.py`：金融分类改用相对导入。
+5. `skills/image/__init__.py`：图片分类改用相对导入。
+6. `skills/markdown/__init__.py`：Markdown 分类改用相对导入。
+7. `skills/ocr/__init__.py`：OCR 分类改用相对导入。
+8. `skills/pdf/__init__.py`：PDF 分类改用相对导入。
+9. `skills/ppt/__init__.py`：PPT 分类改用相对导入。
+10. `skills/ruiming/__init__.py`：实验 API 分类改用相对导入。
+11. `skills/tools/__init__.py`：工具分类改用相对导入。
+12. `skills/video/__init__.py`：视频分类改用相对导入。
+13. `skills/wechat/__init__.py`：微信分类改用相对导入。
+14. `skills/word/__init__.py`：Word 分类改用相对导入。
+
+新增文件：
+
+- `tests/test_code/test_skills_imports.py`：Skills 分类和 73 个公开导出的回归测试。
+
+## 6. Markdown 文档文件清单
+
+### 总索引
+
+- `skills/README.md`
+
+### Excel（7 个）
+
+- `skills/excel/{excel2pdf,fake2excel,find_excel_data,merge2excel,merge2sheet,sheet2excel,split_excel_by_column}/SKILL.md`
+
+### 文件处理（9 个）
+
+- `skills/file/{add_line_by_type,file_name_add_postfix,file_name_add_prefix,file_name_insert_content,get_files,group_by_name,output_file_list_to_excel,replace4filename,search_specify_type_file}/SKILL.md`
+
+### 金融（1 个）
+
+- `skills/finance/t0/SKILL.md`
+
+### 图片（9 个）
+
+- `skills/image/{add_watermark,compress_image,decode_qrcode,del_watermark,down4img,image2gif,img2Cartoon,pencil4img,txt2wordcloud}/SKILL.md`
+
+### Markdown（1 个）
+
+- `skills/markdown/excel2markdown/SKILL.md`
+
+### OCR（1 个）
+
+- `skills/ocr/VatInvoiceOCR2Excel/SKILL.md`
+
+### PDF（13 个）
+
+- `skills/pdf/{add_img_water,add_mark,add_text_watermark,add_watermark,add_watermark_by_parameters,decrypt4pdf,del4pdf,encrypt4pdf,merge2pdf,pdf2docx,pdf2imgs,split4pdf,txt2pdf}/SKILL.md`
+
+### PPT（3 个）
+
+- `skills/ppt/{merge4ppt,ppt2img,ppt2pdf}/SKILL.md`
+
+### 实验 API（3 个）
+
+- `skills/ruiming/{change_label_in_xml,screen_unmarked_image,screen_without_label_json_file}/SKILL.md`
+
+### 工具（10 个）
+
+- `skills/tools/{course,create_article,lottery8ticket,net_speed_test,passwordtools,pwd4wifi,qrcodetools,transtools,url2ip,weather}/SKILL.md`
+
+### 视频（4 个）
+
+- `skills/video/{audio2txt,mark2video,txt2mp3,video2mp3}/SKILL.md`
+
+### 微信（7 个）
+
+- `skills/wechat/{chat_by_keywords,chat_robot,group_send,receive_message,send_file,send_message,send_message_by_time}/SKILL.md`
+
+### Word（5 个）
+
+- `skills/word/{doc2docx,docx2doc,docx2pdf,docx4imgs,merge4docx}/SKILL.md`
+
+## 7. 优化后的效果
+
+以下公开调用方式现已可用：
+
+```python
+from skills.pdf import pdf2docx
+from skills.image import compress_image
+from skills.tools import qrcodetools
+from skills.excel import fake2excel
+```
+
+本次修复覆盖 13 个分类和 73 个公开功能，使 README、Skills 文档与实际包结构保持一致，也为未来桌面客户端通过统一入口发现和调用功能打下基础。
+
+## 8. 验证结果
+
+执行的专项测试：
+
+```powershell
+.\venv\Scripts\python.exe -m unittest tests.test_code.test_skills_imports -v
+```
+
+结果：
+
+```text
+Ran 1 test
+OK
+```
+
+独立测试 Agent 还完成了以下复核：
+
+- 13 个分类全部导入成功；
+- 73 个 `__all__` 导出全部存在且可调用；
+- README 常用导入全部通过；
+- `setuptools.find_packages()` 能发现顶层 `skills` 及其子包；
+- `git diff --check` 通过；
+- `skills` 目录中已无残留的 `office.skills` 错误路径；
+- 建议保留优化，无需回滚。
+
+## 9. 本次没有修改的内容
+
+- 没有修改 `office/api` 业务实现；
+- 没有修改 PDF、Excel、Word、图片等功能的处理逻辑；
+- 没有制作或修改桌面客户端；
+- 没有提交用户创建的 `demo.py` 和 `qrcode.png`；
+- 没有逐个执行可能修改文件、发送微信或调用外部 API 的功能。
+
+## 10. 已知提示
+
+Git 在 Windows 上提示部分 Python 文件未来可能由 LF 转换为 CRLF。`git diff --check` 已通过，该提示不影响本次功能，但后续可通过统一 `.gitattributes` 作为单独优化项处理。

skills/README.md

@@ -28,11 +28,11 @@
 
 ```python
 # 方式 1：直接导入函数
-from office.skills.excel import fake2excel
+from skills.excel import fake2excel
 fake2excel(rows=10)
 
 # 方式 2：导入子模块
-from office.skills.excel import fake2excel as fe
+from skills.excel import fake2excel as fe
 fe(rows=10, columns=['name', 'phone'])
 ```
 
@@ -63,7 +63,7 @@ fe(rows=10, columns=['name', 'phone'])
 
 调用示例：
 ```python
-from office.skills.excel import fake2excel
+from skills.excel import fake2excel
 fake2excel(columns=['name', 'phone'], rows=100, path='./test.xlsx')
 ```
 
@@ -85,7 +85,7 @@ fake2excel(columns=['name', 'phone'], rows=100, path='./test.xlsx')
 
 调用示例：
 ```python
-from office.skills.file import replace4filename
+from skills.file import replace4filename
 replace4filename(path='./test_dir', del_content='old', replace_content='new')
 ```
 
@@ -99,7 +99,7 @@ replace4filename(path='./test_dir', del_content='old', replace_content='new')
 
 调用示例：
 ```python
-from office.skills.finance import t0
+from skills.finance import t0
 profit = t0(buy_price=11.99, sale_price=12.26, shares=700)
 print(profit)
 ```
@@ -122,7 +122,7 @@ print(profit)
 
 调用示例：
 ```python
-from office.skills.image import add_watermark
+from skills.image import add_watermark
 add_watermark(file='test.png', mark='python-office')
 ```
 
@@ -249,7 +249,7 @@ office/skills/<category>/<skill_name>/
 ```
 
 - **细粒度**：每个方法对应一个独立 Skill
-- **可单独调用**：每个 Skill 都可通过 `from office.skills.<category> import <skill_name>` 单独使用
+- **可单独调用**：每个 Skill 都可通过 `from skills.<category> import <skill_name>` 单独使用
 - **文档齐全**：每个 Skill 都有对应的 `SKILL.md` 详细说明
 
 ---

skills/__init__.py

@@ -6,10 +6,10 @@
 每个 Skill 都是一个独立的子目录，可以单独调用。
 
 使用方式：
-    from office.skills.excel import fake2excel
+    from skills.excel import fake2excel
     fake2excel(rows=10)
 
-    from office.skills.image import add_watermark
+    from skills.image import add_watermark
     add_watermark(file='test.png', mark='python-office')
 
 详细功能列表见本目录下的 README.md。

skills/excel/__init__.py

@@ -1,12 +1,12 @@
 # -*- coding: UTF-8 -*-
 """Excel Skills 包 - 统一暴露 Excel 处理相关的所有 Skills"""
-from office.skills.excel.fake2excel import fake2excel
-from office.skills.excel.merge2excel import merge2excel
-from office.skills.excel.sheet2excel import sheet2excel
-from office.skills.excel.merge2sheet import merge2sheet
-from office.skills.excel.find_excel_data import find_excel_data
-from office.skills.excel.split_excel_by_column import split_excel_by_column
-from office.skills.excel.excel2pdf import excel2pdf
+from .fake2excel import fake2excel
+from .merge2excel import merge2excel
+from .sheet2excel import sheet2excel
+from .merge2sheet import merge2sheet
+from .find_excel_data import find_excel_data
+from .split_excel_by_column import split_excel_by_column
+from .excel2pdf import excel2pdf
 
 __all__ = [
     'fake2excel',

skills/excel/excel2pdf/SKILL.md

@@ -18,7 +18,7 @@ description: 将 Excel 文件的指定工作表转换为 PDF 格式。当用户
 ## 调用方式
 
 ```python
-from office.skills.excel import excel2pdf
+from skills.excel import excel2pdf
 
 excel2pdf(
     excel_path='./data.xlsx',
@@ -42,7 +42,7 @@ excel2pdf(
 ## 使用示例
 
 ```python
-from office.skills.excel import excel2pdf
+from skills.excel import excel2pdf
 excel2pdf(excel_path='./report.xlsx', pdf_path='./report.pdf', sheet_id=0)
 ```
 

skills/excel/fake2excel/SKILL.md

@@ -18,7 +18,7 @@ description: 自动创建 Excel 并模拟数据。当用户提到生成测试数
 ## 调用方式
 
 ```python
-from office.skills.excel import fake2excel
+from skills.excel import fake2excel
 
 fake2excel(
     columns=['name', 'phone'],
@@ -45,7 +45,7 @@ fake2excel(
 
 ```python
 # 示例 1：生成中文测试数据
-from office.skills.excel import fake2excel
+from skills.excel import fake2excel
 fake2excel(columns=['name', 'phone', 'address'], rows=1000, path='./test_cn.xlsx')
 
 # 示例 2：生成英文测试数据

skills/excel/find_excel_data/SKILL.md

@@ -18,7 +18,7 @@ description: 在 Excel 文件中搜索指定关键词并返回文件、行号、
 ## 调用方式
 
 ```python
-from office.skills.excel import find_excel_data
+from skills.excel import find_excel_data
 
 find_excel_data(
     search_key='python',
@@ -40,7 +40,7 @@ find_excel_data(
 ## 使用示例
 
 ```python
-from office.skills.excel import find_excel_data
+from skills.excel import find_excel_data
 find_excel_data(search_key='订单', target_dir='./订单数据')
 ```
 

skills/excel/merge2excel/SKILL.md

@@ -18,7 +18,7 @@ description: 将多个 Excel 文件合并到一个 Excel 的不同 sheet 中。
 ## 调用方式
 
 ```python
-from office.skills.excel import merge2excel
+from skills.excel import merge2excel
 
 merge2excel(
     dir_path='./excel_files',
@@ -40,7 +40,7 @@ merge2excel(
 ## 使用示例
 
 ```python
-from office.skills.excel import merge2excel
+from skills.excel import merge2excel
 merge2excel(dir_path='./excels', output_file='./all_in_one.xlsx')
 ```