yscli — YonSuite CLI

YonSuite 业务数据查询与分析命令行工具。查询走 YonSuite API，输出支持表格/JSON/CSV/pretty。

所有已验证的 API 路径、方法、字段见 references/api-path-reference.md。

yscli 已全局安装（pip install -e），直接调用。

配置

| 环境变量 | 必需 | 说明 | |---------|------|------| | YONSUITE_APP_KEY | 是 | App Key | | YONSUITE_APP_SECRET | 是 | App Secret | | YONSUITE_TENANT_ID | 是 | 租户 ID |

可选：YONSUITE_GATEWAY_URL、YONSUITE_TOKEN_URL、YONSUITE_HTTP_TIMEOUT、YONSUITE_MAX_RETRIES。

🔥 快捷命令（高频业务一键直达）

# 销售
yscli weekly-sales                  # 本周销售
yscli monthly-sales                 # 本月销售

# 采购与库存
yscli monthly-purchase              # 本月采购
yscli current-stock                 # 现存量

# 生产
yscli monthly-production            # 本月生产

# CRM
yscli opportunities                 # 商机列表

# 基础档案（支持 --name 模糊搜索）
yscli search-customer --name 示例客户    # 搜索客户
yscli search-vendor --name 示例客户      # 搜索供应商
yscli search-product --name 树莓     # 搜索物料

📋 API 命令（元数据驱动）

yscli sales order list --params '{"pageIndex":1}'
yscli purchase order list --params '{}'
yscli production order list --params '{}'
yscli stock current query --params '{}'
yscli crm opportunity list --params '{}'
yscli archive customer list --params '{}'
yscli archive vendor list --params '{}'
yscli archive product list --params '{}'
yscli archive org list --params '{}'

🛠️ Raw API（万能兜底）

yscli api POST /yonbip/sd/voucherorder/list --data '{"pageIndex":1}'

输出格式

--format table    （默认）
--format json
--format csv
--format pretty

业务数据分析完整链路

所有分析任务必须按以下三步走，不能跳过：

① 数据获取 → 用 yscli 拉取原始数据

yscli weekly-sales --format json > /tmp/data.json
yscli monthly-purchase --format json > /tmp/purchase.json

数据获取铁律：API 端过滤优先！

用 simpleVOs 按 vouchdate 做 between 过滤，直接在 API 端筛好
禁止全量拉取再在 Python 端本地过滤——15MB vs 60KB 的差距
列表查询用 --page-all 自动翻页拉全量，不要手动翻页

② 专业分析 → 加载 data-analysis skill，按它的流程来：

先问决策 — 这个分析要支撑什么决策？什么结论会改变做法？
锁死指标口径 — 实体、粒度、分子/分母、时间窗口、筛选条件
算数 — 汇总、对比、趋势、分布
做压力测试 — 对比基线、敏感性分析、检查陷阱
出结论 — 答案 → 证据 → 置信度 → 局限性 → 建议行动

不加载 data-analysis skill 就直接算数，输出的是算术不是分析。

③ 出 HTML 报告 → 加载 html-presentation skill，按品牌规范生成

不生成 HTML 报告直接贴文本，算交一半的活。

HTML 报告生成

所有数据分析结果都必须生成 HTML 报告（用友品牌风格）。依赖 html-presentation skill。固定模板参考：

| 模块 | 模板 | |------|------| | sales / purchase / production | references/sales-report-template.html / purchase-report-template.html / production-report-template.html | | 价格分析 | references/price-analysis-template.html | | 库存总览 | references/inventory-report-template.html | | 客户销售分析 | references/customer-sales-analysis-template.html |

步骤：

加载 skill_view('html-presentation') 获取配色/字体/Logo 规范
加载对应模板 skill_view('ys-data-search', file_path='references/...') 填充
Logo 资产见 html-presentation skill 的 references/
输出路径：~/Documents/YonSuite报告/{模块}分析报表_YYYY_MM.html
生成后 open

HTML 报告规范：

图表数：必须 4 张图，2×2 网格布局（每日趋势、完工率排行、开工/未开工、完工/未完工）
图表工具：优先用 chart-mcp（mcp_chart_generate_bar_chart 等），不可用时回退 Chart.js CDN
分析维度：至少包含计划量/完工量/入库量三个维度的对比
生产分析：按 vouchdate（制单日期）过滤，加开工状态（OrderProduct_startQuantity）和完工状态（OrderProduct_realFinishStatus）列

关键原则：加载 html-presentation 后再写样式，不凭记忆写。

PPT 翻页 HTML 强制参考：技能介绍/产品说明类 PPT 翻页 HTML，必须加载 references/yonsuite-skill-intro-style.md 并严格遵循其样式体系（slides-wrapper + translateX 横滑机制、#FAFAFA 卡片风格、居中三色渐变条、左上角 Logo、底部圆点指示器）。不允许自由发挥或使用 html-presentation 技能中的 deck + scale() 旧规范。

图表生成

所有分析报告的图表使用 chart-mcp（@antvis/mcp-server-chart）生成，不内嵌 Chart.js CDN，不使用 chart_helpers 脚本。

chart-mcp 已配置在 ./config.yaml 的 mcp_servers 中，工具以 mcp_chart_* 前缀提供（如 mcp_chart_generate_bar_chart、mcp_chart_generate_line_chart、mcp_chart_generate_pie_chart 等 25+ 种）。

调用方式：准备 labels + values 数组，调用对应的 MCP 工具即可生成图表。

金额字段坑（重要）

isSum=False（明细行级）查询时：

realMoney ＝实收金额 ✅ 有效
totalMoney ＝价税合计 ❌ 常为 0，不可靠
单价字段（salePrice/noTaxSalePrice）也常为 0

HTML 报告金额列用 realMoney，不要用 totalMoney。详见 references/sales-field-pitfalls.md。

输出列对照

字段详情见 references/ 下各模块笔记。

| 模块 | 主要列 | |------|--------| | sales | 单号(code)、日期(vouchdate)、客户(receiverCustId_name)、物料(productName)、数量(qty)、金额(realMoney)、状态(statusCode) | | purchase | 单号(code)、日期(vouchdate)、供应商(vendor_name)、物料(product_cName)、数量(qty)、金额(purchaseOrders_natSum/oriSum)、状态(bizstatus) | | production | 单号(code)、日期(vouchdate)、产品(OrderProduct_productName)、数量(OrderProduct_quantity)、完工数(OrderProduct_completedQuantity)、状态(status) | | stock | 物料(product_name)、编码(product_code)、组织(org_name)、仓库(warehouse_name)、现存量(currentqty)、单位(product_unitName) | | opportunity | 编码(code)、名称(name)、客户(customer_name)、预计金额(expectSignMoney)、阶段(opptStage_name)、负责人(ower_name)、日期(opptDate) | | customer | 编码、名称(name.simplifiedName)、分类、联系人、电话 | | vendor | 编码、名称、分类、联系人、电话 | | product | 编码、名称、型号、分类、单位 | | org | 编码、名称、类型(业务单元/部门)、状态 |

查库存的标准流程

查某物料现存量，两步：

查物料编码：yscli search-product --name <关键词>
查现存量：yscli current-stock

协作原则

查询范围精确：用户问什么模块就只查什么，不要自己扩展对比。过"不要过度思考"。
数据完整性：系统里的数据都是真实的，不排除异常值、不分类标签、不分"高值/常规"，所有数据一视同仁。
分析必出 HTML 报告：所有分析结论都必须输出用友品牌风格的 HTML 报告，不终端文本了事。
API 参数名不可跨模块类比：同类概念在不同模块参数名不同（库存过滤是 productn.code 而非 product_code）。不确定时查 iuap 开放平台文档，不从相似 API 猜。
字段名确认：不确定时先 page_size=1 拉一条原始 JSON 看实际 keys，不抄文档。
HTML 表格防横向溢出：多列表格必须用 table-layout: fixed + <colgroup> 固定列宽，外套 overflow-x: auto 容器。body 加 overflow-x: hidden。禁止 th, td { white-space: nowrap; }。
实时拉取，不走预生成：每次查数据直接调 yscli <快捷命令> 走 API 实时获取。
发现问题就修，不是列局限性：分析中发现的局限性先判断能否优化（分页限制→加 --page-all、过滤器缺失→改查询条件），能修直接动手，修不了的才列局限性。

适用场景

YonSuite 业务数据查询与分析 CLI 工具。通过 yscli 命令行查询销售/采购/生产/库存单据、客户/供应商/物料/组织档案、CRM 商机，支持日期筛选、模糊搜索，输出表格/JSON/CSV/pretty，自动生成用友品牌风格 HTML 分析报告。必加载此技能的场景：用户要查 YonSuite 业务数据——查销售订单、采购订单、生产工单、库存现存量、商机列表；查基础档案——客户、供应商、物料、组织；查价格分析、数据看板、分析报表；做数据分析并出 HTML 报告。即使只说'查一下销售数据'、'看下库存'、'这个月采购了多少'、'帮我出份报表'也应触发。三层指令体系：🔥 快捷命令：yscli weekly-sales 等，高频场景一键直达；📋 API 命令：yscli sales order list --params '{}'，元数据驱动的 API 调用；🛠️ Raw API：yscli api POST /path --data '{}'，万能兜底。不适用：非 YonSuite 平台的查询、纯财务凭证/账簿/总账（可能走其他技能）。不适用：YonSuite 系统配置、权限管理、审批流设置；非 YonSuite 系统的业务数据分析；纯用友品牌 PPT/HTML 样式生成（走 html-presentation / yonyou-pptx）。