dsh-vn-biz

Readme

# dsh-vn-biz

**Bộ công cụ nghiệp vụ thị trường Việt Nam cho [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).** 3 tool giúp agent xử lý giấy tờ kiểu Việt Nam ngay trong chat: đọc số tiền VNĐ bằng chữ, tạo mã QR chuyển khoản, và tra cứu doanh nghiệp theo mã số thuế.

Không cần cấu hình API key, cài xong dùng luôn. Chỉ cần hỏi bằng ngôn ngữ tự nhiên, agent tự chọn đúng tool.

## Vì sao cần tool riêng thay vì để agent tự trả lời

Cả 3 việc trên agent đều có thể "tự làm" mà không cần tool — nhưng làm sai hoặc tốn kém hơn hẳn:

- **Độ chính xác.** Đọc số tiền tiếng Việt có nhiều luật ngoại lệ (`mốt`/`lăm`/`linh`, nhóm 3 số 0 nằm giữa như `1.000.000.005`) mà model rất hay tính sai khi số lớn — nhất là khi phải nhân/chia nhẩm nhiều nhóm cùng lúc. `amount_to_words` chạy một thuật toán cố định, luôn ra đúng kết quả, không phụ thuộc model "đoán" đúng hay sai.
- **Tránh bịa thông tin (hallucination).** Model không có database mã số thuế cập nhật — nếu để nó tự trả lời tên công ty theo MST, nó sẽ bịa ra một cái tên nghe hợp lý chứ không phải sự thật. `tax_code_lookup` luôn lấy dữ liệu thật từ API `api.vietqr.io`, đúng thì trả về, không có thì báo không tìm thấy, chứ không đoán.
- **Đúng chuẩn kỹ thuật.** URL ảnh QR VietQR có định dạng cố định (`bankId-accountNo-template.png?...`) — để model tự viết tay chuỗi này rất dễ sai thứ tự tham số hoặc quên encode, quét không lên QR. `vietqr_quicklink` build đúng chuẩn mỗi lần.
- **Tối ưu token.** Không có tool, model phải "suy nghĩ" từng bước để tự tính hoặc tự soạn chuỗi đúng định dạng, tốn token cho phần lý luận, và nếu sai còn phải sửa lại qua nhiều lượt hỏi-đáp. Có tool, một lệnh gọi trả thẳng kết quả đã đúng — vừa nhanh vừa rẻ.

## Demo thật

### Đọc số tiền bằng chữ

> **Bạn:** Đổi số tiền 15750000 sang chữ giúp mình

![amount_to_words trong dsh web](docs/screenshot-amount-to-words.png)

### Tạo mã QR chuyển khoản VietQR

> **Bạn:** Tạo QR chuyển khoản Vietinbank số 113366668888, tên NGUYEN VAN A, 500000đ, nội dung 'thanh toan hoa don thang 8'.

![vietqr_quicklink trong dsh web](docs/screenshot-vietqr.png)

### Tra cứu doanh nghiệp theo mã số thuế

> **Bạn:** Tra công ty mã số thuế 0100109106 giúp mình.

![tax_code_lookup trong dsh web](docs/screenshot-tax-lookup.png)

## Cài đặt

```sh
git clone <repo-url> dsh-vn-biz
cd dsh-vn-biz
npm install
npm run build
```

Cài vào một profile đang chạy:

```sh
dsh plugin --profile <ten-profile> add /path/to/dsh-vn-biz
```

Nhớ restart `dsh web` sau khi cài — danh sách plugin được compose lúc khởi động, server đang chạy sẵn sẽ không tự nhận plugin mới.

Muốn thử nhanh không cài hẳn vào profile:

```sh
pnpm dsh web --patch /path/to/dsh-vn-biz/cordis.patch.yml
```

## Cấu hình

```yaml
- insert:
    - id: vn-biz
      name: dsh-vn-biz
      config:
        taxLookupApiBaseUrl: https://api.vietqr.io/v2/business
```

## Ghi chú

- `tax_code_lookup` và `vietqr_quicklink` gọi API công khai bên thứ ba (`api.vietqr.io`, `img.vietqr.io`) — không cần key, nhưng cũng không có SLA uptime.
- `amount_to_words` chỉ nhận số nguyên không âm (VNĐ không dùng phần thập phân trong thực tế).

## License

MIT