dsh-autotier 0.1.0

package/README.pt.md

@@ -0,0 +1,246 @@
+# dsh-autotier
+
+Roteamento automático por níveis de modelo para o DeepSeek Harness: entra uma
+instrução do usuário, sai uma decisão de nível — sem trocar de modelo à mão.
+
+A intenção complexa (arquitetura, planejamento, depuração, engenharia de várias
+etapas) é planejada no nível **strong** e depois implementada no nível **cheap**.
+A intenção simples (perguntas, recuperação, tarefas em lote, trabalho diário) é
+projetada e implementada diretamente no nível **cheap**. Enquanto o nível cheap
+executa, chamadas de ferramenta de alto risco são negadas por um guard
+determinístico, e falhas repetidas escalam para o nível strong com um TTL de
+retorno.
+
+- **Repositório oficial**: <https://github.com/PerryLink/dsh-autotier>
+- **npm**: `dsh-autotier` (nome simples, sem scope)
+
+## Compatibilidade
+
+| Harness | Estado |
+|---|---|
+| `@deepseek-ai/dsh` `0.1.2-rc.1` | compatível (é o que a CI verifica e o que o fluxo compat instala) |
+| `0.1.5-alpha.1` (a linha atual do checkout) | verificado por tipos contra suas faces publicadas; o smoke ponta a ponta roda em `0.1.2-rc.1` |
+| `@deepseek-ai/cordis` `^4.0.2`, `@deepseek-ai/schemastery` `^3.18.2` | base de peers |
+
+O plugin vive apenas no plano host e não precisa de preset próprio: a linha host
+vale para todas as sessões. Uma seção de prompt no *seu* preset é opcional e
+apenas torna as decisões visíveis ao modelo (veja [Instalação e desinstalação](#instalação-e-desinstalação)).
+
+## O que você recebe
+
+- **Portão de intenção** — cada turno é classificado por sinais determinísticos
+  (texto da mensagem, nomes de ferramentas, presença de imagens, tamanho da
+  conversa). A camada de regras decide sem gastar tokens quando tem confiança;
+  apenas um turno de baixa confiança chama o modelo juiz barato, e nunca dentro do
+  cooldown.
+- **Aterrissagem no seam oficial** — a decisão é aplicada na waterfall
+  `agent/request` retornando uma tripla provider/model/effort de substituição. Os
+  escalares de amostragem já escolhidos pela sessão (`temperature`, `maxTokens`,
+  `stop`) são preservados.
+- **Passagem para o modo plano** — uma instrução complexa entra em modo plano no
+  nível strong; ao sair, volta ao nível cheap para implementar.
+- **Guard de alto risco** — durante a execução cheap, comandos destrutivos
+  (`rm -rf`, `sudo`, `mkfs`, `git push --force`, escrita de arquivos de
+  credenciais, …) são negados com uma mensagem corretiva pedindo escalonamento.
+- **Escalonamento por falhas** — falhas repetidas (opcionalmente com a mesma
+  assinatura) elevam o nível por um TTL; uma falha de modelo/rota percorre a
+  cadeia de fallback configurada.
+- **Válvulas manuais** — `/tier auto|strong|cheap|off` e as ferramentas
+  `tier_status` / `tier_route`. Definir `routingMode: delegated` (ou `/tier off`)
+  interrompe o roteamento para uma sessão que precisa manter o próprio modelo.
+- **Serviço `ctx.autotier`** — uma superfície de leitura (`status`) mais a
+  waterfall de veto `autotier/route` e o evento `autotier/tier-changed`, para que
+  outros plugins observem ou anulem uma decisão.
+
+## Início rápido
+
+```bash
+npm i -g dsh1024
+dsh1024 plugin --profile web add dsh-autotier
+```
+
+Depois inicie (ou reinicie) o harness. A linha é acrescentada ao seu
+`cordis.patch.yml`; o roteamento começa no próximo turno.
+
+## Instalação e desinstalação
+
+**Canal npm**
+
+```bash
+npm i -g dsh1024
+dsh1024 plugin --profile web add dsh-autotier
+```
+
+**Canal git**
+
+```bash
+git clone https://github.com/PerryLink/dsh-autotier.git
+cd dsh-autotier && pnpm install && pnpm run build
+dsh plugin --profile web add .
+```
+
+**Seção de prompt opcional no preset.** O router funciona sem ela. Para que o
+modelo saiba em qual nível está, acrescente uma linha ao *seu* preset
+(`docs/preset-row.md` tem o bloco exato):
+
+```yaml
+- insert:
+    - id: autotier-prompt
+      name: '@deepseek-ai/dsh-system-prompt'
+      # sections: [...]  — veja docs/preset-row.md
+```
+
+**Desinstalação**
+
+```bash
+dsh plugin --profile web remove dsh-autotier
+```
+
+A linha, seu namespace de settings, seu comando, suas ferramentas e seus
+listeners são removidos com o plugin; nada é escrito fora do documento de
+settings.
+
+## Configuração
+
+Cada chave é validada na carga; um valor inválido falha ruidosamente em vez de
+desativar o roteamento em silêncio. O `cordis.patch.yml` deste repositório
+documenta as mesmas chaves em linha.
+
+| Chave | Padrão | Significado |
+|---|---|---|
+| `tiers.strong.provider` | `deepseek-official` | Provider do nível de planejamento/revisão. |
+| `tiers.strong.model` | `deepseek-v4-pro` | Id de catálogo do modelo strong. |
+| `tiers.strong.effort` | `high` | Vocabulário do adaptador `off` \| `low` \| `high` \| `max`. |
+| `tiers.strong.followSession` | `false` | `false` = o effort deste nível substitui o da sessão. |
+| `tiers.strong.fallback` | `[]` | Aterrissagens provider/model ordenadas se o nível estiver indisponível. |
+| `tiers.cheap.provider` | `deepseek-official` | Provider do nível de implementação. |
+| `tiers.cheap.model` | `deepseek-v4-flash` | Id de catálogo do modelo cheap. |
+| `tiers.cheap.effort` | `low` | Vocabulário do adaptador `off` \| `low` \| `high` \| `max`. |
+| `tiers.cheap.followSession` | `true` | `true` = herda o effort da sessão e a escolha explícita vence. |
+| `tiers.cheap.fallback` | `[]` | Aterrissagens provider/model ordenadas se o nível estiver indisponível. |
+| `tiers.vision.provider` | `deepseek-official` | Provider para turnos com imagens. |
+| `tiers.vision.model` | `deepseek-v4-flash-vision-exp` | O único modelo do catálogo com modalidade de imagem. |
+| `intent.ruleThreshold` | `0.7` | Confiança a partir da qual a camada de regras decide sozinha. |
+| `intent.attemptBand.enabled` | `false` | Começar a faixa média no cheap e escalar ao primeiro sinal. |
+| `intent.attemptBand.tauLow` | `0.45` | Limite inferior da faixa attempt-first. |
+| `intent.hysteresis.toStrong` | `0.8` | Pontuação que muda um turno cheap para strong. |
+| `intent.hysteresis.toCheap` | `0.6` | Pontuação abaixo da qual um turno strong volta para cheap. |
+| `intent.rules` | `[]` | Tabela declarativa de regras (`when.patterns` / `when.tools` / `when.cwd`, `tier`, `priority`). |
+| `intent.judge.enabled` | `true` | Permitir o juiz de baixa confiança. |
+| `intent.judge.model` | `''` | Id do modelo juiz; vazio = primeiro modelo do catálogo que contenha `flash`. |
+| `intent.judge.temperature` | `0` | Temperatura de amostragem do juiz. |
+| `intent.judge.maxTokens` | `16` | Limite de saída do juiz (responde com uma palavra). |
+| `intent.judge.cooldownMs` | `30000` | Intervalo mínimo entre duas chamadas ao juiz. |
+| `intent.judge.timeoutMs` | `2000` | Tempo limite da chamada ao juiz. |
+| `intent.judge.unavailableSkip` | `2` | Falhas consecutivas após as quais o turno omite o juiz. |
+| `intent.scenarios` | todos `true` | Interruptores por cenário: `coding`, `review`, `planning`, `retrieval`, `batch`, `daily`, `longText`, `multimodal`. |
+| `intent.costMode` | `balanced` | Arbitragem na ambiguidade: `cost-first` \| `quality-first` \| `balanced`. |
+| `guard.enabled` | `true` | Ativar o guard determinístico de alto risco. |
+| `guard.tiers` | `[cheap]` | Níveis que o guard protege. |
+| `guard.whitelist` | `[]` | Comandos, ferramentas ou prefixos de caminho que nunca disparam o guard. |
+| `guard.protectedPaths` | `['.dsh','AGENTS.md','package.json','.github/workflows']` | Superfícies de automodificação que forçam revisão strong. |
+| `guard.interopDefend` | `auto` | Relação com o `dsh-defend`: `auto` audita a convivência, `none` fica silencioso. |
+| `escalation.threshold` | `2` | Falhas dentro da janela que elevam o nível. |
+| `escalation.windowMs` | `60000` | Janela de contagem de falhas. |
+| `escalation.ttlMs` | `180000` | Quanto tempo um escalonamento permanece. |
+| `escalation.fallbackTtlMs` | `300000` | TTL usado após tomar uma aterrissagem de fallback. |
+| `escalation.signature` | `true` | Contar recorrências da mesma assinatura em vez de cada falha. |
+| `routingMode` | `auto` | `auto` \| `strong` \| `cheap` \| `delegated` \| `off`. |
+
+Todas as chaves também podem ser editadas a quente pelo namespace de settings
+`autotier` (`$DSH_HOME/settings.yaml`); uma escrita que viole um requisito
+cruzado é recusada ao salvar e a última política válida continua em vigor.
+
+## Ferramentas e superfícies
+
+| Superfície | Tipo | Propósito |
+|---|---|---|
+| `/tier` | comando | `auto` \| `strong` \| `cheap` \| `off` \| `status`; substituição por sessão. |
+| `tier_status` | ferramenta | Nível atual, modo, TTL de escalonamento e estado do guard. |
+| `tier_route` | ferramenta | Roteia uma intenção a seco, sem enviar requisição. |
+| `ctx.autotier` | serviço | Superfície `status()` para outros plugins. |
+| `autotier/route` | evento serial | Terceiros podem vetar o nível proposto. |
+| `autotier/tier-changed` | evento emit | Observabilidade quando o nível efetivo muda. |
+
+## Permissões e dados
+
+- **Arquivos** — o plugin não lê nem escreve nada além do serviço compartilhado
+  de settings (o namespace `autotier`).
+- **Rede** — o único tráfego de saída é a chamada ao juiz, que passa pelo caminho
+  normal de `ctx.llm` e pelo provider configurado.
+- **Log de sessão** — o plugin não anexa eventos de sessão próprios. O rastro de
+  roteamento é o logger do plugin mais o evento vivo `autotier/tier-changed`; a
+  única anexação é o `plan/mode` de reserva quando o serviço de modo plano não
+  está disponível. Tipos de evento próprios são fail-closed a partir de
+  `0.1.2-alpha.1`, então nenhum registro durável do plugin é escrito.
+- **Segredos** — este plugin não lê, registra nem armazena credenciais.
+
+## Limites de segurança
+
+- O guard é **defesa em profundidade**, não uma sandbox. Ele nega os padrões que
+  conhece no nível cheap e nunca enfraquece o `dsh-defend`, o serviço de aprovação
+  ou a política de sandbox. Mantenha-os ativos.
+- O guard protege apenas os níveis de `guard.tiers` (cheap por padrão). Um turno
+  strong não é bloqueado por design: o modelo strong é o revisor.
+- Se o próprio guard lançar, a chamada é escalada para strong em vez de permitida —
+  um guard quebrado não deve virar uma porta aberta.
+- `/tier off` desativa o roteamento por completo; o harness se comporta exatamente
+  como antes da instalação.
+
+## Limitações conhecidas
+
+- A camada de regras é determinística e portanto finita: uma frase nova para um
+  pedido complexo pode começar no cheap e escalar só após uma falha ou negação do
+  guard. A chamada ao juiz cobre o meio de baixa confiança.
+- O escalonamento é por agente e em memória; um reinício do harness volta a `auto`.
+- Trocar de nível reinicia o cache de prompt do provider para aquela requisição,
+  então sessões muito ativas podem ver um pequeno custo de falha de cache no turno
+  da troca; os limites de histerese existem para tornar isso raro.
+- O plugin roteia requisições de conversa. Compactação e geração de título são
+  seams separados do host; alinhe as configurações de modelo deles com o nível
+  cheap para o mesmo perfil de custo (`docs/supporting-lanes.md`).
+- `followSession: true` no nível cheap significa que uma escolha explícita de
+  modelo na sessão vence; nesse caso o nível cheap não pode impor o seu.
+- **Ainda não há cartão de Settings nem pílula do compositor.** O roteamento é
+  totalmente automático e a superfície host (`ctx.autotier.status()` /
+  `catalog()`, `/tier`, `tier_status`, `tier_route`) está completa; a metade do
+  navegador está planejada para v0.2.
+- **Um modelo escolhido na GUI não é detectado automaticamente.** Use
+  `routingMode: delegated` ou `/tier off` para interromper o roteamento.
+- **As posteriores por impressão digital ficam em memória** e reiniciam a cada
+  reinício.
+- **A faixa intermediária attempt-first vem desativada** até o corpus de
+  calibração existir (v0.2).
+
+## Desenvolvimento
+
+```bash
+pnpm install
+pnpm run typecheck      # contra as faces de tipo do checkout local do harness
+pnpm run typecheck:ci   # contra as faces publicadas 0.1.2-rc.1 (o que a CI executa)
+pnpm test
+pnpm run build
+pnpm run verify:self-contained
+pnpm run verify:artifacts
+pnpm pack
+```
+
+`pnpm run build` emite `lib/types` (declarações tsc) e `lib/index.js` (bundle
+tsdown). Os testes usam diretamente os pacotes host publicados — `Context` real,
+serviços reais de session/tools/commands/settings — mais uma composição real do
+Loader sobre um `cordis.yml` temporário.
+
+## Tópicos
+
+`dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `router`,
+`model-tier`, `cost`, `auto`.
+
+## Contribuidores
+
+PerryLink. Issues e pull requests em
+<https://github.com/PerryLink/dsh-autotier/issues>.
+
+## Licença
+
+Apache-2.0. Veja [LICENSE](./LICENSE) e
+[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).

package/README.zh.md

@@ -0,0 +1,221 @@
+# dsh-autotier
+
+DeepSeek Harness 的自动模型分档路由：一条用户指令进来，一个档位决策出去 ——
+无需手动切换模型。
+
+复杂意图（架构、规划、调试、多步工程）先由**强档**规划，再由**弱档**实施；
+简单意图（问答、检索、批量杂务、日常）直接由**弱档**设计并实施。弱档执行期间，
+高危工具调用会被确定性守卫拦截；连续失败则按 TTL 自动升级到强档。
+
+- **官方仓库**：<https://github.com/PerryLink/dsh-autotier>
+- **npm**：`dsh-autotier`（裸名，无 scope）
+
+## 兼容性
+
+| Harness | 状态 |
+|---|---|
+| `@deepseek-ai/dsh` `0.1.2-rc.1` | 兼容（CI 的类型检查与 compat 工作流安装的就是它） |
+| `0.1.5-alpha.1`（当前宿主 checkout 线） | 对照其已发布类型面做类型检查；端到端冒烟跑在 `0.1.2-rc.1` 上 |
+| `@deepseek-ai/cordis` `^4.0.2`、`@deepseek-ai/schemastery` `^3.18.2` | peer 基线 |
+
+本插件只驻留 host 平面，不需要自带 agent preset：host 行对所有会话生效。
+在你的 preset 中加一段提示是可选项，仅用于让模型看见路由决策
+（见[安装与卸载](#安装与卸载)）。
+
+## 功能
+
+- **意图门控** —— 每个 turn 都用确定性信号（消息文本、工具名、是否含图、
+  对话长度）分类。零 token 的规则层有把握时直接决策；只有低置信 turn 才会调用
+  廉价的裁判模型，且受冷却时间约束。
+- **落点在官方 seam** —— 决策在 `agent/request` waterfall 上通过返回替换后的
+  provider/model/effort 三元组生效；会话已选定的采样标量（`temperature`、
+  `maxTokens`、`stop`）保持不变。
+- **计划模式交接** —— 复杂指令在强档进入计划模式；退出计划模式后回到弱档实施。
+- **高危守卫** —— 弱档执行期间，破坏性命令（`rm -rf`、`sudo`、`mkfs`、
+  `git push --force`、写凭据文件等）会被拒绝，并给出"请先升级"的纠正信息。
+- **失败升级** —— 连续失败（可按同签名计数）会临时提升档位；模型/链路故障会沿
+  配置的回退链换档。
+- **手动逃生舱** —— `/tier auto|strong|cheap|off` 与 `tier_status` /
+  `tier_route` 工具。设置 `routingMode: delegated`（或 `/tier off`）可为必须保留
+  自身模型的会话关闭路由。
+- **`ctx.autotier` 服务** —— 精简的只读面（`status`），外加
+  `autotier/route` 否决 waterfall 与 `autotier/tier-changed` 事件，便于其他
+  插件观察或覆盖决策。
+
+## 快速开始
+
+```bash
+npm i -g dsh1024
+dsh1024 plugin --profile web add dsh-autotier
+```
+
+随后启动（或重启）harness。该行会被追加到你的 profile `cordis.patch.yml`；
+下一个 turn 起自动路由，无需其他配置。
+
+## 安装与卸载
+
+**npm 通道**
+
+```bash
+npm i -g dsh1024
+dsh1024 plugin --profile web add dsh-autotier
+```
+
+**git 通道**
+
+```bash
+git clone https://github.com/PerryLink/dsh-autotier.git
+cd dsh-autotier && pnpm install && pnpm run build
+dsh plugin --profile web add .
+```
+
+**可选的 preset 提示段**：不加也能工作。若想让模型知道自己跑在哪一档，在
+*你自己的* agent preset 中加一行（完整块见 `docs/preset-row.md`）：
+
+```yaml
+- insert:
+    - id: autotier-prompt
+      name: '@deepseek-ai/dsh-system-prompt'
+      # sections: [...]  — 见 docs/preset-row.md
+```
+
+**卸载**
+
+```bash
+dsh plugin --profile web remove dsh-autotier
+```
+
+该行、settings 命名空间、命令、工具与全部监听器都随插件移除；除设置文档外
+不会在别处留下任何写入。
+
+## 配置
+
+每个键都在加载期校验；非法值会响亮失败，而不是静默关闭路由。本仓
+`cordis.patch.yml` 内联注释了同一组键。
+
+| 键 | 默认值 | 含义 |
+|---|---|---|
+| `tiers.strong.provider` | `deepseek-official` | 规划/复审档的 provider。 |
+| `tiers.strong.model` | `deepseek-v4-pro` | 强档模型的目录 id。 |
+| `tiers.strong.effort` | `high` | 适配器词表 `off` \| `low` \| `high` \| `max`。 |
+| `tiers.strong.followSession` | `false` | `false` = 本档 effort 覆盖会话自身的设置。 |
+| `tiers.strong.fallback` | `[]` | 该档不可用时的有序 provider/model 落点。 |
+| `tiers.cheap.provider` | `deepseek-official` | 实施档的 provider。 |
+| `tiers.cheap.model` | `deepseek-v4-flash` | 弱档模型的目录 id。 |
+| `tiers.cheap.effort` | `low` | 适配器词表 `off` \| `low` \| `high` \| `max`。 |
+| `tiers.cheap.followSession` | `true` | `true` = 继承会话 effort，让显式选择优先。 |
+| `tiers.cheap.fallback` | `[]` | 该档不可用时的有序 provider/model 落点。 |
+| `tiers.vision.provider` | `deepseek-official` | 含图 turn 的 provider。 |
+| `tiers.vision.model` | `deepseek-v4-flash-vision-exp` | 目录中唯一支持图像模态的模型。 |
+| `intent.ruleThreshold` | `0.7` | 规则层可独立决策的置信度下限。 |
+| `intent.attemptBand.enabled` | `false` | 中间波段：先跑弱档，出现信号再升级。 |
+| `intent.attemptBand.tauLow` | `0.45` | attempt-first 波段的下界。 |
+| `intent.hysteresis.toStrong` | `0.8` | 弱档 turn 切到强档的分数。 |
+| `intent.hysteresis.toCheap` | `0.6` | 强档 turn 回落到弱档的分数。 |
+| `intent.rules` | `[]` | 声明式规则表（`when.patterns` / `when.tools` / `when.cwd`、`tier`、`priority`）。 |
+| `intent.judge.enabled` | `true` | 是否允许低置信裁判。 |
+| `intent.judge.model` | `''` | 裁判模型 id；空 = 取目录中第一个含 `flash` 的模型。 |
+| `intent.judge.temperature` | `0` | 裁判采样温度。 |
+| `intent.judge.maxTokens` | `16` | 裁判输出上限（只回答一个词）。 |
+| `intent.judge.cooldownMs` | `30000` | 两次裁判调用的最小间隔。 |
+| `intent.judge.timeoutMs` | `2000` | 裁判调用超时。 |
+| `intent.judge.unavailableSkip` | `2` | 连续失败多少次后本 turn 跳过裁判。 |
+| `intent.scenarios` | 全 `true` | 分场景开关：`coding`、`review`、`planning`、`retrieval`、`batch`、`daily`、`longText`、`multimodal`。 |
+| `intent.costMode` | `balanced` | 歧义裁决方向：`cost-first` \| `quality-first` \| `balanced`。 |
+| `guard.enabled` | `true` | 启用确定性高危守卫。 |
+| `guard.tiers` | `[cheap]` | 守卫保护的档位。 |
+| `guard.whitelist` | `[]` | 永不触发守卫的命令、工具或路径前缀。 |
+| `guard.protectedPaths` | `['.dsh','AGENTS.md','package.json','.github/workflows']` | 触发强档复核的自修改表面。 |
+| `guard.interopDefend` | `auto` | 与 `dsh-defend` 的关系：`auto` 审计共存，`none` 保持安静。 |
+| `escalation.threshold` | `2` | 窗口内达到该失败数即升级档位。 |
+| `escalation.windowMs` | `60000` | 失败计数窗口。 |
+| `escalation.ttlMs` | `180000` | 升级保持有效的时长。 |
+| `escalation.fallbackTtlMs` | `300000` | 已走回退落点后使用的 TTL。 |
+| `escalation.signature` | `true` | 按同签名复发计数，而非统计每次失败。 |
+| `routingMode` | `auto` | `auto` \| `strong` \| `cheap` \| `delegated` \| `off`。 |
+
+所有键也可通过 `autotier` settings 命名空间（`$DSH_HOME/settings.yaml`）热改；
+违反跨字段约束的写入会在保存期被拒绝，并保留上一份可用策略。
+
+## 工具与表面
+
+| 表面 | 类型 | 用途 |
+|---|---|---|
+| `/tier` | 命令 | `auto` \| `strong` \| `cheap` \| `off` \| `status`；会话级覆盖。 |
+| `tier_status` | 工具 | 当前档位、模式、升级 TTL 与守卫状态。 |
+| `tier_route` | 工具 | 对一段意图做干跑路由，不发送请求。 |
+| `ctx.autotier` | 服务 | 供其他插件读取的 `status()` 面。 |
+| `autotier/route` | serial 事件 | 第三方可否决拟定的档位。 |
+| `autotier/tier-changed` | emit 事件 | 生效档位变化时的可观测性事件。 |
+
+## 权限与数据
+
+- **文件** —— 本插件不读文件、不写文件，唯一的写入路径是共享 settings 服务的
+  `autotier` 命名空间。
+- **网络** —— 唯一的出站流量是裁判调用，走正常的 `ctx.llm` 路径与所配置的
+  provider。
+- **会话日志** —— 本插件不追加任何自定义会话事件。路由留痕 = 插件 logger 与
+  实时 `autotier/tier-changed` 总线事件；唯一的写入是 plan-mode 服务缺失时回退
+  追加的 `plan/mode`。`0.1.2-alpha.1` 起自定义事件类型 fail-closed，因此不会留下
+  插件自有的持久记录。
+- **凭据** —— 本插件不读取、不记录、不存储任何凭据。
+
+## 安全边界
+
+- 守卫是**纵深防御**，不是沙箱。它只拒绝弱档上已知的模式，绝不削弱
+  `dsh-defend`、审批服务或 sandbox 策略 —— 请保持它们开启。
+- 守卫只保护 `guard.tiers` 列出的档位（默认 cheap）。强档 turn 按设计不被拦截：
+  强模型本身就是复核者。
+- 守卫自身抛错时，调用会被升级到强档而不是放行 —— 坏掉的守卫不能变成敞开的门。
+- `/tier off` 完全关闭路由；harness 的行为与安装本插件之前完全一致。
+
+## 已知限制
+
+- 规则层是确定性的、因而也是有限的：复杂请求若换了说法，可能先落到弱档，只有
+  失败或守卫拒绝之后才升级。低置信的中间地带由裁判调用覆盖。
+- 升级状态按 agent 保存在内存中；harness 重启后从 `auto` 重新开始。
+- 切换档位会重置该请求的 provider 提示缓存，因此极高频会话在切换 turn 可能看到
+  少量缓存未命中成本；迟滞阈值的存在就是为了让这件事少见。
+- 本插件只路由对话请求。压缩与标题生成是宿主独立的 seam；若想获得同样的成本
+  画像，请把它们各自的模型设置对齐到弱档（`docs/supporting-lanes.md`）。
+- 弱档 `followSession: true` 意味着会话中显式选择的模型优先；此时弱档无法强制
+  使用自己的模型。
+- **暂无 Settings 卡片与 composer 胶囊**。路由已完全自动，host 面
+  （`ctx.autotier.status()` / `catalog()`、`/tier`、`tier_status`、
+  `tier_route`）已完整；浏览器半计划于 v0.2。
+- **GUI 里改选模型不会被自动识别**。请用 `routingMode: delegated` 或
+  `/tier off` 关闭路由。
+- **指纹后验仅存于内存**，重启后重新学习。
+- **attempt-first 中间波段默认关闭**，待校准语料落地后（v0.2）开启。
+
+## 开发
+
+```bash
+pnpm install
+pnpm run typecheck      # 对照本地 harness checkout 的类型面
+pnpm run typecheck:ci   # 对照已发布的 0.1.2-rc.1 类型面（CI 实际执行）
+pnpm test
+pnpm run build
+pnpm run verify:self-contained
+pnpm run verify:artifacts
+pnpm pack
+```
+
+`pnpm run build` 产出 `lib/types`（tsc 声明）与 `lib/index.js`（tsdown 打包）。
+测试直接使用已发布的宿主包 —— 真实 `Context`、真实 session/tools/commands/
+settings 服务 —— 外加一次针对临时 `cordis.yml` 的真实 Loader 组合。
+
+## 主题
+
+`dsh`、`dsh-plugin`、`deepseek-harness`、`deepseek`、`cordis`、`router`、
+`model-tier`、`cost`、`auto`。
+
+## 贡献者
+
+PerryLink。欢迎在 <https://github.com/PerryLink/dsh-autotier/issues> 提 issue
+或 PR。
+
+## 许可证
+
+Apache-2.0。见 [LICENSE](./LICENSE) 与
+[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)。

package/SECURITY.md

@@ -0,0 +1,55 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please **do not** open a public issue for security vulnerabilities.
+
+Report privately through GitHub's private vulnerability reporting:
+
+**https://github.com/PerryLink/dsh-autotier/security/advisories/new**
+
+That flow keeps the report confidential while we triage, and it is the channel we
+watch first.
+
+## Before you report
+
+- **Redact sensitive data** from any logs, session excerpts, or config files you
+  attach: tokens, API keys, secrets, webhook URLs with credentials,
+  Authorization headers, personal paths, and account identifiers.
+- Include, when possible: the plugin version, the harness (`dsh`) version, Node
+  and OS versions, and the minimal steps to reproduce.
+
+## What to expect
+
+- **Acknowledgment**: within 5 business days.
+- **Assessment**: we reproduce and classify the report, then tell you whether it
+  is a vulnerability in this plugin, in the harness, or a configuration issue.
+- **Fix**: security fixes ship as a patch release with a CHANGELOG entry; we
+  credit reporters who ask to be credited.
+
+## Scope
+
+In scope:
+
+- The high-risk guard bypassing or weakening a denial it claims to enforce.
+- A routing decision that silently sends data to an unintended provider.
+- Credential or secret leakage through logs, events, or the settings namespace.
+- A listener, tool, command or settings namespace surviving plugin disposal.
+
+Out of scope:
+
+- The guard not knowing a destructive command you did not configure. The guard is
+  defence in depth and never replaces `dsh-defend`, the approval service, or the
+  sandbox policy.
+- Denial-of-service through a deliberately hostile settings document; invalid
+  values fail loudly at load time by design.
+- Vulnerabilities in the harness itself — report those to
+  <https://github.com/deepseek-ai/deepseek-harness/security>.
+
+## Hardening advice
+
+- Keep `dsh-defend`, the approval service and the sandbox policy enabled.
+- Review `guard.protectedPaths` for your own workspace and add the paths whose
+  modification should always be reviewed on the strong tier.
+- Use `/tier off` to disable routing entirely if you need the pre-install
+  behavior.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,63 @@
+# Third-party notices
+
+## dsh-tier-router (`lib/pure.js`)
+
+The high-risk command guard in `src/guard-rules.ts` is a port of the rule table
+in `lib/pure.js` from
+[dsh-tier-router](https://github.com/BruceLanLan/dsh-tier-router) (v0.5.0),
+licensed **MIT**:
+
+```
+MIT License
+
+Copyright (c) 2026 BruceLanLan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+The port keeps the upstream command/path vocabulary and pattern semantics and
+adds: tier-conditional enforcement (the guard protects the cheap tier only), a
+configurable whitelist, `guard.protectedPaths` review escalation, and a
+structured denial reason. No upstream file is bundled verbatim; the port is
+annotated per module with the source file and version.
+
+### Deliberate deltas over upstream
+
+These are this plugin's own additions (Apache-2.0), not upstream code:
+
+1. **Shell-wrapper re-scan.** Upstream misses `sh -c "rm -rf /"` (the payload is
+   quoted, so the command-position anchor never sees `rm`). `matchCommand` first
+   applies the upstream rules unchanged, then re-scans the `-c` payload of
+   `sh|bash|zsh|dash|ksh` (including combined flag clusters such as `-lc`,
+   case-insensitive names, an optional leading backslash, and a preceding runner
+   with its own arguments), bounded to three nesting levels. An inner match is
+   reported as `shell-wrapper:<inner rule id>`. `hasRecursiveForceRm` itself
+   stays byte-for-byte upstream, and the upstream false negative is asserted in
+   the test suite as a documented regression.
+2. **Fallback classification split.** Upstream's `classifyFallback` tri-state is
+   split into `permanent`/`transient`/`ignore`/`unknown` so the request-error
+   handler can honour its division of labour with `dsh-llm-retry` (permanent
+   codes switch the chain immediately; transient codes wait for retry
+   exhaustion).
+3. **Effort vocabulary.** Upstream's `['medium', 'high', 'max']` ladder is
+   replaced by the adapter-owned `off | low | high | max`; `medium` does not
+   exist on this host and would fail every request.
+
+The read-only reference checkout used for the port lives outside this repository
+and is never shipped.