docs: add DS2API project value note and link it from docs index

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs/README.md

@@ -16,6 +16,7 @@
 
 ### 专题文档
 
+- [DS2API 项目价值说明](./project-value.md)
 - [API -> 网页对话纯文本兼容主链路说明](./prompt-compatibility.md)
 - [Tool Calling 统一语义](./toolcall-semantics.md)
 - [DeepSeek SSE 行为结构说明（逆向观察）](./DeepSeekSSE行为结构说明-2026-04-05.md)
@@ -47,6 +48,7 @@ Recommended reading order:
 
 ### Topical docs
 
+- [DS2API project value note](./project-value.md)
 - [API -> pure-text web-chat compatibility pipeline](./prompt-compatibility.md)
 - [Tool-calling unified semantics](./toolcall-semantics.md)
 - [DeepSeek SSE behavior notes (reverse-engineered)](./DeepSeekSSE行为结构说明-2026-04-05.md)

docs/project-value.md

@@ -0,0 +1,119 @@
+# 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 形态。**