内容
<!-- SPDX-FileCopyrightText: 2026 Ai-chan-0411 <aoikabu12@gmail.com> -->
<!-- SPDX-FileCopyrightText: 2026 Apoorv Garg <apoorvgarg.21@gmail.com> -->
<!-- SPDX-FileCopyrightText: 2026 Aryan Iyappan <aryaniyappan2006@gmail.com> -->
<!-- SPDX-FileCopyrightText: 2026 Subramania Raja <dhanpraja231@gmail.com> -->
<!-- SPDX-FileCopyrightText: 2026 Hari Srinivasan <harisrini21@gmail.com> -->
<!-- SPDX-FileCopyrightText: 2026 Hemalatha Madeswaran <hemalathamadeswaran@gmail.com> -->
<!-- SPDX-FileCopyrightText: 2026 Kaushik Kumar <kaushikrjpm10@gmail.com> -->
<!-- SPDX-FileCopyrightText: 2026 Lokesh Selvam <lokeshselvam7025@gmail.com> -->
<!-- SPDX-FileCopyrightText: 2026 Naraen Rammoorthi <naraen13@gmail.com> -->
<!-- SPDX-FileCopyrightText: 2026 Shaan Narendran <shaannaren06@gmail.com> -->
<!-- SPDX-FileCopyrightText: 2026 Shreem Seth <shreemseth26@gmail.com> -->
<!-- SPDX-FileCopyrightText: 2026 DoomsCoder <vedantkakade05@gmail.com> -->
<!-- SPDX-FileCopyrightText: 2026 Vishnu Muthiah <vishnu.muthiah04@gmail.com> -->
<!-- SPDX-License-Identifier: AGPL-3.0-only -->
<pre>
██████╗ ██████╗ ███████╗███████╗██████╗ ██╗ ██╗ █████╗ ██╗
██╔═══██╗██╔══██╗██╔════╝██╔════╝██╔══██╗██║ ██║██╔══██╗██║
██║ ██║██████╔╝███████╗█████╗ ██████╔╝██║ ██║███████║██║
██║ ██║██╔══██╗╚════██║██╔══╝ ██╔══██╗╚██╗ ██╔╝██╔══██║██║
╚██████╔╝██████╔╝███████║███████╗██║ ██║ ╚████╔╝ ██║ ██║███████╗
╚═════╝ ╚═════╝ ╚══════╝╚══════╝╚═╝ ╚═╝ ╚═══╝ ╚═╝ ╚═╝╚══════╝
</pre>
**适用于可移植 AI 编码代理的注册和洞察平台。定义一次上下文，在多个工具中安装它，并了解哪些有效。**
<p>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat-square" alt="许可证"></a>
<img src="https://img.shields.io/badge/python-3.11+-3776ab?style=flat-square&logo=python&logoColor=white" alt="Python">
<a href="https://pypi.org/project/observal-cli/"><img src="https://img.shields.io/pypi/v/observal-cli?style=flat-square&logo=pypi&logoColor=white&label=pypi" alt="PyPI 版本"></a>
<a href="https://codecov.io/gh/Observal/Observal"><img src="https://img.shields.io/codecov/c/github/Observal/Observal?style=flat-square&logo=codecov" alt="覆盖率"></a>
<a href="https://github.com/Observal/Observal/graphs/contributors"><img src="https://img.shields.io/github/contributors/Observal/Observal?style=flat-square&logo=github" alt="贡献者"></a>
<a href="https://discord.observal.io"><img src="https://img.shields.io/badge/discord-chat-5865f2?style=flat-square&logo=discord&logoColor=white" alt="Discord"></a>
<a href="https://github.com/orgs/Observal/packages?repo_name=Observal"><img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/Haz3-jolt/b28aba6d0efebb0b430d43c8068feb91/raw/ghcr-pulls.json&style=flat-square" alt="GHCR 拉取次数"></a>
</p>
> 如果您觉得 Observal 有用，请考虑给它一个星标。这有助于其他人发现该项目，并继续推动开发。
---
## Observal 的用途
Observal 适用于跨 AI 编码工具进行上下文工程的团队。如果您的组织维护技能、AGENTS 文件、MCP 服务器、钩子、提示、沙盒或子代理定义，Observal 为您提供一个集中位置来打包它们成版本化的代理，发布到注册中心，并安装到您开发人员使用的运行环境中。
定义一个代理一次。Observal 为 Claude Code、Cursor、Kiro、Pi、Copilot、Codex、OpenCode 等支持的工具生成正确的配置。当团队使用这些代理时，Observal 将实际使用情况转化为有关哪些提示、技能、工具和策略有效的洞察。
### 团队使用 Observal 的原因
- **将上下文打包成可重用的代理：** 将技能、MCP 服务器、钩子、提示、沙盒和策略打包成一个版本化的单元。
- **运行一个受控的注册中心：** 审查提交内容，批准内部代理，检查版本差异，并为开发人员提供一个值得信赖的地方来安装。
- **在编码工具中渲染：** 为每个支持的运行环境生成正确的配置，而不是为每个运行环境维护单独的设置说明。
- **了解什么有效：** 使用实际采用率和会话数据来找出哪些代理、工具、提示和工作流程正在帮助团队。
- **在需要时重放会话：** 使用跟踪作为调试、审查、审计和更深入分析的证据，而不使可观察性成为主要工作流。
---
## 支持的运行环境
| 运行环境 |
|-----|
| Claude Code |
| Kiro |
| Cursor |
| Pi |
| Copilot（CLI 和 VS Code 扩展）|
| Codex |
| OpenCode |
| Antigravity CLI |
只需一条命令即可将任何代理安装到任何支持的运行环境中。配置文件将自动为每个运行环境生成。
---
## 快速入门
Observal 由两个部分组成：一个 **服务器**（API + 网页界面 + 数据库），您需要自行托管，以及一个 **CLI**，您需要在每个开发人员的机器上安装。
### 1. 部署服务器
**一键安装**（需要 Docker Engine ≥ 24.0 且包含 Compose v2）：
```bash
curl -fsSL https://raw.githubusercontent.com/Observal/Observal/main/install-server.sh | bash
```
这将下载一个 Docker Compose 包，运行引导式设置（域名、密钥、端口），从 GHCR 拉取容器镜像，并启动整个堆栈（API、网页界面、PostgreSQL、ClickHouse、Redis、worker、负载均衡器、Prometheus、Grafana）。
**从源码**（适用于贡献者）：
```bash
git clone https://github.com/Observal/Observal.git && cd Observal
cp .env.example .env
make up
```
### 2. 安装 CLI
**独立二进制文件**（无需 Python）：
```bash
curl -fsSL https://raw.githubusercontent.com/Observal/Observal/main/install.sh | bash
```
**Python**（3.11+）：
```bash
uv tool install observal-cli
# 或：pipx install observal-cli
```
### 3. 连接您的运行环境
```bash
observal auth login
observal doctor --patch
```
这将与您的服务器进行身份验证，检测您的运行环境，安装遥测钩子，自动开始捕获会话，并为代理安装和注册中心命令做好准备。
登录后，在您的运行环境中运行 `/observal`，它将接管。拉取代理，提交组件，浏览注册中心，运行诊断：
```
/observal pull security-auditor
/observal scan
/observal doctor
```
或者直接告诉您的代理您想要什么，它会找出正确的命令。
---
## Observal 的工作原理
### 代理是可移植的上下文包
一个代理将 5 种组件类型打包成一个单独的可安装包：**MCP 服务器**、**技能**、**钩子**、**提示**和**沙盒**。您定义一个代理一次，将其发布到注册中心，Observal 为用户运行的任何支持的运行环境或运行环境生成正确的配置文件。
```bash
observal pull security-auditor --harness pi
```
### 注册中心是分发层
浏览已发布的代理，查看它们支持哪些运行环境，检查下载次数和评分，并使用一条命令安装。管理员在代理上线前审查提交内容。版本差异显示了版本之间到底发生了什么变化，因此团队可以安全地演化共享上下文。
### 洞察显示什么有效
Observal 将实际使用情况转化为有关哪些代理、提示、工具和工作流程有效或阻碍进展的报告。使用这些洞察来改进共享上下文，而不是根据传闻进行猜测。
### 会话跟踪提供证据
当您需要调试、审计或理解结果时，Observal 可以重放整个编码会话：用户提示、思考块、助手响应和工具调用及其输入和输出。跟踪支持注册中心和洞察工作流，而不是定义产品。
---
## 代理注册中心
**浏览、搜索和安装带有运行环境兼容性徽章的代理：**
**使用每个运行环境的实时配置预览可视化构建代理：**
**组件库：MCP、技能、钩子、提示、沙盒：**
---
## 代理洞察
**AI 驱动的洞察报告** 分析所有会话的使用模式，显示什么有效，什么阻碍进展，以及快速的改进方法。由 [LiteLLM](https://docs.litellm.ai/docs/providers) 提供支持，与任何提供商（Anthropic、OpenAI、Bedrock、Gemini、Azure、Ollama）兼容。
参见 [洞察 LLM 设置](docs/insights-setup.md) 以了解配置。
---
## 会话重放
**完整的会话概览，包含令牌计数、模型、工具和逐回合时间线：**
**捕获每个回合：用户提示、工具调用、思考块、助手响应：**
**深入任何跨度以查看确切的工具输入和输出：**
---
## 审查和治理
**管理员审查队列，包含完整的提示检查和批准/拒绝：**
**版本差异显示版本之间到底发生了什么变化：**
**排行榜跟踪顶级代理和组件的下载量：**
---
## 企业版
在单独的许可证下开源。 使用签名的 JWT 密钥激活。 核心从不导入 `ee/`，开源版本无需它即可完全功能。
企业版添加：
- **审计轨迹/日志**，带有参数化搜索和 CSV 导出
- **SAML SSO** 和 **SCIM 配置文件**
- **高管仪表盘**，用于整个组织的代理性能
**审计日志，带有参数化搜索：**
服务器和 CLI 是所有版本的同一个软件包。企业功能在运行时激活，当存在有效的许可证密钥时：
```bash
# 在服务器安装期间传递密钥
curl -fsSL https://raw.githubusercontent.com/Observal/Observal/main/install-server.sh | bash -s -- --license-key YOUR_KEY
# 稍后将其添加到您的 .env
echo 'OBSERVAL_LICENSE_KEY=your.key' >> .env
make rebuild
```
---
## 文档
完整文档位于 **[docs.observal.io](https://docs.observal.io/)**
---
## 技术栈
| 层 | 技术 |
|-------|-----------|
| 前端 | Next.js 16，React 19，Tailwind CSS 4，shadcn/ui |
| 后端 | Python 3.11+，FastAPI，Strawberry GraphQL |
| 数据库 | PostgreSQL 16（注册中心），ClickHouse（遥测）|
| 队列 | Redis + arq |
| CLI | Python，Typer，Rich |
| 遥测 | 会话钩子，stdio shims，推送式数据采集 |
| 部署 | Docker Compose（10 个服务）|
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。简短版本：
1. 分叉并克隆
2. `make hooks` 安装预提交钩子
3. 创建一个功能分支
4. 运行 `make lint` 和 `make test`
5. 打开一个 PR
参见 [AGENTS.md](AGENTS.md) 以了解内部代码库上下文。
## 社区
[GitHub Discussions](https://github.com/Observal/Observal/discussions) 用于提问和想法。[Discord](https://discord.observal.io) 用于聊天。打开 Issues 以确认的错误。
## 报告问题
```bash
observal support bundle
```
生成一个匿名诊断存档。审查后分享：`observal support inspect observal-support-*.tar.gz`
对于实时调试，Observal 使用基于 loguru 的开发日志（内部称为“optic”）。使用以下命令流式传输日志：
```bash
observal logs
```
日志写入 `~/.observal/logs/dev.log`，并为每个请求、后台作业和遥测事件包含结构化上下文。
## 安全
通过 [GitHub 私有漏洞报告](https://github.com/Observal/Observal/security/advisories) 或电子邮件联系@blazeup.app 报告漏洞。不要公开问题。参见 [SECURITY.md](SECURITY.md)。
## 星级历史
<a href="https://www.star-history.com/?repos=Observal%2FObserval&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Observal/Observal&type=date&theme=dark&legend=top-left" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Observal/Observal&type=date&legend=top-left" />
<img alt="星级历史图表" src="https://api.star-history.com/chart?repos=Observal/Observal&type=date&legend=top-left" />
</picture>
</a>
## 许可证
GNU Affero 通用公共许可证 v3.0（AGPL-3.0）。参见 [LICENSE](LICENSE)。
连接信息
猜你喜欢
暂无推荐服务器