DSH五大核心Skill安装顺序与依赖解析-北京尧图网络

1. DSH 到底是什么Skill 又在补什么很多人第一次接触 DeepSeek Harness下面统一叫 DSH的时候都会有个错觉既然模型本身已经能读懂代码、能写脚本、能解释报错那还要这层东西做什么我一开始也这么想直到真的把一个稍微复杂的活交给它才发现问题不在于“它会不会想”而在于“它想完能不能落地”。DSH 的定位说白了就是给模型配上一双手和一套工具箱而 Skill 就是这套工具箱里的每一件工具。你可以把 DSH 理解成一个“编排层”它负责把用户的意图拆成若干步把每一步该调什么工具、传什么参数、拿到结果之后怎么接着往下走这一整套流程管起来。而模型在这个过程里更像是一个现场指挥负责判断和决策。这两者分工明确缺一不可。模型再聪明如果没法读你磁盘上的文件、没法执行一条命令看真实输出、没法记住上一轮聊到哪儿那它就永远停留在“给建议”的层面做不了“给结果”。所以这篇文章想解决的问题很具体一个刚把 DSH 跑起来的人面对着 Skill 列表一脸茫然不知道先装哪个、后装哪个、装完怎么验证、装错了会怎样。我按自己踩过的顺序把五个真正“没装就没法用”的核心 Skill 拆开讲清楚顺带把安装顺序背后的依赖逻辑、参数怎么算、出了问题怎么查一并交代。适合两类人看一是刚上手 DSH 想快速跑通一条完整链路的二是已经装了一堆 Skill 但发现互相打架、想回头理一遍架构的。1.1 从“会聊天”到“能上手干活”的落差在哪我先讲一个特别典型的场景。你让模型帮你改一个配置文件里的端口号它能给你一段改好的内容甚至能把整段 YAML 贴出来。但接下来呢它不知道这个文件在哪个目录、不知道你本地是不是已经有一份同名文件、不知道改完之后服务要不要重启、更不知道重启之后有没有起来。这四件事一件都落不了地整个任务就卡在“我建议你这样做”这一步。这中间的落差可以拆成四层每一层对应一类能力缺口。第一层是感知缺口模型看不到你的工作区不知道有哪些文件、内容长什么样。第二层是动作缺口模型不能真的执行命令所以它给的命令对不对、跑出来什么结果全靠你手动验证。第三层是记忆缺口上下文一长前面的约定就淡了同一个项目聊到第三天它可能忘了你定的命名规范。第四层是约束缺口模型输出的格式经常“差不多但不完全对”你要的是能直接喂给下一个程序的 JSON它给你一段带解释文字的代码块。这四层缺口恰好对应我后面要讲的五个 Skill前两个补感知和动作第三个补记忆第四个补约束第五个把前面四个串成流水线。所以“必装 5 个”不是拍脑袋定的数字而是这四层缺口加上一层编排正好凑成一套最小可用组合。少装任何一个你会发现某类任务就是做不顺而且很难定位到底卡在哪。我见过不少人一上来装十几个 Skill结果每个都只跑通一次之后全是环境冲突和权限报错。这跟装修一个道理水电没通就先买家具最后只能堆在客厅里。所以顺序这件事真的比数量重要得多。1.2 Skill 的运行机制它凭什么能插进来就生效要理解安装顺序得先明白 Skill 在 DSH 里是怎么被“看见”和“调用”的。虽然不同版本的实现细节有差异但主流做法大同小异基本遵循这么一套机制每个 Skill 是一个独立目录里面至少有一份描述文件说明这个 Skill 叫什么、干什么用、需要什么参数和一份执行入口真正干活的那段逻辑。DSH 启动时会扫描指定目录把描述文件读进来拼成一份“工具清单”交给模型。这里有个关键点很多人忽略模型选择调用哪个 Skill靠的是描述文件里的自然语言说明而不是代码本身。也就是说你写的 description 如果含糊其辞模型就不知道该在什么时候用它。我见过一个自己写的 Skill功能是把 Markdown 转成表格但描述写的是“格式转换工具”结果模型十次里有八次想不起来调它。后来改成“把 Markdown 表格转换为 CSV 文本适用于导出数据场景”命中率立刻不一样了。这件事说明Skill 的描述文件本身就是提示词工程的一部分。第二层机制是参数校验。DSH 在把调用请求转给 Skill 之前一般会按描述文件里的参数定义做一次校验类型不对、必填项缺失直接拒掉不会让错误的参数跑进执行逻辑里。这层设计的意义在于它把“模型瞎编参数”这种常见问题挡在了外面。但反过来如果你的参数定义写得太宽松什么都用字符串那校验就等于没做。第三层是结果回灌。Skill 执行完输出会被塞回对话上下文模型基于这个输出决定下一步。这里就有个隐形成本输出越长占的上下文越多。一个只会返回“成功/失败”的 Skill 和一个返回三千字日志的 Skill对后续推理的影响完全不是一个量级。这也是我后面会反复强调“输出要做裁剪”的原因。理解了这三层你就能明白为什么装 Skill 不是“装上就行”。描述写得准不准、参数定义严不严、输出裁得狠不狠直接决定了这套东西是帮模型干活还是给模型添乱。1.3 为什么必须讲究安装顺序安装顺序的核心逻辑只有一句话后装的 Skill 会依赖先装的 Skill 提供的能力。这不是框架强制的规定而是功能上的自然依赖。举个最直白的例子检索类 Skill 需要先把文件读进来、切块、建索引而“读文件”这件事本身就是文件工作区 Skill 的活。你如果先装检索那它在建索引的时候要么自己去实现一套文件读取要么直接报错。再比如任务编排 Skill它的作用是“把一个大任务拆成子任务分派给不同的执行单元”。那子任务执行单元凭什么去改文件、跑命令还是得回头调前面装的那几个。所以编排类必须放在最后它是消费者不是生产者。我把这个依赖关系画成一句话的安装链路文件 → 命令 → 记忆 → 校验 → 编排。前两个是“手脚”第三个是“笔记本”第四个是“质检员”第五个是“工头”。工头当然要最后到位不然他指挥谁还有个更实际的理由排查成本。你按这个顺序装每装一个就能单独验证一次出问题立刻知道是哪个环节。要是五个一起装完再测报一个错你根本不知道该翻哪个目录的日志。我吃过这个亏花了两个小时在一个编排 Skill 的配置文件里找问题最后发现是文件工作区的根目录路径写错了导致所有下游全部失效。从那以后我就老老实实一个一个装、一个一个验。2. 装之前把地基打好环境与目录约定在动手装任何 Skill 之前有三件事必须先定下来否则后面会反复返工。这三件事分别是运行环境够不够、目录怎么摆、权限边界划在哪儿。听起来像是废话但我见过太多人跳过这步装到第三个 Skill 的时候发现路径全乱、权限全开、日志找不到最后只能推倒重来。2.1 运行环境与依赖自查清单DSH 本身对环境的胃口不算大但它对“确定性”要求挺高。所谓确定性就是同一个 Skill 在你这台机器上跑出来的结果换一台机器也得一样。这就要求你把版本号都钉死别用“最新版”这种模糊说法。我的做法是先跑一遍自查把结果记在一个env-report.md里后面出问题直接对照。检查项大概是这些运行时版本比如 Python 3.11 或 Node 20看你的 DSH 发行版要求、包管理器版本、磁盘剩余空间建索引会吃空间建议留 5GB 以上、可用内存并发跑子任务时会翻倍、以及是否有可用的本地端口段有些 Skill 会起本地服务。磁盘这块我得多说一句。检索类 Skill 建索引的体积大概是原始文本的 1.2 到 2 倍取决于你存不存向量。一个 500MB 的代码仓库索引做完可能占 800MB 到 1GB。如果你手上是几十个仓库一起挂进去那磁盘消耗会很可观。我的习惯是先估算索引体积 ≈ 原始文本体积 × 1.5然后留一倍余量。这个系数不是精确值但用来判断“够不够”很实用。另外提醒一点如果你打算在容器里跑注意容器内的路径和宿主机的路径映射关系。文件工作区 Skill 的根目录如果指向容器内路径而你的文件在宿主机上那模型看到的就是一个空目录。这个问题我第一次遇到时排查了很久因为日志里一切正常只是“读不到文件”。后来养成习惯装完第一个 Skill 第一件事就是让它列一下根目录的内容确认看到的是对的东西。2.2 目录结构与配置文件的最小约定目录结构这事我的建议是别用默认值。默认值通常是为了让所有人快速跑起来所以它把所有东西都放在一个扁平目录里。等你装到第五个 Skill那个目录里会有几十个文件夹改配置全靠猜。我用的结构大概是这样dsh-home/ ├── skills/ # 所有 Skill 的安装目录 │ ├── fs-workspace/ │ ├── shell-runner/ │ ├── memory-index/ │ ├── schema-guard/ │ └── task-orchestrator/ ├── workspace/ # 模型可读写的工作区根目录 │ ├── inbox/ # 待处理文件 │ └── outbox/ # 产出物 ├── data/ │ ├── index/ # 索引数据 │ └── logs/ # 各 Skill 的日志 └── config/ ├── dsh.yaml # 主配置 └── skills.yaml # Skill 注册与参数分成skills、workspace、data、config四块的好处是备份和迁移特别省事。要换机器skills和config打包带走workspace挑需要的带走data里除了索引之外基本可以丢。索引重建虽然费时间但比重装环境可靠。skills.yaml里我建议给每个 Skill 单独留一段写清楚启用状态、根目录、超时时间、日志级别。这样出问题的时候改一个字段就能定位不用去翻 Skill 自己的内部配置。下面是一个可以照抄的骨架skills: fs_workspace: enabled: true root: ./workspace allow_write: true max_read_bytes: 262144 shell_runner: enabled: true cwd: ./workspace timeout_sec: 30 allowlist_profile: dev memory_index: enabled: true store: ./data/index chunk_tokens: 512 chunk_overlap: 64 schema_guard: enabled: true strict: true task_orchestrator: enabled: true max_parallel: 3 subtask_timeout_sec: 300max_read_bytes这个参数值得单独说一下。它的作用是限制单次读取的字节数防止模型一次性把几 MB 的日志拉进上下文把预算烧光。我设成 256KB大约是 6 万到 8 万字符已经够读一份完整的中等规模源码文件了。如果你的场景经常要读大文件建议不要调大这个值而是让模型配合检索 Skill 做分段读取——这样既不爆上下文也能覆盖全文。2.3 权限边界要先画好再装东西这一节我要说得重一点权限必须在装 Skill 之前定好装完再收紧成本高得多。原因很简单Skill 一旦被模型调用过你就不知道它到底在你系统里留下了什么。文件改了什么、命令执行过什么事后追溯很麻烦。我遵循的是“三个默认”原则。默认只读文件工作区初始状态设为只读等确认模型能正确读文件了再打开写权限。默认白名单命令执行 Skill 只放行一组预先写好的命令前缀比如git status、ls、python -m pytest其他一律拒绝。默认时限任何命令执行都有超时超时就杀不给“再等等”的机会。白名单这块我建议按用途分档别一股脑全开。下面这个分档方式是我在几个项目里用下来比较顺手的档位放行内容适用阶段风险提示read-onlyls、cat、grep、git status、git diff初次验证几乎无风险建议起步用这档dev上述 git add/commit、npm run build、pytest、python 脚本日常开发注意命令里的路径不能逃出工作区ops上述服务重启、容器操作慎用建议只在隔离环境开full不设限不建议一旦误操作很难回滚我自己的项目里dev档是长期状态ops档只在明确知道要做什么的时候临时开一下做完立刻收回。这个“临时开”的习惯帮我躲过至少两次误删。还有一条经验把危险命令做成硬拦截不要靠模型自觉。比如rm -rf、git reset --hard、chmod 777这类直接在 Skill 层拦掉不管模型怎么请求都拒绝。这不是不信任模型而是模型有时候会把“清理临时文件”理解成“删掉整个临时目录”而你那个临时目录里可能还有别的东西。拦一下让它换个方式做成本几乎为零。3. 五个必装核心 Skill 逐个拆解下面这五个是我认为构成“最小可用组合”的核心。每个我都会讲清楚它解决什么问题、关键参数怎么设、以及为什么它必须排在这个位置。3.1 第一个fs-workspace 文件工作区这个 Skill 是整个体系的地基它给模型提供的是“看见文件”和“修改文件”的能力。听起来简单但细节很多。一个设计得好的文件工作区 Skill至少要有这几个动作列目录、读文件、写文件、按模式搜索、以及在写之前做存在性检查。为什么它是第一个因为后面四个全都依赖它。命令执行需要在某个目录下跑检索需要读文件内容校验需要把结果写回去编排需要给子任务指定工作区。没有它其他四个就是空中楼阁。关键参数我前面提过root和max_read_bytes这里再补两个。一个是allow_write我建议分阶段开先关着跑通读取再开但只允许写到outbox子目录最后才放开整个workspace。另一个是follow_symlink默认关掉。软链接是个坑模型顺着链接可能读到工作区之外的东西你以为它只在workspace里活动实际上它跑到别处去了。读文件这块有个实操细节不要一次性返回全文。我的做法是读文件时先返回前若干行加总行数模型如果判断需要更多再按行号区间请求。这样一次读取的上下文占用能降一个数量级。具体实现上读动作接受start_line和end_line两个可选参数不传就返回开头 200 行。这个设计参考的是人翻代码的习惯——先看结构再看细节。写文件也有讲究。我要求写动作必须带一个expect_hash参数也就是“我期望这个文件当前的内容哈希是 X”。如果实际哈希对不上说明文件在你读完之后被别人改过这次写入直接拒掉。这个机制叫乐观锁成本很低但能挡住“基于过期内容覆盖”这类事故。我加这个是因为有一次模型读了一个配置文件中间我手动改了一行模型再写回去的时候把那行覆盖掉了排查了半天才发现是这么回事。3.2 第二个shell-runner 命令执行有了读文件的能力接下来最迫切的就是“跑一条命令看看结果”。这在调试场景里几乎是刚需——模型给出一段修复你得知道它到底能不能跑通。shell-runner 就是干这个的。它的核心设计难点不在执行而在边界。执行一条命令容易难的是怎么保证这条命令不会干出你不想让它干的事。我的方案是三层防护命令白名单、工作目录锁定、超时强杀。命令白名单我前面讲过按档位分这里补充一点实现思路不要用字符串包含来判断那太容易被绕过比如在命令里塞个分号接上另一条。正确做法是把命令解析成结构取第一个 token 作为可执行文件名再检查它是否在白名单里。如果要更严一点还可以对参数做模式匹配比如只允许git后面跟status、diff、log这几个子命令。工作目录锁定是指命令执行时的当前目录必须落在workspace之内而且命令里出现的路径参数不能包含..跳出。这一条我建议做成硬性校验因为路径逃逸是最常见的越界方式。超时这块我给两档普通命令 30 秒长任务 300 秒。超过就杀掉进程树不是只杀父进程。这点很重要很多命令会 fork 子进程只杀父进程的话子进程还在跑端口还占着你下次再执行就报端口冲突。杀进程树这个操作在不同系统上写法不一样但思路是一致的先拿到进程组 ID再对整个组发终止信号。输出处理也是个大问题。一条pytest跑下来输出可能几千行全塞回上下文直接把预算烧穿。我的做法是在 Skill 层做裁剪只保留最后 N 行比如 80 行加上一个“共 X 行已截断”的摘要。同时把完整输出写到data/logs/下用一个 ID 索引模型需要看细节的时候可以按 ID 再取。这样既保留了可追溯性又不占上下文。3.3 第三个memory-index 检索与长期记忆前两个 Skill 让模型能看能动手但它们解决不了“记不住”的问题。一个项目聊上几天上下文早就清了好几轮你之前定的规范、约定的接口、踩过的坑全靠人肉提醒。检索类 Skill 就是为了把这个外部化。它的工作原理不复杂把工作区里的文本切成块每块算一个向量存起来查询的时候把问题也转成向量找最相似的几块返回。听起来是标准流程但里面的参数选择对效果影响极大。分块大小我定在512 tokens重叠 64 tokens。为什么是 512因为太小了语义不完整一句话被切成两半检索出来也没用太大了噪声多一块里混了好几个主题匹配精度下降。512 大概是三四段话的量对代码文件来说差不多是一个函数加注释。重叠 64 是为了避免关键句正好落在切口上被切成两半。检索数量我定top-k 8重排后取 5。先粗召回 8 条再用一个轻量的重排模型打分取前 5 条塞进上下文。为什么不直接取 5因为向量召回的排序经常不准多召回一点再重排效果提升很明显。我实测过重排这一步能把“答非所问”的比例降下来一大截。参数我的取值调大的后果调小的后果chunk_tokens512单块噪声多匹配变模糊语义被切断召回内容残缺chunk_overlap64索引体积膨胀切口处的关键信息丢失top_k8重排开销上升好结果可能没进候选final_n5上下文占用增加信息不足回答变浅还有一个容易被忽略的点索引要能增量更新。项目一直在改你不能每次改一个文件就全量重建。我的做法是记录每个文件的修改时间和内容哈希定时扫描只重建变化的那些。全量重建一个中等仓库大概要几分钟增量通常几秒钟差别很大。我踩过的一个坑是索引建好之后文件改了但没更新索引模型检索出来的是旧内容然后基于旧内容给出建议你怎么看都不对。后来我加了个规则任何写文件动作之后自动触发对应文件的索引更新。这样虽然多了一点开销但省掉了大量“为什么它说的和实际不一样”的困惑。3.4 第四个schema-guard 结构化输出校验前面三个 Skill 让模型能干活但输出的东西经常“差一点”。你要 JSON它给你一段带解释的 JSON你要特定字段它给你同义但不同名的字段。人看着没问题程序一解析就崩。schema-guard 就是干这个的定义好结构不合规就重试或报错。它的用法是你在调用的时候附上一份结构定义JSON Schema 是通用做法Skill 拿到模型输出后校验通过就返回不通过就带着错误信息打回去让模型重试。重试次数我设成 2超过就返回失败不无限循环。为什么是 2因为第一次失败通常是格式问题第二次基本能改对如果两次都不对说明模型没理解要求再试也是浪费。结构定义这块我的经验是别写太复杂。嵌套三层以上的结构模型出错的概率会明显上升。如果确实需要复杂结构拆成多次调用每次产出一层再用代码拼起来。这样虽然调用次数多了但成功率反而更高。还有一个技巧在结构定义里给字段加description用自然语言说明这个字段该填什么。这不是给程序看的是给模型看的。我做过对比同样一个结构加了描述之后一次通过率能提高不少。本质上这还是提示词工程只是换了个位置。{ type: object, required: [file, change_type, summary], properties: { file: { type: string, description: 相对于工作区根目录的文件路径不要用绝对路径 }, change_type: { type: string, enum: [create, modify, delete], description: 本次变更的类型只填这三个值之一 }, summary: { type: string, description: 一句话说明改了什么不超过 50 字 } } }校验失败时的错误信息也要设计。别只说“校验失败”要说清楚“哪个字段、期望什么、实际收到什么”。信息越具体模型第二次改对的可能性越大。这一点我是从编译器报错里学的——好的报错能自己教会你怎么改。3.5 第五个task-orchestrator 任务编排前面四个都是“单项能力”第五个是把它们串起来的能力。它的作用是接收一个大任务拆成若干子任务给每个子任务指定该用哪些 Skill、在什么范围内活动然后并发或串行执行最后汇总结果。为什么放最后因为它是个纯消费者自己不产生任何基础能力。它做的每一件事都是回头调前面四个。你如果先装它它一启动就去找文件工作区找不到就报错你还得回头补装。关键参数是max_parallel我设成 3。为什么不设更高因为并发数上去之后资源竞争会变严重而且多个子任务同时改文件容易冲突。3 这个数字是我的经验值足够让独立的子任务并行跑起来又不至于把机器压满。如果你的任务主要是读操作可以调到 5如果涉及写操作建议降到 2 甚至 1。子任务的隔离也很重要。每个子任务应该有自己的一块“活动范围”比如各自一个子目录或者至少是各自一组文件。这样即使两个子任务同时跑也不会互相覆盖。我见过编排设计得不好的情况两个子任务同时往同一个日志文件里写最后日志内容交错完全没法看。汇总环节有个常见问题子任务返回的结果格式不统一。有的返回文本有的返回 JSON有的返回文件路径。我的做法是在编排层定一个统一的结果结构每个子任务执行完必须按这个结构返回不符合的用 schema-guard 打回去重来。这样汇总的时候就不用写一堆分支判断了。3.6 安装顺序与依赖关系总表把五个 Skill 的依赖关系整理成一张表装的时候对着看能省很多来回。顺序Skill提供能力依赖谁装完怎么验1fs-workspace读写工作区文件无让它列一下根目录看输出对不对2shell-runner执行命令并取回输出fs-workspace跑一条ls或git status看退出码和输出3memory-index切块、建索引、检索fs-workspace建一次小索引问一个只有文档里才有的问题4schema-guard结构化输出校验与重试无强依赖建议在前三个之后故意给一个缺字段的输出看是否被打回5task-orchestrator拆任务、分派、汇总前四个全部跑一个两步的小任务看能否正确汇总验证这一步千万别省。我给自己定的规矩是每装完一个必须跑通一个最小验证用例再装下一个。这个习惯让我在后期排查问题时能快速判断“是新装的这个有问题”还是“老的那个被影响了”。省下来的时间远超验证本身花的那几分钟。4. 完整实操从零到跑通一条真实链路这一节我把前面讲的东西串起来走一遍完整流程。假设的场景是工作区里有一个小项目需要改一处配置、跑一次测试、最后产出一份变更说明。4.1 第一步到第三步落地文件、跑通命令、建好索引先装 fs-workspace。把目录建好配置里的root指向workspaceallow_write先设成 false。启动 DSH发一句“列出工作区根目录下的所有文件”。正常的话你应该看到目录列表。如果看到的是空的先检查路径再检查权限最后检查是不是在容器里跑但路径没映射对。确认能读之后打开写权限但只放开outbox目录。发一句“在 outbox 下创建一个 test.md写一行 hello”。然后去文件系统里确认这个文件真的存在内容也对。这一步通过说明写入链路是通的。接着装 shell-runner。配置里cwd指向workspace白名单用read-only档。发一句“执行 git status把输出告诉我”。如果工作区不是 git 仓库换成ls -la也行。关键是看退出码和输出都能回来。有些实现只返回输出不返回退出码那模型就没法判断命令是成功还是失败这个一定要确认。第三步装 memory-index。这一步最费时间因为要建索引。我的建议是先用一个小目录试比如只索引workspace/docs里面有十几个 Markdown 文件。配置好chunk_tokens: 512、chunk_overlap: 64触发一次全量建索引。建完之后问一个“只有文档里才写过”的细节问题看它能不能答上来。如果答不上来先检查分块是不是切碎了关键句再检查 top-k 是不是太小。这三步走完你已经有了“看、动、记”三件套。很多人到这一步就觉得够了其实还差得远——输出格式不对、任务拆不开这两个问题会在稍微复杂一点的场景里立刻暴露。4.2 关键参数怎么算出来的参数这块我一直觉得不能照抄得知道算法。拿上下文预算来说假设你的模型上下文窗口是 128K tokens你不能把它全用满。我的分配是这样的系统提示和工具描述占 10%检索结果占 25%对话历史占 20%工具返回占 15%剩下的 30% 留给模型输出和推理。这个比例不是拍脑袋是按实际使用反推的。工具返回那一块经常被低估一条命令的输出、一次文件读取的内容加起来很容易超过预期。留 15% 是保守估计如果你的场景里命令输出特别长这个比例还得往上调。再拿索引体积估算来说。前面提过系数 1.5具体算法是原始文本按平均 4 字符/token 折算成 token 数再乘以每 token 的存储开销存向量的话通常是 4 字节浮点 × 维度数。假设维度是 768那每个 token 大约 3KB。这个数字看着吓人但实际索引通常只存块级向量不是 token 级所以真实体积要除以块大小。我一般直接用 1.5 倍原始体积做粗估够用了。超时时间也有算法。普通命令的超时我取“同类命令在本机执行时间的 P95 再乘 3”。比如pytest跑全套通常 8 秒那就设 30 秒8×3 约 24取整到 30。乘 3 是为了容纳冷启动和机器负载波动。长任务的超时取 P95 乘 5因为长任务的不确定性更大。4.3 端到端演练一次“改代码跑测试出报告”现在五个 Skill 都装好了走一遍完整流程。任务描述是“把config/app.yaml里的端口从 8080 改成 9090跑一次测试如果通过就生成一份变更说明写到 outbox。”第一步编排层拆任务。它会拆成三个子任务改配置、跑测试、写报告。第二个子任务依赖第一个的结果第三个依赖第二个的结果所以是串行。第二步改配置。文件工作区先读config/app.yaml定位到端口那一行写入新值。写的时候带上expect_hash防止并发冲突。写完返回一个变更摘要。第三步跑测试。命令执行 Skill 在workspace下跑测试命令超时 300 秒。如果退出码非零把最后 80 行输出带回去编排层看到失败就终止后续子任务返回“测试未通过”。第四步写报告。结构化校验 Skill 先让模型产出一个符合结构的结果对象包含文件路径、变更类型、摘要。校验通过后文件工作区把它写成 Markdown 落到outbox。整个流程跑下来正常情况下十几秒到几十秒。如果中间任何一步失败编排层会带着具体的失败信息返回你能直接看到是哪一步、什么原因。这个可观测性是我最看重的——任务失败不可怕可怕的是失败了不知道卡在哪。5. 高频故障与排查实录下面这些是我在实际使用中反复撞上的问题按出现频率排。5.1 五类最容易撞上的问题第一类技能调用不触发。表现是模型明明该用某个 Skill却自己硬答。原因通常是描述文件写得太抽象。解决办法是把描述改成“什么场景下用、输入是什么、输出是什么”三句话越具体越好。第二类路径找不到。表现是文件读取返回空或者报错。九成是根目录配错或者在容器里跑但没做路径映射。排查顺序是先确认配置里的 root再确认进程的工作目录最后确认文件系统权限。第三类命令执行超时。表现是明明命令几秒就能跑完却一直卡到超时。常见原因是命令在等标准输入或者子进程没被正确回收。解决办法是执行时把标准输入重定向到空以及杀进程树而不是只杀父进程。第四类检索结果不相关。表现是问 A 它答 B。先看分块是不是把关键内容切碎了再看 top-k 是不是太小导致好结果没进候选最后看索引是不是过期了。这三个原因按这个顺序查命中率很高。第五类结构化输出反复失败。表现是模型连续两次都产不出合规结构。通常是结构定义太复杂或者字段描述不清楚。把嵌套拆平、给每个字段加一句人话描述基本能解决。5.2 速查表现象最可能原因快速验证处理该调 Skill 却没调描述太模糊看工具清单里的描述文字改成场景化描述读文件返回空根目录配错手动ls该目录修正 root 或做路径映射写入被拒哈希不匹配看文件是否被外部改过重新读取后再写命令卡住不动等待标准输入看进程状态重定向标准输入为空端口被占用子进程未回收查端口占用杀进程树检索答非所问分块或 top-k 问题看召回内容调 chunk 或加大 top-k索引内容过期未增量更新对比文件与索引时间触发重建结构校验总失败定义太复杂看错误信息指向哪个字段拆平结构、补描述再补一个不太算故障但很容易被忽略的点日志要看 Skill 层的不要只看 DSH 主进程的。很多问题在主进程日志里只是一句“调用失败”真正的错误堆栈在对应 Skill 自己的日志文件里。我现在的习惯是出问题第一件事是tail一下相关 Skill 的日志通常一眼就能看到根因。6. 玩法拓展五个 Skill 组合出来的进阶套路装完这五个只是起点真正有意思的是把它们组合起来。下面分享三个我自己常用的套路以及怎么自己写一个最小的 Skill。6.1 三种组合套路套路一批量文档整理。文件工作区扫描一个目录检索 Skill 判断每份文档的主题结构化校验保证输出格式一致最后按主题分目录归档。这个套路我用在整理一堆散落的技术笔记上几十份文档几分钟就跑完了。关键是分块参数要调小一点因为笔记通常很短块太大会把好几篇混在一起。套路二变更影响面分析。命令执行跑git diff拿到改动文件列表检索 Skill 找出这些文件被哪些地方引用编排层汇总成一份影响面报告。这个在改公共模块之前特别有用能提前知道会波及多少地方。我一般会在报告里加上“引用次数最多的前五个文件”优先看这几个。套路三日常巡检。定时触发命令执行跑一组检查命令磁盘、依赖版本、测试通过率结构化校验保证每次输出结构一致最后追加到一份历史记录里。这样对比不同时间点的数据趋势一眼就能看出来。这个套路的重点是输出结构一定要固定不然历史数据没法对比。6.2 自己写一个最小 Skill 的骨架如果你发现现有 Skill 都不太贴合你的场景写一个其实不难。最小骨架大概是这样# skills/my-skill/main.py def run(params: dict) - dict: target params[target] # 干活的地方注意所有路径都要限制在工作区内 result do_something(target) return { ok: True, summary: f处理完成共 {len(result)} 条, detail_id: save_detail(result), # 细节写日志只回摘要 }配套的描述文件是关键写清楚三件事什么时候用、参数是什么意思、返回什么。下面这个描述模板我用了很多次效果不错name: my-skill description: 当需要对某个目录下的文本做批量关键词统计时使用。输入一个目录路径返回出现频率最高的前 20 个词及其次数。不适用于二进制文件遇到会跳过并在结果里标注。 parameters: target: type: string description: 工作区内的相对目录路径例如 docs/notes写自定义 Skill 有几条经验。第一输出一定要裁剪别把原始数据全塞回去给个摘要加一个 detail_id需要细节再取。第二所有路径校验放在最前面别等干到一半才发现路径越界。第三错误信息要带上下文别只抛一个异常要说清楚在哪个文件、哪一步、期望什么。第四先写验证用例再写实现哪怕只是三行断言也能帮你在改代码的时候知道有没有改坏。最后说一个我自己的体会。这套东西装完之后最容易犯的错是“贪多”——看到一个新 Skill 就想装装完发现平时根本用不上还占着工具清单的位置让模型在选择时多了一层干扰。我后来的做法是工具清单控制在十个以内每个都必须说得出“上周用过几次”。说不出来的就卸掉。工具的价值不在于多而在于你闭着眼睛都知道什么时候该用它。

DSH五大核心Skill安装顺序与依赖解析

相关推荐

NPC三电平逆变器同步载波调制原理与Simulink实现

SQLAlchemy ORM实战技巧与性能优化指南

网络安全工程师职业发展：从入门到高薪的实战路径

更多资讯

如何快速上手AndroidGen-GLM-4-9B：5步实现Android自动化任务

【高等数学】【第四章】【综合习题】：多元函数微分学

【高等数学-第三章】【综合习题1】一元函数积分学及其应用

【高等数学-第五章】【综合习题】二重积分

如何构建智能医院：基于Qwen3-Omni-30B-A3B-Instruct的患者音视频诊断与监护系统终极指南

【数据仓库-9】hadoop生态圈与数据仓库

今日更新

淘宝商品详情API开发实战与性能优化指南

Unity Package Manager刷新错误排查与解决方案

Java record 规范构造器能否被反序列化或反射绕过

本周精选

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？