技能編寫最佳實踐

## 提取 PDF 文本

使用 pdfplumber 進行文本提取：

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## 提取 PDF 文本

PDF（便攜式文檔格式）文件是一種常見的文件格式，包含
文本、圖像和其他內容。要從 PDF 中提取文本，您需要
使用一個庫。有許多可用於 PDF 處理的庫，但我們
推薦 pdfplumber，因為它易於使用並能處理大多數情況。
首先，您需要使用 pip 安裝它。然後您可以使用下面的代碼...

## 代碼審查流程

1. 分析代碼結構和組織
2. 檢查潛在的錯誤或邊界情況
3. 建議改進可讀性和可維護性
4. 驗證是否遵守項目約定

## 生成報告

使用此模板並根據需要自定義：

```python
def generate_report(data, format="markdown", include_charts=True):
    # 處理數據
    # 以指定格式生成輸出
    # 可選地包括可視化
```

## 數據庫遷移

運行完全相同的腳本：

```bash
python scripts/migrate.py --verify --backup
```

不要修改命令或添加其他標誌。

description: 從 PDF 文件中提取文本和表格、填充表單、合併文檔。在處理 PDF 文件或用戶提及 PDF、表單或文檔提取時使用。

description: 分析 Excel 電子表格、創建數據透視表、生成圖表。在分析 Excel 文件、電子表格、表格數據或 .xlsx 文件時使用。

description: 通過分析 git diff 生成描述性提交消息。當用戶要求幫助編寫提交消息或審查暫存更改時使用。

description: 幫助處理文檔

description: 處理數據

description: 對文件進行各種操作

pdf/
├── SKILL.md              # 主要說明（觸發時加載）
├── FORMS.md              # 表單填充指南（根據需要加載）
├── reference.md          # API 參考（根據需要加載）
├── examples.md           # 使用示例（根據需要加載）
└── scripts/
    ├── analyze_form.py   # 實用腳本（執行，不加載）
    ├── fill_form.py      # 表單填充腳本
    └── validate.py       # 驗證腳本

---
name: pdf-processing
description: 從 PDF 文件中提取文本和表格、填充表單、合併文檔。在處理 PDF 文件或用戶提及 PDF、表單或文檔提取時使用。
---

# PDF 處理

## 快速開始

使用 pdfplumber 提取文本：
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## 高級功能

**表單填充**：查看 [FORMS.md](FORMS.md) 了解完整指南
**API 參考**：查看 [REFERENCE.md](REFERENCE.md) 了解所有方法
**示例**：查看 [EXAMPLES.md](EXAMPLES.md) 了解常見模式

bigquery-skill/
├── SKILL.md (概述和導航)
└── reference/
    ├── finance.md (收入、計費指標)
    ├── sales.md (機會、管道)
    ├── product.md (API 使用、功能)
    └── marketing.md (活動、歸因)

# DOCX 處理

## 創建文檔

使用 docx-js 創建新文檔。查看 [DOCX-JS.md](DOCX-JS.md)。

## 編輯文檔

對於簡單編輯，直接修改 XML。

**對於跟蹤更改**：查看 [REDLINING.md](REDLINING.md)
**對於 OOXML 詳情**：查看 [OOXML.md](OOXML.md)

# SKILL.md
查看 [advanced.md](advanced.md)...

# advanced.md
查看 [details.md](details.md)...

# details.md
這是實際信息...

# SKILL.md

**基本使用**：[SKILL.md 中的說明]
**高級功能**：查看 [advanced.md](advanced.md)
**API 參考**：查看 [reference.md](reference.md)
**示例**：查看 [examples.md](examples.md)

# API 參考

## 內容
- 身份驗證和設置
- 核心方法（創建、讀取、更新、刪除）
- 高級功能（批量操作、webhook）
- 錯誤處理模式
- 代碼示例

## 身份驗證和設置
...

## 核心方法
...

## 研究綜合工作流

複製此清單並跟蹤您的進度：

```
研究進度：
- [ ] 步驟 1：讀取所有源文檔
- [ ] 步驟 2：識別關鍵主題
- [ ] 步驟 3：交叉參考聲明
- [ ] 步驟 4：創建結構化摘要
- [ ] 步驟 5：驗證引用
```

**步驟 1：讀取所有源文檔**

查看 `sources/` 目錄中的每個文檔。記下主要論點和支持證據。

**步驟 2：識別關鍵主題**

尋找跨源的模式。什麼主題重複出現？源在哪裡達成一致或不同意？

**步驟 3：交叉參考聲明**

對於每個主要聲明，驗證它出現在源材料中。記下哪個源支持每個點。

**步驟 4：創建結構化摘要**

按主題組織發現。包括：
- 主要聲明
- 來自源的支持證據
- 衝突的觀點（如果有）

**步驟 5：驗證引用**

檢查每個聲明是否引用了正確的源文檔。如果引用不完整，返回步驟 3。

## PDF 表單填充工作流

複製此清單並在完成項目時檢查：

```
任務進度：
- [ ] 步驟 1：分析表單（運行 analyze_form.py）
- [ ] 步驟 2：創建字段映射（編輯 fields.json）
- [ ] 步驟 3：驗證映射（運行 validate_fields.py）
- [ ] 步驟 4：填充表單（運行 fill_form.py）
- [ ] 步驟 5：驗證輸出（運行 verify_output.py）
```

**步驟 1：分析表單**

運行：`python scripts/analyze_form.py input.pdf`

這提取表單字段及其位置，保存到 `fields.json`。

**步驟 2：創建字段映射**

編輯 `fields.json` 為每個字段添加值。

**步驟 3：驗證映射**

運行：`python scripts/validate_fields.py fields.json`

在繼續之前修復任何驗證錯誤。

**步驟 4：填充表單**

運行：`python scripts/fill_form.py input.pdf fields.json output.pdf`

**步驟 5：驗證輸出**

運行：`python scripts/verify_output.py output.pdf`

如果驗證失敗，返回步驟 2。

## 內容審查流程

1. 按照 STYLE_GUIDE.md 中的指南起草您的內容
2. 根據清單審查：
   - 檢查術語一致性
   - 驗證示例遵循標準格式
   - 確認所有必需部分都存在
3. 如果發現問題：
   - 記下每個問題及其具體部分參考
   - 修訂內容
   - 再次審查清單
4. 只有在滿足所有要求時才繼續
5. 最終確定並保存文檔

## 文檔編輯流程

1. 對 `word/document.xml` 進行編輯
2. **立即驗證**：`python ooxml/scripts/validate.py unpacked_dir/`
3. 如果驗證失敗：
   - 仔細查看錯誤消息
   - 修復 XML 中的問題
   - 再次運行驗證
4. **只有在驗證通過時才繼續**
5. 重建：`python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. 測試輸出文檔

如果您在 2025 年 8 月之前執行此操作，請使用舊 API。
2025 年 8 月之後，使用新 API。

## 當前方法

使用 v2 API 端點：`api.example.com/v2/messages`

## 舊模式

<details>
<summary>舊版 v1 API（已於 2025-08 棄用）</summary>

v1 API 使用：`api.example.com/v1/messages`

此端點不再受支持。
</details>

## 報告結構

始終使用此確切的模板結構：

```markdown
# [分析標題]

## 執行摘要
[關鍵發現的一段概述]

## 關鍵發現
- 帶支持數據的發現 1
- 帶支持數據的發現 2
- 帶支持數據的發現 3

## 建議
1. 具體可行的建議
2. 具體可行的建議
```

## 報告結構

這是一個合理的默認格式，但根據分析使用您的最佳判斷：

```markdown
# [分析標題]

## 執行摘要
[概述]

## 關鍵發現
[根據您發現的內容調整部分]

## 建議
[根據具體上下文調整]
```

根據特定分析類型調整部分。

## 提交消息格式

按照這些示例生成提交消息：

**示例 1：**
輸入：使用 JWT 令牌添加用戶身份驗證
輸出：
```
feat(auth): 實現基於 JWT 的身份驗證

添加登錄端點和令牌驗證中間件
```

**示例 2：**
輸入：修復日期在報告中顯示不正確的錯誤
輸出：
```
fix(reports): 修正時區轉換中的日期格式

在報告生成中一致使用 UTC 時間戳
```

**示例 3：**
輸入：更新依賴項並重構錯誤處理
輸出：
```
chore: 更新依賴項並重構錯誤處理

- 將 lodash 升級到 4.17.21
- 標準化端點間的錯誤響應格式
```

遵循此風格：type(scope): 簡短描述，然後詳細說明。

## 文檔修改工作流

1. 確定修改類型：

   **創建新內容？** → 遵循下面的"創建工作流"
   **編輯現有內容？** → 遵循下面的"編輯工作流"

2. 創建工作流：
   - 使用 docx-js 庫
   - 從頭開始構建文檔
   - 導出為 .docx 格式

3. 編輯工作流：
   - 解包現有文檔
   - 直接修改 XML
   - 每次更改後驗證
   - 完成時重新打包

{
  "skills": ["pdf-processing"],
  "query": "從此 PDF 文件中提取所有文本並將其保存到 output.txt",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "使用適當的 PDF 處理庫或命令行工具成功讀取 PDF 文件",
    "從文檔中的所有頁面提取文本內容，不遺漏任何頁面",
    "以清晰、可讀的格式將提取的文本保存到名為 output.txt 的文件"
  ]
}

**壞例子：太多選擇**（令人困惑）：
"您可以使用 pypdf、或 pdfplumber、或 PyMuPDF、或 pdf2image、或..."

**好例子：提供默認值**（帶逃生艙口）：
"使用 pdfplumber 進行文本提取：
```python
import pdfplumber
```

對於需要 OCR 的掃描 PDF，改用 pdf2image 和 pytesseract。"

def process_file(path):
    """處理文件，如果不存在則創建它。"""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # 創建具有默認內容而不是失敗的文件
        print(f"文件 {path} 未找到，創建默認值")
        with open(path, 'w') as f:
            f.write('')
        return ''
    except PermissionError:
        # 提供替代方案而不是失敗
        print(f"無法訪問 {path}，使用默認值")
        return ''

def process_file(path):
    # 只是失敗並讓 Claude 解決
    return open(path).read()

# HTTP 請求通常在 30 秒內完成
# 更長的超時考慮慢速連接
REQUEST_TIMEOUT = 30

# 三次重試平衡可靠性和速度
# 大多數間歇性故障在第二次重試時解決
MAX_RETRIES = 3

TIMEOUT = 47  # 為什麼是 47？
RETRIES = 5   # 為什麼是 5？

## 實用腳本

**analyze_form.py**：從 PDF 中提取所有表單字段

```bash
python scripts/analyze_form.py input.pdf > fields.json
```

輸出格式：
```json
{
  "field_name": {"type": "text", "x": 100, "y": 200},
  "signature": {"type": "sig", "x": 150, "y": 500}
}
```

**validate_boxes.py**：檢查重疊的邊界框

```bash
python scripts/validate_boxes.py fields.json
# 返回："OK"或列出衝突
```

**fill_form.py**：將字段值應用於 PDF

```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```

## 表單佈局分析

1. 將 PDF 轉換為圖像：
   ```bash
   python scripts/pdf_to_images.py form.pdf
   ```

2. 分析每個頁面圖像以識別表單字段
3. Claude 可以在視覺上看到字段位置和類型

bigquery-skill/
├── SKILL.md (概述，指向參考文件)
└── reference/
    ├── finance.md (收入指標)
    ├── sales.md (管道數據)
    └── product.md (使用分析)

使用 BigQuery:bigquery_schema 工具檢索表架構。
使用 GitHub:create_issue 工具創建問題。

**壞例子：假設安裝**：
"使用 pdf 庫處理文件。"

**好例子：明確關於依賴項**：
"安裝所需包：`pip install pypdf`

然後使用它：
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"