Cortex — DeepSeek-Harness 多模型编排与评测插件

![npm version] ![npm downloads]

English | 中文 | npm 包 | GitHub

Cortex 是一个 DeepSeek-Harness 插件，让宿主的主模型（强模型）变成高杠杆监督者：主模型负责规划、拆解、验收与纠偏；**被路由的执行模型（低成本小模型，如 Qwen3.8-9B）**与工具负责执行。通过递归任务树、动态路由、四级质量门控、预算控制、失败恢复、策略复用与各维度模型评测，Cortex 在质量不降的前提下持续降低单位成功任务成本。

本项目监督者 = 宿主主模型（驱动 cortex_* 工具，内置注册表如 deepseek-v4-pro）；执行者 = 动态路由为每个子任务选定的模型（L1/L2，如 Qwen3.8-9B）。

建议 GitHub 仓库话题（Topics）：dsh-plugin · dsh · cordis · llm-orchestration · multi-model · model-routing · quality-gate

---

能力一览

能力	入口	说明
任务智能层	cortex_start	画像 → 指纹 → 策略匹配（≥0.90 复用 / 0.70~0.90 轻校验 / <0.70 重新规划）→ 预算池 → 粒度经济性复核
递归任务树	cortex_decompose	安全边界：maxDepth 6 / maxTotalNodes 50 / maxChildrenPerNode 10 / maxReplan 3；DAG depends_on；聚合节点按节点 schema + Gate0 汇总（仅 active 模型）
递归调用	cortex_execute recursive	就绪叶子自动调度 + 聚合汇总；透传 evaluate:gate2 / multi_vote——与手动批执行同标准
动态路由	cortex_execute	候选过滤 → 效用评分（质量/成功率/风险 − 成本/延迟/失败率）→ MQC 升级门槛；costFirst / balanced / qualityFirst；多模型一致性投票
四级质量门控	Gate0 确定性 · Gate1 自检 · Gate2 评估器 · Gate3 cortex_review 批量验收	硬门槛：format_validity / safety / groundedness < 0.5 直接失败；验收决策携带节点质量/Gate1 自检快照
恢复引擎	cortex_recover	失败标准化分类 → 重试 / 切换 / 修正重试 / 拆分 / 升级 / 人工 + 失败模式学习
预算控制	引擎内置	四池 10/70/10/10；STOP-1..4（STOP-2 来自真实观测 MQC：ΔQ/ΔC，不再硬编码）；达 90% 锁定高成本（已上线：路由候选过滤 L2/L3 + 执行池支出兜底）；降级模式；A/聚合节点成本按调用语义入池（start→plan、review→quality、recover→emergency）
模型评测	cortex_evaluate	逐例 7 维评分；模型 × 任务类型 × 能力 × 7 维画像（dims_profile，EMA 持久化、跨重启恢复；生产路径 Gate2/评审 dims 同样回写）；动态能力自适应注册（画像达阈值 → 进能力目录并参与路由候选并集）；结构化 expected 走 Rule First 确定性 correctness；页面一键评测（真实后台执行、含各维度结果表）；性价比 Q×SR/Cost + Pareto 前沿
模型注册表	cortex_models（config/models.yaml）	静态 YAML + DSH ctx.llm 动态发现 + 启停管理；路由评分明细（选型预览）
策略中心	cortex_policy / cortex_strategy_match	指纹相似度三档复用、版本化策略、跳层任务树建议
KPI	cortex_report	监督者调用/任务、A 成本构成（aByKind：start/decompose/review/…按调用类型分解）、监督杠杆、vs 主模型直接执行节省率（负值给出编排开销警告）、质量、策略复用率
缓存与漂移	引擎内置	L1 精确 + L2 语义（近重复文本相似度，保守阈值 0.88，可关闭）+ L3 跨任务组件复用；模型漂移监控（vs 静态基线 → 路由自动降权，注册表/矩阵可见）
本地控制台	/cortex ui / 8788	趋势 / 时间线 / 模型注册表 / 能力矩阵（4 指标 + 各维度 mini 行）/ 评测中心（用例库 + 结果表）；中英 i18n、昼夜主题、元/美元展示切换、SSE 实时
看门狗	/cortex watchdog / /watchdog	跨工作区定时任务注入 + 目标达成自动评估改进循环：定时 schedule（--at/--after/--every，every ≥300s）经官方 inbox 通道（agent.followup——绝不手工写会话事件）注入；目标循环 goal-loop（设目标；注入/执行的任务完成后强模型围绕目标客观评估对话并回注改进意见，直至判定达成（met+score 双保险）或达 maxRounds）；任务清单 task-list（有序任务链，前一项完成自动推进下一项）；工作区间（全局 ws window <HH:MM-HH:MM>，支持跨午夜/days）；startAt/endAt；跨工作区目标（ws: / session: / workspaceId / workspacePath）；Web 管理页 /watchdog + /api/watchdog/*；连续 2 次评估失败 → 规则终态化 failed（可观测）

安装与自动启用

dsh plugin 是受支持的方式：它把本包安装到 profile，且因为本包声明了 dsh.bundle.patch（=cordis.patch.yml），会被自动追加到 dsh.profile.bundles——下次启动即生效，无需手动编辑任何 profile 文件。

从 npm 安装（已发布 — v0.2.0）：

# 作为依赖安装插件包
yarn add dsh-cortex            # 或：npm install dsh-cortex

# 注册进 DSH profile 并启动
npx @deepseek-ai/dsh plugin --profile web add dsh-cortex
npx @deepseek-ai/dsh web        # 启动——13 个 cortex_* 工具已可用

从本地仓库安装（开发模式）：

cd <repo-path>                                        # 本仓库根目录
npx @deepseek-ai/dsh plugin --profile web add .       # 锚定当前目录；也可传绝对路径
npx @deepseek-ai/dsh web

移除： npx @deepseek-ai/dsh plugin --profile web remove dsh-cortex。

随包补丁把 cortex 行插入为 uiEnabled: true, uiPort: 8788（控制台仅回环监听）。stateDir 与 modelsFile 使用内置默认（$DSH_HOME/storages/cortex 与随包 config/models.yaml）——如需覆盖，在 profile 自身的 cordis.patch.yml 里加一条 - id: cortex 的 config 行即可（它比 bundle 层后应用，优先级更高）。

一次典型任务（AI 视角）

cortex_start →（可选 cortex_strategy_match）→ cortex_decompose T0 → cortex_execute [node_ids | recursive]
→ cortex_review（批量验收）→ cortex_recover（失败恢复）→ cortex_report（KPI）→ cortex_policy（策略沉淀）

操作与命令

1. 智能体工具（13 个——监督者主模型自主调用）

工具	用途	关键参数
cortex_start	创建任务（画像 → 指纹 → 策略匹配 → 预算池）	goal、profile{task_type, domain, complexity, risk, quality_requirement, budget_limit, input_tokens?, expected_output_tokens?, latency_requirement_ms?, language?, capability?}、input
cortex_strategy_match	策略中心查询（相似度三档复用判定）	profile
cortex_decompose	拆解父节点（安全边界 / DAG / 重规划）	task_id、parent_id?、replace?、children[{goal, task_type, capability, output_schema, quality_target?, tool_allow?, depends_on?, type?}]
cortex_execute	路由执行（Gate0/1[/2]、缓存、记账）	task_id、node_id?/node_ids?、recursive?、mode?（costFirst
cortex_review	Gate3 批量验收（决策附节点质量/自检快照）	task_id、decisions[{node_id, status, reason_code?, missing_items?, next_action, recommended_depth?, confidence?}]
cortex_recover	恢复决策树（retry/switch/upgrade 引擎内重执行）	task_id、node_id?
cortex_policy	成功任务沉淀策略	task_id、note?
cortex_report	KPI 报表（任务/全局）	task_id?
cortex_models	模型注册表/画像/路由评分/漂移监测	task_type?、capability?、reset?
cortex_evaluate	模型评测（7 维×能力画像、性价比/Pareto）	cases?、use_saved?、models?、task_type?、quality_target?
cortex_eval_cases	评测用例库（页面/对话共享）	action?（list
cortex_capabilities	能力目录（只增不改不删）	action?（list
cortex_l0	L0 确定性工具库（列表/生成/删除）	action?（list|show|add|remove|generate|run）、keywords、allowed?

2. 斜杠命令（/cortex <子命令>）

命令	说明
/cortex status	引擎状态：任务（含 running）、节点、尝试、策略、模型、编排纪律状态
/cortex task <id>	任务树（画像/策略/预算/节点树）
/cortex trace <id>	执行轨迹（attempt + decision）
/cortex kpi [id]	KPI 报表（全局或单任务）
/cortex models [enable|disable <id>|refresh|reset]	注册表列表；reset 清评测回写恢复静态基准；enable/disable 启停；refresh 刷新动态发现
`/cortex policies [disable	enable ]`
/cortex model-pref [set <id> [偏好内容]|clear|show]	模型偏好（含偏好内容=该模型适用哪些任务）：内容覆盖（≥50%）+ active + 质量<0.9 → 实际采用执行（用户偏好优先，能力标签仅建议项 prefCapabilityMismatch 审计；执行失败由恢复引擎自动升级兜底）；内容未覆盖才回退（prefSkip 审计）；跨重启保留；页面★同效（必填偏好内容）
/cortex l0	L0 确定性工具库（list/show/remove/generate/run）
/cortex rate [refresh]	美元→人民币汇率（refresh 强制拉取）
/cortex reset	删除状态文件 + 清内存存储 + 重装静态注册表 + 立即从 DSH 重发现模型（无需重启宿主）；新发现的第三方模型去重追加入 config/models.yaml（追加式写入、保留注释）永久并入静态注册表
`/cortex ui start	stop
/cortex watchdog <add task|add goal|list|rm|pause|resume|run|goal|ws|ui>	看门狗：跨工作区定时任务注入（at/after/every，≥300s）+ 目标达成自动评估改进循环（回注直至达标；连续 2 次评估失败 → 规则终态化 failed 可观测，remedy 回注失败 stall 不空转）；规则可设定时开始/中止（startAt/endAt，endAt 可留空=不限制）；工作区间为全局（ws window <HH:MM-HH:MM>，任务仅在区间内执行，支持跨午夜/days）
/cortex routing [suggest|show|apply|rollback]	路由权重学习：样本驱动权重建议（suggest）、查看当前（show）、一键应用（apply）、回滚（rollback）——由每节点路由样本 + 漂移驱动，学习链产出建议（应用前不生效）
/cortex budget	预算再平衡：共享池余额 + 台账（动态回收/再分配，终态回收）
/cortex calibration	评价器校准链：评审 vs 自检 vs 终态的历史矛盾样本
/cortex help	命令用法

强制模式：/cortex <你的任务文本>（未知子命令但带自由文本）→ 强制走 Cortex 流水线——模型接管优先（需求经 DSH 官方 inbox 通道 agent.followup 注入对话流，主模型自主执行拆解/子任务工具；headless 无注入通道时由引擎直跑 cortex_start → 拆解 → 子模型执行 → review → policy）。

3. 控制台 REST（127.0.0.1:8788）

GET  /api/overview · /api/timeline?hours=all|24|168 · /api/rate · /api/models
     /api/matrix · /api/evaluations · /api/eval-cases · /api/capabilities
     /api/evaluate/status · /api/task/<id> · /api/events（SSE 实时）
POST /api/models/<id>            {enabled?: boolean, preferred?: boolean, reason?: string}   // reason = 偏好内容（页面必填）
     /api/matrix/reset           （清除评测回写）
     /api/eval-cases             {action: add|remove|save, ...}
     /api/capabilities           {name, description?}
     /api/evaluate               {models?, cases?, use_saved?}（后台真实运行）
     /api/watchdog               {action: add-task|add-goal|pause|resume|remove|run|window-set|window-clear|ws-add, ...}（白名单）
GET  /watchdog · /api/watchdog/rules|runs?limit=50|targets|windows   （看门狗管理页，复用 /api/events SSE）

4. 运行时生命周期

• 装载：apply → 注册表装载（静态 YAML + 持久化画像回写 + 模型启停恢复）→ 心跳 stateDir/mounted.json →（可选）控制台 → 用量结算定时器（60s，每 5 轮僵尸巡检）→ 动态模型发现。
• 每轮对话：编排纪律上下文按会话级注入（仅本会话 15 分钟内有活跃流程才抑制；其它会话遗留流程不压制）。
• 卸载 / 重启：effect dispose 停止控制台（主动销毁活跃 SSE 连接，不挂起）并清理定时器；一切持久状态在状态目录（任务/节点/策略/画像/模型启停/汇率），重启后 LWW 重建。
• 自愈：僵尸任务（running 且 4h 无活动）每 ~5 分钟巡检终态化；评测回写与漂移基线跨重启保留；/cortex reset 清空状态文件（即时生效：清内存存储 + 重装静态注册表 + DSH 重发现模型）；动态模型发现每 24 小时自动刷新一次（modelRefreshHours，默认 24，0=关闭）。

模型分配（全链路子 Agent 流水线）

• 敏感分级（qualitySensitiveOf）：S（复杂规划/仲裁/终审/纠偏——需强推理）、M（常规规划/数值统计/关键评测/视觉细节——弱模型可多次执行投票）、L（常规执行）；决策记录带 sensitivity。
• 最强回退链（strongestOf）：配置 strongestModel（须 active）→ 否则由画像动态推导（tier → defaultQuality → 实测质量 → exec 成功率）；未配置最强模型时当前最强可得即为最强——S 档永不空转，且随画像变化动态迁移。
• 每节点子 Agent：planAgent（cortex_decompose auto:true——最强模型生成拆解）、reviewAgent（cortex_review auto:true——常规节点阈值自动 accept + 异常/高敏感节点评审子 Agent）、fixAgent（config.fixAgentAuto——升级前最强模型可直接交付修正/结果）。
• 弱模型投票（repeat_vote，M/S 档）：同一模型 N 轮（2-5）执行后按一致性合并（pass/evaluate/arbitrate）——以约 1/100 成本获得强模型级可靠性。
• 统计确定性（V8.0 §5.1 L0 档）：统计/计数节点自动转为 "提取（模型，可投票/早停）→ 记录多数决合并 → 引擎确定性计算"——模型只提取 records（EXTRACT_CONTRACT），count/聚合由 lib/engine/compute.js（零成本、可重放）完成，杜绝模型计数漂移；type:"compute" 节点 = L0 引擎节点（decompose 可声明 compute:{ops:[...]} 规格，缺省按 goal 推断）——结果 quality_source:"engine"（E 级免 A 评审）。
• 纯文本统计直算：词频/字数/词数/行数——文本即数据，引擎对源文本直接 tokenize/计量（零模型调用、精确到词元、重跑一致）；实体类统计仍走提取+引擎。
• V8.0 关键指标：cortex_report 新增节点自治率（autonomyRate）、S 档成本占比（cost.sShare）、投票/引擎统计（voting：repeat 轮次/成本/引擎计算数/估算节省）；页面报表卡片同步。
• L0 能力库：AI 生成确定性工具函数并运行时积累（stateDir/l0_capabilities.json 跨重启）——执行时先查后建（id/名称/关键词匹配命中 → 引擎零成本执行；显式 l0:"能力id" 缺失且允许时由最强模型生成 → 安全沙箱校验（vm 零信任/禁词/超时/双跑确定性/样例+Gate0）→ 入库 → 执行，未验证代码绝不执行）；同名版本演进、连续 3 次失败自动禁用、估算节省累计；cortex_l0（list/show/add/remove/generate/run）、/cortex l0、页面 "L0 能力" tab 同步。
• 自动模式：autoMode(task)——quality_requirement≥0.9 ∥ complexity≥0.8 ∥ risk≥0.8 → 自动 qualityFirst（无需手工传 mode）。
• §7.1 KPI 补齐：收敛率/平均树深/缓存命中率（任务级+全局，确定性口径）；attempt 记录携带 fromCache/cacheLevel（缓存命中可观测）；命中后不重复写缓存行（同 key 幂等）。
• §4.13 学习链⑤ + §7.1 全局模型使用：蒸馏数据集 stateDir/distill.jsonl——L3（最强档）高质量输出（执行/多投票共识/S 委托 plan·review·fix·L0 生成）达标自动入列（质量≥distillMinQuality 0.9，限容 500 行，可观测报告 distill{rows,models,lastAt}）；globalKpi models 补全 tierUsage/upgradeRate/fallbackRate。
• 领域维度画像（§4.12 模型×领域×任务类型）：domain_profiles[domain][taskType/cap]——评测/Gate2 回写 EMA（同 alpha、跨重启深合并持久化）；路由预测回退链 领域 → 类型级 → 7 维均值 → 默认（predictQuality(model, node, env.domain)）；cortex_evaluate 新增 domain 参数（用例单领域自动继承）；cortex_models 展示领域画像。

模型画像（如何更新）

• 评测回写（cortex_evaluate / 页面一键评测）：任务类型质量 EMA + 成功率 + 成本/延迟 + 7 维能力画像（dims_profile），持久化 profile_overrides.json（首测锚定漂移基线）。
• 执行反馈：每次真实节点执行（非缓存）回写确定性统计——尝试/成功/失败 + 失败类型与任务类型分布，同文件持久化；样本 ≥ EXEC_PROFILE_MIN_SAMPLES（3）时路由采用实测成功率替代静态（用得多 → 画像越准 → 路由越对）。质量分仍只由评测确认（Gate1 自检不入画像，避免主观污染）。
• POST /api/matrix/reset 或 /cortex models reset 恢复静态基准（评测 + 执行反馈一并清除）。
• 仅实测有分值：能力矩阵只对已验证能力（评测/执行回写的键，measured 集合跟踪）显示分值；静态声明与 defaultQuality 不冒充实测——未验证单元格显示"无实测数据"。

子模型能力与多媒体支持

执行器（被路由的子模型）是自包含的一次性 worker agent，能力边界如下：

能力维度含媒体标签：image_analysis（视觉模型声明——图片任务按它精确路由/过滤）与 audio_video_analysis（目录维度；暂无能处理模型声明——矩阵保持空列，直到配置媒体模型/MCP）。拆解图片子节点请用 capability: ['image_analysis']（而非 document_analysis）以便精确路由。

维度	支持
输入	文本、文件（read/glob/grep）、图片（read_image / MCP 浏览器）、URL（web_search/web_fetch，只读）——另支持 base64 图片（data:image/...;base64 或 {image_base64, mime}）自动解码落盘给执行器
工具（agent 模式）	read glob grep read_image + web_search/web_fetch（只读，缺省；executorExtraTools 可覆写）+ mcp__*（任意已配 MCP——如 Playwright 截图）+ skill + 业务插件前缀（缺省 tssdp_）
媒体策略	mediaPolicy：auto（缺省——媒体输入强制 agent 模式+契约）/ reject（明确快速失败+诊断）/ pass_through（交给 MCP）
输出	结构化 JSON + 可选顶层 artifacts [{path, mime}]——引擎校验存在性与魔数（png/jpeg/webp/gif/mp4/mp3/wav/pdf）；非法 → 节点 failed 且留痕
默认拒绝	写文件/执行（write/edit/pwsh/bash/run_code）与二次编排（subagent/workflow/cortex_* 等）——产物类任务可用节点级 tool_allow 显式换入白名单
诚实边界	DSH 模型模态仅 文本+图片——音视频理解需带媒体能力的 MCP/多模态模型；否则执行器返回 {"unsupported": true, "reason": ...} 降级承诺（绝不编造内容），或 mediaPolicy: reject 快速失败并给出清晰诊断

示例流程：图片分析 → 带图片引用的节点执行（agent 模式 + read_image/MCP）；截图/海报产出 → Playwright MCP + artifacts 声明（魔数校验）；音视频处理 → 需配套媒体 MCP（否则明确诊断，按 INPUT_FAILURE 分类进恢复决策树）。

偏好模型的模态兜底：当偏好执行器（如纯文本 L1 模型）被派去处理图片任务时，它先被真实调用（attempt 留痕）。执行器现在确定性预检模态（modelAcceptsImage，宿主 llm.resolveModelInfo 权威判定）：未声明 image 输入的模型快速失败（model lacks image modality，不生成——文本模型绝不允许“编造读图证据”；生产实机被观察：对 1×1 红 PNG 虚构 800×600/白色像素结果）；恢复引擎识别缺口后直接切换到视觉候选——不再走拆解/升级绕圈。

视觉前提（宿主侧）：视觉模型须在宿主 llm-deepseek.models 条目声明 inputModalities: [text, image]（如 ~/.dsh/settings.yaml）——否则 read_image 一律拒绝（"model does not declare image input"；未声明条目回退 [text]）。

成本口径

• 执行模型（子模型）：从子智能体/单轮会话的 assistant/message.usage 精确采集 TokenUsage（billed = input + cacheRead + cacheWrite），按注册表单价真实计价。
• 监督者（主模型）：经 DSH sessionProjections/tokenMeter 取真实会话用量（tokenUsage 投影返回 {totals:{uncachedInputTokens, outputTokens, cacheReadTokens, cacheWriteTokens}}；Cortex 归一化嵌套与旧扁平两种形态，能采到 outputTokens 精确计入 A 成本——无投影时才估算），cortex_report 另给"vs 主模型直接执行"基线节省率。
• 页面触发的评测无监督者上下文（chat 路径执行），不计为监督者调用（不污染 KPI）。

开发与测试

npm test                                   # node --test（引擎/服务/UI/看门狗单元 + 冒烟）——292 个
node tools/verify-post-restart.mjs         # 重启后自检（7 项：含 JSONL 完整性/策略引用/学习链实体）
node tools/smoke-ui.mjs                    # 页面脚本语法 + SSE + 模型启停

目录结构

app-pkg/index.js   入口转发包装器（rollout 缓存穿透，与 dsh-tssdp 同模式）
lib/index.js       插件入口（name/inject/Config/apply + 生命周期）
lib/service.js     CortexService 门面（工具背后高层操作）
lib/tools.js       13 个智能体工具
lib/cli.js         /cortex 命令组
lib/ui-server.js   本地 Web 控制台（127.0.0.1:8788）
lib/watchdog.js    跨工作区定时任务注入 + 目标循环干预（remedy）
lib/watchdog-cli.js /cortex watchdog 命令处理器
lib/engine/*.js    纯函数引擎（fingerprint/router/budget/quality/recovery/store/executor/kpi/granularity/compute/l0/weight-learn/calibration/peak/state-reset）
config/models.yaml 模型注册表（可覆盖）
test/              node --test 测试
tools/             验证/开发脚本

许可证

MIT