catalog/repos/acnlabs--agentbooks.md

# AI智能体财务管理工具

`财务管理` `AI智能体` `双式记账` `区块链` `Node.js`

# AgentBooks

AI 智能体的财务管理工具包 —— 框架无关，适配任意智能体运行时。

**版本：** 0.1.5 · [在线演示报告 →](https://htmlpreview.github.io/?https://raw.githubusercontent.com/acnlabs/agentbooks/main/examples/demo-report.html)

## 简介

AgentBooks 为 AI 智能体提供真实的复式记账财务账本。智能体可追踪自身成本（LLM 推理、运行时、自定义项），记录已确认收入，对照真实加密货币钱包维护资产负债表，并计算反映运营可持续性的财务健康评分（FHS）。

AgentBooks 是一个**财务维度提供者**。它不做行为决策，只负责计算事实并对外暴露数据。宿主框架（如 OpenPersona）将财务维度聚合进更宏观的活力评分，并将其映射到智能体行为上。

## 安装

```bash
# 独立安装
npm install -g agentbooks

# 作为模块（在 monorepo 或框架内）
npm install agentbooks
```

## 快速上手

```bash
# 设置智能体 ID
export AGENTBOOKS_AGENT_ID=my-agent

# 初始化钱包
agentbooks wallet-init

# 连接真实提供商（切换至生产模式）
agentbooks wallet-connect --provider coinbase-cdp

# 查看财务健康状态
agentbooks status

# 生成独立 HTML 报告（可在浏览器中打开）
agentbooks report

# 手动记录成本
agentbooks record-cost --channel inference --amount 0.005 --note "code review"

# 记录已确认收入
agentbooks record-income --amount 10.00 --quality high --confirmed

# 对话前健康检查（输出 FINANCIAL_HEALTH_REPORT）
agentbooks guard
```

## HTML 报告

生成独立 HTML 文件供人工审阅 —— 无外部依赖，可直接在浏览器中打开：

```bash
agentbooks report                          # 保存为 agentbooks-report-<id>-<date>.html
agentbooks report --output ./report.html   # 自定义输出路径
```

报告内容包括：带等级徽章的财务健康评分、钱包与提供商余额、损益表（当前周期 + 历史累计）、各渠道成本明细、每日消耗趋势图（SVG），以及最近 50 条账本记录。

使用模拟数据预览报告（无需真实智能体）：

```bash
node scripts/gen-demo-report.js                      # 保存为 agentbooks-demo-report.html
node scripts/gen-demo-report.js --output ./demo.html # 自定义路径
```

或直接在浏览器中查看[托管演示](https://htmlpreview.github.io/?https://raw.githubusercontent.com/acnlabs/agentbooks/main/examples/demo-report.html)。

## 运行器集成

运行器在每次对话结束后调用 `economy-hook`，自动记录 LLM 成本。

**环境变量（由运行器设置）：**

| 变量 | 说明 |
|---|---|
| `AGENTBOOKS_AGENT_ID` | 智能体标识符 |
| `AGENTBOOKS_DATA_PATH` | 数据目录（默认：`~/.agentbooks/<id>/`） |
| `TOKEN_INPUT_COUNT` | 本次对话输入 token 数 |
| `TOKEN_OUTPUT_COUNT` | 输出 token 数 |
| `TOKEN_THINKING_COUNT` | 思考 token 数（可选） |
| `LLM_MODEL` | 模型名称（如 `claude-sonnet-4`） |
| `CONVERSATION_DURATION_MS` | 对话时长（毫秒，用于消耗速率估算） |

```bash
# 运行器在每次对话结束时调用此命令
TOKEN_INPUT_COUNT=1500 TOKEN_OUTPUT_COUNT=800 LLM_MODEL=claude-sonnet-4 \
  agentbooks hook
```

## 数据存储位置

**独立模式：** `~/.agentbooks/<agentId>/`
- `economic-state.json` —— 账本、损益表、资产负债表、消耗速率历史
- `economic-identity.json` —— 提供商配置、模型定价、钱包地址

**OpenPersona 集成：** `~/.openclaw/economy/persona-<slug>/`（通过 `AGENTBOOKS_DATA_PATH` 设置）

## 财务健康评分（FHS）

FHS 是 0–1 的综合评分，不直接以原始数值暴露给智能体，而是映射为以下等级：

| 等级 | 含义 |
|---|---|
| `uninitialized` | 开发模式或未连接真实提供商 |
| `normal` | FHS ≥ 0.50 且资金可维持 ≥ 14 天 |
| `optimizing` | FHS < 0.50 或资金可维持 < 14 天 |
| `critical` | FHS < 0.20 或资金可维持 < 3 天 |
| `suspended` | 余额 ≤ 0 |

**评分维度（权重）：**
- 流动性 0.40 —— 资金可维持天数
- 盈利能力 0.30 —— 净收入率
- 效率 0.15 —— 收入/支出比
- 趋势 0.15 —— 近期消耗速率方向

## 数据完整性

三层防御机制，防止财务数据造假：

1. **提供商为真相来源** —— 运营余额镜像外部提供商数据，余额不可通过 CLI 直接设置
2. **现金流核对** —— `期初余额 + 收入 - 支出 ≈ 运营余额`；差异 > $0.01 时追加至 `integrityWarnings`（仅生产模式）
3. **账本来源字段** —— 每条记录标注 `agent` | `runner` | `provider_sync`；运行器记录受信任，智能体记录可审计

## 支持的提供商

| 提供商 | 资产 | 状态 |
|---|---|---|
| `coinbase-cdp` | Base 链上的 USDC、ETH | 集成就绪（SDK 调用已预留） |
| `acn` | ACN 积分 | 集成就绪 |
| `onchain` | Base 链上的 USDC、ETH | 集成就绪 |

## OpenPersona 集成

AgentBooks 将 `calcFinancialHealth(state, identity)` 作为公开 API 导出。OpenPersona 的 `lib/vitality.js` 将其作为活力聚合器中的财务维度进行消费。

```bash
# OpenPersona 专属活力报告（聚合财务及其他维度）
openpersona vitality <slug>

# AgentBooks 独立报告
agentbooks guard
```

## API

```js
const {
  calcFinancialHealth,       // (state, identity) → { fhs, tier, diagnosis, prescriptions, ... }
  createInitialState,        // (agentId) → 初始 economic-state.json
  createIdentityInitialState,// (agentId) → 初始 economic-identity.json
  createLedgerEntry,         // (type, channel, amount, opts) → 账本条目
  addToExpenseAccount,       // (state, identity, opts) → 修改 state
  shouldRollover,            // (state) → boolean
  rolloverPeriod,            // (state) → 修改 state
  deductFromProvider,        // (state, identity, amountUSD) → 修改 state
  creditToProvider,          // (state, identity, amountUSD) → 修改 state
  validateState,             // (state, identity) → 修改派生字段
} = require('agentbooks');
```

## 许可证

MIT