香兰财务系统自然语言操作指南（F-API-KEY）

子技能索引

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

接入方式

MCP 覆盖凭证创建/预览、辅助核算、账期列表与结转检查；其余走 REST。两者字段命名不同：MCP 为英文（subjects / auxiliaries[].items），REST /ai/context 为中文键（科目列表 / 辅助核算[].details）。

配置

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

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

# config.txt — 含密钥，勿分享
baseUrl=https://fin.fdmobile.top/api
AK=AK-xxxxxxxx
accountSetId=735079029572375852

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

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

AK 获取： 打开 https://fin.fdmobile.top/ →（无账号先注册：手机号+短信验证码）→ 登录 → 个人设置 → 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）。

错误处理

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

交互流程

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

步骤〇：读取配置

1. 读 config.txt 或环境变量
2. 有 accountSetId → GET /ai/context → 步骤三
3. 仅 AK → GET /account-sets → 步骤二
4. 无 AK → 步骤一

步骤一：注册与获取 AK

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

步骤二：选择账套

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

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

GET /ai/context，展示账套名称与当前账期，按意图走路径：

能力总览：

路径 A：创建凭证

A1 收集业务描述

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

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

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

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

业务里已有客户/供应商/部门等名称，但账套 details 里没有对应项时：

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

步骤 5 的 auxiliary 元素模板：

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

MCP：listAuxiliaryCategories → createAuxiliaryItem → 写入 detailsJson[].auxiliary → previewVoucher。
接口字段见 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. 按期间查未生成凭证记录（含转账，转账行借=转入科目/贷=转出科目）
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（或 checkCarryOver 的 canInvoice=true）。注意： canInvoice 只表示已结转损益，仍须完成 F2 强制检查
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 已连接时：查账期/结转状态优先 Tool；正式结账/反结账与期末检查走 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 月~当前账期月；自动完成数据拉取、指标计算、报告生成并打印体检报告（有 🔴 项时退出码为 2）。脚本能跑通时不要逐接口手动拉数；脚本不可用（无 python3）时才走下方手动流程。拿到报告后：向用户解读风险项含义、给整改建议（这层业务判断由 AI 完成，脚本只算指标）。

I1-I4 详细流程

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

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

路径 J：聚合分析与服务端 AI（与 Web 版 AI 对等）

Web 版 AI 助手的两类高级能力对 F-API-KEY 全量开放：聚合分析工具（多接口编排统计）与服务端 AI 接口（消耗账套内已配置的大模型）。详细字段见 api-reference.md 附录 E；子技能 skills/ai-analysis.md。

J1 销售额统计（只读）

基于销项发票的多维聚合，分页列表接口无法直接做到：

优先脚本：python3 scripts/xl.py sales-stats --dimension byCustomer --start 2026-01-01 --end 2026-06-30 --top 10
REST：GET /agent/tool/sales-statistics?dimension=&startDate=&endDate=&topN=

J2 税务深度体检（只读）

基于漏报检查明细的结构化风险报告：漏报风险（state=0）、缴款风险（payState=0）、15 天临期预警、综合风险分级。依赖已有检查数据，提示「暂无数据，请先发起漏报检查」时引导用户先在税务模块发起检查（见 skills/tax-filing.md）。

优先脚本：python3 scripts/xl.py tax-checkup --focus all
REST：GET /agent/tool/tax-deep-checkup?focusArea=all|unreported|unpaid|expiring

与路径 I 的区别：路径 I 是本地脚本按金税四期口径算 14 项指标（发票+账簿数据）；J2 是服务端聚合已有申报检查数据（漏报/缴款/临期）。用户说「税务风险体检」默认走路径 I；说「深度体检/查漏报」走 J2；不确定时两者都跑。

J3 服务端 AI 接口（消耗账套配置的模型）

这些接口在服务端调用大模型（需用户已在「个人设置 → AI 配置」配置模型），外部 AI 借力使用：

使用原则： 路径 A（本地组装凭证）为主；服务端 AI 凭证接口适合「让系统 AI 试一把」的对照场景或用户明确要求时。返回结果仍须按 A2b 预览确认。AI_CONFIG_MISSING 报错时提示用户先配置 AI。

J4 接口目录发现（能力对等的兜底）

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

python3 scripts/xl.py tools --keyword 发票    # 按关键词过滤
python3 scripts/xl.py tools --full            # 含完整参数定义（较大）

REST：GET /agent/tools?keyword=。目录条目含 name（工具名）、httpMethod、path（REST 路径）、readOnly、params（参数名/来源/描述/必填）。按 path + httpMethod 组装请求（query 参数进 URL，body 参数放 JSON），写操作前照常预览确认。聚合工具条目（sales_statistics 等）的 path 指向 /agent/tool/* 端点。

J5 注意

• J1/J2/J4 均为只读，无需确认即可执行
• 服务端 AI 接口消耗用户配置的模型额度，主动告知用户再调用
• 目录中 readOnly=false 的接口是写操作，必须预览确认后调用

参考文件