内容
# o11y-advisor
专为开发者和编码代理设计的专业可观测性顾问。询问它如何为代码添加观测性、应该使用哪些遥测信号、如何编写告警规则或如何审查 OpenTelemetry 收集器的配置 —— 并从 o11y 文档库中获取基于源代码的答案。
**状态：** 预-alpha 版本 — 架构已确定，实施尚未开始。
---
## 功能描述
o11y-advisor 通过三个界面暴露精选的知识库（OpenTelemetry、Prometheus、Grafana、Loki、Tempo、SRE 实践）：
- **命令行界面（CLI）** — `o11y ask`、`o11y audit-repo`、`o11y review-plan`、`o11y review-collector`、`o11y review-alerts`、`o11y mcp serve`、`o11y skill install`
- **MCP 服务器** — `o11y mcp serve`（stdio 传输，可用于 Claude Code 及其他代理程序）
- **代理技能** — 用于代理编码工作流的 Claude Code 技能包
## 架构
Elixir/Phoenix 后端（托管在 Fly.io）+ Go CLI（单个二进制文件，无运行时依赖）。完整的架构原理请参见 [ADR-0001](docs/adr/0001-polyglot-architecture.md)。
```
┌────────────────────────┐ HTTP/JSON ┌──────────────────────────────┐
│ Go CLI / MCP 代理 │ ──────────────────────► │ Elixir/Phoenix + Arcana │
│ （本地二进制文件） │ │ PostgreSQL + pgvector │
└────────────────────────┘ │ 托管在 Fly.io │
└──────────────────────────────┘
```
知识库（嵌入、图、检索）存储在托管后端，并跨用户共享。CLI 是一个薄客户端，用于格式化结果。
### 数据摄入
数据摄入是一个后端 Mix 任务（`mix ingest.run`），按需和按计划运行 — 不在构建或安装时运行（参见 [ADR-0003](docs/adr/0003-ingestion-timing-and-semconv-pinning.md)）。对于源注册表中的每个条目：
1. **获取** 与条目 `path_glob` 匹配的文件，位于其固定的 `version_pin` 引用 — Git Trees API 列出仓库树，glob 过滤它，每个匹配的原始 Markdown 被下载（`O11yAdvisor.Ingestion.GitHub`）。设置 `GITHUB_TOKEN`/`GH_TOKEN` 以提高 API 速率限制。
2. **解析** 每个文件为 `O11yAdvisor.Ingestion.Document`，并带有 PRD §8 元数据 — `source_url`、`title`、`project`、`content_type`、`license`、`retrieved_at`、`version`（固定的引用）和 `section_path`（`O11yAdvisor.Ingestion.MarkdownParser`）。
完整的数据摄入任务将每个解析的文档分割成块，使用 Arcana 的本地 `BAAI/bge-base-en-v1.5` 嵌入器嵌入块，并将文档/块存储在 Arcana 的 PostgreSQL + pgvector 表中。块保留源元数据用于引用和版本/许可过滤。
## 仓库布局
```
backend/ Elixir/Phoenix API（ExCoveralls + Credo 配置）
cli/ Go CLI 二进制文件（cobra，无运行时依赖）
docs/
adr/ 架构决策记录
LICENSE MIT
PRD O11y Advisor MVP.md 产品需求
CLAUDE.md AI 编码指南
CONTRIBUTING.md 开发流程
```
## 贡献
有关分支策略、提交约定、如何运行测试和 CI 详细信息，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 相关文档
- [产品需求（PRD）](PRD%20O11y%20Advisor%20MVP.md)
- [ADR-0001：多语言架构](docs/adr/0001-polyglot-architecture.md)
- [ADR-0002：评估框架](docs/adr/0002-eval-framework.md)
- [ADR-0003：摄入时机和 Semconv 固定](docs/adr/0003-ingestion-timing-and-semconv-pinning.md)
- [ADR-0004：LLM 推理提供商](docs/adr/0004-llm-provider.md)
