Files

T

2026-09-27 23:52:24 +08:00

5.4 KiB

Raw Permalink Blame History

name, description

name	description
yierp-cli	适用于 YIERP（源自 ERPNext v16）的数据访问与管理技能，支持通过配置 url、apikey、ApiSecret 完成查询、创建、更新、删除和自定义方法调用。

YIERP CLI 数据操作技能

这个技能用于访问 YIERP 系统中的业务数据与文档资源。YIERP 继承 ERPNext v16 的 Frappe / REST API 设计，因此可以使用标准的 HTTP API 方式进行 DocType 数据访问、文档操作和后端方法调用。

同步方向：本技能的工作副本位于项目 D:\git\giterp\yierp-script\.qoder\skills\yierp-cli\（自包含技能包，脚本在其 scripts/）。变更先更新工作副本，再同步到本仓库（本仓库脚本位于 tools/）。

适用目标

通过配置 url、apikey、ApiSecret 建立认证
支持 list、get、create、update、delete、method、whoami 等操作
适合脚本自动化、批量同步、业务查询、报表提取和业务集成
所有说明、注释、提示和输出都使用简体中文

参数顺序：--config / --url / --apikey / --apisecret / --timeout / --no-verify-ssl 为全局参数，必须写在子命令之前，否则会报 unrecognized arguments。

配置方式

配置解析优先级：命令行参数 > 环境变量（含 .env）> 配置文件。

1. .env 文件方式（推荐）

脚本从当前工作目录自动向上查找 .env（至含 .git 的项目根为止），加载 YIERP_URL / YIERP_APIKEY / YIERP_APISECRET，不覆盖已存在的系统环境变量：

YIERP_URL=https://yierp.example.com
YIERP_APIKEY=你的_api_key
YIERP_APISECRET=你的_api_secret

模板见技能包内 .env.example。凭证文件 .env 必须 gitignore、不入库、不随技能发布。

2. 配置文件方式

建议在项目中创建 .yierp/config.json：

{
  "url": "https://yierp.example.com",
  "apikey": "你的_api_key",
  "ApiSecret": "你的_api_secret",
  "timeout": 30,
  "verify_ssl": true
}

3. 环境变量方式

set YIERP_URL=https://yierp.example.com
set YIERP_APIKEY=你的_api_key
set YIERP_APISECRET=你的_api_secret

4. 命令行参数方式

python tools/yierp_cli.py --url https://yierp.example.com --apikey xxx --apisecret yyy list --doctype ToDo

关键命令

1. 检查当前登录用户

python tools/yierp_cli.py whoami

2. 查询列表

python tools/yierp_cli.py list --doctype ToDo --filters '{"status":"Open"}' --limit 20

3. 获取单条记录

python tools/yierp_cli.py get --doctype ToDo --name "TODO-00001"

4. 创建记录

python tools/yierp_cli.py create --doctype ToDo --data '{"description":"测试任务","status":"Open"}'

5. 更新记录

python tools/yierp_cli.py update --doctype ToDo --name "TODO-00001" --data '{"status":"Closed"}'

6. 删除记录

python tools/yierp_cli.py delete --doctype ToDo --name "TODO-00001" --yes

7. 调用自定义后端方法

python tools/yierp_cli.py method --method your_app.api.test --args '{"message":"hello"}'

8. 查看当前配置摘要

python tools/yierp_cli.py config

认证方式

YIERP 使用 Frappe / ERPNext 风格的 token 认证：

Authorization: token {apikey}:{ApiSecret}

因此，在访问 API 时，必须提供：

url：站点地址，例如 https://yierp.example.com
apikey：API 密钥
ApiSecret：对应的 API Secret

数据操作能力

查询类

list：根据 DocType 查询多条记录
get：获取单个文档详情
whoami：验证当前认证用户

写入类

create：新增数据记录
update：修改已有记录
delete：删除记录

业务集成类

method：调用后端方法或自定义逻辑
config：查看当前配置状态

安全要求

更新或删除前必须确认 DocType、记录名称和修改字段。
ApiSecret 为敏感信息，必须仅保存在本地配置中，不得写入日志、截图或仓库。
若 YIERP 使用自签名证书，需关闭 SSL 校验或配置 verify_ssl: false。
最小权限原则：优先用 list 与 get 做验证，再执行写入操作。

失败处理

遇到失败时，优先检查以下问题：

URL 是否正确，站点是否可达
apikey 与 ApiSecret 是否匹配
DocType 名称是否存在
请求体 JSON 是否符合规范
API 路径是否正确，是否为 api/resource 或 api/method
SSL 证书错误是否需要使用 --no-verify-ssl
Windows GBK 控制台中文输出乱码：设置环境变量 PYTHONIOENCODING=utf-8 后重跑，数据本身不受影响

适用场景

客户、供应商、订单、发票、库存、出入库等数据查询
批量报表导出与任务调度
ERP 系统与 CRM、WMS、MES 等系统集成
调用 YIERP 自定义 Python 方法实现复杂业务逻辑

说明

本技能是为 YIERP（源自 ERPNext v16 的定制 ERP 系统）设计的通用接口封装。使用时应优先遵循：

站点配置优先：url 为核心入口
凭证配置优先：apikey 与 ApiSecret 为认证关键
最小动作原则：先查询再写入
安全确认原则：删除与更新必须确认目标后再执行

如果用户没有明确指定站点，默认使用配置文件中的 url。如果用户要求执行数据操作，请优先采用本技能提供的 CLI 脚本执行。

5.4 KiB Raw Permalink Blame History Unescape Escape