我想知道它能帮我干什么
按「问题 → 上手 → 边界」走,不碰源码。
这不是一个插件,而是围绕「把长任务拆成树、让每一层都真的有人干、干完还能验收和接力」的一组 DSH 包与规约:
执行层 tree-engine 提供 9 个 tree_* 工具(含只读自检 tree_doctor),会话树单包 session-tree 提供可见的侧栏树、跨层通信与 50% 交接,
外加自省层 introspect,以及 3 份随包 Skill。
图序(按概念而非出现顺序):1 架构 · 2 工具面 · 3 会话树 · 4 状态机 · 5 42/50 · 6 时序 · 7 时间线 · 8 发布 · 9 优先级
按「问题 → 上手 → 边界」走,不碰源码。
先看分层与接口,再看状态机、验证与发布门禁。
工具面、所有权、阈值与失败语义优先;不要凭常识补动作。
What / Why / How —— 先建立一张心智图,再看细节。
它不是单个插件,而是一组围绕树形分解的 DSH 包:执行层 tree-engine(9 个工具 + 竹节接力 + leaf 写面护栏)、会话树单包 session-tree(侧栏树 + tree_send + session_handoff)、自省层 introspect(self_spec)。
事实:根 README.md 包表;各包 package.json。
单会话上下文有限;DSH 默认侧栏把 origin:'subagent' 的行藏起来,跨层/兄弟会话也没有内置通信路径;任务拆下去后,若没有账本、所有权与验收,就会「派了但不知道干到哪」。
事实:docs/architecture/session-handoff-2026-11-11.md §0.1;packages/dsh-session-tree/README.zh.md「为什么」。
profile 里 link: 两个包并 pnpm install,对 bundle 做一次 disable→enable;新开会话即可看到 3 个 Skill。然后说「把这个任务拆成三层并派人做,验证通过再收口」,模型按 Skill 调工具。
事实:docs/guides/skills-usage.md §2–§4;D12 热更纪律。
树是账本,会话是执行体。任务分解成 leaf(账本行),每个 leaf 派一个真实 DSH 子会话去干;上下文到 42% 时引擎给同一个 leaf 换会话(竹节),到 50% 时任意会话可同层接替(handoff)——两种接力,都不丢任务书。
ctx 用 DSH 原生服务。@orphiczhou/* 三个候选名在 registry 均 404,安装只走 Git / link:(D3)。| 包 | 版本 | 状态 | 一句话 |
|---|---|---|---|
dsh-tree-engine | 0.13.0 | 运行中 | 9 个 tree 工具(含自检)+ 竹节 + 护栏 + 验证 + /tree-panel 只读投影路由 |
dsh-session-tree | 1.8.3 | 本仓 | 侧栏树 + tree_send(同树)+ handoff + Skill + Tree Runs 面板 + 面板 v2(Flow Runs 同布局:列表+树图+详情)+ 树图高度可调/打开即 Fit(v1.8.0)+ 图内节点点击修复(v1.8.1)+ 依赖关系可读性(v1.8.2:边 title/选中高亮/Blocks) |
dsh-agent-introspect | 0.1.0 | 运行中 | self_spec 自省 |
来源:根 README.md §组件与状态;agent.md §2;各包 package.json。
不读源码也能建立正确预期;每张卡都给出「最容易误解的点」。
DSH(DeepSeek Harness)是插件宿主。一个 bundle 由宿主半(index.js)和可选的客户端半(client.js)组成;cordis.patch.yml 决定它向 profile 贡献哪些行。
易误解:改了 index.js 保存后工具就变——不会,Loader 按包名缓存宿主模块,必须 disable→enable。
把 DSH 左栏换成一棵可展开的树:每个会话下面挂它的 subagent 后代,任意深度;可按工作区分组、隐藏/恢复、搜索、按最近活动排序。
易误解:树只解决「看得见」;跨层发消息要靠 tree_send,接替要靠 session_handoff。
leaf 是账本里的一行(不是会话本身):有 leaf_id、parent、role、runtime、events、verification。三层上限:root → commander → worker,worker 不能有子节点。
易误解:leaf 的 session_id 可以换(竹节/重派),账本不换。
worker 用 tree_report {action:"context", pct} 自报水位;pct ≥ 42 时引擎在同一个 leaf 上换一个新会话接手,旧会话先 interrupt,任务书/简报跟着走。
易误解:这是引擎自动的;不等于 50% 的会话交接,也不改 attempt。
任意层会话在上下文约 50% 时,session_handoff 写一份 HANDOFF-*.md,并启动同层级接替会话:子会话→同父兄弟,根→新根(或父不活时降级根并标 degraded)。
易误解:交接不自动迁移 tree leaf 的 owner;接替会话要写 done,需先 set-session 重绑。
竹节是引擎对 leaf 的换棒(更早、自动、保任务树);交接是会话对会话的接替(更晚、手动/纪律、保会话层级)。
协调规则:先按竹节;已经 50% 还没等到竹节(链满 frozen、简报回收失败、已不是 running owner)→ 立即交接,并在 tree_report progress 留痕。
以下为开发态 link: 安装;只想用会话树可跳过 tree-engine(见 §8 边界)。
编辑 %USERPROFILE%\.dsh\profiles\desktop\package.json,在 dsh.profile.bundles 与 dependencies 中各加两项;改前先备份。
{
"dsh": { "profile": { "bundles": [
"@local/dsh-tree-engine",
"@local/dsh-agent-introspect",
"@orphiczhou/dsh-session-tree"
] } },
"dependencies": {
"@local/dsh-tree-engine": "link:D:/Codes/dsh-tree-harness/packages/dsh-tree-engine",
"@local/dsh-agent-introspect": "link:D:/Codes/dsh-tree-harness/packages/dsh-agent-introspect",
"@orphiczhou/dsh-session-tree": "link:D:/Codes/dsh-tree-harness/packages/dsh-session-tree"
}
}用 DSH 自带 runtime 的 pnpm,不要另装 Node。
node "$env:USERPROFILE\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\pnpm\bin\pnpm.cjs" install新增/修改 index.js 或 cordis.patch.yml 后,对相应 bundle entry 做一次 disable→enable;只保存文件不会重新求值。
plugin_manager {action:"set_plugin", target:"include:session-tree", enabled:false}
plugin_manager {action:"set_plugin", target:"include:session-tree", enabled:true}
plugin_manager {action:"set_plugin", target:"include:tree-engine", enabled:false}
plugin_manager {action:"set_plugin", target:"include:tree-engine", enabled:true}Skill 目录在会话启动时注入;旧会话不会刷新。新会话应能看到 session-handoff、tree-commander、tree-worker。
把这个任务拆成三层并派人做,验证通过再收口:
给仓库补一段 CHANGELOG,要求测试全绿、有 Unreleased 段。根会话应调 tree_plan / tree_node / tree_dispatch;执行者用 tree_report 上报;验收用 tree_verify;tree_status validate 应为 0 issues。
| 检查项 | 期望 | 不满足时先查 |
|---|---|---|
| 工具面 | 能看到 tree_send、session_handoff、9 个 tree_* | bundle 是否启用;include:session-tree / include:tree-engine 是否重载 |
| Skill 目录 | 3 个 Skill 各出现一次 | 是否新开会话;profile 是否有 @deepseek-ai/dsh-skill-filesystem(DSH 内置) |
| 会话树 | 左栏出现嵌套会话;SessionTree provider 在线 | 客户端半是否加载;刷新页面一次 |
| 交接 | session_handoff {action:"status"} 渲染行含 threshold 50%、preset=、permission=、lang= | 是否旧实现遮蔽(移除旧 bundle);是否宿主半未重载 |
| 引擎 | tree_status {action:"validate"} 可调用;sweepMode=timer | tree-engine 是否启用;apply.log 尾部是否有 engine ready |
事实来源:README.md §快速开始/验证运行;docs/guides/skills-usage.md §2–§3;agent.md D12;packages/dsh-session-tree/README.zh.md「确认装好了」。
① 新会话直接 handoff 被 below-threshold 拒——这是预期,说明工具已挂上;想看完整路径加 force:true,只想写文件用 spawn:false(干跑不被阈值闸拦)。
② 5 分钟内第二次交接被 recent-handoff 拒——防重复闸,不是故障;确需立刻再写才用 force:true。
③ Skill 目录里没有三个 Skill——先确认是不是旧会话;目录只在会话启动时注入。
十来个工具不算多,但要分清「谁提供、管哪一层、边界在哪」。
| 能力 | 入口 | 能做什么 | 关键边界(别误解) |
|---|---|---|---|
| 侧栏会话树 | client.jsSessionTree provider |
把左栏换成嵌套树:任意深度展开、点节点打开会话;按宿主 workspace 分组;工作区排序(最近活动 / Host 顺序)、隐藏/恢复、搜索召回、已归档会话三态。 | 工作区归属看 workspace.sessionIds,不是 cwd;排序/隐藏是客户端 localStorage 视图状态;客户端半改动刷新页面生效。 |
tree_send |
session-tree 宿主半 | 给树里任意可续聊子会话投递消息,包括既不是直接父、也不是直接子的兄弟;delivery 可选 steer(最近步边界)或 queue(下一轮)。 |
按目标的持久化父地址授权,所以直接父会话必须活着、目标必须 continuable;只返回受理,不等待回复。 |
session_handoff |
session-tree 宿主半 | status 读上下文占用/路由/预设/权限/工作区/接替方案;handoff 写 HANDOFF-*.md 并启动同层级接替会话,继承 cwd/工作区/Agent 预设/权限模式/模型/思考等级。 |
阈值缺省 50%;5 分钟防重复;spawn:false 只写文件(不被阈值闸拦);提示语只做 zh/en,其它语言回退英文。 |
9 个 tree_* |
tree-engine 宿主半 | 建树、建 commander/worker、依赖编排、派发/取消、上下文自报、事件、收割、验证(6 模式 + 对抗式)、日志、备份/恢复/登记、只读自检(tree_doctor,7 检查项)。 |
action 是闭集(见图 2);tree_verify FAIL 不阻断 succeeded;set-status done 在工具面打不通(里程碑无写入命令);tree_doctor FAIL 也不 throw(诊断器不是门禁)。 |
| leaf 写面护栏 | src/guards.jsLEAF_WRITE_MATRIX |
统一判定「谁能写这一个 leaf」:set-context / set-verification / 非 done event / dispatch:cancel / status / set-session 六类写操作走同一张矩阵;未知 kind fail-closed。 |
非授权一律 E_BORROWED_IDENTITY;done 仍只给 owner;root 只在 context/status 有例外(不扩大到 verification/set-session);矩阵是代码事实,不是 Skill 口号。 |
| 3 个随包 Skill | @deepseek-ai/dsh-skill-filesystem由两包 patch 第 2 行挂载 |
把「怎么拆三层 / 怎么当 worker / 50% 怎么交接」写进会话可发现的 Skill 目录;极简提示词即可触发,不必先喂工具名。 | 目录在会话启动时注入,旧会话不刷新;patch 行改动需 disable→enable;缺 provider 时工具仍可用,只是少目录项。 |
self_spec |
agent-introspect 宿主半 | 投影当前会话的 model、permissions、sandbox、cwd、token 用量;给 AI Agent 判断「我在什么权限/模型下干活」。 | effort 与温度显式不可读;只读投影,不改会话。 |
| 活体观测 | cordis_inspect_listcordis_inspect_query |
列 provider、查 host Tool / Service / Config 与 client provider;验收「工具是否真的注册」的唯一可编程通道。 | 只读;依赖宿主开权限;活体读数可能受 Loader 缓存影响(旧实现仍在线)。 |
| 竹节接力 | tree-engine sweep |
worker 自报 pct ≥ 42(或宿主 tokenMeter 先到)→ 旧会话出 K1–K5 简报 → 先 interrupt 后 start 新会话 → 同一 leaf 继续,owner 重绑给接手会话。 |
仅非 root;active 时才置 segment_pending;链长 5 → runtime.state=frozen;attempt 不变(不是重试)。 |
| 验证策略 | src/verify.js + ports |
六种模式:self-report / artifact / command / llm-judge / composite / human;按 leaf.taskType 路由到策略模板,DoD 在派发时前置注入。 |
llm-judge 宿主端口未装配时 fail-closed;human 在 approval=never 下降级 frozen 待裁;FAIL 只落账,不替 commander 做决定。 |
事实来源:packages/dsh-session-tree/README.zh.md「功能」;packages/dsh-tree-engine/index.js 工具 schema(9 个);src/verify.js;src/guards.js(LEAF_WRITE_MATRIX);src/doctor.js(7 检查项);docs/guides/skills-usage.md §8。
tree_doctor 只读自检),右边 2 个是「会话层能力」,第 5 行右半是写面护栏(能力不是工具:LEAF_WRITE_MATRIX 决定「谁能写这个 leaf」);每张卡第二行是该工具真正支持的 action——不在卡片里的 action 会返回 unknown action,docs/architecture/tools-mapping.md 里的 drift / milestone-* / gc 等仍在设计稿里。tree_send 则允许跳过父子邻接直接给树里任意可续聊会话发消息。关键:leaf 是账本,不是会话,所以换会话不等于换任务。tree_dispatch 并行;tree_status harvest 收割,逐点 verify。tree_verify → 读 result.pass 再收口;root 最后 validate。tree-engine 的 tree_* 只负责任务账本与执行编排;会话生命周期(创建/fork/列表)仍走 DSH 原生 subagents,跨会话消息也可用内置 send_message(但只覆盖直接父子)。
发布面只有会话树是「公开镜像包」;tree-engine 与 introspect 随本仓公开、未单独发仓(见 docs/guides/publishing.md §1)。
事实:docs/guides/publishing.md §1;docs/architecture/tools-mapping.md §4。
看懂「谁调用谁」比记住文件名重要;这张图也解释了为什么它能离线测试。
整个方案可以压缩成四层:DSH 宿主提供会话/工具/定时器;profile 决定装哪些 bundle;插件宿主半把 DSH 服务翻译成工具与端口;纯逻辑负责状态机、护栏、验证与竹节。客户端半是旁路,只负责左栏那棵树。
| 维度 | 宿主半 | 客户端半 |
|---|---|---|
| 入口 | exports["."] → index.js | exports["./client"] → client.js |
| 声明 | dsh.bundle.patch | dsh.client(platform:"web") |
| 装载 | patch insert 行 → Loader import | window.__ModuleLoader__.load() |
| 职责 | 注册工具 / 注入服务 / 挂 Skill provider | 侧栏 DOM / 工作区分组 / 菜单 |
| 热更 | disable→enable 或重启 DSH | 刷新页面 |
| 失败半径 | 工具缺失或协议不符 | 界面半边不渲染;宿主半仍工作 |
事实:根 README.md §宿主半/客户端半;docs/archive/handoff-2026-10-14.md §5 客户端契约。
引擎把宿主能力收束成几个端口:派发、取消、读会话、glob、执行命令、judge。生产装配接 DSH 服务,测试装配接假实现——这是它能同时做到「深逻辑」与「离线 112 项」的原因。
Skill 则走另一条装配:两个 tree 包各在自己的 patch 第 2 行 insert @deepseek-ai/dsh-skill-filesystem,bundledSkillDir 经安装包身份解析到包内 skills/,不字符串拼 baseUrl。
- insert:
- id: tree-engine
name: '@local/dsh-tree-engine'
- id: tree-engine-skills
name: '@deepseek-ai/dsh-skill-filesystem'
config:
providerName: tree-engine
includeDefaultRoots: false
watch: false
bundledSkillDir: !!js process.getBuiltinModule('node:path')
.join(/* 经 require.resolve(package.json) 定位 */, 'skills')事实:packages/dsh-tree-engine/cordis.patch.yml;docs/guides/skills-usage.md §1。
三个包都不 import 任何 @deepseek-ai/* 包,只通过宿主 ctx 取服务。好处是测试不需要装载 DSH;代价是 DSH API 漂移时要自己补兼容层——RC2 的 startContinuable 移除就是一次实例,当前兼容层已运行但缺单测。
以 2026-11-11 A 组真机树 chglog 为骨架;命令/返回做了可读化重排,数值与结构来自报告。
目标:给仓库补一段 CHANGELOG。根会话建树并派一个中间层 commander,commander 再建 6 个 worker;其中一个 worker 的产物被独立验收判 FAIL(HEAD 断言在提交后失真),修复后复审 PASS,最终 7 个非 root 节点全部 succeeded、tree_status validate 为 PASS (0 issues)。
| # | 谁 | 调用 | 可见返回 / 证据 |
|---|---|---|---|
| 1 | 根会话 | tree_plan {action:"create", tree_id:"chglog", session_id:"<uuid>", root_brief:{goal:"补齐 CHANGELOG"}, root_dod:{dod:"测试全绿 + Unreleased 段"}} | tree_plan: created tree chglog (root chglog-root)tree_id 4–8 字符,小写无连字符 |
| 2 | 根会话 | tree_node {action:"add", tree_id:"chglog", leaf:{leaf_id:"chglog-C1-commander", parent:"chglog-root", path:"C1", role:"commander", added_by:"<root>", taskType:"doc"}} | tree_node: chglog-C1-commander status=pending_brief · (未派发) ctx=0% |
| 3 | 根会话 | tree_dispatch {action:"start", tree_id:"chglog", leaf_id:"chglog-C1-commander", prompt:"作为 C1 指挥官:拆出 facts/写作/验收 worker,派发并收口。"} | tree_dispatch: chglog-C1-commander → running依赖未满足会 E_DEPENDENCY_NOT_MET |
| 4 | commander | tree_node {action:"add", … parent:"chglog-C1-commander", leaf_id:"chglog-C1a1-facts", role:"worker", taskType:"research"} | 若再 tree_plan create 同 id → E_DUPLICATE_LEAF;自拟新 id → 静默分裂 |
| 5 | commander | tree_dispatch {action:"start", leaf_id:"chglog-C1a1-facts", prompt:"…"} | 子会话收到「任务书 + 策略 DoD + 结算指令」;dod 参数不改变验收标准 |
| 6 | worker | tree_report {action:"context", tree_id:"chglog", leaf_id:"chglog-C1a1-facts", pct:42} | tree_report: ok (chglog-C1a1-facts)pct 必须是整数;42 为 DSH 缺省阈值 |
| 7 | 引擎 | sweep 检测到 pct ≥ 42 → 发 K1–K5 简报指令 → interrupt 旧会话 → start 新会话 | tree_status harvest 可见 bamboo(ok);owner 重绑,新会话可写 done |
| 8 | owner | tree_report {action:"event", type:"done", meta:{summary, self_check}} | runtime.state = succeeded;事件 12 类闭集,done 仅 owner 可写 |
| 9 | commander | tree_status {action:"harvest", tree_id:"chglog"} | 立即触发一轮 sweep;后台仍有 60s 定时;sweepMode=timer |
| 10 | commander | tree_verify {action:"run", tree_id:"chglog", leaf_id:"chglog-C1a1-facts"} | tree_verify: PASS (artifact) 或 FAIL;裁决落 leaf.verification |
| 11 | verifier | 按策略执行 self-report / artifact / command / judge / composite / human | FAIL 返回 {result:{pass:false}},不抛错;真实 A 组出现 VERDICT: FAIL → 修复 → PASS |
| 12 | 根会话 | tree_status {action:"validate", tree_id:"chglog"} | tree_status: validate PASS (0 issues);A 组最终 7 个非 root 节点全 succeeded |
事实来源:docs/reports/skill-e2e-2026-11-11.md §4 A 组(修正后 chglog:root + commander + 6 worker,maxDepth=2,7 个非 root 节点 succeeded,validate 0 issues,真实 FAIL→PASS);docs/guides/skills-usage.md §5;packages/dsh-tree-engine/index.js 工具描述。示意:命令参数与单行返回为可读化重排,ID/摘要做了简化。
引擎内部完成「测量 → 交棒指令 → 简报回收 → interrupt → start → 落账」。新会话拿到角色预设 + 原任务书 + 简报全文 + DoD;leaf.session_id 重绑给新会话,所以新会话能写 done。
不是重试:attempt 不变;不是新 leaf:树结构不变;链长上限 5,超限 frozen。
session_handoff 先写 HANDOFF-*.md,再启动同父兄弟;接替会话继承 cwd / 工作区归属 / Agent 预设 / 权限模式 / 模型 / 思考等级,首条消息跟随界面语言。
树账本不会自动迁移:交接只发生在会话层,leaf.session_id 仍是旧会话;接替会话若要写 done,需由 leaf 的 creator/上级 tree_node set-session 重绑。
A 组能跑通,但报告也写明了限制:三次交接全部用 force:true 模拟,真实 50% 阈值没有跑到;其中一次中间层 attempt1 在收尾前约 30 分钟超时,靠 attempt2 续跑才收口;C 组修正前还遇到宿主 429 配额中断。这些是「真机证据」的一部分,不应被 7/7 succeeded 的摘要盖住。
这一节最接近「协议」;如果只看一段,建议看 6.3 的 owner 表和 6.4 的阈值表。
「工作模式」= Agent preset(决定组成/工具集);「权限」= permission preset(sandbox + approval 捆绑)。两者是不同服务,必须分别继承。
| 层级 / 创建方式 | 工作目录 | 侧栏工作区 | Agent 预设 | 权限模式 | 模型 / 思考等级 |
|---|---|---|---|---|---|
rootagents.create + 发布前 setup |
meta.cwd + workingDirectory.set |
创建后 workspaceRegistry.resolveByPath(cwd) → Workspace.attachSession |
meta.agentPreset + setup 内 agentPresets.mount + agent-preset/selected |
setup 内追加 permission/preset、sandbox/mode、approval/policy,必须在发布前 |
agentOptions 原样携带 provider/model/reasoningEffort/maxTokens |
siblingsubagents.startActivationprovider:"spawn" |
request.cwd |
不需要:侧栏渲染在父会话下、与源同层 | 委派自动继承父组成(不额外传 agentPreset) |
委派自动继承(source:"delegation") |
request.agentOptions 原样携带 |
| degraded root 子会话但父已不活 |
同上 | 同上 | 同上 | 同上 | 同上;返回显式 degraded:"parent-inactive" |
事实来源:docs/architecture/session-handoff-2026-11-11.md §0.2–§0.3;packages/dsh-session-tree/index.js 的 spawnSuccessor。真机验证:root 14/14、sibling 12/12(docs/reports/e2e-handoff-2026-11-11.md);B/C 组 verify-handoff 各 12/12。
set-session 才让接替者写 done。| 维度 | 竹节(tree-engine) | 会话交接(session-tree) |
|---|---|---|
| 触发 | worker tree_report {action:"context", pct≥42},或宿主 tokenMeter 测量先到 | 任意会话 session_handoff {action:"status"} 读到 context_pct ≥ 50,由模型/用户发起 |
| 范围 | 同一个 leaf 换执行会话;树结构、任务书不变 | 同一层级换会话:子→同父兄弟;根→新根 |
| 产物 | K1–K5 简报注入新会话提示词;runtime.segmentChain 追加 | HANDOFF-*.md 落工作区;首条提示让接替者先读 |
| owner | 接力成功后 leaf.session_id 重绑给接手会话(v0.5.0 起) | 不自动迁移;需 leaf 的 creator/上级 tree_node set-session |
| 阈值/上限 | 缺省 42;链长上限 5,超限 frozen;attempt 不变 | 缺省 50;5 分钟防重复;force 可双绕;spawn:false 只写文件 |
| 失败语义 | 简报缺失 → no-handoff-summary 降级接手;超时/取消先到者生效 | 文件写失败 → 整体报错;spawn 失败 → 保留文件 + spawn_error |
| 协调 | 先按竹节:已换棒就不必再交接;50% 仍没等到竹节(链满 frozen / 简报回收失败 / 已不是 running owner)→ 立即交接,并在 tree_report progress 留痕。 | |
事实来源:docs/architecture/segment-handoff.md §4;packages/dsh-tree-engine/src/engine.js set-context/bambooRelay;packages/dsh-session-tree/index.js 阈值与防重复;docs/guides/skills-usage.md §8。
| 时机 | leaf.session_id | 后果 |
|---|---|---|
tree_dispatch start | 绑为执行者会话 | 执行者可写 done |
| 竹节接力成功 | 重绑为接手会话 | 接手者可写 done(v0.5.0 修复) |
session_handoff | 不变 | 接替者写 done 会被 E_BORROWED_IDENTITY 拒 |
tree_node set-session | 由 leaf 的 creator/上级重绑 | 交接后恢复写 done 的合法路径 |
事实:src/engine.js dispatch/bamboo/set-session;tree-commander SKILL §1.3/§3.3。旧版 B1 缺陷已在 v0.5.0 修复并加回归测试。
如果 commander 能代写 worker 的 done,验收就退化成自证。引擎因此把 done 事件的所有权钉在 leaf.session_id 上;set-status 则放宽到 owner / creator / root(用于剪枝、归档)。
但注意边界:set-context、set-verification、非 done 的 event:append、dispatch:cancel 目前在引擎侧没有统一的 caller 校验(审计 P1-05);「借身份全拒」的旧表述不成立,见 §8。
| 场景 | 会发生什么 | 是否预期 / 怎么处理 |
|---|---|---|
新会话直接 handoff | below-threshold,返回 context_pct 与 threshold_pct,不写文件 | 预期:证明工具已挂载。想看完整路径加 force:true;只想写文件用 spawn:false |
spawn:false,低于 50% | 阈值闸被 fileOnly 绕过;写 HANDOFF-*.md,status="file-only",不启动会话 | 预期:v1.3.3 起的行为;防重复闸仍生效 |
5 分钟内第二次 handoff | recent-handoff,返回上次时间与文件路径 | 预期:防重复;确需再写才 force:true |
| 交接时 spawn 失败 | 文件已保留;返回 handoff_path + spawn_error,successor="unavailable" | 不是「没写成」:文件在;修好服务后用 force:true 重试(否则可能撞防重复) |
| 继承部分失败 | status="handed-off" 仍成立;warnings[] 非空,successor.preset_error / permission_error / workspace.reason 暴露 | 接替会话可用但继承不完整;验收必须同时看 warnings,不能只看 status |
| pct 不可得 | 带 warnings 继续,不臆造百分比;阈值闸无法评估 | 看 context_pct="unavailable",不要当成 0% |
locale 条目services.get("loader").resolve("locale").options.config.preference;volatile 引用经 get() 展开;按包名 @deepseek-ai/dsh-client-locale 兜底查嵌套条目。
cordis.patch.yml / cordis.yml 中 locale 条目的 preference;优先 DSH_PROFILE_DIR,宿主未导出该变量时用 process.cwd()(实测宿主 cwd 就是 profile 目录)。
zh* → zh;en* → en;其它已存语言(ja/es/fr/de/ru/pt…)与无偏好 → en。每次 status/handoff 重新解析,不缓存。
事实来源:docs/reports/e2e-kickoff-language-2026-11-11.md §1–§3;CHANGELOG.md 1.3.1 的「已知边界」。真机:修复前 lang=en → 修复后 lang=zh 且接替首条中文 PASS。
| 你改了什么 | 生效方式 | 原因 / 验收 |
|---|---|---|
client.js(侧栏) | 刷新页面 | 客户端半由浏览器加载;热更可能残留旧实例,刷新最干净 |
index.js(宿主半) | 对 bundle entry disable→enable,或重启 DSH | Loader 按包名缓存已导入宿主模块;只保存文件不会重新求值(D12) |
cordis.patch.yml(新增/改 insert 行) | 对 bundle entry disable→enable | patch 是装载期层;新增 Skill provider 行也走这条 |
skills/*/SKILL.md 正文 | 下一次新会话直接读到 | 目录在会话启动时注入;旧会话不刷新;目录描述可能热更新,但正文按需读取 |
profile package.json(bundles/dependencies) | pnpm install + 重载/重启 | 新增包走新包名无缓存;并入已有包名则仍需重载 |
| 版本号 | bump + 发布同步 | 市场按 package.json.version 判断更新(D6);不 bump = 假更新 |
① 两个 tree 包的 cordis.patch.yml 第 2 行 insert @deepseek-ai/dsh-skill-filesystem(providerName 唯一、includeDefaultRoots:false)→ ② bundledSkillDir 经 require.resolve(pkg/package.json) 定位包内 skills/ → ③ 宿主挂载 provider → ④ 新会话启动时把目录写进 <available_skills> → ⑤ 模型按意图命中或 skill {name} 加载正文。
leaf.status——这也是真机里最容易误读的一处。① done 不是绝对终态:仍可转 pruned / archived,但不能回 active。
② set-status done 在工具面不可达:它要求 milestones 非空且全 audit_pass,而工具面没有 milestone 写入 action;正常收口走「done 事件 → runtime.succeeded」。
③ failed 在 runtime 设计里存在,但当前代码没有赋值路径;不要把它当作可等待的终态。
这套项目的发布纪律比功能更值得看:18 文件 SHA 一致、三轮洁净室、npm 刻意冻结。
| 对象 | 命令 | 结果 | 依赖 / 备注 |
|---|---|---|---|
dsh-tree-engine | node --test tests/*.test.js | 213/213 | 纯逻辑 + 假时钟/假 store;含 doctor 9 例、写面护栏 8 例负例、compat 14、identity 10、budget 7、relay 11、token-meter 11、usage-port 3、sweep 8、depth-cap 4;--test-reporter=tap 要放在位置参数前 |
session-tree handoff | node test/handoff.test.js | 41/41 | mock 四类服务;含语言跟随 6 例 + spawn:false 干跑 |
session-tree skills | node test/skills.test.cjs | 3/3 | frontmatter / package.json.files / patch provider 行 |
session-tree render | node test/render.test.cjs | 全绿 133/133 + 9/9 + 11/11 | 确定性夹具渲染;客户端半的 DOM 契约 |
session-tree style | node test/style-guard.cjs | 22/22 | 样式注入 / SSR 边界 |
session-tree bundle | node scripts/verify-bundle.mjs | 0 fail | 发布物清单自检 |
provider-conformance | node test/provider-conformance.cjs [asar 解包目录] | 29/29需 rc.2 兼容 fixture | 默认读 %TEMP%\dsh-asar-inspect\out;缺目录 ENOENT;DSH 0.2.2-rc.1 布局漂移 |
实测:2026-11-12 复跑 tree-engine 165/165、handoff 41/41、skills 3/3、style-guard 22/22,退出码均为 0;tree_doctor 活体 7/7 PASS(version=0.8.0)。注意:不要写 node --test tests——Node 24 会把目录当文件路径,报 test at tests:1:1 的假失败。
| 版本 | 日期 | 主题 | 提交 | SHA 一致 | 备注 |
|---|---|---|---|---|---|
| session-tree 1.1.0 | 2026-11-11 | 工作区排序 / 隐藏 / 召回 | dcf3519 | 15/15 | 客户端半;刷新页面生效 |
| session-tree 1.2.0 | 2026-11-11 | 交接并入 + 同工作区/预设/权限继承修复 | 597ca31 | 16/16 | 独立 handoff 包删除 |
| session-tree 1.3.0 | 2026-11-11 | 随包 session-handoff Skill + skill provider patch | 1086e9e | 18/18 | tree-engine 0.5.0 同步 |
| session-tree 1.3.1 | 2026-11-11 | 接替提示语跟随界面语言(zh/en) | c257d61 | 18/18 | 真机 en→zh PASS |
| session-tree 1.3.2 | 2026-11-11 | Skill 使用文档补全(洁净室一轮) | c1541e5 | 18/18 | G1–G12 修订 |
| session-tree 1.3.3 | 2026-11-11 | spawn:false 干跑绕过阈值闸 + N1–N7 | cce2975 | 18/18 | handoff 41/41 |
| session-tree 1.3.4 | 2026-11-11 | R1-B/R2-B 文档债清扫 | f784c6e | 18/18 | 无代码行为变化 |
| session-tree 1.4.0 | 2026-11-13 | Q4 tree_send 同树收紧 + 会话界面元数据(composer.dock + header chip) | 0343f0c | 21/21 | 当前公开镜像;main + tag |
| session-tree 1.3.7 | 2026-11-12 | W2.2 provider-conformance rc.2 fixture 解析(Wave 2) | 91c177e | 19/19 | 上一版公开镜像 |
| session-tree 1.3.6 | 2026-11-12 | 文档归档 + 人类/Agent 安装指南 | 298298d | 19/19 | 上一版公开镜像 |
| session-tree 1.3.5 | 2026-11-11 | 第三轮洁净室 PASS 收尾 | 1fb9193 | 18/18 | 上一版公开镜像 |
事实来源:docs/guides/publishing.md §3/§5;docs/reports/skill-cleanroom-2026-11-11.md;CHANGELOG.md。本仓 master 最新以 git log 为准(2026-11-12:Wave-2 tree-engine v0.7.0 + 组合修复 v0.8.0 + 工具链/文档收口)。
--target,不运行任何 git(不 add/commit/push/tag)package.json:内容变化必须先在源包 bumpfiles/match/mismatch/missing/extra--force)Git 安装已够用;npm token / 2FA / CI 是额外凭据面;不发 npm 就不存在「npm 版本 ≠ GitHub 版本」的双源漂移。
三个 @orphiczhou/* 候选名在 registry 均 404。解冻不是技术动作,是项目所有者的显式决策:要先定包名、版本/tag 策略、凭据归属、文档切换、预发布演练、registry 元数据核对,缺一不可。
仓库里同时存在 66/66(审计基线 v0.5.0)、67/67(v0.5.1)、84/84(v0.6.0)、34/34(v1.2.0 时代 handoff)、40/40(v1.3.1)、41/41(v1.3.3+)等历史口径。判断当前值要以当前 package.json + 实测命令为准;本页统一采用 2026-11-12 的 165/165 / 41/41 / 3/3(Wave 2 收口 + v0.8.0)。
这一节按「会不会让你误判」排序;每条都给出当前处理方式,不粉饰。
| # | 边界 / 坑 | 实际影响 | 当前处理 / 绕法 |
|---|---|---|---|
| 1 | npm 冻结(D3) | 不能 npm install;三个候选名 registry 404;市场条目是 browse-only,按 Git 安装 | 用 Git URL 或 link:;解冻需所有者显式批准(条件见 docs/guides/publishing.md §4) |
| 2 | sweep 依赖宿主 timer | 宿主 timer 可用时用其 interval;不可用时靠进程内 60s 兜底(sweepMode=timer),自动收割可能慢一轮 | 不要假设「必须显式 harvest」;tree_status harvest 只是立即触发一轮 |
| 3 | provider-conformance 依赖 asar fixture | fixture 缺失或只拿到 DSH 0.2.2-rc.1 的 shared-chunk 拆包布局时,region 启发式拿不到 29/29 | fixture 解析顺序 DSH_RC2_FIXTURE_DIR → %TEMP%\dsh-asar-inspect\out-rc2-compat → out;rc.2 兼容 fixture → 29/29,缺 fixture / 布局不符 → exit 2 可操作报错;属测试环境依赖,不是包内容缺陷(SHA-256 见 docs/reports/conformance-rc2-2026-11-12.md) |
| 4 | docs/architecture/tools-mapping.md 是设计稿 | 表里的 tree_report drift、tree_node milestone-*、tree_maintain gc 等未实现;照表调会 unknown action | 以 index.js schema 为准;本页图 2 只列已实现 action |
| 5 | 市场只认 version | 改了代码但不 bump,market 不刷新,等于发假更新;无内容变化乱 bump 又制造假版本 | D6:有内容变化必须 bump;version = GitHub tag = package.json.version |
| 6 | 宿主半按包名缓存 | 改 index.js / patch 行后,活体仍是旧实现;hmr.root 不保证宿主半重载 | 对相应 entry disable→enable,或重启 DSH;客户端半只刷新页面 |
| 7 | Skill 目录在会话启动时注入 | 改完 patch 行后,旧会话看不到新 Skill;只改 SKILL.md 正文也可能要新会话才读 | 新开会话验收;目录项应各出现一次(重复挂载会重复) |
| 8 | set-status done 工具面不可达 | 它要求 milestones 非空且全 audit_pass,但工具面没有 milestone 写入 action | 正常收口:done 事件 → runtime.succeeded;status 只作观察,不要反复试 set-status |
| 9 | tree_verify FAIL 不阻断 succeeded | verify 只落账 leaf.verification 并返回 result.pass=false,不会自动拦住节点完成 | commander 必须读 result.pass 再决定收口;这是协议纪律,不是引擎硬闸 |
| 10 | leaf.status 与 runtime 脱节 | runtime 已 succeeded,status 可能仍 pending_brief/active;观察者易误读 | 收口看 runtime.state;status 只用于列表/剪枝/归档 |
| 11 | artifact 验证取首个匹配 | **/*.md 按字典序取第一个,可能命中 node_modules 里的 md;minSize 比较的是字符数,不是字节 | 显式传产物路径/策略;或在 leaf 产物目录内验证(未修) |
| 12 | 会话预算漏计竹节接力 | max_sessions=50 只统计 leaf.session_id + leaf.segment_chain + registry;竹节写的是 runtime.segmentChain,高频接力时上限不成立 | 已知实现边界(审计 P1-06);不要把 50 当作严格上限 |
| 13 | caller 校验覆盖范围 | Wave-1 写面护栏已统一六类写操作(set-context / set-verification / 非 done event / dispatch:cancel / status / set-session);verify 自体仍不阻断 succeeded | 非授权一律 E_BORROWED_IDENTITY;verify 结论由 commander 读取并裁决(协议纪律,不是引擎硬闸) |
| 14 | 交接不迁移 leaf owner | 接替会话写 done → E_BORROWED_IDENTITY | 由 leaf 的 creator/上级 tree_node set-session 重绑;或旧会话交棒前先写 done |
| 15 | tree_maintain gc 未实现 | tree-engine-data/ 下历史 smoke/e2e 树只能手工清理 | 用 backup 先留档,再手工删目录;或列入下一轮功能 |
| 16 | 真实 50% 阈值未跑到 | B/C 组三次交接均 force:true 模拟;「机制成立、阈值真实性部分」 | 需要一次不 force 的自然 50% 演练;否则只能说阈值逻辑与闸门被验证,不是真实压力验证 |
| 17 | 语言只做 zh/en | ja/es/fr/de/ru/pt 等已存语言回退英文;中文提示后可能跟英文框架后缀 | 可接受的回退;要扩展需同步更新断言脚本 |
| 18 | RC2 兼容层已补单测(v0.7.0) | startContinuable / startActivation 双形探测已抽到 src/compat.js,tests/compat.test.js 11 例覆盖 | 宿主再升级前先用 cordis_inspect_query 读方法表;新形状变化需补测后再发版 |
事实来源:README.md §已知边界;docs/operations/handoff-2026-11-11.md §7;docs/reports/audit-tree-system-2026-11-11.md §3–§4;docs/architecture/merge-session-tree-2026-11-11.md §5;docs/reports/skill-e2e-2026-11-11.md §5。
以下为地图生成时(2026-11-11)快照;其中第 1、2、4、5、7、9 项已在 v1.3.4–v1.3.6 修复(保留作历史记录),引用时以仓库当前文件为准。2026-11-12 Wave-2 文档收口后,README / agent.md / handoff / skills-usage 的版本与测试数已统一到 v0.7.0 / 112/112;本表只作历史对照。
| 位置 | 文中写法 | 当前事实 / 建议 |
|---|---|---|
README.md 包表(session-tree 行) | 「GitHub 公开(v1.3.3)」 | 当前公开镜像 v1.3.5 = 1fb9193;该单元格是旧数字,应改 v1.3.5(同表其他位置已是 v1.3.5) |
docs/operations/handoff-2026-11-11.md §9 交接提示词 | 「会话树单包 … v1.3.3」 | 同文件 §1 已写 v1.3.5;提示词是旧版本,照抄会误判 |
docs/operations/handoff-2026-11-11.md §1 vs agent.md §2 | 宿主 loader 账本 245 条 vs 244 条 | 两份快照相差 1;属时序差异,引用时标注「当时快照」或省略该数字 |
docs/architecture/session-handoff-2026-11-11.md 标题/状态 | 「v1.3.3」为主 | 当前包是 v1.3.5;该文是设计/交付记录,建议标题加「历史快照」或补 1.3.4/1.3.5 |
docs/guides/skills-usage.md §9 版本差异速查 | 只列到 1.3.3 | 文档头写「v1.3.5 及以上」,版本矩阵缺 1.3.4/1.3.5(两版均无行为变化,可一句带过) |
docs/reports/audit-tree-system-2026-11-11.md §1 | tree-engine 66/66、v0.5.0 基线 | 地图生成时为 v0.5.1 / 67/67;现为 v0.8.0 / 165/165;审计结论仍有效,但测试数字是历史快照 |
docs/architecture/engine-spec.md §1/§3 | 「33 工具」「源缺省 85」「16 文件」 | 这是上游源引擎的 S0 规约,不是本仓 9 工具/42% 的现状;两套数字不要混用 |
packages/dsh-tree-engine/README.md v0.3 节 | 「register-session(旁路登记幂等)」 | 代码对重复登记直接 E_SCHEMA_INVALID(注释口径是「幂等拒绝重复计」);工具描述仍写 idempotent(审计 P1-07) |
README.md 包表 vs §跑测试 | 「包内 5 份测试」vs「6 个测试入口」 | 实际 test/ 下 5 个测试文件 + scripts/verify-bundle.mjs 1 个入口;两种说法指代不同,建议统一为「5 个测试文件 + 1 个清单自检」 |
README.md 文档索引 vs docs/operations/handoff-2026-11-11.md | 仍标「当前交接」 | 该文正文混有 v1.3.2/v1.3.3 残留;建议标注「历史交接,版本数字以包 package.json 为准」 |
本页没有截图。所有「界面」只以文字/框图示意;所有命令返回都是可读化重排,字段名来自真实 schema,具体 ID、百分比、路径、单行渲染会随会话变化。带 事实 的段落有仓库文件或实测输出支撑;带 示意 的只表达结构;带 建议 的是分析,不是仓库承诺。
以下是分析建议,不是仓库承诺;优先级按「影响 × 实现成本 × 依赖」定性判断。
当前功能面已经够用,真正的短板在三处:装不上/看不见(诊断)、写面不够严(完整性)、真机验活只做过一次性取证(回归)。因此建议的顺序不是「继续加工具」,而是先把这三处补齐,再谈可视化与多语言。
2026-11-12 更新:Wave 1(doctor / 写面护栏)与 Wave 2(W2.1–W2.8,tree-engine v0.7.0/v0.8.0、165/165)已完成;下表保留候选与验收口径,已完成项标 ✅,Wave 3 候选见 §9.3。Wave-2 收口证据见 docs/reports/wave2-closeout-2026-11-12.md。
| # | 功能 | 解决什么问题 | 价值 | 成本 | 风险 / 依赖 | 优先级 | 验收 |
|---|---|---|---|---|---|---|---|
| 1 | ✅ 安装/运行自检 doctor(Wave-1 已完成) | 「工具没出现 / Skill 没有 / 树是旧的」只能靠人猜;D12 缓存、Skill 注入时机、provider 缺失都很难自查 | 高 | 低–中 | 只读;不能改 profile;要区分「未装」「未重载」「旧会话」「provider 缺失」「版本漂移」 | P0 | 已落地 tree_doctor(7 检查项;FAIL 不 throw);活体 7/7 PASS |
| 2 | ✅ 写面护栏补全(Wave-1 已完成) | set-context/set-verification/非 done event/取消 无统一 caller 校验,worker 可改他人水位 | 高 | 中 | 可能破坏旧 E2E 的宽松假设;竹节 owner 重绑后规则要兼容;需同步 SKILL 护栏表 | P1 | 已落地 LEAF_WRITE_MATRIX + assertLeafWriter + 8 条负例;112/112 不回归 |
| 3 | ✅ 会话预算纳入竹节链(W2.1 已完成) | max_sessions=50 漏计 runtime.segmentChain,高频接力时护栏数字失真 | 中 | 低 | 需同时改 guards.js、validate、文档口径;不要把「预算拒绝」误判成竹节故障 | P1 | 已落地:归一化去重合并计数;budget.test.js 7 例;超限拒绝;接力前旧会话口径见 §8 #12 |
| 4 | ✅ Skill 版本/文档一致性检查(W2.4 已完成) | 三份 SKILL 的版本头、命令与测试数字靠人工对齐,容易和代码/README 漂移 | 中 | 低 | 只读脚本;要解析 frontmatter 与 README 表格;不引入外部依赖 | P1 | 已落地 scripts/check-version-consistency.mjs:23 checks;故意改错能 FAIL;已接入 release-all.mjs 预检 |
| 5 | ✅ provider-conformance rc.2 fixture(W2.2 已完成) | 29/29 依赖 asar 解包布局;DSH 0.2.2-rc.1 shared chunk 让旧启发式失败 | 中 | 中 | fixture 易随版本漂移;不能把缺 fixture 当代码失败;需记录 fixture 来源与校验 | P1 | 已落地:fixture 解析顺序 + 29/29;缺 fixture exit 2 可操作报错;SHA-256 留档 |
| 6 | ✅ RC2 兼容层单测(W2.3 已完成) | 双形探测分支(startContinuable/startActivation)未被覆盖;宿主升级时风险高 | 中 | 低 | 需要 mock 两种服务形状;不要为了测兼容层引入宿主依赖 | P1 | 已落地:抽 src/compat.js + compat.test.js 11 例;总数 84→112 |
| 7 | artifact 验证路径修复 | **/*.md 首个匹配可能命中 node_modules;minSize 是字符数不是字节 | 中 | 低–中 | 改默认行为可能影响现有 E2E;需要「显式产物路径」与「排除 node_modules」两种模式 | P2 | 新增 2 条测试;真实 E2E 产物不误判 |
| 8 | tree_maintain gc | 历史 smoke/e2e 树只能手工清理;tree-engine-data 膨胀 | 中 | 低 | 删除不可逆;必须先 backup;只对 pruned/archived 开放;dry-run 默认 | P2 | dry-run 列出候选;真实删除前有 backup;拒绝 active/done |
| 9 | tools-mapping 从 schema 生成 | 设计稿与实现 action 不一致,照表调用会 unknown action | 中 | 低 | 生成器需读 index.js 或导出 schema;避免手写第二真源 | P2 | 生成表与 9 工具 schema 逐项一致;CI 检查未实现 action |
| 10 | leaf.status 与 runtime 同步 | status 可能停在 pending_brief/active,观察者误读 | 中 | 中 | 动状态机风险高;可能影响 set-status/剪枝/归档;优先做「派生展示」而不是改真源 | P2 | 列表/渲染以 runtime 为准;仍保留 status 语义;回归全绿 |
| 11 | 真实 50% 自然演练 | B/C 组三次交接全是 force 模拟;阈值真实性未验证 | 中 | 高(token) | 需要长会话与配额;可能撞 429;不应为了触发而灌水 | P2 | 不 force 的 status ≥50% → handoff;verify-handoff 12/12 |
| 12 | 只读树面板 | 目前只有 tree_status overview 文本;看不到 runtime/verification 的全局视图 | 高 | 高 | 新客户端半、路由、权限;只读边界要写死;不要复制引擎状态 | P2 | 只读;不新增写接口;数据来自 tree-state/事件 |
| 13 | 多语言 kickoff | 只有 zh/en;ja/es/fr/de/ru/pt 回退英文 | 低 | 中 | 需要同步更新语言验收脚本与文档;收益有限 | P2 | 按 locale 选择提示语;回退测试;文档矩阵更新 |
| 14 | npm 解冻 | npm 安装缺失;市场只支持 Git/browse | 低–中 | 高(决策+凭据) | D3 需所有者批准;token/2FA/CI 新攻击面;双源漂移 | 暂缓 | 不是代码任务:先过 publishing.md §4 六项条件 |
tree_doctor)doctor:把「为什么没生效」变成一条命令目标:用户/支持者不再靠猜「是没装、没重载、旧会话,还是缺 provider」。
方案:先做只读脚本 scripts/doctor.mjs(不改宿主),输出人类可读表 + --json。检查项:① profile package.json 的 bundles/dependencies 是否有两个 tree 包;② cordis.patch.yml 是否有两条 bundle insert 与两条 skill provider insert;③ 包版本与公开 tag 是否漂移(离线时跳过);④ tree-engine-data/apply.log 是否有 engine ready 与当前版本;⑤ 通过 cordis_inspect(若可用)确认 tree_send/session_handoff/9 工具是否注册;⑥ Skill provider 是否可解析(读 patch 与包内 skills/);⑦ 给出「下一步做什么」的命令,而不是只报错。
风险/依赖:只读;不能自动改 profile(改配置必须用户确认);Windows 路径与编码要小心;「宿主服务不可用」与「未装配」必须区分,避免误报。
验收:构造 4 种故障(缺 bundle、缺 provider、patch 未重载、旧会话)分别给出不同 hint;正常环境 0 fail;--json 可被 CI 消费。
目标:消除审计 P1-05 的越权写面,让「worker 只能改自己的水位/事件/裁决」成为代码事实,而不是 Skill 里的口号。
方案:在 src/guards.js 增加统一的 assertLeafWriter(caller, leaf, op):set-context 允许 owner 或祖先 commander;event 非 done 允许 owner;set-verification 允许 commander/root 或显式 verify caller;dispatch:cancel 允许 parent/creator;verify run 允许 commander。每个命令补负例测试;同步 tree-worker/tree-commander 的护栏表。
风险/依赖:旧 E2E 可能依赖宽松路径;竹节 owner 重绑后规则要按「当前 owner」判断;root 信任锚要保留例外;不要误伤 set-session 的 creator 语义。
验收:5 个写操作各有「非授权 → 拒」与「授权 → 通过」测试;112/112 不回归(落地时为 67/67);A 组真机 7/7 succeeded 仍成立;SKILL/README 与实现一致。
目标:交接(root/sibling)、接替提示语语言、Skill 目录可见性这三条真机断言不再只在报告里跑过一次,而是每次发布前都跑并留证。
方案:复用现有 scripts/e2e/verify-handoff.mjs、scripts/e2e/verify-kickoff-language.mjs、scripts/skill-e2e/collect-skills.mjs,合成一个 runbook(或薄包装脚本):起真实子会话 → 逐条断言 → artifacts 落到 scripts/skill-e2e/artifacts/ → 在 docs/guides/publishing.md §6 检查清单加一项「真机 E2E 三断言」。失败时保留会话 id 与解码结果,便于复跑。
风险/依赖:需要真实会话与配额(曾遇到 429);无 GUI 的 CI 不能跑,只能发布前由人触发;会话日志格式可能随 DSH 版本漂移(断言器要能明确报「格式变了」而不是静默 PASS)。
验收:发布前一次运行三条断言全 PASS 且 artifacts 落盘;故障注入(改坏一条断言)能 FAIL;runbook 步骤可被另一个会话照做。
publishing.md §4 六项。doctor 只能建议,不能代改。@deepseek-ai/* 依赖是它能离线测试、快速适配的核心优势。tree_verify 已明确不阻断 succeeded,再自动化裁决只会制造假绿。| 波次 | 内容 | 退出条件 |
|---|---|---|
| Wave 1 ✅ | doctor + 写面护栏(预算计入竹节 carry 到 Wave 2) | 4 类故障可诊断;负例测试齐;tree_doctor 7/7 PASS |
| Wave 2 ✅ | W2.1 预算链 + W2.2 conformance fixture + W2.3 RC2 兼容层 + W2.4 一致性脚本 + W2.5 E2E runner + W2.6 root id 兼容 + W2.7 发布自动化 + W2.8 GUI 规范 | 112/112;conformance 29/29;一致性脚本 23 checks;沙箱发布演练 exit 0;真机三断言留待发布前触发 |
| Wave 3 📋 | artifact 路径 + gc + schema 生成文档 + 真实 50% 演练 + runtime.history 预算口径 + relay 预检 | 产物不误判;删除可回滚;文档无 unknown action;自然阈值 PASS |
建议依据:docs/reports/audit-tree-system-2026-11-11.md P1-05/P1-06/P1-07;README.md 已知边界;docs/reports/skill-e2e-2026-11-11.md §5;docs/guides/publishing.md §4。
以下八项已在本轮完成;证据以仓库文件/实测输出为准,完整清单见 docs/reports/wave2-closeout-2026-11-12.md。真机三断言本体与镜像真推是已知边界(发布前由 Lead/人工触发)。
| ID | 项 | 状态 | 证据 |
|---|---|---|---|
| W2.1 | 会话预算计入竹节链 | ✅ | src/guards.js + src/engine.js validate;tests/budget.test.js 7 例;接力后计数与超限拒绝 |
| W2.2 | provider-conformance rc.2 fixture | ✅ | test/provider-conformance.cjs 29/29;缺 fixture exit 2;fixture SHA-256 留档(docs/reports/conformance-rc2-2026-11-12.md) |
| W2.3 | RC2 兼容层单测 | ✅ | src/compat.js + tests/compat.test.js 11 例;总数 84→112 |
| W2.4 | Skill/README/版本一致性检查 | ✅ | scripts/check-version-consistency.mjs 23 checks;--json/--run-tests;故意改错能 FAIL |
| W2.5 | 真机 E2E 常态化 runner | ✅(本体未跑) | scripts/e2e/run-release-e2e.mjs:三条断言编排/汇总/artifacts + --replay;离线故障注入能 FAIL(docs/reports/e2e-release-runner-2026-11-12.md) |
| W2.6 | root 会话 id 兼容 | ✅ | normalizeSessionId/sameSession;tests/identity.test.js 10 例;活体修复前 E_INVALID_UUID_STRICT → 修复后建树成功、root 存裸 UUID |
| W2.7 | 发布自动化(一条命令) | ✅(真推未跑) | scripts/release-all.mjs:预检→同步/SHA→本仓 commit→镜像 commit/tag→ls-remote;隔离沙箱全链路演练(docs/reports/release-automation-2026-11-12.md) |
| W2.8 | GUI 迭代规范 | ✅ | docs/architecture/session-tree-ui.md:交互方案 + code map + 7 步迭代流程 + 变更记录(现行) |
给需要引用/复核的人:每个数字都尽量能指回文件或实测。
| 术语 | 一句话解释 |
|---|---|
| DSH | DeepSeek Harness,带 Cordis 插件宿主与 Web GUI 的桌面运行时;本项目的运行底座。 |
| bundle | 一个可安装的插件包,由宿主半、可选客户端半与 cordis.patch.yml 组成。 |
| patch row | cordis.patch.yml 里的 insert 行;决定 bundle 向 profile 贡献哪个模块/服务。 |
| 宿主半 / 客户端半 | 宿主半跑在 DSH 进程里,注册工具/服务;客户端半跑在浏览器,负责侧栏 UI。 |
| leaf | 任务树账本里的一行:leaf_id、parent、role、status、runtime、events、verification。 |
| tree / task tree | 一棵任务树;tree_id 4–8 字符小写;root leaf 自动创建。 |
| commander / worker | 中间层指挥官(可再建子节点)与执行者(不能有子节点);深度上限 3。 |
| owner | leaf.session_id 当前指向的会话;只有 owner 能写 done 事件。 |
| 竹节 / bamboo | 同一 leaf 上换执行会话的机制,缺省阈值 42%;任务书/简报随会话走,leaf 不变。 |
| handoff | 会话级同层接替:写 HANDOFF-*.md,启动同父兄弟或新根;不换 leaf。 |
| taskType / DoD | 节点任务类型(research/question/doc/code-change/default)与「完成定义」;决定验证策略与注入文本。 |
| adversarial | 对抗式验证:结构检查 + 异族红队攻击 + FAIL 回注修复,最多 3 轮。 |
| cleanroom | 洁净室评审:独立子会话、干净上下文、只读 GitHub 实际内容,多轮找缺口。 |
| 21/21 SHA | 发布同步脚本对 21 个文件逐个 SHA-256 比对,全部一致才允许推送(v1.4.0 起;v1.3.6–v1.3.7 为 19/19;更早版本 18/18 / 16/16 / 15/15)。 |
| 包 | 当前版本 | 状态 | 公开位置 | 测试 |
|---|---|---|---|---|
dsh-tree-engine | 0.8.0 | 运行中 | 随本仓公开(未单独发仓) | 112/112 |
dsh-session-tree | 1.4.0 | 本仓 | orphiczhou/dsh-session-tree · 镜像 tag v1.4.0 = 0343f0c · 21/21 SHA | 41/41 + 3/3 + 22/22 + 0 fail + 29/29 |
dsh-agent-introspect | 0.1.0 | 运行中 | 随本仓公开 | 无单测 |
本页所有版本号、测试数、阈值与工具名均来自以下文件(2026-11-11 快照);「本会话实测」为本次制作时的真实命令输出。
| 仓库相对路径 | 用来核对什么 | 快照 / 注意 |
|---|---|---|
README.md | 包表、快速开始、随包 Skill、已知边界、文档索引 | 2026-11-12;个别旧数字见 §8.1 |
agent.md | 角色、D1–D17、R1–R14、状态快照、任务板、发布门禁 | 最后更新 2026-11-12(Wave-2 收口,D17) |
docs/guides/skills-usage.md | 三个 Skill 的触发、参数、样例、42% vs 50%、排障 | 适用 v1.4.0 / v0.8.0 |
docs/operations/handoff-2026-11-12.md | 当前交接、关键路径、测试/验活、风险与下一轮议程 | 快照 2026-11-12 01:40 |
docs/architecture/session-handoff-2026-11-11.md | 交接设计、继承矩阵、闸门顺序、语言解析、防重复 | 设计/交付记录,含 v0.1.0 历史 |
docs/architecture/engine-spec.md | 上游源引擎的 S0 行为规约(33 工具、85 阈值) | 不是本仓 9 工具/42% 的现状 |
docs/architecture/tools-mapping.md | 9 工具与 33 源工具的映射、设计 action 集 | 设计稿,含未实现 action |
docs/architecture/segment-handoff.md | 竹节阈值 42、链长 5、先 interrupt 后 start、K1–K5 | 2026-10-04 设计备忘 |
docs/reports/audit-tree-system-2026-11-11.md | 4 BLOCK / 12 需修 / 15 建议;P1-05/06/07 等 | v0.5.0 基线(66/66) |
docs/reports/skill-e2e-2026-11-11.md | A/B/C 真机证据、7 节点 succeeded、FAIL→PASS、12/12 继承断言 | 2026-11-11;含 429 限制 |
docs/reports/e2e-handoff-2026-11-11.md | root 14/14、sibling 12/12;工作区/预设/权限继承 | 2026-11-11 |
docs/reports/e2e-kickoff-language-2026-11-11.md | 语言解析优先级;修复前 en → 修复后 zh PASS | 2026-11-11 |
docs/guides/publishing.md | GitHub 两仓、市场、npm 冻结、版本纪律、发布脚本护栏 | 快照 15:00;tag 链 |
docs/reports/skill-cleanroom-2026-11-11.md | 三轮洁净室:G1–G12、N1–N7、第三轮 PASS | 2026-11-11 |
docs/architecture/merge-session-tree-2026-11-11.md | §5 provider-conformance 的 rc.2 fixture 限制 | 2026-11-11 |
docs/reports/wave2-closeout-2026-11-12.md | W2.1–W2.8 结论表、代码变更清单、测试增量 84→112、脚本退出码、W2.6 活体前后 | 2026-11-12 |
docs/reports/conformance-rc2-2026-11-12.md | W2.2 29/29 复验、fixture 来源与 SHA-256、缺 fixture exit 2 | 2026-11-12 |
docs/reports/e2e-release-runner-2026-11-12.md | W2.5 runner 参数/流水线/artifacts、离线故障注入、replay 边界 | 2026-11-12 |
docs/reports/release-automation-2026-11-12.md | W2.7 一条命令发布、失败即停与回滚、凭据纪律、沙箱演练 | 2026-11-12 |
CHANGELOG.md | 1.3.1–1.3.7 的变更与验证;1.3.0 的 Unreleased 段 | 2026-11-12 |
packages/*/package.json | 版本、files、exports、dsh.bundle/client | 当前工作树 |
packages/dsh-tree-engine/index.js | 9 工具 schema、action 闭集、工具描述 | v0.8.0 |
packages/dsh-tree-engine/src/*.js | 状态机、护栏、验证策略、竹节、时钟、配置、RC2 兼容层(compat.js) | 当前工作树 |
packages/dsh-session-tree/index.js | tree_send/session_handoff schema、继承、语言、闸门 | v1.4.0 |
packages/dsh-session-tree/README.zh.md | 侧栏树、工作区、tree_send、交接继承、安装/排障 | v1.4.0 |
packages/*/cordis.patch.yml | 两行 insert:bundle + dsh-skill-filesystem | 当前工作树 |
git log / git status | 本仓 master e09f39b;工作树不 clean(Wave-2 未提交);无 tag | 2026-11-12 实测 |
| 本轮实测 | tree-engine 165/165、handoff 41/41、skills 3/3、style-guard 22/22,退出码 0;tree_doctor 7/7 PASS | 2026-11-12 |
写文档/汇报时,优先引用包内 package.json(版本)与实测命令(测试数);引用 docs/ 时请带上「快照日期」,因为本项目在 2026-11-11 一天内迭代了 5 个 session-tree 版本、2026-11-12 又把 tree-engine 从 0.6.0 推到 0.7.0;旧文档里的 34/34、40/40、66/66、67/67、84/84、v1.3.3、v0.5.1 都曾是正确的历史值。