common-core 0.1.0__tar.gz

common_core-0.1.0/.env.example

@@ -0,0 +1,77 @@
+# common_core canonical config example.
+# This is the shared contract' single source for key naming. Real secrets
+# live in each skill's own .env (or process env) and must not be committed.
+# Copy keys you need into a skill-specific .env; never load this file directly.
+
+# --- LLM (OpenAI-compatible) ---  type=str required
+LLM_BASE_URL=https://api.deepseek.com/v1
+LLM_API_KEY=replace-me
+LLM_MODEL=deepseek-chat
+LLM_TEMPERATURE=0
+LLM_MAX_TOKENS=2048
+LLM_TIMEOUT_SECONDS=30
+
+# --- Embedding (global key, not LLM_ prefixed) ---  type=str required-for-dense
+EMBEDDING_MODEL=BAAI/bge-small-zh-v1.5
+
+# --- Milvus ---  type=str/int required-host+collection
+MILVUS_HOST=127.0.0.1
+MILVUS_PORT=19530
+MILVUS_USER=
+MILVUS_PASSWORD=
+MILVUS_SECURE=false
+MILVUS_DB=
+MILVUS_TEXT_COLLECTION=knowledge_kb
+MILVUS_IMAGE_COLLECTION=
+MILVUS_DIM=0
+MILVUS_OUTPUT_FIELDS=id,content,source
+
+# --- Redis ---  type=str/int
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_PASSWORD=
+REDIS_DB=0
+REDIS_DEFAULT_TTL=1800
+REDIS_KEY_PREFIX=rag
+REDIS_SOCKET_TIMEOUT=3
+
+# --- Auth ---  type=str mode=jwt|disabled
+AUTH_MODE=jwt
+AUTH_JWT_SECRET=
+AUTH_JWT_PUBLIC_KEY=
+# 与 AUTH_JWT_SECRET / AUTH_JWT_PUBLIC_KEY 三选一；
+# 若同时配置，静态密钥优先于 JWKS，轮换时应移除静态键。
+AUTH_JWT_ALGORITHMS=HS256
+AUTH_JWT_ISSUER=
+AUTH_JWT_AUDIENCE=
+# 企业 IdP 的 JWKS 端点；配置后按 LIFESPAN 缓存公钥，
+# 遇到未知 kid 自动刷新，签名密钥轮换无需重启服务。
+AUTH_JWKS_URL=
+AUTH_JWKS_LIFESPAN=300
+AUTH_JWKS_TIMEOUT=30
+AUTH_MCP_ISSUER_URL=
+AUTH_MCP_RESOURCE_SERVER_URL=
+
+# --- Metrics ---  type=bool/int/str
+METRICS_ENABLED=false
+METRICS_PREFIX=app
+METRICS_PORT=9090
+METRICS_BIND=127.0.0.1
+
+# --- Retrieval ---  type=int/float
+RETRIEVAL_TOP_K=20
+RETRIEVAL_MIN_RELEVANCE=0.70
+RETRIEVAL_HYBRID_WORKERS=16
+RRF_TOP_K=20
+RRF_K=60
+RERANK_TOP_K=3
+
+# --- Query rewrite ---  type=str mode=off|identity|llm_rewrite|query_expansion
+RETRIEVAL_QUERY_REWRITE_MODE=off
+RETRIEVAL_QUERY_REWRITE_LLM_MODEL=
+RETRIEVAL_QUERY_REWRITE_TEMPERATURE=0
+RETRIEVAL_QUERY_REWRITE_MAX_TOKENS=256
+RETRIEVAL_QUERY_REWRITE_EXPAND_COUNT=2
+RETRIEVAL_QUERY_REWRITE_PROMPT=
+RETRIEVAL_QUERY_REWRITE_EXPANSION_PROMPT=
+RETRIEVAL_QUERY_REWRITE_SCOPES=

common_core-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with test dependencies
+        run: pip install -e ".[test]"
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short

common_core-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: python -m twine upload dist/*

common_core-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# IDE / editor local config
+.idea/
+.vscode/
+*.iml
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Environment files / secrets
+.env
+.env.*
+!.env.example
+
+# Misc
+.DS_Store

common_core-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.5
+Name: common-core
+Version: 0.1.0
+Summary: Shared runtime for AI skills: context, config, auth, observability, provider contracts.
+Requires-Python: >=3.11
+Requires-Dist: prometheus-client>=0.20
+Requires-Dist: pyjwt[crypto]>=2.8
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: cache
+Requires-Dist: redis>=5.2; extra == 'cache'
+Provides-Extra: llm
+Requires-Dist: openai>=1.60; extra == 'llm'
+Requires-Dist: sentence-transformers>=3.3; extra == 'llm'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Provides-Extra: vector
+Requires-Dist: pymilvus>=2.5; extra == 'vector'

common_core-0.1.0/docs/config.md

@@ -0,0 +1,110 @@
+# common_core 配置契约
+
+这是所有 AI skill 配置的**唯一契约入口**。契约约束键名、类型、必填/可选与敏感标记；真实值只存在于各 skill 的 `.env` 或进程环境，绝不进入本库或仓库。
+
+## 加载顺序
+
+配置来源优先级从高到低固定为：
+
+1. 系统环境变量（`os.environ`）
+2. 当前 skill 部署目录的 `.env`
+3. 代码中的默认值
+
+只由可执行入口（各 skill 的 `main()`）显式加载 `.env`（`override=False`），`common_core` 不主动读取自身安装目录下的 `.env`。每个 MCP 进程只加载一份 env 源；同名键（如 `LLM_MODEL`）在不同 skill 进程里允许不同值，互不冲突。
+
+## 完整键表
+
+标记说明：`必填` 列里的 `*` 表示所有 skill 都要；`rag`/`sql` 表示仅该 skill 要求。`敏感` 列标记为 `是` 的键必须脱敏，且 `.env.example` 只允许出现占位符。
+
+| 键 | 类型 | 默认值 | 必填 | 敏感 |
+| --- | --- | --- | --- | --- |
+| `LLM_BASE_URL` | str | `""` | `*` | 否 |
+| `LLM_API_KEY` | str | `""` | `*` | 是 |
+| `LLM_MODEL` | str | `""` | `*` | 否 |
+| `LLM_TEMPERATURE` | float | `0.0` | 可选 | 否 |
+| `LLM_MAX_TOKENS` | int | `2048` | 可选 | 否 |
+| `LLM_TIMEOUT_SECONDS` | float | `30.0` | 可选 | 否 |
+| `EMBEDDING_MODEL` | str | `""` | `rag` | 否 |
+| `MILVUS_HOST` | str | `localhost` | `rag` | 否 |
+| `MILVUS_PORT` | int | `19530` | 可选 | 否 |
+| `MILVUS_USER` | str | `""` | 可选 | 否 |
+| `MILVUS_PASSWORD` | str | `""` | 可选 | 是 |
+| `MILVUS_SECURE` | bool | `false` | 可选 | 否 |
+| `MILVUS_DB` | str | `""` | 可选 | 否 |
+| `MILVUS_TEXT_COLLECTION` | str | `""` | `rag` | 否 |
+| `MILVUS_IMAGE_COLLECTION` | str | `""` | 可选 | 否 |
+| `MILVUS_DIM` | int | `0` | 可选 | 否 |
+| `MILVUS_OUTPUT_FIELDS` | csv | `[]` | 可选 | 否 |
+| `REDIS_HOST` | str | `localhost` | `rag` | 否 |
+| `REDIS_PORT` | int | `6379` | 可选 | 否 |
+| `REDIS_PASSWORD` | str | `""` | 可选 | 是 |
+| `REDIS_DB` | int | `0` | 可选 | 否 |
+| `REDIS_DEFAULT_TTL` | int | `1800` | 可选 | 否 |
+| `REDIS_KEY_PREFIX` | str | `rag` | 可选 | 否 |
+| `REDIS_SOCKET_TIMEOUT` | float | `3.0` | 可选 | 否 |
+| `AUTH_MODE` | enum | `jwt` | `*` | 否 |
+| `AUTH_JWT_SECRET` | str | `""` | `*`（jwt 三选一） | 是 |
+| `AUTH_JWT_PUBLIC_KEY` | str | `""` | `*`（jwt 三选一） | 是 |
+| `AUTH_JWT_ALGORITHMS` | csv | `HS256`（配置 JWKS 时默认 `RS256/ES256`） | 可选 | 否 |
+| `AUTH_JWT_ISSUER` | str | `""` | 可选 | 否 |
+| `AUTH_JWT_AUDIENCE` | str | `""` | 可选 | 否 |
+| `AUTH_JWKS_URL` | str | `""` | `*`（jwt 三选一） | 否 |
+| `AUTH_JWKS_LIFESPAN` | float | `300` | 可选 | 否 |
+| `AUTH_JWKS_TIMEOUT` | float | `30` | 可选 | 否 |
+| `AUTH_MCP_ISSUER_URL` | str | `""` | 可选 | 否 |
+| `AUTH_MCP_RESOURCE_SERVER_URL` | str | `""` | 可选 | 否 |
+| `METRICS_ENABLED` | bool | `false` | 可选 | 否 |
+| `METRICS_PREFIX` | str | `app` | 可选 | 否 |
+| `METRICS_PORT` | int | `9090` | 可选 | 否 |
+| `METRICS_BIND` | str | `127.0.0.1` | 可选 | 否 |
+| `RETRIEVAL_TOP_K` | int | `20` | 可选 | 否 |
+| `RETRIEVAL_MIN_RELEVANCE` | float | `0.70` | 可选 | 否 |
+| `RETRIEVAL_HYBRID_WORKERS` | int | `16` | 可选 | 否 |
+| `RETRIEVAL_ASSEMBLY_MAX_CHARS` | int | `8000` | 可选 | 否 |
+| `RRF_TOP_K` | int | `20` | 可选 | 否 |
+| `RRF_K` | int | `60` | 可选 | 否 |
+| `RERANK_TOP_K` | int | `3` | 可选 | 否 |
+| `RETRIEVAL_QUERY_REWRITE_MODE` | enum | `off` | 可选 | 否 |
+| `RETRIEVAL_QUERY_REWRITE_LLM_MODEL` | str | `""` | 可选 | 否 |
+| `RETRIEVAL_QUERY_REWRITE_TEMPERATURE` | float | `0.0` | 可选 | 否 |
+| `RETRIEVAL_QUERY_REWRITE_MAX_TOKENS` | int | `256` | 可选 | 否 |
+| `RETRIEVAL_QUERY_REWRITE_EXPAND_COUNT` | int | `2` | 可选 | 否 |
+| `RETRIEVAL_QUERY_REWRITE_PROMPT` | str | `""` | 可选 | 否 |
+| `RETRIEVAL_QUERY_REWRITE_EXPANSION_PROMPT` | str | `""` | 可选 | 否 |
+| `RETRIEVAL_QUERY_REWRITE_SCOPES` | str | `""` | 可选 | 否 |
+| `RERANKER_MODEL` | str | `BAAI/bge-reranker-base` | `rag` | 否 |
+| `RERANKER_DEVICE` | str | `""` | 可选 | 否 |
+| `RERANKER_CE_WEIGHT` | float | `0.6` | 可选 | 否 |
+| `RERANKER_RETRIEVAL_WEIGHT` | float | `0.4` | 可选 | 否 |
+| `SQL_HOST` | str | `localhost` | `sql` | 否 |
+| `SQL_PORT` | int | `3306` | 可选 | 否 |
+| `SQL_USER` | str | `""` | `sql` | 否 |
+| `SQL_PASSWORD` | str | `""` | `sql` | 是 |
+| `SQL_DATABASE` | str | `""` | `sql` | 否 |
+| `SQL_CHARSET` | str | `utf8mb4` | 可选 | 否 |
+| `SQL_CONNECT_TIMEOUT` | float | `3.0` | 可选 | 否 |
+| `SQL_READ_TIMEOUT` | float | `5.0` | 可选 | 否 |
+| `SQL_POOL_MAX_CONNECTIONS` | int | `10` | 可选 | 否 |
+| `SQL_POOL_MIN_CACHED` | int | `2` | 可选 | 否 |
+| `SQL_POOL_MAX_CACHED` | int | `5` | 可选 | 否 |
+| `SQL_POOL_BLOCKING` | bool | `true` | 可选 | 否 |
+| `SQL_DEFAULT_MAX_ROWS` | int | `20` | 可选 | 否 |
+
+## 校验规则
+
+- `RuntimeConfig.validate()` 启动时 fail-fast，缺任一必填键抛 `ConfigError`，附带完整缺失键清单。
+- `AUTH_MODE` 只允许 `jwt` / `disabled`；`jwt` 模式必须提供
+  `AUTH_JWT_SECRET`、`AUTH_JWT_PUBLIC_KEY`、`AUTH_JWKS_URL` 三者之一。
+- 配置 `AUTH_JWKS_URL` 后，`AUTH_JWKS_LIFESPAN` 必须大于 0；
+  不显式声明 `AUTH_JWT_ALGORITHMS` 时默认启用 `RS256` / `ES256`。
+- 静态密钥优先于 JWKS：同时配置 `AUTH_JWT_SECRET` / `AUTH_JWT_PUBLIC_KEY`
+  与 `AUTH_JWKS_URL` 时仍走静态密钥路径，做轮换迁移时请移除静态键。
+- 其余读取失败（整数、布尔解析失败）回退默认值，不中断启动。
+
+## 一致性
+
+CI 用 `common_core/scripts/check_env_examples.py` 对比每个 skill 的 `.env.example` 与上表：缺必填键、出现未声明键、或敏感键写成真实值即失败。修改键名/必填/敏感属性时，必须同步 `config.py`、`config.md` 与该脚本。
+
+## 环境文件解析
+
+`resolve_env_file()` 按“显式 `--env-file` 参数 > `*_ENV_FILE` 环境变量 > 当前目录 `.env`”解析，交给 `load_env_files()`（`override=False`）。启动日志会打印配置来源与脱敏配置指纹（见 `config_fingerprint()` / `log_config_audit()`）。

common_core-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "common-core"
+version = "0.1.0"
+description = "Shared runtime for AI skills: context, config, auth, observability, provider contracts."
+requires-python = ">=3.11"
+dependencies = [
+  "prometheus-client>=0.20",
+  "PyJWT[crypto]>=2.8",
+  "python-dotenv>=1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/common_core"]
+
+[project.optional-dependencies]
+llm = ["openai>=1.60", "sentence-transformers>=3.3"]
+vector = ["pymilvus>=2.5"]
+cache = ["redis>=5.2"]
+mcp = ["mcp>=1.2"]
+test = ["pytest>=8.0"]

common_core-0.1.0/scripts/check_env_examples.py

@@ -0,0 +1,155 @@
+"""CI guard: keep every skill ``.env.example`` aligned with the config contract.
+
+The contract is defined here (Key name, required for which skill, sensitive,
+expected type). It is the single source the examples and ``config.md`` must
+agree with. Running this in CI fails the build when an example:
+
+- omits a required shared key,
+- declares an unknown key (typo / drift from the contract), or
+- ships a real-looking secret instead of a placeholder.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+# Canonical contract. Keys used by skills beyond the common shared set are
+# listed as optional so they are still spell-checked.
+CONTRACT: dict[str, dict[str, str]] = {
+    # (required-for, sensitive, type)
+    "LLM_BASE_URL": {"required": {"common_core", "retrieve_skill"}, "sensitive": False, "type": "str"},
+    "LLM_API_KEY": {"required": {"common_core", "retrieve_skill"}, "sensitive": True, "type": "str"},
+    "LLM_MODEL": {"required": {"common_core", "retrieve_skill"}, "sensitive": False, "type": "str"},
+    "LLM_TEMPERATURE": {"required": set(), "sensitive": False, "type": "float"},
+    "LLM_MAX_TOKENS": {"required": set(), "sensitive": False, "type": "int"},
+    "LLM_TIMEOUT_SECONDS": {"required": set(), "sensitive": False, "type": "float"},
+    "EMBEDDING_MODEL": {"required": {"retrieve_skill"}, "sensitive": False, "type": "str"},
+    "MILVUS_HOST": {"required": {"retrieve_skill"}, "sensitive": False, "type": "str"},
+    "MILVUS_PORT": {"required": set(), "sensitive": False, "type": "int"},
+    "MILVUS_USER": {"required": set(), "sensitive": False, "type": "str"},
+    "MILVUS_PASSWORD": {"required": set(), "sensitive": True, "type": "str"},
+    "MILVUS_SECURE": {"required": set(), "sensitive": False, "type": "bool"},
+    "MILVUS_DB": {"required": set(), "sensitive": False, "type": "str"},
+    "MILVUS_TEXT_COLLECTION": {"required": {"retrieve_skill"}, "sensitive": False, "type": "str"},
+    "MILVUS_IMAGE_COLLECTION": {"required": set(), "sensitive": False, "type": "str"},
+    "MILVUS_DIM": {"required": set(), "sensitive": False, "type": "int"},
+    "MILVUS_OUTPUT_FIELDS": {"required": set(), "sensitive": False, "type": "csv"},
+    "REDIS_HOST": {"required": {"retrieve_skill"}, "sensitive": False, "type": "str"},
+    "REDIS_PORT": {"required": set(), "sensitive": False, "type": "int"},
+    "REDIS_PASSWORD": {"required": set(), "sensitive": True, "type": "str"},
+    "REDIS_DB": {"required": set(), "sensitive": False, "type": "int"},
+    "REDIS_DEFAULT_TTL": {"required": set(), "sensitive": False, "type": "int"},
+    "REDIS_KEY_PREFIX": {"required": set(), "sensitive": False, "type": "str"},
+    "REDIS_SOCKET_TIMEOUT": {"required": set(), "sensitive": False, "type": "float"},
+    "AUTH_MODE": {"required": {"common_core", "retrieve_skill"}, "sensitive": False, "type": "enum"},
+    "AUTH_JWT_SECRET": {"required": set(), "sensitive": True, "type": "str"},
+    "AUTH_JWT_PUBLIC_KEY": {"required": set(), "sensitive": True, "type": "str"},
+    "AUTH_JWT_ALGORITHMS": {"required": set(), "sensitive": False, "type": "csv"},
+    "AUTH_JWT_ISSUER": {"required": set(), "sensitive": False, "type": "str"},
+    "AUTH_JWT_AUDIENCE": {"required": set(), "sensitive": False, "type": "str"},
+    "AUTH_JWKS_URL": {"required": set(), "sensitive": False, "type": "str"},
+    "AUTH_JWKS_LIFESPAN": {"required": set(), "sensitive": False, "type": "float"},
+    "AUTH_JWKS_TIMEOUT": {"required": set(), "sensitive": False, "type": "float"},
+    "AUTH_MCP_ISSUER_URL": {"required": set(), "sensitive": False, "type": "str"},
+    "AUTH_MCP_RESOURCE_SERVER_URL": {"required": set(), "sensitive": False, "type": "str"},
+    "METRICS_ENABLED": {"required": set(), "sensitive": False, "type": "bool"},
+    "METRICS_PREFIX": {"required": set(), "sensitive": False, "type": "str"},
+    "METRICS_PORT": {"required": set(), "sensitive": False, "type": "int"},
+    "METRICS_BIND": {"required": set(), "sensitive": False, "type": "str"},
+    "RETRIEVAL_TOP_K": {"required": set(), "sensitive": False, "type": "int"},
+    "RETRIEVAL_MIN_RELEVANCE": {"required": set(), "sensitive": False, "type": "float"},
+    "RETRIEVAL_HYBRID_WORKERS": {"required": set(), "sensitive": False, "type": "int"},
+    "RETRIEVAL_ASSEMBLY_MAX_CHARS": {"required": set(), "sensitive": False, "type": "int"},
+    "RRF_TOP_K": {"required": set(), "sensitive": False, "type": "int"},
+    "RRF_K": {"required": set(), "sensitive": False, "type": "int"},
+    "RERANK_TOP_K": {"required": set(), "sensitive": False, "type": "int"},
+    "RETRIEVAL_QUERY_REWRITE_MODE": {"required": set(), "sensitive": False, "type": "enum"},
+    "RETRIEVAL_QUERY_REWRITE_LLM_MODEL": {"required": set(), "sensitive": False, "type": "str"},
+    "RETRIEVAL_QUERY_REWRITE_TEMPERATURE": {"required": set(), "sensitive": False, "type": "float"},
+    "RETRIEVAL_QUERY_REWRITE_MAX_TOKENS": {"required": set(), "sensitive": False, "type": "int"},
+    "RETRIEVAL_QUERY_REWRITE_EXPAND_COUNT": {"required": set(), "sensitive": False, "type": "int"},
+    "RETRIEVAL_QUERY_REWRITE_PROMPT": {"required": set(), "sensitive": False, "type": "str"},
+    "RETRIEVAL_QUERY_REWRITE_EXPANSION_PROMPT": {"required": set(), "sensitive": False, "type": "str"},
+    "RETRIEVAL_QUERY_REWRITE_SCOPES": {"required": set(), "sensitive": False, "type": "str"},
+    # skill-specific keys
+    "RERANKER_MODEL": {"required": {"retrieve_skill"}, "sensitive": False, "type": "str"},
+    "RERANKER_DEVICE": {"required": set(), "sensitive": False, "type": "str"},
+    "RERANKER_CE_WEIGHT": {"required": set(), "sensitive": False, "type": "float"},
+    "RERANKER_RETRIEVAL_WEIGHT": {"required": set(), "sensitive": False, "type": "float"},
+    "SQL_HOST": {"required": {"structured_query_skill"}, "sensitive": False, "type": "str"},
+    "SQL_PORT": {"required": set(), "sensitive": False, "type": "int"},
+    "SQL_USER": {"required": {"structured_query_skill"}, "sensitive": False, "type": "str"},
+    "SQL_PASSWORD": {"required": {"structured_query_skill"}, "sensitive": True, "type": "str"},
+    "SQL_DATABASE": {"required": {"structured_query_skill"}, "sensitive": False, "type": "str"},
+    "SQL_CHARSET": {"required": set(), "sensitive": False, "type": "str"},
+    "SQL_CONNECT_TIMEOUT": {"required": set(), "sensitive": False, "type": "float"},
+    "SQL_READ_TIMEOUT": {"required": set(), "sensitive": False, "type": "float"},
+    "SQL_POOL_MAX_CONNECTIONS": {"required": set(), "sensitive": False, "type": "int"},
+    "SQL_POOL_MIN_CACHED": {"required": set(), "sensitive": False, "type": "int"},
+    "SQL_POOL_MAX_CACHED": {"required": set(), "sensitive": False, "type": "int"},
+    "SQL_POOL_BLOCKING": {"required": set(), "sensitive": False, "type": "bool"},
+    "SQL_DEFAULT_MAX_ROWS": {"required": set(), "sensitive": False, "type": "int"},
+}
+
+PLACEHOLDER_MARKERS = ("replace-me", "changeme", "your-", "<", ">")
+
+
+def parse_env(path: Path) -> set[str]:
+    keys: set[str] = set()
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key = line.split("=", 1)[0].strip()
+        if key:
+            keys.add(key)
+    return keys
+
+
+def check_example(path: Path, skill: str, errors: list[str]) -> None:
+    keys = parse_env(path)
+    for required, meta in CONTRACT.items():
+        if skill in meta["required"] and required not in keys:
+            errors.append(f"{path.name}[{skill}]: missing required key {required}")
+    for key in sorted(keys):
+        if key not in CONTRACT:
+            errors.append(f"{path.name}: unknown key {key} not in contract")
+            continue
+        if CONTRACT[key]["sensitive"]:
+            value = ""
+            for raw in path.read_text(encoding="utf-8").splitlines():
+                if raw.startswith(key + "="):
+                    value = raw.split("=", 1)[1].strip()
+                    break
+            if value and not any(m in value.lower() for m in PLACEHOLDER_MARKERS):
+                errors.append(f"{path.name}: sensitive key {key} holds a real-looking value in an example")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", type=Path, default=Path.cwd())
+    args = parser.parse_args()
+    errors: list[str] = []
+    examples = {
+        "common_core": args.root / "common_core" / ".env.example",
+        "retrieve_skill": args.root / "retrieve_skill" / ".env.example",
+        "structured_query_skill": args.root / "structured_query_skill" / ".env.example",
+    }
+    for skill, path in examples.items():
+        if not path.is_file():
+            errors.append(f"missing example for {skill}: {path}")
+            continue
+        check_example(path, skill, errors)
+    if errors:
+        print("\n".join(f"[fail] {e}" for e in errors))
+        return 1
+    print("env examples aligned with config contract")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

common_core-0.1.0/src/common_core/__init__.py

@@ -0,0 +1,54 @@
+"""共用运行时（common_core）：供多个 skill 共享的底层组件集合。
+本包不依赖具体业务，提供配置、鉴权、上下文、可观测性、安全审查与数据提供者的基础组件，是各 skill 的地基。
+导出名用于方便业务模块从包顶层直接引入常用类与函数。
+"""
+
+from .auth import AuthError, IdentityClaims, TokenVerifier
+from .config import (
+    AuthConfig,
+    CacheConfig,
+    LLMConfig,
+    MetricsConfig,
+    RetrievalConfig,
+    RuntimeConfig,
+    VectorStoreConfig,
+)
+from .context import AgentContext
+from .mcp_auth import (
+    MCPBearerTokenVerifier,
+    ToolAuthError,
+    ToolContextGuard,
+    build_mcp_auth,
+    resolve_tool_context,
+)
+from .observability import Observability
+from .protocols import QueryRequest, QueryResult
+from .security import INJECTION_PATTERNS, check_safety, mask_pii, normalize_query
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuthConfig",
+    "AuthError",
+    "AgentContext",
+    "CacheConfig",
+    "INJECTION_PATTERNS",
+    "IdentityClaims",
+    "LLMConfig",
+    "MCPBearerTokenVerifier",
+    "MetricsConfig",
+    "Observability",
+    "QueryRequest",
+    "QueryResult",
+    "RetrievalConfig",
+    "RuntimeConfig",
+    "ToolAuthError",
+    "ToolContextGuard",
+    "TokenVerifier",
+    "VectorStoreConfig",
+    "build_mcp_auth",
+    "check_safety",
+    "mask_pii",
+    "normalize_query",
+    "resolve_tool_context",
+]