标准术语表
August 14, 2026 · View on GitHub
dsh-exa-mcp 工程涉及的统一术语。英文术语保留原文，中文为约定译名。来源标注为 dsh 官方文档或本插件实测。
一、DeepSeek Harness / Cordis 侧
| 术语 | 说明 | 参考 |
|---|---|---|
| dsh | DeepSeek Harness 的 CLI 名（npx @deepseek-ai/dsh） | 官方 README |
| Cordis | dsh 的插件框架：插件向共享上下文贡献服务、类型化事件与可逆效果 | cordis-primer |
| 插件（plugin） | Cordis 中一个可挂载的模块（导出 name 与 apply(ctx, config)） | config.md |
| bundle（组合包） | npm 包形态的配置层，package.json 声明 dsh.bundle.patch | publish.md |
| profile | $DSH_HOME/profiles/<name>/ 下的可运行组合，dsh.profile.bundles 列出叠加的 bundle | 同上 |
| patch（补丁层） | 顶层 YAML 数组（insert / 按 id 覆盖），在加载时合成进配置树 | cordis-primer#loader-configuration |
| overlay | 命令行 --patch <path> 传入的临时补丁层，优先级最高 | publish.md 加载顺序 |
| entry / row（行） | 配置树中的一行：id + name（插件名）+ config（可选）+ disabled（可选） | cordis-primer |
!!js | YAML 标签，标记一个 JS 表达式，在插件 config（及 disabled）加载时求值；作用域含 process 与已注入的 ctx.<service> | cordis-tutorial/05-config |
| ctx | 插件上下文（Context）：服务注册表、事件总线、效果注册 | cordis-primer |
| 服务（service） | 注册在 ctx 上的能力（如 ctx.tools、ctx.llm、ctx.sessions） | architecture.md |
| inject（注入） | 插件声明依赖的服务，激活前框架等待其就绪 | service.md |
| 事件（event） | 类型化广播；会话事件持久化为 session log，代理事件实时分发 | events.md |
| 效果（effect） | 插件在 ctx 上注册的可逆副作用，插件卸载时自动回滚 | cordis-primer |
| HMR | 热替换：编辑配置后无需重启进程即可重载插件 | publish.md |
| session log | 追加式会话事件日志（session.jsonl.zstd，多帧 zstd 压缩），模型上下文的事实来源；Web UI 可导出明文 zip | architecture.md#session-log |
| tool registry | 工具注册表 ctx.tools；模型可见工具即注册于其中的定义 | tools.md |
| seam（能力缝） | 可替换能力的三件套：服务定义 + 服务提供者 + 消费者 | capability-seams.md |
| LLM adapter | 模型适配器（如 @deepseek-ai/dsh-llm-deepseek），注册在 ctx.llm | llm-streaming.md |
| credentials（凭据库） | ctx.credentials 管理的本地凭据（如 ~/.dsh/.credentials.yaml），经 apiKeyEnv 引用 | credentials.md |
| apiKeyEnv | 适配器配置字段：从凭据库/环境变量解析 API key 的变量名 | verify-config-source-ownership |
| DSH_HOME | dsh 数据目录（默认 ~/.dsh）：profiles / sessions / storages / settings / credentials | app-boot |
--dump-config | 离线合成并打印最终配置树（不启动、不求值 !!js） | app-boot#renderConfigDump |
| turn / step | turn = 一次任务回合；step = 一次模型请求 + 其调用的工具 | architecture.md#turn-flow |
| dsh-plugin topic | 官方约定的 GitHub 主题标签，用于插件可发现性 | 官方 README |
二、MCP / mcp-client 桥侧
| 术语 | 说明 | 参考 |
|---|---|---|
| MCP | Model Context Protocol，模型上下文协议 | https://modelcontextprotocol.io/ |
| Streamable HTTP | MCP 传输方式之一（HTTP + SSE），mcp.exa.ai 使用此方式 | mcp-client README |
| stdio | MCP 传输方式之一（子进程 stdin/stdout） | 同上 |
@deepseek-ai/dsh-mcp-client | dsh 的 MCP 客户端桥插件：连接外部 MCP 服务器并把工具注册到 ctx.tools | 同上 |
| serverName | mcp-client 配置的命名空间，[A-Za-z0-9_-]{1,32}，全实例唯一 | 同上 |
| 公开工具名 | mcp__<serverName>__<rawName>（超长/非法字符时确定性哈希归一化） | 同上 |
failOnStartupError | 初始连接/同步失败时是否让插件激活失败（默认 false：仅记录并进入重连） | 同上 |
| reconnect | 断线自动重连策略（initialDelayMs/maxDelayMs/maxAttempts） | 同上 |
| toolCallTimeoutMs | 单次 callTool 超时（默认 60000 ms） | 同上 |
tools/list_changed | MCP 通知：服务器工具集变化后 mcp-client 自动重同步 | 同上 |
| JSON-RPC / -32602 | MCP 调用错误码（-32602 = 参数校验失败） | https://spec.modelcontextprotocol.io/ |
三、Exa 侧
| 术语 | 说明 | 参考 |
|---|---|---|
| Exa | 网页搜索/抓取服务提供商 | https://exa.ai |
mcp.exa.ai/mcp | Exa 托管的 MCP 端点（Streamable HTTP） | Exa MCP 文档 |
| 免费额度（free tier） | 匿名使用，限流（429），默认仅 web_search_exa + web_fetch_exa | exa-mcp-server |
| API Key | https://dashboard.exa.ai/api-keys 申请；经 x-api-key / Authorization: Bearer / ?exaApiKey= 传递 | 同上 |
| OAuth | 托管端点的登录流程（?login），dsh 桥不支持 | 同上 |
web_search_exa | 基础搜索工具（query + numResults） | 本插件实测 schema，见 API.md |
web_fetch_exa | 网页全文抓取工具（urls 数组 + maxCharacters） | 同上 |
web_search_advanced_exa | 高级筛选搜索（27 参数）；匿名也可用，需 ?tools= 白名单启用 | 实测见 API.md |
agent_run | Exa Agent 多步研究；需鉴权（API key/OAuth）+ ?tools= 启用，按用量计费 | 实测见 API.md |
?tools= / ?defaultSearchType= | MCP URL 查询参数：工具白名单 / 默认检索模式 | Exa MCP 文档 |
四、本插件约定
| 术语 | 约定 |
|---|---|
| 行 id | mcp-exa（覆盖/禁用时按此 id 打补丁） |
| serverName | exa |
| 工具命名空间 | mcp__exa__* |
| key 环境变量 | EXA_API_KEY（有则带 key，无则匿名） |
| 默认超时 | toolCallTimeoutMs: 180000 |