devkit-tools 0.1.0__tar.gz

devkit_tools-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# 统一换行：仓库内文本一律 LF，避免跨平台 CRLF 噪音
+* text=auto eol=lf

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

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: mypy
+      - run: pytest --cov-fail-under=85

devkit_tools-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,23 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "23 5 * * 1"  # 每周一一次
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: github/codeql-action/init@v3
+        with:
+          languages: python
+          build-mode: none  # Python 为解释型语言，无需构建
+      - uses: github/codeql-action/analyze@v3

devkit_tools-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build
+      - run: pip install -e ".[dev]"
+      - run: pytest --cov-fail-under=85
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Trusted Publishing (OIDC)：无需 token
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

devkit_tools-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# venv
+.venv/
+venv/
+
+# test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# editors / OS
+.idea/
+.vscode/
+.DS_Store

devkit_tools-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,6 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.5.7
+    hooks:
+      - id: ruff
+      - id: ruff-format

devkit_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Liao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

devkit_tools-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: devkit-tools
+Version: 0.1.0
+Summary: 面向开发者的命令行工具包：数据格式转换 + 环境诊断
+Project-URL: Homepage, https://github.com/yukinpost/devkit-cli
+Project-URL: Issues, https://github.com/yukinpost/devkit-cli/issues
+Author-email: yukinpost <jasonliaojx98@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,convert,envcheck,json,toml,yaml
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: packaging>=23.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# devkit-tools
+
+[![CI](https://github.com/yukinpost/devkit-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/yukinpost/devkit-cli/actions/workflows/ci.yml)
+
+面向开发者的命令行工具包。v0.1 提供两个开箱即用的子命令：
+
+- **`convert`** — 在 JSON / YAML / TOML / CSV 之间互相转换
+- **`envcheck`** — 诊断开发环境中必备工具的安装与版本
+
+> 路线图模块（`templater` / `watch` / `gitstats`）见 [docs/requirements.md](docs/requirements.md)，将在 v0.2+ 实现。
+
+## 安装
+
+```bash
+pip install devkit-tools
+```
+
+需要 Python 3.10+。
+
+## convert
+
+```bash
+# 文件互转（输出格式由扩展名推断）
+devkit convert config.json config.yaml
+
+# 显式指定格式
+devkit convert data.txt --from json --to toml
+
+# 管道模式
+cat data.json | devkit convert --to yaml
+
+# 美化输出
+devkit convert data.json --to json --pretty
+```
+
+支持矩阵与边界（如 CSV 仅支持二维表）见 [docs/requirements.md](docs/requirements.md) 2.2.1。
+
+## envcheck
+
+```bash
+# 用预置检查项诊断环境
+devkit envcheck
+
+# 自定义检查项 + 输出修复建议
+devkit envcheck --config examples/config/dev-toolkit.yml --suggest-fix
+
+# JSON 报告（便于 CI 消费）
+devkit envcheck --format json
+```
+
+任一检查未通过时返回非零退出码。`--suggest-fix` 只输出建议，**不会修改你的系统**。
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+pytest          # 测试 + 覆盖率
+ruff check .    # lint
+mypy            # 类型检查
+```
+
+## License
+
+[MIT](LICENSE)

devkit_tools-0.1.0/README.md

@@ -0,0 +1,64 @@
+# devkit-tools
+
+[![CI](https://github.com/yukinpost/devkit-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/yukinpost/devkit-cli/actions/workflows/ci.yml)
+
+面向开发者的命令行工具包。v0.1 提供两个开箱即用的子命令：
+
+- **`convert`** — 在 JSON / YAML / TOML / CSV 之间互相转换
+- **`envcheck`** — 诊断开发环境中必备工具的安装与版本
+
+> 路线图模块（`templater` / `watch` / `gitstats`）见 [docs/requirements.md](docs/requirements.md)，将在 v0.2+ 实现。
+
+## 安装
+
+```bash
+pip install devkit-tools
+```
+
+需要 Python 3.10+。
+
+## convert
+
+```bash
+# 文件互转（输出格式由扩展名推断）
+devkit convert config.json config.yaml
+
+# 显式指定格式
+devkit convert data.txt --from json --to toml
+
+# 管道模式
+cat data.json | devkit convert --to yaml
+
+# 美化输出
+devkit convert data.json --to json --pretty
+```
+
+支持矩阵与边界（如 CSV 仅支持二维表）见 [docs/requirements.md](docs/requirements.md) 2.2.1。
+
+## envcheck
+
+```bash
+# 用预置检查项诊断环境
+devkit envcheck
+
+# 自定义检查项 + 输出修复建议
+devkit envcheck --config examples/config/dev-toolkit.yml --suggest-fix
+
+# JSON 报告（便于 CI 消费）
+devkit envcheck --format json
+```
+
+任一检查未通过时返回非零退出码。`--suggest-fix` 只输出建议，**不会修改你的系统**。
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+pytest          # 测试 + 覆盖率
+ruff check .    # lint
+mypy            # 类型检查
+```
+
+## License
+
+[MIT](LICENSE)

devkit_tools-0.1.0/docs/requirements.md

@@ -0,0 +1,309 @@
+# devkit 项目需求文档
+
+> 版本：v0.1.0（初稿）
+> 目标：创建可维护的开源项目，积累申请 OpenAI Codex for OSS 所需的公开证据、维护记录与 Codex 使用场景
+
+---
+
+## 1. 项目概述
+
+### 1.1 项目定位
+
+**devkit** 是一款面向开发者的通用命令行工具包，覆盖日常开发的 5 大高频场景：项目初始化、数据格式转换、文件变更监听、环境诊断和 Git 统计。无需切换工具链，一个命令即可完成。
+
+### 1.2 项目目标
+
+- 为开发者提供开箱即用的命令行效率工具
+- 发布到 PyPI，支持 `pip install devkit-tools` 安装
+- 跨平台支持（Windows / macOS / Linux）
+- 建立真实维护证据：CI 记录、版本发布、issue/PR 处理、用户反馈和下载数据
+- 为 Codex for OSS 申请准备材料；申请结果取决于官方审核、项目影响力和维护者身份，不作为项目交付承诺
+
+### 1.3 目标用户
+
+- 全栈开发者
+- DevOps 工程师
+- 开源项目维护者
+- 技术团队 Lead（用于团队环境标准化）
+
+---
+
+## 2. 功能需求
+
+### 2.1 `templater` — 项目脚手架（v0.2+ 路线图，非 v0.1 范围）
+
+| 项目 | 内容 |
+|------|------|
+| **ID** | F-001 |
+| **描述** | 从模板目录或 GitHub 仓库生成项目骨架代码 |
+| **CLI** | `devkit template create <name> [--template <name>] [--dir <path>]` |
+| **子命令** | `template list` — 列出可用模板 |
+| **输入** | 模板名称、项目名称、目标路径（可选，默认当前目录） |
+| **输出** | 生成完整的项目目录和文件 |
+| **核心功能** | 1. 扫描本地模板目录<br>2. Jinja2 模板渲染（内容 + 文件名均支持变量）<br>3. 交互式变量提示与默认值<br>4. 自动 `.gitignore` 过滤模板自身元数据<br>5. 可选 `git init` 初始化仓库 |
+| **内置模板** | `python-cli` — Python Click 命令行项目骨架<br>`web-api` — FastAPI Web API 项目骨架 |
+| **依赖** | Jinja2, gitpython (optional) |
+
+### 2.2 `convert` — 数据格式转换
+
+| 项目 | 内容 |
+|------|------|
+| **ID** | F-002 |
+| **描述** | 在常见文本数据格式之间转换；v0.1 支持 JSON / YAML / TOML / CSV，XML 作为 v0.2 扩展 |
+| **CLI** | `devkit convert <input> [output] [--from <fmt>] [--to <fmt>] [--pretty]`<br>`cat <input> \| devkit convert --to yaml` |
+| **输入** | 文件路径 或 stdin 管道输入 |
+| **输出** | 文件写入 或 stdout 输出 |
+| **核心功能** | 1. 自动检测输入格式（文件扩展名 + 内容嗅探）<br>2. 按支持矩阵执行转换；不支持或可能丢失语义时显式失败或警告<br>3. 支持 `--pretty` 美化输出<br>4. 支持 stdin/stdout 管道模式<br>5. CSV 用 stdlib `csv` 逐行处理；结构化格式整树加载并设输入大小上限（详见 2.2.1） |
+| **依赖** | PyYAML（`safe_load`/`safe_dump`）；TOML 读：`tomllib`(Python 3.11+ stdlib) / `tomli`(3.10 回退)，运行时分支 `tomllib if sys.version_info >= (3, 11) else tomli`；TOML 写：`tomli-w`；XML：`defusedxml`（v0.2 再引入） |
+
+#### 2.2.1 转换边界
+
+| 类型 | v0.1 支持策略 |
+|------|---------------|
+| JSON / YAML / TOML | 映射到统一的 dict/list/scalar 数据模型，保留结构语义 |
+| CSV | 仅支持二维表：表头 + 行记录；嵌套对象转 CSV 时需要显式字段展开，否则失败 |
+| XML | v0.2 支持；需定义属性、文本节点、重复节点的映射规则，默认不承诺无损互转 |
+| 大文件 | CSV 用 stdlib `csv` 逐行处理（天然流式）；JSON/YAML/TOML 整树加载，提供可配置输入大小上限并在超限时明确报错 |
+
+### 2.3 `watch` — 文件监听自动执行（v0.2+ 路线图，非 v0.1 范围）
+
+| 项目 | 内容 |
+|------|------|
+| **ID** | F-003 |
+| **描述** | 监听文件变更，触发自定义命令（编译/测试/格式化等） |
+| **CLI** | `devkit watch <pattern> --exec <command> [--debounce <ms>] [--ignore <pattern>]`<br>`devkit watch --config watch.yml` |
+| **输入** | glob 文件匹配模式、要执行的命令 |
+| **输出** | 实时控制台输出命令执行结果 |
+| **核心功能** | 1. 使用 watchdog 跨平台文件系统监听<br>2. 防抖/节流合并高频事件（默认 300ms）<br>3. glob 模式匹配支持的/忽略的文件<br>4. 自动遵守 `.gitignore` 规则<br>5. 彩色日志区分事件类型（新增/修改/删除）<br>6. 支持 YAML 配置文件声明多组监听规则 |
+| **依赖** | watchdog |
+
+### 2.4 `envcheck` — 环境诊断医生
+
+| 项目 | 内容 |
+|------|------|
+| **ID** | F-004 |
+| **描述** | 检查开发环境中必备工具的安装状态、版本合规性和常见配置问题 |
+| **CLI** | `devkit envcheck [--config <file>] [--format table\|json\|html] [--suggest-fix]` |
+| **输入** | YAML 配置文件（声明检查项规格，如工具名、最低版本、PATH 路径等） |
+| **输出** | Terminal 表格 / JSON / HTML 三种报告格式 |
+| **核心功能** | 1. 预置检查项：Python、Node.js、Git、Docker、Go、Rust 等<br>2. 版本语义化比较（>=, ~=, ^）<br>3. PATH 路径完整性检查<br>4. 端口占用检测（可选）<br>5. 检查项可并行执行<br>6. `--suggest-fix` 输出修复建议，v0.1 不自动修改系统 PATH 或配置文件<br>7. 检查规格由 YAML 配置驱动，可扩展 |
+| **依赖** | 标准库（shutil, subprocess, json, re, socket）+ PyYAML + packaging |
+
+### 2.5 `gitstats` — Git 仓库统计（v0.2+ 路线图，Should，非 v0.1 Must）
+
+| 项目 | 内容 |
+|------|------|
+| **ID** | F-005 |
+| **描述** | 解析 Git 历史，输出贡献者排名、提交频率、文件变更热度等统计 |
+| **CLI** | `devkit gitstats [--path <repo>] [--since <date>] [--format table\|json\|html]` |
+| **输入** | Git 仓库路径（默认当前目录） |
+| **输出** | Terminal 表格 / JSON / HTML 报告 |
+| **核心功能** | 1. 贡献者排行（按提交数/变更行数）<br>2. 提交频率时间线（按周/月聚合）<br>3. 文件变更热度 Top N<br>4. 代码年龄分布（新增 vs 修改 vs 删除）<br>5. Bus Factor 估算（贡献集中度）<br>6. HTML 报告内置 ASCII 图表，无外部 JS 依赖 |
+| **依赖** | gitpython 或 git CLI |
+
+### 2.6 v0.1 MVP 范围
+
+| 优先级 | 范围 | 说明 |
+|--------|------|------|
+| Must | CLI 主入口、打包、CI、README、LICENSE | 确保项目可安装、可测试、可发布 |
+| Must | `convert` 基础版 | 支持 JSON/YAML/TOML/CSV；明确错误处理和支持矩阵 |
+| Must | `envcheck` 只读诊断 | 支持配置驱动检查和修复建议；不自动改系统环境 |
+| Should | `gitstats` 基础统计 | 若时间允许，仅实现贡献者排行和提交频率 |
+| Later | `templater`、`watch`、XML 转换、HTML 报告、插件系统 | 放入 v0.2+，避免 v0.1 范围失控 |
+
+---
+
+## 3. 非功能需求
+
+| 类别 | 要求 |
+|------|------|
+| **NF-001 性能** | CSV 使用 stdlib `csv` 逐行处理（天然流式）；JSON/YAML/TOML 整树加载是格式本身决定的，需提供可配置的输入大小上限并在超限时给出明确错误。不承诺具体内存数字 |
+| **NF-002 兼容性** | 支持 Python 3.10+，在 Windows 10+/macOS 12+/Ubuntu 20.04+ 通过 CI |
+| **NF-003 可用性** | CLI 提供 `--help` 详细说明；所有命令返回非零退出码表示失败 |
+| **NF-004 安全性** | YAML 使用 `safe_load`/`safe_dump`；如 v0.2 实现 XML 解析，必须使用 defusedxml 防止 XXE 攻击；不执行未经验证的模板代码 |
+| **NF-005 测试覆盖** | v0.1 已实现模块（convert、envcheck）行覆盖率 ≥ 85%，在 CI 用 `pytest --cov --cov-fail-under=85` 卡线 |
+| **NF-006 代码质量** | CI 中 `ruff check` 无 warning、`mypy` 通过；类型注解覆盖目标 ≥ 90%（针对 v0.1 已实现模块） |
+
+---
+
+## 4. 技术架构
+
+### 4.1 技术栈
+
+| 层次 | 选型 | 说明 |
+|------|------|------|
+| 语言 | Python ≥ 3.10 | 跨平台、生态成熟 |
+| CLI 框架 | Click | 最流行的 Python CLI 框架 |
+| 构建 | Hatchling | PEP 517/518 标准构建 |
+| 测试 | pytest + pytest-cov | 行业标准 |
+| 代码检查 | ruff | 极速 linter + formatter |
+| 类型检查 | mypy（pyright 可选） | 类型安全 |
+| 依赖管理 | pyproject.toml 集中声明 | 单一事实来源 |
+| CI/CD | GitHub Actions | 矩阵测试（3 OS × 4 Python 版本）|
+| 发布渠道 | PyPI | `pip install devkit-tools` |
+
+### 4.2 架构分层
+
+v0.1 数据源 = 文件系统 + stdin/stdout；Git 仓库等数据源随 gitstats 在 v0.2+ 引入。
+
+```
+CLI 层（click） ──→ 模块入口 ──→ 核心逻辑层 ──→ 数据层
+     │                │               │               │
+     │                │               │               ├── 文件系统
+     │                │               │               ├── stdin/stdout
+     │                │               │               └──（v0.2+: Git 仓库）
+     │                │               │
+     │                └── 公共基础设施 ──┼── 错误处理
+     │                                ├── 日志系统
+     │                                └── 配置加载
+     │
+     └── 输出格式化（表格 / JSON / HTML / 彩色终端）
+```
+
+### 4.3 项目结构
+
+以下为完整路线图结构；v0.1 可只创建已实现模块和对应测试，未实现模块不保留空壳代码。
+
+```
+devkit-cli/
+├── pyproject.toml                  # 项目元数据、依赖、CLI入口
+├── README.md                       # 项目文档（中英文）
+├── LICENSE                         # MIT License
+├── .gitignore
+├── .pre-commit-config.yaml
+├── .github/
+│   └── workflows/
+│       ├── ci.yml                  # CI: lint + test + build
+│       ├── release.yml             # PyPI 发布
+│       └── codeql.yml              # 安全扫描
+│
+├── docs/
+│   ├── requirements.md             # 本需求文档
+│   └── guide/                      # 用户指南（按模块分）
+│
+├── tests/
+│   ├── __init__.py
+│   ├── conftest.py
+│   ├── test_convert.py
+│   └── test_envcheck.py
+│   # v0.2+: test_templater.py / test_watch.py / test_gitstats.py
+│
+├── examples/
+│   └── config/
+│       └── dev-toolkit.yml         # envcheck 检查项示例配置
+│   # v0.2+: examples/templates/（templater 内置模板）
+│
+└── src/
+    └── dev_toolkit/
+        ├── __init__.py             # 版本号
+        ├── __main__.py             # python -m 入口
+        ├── cli.py                  # Click 主 CLI 组
+        │
+        ├── convert/
+        │   ├── __init__.py
+        │   ├── cli.py
+        │   ├── core.py             # 统一转换接口
+        │   └── handlers.py         # 各格式处理器
+        │
+        └── envcheck/
+            ├── __init__.py
+            ├── cli.py
+            ├── core.py             # 检查引擎
+            ├── checks.py           # 检查项实现
+            └── reporters.py        # 多格式报告输出
+        #
+        # v0.2+ 路线图模块（实现时再创建，不留空壳）：
+        #   templater/  — Jinja2 渲染引擎 + 文件操作
+        #   watch/      — watchdog 事件循环 + 命令执行/防抖
+        #   gitstats/   — Git 数据采集 + 统计聚合分析
+```
+
+---
+
+## 5. 发布计划
+
+### 5.1 里程碑
+
+| 阶段 | 时间 | 交付物 |
+|------|------|--------|
+| M1 核心框架 | Day 1-2 | CLI 框架 + pyproject.toml + CI 配置 + README/LICENSE |
+| M2 MVP 功能 | Day 3-5 | convert 基础版 + envcheck 只读诊断 |
+| M3 测试完善 | Day 6-7 | 单元测试 + 关键集成测试 + CI 矩阵测试通过 |
+| M4 文档与发布 | Day 8-9 | 用户指南 + 示例配置 + PyPI 发布 |
+| M5 申请准备 | Day 10+ | 整理维护证据和 Codex 使用记录；达到真实使用/维护证据后再提交申请 |
+
+### 5.2 版本规划
+
+| 版本 | 内容 |
+|------|------|
+| v0.1.0 | 初始发布：convert + envcheck MVP、基础测试、CI、PyPI |
+| v0.2.0 | 扩展：templater、gitstats 基础统计、XML 转换 |
+| v0.3.0 | 扩展：watch、HTML 报告、更多内置模板和 gitstats 指标 |
+| v0.4.0 | 插件系统：支持第三方自定义检查项/模板 |
+| v1.0.0 | 稳定版：API 稳定、文档完备、生态初步形成 |
+
+---
+
+## 6. Codex for OSS 申请准备
+
+### 6.1 官方条件理解
+
+Codex for OSS 面向核心维护者或广泛使用的公开开源项目维护者。当前官方说明中的权益包括 API credits、6 个月 ChatGPT Pro with Codex，以及按项目需要评估的 Codex Security 访问权限。申请结果取决于官方审核和项目实际影响力，因此本文档只把申请准备作为目标，不承诺一定获批。
+
+### 6.2 申请证据清单
+
+| 证据类型 | 目标材料 |
+|----------|----------|
+| **项目质量** | 清晰 README、MIT License、安装说明、示例、CI、测试覆盖率、发布记录 |
+| **真实使用** | PyPI 下载量、GitHub stars/forks、issue、用户反馈、实际使用案例 |
+| **维护记录** | 持续 commit、changelog、issue/PR 响应、版本发布节奏 |
+| **Codex 使用记录** | PR review、issue triage、测试生成、release 准备、文档维护的实际记录 |
+| **生态价值** | 说明项目解决的具体维护者痛点，而不只强调工具数量 |
+
+### 6.3 Codex 使用场景规划
+
+在申请材料中优先说明可验证、可复现的维护工作流：
+
+1. **代码审查辅助** — 使用 Codex 或 Codex GitHub Action 对 PR 进行质量反馈，结果由维护者确认后采纳
+2. **Issue 修复** — 用 Codex 复现问题、定位根因、生成补丁草案并运行测试
+3. **测试生成** — 为新增转换规则、环境检查项和 CLI 错误路径补充测试
+4. **发布准备** — 用 Codex 汇总 changelog、检查发布清单、审阅 README 示例
+5. **安全辅助** — CodeQL 和依赖扫描作为基础安全流程；Codex Security 仅在获得访问权限后用于深度安全审查，不与 CodeQL 混同
+
+### 6.4 API Credits 使用规划
+
+1. **PR 质量反馈** — 在受信任触发条件下使用 Codex GitHub Action 或 `codex exec` 生成审查意见
+2. **维护自动化** — 自动整理 issue、生成复现步骤、建议测试范围
+3. **发布流程** — 在 release 前检查文档、示例、变更说明和兼容性影响
+4. **质量门禁** — 对关键 PR 做 Codex 辅助分析，但最终合并仍由维护者决定
+
+CI 中使用 OpenAI API key 时必须保护密钥，限制可触发工作流的用户和事件，避免直接把不受信任的 PR 内容作为高权限提示输入。
+
+---
+
+## 7. 风险与缓解
+
+| 风险 | 影响 | 缓解措施 |
+|------|------|----------|
+| 项目无人使用或影响力不足 | 申请证据不足 | 先解决明确开发者痛点，发布可复现示例，积累 PyPI/GitHub/用户反馈数据 |
+| 申请条件不满足 | 无法通过 Codex for OSS 审核 | 将申请作为外部机会，不作为项目成功标准；持续维护并等待更充分证据 |
+| v0.1 范围过大 | 延期、质量下降 | 以 convert + envcheck 为 MVP，其他模块进入 v0.2+ |
+| 数据格式转换语义丢失 | 用户结果不可信 | 建立支持矩阵；对不支持或有损转换显式失败或警告 |
+| 自动修复环境变量风险 | 破坏用户环境 | v0.1 仅输出修复建议，不自动修改 PATH 或 shell 配置 |
+| PyPI 包名不可用 | 发布受阻 | 发布前确认包名（`devkit-cli` 已被占用，分发名改用 `devkit-tools`，命令仍为 `devkit`） |
+| 申请审核时间长 | 等待周期长 | 提交后持续维护项目，积累更多贡献数据 |
+| Python 版本兼容问题 | 用户安装失败 | CI 矩阵覆盖 3.10/3.11/3.12/3.13 |
+| 跨平台 watch 不稳定（v0.2+） | 部分平台不可用 | watch 模块进入 v0.2+ 时增加 Windows/macOS 专属 CI runner 测试 |
+
+---
+
+## 8. 术语表
+
+| 术语 | 说明 |
+|------|------|
+| CLI | Command Line Interface，命令行界面 |
+| PyPI | Python Package Index，Python 包索引 |
+| Jinja2 | Python 模板引擎（v0.2+ templater） |
+| Watchdog | Python 跨平台文件系统监听库（v0.2+ watch） |
+| Bus Factor | 项目核心知识在少数人手中的集中度指标（v0.2+ gitstats） |
+| Debounce | 防抖，高频事件合并为一次处理（v0.2+ watch） |

devkit_tools-0.1.0/examples/config/dev-toolkit.yml

@@ -0,0 +1,17 @@
+# envcheck 检查项示例配置
+# 用法：devkit envcheck --config examples/config/dev-toolkit.yml --suggest-fix
+checks:
+  - name: Python
+    command: python
+    version_arg: "--version"
+    min_version: "3.10"
+  - name: Git
+    command: git
+    version_arg: "--version"
+  - name: Node.js
+    command: node
+    version_arg: "--version"
+    min_version: "18.0"
+  - name: Docker
+    command: docker
+    version_arg: "--version"