本项目基于对 lingguang.com 网页接口的逆向分析，非官方 SDK。 接口随时可能变动，使用前请阅读 风险与边界。

不想自己折腾配置？ 复制以下内容发给AGENT工具。

请帮我配置 lingguang-mcp，这是一个让我能通过你查询支付宝账单和钉钉消息的工具。
仓库地址：https://github.com/tokisaki-galaxy/lingguang-mcp
详细说明见随附的 USAGE.md。请按里面的步骤帮我装好并挂载到 MCP。

如果你是一个LLM,请阅读与当前文件同级的USAGE.MD文件帮助用户快速配置

为什么需要它

支付宝账单和钉钉消息，对个人用户没有可用的开放接口：

• 支付宝不向个人开放账单 API
• 钉钉需要企业管理员开启数据访问权限

灵光是唯一入口。它已经拿到支付宝授权、已经连上钉钉， 能通过 Agent 真实查询账单并给出每笔交易的商户、金额、时间。

所以本项目本质上是一个遥控器加录音机： 替你的 Agent 向灵光提问、取回结论、记录 Agent 的执行轨迹。 它不绕开灵光自己拿数据，也拿不到。

两种使用方式

本项目同时提供 CLI 和 MCP 两套接口，共用同一套核心逻辑，能力完全对齐。

两边签名一致，行为一致。你可以先用 CLI 手动验证， 确认可用后再挂到 Agent 上跑自动化。

技术栈

架构分三层，cli/ 和 mcp/ 是 core/ 的薄壳：

src/lingguang/
  core/     解析器、HTTP 客户端、业务编排、异常分类
  cli/      命令行入口
  mcp/      MCP stdio server 与工具定义

安装

两种方式，按需选一个。

日常使用（推荐）

不用 clone，一条命令装好，之后任何目录都能直接用：

uv tool install git+https://github.com/tokisaki-galaxy/lingguang-mcp.git

升级就是重跑这条命令。卸载：

uv tool uninstall lingguang-mcp

没有 uv 的话，先装：

# Windows PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

要改代码

git clone https://github.com/tokisaki-galaxy/lingguang-mcp
cd lingguang-mcp
uv sync --extra dev

在项目目录里用 uv run lingguang <命令> 跑， 或者激活虚拟环境后直接用 lingguang。

获取 cookie

这是唯一需要手动做的一步。cookie 相当于账号登录凭证， 程序没法替你登录，因为灵光要扫码。

步骤

1. 用浏览器打开 https://www.lingguang.com 并登录

2. 按 F12 打开开发者工具，切换到 Application 标签 （中文版 Chrome 或 Edge 里叫「应用」）

3. 左侧栏找到 Storage → Cookies → https://www.lingguang.com

4. 在右侧表格里找到这三个值，双击 Value 列复制：

   Cookie 名	说明	是否必须
   ctoken	会话标识，形如 bigfish_ctoken_xxx	必须
   prod_LINGGUANGJSESSIONID	服务端会话	强烈建议
   spanner	网关会话	强烈建议

   spanner 的域名是 cognihome.lingguang.com。 如果在上面的列表里找不到，检查左侧有没有 cognihome.lingguang.com 这一项。

5. 把它们拼成一行，用分号加空格分隔：

   ctoken=bigfish_ctoken_xxxxx; prod_LINGGUANGJSESSIONID=prod_yyyyy; spanner=zzzzz
   

6. 存成文件，比如项目根目录下的 cookie.txt

最容易踩的坑

prod_LINGGUANGJSESSIONID 是 HttpOnly 的， 在控制台敲 document.cookie 读不到，必须在 Application 面板里复制。

导入并验证

lingguang auth import cookie.txt

导入后会立刻验证一次。成功会显示：

已保存到 ~/.config/lingguang/credentials.json
验证通过，cookie 可用

失败会直接报错，不会等到下次用的时候才炸。

也可以用环境变量跳过文件：

# Windows PowerShell
$env:LG_COOKIE="ctoken=xxx; spanner=yyy"

# Linux / macOS
export LG_COOKIE="ctoken=xxx; spanner=yyy"

自检

lingguang doctor

三项都通过就可以用了：

[通过] cookie 齐全
[通过] loginCheck 成功
[通过] 解析器能提取正文（891 字符）

CLI 用法

# 列出会话
lingguang sessions list

# 查看某个会话，带工具执行轨迹
lingguang sessions show <session-id> --tools

# 提问并等待结果
lingguang ask "这个月吃饭花了多少钱" --wait

# 只提交不等待，拿 query_id
lingguang ask "这个月吃饭花了多少钱"
lingguang answer <query-id> --wait 40

# 导出归档
lingguang export <session-id> --format md -o out.md

完整命令：

所有查询命令都支持 --json，方便管道处理。

MCP 用法

挂载

编辑 opencode 配置文件：

{
  "mcp": {
    "lingguang": {
      "type": "local",
      "command": ["lingguang", "serve"],
      "enabled": true
    }
  }
}

如果用 uv tool install 装的，lingguang 已经在 PATH 里， 上面的配置直接用就行。

如果没装到 PATH，用 uv run 指向项目目录，跨平台通用：

{
  "mcp": {
    "lingguang": {
      "type": "local",
      "command": [
        "uv", "run",
        "--directory", "C:\\path\\to\\lingguang-mcp",
        "lingguang", "serve"
      ]
    }
  }
}

Linux 或 macOS 把路径换成 /path/to/lingguang-mcp 即可。

提供的工具

为什么提问是两段式

账单分析要跑 20 到 30 秒。MCP 工具同步阻塞会撞客户端超时， 调用方也没法中途取消。所以拆成：

ask        -> 立即返回 { session_id, query_id }
get_answer -> 按 query_id 取结果，wait_seconds 最多等 60 秒

Agent 的自然用法是 ask 之后立刻 get_answer(wait_seconds=40) 等结果。

工具轨迹是核心价值

每轮回答都能拿到 Agent 真实调用的子程序列表：

查看账单查询服务目录 / 统计本月收支概况 / 分析近三个月账单趋势 / 统计本月分类消费构成

这是普通对话接口给不了的结构化信息。

风险与边界

这不是官方工具，接口随时可能失效。

本项目依赖逆向出的网页接口。上游改版时解析器会崩。 lingguang doctor 能帮你发现，但不能替你修。 解析全挂时用 export --format raw 拿原始 JSON 兜底。

请保持低频使用。

这是最重要的一条。蚂蚁侧有风控系统，本工具按「个人日常使用」的 频率设计。不要用它做批量抓取、定时轮询或自动化脚本。 高频请求会让账号被风控标记，后果会连带影响你在灵光 App 里的正常使用。

正常节奏参考：一天问几次，和你在 App 里用的频率保持一致。

cookie 等于你的登录态。

ctoken 泄露等于别人能以你的身份访问灵光，看到你的账单。 不要把 cookie.txt 或 credentials.json 分享给任何人，不要提交到仓库。 .gitignore 已经排除了这两类文件。

cookie 会在长时间不操作后失效。失效时重新导入即可， lingguang auth status 会告诉你上次成功是多久之前。

数据保存在哪里。

除了 ~/.config/lingguang/credentials.json 存 cookie， 本工具不保存任何历史数据。默认不落库，每次调用都实时拉取。 需要归档时用 lingguang export 导出到你自己选的位置。

关于 APASS 高危确认。

灵光 2.0 宣称接入蚂蚁 APASS，高危操作需用户确认。 但实测表明该能力尚未在网页端落地。 如果未来某次提问触发了确认，get_answer 会返回 awaiting_confirmation 状态，此时需要你在灵光 App 里手动确认。

开发

# 跑测试
uv run pytest

# 含真实接口的契约测试（需要先导入 cookie）
uv run pytest -m live

约束：cli/ 和 mcp/ 只准 import core 下的 service、models、errors，不直接碰 client 和 parser。

接口逆向的完整记录，包括九条实测约束和已知坑， 见 docs/reverse-notes.md。

工程决策的推演过程见 ENGINEERING-PLAN.md。

给 AI 助手看的使用说明见 USAGE.md。

许可

MIT。详见 LICENSE。

本项目仅供个人学习与自用。使用者需自行承担因使用本项目产生的 包括但不限于账号受限、数据丢失在内的风险。 项目作者不对因使用本项目造成的任何后果负责。