170 lines
6.1 KiB
Markdown
170 lines
6.1 KiB
Markdown
# 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 |