DeepSeek Harness 插件

btspoony/mstar-harness#dsh

Star 数 ★ 70 下载量(近 30 天) 7,473 分类 工作流与自动化 收录于 2026-08-14 npm @mstar-harness/dsh

技能驱动的 harness/loop 工程化工作流插件。

安装

# npm 包(预构建)

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

# GitHub 源码(首次需按提示配置 allowBuilds 构建授权后重试)

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

装任何插件都等于在你的机器上跑第三方代码,权限和你本人一样大——能读你的文件、用你的凭据、访问网络,工具审批管不到它。GitHub 来源的插件还会在安装时执行构建脚本——pnpm 默认拦截,所以安装可能停在 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED 或 ERR_PNPM_IGNORED_BUILDS;dsh 会打印出需要添加的确切键名,把它加进该 profile 的 pnpm-workspace.yaml 的 allowBuilds 下,重跑一次即可装上。放行构建本身就是一次信任判断:请只安装可信来源,并尽量锁定 commit(github:owner/repo#sha)。

README

English | 中文

让 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)。

一条命令的 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——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 时把 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,断言每个派生 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 根不在探测名列表中的仓库必须配置;探测从会话工作区根开始(绝不从启动 cwd)并在那里停止——永不越过会话工作区向上,因此其上方的 harness 目录(如全局 ~/.mstar)永远不会被采纳。
enforcement 'hard' | 'soft' compass,否则仅告警 按部署覆盖。优先级:Config 优先;否则取 Assignment 自身的 **Enforcement**: hard 头字段(仅派发闸门);否则取仓库 .mstarc [config] enforcement;否则取迭代 compass frontmatter;否则仅告警。Config / .mstarc soft 是仅有的本地回滚——Assignment 级 soft 不能覆盖 hard compass。
dispatchTools string[] ['subagent', 'subagent_fork'] 派发闸门匹配的委派工具名——dsh preset 的两个委派工具:subagent 及其 fork 兄弟 subagent_fork(两者都携带 Assignment 形态的 { description, prompt } 参数;toolName 配置可重命名实例)。
dispatchBinding string 未设置——caller 从调用方会话推导 派发方 agent 自身的 harness 角色(反递归 caller)——根会话身份。Assignment 的 Execute as 等于该 caller 即自我递归(dispatch.anti-recursion.self-type)。该字段只在调用方是根会话(session.header.parentSession 不存在——本 harness 中的协调 agent)时读取:此时显式值(profile patch 或配置页)原样生效,显式置空('')fail-closed,未设置则读作 project-manager(身份读取,绝不凭空编造)。子会话——或闸门读不到会话的路径(无 exec 的宿主 beforeDispatch 钩子)——永不继承它:无论该字段写什么,caller 都是空,于是每一条 Assignment 形态的派发都以 dispatch.anti-recursion.empty-binding fail-closed,因为叶子不得派发,且任何配置都不能解除这条红线。可在 dsh 插件配置页实时编辑(与 roleGate 同一条 volatile 通道)。协调 agent 不是根会话的部署无法用该字段承载。
roleMap Record<string, string> 未设置 mstar 角色 id(Execute as)→ dsh-llm-fallbacks 角色 id。仅作日志与未来规则驱动互操作的分类桥——角色-preset 通道按设计不使用(见 LLM fallbacks 集成)。
rolePresets Record<string, string> 未设置 mstar 角色 id(Execute as)→ 部署方声明的 agent preset id;角色-preset 通道的唯一载荷来源。角色匹配的 start 会在激活请求上选择该 preset(SubagentStartRequest.agentPreset),由 dsh 把它作为子代理的整份组合挂载(persona 经 @deepseek-ai/dsh-persona、工具与技能),并在 resume 时重放该选择。部署方需为每个角色声明一份完整 preset——preset 是整份组合,绝不是只改 persona 的补丁。合并次序:请求自身已携带 agentPreset(委派工具配置的默认值,或模型自己的 agent_preset 选择)时原样生效;否则从 Assignment 头部读取角色,未映射的角色静默跳过。空/纯空白 id 会在插件挂载时被 Config 校验拒绝。当提供者不支持独立选择(capabilities.agentPreset 为 false,或该提供者继承父会话)或组合未挂载 agentPresets registry(web 与 headless bundle 挂载 @deepseek-ai/dsh-agent-preset-registry;base 与 SDK bundle 不挂载)时,通道跳过选择(恰一条 contained debug 日志,start 不受影响)。配置的 id 每次 apply 校验一次——未声明的 id 会得到一条 warning,而不是等到子代理启动失败才暴露。
roleGate 'off' | 'warn' | 'hard' 'hard' 子代理启动缝隙处的派发角色归一化(见《角色身份交付》)。显式声明——Execute as: / Act as: / Role: 字段行,或反引号/加粗的已声明角色 id,两者都只在 Assignment 头部内读取——会在 preset 合并前被改写为规范的 Execute as: <role> 头,使两个角色消费方都能绑定。hard 拒绝完全没有可靠角色声明的启动,也拒绝点名两个及以上不同角色的启动(消息点名真实原因与这些 id、确切修复以及逃生口);同时拒绝字段存在但值不可用(为空或不是小写角色 id——消息点名原始值与合法形状)以及只存在于围栏代码块中的规范声明(头部读取不识别围栏,缝隙仍会绑定该引用);warn 每次 apply 只记一条咨询并照常启动;off 只跳过拒绝——单一显式声明仍会被归一化。豁免按子代理实际启动目录判定(绝对 cwd 原样;相对 cwd 相对父目录当前目录解析;缺省 cwd 继承该目录——父目录取运行时自身解析所用的 working-directory 投影,而非不可变的 header.cwd):解析不到 {HARNESS_DIR} 的目录静默直通;已声明可用角色、携带 agentPreset 的请求以及未知提供者同样直通。这是插件两个可实时编辑的设置字段之一(roleGate 与 dispatchBinding):在 dsh 插件配置页保存不同模式会写入 profile patch,并在下一次子代理启动时生效(无需重载);表中其他字段都在 apply 时读一次,需要重载。
skillRoots string[] 未设置(不注册自定义根) 向 dsh skill-filesystem 提供者注册的额外技能根(customSkillDirs 语义——先于用户根扫描)。开发期:镜像 <repo-root>/skills 的绝对路径。
bundledSkillDir string 打包的 harness-skills/ 镜像(包相对路径) 向 dsh skill-filesystem 提供者注册的打包技能根(bundledSkillDir 语义——最后扫描、受信任)。默认取包内自带的 harness-skills/ 镜像(bundle-assets 同步;gitignore)——包相对路径,非 cwd 锚定。显式值优先。
catalogTtlMs number 60000 pre-step catalog 缓存刷新间隔(毫秒):按工作区缓存的统一 mstar-engine 行(迭代闸门 + 工作区摘要)多久重读一次 store.db 执行权威 / compass / 知识索引。刷新间隔之间热路径只是时间戳比较 + Map 命中;会话中 plan/compass/residual 的变化会在一个间隔内落地。
workflowGate 'off' | 'warn' | 'ask' | 'hard' 'warn' workflow/ralph 闸门模式(见 Gates → Workflow / ralph gate)。off = 直通且不产生 verdict 行;warn = 仅咨询;ask = 首见名字走审批瀑布(P-c);hard = 策略违规在任何子进程启动前否决。默认 warn 不改任何 hard 行为——除非部署显式选入 ask/hard,闸门仅咨询。
workflowNames string[] 未设置 workflow 名字白名单(P-a):被闸门视为 KNOWN 的 meta.name 值。为空或缺省 ⇒ 每个名字都 unknown(有文档——闸门绝不因缺省而"全放行")。ralph 调用不携带 meta.name——P-a 对其永不适用。mstar 只读扇出路径推荐值:['mstar-qc-tri', 'mstar-audit-fanout', 'mstar-pr-seats']。

推荐的 operator 覆盖层。 上表三个推荐 workflowNames 覆盖 mstar 只读扇出路径(plan QC tri、大型仓库 /codebase-audit、/amazing-pr-review deep);写入它们是 profile 层的操作者覆盖,绝非 mstar 默认。出厂空列表下每个名字都是 unknown,在默认 workflowGate: 'warn' 下这只是运行会存活的一条 workflow.name.unknown 咨询。生产部署若还要否决 unknown 名字,可设置 workflowGate: 'hard';出厂默认仍为 'warn'。

bundledSkillDir 默认取包内自带的 harness-skills/ 镜像(见 Skills mount)——显式 Config 值仍然优先。相对覆盖仍是 cwd 锚定(skill-filesystem 以 join() 语义相对 dsh 进程 cwd 解析),因此覆盖默认的部署应在 profile 层传绝对路径(见 bundle/README.md)。

组合后的行集合

profile bundle 组合出以下行——注册表行来自 @deepseek-ai/dsh-base 层,本 bundle 的补丁在其上插入 mstar 行并携带中性默认(即全应用 e2e fixture 启动的行集合):

- name: '@deepseek-ai/dsh-skill'   # skill 注册表(ctx.skills)——dsh-base 行
- name: '@deepseek-ai/dsh-tools'   # tool 注册表(ctx.tools)——dsh-base 行
- name: '@deepseek-ai/dsh-commands' # command 注册表(ctx.commands)——dsh-base 行
- name: '@mstar-harness/dsh'       # 本 bundle 补丁插入(config: {}——插件默认生效)

注册表行先于插件挂载,使 mstar 各闸门、seam 工具与 bundled 命令注册时 ctx.skills / ctx.tools / ctx.commands 已存在。

What the plugin does when mounted

  • 状态闸门——fs/write-intent + fs/edit-intent 监听器校验 v3 协调文档目标集——v2 根 {HARNESS_DIR}/status.json、workflows/<id>/snapshot.json 与 projects/<id>/residuals.json——各自使用匹配的 engine 校验器(validateStatus = v2 根 / validateWorkflowSnapshot / validateProjectRegister,即 P2 修复的 harnessDocKindOfTarget 形态),外加快照目标的 findingsCleanupGate 扩展(按配置模式的计划行,从项目注册表读取残留)。
  • 派发闸门——tools/pre-execute 监听器作用于委派工具,通过 engine 的单一 composeDispatchGate 组合(字段闸门、反递归预检、默认分支闸门——与 opencode/omp/CLI 对齐,违规码按构造即相同)校验 subagent Assignment 文本,外加 dsh 租约闸门与 worktree L1/L2 检查。
  • 技能撰写 lint——已配置技能根下的 SKILL.md 写入运行 engine 技能撰写 lint(lintFrontmatter + lintFiveQuestion)。
  • seam lint——harness 下 DESIGN.md / 评审报告({REVIEW_DIR} = {HARNESS_DIR}/reviews/)/ 知识文档 / roles 目录的写入运行各自的 artifact 级 engine lint。
  • 模型可见工具——ctx.tools 上恰好注册三个工具,且只覆盖 MCP 面做不到的事:mstar_plan_bind(持久槽生产者——dsh 本地 executionBinding 槽及其采纳收据的唯一写入者)、mstar_audit_validate(评审报告凭据扫描,mstar_audit 家族没有任何 action 提供)与 mstar_execution_clear(不存在共享的 execution.clear 命令)。其余所有运行时能力都走 MCP 家族:每个家族一个工具 + action 参数。store 级命令(store.*)是刻意的例外:它们搬运整个 store,因此只在 CLI,家族成员以 transport: "cli" 发布。成员规则与各工具的独有贡献见 § Native command surface。
  • bundled 命令——向 ctx.commands 注册 /iteration-start、/iteration-drive、/iteration-loop、/codebase-audit(来自打包的 harness-commands/ 镜像;每条声明 frontmatter input hint,使 web 客户端 claim /name 并等待用户后续输入而非立即执行;handler 把命令正文 + 用户输入 steer 进接收 agent)。
  • 原生执行绑定路径——持久执行绑定由成功的原生 mstar_plan_bind(两个 bind 臂,均在引擎只读 C1 session resume 成功之后)自动采纳,并按需用 mstar_execution_clear 工具清除:身份来自 exec.agent.id(无参数、无模型可选面),清除会保留本会话自己的用户选择与排除下限,未绑定会话或不可读的 binding 记录会得到命名拒绝及其恢复路径,而不是静默写入。这条路径上没有任何斜杠命令——操作者绑定或清除执行会话,用的就是这两个原生工具。
  • pre-step catalog 行——一个咨询式 agent/pre-step 监听器追加一条统一的 mstar-engine catalog 消息,只携带一条 delta 行(workflow / 非 Done plans / branch 锚点 / 解析到 steering compass 时的相位 gate 判定),选中项带警告时再附 workflow warning 披露行。residuals 汇总、branch policy、spec 集成锚点、row scope、知识摘要、compass 方向与 agent-flow ledger 均为 payload-only(面板 + engine 权威)——见 § Engine-status catalog。发射按会话+工作区变更驱动——首次发射之后,仅当渲染出的行或面板相关 payload 变化时才追加;turn 开始本身从不触发,未解析到 {HARNESS_DIR} 的工作区不会组合该行。其背后的构建共享同一份内存 TTL 缓存(catalogTtlMs,默认 60 秒);每会话最新发射持久化到 control 根的 store.db(dsh_status_emissions),而非文件缓存。

Enforcement semantics

默认仅告警:闸门违规记录日志并发出咨询事件(mstar/status-gate、mstar/dispatch-gate、mstar/skill-lint 及各 seam 咨询),动作照常继续。Enforcement: hard——来自迭代 compass frontmatter、Assignment 头字段、仓库 .mstarc [config] enforcement 或插件 Config(enforcement: hard)——把违规升级为经 cordis 拒绝通道的真实否决/拒绝:subagent 派发在不调用 next() 的情况下返回 PreToolDecision { kind: 'deny', reason };状态/技能 lint 写入因 intent 瀑布链内容盲而从不硬否决——对已非法的文档按修复逃生放行(hard: true, repair: true 咨询),让修复性写入能落地。Config / .mstarc soft 是本地回滚;hard 闸门绝非全局默认。

Gates

Status gate

fs/write-intent + fs/edit-intent 监听器(以 prepend 注册,确保先于 dsh-fs-policy 执行)对 {HARNESS_DIR}/status.json 的写入把关:基于当前磁盘文档运行 validateStatus + 按 plan 的 findingsCleanupGate(文档只解析一次——无 TOCTOU 双重读取)。闸门从不抛出:每次决策都以 mstar/status-gate 咨询事件呈现,并通过 next() 委托 intent 瀑布链。告警模式(默认)在有违规时记录日志并发出事件。hard 模式对已非法的文档按**修复逃生(repair escape)**放行(error 级日志 + hard: true, repair: true 咨询)——intent 瀑布链不携带写入内容,若对非法文档硬否决,反而会卡死修复性写入本身。意外内部错误在两种模式下都降级为放行并发出 degraded: true 咨询(错误隔离包络);首次破坏文档的写入本身无法在此 seam 上被否决(见 Known Limitations)。

有一类拒绝不是修复逃生:当 findings-cleanup 判定因 issue 权威缺失(store.not-initialized)、staged(store.not-active)、损坏、低于 floor 或忙而读不到时,hard 模式下写入被否决(status.veto / findings.cleanup-authority-unavailable)——该否决基于权威不可读而非文档内容,故任何内容都修复不了它,恢复手段是 store 命令(mstar store init|upgrade|migrate)。register 类型仍只做同步形状校验:project register 是迁移历史,退役路径不是查询入口。

Dispatch gate

tools/pre-execute 监听器作用于委派工具:解析载荷中的 Assignment 文本,在头区域上运行 engine 的单一派发闸门组合(composeDispatchGate——形状守卫、validateAssignmentFields、antiRecursionPrecheck、默认分支闸门、头区域强制执行;opencode/omp/CLI 绑定使用同一组合,违规码按构造即相同),外加 dsh 侧 worktree L1/L2 检查与租约闸门。拒绝通道为不调用 next() 而返回 PreToolDecision { kind: 'deny', reason };告警模式记录日志、发出 mstar/dispatch-gate 并委托。非 Assignment 提示与非委派工具保持惰性。两种模式下 engine 故障都降级为放行,且降级可观测:catch 路径发出 degraded: true 的插件自有咨询 + error 日志,使 hard 部署能察觉控制失效而非静默放行。以 prepend 注册,防止更早挂载的决策监听器把本闸门短路在不可达处。

每个委派载体都被把关:已配置的 dispatchTools(默认 subagent / subagent_fork)以及 Agent Teams 载体——spawn_teammate、team_task_create、team_task_update、send_message。

Lease gate

在 opencode 字段之上:声明 Execution mode: sdd 或行处于 InProgress 的可写 Assignment 派发,将 Worktree path/Working branch 与权威行 metadata.worktree_path/metadata.working_branch 比对,不读取 holder 或逐行 lease。缺少登记 scope 产生 lease.dispatch.unverifiable(可写派发前 STOP)。权威/status/snapshot/row 缺失或不可读仍产生 lease.dispatch.unverifiable 或 lease.dispatch.unreadable;warn 咨询,hard 拒绝。Worktree/branch 不匹配保留 lease.dispatch.worktree-mismatch/branch-mismatch;holder-mismatch 已删除。只读角色跳过;其他非 SDD/非 InProgress 派发保持降级放行。读取限定 assignmentHeaderRegion。

Skill lint gate

作用于已配置技能根下 SKILL.md 文件的 fs/write-intent 监听器,对写入前的磁盘文档运行 engine 技能撰写 lint(lintFrontmatter + lintFiveQuestion——与 CLI mstar skill lint 组合一致)。该槽位内容盲(intent 瀑布链只携带 (target, actor)):文件缺失 = 首次创建 = 放行;磁盘文档干净 = 静默放行;告警模式下有违规 = 咨询 + 委托;hard 模式下有违规 = 修复逃生——文档已经非法,本次写入可能就是修复本身(error 级日志 + hard: true, repair: true 咨询,携带强制执行后的 hardBlocked 判定)。强制执行解析方式与其他闸门相同(Config 覆盖优先,否则取迭代 compass,否则仅告警)。闸门从不抛出;读取失败与意外错误降级为放行并发出 degraded: true 咨询。类型化 hard 否决(SkillLintVetoError,码 skill-lint.veto)位于传入文档分支(lintSkillWrite)——当前接线见 Known Limitations。

Workflow / ralph gate

tools/pre-execute 的一个分支(位于 subagent prompt 分支之前)把关 workflow 与 ralph 工具调用——这是剩余的不携带 Assignment 文本、模型可达的扇出路径。它匹配固定工具名(workflow / ralph);重命名后的 workflow 实例不在范围(名字守卫是固定默认)。非 workflow 工具不受影响——subagent 分支照旧拥有它们,语义不变。

WorkflowGate 的 off/warn/ask/hard 四级模式仍独立于 Enforcement。P-b 先检查登记的可写 scope,再检查 P-a 名字与 P-c 首见审批;不再逐行 holder 准入。

策略 off warn(默认) ask hard
P-b:InProgress 行缺少 metadata.worktree_path/metadata.working_branch allow(off) warn/咨询,workflow.lease.uncovered warn/咨询;ask 仅服务名字 子进程前 deny,workflow.lease.uncovered,点名该行
P-a:workflow 名字 ∈ workflowNames(非空列表) allow(短路) allow——无咨询(P-a 在任何模式下都放行) allow——无 ask allow
P-a:workflow 名字 unknown(空/缺省列表 ⇒ 每个名字都 unknown) allow(短路) warn——放行 + 咨询(workflow.name.unknown)+ 一条 warn ask(首见)→ {kind:'ask'};之后复用缓存决策(allow/deny)——已解析名字绝不再 ask deny——在任何子进程启动前否决(workflow.name.unknown),reason 点名该名字
ralph(无 meta.name——无白名单身份) allow(短路) allow——P-a/P-c 永不适用 allow——P-a/P-c 永不适用 allow——P-a/P-c 永不适用;P-b 仍适用(uncovered 时 deny)

默认 warn 的理由。 默认 warn 使闸门绝不让部署意外吃硬阻断:除非操作者显式选入 ask(人工 ask 通道)或 hard(否决),闸门仅咨询。workflowNames 空/缺省使每个名字都 unknown——闸门绝不因缺省而"全放行",但默认模式把这一点变成咨询而非阻断。

与 Enforcement: hard 的交互。 workflow 闸门的模式是它自己的 Config 旋钮——跨切面的 Enforcement: hard 解析(compass / Assignment 头字段 / Config enforcement)不会升级 workflowGate。hard-enforcement 部署仍按已配置模式运行 workflow 闸门(默认 warn = 仅咨询),除非同时设置 workflowGate: 'ask' 或 'hard';反之 workflowGate: 'hard' 与跨切面解析无关地否决。二者不可混淆:workflow 闸门只在部署把模式选入时才关闭 "Enforcement: hard 下的未把关扇出" 缺口。

Fail-open 边缘(有文档,绝不崩溃合规调用)。(1)畸形参数——workflow 调用缺少非空字符串 meta.name(控制字符归一化之后),或 ralph 调用缺少字符串 objective → 在每个模式下(hard 亦然)直通 + 一条 warn,且无 verdict 行(未产生策略判定)。只含控制字符的名字归一化为空 → 视为畸形。(2)status.json 不可读——经含容解析器路径的 P-b 状态读取抛出 → 仅本次调用的 P-b 降级 + 一条 warn;P-a/P-c(基于名字,无状态依赖)照常运行。闸门从不抛出:每次读取都是结构化的。

Verdict 账本行。 每个被把关的调用都在 agent-flow 账本记录一条持久化 workflow-verdict 行(P2 账本 plan 的记录路径,完全含容——账本写入失败绝不波及闸门):tool(workflow | ralph)、workflow(归一化后的 meta.name)或 objective、mode(绝不为 off——off 在策略前短路)、判定词汇 ok / advisory / denied / ask(ask 判定是本次扩展:首见 ask 本身也是被把关的调用,其行携带 ask 直到审批瀑布解析——"每次被把关的调用一行")。违规码来自判定、绝不猜测:workflow.name.unknown(P-a)vs workflow.lease.uncovered(P-b)。fail-open 路径(畸形参数 / 状态不可读)不记录;未解析出 harness 目录的调用跳过该行(与派发记录路径相同的静默 no-op)。

P-c 答案观测 seam。 闸门无法观测 ask 结果——工具注册表的 serviceAsk 在内部消费审批结果。run-start 观测就是答案 seam:被 ALLOW 的 ask 执行调用 → 持久化 tool-workflow/run-start 会话事件落入父会话日志 → workflow-ledger 消费者记录 W-B2 workflow-run 行并把 allow 按运行名缓存进 apply 作用域的 WorkflowAskCache。被 DENY 的答案不产生运行 → 无观测 → ask 模式下下一次同名调用重新 ask(fail-closed——无授权证据,绝不发明 allow)。缓存键在两个 seam 都是归一化(剥离 ASCII 控制字符)不截断的名字——闸门合成 meta.name 与观测记录 runName 都走同一个 normalizeWorkflowName,因此含控制字符的名字(au\u0000dit)永远无法卡死缓存(ask 一次、同一键观测),>1024 字符的名字仍以完整名字为键(账本行的展示名字单独截断;身份轴从不截断)。缓存是 apply 作用域的——新 apply(HMR 重载)从空开始,因此未解析的首见名字每次调用都会重新 ask,直到一次观测(或显式 record())落地。缓存记录抛错时观测降级为一条 warn——账本行已追加,运行不受影响。

P-b 抢占: InProgress 行缺少登记 source scope 优先于名字策略,对 ralph 同样适用。在可写派发前通过普通 prepare 配置实际 source 事实,不逐行恢复或 claim lease。Warn/ask 仍仅咨询,hard 否决。

Execution read route

engine 自己的路线(resolveExecutionReadRoute)决定由哪个权威作答,没有任何工具参数或配置键能选中一个。control harness 的执行权威为 ACTIVE 时,各闸门以显式身份从 DB 权威取它们所针对的生命周期——绝不做 newest/only 猜测,绝不回退到退役的 status.json / snapshot 字节——对退役协调文档的写入被无条件拒绝(execution.direct-write-refused),规范路径与符号链接别名一视同仁。缺失(store.not-initialized)或 staged(store.not-active)的 store 不是执行路线:那里的协调文档没有文件回退(execution.not-active)。

同时存在多个 ACTIVE 生命周期是常态,不是错误:每个 plan、worktree 与 PR 各自推进自己的生命周期,宿主不限制并发数量。会话只需回答某次操作属于哪个生命周期,解析器按以下顺序从操作本身作答:

  1. 某个 plan 行登记的 worktree 包含会话 cwd;
  2. 某个生命周期的集成 worktree 包含会话 cwd;
  3. 会话的显式选择(面板选择或 mstar plan bind);
  4. 操作点名的 plan 行——Assignment 的 Plan Path / SDD dir、--plan 参数(plan 行只属于一个生命周期,因此即使 cwd 命中多个,点名也足以确定归属);
  5. 唯一活跃条目。

每条自动梯级(1、2、4)都需要恰好一个不同生命周期:零个或多个命中则落到下一梯级,绝不按注册顺序、最近使用或最长前缀猜测。显式选择刻意压过梯级 4——点名了生命周期却没有所请求 plan 行的选择是调用方必须看到的矛盾(lease.dispatch.plan-not-found),绝不是静默切换生命周期——而点名已不再活跃的生命周期意味着该选择已过期,可落到梯级 4。五条都不适用时,写入才报 workflow.selection.unbound-multi-active,且该拒绝只作用于那一次操作:它列出活跃 id 与点名方式。

LLM fallbacks integration

可选的 dsh-llm-fallbacks 插件(以第二条命令安装——见 Install paths)驱动基于角色的 subagent 配置——角色种子与采纳建议;角色身份交付本身走 dsh 原生 subagent preset 通道(与 fallbacks 无关,见下文)。mstar 插件对该包携带零运行时与零类型引用——src/ 无任何导入(运行时或类型);被消费的服务面由 src/gates/fallbacks-structural.ts 的本地结构类型镜像,该包仅是 mstar 插件的开发期依赖(类型镜像 + 真实包测试 harness)。dist/ 仅在 1 处字符串字面量中命名该包——探测的 loader 条目匹配——绝非导入或类型引用;互操作是决策点能力探测,绝不读取其他插件的模块内部。

能力探测

挂载状态的两个视图(决策点即时读取,无缓存——loader 并发挂载条目):

  • fallbacksService(ctx)——插件被 apply 期间命名的 cordis 服务(ctx.get('llm-fallbacks'));HMR/纤程切换窗口内即使 loader 条目仍在,服务也为 undefined(条目是声明式的,比纤程活得久)。
  • fallbacksMounted(ctx)——能力视图,服务优先 + loader 条目回退:名为 dsh-llm-fallbacks 的 loader 条目存在、启用(尊重 entry.disabled 与 group 行)且纤程存活。

状态区分:mounted(服务已 apply——完整能力)、unmounted(无条目:未安装 fallbacks 插件——mstar 能力降级,绝不中断)、disabled(条目存在但禁用/分组——能力关闭),以及 HMR 窗口(条目在、服务缺——loader 回退覆盖)。

角色身份交付(原生 subagent preset 通道)

角色身份通过选择一个已部署的 agent preset 交付:插件经 cordis internal/get waterfall——框架文档化的服务读取拦截钩子——拦截 ctx.subagents 的服务读取并包装运行时值,使角色匹配的 startActivation(spec) 在子会话组装之前合入 spec.request.agentPreset。dsh 0.2.1 中 startActivation 是唯一的启动面(一次性与 continuable 子代理一致),而 preset 拥有子代理的整份组合(persona、工具、技能);dsh 会把该选择记入子会话日志并在 resume 时重放。底层 SubagentRuntime 对象绝不被改动(无 monkey-patching),包装监听器归 apply fiber 所有(HMR 重挂载会先卸载再恢复,并重新绑定新 Config)。persona 交付走 dsh 0.2.1 的设计而非私有段:上游已移除 SubagentStartRequest.persona 与 start/startContinuable 对,且 tool-subagent 对 persona 配置直接报错「configure persona and tool plugins in an Agent Preset and select it with agentPreset (spawn only)」。

能力闸门:独立选择要求提供者 SubagentCapabilities.agentPreset 为 true 且 inheritsParentContext 为 false——正是上游 tool-subagent 断言的同一组合(「provider does not support independent agent preset selection」)。同时必须挂载 agentPresets registry:没有它 dsh 会 fail loud PRESET_UNAVAILABLE,因此通道跳过选择并记录恰一条 debug 日志(每次 apply 只记一次),start 照常继续。闸门未通过绝不使派发失败。

组合归部署方所有:mstar 只负责角色 → preset 的选择。每个角色指向的 preset 都由部署方声明(@deepseek-ai/dsh-agent-preset 行,通常挂载 @deepseek-ai/dsh-persona 并携带该角色的 persona 文本,与上游自带的 standard/minimal preset 同构);mstar 不生成 preset,因为 preset 是完整组合——由 mstar 并不拥有的行构成。

先归一、后拒绝(roleGate):同一个包装器在 preset 合并之前先归一化显式角色声明——Role: \fullstack-dev` 行、Act as:值(去掉一个前导@、引号或反引号后),或反引号/加粗且属于**已声明**角色 id(rolePresets键 ∪ 打包的harness-agents/shell 文件名)的 token——以上都在 Assignment 头部内读取,都会被改写进规范的Execute as: 头,改写后的 prompt 才是内层消费方与运行时收到的内容。两类候选都限定在头部并读取围栏掩码后的文本:正文句子或围栏示例里引用的角色 id 永远不是候选(粘贴的散文或模板无法武装角色);而头部解析器**只在围栏内**读到的规范声明在hard下会被拒绝而不是静默放行——头部读取不识别围栏,缝隙会绑定该引用。头部里的**每一条**Execute as字段行都会被修复并把标签归一化,因为解析器区分大小写且绑定**最后一条**字段行;两个及以上**不同**候选视为歧义,绝不去猜——该拒绝消息点名这些 id 并说明只能有一个声明(自由散文如「You are an architect doing…」永不挖掘)。只有完全没有可靠角色声明(或有歧义、围栏内、字段存在但不可用——为空或不是小写角色 id)的启动才会被拒绝(默认hard),消息点名真实原因与原始值、确切修复以及**与模式匹配**的恢复路径:hard拒绝提供roleGate: warn|off,而 warn咨询只建议roleGate: off(它已经放行)。非 harness 项目按子代理**实际**启动目录判定(绝对 cwd原样;相对cwd相对父目录**当前**目录解析;缺省cwd继承该目录,与运行时自身resolveDirectory的选择完全一致;父目录取 working-directory 投影而非不可变的header.cwd)并豁免;已携带可用 Execute as的 prompt、携带agentPreset 的请求以及未知提供者同样直通(后者的失败由服务按自身语义抛出)。off` 只跳过拒绝;单一显式声明仍会被归一化。

roleGate 与 dispatchBinding 可在插件配置页编辑 —— 两者都是 volatile schema 节点,经 Loader 的实时引用读取,因此配置页的一次保存写入 profile patch 并在无需重挂载的情况下生效。

反递归绑定(dispatchBinding)是根会话身份,永不被继承——caller 从调用方会话推导,且该字段只在根会话上读取。根会话(session.header.parentSession 不存在)就是本 harness 的协调 agent:显式绑定(profile patch 或配置页)原样生效,显式置空仍然 fail-closed,没有显式值时读作 project-manager——身份读取,绝不凭空编造。子会话(任何 parentSession)永不继承该绑定:无论字段写什么,caller 都保持空,于是每一条 Assignment 形态的派发都以 dispatch.anti-recursion.empty-binding fail-closed——正是引入默认值之前的行为,因为叶子不得派发。闸门读不到会话的路径(无 exec 的宿主 beforeDispatch 钩子)同样回落到空,绝不回落到协调者,也绝不回落到已配置的值。声明或推导出的 caller 仍是真实比较:Execute as 等于它仍按自我递归拒绝(dispatch.anti-recursion.self-type);显式置空状态还会在 apply 时记录一条 warn,指向插件配置页。协调 agent 不是根会话的部署无法用该字段承载。

Seam 探针(fail-loud):通道每次 apply 对 cordis internal/get seam 探测一次(临时 canary 监听器 + 一次受控代理式 ctx.subagents 读取——绝不 ctx.get);seam 缺失或未被识别时记录恰一条 warn——role persona channel not installed — cordis 'internal/get' seam missing or unrecognized (role presets will not be selected for subagent starts) + (reason: seam-absent | wrap-skipped)——而非静默失败。健康 boot 不产生任何 warn(锁定的判定表):在今天的组合形态下 apply ctx 不解析 subagents,因此每次 apply 发出一条无 warn 的 service-absent debug——cordis 在 dispatch 作用域解析该服务,读取在那时逐次被拦截;探针内部错误按 fail-open 降级(一条 debug)。wrap-skipped 已被钉死但无法从当前发布的 apply 布线触达——它只在 apply 时即可解析 subagents 的场景触发,该路径由 harness pins 覆盖。seam 名由专用探针家族 tests/persona-seam-probe.spec.ts 钉死(经导出的 PERSONA_SEAM_EVENT 常量);安装产物断言在携带探针的版本发布后自动启用(tests/install-e2e.spec.ts 的 surface-vintage guard)。

角色 seeds 与采纳建议(Adoption advisory)

当可选的 dsh-llm-fallbacks 能力已挂载(第二条安装命令——见 Install paths)时,mstar 插件会向 fallbacks seed registry 零配置声明 mode: subagent 的 mstar 角色 seed:persona = harness-agents/ 镜像 description(原样)+ 一行强制加载引导(Load mstar-roles (references/<role-id>.md) first — identity comes before skills; load topic skills only when the Assignment activates them via its Skill presets field.);含 {{...}} 插值风险的 persona 跳过并告警,绝不声明。声明会合并保留 readback 中当前已 seeded 的非 mstar id——例如上游包在其自身 apply 时自声明的 5 个上游 preset 角色:上游 declare 全量替换 registry,若不保留,mstar-only 批会摘掉 preset id 的 seeded 注记(行仍在,仅失去 seeded)。声明在每次 fallbacks(重新)apply(HMR/纤程切换)时幂等重放——绝不用一次性 latch——因此两种 boot 顺序(presets 先或 mstar 先)都收敛到同一全 seeded registry。boot 时收敛经 bounded retry(有界重试):上游的 seed 写通道在其 apply 之后一个 macrotask 才绑定,因此 apply 窗口内首次尝试被 seeds: settings service is unavailable 拒绝时会重试(跨上游 apply 窗口的 3 次尝试),暂时性拒绝自行收敛;仅当所有尝试最终失败时,声明才记录恰好一条终态错误,同时 advisory 的决策点 re-declare 仍可用作 retry 路径。无需手动编辑 roles.list。

一条只告警的采纳建议通道(日志器 mstar/fallbacks-advisory)每次 apply 只跑一遍——apply 时先尝试一次;当 fallbacks 行在 dsh 之后挂载(loader 并发挂载条目)时,改在首个 subagent/start 决策点只跑一遍。服务存在时,通道先 await 幂等 re-declare(闭合 boot 竞争窗口)再读取有效状态(getEffectiveRoles),并按每类至多一条告警有界报告:

  • 缺失 mstar 角色——无有效行的 mstar id(一条告警列出全部;id 集合派生自 harness-agents/ 镜像——绝不硬编码;无镜像 → 检查跳过并记一条 debug);
  • persona 覆盖——行 persona 与 seed 默认值不同的 mstar 角色(一条告警点名 + revert 入口:fallbacks/revert-seed gateway / fallbacks 设置卡片回滚按钮——操作者覆盖在 revert 前保留);
  • 空 persona——persona 缺失/空白的行,仅限非 seeded 或 overridden-empty(一条告警点名);
  • 遗留键——上游已退役的 v1 配置键(rootChain、顶层 timeSlots、enabled、roles.default、roles.rules、roles.list[].label/.description/.fallback/数组形式 chain、alwaysModeRetryCap、roleAutoMatch),经已应用服务自带的 detectLegacyKeys(一条告警引用其语义;v1 配置在读取时内存升级);
  • declare 跳过/冲突——本地跳过(interpolation / no-persona)+ 上游跳过/冲突(码 persona-source——操作者覆盖保留)合并为一条告警;默认已 seeded 静默(一条 debug 点名)。

loader 回退路径(无服务)保留结构化 roles.list 读取(缺失 id / 空 persona;无 revert 入口——无 seeds 面;遗留键检查跳过——绝不重新实现)。行配置缺失或非对象、或 roles.list 不可读 → 跳过并记一条 debug。该建议绝不写入 fallbacks 配置——唯一写路径是经已发布 seeds 面的幂等 seeds re-declare(无差异 → 上游零设置写入)——绝不抛出,且 fallbacks 未挂载时不调用:它是信号,不是闸门。

配置面

Key Type Default Meaning
roleMap Record<string, string> 未设置 mstar 角色 id → fallbacks 角色 id。仅作日志与未来规则驱动互操作的分类桥——角色-preset 通道按设计不使用。
rolePresets Record<string, string> 未设置 mstar 角色 id → 已部署的 agent preset id;通道的唯一载荷来源(选中的 preset 拥有子代理的 persona、工具与技能)。

Service

apply 构造 ctx.dshMstar(engine 支撑:validateStatus、validateResidual、findingsCleanupGate、resolveCompassEnforcement、resolveHarnessDir、readHarnessVersion、applyEnforcement)。分层:P1 各闸门是本包内与 engine 同置的包装器,直接导入 engine(同一插件,构建时打包 engine);ctx.dshMstar 是供 inject 消费者使用的组合/测试外观;宿主适配器(下节)是面向宿主的门面。两条路径共用 engine 这唯一语法源。伴随入口 @mstar-harness/dsh/invariant 以文档化的空安装器保留包所有权。

Host adapter

插件以 DshHostAdapter 实现 engine HostAdapter 契约(host: 'dsh'),并以 ctx.dshHostAdapter 服务暴露。检测:engine detectHost 将 dsh 委派工具名——ToolSignal subagent(模型可见的 dsh subagent 工具)——映射为 'dsh',在 omp 之后、kimi/zcode/codex 之前求值;混合会话按固定顺序让位于更早的行。适配器与插件内闸门共用同一套校验核心(单一代码路径):beforeStatusWrite(path, doc) 在宿主提供文档时校验传入文档,否则走磁盘文档回退(文件缺失 = 首次创建 = 放行);beforeDispatch(assignment) 运行字段 + 分支 + 反递归闸门并携带强制执行后的 hardBlocked 判定(租约闸门留在监听器侧——它绑定该钩子不携带的 ToolExecution 会话上下文);beforeMerge(lease) 是 engine validateIntegrationMergeLease 的薄包装(向 status.json 的预留写入是 P3 seam)。log 默认路由到 dsh ctx 日志器 mstar/host-adapter。

dsh 的冻结技能根形态(engine resolveSkillRoot('dsh', …))为 $DSH_BUNDLED_SKILL_DIR/<name>[/<rel>]——解析器只定义技能相对路径解析器(resolveAssetPath)所用的规范形态;它不挂载目录。挂载由插件负责(下一节)。

Skills mount

mstar 技能通过 dsh skill-filesystem 提供者以单一规范挂载接入:插件把配置的根注册为一个提供者(providerName: 'mstar'、includeDefaultRoots: false——隔离,绝不看到宿主应用自身的项目/用户技能),上文的 engine 形态是共享的技能根契约。两条 Config 路径填充它:

路径 机制 时机
Bundled 默认 bundledSkillDir 默认取包内自带的 harness-skills/ 镜像——仓库根 skills/(19 个 mstar-* + pm)由 bundle-assets 在构建时同步(gitignore),按包相对路径解析(非 cwd 锚定——任意启动 cwd 都可用) 发布包 / 无覆盖的任何部署
自定义根 skillRoots / 显式 bundledSkillDir → skill-filesystem customSkillDirs / bundledSkillDir 条目(显式值优先) 本地开发 / 测试 / 使用不同镜像的部署

打包镜像是单一规范挂载:技能内容只在仓库根 skills/ 镜像中存一份并同步进包(与 opencode 的 harness-skills/ 相同),mstar 技能在任何地方都保持可独立使用。不重复加载:opencode 插件在自己的包里携带同一批技能,因此 dsh 只能通过这条 skill-filesystem 路径挂载它们。

开发期现实:@deepseek-ai/dsh-skill-filesystem 运行时是 peer stub(契约镜像的注册,无文件 watcher),因此挂载通过真实组合(stub + 实际镜像 skills/ 的 frontmatter,用 engine lintSkillFrontmatter 校验)验证;真实运行时组合(真实 seam 包、watcher、$DSH_BUNDLED_SKILL_DIR 环境变量流)是部署目标,不在本包测试套件覆盖内。

Commands

插件把 bundled 的 mstar 命令(omp/opencode 对齐面)注册到 ctx.commands:harness-commands/*.md——仓库根 commands/ 镜像(iteration-start、iteration-drive、iteration-loop、codebase-audit)由 bundle-assets 在构建时同步(gitignore)。每条注册读取命令的 name/description/input frontmatter;声明了 input hint 的注册会将其作为 input.hint 公布,使 dsh web 客户端的决策表从「脱离式裸执行」翻转为 leadingInput claim——菜单点选后把 /name 插入输入框(命令色 token + ghost hint),按 Enter 才提交,用户可以键入后续参数(与 /plan、/goal、/advisor 相同的交互)。handler 把命令正文以 USER source 消息 steer 进接收 agent(dsh-plan-mode 命令先例——source: { kind: 'user' },模型把正文当作要执行的任务而非注入上下文;即 dsh-commands 的「经接收 Agent 显式调度模型可见工作」路径),用户键入的参数以 ## User input 小节追加在正文后,返回成功结果。注册以 ctx.inject(['commands'], …) 延迟进行——与工具注册相同的可选单元模式——插件在无 commands 服务时也能启动;镜像缺失(未跑 bundle-assets)则不注册任何命令。

Workflow scripts

模型交给 dsh workflow 工具的四个只读扇出脚本以包相对的普通 JavaScript 放在 workflows/——不是 TypeScript,也没有 export const meta 语句——因此脚本可被原样读取、diff 与回传。scripts/dsh-workflow-files-contract.test.ts(仓库根)校验的是交付面而非摘要:每个已发布正文可解析、package.json 会发布 workflows 目录、且 skill 的 meta 身份与 **File** 锚点正好指向磁盘上的这些文件——重命名、新增脚本或目录未发布都会失败,而一次刻意的改写不会。何时使用、其 meta 身份、参数规则、席位数守卫与失败面见 skill mstar-host → references/dsh-workflow-scripts.md;本表是文件清单。

文件 用途 必需 args
workflows/mstar-qc-tri.js Plan QC 三席复审:三个独立的只读 QC 席位,各自返回 verdict envelope planId, planPath, range, reviewCwd, branch, sddDir
workflows/mstar-audit-fanout.js 代码库审计:每个类别一个只读席位,按 8 席 subagent 池分批 repo, auditRef, recon(可选 categories,缺省为全部九类)
workflows/mstar-pr-seats.js PR 审查席位:2-3 个域席位加可选的跨域安全席位,只出 findings worktree, target, diffBase, auditRef, budgetLine, domains(2–3 个标签)(另有 security, diffFile)
workflows/mstar-review-single.js 单席 SDD task 审查者,不占用 Team roster 席位 planId, taskId, reviewCwd, branch, briefPath, implementerReport, diffFile, diffBase, diffHead, globalConstraints

Native command surface

本宿主的可写 mstar 命令面是 MCP 路线:整个宿主共享一条 mstar-mcp 连接(即 bundle 行——见 § Shared MCP connection),每个命令家族一个工具(mcp__mstar__mstar_<family> + action 参数)。该连接自身不携带任何身份,但随发行的行以 --trust-caller-session-id opt-in,因此需要会话身份的操作在这条连接上传 sessionId(未 opt-in 的连接不发布选择器并拒绝传入的 id)。下列三个 dsh 原生工具只留给本 MCP 面做不到的事——写不了的插件本地状态,或没有发布的能力;那里身份来自 exec.agent.id。

成员规则——记住它而不是记清单:一个命令只有在满足下列之一时才是 dsh 原生工具

  1. 产出 MCP 路线写不了的 dsh 本地持久记录,或
  2. 提供 MCP 面根本没有发布的能力。

目前恰好有三个工具满足该规则:

  • mstar_plan_bind —— 规则 1。它既绑定引擎 coordinator 行,也持久化本插件自己的持久状态:control 根 store.db 中本会话的 executionBinding 槽,以及 workflow ledger 归因解析器与 mstar_execution_clear 读取的进程内采纳收据。形态:共享 plan.bind 参数按已发布 schema 机械镜像(身份来自 exec.agent.id),引擎拒绝原样返回,已知叶席位在准入前 fail-closed 拒绝。MCP action: "bind" 路线只绑定引擎行、到此为止——两条路线并不等价。
  • mstar_audit_validate —— 规则 2。评审报告凭据扫描(mstar-audit Hard Rule 4,即 mstar audit scaffold 背后的校验器);mstar_audit 家族只发布 scaffold / secret-scan / supply-chain,都不校验已存在的报告文件。
  • mstar_execution_clear —— 规则 2。它清除同一个 dsh 本地 executionBinding 槽,而 MCP 路线没有可承载的共享 execution.clear 命令。它完全不带参数:身份来自 exec.agent.id,因此只能触达调用者自己的绑定,并保留用户的工作流选择与排除下限;已知叶席位在读取 store 之前 fail-closed 拒绝。其拒绝(execution.clear.no-harness / no-binding / store-refused)都点名原因与恢复路径。

其余运行时命令全部走 MCP——store.* 命令只在 CLI,不在此发布;旧的 mstar_<family>_<action> 工具名不会以别名复活:用家族 + action 调用,并用 mcp__mstar__mstar_schema(family: <name>,或单个叶子契约的 command: <command-id>)读取家族真实的 action 与字段。未知或缺失的 action 会以该家族真实的 action 列表拒绝,缺失必填字段则以上下文共享的聚合消息点名每个缺失字段——校验、拒绝聚合与 payload 组合仍归共享命令层,未变。这个表面上的身份、准入与 fail-closed 叶席位拒绝遵循 ADR docs/adr/implemented/architecture/2026-10-19-dsh-native-identity-channels.md。

叶席位拒绝的是「类」,不是命令清单。 只有当调用会建立或替换 coordinator 席位(绑定或完成 plan、recover 会话、在调用方已验证的实时绑定下拉起子会话),或写入 workflow 作用域的交付 / 生命周期 / 采纳 / 协调者账本状态时,叶席位才会被拒绝——也就是 CLI mstar mcp --seat 帮助文本点名的那两类。该集合只在 packages/commands/src/coordinator-seat.ts(CLI 的 --seat leaf 过滤)中派生一次,并由 packages/dsh/src/gates/coordinator-seat.ts 镜像给本宿主的 tools/pre-execute 闸门,因此它跟随命令层、不会逐命令漂移:新增的 workflow 家族 action 一经发布即对叶席位拒绝,而其它新增席位命令在 coordinator-seat.ts 中只登记一次,并由 packages/dsh/src/gates/coordinator-seat.ts 镜像、由 packages/dsh/tests/leaf-seat.spec.ts 固定。这两类之外的都不受该席位检查拒绝。叶席位可执行的读取工作:plan.show、workflow-note.coverage、sdd.workspace、issue.list / issue.show。它仍被允许的写入(经既有绑定或非 workflow 家族行事):plan.prepare / plan.progress、issue.add / issue.close、sdd.task-brief、sdd.evidence.*。两处列表都只是举例;以上派生才是权威。

Shared MCP connection(显式声明的 control 根)

bundle 补丁只插入一行 mstar-mcp,而这一行就是整个宿主的全部 MCP 通道:插件不自行注册任何 MCP client,不存在按 agent 挂载,subagent 共用父级已有的那一条连接。按 agent 的实例本来也拿不到按调用参数(PreToolDecision 没有改写参数的通道),因此它换不来任何能力——只会每个 agent 多一个 Node 进程。

control 根是「声明」出来的,绝不推断。 它按一条有序规则解析,启动 cwd 从不是候选——那个目录属于宿主,它说不出调用方属于哪个工作区,采用它会把写入落到不相干的项目上:

  1. 连接钉——mstar mcp --harness <绝对路径>,否则服务器环境中非空的 MSTAR_HARNESS_DIR;
  2. 否则由被准入的这次调用通过工具的 harness 字段指名根(绝对路径;相对选择器以同一具名原因被拒绝,因为启动目录从不锚定调用方的根);
  3. 契约不读取任何根的无根命令类以空根运行——harness.scaffold(建立根本身就是它的操作),以及 schema、path.resolve、host.*、doctor 与 lint / skill.lint / qc.validate-report 之类的只读校验器:它们只按显式输入作答,因此从不解析隐式 harness 路径;
  4. 否则该调用以 [mcp.control-root-unresolved] 被拒绝,并点名原因与全部恢复路径——两条启动方恢复路径对任何命令都成立,而按调用的 harness 选择器是依工具而定的(不发布该字段的命令无法接受它)。

连接钉优先于按调用的 harness,因此调用方绝不可能把某次调用钉在启动方未声明的工作区上;这次调用实际使用的那个根还会把调用工作区锚定在其父目录,因此由 cwd 派生的路径落在那份 harness 下,而不是启动 cwd。在未钉的连接上,凡是根不另有来源的工具,其声明的根选择器都是必填——用 harness 指明根的命令就是该字段,sdd.workspace 则是 controlRoot——模型无法漏掉解析所需的这唯一事实,tools/list 也绝不会把解析器拒绝省去的字段公布为可选。只读校验器(review.seats、worktree.qc-alignment、lint、skill.lint、roles.validate、design-md.validate、compound.validate、dispatch.validate、qc.validate-report)的相对路径参数按已声明的工作区解析,因此 --workspace /caller 读的是 /caller 下的文件,而不是宿主检出的;未声明工作区时相对路径一律被拒绝。

连接自身不携带身份;随发行的行信任调用方声明的 sessionId。 共享连接自身无身份,且仅属 MCP 的身份接线已移除:没有 --identity-env、没有已声明身份锁、没有选择器剥离,也没有连接级默认 session id。按调用的 sessionId 选择器只在启动方显式 opt-in(mstar mcp --trust-caller-session-id)的连接上发布;随发行的行会传这个开关,未 opt-in 的连接仍以 mcp.caller-identity-unavailable 拒绝传入的 id。在 opt-in 连接上该值是 bearer 身份:executionContextFor 把它变成 context.caller,引擎据此解析调用方自己的 coordinator 绑定,因此知道一个活跃会话的 id 就足以以它行事——授权仍是那条绑定行加上可选的 --expect CAS 令牌。需要会话身份的操作在本条连接上传 sessionId 运行——包括 plan progress、plan complete、workflow register/evidence/phase、session recover、workflow-note.append。上文列出的三个 dsh 原生工具只留给本 MCP 面做不到的事,那里身份是 exec.agent.id——宿主事实,绝不是模型提供的字段。未 opt-in 的连接没有调用方声明通道,那里才走原生工具或 CLI。

Engine seam mapping

每个 engine 模块都挂到一条 dsh 表面——除 lint 模块的 plan/tdd fs 闸门外均已交付(延后项;见 Known Limitations):

Engine 模块 dsh seam 状态
core(applyEnforcement、GateResult/Severity) 跨切面否决/拒绝 已交付(P1)
path(resolveHarnessDir) harness 目录探测 + {HARNESS_DIR}/status.json 目标匹配 已交付(P1)
status(validateStatus、validateResidual、findingsCleanupGate) status.json 的 fs/write-intent + fs/edit-intent 已交付(P1)
lease(verifyPlanExecutionLease、validateIntegrationMergeLease) exec 租约:tools/pre-execute(派发闸门内);merge 租约:HostAdapter.beforeMerge 已交付(P1 exec / P3 merge)
dispatch(composeDispatchGate、isReadOnlyAssignmentRole、parseAssignmentFields) 作用于 subagent 工具的 tools/pre-execute(PreToolDecision.deny 阻断);agent/pre-step 咨询 已交付(P1)
host(resolveSkillRoot、HostAdapter) engine host.ts 检测行 + 插件适配器(host: 'dsh') 已交付(P2)
skill-authoring(lintFrontmatter、lintFiveQuestion) skill-filesystem 根 + 对 SKILL.md 的 fs/write-intent 已交付(P2)
lint(lintSkillFrontmatter、planQualityBar、assertSddTddTriple) 未接线——plan/tdd 的 fs 闸门为延后项;lintSkillFrontmatter 仅运行于 skills-mount 测试套件 延后
agent catalog 生产者自有的 mstar-engine catalog source(锚点)+ dsh_status_emissions(面板读 store,而非发射) 已交付(P2)
sdd(sddWorkspace、taskBrief) MCP 家族 mstar_sdd(workspace / task-brief)——无 dsh 原生包装 已交付(P3)
iteration(evaluatePhaseGate、parseCompassFrontmatter) agent/pre-step + iteration 闸门 已交付(P3)
worktree(l1PreDispatchCheck、l2PreDispatchCheck) tools/pre-execute L1/L2(派发闸门内) 已交付(P3)
design-md / audit / compound / roles fs/write-intent seam + 唯一的原生 mstar_audit_validate;其余为 MCP 家族 已交付(P3)

Engine-status catalog

一个咨询式 agent/pre-step 瀑布监听器向发射时的组合步骤追加一条 mstar-engine catalog MessageSource——生产者自有的 mstar-engine kind,即恰好 { kind: 'mstar-engine', form: 'catalog' }、不含任何其它成员(dsh 生产者自有 source 契约):模型可见的 <mstar_engine_status> 块渲染为 payload 的投影(renderEngineStatusCatalog):渲染为一条 delta 行——workflow: <id> (<kind>) | plans: <非 Done 行> | branch: <base> → <target> | gate: <判定> (<transition>)——只携带选中的生命周期、其非 Done plan 行、解析到的分支锚点,以及 steering compass 校验迭代时的相位闸门判定(FAIL 带违规码;裸判定不指出原因)。plans: 字段区分空注册表(plans: none registered)与所有 plan 行均已 Done 的工作流(plans: all done),其余情况列出非 Done 行。payload 里的其余事实刻意不进该行:residuals 汇总与其明细行、branch policy、spec 集成锚点、各 plan 行的 row scope(记录范围,绝不是所有权声明或租约)、knowledge 摘要、compass direction、agent-flow ledger、原先的 iteration/transition 历史以及水印三行。这些事实留在 MstarEngineStatusPayload(面板读 store,而非发射)与其背后的 engine 权威中——mstar status、mstar roadmap show、mstar plan show、compass 文档、{KNOWLEDGE_DIR} 与 dsh_status_emissions——该行只是变更提示,绝不是权威。水印仅存在于 payload:mstar 版本(插件自身清单;单一版本不变量把打包的 engine 钉在同一版本)、harness 目录(解析后的 {HARNESS_DIR},缺失为 none)与 enforcement(compass 模式,soft / hard (compass))留在 MstarEngineStatusPayload,并在常驻 system prompt(mstar:engine-status 摘要 + mstar:harness-rules)中模型可见一次,故该行绝不重复它们。回退组合:只要 prompt 注册未被确认生效——宿主未提供 system-prompt 服务、异步注册失败(返回 true 仅表示 inject 子已排期)、或既有注册被释放——监听器逐步骤求值的 showWatermark 判定即让该行自行重渲染水印三行,版本 / harness 目录 / enforcement 事实因此不会丢失(随后才生效的注册会自动结束回退)。监听器先调用 next() 并基于委托后的决策追加——从不否决步骤、从不替换已组合的消息。未选中任何生命周期时,该行以 workflow selection: ERROR (<code>) <message> 取代状态行(此时的聚合按构造即空,绝不能被读成「无 plans」),该消息不再指向已退役的 status.json 路径——它指出原因并给出真实的恢复命令:plan 用 mstar workflow register、迭代用 mstar iteration register(为本会话从已注册生命周期中挑一个,是另一条出路)。模型可见 ⟺ 已记录:持久化的 source 不携带任何事实——该行是持久化的锚点,其实际发出的 payload 在同一次发射时按会话持久化为 control 根 store.db 表 dsh_status_emissions 的最新一行,因此「会话日志 + 该存储」无需重新解析该块即可重建该行(dsh packages/AGENTS.md)。dsh session-format V4 在消息准入处拒绝已退役的 { kind: 'plugin', plugin } 包装,故 source 上永远只写生产者自有的 kind。锚点 kind(更名,带读兼容):发出的 kind 为 mstar-engine(更名前为 mstar-engine-status);已发布构建发出的行在其 V3 会话日志中持久化旧的 plugin 包装,dsh V3→V4 迁移会把它提升为 plugin:mstar-engine(更名前标识则为 plugin:mstar-engine-status),该持久行是模型可见的锚点,而面板不再读取它:工作流面板的数据路径是 store 支撑的 mstar/panelSnapshot(见 § Web 客户端插件),该网关只保留 picker 的 mstar/selectWorkflow 写入。面板半体通过宿主共享的 /api typert 网关按需读取工作区快照:路由由宿主网关持有(插件无法注册路由;connection.rpc.handle 的普通信道会经由调用 fiber 上的 webServer 挂载、并使本行的 boot 挂起——本包刻意不走该机制),本包只经可选 ctx.typert.register(...) 子单元贡献 mstar/panelSnapshot 端点描述符。浏览器半体调用 connection.rpc.call('/api', 'mstar/panelSnapshot', { args: { sessionId, cwd } }),得到该会话自己的工作区快照,或带原因的显式 unavailable(绝不返回其它会话的数据、绝不静默空字段)。信任边界,如实说明:该端点自身不做任何鉴权——传输层围栏(host/origin + 浏览器鉴权)只证明调用方是本宿主自己服务的页面,因此持有 (sessionId, cwd) 组合 + 能访问本机 /api 网关即为能力。应答按请求限定:查询以被断言的 id 为键,存储记录的 cwd 必须同时等于断言值与服务端解析出的会话 cwd,客户端在渲染前还会复核回显的 id 与工作区——因此一个会话的请求绝不会被返回另一个会话的记录。payload 是工作区摘要(版本、harness 目录、enforcement、plan/residual/row-scope 计数),面板自身的会话记录本就暴露这些信息;它不被当作机密,而不同的 unavailable 原因会让该端点对已持有 id 的调用方成为一个弱的「会话是否存在」探针。fiber 销毁即移除监听器(HMR 安全)。

发射是变更驱动、而非 turn 驱动:按会话+工作区,首次发射时追加,之后仅当渲染文本或面板相关 payload 投影变化时才追加(该投影会把 store revision 归一化,因为发射自身的 store 写入会推进它——直接比较原始 payload 会把这个副作用读成变化,从而每步都重发)——20 步的 turn 只显示一次 catalog,而不是 20 次,20 个不变 turn 的会话也不再每 turn 堆积一份相同副本。turn 开始本身从不触发,因此未解析到 {HARNESS_DIR} 就完全没有该行(否则该块会是空包裹),面板显示其 waiting 态。两个后果值得明说:发出的块是 payload 的投影(不渲染水印三行,见上),且持久化 payload 就在同一闸门写入——因此已存发射是模型最后看到的 payload(面板读 store,而非该行),其 turn / at 携带发射自身的 turn 与时间、绝不是读取时间戳;只要没有发射,已存行仍记录当前状态。仍保留一条显式重锚路径:picker 提交会驱逐该会话的 digest,故下一步即使文本未变也会重发。已知限制:该行不做周期性重锚,因此宿主侧上下文压缩之后它可能在下一次变化之前缺席——常驻 system prompt 摘要仍携带版本、活跃工作流与其未 Done 的 plans。source 共享同一按工作区缓存条目:显式 harnessDir 时在 boot 构建(否则在工作区首次 pre-step 构建),并按 TTL 刷新(catalogTtlMs,默认 60 秒)——刷新间隔之间热路径只是时间戳比较 + Map 命中,会话中 plan/compass/residual 的变化在一个间隔内落地。

Agent-flow ledger

agent-flow 账本位于现有 control-root store.db 的 host 域,不再使用 workflow JSONL 文件。catalog 和面板窗口只是有界读取投影,不裁剪存储的事件。ACTIVE 权威建立之前,dsh 原生会话日志继续记录,authority 持久化如实报告 unavailable/degraded,并提供 store init / store upgrade 恢复路径;绝不伪造成功或回退到旧文件。真实派发与结算证据仍为咨询式、try/catch 包裹:账本不可用不阻断派发或结算。

  • 记录点(单一核心)——DshHostAdapter.dispatchGate 是两条派发面背后唯一的记录路径:tools/pre-execute 监听器(exec 绑定;租约闸门在此汇入)与宿主 beforeDispatch 钩子(无 exec)。凡是到达闸门的 Assignment 形态派发都会记录,包括 hard 拒绝(判定 ok / advisory / denied);形状守卫在共享核心,故非 Assignment 文本在两面都保持静默。记录为 try/catch 包裹的咨询行为。已知取舍:同一次派发若同时经过两面(宿主 beforeDispatch 之后又以相同文本走 in-loop subagent 工具调用)会记录两条事件——两面按设计互斥,双记录如实记录、不去重。
  • 记录身份——已核实的原生 workflow 事件保留 {sessionId, streamId, seq} 与 wfe1:<kind>:<sessionId>:<streamId>:<seq>。流化身来自持久原生会话头部,绝不是 store epoch 或文件 mtime。实时工具调用行在两个 ID 均已知时可带 wfc1:<sessionId>:<callId>:<kind> 作关联;不伪造缺失 ID,实时行允许重复。
  • 派发(dispatch)——每个 Assignment 形态的派发一行,记录派发身份:role(在写入边界归一化——去首尾空白并剥掉一个前导 @,故 @explore 与 explore 是同一 actor 而非两个角色)、planId、Assignment 的 Task N 标签记为 taskId、taskCategory 与判定。
  • 结算(settle)——仅为真实配对的完成记录。前台调用在 tools/post-execute 监听器结算;{ kind: 'background', jobId } 结果按注册表 jobId 配对(jobs 注册表键,绝非子会话 id),待 ctx.inject(['jobs']) → jobs.events.subscribe 发出终态 settled 事件时结算(completed → ok / killed → denied / failed → error,可用时附 durationMs)。每条配对结算都携带派发身份(Task N 标签仍是 taskId;taskRef 专用于注册表 job id,仅后台结算携带)外加可选 childId——前台 runId,或 catalog 关联已提供的后台子会话 id。可选 id 缺失或超长时只省略该字段:真实完成照常记录,id 绝不截断、绝不重键。未配对载荷不记录任何东西——绝不伪造结算。{ kind: 'continuable', subagentId } 结果本轮没有终态信号,因此不记录结算(子会话拥有自己的轮次),只为子身份关联武装;其它任何成功值结算为 ok,失败结果(isError 或 error payload)结算为 error——返回的前台 runId 无论结果如何都仍是该结算的 childId。
  • subagent-link(非终态)——从父会话自有的 subagent/catalog 事件观测子会话 ID,并在派发的 apply 作用域调用窗口内关联。它记录身份而非完成,不伪造 outcome、verdict 或 paired;catalog 证据缺失时不产生 link 行。关联在按派发的调用窗口内进行:pre-execute 在活跃父 Session 上保留首个原始 label 槽位并以其实 seq 作为窗口起点,tools/post-execute 处有效的 background / continuable 结果使该候选转为 eligible,随后由一个根上下文 session/event 观察器对后续到达者沿会话向前跟踪(补偿扫描冻结在捕获的端点)。当 label 缺失/为空、派发未配对、后台结果无有效 jobId、catalog 版本未知、mode 与结果 kind 不符、continuable catalog 指向的并非工具返回的子会话、槽位图达到容量(每个父 Session 500 个 label)或该槽位已被消费时,不产生任何行——而 apply 之前写入的 catalog(构造期 seeds)永远无法标记新派发。重复 label 为确定性 best-effort(首个保留 + 首个匹配 catalog 胜出),不构成唯一所有权证明;不发出 catalog 的提供者(无 localAgent 的远程运行)会让派发合法地没有 link 行。
  • 原生存储——事件、已接受来源身份、单调扫描下界、会话绑定与最新状态发射分别使用 dsh_ledger_events、dsh_accepted_identities、dsh_scan_bounds、dsh_session_bindings、dsh_status_emissions。不再有共享 JSONL tail/index/cursor/cache 权威、文件压缩、冻结或锁。旧文件字节保留为只读一次性 upgrade 输入/历史。一条账本记录(dispatch/settle/link)会立即失效受影响工作区的 TTL 缓存条目,故下一次 pre-step 重建并持久化 payload,且仅在渲染事实变化时才重新注入模型行;60 秒 TTL 只约束非账本陈旧度。

Workflow 行

同一账本从调用方父会话的原生日志中持久化的 tool-workflow/* 事件记录 workflow / ralph 扇出运行,而非内存中的 workflow/* emits。冷扫描与实时 session/event 监听器消费已核实的来源位置。事件追加、已接受身份/摘要检查与扫描下界推进在同一个原生事务内共同提交。

tool-workflow/* 事件 账本行 字段
run-start workflow-run runId、name、agent?(承载的父会话 id)
agent-start workflow-agent runId、seq(1 起始的成员序号)、label、phase?、childId
run-end workflow-run-end runId、stopReason(completed / cancelled / error)

tool-workflow/agent-end 是上游成员簿记,没有账本类型(成员 outcome 有意不持久化)。缺席的可选字段仍省略。既有展示字段限长与身份尺寸校验保留:超长展示值带标记截断,超长 runId / childId 整行跳过,绝不制造身份碰撞。读取窗口限制只是投影,不是存储截断。

第四种类型 workflow-verdict 由 workflow/ralph 闸门(而非本消费者)写入——每个被把关的调用一行(tool、workflow/objective、mode、判定 ok/advisory/denied/ask、违规 code)——见 Gates → Workflow / ralph gate。展示身份字段(workflow / objective)同样带 1024 字符上限;判定的违规码绝不猜测(P-a workflow.name.unknown vs P-b workflow.lease.uncovered)。

已接受来源回放。 已核实的原生 workflow 事件 ID 经数据库身份/摘要域只接受一次,覆盖冷热重叠与插件重启;同一已接受 ID 携不同字节会被拒绝而非覆写。扫描下界在已核实的流化身内单调推进。会话头部不可读时不接受事件,也不臆造化身。构造期带种子日志的会话在 session/created 上扫描;分叉从 inheritedEventCount 之后开始,保留父会话归属。实时 dispatch/settle/link/verdict 行允许重复,关联 ID 不使它们成为 accepted-operation 权威。缺失、staged、损坏或 schema 拒绝的 authority 如实保持 unavailable;真实的定址无记录仍与这些状态区分,并保留原生拒绝原因和恢复路径。每个事件边界都会解析会话选定的原生目标并校验其当前 store 身份、epoch 与 workflow 作用域:缺失、过期、撤销、损坏或不匹配的权威不记录任何已接受事实,也绝不回退到 newest/only 的 workflow、root 文件或 legacy 目标;原生会话日志记录与权威持久化是否可用相互独立。

childId 关联 + 成员计数。 workflow-agent 行保留已发布成员的 childId(子会话 id);运行的展示 name 只存在于 workflow-run 行,面板为 agent/end 行经窗口查找解析(同一 runId——成员行本身不带名称)。面板把成员 COUNT 挂到 workflow-run 行(窗口内该 runId 的 workflow-agent 行数;窗口有界——被 ≤50 事件窗口截掉的成员如实缺席,绝不猜 0)。

深度咨询(观察时)。 agent-start 时,消费者经 sessions.get(childId) 解析子会话,当其 header.delegationDepth ≥ 2 时告警——每个运行至多一次(per-runId 闩锁),日志器 mstar/workflow-ledger。仅观察时,绝不是拒绝通道:子会话读取抛出只降级咨询本身,绝不影响行或运行。

零行为变更保证。 消费者仅观察:零门禁——每次读取与追加都 try/catch 包裹;账本写入失败绝不崩溃或改变 workflow 运行;会话读取抛出只记一条 warn 并继续。sessions 服务经 ctx.get('sessions') 结构化读取——对 @deepseek-ai/dsh-session 无运行时依赖。

挂载顺序说明。 消费者只在 apply 时 sessions 服务可用时激活——dsh-session 行必须先于 mstar 行挂载(标准 web profile 顺序即如此)。dsh-session 后于插件挂载(或缺失)的组合静默降级:一条 debug 日志(sessions service absent — workflow-ledger consumer disabled)且不记录任何行——绝不是错误,绝不是运行损坏。

面板可见性。 三种 workflow 行经现有事件行样式(无重设计)渲染在 事件记录(Event Log)tab 的 Agent 流转事件分区:摘要身份是运行 NAME(agent/end 行经窗口查找解析;回退 runId → 「未知」),详情体新增四个 workflow 字段——run-id / name / members / stop-reason(缺失 → 「—」)——expected/settled 席位渲染「—」(workflow 行不是角色派发——不存在 settle 配对,与 settle 行同先例)。未知 kind 字符串渲染为通用行(kind 原文、无 workflow 字段)——绝不丢弃、绝不猜测。catalog 摘要把 workflow 行计为独立 workflow 桶(模型行 by role: workflow N)——绝不并入派发角色计数。

维护者视角。 改变账本形态(事件 schema、边界、settle 接缝)必须同步更新投影:gates/agent-flow.ts(记录 / 读取 / settle / catalog 关联监听器)、gates/catalog.ts(agentFlow payload 视图 + 面板投影的发射键)与 client/panel/graph/project-graph.ts(ZoneView flow/agents 投影)——面板只渲染证据展示的内容。

Web 客户端插件(工作流面板)

本包为 dsh web profile 提供浏览器客户端半体,在已安装的 mstar bundle 行上被自动发现(package.json 的 dsh.client 声明 + exports["./client"] → dist/client.js——上游 web dsh.client 发现逻辑扫描 loader entries,并把每个客户端的 exports["./client"] 解析进 boot 图)——无需独立 profile 层或安装步骤(spec §6.1)。web 应用在 /plugins/@mstar-harness/dsh/client.js 提供该 bundle,并经 closure-factory loader 握手加载(window.__ModuleLoader__.load({ id, factory }))。

客户端入口经公开的两段式席位契约把面板注册为右 Sidebar 页签类型:ctx.sidebarRightTabs.register(definition)——id: '@mstar-harness/dsh'、kind: 'mstar-workflow'(页类型——无 patterns/canOpen/priority,按 kind 打开)、跟随 locale 的 title() thunk,以及恰好一个引导页 capsule(order: 20,描述 + MStar glyph 图标)——点选 capsule 会在该 pane 的槽位打开面板(替换引导页签、展开侧栏),再次点选聚焦既有页签(宿主页去重规则)——不自动打开、不重复表面。旧 conversation.view view-ring 页签已移除(迁移,而非第二表面):sidebar 页签取代会话区页签。面板体与其 chip 标题在同一 id 下注册为 keyed 席位(sidebar.right.pane.tab + sidebar.right.pane.tab.title;chip 为 glyph + 打开时捕获的标题——不跟随会话中途的语言切换)。tab.visible === false(列折叠或同 pane 其它页签激活)时面板体**不渲染任何内

…

内容来自项目 README(GitHub)↗

链接

同类插件

查看整个分类 →

社区评论

评论公开保存在 GitHub Discussions。加载评论会连接 GitHub 和 Giscus;发表内容需要 GitHub 账号。