btspoony/mstar-harness

Morning Star

Harness 工作流引擎 · Agent 插件

英文 /

GitHub · Issues

CI
License
Version
Last commit
dshfind
Greptile: The War on Bugs

npm: cli
npm: dsh
npm: omp
npm: opencode

Morning Star 是一个面向 harness 工程工作流的 Agent 插件：一个 TypeScript Harness 工作流引擎（@mstar-harness/engine）强制执行确定性的工作流门禁，而 mstar- 判断技能驱动多智能体代码交付。

- 确定性门禁，由 TS 引擎强制执行 —— 路径/状态/租约/派发/sdd/迭代/lint 门禁在 @mstar-harness/engine 中运行，而非作为提示建议
- 判断保留在 mstar- 技能中 —— 技能始终是角色、门禁和工作流判断的唯一事实来源（SSOT）
- 一个引擎跨多个宿主 —— 同一个引擎 + 技能为 dsh（DeepSeek Harness）、omp、OpenCode、Cursor、Kimi Code、ZCode 和 Codex 提供支持
- Agent 插件打包 —— 一条命令安装；可跨任何 Agent Plugins v1.0.0 客户端移植
- 可插拔的 JSON 持久化 — 协调文档（status.json、工作流快照、项目残留、审查信封）通过 ArtifactStore 持久化；默认的 FsStore 保留现有的 .mstar/ 路径，集成方通过 MSTAR_STORE_MODULE / --store / 进程内 setArtifactStore 挂载自己的存储
- 推荐宿主（最佳 → 可用）：dsh = omp ≥ ZCode = OpenCode = Cursor > Kimi > Codex

交付内容

| 组件 | 说明 |
|-----------|------------|
| Harness Workflow Engine | @mstar-harness/engine — 对确定性工作流门禁的 TS 强制执行 |
| mstar CLI | @mstar-harness/cli — 安装器引导 + mstar 工作流动词 |
| mstar-* 技能 | 角色、门禁与工作流判断（单一事实来源） |
| 宿主适配器 | dsh、omp、OpenCode、Cursor、Kimi Code、ZCode、Codex |

发布说明：CHANGELOG.md / CHANGELOG_CN.md。

安装

| 宿主 | 命令 |
|------|---------|
| dsh (DeepSeek Harness) | npx @mstar-harness/cli init --target dsh（一条 CLI 命令，运行两个独立的 dsh plugin --profile web add 安装：@mstar-harness/dsh + dsh-llm-fallbacks；--no-fallbacks 跳过后者）或 dsh plugin --profile web add @mstar-harness/dsh+ dsh plugin --profile web add dsh-llm-fallbacks |
| omp | npx @mstar-harness/cli init --target omp（链接 ~/.mstar/harness/packages/omp）或 omp plugin install @mstar-harness/omp |
| OpenCode | npx @mstar-harness/cli init --target opencode |
| Cursor | npx @mstar-harness/cli init --target cursor |
| Kimi | Kimi TUI：/plugins install https://github.com/btspoony/mstar-harness→ /plugins reload |
| ZCode | npx @mstar-harness/cli init --target zcode然后在 ZCode → Settings → Plugin Management 中安装 morning-star-harness |
| Codex | npx @mstar-harness/cli init --target codex然后 codex plugin add morning-star-harness@mstar-repo（仓库内置市场） |
| 通用（Agent Plugins v1） | 将任何符合 Agent Plugins v1.0.0 的客户端指向此仓库根目录（plugin.json + skills/ 是可移植包） |

引擎门禁检查（推荐）

npm i -g @mstar-harness/cli

将 mstar-harness 二进制文件（短别名 mstar）放入 PATH，这样技能引用的引擎检查命令（mstar status validate、mstar dispatch validate、mstar iteration gate 等）才能真正运行。

init 现在会在成功运行后自动全局安装匹配版本的 CLI — 传入 --no-global-cli 可选择退出。

若不进行全局安装，harness 仍可正常工作，且这些检查保持为建议性质。在迭代罗盘中设置 enforcement: hard 可使 dispatch 预检快速失败。
注意：mstar 是一个短别名，也是一个共享的 bin 命名空间——一个名为 mstar 的无关第三方 npm 包声称拥有相同的命令名。该别名仅在安装了 @mstar-harness/cli 的环境中存在：不带包名的裸 npx mstar … 会通过注册表解析到那个其他工具，而全局同时安装这两个包会静默覆盖 mstar shim（后安装者胜出）。规范调用名仍为 mstar-harness——在任何冲突场景下请使用长名称。

验证

npx @mstar-harness/cli doctor --target 。

Codex agent-link 修复与命名角色验证：Codex 安装。

该仓库在其根目录附带一个可移植的 Agent Plugins v1.0.0 清单（plugin.json）；skills/ 是 Agent Skills 组件——使用 npx @mstar-harness/cli plugin validate 进行验证。

手动安装 / 路径布局：INSTALL.md。CLI 标志：mstar-use-cli 技能。

使用

三种入口形态：无迭代（单一计划 / 热修复）、有迭代（多计划 Phase 1–5），或审计、评审与验证（发现工作、评估变更，或运行所请求的 E2E 检查）。

完整命令参考：docs/commands.md。

通用（无迭代）

进入 PM，然后运行每个计划的循环：Prepare → Execute → QC → QA gate → Done。

| 宿主 | 进入 PM |
|------|----------|
| dsh (DeepSeek Harness) | pm 技能（通过 mstar 技能提供方；无自动加载） |
| omp | 每个会话执行 /skill:pm（无自动加载） |
| OpenCode | agent.project-manager（仅 OpenCode 的 shell，packages/opencode/agents/project-manager.md） |
| Cursor | /pm |
| Kimi | 会话自动加载 pm；或 /skill:pm |
| ZCode | 每个会话执行 /morning-star-harness:pm（无自动加载） |
| Codex | /pm |

迭代

| 命令 | 何时使用 |
|---------|------|
| /iteration-start [direction] [pause] | 开始新迭代：Phase 1（交互式 grill-me），然后自动继续 Phase 2→6。direction — 可选提示（仍为交互式）。pause — 在 Phase 1 后停止；使用 /iteration-drive 恢复。 |
| /iteration-drive | 在已锁定的迭代上恢复 Phase 2→6。 |
| /iteration-loop [direction] [scale] | 完整的 Phase 1→6 自主运行（无 grill-me）。direction — 可选自由文本。scale — S / M / L / XL（默认 M）。 |

限定范围的计划会话

同一命令可接受一个范围，以便从独立终端驱动一个已准备好的计划，而非整个迭代：

| 命令 | 何时使用 |
|---------|------|
| /iteration-drive --assignment  | 全新的限定范围入口，通过协调者准备好的 Assignment 寻址。 |
| /iteration-drive --workflow  --plan  | 全新的限定范围入口，直接寻址已准备好的行。 |
| /iteration-drive --resume  | 显式恢复已绑定的会话——这是唯一的恢复形式。 |
作用域会话恰好绑定一个计划，通过常规的按计划门禁驱动其任务，并停在一个持久的交接处：该行保持 InReview，只有协调者记录 Done——在迭代路线上经过验证的合并之后，或在独立开发路线上直接从已接受的交接处记录。对同一计划的第二次全新进入会被拒绝为重复持有者——只有对原始会话的显式 --resume 才能继续。任何其他非空参数形态都会失败关闭；无参数则保留上述整个迭代路线。

第二个终端是传输层，而非依赖项：任何终端都可以，诸如 Herdr 或 tmux 之类的多路复用器是可选的——没有任何东西会读取窗格状态、TTL 或终端标签来确定所有权。

协调者的一半——prepare，然后是 accept，再从那里走迭代路线（integration-start → 固定合并 → integration-accept → complete）或独立开发路线（从已接受的交接处直接 complete），以 reconcile 作为崩溃路径——运行 mstar plan 动词；标志、JSON 信封和退出码：mstar-use-cli → references/plan-and-workflow.md。

配方：docs/commands.md。

审计、审查与验证

审计和审查命令是只读且建议性的；发现项可以转化为 Prepare → Execute 的计划。SSOT → mstar-audit（变体：codebase-audit、pr）。

| 命令 | 何时使用 |
|---------|------|
| /codebase-audit [keywords] | 对值得做的事情进行只读调查——按优先级排列、可直接执行的计划；当你想要一次有针对性的检查时，用类别焦点（bug、security、perf、tech-debt……）来缩小范围。 |
| /amazing-pr-review [pr\|branch\|scope] [quick\|default\|deep] | 对 PR / 分支 / 差异进行合并前的深度审查，分三个强度——quick（单遍，1 个席位）/ default（无标志落地层级，减少席位）/ deep（完整三阶段流水线）——给出一个裁决（ship it / needs fixes / blocked）以及每一条发现，当给出 PR 编号时，由该命令的主代理在第 3 阶段综合时发布到 GitHub。deep 运行完整的三阶段流水线（收集 → 领域审查 → 主代理综合；一个裁决 / 一份 GitHub Review）；default / quick 是更轻量的单/双席位遍次。多 PR 输入 → 仅第一个 PR；其余 PR 作为审计待办排队（下一会话）；建议每个 PR 一个会话。 |
| /amazing-e2e-check [environment/device] [scenarios] | 在单独的工作流中通过 mstar-e2e 执行显式请求的浏览器/设备/已安装部署场景；绝不是常规的迭代 QA 门禁。 |

Harness 工作流

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 -->|快速自主循环| F2["iteration-loop：阶段 1→5 持续进行"]
F --> G["PM：锁定指南针并创建集成分支"]
F2 --> G
G --> H["阶段 2→5：执行 → 关闭 → PR → 可合并"]
E -->|否| I["PM：从工作流快照中选择活动计划"]
H --> I
I --> J{"是否有计划未完成"}
J -->|是| K["PM：在功能分支上派发一个计划"]
K --> L["开发角色：实现并报告"]
L --> M["PM：更新计划和工作流快照"]
M --> N["QC 三人组：审查门禁"]
N --> O{"QC 决策"}
O -->|请求修改| K
O -->|批准| P{"QA 门禁"}
P -->|mandatory| P1["qa-engineer：验收验证"]
P -->|pm-acceptance| P2["PM：验收清单"]
P1 --> Q{"是否仍有残留发现"}
P2 --> Q
Q -->|是| R["PM/QA：在项目登记册中登记或接受残留项"]
R --> S["PM：将计划标记为完成并合并到集成分支"]
Q -->|否| S
S --> T["PM：同步指南针计划状态"]
T --> J
J -->|否| U["iteration-close：关闭入口清单"]
U --> V["PM：复合轮次和知识索引"]
V --> W["PM：更新路线图和指南针已完成 frontmatter"]
W --> X["PM：关闭出口清单并提交"]
X --> Y["阶段 4：创建 PR"]
Y --> Z["阶段 5：可合并循环，直到 CI 通过且审查意见已解决"]

无迭代：相同的逐计划门禁，但没有 iteration-start / iteration-close 包装。

角色与技能

| Agent ID | 职责 |
|----------|----------------|
| project-manager | 路由、分配、阶段推进 |
| product-manager | 需求、产品规划、研究 |
| architect | 架构和技术契约 |
| fullstack-dev / fullstack-dev-2 | 后端主导实现 / 第二条并行轨道 |
| frontend-dev | UI、交互、前端性能 |
| qa-engineer | 当 QA gate: mandatory 时进行验收 |
| code-reviewer | SDD 逐任务审查；代码库审计（audit 类别） |
| qc-specialist / -2 / -3 | QC 三人组 |
| ops-engineer | 部署、监控、基础设施 |
| writing-specialist | 文档、小说、文案、脚本 |
| prompt-engineer | 提示词 / 技能 / 规则工作 |

先加载 mstar-harness-core，然后按需加载主题技能（mstar-roles）。

| 技能 | 用途 |
|-------|---------|
| mstar-harness-core | 入口、状态机、Task 类别、技能索引 |
| mstar-phase-gates | 准备/执行、澄清、热修复 |
| mstar-iteration | 阶段 1–5 迭代生命周期 |
| mstar-dispatch-gates | 派发、委派、防递归 |
| mstar-sdd | 子代理驱动开发 |
| mstar-branch-worktree | 分支、工作树、QC/QA 检出 |
| mstar-conventions | {HARNESS_DIR} 发现 / 初始化 |
| mstar-artifacts | 计划、status.json、残留项、Findings 清理 |
| mstar-project-governance | 路线图编写 + 残留登记册生命周期、_default 回退 |
| mstar-design-md | UI 计划的 DESIGN.md 门禁 |
| mstar-review-qc | PM QC 三重编排 |
| mstar-coding-behavior | RCA、测试先行、评审反馈、证据 |
| mstar-compound / mstar-compound-refresh | 知识结晶 / 维护 |
| mstar-strategy | STRATEGY.md 对齐 |
| mstar-skill-authoring | 通用技能编写（SkillsBench 门禁） |
| mstar-audit | 只读代码库审计 → 优先级改进计划 |
| mstar-e2e | 显式独立 E2E、浏览器、设备及已安装部署验证 |
| mstar-roles | 角色提示词 + 加载列表 |
| mstar-host | 宿主适配器（dsh / omp / OpenCode / Cursor / Kimi / ZCode / Codex） |
| pm | /pm / /skill:pm / 宿主 PM 入口 |

消费者计划默认使用 .mstar/。过程产物（plans/、iterations/、status.json、workflows/、projects/、sdd/、……）已被 gitignore；受跟踪的结果：{HARNESS_DIR}/AGENTS.md、knowledge/、specs/。Specs 解析顺序为 .mstar/specs/ → docs/specs/ → 仓库根目录 specs/。采用非默认布局的仓库可以在被 gitignore 的 .mstarc 中声明每个 harness 目录符号（[config] 键 harness_dir / plan_dir / sdd_dir / iteration_dir / knowledge_dir / specs_dir / workflow_dir / project_dir —— 优先于探测）。详情 → mstar-conventions。

维护者：AGENTS.md。

许可证

MIT。参见 LICENSE。