执行命令后，Agent 没有留下可核对的结果；Hook 报错时，任务却可能继续向下走。
最快的做法是：先配置 1 个可观察的拦截点，优先选择失败时拒绝放行的路径，再逐步加入匹配规则和自动化动作。不要一次接入完整脚本集合，也不要把 Hook 当成操作系统级沙箱。
这篇文章适合三类人：
- Agent 开发者：需要在工具调用前后加入校验或反馈。
- 平台工程师：需要统一项目级与环境级 Hook 的交付方式。
- 远程环境维护人员：需要确认 Hook 在断线、重启和无人值守场景下仍可观察、可回退。
[ SECTION_01 ] 配置前的控制目标
DeepSeek Harness Hooks 配置最容易出错的地方，不是脚本不会写，而是一个 Hook 同时承担了太多责任。
动手前先把目标分成四类：
- 权限拦截：决定某次工具调用能否继续。
- 结果记录：记录工具名称、参数摘要、退出结果和错误类型。
- 停止门禁：在 Agent 认为任务完成前，要求额外验证。
- 上下文补充：把环境状态、检查结果或限制条件反馈给后续流程。
第一版只能选其中一个。对于需要控制命令执行的场景，优先选择工具执行前的拦截点，例如 PreToolUse。如果当前版本的 Hook Protocol 并没有提供同步阻断契约，就不能自行假设它具备阻断能力。
任务书已确认，当前版本的协议源码、配置目录、持久化调用和结果事件需要逐项复核。不同 Hook 方言、匹配点和失败默认值不能从其他 Agent 工具迁移过来。公开的 Harness 协议也强调，协议实现和具体工具之间仍可能存在不同配置层与能力边界，不能把通用规范当成 DeepSeek Harness 的字段说明。(Harness Protocol 官方入门文档)
Hook 还不能替代以下控制：
- 工作区隔离。
- macOS 用户权限。
- 凭据可见范围。
- 网络访问策略。
- 进程和文件系统沙箱。
因此，“Hook 返回拒绝”与“系统绝对无法执行”不是同一件事。前者是 Agent 运行链路的控制，后者需要操作系统或基础设施层配合。
[ SECTION_02 ] 配置目录与协议核对
配置文件的实际位置不能靠其他 Agent 的使用经验推断。应按当前版本源码确认三个问题：
- 配置加载入口读取了哪些文件。
- 用户级配置与项目级配置是否同时生效。
- 项目级配置是合并、覆盖，还是完全替换用户级配置。
建议先在本地代码仓库中搜索 hooks、配置加载器、事件枚举和 Hook 执行器。然后记录以下核对结果：
- 配置文件的实际路径。
- 文件格式与解析器。
- Hook 事件名称。
- 匹配字段。
- 输入是标准输入、环境变量，还是结构化事件。
- 输出是退出码、标准输出，还是协议对象。
- 超时和进程启动失败的处理方式。
当前不建议在文章或团队模板中写死未经源码核实的配置键。网上常见的 before_tool、after_tool、command、timeout 等名称，可能属于其他实现。某些开源 Agent 已经出现“事件可触发但只读、尚不能修改参数”的阶段性实现，这正说明 Hook 名称相似，不代表行为相同。(DeepSeek 相关开源变更记录)
配置目录确认后，如果需要交付给团队，可把配置文件、Hook 脚本和运行时依赖放在同一版本目录，并在提交记录中保存版本号。不要只复制一段配置文本。远程 Mac 上也应保留同样的目录结构，避免本地路径在迁移后失效。
[ SECTION_03 ] 首次接入与最小匹配
第一次接入只验证一个低风险工具调用。例如，只监听读取类工具，记录工具名称和参数摘要，不修改参数，也不触发外部写入。
一个合格的最小 Hook 至少要能回答四件事：
- 什么时候触发。
- 收到了什么输入。
- 返回了什么处理结果。
- 没有命中时是否保持原路径。
测试时准备两个任务：
- 一个确定会命中规则的允许任务。
- 一个确定不会命中的无关任务。
成功信号不是“配置文件能够被解析”，而是同一个触发路径能够重复出现，并且无关任务仍然正常完成。至少保留以下记录：
配置版本：
项目目录：
会话标识：
触发事件：
工具名称：
参数摘要：
Hook 处理结果：
Agent 后续结果：
未命中时的结果：
记录中不要保存完整命令、客户路径、令牌或密钥。远程环境中的日志尤其需要脱敏。凭据应通过受控环境变量或专门的密钥注入机制提供，不应拼接到命令行参数里；公开的自动化文档也提醒，命令行参数可能被进程查看或审计记录捕获。(GitHub Actions 官方密钥文档)
[ SECTION_04 ] 放行、拒绝与异常策略
Hook 的核心不是“能不能运行脚本”，而是失败后 Agent 到底能不能继续。
第一轮放行测试要拆成四类证据：
- ✅ 明确放行：规则满足，工具正常执行。
- ❌ 明确拒绝：规则不满足，工具不应执行。
- ⚠️ 脚本异常：Hook 进程返回异常或输出不符合协议。
- ⚠️ 执行超时：Hook 未在协议允许的时间内返回。
每一类都需要从会话事件、持久化事件或实际执行结果中核对。不能只看配置文本，也不能因为终端显示了“Hook started”就认定危险命令已被阻止。
如果脚本异常或超时后的行为没有明确证据，默认采用“拒绝放行”。这是比“失败继续”更适合权限拦截的回退策略。等到源码或实测确认失败语义后，再决定是否允许某些观察型 Hook 采用宽松模式。
这里要区分两种 Hook：
- 观察型 Hook：主要写日志。失败通常影响可观察性。
- 门禁型 Hook：决定工具能否执行。失败可能直接影响安全边界。
两者不要共用同一套失败处理。观察型日志写入失败时，可以停止任务并报警；门禁型校验失败时，应该保持拒绝，避免因日志或检查服务异常而放行。
[ SECTION_05 ] 写入与命令场景的边界
从读取类工具扩展到 Bash、文件修改或外部工具时，每次只增加一类操作。
建议按下面的顺序收紧边界：
- 先限定工作区根目录。
- 再限定允许访问的文件类型。
- 再限定可接受的参数类型。
- 最后才增加命令执行或外部网络访问。
- 每次扩展前保留上一版可回退配置。
匹配器过宽，会把正常任务一起拦住。例如只按工具名称匹配，可能无法区分只读操作和写入操作。匹配器过窄，则可能漏掉参数顺序、路径形式或调用变体。
危险命令拦截不能只依赖字符串黑名单。更稳妥的判断顺序是：
- 工具名称是否属于高风险类别。
- 工作目录是否在允许范围。
- 参数是否包含写入、删除、权限变更或外部连接意图。
- 是否需要人工确认。
- Hook 是否能够返回明确拒绝结果。
⚠️ 经验提醒：如果 Hook 只能记录事件，不能同步改变执行决策，就不要把它宣传成命令拦截器。此时应把它放在审计链路中，并在真正的工具执行层增加独立的权限策略。
[ SECTION_06 ] 决策评分：先小范围还是直接铺开
下面用 5 分制比较两种上线方式。分数越高，越适合当前阶段。
方案 A：单一拦截点试点
- 可观察性：★★★★★
- 失败可控性：★★★★★
- 回退难度：★★★★★
- 初期覆盖范围：★★☆☆☆
- 适合对象：首次接入、协议尚未完全熟悉、远程环境不稳定的团队。
方案 B：完整脚本集合一次上线
- 可观察性：★★☆☆☆
- 失败可控性：★★☆☆☆
- 回退难度：★☆☆☆☆
- 初期覆盖范围：★★★★★
- 适合对象：已有固定版本、完整事件记录和自动化回归测试的团队。
决策条件很简单：
- 如果还不能证明异常和超时后的实际结果，选方案 A。
- 如果 Hook 输入输出契约已经被源码确认，且四类测试都有记录，再考虑方案 B。
- 如果远程 Mac 尚未完成重启复测，继续保留方案 A。
- 如果团队需要审计结果但不需要阻断，先部署观察型 Hook，不要混入权限拦截逻辑。
[ SECTION_07 ] 远程 Mac 的交付检查
迁移到远程 Mac 后，真正需要重建的是执行责任，而不是单纯复制文件。
至少完成以下 5 步：
-
确认脚本存在
检查 Hook 脚本路径、文件内容和执行权限。相对路径要改成远程环境可解析的路径，或由启动器明确设置工作目录。 -
确认运行时存在
核对解释器、依赖包和版本。交互式终端里能运行，不代表无人值守会话也能找到同一个运行时。 -
确认环境变量
区分普通配置和敏感凭据。敏感值只注入到需要它的进程，不写入 Hook 输出或普通日志。环境级密钥应在审批或保护条件满足后才暴露给任务，这类分层机制在自动化部署文档中已有明确说明。(GitHub Actions 官方环境文档) -
确认重启恢复
重启后重新检查 Hook 文件、依赖、工作目录、日志目录和启动方式。不能把“远程桌面已连接”当作 Agent 服务已恢复。 -
确认非交互运行
使用与持续任务相同的启动方式测试。重点观察标准输入、标准输出、退出码和超时是否改变。
远程 Mac 还存在三个隐性成本：
- 断线后缺少实时终端，错误可能只留在日志里。
- 重启后环境变量和工作目录可能变化。
- 多个项目共用机器时，用户级 Hook 可能意外影响其他工作区。
需要临时算力或独立验证环境时，可以先参考 NOVAKVM 的 Mac 环境入口，再按项目要求核对工作区、运行时和日志保留方式。若需要选择具体 Mac 规格，应把 Hook 依赖和持续任务类型一起评估，而不是只比较处理器名称。
[ SECTION_08 ] FAQ：配置与回退
怎样确认 Hook 配置的生效目录？
不要直接套用其他 Agent 的目录或文件名。应先查看当前 DeepSeek Harness 源码中的配置加载入口、用户级目录和项目级目录，再确认实际生效层级。修改后使用新会话验证，因为部分配置可能只在启动或会话初始化时读取。目录未核实前，不建议把配置复制到远程 Mac。
怎样用 Hook 阻止危险命令执行？
把拦截点放在工具真正执行之前，优先匹配工具名称、工作区和参数类型，而不是只搜索一段命令字符串。Hook 必须对明确风险返回拒绝结果，并记录触发原因。工作区限制、凭据隔离和系统权限仍需独立配置，Hook 不能替代操作系统级沙箱。
Hook 脚本失败后，Agent 还会继续执行吗？
不能从配置文本推断答案。不同版本可能区分正常非零退出、超时、进程启动失败和协议输出错误。上线前应分别制造脚本异常与超时，观察会话事件或执行结果。若失败行为无法确认，应按拒绝放行处理，不要扩大工具权限。
远程 Mac 重启后，Hooks 还会继续生效吗？
只有在 Hook 文件、解释器、环境变量、工作目录和启动方式都能在重启后的非交互会话中恢复时，才能认为它仍然有效。重启后至少复测一次允许任务、拒绝任务和异常 Hook，并检查日志是否继续写入。远程连接恢复不等于 Agent 配置已经恢复。
[ SECTION_09 ] 上线验收与回退记录
上线前不要只做“允许”和“拒绝”两次演示。应形成四类端到端证据：
- 允许任务：命中允许规则，工具执行成功，结果事件完整。
- 拒绝任务：命中风险规则，工具没有实际执行，拒绝原因可追踪。
- 异常 Hook：脚本异常或超时，Agent 按预期停止或进入明确错误状态。
- 恢复任务：修复 Hook 或回退版本后，普通任务能够重新执行。
验收记录至少包含：
- DeepSeek Harness 版本或提交标识。
- Hook 配置版本。
- 工作区位置。
- 触发事件和匹配规则。
- 工具执行结果。
- 日志位置与脱敏情况。
- 重启后的复测结果。
- 发生异常时的回退动作。
如果其中一类证据缺失，就保留试点范围，不开放 Bash、文件写入和外部工具。平台工程团队可以把这份记录接入自己的发布流程；对于需要环境保护和人工确认的持续任务，也可以参考 NOVAKVM 的 Mac 交付页面核对远程环境交付条件。
本地配置已经通过四类测试后，再把同一版本的脚本、运行时依赖、重启恢复和日志留存要求带到远程 Mac。这样做比直接复制配置更稳妥，因为当前方案如果依赖个人电脑，常见问题是机器休眠、环境漂移和无人值守任务中断；如果依赖临时云主机，又可能遇到 macOS 工具链缺失、工作区恢复不完整或权限边界不清。对于需要临时算力、远程调试或持续验证的任务，使用 NOVAKVM 的 Mac 环境先完成交付验收，再开放长期运行，通常更容易把 Hook 的执行责任、日志和回退动作固定下来。
参考依据：