mirror of
https://github.com/CJackHwang/ds2api.git
synced 2026-05-05 08:55:28 +08:00
120 lines
4.8 KiB
Markdown
120 lines
4.8 KiB
Markdown
# DS2API 项目价值说明
|
||
|
||
文档导航：[总览](../README.MD) / [文档索引](./README.md) / [接口文档](../API.md) / [兼容主链路](./prompt-compatibility.md) / [Tool Calling 语义](./toolcall-semantics.md)
|
||
|
||
> 本文用于说明 DS2API 的项目定位与长期价值。
|
||
> 它不是架构说明，也不是功能清单，而是从“网页能力如何稳定 API 化”这个角度解释本项目为什么成立。
|
||
|
||
## 1. 项目定位
|
||
|
||
DS2API 的定位不是“又一个 API 代理”，也不是训练工具。
|
||
|
||
它本质上是一个网页转 API 的兼容层：把 DeepSeek 网页对话侧可用的能力，整理成 OpenAI / Claude / Gemini 风格客户端可以接入的请求与响应形态。
|
||
|
||
本项目的核心价值在于：
|
||
|
||
1. 把 DeepSeek 网页对话能力 API 化。
|
||
2. 把不同客户端协议统一到同一套兼容入口。
|
||
3. 把网页侧会话、thinking、文件引用、流式输出等行为整理成客户端可消费的结果。
|
||
4. 为上层编程工具、自动化工具或外部编排器提供稳定后端。
|
||
|
||
## 2. 解决的问题
|
||
|
||
### 2.1 把网页能力变成可接入的 API 形态
|
||
|
||
网页侧能力可以直接对话，但标准客户端需要的是稳定的 API 契约。两者之间有一段天然差距：
|
||
|
||
- 输入格式不同
|
||
- 输出事件不同
|
||
- 流式语义不同
|
||
- 文件引用方式不同
|
||
- thinking 与正文的暴露方式不同
|
||
|
||
DS2API 通过 `promptcompat`、`completionruntime`、`assistantturn` 和各协议 renderer，把这段差距收敛到一条可维护的主链路中：
|
||
|
||
- 请求侧把 OpenAI / Claude / Gemini 消息归一成网页纯文本上下文。
|
||
- 上游侧按 DeepSeek 网页 completion 需要的 payload 发起会话。
|
||
- 输出侧把 DeepSeek SSE 收集或流式事件再渲染回各协议原生形态。
|
||
|
||
这才是本项目的主定义：把网页能力稳定转成 API 可消费形态。
|
||
|
||
### 2.2 不只是转发，而是兼容
|
||
|
||
普通转发只能把请求送出去，无法处理协议语义之间的差异。DS2API 需要额外处理：
|
||
|
||
- 模型 alias 与 DeepSeek 原生模型的映射
|
||
- thinking / reasoning 开关与输出结构
|
||
- search 与 citation / reference 标记
|
||
- 文件上传、历史文件和 current input file
|
||
- 上游空输出、content filter、auto-continue、重试和 usage 估算
|
||
|
||
这些都不是“把 URL 改一下”能解决的事情。项目价值正是在这些细节里体现出来。
|
||
|
||
### 2.3 让外部工具链能挂上去
|
||
|
||
当用户把 DS2API 接到编程工具、自动化工具或第三方 SDK 时，很多请求会变成长链路任务：
|
||
|
||
- 读取文件
|
||
- 搜索上下文
|
||
- 修改代码
|
||
- 执行命令
|
||
- 继续修正
|
||
- 输出最终结果
|
||
|
||
DS2API 不直接定义这些外部工具链，但它提供了一个足够稳定的 API 底座，让这些工具链可以外挂在上面继续工作。
|
||
|
||
## 3. 工具调用的价值
|
||
|
||
工具调用不是 DS2API 成立的前提，但它是项目很重要的增强能力。
|
||
|
||
即使没有工具调用，DS2API 仍然是网页转 API 兼容层；当请求包含工具能力时，项目会额外处理模型输出漂移、长参数和流式防泄漏等问题：
|
||
|
||
- 长脚本用 CDATA 保住原文
|
||
- 文件路径和命令参数不容易被转义打坏
|
||
- tool call 语法有统一的 DSML / canonical XML 处理
|
||
- 模型输出漂了也能宽匹配、自修正
|
||
- 流式场景能尽量不把工具块漏回普通文本
|
||
|
||
这使 DS2API 可以服务编程工具和 agent 类客户端，但项目主轴仍然是“网页能力 API 化”，不是把工具调用当作项目唯一卖点。
|
||
|
||
## 4. CDATA 的作用
|
||
|
||
CDATA 不是项目价值本身，但它是工具调用与长文本兼容中很实用的一部分。
|
||
|
||
对本项目这种场景来说，CDATA 的作用很直接：
|
||
|
||
- 保护长文本不被转义破坏
|
||
- 保住脚本、命令、代码片段的原样性
|
||
- 让结构化参数和自由文本更稳定地共存
|
||
- 让历史内容更容易被原样回放和再处理
|
||
|
||
它的意义不是让协议显得更复杂，而是让内容更少在转写、解析和回放过程中坏掉。
|
||
|
||
## 5. 它不是什么
|
||
|
||
为了避免误解，需要明确项目边界：
|
||
|
||
- 不是官方 DeepSeek API。
|
||
- 不是训练平台。
|
||
- 不是人工标注系统。
|
||
- 不是独立评测工具。
|
||
- 不是简单反代。
|
||
|
||
DS2API 是兼容层。它的职责是把网页能力整理成 API 体验，并在必要时对工具、历史、文件和流式输出做兼容处理。
|
||
|
||
## 6. 长期价值
|
||
|
||
DS2API 的长期价值，不在某个单点功能，而在于它把多个难点放进了同一条可维护链路：
|
||
|
||
- 多协议入口
|
||
- DeepSeek 网页 completion 适配
|
||
- prompt 纯文本兼容
|
||
- thinking / search / file 引用处理
|
||
- Go / Node 流式输出对齐
|
||
- tool call 解析与防泄漏
|
||
- Admin / WebUI / 账号池 / 并发队列
|
||
|
||
如果要用一句话概括它的价值，可以写成：
|
||
|
||
**DS2API 的价值，是把 DeepSeek 网页能力稳定整理成标准客户端可以持续使用的 API 形态。**
|