内容
# Geistr 核心
Geistr 核心是一个可重复使用的桌面优先 AI 应用基础。你可以将其作为一个完善的本地 AI 工作空间来运行，也可以将其作为构建自己的代理应用、研究工作空间、导师、编码助手、创意工具或内部自动化产品的基石。
核心思想很简单：现代桌面代理应用的难点应该只做一次——聊天、会话、提供者、工具、权限、内存、技能、MCP、后台工作流、设置和良好的 UI 渲染——这样你的下一个应用就可以专注于其领域，而不必重建基础。
## 为什么我创建了这个
我一直有针对特定用例的 AI 应用的想法，每次我开始一个新的项目时，我都会发现自己从头开始重建相同的核心部分。
所以我问自己：**为什么我没有一个核心应用已经具备我需要的功能，这样我就可以在其基础上进行构建？**
这就是为什么我为自己的使用创建了 Geistr Core：一个基础应用，我可以在需要构建专注的 AI 产品时重复使用。我将其开源，以便任何有好想法的人都可以构建自己的应用，而不必花费数周时间重新创建基础。
使用它可以节省时间，更接近你的真正想法，并专注于你想要创建的特定体验。
## 你可以获得的
- **桌面应用壳** — Electron + React 应用，带有聊天、侧边栏导航、设置、主题、附件和打包构建。
- **Pi SDK 代理运行时** — Geistr 封装了 [Pi SDK / `@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) 和 [`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai)，而不是重建代理/会话/模型基础设施。
- **许多提供者** — 提供者/模型选择、思考级控制、API 密钥身份验证和订阅/OAuth 样式提供者支持（如果可用）。
- **持久的本地会话** — SQLite 支持的聊天会话、事件历史、附件和运行时上下文组装。
- **内存** — 内存索引、检索到提示、读写内存工具和内存星系图 UI。
- **提供者独立的网络访问** — 内置 `web_search` 和 `web_fetch` 工具，通过 Geistr 名称公开，不绑定到所选模型提供者。
- **技能** — 安装的技能目录、紧凑的提示列表和仅读 `skill_load` 工具，用于按需加载完整技能指令。
- **MCP 服务器** — STDIO 和 Streamable HTTP MCP 支持，带有受控工具暴露。
- **权限模式** — 四个应用级访问模式：只读、请求批准、默认和完全访问。
- **丰富的聊天渲染** — 流式传输助手响应、思考/工具活动可见性、批准卡、附件、Markdown 渲染和循环进度。
- **后台循环** — 可重复使用的工作流运行时，用于压缩、后台任务、验证器、工件、重试、进度和代理触发的作业。
- **打包流程** — 用于桌面分发实验的本地 `electron-builder` 打包。
## 核心架构
Geistr Core 将可重复使用的代理应用基础设施与你在此基础上构建的应用分开。
```txt
apps/desktop/ Electron + React 桌面应用
packages/core/ 可重复使用的 Geistr Core 运行时和应用系统
docs/ 架构、功能和扩展文档
.agents/skills/ 代理辅助开发的项目工作流技能
scripts/ 仓库维护脚本
```
桌面应用拥有 UI、IPC、窗口、本地设置屏幕和视觉呈现。`packages/core` 拥有可重复使用的系统：Pi SDK 集成、提供者/模型选择、提示组装、工具、权限、内存、技能、MCP、循环、工件和持久性缝隙。
这给你一个实际的分割：
- 通过更改 UI、提示、技能、循环和领域工具来构建新产品；
- 保持核心运行时稳定；
- 避免在每个屏幕上重复 Pi SDK 连接；
- 让代理读取本地文档并了解如何安全地扩展应用。
从架构文档开始：
- [`docs/architecture/architecture.md`](docs/architecture/architecture.md)
- [`docs/architecture/desktop-shell.md`](docs/architecture/desktop-shell.md)
- [`docs/core/core-agent-runtime.md`](docs/core/core-agent-runtime.md)
- [`docs/core/session-persistence.md`](docs/core/session-persistence.md)
## 技术栈
- **运行时/包管理器：** [Bun](https://bun.sh/)
- **桌面：** [Electron](https://www.electronjs.org/)
- **渲染器：** [React](https://react.dev/) + TypeScript + Vite
- **代理运行时：** [Pi SDK / `@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
- **模型/提供者层：** [`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai)
- **MCP：** [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
- **本地持久性：** SQLite 支持的会话存储
- **打包：** [electron-builder](https://www.electron.build/)
- **测试：** Vitest + Testing Library
## Pi SDK 关系
Geistr Core 使用 Pi SDK 作为会话、模型、身份验证、工具、上下文和代理行为的基础。应用不试图取代 Pi。相反，它在稳定的 Geistr 接口后面封装 Pi，这样桌面应用就可以专注于产品行为和 UI。
有用的文档：
- [`docs/roles/pi-sdk.md`](docs/roles/pi-sdk.md)
- [`docs/core/core-agent-runtime.md`](docs/core/core-agent-runtime.md)
- [`docs/core/provider-model-selection.md`](docs/core/provider-model-selection.md)
- [`docs/core/settings-provider-auth.md`](docs/core/settings-provider-auth.md)
## 内存
Geistr 包括一个本地内存系统，用于索引有用的会话内容、检索相关记忆到未来的提示，并允许代理通过受控工具读写记忆。
它还包括一个只读的 **内存星系** UI，用于以图形方式探索记忆。
文档：
- [`docs/loops/memory-tools.md`](docs/loops/memory-tools.md)
- [`docs/core/memory-galaxy.md`](docs/core/memory-galaxy.md)
- [`docs/core/session-persistence.md`](docs/core/session-persistence.md)
## 网络搜索和获取
Geistr 包括提供者独立的网络工具：
- `web_search` — 搜索公共网络
- `web_fetch` — 获取和读取 URL
这些工具作为 Geistr 工具公开，不依赖于用户选择的模型提供者。当前适配器在内部使用 Exa MCP，但代理看到稳定的 Geistr 工具名称。
文档：
- [`docs/core/web-tools.md`](docs/core/web-tools.md)
- [`docs/skills-mcp/mcp-servers.md`](docs/skills-mcp/mcp-servers.md)
## 技能和 MCP
技能为代理提供操作指令，而无需将每个指令注入每个提示。运行时以紧凑的方式列出活动技能，代理可以在需要时调用 `skill_load` 加载完整指令。
MCP 支持允许应用通过 STDIO 或 Streamable HTTP 服务器公开外部工具，同时仍然通过 Geistr 的权限和运行时模型路由它们。
文档：
- [`docs/skills-mcp/skills.md`](docs/skills-mcp/skills.md)
- [`docs/skills-mcp/mcp-servers.md`](docs/skills-mcp/mcp-servers.md)
- [`docs/roles/skills.md`](docs/roles/skills.md)
- [`docs/roles/tools.md`](docs/roles/tools.md)
## 权限模式
Geistr 有四种应用级权限模式：
| 模式 | 行为 |
|---|---|
| 只读 | 安全读取自动运行；变异工具不可用或被阻止。 |
| 请求批准 | 安全读取自动运行；变异请求通过 UI 批准。 |
| 默认 | 安全读取和低风险内部更改自动运行；危险操作请求。 |
| 完全访问 | 大多数操作无提示运行；灾难性阻止操作仍然被阻止。 |
文档：
- [`docs/core/tool-permissions.md`](docs/core/tool-permissions.md)
## 后台循环
Geistr Core 包括其自己的循环运行时，用于监督后台工作流。
循环是一个有界的工作流，由明确的步骤组成：模型节点、确定性代码节点、门、验证器、工件、重试、批准、副作用、终结器和进度事件。循环可以在后台自动运行，也可以暴露给代理，通过循环目录，代理可以触发它们。
第一个真正的循环是会话压缩：它在长时间会话后运行，总结上下文，存储工件，并唤醒同一个会话，带有压缩的待处理结果。
相同的模式可以驱动更多。例如，您可以构建一个 **深度搜索循环**，具有明确的步骤：
1. 阐明研究问题；
2. 搜索网络；
3. 获取有前途的来源；
4. 提取声明和引用；
5. 验证覆盖范围；
6. 编写结构化报告工件；
7. 通知主聊天完成。
主代理可以从循环目录触发 `deep_search`，在运行过程中继续聊天，并在后台 UI 中显示进度。
文档：
- [`docs/loops/loop-runtime.md`](docs/loops/loop-runtime.md)
- [`docs/loops/loop-catalog.md`](docs/loops/loop-catalog.md)
- [`docs/loops/background-loop-runner.md`](docs/loops/background-loop-runner.md)
- [`docs/loops/artifact-store.md`](docs/loops/artifact-store.md)
- [`docs/loops/session-compaction-loop.md`](docs/loops/session-compaction-loop.md)
## 下载和安装
对于正常使用，请从 [GitHub Releases](https://github.com/Asm3r96/geistr-core/releases/latest) 下载最新的安装程序：
- **Windows：** 下载 `Geistr Core Setup 1.0.0.exe`
- **macOS Apple Silicon：** 下载 `Geistr Core-1.0.0-arm64.dmg`
- **Linux：** 下载 `.AppImage` 文件
> 首批公开构建版本未经签名。Windows SmartScreen 或 macOS Gatekeeper 可能会显示警告，直到添加签名和公证为止。
如果您想修改 Geistr Core 或在其基础上构建应用，请使用下面的源工作流。
## 从源代码运行本地
安装依赖项：
```bash
bun install
```
运行验证：
```bash
bun run typecheck
bun run test
```
在开发中运行桌面应用：
```bash
cd apps/desktop
bun run dev
```
构建桌面应用：
```bash
cd apps/desktop
bun run build
```
创建本地打包的桌面目录：
```bash
bun run package:desktop:dir
```
打包文档：
- [`docs/release/desktop-packaging.md`](docs/release/desktop-packaging.md)
## 发布流程
此仓库包括用于 CI 和基于标签的发布的 GitHub Actions。
- CI 在推送和拉取请求到 `main` 时运行。
- 发布构建在推送类似 `v1.0.0` 的标签时运行。
- 发布工件上传到 GitHub Releases。
要发布版本，请在推送仓库后：
```bash
git tag v1.0.0
git push origin v1.0.0
```
文档/文件：
- [`CHANGELOG.md`](CHANGELOG.md)
- [`RELEASE_NOTES.md`](RELEASE_NOTES.md)
- [`.github/workflows/ci.yml`](.github/workflows/ci.yml)
- [`.github/workflows/release.yml`](.github/workflows/release.yml)
## 在其基础上构建
良好的扩展点：
- 添加特定领域的提示和配置文件默认值；
- 在 Geistr 权限层后面添加工具；
- 添加可重复使用的代理工作流的技能；
- 为外部系统添加 MCP 服务器；
- 为长期运行的后台作业添加循环；
- 在桌面壳上添加应用特定的屏幕；
- 替换或扩展提供者/身份验证配置；
- 自定义内存索引和检索行为。
扩展前推荐的文档：
- [`docs/README.md`](docs/README.md)
- [`docs/roles/core.md`](docs/roles/core.md)
- [`docs/roles/apps.md`](docs/roles/apps.md)
- [`docs/roles/development-workflow.md`](docs/roles/development-workflow.md)
- [`docs/roles/code-quality.md`](docs/roles/code-quality.md)
## 仓库状态
此仓库旨在成为公共的可重复使用的核心基础。它不应包含特定于产品的行为。而是在其基础上构建特定于产品的应用，而不是将它们混合到核心层。
## 许可证
MIT
