v4.0.0

DS2API 4.0 Update Technical Report — Changes from v3.6.1

Date: 2026-04-26
Scope: v3.6.1 → v4.0.0

本报告完全由本项目v4.0.0版本官网Deepseek专家模式在ClaudeCode中自行探索完成总结，实测工具调用效果在中短上下文已经接近原生API甚至持平。

---

1. Executive Summary

DS2API 4.0 represents a major architectural refactoring and consolidation release. The core theme of this update is the normalization of multi-protocol API requests into a unified pure-text web-chat compatibility pipeline, with significant changes across backend structure, tool calling, model handling, configuration, and documentation.

This report summarizes the key documentation changes between v3.6.1 and the current codex/docs-4x-architecture branch, covering 16 modified files with approximately 854 additions and 414 deletions.

---

2. New Files Introduced

2.1 docs/prompt-compatibility.md (402 lines, NEW)

This is the most significant new documentation artifact. It serves as the source-of-truth document for the "API → pure-text web-chat context" compatibility flow. This document explains how OpenAI / Claude / Gemini style API requests are normalized into DeepSeek web-chat pure-text context.

Key sections covered:

• The three-pronged translation: prompt (single string with role markers, system instructions, history), ref_file_ids (file references), and control bits (thinking_enabled, search_enabled)
• Role marker format (<｜User｜>, ``, </s>, etc.)
• Tool text injection: tools are translated into prompt text, not native schema transport
• History split: mandatory global enable with HISTORY.txt file packaging
• File handling: system prompt text vs. file-type attachments
• Per-protocol entry point differences (OpenAI, Claude, Gemini)
• Modification synchronization requirements

Why this matters: Any change to message normalization, tool prompt injection, history split, or completion payload assembly must now update this document.

2.2 docs/README.md (NEW entries)

Added a "Topical docs" reference to prompt-compatibility.md and expanded documentation maintenance conventions to require grounding in actual code locations (internal/server/router.go, internal/httpapi/*/**/routes.go, etc.).

---

3. Major Documentation Changes

3.1 ARCHITECTURE.md — Backend Restructuring

File: docs/ARCHITECTURE.md
Changes: +118 / -14 lines

The architecture documentation underwent a fundamental reorganization to reflect the 4.x backend refactoring:

Area	Before (3.6.1)	After (4.x)
internal/adapter/*	Three adapters: claude/, gemini/, openai/	Replaced by internal/httpapi/* with sub-packages: admin/, claude/, gemini/, openai/{chat,responses,files,embeddings,history,shared}
internal/deepseek/	Flat structure	Split into client/, protocol/, transport/
New modules	—	internal/promptcompat/, internal/toolstream/, internal/chathistory/
Router	Simple adapter dispatch	chi router tree with /v1/*, /anthropic/*, /v1beta/models/*, /admin/*

Mermaid diagram updated from simple adapter-based flow to a comprehensive diagram showing HTTP surface, compatibility core, shared runtime, and Vercel Node runtime subgraphs with detailed connection paths.

3.2 toolcall-semantics.md — Canonical XML Only

File: docs/toolcall-semantics.md
Changes: +16 / -63 lines (significant rewrite)

The tool calling specification was narrowed from a broad XML/Markup family parser to a single canonical format:

Aspect	Before (3.6.1)	After (4.x)
Supported formats	<tool_call>, <function_call>, <invoke>, <tool_use>, antml variants	ONLY <tool_calls> → <invoke name="..."> → <parameter name="...">
JSON tool_calls	Supported if inside markup	NOT parsed as executable
Fenced code blocks	Not mentioned	Explicitly excluded from parsing
Missing opening tag	Not handled	Go parser repairs missing <tool_calls> when </tool_calls> is present
filterToolCallsDetailed	Structural cleaning only	Removed — no allow-list filtering

Streaming behavior documented: canonical blocks enter structured capture; non-conforming content remains as plain text.

3.3 API.md — Model Portfolio Update

File: API.md
Changes: +12 / -63 lines (model list condensed)

Aspect	Before (3.6.1)	After (4.x)
V4 Flash/Pro introduced	—	deepseek-v4-flash, deepseek-v4-pro, deepseek-v4-flash-search, deepseek-v4-pro-search, deepseek-v4-vision, deepseek-v4-vision-search
Historical models removed	deepseek-chat, deepseek-reasoner, deepseek-expert-*, deepseek-vision-*	Removed in favor of V4 line
Claude models updated	claude-sonnet-4-5 default	claude-sonnet-4-6 now default (with backward compat aliases)
Deprecated families	claude-1.*, claude-2.*, claude-instant-*, gpt-3.5*	Now explicitly rejected
model_aliases naming	Used claude_mapping	Renamed to model_aliases for consistency
history_split.enabled	Configurable	Globally forced to true
history_split.trigger_after_turns	Not exposed	Now settable via /admin/settings
Tool config settings	Listed as configurable	Marked as fixed (feature_match + high, read-only)
compat fields	Importable	Excluded from /admin/config/import merge mode
Default model for tests	deepseek-chat	deepseek-v4-flash

3.4 DEPLOY.md — Vercel Architecture Expansion

File: docs/DEPLOY.md
Changes: +12 / -0 lines

Change	Details
DS2API_VERCEL_STREAM_LEASE_TTL_SECONDS default	Changed from "sync with responses.store_ttl_seconds" to fixed 900
New env var	DS2API_RAW_STREAM_SAMPLE_ROOT — raw stream sample save/read directory
Vercel sections renumbered	3.3 → 3.4, 3.4 → 3.5, 3.5 → 3.6
Model example	deepseek-chat → deepseek-v4-flash

3.5 Pow/README.md — WASM to Pure Go

File: pow/README.md
Changes: -30 / +8 lines

The PoW implementation moved from WASM-based (wazero runtime + sha3_wasm_bg.*.wasm assets) to a pure Go implementation:

Metric	WASM (v3.6.1)	Pure Go (4.x)
Hash performance	5.33M hash/s	Referenced as faster
Solve performance	~75 solves/s/core	~2.8× faster
Dependencies removed	github.com/tetratelabs/wazero, WASM binary assets	Pure Go only

3.6 AGENTS.md — Documentation Sync Rules

File: AGENTS.md
Changes: +6 / -0 lines

New rule: When business logic or user-visible behavior changes, documentation must be updated in the same change. docs/prompt-compatibility.md specifically called out as the source-of-truth for the API-to-web-chat compatibility flow, with concrete file lists to check.

3.7 CONTRIBUTING.md — Quality Gates

File: docs/CONTRIBUTING.md
Changes: +11 / -0 lines

Addition	Details
PR gates	Added ./scripts/lint.sh + ./tests/scripts/check-refactor-line-gate.sh + ./tests/scripts/run-unit-all.sh + npm run build --prefix webui
Go linting	gofmt -w step before golangci-lint
I/O Close errors	Must be logged, not silently ignored
run-live.sh	Clarified as optional (real-account E2E), not part of fixed PR gates

3.8 TESTING.md — Test Path Updates

File: docs/TESTING.md
Changes: +25 / -0 lines

Change	Before	After
Test paths	internal/adapter/openai/...	internal/httpapi/openai/...
PR gate section	Not present	Added with explicit command list

---

4. Structural Changes Summary

Directory Reorganization

REMOVED:
  internal/adapter/{claude,gemini,openai}/

ADDED:
  internal/httpapi/{admin,claude,gemini,openai/{chat,responses,files,embeddings,history,shared}}/
  internal/promptcompat/
  internal/toolstream/
  internal/chathistory/
  internal/deepseek/{client,protocol,transport}/   (was flat)

REFACTORED:
  internal/deepseek/pow.go  →  pow/  (Pure Go PoW, no WASM)
  API surface: router.go → chi router with protocol/resource sub-routes

Key Cross-Cutting Changes

1. PoW: WASM dependency removed; pure Go Keccak-f[1600] implementation with pow.SolvePow() / pow.SolveAndBuildHeader()
2. Tool calling: XML/Markup parser narrowed to canonical <tool_calls> only; toolcall settings fixed to feature_match + high; prompt-driven examples dynamically generated from declared tools
3. Model management: V4 model line introduced; model_aliases renamed from claude_mapping; deprecated model families explicitly rejected
4. History split: Globally forced enabled=true; trigger_after_turns configurable; HISTORY.txt packaging with IGNORE wrapper
5. CORS: Expanded to cover all protocol surfaces; supports x-goog-api-key, Anthropic-Version, Anthropic-Beta; third-party headers passed through
6. Vercel streaming: Finalization semantics aligned between Go and Node; lease TTL fixed at 900s
7. Web security: Secret previews fully masked; uuid dependency replaced for http-environment key generation

---

5. Migration Considerations

For users upgrading from v3.6.1:

• PoW: Binaries no longer need WASM assets; go.mod simplified (no wazero)
• Config: claude_mapping renamed to model_aliases in /admin/config and /admin/settings; old keys accepted as fallback
• Model IDs: deepseek-chat / deepseek-reasoner deprecated in favor of deepseek-v4-flash / `deepseek-...

v3.6.1

重要须知

自该版本v3.6.1以后开始实验性支持1M以上的超长上下文（基于拆分HISTORY.txt文件）可在管理面板选择关闭恢复原来模式（不推荐），此前上下文窗口约为社区反馈的40k（专家模式）。

本次更新内容

• 修复v3.6.0从源码构建docker失败问题
• webui增加对历史对话保存展示HISTORY文件内容的支持
• 增加安全报告规范和社区贡献者守则

What's Changed

• feat: 对话记录支持保存并展示 HISTORY 内容 by @ouqiting in #286
• Add Code of Conduct and improve security policy clarity by @CJackHwang in #287
• Fix webui batch import template Docker build by @jacob-sheng in #289
• 修复3.6.0docker构建问题 by @CJackHwang in #290

Full Changelog: v3.6.0...v3.6.1

v3.6.0

更新内容

• 自定义key和账号的备注信息
• 默认启用-历史对话拆分文件上传 解除上下文窗口限制（1M）
• 后台历史对话记录查看
• 修复已知标签引用问题

What's Changed

• 给webui新增“对话记录” by @ouqiting in #281
• 修复搜索场景下 citation 标签偶发未替换问题（FINISHED 后继续收集引用元数据） by @livesRan in #282
• feat(account): add structured API key and account name/remark support by @CJackHwang in #279
• 非常大的更新（3.6.0） by @CJackHwang in #284

New Contributors

• @ouqiting made their first contribution in #281

Full Changelog: v3.5.2...v3.6.0

v3.5.2

补丁

v3.5.1映射问题修复

LICENSE变更

从GPL3.0更新license为AGPL3.0

What's Changed

• 修复重复 URL 且 cite_index 不稳定时 citation 映射不完整的问题 by @livesRan in #275
• Fix citation link mapping for duplicate URLs and unstable cite_index by @CJackHwang in #276

Full Changelog: v3.5.1...v3.5.2

v3.5.1

更新内容

• 文档精简
• 修复非流式模式非思考模型的搜索标签[citation:N]未解析的问题

What's Changed

• /v1/chat/completions 接口返回报文中出现了[citation:1][citation:2]等未解析的标签，本次改动将返… by @livesRan in #271
• Fix zero-based citation index normalization by @CJackHwang in #273
• Remove outdated architecture documentation and improve citation parsing by @CJackHwang in #272

New Contributors

• @livesRan made their first contribution in #271

Full Changelog: v3.5.0...v3.5.1

v3.5.0

减少了自v3.3.0以来的大部分模型输出不稳定情况（仍可能出现有思考但空输出的情况，并非项目所致，为模型思考模式问题）

XML工具调用解析与代码围栏感知

• f313d00 – 在工具筛选中增加代码围栏感知能力，防止代码块内的XML工具调用被误判，并优化了提示词指令。
• 69eb711 – 扩展工具调用解析器，支持变长Markdown围栏（如 ```）。
• 5b7cdaa – 修复了被Markdown围栏包裹的XML工具调用解析问题。

系统提示与思考模式

• 10d681f – 开启思考模式时，向系统提示词中注入对话连贯性与推理指令。

API与文档对齐

• 08f32c4 – 使API文档与当前已实现的路由保持一致。
• 0e7f5cd – 同步工具调用语义文档与当前实现。
• 2c08375 – 将模型别名示例刷新为当前默认值。

代码质量与强制规范

• 69b7bc0 – 强制要求工具调用XML输出中所有字符串参数必须使用CDATA包裹，提升鲁棒性，避免转义问题。
• 更新代码测试

合并请求

• 12256ce – 合并PR #266：文档准确性更新。
• fa38934 – 合并PR #267：XML解析修复。
• 修复webui账号数显示问题。

其余

• 移除无用旧json工具调用兼容层减少json相关工具误调用或丢失，减少冗余代码。

What's Changed

• fix: Increase account page size limit to 5000 by @utafrali in #263
• Strip fenced code blocks before XML tool-call parsing to avoid executing examples by @CJackHwang in #267
• docs: align API docs with implemented routes and limits by @CJackHwang in #266
• refactor: enforce mandatory CDATA wrapping for all string parameters in tool call XML output by @CJackHwang in #265
• chore: bump version to 3.5.0 by @CJackHwang in #268

New Contributors

• @utafrali made their first contribution in #263

Full Changelog: v3.4.0...v3.5.0

v3.4.0

更新内容

全模型全渠道附件上传deepseek功能
prompt构造优化
webui优化
报错优化

文件识别相关接口其他渠道兼容性待测试，OpenAI接口已通过

What's Changed

• Update VERSION by @CJackHwang in #254
• feat(prompt): tokenizer-style prompt stitching with thinking-prefix support by @CJackHwang in #255
• 全模型全渠道附件上传deepseek功能 by @CJackHwang in #256

Full Changelog: v3.3.0...v3.4.0

v3.3.0

补丁

专家模式适配（更多模型）
客户端校验版本号升级

注意

该版本（v3.3.0）以前的旧版本已全部失效，请更新至最新以保障功能可用

快速模式下上下文窗口限制1M，专家模式下上下文窗口限制40k
（暂无计划更新多轮对话缓存机制，这会限制已经大于40k上下文的对话无法使用，加上近期DeepSeek客户端变动大，看看后续是否会放开限制）

What's Changed

• Add default, expert, and vision DeepSeek model families by @shuaihaoV in #249
• Merge pull request #249 from shuaihaoV/feat/deepseek-model-type-families

Add default, expert, and vision DeepSeek model families by @CJackHwang in #252

New Contributors

• @shuaihaoV made their first contribution in #249

Full Changelog: v3.2.0...v3.3.0

v3.2.0

版本更新摘要 (v3.2.0)

成就：此v3.2版本与DeepSeek现阶段一致

1. 新增功能与核心增强

• 代理管理与路由 (Feature): 引入了对 SOCKS5/SOCKS5H 代理的管理功能，支持账号级别的代理路由配置，大幅提升了网络环境的适配能力。
• 原生 PoW 解算器 (Refactor): 重构了 Proof of Work (PoW) 模块，将原有的 WASM 实现替换为原生 Go 实现。这一改动显著提升了解算效率并降低了跨平台运行的复杂性。
• 工具调用优化 (Tool Call):
  • 改进了 XML 工具解析的鲁棒性。
  • 修复了工具调用参数中 HTML 字符被转义的问题。
  • 解决了标记语言（Markup）解析中 XML 实体的双重解码 Bug。

2. 接口与数据处理

• Token 统计优化: * 改进了 DeepSeek SSE 流式输出中的 Token 使用量传播逻辑。
  • 临时切换至内部 Token 估算算法，以解决上游字段不一致的问题，确保计费与统计的准确性。
• 异常处理: * 当上游输出为空时，现在会正确返回 429 错误码。
  • 增强了 SSE Token 重放解析的安全硬化。
  • 优化了代理失败时的回退（Fallback）行为，并对响应中的代理密码进行了脱敏处理。

3. 代码质量与工程化

• Linter 升级: 全面迁移至 golangci-lint v2，重新组织了配置文件，并新增了 CI 门禁（Gate），确保代码提交符合规范。
• 错误处理规范化: 规范了全局错误消息格式，并妥善处理了 Close() 调用的延迟错误。
• 依赖更新: 升级了前端 WebUI 的 Vite 版本及其他后端核心依赖。

4. 文档与结构

• 架构文档: 新增了系统架构文档，并对文档索引进行了集中管理。
• README 优化: 移除了各子目录下重复的项目结构介绍，使文档更加简洁清晰。

---

What's Changed

• Dev by @CJackHwang in #219
• Migrate and reorganize .golangci.yml to v2 with updated linters and exclusions by @CJackHwang in #220
• Handle deferred Close errors, normalize error messages, and add nolint annotations by @CJackHwang in #226
• Treat missing golangci-lint as bootstrap-compatible by @CJackHwang in #225
• Fix lint bootstrap behavior and harden SSE token replay parsing by @CJackHwang in #224
• Add golangci-lint bootstrap and CI lint gate; update docs and .gitignore by @CJackHwang in #222
• Dev by @CJackHwang in #221
• fix(openai): return 429 for empty upstream output by @CJackHwang in #227
• refactor: replace WASM-based PoW solver with a native Go implementation in the pow package by @CJackHwang in #229
• chore(deps-dev): bump vite from 8.0.3 to 8.0.5 in /webui in the npm_and_yarn group across 1 directory by @dependabot[bot] in #231
• 依赖升级 by @CJackHwang in #233
• Propagate DeepSeek SSE token usage to /v1/responses and remove stale POW env docs by @CJackHwang in #234
• refactor: improve XML tool parsing robustness, update system prompt constraints, and simplify tool filtering logic by @CJackHwang in #232
• docs: add architecture docs and centralize documentation index; update READMEs and API links by @CJackHwang in #236
• docs: remove duplicated project structure sections from READMEs by @CJackHwang in #238
• Fix HTML-escaped tool-call args and preserve upstream token usage (stream & non-stream) by @CJackHwang in #239
• fix: avoid double-decoding XML entity text in markup tool-call parsing by @CJackHwang in #242
• Merge pull request #239 from CJackHwang/codex/fix-escaping-issues-and-token-counting

Fix HTML-escaped tool-call args and preserve upstream token usage (stream & non-stream) by @CJackHwang in #240

• feat: 增加 SOCKS5/SOCKS5H 代理管理与账号代理路由 by @tanaer in #241
• Temporarily ignore DeepSeek upstream usage fields and prefer internal token estimation by @CJackHwang in #244
• Fix proxy-bound fallback behavior and redact proxy password responses by @CJackHwang in #246
• Merge pull request #244 from CJackHwang/codex/temporarily-switch-to-internal-usage-count

Temporarily ignore DeepSeek upstream usage fields and prefer internal token estimation by @CJackHwang in #245

New Contributors

• @dependabot[bot] made their first contribution in #231
• @tanaer made their first contribution in #241

Full Changelog: v3.1.1...v3.2.0

v3.1.2_beta

What's Changed

• Dev by @CJackHwang in #219
• Migrate and reorganize .golangci.yml to v2 with updated linters and exclusions by @CJackHwang in #220
• Handle deferred Close errors, normalize error messages, and add nolint annotations by @CJackHwang in #226
• Treat missing golangci-lint as bootstrap-compatible by @CJackHwang in #225
• Fix lint bootstrap behavior and harden SSE token replay parsing by @CJackHwang in #224
• Add golangci-lint bootstrap and CI lint gate; update docs and .gitignore by @CJackHwang in #222
• Dev by @CJackHwang in #221

Full Changelog: v3.1.1...v3.1.2_beta