Skip to content

Commit ea3d11b

Browse files
nextroad-devnextroad-dev
committed
docs: prepare repository for open source
Restructure README, add English README, CHANGELOG, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, NOTICE and issue/PR templates. Remove internal plan docs, ignore local tooling dirs, and limit CI push triggers to main and version tags.
1 parent 52cf56b commit ea3d11b

15 files changed

Lines changed: 334 additions & 283 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
name: Bug report / 问题反馈
3+
about: 报告一个缺陷
4+
labels: bug
5+
---
6+
7+
**版本**（镜像 tag/摘要或 commit）：
8+
9+
**部署方式**（Docker / 二进制 / 源码）：
10+
11+
**问题描述与预期行为**：
12+
13+
**复现步骤**：
14+
15+
**相关日志**（请先脱敏，勿包含 API 密钥）：

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: 报告安全漏洞 / Report a vulnerability
4+
url: https://github.com/nextroad-dev/Auto-Router/security/advisories/new
5+
about: 请私下报告安全问题，不要公开提 Issue。

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
name: Feature request / 功能建议
3+
about: 提出新想法
4+
labels: enhancement
5+
---
6+
7+
**要解决的问题**：
8+
9+
**期望的方案**：
10+
11+
**考虑过的替代方案**：

‎.github/pull_request_template.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
## 变更说明
2+
3+
<!-- 做了什么、为什么 -->
4+
5+
## 测试
6+
7+
- [ ] `gofmt -l .` 无输出，`go vet ./...`、`go test ./...` 通过
8+
- [ ] 前端改动：已 `npm test`、`npm run typecheck`，并重新 `npm run build` 提交嵌入产物
9+
- [ ] 接口改动：已更新 `docs/openapi.yaml`
10+
- [ ] 使用者可见的行为变更：已记入 `CHANGELOG.md`

‎.github/workflows/ci.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@ name: CI
22

33
on:
44
push:
5+
branches: [main]
6+
tags: ["v*"]
57
pull_request:
68

79
permissions:

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,7 @@
1515
*.test
1616
coverage.out
1717
/webui/.generated/
18+
19+
# local tooling
20+
/.pi/
21+
/.serena/

‎CHANGELOG.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Changelog
2+
3+
本文件记录对使用者可见的行为变更，尤其是日志字段与配置契约。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
4+
5+
## [Unreleased]
6+
7+
### 新增
8+
9+
- 模型管理页支持永久删除任意来源的逻辑模型：一并删除其全部提供商绑定、移除模型分组引用并刷新运行时目录；提供商和历史路由日志保持不变。删除排除记录持久保存，配置导入和 models.dev 同步不会自动恢复；显式重新创建模型或在提供商页面重新绑定可恢复，其他已删除绑定仍需逐个显式恢复。返回 `snapshot_publish_failed` 时删除已提交但运行时刷新失败，需重启以加载最新目录。
10+
- 模型管理页可查看 models.dev 最近同步结果并显式触发全局同步；仪表盘分开显示服务健康/依赖状态与路由、Jev 窗口汇总。
11+
12+
### 变更
13+
14+
- 模型密集页面（模型管理、提供商模型抽屉、模型分组、仪表盘模型用量）在大量模型和长标识下保持可用宽度，横向滚动限定在表格内部。
15+
- 请求日志用量提取改为增量扫描：长响应或大流式事件不再因正文体积导致用量观测停止（单个用量值仍有 4 KiB 上限）。流式事件中分开上报的输入、输出 token 数会合并保留。旧版本曾因未完成的 SSE 事件超过 16 KiB 或事件数超过 4096 而停止统计，升级后需核对运行版本。历史日志中的旧状态和空计数不会回填。
16+
- 日志 API、服务日志与 `-logs-check` 统一省略未知或不适用的可选字段：未启用 IP 记录时无 `client_ip`，成功请求无空错误字段，未调用 Jev 时无 `jev_latency_ms`，未产生有效推荐时无 `confidence`。实际置信度为 0 或耗时不足 1 ms 时仍输出 0。历史记录中失败/跳过 Jev 的占位置信度 0 仅在读取时隐藏，不改写数据库。
17+
- `evidence_hash` 移至 `diagnostics.evidence_hash`（不是提示词哈希，不参与路由）。
18+
- 当前组路由的日志 API 与 `-logs-check` 不再输出空的 `candidate_models`、`model_count`、`selected_model`、`probabilities`；旧记录有数据时仍可读取。CLI JSON 的 `selected` 改名为 `selected_model`，与 API 一致。Jev 追踪不再重复主记录已有的状态、耗时、置信度、兜底原因和指纹；`group_count` 不再输出，可由 `candidate_groups.length` 得出。推荐使用 `candidate_groups`、`recommended_group`、`selected_group`、`group_probabilities`。**直接解析这些字段的脚本需要同步调整。**没有删除历史数据库字段。
19+
20+
### 移除
21+
22+
- `confidence_band` 不再生成，也不再作为主日志字段输出；`confidence_band` 查询参数仅用于兼容筛选旧记录。有实际历史分档时保留为 `diagnostics.legacy_confidence_band` / `legacy_trace_confidence_band`。
23+
- `has_code`、`reasoning_likely` 及正文关键词识别已移除，不再出现在 Jev 结构特征输入、诊断 API 或 `-analyze-check` 输出中。工具调用、文件检索、图片/文件/音频、输出上限等协议结构识别继续用于能力筛选；客户端的 reasoning 参数仍按原请求转发上游。
24+
- 传输客户端中未生效的 `jev.Config.InputMode` 字段已移除，输入模式只由路由层管理。
25+
- 旧版路由偏好（`routing.default_preference` 与 `X-Routing-Preference` 请求头）、高置信度阈值、默认兜底模型和成本/延迟等级已移除，它们不影响分组路由。数据库中保存的旧值启动时被忽略；仍发送的 `X-Routing-Preference` 请求头会被忽略并在转发前剥离。
26+
27+
### 迁移说明
28+
29+
- 服务启动不再读取旧 JSON 配置文件或 `AUTO_ROUTER_*` 运行配置环境变量；运行配置以代码默认值启动，再应用 SQLite 中保存的运行时覆盖。旧值不会自动迁移，请在管理台“系统设置”重新录入。传入旧版 `-config` 只显示忽略提示；检测到旧环境变量时显示通用迁移提示，不记录或回显变量名和值。
30+
- `-sync-models` 仅显示迁移提示并立即退出，请使用管理台“模型管理 → 立即同步 models.dev”。
31+
- 设置页“重置所有运行时覆盖”会恢复代码默认值并清除运行时保存的 Jev 密钥，但不会删除 Provider、模型、绑定或入站凭据。

‎CODE_OF_CONDUCT.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# 行为准则
2+
3+
我们希望为所有参与者提供友善、尊重、无骚扰的协作环境。
4+
5+
## 期望的行为
6+
7+
- 尊重不同的观点与经验，就事论事地讨论技术问题。
8+
- 给出和接受建设性的反馈。
9+
- 对新贡献者保持耐心。
10+
11+
## 不可接受的行为
12+
13+
- 人身攻击、侮辱、歧视性言论或骚扰。
14+
- 未经许可公开他人的私人信息。
15+
- 其他在专业场合中不恰当的行为。
16+
17+
## 执行
18+
19+
项目维护者有权删除、编辑或拒绝不符合本准则的评论、提交和 Issue，并可暂时或永久限制违规者参与。
20+
21+
如需反馈违规行为，请通过 GitHub 私下联系维护者（例如在仓库的 Security 页面提交私密报告并注明与行为准则相关）。
22+
23+
本准则改编自 [Contributor Covenant](https://www.contributor-covenant.org/zh-cn/version/2/1/code_of_conduct/) 2.1 版精神。

‎CONTRIBUTING.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# 贡献指南
2+
3+
感谢你愿意参与 Auto Router！
4+
5+
## 开始之前
6+
7+
- 较大的改动（新协议、路由策略、存储结构）请先开 Issue 讨论。
8+
- 安全问题请按 [SECURITY.md](SECURITY.md) 私下报告，不要公开提交。
9+
- 参与即表示同意遵守 [行为准则](CODE_OF_CONDUCT.md)，贡献内容以 [Apache-2.0](LICENSE) 授权。
10+
11+
## 开发环境
12+
13+
- Go：版本见 [`go.mod`](go.mod)
14+
- Node 22（仅修改管理台前端时需要）
15+
16+
```sh
17+
git clone https://github.com/nextroad-dev/Auto-Router.git
18+
cd Auto-Router
19+
go run ./cmd/auto-router # 默认监听本机，打开 /admin/
20+
```
21+
22+
## 后端
23+
24+
```sh
25+
gofmt -l . # 不应有输出
26+
go vet ./...
27+
go test -count=1 ./...
28+
go test -race -count=1 ./...
29+
```
30+
31+
- 代码需通过 `gofmt`；仓库使用 LF 换行（见 `.gitattributes`）。
32+
- 行为改动请附带测试。
33+
- 修改管理 API 时同步更新 [`docs/openapi.yaml`](docs/openapi.yaml)。
34+
35+
## 管理台前端（`webui/`）
36+
37+
```sh
38+
cd webui
39+
npm ci
40+
npm run dev # 开发服务器
41+
npm run api:types # 由 openapi.yaml 生成 src/lib/generated-api.ts
42+
npm test # Vitest
43+
npm run typecheck
44+
npm run test:e2e # Playwright（首次需 npx playwright install chromium）
45+
npm run build # 产物输出到 internal/api/dashboard/static/web/
46+
npm run check:embedded-assets
47+
```
48+
49+
构建产物（`internal/api/dashboard/static/web/`）提交在仓库中，使 `go build` 不依赖 Node。**修改前端后请重新 `npm run build` 并一同提交产物**，CI 会校验其与源码一致。`src/lib/generated-api.ts` 同样需与 `docs/openapi.yaml` 保持一致。
50+
51+
## 提交与 PR
52+
53+
- 从 `main` 创建分支；提交信息建议使用 `feat:` / `fix:` / `docs:` / `chore:` 前缀。
54+
- 一个 PR 聚焦一件事，说明动机与测试方式。
55+
- 影响使用者的行为变更（日志字段、配置、接口）请记入 [CHANGELOG.md](CHANGELOG.md) 的 `Unreleased`。
56+
- 提交前请本地跑通上面的检查；CI 会在 Linux 和 Windows 上运行。

‎NOTICE‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
Auto Router
2+
Copyright 2026 Auto Router contributors
3+
4+
Licensed under the Apache License, Version 2.0 (see LICENSE).
5+
6+
Third-party assets embedded in the admin console build
7+
(internal/api/dashboard/static/web/):
8+
9+
- IBM Plex Sans, IBM Plex Mono — Copyright IBM Corp., SIL Open Font License 1.1
10+
(via @fontsource/ibm-plex-sans, @fontsource/ibm-plex-mono)
11+
- Noto Sans SC — Copyright Google LLC / Adobe, SIL Open Font License 1.1
12+
(via @fontsource/noto-sans-sc)
13+
- Lucide icons — ISC License (via @iconify-json/lucide)
14+
15+
The full list of frontend dependencies and their licenses is in
16+
webui/package-lock.json; Go dependencies are listed in go.sum.

0 commit comments

Comments
 (0)