# 神识 · 魂镜模型网关（hunjing-shenshi / Shenshi）

> 文化命名「神识」（契约词典 §2.1）：统一模型能力——Provider/Endpoint 接入、能力槽位、协议转换、路由、流式、BYOK、配额与成本。神识不拥有人物状态。

## 当前状态（rewrite/1.0 M4a）

- 数据面 `POST /v1/chat/completions`：IR 入站 → 候选路由 → SSE 出站；**首帧到达前不提交响应**，失败可整体切道并返回 JSON 错误（HJ-2001），已写出字节后不换道、如实 error 终帧；
- 适配器：`openai_compatible`（云厂商兼容面与元炁本地端点共用此协议）与 `stub` 回声桩（未配置端点时兜底）；
- 端点配置：环境 `SHENSHI_ENDPOINTS`（JSON 数组，字段 type/name/base_url/api_key/model/priority），示例见 `.env.example`；
- 故障策略（shenshi-gateway.md §4）：候选按 Priority 升序 + 粘性会话置首 + 冷却端点排尾兜底；**首字超时（默认 10s）切道**；401/403 凭证级冷却 10 分钟，429/5xx/超时仅冷却该端点绑定 30 秒；
- 计量（M4a）：每次尝试一条 stdout JSON 日志（`kind=shenshi_usage`）+ 进程内聚合，`GET /me/usage` 返回按 模型×端点 的请求数/成功数/token；生产 PG 落库与 BYOK 归属随 M4b；
- 健康面 `GET /healthz` `GET /readyz`；服务令牌 `SHENSHI_SERVICE_TOKEN`（开发档可空）。

## 目录结构

```text
shenshi/
  main.go                    # 入口：store/byok/quota 装配与路由
  internal/ir/types.go       # IR 请求/增量（与灵台 app/shenshi_client/types.py 对齐）
  internal/transform/        # 出站适配器（openai 兼容 / anthropic / gemini / stub）
  internal/route/registry.go # 槽位 → 端点候选注册表
  internal/relay/sse.go      # SSE 帧写出（X-Accel-Buffering: no）
  internal/store/            # 神识自有库（PG + 内存双实现）
  internal/byok/             # BYOK 密钥库（AES-GCM 加密与脱敏）
  internal/quota/            # 配额三段式（预扣/结算/退款，钳位集中）
  internal/metering/         # 用量计量（stdout + 落库）
  internal/server/           # HTTP 服务与测试
```

## 本地运行

统一经根目录 Makefile：

```bash
make dev-shenshi          # SHENSHI_PORT=8080
make vet-shenshi          # go vet
make test-shenshi         # go test ./...
# 灵台侧联调配置（根目录 .env）：SHENSHI_BASE_URL=http://127.0.0.1:8080
```

## 测试

```bash
go vet ./... && go test ./...
```

设计依据：[神识模型网关](../docs/architecture/shenshi-gateway.md)；错误码段 HJ-2xxx 见[契约词典](../docs/contracts/contract-glossary.md) §15。