docs: translate issue/PR templates, docs index and pow README to English

Translate the GitHub bug/feature issue forms and PR template, the docs index, and pow/README to English. Rename the reverse-engineering note file to an ASCII name (deepseek-sse-behavior-2026-04-05.md); its body is translated in a follow-up.
2026-06-02 22:17:26 +03:00
parent f64ef4c733
commit c01b8defb3
6 changed files with 60 additions and 93 deletions
@@ -1,14 +1,14 @@
-name: '🐛 反馈 Bug'
-description: '反馈一个问题/缺陷'
+name: '🐛 Bug Report'
+description: 'Report a problem or defect'
 title: '[Bug] '
 labels: ['bug']
 body:
  - type: dropdown
    attributes:
-      label: '📦 部署方式'
+      label: '📦 Deployment method'
      multiple: true
      options:
-        - '本地部署'
+        - 'Local'
        - 'Docker'
        - 'Vercel'
        - 'Other'
@@ -16,13 +16,13 @@ body:
      required: true
  - type: input
    attributes:
-      label: '📌 软件版本'
+      label: '📌 Software version'
    validations:
      required: true

  - type: dropdown
    attributes:
-      label: '💻 系统环境'
+      label: '💻 Operating system'
      multiple: true
      options:
        - 'Windows'
@@ -37,24 +37,24 @@ body:
      required: true
  - type: input
    attributes:
-      label: '📌 系统版本'
+      label: '📌 OS version'
    validations:
      required: false
  - type: textarea
    attributes:
-      label: '🐛 问题描述'
-      description: 请提供一个清晰且简洁的问题描述，若上述选项为`Other`，也请详细说明。
+      label: '🐛 Bug description'
+      description: Please provide a clear and concise description of the problem. If you selected `Other` above, please describe it in detail too.
    validations:
      required: true
  - type: textarea
    attributes:
-      label: '📷 复现步骤'
-      description: 请提供一个清晰且简洁的描述，说明如何复现问题。
+      label: '📷 Steps to reproduce'
+      description: Please provide a clear and concise description of how to reproduce the problem.
  - type: textarea
    attributes:
-      label: '🚦 期望结果'
-      description: 请提供一个清晰且简洁的描述，说明您期望发生什么。
+      label: '🚦 Expected behavior'
+      description: Please provide a clear and concise description of what you expected to happen.
  - type: textarea
    attributes:
-      label: '📝 补充信息'
-      description: 如果您的问题需要进一步说明，或者您遇到的问题无法在一个简单的示例中复现，请在这里添加更多信息。
+      label: '📝 Additional information'
+      description: If your issue needs further explanation, or it cannot be reproduced in a simple example, please add more information here.
@@ -1,21 +1,21 @@
-name: '🌠 功能需求'
-description: '提出需求或建议'
+name: '🌠 Feature Request'
+description: 'Propose a feature or suggestion'
 title: '[Feature Request] '
 labels: ['enhancement']
 body:
  - type: textarea
    attributes:
-      label: '🥰 需求描述'
-      description: 请添加一个清晰且简洁的问题描述，阐述您希望通过这个功能需求解决的问题。
+      label: '🥰 Feature description'
+      description: Please add a clear and concise description of the problem you want this feature to solve.
    validations:
      required: true
  - type: textarea
    attributes:
-      label: '🧐 解决方案'
-      description: 请清晰且简洁地描述您想要的解决方案。
+      label: '🧐 Proposed solution'
+      description: Please describe the solution you would like clearly and concisely.
    validations:
      required: true
  - type: textarea
    attributes:
-      label: '📝 补充信息'
-      description: 在这里添加关于问题的任何其他背景信息。
+      label: '📝 Additional information'
+      description: Add any other context about the problem here.
@@ -1,20 +1,20 @@
-#### 💻 变更类型 | Change Type
-
-<!-- For change type, change [ ] to [x]. -->
-
- [ ] ✨ feat
- [ ] 🐛 fix
- [ ] ♻️ refactor
- [ ] 💄 style
- [ ] 👷 build
- [ ] ⚡️ perf
- [ ] 📝 docs
- [ ] 🔨 chore
-
-#### 🔀 变更说明 | Description of Change
-
-<!-- Thank you for your Pull Request. Please provide a description above. -->
-
-#### 📝 补充信息 | Additional Information
-
-<!-- Add any other context about the Pull Request here. -->
+#### 💻 Change Type
+
+<!-- For change type, change [ ] to [x]. -->
+
+- [ ] ✨ feat
+- [ ] 🐛 fix
+- [ ] ♻️ refactor
+- [ ] 💄 style
+- [ ] 👷 build
+- [ ] ⚡️ perf
+- [ ] 📝 docs
+- [ ] 🔨 chore
+
+#### 🔀 Description of Change
+
+<!-- Thank you for your Pull Request. Please provide a description above. -->
+
+#### 📝 Additional Information
+
+<!-- Add any other context about the Pull Request here. -->
@@ -1,39 +1,6 @@
-# DS2API 文档导航 | Documentation Index
+# DS2API Documentation Index

-语言 / Language: [中文](README.md) | [English](README.md#english)
-
-## 中文
-
-为减少重复维护，本仓库文档按“入口文档 + 专题文档”拆分。建议从下列顺序阅读：
-
-1. [项目总览（README）](../README.MD)
-2. [架构与目录说明](./ARCHITECTURE.md)
-3. [接口文档（API）](../API.md)
-4. [部署指南](./DEPLOY.md)
-5. [测试指南](./TESTING.md)
-6. [贡献指南](./CONTRIBUTING.md)
-
-### 专题文档
-
- [API -> 网页对话纯文本兼容主链路说明](./prompt-compatibility.md)
- [Tool Calling 统一语义](./toolcall-semantics.md)
- [上游 Fork 监控清单](./upstream-forks.md)
- [DeepSeek SSE 行为结构说明（逆向观察）](./DeepSeekSSE行为结构说明-2026-04-05.md)
-
-### 文档维护约定
-
- 文档更新必须以实际代码实现为依据：总路由装配看 `internal/server/router.go`，协议/resource 路由看 `internal/httpapi/*/**/routes.go` 与 `internal/httpapi/admin/handler.go`，配置默认值看 `internal/config/*`，模型/alias 看 `internal/config/models.go`，prompt 兼容链路看 `docs/prompt-compatibility.md` 列出的代码入口。
- `README.MD`：面向首次接触用户，保留“是什么 + 怎么快速跑起来”。
- `docs/ARCHITECTURE*.md`：面向开发者，集中维护项目结构、模块职责与调用链。
- `API*.md`：面向客户端接入者，聚焦接口行为、鉴权和示例。
- `docs/prompt-compatibility.md`：面向维护者，集中维护“API -> 网页对话纯文本上下文”的统一兼容语义；相关行为修改时必须同步更新。
- 其他 `docs/*.md`：主题化说明，避免在多个文档重复粘贴同一段内容。
-
---
-
-## English
-
-To reduce maintenance drift, docs are split into an “entry doc + topical docs” layout.
+To reduce maintenance drift, docs are split into an "entry doc + topical docs" layout.

 Recommended reading order:

@@ -49,13 +16,13 @@ Recommended reading order:
 - [API -> pure-text web-chat compatibility pipeline](./prompt-compatibility.md)
 - [Tool-calling unified semantics](./toolcall-semantics.md)
 - [Upstream fork monitoring notes](./upstream-forks.md)
- [DeepSeek SSE behavior notes (reverse-engineered)](./DeepSeekSSE行为结构说明-2026-04-05.md)
+- [DeepSeek SSE behavior notes (reverse-engineered)](./deepseek-sse-behavior-2026-04-05.md)

 ### Maintenance conventions

 - Documentation updates must be grounded in the actual implementation: root routing lives in `internal/server/router.go`, protocol/resource routes live in `internal/httpapi/*/**/routes.go` and `internal/httpapi/admin/handler.go`, config defaults in `internal/config/*`, models/aliases in `internal/config/models.go`, and the prompt compatibility pipeline in the code entrypoints listed by `docs/prompt-compatibility.md`.
- `README.MD`: onboarding-oriented (“what + quick start”).
+- `README.MD`: onboarding-oriented ("what + quick start").
 - `docs/ARCHITECTURE*.md`: developer-oriented source of truth for module boundaries and execution flow.
 - `API*.md`: integration-oriented behavior/contracts.
- `docs/prompt-compatibility.md`: maintainer-oriented source of truth for the “API -> pure-text web-chat context” compatibility flow; update it whenever related behavior changes.
+- `docs/prompt-compatibility.md`: maintainer-oriented source of truth for the "API -> pure-text web-chat context" compatibility flow; update it whenever related behavior changes.
 - Other `docs/*.md`: focused topics, avoid copy-pasting the same section into multiple files.
@@ -1,14 +1,14 @@
-# DeepSeek PoW 纯算实现
+# DeepSeek PoW Pure-Compute Implementation

-当前服务端 PoW 已走纯 Go 实现：`internal/deepseek/pow.go` 负责从上游 challenge map 中取字段，调用 `ds2api/pow` 求解 nonce，并组装 `x-ds-pow-response` header。
+The server-side PoW now runs on a pure Go implementation: `internal/deepseek/pow.go` reads the fields from the upstream challenge map, calls `ds2api/pow` to solve the nonce, and assembles the `x-ds-pow-response` header.

-## 算法
+## Algorithm

-DeepSeekHashV1 = SHA3-256 但 **Keccak-f[1600] 跳过 round 0** (只做 rounds 1..23)。其余参数不变:
-rate=136, padding=0x06+0x80, output=32 字节。
+DeepSeekHashV1 = SHA3-256 but with **Keccak-f[1600] skipping round 0** (only rounds 1..23). All other parameters are unchanged:
+rate=136, padding=0x06+0x80, output=32 bytes.

-PoW 协议:服务端选 answer ∈ [0, difficulty),计算 `challenge = hash(prefix + str(answer))`。
-客户端遍历 [0, difficulty) 找到匹配的 nonce。
+PoW protocol: the server picks answer ∈ [0, difficulty) and computes `challenge = hash(prefix + str(answer))`.
+The client iterates over [0, difficulty) to find the matching nonce.

 ```
 prefix = salt + "_" + str(expire_at) + "_"
@@ -17,13 +17,13 @@ hash   = DeepSeekHashV1(input)      → 32 bytes
 header = base64(json({algorithm, challenge, salt, answer, signature, target_path}))
 ```

-## 主要入口
+## Main entrypoints

- `pow/deepseek_hash.go`：DeepSeekHashV1 / Keccak-f[1600] rounds 1..23。
- `pow/deepseek_pow.go`：`SolvePow`、`BuildPowHeader`、`SolveAndBuildHeader`。
- `internal/deepseek/pow.go`：服务侧适配层，校验 `algorithm == DeepSeekHashV1` 并调用 `pow.SolvePow`。
+- `pow/deepseek_hash.go`: DeepSeekHashV1 / Keccak-f[1600] rounds 1..23.
+- `pow/deepseek_pow.go`: `SolvePow`, `BuildPowHeader`, `SolveAndBuildHeader`.
+- `internal/deepseek/pow.go`: server-side adapter layer; validates `algorithm == DeepSeekHashV1` and calls `pow.SolvePow`.

-## 测试
+## Tests

 ```bash
 cd pow && go test -v ./... && go test -bench=. -benchmem