thatsme/giulia
GitHub: thatsme/giulia
Giulia 是一个基于 Elixir/OTP 构建的持久化本地优先 AI 开发 Agent，通过维护会话间的代码上下文和知识图谱，解决了传统 AI 编程助手每次对话都丢失上下文的问题。
Stars: 10 | Forks: 0
# Giulia
Giulia 是一个用 Elixir/OTP 构建的高性能、本地优先 AI 开发 Agent。它作为一个持久化的后台 Daemon 运行，具备多项目感知能力，提供 AST 级别的代码智能、知识图谱、运行时 BEAM 内省和语义搜索——全部通过 REST API 实现。
## Giulia 存在的原因
AI 编程助手在每次会话中都会从零开始。它们丢失上下文，重新索引文件，并在每次交互时对所有内容进行 grep 搜索。Giulia 通过在 BEAM VM 上作为长驻 Daemon 运行解决了这个问题：
- **热状态**：AST 索引、知识图谱和 Embedding 在会话间保留在 ETS 中。
- **多项目**：即时切换终端和项目——每个项目都有自己独立的上下文。
- **无冷启动**：CubDB 持久化在重启时恢复完整状态，无需重新扫描。
- **深度分析**：依赖图、影响范围、耦合指标和死代码检测——预先计算并缓存，而非在每次查询时计算。
## 它的功能
### 静态分析 (L1 -- ETS + libgraph)
对整个项目图进行亚毫秒级查询。模块、函数、依赖关系、中心性、影响图、耦合热力图、复杂度评分。所有这些都基于 Sourceror AST 解析和并行文件扫描构建。
### 运行时内省
通过分布式 Erlang 连接到任何正在运行的 BEAM 节点。检查内存、Top 进程、热点模块，并将运行时数据与静态分析融合以进行性能分析。Worker 和 Monitor 容器作为双节点集群运行。
### 持久化智能
- **CubDB 热启动**：AST 条目、知识图谱、指标缓存和 Embedding 在重启后依然存在。Merkle 树完整性验证检测过时文件以进行增量重新扫描。
- **ArcadeDB L2**：多模型图数据库，用于跨构建历史、整合查询、复杂度漂移检测和耦合趋势分析。
## 快速开始
### 前置条件
- 带有 Compose v2 插件的 Docker Desktop (`docker compose`，而不是 `docker-compose`)
- Git
### 构建并启动
```
git clone https://github.com/thatsme/giulia.git
cd giulia
# 构建 Docker image
docker compose build
# 启动 worker (端口 4000) + monitor (端口 4001)
docker compose up -d
# 验证
curl http://localhost:4000/health
```
### 首次扫描
```
# 扫描项目 (使用 host 路径 -- Giulia 将其转换为 container 路径)
curl -X POST http://localhost:4000/api/index/scan \
-H "Content-Type: application/json" \
-d '{"path":"/path/to/your/project"}'
# 获取 architect brief (通过一次调用实现完整的项目感知)
curl "http://localhost:4000/api/brief/architect?path=/path/to/your/project"
```
## 架构
```
Claude Code / CLI Client
|
| HTTP
v
+------------------+ +-------------------+
| giulia-worker | | giulia-monitor |
| :4000 |<--->| :4001 |
| Static analysis | ^ | Runtime profiling |
| Scans, graphs, | | | Burst detection |
| embeddings | | | Performance data |
+------------------+ | +-------------------+
| | |
v v | Distributed Erlang
+------+ +-------+ |
| ETS | | CubDB | +---> External BEAM apps
| (L1) | | (warm |
| | | start)|
+------+ +-------+
|
v
+-----------+
| ArcadeDB |
| (L2) |
| :2480 |
| History, |
| trends, |
| cross- |
| build |
+-----------+
```
## 文档
| 文档 | 描述 |
|---|---|
| [INSTALLATION.md](INSTALLATION.md) | 前置条件、设置、配置、故障排除 |
| [ARCHITECTURE.md](ARCHITECTURE.md) | 系统设计、OTP 监督树、数据流 |
| [API.md](API.md) | REST API 参考（9 个类别中的 70 个端点） |
| [TESTING.md](TESTING.md) | 测试环境设置、运行测试、约定 |
| [CONTRIBUTING.md](CONTRIBUTING.md) | 开发工作流、构建计数器规则、PR 流程 |
| [CODING_CONVENTIONS.md](CODING_CONVENTIONS.md) | 代码风格、模式、命名约定 |
| [SECURITY.md](SECURITY.md) | 路径沙箱、章程执行、威胁模型 |
## 自我分析演示
Giulia 可以分析她自己。下面的报告是通过将 Giulia 的 70 个 API 端点指向她自己的代码库生成的——同样的分析适用于任何 Elixir 项目。
**[Giulia 自我分析报告 (构建 140)](Giulia_REPORT_2026031814.md)**
自我分析的亮点：
- 141 个模块，1,477 个函数，1,618 个图顶点，1,968 条依赖边
- 740 个 specs 覆盖了 70.7% 的公共函数，0 个死代码，0 个孤立 specs
- 识别出 3 个循环依赖（Client 子系统、Store 内部、State 内部）
- Context.Store 拥有 67 个模块的影响范围（47% 的代码库在 2 跳以内）
- 0 个未受保护的枢纽——所有高扇入模块都有完整的 spec 覆盖
- 运行时：137 MB 内存，546 个进程，0 调度器压力
## 项目状态
- **构建**：140
- **测试**：1,707 个测试
- **API**：9 个类别中的 70 个自描述端点（发现、索引、知识、智能、运行时、搜索、事务、审批、监控）
- **存储**：三层（ETS L1 + CubDB 热启动 + ArcadeDB L2）
- **容器**：双容器架构（worker + monitor）
## 许可证
版权所有 2026 Alessio Battistutta
根据 Apache 许可证 2.0 版本授权。详情请参见 [LICENSE](LICENSE)。
标签：ArcadeDB, AST代码智能, BEAM虚拟机, CubDB, Docker, Elixir, OTP, REST API, Sourceror, WebSocket, 人工智能开发代理, 代码复杂度分析, 代码搜索引擎, 依赖分析, 分布式Erlang, 后台守护进程, 多模型图数据库, 多项目管理, 安全防御评估, 开发效能工具, 持久化存储, 本地优先, 死代码检测, 热启动, 语义搜索, 请求拦截, 运行时内省, 错误基检测, 静态代码分析