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

[![npm version](https://img.shields.io/npm/v/dsh-cortex)](https://www.npmjs.com/package/dsh-cortex) [![npm downloads](https://img.shields.io/npm/dm/dsh-cortex)](https://www.npmjs.com/package/dsh-cortex) [![license](https://img.shields.io/npm/l/dsh-cortex)](https://github.com/iguowz/dsh-cortex/blob/main/LICENSE)

[English](./README.md) | **中文** | [npm 包](https://www.npmjs.com/package/dsh-cortex) | [GitHub](https://github.com/iguowz/dsh-cortex)

Cortex 是一个 [DeepSeek-Harness](https://npmjs.com/package/@deepseek-ai/dsh) 插件，让宿主的**主模型（强模型）**变成**高杠杆监督者**：主模型负责规划、拆解、验收与纠偏；**被路由的执行模型（低成本小模型，如 `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` 批量验收 · **Gate3.5 红队复核** | 硬门槛：format_validity / safety / groundedness < 0.5 直接失败；验收决策携带节点质量/Gate1 自检快照；红队对将被接受的高影响节点（S/M、risk≥0.5 或质量≥0.9）对抗性质证——命中实质缺陷 → 降级 retry |
| 恢复引擎 | `cortex_recover` | 失败标准化分类 → 重试 / 切换 / 修正重试 / 拆分 / 升级 / 人工 + 失败模式学习 |
| 软缺陷纠偏 | `cortex_execute` / `cortex_recover` | 软上限 `max_delegations`（缺省 3）：有能力但结果不足时**就地纠偏**（同模型 → 换更优模型 → 升级给主模型）；可选 **continuable 子会话**（`config.continuableCorrection`）跨轮保留上下文；硬失败仍走类型恢复 |
| 模型单价覆盖 | `cortex_models` / UI / CLI | 设置/清除模型生效价（`price`/`clear_price`，或 `/cortex models set-price|clear-price`）——**三级优先级：模型/提供方权威价 > 用户设置 > 默认价**；持久化，路由按生效价计价 |
| 预算控制 | 引擎内置 | 四池 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 <HH:MM-HH:MM>`，支持跨午夜/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 安装（已发布）：**

```bash
# 作为依赖安装插件包
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_* 工具已可用
```

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

```bash
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. 智能体工具（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 <id>` | 任务树（画像/策略/预算/节点树） |
| `/cortex trace <id>` | 执行轨迹（attempt + decision） |
| `/cortex kpi [id]` | KPI 报表（全局或单任务） |
| `/cortex models [enable\|disable <id>\|refresh\|reset\|set-price <id> <in> <out> [cached]\|clear-price <id>]` | 注册表列表；`reset` 清评测回写恢复静态基准；enable/disable 启停；refresh 刷新动态发现；`set-price`/`clear-price` 设置/清除模型生效价（持久化，三级优先级） |
| `/cortex policies [disable|enable <id>]` | 策略库 + 受控启停（回滚：重新 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|status` | 本地控制台管理 |
| `/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 org [mode <standard\|department\|auto> [task]\|dispatch [task]\|roi [task]\|intents\|ledger [probe]]` | 部门与治理：任务级模式（或缺省改全局默认）、派遣优先级、部门回报率、待办与待批、账本查看 |
| `/cortex gate <interactions\|approve\|veto\|lift\|protocols>` | 治理门：待人工回答的问题、批准挂起的关键操作、显式否决/解除、审查协议与提示模板 |
| `/cortex control <status\|pause\|resume\|terminate\|isolate\|unisolate\|purge> [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/<id> · /api/tasks?limit&session · /api/events（SSE 实时）
     /api/organization[?dispatch=<taskId>] · /api/interactions · /api/control
     /api/protocols[?task=<id>] · /api/tune · /api/budget · /api/routing
     /api/kpi-snapshots · /api/lang · /api/watchdog/calibration
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/tasks/<id>             （DELETE——删除历史任务及其节点/执行记录）
     /api/tasks/<id>/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`）：用户设置的单价覆盖默认价，而模型/提供方权威价优先于两者；持久化（跨重启保留）并按生效价参与路由成本评分。

## 开发与测试

```bash
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<version>`、基于 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