Metadata-Version: 2.5
Name: lingguang
Version: 0.1.0
Summary: 把灵光 AI 的支付宝账单查询与钉钉消息能力封装成 MCP 工具和 CLI
Project-URL: Homepage, https://github.com/tokisaki-galaxy/lingguang-mcp
Project-URL: Repository, https://github.com/tokisaki-galaxy/lingguang-mcp
Project-URL: Issues, https://github.com/tokisaki-galaxy/lingguang-mcp/issues
Project-URL: Documentation, https://github.com/tokisaki-galaxy/lingguang-mcp#readme
Author: tokisaki-galaxy
License-Expression: MIT
License-File: LICENSE
Keywords: agent,alipay,dingtalk,lingguang,llm,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: mcp>=1.2.0
Requires-Dist: requests>=2.32
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# lingguang-mcp

**把灵光 AI 的账单查询与钉钉消息能力，封装成 MCP 工具和 CLI**

让 AI Agent 替你向灵光提问、取回结论、记录 Agent 的执行轨迹

![Python](https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white) ![MCP](https://img.shields.io/badge/MCP-2026--07--28-6E56CF?style=flat-square) ![License](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)

![CLI](https://img.shields.io/badge/interface-CLI%20%2B%20MCP-FF6B35?style=flat-square) ![Transport](https://img.shields.io/badge/transport-stdio-2E8B57?style=flat-square) ![Tests](https://img.shields.io/badge/tests-54%20passed-4CAF50?style=flat-square)

</div>

> 本项目基于对 `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 | MCP |
|---|---|---|
| 适合 | 人工手动操作、脚本调用、排查问题 | AI Agent 自动调用 |
| 启动 | `lingguang <命令>` | `lingguang serve` |
| 传输 | 进程内 | stdio |
| 能用的工具 | 全部，另有 `doctor` / `export` / `auth` 等运维命令 | 6 个基础工具 |
| 删除会话 | `lingguang sessions delete <id> --yes` | `delete_session`（需 `confirm=true`） |

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

---

## 技术栈

| 层 | 选型 | 说明 |
|---|---|---|
| 语言 | Python 3.11+ | 用 `uv` 管理依赖 |
| HTTP | `requests` | SSE 按字节流自定义切帧，不用 `iter_lines` |
| MCP | 规范 `2026-07-28` | stdio 传输，无协议级会话 |
| CLI | `typer` | 自动生成帮助，支持 `--json` 管道输出 |
| 测试 | `pytest` | 54 项单测 + 5 项契约测试 |
| 存储 | 无 | 默认不落库，留 `MessageSink` 接口做扩展点 |

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

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

---

## 安装

两种方式，按需选一个。

### 日常使用（推荐）

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

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

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

```bash
uv tool uninstall lingguang-mcp
```

没有 `uv` 的话，先装：

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

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

### 要改代码

```bash
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 面板里复制。

### 导入并验证

```bash
lingguang auth import cookie.txt
```

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

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

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

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

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

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

---

## 自检

```bash
lingguang doctor
```

三项都通过就可以用了：

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

---

## CLI 用法

```bash
# 列出会话
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
```

完整命令：

| 命令 | 用途 |
|---|---|
| `lingguang auth status` | 检查登录态 |
| `lingguang auth import <文件>` | 导入 cookie |
| `lingguang auth clear` | 清除本地 cookie |
| `lingguang sessions list` | 列出会话 |
| `lingguang sessions show <id> [--tools] [--keyword KW]` | 查看会话内容 |
| `lingguang sessions delete <id> --yes` | 删除会话 |
| `lingguang ask "问题" [--wait] [--timeout N]` | 提问 |
| `lingguang answer <query-id> [--wait N]` | 取回提问结果 |
| `lingguang export <id> --format md\|json\|jsonl\|raw` | 导出会话 |
| `lingguang doctor` | 环境自检 |
| `lingguang serve` | 启动 MCP server |

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

---

## MCP 用法

### 挂载

编辑 opencode 配置文件：

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

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

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

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

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

### 提供的工具

| 工具 | 用途 |
|---|---|
| `list_sessions` | 列出会话，支持游标分页 |
| `get_transcript` | 读取会话正文与 Agent 工具执行轨迹 |
| `ask` | 提交提问，立即返回，不阻塞 |
| `get_answer` | 取回提问结果，可短暂轮询 |
| `auth_status` | 检查登录态 |
| `delete_session` | 删除会话，必须显式传 `confirm=true` |

### 为什么提问是两段式

账单分析要跑 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 里手动确认。

---

## 开发

```bash
# 跑测试
uv run pytest

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

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

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

工程决策的推演过程见 [ENGINEERING-PLAN.md](ENGINEERING-PLAN.md)。

给 AI 助手看的使用说明见 [USAGE.md](USAGE.md)。

---

## 许可

MIT。详见 [LICENSE](LICENSE)。

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