内容
align="center">
<img src="img/Geny_full_logo.png" alt="Geny" width="520"/>
</p>
<h1center">Geny — <em>Geny 执行，不</em></>
<p align="center>我来处理 — 你只需坐享其成></p>
<p align="center">
多智能体uber +工作者</strong> 平台。 将一个会聊天的D / Spine VT运行工具的子配对，在 3D 城市中观察它们通过一次配置点击切换 LLM 后端。
</p>
<p align="center href="README_ko.md">한국어 README> ·
<a href="itecture.md">架构</ ·
<a href=".md">LLM 提供商</a> ·
<adocs/sessions.md和委托</a> href="docs/environments.md">环境</a> ·
<a href="docs/error错误代码</ap>
<p align">
<aLICENSE"><img src="img.shields.io/badge/license-Apache--2.0 alt="License:2.0"></ <a href="https://github.com/CocoRoF/Geny/releases/latest"><img src="https://img.shields.io/github/v/release/CocoRoF/Geny?label=desktop%20connector&color=8b5cf6" alt="最新版本"></a>
<a href="https://pypi.org/project/geny-executor/"><imghttps://img.shields.io/pypi/v/geny-execlabel=geny-executor&color=3775a alt="geny on PyPI"></ <img src="https://img.shields.io/badge3.11%2B-3776ab" alt 3.11+">
<img src="https://img.shields.io/badge/next.js-16-black" alt="Next.js 16">
<a href="https://github.com/CocoRoF/Geny/stargazers"><img src="https://img.shields.io/github/stars/CocoRoF/Geny?style=social" alt="GitHub stars"></a>
</p>
```bash
# 60 秒启动 — GPU，无需 API
git clone https://githubocoRoF/Geny.git && cd Geny && ./geny up
# → 打开 http://localhost:3000
```
<p align="center"><sub>详情，配置文件和手动设置 → <a href="#installation">安装</a></sub></p>
## Geny 生态系统
这些项目旨在协同工作。 **Geny** 是堆栈顶；下面每个项目都是可独立使用的积木块。 **标记当前位置。**
| 介绍 |栈中的角色 |
---|
| ➡️y**](https:///CocoRoF/) | 多智能uber + 自主平台 | 产品 —所有项目 |
| [**-executor**](https:///CocoRoy-executor) | 21 阶段，基于智能体流程 · · Apache-2.0 | 引擎 — 所有项目运行的基础 |
| [**GAPT**](https://githubocoRoF/genapted-project-toolkit 自托管 AI DevOps 平台 — 沙盒 · 构建 · 智能体安全真实仓库的地方 |
| [**geny-avatar**](https.com/CocoRoy-avatar) |D live-avatar 编辑含 AI 纹 | Geny 面孔的制作地点 |
| [**edit2docs**](https:///CocoRoFdocs) | AI 智能体原生 DOCX / / PPTX PyPI · Apache.0 | 智能、编辑和预览办公文档的方式 |
| [****](https://githubocoRoF/an | AI 原生浏览器引擎 · Py 智能体读取和搜索网页的方式 |
<details>
它们如何协同工作</summary>
```
— 产品（使用内容）
│
┌─────────────┼──────────────┐
智能体 avatars + 部署
│ │ │
▼ ▼y-executor gen GAPT
引擎） （avatar） （ 平台）
edit2docs文档：生成 · 原生预览）
-Web （网页 · 读取 · </details>
---
📸 IMAGE N hero screenshot — theD city playground with + the VTuber chat2D avatar overlaid -->
> 📸图片** — _英雄截图：3D 乐场，智能走，VTuber天面板和 Live2D avatar 叠加。 桌面连接
一个 **VTuber 连接器**，浮动在桌面底部 — 保持服务器运行，实时 avatar 出现在屏幕底部。
<!-- 📸 IMAGE NEEDED: the desktop connector — the floating avatar sitting at the bottom of a real desktop, tray menu open -->
> 📸 **需要图片** — _桌面连接器：浮动的 avatar 位于真实桌面底部菜单打开。_
### 1) 安装程序 — **[最新版本获取](https://github.comRoF/Geny)**
| 操作 | 安装 /启动 |
|---|---| **Windows** |y-Setup-` | 双击 → SmartScreen 警，**更多信息仍然运行** （签名） |
| **macOS** | `-*.dmg` | 打开并拖动到应用程序 → 首次启动右键 → 打开** （Gatekeeper） |
| **Linux** | `Geny-*.AppImage `*.deb`Image：`chmod Geny-*.App ./GenyAppImage` · debsudo dpkg Geny-*. |
> 尚未安装程序？该在构建中 — 这仓库，因此 GitHub Actions 自动构建 macOS / Linux 安装程序。
2) 启动后 — **仅需三个字段即可登录**
1. **Geny 服务器地址** — 预填充为 `https://-x.hrletsgo.me` （或您自己的主机，如果您自行托管）。
2. **管理员 ID**
3. **管理员密码**
登录**，将保存到您的链中；avatar屏幕底部，准备 （拖动 avatar它；托盘图标打开设置 / 更新 /。）
### 自动从 v0.3 开始，连接通过 GitHub Releases 自动更新** — 它在运行时检测到新版本，在重启时应用（您也可以通过托盘检查 *检查）。 Windows · LinuxImage）版本无需签名即可工作；macOS在应用代码签名。 *仅需手动，以后的每个自动的。*
源代码构建
```bash
git clone https://github.com/CocoRoF/Geny.git
cd/desktop
npm install
npm run dev # 开发运行
npm run dist:win # / dist:mac / dist — 自己构建安装```
更多信息： [`.md`](desktop/README · 设计：_docs/vtuber-desktop/PLAN.md`](devtuber-desktop/PLAN.md)
---
## Geny 是什么="img/Geny_Charactor.png" align="right" width="200" alt="Geny 角色"/>
| 概念 | 介绍 |
|---|---|
| **VTuber 会话** | 对话式界面。 Live2D / Spine avatar，角色提示，TTS，情绪标签。 与用户交将实际工作对的子工作器| **子会话** |。 使用工具的智能体 — 文件操作，网页抓取，MCP 桥接的主机工具。 通过结构化的_WORKER_RESULT]`结果报告回 **环境**序列化的 [`EnvironmentManifest`](docs/environments.md固定了每个管道阶段 + 提供者 + 。 一个工确定性重现| **3D 乐场**.js / React Three仪表盘 — 表现为在程序行走的角色 **五个 LLM 后端** | `anthropic` / `openai` / `google` / `vllm` （自托管）/ `_cli` — 切换每个环境，无需。 |
| **稳定的错误代码** | 每个执行器失败都会出现一个稳定的 `exec.<reason>` 代码。 前端渲染本地化，可语 / 英语提示。 |
后端基于 [`geny-executor`](https://github.com/CocoRoF/geny-executor) 21 阶段的基于清单的智能体无 LangChainGraph）。前端是 Next.js 16，3F 驱动的D，Pix 用于白板 / 2D 叠，以及韩语 /18n 层 架构（高层次）
<!-- NEEDED: diagram to replace / ASCII map below -->
```
┌────────────────────────── ─────────────────────────────────│ │
│端（Next.js 16 + R3Fi） │
│ ├── 3城市游乐场.js / R3 │
│ VTuber 聊 + Live2D avatar │
│ ├── 环境编辑器（21 阶段的清单 │
│ 端设置（提供者卡） │
│ ├── 知识 / 白板选项卡 │
└── 日志选项国际化的错误代码，迹，阶段事件） │
││ 后端（FastAPI） │
│ ├── 控制器 / ← FastAPI 路由（会话，环境，VTuber，…） │
│ ├── 服务 / │
│ │ ├── 执行器 / ← geny-executor 连接 │
│ │ ├── gapt / ← GAPT 客户端 + 工作区提供者 │
│ │ ├── 环境 / ← 清单 模板 │
│ │ ├── llatches / ← 韩语错误信封 工具点击 │
│ │ ├── 内存 / ← 会话内存 v2 +检索 │
│ ├── ← 每个 ACL 评估 │ ├── VTuber / ←D / Spine 思考触发 │
│ │ └── 聊天 / ←天室存储 + 委托路由 │
│ ├── 工具 / ← 自动加载的 Python 工具（发送内存，…）│ ├── mcp / ← 自动加载的 MCP 服务器配置 ├── 脚本 / geny_mcp_bridge.py ← 每个会话包装，用于 |
│ └── / ← （vtuber.md，worker.md，… │
│ geny-exec2.47 PI 依赖） │
│ ├── 阶段的智能体流程 │
│ 5 个 LLM │
├── ContainerCLIRunnerHandle（在中运行 CLI│ └── Executor 分类 │
│
│ g ← G模块（沙盒） │
├── 服务器 /API 控制平面（项目 / 工作区 / …） │
│ 每个工作区的容器 文件系统 · 终端 · 预览 │
│ 管道（组合 / webhook 目标）└────────────────────────────────┘
```
完整架构文档 → [`itecture.md`](docs/architecture.md)。
GenyAPT 集成 →/analysis-integration-plan.md`](analysis/gapt-integration)。
---
##
### VTuber工作器配每个 VTuber 会自动与子工作器配对。 VT对话和个性工作器执行实际委托流经一个 MCP 桥接cp____send_direct_message_internal`) — 参见 [`docs/sessions.md`](docs/sessions.md)。
### 五个 LLM 后端，一个选择器
设置 → LLM 后端为每个提供者（Anthropic / OpenAI / Google / vLLM / Claude Code CLI）提供一个卡片，带有健康探测 + 。 任何 6通过下拉菜单选择 参见 [`.md`](docs/providers<!-- 📸 IMAGE: Settings → LLM — the with health status📸 **** — _设置 → LLM 后端：者卡片及其健康状态。_
### 基于清单管道定义EnvironmentManifest` JSON 工件 — 21，每个插槽一个策略，版本控制。环境编辑器自定义任何预设器 / VT 子工作器）触及代码参见 [`docs/environments.md`](docs/en)。
<!-- 📸 IMAGE NEEDED: the Environment editor — the 21-stage manifest UI with strategy dropdown> 📸图片** — _环境编辑器：21 阶段的清单 UI，带有策略下拉菜单。 每个会话 包装（Cl CLI）
当 `claude_code_cli` 固定为其第 6 时，Geny一个每个会话桥接，以便生成的 CLI 的 LLM 将y 的工具注册表** 视为 `mcp__geny__ — 文件抓取，发布者器委托 — 所有这些都可以在 CLI体循环中。
### 稳代码 + 国际每个执行器异常 `exec.<>`话日志呈现韩语（）消息 + 推荐的下一步操作，而不是原始的英语服务器错误 — [`docs/error`](docs/error)。
### 3城市游乐活动会话表现为程序 资产城市走角色。 A径查找，骨骼动画头像循环。 R3 Drei + Three<!-- 📸 IMAGE NEEDED: the city playground — agents walking the procedural city,-day lighting -->
**需要图片 _3D游乐场：智能体在程序生成的城市中行走，时间循环照明。_
### Live2D + Spine + AI 烘焙头像
Geny 配备了一个独立的木偶编辑器服务 ([`geny-avatar`](https://github.com/CocoRoF/geny-avatar))，作为 git 子 上传 Spine 木偶图层，罩，使用 AI理模型直接烘 Geny 的 VTuber 库中。
/ / 语音笔记-tts 用于输出isper 用于输入，OmniVoice 多说话者 语音笔记在白板述。
###板 + 内存 v2
会话内存geny-exec 的第 2 阶段（上下文）和18 阶段）路由 — 渐进式披露，保险库地图，矢量检索。 知识白了一个用于图表的协作.js 画布。
### 就绪
的会话元数据分片允许多个后端 pod 为一个用户提供服务 — 可用于云部署。
### 沙和部署（GAPT）
项目 / 沙盒 / 部署被委派给 **[GAPT](github.com/CocoRoF/genapted-project-toolkit)** （y-adapted-project-toolkit作为 **git 子模块** 在/`](gapt/)（main`；`.githooksmerge` 自动通过 `git pull` 滚动）。 GAPT 在其自己的隔离git · 文件操作 · 开发服务器预览 · 组合 / ssh 部署目标）中运行每个工作 Postgres 支持和 Caddy 路由。 Geny 保留其自己的智能（角色 · 语音 · 情绪 · 内存），并通过执行器的 `ContainerCLIRunner` 将会话指向 工作区 — 因此智能体在中编辑代码，而 Geny 的护城河保持在主机侧。 也可以通过其 41 种工具的 MCP 直接驱动 GAPT。 设计： [`docs/analysis/gapt-integration-plandocs/analysis/gapt-integration-plan.md) · 部署和测试： [`docs/gapt-test-guide.md`](operations/gapt-test-guide.md)。
---
## 项目结构
```
geny/
.md / README_ko.md 此中心枢纽
├── img/ # logo 和截图
├── docs/ # 主题页面文档（架构，会话等）
├── backend/ # + geny-executor 主│ ├── main.py # 应用程序入口 + 执行器连接
│ pyproject.toml # 固定 geny-executor >= 2.47.0
│ ├── controller/ # FastAPI 路由
│ │ ├── agent_controller.py # 会话 + 流 + 调用
│ │ ├── llm_backends_controller.py# 5 个提供商的健康状况认证
│ │ ├── mcp_bridge_controller.py # 每个会话的 MCP RPC
│ │ ├── vtuber_*.py # VTuber 库 + 聊天 + 思考
│ │ ├── memory_*.py # 内存 + 知识 + 运算
│ │ ├── chat_controller.py # 聊天室 CRUD
│ │ ├── environment_controller.py # 清单编辑器后端
│ │ └── … # cron，whiteboard，语音笔记，...
│ ├── service/
│ │ ├── executor/ # AgentSessionManager + AgentSession
│ │ ├── environment/ # 清单存储 + 模板
│ │ ├──.py # 韩语错误信封 + CLI 工具点击
│ / # 会话内存 v2
│ │ ├── permission/ # 每个工具的 ACL
│ │ ├── vtuber/ # Live2D / Spine 库 + 触发器
│ │ ├── chat/ # 聊天室存储 + 委托路由
│ │ ├── config/ # ConfigManager + 设置卡
│ │ ├── logging/ # SessionLogger（现在带有 error_code）
│ │ └── …
│ ├── # 自动加载的 Python
│ │ ├── built_in/ # 配备：消息，内存，知识
│ │ └── custom/ # web_search，browser，whiteboard，blog
│ ├── mcp/ # 自动加载的 MCP 服务器配置
│ ├── scripts/geny_mcp_bridge.py # CLI 包装，用于 stdio
│ └── prompts/ # 角色 markdown（vtuber.md，worker.md，…）
├── frontend # Next.js 16 + R + Pixi
│ └── src/
│ ├── components/ # 选项卡，模态窗口，面板，env_management/…
│ ├── lib/ # api.ts，i18n/，modelCatalog.ts，…
│ ├── store/ # Zustand 存储
│ └── types/ # 共享 TypeScript 类型
├── vendor/geny-avatar/ # 木偶编辑器子模块
├── gapt/ # GAPT git 子模块（跟踪 main）
│ ├── server/ # FastAPI 控制平面（项目/工作区/…）
│ ├── compose/ # GAPT 组合栈（postgres/redis/caddy/…）
│ ├── docker/workspace/ # 每个工作区的沙盒镜像
│ └── mcp/ # 41 种工具的智能体 MCP，用于 GAPT
└── docker-compose.{yml,dev,prod}.yml # 组合栈
```
有关开发者内部架构图，请参见 [`backend/docs/`](backend/docs/) 和 [`docs/architecture.md`](docs/architecture.md)。
---
## 技术栈
| 层 | 技术 |
|---|---|
| **前端** | Next.js 16, React 19, TypeScript, Tailwind CSS v4, Zustand 5, Pixi.js |
| **3D 引擎** | Three.js, React Three Fiber, Drei |
| **虚拟人** | Live2D Cubism, Spine 4, [geny-avatar](https://github.com/CocoRoF/geny-avatar) 编辑器 |
| **后端** | Python 3.11+, FastAPI, Uvicorn |
| **智能代理流水线** | [`geny-executor`](https://github.com/CocoRoF/geny-executor) （21 个阶段，5 个提供商） |
| **LLM 软件开发工具包** | `anthropic`, `openai`, `google-genai` + vLLM（兼容 OpenAI）+ Claude Code CLI 子进程 |
| **MCP** | 主机附加服务器 + 每会话 CLI MCP 包装 |
| **文本转语音 / 语音转文本** | edge-tts（输出），Whisper（输入），OmniVoice（多说话者） |
| **持久化** | PostgreSQL（会话，内存，知识），Redis（多 pod 元数据，可选） |
| **容器** | Docker Compose（开发/生产配置文件 + OAuth 凭证生存的命名卷） |
---
## 安装
### 一键安装（推荐）—— `./geny up`
轻量级路径：启动并运行，无需 GPU，无需 API 密钥，无需 Git 子模块。
```bash
git clone https://github.com/CocoRoF/Geny.git
cd Geny
./geny up # postgres + backend + frontend（无 GPU，无密钥）
```
`./geny up` 处理以下任务：检查 docker/compose → 初始化 `.env`（如果丢失，则从示例中获取）→ 构建 + 启动 → 等待后端健康 → 打印 URL。打开 **http://localhost:3000** → 创建管理员账户 → **设置 → LLM 后端**：
- **本地 & 无密钥**：启动 Ollama，然后在 Ollama 卡上 *发现模型*。
- **云端**：将 Anthropic / OpenAI / Google 密钥粘贴到其卡中。
其他命令：
```bash
./geny up --full # + 虚拟人编辑器（Git 子模块）+ 本地 GPU 文本转语音/语音转文本（NVIDIA）
./geny doctor # 诊断主机设置（--fix 初始化 .env / 初始化子模块）
./geny logs backend # 跟随日志
./geny update # Git 拉取 + 重建 + 重启
./geny down # 停止
```
> 轻量级堆栈使用云端 edge-tts 进行语音。自托管高质量语音（OmniVoice）+ 语音转文本（Whisper）在 NVIDIA GPU 存在时，通过 `./geny up --full`启用。
### Docker（手动）
```bash
# 1. 克隆带有子模块（gapt + geny-avatar + geny-licensed-assets）
git clone --recurse-submodules https://github.com/CocoRoF/Geny.git
cd Geny
# 如果没有使用 --recurse-submodules 克隆？请拉取它们：
# git submodule update --init --recursive
# 自动在每次拉取时更新主跟踪子模块（gapt，geny-avatar）：
# git config core.hooksPath .githooks # 一次性；运行 `submodule update --remote`
# 按需更新 GAPT 到最新的上游主分支：
# git submodule update --remote gapt && git add gapt && git commit -m "chore: bump gapt"
# 2. 配置
cp backend/.env.example backend/.env
# 编辑 backend/.env — 至少设置 ANTHROPIC_API_KEY（或通过设置使用 OAuth）
# 3. 运行
docker compose up --build
```
打开 **http://localhost:3000**。
Compose 配置文件：
| 文件 | 用途 |
|---|---|
| `docker-compose.yml` | 默认开发堆栈 |
| `docker-compose.dev.yml` / `dev-core.yml` | 开发环境，热重载绑定挂载 |
| `docker-compose.prod.yml` / `prod-core.yml` | 生产环境，位于 nginx 后面 |
自定义端口 + 数据目录记录在 [`docs/architecture.md`](docs/architecture.md) 中。
### 手动设置
对于非 Docker 开发，请参阅 [`docs/architecture.md`](docs/architecture.md) 中的可展开部分。最低要求：Python 3.11+，Node.js 18+，Claude Code CLI（`npm i -g @anthropic-ai/claude-code`），以及至少一个提供商的凭证。
**文档编辑/预览不需要额外的系统软件包。** 智能代理编辑用户上传的办公文件（pptx / docx / xlsx）并在会话的 Canvas 标签中显示实时预览，通过 [edit2docs](https://github.com/CocoRoF/edit2docs) 的原生 OOXML 渲染管道（geny-executor ≥2.44）—— LibreOffice 和 poppler 不再需要，已从 Docker 镜像中删除（~500 MB 更轻） 。韩文文档开箱即用（捆绑的 Noto CJK 处理）。
---
## 虚拟人编辑器（geny-avatar）
Geny 配备了一个 Next.js 虚拟人编辑器服务（[`geny-avatar`](https://github.com/CocoRoF/geny-avatar)）作为 Git 子模块在 `vendor/geny-avatar` 下。上传 Spine 或 Cubism 虚拟人，分解图层，绘制遮罩，使用 AI（gpt-image-2 / SAM）重新生成纹理，并直接将模型烘焙到 Geny 的 VTuber 库中（它带有 `(Editor)` 后缀）。
`vendor/geny-avatar` 通过版本化的 `post-merge` 钩子跟踪 `main`分支（`.githooks/post-merge`）—— 服务器在每次 `git pull` 时快速转发子模块，无需指针跳转。
```bash
git config core.hooksPath .githooks # 每个克隆一次
git pull # 快速转发 vendor/geny-avatar
docker compose -f docker-compose.prod.yml --profile tts-local up -d --build avatar-editor backend
```
详细集成 → [`docs/_archive/`](docs/_archive/) （geny-avatar 集成冲刺）。
---
## 环境变量
在 `backend/.env` 中配置:
| 变量 | 描述 | 默认值 |
|---|---|---|
| `APP_HOST` | 服务器绑定地址 | `0.0.0.0` |
| `APP_PORT` | 服务器端口 | `8000` |
| `DEBUG_MODE` | 详细日志记录 | `false` |
| `ANTHROPIC_API_KEY` | Anthropic 密钥（或通过设置使用 OAuth） | — |
| `OPENAI_API_KEY` | OpenAI 密钥（或通过设置粘贴） | — |
| `GOOGLE_API_KEY` | Google GenAI 密钥 | — |
| `GITHUB_TOKEN` | GitHub PAT，用于 PR 自动化 | — |
| `USE_REDIS` | 启用 Redis 多 pod 元数据 | `false` |
| `REDIS_HOST` / `REDIS_PORT` / `REDIS_PASSWORD` | Redis | `localhost` / `6379` / — |
| `GENY_AGENT_STORAGE_ROOT` | 会话存储路径 | `/data/geny_agent_sessions`（Docker） |
前端的 `API_URL` 环境变量（shell，构建时）覆盖后端目标 — 参见 [`docs/architecture.md`](docs/architecture.md)。
---
## 快速 API 游览
Geny 在 `/api/` 下公开 REST + SSE。最常用的：
```bash
# 创建 VTuber 会话（自动配对子工作器）
curl -X POST http://localhost:8000/api/sessions \
-H "Content-Type: application/json" \
-d '{
"session_name": "geny-1",
"role": "vtuber",
"env_id": "template-vtuber-env",
"character_display_name": "Geny"
}'
# 列出会话
curl http://localhost:8000/api/sessions
# 向 VTuber 发送聊天消息（自动委托给子工作器处理复杂任务）
curl -X POST http://localhost:8000/api/chat/rooms/<room_id>/messages \
-H "Content-Type: application/json" \
-d '{"content": "Create test.txt and write a short self-introduction in it"}'
# 流式传输会话日志（SSE）
curl -N http://localhost:8000/api/command/logs/<session_id>/stream
```
| 端点家族 | 用途 |
|---|---|
| `/api/sessions` | 会话 CRUD + 状态 |
| `/api/agent/sessions/{id}/invoke` | 一次性调用 |
| `/api/command/logs/{id}/stream` | SSE 日志流（携带错误代码用于国际化） |
| `/api/chat/rooms/*` | 聊天室存储（VTuber ↔ 用户消息） |
| `/api/environments` | 清单 CRUD + 模板 |
| `/api/llm-backends` | 5 个提供商的健康状况，身份验证，登录流程 |
| `/api/internal/mcp/{sid}/rpc` | 每会话 MCP 桥接（CLI 包装） |
| `/api/vtuber/library` | Live2D / Spine 模型注册表 |
| `/api/memory/*` | 会话内存 + 知识白板 |
完整 API 参考 → `/docs` （FastAPI 自动生成），当后端运行时。
---
## 工具和技能
### 基于 DB 的自定义工具（UI 驱动 - 推荐）
在 **环境管理 → 自定义工具** 标签中注册 HTTP API，无需编写 Python：
| 后端类型 | 功能 |
|---|---|
| `http` | 发出 HTTP 请求。 `${arg:foo}` / `${secret:KEY}` / `${session:session_id}` URL、标头、主体中的占位符 |
| `mcp_proxy` | 将上游 MCP 服务器的工具重新暴露在新名称下，并带有可选的模式叠加层 |
| `builtin_alias` | 现有 `backend/tools/custom/*_tools.py` Python 工具的元数据叠加层 - Geny 自带 `blog_agent_*` 系列作为示例 |
完整指南 → [`docs/custom_tools.md`](docs/custom_tools.md)。
存储为 `custom_tools` 表中的 JSONB 行（模型：[`backend/service/database/models/custom_tool.py`](backend/service/database/models/custom_tool.py)）并在每次 CRUD 变更时热重载到实时 `ToolLoader`中 - 无需进程重启。
### 自动加载的 MCP 服务器
将 `.json` 文件放入 `backend/mcp/`，它将在每个会话中通过环境清单拉取：
```jsonc
// backend/mcp/github.json
{
"type": "http",
"url": "https://api.github.com/mcp/",
"description": "GitHub MCP 服务器"
}
```
参见 [`backend/mcp/README.md`](backend/mcp/README.md)。
### 自动注册的 Python 工具
将 `*_tools.py` 文件放入 `backend/tools/custom/`：
```python
# backend/tools/custom/search_db_tools.py
from tools.base import tool
@tool
def search_database(query: str) -> str:
"""Search the database for records"""
return f"Results for: {query}"
TOOLS = [search_database]
```
参见 [`backend/tools/README.md`](backend/tools/README.md)。对于更丰富的人体工程学（描述/模式编辑/从 UI 进行 dry-run），请优先使用 **基于 DB 的自定义工具**路径。
### 技能（SKILL.md）
每个会话都带有斜杠命令风格的技能。Geny 配备了多个层级：
- `executor` — 捆绑在 `geny-executor` 本身。
- `geny` — 第一方 Geny 技能 (`backend/skills/bundled/`).
- `sample` — Geny 提供的 *模板* (`backend/skills/samples/`)，您可以复制到自己的技能中。
- `user` — 操作员提供的位于 `~/.geny/skills/` 下（通过 `skills.user_skills_enabled` 启用）。
通过 **环境管理 → 技能** 标签进行管理。
### 每会话 MCP 包装（Claude Code CLI）
当会话的第 6 阶段提供商为 `claude_code_cli` 时，Geny 将其自己的工具注册表附加到生成的 CLI 的 LLM 上，通过 stdio MCP 桥接器 (`scripts/geny_mcp_bridge.py`)。CLI 的 LLM 将 `send_direct_message_internal`、`memory_write`、`web_search` 等视为 `mcp__geny__<tool>` 并原生调用它们 - 有关完整流程，请参见 [`docs/sessions.md`](docs/sessions.md)。
---
## 错误处理 + 国际化
每个执行器异常都带有稳定的 [`ExecutorErrorCode`](https://github.com/CocoRoF/geny-executor/blob/main/docs/error_codes.md)，例如 `exec.cli.auth_failed`。后端将其通过 `SessionLogger` 线程到 SSE 有效载荷；前端渲染本地化消息 + 通过 `executor.<code>` 国际化查找的可行下一步骤。而不是原始的英文服务器消息，终端用户看到的是（韩文示例）：
> Claude Code CLI 인증이 만료됐어요. 설정 → LLM 백엔드 → Claude Code (CLI) 카드의 ‘다시 로그인’을 누르거나 `ANTHROPIC_API_KEY` 를 붙여넣어 주세요.
详细流程 → [`docs/error_codes.md`](docs/error_codes.md)。
---
## 跨平台支持
- **Windows**： `%LOCALAPPDATA%\geny_agent_sessions`，自动检测 `.cmd`/`.exe` 可执行文件。
- **macOS / Linux**：`/tmp/geny_agent_sessions`（主机）→ `/data/geny_agent_sessions`（容器）。
---
## 社区
| 贡献者 | 什么 | 链接 |
|---|---|---|
| <a href="https://github.com/SonAIengine"><img src="https://avatars.githubusercontent.com/u/166786347?v=4&s=48" width="48" height="48" alt="Son Seong Jun" title="Son Seong Jun"/></a> [`graph-tool-call`](https://github.com/SonAIengine/graph-tool-call) | 工具搜索逻辑的灵感 | — |
---
## 相关项目
**Geny 生态系统**的一部分 - 参见上面的 [Geny 生态系统](#the-geny-ecosystem)：
- [**geny-executor**](https://github.com/CocoRoF/geny-executor) — Geny 后端运行的 21 阶段智能代理流水线（Apache-2.0）
- [**GAPT**](https://github.com/CocoRoF/geny-adapted-project-toolkit) — Geny 委托项目和部署的沙箱/DevOps 平台（子模块位于 `gapt/`）
- [**geny-avatar**](https://github.com/CocoRoF/geny-avatar) — 将虚拟人烘焙到 Geny 的虚拟人编辑器（子模块位于 `vendor/geny-avatar`）
---
## 贡献
Issues 和拉取请求欢迎 - 错误报告、文档、翻译、虚拟人、工具和技能都算数。最快的入门方式：
1. `./geny up`（60 秒本地堆栈）→ 重现或构建它。
2. 查看 [`docs/`](docs/) 中的架构/会话/环境指南。
3. 为任何大型问题打开问题；小修复可以直接提交 PR。
如果 Geny 对您有帮助，⭐ 帮助其他人找到它。
---
## 许可证
[Apache License 2.0](LICENSE). 版权所有 2026 CocoRoF - 参见 [NOTICE](NOTICE)。
---
## 版本控制 + 历史记录
| 日期 | 亮点 |
|---|---|
| 2026-07-06 | Opsidian 3D 知识图谱在 [@cocorof/graphier](https://github.com/CocoRoF/graphier) 上重建 - WebGL 实例化，无需加热的过滤器，缩略图 |
| 2026-07-06 | 屏幕观察视觉管道修复端到端（geny-executor 2.45 CLI 视觉线） |
| 2026-07-05 | geny-executor 2.44 - LibreOffice 免费文档预览 via edit2docs 原生渲染 |
| 2026-07-04 | geny-executor 2.43 - AN-Web 上的 Browser* / Doc* 内置模块 + edit2docs 引擎 |
| 2026-07-03 | 延迟工具搜索 - 工具模式加载按需而不是每次前端初始化 |
| 2026-05-22 | 文档刷新 - README EN/KO, docs/* 主题页面 |
| 2026-05-22 | 第 2 阶段：执行器错误代码 → 前端国际化（PR #830） |
| 2026-05-21 | geny-executor 2.1.0 - `ExecutorErrorCode` 分类 + 结构化事件有效载荷 |
| 2026-05-20 | geny-executor 2.0.6 - copilot_cli 移除 + 4 个兼容性补丁上游 |
| 2016-05-19 | 第一阶段 - claude_code_cli MCP 包装（每会话桥接 + 工具使用剥离 + 可观察性 Tap） |
| 2026-04-29 | host_selections（环境范围的钩子/技能/权限选择器） |
查看 [GitHub 提交历史记录](https://github.com/CocoRoF/Geny/commits/main) 以获取完整的日志。
> _主要用户模式为韩文 - 使用 ENG 按钮立即切换到英文。_
连接信息
猜你喜欢
暂无推荐服务器