Tài liệu API

Bắt đầu nhanh

npm install
cp .env.example .env
# Sửa .env: điền OPENROUTER_API_KEY
npm run gen:key staff-01
npm run dev   # http://localhost:8787

Cắm vào Cline / OpenCode

Base URL	`http://localhost:8787/v1`
API Key	`goki-…` (từ `npm run gen:key` hoặc `npm run keys create`)
Model	`goki-v1-pro` (điều phối) hoặc `goki-v1-flash` (rẻ, chuyển tiếp thẳng)

Endpoint

`POST /v1/chat/completions`	Chat + streaming SSE + tool calls (chuẩn OpenAI)
`GET /v1/models`	Danh sách model alias
`GET /health`	Health check
`POST /v1/repos/sync`	Upload repo tenant để lập kế hoạch có ngữ cảnh
`GET /v1/repos/files`	Liệt kê file tenant
`DELETE /v1/repos`	Xóa repo tenant
`/admin/*`	Dashboard admin (basic-auth, set `GOKI_ADMIN_PASS`)
`/app/*`	Dashboard user (login bằng API key)

Danh sách model

Alias	Vai trò	Upstream	Giá in/out	Context
`goki-v1-pro`	điều phối	deepseek/deepseek-v4-pro	$0.70 / $1.45	1,048,576
`goki-sonnet-1`	điều phối	deepseek/deepseek-v4-pro	$0.70 / $1.45	1,048,576
`goki-v1-flash`	công nhân	deepseek/deepseek-v4-flash	$0.15 / $0.30	1,048,576
`goki-coder-1`	công nhân	deepseek/deepseek-v4-flash	$0.15 / $0.30	1,048,576
`goki-v1-reviewer`	phản biện	z-ai/glm-5.2	$1.60 / $5.00	1,048,576
`goki-v1-vision`	đọc ảnh	z-ai/glm-4.6v	$0.50 / $1.50	131,072

Đường ống điều phối

Yêu cầu khách hàng
  │
  ├─ Có ảnh? ──→ Model đọc ảnh → xuất KẾ HOẠCH
  │
  ├─ Có công cụ + write? ──→ Đường ống điều phối:
  │   1. Điều phối: stream suy nghĩ + bản đặc tả nháp + đánh độ khó
  │   2. Phản biện đặc tả: mài đặc tả (type, edge case, dependency)
  │   3. Công nhân × N song song: sinh code theo tác vụ
  │   4. tsc --noEmit: bắt lỗi cú pháp/type/import → thử lại
  │   5. Chạy test thật: node --test nếu có .test.ts
  │   6. Phản biện code: review logic → thử lại nếu fail
  │   7. Kiểm tra xung đột ngữ nghĩa: import khớp export
  │   8. Bỏ phiếu công nhân: 3 phiên bản, 2/3 đồng ý
  │   9. Tự sửa chữa: tsc lỗi 2 lần → phản biện tiếp quản
  │  10. Cắt rườm rà đầu ra → xuất tool_call về Cline
  │  11. Lưu kết quả đã kiểm tra vào cache
  │
  └─ Chat thường ──→ Chuyển tiếp thẳng lên upstream

Đa tenant

Tenant ID được xác định từ: header X-Tenant-Id → tiền tố API key → default. Mỗi tenant có cache, repo, đồ thị ký hiệu riêng.

curl -X POST http://localhost:8787/v1/repos/sync \
  -H "Authorization: Bearer goki-..." \
  -H "X-Tenant-Id: team-alpha" \
  -H "Content-Type: application/json" \
  -d '{"files":[{"path":"src/auth.ts","content":"export function login(){}"}]}'

Cấu hình (.env)

`OPENROUTER_API_KEY`	Key provider upstream (bắt buộc)
`GOKI_MODE`	`passthrough` hoặc `orchestrator`
`GOKI_STORAGE`	`file` hoặc `db` (Postgres + Redis)
`GOKI_TOOL_ORCHESTRATION`	`on` = xuất tool_call cho Cline
`GOKI_COMPRESSION`	`on` = nén ngữ cảnh
`GOKI_ADMIN_PASS`	Bật dashboard admin tại `/admin`

CLI

npm run dev          # server dev
npm run typecheck    # kiểm tra TypeScript
npm run test:all     # test nén + edge + code
npm run gen:key      # sinh API key tĩnh (file mode)
npm run keys create  # tạo key DB
npm run db:init      # khởi tạo schema Postgres
npm run billing      # xem revenue/cost/margin
npm run eval         # bộ đánh giá 15 tác vụ