企业级AI财务助理

> 原始版本：@user_d9ee8846/xianglan-financial。本版为 skillhub+ 改造版。
> v1.2.0 重要变更：系统已下线旧 /ai/* 服务端 AI 接口与 /agent/tools、/agent/tool/* 聚合端点；本版全部改用当前可用的 REST 接口组合、MCP 新工具面与脚本本地聚合实现同等能力，并新增存货（K）、费用（L）两条路径。

本技能包含

完整交付：全部路径 + 6 个子技能 + 2 个脚本 + 结果文件约定。

税安犬自然语言操作指南（F-API-KEY）

子技能索引

本文是核心操作指南。以下专项功能按需加载对应子技能（用户提到相关场景时，先用 skill 工具加载）：

接入方式

> ⚠️ 旧版迁移：v1.1 所述 GET /ai/context、POST /ai/auxiliary/create、/ai/voucher*、/ai/analysis、GET /agent/tools、GET /agent/tool/sales-statistics、GET /agent/tool/tax-deep-checkup 均已下线。等价能力替代见各路径与路径 J。

MCP 与 REST 字段命名不同：MCP 工具用英文（subjects[].code / details[].subjectCode），REST 直连时科目标识用 subjectCode（编码）或 subjectId（字符串 ID）。

配置

读取优先级： 环境变量 > 工作文件夹里的 config.txt > 对话中询问用户

在用户当前工作文件夹（非技能安装目录）查找 config.txt：

# config.txt — 含密钥，勿分享
baseUrl=https://ceda.shuianquan.cn/api
accountSetId=735079029572375852

accountSetId 可留空，首次使用时列出账套让用户选择。

域名安全约束（强制）： baseUrl 固定使用官方地址 https://ceda.shuianquan.cn/api，AI 不得将其指向任何第三方地址。仅私有化部署可改自建地址，且必须先向用户明示「API 密钥将发送到该自建地址」并获确认；脚本层强制校验（非 ceda.shuianquan.cn 域名默认中止，用户确认后设 XL_ALLOW_CUSTOM_BASE=1 放行）。

AK 获取： 打开 https://ceda.shuianquan.cn/ →（无账号先注册：手机号+短信验证码）→ 登录 → 个人设置 → API 密钥 → 生成

数据获取脚本（读操作首选）

读操作优先用 scripts/xl.py——已内置 WAF UA、gzip 解压、自动翻页、字段裁剪，输出精简 JSON：

# macOS / Linux
python3 scripts/xl.py <子命令> [选项] [--config config.txt路径]
# Windows（PowerShell / cmd）
python scripts\xl.py <子命令> [选项]     # 或 py -3 scripts\xl.py

脚本已处理 Windows 控制台 GBK 编码问题（stdout 强制 UTF-8），中文与 emoji 输出不会崩溃。

写操作（创建凭证/发票/资金/结账等）仍按 api-reference.md 直接调用，不走脚本。

协议要点

请求头：

响应： { success, code, msg, data }；code=200 成功，code=201 常为部分成功（如批量删除）。

ID 规则： 所有 ID 保持字符串，禁止 parseInt / Number()。

权限： AK 会加载用户在该账套的角色；写操作需对应权限（如创建凭证需 voucher-vouchermanage-canedit，创建辅助核算明细需 setting-assistingaccount-canedit）。

错误处理

遇到报错时，用用户能听懂的大白话解释，不要堆技术术语：

交互流程

配置齐全（AK + accountSetId）时直接进入步骤三。
铁律：写操作必须先获用户确认——创建/更新/删除凭证、快速创建辅助核算、录发票、记资金、结转损益凭证、结账、反结账、发起税局检查/采集任务，一律先预览、用户同意再执行。

步骤〇：读取配置

1. 读 config.txt 或环境变量
2. 有 accountSetId → xl.py context（或组合 REST，见路径 A 步骤三）→ 步骤三
3. 仅 AK → GET /account-sets → 步骤二
4. 无 AK → 步骤一

步骤一：注册与获取 AK

引导用户：打开 https://ceda.shuianquan.cn/ → 没有账号先点「注册」（手机号 + 短信验证码，免费试用）→ 登录 → 「个人设置 → API 密钥」生成 AK-xxxxxxxx。拿到 AK 后拉账套列表。

步骤二：选择账套

GET /account-sets，以表格展示（名称、会计准则、纳税人类型、当前账期）让用户选择，不得代选或默认第一个。

步骤三：获取上下文并路由

python3 scripts/xl.py context，展示账套名称与当前账期，按意图走路径：

能力总览：

路径 A：创建凭证

A1 收集业务描述

等用户描述，不替用户假设业务内容。

A2 匹配科目与辅助核算（强制）

1. 从 科目列表（xl.py context 输出，即 GET /subject 的 leaf=true 末级科目）匹配末级科目。
2. 提交科目标识： 优先 subjectCode（取自上下文 code）；若仅有 id 则用 subjectId（字符串）。二者勿混用猜编码。
3. 若该科目 auxiliaryAccounting 非空：必须为每个分类 ID 准备一条辅助核算，缺一不可。
4. 在对应 辅助核算[].details（MCP 为科目上的 auxiliaryIds + searchApi 检索明细）中按名称（或编码）匹配；匹配成功则记下 id/name。
5. 匹配失败时禁止跳过、禁止空 auxiliary、禁止臆造 id，必须走快速创建（A2a）后再预览。

A2a 快速创建辅助核算明细（匹配失败时强制）

业务里已有客户/供应商/部门等名称，但账套 辅助核算[].details 里没有对应项时：

识别科目所需分类 →（可选）确认名称/编码 → POST /accounting-category-details
→ 用返回的 id/code/name 填入该分录 details[].auxiliary[]
→ 再进入预览

步骤 5 的 auxiliary 元素模板：

{
  "categoryId": "<响应.categoryId>",
  "categoryType": "<响应.categoryType>",
  "id": "<响应.id>",
  "value": "<响应.id>",
  "code": "<响应.code>",
  "name": "<响应.name>"
}

MCP：listSubjects（科目+辅助核算类别）→ searchApi("辅助核算") + callApi 创建明细 → 写入 details[].auxiliary → draftVoucher 预览。
接口字段见 api-reference.md §4E。

A2b 构建预览

预览格式（必须）：

═══════════════════════════════════════════
  业务描述：{描述}
═══════════════════════════════════════════
  序号 │ 方向 │ 科目名称         │ 摘要         │ 金额
  ...
  （辅助核算：客户-华为技术 / 部门-财务部）
  借方合计：{x}  贷方合计：{x}  ✅ 借贷平衡
═══════════════════════════════════════════
  请输入 y 确认创建，n 取消：

有辅助核算的分录须在预览中展示辅助项名称。有附件：先 POST /upload/voucher，再构造 billList（见 api-reference.md §4A）。

A3 确认后提交

POST /voucher，code: 0 自动生成凭证号。展示返回的凭证字+号。
提交体中带辅助核算的分录必须已含完整 auxiliary[]（含真实 id）。

路径 B：读取报表

B1 映射 API

完整对照见 api-reference.md。

B2 补全参数

默认用账套 currentAccountDate 推导期间。showLastYearAmount 接口默认 0；用户要看上年同期时显式传 1（仅 lr/xjll）。

B3–B4 查询与展示

必须以 API 返回为准，禁止臆造数据。展示规则见 report-format.md。

B5 连续追问

资产负债表不平衡 → 试算平衡；某科目异常 → 余额表 → 明细账。

路径 C：查询凭证

C1 提取条件

voucherDate.start==end 时按整月匹配。

C2 查询

POST /voucher/list?page=1&pageSize=20&property=code&order=asc，voucherDate 必填。

last=false 时继续翻页。

C3 展示

列表：日期、凭证号、摘要、借贷合计、附件数、审核状态（auditMemberId 非空=已审核）。
详情：列表响应已含完整 details，一般无需再 GET /voucher/{id}；编辑前才需 GET 全量字段。

C4 后续

可引导查看详情、修改（PUT 全量）、审核、或基于业务新建凭证。

路径 D：发票（摘要）

录入： GET /invoice/business 选业务类型 → 预览 → POST /invoice（id=null）→ 可选 POST /invoice/upload/att。

按期间查询： POST /invoice/list/{IN|OUT}?page=&pageSize=，body {start, end}；加 voucherId:false 只查未生成凭证的发票（行内 voucherId=null 即未生成，voucher 显示"记-12"）。

批量生成凭证（需确认）：
1. GET /invoice/business?type=IN|OUT 取业务类型凭证模板（items/categoryItems：科目+方向+取数字段）
2. 按期间查未生成凭证发票；无业务类型的发票无法生成，先 POST /invoice/adapt/business-type 智能匹配
3. 本地按模板组装每张凭证的 VoucherDto（code:0 自动编号、tid 每张一个 uuid、invoiceId 或合并时 invoiceIds），按路径 A 预览格式展示，用户确认 y
4. POST /invoice/generate/voucher（body 为 VoucherDto 数组=批量）；响应 data 为空 map=全部成功，否则 {tid: 错误消息} 逐张重试
5. 重新查询列表确认 voucher 字段（接口不返回凭证号）

详情见 api-reference.md 附录 A。

路径 E：资金（摘要）

录入： GET /cashier/io + GET /cashier/account → 预览 → POST /cashier/journal。

按期间查询： 逐账户 POST /cashier/journal/list/{accountId}?page=&pageSize=，body {start, end}；加 vouched:2 只查未生成凭证的记录（vouched:1=已生成；行内 voucherId/voucherCode 判定）。注意剔除响应末尾 init=true 的期初行。

批量生成凭证（需确认）：
1. GET /cashier/account（账户科目 subjectId）+ GET /cashier/io（收支类型科目/凭证字 voucherWord）取科目映射
2. 按期间查未生成凭证记录（含转账，转账行借=转入科目/贷=转出科目；转账单另有 GET /cashier/transfer 列表与 POST /cashier/transfer 新增）
3. 本地组装 VoucherDto（code:0、tid uuid、businessIds:[日记账id]、businessType:'cashier'；收=账户借/对方贷，支=反向），预览后用户确认 y
4. POST /cashier/journal/generate/voucher（VoucherDto 数组=批量）；响应空 map=全部成功，否则按 tid 重试失败项
5. 以 vouched:1 重查确认 voucherCode

详情见附录 B。

路径 F：结账 / 账期

覆盖账期查询、期末检查、结转损益、正式结账与反结账。接口细节见 api-reference.md §7；MCP 见 mcp.md。

账期状态 status： 0 未结转未结账 → 1 已结转未结账（可结账）→ 2 已结账。

F1 查账期 / 结账状态

展示：年/月、status 中文含义、账套 currentAccountDate。

F2 期末检查

结账前按需执行（期间默认当前待结账月）：

向用户用白话汇报通过/失败项；失败时引导修账（试算→余额表→明细账），不要直接结账。

F3 结转损益

1. GET /checkout/profitCheck?year=&month=
2. 有 voucherItems → 按下方规则预览结转分录 → 用户确认后 POST /voucher
3. 仅有 voucherIds → 已结转，展示凭证即可
4. 皆无 → 无需结转

voucherItems → 凭证分录映射（强制）：

• subjectId / subjectCode：取自该项的 subjectId / code（字符串）
• summary：优先用项上的 summary，空则用「结转本期损益」
• 凭证顶层建议：carryForward: true（结转损益凭证）
• 有 voucherMergeItems 时：默认用 voucherItems（分方向）；用户要求「合并结转」再用 voucherMergeItems
• 借贷必须平衡后再提交；预览格式同路径 A

F4 正式结账

1. 确认 status=1
2. 强制检查均已通过
3. 用户明确确认后：GET /checkout/invoicing?year=&month=
4. 权限：checkout-checkoutmanage-cancheck

成功后说明：该月凭证已锁定，账期推进到下一月。

F5 反结账

1. 仅允许从最后已结账月往前：GET /checkout/unCheck?year=&month=（或 startDate+endDate 批量）
2. 用户明确确认后执行
3. 权限：checkout-checkoutmanage-canuncheck

F6 注意

• 写操作（结转凭证、结账、反结账）前必须用户确认
• 必须按月连续结账，不能跳月
• MCP 已连接时：查凭证/余额/明细账优先 MCP 工具；正式结账/反结账与期末检查走 REST

路径 G：批量建账套工作空间

用户想「为所有账套建工作空间 / 批量初始化账套目录 / 每个账套一个文件夹」时，引导运行技能安装目录下的脚本：

1. 前置： 当前工作文件夹有 config.txt（含 baseUrl 与 AK，无需 accountSetId）；也可用环境变量 XL_API_BASE / XL_API_KEY。缺 AK 时先走步骤一
2. 脚本行为（API 全为只读 GET）： 拉取全部账套 → 按账套名称建子文件夹（过滤非法字符，重名追加 ID 尾缀）→ 预填子级 config.txt（含该账套 accountSetId）与 README.md → 按该账套最近未结账期间（GET /checkout/last，失败回退 currentAccountDate）建 YYYY-MM 期间目录
3. 安全： 已有 config.txt 的子文件夹整目录跳过，不覆盖；向用户说明后运行
4. 完成后展示脚本汇总（新建/跳过/失败），并提示：进入对应子文件夹对话即操作该账套

路径 H：资产折旧

覆盖「检查是否需要折旧 → 计提折旧 → 凭证预览 → 创建 → 关联」。接口细节见 api-reference.md 附录 C。

期间状态 status： 1 待计提 → 2 已计算折旧（待生成凭证）→ 生成凭证后 voucherId 非空；4 无需折旧。

H1 折旧检查

GET /assets/depreciation?page=1&pageSize=20（或 GET /assets/checkDate 取下拉清单），找到目标期间行：

期末场景可用 GET /checkout/assetsCheck?year=&month= 一次验证「本期已折旧且已生成凭证、本期资产变动均已生成凭证」。

H2 计提折旧（需确认）

计提只做「计算+落明细」，不生成凭证：

• 单期：GET /assets/depreciation/{depreciationId}
• 批量跨期间：POST /assets/depreciation/batch?startDate=yyyy-MM-01&endDate=yyyy-MM-01

完成后期间 status→2（无明细则 →4）。可先 POST /assets/depreciation/detail（body {start, end}）或 GET /assets/depreciation/amount/{id} 查看本期折旧明细/总额。权限：fixedassets-fixedassets-card-candepreciation。

H3 折旧凭证（需确认）

1. 后端预览： GET /assets/depreciation/generate/voucher/{id}?type=merge（merge=按科目合并汇总；expand=逐资产展开），返回分录列表（summary/assetsSubjectCode/debitAmount|creditAmount/auxiliary），不创建凭证。科目取自资产卡片：借=折旧费用科目，贷=累计折旧科目；卡片未配置科目会报错，需先在资产卡片补齐
2. 按路径 A 预览格式展示分录，用户确认 y
3. POST /voucher 创建凭证（subjectCode 提交，code:0 自动编号，建议 voucherDate=期间月末）
4. 必须关联回写： GET /assets/depreciation/relate/{id}?voucherId={凭证id} —— 期间回写 voucherId，凭证打标 businessType="assets-depreciation"。

漏掉这步会导致期末资产检查不通过

权限：预览/关联 fixedassets-fixedassets-card-cancreatevoucher。

H4 注意

• 写操作（计提、创建凭证、关联）前必须用户确认；取消计提 GET /assets/depreciation/cancel/{id} 仅限未生成凭证的期间
• 删除已关联的折旧凭证会自动回滚期间状态（voucherId 置空、status 回 2），可重新生成
• /checkout/invoicing 正式结账不内联资产检查，结账前应主动跑 assetsCheck

路径 I：税务风险自检（只读体检）

金税四期「以数治税」口径的账载数据风险体检。全部只读查询，无任何写操作，无需确认即可执行；但数据量较大，开始前告知用户将拉取全年发票与账簿数据。

降级规则（强制）： 任一接口返回 403/404/无权限 → 跳过对应指标，在报告末尾列入「未检测项」，不得中断整体体检。

I0 优先：运行自检脚本

# macOS / Linux
python3 scripts/tax-risk-check.py [config.txt 路径] [--start 2026-01] [--end 2026-07] [--json out.json]
# Windows（PowerShell / cmd）
python scripts\tax-risk-check.py [config.txt 路径]

脚本读当前文件夹 config.txt（需 AK + accountSetId），默认期间=当前账期所在年 1 月~当前账期月；自动完成数据拉取、14 项指标计算、报告生成并打印体检报告（有 🔴 项时退出码为 2）。脚本能跑通时不要逐接口手动拉数；脚本不可用（无 python3）时才走下方手动流程。拿到报告后：向用户解读风险项含义、给整改建议（这层业务判断由 AI 完成，脚本只算指标）。

I1-I4 详细流程

详见子技能 skills/tax-risk-check.md，包含：
- 确定检查范围
- 拉取数据接口清单
- 14 项风险指标及默认阈值
- 体检报告输出格式

典型触发词： 税务风险、风险自检、体检、稽查自查、做个风险体检

路径 J：聚合统计与开票识别

J1 销售额统计（只读）

基于正常状态销项发票的多维统计：

首选脚本（本地聚合，支持任意区间与客户维度）：

python3 scripts/xl.py sales-stats --dimension byCustomer --start 2026-01-01 --end 2026-06-30 --top 10

服务端逐月汇总（免翻页，看全年趋势）： GET /invoice/summary/year?year=2026 返回 12 个月列表（每月进/销项张数、含税、不含税、税额、是否已结账；含无发票月份占位）。当期单月汇总用 GET /invoice/summary?period=yyyy-MM-01。

注意： summary 系接口不剔除作废/红冲发票（全口径）；脚本 sales-stats 只统计正常状态发票，两者口径不同，汇报时说明。

J2 税局漏报检查（taxCheck，只读查询 + 受控发起）

查询税局口径的税种申报/缴款状态明细：

python3 scripts/xl.py tax-checkup            # 全部明细并按风险分组
python3 scripts/xl.py tax-checkup --state 0 --paystate 0   # 只看未申报且未缴款

数据来源： GET /taxCheck/details（当前账套漏报检查明细）。行字段：taxProjectName（税种）、fromDate/toDate（税款属期）、state（0=未申报 1=已申报）、payState（-1=无需缴款 0=未缴款 1=已缴款）、bqybtseSj（本期应补退税额）、sbqx/jkqx（申报/缴款期限）、message（税局提示）。脚本自动分组为「漏报风险 / 已申报未缴款 / 其他」。

没有数据时： 说明尚未发起过检查。发起检查 POST /taxCheck/start（写操作：向税局发起异步任务，结果整体替换明细；进行中重复发起会提示任务进行中）。必须先向用户确认，确认后用 raw 调用，并提示「发起后稍等片刻再重查」；任务进度可查 GET /declareTask（申报任务列表）。

与路径 I 的区别：路径 I 是本地脚本按金税四期口径算 14 项指标（发票+账簿数据）；J2 是税局侧已有检查数据（漏报/缴款状态）。用户说「税务风险体检」默认走路径 I；说「查漏报/哪些税没报」走 J2。

J3 开票 AI 识别（服务端 AI）

前置：识别能力由服务端统一配置（Kimi API），无需用户个人配置；报错时提示用户联系服务商确认识别功能已开通。识别结果用于销项发票录入（见 skills/invoice-management.md），购买方信息确认后再录。

J4 内置接口目录检索（能力兜底）

本技能文档未覆盖的系统功能（如 BI 报表、申报任务、基础档案、备忘、审计日志、工资凭证等），先查内置目录再直调：

python3 scripts/xl.py tools --keyword 发票    # 按关键词过滤（匹配名称/路径/描述，可逗号分隔多词）
python3 scripts/xl.py tools --full           # 含完整描述

目录与系统服务端智能体同源（构建期从全部 Controller 生成，共 655+ 条），每条含 name（工具名）、method、path（REST 路径）、readOnly、desc。按 path + method 组装请求（query 参数进 URL，body 参数放 JSON），用 raw 透传或 curl 调用；readOnly=false 是写操作，必须预览确认后调用。目录不含参数明细，参数结构可参考 api-reference.md 对应章节或先用小请求试探。

J5 已下线能力（v1.1 → v1.2 迁移）

路径 K：存货（v1.2 新增）

进销存查询与凭证。接口细节见 api-reference.md 附录 F。

存货档案： GET /stocks?page=&pageSize=&filter=（含实时库存数量、编码/名称/规格过滤）。

核心只读报表：

发票匹配生成存货单据（需确认）： POST /invoice/match/items（body 发票 ID 列表，返回待匹配明细）→ 预览匹配关系 → POST /invoice/match/generate。

存货单据生成凭证（需确认）： POST /inventory/bill/{id}/voucher 生成单张；POST /inventory/bill/voucher/preview 预览。期末成本：POST /inventory/bill/calculate-cost（月末一次计算成本）、GET /inventory/cost/period/{year}/{month} 查成本期间状态。

路径 L：费用（v1.2 新增）

费用单查询与凭证。接口细节见 api-reference.md 附录 G。

查询：

生成凭证（需确认）： POST /expense/generate/voucher（body 为 VoucherDto 列表，关联费用单 ID；组装方式同路径 D 发票批量生成凭证）。

相关： 工资凭证生成 POST /salary/voucher/generate（body {salaryId, templateId, voucher}，模板列表 GET /salary/voucher/template）——工资表生成记账凭证并重算科目余额，同样需预览确认。

参考文件

配套资源

• scripts/xl.py
• scripts/endpoints.json
• scripts/tax-risk-check.py
• api-reference.md
• report-format.md
• mcp.md
• skills/（ai-analysis / tax-setup / invoice-collection / invoice-management / tax-filing / tax-risk-check）
• examples.md