FinanceOps Agent Lab

Overview

FinanceOps Agent Lab is a local-first experimental agent workbench for structured financial data reading, policy intelligence, and tool-based analysis workflows.

中文名：财税运营智能体实验室。

FinanceOps Agent Lab 是一个本地优先的财税数据分析 Agent 工具台，用于表格结构读取、政策信息检索、工具化分析流程和可人工复核的结构化输出。

It is maintained as a personal engineering archive and demo-oriented project. The focus is on modular agent architecture, tool orchestration, workspace-based analysis, and human-reviewable outputs.

This repository is not a formal financial, tax, legal, or compliance product. It is an engineering workbench for local experiments and public portfolio review.

Core Capabilities

• Structured tabular data reading / 表格结构读取
• Policy intelligence and evidence triage / 政策信息检索与证据分层
• Agent tool runtime / Agent 工具运行时
• Workspace sandbox / 工作区沙箱
• Human-reviewable report output / 可人工复核的报告输出
• Optional collaboration integrations / 可选协作平台集成

Architecture

Desktop GUI
   ↓
Agent API
   ↓
Agent Runtime
   ↓
Tools Layer
   ├── Tabular Reader
   ├── Policy Monitor
   ├── Workspace Explorer
   └── Report Formatter
   ↓
Human-reviewable Output

• Desktop GUI: local control panel for chat, workspace access, settings, and review surfaces.
• Agent API: local HTTP API for health checks, workspace inspection, and agent interaction.
• Agent Runtime: orchestration layer for prompts, tool calls, approval gates, and session state.
• Tools Layer: file reading, table parsing, policy search, workspace operations, chart/report helpers.
• Workspace Sandbox: local file and artifact boundary for safer workspace-based analysis.
• Optional Integrations: Feishu or other collaboration platforms can be retained as integration modules, but they are not the core public entry point.

Repository Structure

apps/desktop-gui       Desktop GUI built with Vite and React.
services/agent-api     Local HTTP API for health, workspace, threads, and agent chat.
services/policy-monitor Policy information collection and query service.
packages/agent-core    Agent runtime, tool orchestration, sandbox, and CLI entry points.
packages/tools         Python tools for file ingestion, table reading, and integrations.
packages/memory        Memory-related abstractions and test fixtures.
packages/workflows     Reserved workflow package area.
docs                   Public docs plus historical development records.
scripts                Development and local startup scripts.
tests                  Top-level test placeholder area.

Some documents under docs/ are retained as migration and development records. They do not all represent the final public product specification.

Quick Start

Install dependencies from the repository root:

npm install

Start the local Agent API:

npm --workspace @anxin/agent-api run dev

In another terminal, start the desktop GUI:

cd apps/desktop-gui
npm install
npm run dev -- --host 127.0.0.1

Open:

• GUI: http://127.0.0.1:5174/
• API: http://127.0.0.1:8787

The workspace package name @anxin/agent-api is retained as a compatibility name. The public project name is FinanceOps Agent Lab.

Environment Variables

• Real .env files must not be committed.
• .env.example can be used as a field reference.
• Model provider credentials must be configured locally.
• /api/health may return ok:false when local model credentials are not configured. This means the server is reachable but the model provider is not ready.
• Do not place real API keys, private tokens, or customer data in docs or sample files.

Demo Workflows

Tabular Reading

读取这个表格，识别所有 sheet、字段、表头层级和异常空值。

Policy Intelligence

检索与出口退税相关的政策信息，并区分官方来源和参考来源。

Workspace Exploration

检查当前工作区文件，列出可用于财务分析的数据表、报告草稿和待补材料。

Structured Report Output

将读取结果整理成 Markdown 报告，并区分事实、推断和待人工确认项。

These prompts are demo prompts only. They do not promise legal, tax, accounting, or compliance conclusions.

Validation

Frontend validation:

cd apps/desktop-gui
npm run build
npm test

API smoke checks, after starting npm --workspace @anxin/agent-api run dev:

curl -s http://127.0.0.1:8787/api/health
echo
curl -s http://127.0.0.1:8787/api/workspace
echo

/api/health may return ok:false when local model credentials are not configured. This means the server is reachable but the model provider is not ready.

Current Status

• Desktop GUI can run in dev mode.
• Desktop GUI production build passes.
• Desktop GUI tests pass.
• Agent API can start locally.
• Workspace endpoint returns successfully.
• Root-level tests pass.
• Model provider validates successfully when local credentials are configured.
• npm audit has no high or critical findings after the final dependency review.
• MIT License is recorded in LICENSE.
• Public release readiness gate passed; repository visibility must still be changed manually by the owner.

Public-readiness records:

• docs/public-release-audit/public-release-readiness.md
• docs/public-release-audit/public-release-final-check.md
• docs/model-provider-validation.md
• docs/legacy-naming-decision.md

Known Limitations

• This project is not a production tax or compliance product.
• Generated outputs require human review.
• Some historical package names and internal identifiers still use legacy names for compatibility.
• Local model credentials are required for runtime validation and must never be committed.
• Remaining npm audit moderate findings were reviewed; no high or critical findings remain.

Data and Privacy Policy

• No real customer data should be committed.
• No real .env files should be committed.
• API keys and credentials must be configured locally.
• Sample files should use synthetic or anonymized data only.
• Generated artifacts should be reviewed before sharing outside a local workspace.
• Public-release sanitization is a release gate: local runtime outputs, raw workspace artifacts, private customer data, and real credentials must stay out of Git.
• The final public-readiness scan did not identify real credentials or obvious real customer data.

Disclaimer

This project does not provide legal, tax, accounting, or compliance advice. All generated outputs should be reviewed by qualified humans before use.

Roadmap

• Sanitize historical docs and example data.
• Add public demo prompts.
• Keep root-level test baseline green.
• Replace legacy package names only if compatibility cost is acceptable.
• Keep repository visibility changes as the final manual owner action after PR merge.

License

This project is released under the MIT License. See LICENSE for details.