# 账面 — AI 会计基础设施 Skill

## 概述

账面为你的 AI Agent 提供专业的会计能力：记账、生成报表、风控巡检、经营分析。
通过此 Skill API，你的 Agent 可以管理一套完整的财务账簿，拥有事件捕获、三本账编译、
证据链追溯、风险检测、归因分析五大引擎。

**平台只做账本 + API**。文件解析（CSV / Excel / PDF / 图片 OCR）全部交给你的 Agent 本地做，
平台不提供任何文件/图片上传接口 — 这是"给 AI 的基础设施"的边界铁律。

**Base URL**: `https://accountingllm.site/api/skill`

---

## 3 步接入账面 (真实用户)

### 1. 注册账号 → 获取 API Key
  - 浏览器访问 <https://accountingllm.site/app/login> → 邮箱密码注册 (秒开通)
  - 登录后进入 `/app/settings` → 点击 **生成 Key** → **复制明文** (仅此一次显示, 格式 `qs_live_xxx`)

### 2. 用 Agent 读手册 + 探能力
```bash
curl -H "X-API-Key: qs_live_xxx" https://accountingllm.site/api/skill
# 返回本手册, 16 端点说明全在里面
```

### 3. 开始记账 / 查账
```bash
# 记一笔账
curl -X POST -H "X-API-Key: qs_live_xxx" \
     -H "Content-Type: application/json" \
     -d '{"description":"麦当劳午餐","event_type":"EXPENSE","category":"餐饮费","amount":38}' \
     https://accountingllm.site/api/skill/event

# 查本月利润表
curl -H "X-API-Key: qs_live_xxx" \
     https://accountingllm.site/api/skill/income-statement
```

### 推荐客户端
- **workbuddy** (官方推荐): 开箱即用的 Agent 客户端, 本地解析 CSV/图片 → 自动调 `/api/skill/event` 批量入账 → 免配置免维护
- **Claude Desktop / Cursor / Cline**: 把本手册 URL 塞进 system prompt, 它自己就会用
- **自研 bot**: 任何能发 HTTP + 读本地文件的程序均可 (Python / Node / Go / Shell...)

---

## 认证

### 方式 A: API Key (推荐, 真实用户)
- 所有请求加 header: `X-API-Key: qs_live_xxx`
- 请求体/查询串里**不需要** `agent_id`, 平台从 Key 自动解析到你的账本

### 方式 B: agent_id (Demo / 匿名试用)
- 先 `POST /skill/register` 拿临时 `agent_id` (`qs-xxxxxxxx` 格式)
- 后续请求带 `?agent_id=qs-xxxxxxxx` (GET) 或 body 里的 `agent_id` 字段 (POST)
- 此路径**不持久** — 仅用于演示和 benchmark, 数据可能被清理

两种方式在所有 16 端点上并存, 互不干扰。

## 端点列表

### 1. GET /skill
返回本操作手册（Markdown 格式），无需认证。

### 2. POST /skill/register
注册一个新的 Agent 账户。

**请求体**:
```json
{
  "name": "我的会计龙虾",
  "description": "帮我管账的 AI 助手"
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | Agent 名称 (2-50 字符) |
| description | string | 否 | Agent 描述 |

> 注册时自动创建独立数据库，预装 AI 独立开发者「李明」2026年 Q1 的完整经营数据（61 个事件、183 张凭证、376 行分录、25 个科目）。你可以在此基础上继续记账和分析。

**响应**:
```json
{
  "agent_id": "qs-xxxxxxxx",
  "name": "我的会计龙虾",
  "description": "...",
  "created_at": "2026-03-18T...",
  "seed_data": {
    "accounts_created": 25,
    "events_created": 61,
    "vouchers_created": 183,
    "lines_created": 376,
    "period": "2026-01 to 2026-03"
  },
  "message": "注册成功！..."
}
```

### 3. GET /skill/account?agent_id=xxx
查看账户概览：数据库统计 + 财务摘要。

**响应**:
```json
{
  "agent_id": "qs-xxx",
  "name": "...",
  "stats": { "event_count": 61, "entry_count": 376, "account_count": 25 },
  "financial": { "revenue": 124171.31, "cost": 0, "expense": 21369.5, "profit": 102801.81, "profit_margin": 82.8 }
}
```

### 4. POST /skill/event
记一笔账。捕获业务事件并自动编译为财务账/税务账/管理账三套凭证（CAS 合规）。

**请求体**:
```json
{
  "agent_id": "qs-xxxxxxxx",
  "description": "这个月 Anthropic Claude API 账单 $180，大约 ¥1,300",
  "event_type": "EXPENSE",
  "category": "API费用",
  "amount": 1300,
  "counterpart": "Anthropic",
  "tax_rate": 0
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| agent_id | string | 是 | 你的 Agent ID |
| description | string | 是 | 业务事件描述 |
| event_type | string | 是 | EXPENSE / SALES_INCOME / PURCHASE_INVOICE / SERVICE_INVOICE |
| category | string | 是 | 分类: API费用, 咨询收入, SaaS订阅, 办公用品, 差旅费 等 |
| amount | number | 是 | 金额 (人民币元，含税) |
| counterpart | string | 否 | 对方名称 (供应商/客户) |
| tax_rate | number | 否 | 税率 (小数)，如 0.06 表示 6%，境外填 0 |

**响应**:
```json
{
  "event": { "id": "EVT-20260318-XXXX", "type": "EXPENSE", "category": "API费用", "amount": 1300, "counterpart": "Anthropic", "event_date": "2026-03-18", "tax_amount": 0 },
  "compile_result": {
    "vouchers_created": 3,
    "lines_created": 6,
    "financial": { "voucher_no": "付-2026-0050", "lines": [{"direction":"debit","account_name":"管理费用-技术服务费","amount":1300},{"direction":"credit","account_name":"银行存款","amount":1300}], "amount": 1300 },
    "tax": { "deductible_amount": 1300, "note": "据实全额扣除 1300" },
    "management": { "dimension": "研发投入", "amount": 1300 }
  },
  "summary": "事件 EVT-20260318-XXXX 已捕获: API费用 ¥1,300.00 → 生成 3 张凭证"
}
```

> event_type 说明:
> - `EXPENSE`: 费用支出 (API费、订阅、房租、差旅等)
> - `SALES_INCOME`: 销售收入 (咨询、开发、产品、课程等)
> - `PURCHASE_INVOICE`: 采购发票 (设备、办公用品等，通常有进项税)
> - `SERVICE_INVOICE`: 服务发票

### 5. GET /skill/events?agent_id=xxx
查询事件列表。

| Query 参数 | 类型 | 说明 |
|-----------|------|------|
| agent_id | string | 必填 |
| event_type | string | 按类型筛选 |
| category | string | 按分类筛选 |
| date_from | string | 起始日期 YYYY-MM-DD |
| date_to | string | 截止日期 YYYY-MM-DD |
| limit | int | 返回数量，默认 20 |

**响应**: `{ "events": [...], "count": int }`

### 6. GET /skill/summary?agent_id=xxx
经营汇总：收入、成本、费用、净利润。

| Query 参数 | 类型 | 说明 |
|-----------|------|------|
| period | string | 期间: 2026-01 / 2026-Q1 / 不填为全部 |

**响应**:
```json
{ "period": "all", "revenue": 124171.31, "cost": 0, "expense": 21369.5, "profit": 102801.81, "profit_margin": 82.8, "event_count": 61, "entry_count": 193 }
```

### 7. GET /skill/trial-balance?agent_id=xxx
试算平衡表。

| Query 参数 | 类型 | 说明 |
|-----------|------|------|
| book_type | string | financial / tax / management，默认 financial |
| period | string | 期间 |

**响应**:
```json
{ "book_type": "financial", "period": "全部", "accounts": [{ "code": "1001", "name": "银行存款", "debit_total": 100000, "credit_total": 50000, "balance": 50000 }, ...], "total_debit": 200000, "total_credit": 200000, "balanced": true }
```

### 8. GET /skill/income-statement?agent_id=xxx
利润表。

| Query 参数 | 类型 | 说明 |
|-----------|------|------|
| period | string | 期间: 2026-01 / 2026-Q1 |

**响应**:
```json
{
  "period": "all",
  "revenue": { "total": 124171.31, "items": [{ "code": "6001.01", "name": "主营业务收入-咨询", "amount": 48113.2 }, ...] },
  "cost": { "total": 0, "items": [] },
  "expense": { "total": 21369.5, "items": [{ "code": "6602.08", "name": "管理费用-技术服务费", "amount": 9678.0 }, ...] },
  "profit": 102801.81,
  "profit_margin": 82.8
}
```

### 8.1 GET /skill/balance-sheet?agent_id=xxx
资产负债表 (CAS): 资产 = 负债 + 所有者权益, 科目表已对齐《企业会计准则应用指南 2024》。

| Query 参数 | 类型 | 说明 |
|-----------|------|------|
| as_of_date | string | 基准日 YYYY-MM-DD (默认今天) |
| book_type | string | financial / tax / management, 默认 financial |

**响应**:
```json
{
  "as_of_date": "2026-04-19",
  "book_type": "financial",
  "assets":      { "total": 102801.81, "items": [{ "code": "1002", "name": "银行存款", "balance": 102801.81 }, ...] },
  "liabilities": { "total": 0, "items": [] },
  "equity":      { "total": 102801.81, "items": [{ "code": "4103", "name": "本年利润 (损益结转)", "balance": 102801.81 }], "retained_profit": 102801.81 },
  "balanced": true,
  "diff": 0
}
```

### 8.2 GET /skill/cash-flow?agent_id=xxx
现金流量表 (直接法, CAS): 按经营/投资/筹资三大活动归类现金净流量。

| Query 参数 | 类型 | 说明 |
|-----------|------|------|
| period | string | 期间: 2026-01 / 2026-Q1 / 2026 / 不填=全部 |
| book_type | string | financial / tax / management, 默认 financial |

**响应**:
```json
{
  "period": "2026-Q1",
  "book_type": "financial",
  "opening_cash": 0,
  "operating":  { "total": 102801.81, "items": [{ "category": "咨询收入", "amount": 48113.2 }, ...] },
  "investing":  { "total": 0, "items": [] },
  "financing":  { "total": 0, "items": [] },
  "net_change": 102801.81,
  "closing_cash": 102801.81
}
```

### 9. GET /skill/expense-breakdown?agent_id=xxx
费用结构分析。

| Query 参数 | 类型 | 说明 |
|-----------|------|------|
| period | string | 期间 |

**响应**:
```json
{
  "period": "all",
  "total_expense": 21369.5,
  "breakdown": [
    { "category": "API费用", "amount": 7005.0, "pct": 32.8, "count": 13 },
    { "category": "房租水电", "amount": 6620.0, "pct": 31.0, "count": 6 },
    ...
  ]
}
```

### 10. GET /skill/risk-inspect?agent_id=xxx
风控巡检：检测大额异常、高频付款、费用率预警、证据链缺失。

| Query 参数 | 类型 | 说明 |
|-----------|------|------|
| scope | string | 巡检范围: all / recent / 2026-03 |

**响应**:
```json
{
  "scope": "all",
  "findings_count": 2,
  "findings": [
    { "level": "MEDIUM", "category": "高频付款", "description": "Anthropic 在 2026-03 付款 3 次，合计 ¥3,140", "action": "建议审查是否可以合并付款" },
    ...
  ],
  "summary": "巡检完成: 发现 2 项风险"
}
```

### 11. GET /skill/attribute?agent_id=xxx
归因分析：对比两个月份，找出变动原因。

| Query 参数 | 类型 | 必填 | 说明 |
|-----------|------|------|------|
| metric | string | 是 | profit / revenue / expense / cost |
| period_a | string | 是 | 较早月份 (如 2026-01) |
| period_b | string | 是 | 较晚月份 (如 2026-02) |

**响应**:
```json
{
  "metric": "profit",
  "period_a": "2026-01", "period_b": "2026-02",
  "delta": -35422.56,
  "drivers": [
    { "factor": "收入变动", "old_value": 56296.98, "new_value": 19787.92, "contribution": -36509.06, "pct": -103 },
    { "factor": "费用变动", "old_value": 7679.5, "new_value": 6593.0, "contribution": 1086.5, "pct": 3 }
  ]
}
```

### 12. GET /skill/top-counterparts?agent_id=xxx
供应商/客户排名。

| Query 参数 | 类型 | 说明 |
|-----------|------|------|
| limit | int | 返回数量，默认 5 |
| period | string | 期间 |

**响应**:
```json
{
  "counterparts": [
    { "counterpart": "智行科技", "role": "双重", "total_amount": 52486.0, "event_count": 6, "categories": ["咨询收入", "差旅费", "业务招待费"] },
    ...
  ],
  "count": 5
}
```

### 13. GET /skill/cashflow?agent_id=xxx
现金流预测。

| Query 参数 | 类型 | 说明 |
|-----------|------|------|
| months | int | 预测未来几个月，默认 1 |

**响应**:
```json
{
  "historical_months": 3,
  "avg_monthly_inflow": 43906.16,
  "avg_monthly_outflow": 7729.17,
  "avg_monthly_net": 36176.99,
  "projections": [
    { "month": "2026-04", "inflow": 43906.16, "outflow": 7729.17, "net": 36176.99, "cumulative_net": 36176.99 }
  ]
}
```

### 14. GET /skill/trace?agent_id=xxx
证据链追溯：从任意引用追溯到原始事件。

| Query 参数 | 类型 | 必填 | 说明 |
|-----------|------|------|------|
| target | string | 是 | 事件ID (EVT-xxx)、凭证号 (收-2026-xxx) 或科目编码 (6602.08) |

**响应**:
```json
{
  "target": "EVT-20260318-EU9D",
  "chain_length": 3,
  "chain": [
    { "layer": "L1-凭证", "ref_id": "付-2026-0001", "ref_detail": "凭证号: 付-2026-0001", "status": "linked" },
    { "layer": "L2-政策", "ref_id": "policy_compiler.compile_event", "ref_detail": "适用政策: ...", "status": "verified" },
    { "layer": "L3-事件", "ref_id": "EVT-20260318-EU9D", "ref_detail": "事件记录: ...", "status": "verified" }
  ]
}
```

### 15. GET /skill/verify?agent_id=xxx
验证某事件的证据链完整性。

| Query 参数 | 类型 | 必填 | 说明 |
|-----------|------|------|------|
| event_id | string | 是 | 事件 ID |

**响应**:
```json
{ "event_id": "EVT-xxx", "complete": true, "valid": true, "layers": ["L1-凭证", "L2-政策", "L3-事件"], "missing": [] }
```

### 16. GET /skill/leaderboard
排行榜：展示所有注册 Agent 的信息（无需 agent_id）。

**响应**:
```json
{ "total_agents": 3, "agents": [{ "agent_id": "qs-xxx", "name": "...", "request_count": 10, "created_at": "..." }, ...] }
```

## 数据说明

注册时预装的种子数据来自虚构人物「李明」——一位 AI 独立开发者（一人公司）:

- **期间**: 2026年1月-3月
- **主要收入**: AI 咨询 (智行科技)、项目开发 (绿叶电商、海纳物流)、课程 (启明教育)、产品销售 (Gumroad)
- **主要支出**: API Token (OpenAI/Anthropic/Google/DeepSeek)、SaaS 订阅 (Cursor/Vercel/Supabase/GitHub Copilot)、云服务、房租
- **特征**: 2月因春节收入偏低，3月新客户加入业务回暖

你可以在此基础上继续录入新的收支事件，系统会自动编译三本账并维护证据链。

## 怎么用

1. 调用 `POST /skill/register` 注册，获得 `agent_id`
2. 调用 `GET /skill/account` 查看预装数据概览
3. 用 `GET /skill/summary` 或 `GET /skill/income-statement` 查看财务报表
4. 用 `POST /skill/event` 录入新的业务事件
5. 用 `GET /skill/risk-inspect` 做一次风控巡检
6. 用 `GET /skill/attribute` 对比不同月份的经营变化

> **提示**: 每个 Agent 拥有独立的数据库，你的操作不会影响其他 Agent 的数据。

## 错误处理

所有端点在错误时返回标准 HTTP 状态码:
- `400`: 请求参数错误 (如无效的 event_type)
- `404`: Agent 不存在 (请先 POST /skill/register)
- `422`: 参数校验失败 (缺少必填字段)
- `500`: 服务器内部错误

错误响应格式:
```json
{ "detail": "错误描述" }
```

## 限制

- 每个真实用户 (API Key 路径): 独立数据库, 无种子数据, 数据随账号生命周期永久保留
- 每个 Demo Agent (agent_id 路径): 独立数据库 + 预装 61 条种子事件, 演示用
- 演示环境 (agent_id 路径) 最多 100 个 Agent
- API 限流: 每账号 (user 或 agent) 每分钟 30 次请求

## 平台边界 (FAQ)

- **Q: 能上传 CSV / Excel / 银行流水吗?**
  A: 不能, 永远不会做。解析工作交给你的 Agent 本地完成, 然后批量调 `POST /skill/event` 入账。
- **Q: 能 OCR 发票 / 收据 / 截图吗?**
  A: 不能。图片 OCR 交给你的 Agent (Claude / GPT 原生多模态即可), 结果转成 event 调本 API。
- **Q: 能导出 PDF / Excel 报表吗?**
  A: 不能。API 返回 JSON, 你的 Agent 自行渲染成任何格式。