ateng-mcp-server-rag 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. ateng_mcp_server_rag-1.0.0/.cliff.toml +55 -0
  2. ateng_mcp_server_rag-1.0.0/.dockerignore +79 -0
  3. ateng_mcp_server_rag-1.0.0/.editorconfig +29 -0
  4. ateng_mcp_server_rag-1.0.0/.env.example +2 -0
  5. ateng_mcp_server_rag-1.0.0/.gitattributes +37 -0
  6. ateng_mcp_server_rag-1.0.0/.githooks/commit-msg +65 -0
  7. ateng_mcp_server_rag-1.0.0/.github/CODEOWNERS +12 -0
  8. ateng_mcp_server_rag-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md +29 -0
  9. ateng_mcp_server_rag-1.0.0/.github/ISSUE_TEMPLATE/config.yml +16 -0
  10. ateng_mcp_server_rag-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md +19 -0
  11. ateng_mcp_server_rag-1.0.0/.github/PULL_REQUEST_TEMPLATE.md +25 -0
  12. ateng_mcp_server_rag-1.0.0/.github/dependabot.yml +62 -0
  13. ateng_mcp_server_rag-1.0.0/.github/workflows/ci.yml +211 -0
  14. ateng_mcp_server_rag-1.0.0/.github/workflows/release.yml +358 -0
  15. ateng_mcp_server_rag-1.0.0/.gitignore +121 -0
  16. ateng_mcp_server_rag-1.0.0/.python-version +1 -0
  17. ateng_mcp_server_rag-1.0.0/AGENTS.md +78 -0
  18. ateng_mcp_server_rag-1.0.0/CODE_OF_CONDUCT.md +50 -0
  19. ateng_mcp_server_rag-1.0.0/CONTEXT.md +131 -0
  20. ateng_mcp_server_rag-1.0.0/CONTRIBUTING.md +224 -0
  21. ateng_mcp_server_rag-1.0.0/Dockerfile +41 -0
  22. ateng_mcp_server_rag-1.0.0/LICENSE +201 -0
  23. ateng_mcp_server_rag-1.0.0/PKG-INFO +540 -0
  24. ateng_mcp_server_rag-1.0.0/README.md +485 -0
  25. ateng_mcp_server_rag-1.0.0/SECURITY.md +38 -0
  26. ateng_mcp_server_rag-1.0.0/docker-compose.yml +13 -0
  27. ateng_mcp_server_rag-1.0.0/docs/adr/0001-python-fastmcp-tech-stack.md +3 -0
  28. ateng_mcp_server_rag-1.0.0/docs/adr/0002-oss-template-ci-cd-release-workflow.md +3 -0
  29. ateng_mcp_server_rag-1.0.0/docs/adr/0003-pluggable-vector-store-architecture.md +3 -0
  30. ateng_mcp_server_rag-1.0.0/docs/adr/0004-hybrid-embedding-and-reranking-engine.md +3 -0
  31. ateng_mcp_server_rag-1.0.0/docs/adr/0005-unified-mcp-rag-environment-variables-contract.md +3 -0
  32. ateng_mcp_server_rag-1.0.0/docs/adr/0006-lightweight-native-ingestion-pipeline.md +3 -0
  33. ateng_mcp_server_rag-1.0.0/docs/adr/0007-zero-external-middleware-architecture.md +3 -0
  34. ateng_mcp_server_rag-1.0.0/docs/adr/0008-dual-mode-metadata-storage-architecture.md +11 -0
  35. ateng_mcp_server_rag-1.0.0/docs/adr/0009-multimodal-image-assets-and-mcp-resources.md +13 -0
  36. ateng_mcp_server_rag-1.0.0/docs/adr/0010-binary-document-ingestion-and-image-anchoring.md +11 -0
  37. ateng_mcp_server_rag-1.0.0/docs/adr/0011-native-fts-hybrid-search-and-reranking.md +17 -0
  38. ateng_mcp_server_rag-1.0.0/docs/adr/0012-neighboring-context-window-stitching.md +12 -0
  39. ateng_mcp_server_rag-1.0.0/pyproject.toml +111 -0
  40. ateng_mcp_server_rag-1.0.0/scripts/commit.sh +748 -0
  41. ateng_mcp_server_rag-1.0.0/scripts/release.sh +394 -0
  42. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/__init__.py +13 -0
  43. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/__main__.py +11 -0
  44. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/asset_gateway.py +583 -0
  45. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/assets.py +541 -0
  46. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/config.py +349 -0
  47. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/embedding/__init__.py +18 -0
  48. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/embedding/base.py +26 -0
  49. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/embedding/factory.py +96 -0
  50. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/embedding/fastembed_provider.py +64 -0
  51. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/embedding/openai_provider.py +193 -0
  52. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/fts.py +219 -0
  53. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/hybrid_search.py +291 -0
  54. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/metadata/__init__.py +28 -0
  55. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/metadata/base.py +400 -0
  56. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/metadata/factory.py +72 -0
  57. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/metadata/mysql.py +287 -0
  58. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/metadata/postgres.py +240 -0
  59. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/metadata/relational.py +705 -0
  60. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/metadata/sqlite.py +824 -0
  61. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/office.py +734 -0
  62. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/parsers.py +629 -0
  63. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/remote_images.py +287 -0
  64. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/reranker/__init__.py +20 -0
  65. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/reranker/api_reranker.py +153 -0
  66. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/reranker/base.py +50 -0
  67. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/reranker/factory.py +76 -0
  68. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/reranker/fastembed_reranker.py +98 -0
  69. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/s3_storage.py +464 -0
  70. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/server.py +2265 -0
  71. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/splitter.py +149 -0
  72. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/tasks.py +230 -0
  73. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/vector_store/__init__.py +20 -0
  74. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/vector_store/base.py +86 -0
  75. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/vector_store/chroma.py +213 -0
  76. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/vector_store/factory.py +41 -0
  77. ateng_mcp_server_rag-1.0.0/src/mcp_server_rag/vector_store/milvus.py +476 -0
  78. ateng_mcp_server_rag-1.0.0/tests/__init__.py +1 -0
  79. ateng_mcp_server_rag-1.0.0/tests/test_cross_kb_and_doc_mgmt.py +269 -0
  80. ateng_mcp_server_rag-1.0.0/tests/test_embedding_providers.py +665 -0
  81. ateng_mcp_server_rag-1.0.0/tests/test_enterprise_metadata.py +696 -0
  82. ateng_mcp_server_rag-1.0.0/tests/test_file_ingestion.py +272 -0
  83. ateng_mcp_server_rag-1.0.0/tests/test_hybrid_fts_search.py +690 -0
  84. ateng_mcp_server_rag-1.0.0/tests/test_image_gateway_and_s3.py +1234 -0
  85. ateng_mcp_server_rag-1.0.0/tests/test_kb_lifecycle.py +123 -0
  86. ateng_mcp_server_rag-1.0.0/tests/test_metadata_catalog.py +531 -0
  87. ateng_mcp_server_rag-1.0.0/tests/test_milvus_adapter.py +621 -0
  88. ateng_mcp_server_rag-1.0.0/tests/test_multimodal_and_context.py +517 -0
  89. ateng_mcp_server_rag-1.0.0/tests/test_office_ingestion.py +1060 -0
  90. ateng_mcp_server_rag-1.0.0/tests/test_read_only_guard.py +205 -0
  91. ateng_mcp_server_rag-1.0.0/tests/test_reranker.py +372 -0
  92. ateng_mcp_server_rag-1.0.0/tests/test_search.py +250 -0
  93. ateng_mcp_server_rag-1.0.0/tests/test_server.py +27 -0
  94. ateng_mcp_server_rag-1.0.0/tests/test_text_ingestion.py +124 -0
  95. ateng_mcp_server_rag-1.0.0/tests/test_url_ingestion.py +164 -0
  96. ateng_mcp_server_rag-1.0.0/uv.lock +5913 -0
@@ -0,0 +1,55 @@
1
+ # ==============================================================================
2
+ # git-cliff 自动化变更日志配置
3
+ # 详见: https://git-cliff.org/docs/configuration
4
+ # ==============================================================================
5
+
6
+ [remote.github]
7
+ owner = "atengk"
8
+ repo = "mcp-server-rag"
9
+
10
+ [changelog]
11
+ header = ""
12
+ body = """
13
+ {% for entry in commits | commit_groups(groups=commit_parsers_groups) %}
14
+ ### {{ entry.group | trim }}
15
+ {% for commit in entry.commits %}
16
+ - {% if commit.scope %}**{{ commit.scope }}**: {% endif %}{{ commit.message | upper_first }}\
17
+ {% if commit.remote.pr_number %} in #{{ commit.remote.pr_number }}{% endif %}\
18
+ {% if commit.remote.username %} by @{{ commit.remote.username }}{% endif %}\
19
+ {% if not commit.remote.pr_number %} ({{ commit.id | truncate(length=7, end="") }}){% endif %}\
20
+ {% endfor %}
21
+ {% endfor %}
22
+ {% if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %}
23
+ ### 🎉 新贡献者致谢 (New Contributors)
24
+ {% for contributor in github.contributors | filter(attribute="is_first_time", value=true) %}
25
+ - 感谢 @{{ contributor.username }} 提交的首次贡献!
26
+ {% endfor %}
27
+ {% endif %}\n
28
+ """
29
+ trim = true
30
+
31
+ [git]
32
+ # 开启 Conventional Commits 解析
33
+ conventional_commits = true
34
+ # 即使未按规范前缀书写的普通提交也完整保留,杜绝漏掉任何变更
35
+ filter_unconventional = false
36
+ split_commits = false
37
+
38
+ commit_parsers = [
39
+ # 过滤发版自增、开发快照推进与 PR/分支合并等无实质代码变更的视觉噪点
40
+ { message = "^chore\\(release\\):", skip = true },
41
+ { message = "^chore\\(build\\):.*next development iteration", skip = true },
42
+ { message = "^Merge pull request|^Merge branch", skip = true },
43
+ { message = "^.*!:|BREAKING CHANGE", group = "💥 破坏性更新 (Breaking Changes)" },
44
+ { message = "^feat", group = "🚀 新特性 (Features)" },
45
+ { message = "^fix", group = "🐛 缺陷修复 (Bug Fixes)" },
46
+ { message = "^perf", group = "⚡ 性能优化 (Performance)" },
47
+ { message = "^refactor", group = "🚜 代码重构 (Refactor)" },
48
+ { message = "^docs", group = "📝 文档变动 (Documentation)" },
49
+ { message = "^style", group = "🎨 代码格式 (Style)" },
50
+ { message = "^test", group = "🧪 测试相关 (Tests)" },
51
+ { message = "^build", group = "📦 构建系统 (Build System)" },
52
+ { message = "^ci", group = "⚙️ 流水线与工具 (CI/CD)" },
53
+ { message = "^chore", group = "🧹 常规维护 (Chores)" },
54
+ { message = "^revert", group = "⏪ 代码回滚 (Reverts)" },
55
+ ]
@@ -0,0 +1,79 @@
1
+ # ==============================================================================
2
+ # Docker 构建上下文忽略清单
3
+ # 避免将本地缓存、构建中间产物及机密信息发送到 Docker 守护进程
4
+ # ==============================================================================
5
+
6
+ # 版本控制、CI 与本地工程脚本
7
+ .git
8
+ .github
9
+ .githooks
10
+ scripts
11
+ .cliff.toml
12
+ .gitignore
13
+ .dockerignore
14
+
15
+ # 操作系统、IDE 与临时目录
16
+ .DS_Store
17
+ Thumbs.db
18
+ .idea
19
+ .vscode
20
+ tmp
21
+ temp
22
+ .tmp
23
+ .temp
24
+ *.tmp
25
+ *.temp
26
+ scratch
27
+ .scratch
28
+ scratchpad
29
+ .scratchpad
30
+ sandbox
31
+ .sandbox
32
+
33
+ # 测试覆盖率与代码分析缓存
34
+ coverage
35
+ *.lcov
36
+ .nyc_output
37
+ .pytest_cache
38
+ .ruff_cache
39
+ .mypy_cache
40
+ .eslintcache
41
+
42
+ # 敏感文件与本地环境变量
43
+ .env
44
+ .env.*
45
+ !.env.example
46
+
47
+ # 日志
48
+ *.log
49
+ logs
50
+
51
+ # Node.js
52
+ node_modules
53
+ npm-debug.log*
54
+ yarn-debug.log*
55
+ pnpm-debug.log*
56
+
57
+ # Java
58
+ target/
59
+ .gradle/
60
+ build/
61
+ bin/
62
+ *.class
63
+
64
+ # Python
65
+ __pycache__
66
+ *.pyc
67
+ *.pyo
68
+ *.pyd
69
+ .Python
70
+ env/
71
+ venv/
72
+ .venv/
73
+
74
+ # Go / 可执行文件
75
+ *.exe
76
+ /bin
77
+
78
+ # Rust
79
+ **/*.rs.bk
@@ -0,0 +1,29 @@
1
+ # EditorConfig 跨编辑器代码格式规范
2
+ # 详见: https://editorconfig.org
3
+
4
+ root = true
5
+
6
+ [*]
7
+ charset = utf-8
8
+ end_of_line = lf
9
+ indent_style = space
10
+ indent_size = 2
11
+ insert_final_newline = true
12
+ trim_trailing_whitespace = true
13
+
14
+ [*.{java,py,rs}]
15
+ indent_size = 4
16
+
17
+ [*.go]
18
+ indent_style = tab
19
+ indent_size = 4
20
+
21
+ [*.{json,yml,yaml,xml}]
22
+ indent_size = 2
23
+
24
+ [*.md]
25
+ trim_trailing_whitespace = false
26
+
27
+ [Makefile]
28
+ indent_style = tab
29
+
@@ -0,0 +1,2 @@
1
+ # MCP Server RAG 环境变量示例配置
2
+ LOG_LEVEL=INFO
@@ -0,0 +1,37 @@
1
+ # ==============================================================================
2
+ # Git 跨平台换行符自动归一化配置
3
+ # 强制所有文本文件统一使用 LF 换行符,杜绝 Windows CRLF 导致 Linux 脚本崩溃
4
+ # ==============================================================================
5
+
6
+ # 默认自动检测文本并统一换行为 LF
7
+ * text=auto eol=lf
8
+
9
+ # 纯文本与配置文件强制 LF
10
+ .githooks/* text eol=lf
11
+ *.sh text eol=lf
12
+ *.bash text eol=lf
13
+ *.zsh text eol=lf
14
+ Dockerfile text eol=lf
15
+ *.yml text eol=lf
16
+ *.yaml text eol=lf
17
+ *.json text eol=lf
18
+ *.md text eol=lf
19
+ *.xml text eol=lf
20
+ *.properties text eol=lf
21
+
22
+ # Windows 专用脚本保留 CRLF
23
+ *.bat text eol=crlf
24
+ *.cmd text eol=crlf
25
+ *.ps1 text eol=crlf
26
+
27
+ # 二进制文件声明
28
+ *.png binary
29
+ *.jpg binary
30
+ *.jpeg binary
31
+ *.gif binary
32
+ *.ico binary
33
+ *.zip binary
34
+ *.tar.gz binary
35
+ *.jar binary
36
+ *.war binary
37
+ *.exe binary
@@ -0,0 +1,65 @@
1
+ #!/usr/bin/env bash
2
+ # ==============================================================================
3
+ # Conventional Commits 本地提交通用规范校验钩子
4
+ #
5
+ # 在本地提交阶段自动校验提交说明首行格式,智能放行 Merge、Revert 与临时变基提交,
6
+ # 格式不合规时进行拦截并输出友好诊断指引与交互向导建议。
7
+ #
8
+ # @author Ateng
9
+ # @since 2026-10-09
10
+ # ==============================================================================
11
+
12
+ set -eo pipefail
13
+
14
+ MSG_FILE="$1"
15
+
16
+ if [ ! -f "$MSG_FILE" ]; then
17
+ exit 0
18
+ fi
19
+
20
+ # 提取第一行非注释内容并去除首尾空白
21
+ FIRST_LINE=$(grep -v '^#' "$MSG_FILE" | head -n 1 | tr -d '\r' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
22
+
23
+ # 若内容为空,交由 Git 原生逻辑拦截
24
+ if [ -z "$FIRST_LINE" ]; then
25
+ exit 0
26
+ fi
27
+
28
+ # 1. 自动放行机制 (Merge, Revert, 临时变基)
29
+ if echo "$FIRST_LINE" | grep -Eq '^(Merge (branch|tag|remote-tracking branch|pull request)|Revert |(fixup|squash)!)'; then
30
+ exit 0
31
+ fi
32
+
33
+ # 2. Conventional Commits 正则校验
34
+ # 格式: <type>(<scope>)<!>: <subject>
35
+ CONVENTIONAL_REGEX="^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-zA-Z0-9._-]+\))?!?: .+$"
36
+
37
+ if ! echo "$FIRST_LINE" | grep -Eq "$CONVENTIONAL_REGEX"; then
38
+ # 终端色彩适配
39
+ if [ -t 1 ]; then
40
+ COLOR_RESET="\033[0m"
41
+ COLOR_BOLD="\033[1m"
42
+ COLOR_RED="\033[31m"
43
+ COLOR_YELLOW="\033[33m"
44
+ COLOR_CYAN="\033[36m"
45
+ else
46
+ COLOR_RESET=""
47
+ COLOR_BOLD=""
48
+ COLOR_RED=""
49
+ COLOR_YELLOW=""
50
+ COLOR_CYAN=""
51
+ fi
52
+
53
+ printf "\n%b[ERROR] 提交信息不符合 Conventional Commits 规范!%b\n" "${COLOR_RED}" "${COLOR_RESET}"
54
+ printf "当前提交信息: %b\"%s\"%b\n\n" "${COLOR_BOLD}" "$FIRST_LINE" "${COLOR_RESET}"
55
+ printf "%b规范格式:%b <type>(<scope>): <subject>\n" "${COLOR_YELLOW}" "${COLOR_RESET}"
56
+ printf "%b支持类型:%b feat | fix | docs | style | refactor | perf | test | build | ci | chore | revert\n" "${COLOR_YELLOW}" "${COLOR_RESET}"
57
+ printf "%b参考示例:%b\n" "${COLOR_YELLOW}" "${COLOR_RESET}"
58
+ printf " feat: 支持用户登录授权\n"
59
+ printf " fix(parser): 修复空字符串解析异常\n"
60
+ printf " docs: 完善项目接入文档\n\n"
61
+ printf "💡 %b建议直接运行交互式向导快速提交:%b %bbash scripts/commit.sh%b\n\n" "${COLOR_CYAN}" "${COLOR_RESET}" "${COLOR_BOLD}" "${COLOR_RESET}"
62
+ exit 1
63
+ fi
64
+
65
+ exit 0
@@ -0,0 +1,12 @@
1
+ # ==============================================================================
2
+ # GitHub 代码属主与审阅者自动指派配置 (Code Owners)
3
+ # 详见: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
4
+ # ==============================================================================
5
+
6
+ # 全局默认所有者(通配所有未被下级路径覆盖的文件)
7
+ * @atengk
8
+
9
+ # 核心基础设施与自动化流水线重点守护
10
+ /.github/ @atengk
11
+ /scripts/ @atengk
12
+ /.githooks/ @atengk
@@ -0,0 +1,29 @@
1
+ ---
2
+ name: "Bug 报告"
3
+ about: 报告项目中出现的错误或异常行为
4
+ title: "fix: [简要描述该问题]"
5
+ labels: ["bug"]
6
+ assignees: ""
7
+ ---
8
+
9
+ ### 缺陷描述
10
+ <!-- 清晰且简要地描述该问题是什么 -->
11
+
12
+ ### 重现步骤
13
+ 1. 执行操作 '...'
14
+ 2. 传入参数 '...'
15
+ 3. 观察到报错 '...'
16
+
17
+ ### 期望结果
18
+ <!-- 描述你期望发生的正常行为 -->
19
+
20
+ ### 实际结果与日志
21
+ <!-- 贴出完整的报错堆栈、控制台输出或截图 -->
22
+ ```text
23
+
24
+ ```
25
+
26
+ ### 环境信息
27
+ - **操作系统**: [例如 Windows 11, macOS 14, Ubuntu 22.04]
28
+ - **运行环境/版本**: [例如 JDK 21, Node 20, Python 3.11, Go 1.22]
29
+ - **项目版本**: [例如 v1.0.0 或 git commit hash]
@@ -0,0 +1,16 @@
1
+ # ==============================================================================
2
+ # GitHub Issues 治理配置
3
+ # 详见: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository
4
+ # ==============================================================================
5
+
6
+ # 关闭无模板空白 Issue 入口,防止无效提交
7
+ blank_issues_enabled: false
8
+
9
+ # 导流外链:引导用户提问或查阅文档
10
+ contact_links:
11
+ - name: 💬 社区技术答疑与使用交流 (GitHub Discussions)
12
+ url: https://github.com/atengk/mcp-server-rag/discussions
13
+ about: 请在此讨论配置用法、提问咨询或分享实践,避免占用 Issue 跟踪。
14
+ - name: 📖 项目官方主页与文档 (Documentation)
15
+ url: https://github.com/atengk/mcp-server-rag#readme
16
+ about: 查阅快速开始指南、MCP 客户端接入配置及功能说明。
@@ -0,0 +1,19 @@
1
+ ---
2
+ name: "需求与特性建议"
3
+ about: 为项目提出新功能建议或设计优化方案
4
+ title: "feat: [简要描述新特性]"
5
+ labels: ["enhancement"]
6
+ assignees: ""
7
+ ---
8
+
9
+ ### 需求背景与痛点
10
+ <!-- 描述当前使用场景遇到的阻碍或不便:为什么需要这个新特性? -->
11
+
12
+ ### 建议的解决方案
13
+ <!-- 清晰且详细地描述你建议的实现方式、API 设计或功能形态 -->
14
+
15
+ ### 替代方案或权衡考虑
16
+ <!-- 是否尝试过或考虑过其他替代做法? -->
17
+
18
+ ### 补充上下文
19
+ <!-- 如有相关截图、参考资料或链接,请在此提供 -->
@@ -0,0 +1,25 @@
1
+ ## 变更说明
2
+ <!-- 请简要说明此 PR 解决的问题或新增的能力 -->
3
+
4
+ ## 关联 Issue
5
+ - 修复/关联: close #
6
+
7
+ ## 变更类型
8
+ <!-- 请在符合项的括号内填入 x,例如 [x](与 CI Conventional Commits 门禁规范严格保持一致) -->
9
+ - [ ] `feat`: 新增功能
10
+ - [ ] `fix`: 缺陷修复
11
+ - [ ] `docs`: 文档变动
12
+ - [ ] `style`: 代码格式调整(不影响业务逻辑)
13
+ - [ ] `refactor`: 代码重构(非新功能、非修复)
14
+ - [ ] `perf`: 性能优化
15
+ - [ ] `test`: 补全或重构测试
16
+ - [ ] `build`: 构建系统或外部依赖变动
17
+ - [ ] `ci`: CI/CD 自动化流水线变动
18
+ - [ ] `chore`: 其他常规维护与辅助工具变动
19
+ - [ ] `revert`: 撤销/恢复先前的提交
20
+
21
+ ## 自检清单
22
+ - [ ] 提交信息符合 [Conventional Commits](https://www.conventionalcommits.org/zh-hans/) 规范
23
+ - [ ] 本地已通过全部已有测试及代码检查
24
+ - [ ] 如有新增/修改功能,已补充对应测试用例
25
+ - [ ] 如涉及 API 或配置变更,已同步更新相关文档
@@ -0,0 +1,62 @@
1
+ # ==============================================================================
2
+ # Dependabot 依赖自动化更新配置 (Dependabot Version Updates)
3
+ #
4
+ # 💡 机制说明:
5
+ # 1. 本配置负责常规月度依赖升级(Version Updates),采用语义化双轨模型聚合 PR;
6
+ # 2. 针对高危 CVE 漏洞的即时修复(Dependabot Security Updates)由 GitHub 平台原生实时守护,两者互补。
7
+ # 详见: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates
8
+ # ==============================================================================
9
+
10
+ version: 2
11
+ updates:
12
+ # 持续监控 GitHub Actions 工作流版本更新
13
+ - package-ecosystem: "github-actions"
14
+ directory: "/"
15
+ schedule:
16
+ interval: "monthly"
17
+ open-pull-requests-limit: 5
18
+ commit-message:
19
+ prefix: "ci"
20
+ include: "scope"
21
+ labels:
22
+ - "dependencies"
23
+ groups:
24
+ # 语义化双轨模型:将所有 Actions 的 Minor 与 Patch 补丁打包为单一 PR,杜绝通知轰炸;
25
+ # 遇到 Major 重大版本跳跃(如 v4 -> v7)自动单列独立 PR,便于审查破坏性更新与定位问题。
26
+ actions:
27
+ patterns:
28
+ - "*"
29
+ update-types:
30
+ - "minor"
31
+ - "patch"
32
+
33
+ # --- [Python / pip 生态] ---
34
+ - package-ecosystem: "pip"
35
+ directory: "/"
36
+ schedule:
37
+ interval: "monthly"
38
+ open-pull-requests-limit: 5
39
+ commit-message:
40
+ prefix: "build"
41
+ include: "scope"
42
+ labels:
43
+ - "dependencies"
44
+ groups:
45
+ dependencies:
46
+ patterns:
47
+ - "*"
48
+ update-types:
49
+ - "minor"
50
+ - "patch"
51
+
52
+ # --- [Docker 容器镜像生态] ---
53
+ - package-ecosystem: "docker"
54
+ directory: "/"
55
+ schedule:
56
+ interval: "monthly"
57
+ open-pull-requests-limit: 3
58
+ commit-message:
59
+ prefix: "build"
60
+ include: "scope"
61
+ labels:
62
+ - "dependencies"
@@ -0,0 +1,211 @@
1
+ # ==============================================================================
2
+ # 工作流模版:Python 持续集成流水线 (Python CI)
3
+ # 适用场景:Python 模块、开源类库、FastAPI / Django / Flask Web 应用与 MCP Server 的 PR 门禁
4
+ # 触发条件:
5
+ # - push: 主干分支 (main, master) 代码推送
6
+ # - pull_request: 针对主干分支的 PR 创建、编辑、代码同步
7
+ # 核心特性:
8
+ # - 动态并发控制 (Dynamic Concurrency):PR 提交自动中断陈旧运行,主干提交按序排队
9
+ # - 内部路径短路直通 (Path Fast-Pass):纯文档改动秒级放行,彻底消除分支保护规则死锁
10
+ # - 分层兼容性矩阵 (Matrix Strategy):PR 快速验证核心版本,主干全量扫描跨版本兼容性
11
+ # - 超高速现代静态分析工具 Ruff (代码规范 check 与格式化 format)
12
+ # - 终审门禁看板 (All Checks Passed):统一盖戳并直出 GitHub Step Summary 结构化报表
13
+ # ==============================================================================
14
+
15
+ name: Python CI
16
+
17
+ on:
18
+ push:
19
+ branches: [main, master]
20
+ pull_request:
21
+ branches: [main, master]
22
+ types: [opened, edited, synchronize, reopened]
23
+
24
+ # 动态并发控制:PR 提交自动取消陈旧构建以节约算力;主干提交排队顺序执行保历史完整
25
+ concurrency:
26
+ group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
27
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
28
+
29
+ permissions:
30
+ contents: read
31
+
32
+ jobs:
33
+ # ----------------------------------------------------------------------------
34
+ # Job 1: PR 标题规范校验 (仅在 PR 触发时执行)
35
+ # ----------------------------------------------------------------------------
36
+ validate-pr-title:
37
+ name: 校验 PR 标题规范
38
+ runs-on: ubuntu-latest
39
+ if: github.event_name == 'pull_request'
40
+ timeout-minutes: 5
41
+ permissions:
42
+ pull-requests: read
43
+ steps:
44
+ - name: 校验 PR 标题符合 Conventional Commits
45
+ uses: amannn/action-semantic-pull-request@v6
46
+ env:
47
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
48
+ with:
49
+ types: |
50
+ feat
51
+ fix
52
+ docs
53
+ style
54
+ refactor
55
+ perf
56
+ test
57
+ build
58
+ ci
59
+ chore
60
+ revert
61
+
62
+ # ----------------------------------------------------------------------------
63
+ # Job 2: 动态探测变更路径 (实现内部短路直通网关)
64
+ # ----------------------------------------------------------------------------
65
+ detect-changes:
66
+ name: 探测变更路径
67
+ runs-on: ubuntu-latest
68
+ timeout-minutes: 5
69
+ outputs:
70
+ code_changed: ${{ steps.filter.outputs.code }}
71
+ steps:
72
+ - name: 检出源码
73
+ uses: actions/checkout@v7
74
+
75
+ - name: 分析改动文件类型
76
+ uses: dorny/paths-filter@v4
77
+ id: filter
78
+ with:
79
+ filters: |
80
+ code:
81
+ - '!(*.md|docs/**|.gitignore|.editorconfig|LICENSE)'
82
+
83
+ # ----------------------------------------------------------------------------
84
+ # Job 3: 代码风格与规范静态分析 (Ruff)
85
+ # ----------------------------------------------------------------------------
86
+ lint:
87
+ name: 代码规范与格式化 (Ruff)
88
+ runs-on: ubuntu-latest
89
+ needs: [detect-changes]
90
+ if: needs.detect-changes.outputs.code_changed != 'false'
91
+ timeout-minutes: 10
92
+ steps:
93
+ - name: 检出源码
94
+ uses: actions/checkout@v7
95
+
96
+ - name: 设置 Python 环境
97
+ uses: actions/setup-python@v7
98
+ with:
99
+ python-version: '3.12'
100
+ cache: 'pip'
101
+
102
+ - name: 安装 Ruff 静态检查工具
103
+ run: pip install ruff
104
+
105
+ - name: 代码风格与语法检查 (Ruff Linter & Formatter)
106
+ run: |
107
+ ruff check .
108
+ ruff format --check .
109
+
110
+ # ----------------------------------------------------------------------------
111
+ # Job 4: 跨版本兼容性单元测试矩阵 (pytest)
112
+ # ----------------------------------------------------------------------------
113
+ test:
114
+ name: 自动化测试 (Python ${{ matrix.python-version }})
115
+ runs-on: ubuntu-latest
116
+ needs: [detect-changes]
117
+ if: needs.detect-changes.outputs.code_changed != 'false'
118
+ timeout-minutes: 15
119
+ strategy:
120
+ fail-fast: ${{ github.event_name == 'pull_request' }}
121
+ matrix:
122
+ # 分层矩阵策略:PR 仅测 3.12 极速反馈;主干推送执行多版本跨兼容性全量验证
123
+ python-version: ${{ github.event_name == 'pull_request' && fromJSON('["3.12"]') || fromJSON('["3.10", "3.11", "3.12"]') }}
124
+
125
+ steps:
126
+ - name: 检出源码
127
+ uses: actions/checkout@v7
128
+
129
+ - name: 设置 Python 环境
130
+ uses: actions/setup-python@v7
131
+ with:
132
+ python-version: ${{ matrix.python-version }}
133
+ cache: 'pip'
134
+
135
+ - name: 安装项目依赖与测试框架
136
+ run: |
137
+ python -m pip install --upgrade pip
138
+ pip install pytest pytest-cov
139
+ if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
140
+ if [ -f pyproject.toml ]; then pip install .; fi
141
+
142
+ - name: 运行 pytest 单元测试
143
+ run: |
144
+ if find tests -name "test_*.py" -o -name "*_test.py" 2>/dev/null | grep -q .; then
145
+ pytest --cov
146
+ else
147
+ echo "暂未发现测试用例文件,跳过测试执行。"
148
+ fi
149
+
150
+ # ----------------------------------------------------------------------------
151
+ # Job 5: 质量门禁终审盖戳 (分支保护规则唯一指定强绑门禁)
152
+ # ----------------------------------------------------------------------------
153
+ all-checks-passed:
154
+ name: 质量门禁终审 (All Checks Passed)
155
+ runs-on: ubuntu-latest
156
+ needs: [detect-changes, validate-pr-title, lint, test]
157
+ if: always()
158
+ timeout-minutes: 5
159
+ steps:
160
+ - name: 汇总校验各任务执行结果
161
+ run: |
162
+ TITLE_RESULT="${{ needs.validate-pr-title.result }}"
163
+ DETECT_RESULT="${{ needs.detect-changes.result }}"
164
+ LINT_RESULT="${{ needs.lint.result }}"
165
+ TEST_RESULT="${{ needs.test.result }}"
166
+
167
+ echo "任务状态汇总: PR标题=[$TITLE_RESULT], 变更探测=[$DETECT_RESULT], 规范扫描=[$LINT_RESULT], 单测矩阵=[$TEST_RESULT]"
168
+
169
+ if [ "$TITLE_RESULT" = "failure" ] || [ "$TITLE_RESULT" = "cancelled" ]; then
170
+ echo "::error::PR 标题规范校验失败!请按照 Conventional Commits 规范修改 PR 标题。"
171
+ exit 1
172
+ fi
173
+
174
+ if [ "$DETECT_RESULT" = "failure" ] || [ "$DETECT_RESULT" = "cancelled" ]; then
175
+ echo "::error::变更路径探测任务异常中断!"
176
+ exit 1
177
+ fi
178
+
179
+ if [ "$LINT_RESULT" = "failure" ] || [ "$LINT_RESULT" = "cancelled" ]; then
180
+ echo "::error::Ruff 代码规范与格式化扫描失败!"
181
+ exit 1
182
+ fi
183
+
184
+ if [ "$TEST_RESULT" = "failure" ] || [ "$TEST_RESULT" = "cancelled" ]; then
185
+ echo "::error::pytest 兼容性单元测试失败!门禁熔断阻断。"
186
+ exit 1
187
+ fi
188
+
189
+ echo "✅ 全部必要质量门禁已全部通过!"
190
+
191
+ - name: 生成门禁看板摘要报告
192
+ if: always()
193
+ run: |
194
+ {
195
+ echo "## 🚦 Python CI 质量门禁终审报告"
196
+ echo ""
197
+ echo "| 检查项 | 判定状态 | 执行说明 |"
198
+ echo "| :--- | :---: | :--- |"
199
+ if [ "${{ github.event_name }}" = "pull_request" ]; then
200
+ echo "| **PR 标题规范校验** | ${{ needs.validate-pr-title.result == 'success' && '✅ 通过' || '❌ 失败' }} | Conventional Commits 语义化规范 |"
201
+ fi
202
+ echo "| **变更路径探测** | ${{ needs.detect-changes.result == 'success' && '✅ 通过' || '❌ 异常' }} | 区分文档短路与核心代码构建 |"
203
+ if [ "${{ needs.detect-changes.outputs.code_changed }}" = "false" ]; then
204
+ echo "| **代码规范与测试** | ⚡ 短路直通 | 仅涉及文档改动,自动跳过耗时测试并放行 |"
205
+ else
206
+ echo "| **Ruff 代码规范扫描** | ${{ needs.lint.result == 'success' && '✅ 通过' || '❌ 失败' }} | 静态语法风格与自动格式化校验 |"
207
+ echo "| **pytest 兼容性测试** | ${{ needs.test.result == 'success' && '✅ 通过' || '❌ 失败' }} | 分层多版本兼容性矩阵验证 |"
208
+ fi
209
+ echo ""
210
+ echo "> 💡 **分支保护规则建议**:请在 GitHub 仓库设置中将 \`质量门禁终审 (All Checks Passed)\` 设为唯一 Required Status Check。"
211
+ } >> "$GITHUB_STEP_SUMMARY"