# Newcclm 完整说明（面向 AI 助手）

本文件供 AI 助手阅读，用于帮用户配置和排查 Newcclm。
比 /llms.txt 更详细，包含完整参数、可直接执行的示例和错误对照表。

---

## 1. 服务概述

Newcclm 是一个 AI 助手服务，提供两种使用方式：

1. **自带命令行客户端**（推荐给普通用户）
   运行 `npx newcclm`，用账号登录即可。不需要 API Key，不需要任何配置。

2. **按 OpenAI 兼容协议接入自己的工具**
   需要一把 `sk-` 开头的密钥，向服务方申请。适用于 Cursor、WorkBuddy、
   DeepSeek Harness 等支持自定义接口的工具。

---

## 2. 接入参数（方式 2 使用）

| 项 | 值 |
| --- | --- |
| 提供商类型 | Custom Provider / OpenAI Compatible |
| Base URL | `https://sccclm.com/v1` |
| API Key | `sk-...`（向服务方申请） |
| Model | `newcclm-fast` 或 `newcclm-coding` |
| 协议 | OpenAI 兼容（`/v1/chat/completions`） |
| 认证头 | `Authorization: Bearer <API_KEY>` |
| 流式 | 支持，传 `"stream": true` |
| 上下文 | 1M token |

### 档位说明

| 模型名 | 面向场景 | 底层模型 |
| --- | --- | --- |
| `newcclm-fast` | 快速档：回邮件、改文案、整理资料、日常提问 | GLM-5.3-Flash |
| `newcclm-coding` | 增强档：复杂分析、长文档、写代码 | Qwen3.8-Flash |

备用线路为 DeepSeek V4-Flash，仅在主线路故障时自动接管（容灾，非降级）。
三个底层模型均为 1M 上下文。

### 底层模型公开说明

本服务公开底层模型，不做隐藏替换：

- **GLM-5.3-Flash** —— 日常主力，对应 `newcclm` / `newcclm-fast`
- **Qwen3.8-Flash** —— 编码与长上下文，对应 `newcclm-coding`
- **DeepSeek V4-Flash** —— 备用线路，主线路故障时接管

**使用者须同时遵守上述各模型自身的使用条款**，包括但不限于：不得用于生成违法内容、
不得转售模型本身的能力。这是上游条款对最终用户的要求（flow-down），不因中转而免除。

### 重要限制

- **只能使用上表中的模型名。** 填 `gpt-4o`、`claude-3-5-sonnet`、`deepseek-chat`
  等真实模型名会返回模型不存在的错误。
- **Base URL 不要再叠加 `/v1`**，也不要加 `/chat/completions`（除非客户端
  明确要求填写完整端点）。
- **不要选择 Anthropic 原生协议**，会连接失败。

---

## 3. 可直接执行的验证请求

```bash
curl https://sccclm.com/v1/chat/completions \
  -H "Authorization: Bearer $NEWCCLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "newcclm-fast",
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

流式版本：

```bash
curl https://sccclm.com/v1/chat/completions \
  -H "Authorization: Bearer $NEWCCLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "newcclm-fast",
    "stream": true,
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

返回一段包含 `choices` 的 JSON 即为正常。

---

## 4. DeepSeek Harness（DSH）配置

在 Settings → Models 添加自定义提供方。**不要使用 DeepSeek 官方或 Anthropic 预设目录。**

```yaml
# ~/.dsh/settings.yaml
llm-pi-ai:
  providers:
    newcclm:
      displayName: Newcclm
      api: openai-completions
      baseURL: https://sccclm.com/v1
      apiKeyEnv: NEWCCLM_API_KEY
      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens
      models:
        - id: newcclm-fast
        - id: newcclm-coding
```

```bash
export NEWCCLM_API_KEY="YOUR_API_KEY"
```

常见错误写法：

- `api: anthropic-messages` —— 协议错，连不上
- `baseURL: https://sccclm.com/v1/chat/completions` —— 重复了路径
- models 里填 `deepseek-chat` 等真实模型名 —— 会报模型不存在

---

## 5. 命令行客户端

```bash
npx newcclm                 # 进入对话
npx newcclm -p "问题"        # 单次提问后退出
npx newcclm --status        # 查看账号与剩余用量
npx newcclm --register      # 注册账号
npx newcclm --login         # 切换账号
npx newcclm --logout        # 退出登录
npx newcclm --help          # 查看用法
```

对话内可用命令：`/fast`、`/smart`、`/clear`、`/quit`。

登录凭证保存在 `~/.newcclm/config.json`（仅本人可读）。
该客户端不需要 API Key。

---

## 6. 计费

| 项 | 说明 |
| --- | --- |
| 个人档 | ¥30 / 30 天，或 $5 / 30 天 |
| 每月额度 | $4 用量 |
| 额度用尽 | 不会中断，可补充后继续 |
| 自动续费 | 无 |
| 小团队档 | ¥300 / 30 天起，多账号、可开发票 |
| 查询用量 | `npx newcclm --status` 或 https://sccclm.com/account/ |

---

## 7. 错误对照表

| 返回 / 现象 | 含义 | 建议处理 |
| --- | --- | --- |
| `Invalid token` | 密钥错误、缺失或已失效 | 检查密钥完整性；客户端用户重新登录 |
| `model not found` | 模型名不是本服务的档位名 | 只能填 `newcclm-fast` / `newcclm-coding` |
| `404 Not Found` | Base URL 写错 | 应为 `https://sccclm.com/v1`，不要叠加 `/v1` |
| 消息含 `quota` / `balance` | 当月用量用尽 | 补充用量，或等下个计费周期 |
| `429 Too Many Requests` | 触发限流 | 降低并发，稍后重试 |
| `401` 且消息含 `upstream` | 服务方上游故障，**非用户配置问题** | 稍后重试；不要反复修改自己的配置 |
| `both_paths_failed` | 主备线路均不可用（服务方故障） | 稍后重试 |
| 连接超时 | 网络问题 | 检查网络环境；如仅本服务不可达，联系服务方 |

**注意**：本服务会区分"用户配置问题"和"服务方故障"。若错误消息中出现
`upstream` 字样，说明问题在服务方一侧，用户无需修改配置。

---

## 8. 相关地址

- 首页：https://sccclm.com/
- 帮助中心：https://sccclm.com/help/
- 客户端指南：https://sccclm.com/help/client.html
- DSH 配置：https://sccclm.com/help/dsh.html
- 常见问题：https://sccclm.com/help/faq.html
- 查询用量：https://sccclm.com/account/
- 简明版：https://sccclm.com/llms.txt

---

## 9. 免责说明

Newcclm 是独立的第三方工具服务，与所调用模型的各家厂商没有隶属关系。
模型相关的名称与商标归各自所有者。