一句话定位

这是 Morning Star（启明星）多代理协作框架的 dsh（DeepSeek Harness）宿主插件。它把一套带状态机的工作流引擎挂到 dsh 内部：在写入 harness 状态文件、派发子代理、修改技能文档等关键节点自动校验，并在 dsh 对话窗口右侧渲染一个可视化的工作流面板。

核心能力

• 守护 harness 状态文件写入：拦截对 {HARNESS_DIR}/status.json 的写入请求，按当前文档做完整性校验与残留清理检查，违规时通过 dsh 的拒绝通道返回决策
• 校验子代理派发：拦截 subagent / subagent_fork 工具调用，按工作流约束判断该派发是否合法，在"硬约束"模式下可拒绝不合规派发（含反自递归预检）
• 自动注入角色人设：监听 dsh 子代理启动事件，把对应角色的描述作为系统提示片段注入子代理上下文
• 挂载技能目录：以独立的技能提供者身份把 mstar 的 skills/ 镜像挂到 dsh，让 dsh 能识别并调用 mstar-* 系列技能
• 输出引擎状态目录：每次模型推理前向对话上下文追加一行 mstar-engine-status 摘要（含迭代阶段、当前计划、剩余项、合规策略等）
• 暴露四个工作流斜杠命令：注册 /iteration-start、/iteration-drive、/iteration-loop、/codebase-audit，无需离开 dsh 即可启动/恢复多计划迭代
• 在对话窗口右侧渲染"MStar 工作流"面板：以画布形式展示当前迭代阶段、计划看板与代理流转状态

技术实现

• 语言: TypeScript
• 关键依赖: @deepseek-ai/cordis（插件容器）、@mstar-harness/engine（共享工作流引擎）、@deepseek-ai/dsh-skill-filesystem（技能挂载通道）、schemastery（配置校验）
• 架构模式: dsh cordis 扩展插件（named export + apply 钩子），通过 fs 写入拦截、工具预执行拦截、subagent 启动事件、agent 推理前目录注入四个 dsh 官方扩展面工作，零 dsh 本体修改
• 入口文件: packages/dsh/src/index.ts（DSH 子包）；根 package.json 的 main 指向 packages/opencode/src/mstar.ts（OpenCode 宿主入口，本插件不涉及）

适用场景

使用 dsh（DeepSeek Harness）的多代理项目，需要让多个代理（PM、QC、QA、开发者角色）按一致的状态机和阶段门禁协作。当前的痛点是 dsh 自带的派发工具只负责"派一个代理去干活"，无法保证每个派发都符合整体计划的工作流约束；装上这个插件后，所有派发和状态写入都会被引擎先审核一遍，并把当前进度可视化出来。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:btspoony/mstar-harness

安装命令格式由 dsh 官方插件规范规定；上述命令会把 @mstar-harness/dsh 加入 web profile 的 bundle 列表并自动重建挂载。也可使用一行式 CLI 安装：npx @mstar-harness/cli init --target dsh，会自动顺带安装 dsh-llm-fallbacks。

配置项

所有字段都可省略，省略时按"硬编码默认"或"运行时探测"工作。

常见问题

Q: 安装之后 dsh 启动变慢了吗？

A: 影响极小。引擎状态目录默认 60 秒刷新一次，热路径只是时间戳比对加 Map 查询；只有在第一次或缓存过期时才会重读 harness 文件。

Q: 派发门禁会不会"误杀"我合法的派发？

A: 默认是 warn 模式，只警告不阻止；只有当你在迭代 compass 中显式开启 Enforcement: hard、或在配置中写 enforcement: hard 时才会真正拒绝。硬模式下被拦截会附带具体原因，按提示修改即可。

Q: 反自递归预检怎么配置才生效？

A: 在你的 dsh 配置里给插件的 mstar 行加上 dispatchBinding: '<发起派发的 mstar 角色名>'，例如 dispatchBinding: fullstack-dev。没配置就跳过预检，不会误报。

Q: 我看到 dsh 多了一个"MStar 工作流"标签页，怎么关掉？

A: 它来自插件包内的浏览器端 client bundle（packages/dsh/src/client/），由 dsh web profile 自动加载。如果你不需要，把 @mstar-harness/dsh 从 profile 移除后重启 dsh 即可。

Q: 我能修改插件内的角色人设或技能目录吗？

A: 可以。两种方式：编辑 dsh profile 层的 cordis.patch.yml，在 mstar 行的 config 里加 rolePersonas / bundledSkillDir 覆盖；或者修改仓库根目录的 skills/、agents/ 后跑 bun run bundle-assets 重新打包。

Q: 报错 "persona contains {{...}}" 怎么办？

A: dsh 系统提示渲染器对 {{ 与 }} 做严格变量插值，你在 rolePersonas 写的文本里若出现成对的大括号就会被拒。把双大括号改成单大括号、或换个写法即可；孤立的 {{（没有配对的 }}）是安全的。

Q: 跟 dsh 升级冲突吗？

A: 不会。插件不修改 dsh 本体，dsh 升级后只需 bun run build && dsh plugin --profile web add . 重新挂一次（或重新 add 远端版本）。如果升级的是 dsh 0.1.0-rc.7 之前版本，则可能需要先升级 dsh。

上手难度

进阶 — 需要理解 mstar 的状态机概念（{HARNESS_DIR}/status.json、iteration compass、QC/QA gate），普通 dsh 用户多数情况下装上即用，但要让"硬约束"真正生效就需要读懂 compass 元数据。

已知问题与限制

• 状态文件写入拦截是"内容盲"的：fs 写入事件只携带目标路径与代理，不带新内容，所以"把好文档改坏"的那一次写入无法被拦；修复方式是手动改回正确格式，或删除 status.json 让 harness 重建
• 反自递归预检依赖 dispatchBinding 配置：未配置时直接跳过，多角色派发方需要为每种角色分别部署配置
• 技能内置镜像在构建时同步：如果你是从源码安装但没跑 bun run bundle-assets，则没有内置技能也没有内置命令，但不会报错
• {{ 与 }} 的内容不能写在 rolePersonas 中，否则插件挂载阶段就会被 schemastery 校验拒绝
• 对 workflow/ralph 工具调用做门禁时，未配置 workflowNames 等同于"全部未知"，所以第一次跑新工作流会被标记
• 内容盲技能 lint 也有同款盲区：fs 写入事件不带内容，所以"首次创建的内容不合规"或"好文档被覆盖"无法拦截
• lintSkillWrite 的硬拦截错误类已实现但当前 dsh 还没有"带内容"的技能写入钩子，所以只能以"repair escape"形式给出告警
• 角色→模型的自动路由功能未交付：当前插件只注入人设，不会改写子代理的模型选择；该能力依赖上游接口
• design-md 命名匹配是全局 basename 匹配（任意目录下的 DESIGN.md 都会触发设计系统校验），可能对不相关项目产生噪音告警

Morning Star is an Agent Plugin for harness engineering workflows: a TypeScript Harness Workflow Engine (@mstar-harness/engine) enforces deterministic workflow gates, while mstar-* judgment skills drive multi-agent code delivery.

• Deterministic gates, enforced by a TS engine — path/status/lease/dispatch/sdd/iteration/lint gates run in @mstar-harness/engine, not as prompt suggestions
• Judgment stays in mstar-* skills — skills remain the single source of truth (SSOT) for roles, gates, and workflow judgment
• One engine across hosts — the same engine + skills power dsh (DeepSeek Harness), omp, OpenCode, Cursor, Kimi Code, ZCode, and Codex
• Agent Plugin packaging — one-command install; portable across any Agent Plugins v1.0.0 client
• Recommended host (best → usable): dsh = omp ≥ OpenCode ≥ Cursor > Kimi = ZCode > Codex

What ships

Release notes: CHANGELOG.md / CHANGELOG_CN.md.

Install

Engine gate checks (optional)

npm i -g @mstar-harness/cli

Puts the mstar-harness binary (short alias mstar) on PATH, so the engine-check commands the skills cite (mstar status validate, mstar dispatch validate, mstar iteration gate, …) actually run.

Without a global install the harness still works and those checks stay advisory. Set enforcement: hard in an iteration compass to make dispatch preflights fail-fast.

Caution: mstar is a short alias and a shared bin namespace — an unrelated third-party npm package named mstar claims the same command name. The alias exists only where @mstar-harness/cli is installed: bare npx mstar … without the package resolves via the registry to that other tool, and globally co-installing both packages silently overwrites the mstar shim (last install wins). The canonical invocation name stays mstar-harness — use the long name on any conflict.

Verify

npx @mstar-harness/cli doctor --target <opencode\|cursor\|codex\|zcode\|omp\|dsh>.

The repo ships a portable Agent Plugins v1.0.0 manifest (plugin.json) at its root; skills/ is the Agent Skills component — verify it with npx @mstar-harness/cli plugin validate.

Manual install / path layout: INSTALL.md. CLI flags: docs/cli.md.

Use

Three entry shapes: without iteration (single plan / hotfix), with iteration (multi-plan Phase 1–5), or codebase audit (discover what to do).

General (without iteration)

Enter PM, then run the per-plan cycle: Prepare → Execute → QC → QA gate → Done.

Iteration

Codebase audit

Command loading

Phase 2 defaults: per-plan worktree + lease, Findings cleanup: zero-residual. Override only with explicit Worktree mode: waived / Findings cleanup: allow-residual. SSOT → mstar-iteration, mstar-branch-worktree, mstar-plan-artifacts.

Project knowledge bootstrap: mstar-compound-refresh → references/project-knowledge-bootstrap.md.

Harness Workflow

flowchart TD
    A["PM: entry and intent clarification"] --> B{"PM: spec and context ready"}
    B -->|No| C["PM: clarify and refine requirements"]
    C --> B
    B -->|Yes| D["PM: initialize/load HARNESS_DIR and PLAN_DIR"]
    D --> E{"Iteration scope needed"}
    E -->|Deep / first iteration| F["iteration-start: grill-me → compass → review → lock"]
    E -->|Fast autonomous loop| F2["iteration-loop: Phase 1→5 continuous"]
    F --> G["PM: lock compass and create integration branch"]
    F2 --> G
    G --> H["Phase 2→5: execute → close → PR → merge-ready"]
    E -->|No| I["PM: select active plan from status.json"]
    H --> I
    I --> J{"Any plan not Done"}
    J -->|Yes| K["PM: dispatch one plan on a feature branch"]
    K --> L["Dev roles: implement and report"]
    L --> M["PM: update plan and status.json"]
    M --> N["QC trio: review gate"]
    N --> O{"QC decision"}
    O -->|Request Changes| K
    O -->|Approve| P{"QA gate"}
    P -->|mandatory| P1["qa-engineer: acceptance verification"]
    P -->|pm-acceptance| P2["PM: acceptance checklist"]
    P1 --> Q{"Residual findings remain"}
    P2 --> Q
    Q -->|Yes| R["PM/QA: register or accept residuals in status.json"]
    R --> S["PM: mark plan Done and merge to integration branch"]
    Q -->|No| S
    S --> T["PM: sync compass plan status"]
    T --> J
    J -->|No| U["iteration-close: close entry checklist"]
    U --> V["PM: compound round and knowledge index"]
    V --> W["PM: update roadmap and compass completed frontmatter"]
    W --> X["PM: close exit checklist and commit"]
    X --> Y["Phase 4: create PR"]
    Y --> Z["Phase 5: merge-ready loop until CI green and reviews resolved"]

Without iteration: same per-plan gates, no iteration-start / iteration-close wrapper.

Roles and skills

Load mstar-harness-core first, then topic skills on demand (mstar-roles).

Consumer plans default to .mstar/. Process artifacts (plans/, iterations/, status.json, sdd/, …) are gitignored; tracked results: {HARNESS_DIR}/AGENTS.md, knowledge/, specs/. Specs resolve .mstar/specs/ → docs/specs/ → repo-root specs/. Details → mstar-plan-conventions.

Maintainers: AGENTS.md.

License

MIT. See LICENSE.