Geond Agent Protocol

🧠 Geond Agent Protocol

🌐 语言 / Language：English · 한국어 · 日本語 · 简体中文 · Español · Français · Deutsch

为在同一个代码仓库上协同工作的 AI 智能体提供共享记忆与协调能力。

Geond 为 Copilot Chat、Codex、Claude Code、Antigravity、Manus、各类 CLI 智能体以及支持 MCP 的工具，提供一个持久化的空间,用于共享：发生了什么、为什么发生、改动了什么、哪些资源已被预留、如何完成验证，以及下一位智能体或审查者应当做什么。

Geond 默认采用**本地优先（local-first）**设计。你的编辑器、CLI、MCP 服务器、仪表盘和导入器都可以在本机针对本地 PostgreSQL 运行。当团队需要多机协作时，这些本地进程可以指向一个共享的、兼容 PostgreSQL 的配置（例如 Azure Database for PostgreSQL）。

⚠️ Alpha 阶段说明

Geond 目前处于 alpha 阶段。以仓库为中心的记忆、MCP、CLI、仪表盘读模型、资源预留、交接（handoff）、代码图索引、使用证据、基准测试以及共享 PostgreSQL 验证均已在今日实现。企业级 IAM、行级安全、专用 MCP 审计流、广泛的 SaaS 适配器，以及依赖扩展的自动预留，属于未来路线图方向。

💡 关于名称

Geond 的灵感来自古英语中意为「beyond（超越）」的词根，发音为「Jee-ond」。该项目通过将智能体连接到可检视的共享记忆，帮助它们超越无状态的提示词。

🚀 快速开始

前置条件：Python 3.11+、uv、带 Compose 的 Docker、Git 以及 ripgrep。各操作系统的具体说明请参阅 docs/developer_setup.md。

cp .env.example .env
uv sync
docker compose up -d postgres
docker compose --profile tools run --rm geond-migrate
uv run geond doctor --format text
uv run geond seed-sample
uv run geond mcp-smoke --format text --strict

启动 MCP 服务器：

uv run geond-mcp

预览或写入 MCP 客户端配置：

uv run geond install --format text
uv run geond install --write

启动只读仪表盘：

uv run geond dashboard serve

打开打印出的 localhost URL。更多 MCP 客户端示例请参阅 docs/mcp_client_config.md。

🔌 MCP 服务器与 Glama 发布

直接运行 stdio MCP 服务器：

uv run geond-mcp

从 Docker 镜像运行：

docker build -t geond-agent-protocol:local .
docker run --rm -i \
  -e GEOND_DATABASE_URL=postgresql://geond:geond_dev_password@host.docker.internal:55432/geond \
  geond-agent-protocol:local

GEOND_DATABASE_URL 用于将 Geond 指向 PostgreSQL。本地开发通常使用快速开始中的 Compose 数据库。团队模式可以使用 GEOND_DATABASE_PROFILE=azure 加上 AZURE_GEOND_DATABASE_URL，在各机器之间共享记忆，同时让每个 MCP 进程保持本地运行。

为进行注册表验证，Glama 应部署本仓库的 Dockerfile、创建 Glama release，并首先调用 get_geond_server_info。该工具不需要数据库连接，因此对基于浏览器的冒烟测试是安全的。

三个具有代表性的 MCP 工作流：

1. 启动协作工作：review_workspace_context → reserve_files → 编辑 → record_changeset
2. 解释先前上下文：search_dev_memory → explain_change → get_changeset_detail
3. 留下交接信息：record_agent_action → record_handoff_summary → list_handoff_summaries

✨ Geond 能实现什么

🎬 演示 GIF

这些 GIF 由经过脱敏的场景文本生成，并非私人转录内容。可使用 uv run python scripts/render_readme_gifs.py 重新生成它们。

关于经浏览器验证的仪表盘截图和更长的终端演示说明，请参阅 docs/public_demo_script.md。

📚 学习路径

从 learn/README.md 开始，其中包含与 README 场景相对应的引导式 notebook：

⚙️ 工作原理

flowchart LR
    A[智能体转录与操作] --> B[适配器与脱敏]
    B --> P[(PostgreSQL + pgvector)]
    C[MCP 客户端与 CLI] --> M[Geond MCP / CLI]
    M --> P
    P --> S[搜索与证据引用]
    P --> G[代码图]
    P --> R[预留与交接]
    P --> D[只读仪表盘]
    G --> R
    R --> D
    S --> D

1. 记忆：导入器对来自各智能体工具的会话、事件、消息、使用记录和任务历史进行规范化，然后在持久化之前对常见机密进行脱敏。
2. 代码图：Python、TypeScript 和 JavaScript 索引器连接文件、符号、导入、调用、引用和变更集。
3. 预留：智能体可以按 TTL 声明文件或符号，并带有策略检查、续期、释放以及可审计的预留事件。
4. 交接：智能体留下结构化的下一步行动包，包含已测试的命令、阻塞项、剩余风险和证据引用。
5. 仪表盘：人类以及 PM/编排智能体可以读取紧凑的概览、活动、时间线、代码风险、使用情况、血缘、预留和交接读模型。
6. 共享 PostgreSQL：本地优先的配置使用 Docker PostgreSQL；团队配置可以将本地进程指向 Azure 或其他兼容 PostgreSQL 的后端。

🔄 常见工作流

更完整的演示路径请参阅 docs/demo.md。

🗄️ 团队共享数据库

使用 GEOND_DATABASE_URL 作为默认本地数据库。若要保持本地进程运行、同时又想在多台机器之间共享记忆，可添加第二个配置：

GEOND_DATABASE_PROFILE=azure
AZURE_GEOND_DATABASE_URL=postgresql://...

仪表盘会将当前活动数据源归类为本地 PostgreSQL、Azure PostgreSQL 或远程 PostgreSQL，且不会显示用户信息、密码或令牌。经验证的团队流程记录在 docs/azure_validation/team_collab_validation.md。

📖 借鉴的 README 模式

Geond 的 README 借鉴了一些公开的入门引导模式，并根据本项目进行了调整，而非照搬其产品范围：

• OpenHuman：清晰地说明透明的、本地优先的记忆与紧凑上下文。
• CLI-Anything：通过简短命令和 GIF，让首屏更具视觉性和行动导向。
• Microsoft AI Agents for Beginners：以场景表格和可重复的学习路径来呈现智能体概念。

📚 文档

• docs/architecture.md — 说明系统分层与数据模型。
• docs/agent_activity_dashboard.md — 描述仪表盘读模型以及 PM/编排视图。
• docs/agent_operating_loop.md — 定义智能体的「读取、预留、记录、交接」循环。
• docs/agent_testbeds.md — 跟踪 Copilot Chat、Codex、Claude Code 和 Antigravity 测试床。
• docs/manus_integration.md — 记录 Manus API v2 导入、上下文包、任务契约与局限性。
• docs/mcp_client_config.md — 展示 VS Code、Claude Desktop、Continue、Antigravity 及其他 MCP 客户端的设置方式。
• docs/ai_usage_observability.md — 涵盖 token、成本、定价快照以及「使用量 vs 证据」的设计。
• docs/benchmarking.md — 说明检索、证据和智能体运行的基准测试命令。
• docs/open_source_readiness.md — 跟踪发布风险、隐私、依赖和治理问题。
• learn/README.md — 提供基于 notebook 的入门路径。

🤝 贡献指南

项目处于 alpha 阶段，欢迎贡献。不错的切入点包括：导入器、文档、测试、仪表盘读模型改进、MCP 契约测试、安装器易用性，以及针对非开发类工作产物的聚焦适配器。

在提交 PR 之前，请阅读 CONTRIBUTING.md。它涵盖环境搭建、隐私规则、测试命令、脱敏预期，以及必须排除在 git 之外的文件。安全报告请见 SECURITY.md。

🔒 安全与隐私

Geond 专为本地优先使用而设计。导入器会在持久化之前对常见机密进行脱敏；外部嵌入（embeddings）为可选开启；仪表盘也不会暴露包含凭据的连接字符串。即便如此，智能体转录内容仍可能包含敏感信息。在分享 .env、转录内容、截图、基准测试日志和仪表盘截图之前，请务必先审查它们。

请勿提交私人转录内容、本地证据导出、仅本地草稿，或 repo、tmp、result、results 目录及生成的视频。请参阅 SECURITY.md 和 docs/open_source_readiness.md。

📄 许可证

Apache-2.0。详见 LICENSE。