# 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/tw/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/tw/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/tw/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/tw/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/tw/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/tw/account/ |

---

## 7. 錯誤對照表

| 返回 / 現象 | 含義 | 建議處理 |
| --- | --- | --- |
| `Invalid token` | 密鑰錯誤、缺失或已失效 | 檢查密鑰完整性；客戶端用戶重新登錄 |
| `model not found` | 模型名不是本服務的檔位名 | 只能填 `newcclm-fast` / `newcclm-coding` |
| `404 Not Found` | Base URL 寫錯 | 應爲 `https://sccclm.com/tw/v1`，不要疊加 `/v1` |
| 消息含 `quota` / `balance` | 當月用量用盡 | 補充用量，或等下個計費週期 |
| `429 Too Many Requests` | 觸發限流 | 降低併發，稍後重試 |
| `401` 且消息含 `upstream` | 服務方上游故障，**非用戶配置問題** | 稍後重試；不要反覆修改自己的配置 |
| `both_paths_failed` | 主備線路均不可用（服務方故障） | 稍後重試 |
| 連接超時 | 網路問題 | 檢查網路環境；如僅本服務不可達，聯繫服務方 |

**注意**：本服務會區分"用戶配置問題"和"服務方故障"。若錯誤消息中出現
`upstream` 字樣，說明問題在服務方一側，用戶無需修改配置。

---

## 8. 相關地址

- 首頁：https://sccclm.com/tw/
- 幫助中心：https://sccclm.com/tw/help/
- 客戶端指南：https://sccclm.com/tw/help/client.html
- DSH 配置：https://sccclm.com/tw/help/dsh.html
- 常見問題：https://sccclm.com/tw/help/faq.html
- 查詢用量：https://sccclm.com/tw/account/
- 簡明版：https://sccclm.com/tw/llms.txt

---

## 9. 免責說明

Newcclm 是獨立的第三方工具服務，與所調用模型的各家廠商沒有隸屬關係。
模型相關的名稱與商標歸各自所有者。