okp: Instructions file for Codex

AGENTS.md — Project Conventions for okp

Overview

Open Knowledge Protocol (okp) — open structured knowledge for people and agents. PostgreSQL-backed storage with API/CLI/Skills access surfaces.

Tech Stack

• Backend: Go 1.26+, chi v5 (router), GORM v2 (ORM), pgx (PG driver)
• Database: PostgreSQL — 唯一存储层，无 Redis/缓存依赖
• CLI: cobra (命令行框架)，与 API 共享 service 层
• Skills: 纯 Markdown 指令文件，同构于 lark-* skill 模式

Architecture

cmd/api/          — HTTP API 入口
cmd/cli/          — CLI 入口（开发者工具 + 脚本集成）

internal/
  config/         — 环境变量配置
  model/          — GORM 数据模型（Concept, Link, Revision）
  store/          — 数据库初始化和连接管理
  handler/        — HTTP handlers（6 端点 + health + domains list）
  service/        — 业务逻辑（CRUD, search, lint, export）
  middleware/     — HTTP 中间件（auth token, logging, recovery）

skills/
  okp-import/      — 导入 skill（面向领域 owner 的 agent）
    references/   — 各 type 的 concept 模板和 golden examples
  okp-search/      — 搜索 skill（面向消费 agent）
  embed.go         — go:embed shim，供 CLI `okp skills install` 内嵌安装

API 端点

PUT    /api/v1/concepts/*              — upsert（L1 硬门禁在此校验；concept ID 含 /，用 catch-all 通配）
DELETE /api/v1/concepts/*              — 删除 concept + links + revisions
POST   /api/v1/concepts:batch          — 批量 upsert
GET    /api/v1/concepts                — list/search（domain/type/tag/status/q）
GET    /api/v1/concepts/*              — 单取
GET    /api/v1/links/*                 — 出链 + 反向引用（links 拆为独立顶层资源）
PUT    /api/v1/links/*                 — 替换概念的出链
GET    /api/v1/domains/{domain}/export — OKF bundle 导出（NDJSON 概念流，由客户端本地渲染文件树）
GET    /api/v1/domains/{domain}/activity — 日粒度创建、更新和成功知识读取请求（默认 30 天，最多 365 天）
GET    /api/v1/domains                 — 领域清单（concept 数及聚合 created_at/updated_at）
PUT    /api/v1/domains/{domain}        — 创建/更新 README、schema、visibility
DELETE /api/v1/domains/{domain}        — 级联删除 domain 全部数据
POST   /api/v1/domains/{domain}/invites — 生成邀请码（max_uses 0 = 不限次数，1-100 为次数上限）
GET    /api/v1/health                  — 健康检查