快速开始

糯糯同时提供 OpenAI 兼容网关(/v1/chat/completions,需要 API Key)与 网页聊天 API(/api/chat,仅 IP 限流)。服务基地址为 http://<host>:3866(生产建议置于 Nginx / TLS 之后)。

1. 本地演示环境,免鉴权调用聊天 API:

curl http://localhost:3866/api/chat \
  -H "Content-Type: application/json" \
  -d '{"model":"NN-4","messages":[{"role":"user","content":"你好"}]}'

2. 通过 OpenAI 兼容网关调用(需 API Key):

curl https://api.nuonuo.ai/v1/chat/completions \
  -H "Authorization: Bearer $NUONUO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"NN-4","messages":[{"role":"user","content":"介绍一下超长上下文"}],"max_tokens":1024}'

响应为 OpenAI 形态 + 糯糯扩展字段(route / evidence_level / engine / usage.context_usage)。鉴权与防滥用规则见 安全与门禁。

API 参考

通用约定:请求体为 JSON(UTF-8,上限 512KB);解析失败返回 400 INVALID_JSON,超限返回 413 BODY_TOO_LARGE。响应统一 application/json; charset=utf-8 且 Cache-Control: no-store(/files/out/* 与静态文件除外)。错误统一格式 {"error":"<错误码>","message":"…"},部分错误附 retryAfter 或 words。

/v1 鉴权与防中转滥用

• 鉴权方式:Authorization: Bearer <key>;密钥来自 NUONUO_API_KEYS(逗号分隔,每段 ≥ 20 字符),恒定时间比对。
• 未配置密钥 → 503 V1_NOT_CONFIGURED;缺失 / 无效密钥 → 401 INVALID_API_KEY。
• 仅支持非流式:stream:true → 400 STREAM_NOT_SUPPORTED。
• max_tokens:可选正整数,上限 131072;非法 → 400 INVALID_MAX_TOKENS,超限截断后 finish_reason:"length"。
• 防中转滥用:以 Key 前缀哈希或 ip 为身份,60 秒滑动窗口六信号评分,命中触发 ABUSE 错误码:

常见错误码:RATE_LIMITED / DAILY_LIMIT / BUSY(429,IP 限流 / 日限 / 全局并发,附 Retry-After)、UNKNOWN_MODEL / EMPTY_MESSAGES(400)、SENSITIVE_CONTENT(400,附 words)、ENGINE_NOT_CONFIGURED(503)、UPSTREAM_TIMEOUT / UPSTREAM_ERROR / INTERNAL_ERROR(504 / 502 / 500)、INVALID_JSON(400)、BODY_TOO_LARGE(413)、NOT_FOUND(404)。完整错误码总表见 docs/API-REFERENCE.md 第 13 节。

CLI 命令

安装 CLI:一条 curl 命令或本地执行 bash cli/install.sh(安装方式见 下载客户端页);安装完成后先运行 nuonuo doctor 自检环境。

超长上下文机制(核心算法)

糯糯的"超长上下文"不是硬塞 1M token,而是 上下文治理——来自一套实战验证的确定性工程体系:

1. 最小上下文加载:只加载完成当前任务所需的消息(默认最近 12 条入窗),不把整段历史塞进窗口——历史存于会话存储,按需分页取回。
2. 窗口压缩(continuity=renew):接近上限时,把最早 1/3 对话折叠成结构化摘要,置换出窗口空间;压缩事件在响应中可观测(usage.context_usage.compressed)。
3. 记忆提取与召回:用户偏好 / 约定(我叫 / 我喜欢 / 请记住…)自动提取为长期记忆;询问"还记得…"时按字面重合度召回,不靠模型幻觉。
4. 线程连续性三态:keep(窗口内继续)/ renew(压缩后重建)/ block(冲突时暂停并提示)——防止压缩后失忆。
5. 证据链:每条回答标注证据等级 E0–E5,可验证、可审计、可回滚。

对话响应携带上下文占用对象,可实时观测治理效果:

"usage": {
  "prompt_tokens": 2, "completion_tokens": 15,
  "context_usage": {
    "used": 3200, "limit": 128000, "percent": 2.5,
    "compressed": 0, "renewals": 0, "memory_count": 3, "state": "keep"
  }
}

对应算法源:17 状态状态机(任务生命周期)、work-router(路由收敛)、completion-gate(完成门禁)、verification(证据映射)——均为本地项目中经过测试验证的实现。

模型与路由

API 层模型白名单为 NN-1 ~ NN-5(大小写不敏感,默认 NN-4);非白名单 → 400 UNKNOWN_MODEL。路由策略(六维评分简化):命中"复杂 / 推理 / 长文 / 代码 / 分析 / 方案"等信号自动升档;智能路由对订阅用户默认开启。

安全与门禁

鉴权方式一览:

• 无鉴权(仅 IP 限流):/api/health、/api/chat、/api/vision/analyze、/api/orders/*、/api/redeem、/api/sessions、/api/tree、/api/task/*、/api/auth/send-code、/api/auth/login、/files/out/*
• x-user-token 头(登录后签发):/api/auth/me、/api/auth/realname、/api/user/memory;个人记忆还会经 loadUserByToken 注入聊天管线
• Authorization: Bearer <key>:仅 /v1/chat/completions(NUONUO_API_KEYS)
• ?token= 或 X-Admin-Token 头:/admin/api/*(NUONUO_ADMIN_TOKEN,恒定时间比对)

门禁与防护机制:

• 限流与并发:60 秒滑动窗口默认 20 次 / 分钟、500 次 / 天;全局并发上限 50 → 429 RATE_LIMITED / DAILY_LIMIT / BUSY,附 Retry-After 头
• 防中转滥用:/v1 网关对 Key / IP 做六信号评分(60s 窗口),命中 ABUSE_BAN / ABUSE_CHALLENGE / ABUSE_LIMIT
• 敏感词与掩码:输入命中敏感词 → 400 SENSITIVE_CONTENT(附 words);输出经掩码时响应带 masked:true
• 防路径穿越:/files/out 与看图 image_path 只取 basename 并校验目录内
• 防枚举:订单号格式强校验(^NN-\d{8}-[0-9A-F]{8,12}$);兑换码无效 / 已撤销 / 已过期统一返回 404 REDEEM_NOT_FOUND,不泄露细节
• 兑换码绑定下单邮箱:邮箱不一致 → 403 EMAIL_MISMATCH,防码泄露被他人激活
• 台账加密:chat / access / errors 日志 AES-256-GCM 加密 JSONL,管理端读取时自动解密
• 失败关闭:未配置上游且未开演示模式 → 503 ENGINE_NOT_CONFIGURED,不静默降级

技术底座与许可

糯糯基于开源基座二次优化,底座来源透明保留:

• 智谱 GLM-5.2 / GLM-5( MIT 许可证)— 旗舰档
• DeepSeek V4-Flash / V4-Pro(MIT 许可证)— 轻量 / 推理档
• Kimi K3(自定义许可证,阈值内商用)— 超旗舰档(可选)

自有算法层(状态机 / 门禁 / 路由 / 证据 / 上下文治理)为糯糯原创实现。正式商用前需完成:公司主体、算法备案、AI 生成内容标识、平台协议核验。

状态与路线图

本文档最后更新:2026-08-15 · 依据 docs/API-REFERENCE.md(server.js v0.3.0,端口默认 3866)