gini-agent

# 吉尼代理 吉尼代理是一款个人代理，记住、改进并运行，而无需您阅读日志行。 吉尼不仅仅是一个聊天框、命令行界面、消息机器人或一堆工具。聊天是一种交互界面。运行时是对话、运行、任务、审批、记忆、技能、作业、工具、跟踪、审计事件和运行时健康状况的记录系统。 ## 文档 - [白皮书](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)：当前命令行界面/应用编程接口能力映射和验证命令 - [模型提供商](docs/providers/README.md)：每个提供商的设置指南（凭证、先决条件、命令行界面/网页配置）适用于 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)：版本控制、变更日志约定和发布过程 - [从 openclaw 迁移](docs/migration-from-openclaw.md)：将现有的 openclaw 安装导入 gini - [实施说明](docs/implementation-notes.md)：源代码布局和模块边界规则 - [路线图](ROADMAP.md)：已交付的界面和计划内容，附有设计意图 ## 架构决策 - [架构决策记录](docs/adr/README.md)：所有 ADR 的索引以及如何添加新的 ADR ## 一句话架构 吉尼的 **运行时是网关**：每个实例的单个 Bun 进程拥有状态并执行工作。Next.js 网页应用、命令行界面、Expo 移动应用、MCP 界面和消息桥接器都是同一个身份验证的 `/api/*` 接口的客户端。有关设计，请参见 [架构概述](docs/architecture-overview.md)。 ```text 网关（Bun 运行时，每个实例一个） 状态、代理循环、工具、内存、作业 ^ --------------------+-------------------- | | | Next.js BFF 命令行界面/脚本 其他客户端 浏览器界面 持有者令牌 移动、MCP、消息 无浏览器令牌 ``` ## 盒子里有什么 - 身份验证的本地网关和 Next.js + Tailwind + shadcn/ui 控制平面 - 持久聊天、运行、任务、审批、跟踪、审计事件、作业、记忆和技能 - 审批门控文件、终端和代码工具 - 提供商支持：Codex OAuth；OpenAI / Azure OpenAI / DeepSeek / OpenRouter 应用编程接口密钥；第一方 Anthropic Claude 应用编程接口；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 — 并提示选择所需的凭证（应用编程接口密钥、Bedrock 的 AWS 访问密钥对、Azure 的资源端点或现有的 `codex login` 身份验证）。保存它，您将进入正在运行的应用程序。运行时在重新启动和崩溃后保持活动，直到您明确运行 `gini stop` 或 `gini autostart disable`。 如果浏览器没有自动打开（或您想手动导航），请运行 `gini status` 以打印实际的网页网址。已安装的 `default` 实例始终位于 `:7777`；其他实例获取基于哈希的端口，因此请检查 `gini status` 而不是猜测。安装程序还会在打开浏览器之前打印网址。 macOS 26（Tahoe）上的注意事项：在 SIGKILL 后，launchd 有时会拒绝自动重启（`pended nondemand spawn = inefficient`）。当这种情况发生时，运行 `gini autostart kick` 以强制重启；RunAtLoad 仍会在登录时触发。 如果您选择退出自动启动（`--no-autostart`）或您在 Linux 上（自动启动目前仅限于 macOS），请运行 `gini setup` 然后 `gini start` 以手动启动运行时。 安装后，网址是稳定的： - 网页：`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，因此每个工作树自动获得隔离状态和端口。有关开发设置，包括 `./scripts/install.sh --local` 以测试针对本地检查的安装流程，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 命令行界面 命令行界面涵盖聊天、运行、任务、审批、内存、作业、连接器、提供商、快照、导入等。使用以下命令发现命令： ```bash gini --help ``` 有用的起点： ```bash gini status # 运行时健康和网址 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 应用编程接口，使用 $ANTHROPIC_API_KEY # Amazon Bedrock：模型无关的 Converse，带有您通过网页表单或 `gini setup` 输入的 AWS 密钥的 SigV4 签名 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，…）并在命令行界面或网页中配置 — 请参阅每个提供商的指南：[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`（资源密钥），而 `bearer` 可用于 Entra 令牌。应用编程接口密钥从环境变量中读取，而 Codex OAuth 从 `~/.codex/auth.json`（或 `CODEX_AUTH_JSON`）读取 — 任何内容都不会写入吉尼配置。运行 `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 re-authentication](docs/providers/codex.md#re-authentication) 和 [Provider Re-Authentication Guidance](docs/adr/provider-reauth-guidance.md)。 `gini setup` 的交互式选择器涵盖每个提供商 — OpenAI、Codex、Anthropic、Amazon Bedrock、Azure OpenAI、OpenRouter、DeepSeek 和 Local — 提示每个提供商所需的凭证（应用编程接口密钥、Bedrock 的 AWS 访问密钥 + 秘密、Azure 的资源端点和部署、Local 的基本网址）。`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)？将您的代理、聊天历史、内存、技能、工作区文件和消息桥接导入吉尼实例。导入分为两步 — `plan` 打印红色的摘要，而 `apply` 则写入状态： ```bash gini import plan openclaw # 演练：总结将导入的内容 gini import apply openclaw # 将 openclaw 状态导入吉尼 ``` `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) 进行开发设置、验证命令和拉取请求约定。有关架构约定和模块边界，请参阅 [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)