DeepSeekHelper

<p align="center"> <img src="assets/banner.svg" alt="DeepSeekHelper banner" width="800"> </p>

English | 中文

A Codex plugin that exposes DeepSeek-powered MCP tools for supervised collaboration. Codex delegates, reviews, discusses, and verifies work with DeepSeek while keeping final edits, tests, and judgment inside Codex.

---

一个 Codex 插件，通过 MCP 工具让 Codex 与 DeepSeek 进行有监督的协作。Codex 可以将中低难度的工作委托给 DeepSeek，也可以使用 DeepSeek 进行审查、讨论和验证，同时将最终编辑、测试和判断保留在 Codex 内。

---

Star History

<a href="https://www.star-history.com/?type=date&repos=UrgencyWu%2Fdeepseekhelper"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=UrgencyWu/deepseekhelper&type=date&theme=dark&legend=top-left" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=UrgencyWu/deepseekhelper&type=date&legend=top-left" /> <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=UrgencyWu/deepseekhelper&type=date&legend=top-left" /> </picture> </a> ---

English

About

DeepSeekHelper adds twelve local MCP tools to Codex, each wrapping the DeepSeek API with structured supervision boundaries:

DS, ds, DeepSeek, deepseek, DeepSeekHelper, deepseekhelper, and DeepSeek Helper are equivalent names in everyday prompts. Alias matching is case-insensitive. For example, "Ask DS to review this diff" and "ask deepseek to review this diff" should trigger the same workflow as "Ask DeepSeekHelper to review this diff."

• Delegation — deepseek_task sends scoped, low/medium difficulty work to DeepSeek for drafts, plans, snippets, and documentation.
• Review — deepseek_review gets an independent second pair of eyes on code, docs, plans, prompts, or implementation summaries.
• Discussion — deepseek_discuss compares trade-offs, risks, and alternatives for higher-difficulty decisions.
• Verification — deepseek_verify checks claims, assumptions, edge cases, and test gaps against the evidence Codex provides.
• Prompt generation — deepseek_prompt creates strict delegation or review prompts so Codex can hand off work with clear constraints.
• Model management — deepseekhelper_status, deepseek_models, and deepseek_auth_check surface available models, automatic Flash/Pro classification, and API connectivity.
• Usage tracking — deepseek_usage_summary and deepseek_usage_tail report token counts, cache hit rates, and estimated costs without logging prompt or response content.
• Explicit updates — deepseek_update_check and deepseek_update_apply let users check and apply git upstream updates on demand.

The plugin automatically selects the right DeepSeek model for the job: Flash-class for drafting and prompt generation, Pro-class with thinking for review, discussion, and verification. Every call records anonymous usage metadata locally so you can audit cost and cache efficiency over time.

Features

• Supervised low and medium difficulty task assistance.
• Independent review for code, documentation, plans, prompts, and implementation summaries.
• Design and architecture discussion with trade-offs.
• Verification of claims, assumptions, edge cases, and test gaps.
• Automatic Flash/Pro model selection from the DeepSeek /models list.
• Token, cache hit/miss, and estimated cost tracking.

Requirements

• Codex with local plugin support.
• Node.js 18 or newer.
• A DeepSeek API key.

Installation

Clone the repository and install dependencies:

git clone https://github.com/UrgencyWu/deepseekhelper.git
cd deepseekhelper
npm install

Install or register the plugin in Codex using the plugin directory. The plugin includes:

.codex-plugin/plugin.json
.mcp.json
skills/deepseekhelper/SKILL.md
scripts/server.mjs

The included .mcp.json starts the MCP server with:

{
  "mcpServers": {
    "deepseekhelper": {
      "command": "node",
      "args": ["scripts/server.mjs"]
    }
  }
}

If your Codex plugin host does not start MCP servers from the plugin root, replace scripts/server.mjs with the absolute path to your local scripts/server.mjs.

Configuration

Set your DeepSeek API key before starting Codex:

export DEEPSEEK_API_KEY="your-deepseek-api-key"

On macOS, Codex launched as a desktop app may not inherit shell variables. You can set the key through launchctl and restart Codex:

launchctl setenv DEEPSEEK_API_KEY "your-deepseek-api-key"

DeepSeekHelper falls back to launchctl getenv DEEPSEEK_API_KEY on macOS if the variable is not present in the direct process environment.

Optional settings:

export DEEPSEEKHELPER_MODEL=auto
export DEEPSEEKHELPER_MODEL_CACHE_DAYS=1
export DEEPSEEK_BASE_URL=https://api.deepseek.com

Do not commit .env files or real API keys. See .env.example for a template.

Tools

| Tool | Purpose | |---|---| | deepseekhelper_status | Show configuration, model policy, data paths, and available models. | | deepseek_models | Fetch available DeepSeek models and show profile classification. | | deepseek_auth_check | Verify the key can call both /models and chat completions. | | deepseek_task | Ask DeepSeek to handle low or medium difficulty work under Codex supervision. | | deepseek_review | Ask DeepSeek for independent review. | | deepseek_discuss | Ask DeepSeek to compare options and risks. | | deepseek_verify | Ask DeepSeek to verify claims, assumptions, edge cases, and test gaps. | | deepseek_prompt | Ask DeepSeek to create a strict delegation or review prompt. | | deepseek_usage_summary | Summarize calls, tokens, cache hit rate, and estimated cost. | | deepseek_usage_tail | Show recent usage records without prompt or response content. | | deepseek_update_check | Check whether the plugin is behind its git upstream without modifying files. | | deepseek_update_apply | Explicitly fast-forward the plugin from its git upstream. |

Model Selection

Selection order:

1. Explicit model argument on a tool call.
2. DEEPSEEKHELPER_MODEL or legacy DEEPSEEK_MODEL, if configured and not auto.
3. Automatic policy using the daily cached DeepSeek /models list.

Automatic policy:

• deepseek_task low/medium: latest Flash-class model, thinking disabled by default.
• deepseek_prompt: latest Flash-class model, thinking disabled by default.
• deepseek_review, deepseek_discuss, deepseek_verify: latest Pro-class model, thinking enabled with high effort by default.

The model list is cached for one day by default in data/models-cache.json. Use the refresh arguments on deepseekhelper_status or deepseek_models to force a fresh lookup.

Default Collaboration Strategy

DeepSeek token cost is treated as non-constraining. Codex should apply this strategy automatically when the user asks for DS, DeepSeek, or DeepSeekHelper collaboration:

• Trivial edits: Codex should handle them directly without DS.
• Medium code changes: use deepseek_task first for a focused plan, snippet, or unified diff; Codex then applies and verifies.
• Documentation or design drafts: use deepseek_task for a first draft; Codex edits for local accuracy and style.
• High-difficulty code, architecture, security, data, release, or migration work: Codex leads implementation and uses deepseek_discuss, deepseek_review, or deepseek_verify for second-model scrutiny.
• Published or user-visible conclusions: use deepseek_verify when accuracy or omissions matter.

Codex should pass compact, relevant context to DS instead of dumping an entire repository. Codex remains responsible for file edits, command execution, tests, and final judgment.

Usage Tracking

Each DeepSeek API call appends metadata to:

data/usage.jsonl

The log records timestamps, tool name, model, model tier, thinking mode, token counts, cache hit/miss tokens, and estimated cost. It does not record prompts or responses.

data/ is ignored by git and should remain local.

Low-Approval Workflow

For routine use, ask Codex to call DeepSeekHelper MCP tools directly. Normal status checks, model checks, auth checks, task delegation, review, discussion, verification, prompt generation, and usage reports should not require shell commands.

Use phrases such as:

Use DeepSeekHelper to review this diff.
Ask DeepSeekHelper to discuss these design options.
Show today's DeepSeekHelper token usage.
Run a DeepSeekHelper auth check.

Avoid approval-prone shell workflows for everyday use. Commands such as npm install, npm audit, curl, gh, git push, dependency installation, and GitHub publishing should only be run when you explicitly ask for setup, audit, release, or publishing work.

Updating

DeepSeekHelper updates are explicit. The plugin does not update itself in the background.

Use:

Ask DeepSeekHelper to check for updates.
Ask DeepSeekHelper to update itself.
Ask DeepSeekHelper to update itself and install dependencies if needed.

The update tools use the plugin's git upstream:

• deepseek_update_check: checks branch, upstream, cleanliness, and ahead/behind state. It does not modify files.
• deepseek_update_apply: refuses to run if the working tree is dirty, runs git fetch --prune, then git pull --ff-only.

If package.json or package-lock.json changes, deepseek_update_apply only runs npm install when called with install_dependencies: true.

After an update, reload or restart Codex so the MCP server uses the new code.

Development Checks

Run:

node --check scripts/server.mjs
npm audit --omit=dev

If you have the Codex plugin creator validation script available, run:

python3 /path/to/plugin-creator/scripts/validate_plugin.py .

Security

Never commit API keys, .env, data/, node_modules/, usage logs, or model cache files. See SECURITY.md.

Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

License

MIT

---

中文

关于

DeepSeekHelper 为 Codex 提供了十二个本地 MCP 工具，每个工具封装了 DeepSeek API，并带有结构化的监督边界：

在日常提示中，DS、ds、DeepSeek、deepseek、DeepSeekHelper、deepseekhelper 和 DeepSeek Helper 都表示同一个插件。别名匹配不区分大小写。例如“让 DS 复核这个 diff”、“让 deepseek 复核这个 diff”和“让 DeepSeekHelper 复核这个 diff”应触发相同工作流。

• 委托 — deepseek_task 将限定范围的中低难度工作发送给 DeepSeek，获取草稿、计划、代码片段和文档。
• 审查 — deepseek_review 让 DeepSeek 作为独立的第二双眼睛，审查代码、文档、计划、提示词或实现总结。
• 讨论 — deepseek_discuss 对比权衡、风险和替代方案，辅助高难度决策。
• 验证 — deepseek_verify 根据 Codex 提供的证据，检查声明、假设、边界情况和测试盲区。
• 提示词生成 — deepseek_prompt 创建严格的委托或审查提示词，让 Codex 以清晰的约束交付工作。
• 模型管理 — deepseekhelper_status、deepseek_models 和 deepseek_auth_check 展示可用模型、自动 Flash/Pro 分类以及 API 连通性。
• 用量跟踪 — deepseek_usage_summary 和 deepseek_usage_tail 报告 token 数量、缓存命中率和预估费用，不记录提示词或响应内容。
• 显式更新 — deepseek_update_check 和 deepseek_update_apply 让用户按需检查并应用 git 上游更新。

插件会自动为任务选择合适的 DeepSeek 模型：草稿和提示词生成使用 Flash 级模型，审查、讨论和验证使用带思考模式的 Pro 级模型。每次调用都会在本地匿名记录用量元数据，方便随时审计成本和缓存效率。

功能

• 有监督的中低难度任务辅助。
• 对代码、文档、计划、提示词和实现总结的独立审查。
• 带权衡分析的设计和架构讨论。
• 对声明、假设、边界情况和测试盲区的验证。
• 基于 DeepSeek /models 列表的自动 Flash/Pro 模型选择。
• Token、缓存命中/未命中和预估费用跟踪。

环境要求

• 支持本地插件的 Codex。
• Node.js 18 或更高版本。
• DeepSeek API 密钥。

安装

克隆仓库并安装依赖：

git clone https://github.com/UrgencyWu/deepseekhelper.git
cd deepseekhelper
npm install

在 Codex 中通过插件目录安装或注册插件。插件包含：

.codex-plugin/plugin.json
.mcp.json
skills/deepseekhelper/SKILL.md
scripts/server.mjs

插件内置的 .mcp.json 启动 MCP 服务器：

`