mirror of https://github.com/CJackHwang/ds2api.git synced 2026-05-02 07:25:26 +08:00

Files

CJACK 6959aa2982 feat: add ETag cache optimization, code-split WebUI, and refactor XML tool scanner

- Chat history: early 304 via Revision()/DetailRevision() to avoid full snapshot reads
- WebUI: lazy-load tab containers with Suspense fallback
- Toolstream: split tool_sieve_xml.go into tags.go and scan.go
- CI: trigger on main branch, guard cross-build to dev/main pushes only
- Docs: add DEVELOPER.md developer quick reference

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

2026-04-27 14:37:23 +08:00

3.5 KiB

Raw Blame History

DS2API 开发者速查

语言 / Language: 中文

本文面向维护者和贡献者，用于快速判断“从哪里看、改哪里、跑什么”。架构细节仍以 ARCHITECTURE.md 为准，接口行为以 API.md 为准。

1. 本地入口

常用启动与检查：

# 后端
go run ./cmd/ds2api

# WebUI 开发服务器
npm run dev --prefix webui

# WebUI 生产构建
npm run build --prefix webui

PR 前固定门禁：

./scripts/lint.sh
./tests/scripts/check-refactor-line-gate.sh
./tests/scripts/run-unit-all.sh
npm run build --prefix webui

修改 Go 文件后先运行：

gofmt -w <changed-go-files>

2. 代码定位

优先从这些入口顺着调用链看：

目标	入口
总路由、CORS、健康检查	`internal/server/router.go`
OpenAI Chat / Responses	`internal/httpapi/openai/chat`、`internal/httpapi/openai/responses`
Claude / Gemini 兼容入口	`internal/httpapi/claude`、`internal/httpapi/gemini`
API 请求归一到网页纯文本上下文	`internal/promptcompat`、`docs/prompt-compatibility.md`
工具调用解析与流式防泄漏	`internal/toolcall`、`internal/toolstream`、`docs/toolcall-semantics.md`
DeepSeek 上游调用、登录、PoW、代理	`internal/deepseek/client`、`internal/deepseek/transport`
账号池、并发槽位、等待队列	`internal/account`
Admin API	`internal/httpapi/admin`
WebUI 页面	`webui/src/layout/DashboardShell.jsx`、`webui/src/features/*`
服务器端对话记录	`internal/chathistory`、`internal/httpapi/admin/history`

3. 常见改动建议

改接口行为时，同时检查 API.md / API.en.md 是否需要同步。
改 prompt 兼容链路时，必须同步 docs/prompt-compatibility.md。
改 tool call 语义时，同时检查 Go、Node sieve 和 docs/toolcall-semantics.md。
改 WebUI 配置项时，同时检查 webui/src/features/settings、语言包和 config.example.json。
拆分大文件时，保持对外函数签名稳定，并跑 ./tests/scripts/check-refactor-line-gate.sh。

4. 故障定位

接口请求先看路由入口，再看协议适配层，最后看共享 runtime：

路由是否命中：internal/server/router.go 和对应 RegisterRoutes。
鉴权与账号选择：internal/auth、internal/account。
请求归一化：internal/promptcompat 或协议转换包。
上游请求：internal/deepseek/client。
流式输出：internal/stream、internal/sse、internal/toolstream。
响应格式：internal/format/* 或 internal/translatorcliproxy。

对话记录页面问题优先检查：

Admin API：/admin/chat-history、/admin/chat-history/{id}。
后端存储：internal/chathistory/store.go。
前端轮询和 ETag：webui/src/features/chatHistory/ChatHistoryContainer.jsx。

Tool call 问题优先跑：

go test -v ./internal/toolcall ./internal/toolstream -count=1
node --test tests/node/stream-tool-sieve.test.js tests/node/chat-stream.test.js

5. 测试选择

小范围 Go 改动：

go test ./internal/<package> -count=1

前端改动：

npm run build --prefix webui

高风险协议或流式改动：

./tests/scripts/run-unit-all.sh

发布或真实账号链路验证：

./tests/scripts/run-live.sh

端到端测试产物默认写入 artifacts/testsuite/。分享日志前需要清理 token、密码、cookie 和原始请求响应内容。

3.5 KiB Raw Blame History Unescape Escape