内容
# 吉尼智能代理
吉尼智能代理是一款个人代理，它可以记住、改进和运行，而无需强制您阅读日志行。
吉尼不仅仅是一个聊天框、命令行界面（CLI）、消息机器人或工具集合。聊天是一种交互界面。运行时是对话、运行、任务、审批、记忆、技能、工作、工具、跟踪、审计事件和运行时健康状况的记录系统。
## 文档
- [白皮书](docs/whitepaper.md)：本项目所填补的空白以及衡量的标准
- [架构概述](docs/architecture-overview.md)：网关/客户端映射
- [网关和控制平面](docs/gateway.md)：运行时流程、BFF、身份验证、实例、端口、磁盘布局
- [对话和运行](docs/conversation-runs.md)：聊天、运行、任务、计划步骤、跟踪和审计移交
- [记忆](docs/memory.md)：保留、回忆、嵌入、重新排序、审查和存储
- [从技能中学习技能](docs/skill-learning.md)：吉尼如何从任务结果中改进自己的技能（两层奖励、归因、每日审查、人工门户）
- [运行时能力](docs/runtime-capabilities.md)：当前CLI/API能力映射和验证命令
- [模型提供商](docs/providers/README.md)：每个提供商的设置指南（凭证、先决条件、CLI/网页配置）适用于OpenAI、Anthropic、Bedrock、Azure、OpenRouter、DeepSeek、Codex和Local
- [操作](docs/operations.md)：安装、启动、停止、烟雾测试、诊断和清理
- [远程访问](docs/remote-access.md)：隧道模式和确认，以及每个隧道提供商的独立指南 - [吉尼中继](docs/remote-access/gini-relay.md)、[Tailscale](docs/remote-access/tailscale.md)、[ngrok](docs/remote-access/ngrok.md)、[Cloudflare](docs/remote-access/cloudflare.md) - 应用程序内联打开的相同页面
- [发布](docs/releases.md)：版本控制、CHANGELOG约定和发布过程
- [从openclaw迁移](docs/migration-from-openclaw.md)：将现有的openclaw安装导入gini
- [实施说明](docs/implementation-notes.md)：源代码布局和模块边界规则
- [路线图](ROADMAP.md)：已发布的界面和计划内容
## 架构决策
- [架构决策记录](docs/adr/README.md)：所有ADR的索引以及如何添加新的ADR
## 架构一句话
吉尼的**运行时是网关**：每个实例都有一个Bun进程，拥有状态并执行工作。Next.js网页应用、CLI、Expo移动应用、MCP界面和消息桥接器都是同一个身份验证的 `/api/*` 接口的客户端。参见[架构概述](docs/architecture-overview.md)了解设计。
```text
网关（Bun运行时，每个实例一个）
状态、代理循环、工具、内存、作业
^
--------------------+--------------------
| | |
Next.js BFF CLI/脚本 其他客户端
浏览器UI 承载令牌 移动设备、MCP、消息
无浏览器令牌
```
## 盒子里有什么
- 身份验证的本地网关和Next.js + Tailwind + shadcn/ui控制平面
- 持久聊天、运行、任务、审批、跟踪、审计事件、作业、记忆和技能
- 审批门控文件、终端和代码工具
- 提供商支持：Codex OAuth；OpenAI / Azure OpenAI / DeepSeek / OpenRouter API密钥；第一方Anthropic Claude API；Amazon Bedrock（模型无关的Converse，AWS SigV4 — Claude，Nova，Llama，Mistral，DeepSeek）；以及任何OpenAI兼容的本地服务器
- 默认情况下本地嵌入、重新排序和语音消息语音转文本
- 具有隔离状态、端口和日志的并行实例
参见[白皮书](docs/whitepaper.md)和[架构概述](docs/architecture-overview.md)了解设计。
## 快速入门
```bash
curl -fsSL https://raw.githubusercontent.com/Lilac-Labs/gini-agent/main/scripts/install.sh | bash
```
在macOS上，安装程序启用自动启动（每个用户的LaunchAgents用于运行时和网页应用），等待网页应用启动，并在您的浏览器中打开 `/setup` 页面。该表单提供完整的提供商目录 — OpenAI、Codex、Anthropic、Amazon Bedrock、Azure OpenAI、OpenRouter、DeepSeek和Local — 并提示您选择所需的提供商（API密钥、AWS访问密钥对用于Bedrock、Azure的资源端点或现有的 `codex login` 身份验证）。保存它，您将进入正在运行的应用程序。运行时在重新启动和崩溃后保持活动，直到您明确运行 `gini stop` 或 `gini autostart disable`。
如果浏览器没有自动打开（或您想手动导航），请运行 `gini status` 以打印实际的网页URL。已安装的 `default` 实例始终位于 `:7777`；其他实例获取哈希派生的端口，因此请检查 `gini status` 而不是猜测。安装程序还会在打开浏览器之前打印URL。
macOS 26（Tahoe）上的注意事项：在SIGKILL之后，launchd有时会拒绝自动重启（pended nondemand spawn = inefficient）。当这种情况发生时，运行 `gini autostart kick` 以强制重启；RunAtLoad仍然会在登录时触发。
如果您选择退出自动启动（`--no-autostart`）或您在Linux上（自动启动目前仅限于macOS），请运行 `gini setup` 然后 `gini start` 以手动启动运行时。
安装后，URL是稳定的：
- 网页：`http://127.0.0.1:7777`
- 运行时：`http://127.0.0.1:7778`
### 更新
```bash
gini update
```
更新安装程序管理的运行时位于 `~/.gini/runtime` 并重启它。实例状态位于 `~/.gini/instances/` 下的实例状态和 `~/.gini/models/` 下的模型缓存将被保留。
### 从源码编译
```bash
bun install
bun run gini install
bun run gini start
```
从仓库克隆中，实例源自目录basename，因此每个工作树自动获得隔离状态和端口。参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发设置，包括 `./scripts/install.sh --local` 用于测试安装流程与本地checkout。
## CLI
CLI涵盖聊天、运行、任务、审批、记忆、作业、连接器、提供商、快照、导入等。使用以下命令发现命令：
```bash
gini --help
```
有用的起点：
```bash
gini status # 运行时健康和URL
gini chat new # 启动聊天会话
gini approvals # 审查待处理工具审批
```
（从仓库克隆中，以 `bun run` 为前缀。）
## 提供商
运行 `gini setup` 以获取交互式选择器，或直接配置：
```bash
gini provider set codex gpt-5.5 # Codex OAuth（读取 ~/.codex/auth.json）
gini provider set openai gpt-5.4-mini # 使用 $OPENAI_API_KEY
gini provider set openrouter <model> # 使用 $OPENROUTER_API_KEY
gini provider set local <model> --base-url http://127.0.0.1:8000/v1
gini provider set anthropic claude-opus-4-8 # 第一方Claude API，使用 $ANTHROPIC_API_KEY
# Amazon Bedrock：模型无关的Converse，带有AWS密钥的SigV4签名，您通过网页表单或 `gini setup` 输入
gini provider set bedrock us.amazon.nova-pro-v1:0 --aws-region us-east-1 # 设置模型 + 区域；单独输入密钥
# Azure OpenAI：一个一级提供商，针对您资源上的部署
gini provider set azure gpt-4o \
--base-url https://<resource>.openai.azure.com \
--deployment <deployment> --api-version 2024-10-21 --auth-scheme api-key # 使用 $AZURE_OPENAI_API_KEY
```
有关每个提供商的逐步设置 - 获取凭证、安装任何先决条件工具（Ollama，…）以及在CLI或网页中配置它 - 请参阅每个提供商的指南： [OpenAI](docs/providers/openai.md)， [Anthropic](docs/providers/anthropic.md)， [Amazon Bedrock](docs/providers/bedrock.md)， [Azure OpenAI](docs/providers/azure.md)， [OpenRouter](docs/providers/openrouter.md)， [DeepSeek](docs/providers/deepseek.md)， [Codex](docs/providers/codex.md)和 [Local](docs/providers/local.md)。提供商索引 [providers index](docs/providers/README.md) 以一览其身份验证模型。
`local` 提供商与任何OpenAI兼容的服务器（oMLX，vLLM，LM Studio，llama.cpp）一起工作。 `azure` 提供商针对Azure OpenAI资源：设置 `--base-url` 为 `https://<resource>.openai.azure.com` 并选择部署； `--api-version` 默认设置为GA值， `--auth-scheme` 默认设置为 `api-key` （资源密钥），对于Entra令牌， `bearer` 可用。 API密钥从环境变量中读取，Codex OAuth从 `~/.codex/auth.json` （或 `CODEX_AUTH_JSON` ）读取 - 不会写入Gini配置。运行 `gini --help` 获取完整的标志集，或参阅 [provider-extra-body.md](docs/adr/provider-extra-body.md) 获取 `--extra-body` 合同和 [Azure OpenAI As A First-Class Provider](docs/adr/azure-provider.md) 获取Azure路由合同。当聊天中出现凭证失败时，请参阅 [Codex重新身份验证](docs/providers/codex.md#re-authentication)和 [提供商重新身份验证指南](docs/adr/provider-reauth-guidance.md)。
`gini setup` 的交互式选择器涵盖了每个提供商 - OpenAI、Codex、Anthropic、Amazon Bedrock、Azure OpenAI、OpenRouter、DeepSeek和Local - 并提示您提供每个提供商所需的内容（API密钥、用于Bedrock的AWS访问密钥对、Azure的资源端点和部署、用于Local的基URL）。 `gini provider set …` （上面）和网页 **设置 → 添加提供商** 表单仍然可用于脚本化或非交互式配置。
## 并行实例
每个实例都有隔离的状态、端口和日志：
```bash
gini --instance sandbox run
gini smoke # /tmp下的临时实例
```
多个代理可以并发运行烟雾测试而不会发生冲突。
## 消息通道
吉尼可以桥接到诸如Telegram和Discord之类的消息通道。这些桥接是为了锻炼网关的消息合同而添加的，**不**正在积极开发中。我们强烈建议通过原生网页应用和iOS应用与吉尼互动。这些是主要且积极开发的界面。参见 [telegram-bridge.md](docs/adr/telegram-bridge.md) 和 [discord-bridge.md](docs/adr/discord-bridge.md) 获取桥接合同。
## 从openclaw迁移
已经运行 [openclaw](https://github.com/openclaw/openclaw)？将您的代理、聊天历史、记忆、技能、工作区文件和消息桥接导入到gini实例中。导入分为两步 - `plan` 打印一个红色的摘要， `apply` 将状态写入：
```bash
gini import plan openclaw # 演练：总结将要导入的内容
gini import apply openclaw # 将openclaw状态导入gini
```
`apply` 在进程中修改状态，因此请先停止目标实例（`gini stop --instance <name>`），应用，然后再次启动。每个应用的导入首先将您的整个openclaw状态存档到 `<instance>/imports/openclaw-<timestamp>.zip`，因此不会丢失任何内容。参见 [从openclaw迁移](docs/migration-from-openclaw.md) 获取字段到字段的映射、幂等规则和验证步骤。
## 本地状态
```text
~/.gini/instances/<instance>/ # 配置、state.json、memory.db、跟踪、快照、工作区、日志
~/.gini/models/ # 共享嵌入/重新排序/语音转文本模型缓存
```
使用 `gini uninstall` 删除实例或整个安装。参见 [操作](docs/operations.md) 获取诊断和清理。
## 路线图
参见 [ROADMAP.md](ROADMAP.md) 获取已发布的界面和计划内容。
## 贡献
欢迎贡献。首先使用 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发设置、验证命令和PR约定。对于架构约定和模块边界，参见 [AGENTS.md](AGENTS.md)。通过 [SECURITY.md](SECURITY.md) 私人报告安全问题。
## 星史
<a href="https://star-history.com/#Lilac-Labs/gini-agent&Date">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Lilac-Labs/gini-agent&type=Date&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Lilac-Labs/gini-agent&type=Date" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Lilac-Labs/gini-agent&type=Date" />
</picture>
</a>
## 许可证
[MIT](LICENSE)
连接信息
猜你喜欢
暂无推荐服务器