generative-agent-assistant 0.1.0

A general-purpose generative agent runtime: ReAct loop, sessions, SSE streaming, MCP tool registry, charts and approvals, served by FastAPI with a built-in web UI.

generative-agent-assistant

通用 ReAct agent 运行时 —— 会话持久化 / SSE 流式输出 / 工具注册 / 图表渲染 / 人工审批 / 子代理派发，自带一套开箱可用的 Web 界面，由 FastAPI 承载。 pip install 之后跑一次配置向导填上你自己的模型与中间件地址，一条命令起完整服务。

A general-purpose ReAct agent runtime (sessions, SSE streaming, tool registry, charts, human approval, sub-agents) with a built-in web UI, served by FastAPI.

• 许可：MIT（随包的第三方前端库另有各自许可，见 gca/static/THIRD_PARTY_NOTICES.md）
• Python：>= 3.12

---

安装

pip install generative-agent-assistant

装完即有 gca 命令（init / doctor / serve）与 import gca 库入口。

---

60 秒上手

1. gca init —— 配置向导（只有 3 项必填）

$ gca init
GCA 配置向导 · 配置将写入 /Users/you/.gca/.env（权限 600）

[1/3] 大模型（必填，3 项）
  API Base URL    OpenAI 兼容端点                   : http://127.0.0.1:18111/v1
  模型名称        如 qwen-plus / glm-4.6            : qwen-plus
  API Key         （输入不回显）:
       ✓ 端点连通（50 ms）

[2/3] 中间件（可选，直接回车跳过）
  Redis URL       redis://[:密码@]host:port/db      :
       – 已跳过：「异步任务·run_bash」不可用
  MinIO Endpoint  host:port                         :
       – 已跳过：「文件上传·文档解析」不可用

[3/3] 服务
  监听端口        [8001]:

自动处理（不问你）：
  · JWT_SECRET  已生成 48 字节随机密钥（唯一的启动阻断项，不用你操心）
  · AGENT_BASH_SANDBOX  自动判定 = on（当前平台 Darwin）
  · AGENT_WORKSPACE  /Users/you/.gca/workspace（已创建）
  · DB_PATH  db/chat.db（相对 /Users/you/.gca，SQLite 首启自建）

降级清单（现在跳过，随时重跑 gca init 补上）：
  · 已跳过 Redis     → 「异步任务·run_bash」不可用
  · 已跳过 MinIO     → 「文件上传·文档解析」不可用

默认跳过：Langfuse 可观测 / SoMark OCR / 配置中心（要配请跑 gca init --advanced）

✓ 已写入 /Users/you/.gca/.env（权限 600）
  ⚠ 该文件含明文密钥，勿提交 git、勿贴聊天窗。

下一步：gca doctor 自检  →  gca serve 启动

上面是一次真机实跑的原样输出。其中大模型端点用的是本地 stub（127.0.0.1:18111）， 所以你会看到本地地址 —— 换成你自己的服务商端点即可。

2. gca doctor —— 起服前自检

$ gca doctor
配置文件   /Users/you/.gca/.env               ✓  (权限 600)
JWT_SECRET 已配置（64 字符）                       ✓
大模型     http://127.0.0.1:18111/v1  model=qwen-plus ✓  11 ms
Redis      未配置（可选）                          –  跳过 → 「异步任务·run_bash」不可用
MinIO      未配置（可选）                          –  跳过 → 「文件上传·文档解析」不可用
配置中心   未配置（可选）                          –  跳过
SQLite     /Users/you/.gca/db/chat.db         ✓  可写

结论：可启动（2 项功能降级）
  · Redis 未配置 → 「异步任务·run_bash」不可用
  · MinIO 未配置 → 「文件上传·文档解析」不可用

退出码语义：必填项不通过 → 1（不该起服）；只有可选项降级 → 0（可以起）。

3. gca serve —— 一键启动（含界面）

$ gca serve --port 18101
GCA 0.1.0 · home=/Users/you/.gca · 降级：Redis 未配 → 「异步任务·run_bash」不可用、MinIO 未配 → 「文件上传·文档解析」不可用
GCA 启动中 …  http://127.0.0.1:18101   (GCA_HOME=/Users/you/.gca)
停止：Ctrl-C
INFO:     Started server process [55650]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:18101 (Press CTRL+C to quit)

中间件都配齐时，第一行横幅变成：

GCA 0.1.0 · home=/…/home_full · 全部功能可用

启动后：

curl http://127.0.0.1:18101/health     # {"status":"ok"}
open  http://127.0.0.1:18101/          # 完整 Web 界面（89 KB HTML，静态资源随包发）

4. 首次使用：先注册一个账号

界面是带鉴权的，首次打开需要注册（本地 SQLite 存用户，无外部依赖）。 在界面上按提示注册即可；也可以直接调接口：

curl -X POST http://127.0.0.1:18101/api/auth/register \
     -H 'Content-Type: application/json' \
     -d '{"username":"yourname","password":"your-password"}'
# → 返回 access_token（注册即登录）；登录走 /api/auth/login

---

配置说明

配置文件落在 $GCA_HOME/.env（默认 ~/.gca/.env，权限 600）， gca init 负责生成，你也可以直接手改。

必填：只有大模型三件套

键	说明
LLM_BASE_URL	OpenAI 兼容端点，如 https://…/v1
LLM_DEFAULT_MODEL	默认模型名，如 qwen-plus
LLM_API_KEY	你的 API Key（明文落盘，权限 600）

不填这三项就没法对话；其余全部可自动生成、用默认值，或跳过后降级运行。

自动生成：JWT_SECRET

它是唯一会让服务起不来的必配项（空值或占位值直接 fail-fast）， 所以向导用 48 字节随机数直接生成，不问你。 重跑 gca init 会沿用已有值，已签发的 token 不会失效。

可选：跳过之后具体哪些功能不可用

中间件	键	跳过后不可用的功能	其余功能
Redis	REDIS_HOST / PORT / PASSWORD / DB	异步任务队列、run_bash 工具	照常可用
MinIO	MINIO_ENDPOINT / ACCESS_KEY / SECRET_KEY / BUCKET_*	文件上传、文档解析（PDF/Word 转 Markdown）	照常可用

对话、SSE 流式、会话历史、图表渲染、审批、子代理都不依赖这两个中间件 —— 只填大模型三件套就能起服并正常聊天（这一点有实测：三个外部服务全指死端口仍启动成功）。 SQLite 会在 $GCA_HOME/db/chat.db 自建，无需你准备数据库。

gca init --advanced 还会追问：第二个模型 provider、文档 OCR、可观测平台、外部配置中心 —— 都可留空。

配置解析优先级

真实环境变量（shell export / 容器 -e）   ← 最高，CI 与容器友好
  > $GCA_HOME/.env
  > 外部配置中心（仅当你显式配了地址才会尝试，失败自动回退 .env）
  > 代码内默认值

非交互 / CI / 容器

gca init --non-interactive \
  --set LLM_BASE_URL=https://your-endpoint/v1 \
  --set LLM_MODEL=qwen-plus \
  --set LLM_API_KEY=sk-xxx \
  --set REDIS_URL=redis://:password@127.0.0.1:6379/0 \
  --set MINIO_ENDPOINT=127.0.0.1:9000

REDIS_URL 会自动拆成代码消费的四个键；MINIO_ENDPOINT 带 scheme 也会归一成 host:port。 非交互模式下只从环境变量捡默认面的键，不会把你 shell 里其它同名变量烤进配置文件。

---

⚠ --home 是「粘」的

一旦你用了自定义目录：

gca init --home /srv/gca      # 配置写到 /srv/gca/.env

那么后续每条命令都必须带上同样的 --home，否则会去默认的 ~/.gca 找配置：

gca doctor --home /srv/gca
gca serve  --home /srv/gca

等价写法是导出环境变量 export GCA_HOME=/srv/gca，之后三条命令都不用再带 --home。 不带且默认目录没配置时，gca serve 会打印引导文案让你先跑 gca init（不会甩 traceback）。

$GCA_HOME 同时是数据锚点：SQLite 库、agent 工作区、mcp.json 都按它解析。 换 home = 换一套数据。

---

接入你自己的 MCP 工具

本包只内置 5 个通用工具：read_file / write_file / list_dir / run_bash / dispatch_agent。 领域能力（数据库、检索、内部系统…）请通过 MCP 自行接入 —— 在 $GCA_HOME/mcp.json 放一份配置即可：

{
  "servers": [
    {
      "id": "my-tools",
      "name": "My Tools",
      "enabled": true,
      "transport": "streamable-http",
      "url": "http://127.0.0.1:9000/mcp",
      "headers": {},
      "toolPrefix": "auto",
      "modes": ["agent"]
    }
  ]
}

字段语义：

• enabled 必须是 JSON 布尔 true（字符串 "false" 是 truthy，这里严格判定，避免「以为下线了其实在线」）
• modes 要包含 "agent" 才会在对话轮次里被装载
• toolPrefix："auto"（缺省）→ 工具名前缀为 mcp__my_tools__；给空串 "" 则用裸名
• 环境变量 GCA_MCP_URL_<ID大写下划线> 可覆盖 url（容器内换内线地址用），不影响工具名与路由

没有 mcp.json 是完全正常的初始态：配置加载返回空列表、不抛异常， agent 直接走内置工具集，服务照常可用。 （只有写坏了 JSON 才会报错 —— 那是真错误，静默吞掉比报错更糟。）

---

作为库使用

from gca.main import app                 # ASGI 应用，直接交给 uvicorn
from gca.agent.loop import run_loop, run_loop_stream, dispatch
from gca.agent.tools import DEFAULT_TOOLS
from gca.agent.mcp_client import load_mcp_config

uvicorn gca.main:app --host 0.0.0.0 --port 8001

import gca 期间零网络、零拨号：不读包外路径、不连配置中心，配置与连接全部下沉到显式入口。

---

边界与已知限制

• 本包不含任何自然语言取数 / Text-to-SQL 能力，也不含任何业务数据字典或行业口径。 它是一个纯粹的通用 agent 基座；这类能力请以 MCP 工具的形式自行接入。
• gca init 的模型校验只发 GET {base_url}/models 探活，不发 chat 请求 —— 不替你烧配额。代价是：只开放 chat 接口、不实现 /models 的端点会被标成「可达但 HTTP 404」， 这属正常，可以直接继续。
• Python >= 3.12，3.11 及以下装不了。
• API Key 明文落盘在 $GCA_HOME/.env。文件权限已钉死 600、目录 700， 但仍请勿提交 git、勿贴进聊天窗。
• Redis / MinIO 需要你自备（向导只问 URL，不代管安装）。
• 默认监听 127.0.0.1（仅本机）。要对外提供服务请显式 --host 0.0.0.0， 并自行处理反向代理与 TLS。

---

第三方组件

随包的 gca/static/ 内含三个 vendored 前端库，版权归各自作者，按各自许可分发：

库	版本	许可
Apache ECharts	5.6.1	Apache-2.0
marked	12.0.2	MIT
DOMPurify	3.4.11	Apache-2.0 OR MPL-2.0

完整版权行与许可声明见包内 gca/static/THIRD_PARTY_NOTICES.md。

---

许可

MIT © Albert Xu