★ FEATURED ARTICLE DeepSeek Harness下称 DSH这类智能体运行框架刚上手时最典型的翻车场景是这样的命令行敲下去模型能读文件、能对话看起来一切正常可一旦让它改一个横跨三个文件的 bug它就开始东一榔头西一棒子——先翻了个不相干的配置又忘了刚才读过的函数签名最后给你一份看起来很对但跑不起来的补丁。问题往往不在模型本身而在于你没给它装 Skill。DSH 的 Skill 机制本质上是把某类任务该怎么做、该看哪些文件、该用哪些工具、做完怎么自检这套经验提前固化下来模型在合适的时机自动加载而不是每次从零开始猜。这篇内容面向刚接触 DSH、或者装了却感觉没提效反而更乱的人我会把入门阶段最该先装的 5 个核心 Skill、它们的安装先后顺序为什么不能颠倒、每个 Skill 落地时要盯住哪些配置细节以及跑通之后怎么把它们串成日常工作流一次讲透。全程给的是可照着改的配置和验证方法不是概念科普。1. 先搞清楚 Skill 在 DSH 里到底扮演什么角色1.1 Skill 不是插件它更像一份岗位说明书很多人第一次接触 DSH 的 Skill会下意识拿它跟传统插件类比觉得装得越多能力越强。这个理解偏差会直接导致后面一系列问题。传统插件是往主程序里塞新代码装了就常驻功能边界由代码写死Skill 更接近于一份给模型看的岗位说明书加上配套工具包它由三部分组成一段描述元数据告诉调度器我什么时候该被叫出来、一份正文指令告诉模型这类任务的标准做法是什么、以及可选的脚本与资源文件让模型不必现场写代码就能调用现成能力。这个差别带来两个直接后果。第一Skill 是有触发条件的描述写得含糊模型就永远想不起来用它描述写得太宽泛它又会把不相干的任务也往这个 Skill 上套反而添乱。第二Skill 是按需加载的正文不会一股脑塞进上下文只有被触发时才展开所以数量多本身不致命真正致命的是描述之间互相打架、职责重叠。我一般会跟人说装 Skill 就像给新同事配工位。你先得让他知道自己是干什么的描述再给他操作手册正文最后把常用工具放桌上脚本。三样缺一样他都干不利索。1.2 新手最容易犯的错是贪多一口气装十几个网上流传的各种 Skill 合集动辄几十个新手最常见的做法是复制粘贴全装上然后发现效果还不如不装。原因很朴素触发竞争。假设你同时装了代码审查和代码重构两个 Skill两者描述里都写了分析代码质量问题模型在面对一个函数时就得在两者之间做选择选错的概率相当高更糟的是有些实现会让两个 Skill 的指令叠加进上下文互相矛盾的要求把模型绕晕。我的建议很明确入门阶段只装 5 个而且这 5 个要形成一条完整的链路能覆盖看懂项目 → 动手改 → 改完自检 → 下次不重复劳动这个闭环。等这条链路跑顺了你自然就知道自己缺什么再针对性地补而不是漫无目的地囤。提示判断一个 Skill 该不该装问自己一句——我上周有几次任务是它负责的如果答案是零先别装。装了不用的 Skill 不是资产是干扰项。1.3 判断一个 Skill 质量的三个硬指标拿到一个 Skill 别急着装先拆开看三处。描述字段是否写清楚了做什么和什么时候用最好还带上一两个触发词的例子正文是否有明确的执行步骤而不是一堆你要仔细分析请注意质量这类正确但无用的废话脚本和资源是否有清晰的输入输出约定有没有对异常路径做处理比如文件不存在、命令超时了该怎么反馈。还有一个容易被忽略的点Skill 的正文长度。有些 Skill 写得像论文动辄几千字一触发就把上下文吃掉大半剩下的预算不够读代码了。合格的写法是把高频路径写在前面把边缘情况的处理折叠到附录段落让模型先拿到主干。2. 入门必装的 5 个 Skill 及它们之间的依赖链2.1 选这五个而不是别的理由在哪我筛这 5 个的标准不是功能强而是它们在一条链上后一个的输入正好是前一个的输出。单独看每个都不惊艳串起来才形成复利。这 5 个分别是序号Skill 定位核心职责缺了会怎样1环境自检检查运行时、路径、权限、依赖版本后面所有 Skill 报的错都是假错排查方向全跑偏2项目上下文索引建立目录地图、模块边界、入口文件清单模型到处乱翻文件读十个才命中一个3终端执行在受控沙箱里跑命令、看真实输出模型只能猜代码能不能跑永远在纸上谈兵4代码审查改动后按固定清单自查、跑静态检查补丁看着对一运行就崩你得反复返工5会话记忆与编排沉淀项目约定、复用上次结论每次开新会话都从零解释一遍背景你会发现这五个的排列顺序几乎就是它们的安装顺序这不是巧合。环境自检排第一是因为它是唯一一个用来验证其他 Skill 是否装对的 Skill上下文索引排第二因为终端执行和代码审查都要读它的产物记忆编排放最后因为它需要前面四个都完成注册才能正确地调度它们。2.2 从看懂项目到改对代码的调用链长什么样举个具体例子感受一下链路。你让 DSH 修一个用户列表分页参数越界导致 500的 bug理想流程是这样走的第一步上下文索引 Skill被触发它不是漫无目的地扫全仓库而是按预设规则产出三样东西入口路由文件在哪、分页逻辑大概在哪几个模块、相关的类型定义和数据访问层在哪。这个产物会以紧凑的摘要形式进入上下文而不是原始文件内容。第二步模型带着这份地图直接跳到分页处理函数读到page和pageSize没有做下界校验。这时候终端执行 Skill派上用场——它可以跑一次针对这个接口的最小复现命令确认真实返回值是不是 500而不是靠推理。第三步改完代码代码审查 Skill接管按清单逐项过边界值有没有覆盖、有没有引入新的空指针风险、改动是否波及调用方、静态检查是否通过。它会调终端执行去跑 lint 和单测。第四步这次修复的结论——分页参数统一走某个校验工具函数——被记忆 Skill记成项目约定下次遇到同类问题直接复用不会又改出一个风格不一致的版本。整条链上环境自检 Skill全程潜伏任何一个环节报出奇怪的错误比如命令找不到、路径不存在它先跳出来判断这是环境问题还是代码问题。2.3 为什么不能只装最强的那个有人会问我能不能只装一个全能开发 Skill把上面所有事都写进去技术上可以实践上很难维护。单个巨型 Skill 的正文会膨胀到几千字每次触发都吃满上下文而且它的描述必须写得极宽泛才能覆盖所有场景结果就是什么任务都触发它失去了按需加载的意义。Skill 机制的价值恰恰在于拆分带来的精准触发。五个小 Skill 各管一段描述清晰、正文精简每个都能在正确的时机被叫出来。这跟写代码时拆函数的道理一样——不是因为函数不能写长而是拆开之后每段都能被单独测试和复用。3. 安装顺序为什么不能颠倒逐步拆解3.1 第一步装环境自检它是你后面所有排错的基准线环境自检 Skill 干的事听起来很无聊检查运行时版本、确认配置目录存在且可写、验证依赖命令在 PATH 里、检查网络出口和代理设置、输出一份体检报告。但它是整条链的地基原因在于DSH 里绝大多数看起来像模型能力问题的现象根子都在环境上。我遇到过最典型的例子某个 Skill 装了之后一直不触发折腾了半天描述字段最后发现是配置目录权限不对Skill 文件根本没被读到。如果没有自检 Skill 先跑一遍你会沿着描述写得好不好这条完全错误的路排查到天亮。这个 Skill 的验证方法很简单装完直接触发一次看它输出的报告。合格的报告应该明确列出每一项的期望值、实际值、结论三列而不是只说一句环境正常。下面是一个配置示例字段名请以你手上的版本为准逻辑是通用的skill: env-doctor description: 当出现命令执行失败、Skill 未生效、依赖缺失、路径异常等情况时使用。 在任何任务开始前也可主动调用做一次体检。触发词环境检查、体检、 命令找不到、Skill 没反应。 checks: - name: runtime_version cmd: dsh --version expect: 1.0.0 - name: config_dir path: ~/.dsh require: [exists, writable] - name: skill_registry cmd: dsh skill list expect_contains: env-doctor - name: shell_available cmd: echo ok timeout: 5注意timeout这个字段很多自检 Skill 栽在这上面——某个检查项卡住不返回整个体检就挂起了你还以为工具死了。给每一项都设超时超时就标记为未知而不是失败这个区分很重要。3.2 第二步装项目上下文索引先让模型有地图再让它走路上下文索引 Skill 解决的问题是**模型不知道项目长什么样只能靠试探**。没有它的时候你让模型改一个接口它可能先读路由文件、再读控制器、再读服务层每一步都是靠猜路径中间读错三四个文件是常事上下文预算哗哗地掉。这个 Skill 的核心设计是分层索引第一层是目录骨架哪些是源码、哪些是测试、哪些是产物靠规则排除 node_modules、dist、.git 这类目录第二层是入口识别路由表、main 函数、CLI 入口、配置文件第三层是按需深挖只有在确定要改某模块时才展开该模块的文件清单。三层不是一次全做而是逐层展开这样上下文占用可控。配置上最关键的是排除规则和入口匹配规则skill: project-map description: 在需要理解项目结构、定位某个功能的实现位置、判断改动影响范围时使用。 触发词项目结构、这个功能在哪、影响哪些文件、入口在哪。 exclude: - **/node_modules/** - **/dist/** - **/.git/** - **/*.min.js entry_patterns: - src/main.* - src/router/**/*.* - cmd/**/main.go max_files_per_layer: 200max_files_per_layer这个上限别省。我见过有人在超大仓库里不设上限索引阶段直接扫了几万个文件光生成摘要就花掉几分钟用户体验极差。设个上限超出就截断并明确告诉模型这里只列了前 200 个需要更多请指定子目录——明确告知截断比默默截断重要得多否则模型会以为自己看到了全部。提示索引产物不要每次会话都重算。配合第五个 Skill记忆编排把索引结果缓存起来只在检测到目录结构变化时失效。这一条能让日常使用体验提升一大截。3.3 第三步装终端执行权限边界比功能丰富更重要终端执行 Skill 是五个里风险最高的一个也是最能拉开效率差距的一个。有了它模型可以跑测试、跑 lint、跑构建、跑最小复现脚本看到的是真实输出而不是推理结果没有它所有结论都是应该可以大概率没问题。但装它的时候第一个要想的不是能跑什么而是不能跑什么。我的做法是三层防护第一层是命令白名单只放行读操作和构建测试类命令删除、格式化、批量替换这类写操作默认拦截需要时手动临时放开。第二层是工作目录限制所有命令的工作目录必须落在项目根目录之内禁止cd到项目外。第三层是输出截断单条命令输出超过一定行数就截断并保留头尾避免一条npm install的日志把上下文塞爆。skill: shell-run description: 需要执行命令验证结论、运行测试、查看构建输出、复现问题时使用。 触发词跑一下、执行、验证、复现、测试结果。 workdir_root: ${PROJECT_ROOT} allow: - git status - git diff - npm run lint - npm test - pytest - python -m* deny: - rm * - git push* - chmod * default_timeout: 60 output_max_lines: 200 truncate_strategy: head_tailtruncate_strategy: head_tail是我强烈建议保留的。很多实现默认只留开头结果测试失败的详细信息全在末尾被截没了模型看到的是一片通过的假象。保留头尾二十行失败信息基本都能捞到。装完之后必须做一次边界验证故意让它执行一条rm -rf ./tmp确认被拦截再执行一条超长输出的命令确认截断生效且不影响判断。这两项过了才算真装对。3.4 第四步装代码审查让改完变成改对代码审查 Skill 的价值不在于它能发现多高深的问题而在于它强制模型在提交前走一遍固定清单。人写代码容易漏模型更是如此——它改完一处就急着邀功很少主动去想这个改动的调用方要不要跟着改。我建议的清单是固定的六项每项都要有明确的可执行判断而不是请检查代码质量这种废话检查项具体动作判定方式边界覆盖参数的空值、零值、极值、负数逐项列出是否处理调用影响搜索被改函数的所有调用点列出受影响文件清单异常路径外部调用失败、超时、返回空确认有兜底类型一致改动涉及的接口签名对比前后定义静态检查跑 lint 与类型检查看真实输出测试相关跑受影响的单测看通过数配置上要绑死它依赖的终端执行 Skill并且在 Skill 正文里明确任何一项无法确认时标注为未验证并说明原因禁止假设通过。这一句很关键不加的话模型倾向于全部打勾交差。skill: code-review description: 在完成任何代码修改后、提交前、或需要评估改动风险时使用。 触发词审查、自查、改完检查、影响范围、提交前。 depends_on: [project-map, shell-run] rule: | 逐项检查无法确认的项标注「未验证」并说明缺口 严禁在无证据情况下判定为通过。3.5 第五步装记忆与编排把前四个的成果沉淀下来最后一个 Skill 负责两件事记忆和编排。记忆是把项目级约定、上次的排查结论、用户偏好存成结构化片段下次会话按需召回编排是根据任务类型决定调哪几个 Skill、按什么顺序调避免模型每次自己临时决定。这里最容易被忽视的是记忆的失效机制。存了不删过期的约定会一直污染判断比如你三个月前定的日志统一用某个工具现在早就换了模型还在按老规矩改。所以记忆 Skill 必须带时间戳和来源召回时优先近期、可追溯到具体文件的条目超过一定时间的降权处理。编排部分则要防一个坑避免循环调用。A Skill 里说遇到不确定就先调 BB 里又说前提是 A 已经确认两者互相等待就会死循环。解决办法是在编排配置里强制指定优先级和一个最大调用深度skill: memory-orchestrator description: 需要复用历史结论、记录项目约定、或需要按流程串联多个技能时使用。 触发词上次怎么改的、记住这个规则、按流程来。 recall: sources: [.dsh/memory/*.json] decay_days: 90 require_source: true orchestrate: max_depth: 3 priority: [env-doctor, project-map, shell-run, code-review, memory-orchestrator]priority里把自己也放最后是为了在调度时避免自引用。max_depth: 3是保险丝超过三层还没收敛说明任务拆得不对该停下来问人而不是继续递归。4. 配置写完不等于装好验证与常见失效形态4.1 装完不生效的三种典型表现先看现象再动手Skill 装了没反应症状其实分得很清楚对着现象定位能省掉大半时间。第一种完全不被触发。任务是它该管的但模型压根没提这个 Skill。九成是描述字段的问题——要么太抽象处理代码相关任务要么没有触发词要么被别的 Skill 的描述盖住了。验证方法临时把其他 Skill 的描述清空再试一次如果这次触发了就是竞争问题如果还不触发去看注册表里有没有它。第二种触发了但不按流程走。模型说我用某某 Skill 处理然后开始自由发挥完全不照正文的步骤来。这通常是正文太长或结构太差模型抓不到主干。把正文改成第一步、第二步的短句列表每步不超过两行能明显改善。第三种报了错但错得莫名其妙。比如提示某个命令不存在、某个路径打不开。这基本可以确定是环境问题先去跑环境自检 Skill。在环境没确认干净之前不要动任何 Skill 的配置否则你在错误的方向上改来改去问题只会更乱。4.2 用一组最小用例验证每个 Skill 真的生效我给每个 Skill 都准备了一个体检用例装完立刻跑形成肌肉记忆。环境自检的用例是故意把配置文件改名看它能不能报出配置目录异常而不是直接崩。项目索引的用例是在仓库里新建一个空目录看索引结果里有没有正确纳入或排除。终端执行的用例前面说过了一条被拦的删除命令加一条超长输出。代码审查的用例更直接往代码里故意塞一处空指针看它能否指出来。记忆编排的用例稍微绕一点先让它记住一条约定再开一个新会话问它看能不能召回。这一步特别值得做因为很多人的记忆配置路径写错了存是存进去了读的时候读另一个位置永远召回为空。注意验证用例要小、要快、要独立。别拿真实任务的输出当验证标准那东西每次都不一样你没法判断是 Skill 的问题还是任务本身的性质。4.3 配置里那几个一改就翻车的字段有几个字段我是吃过亏的单独拎出来说。description的写法有讲究。它应该包含三部分做什么、什么时候用、触发词。很多人只写第一part结果就是永远不触发。另外描述别超过一定长度太长会稀释语义权重反而不如短而准的描述容易被命中。timeout别设太大也别太小。设成 300 秒一个卡住的命令能把一次会话拖死设成 3 秒正常构建都跑不完。我的经验值是读操作 10 秒、测试类 120 秒、构建类 300 秒按命令类型分组配置而不是全局一个值。output_max_lines前面说过了但还有个细节截断的时候要带上总行数提示告诉模型输出共 1200 行这里展示头 100 行和尾 100 行。不加这句模型会以为输出就这么点漏掉的中间部分它根本不知道存在。5. 跑通之后把五个 Skill 串成真正的日常流5.1 三个高频场景的组合打法光装好还不够得有固定的组合套路。我日常用得最多的是这三种。场景一接手陌生模块。触发顺序是项目索引 → 终端执行 → 记忆。索引先给出模块地图和入口终端执行跑一次现有测试看基线状态记忆负责把这次摸出来的结论存下来。整个过程大概两三分钟比自己读半小时强。场景二修 bug。顺序是索引定位 → 终端复现 → 改代码 → 审查自查 → 记忆沉淀。这里面最容易被跳过的是终端复现很多人看完代码觉得就是这里就直接改改完发现症状没变。让终端跑一次复现命令拿到真实的错误输出比读十遍代码都管用。场景三例行重构。顺序是审查先评估现状→ 索引确定影响面→ 改 → 终端跑测试 → 审查二次确认→ 记忆。重构的关键是影响面和回归验证两件事这两个正好分别对应索引和终端执行。5.2 想更进一步自己写一个 Skill 的最小骨架等你把这五个用顺了大概率会遇到我这个项目有个特殊流程现成的 Skill 都不管用的情况。这时候自己写一个成本其实很低。最小骨架就是三样东西一个目录、一个描述文件、一份正文。目录名用英文小写加连字符描述文件里写清楚名字、描述、依赖、允许的工具正文用 Markdown 写步骤。核心就一句话——让一个不了解你项目的人照着这份文档也能做完这件事能达到这个标准模型大概率也能。写的时候有个小技巧正文开头先写一句这个 Skill 不适用的情况比写十句适用情况更能减少误触发。因为模型在犹豫要不要用时看到明确的排除条件会更容易做决定。5.3 什么时候该删 Skill比什么时候该装更重要最后说个反直觉的观点Skill 的维护重点是删不是加。每个月花五分钟过一遍已装的列表问三个问题这个月用过吗用的时候出过错吗有没有和别的 Skill 职责重叠连续两个月没用过的删或者禁用。出过错的先禁用再修别让它带病工作。职责重叠的合并或者删掉触发率低的那个。我自己的列表长期稳定在八个左右其中五个是核心链路另外三个是项目专用的。列表越短触发越准这是反直觉但真实存在的规律。6. 我踩过的几个坑以及对应的排查链路6.1 描述写得越全面触发率反而越低早期我给项目索引 Skill 写的描述是帮助理解代码库、分析项目结构、定位功能实现、评估改动影响、生成文档说明——五个动词堆在一起自以为覆盖全面。实际结果是它经常在根本不需要的任务里被触发真正需要时又因为描述太泛而竞争不过更具体的 Skill。后来我把它拆成了两句话一句说需要知道某个功能实现在哪、改动会波及哪些文件时用一句列出三个触发词。触发准确率立刻上去了。教训是描述不是功能清单是使用场景的索引。功能写在正文里场景写在描述里这两者别混。6.2 终端执行不设输出截断一次安装日志吃掉半个上下文这个坑我印象很深。当时装了个依赖日志几千行全进了上下文结果模型后面的回答明显变笨因为它能用的上下文预算被挤没了。加了截断之后同样的操作只占几十行效果立竿见影。排查这类问题有个通用思路如果你发现模型突然变笨——回答变短、开始重复、忘记前面的结论——先怀疑上下文被无关内容占满了。去看最近一次触发的 Skill 有没有产生大量输出尤其是命令日志、文件全文、JSON 响应这类。6.3 记忆存了不失效三个月前的约定一直在误导这个坑更隐蔽。我在记忆里存过一条所有接口返回统一包一层 data 字段的约定后来项目改成了直接返回。但记忆没删模型每次写新接口还是按老规矩包一层每次都要我手动纠正。修复办法是给每条记忆加两个字段来源哪个文件、哪次会话得出的和时间。召回时按时间降权超过一定天数自动标记为待确认模型在使用前会先跟你核对一次。多花这一秒能省掉后面无数次的返工。6.4 排查顺序从环境到配置到描述别跳步最后把我自己的排查顺序固化下来遇到Skill 不对劲就按这个走基本不会跑偏第一步跑环境自检确认运行时、路径、权限、注册状态全部正常。第二步看注册表里这个 Skill 到底有没有被读到没读到就是文件放错位置或格式不对。第三步临时禁用其他所有 Skill单独测这一个排除竞争。第四步如果单独测能触发就是描述竞争问题回去改描述。第五步如果触发了但不按流程走改正文结构。第六步如果报错看错误信息指向环境还是代码。这个顺序的核心是从外到内先排除环境再排除注册再排除竞争最后才动 Skill 本身的内容。反着来的人往往在排查了半小时描述字段之后才发现文件压根没被读到。我个人在实际操作中的体会是DSH 这类工具的提效曲线不是线性的前一周你会觉得装了反而更麻烦因为要配、要调、要验证等这五个 Skill 串成链路之后某天你会突然发现自己已经很久没有手动解释这个项目的路由在哪了。到那时候再考虑往列表里加第六个。
阅读完成 · 觉得有帮助？
