iguowz/dsh-cortex

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

npm version npm downloads license

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 轻校验 /  用户设置 > 默认价；持久化，路由按生效价计价 |
| 预算控制 | 引擎内置 | 四池 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 行）/ 评测中心 / L0 能力 / 学习链 / 部门；中英 i18n 跟随 DSH「通用设置 → 语言」（控制台读写同一份 locale 设置，页头按钮经官方设置服务写回，所有已开控制台经 SSE 即时跟随；无设置服务的独立控制台只读跟随文档并明确提示）、昼夜主题、元/美元展示切换、SSE 实时；不再展示任何全局模式指示（模式是任务属性），任务列表逐行标「部门」徽标 |
| 组织模式（部门探针与治理） | cortex_start.organization_mode / cortex_probe | 组织模式是任务属性（standard / department / auto——auto 按难度判定 = max(复杂度, 规模, 风险)，阈值 organizationAutoThreshold 0.75；显式声明优先）。部门模式叠加：内置 8 个探针（需求/研发/测试/安全/合规/发布/运维/知识，自定义只增不改不删）+ 管辖范围/工具上限/质量下限/预算份额 + 授权档 P0–P4（观察/建议/执行/决策/否决）+ Rule-First fail-closed 治理（pass/review/veto，否决冻结该节点及其下游，仅显式 lift 可解）+ 哈希链账本（governance.jsonl，可 verify）+ 事件总线 × 订阅 → 确定性待办（intents.jsonl）+ 对抗治理复核 + 关键操作批准链（否决解除/P4 授予/启用治理须批准后才生效）+ 探针预算硬配额 + 派遣优先级与 ROI 排名——全部留痕、全部按任务可选 |
| 人工介入 | 引擎 + cortex_probe interactions | 规则判定"必须由人回答"（关键操作待批 / 否决确认 / 冲突裁决 / 人工审核 / 主模型深挖 / 部门预算）时登记问题+选项+建议动作，无人值守路径主动唤起对话让主模型向用户提问（去重、合并、投递留痕 interactions.jsonl）；绝不替用户拍板。控制台刻意不设第二处待办入口（问题在对话里问，数据面 /api/interactions 仍供脚本消费） |
| 阶段三控制面 | cortex_execute.control / 控制台 / CLI | 准入队列（全局 + 单任务双限，轮转发号，大任务不饿死小任务）、工作流控制（pause/resume/terminate/单节点 isolate——取消在飞调用、不伪造成失败态）、审查协议与提示模板库（版本化、追加式、含契约缺口自检） |
| 自优化 | 控制台「学习链」/ /cortex | 基于已落库事实（KPI/队列/执行画像/学习链样本）的有界调参建议，仅在显式点击后按置信阈值与单次上限应用，每次留痕；路由权重学习（suggest/apply/rollback）、预算再平衡台账、评价器校准样本、审计快照 |
| 看门狗 | /cortex watchdog / /watchdog | 跨工作区定时任务注入 + 目标达成自动评估改进循环：定时 schedule（--at/--after/--every，every ≥300s）经官方 inbox 通道（agent.followup——绝不手工写会话事件）注入；目标循环 goal-loop（设目标；注入/执行的任务完成后强模型围绕目标客观评估对话并回注改进意见，直至判定达成（met+score 双保险）或达 maxRounds）；任务清单 task-list（有序任务链，前一项完成自动推进下一项）；工作区间（全局 ws window ，支持跨午夜/days）；startAt/endAt；跨工作区目标（ws: / session: / workspaceId / workspacePath）；Web 管理页 /watchdog + /api/watchdog/；连续 2 次评估失败 → 规则终态化 failed（可观测） |

近期主要改动

初始版本之后新增能力的浓缩记录（逐轮证据见 docs/开发任务清单.md）：

- 组织模式——部门探针与治理（cortex_probe、cortex_start.organization_mode）：模式是任务属性（standard / department / auto = 引擎按难度判定 = max(复杂度, 规模, 风险)，阈值 organizationAutoThreshold 0.75；显式声明优先；领域/能力标签刻意不计入难度）。部门模式叠加 8 个内置探针（自定义只增不改不删）、授权档 P0–P4、Rule-First fail-closed 治理（pass/review/veto，否决冻结节点及其下游，仅显式 lift 可解）、哈希链账本（可 verify）、事件总线 × 订阅 → 确定性待办、对抗治理复核、关键操作批准链、探针预算硬配额、派遣优先级与 ROI 排名。部门模式是标准模式之上的一层——不引入自己的模型池、过滤或路由口径。
- 人工介入：规则要求"人必须回答"的问题（关键操作待批/否决确认/冲突裁决/人工审核/主模型深挖/部门预算）连同选项与建议动作登记，无人值守时引擎主动唤起对话让主模型提问——去重、合并、投递留痕；控制台刻意不设第二处待办入口（问题在对话里问，/api/interactions 与 cortex_probe interactions 仍供脚本消费）。
- 阶段三控制面：准入队列（全局 + 单任务、轮转发号）、工作流控制（pause/resume/terminate/单节点 isolate）、审查协议与提示模板（版本化、追加式、契约缺口自检）、自优化建议（护栏 + 台账）、路由权重学习、预算再平衡与审计快照——控制台「学习链」可见，/cortex control|tune|org|gate|protocols 可达。
- 控制台语言跟随 DSH 通用设置：lib/locale.js 读宿主 locale 偏好（设置服务优先、settings.yaml 只读回退），写回走官方设置服务；页头按钮即切换，所有已开控制台经 SSE 跟随（并有存储事件/心跳兜底，宿主事件缺失也不会静默卡住页面），首屏即带语言。会话「任务」面板注册一份 cortex 词典（中英），全部标签/状态/按钮走它。
- 控制台瘦身：全局组织模式切换与「默认模式」徽标一并下线（模式按任务，任务行仍标自己的模式徽标）、「需你操作」块下线；其余面板（探针/责任分工/授权档/账本/待办优先级/待办与待批/回报率/学习链/L0/评测）统一业务措辞，不出现框架名与原始 JSON。
- 质量与路由深度：Gate3.5 红队复核、各维度能力画像（dims_profile，EMA，评测与生产 Gate2/评审双路回写）、漂移监控（自动路由降权）、性价比 + Pareto 前沿、静态基准重置、生效价覆盖（三级优先级）、L1/L2/L3 缓存、type:"compute" 引擎确定性统计、L0 确定性工具库（运行时生成 + 沙箱校验后入库）。
- 可维护性：抽出 lib/engine/util.js 收敛 9 组重复实现；浏览器 bundle 的界面文案集中到一份词典（回归用例禁止 bundle 内写死中文）；带证据清理死导出/死样式/无用脚本。

安装与自动启用

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

从 npm 安装（已发布）：

作为依赖安装插件包
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        # 启动——14 个 cortex_* 工具已可用

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

cd                                         # 本仓库根目录
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. 智能体工具（14 个——监督者主模型自主调用）

| 工具 | 用途 | 关键参数 |
|---|---|---|
| cortex_start | 创建任务（画像 → 指纹 → 策略匹配 → 预算池） | goal、profile{task_type, domain, complexity, risk, quality_requirement, budget_limit, input_tokens?, expected_output_tokens?, latency_requirement_ms?, language?, capability?}、input、organization_mode?（standard\|department\|auto——按任务选择；显式优先于 auto；回执带 organizationMode{mode,source,reason,difficulty?}） |
| cortex_strategy_match | 策略中心查询（相似度三档复用判定） | profile |
| cortex_decompose | 拆解父节点（安全边界 / DAG / 重规划；大文本 split 自动拆 N 个分片执行 + 1 个聚合） | task_id、parent_id?、replace?、children[{goal, task_type, capability, output_schema, quality_target?, tool_allow?, depends_on?, type?, split?}] |
| cortex_execute | 路由执行（Gate0/1[/2]、缓存、记账；control 工作流控制） | task_id、node_id?/node_ids?、recursive?、mode?（costFirst|balanced|qualityFirst）、multi_vote?、max_parallel?、force_models?、evaluate?（none|gate2）、max_delegations?、control? |
| cortex_review | Gate3 批量验收（决策附节点质量/自检快照；Gate3.5 红队复核） | task_id、decisions[{node_id, status, reason_code?, missing_items?, next_action, recommended_depth?, confidence?}]、auto?、red_team? |
| cortex_probe | 部门与治理（探针/任务级模式/授权档/账本/派遣/ROI/待办与待批/人工介入/否决与解除/预算） | action（list\|show\|add\|enable\|disable\|policy\|assign\|mode\|authority\|authority-reset\|ledger\|verify\|dispatch\|roi\|intents\|intent-ack\|intent-resolve\|interactions\|interaction-ack\|interaction-resolve\|subscriptions\|approve\|veto\|lift）、task_id?、node_id?、probe_id?、mode?、policy?、reason? |
| cortex_recover | 恢复决策树（retry/switch/upgrade 引擎内重执行） | task_id、node_id? |
| cortex_policy | 成功任务沉淀策略 | task_id、note? |
| cortex_report | KPI 报表（任务/全局） | task_id? |
| cortex_models | 模型注册表/画像/路由评分/漂移/单价覆盖 | task_type?、capability?、model?、enabled?、refresh?、reset?、price?、clear_price? |
| cortex_evaluate | 模型评测（7 维×能力画像、性价比/Pareto） | cases?、use_saved?、models?、task_type?、quality_target? |
| cortex_eval_cases | 评测用例库（页面/对话共享） | action?（list|add|remove）、input、goal、capability、expected、output_schema、id |
| cortex_capabilities | 能力目录（只增不改不删） | action?（list|add）、name、description? |
| cortex_l0 | L0 确定性工具库（列表/生成/删除） | action?（list\|show\|add\|remove\|generate\|run）、keywords、allowed? |

2. 斜杠命令（/cortex ）

| 命令 | 说明 |
|---|---|
| /cortex status | 引擎状态：任务（含 running）、节点、尝试、策略、模型、编排纪律状态 |
| /cortex task  | 任务树（画像/策略/预算/节点树） |
| /cortex trace  | 执行轨迹（attempt + decision） |
| /cortex kpi [id] | KPI 报表（全局或单任务） |
| /cortex models [enable\|disable \|refresh\|reset\|set-price    [cached]\|clear-price ] | 注册表列表；reset 清评测回写恢复静态基准；enable/disable 启停；refresh 刷新动态发现；set-price/clear-price 设置/清除模型生效价（持久化，三级优先级） |
| /cortex policies [disable|enable ] | 策略库 + 受控启停（回滚：重新 enable） |
| /cortex model-pref [set  [偏好内容]\|clear\|show] | 模型偏好（含偏好内容=该模型适用哪些任务）：内容覆盖（≥50%）+ active + 质量 | 看门狗：跨工作区定时任务注入（at/after/every，≥300s）+ 目标达成自动评估改进循环（回注直至达标；连续 2 次评估失败 → 规则终态化 failed 可观测，remedy 回注失败 stall 不空转）；规则可设定时开始/中止（startAt/endAt，endAt 可留空=不限制）；工作区间为全局（ws window ，任务仅在区间内执行，支持跨午夜/days） |
| /cortex routing [suggest\|show\|apply\|rollback] | 路由权重学习：样本驱动权重建议（suggest）、查看当前（show）、一键应用（apply）、回滚（rollback）——由每节点路由样本 + 漂移驱动，学习链产出建议（应用前不生效） |
| /cortex budget | 预算再平衡：共享池余额 + 台账（动态回收/再分配，终态回收） |
| /cortex calibration | 评价器校准链：评审 vs 自检 vs 终态的历史矛盾样本 |
| /cortex org [mode  [task]\|dispatch [task]\|roi [task]\|intents\|ledger [probe]] | 部门与治理：任务级模式（或缺省改全局默认）、派遣优先级、部门回报率、待办与待批、账本查看 |
| /cortex gate  | 治理门：待人工回答的问题、批准挂起的关键操作、显式否决/解除、审查协议与提示模板 |
| /cortex control  [task] [node] | 阶段三工作流控制（准入队列快照 + 单任务/单节点控制）与审计清理 |
| /cortex tune [apply\|history] | 自优化建议（缺省 dry-run）/ 按护栏应用 / 台账 |
| /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/ · /api/tasks?limit&session · /api/events（SSE 实时）
/api/organization[?dispatch=] · /api/interactions · /api/control
/api/protocols[?task=] · /api/tune · /api/budget · /api/routing
/api/kpi-snapshots · /api/lang · /api/watchdog/calibration
POST /api/models/            {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/tasks/             （DELETE——删除历史任务及其节点/执行记录）
/api/tasks//control     {action: pause|resume|terminate|isolate|unisolate}
/api/control/purge          {kinds?, reason?}（审计清理，维护动作本身留痕）
/api/organization           {action: mode|assign|approve|intent-ack|intent-resolve|interaction-ack|interaction-resolve, ...}（白名单）
/api/interactions           {action: ack|resolve, id, note?}
/api/protocols              {protocol?|template?}（版本化追加式写入）
/api/lang                   GET → {value, writable, pushed, settingsFile}（控制台语言跟随 DSH 通用设置）
POST {lang} → 经官方设置服务写入宿主 locale 设置
/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）。
- 模型生效价覆盖（cortex_models.price/clear_price、UI 或 /cortex models set-price|clear-price）：用户设置的单价覆盖默认价，而模型/提供方权威价优先于两者；持久化（跨重启保留）并按生效价参与路由成本评分。

开发与测试

npm test                                   # node --test（引擎/服务/UI/看门狗单元 + 冒烟 + Mock 全流程）——512 个
node scripts/mock-flow-scenario.mjs        # Mock 完整流程场景矩阵（成功/失败/修正/恢复/治理/介入/部门×标准同构，9/9，零模型调用）
node scripts/org-scenario.mjs              # 部门探针与治理场景矩阵（含任务级组织模式，17/17，零模型调用）
node scripts/phase3-scenario.mjs           # 阶段三场景矩阵（队列/控制/协议/自优化，6/6，零模型调用）
node scripts/verify-http-org.mjs           # 治理 REST 端到端（含人工介入数据面与任务级模式，40/40）
node tools/verify-post-restart.mjs         # 重启后自检（8 项：含 JSONL 完整性/策略引用/学习链实体/人工介入通道）
node tools/verify-live.mjs [baseUrl]       # 实时实例自检（35 项，只读零模型调用）：页面标记（已下线 UI 不出现、新 UI 存在）+ 组织/介入/任务/控制/协议/自优化/总览 + 路由权重数据面与页面渲染 + 控制台语言跟随（/api/lang + 首屏标记） + 任务级模式字段
node scripts/verify-server.mjs             # 隔离控制台（缺省临时状态目录、退出即删；要看真实数据需显式传 CORTEX_VERIFY_STATE_DIR）
node tools/smoke-ui.mjs                    # 页面脚本语法 + SSE + 模型启停

版本与发布：版本取自 package.json；升版本（如 npm version patch）并推送到 main，在测试通过后会自动创建带版本信息的注解标签 v、基于 git log 生成 GitHub Release，并发布到 npm；标签推送不再二次触发 CI（无重复执行）。

目录结构

app-pkg/index.js   入口转发包装器（rollout 缓存穿透，与 dsh-tssdp 同模式）
app-pkg/client.js  浏览器端 bundle（侧边栏按钮 + 设置弹窗 section + 会话「任务」tab）
lib/index.js       插件入口（name/inject/apply + 生命周期、语言跟随桥）
lib/service.js     CortexService 门面（工具背后高层操作）
lib/tools.js       14 个智能体工具
lib/cli.js         /cortex 命令组
lib/ui-server.js   本地 Web 控制台（127.0.0.1:8788）+ 看门狗管理页
lib/locale.js      控制台语言桥（DSH 通用设置的 locale；读设置服务或 settings.yaml，写走官方设置服务）
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/probe/governance/protocols/interaction/queue/self-tune/task-view/bus/util）
config/models.yaml 模型注册表（可覆盖）
test/              node --test 测试（含 mock-flow：由 mock 宿主驱动的完整流水线）
scripts/           场景矩阵 + 共享 mock 宿主（mock-host.mjs 供测试与脚本复用）
tools/             验证/开发脚本

问题反馈

发现 Bug、描述不准确或想要的新功能？欢迎到 GitHub 提交 issue：

- 问题跟踪：https://github.com/iguowz/dsh-cortex/issues
- 请附上：DSH 版本、Cortex 版本（/cortex status 可查看）、执行的操作，以及完整的报错/轨迹输出。

问题、疑问与功能建议同样欢迎。

许可证

MIT