# Littlebeaver Invoice Assistant

> 读取并分析本机小河狸发票助手中的数据。当用户要求连接小河狸发票助手、查询发票台账或明细、选择公司、统计进销项、分析客户/供应商/商品排行、查看月度开票趋势、汇总税额，或查询已归档电子发票附件时使用。通过应用的 localhost Skill API 在本机处理数据。

- Skill: `littlebeaverstudio/littlebeaver-invoice-assistant` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add littlebeaverstudio/littlebeaver-invoice-assistant`
- Raw SKILL.md: https://api.skillmd.com/api/skills/littlebeaverstudio/littlebeaver-invoice-assistant/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Finance & Business
- License: 小河狸非转售许可 1.0（企业内部使用免费，转售收费需授权）
- Author: LittleBeaverStudio (https://skillmd.com/u/littlebeaverstudio)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/littlebeaverstudio/littlebeaver-invoice-assistant

---


## 许可与使用范围

本 Skill 采用「小河狸工作室非转售许可 1.0」，完整条款见本目录 `LICENSE` 文件。

- ✅ **免费使用**：
  - 个人学习、研究或个人事务；
  - **企业内部使用**——某一组织（无论是否为营利单位）为**其自身**业务运营而使用，包括内部办公、内部财务与会计处理、内部管理与报表、内部系统集成；同一控股关联实体使用视同内部使用。
- ✅ 可为上述用途自行修改本 Skill。
- ❌ **须另行取得书面授权**：对外销售、出租、许可；集成进对外收费的产品或服务；托管 / SaaS / 代运营；打包进收费课程、付费社群或付费安装包；收费的实施与咨询培训；**以及利用本 Skill 向任何第三方交付成果或提供服务**（含代理记账、为客户提供账目或报表服务等）。
- 📌 **区分标准只有一条**：**是否以本 Skill 向本组织之外的第三方交付成果或提供服务**。仅为自身业务使用 → 免费；向第三方交付或服务 → 需授权。
- 📌 再分发须保留本许可、版权声明与来源：小河狸工作室 LittleBeaverStudio · https://littlebeaver.top

**商业授权申请**：https://littlebeaver.top （邮箱 yk.niu@outlook.com）


# 小河狸发票助手 Skill

许可证：小河狸工作室非转售许可 1.0（企业内部使用免费，转售收费需授权，全文见 LICENSE）

通过用户本机运行的“小河狸发票助手”桌面应用读取发票数据。确保应用与智能体运行在同一台电脑上。仅调用本机 API，不通过本 Skill 上传发票数据。

默认使用简体中文回答。金额默认按人民币格式显示并保留两位小数；使用“开具”“取得”“进项”“销项”“价税合计”“作废”等中国财税常用术语。除非用户明确要求，否则不要把台账计算结果表述为最终应纳税额或纳税申报结论。

## 连接应用

1. 优先使用 `scripts/invoice_assistant_client.py`。
2. 用户提供地址时，传入 `--base-url http://127.0.0.1:<port>`。
3. 用户未提供地址时，扫描 `http://127.0.0.1:8876` 至 `http://127.0.0.1:8895`，并通过 `/api/metadata` 自动发现应用。
4. 自动发现失败时，请用户先打开“小河狸发票助手”，然后重试。

可选环境变量：

- `INVOICE_ASSISTANT_BASE_URL`：指定应用地址，例如 `http://127.0.0.1:8876`。
- `INVOICE_ASSISTANT_PORTS`：指定逗号分隔的端口或端口范围，例如 `8876-8895,9000`。

## 常用查询

在 Skill 目录中运行：

```bash
python scripts/invoice_assistant_client.py info
python scripts/invoice_assistant_client.py companies
python scripts/invoice_assistant_client.py summary --company-id 1 --start 2026-01-01 --end 2026-06-30
python scripts/invoice_assistant_client.py invoices --company-id 1 --keyword 作废 --page-size 100
python scripts/invoice_assistant_client.py items --company-id 1 --keyword 咨询服务
python scripts/invoice_assistant_client.py attachments --company-id 1
python scripts/invoice_assistant_client.py open-attachment --attachment-id 123
python scripts/invoice_assistant_client.py rankings --company-id 1 --limit 10
```

处理自然语言分析请求时，先获取满足问题所需的最小数据集：

- 选择公司：运行 `companies`。
- 汇总金额和月度趋势：运行 `summary`。
- 分析客户、供应商和商品排行：运行 `rankings`。
- 核查具体发票：运行 `invoices`，按需设置 `keyword`、`start`、`end`、`direction` 和分页参数。
- 分析商品或服务明细：运行 `items`。
- 查询已归档电子发票：运行 `attachments`，读取匹配的 PDF/OFD/XML 元数据。仅在用户明确要求打开本机文件时运行 `open-attachment`。

## API 规则

使用以下本机 Skill API：

- `/api/skill/health`
- `/api/skill/info`
- `/api/skill/companies`
- `/api/skill/summary`
- `/api/skill/invoices`
- `/api/skill/items`
- `/api/skill/attachments`
- `/api/skill/attachments/<id>/open`
- `/api/skill/rankings`

各接口支持的筛选参数不同：

- `company_id`：可重复传入。
- `start` 和 `end`：使用 `yyyy-mm-dd` 格式。
- `direction`：使用 `开具` 或 `取得`。
- `keyword`：对发票和明细执行模糊搜索。
- `page` 和 `page_size`：控制明细分页。
- `limit`：控制排行数量。
- `invoice_id`：按发票主表 ID 筛选附件。
- `file_type`：使用 `PDF`、`OFD` 或 `XML`。

`summary` 和 `rankings` 接口排除状态中包含“作废”的发票；明细接口保留所有状态，以便核查作废或异常发票。

附件响应包含文件类型、文件名、发票号码、公司、导出时间、文件大小、文件是否存在以及 `open_api` 路径，不暴露本机绝对路径。打开附件只调用用户本机的默认应用，不上传文件内容。

需要完整字段说明时，读取 `references/api.md`。

## 分析要求

回答财务问题时，明确说明所选公司、日期范围以及是否排除作废发票。

分析“哪些客户开票下降明显”等问题时，先读取汇总或排行数据；需要精确计算降幅时，再按月读取发票明细并比较相邻期间。区分发票台账测算与正式纳税申报结果。