内容
# HorizonLayer
HorizonLayer 是一个面向编码代理的本地优先的知识层。PostgreSQL 是用于存储工作空间、页面、结构化数据库、会话、链接和可恢复运行检查点的规范存储。
此仓库从版本 `0.0.1` 开始，具有全新的架构和兼容性接口。
当前服务器故意设计得小且仅限标准输入输出。它提供了八种工具：
| 工具 | 用途 |
| --- | --- |
| `workspace` | 发现和管理隔离的知识范围 |
| `session` | 启动、恢复、列出和关闭代理工作会话 |
| `page` | 存储嵌套的、基于块的非结构化知识 |
| `database` | 定义结构化的集合和类型属性 |
| `row` | 创建和查询结构化记录 |
| `link` | 关联存储在同一个工作空间中的实体 |
| `search` | 在一个工作空间中运行 PostgreSQL 原生检索 |
| `run` | 记录一次执行尝试及其检查点 |
现有的知识变更使用乐观修订，存档/恢复替换公共硬删除。数据库直接从规范的 [`schema.sql`](schema.sql) 初始化。
搜索响应默认情况下是紧凑的，以保持代理上下文较小。它们返回无损类型化引用，例如 `p_wrEjJOuSTVWohCth0LT9MA`，四舍五入的相关性得分和精确到秒的 UTC 时间戳。RAG 结果在 `sources` 中取消重复的实体元数据；每个块引用都指向其从零开始的源索引。紧凑引用在任何需要对应 UUID 的地方都有效。传递 `format: "full"` 给 `search`，当需要精确 UUID、毫秒时间戳、标签、重要性或关系元数据时。
## 为编码代理安装
一条命令即可安装 HorizonLayer 插件、其专注的代理技能和适用于 Codex 和 Claude Code 的 MCP 服务器配置：
```bash
npx -y horizonlayer@0.0.1 install
```
仅为一个客户端安装，使用 `install codex` 或 `install claude`。安装后重启客户端。MCP 服务器通过插件启动，并将重用现有的 `DATABASE_URL` 或通过 Docker 启动自己的本地 PostgreSQL 容器。
## 代理友好的本地命令
HorizonLayer 可以通过 Docker Desktop 在 macOS 和 Windows 上配置完整的本地运行时。设置启动 Docker Desktop（如果已安装），启动 PostgreSQL 和 Qdrant，并使用持久卷初始化架构，下载固定的本地嵌入模型，并验证向量集合：
```bash
horizonlayer setup
horizonlayer doctor
horizonlayer dashboard --open
```
`dashboard` 重用保存的运行时配置，并保持在前台运行，以便代理或进程监督器可以拥有其生命周期。`--open` 启动系统浏览器。使用以下命令停止托管的 PostgreSQL 和 Qdrant 服务：
```bash
horizonlayer stop
```
运行时配置存储在 macOS 上的 `~/Library/Application Support/HorizonLayer` 和 Windows 上的 `%LOCALAPPDATA%\\HorizonLayer`。显式环境变量（例如 `DATABASE_URL`）仍然覆盖保存的本地配置。
## 本地开发
要求：Node.js 22+ 和 PostgreSQL 17+（或用于启动器的本地备用 Docker）。
```bash
npm ci
npm run build
npm run verify
```
在现有数据库上运行：
```bash
DATABASE_URL=postgres://postgres:postgres@localhost:5432/horizon_layer npm run dev
```
或者让打包的启动器重用/启动本地 PostgreSQL：
```bash
node dist/launcher.js
```
下一个产品阶段将添加可选的、完全本地的向量/RAG 检索，然后是新的 Web 人机界面。PostgreSQL 仍然是真相的来源；向量索引将是派生和可重建的。
## 验证
```bash
npm run verify
npm run build
DATABASE_URL=postgres://postgres:postgres@localhost:5432/horizon_layer npm run test:smoke:live
```
实时烟雾测试通过官方 MCP 客户端连接 stdio，并针对配置的数据库练习完整的八工具工作流程。
许可证：MIT。
