技能创建者的最佳实践

<!-- 过于冗长 — 代理已经知道 PDF 是什么 -->
## 提取 PDF 文本

PDF（便携式文档格式）文件是一种包含
文本、图像和其他内容的常见文件格式。要从 PDF 中提取文本，你需要
使用一个库。推荐使用 pdfplumber，因为它能很好地处理大多数情况。

<!-- 更好 — 直接切入代理独自无法知道的内容 -->
## 提取 PDF 文本

使用 pdfplumber 进行文本提取。对于扫描文档，回退到
使用 pytesseract 的 pdf2image。

```python
import pdfplumber

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

## 代码审查过程

1. 检查所有数据库查询是否存在 SQL 注入（使用参数化查询）
2. 验证每个端点上的身份验证检查
3. 查找并发代码路径中的竞态条件
4. 确认错误消息不泄露内部细节

## 数据库迁移

确切运行此序列：

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

不要修改命令或添加额外标志。

<!-- 选项太多 -->
你可以使用 pypdf、pdfplumber、PyMuPDF 或 pdf2image...

<!-- 清晰的默认值带逃生通道 -->
使用 pdfplumber 进行文本提取：

```python
import pdfplumber
```

对于需要 OCR 的扫描 PDF，改用带有 pytesseract 的 pdf2image。

<!-- 具体答案 — 仅对此确切任务有用 -->
在 `customer_id` 上将 `orders` 表连接到 `customers`，过滤
`region = 'EMEA'`，并对 `amount` 列求和。

<!-- 可重用方法 — 适用于任何分析查询 -->
1. 从 `references/schema.yaml` 读取模式以查找相关表
2. 使用 `_id` 外键约定连接表
3. 将用户请求中的任何过滤器应用为 WHERE 子句
4. 根据需要聚合数字列并格式化为 markdown 表格

## 陷阱

- `users` 表使用软删除。查询必须包括
  `WHERE deleted_at IS NULL`，否则结果将包含已停用的账户。
- 用户 ID 在数据库中是 `user_id`，在 auth 服务中是 `uid`，
  在 billing API 中是 `accountId`。这三者指代相同的值。
- 只要 Web 服务器运行，`/health` 端点就返回 200，
  即使数据库连接断开。使用 `/ready` 检查完整
  服务健康状态。

## 报告结构

使用此模板，根据具体分析需要调整部分：

```markdown
# [分析标题]

## 执行摘要
[关键发现的单段概述]

## 关键发现
- 发现 1 附带支持数据
- 发现 2 附带支持数据

## 建议
1. 具体可操作的建议
2. 具体可操作的建议
```

## 表单处理工作流

进度：
- [ ] 步骤 1：分析表单（运行 `scripts/analyze_form.py`）
- [ ] 步骤 2：创建字段映射（编辑 `fields.json`）
- [ ] 步骤 3：验证映射（运行 `scripts/validate_fields.py`）
- [ ] 步骤 4：填充表单（运行 `scripts/fill_form.py`）
- [ ] 步骤 5：验证输出（运行 `scripts/verify_output.py`）

## 编辑工作流

1. 进行编辑
2. 运行验证：`python scripts/validate.py output/`
3. 如果验证失败：
   - 审查错误消息
   - 修复问题
   - 再次运行验证
4. 仅在验证通过时继续

## PDF 表单填充

1. 提取表单字段：`python scripts/analyze_form.py input.pdf` → `form_fields.json`
   （列出每个字段名称、类型以及是否必填）
2. 创建 `field_values.json` 将每个字段名称映射到其预期值
3. 验证：`python scripts/validate_fields.py form_fields.json field_values.json`
   （检查每个字段名称是否存在于表单中，类型是否兼容，以及
   必填字段是否缺失）
4. 如果验证失败，修订 `field_values.json` 并重新验证
5. 填充表单：`python scripts/fill_form.py input.pdf field_values.json output.pdf`