Yuanjie Basics

---
name: yuanjie-basics
description: How to use the Yuanjie BFP read-only tools at all - picking a tool, passing parameters, and what this connector cannot do. Read this before the per-product skills.
description_zh: 这批工具怎么用的总纲：怎么挑工具、参数怎么给、做不到什么。四篇产品线说明书的前置。
description_en: Ground rules for the Yuanjie BFP read-only tools - tool selection, parameter passing, and hard limits.
version: 1.0.0
author: 原界
---

# 原界 BFP 业务数据查询

这批工具连到用户所在企业的原界 BFP 系统，**全部是只读查询**——不提交单据、
不改库、不发消息。用户要"提交"「审批」「补卡」这类动作时，本连接器做不到，
如实告诉用户即可，不要用查询工具去凑。

## 什么时候用

用户问的是**他所在公司的业务数据**时用。典型的说法：

- 考勤：我这个月有几次迟到 / 还有多少年假 / 谁今天没来
- 招聘：还在招哪些岗位 / 这个候选人什么情况 / 今天有几场面试
- 进销存：某个商品现在还有多少库存 / 这张调拨单到哪一步了
- 人事：某部门有多少人 / 缺编多少 / 某人的档案
- 品牌授权：这个防伪标码流到哪儿了 / 某客户标费额度还剩多少

问的是通用知识、或别家公司的事，不要调这些工具。

## 怎么挑工具

工具名就是能力 id 把点号换成下划线，例如 `attendance_anomaly_plan`。
每把工具的 description 是它的完整用途说明，**照着选，别按名字猜**——
名字里的模块前缀（`recruit_` / `erp_` / `hhr_`）只表示它属于哪条产品线，
同一件事在不同产品线下可能有两把不同的工具，用户所在企业只开通了其中一条。

调不到想要的数据时，先看返回里的说明，再换一把工具，**不要反复重试同一把**。

## 参数怎么给

- **必填的一定要给全。** 缺参数会直接失败，不会用默认值凑。
- 大部分参数的类型在声明里没标死，一律**按用户说的原文传字符串**。
  工号、单号、编码这类看起来像数字的，也当字符串传——它们可能有前导零。
- 日期没有统一格式要求时，传 `YYYY-MM-DD`。
- 有 `action` 参数的工具，取值**只能从 enum 里选**，传别的会被拒绝。

## 三件做不到的事

1. **不能提交任何单据。** 补卡、请假、加班、审批、调拨——一律做不到。
   用户要提交时，告诉他去原界客户端或飞书里操作。
2. **不能发消息、不能建文档。**
3. **查不到别人的私密数据。** 所有查询都以当前授权用户的身份和权限执行，
   他看不到的，这里也看不到——返回"无权限"时不是工具坏了，是确实不该看。

## 失败了怎么说

工具返回里带 `isError` 时，把失败原因**原样转述给用户**，别改写成
"系统繁忙"。原因通常是三类之一：参数缺了或不对、这个企业没开通这条产品线、
当前用户没有这项数据的权限。三类的处置完全不同，含糊掉用户就不知道该做什么。