@mstar-harness/dsh

dsh plugin --profile web add @mstar-harness/dsh

@mstar-harness/dsh

[English](README.md) | 中文

让 Morning Star 成为一等公民的 dsh（DeepSeek Harness）宿主——一个 cordis 函数插件，将 mstar engine 进程内挂载，实现 engine HostAdapter（host: 'dsh'），守护 {HARNESS_DIR}/status.json 写入（校验 + 咨询；hard 下按修复逃生放行），在 Enforcement: hard 开启时阻止被禁止的 subagent 派发，对挂载技能根下的 SKILL.md 写入执行技能撰写 lint，通过 dsh skill-filesystem 提供者挂载 mstar skills/ 镜像（单一规范挂载），并向每个组合后的 agent 步骤追加一条持久化的 mstar-engine catalog 行（持久化日志的读取方也接受旧标识 mstar-engine-status）。随 dsh Loader 应用启动；一切均通过 seam 的拒绝/咨询通道行使职责，从不改动工具本身。

本插件的运行时要求来自 dsh 宿主：宿主提供的运行时必须提供 mstar store 所需的原生 node:sqlite 模块（store 闸门强制的是这项能力）。Bun 宿主不做版本闸门 —— workspace 各 manifest 里的 engines.bun 只是开发工具链声明 —— store 的 Node 版本下限只作用于 Node 入口。本包不额外要求 Node。

Usage

dsh 应用如何使用本插件——安装路径、配置、挂载时发生什么、强制执行语义。

Install paths

本包以 workspace 包形式发布（workspaces: ["packages/*"]），构建时把 engine 打进 dist/（bun run build；dist 已被 gitignore）。安装途径是 profile bundle，装进现成的 web profile（dsh --profile web——开箱即用的 web 应用 profile，即 dsh web），经 dsh.bundle.patch 清单——一个叠在 dsh-base 默认层之上的补丁层。该补丁还挂载一行宿主中立的 MCP 服务器——即整个宿主共享的 mstar-mcp 连接；需要固定 harness 根的部署用 mstar mcp --harness <绝对路径> 启动它（挂载契约见 [bundle/README.md](bundle/README.md)）。

一条命令的 CLI 入口（推荐）——npx @mstar-harness/cli init --target dsh 一次性装齐全量能力：它按序运行下面两条 dsh plugin --profile web add 安装（先 mstar bundle，再 dsh-llm-fallbacks），并可用 npx @mstar-harness/cli doctor --target dsh 逐行报告 uninstalled / disabled / mounted / drifted（drifted = fallbacks 行的安装版本不等于 pin；init --target dsh 会按 pin 重新 add，在此之前 doctor 以非零退出）。它编排的仍是同一条双命令安装；--no-fallbacks 跳过第二行（连带跳过 seeded 角色——见下文「零配置获得什么」）。

（a）registry 安装（发布形态）——npm 包自带构建好的 dist/（安装时无需构建）：

dsh plugin --profile web add @mstar-harness/dsh

（b）local checkout 安装（开发）——包检出本身，用于迭代插件：

cd <repo>/packages/dsh
dsh plugin --profile web add .

dsh plugin --profile <name> add <spec> 首次使用时初始化 profile（web 从出厂模板起步：@deepseek-ai/dsh-base + @deepseek-ai/dsh-web-app），把 <spec> 转发给 profile 目录中的 pnpm，并按已安装状态对账 dsh.profile.bundles 层列表：任何 package.json 声明 dsh.bundle 的依赖都会加入层栈。相对 spec（.、file:/link:）锚定调用目录，因此 add . 须在包检出目录内执行；pnpm 须在 PATH 上。local checkout 需要先执行过 bun run build（本包不使用 prepare 脚本——monorepo 与 cli/opencode 一致，显式构建各包）。细节、层位置与出厂默认见 [bundle/README.md](bundle/README.md)——registry 与 local checkout 形态均走同一 pnpm + reconcile 机制。cordis 与 @deepseek-ai/dsh-* 各 seam 均为 peerDependencies——由组合后的 dsh 应用提供。

（c）可选能力：dsh-llm-fallbacks（第二条命令）——基于角色的 subagent 配置能力（见 LLM fallbacks integration）是独立的插件行，须以单独命令安装：

dsh plugin --profile web add dsh-llm-fallbacks

双命令安装即契约——把 dsh-llm-fallbacks 行折叠进本 bundle 的补丁明确否决（roadmap §8.3 F4）：loader 没有 insert-if-absent 语义，因此同 id 插入是 duplicate loader entry id 启动失败（整个 dsh 会话无法启动）；异 id 插入则插件被挂载两次——对同时直接安装该包的人，会出现两次 apply() 与分裂的 fallback 状态（各自独立的 state store、双份监听器、配置覆盖抽签）。层序为 reconcile 追加序：dsh-llm-fallbacks 落在 dsh-base/llm-retry 之后（其硬性排序要求）并位于 mstar 行之后。单命令多激活是上游功能缺口（reconcile 去重或 insert-if-absent 补丁语义），本仓库无法实施。

零配置获得什么——两条行都装上后（经 CLI 入口或上面两条命令），mstar 插件在 boot 时把 13 个 mode: subagent 的 mstar 角色种子（从打包的 harness-agents/ 镜像派生，排除 project-manager）声明进 fallbacks taxonomy：每个 seeded 角色的 persona 默认取其镜像 description 外加一行强制角色加载引导；seeded 状态保持可 revert（fallbacks/revert-seed 网关 / settings 回滚按钮）；运行时 advisory 报告缺失 id 与 persona 覆盖。该 seeds 机制即 B4——installed-deployment e2e（tests/install-e2e.spec.ts）本轮把验证闭环：真实 init --target dsh 安装进临时 DSH_HOME、从安装产物 boot，断言 13 个 id 全部出现在 effective taxonomy 且 persona 非空。不含模型路由、不含 automatch 派发、不含 dsh-tui。

被派发子代理的角色身份需要部署方的一处声明。 dsh 0.2.1 通过选择 agent preset 交付子代理身份，因此角色匹配的派发会选择 rolePresets 为该角色映射的 preset。请为每个角色声明一份完整 preset（@deepseek-ai/dsh-agent-preset 行，其 plugins 挂载 @deepseek-ai/dsh-persona 并携带该角色的 persona 文本——persona、工具与技能都在该组合内），并把其 id 列进插件的 rolePresets。未映射的角色保持委派方的组合——不会有任何故障，只是子代理不携带角色身份。详见下文《角色身份交付》。

fresh publish 年龄窗口提示：pnpm 的 minimumReleaseAge 门禁可能让 dsh plugin add <spec> 的 range 解析在全新发布后约 24h 内选中旧版本（不含 seeds surface）——窗口过后重跑 npx @mstar-harness/cli init --target dsh（或显式 pin 版本）即可收敛到最新 surface。

Headless profile（一次性运行）

本插件并非 web 专属：它同样可以挂载进 dsh headless profile（dsh --profile headless "<task>"——一次性、无 GUI/无端口模式）。安装路径完全一致，一条命令：

dsh plugin --profile headless add @mstar-harness/dsh

出厂 headless 模板在首次使用时自动初始化（@deepseek-ai/dsh-base + @deepseek-ai/dsh-headless），reconcile 步骤把 mstar 行追加进 bundle 层栈（dsh-base → dsh-headless → @mstar-harness/dsh）。插件的所有能力都落在 headless 继承的 dsh-base seam 上——status/dispatch/lease/worktree 闸门、技能挂载、engine-status catalog、harness-rules system-prompt 注入、三个原生工具——因此在一次性运行中 harness 完整生效。必须从仓库工作目录启动（runner 写入 meta.cwd = process.cwd()，按工作区的 harness 目录探测从这里开始）。浏览器客户端半体仅属于 web profile，headless 下自然不加载。

Headless 使用注意事项（已在 dsh 0.1.0-rc.6 上验证）：

• 一次性 turn 模型——runner 把任务作为一条 user message 提交，agent 转入 idle（whenIdle()）后即退出；它不会等待 run_in_background 子任务。前台 subagent 派发可用（创建子会话、结果回到父会话）；后台 QC-tri 式并行在进程内不会完成——要么前台派发 QC 席（串行墙钟时间），要么让 agent 在结束 turn 之前用 tool-subagent-control 收集完后台结果。
• 无交互通道——没有可用应答者时，ask_user_question 与审批提示会 fail-closed。无人值守运行应保留受限权限预设（workspace-write 搭配 approval ask，或使用 read-only 进行只读检查），并在开始工作前核实会话实际生效的权限。仅执行该边界内已允许的操作；若某项操作需要审批，停止该操作并通过 web profile 获取审批。不要通过解除沙箱限制来绕过缺失的审批通道。交互式 Prepare 流程（grill-me）属于 web profile。
• 默认模型解析——headless 不组合 fallbacks 行，因此 settings 里 agent-default-model 钉在 FallbacksChain 会以 NO_ADAPTER 失败（web profile 的产物）。把默认模型指向真实 provider，或同样把 dsh-llm-fallbacks 装进 headless profile（注意：已发布的 dsh 0.1.0-rc.6 上，fallbacks 的 settings 集成早于 SettingsProvider.installSection API，虚拟适配器不会注册——随 dsh ≥ 0.1.2-alpha 解决）。

Configuration

Key · Type · Default · Meaning

harnessDir · string · 仓库 .mstarc [config] harness_dir，否则按会话工作区探测（.mstar/ → .agents/ → .plans/ → plans/，从会话工作区根目录开始——绝不从启动 cwd） · 显式 harness 根目录；优先于 engine 探测。**harness 根不在探测名列

…(truncated)