工作流与自动化

mstar-harness

btspoony/mstar-harness · ★ 69

btspoony

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

许可证
MIT
收录
2026-08-14
维护状态
active
安装方式
github
查看 manifest 检查详情
manifest 状态
已声明
manifest 路径
package.json#dsh
manifest 检查
2026-08-19
生命周期脚本
未发现

manifest 静态检查只记录声明与安装脚本,不代表兼容性或安全审查。

安装

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

GitHub 源码安装:首次需按提示配置 allowBuilds 构建授权后重试

安装与环境配置指引、插件开发教程见 DSH 中文社区文档 ↗

项目说明

原始 README · 正文语言:中文 · 阅读英文 README

目录
  1. Usage
  2. Install paths
  3. Headless profile(一次性运行)
  4. Configuration
  5. 组合后的行集合
  6. What the plugin does when mounted
  7. Enforcement semantics
  8. Gates
  9. Status gate
  10. Dispatch gate
  11. Lease gate
  12. Skill lint gate
  13. Workflow / ralph gate
  14. Execution read route
  15. LLM fallbacks integration
  16. 能力探测
  17. 角色身份交付(原生 subagent preset 通道)
  18. 角色 seeds 与采纳建议(Adoption advisory)
  19. 配置面
  20. Service
  21. Host adapter
  22. Skills mount
  23. Commands
  24. Workflow scripts
  25. Native command surface
  26. Shared MCP connection(显式声明的 control 根)
  27. Engine seam mapping
  28. Engine-status catalog
  29. Agent-flow ledger
  30. Workflow 行
  31. Web 客户端插件(工作流面板)

English | 中文

dsh

让 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 载体——team_task_create、team_task_update、send_message。持久 teammate 由 subagent / subagent_fork 本身创建(经 subagent catalog 命名的可续接子代理),因此创建调用按普通 subagent 派发把关。

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 审查者;审查者不占自己的席位——没有 roster,持久 teammate 是可续接的 subagent 子代理 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)中仅当工作区解析出 ACTIVE workflow 时模型可见一次;无工作流上下文时两个 prompt 表面都不注入任何内容(空文本会被 dsh 丢弃,不会渲染成空行),故该行绝不重复它们。回退组合:只要 prompt 注册未被确认生效——宿主未提供 system-prompt 服务、异步注册失败(返回 true 仅表示 inject 子已排期)、或既有注册被释放——监听器逐步骤求值的 showWatermark 判定即让该行自行重渲染水印三行,版本 / harness 目录 / enforcement 事实因此不会丢失(随后才生效的注册会自动结束回退)。监听器先调用 next() 并基于委托后的决策追加——从不否决步骤、从不替换已组合的消息。该行仅为 ACTIVE 工作流上下文追加:当无法解析出工作流——无活动生命周期、多活动未绑定、status.missing、store.not-initialized 或终态历史——步骤消息中不追加任何内容,该判定仅面板与 CLI 可见(持久化的 dsh_status_emissions 快照仍携带它;CLI 拒绝文本指出原因与真实恢复命令: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 摘要仅在解析出 ACTIVE workflow 时仍携带版本、活跃工作流与其未 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: 'activation', name } 结果——dsh 0.2.2-rc.3 的委派工具唯一返回的形状——在工具返回时不记录结算:名字经 subagent surface 解析为该子会话的 SessionId 并配对,由其自身的 subagent/end 按同一套结果映射结算该派发。早于该异步解析到达的 end 按直接父会话保留,解析落地时对账;任何在飞派发都无法认领的 end 记为显式未解析延续,绝不由发明的配对结算。其它任何成功形状同样记该未解析延续——不可归属的载荷不是完成——而失败结果(isError 或 error payload)结算为 error。
  • 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,以及*

…