@xhopcfine/aster-plugin-debt-pro

AI 化债星专业版的 Aster 插件版。

这个插件把债务管理、业务主体、还款计划、合同文件、担保物、成本项、报表和帮助文档等能力打包成一个可全局安装的 Aster 插件。安装后可以在本机启动完整 Web 界面，并使用本地 SQLite 保存数据。

特性

• 提供接近原 AI 化债星专业版的 Web 界面和业务流程。
• 支持业务主体、债务台账、还款计划、还款登记、合同文件、担保物、成本项和报表。
• 支持债务批量导入模板、导入校验和导入执行。
• 内置用户使用文档，文档图片随插件一起发布。
• 数据保存在本机 SQLite，适合私有化、本地化和客户数据不出本机的使用场景。
• Aster 可以通过插件工具查询债务总览、业务主体、债务和还款计划。
• 不需要 MCP，Aster 通过插件工具和本机 API 使用系统能力。

安装

先全局安装 Aster：

npm install -g aster-agent@latest --registry=https://registry.npmjs.org/

再全局安装债务管理插件：

npm install -g @xhopcfine/aster-plugin-debt-pro@latest --registry=https://registry.npmjs.org/

然后用全局 aster 命令启用插件：

aster plugins install debt-pro --package @xhopcfine/aster-plugin-debt-pro --enabled

启动 Aster：

aster

注意：Aster 不会自动下载这个插件包。用户必须先用 npm install -g @xhopcfine/aster-plugin-debt-pro@latest --registry=https://registry.npmjs.org/ 全局安装插件，然后再用 aster plugins install ... 启用它。

启动 Web 界面

插件提供独立的本地 Web/API 启动命令：

aster-debt-pro-web --port 8766 --open

默认地址：

http://127.0.0.1:8766

也可以指定数据库路径：

aster-debt-pro-web --port 8766 --db D:\data\debt-pro.db --open

快速使用

启动 Web 界面后，在浏览器中进入：

http://127.0.0.1:8766

常用流程：

• 先在“业务主体”中维护债务人、债权人和内部公司。
• 在“债务列表”中新建债务，填写本金、利率、起息日、到期日和还款规则。
• 系统根据规则生成还款计划，也可以在债务详情中调整计划。
• 在还款计划中登记还款，系统同步更新已还、待还和债务总览。
• 在债务详情中上传合同文件，支持合同台账、下载和预览。
• 在报表中心查看债务统计和还款计划统计。
• 在帮助文档中查看系统使用说明。
• 也可以在 Aster 对话中说“启动 Debt Pro”或“停止 Debt Pro”，由插件工具启动或停止本地 Web 服务。

Aster 工具

插件会向 Aster 暴露这些工具。通常用户不需要手动输入工具名，直接用中文描述需求即可。

| 工具 | 作用 | | --- | --- | | debt_start | 启动本地 Debt Pro Web/API 服务 | | debt_stop | 停止本地 Debt Pro Web/API 服务 | | debt_status | 查看服务状态、Web 地址和 SQLite 路径 | | debt_url | 查看本地 Web 界面地址 | | debt_overview | 查看债务总览指标，包括债务本金、应还利息、已还金额和待还金额 | | debt_party_manage | 查询、新增和查看业务主体 | | debt_manage | 查询、新增、修改、删除和查看债务 | | debt_repayment | 查询还款计划、查询还款记录和登记还款 | | debt_list_available_apis | 从插件内部 OpenAPI 中列出所有可调用接口 | | debt_get_api_documentation | 根据 operationId 查看接口参数、路径和请求体说明 | | debt_call_internal_api | 根据 operationId 在插件进程内调用 API，不依赖外部端口 | | debt_openapi_spec | 查看插件内部 OpenAPI JSON 摘要或完整内容 |

通过 Aster 工具执行新增、修改、删除、登记还款等写操作时，必须由用户明确确认。插件内部要求写操作传入 confirm: true。

OpenAPI 通用调用流程：

先用 debt_list_available_apis 查找接口，再用 debt_get_api_documentation 查看参数，最后用 debt_call_internal_api 调用。

debt_call_internal_api 使用 Fastify app.inject() 在插件进程内调用接口，不要求用户先启动 aster-debt-pro-web，也不依赖 8766 端口。Web/API 服务只用于浏览器界面访问。

示例对话：

启动 Debt Pro
启动 Debt Pro，并允许局域网访问
查看 Debt Pro 状态
打开 Debt Pro 的地址是多少
停止 Debt Pro

如果需要让同一局域网内其他设备访问，启动工具会使用 public=true 监听 0.0.0.0，并在 debt_status 中返回 network_urls。如果需要真正公网访问，仍需要服务器防火墙、安全组或反向代理放行对应端口。

数据和端口

默认地址：

• Web/API: http://127.0.0.1:8766

默认数据库：

~/.aster/plugins/debt-pro/debt-pro.db

合同文件等上传文件会保存在插件本地数据目录下。插件只访问本机 127.0.0.1 和本机 SQLite，不会因为使用这个插件而把债务、合同或还款数据发送到外部服务。

常见问题

需要安装 Python 或原 AI 化债星后端吗？

不需要。插件后端已经迁移为 Node.js 本机服务，数据使用 SQLite。

需要配置 MCP 吗？

不需要。Aster 不通过 MCP 使用这个插件，而是直接调用插件工具。Web 界面访问的是插件启动的本机 API。

新电脑上可以直接用吗？

可以。新电脑上先全局安装 aster-agent@latest，再全局安装 @xhopcfine/aster-plugin-debt-pro@latest。安装命令需要带 --registry=https://registry.npmjs.org/，然后用 aster plugins install debt-pro --package @xhopcfine/aster-plugin-debt-pro --enabled 启用插件即可。首次启动时会自动创建本地 SQLite 数据库。

Web 界面打不开怎么办？

先确认服务是否已启动：

aster-debt-pro-web --port 8766 --open

如果端口被占用，可以换一个端口：

aster-debt-pro-web --port 8770 --open

导入模板下载失败怎么办？

先确认访问的是插件 Web/API 地址，例如：

http://127.0.0.1:8766

插件模式下债务批量导入模板由本机 API 动态生成，不需要单独复制 Excel 模板文件。