Skip to content

Alexsun1one/tax

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

222 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

🧾 FinBox AI · 慧账宝

企业级 B2B 财税 AI SaaS 平台 · 8 位预置专家 Agent · 世界级 Skills Library · 隐私优先

license stage frontend backend llm

postgres qdrant redis tailwind shadcn mcp

让每家企业都拥有一支可靠、可审计、可成长的 AI 财税团队。

🆕 用户手册 · 按你的角色挑着看

  • 🎓 NEW_USER_GUIDE.md · 5 分钟初识系统 · 它是什么 · 8 个 AI 同事 · 常见场景
  • 📘 USER_MANUAL.md · 完整操作手册 · 每个菜单都告诉你怎么用 (推荐打印/收藏)
  • 🧩 FLOW_GUIDE.md · Flow DAG 编排深度指南 · YAML 语法 / 5 种节点 / 完整案例
  • 🎨 GEPA_GUIDE.md · 自动进化深度指南 · 信号 / 闭环 / 评分 / 安全栏杆
  • ❓ FAQ.md · 12 大类故障排查 · 现象 → 原因 → 解法
  • 📋 YOUR_TODO.md · 上线前你本人要做的事清单 · 买域名 / 备案 / 申请密钥 / 设密码

🔧 给技术同事看的

📚 文档总索引 · 📐 架构文档 · 🔄 业务流程 · 🚀 端到端 Demo 手册 · 📊 可观测性 · ✅ 零基础运维手册 · 📋 OpenSpec · 📜 开发铁律


English TL;DR — FinBox AI ("慧账宝") is an enterprise-grade B2B AI platform for finance, tax, audit, legal, HR, sales & procurement. It ships with 8 pre-configured expert Agents, a 130k-word Skills Library (40 skills), tamper-proof contract diffing, intelligent Excel ingestion, one-click report generation, and a privacy-first stack (audit log / network whitelist / kill switch / human approval gate). Built on Next.js 16 + FastAPI + PostgreSQL + Qdrant + vLLM (Qwen3.5-35B). Every LLM call is audited — token cost is always under control.


🎯 产品定位

慧账宝(FinBox AI) — 一句话:

给中小与中大型企业一支"开箱即用的 AI 财税专家团队",以真实数据链路、世界级 Skills 与企业级合规底座,7×24 辅助 CFO 团队做账、审计、申报、合同、销售分析与人事决策。

详细一点:FinBox AI 不是 ChatGPT 皮肤不是 RPA 玩具,而是一套——

  • 全栈真实链路:前端 Next.js 16 + 后端 FastAPI + PostgreSQL + Qdrant 向量库 + vLLM 本地大模型 —— 禁止 mock / 禁止假功能。
  • 多 Agent 协作:两种并存模式 —
    • @mention 接力(轻量):Supervisor 按关键词路由到专家 Agent,Agent 间最多接力 3 跳,适合临时对话。
    • Flow DAG 编排(正式流程 · ✅ 2026-04-23 上线):写一份 YAML 定义 DAG,拓扑排序 + asyncio.gather 同层并行,支持 retry / on_error / approval_gate / branch / cron 调度 / checkpoint 重入幂等,全链路 Prometheus 埋点。内置模板 month_end_close.yaml(月末闭账)。详见 /flows
  • 归属人机制:每个 Agent 必须绑定 owner_user_id(在 /evolution > Agent 归属人 Tab 管理),高风险动作必须人工 approve,出问题可追溯到具体责任人。
  • Token 成本可控:每次 LLM 调用强制写 agent_audit_log(哈希链 append-only,PG 用 advisory lock 串行化保证并发不 fork),档位限额、实时 Dashboard、Kill Switch(Redis 多实例一致 / file fallback)。
  • 合规优先:PII 自动脱敏(默认对所有 LLM 调用生效,含本地 vLLM;可 PII_REDACT=0 关闭)、审计日志 append-only + 哈希链可校验、Kill Switch 三级告警。注意:「默认拒绝出网」目前只是白名单清单 + 校验函数,还没接到 httpx/iptables,是 Phase 1 计划项

✨ 核心能力

👥 8 位预置 AI Agent 团队

开箱即用的企业级 AI 专家:

  • 💼 CFO Agent — 战略、现金流、利润诊断
  • 📊 会计 Agent — 做账、凭证、对账
  • 🔍 审计 Agent — 内控评估、风险扫描
  • 🧾 税务师 Agent — 申报、筹划、汇算
  • ⚖️ 法务 Agent — 合同审核、条款比对
  • 📈 销售 Agent — 客户画像、预测
  • 🛒 采购 Agent — 供应商评估、议价
  • 👔 HR Agent — 薪酬结构、人效

每个 Agent 均可自定义 Skills、Tools、温度、归属人。

👤 归属人一键指派: /evolution > Agent 归属人 Tab → 未指派的 Agent 会醒目红框提示 · 点 "指定负责人" 弹 candidate picker · 支持模糊搜索 + 键盘 ↑↓ + Enter 提交 · 真落 finbox_agent_profiles.owner_user_id + owner_email.

📚 Skills Library · 40 × 世界级

[screenshot: skills-library]

40 个领域技能、累计约 13 万字的结构化知识与推理模板,分 8 大领域:

backend/skills/
├── cfo/          # 战略 / 现金流 / 诊断
├── accounting/   # 做账 / 凭证 / 对账
├── audit/        # 内控 / 合规
├── tax/          # 申报 / 筹划
├── legal/        # 合同 / 合规
├── sales/        # 客户 / 预测
├── procurement/  # 供应商 / 议价
└── hr/           # 薪酬 / 绩效

skills.composer 按需注入 Prompt,支持摘要模式避免超长上下文。

🛡️ 合同防篡改比对 + 10 套模板

[screenshot: contract-diff]

  • 双版本 Word / PDF 一键比对
  • 语义归一(去格式扰动),逐条标红
  • 法务 Agent + Skills 给出风险等级与关键条款
  • 内置 10 份企业级模板(SaaS / 采购 / 保密 / 劳动合同 / …)
  • 支持 Excel → 批量生成 Word + PDF + ZIP 下载

🧩 Excel 智能矩阵入库

[screenshot: matrix-upload]

  • 上传任意列名 Excel,AI 自动对齐标准矩阵
  • 嵌入检索 + LLM 裁定 hybrid 策略
  • 置信度高自动入库,歧义时请用户确认
  • 学习型:租户专属 schema 自动沉淀到 Qdrant

📊 一键报表 · 日/周/月/季/年

[screenshot: reports-cockpit]

  • 10+ 专业报表模板(YAML 可扩展)
  • 数据源拉取 → CFO Agent 解读 → WeasyPrint PDF → 邮件发送
  • 每期自动归档到 MinIO
  • 支持 KPI 卡 / 趋势图 / 告警 / 洞察

🔒 隐私 & 合规 MVP

[screenshot: privacy-panel]

  • 审计日志:操作 / Agent / 文件三张表 append-only
  • 网络白名单:默认拒绝一切出网
  • Kill Switch:Skill / Agent / 租户三级熔断
  • DLP 脱敏:PII 自动掩码
  • 人工审批 Gate:高风险动作必须 owner 放行

🧩 Flow DAG 编排 · 多 Agent 协同 (NEW)

[screenshot: flow-dag]

把"会计对账 → 税务/审计并行 → CFO 汇总 → 人工审批 → 归档"这种跨 Agent 协作写成 YAML DAG, 系统自动跑 · 同层并行 · 失败重试 · 跑到审批节点自动停下来等人批。

  • 5 种 node:agent / tool / approval_gate / branch / noop
  • 重试策略 (exponential / linear / none) · on_error (stop / continue / escalate)
  • Jinja2 Sandbox 模板变量 {{ nodeA.output.text }} 安全插值
  • Cron 定时触发 (APScheduler 每分钟扫表 · Redis 锁防多 worker 重复)
  • Checkpoint 每节点写 DB · 跨 24 小时审批也能重入
  • Prometheus 指标: finbox_flow_runs_total + finbox_flow_node_duration_seconds

内置模板: month_end_close.yaml (月末闭账). 入口: /flows.

🎨 GEPA 自动进化 · Prompt 每周自我进化 (NEW)

[screenshot: gepa-autotune]

不想手动调 Prompt?GEPA (Gradient-Enhanced Prompt Autotuning) 每周自动给每个 Agent 生成 3~5 个改进版 prompt,用 LLM-as-judge 打分选最优,5% 流量 canary A/B, 表现好 → 推送给 owner 一键采纳 · 表现差 → 自动回滚。

  • 用户每次 👍/👎 聊天记录都是训练信号
  • 每周一凌晨 03:00 自动 tick · 生成候选 / 评分 / canary / HITL
  • 全链路 guardrail: 回归测试 / 延迟监控 / 成本上限
  • 入口: /agent-studioAuto-tune Tab

🌐 15 个企业级外部集成接口 · 8 个真接通 / 7 个待最后一公里对接

诚实声明: 所有接口形状都按行业惯例定好, 统一落在 backend/integrations/, 每个 provider 一个文件, 遵循统一契约 verify() / query() / submit() + sandbox/prod 双模. sandbox=1(默认) 返回可复现的假数据用于开发联调;sandbox=0 走真实 provider — 没配 KEY 会直接报错而不是静默退回 stub, 防止"演示时以为联通了其实没有"。

类别 接口 提供商 状态
短信 OTP /integrations/sms-otp 阿里云 dysmsapi ✅ 真接通
邮件 SMTP /integrations/email 阿里云 DM / 自建 SMTP ✅ 真接通
企微 / 钉钉 /integrations/im 企微 / 钉钉 webhook ✅ 真接通
电子签章 /integrations/e-signature e 签宝 v3 ✅ 真接通
电子税局 /integrations/etax 各省电子税务局开放平台 ✅ 真接通
企业工商 /integrations/enterprise-info 企查查开放 API ✅ 真接通
实名认证 /integrations/identity-verify 阿里云 / 腾讯云 ✅ 真接通
发票核验 /integrations/invoice-verify 百望云 v2 ✅ 真接通
营业执照 OCR /integrations/business-license 国家总局 🟡 sandbox 可用
银行对接 /integrations/bank-statement 各家商业银行 🟡 sandbox 可用
支付 /integrations/payment 微信 / 支付宝 🟡 sandbox 可用
SSL 证书监控 /integrations/ssl-status 自建探针 ✅ 真接通
API 额度 /integrations/api-quota 各云服务 🟡 sandbox 可用
快递物流 /integrations/logistics 顺丰 / 京东 🟡 sandbox 可用
第三方 OCR /integrations/ocr 百度 / 阿里 🟡 sandbox 可用
翻译 /integrations/translate 百度 / Google 🟡 sandbox 可用

图例: ✅ 真接通 (配好 KEY 即可用于生产) · 🟡 sandbox 可用 (契约稳定, 客户正式签约前 1~2 天接真 API).


🏗️ 技术架构

简图

┌──────────────────────────────────────────────────────────────┐
│  Next.js 16 (Cockpit + Workbench + Chat + Reports + ...)    │
└──────────────┬───────────────────────────────────────────────┘
               │ HTTPS / WebSocket / SSE
┌──────────────▼───────────────────────────────────────────────┐
│  Nginx (TLS / WAF)  →  JWT Auth  →  Rate Limit (Redis Lua)  │
└──────────────┬───────────────────────────────────────────────┘
               │
┌──────────────▼───────────────────────────────────────────────┐
│  FastAPI (REST + SSE + WS)   ·   Celery Workers  ·  MCP     │
└───┬──────────┬──────────┬──────────┬──────────┬──────────────┘
    │          │          │          │          │
┌───▼──┐  ┌────▼───┐  ┌───▼───┐  ┌───▼───┐  ┌───▼──────────┐
│ PG16 │  │ Qdrant │  │ Redis │  │ MinIO │  │ LiteLLM→vLLM │
│业务库│  │ 向量库 │  │ 缓存  │  │ 对象  │  │ Qwen3.5-35B  │
└──────┘  └────────┘  └───────┘  └───────┘  └──────────────┘
                                                      │
                                         ┌────────────▼──────────┐
                                         │ Skills(40) + MCP Tools│
                                         │ BGE-M3 · RapidOCR     │
                                         └───────────────────────┘

完整 mermaid 流程图(L1 总览 / L2 Agent 层 / L3 数据流 / L4 隐私)请见 docs/ARCHITECTURE.md

10 个核心业务 sequence diagram(注册 / 合同 / 报表 / 对话 / 审批 / 监控 ...)请见 docs/BUSINESS_FLOWS.md

技术栈

主力组件
前端 Next.js 16 · React · Tailwind 4 · shadcn/ui · Radix · framer-motion · Tremor
后端 FastAPI 0.115+ · SQLAlchemy 2.0 (async) · Pydantic v2 · Celery 5.4 · sse-starlette
数据 PostgreSQL 16 · Qdrant 1.12 · Redis 7 · MinIO (S3)
AI vLLM + Qwen3.5-35B-Instruct · LiteLLM · BGE-M3 · RapidOCR + PaddleOCR
文档 PyMuPDF · LibreOffice headless · python-docx · docxtpl · WeasyPrint · markitdown
Agent pydantic-ai + openai SDK · MCP (Anthropic) · 自研 FinBoxAgent
基础 Nginx · Docker Compose · Prometheus + Grafana (计划) · OpenTelemetry (计划)

🚀 快速开始

开发环境推荐:Ubuntu 22.04 / Python 3.12 / Node 20+ / 有 1 张 >= 24G 显存 GPU(跑 vLLM)。

没 GPU? 可先跳过 vLLM,配 LiteLLM 指向第三方模型(DeepSeek / Kimi / OpenAI)体验。

1️⃣ 起基础设施(PostgreSQL / Redis / Qdrant / MinIO / NocoBase)

cp docker-compose.env.example .env
# 编辑 .env 至少把以下 4 项改成强随机:
#   DB_PASSWORD / JWT_SECRET / PORTAL_TOKEN_SECRET / APP_KEY
#   NOCOBASE_ADMIN_PASSWORD (生产环境弱密码会被启动期自检拒绝)
#   NOCOBASE_SERVICE_PASSWORD (推荐: 给 FastAPI 用的非 root 服务账号)
docker compose up -d postgres redis qdrant minio nocobase

⚠️ 关键:FastAPI 的所有业务数据 CRUD 都走 NocoBase(finbox_* 表)。如果不起 NocoBase,/api/v1/dashboard/overview/expenses/cockpit 等页面会 500。本项目不再支持 "纯 FastAPI 单跑" 模式。

2️⃣ 起 LLM 引擎(vLLM)

# 拉取 Qwen3.5-35B-Instruct 权重到 ~/models/qwen3.5-35b-instruct
bash backend/scripts/start_vllm.sh
# vLLM 默认监听 http://localhost:8001/v1 (OpenAI 兼容)

3️⃣ 起后端(FastAPI)

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 初始化数据库
python scripts/init_db.py

# 启动
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

# Celery worker(新开一个 shell)
celery -A backend.tasks worker -l info

4️⃣ 起前端(Next.js)

cd frontend
npm install
npm run dev
# → http://localhost:3000

一键启动脚本

# 本地全栈 (假定基础设施已 docker compose up -d)
bash start_all.sh

# 本地纯前端调试 + 没起 NocoBase/Clerk 时, 可临时关认证 (仅本机!):
FINBOX_LOCAL_NO_AUTH=1 bash start_all.sh

# AutoDL 环境
AUTODL_FRONTEND_URL=https://your-instance.autodl.pro:port bash start_all.sh

生产部署不要用 start_all.sh —— 它假设了 dev 习惯。生产应该用 docker-compose.yml + FINBOX_ENV=prod 启动。

端点清单

服务 URL
前端 http://localhost:3000
后端 API http://localhost:8000/docs
vLLM http://localhost:8001/v1
LiteLLM http://localhost:4000
PostgreSQL postgresql://finbox:***@localhost:5432/finbox
Qdrant http://localhost:6333/dashboard
Redis redis://localhost:6379/0
MinIO Console http://localhost:9001

📋 OpenSpec 规范驱动开发

FinBox AI 采用 Spec Driven Development (OpenSpec) —— 新功能先写 spec、再实现、最后勾选 tasks。

openspec/
├── changes/
│   ├── chat-as-os/                       ✅ AI Native Brain + Generative UI
│   ├── multi-agent-group-chat/           ✅ 多 Agent 群聊 + @mention 接力
│   ├── saas-depth-hardening/             ✅ P0/P1/P2 硬化全部完成
│   ├── marketplace-paid/                 🚧 Phase 3 · Marketplace 收费商店
│   └── archive/
│       ├── 2026-04-23-agent-group-orchestration/  ✅ YAML DAG + 并行 + 审批
│       └── 2026-04-23-gepa-auto-tune/             ✅ 每周 prompt 自进化

每个 change 的目录结构:

<change>/
├── design.md          # 设计与 tradeoff
├── specs/<feature>/
│   └── spec.md        # Given/When/Then scenarios
└── tasks.md           # 实现任务清单(勾选制)

👉 详见 openspec/ 与 Skill .cursor/skills/openspec-*


🔒 合规与安全

透明声明:下面带 ✅ 的是当前已实现并有测试覆盖带 🚧 的是 Phase 2 计划项 —— 我们不在 README 里把计划项写成已完成。

  • 数据主权:默认私有化部署,数据库 / 向量库 / 模型 / 文件全部在客户内网或自有 GPU 机
  • RBAC:内置 admin/manager/member/viewer 4 角色 + 50+ 权限点,require_perm() 守卫真正生效(v5 版本前曾有真值判断 bug 导致守卫失效,已修 + 单测护栏,回归详见 tests/test_rbac.py
  • 多租户隔离:所有报表 SQL / 驾驶舱 / 全局搜索 / NocoBase CRUD 强制按 tenant_id 过滤;防御性扫描器 tests/test_route_sql_tenant_isolation.py 阻止后续贡献漏 tenant
  • PII 脱敏:身份证 / 手机 / 银行卡 / 邮箱等进入 LLM prompt 前自动 mask(默认对所有 LLM 调用生效,含本地 vLLM;PII_REDACT=0 可关并 WARN)
  • 审计留痕agent_audit_log append-only + SHA256 哈希链;并发安全(PG advisory lock / SQLite threading lock per tenant);AuditLogger.verify_chain(tenant_id) 给运维核验链完整性
  • Kill Switch:Redis-first 全集群一致;Redis 不可用退化到本地文件 + WARN 提醒多实例不一致;KILL_SWITCH_TTL_SECONDS 防误激活后没人解
  • 生产启动安全自检FINBOX_ENV=prod 时若 DISABLE_AUTH=1 / 默认 JWT secret / 默认 NocoBase 密码 → 直接 SystemExit(2) 拒绝启动
  • 🚧 出网白名单实际拦截:当前仅有白名单清单 + is_whitelisted() 校验函数;还没挂到 httpx / iptables(Phase 2)。不要把 README 之前的"默认拒绝一切出网"当成已实现
  • 🚧 人工 Gate / 高风险动作 owner approve:审批表 + 路由已建(routes/approval_actions.py),但 LLM 工具的"敏感动作自动拦截入审批"链路还没 e2e 串起来
  • 🚧 审计日志 90 天归档:append-only 已实现,自动归档调度还没接
  • ⚖️ 合规遵循:《数据安全法》《个人信息保护法》《生成式 AI 服务管理暂行办法》—— 我们按这些法规设计架构,但未通过任何第三方合规认证(SOC2/ISO27001 在 Phase 3 路线图)

🛣️ Roadmap

阶段时间关键交付
✅ Phase 0 — 地基 2026 Q1
  • OpenSpec 6 Changes 产出
  • Skills Library 40 个 (~13 万字真实内容)
  • 8 Agent 预置 + Supervisor (关键词路由 + @mention 接力)
  • 合同模板 10 份
  • 报表模板 15 份 (全部带强制 tenant_id 过滤)
  • 隐私 MVP:
    • ✅ AuditLog append-only + SHA256 哈希链 + 并发安全
    • ✅ KillSwitch (Redis-first / file fallback)
    • ✅ PII 自动脱敏 (默认全量 + 可关 + WARN)
    • 🚧 NetworkWhitelist 实际拦截 (清单已有, 拦截层未接)
  • Integrations 15 个接口定稿 · 8 个已真接通 · 7 个 sandbox 可用
🚧 Phase 1 — 真实数据打通 2026 Q2
  • 驾驶舱 Cockpit UI(KPI / 趋势 / 告警 / 快捷操作)
  • Token 成本 Dashboard
  • MinIO 全链路接入
  • LiteLLM 配置 Prisma 计费
  • Tiptap 文档编辑器
  • 企业级对话交互记录
✅ Phase 2 — Agent 进化 (已交付) 2026 Q3
  • ✅ NocoBase 低代码平台集成 (含 Circuit Breaker 断路器 · token 预热 · 5xx 自动降级)
  • ✅ GEPA (Gradient-Enhanced Prompt Autotuning) · canary A/B · 每周自动进化 · HITL 一键采纳
  • ✅ Flow DAG 编排 · YAML 多 Agent 协同 · 并行 / 重试 / approval 卡点 / branch / cron
  • ✅ 第三方集成真实落地(国税发票验真 / e 签宝 / 阿里支付宝 / 企查查 / 阿里云 SMS / …)
  • ✅ Prometheus + Grafana + Sentry 全链路观测 · Langfuse LLM trace
  • 🚧 LangGraph StateGraph 后端迁移 (二期 · 当前自写 asyncio.gather 够用)
🎯 Phase 3 — 企业交付 (进行中) 2026 Q4
  • 🚧 Marketplace 收费商店 (订阅/按次/按 token · 70/30 分成 · 微信+支付宝结算) — 优先级最高
  • ⚪ 业务 Flow 模板 2 个 (invoice_to_voucher.yaml + contract_full_review.yaml)
  • ⚪ 集团客户私有化部署工具链 (一键脚本 + 双机热备)
  • ⚪ 多语言 (英 / 日 / 东南亚)
  • ⚪ SOC2 / ISO27001 合规认证 (准备文档已就绪: docs/SOC2_READINESS.md)

当前任务详情见 openspec/changes/README.md · 用户可读的版本见 YOUR_TODO.md


🤝 贡献

FinBox AI 遵循严苛的 AGENTS.md 开发铁律 —— 不做假功能 / Spec Driven / 真实链路 / Token 可控 / 归属人 / 世界级 UI / 开源优先 / 频繁 commit。

开发工作流

# 1. 新 feature 先提 OpenSpec proposal
openspec new change <change-name>

# 2. 写规范 (specs/*/spec.md + design.md + tasks.md)
# 3. 实现、自测
# 4. commit(中英文混合语义化,每改动必 push)
git add -A && git commit -m "feat(cockpit): 新增 token 成本卡片"
git push origin main

# 5. 勾选 tasks.md,更新 ARCHITECTURE.md / BUSINESS_FLOWS.md(如涉及)

分支策略

  • main —— 主线,必须可运行,commit 必 push
  • feat/* fix/* —— 大改动走分支,PR 合入
  • 绝不允许 uncommitted 丢失

Code Review 清单

  • 无 mock / placeholder / "TODO"
  • 有 spec 依据或已补 spec
  • LLM 调用写了 agent_audit_log
  • 敏感数据 PII Mask
  • 高风险动作走审批 Gate
  • 相关文档(ARCHITECTURE / BUSINESS_FLOWS / SITE_STRUCTURE / README)已同步
  • 单测 / E2E 通过

📞 联系


📄 License

Proprietary — © 2026 FinBox AI. All rights reserved.

本项目为闭源商业软件。未经书面授权,禁止复制、修改、分发或用于商业目的。

部分依赖遵循其原始开源许可(MIT / Apache 2.0 / BSD / AGPL),详见 backend/requirements.txt / frontend/package.json


Built with ❤️ for CFOs, Accountants, Auditors, Tax Pros, Legal Counsels, Sales, Procurement & HR Teams.

架构图每完成一个 feature 必更新 · Token 成本日级可查 · 审计日志永久留痕

About

tax

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors