浪潮云会计

概述

易云云会计使用指南

浪潮云会计是面向小微企业的专业云财务 SaaS 应用，通过本地 Python 脚本直接调用后端 API。认证登录通过本地 Python 脚本完成。

快速配置（一次性，已安装可跳过）

保持最新版本

初始化命令 setup.py init 会自动检查 SKILLHUB 上的最新版本。如果输出 JSON 中包含 update_notice 字段，说明当前版本已过时。

处理流程：

1. 向用户说明：「当前 SKILL 版本 {current} 已过时，建议更新到 {latest} 以获得最佳体验。是否现在更新？」（使用 update_notice 中的 current 和 latest 值）
2. 用户同意 → 依次执行以下两条命令：

python {SKILL_DIR}/scripts/setup.py upgrade

升级成功后，重新执行初始化：

python {SKILL_DIR}/scripts/setup.py init

1. 用户拒绝 → 忽略 update_notice，直接使用当前初始化结果继续业务操作

升级输出（JSON）：

• 成功：{"success": true, "version": "<新版本号>"}
• 失败：{"success": false, "error": "<错误描述>"} → 告知用户升级失败，可稍后重试或前往 SKILLHUB 手动更新

初始化（首次使用时执行一次，同一会话内不重复）

SKILL.md 文件所在目录即为 SKILL_DIR。执行以下 1 条命令 完成全部初始化。

⚠️ 同一会话内只执行一次初始化。 如果当前会话中已经执行过此命令，直接复用已有结果，不要重复执行。

python {SKILL_DIR}/scripts/setup.py init

此命令自动完成：

1. 版本自检（检查 SKILLHUB 是否有新版本，有则在输出中附加 update_notice）
2. 读取本地凭据（userid/uuid）
3. 查询并缓存公司配置（dbid/compid/serviceId 等）

成功输出（JSON）：包含 userid、uuid、entry_url（回复末尾「前往云会计」链接，直接使用）、env（当前运行环境，含 base_url 与 web_url）、公司配置信息和运行时路径（python_path、scripts_dir）。记录这些值到上下文中，后续所有业务调用直接使用。如果裸命令找不到，使用 python_path 的绝对路径。

持久化文件：初始化结果同时写入磁盘文件，当上下文中丢失这些值时，直接读取文件恢复，无需重新执行初始化：

• 凭据：{SKILL_DIR}/.credentials.json（含 userid、uuid、host；非正式环境追加环境后缀，如 .credentials.test.json，不同环境互不覆盖）
• 公司配置：{SKILL_DIR}/.company_config.json（含 dbname、dbid、compid、service_id 等）

报错（无凭据）→ 向用户收集手机号后执行 send-code，系统自动判断老用户/新用户并引导后续流程。详见 references/auth.md。

账套切换：脚本自动检测凭据变化。如果用户切换了账套（凭据 userid/uuid 与缓存不一致），会自动重新查询公司配置。

强制刷新缓存：如果需要强制刷新公司配置缓存（如缓存数据异常），使用：

python {SKILL_DIR}/scripts/setup.py init --refresh

初始化完成，等待用户的业务指令。

场景路由表

根据任务场景，读取对应参考文档获取工具参数、调用示例和业务规则。

脚本命名规则：每个业务域独立一个脚本，位于 {SKILL_DIR}/scripts/ 目录下。

常见工作流

以下工作流已预编排好完整步骤，当用户需求匹配时，进入对应参考文档按步骤执行。

调用方式

认证通道：本地 Python 脚本

python {SKILL_DIR}/scripts/credentials.py check   # 检查凭据是否存在
python {SKILL_DIR}/scripts/login.py               # 登录（需短信验证码）

业务通道：Python 脚本直调

工具参数和调用示例详见场景路由表中对应的参考文档。

简单参数直接用 --key value：

python {SKILL_DIR}/scripts/subjects.py query --kmsx 01

含 JSON 参数使用 --args-file（避免 shell 引号/编码问题）：

# 1. 将 JSON 参数写入临时文件
# 2. 执行：
python {SKILL_DIR}/scripts/invoice.py save --fplx jxfp --oper isnew --args-file <path>

支持批量调用（一次处理多条记录）：

python {SKILL_DIR}/scripts/call_api.py --batch-file <path>

完整使用说明、批量配置格式和响应结构见 references/api-template.md。

响应区分：返回值含 success: false → 脚本层出错；无 success 字段 → 后端原始响应，按 status 字段判断（1=成功）。

核心规则

数据安全

• 先查后增删：修改/删除前先查询确认目标数据状态
• 删除需谨慎：确认无关联下级数据、无发生额、无余额
• 不猜测数据：所有值必须来自查询结果或用户明确提供

依赖命令定位（"找不到"或"崩溃"时的处理）

setup.py init 成功即证明 python 已安装可用。初始化输出中包含 python_path 字段，记录了实际可用的绝对路径。如果后续使用裸命令（python）时遇到以下错误，禁止重新安装依赖：

• "not found" / "找不到命令"：当前 shell 的 PATH 未包含该命令
• segfault / access violation / 崩溃：命令存在但版本损坏或不兼容

处理步骤（按优先级）：

1. 使用初始化输出的路径：直接使用 python_path 的绝对路径执行命令
2. 全局搜索：如果初始化输出的路径不可用，执行 where python（Windows cmd）或 which -a python（git bash / Linux）
3. 使用绝对路径：选定后，后续该命令统一使用此绝对路径

原因：不同 Agent 的 shell 环境 PATH 不同，"找不到"或"崩溃"通常是 PATH 或版本问题，不代表未安装。

会话上下文复用

初始化结果已持久化到磁盘文件。工作流中需要 userid、uuid、host、dbid、compid、service_id 等值时：

• 优先使用当前上下文中已有的值
• 上下文丢失时直接读取 {SKILL_DIR}/.credentials.json 和 {SKILL_DIR}/.company_config.json 恢复，无需重新执行 setup.py init
• 仅当接口返回凭据过期信号时才需要重新执行初始化

认证与凭据

• 每次调用必传 userid、uuid 和 host（脚本自动从凭据文件读取，无需手动传入）
• 凭据有效期约 1 小时，过期后需重新登录
• 过期信号：status≠1 且 info 含"过期/失效/登录/expired/unauthorized"
• 不自动获取验证码：让用户查看短信并告知验证码

参数规范

• 大部分参数为字符串类型
• 科目编码：一级 4 位（如 1001），二级在父级后加 3 位（如 1001001），依次类推
• fullname 必须包含从一级到当前级的完整路径，用 - 连接（如 "库存现金-金库"）

不支持的能力

用户请求的功能在当前脚本中找不到时，告知用户该功能暂未实现并记录，待后续开发扩展。不编造或猜测不存在的接口或参数。同时在回复末尾附加产品页面链接（见下方"回复尾部链接引导"的场景 B）。

回复尾部链接引导

每次回复末尾，根据场景附加一条产品页面引导链接。链接直接取脚本输出的 entry_url 字段（setup.py init、login.py 的 login / register / add-base / auto-login / switch-base 均会返回），不要自己拼接、不要硬编码域名。

规则：

• 每次回复只附加一条，根据场景选择 A 或 B
• {entry_url} 使用脚本输出中 entry_url 的原值（已含 userid/uuid 查询参数），直接使用，不要改写或重新拼接
• 上下文中没有 entry_url 时（如新会话），执行 python {SKILL_DIR}/scripts/setup.py init 重新获取（输出含 entry_url 与 env.web_url）
• 不要硬编码域名（正式与测试环境不同）