前言¶
DeepSeek Harness（DSH）里的智能体会反复调用工具、推进多轮对话。常见问题是：请求本身不够清楚时模型仍先猜再改；危险或越界的工具调用在真正执行前缺少统一拦截；工具明明成功返回，任务却悄悄没做完；一轮对话过早结束，用户以为已经交付。社区里也有各类 guardrail 或人工审批方案，但要么绑死在特定 UI，要么只覆盖单一场景。
下面介绍 dsh-jev-loop：在 DSH agent-loop 的四个标准事件上挂载 Jev（TypeSafe System One） 判定，不依赖界面，可挂进任意 Harness 组合（无头或有 UI 均可）。维护者为 JWE24-code，npm 包名与插件名均为 dsh-jev-loop，当前版本 0.1.4，MIT 许可证。仓库带 dsh-plugin topic，由 dshfind 等市场机制索引，与 DeepSeek / 幻方无官方从属；社区目录见 SkillHub 插件页。
这是什么¶
一句话：dsh-jev-loop 在 agent/pre-step、tools/pre-execute、tools/post-execute、agent/turn-stopping 四个关口，把会话片段发给 TypeSafe API 做概率化判定，并按阈值决定注入提示、记录、询问、拒绝、阻断或继续推进。可选控制面板 moqi-jev-loop 单独发布，只依赖本包提供的 jevLoop 服务；核心包本身无 UI 依赖。
四个关口在做什么¶
| 关口 | 事件 | Jev 判定内容 | 本地决策 |
|---|---|---|---|
| Pre-step | agent/pre-step |
请求是否过于模糊 | 注入「先问再猜」类指令 |
| Pre-execute | tools/pre-execute |
破坏性、外泄、偏离任务 | log / ask / deny |
| Post-execute | tools/post-execute |
成功调用是否静默遗漏 | log / block 并反馈 |
| Turn-stopping | agent/turn-stopping |
请求是否真正完成 | nudge 继续或放行 |
四个关口默认自动参与循环。Jev 返回校准后的概率，本包负责阈值与动作；无 API Key、超时、429、错误 JSON 等情况下一律 fail open，判定服务不可用也不会卡住 agent loop。
数据流与隐私¶
启用任一关口后，部分会话内容会离开本机：发往第三方 TypeSafe API（默认 https://api.typesafe.ai/v1/systemone，可通过 baseUrl 修改）。具体包括：每个被拦截工具调用的名称与参数（执行前）、每个成功工具调用的输出（执行后，并附带最新 prompt）、以及 pre-step 与 turn-stopping 使用的近期 transcript（prompt、模型回复、工具结果），单次请求受 maxStateChars 上限。工具读到的文件、命令输出及其中出现的敏感信息会一并送出。若需保留本地，可将对应 *Enabled 设为 false，或在 preExecuteSkip 中列出需跳过的工具名。
兼容的 Harness 版本¶
README 写明支持 0.1.5-rc.x 与 0.2.0 / 0.2.1；CI 对 @deepseek-ai/dsh@0.1.5-rc.3、0.2.0-rc.2、0.2.1-rc.2 做类型检查。peerDependencies 范围与此一致；更新的 Harness 线未纳入 CI 前视为未测试。
安装与 API Key¶
先做安装，再配置密钥。
dsh plugin --profile <profile> add dsh-jev-loop
密钥可通过环境变量 TYPESAFE_API_KEY 或 TYPESAFE_APIKEY 提供，也可写入 Harness 凭据存储中的 TYPESAFE_API_KEY。配置项里可用 apiKeyEnv（默认 TYPESAFE_API_KEY）指向环境变量，避免在 patch 文件里写明文 apiKey。
配置入口¶
在 profile 的 cordis.patch.yml 里针对 dsh-jev-loop 一行修改，或在 profile 自有 patch 层覆盖。仓库内 cordis.patch.yml 可作参考。各 *Enabled 的默认值也可在运行时由 moqi 的 /JevLoop 面板覆盖，并持久化到 $DSH_HOME/jev-loop.json。
常用字段摘要（完整表见 README）：
| 字段 | 默认值 | 含义 |
|---|---|---|
preStepEnabled |
false |
首步前是否判定请求是否欠规格 |
preExecuteEnabled |
true |
工具派发前是否判定风险 |
preExecuteMode |
log |
log 仅观察，ask 要批准，deny 拒绝 |
postExecuteEnabled |
true |
成功结果是否检查遗漏 |
turnStoppingEnabled |
true |
回合结束前是否检查「是否真的做完」 |
maxStateChars |
24000 |
发往 Jev 的状态硬上限 |
timeoutMs |
3000 |
单次请求超时 |
auditPath |
$DSH_HOME/jev-loop.jsonl |
判定审计 JSONL |
成本与审计¶
每次判定对应一次 POST /v1/systemone；pre-execute 在一次调用里同时问三类风险。transcript 类关口只送最近 turnStoppingMaxMessages（默认 14）条消息。请求体 SHA-256 相同时走内存缓存（默认 500 条），重复判定不重复计费。每条判定写入 auditPath，含概率、缓存命中、延迟与 token；超过 auditMaxBytes（默认 5 MiB）时轮转到 jev-loop.jsonl.1，审计体积大致控制在两倍上限内。
典型用法¶
在现有 profile 里只挂核心 bundle¶
若要在自有 profile 中仅启用本插件与基础包，可在 bundle 列表中写：
bundles: ['@deepseek-ai/dsh-base', 'dsh-jev-loop']
用仓库提供的 throwaway profile 自测¶
维护者在 README 中给出本地构建与临时 profile 流程（需自行准备 TYPESAFE_APIKEY）：
npm install
npm run link-harness
npm run build
npm test
npm run install-profile -- jev-core
TYPESAFE_APIKEY=… dsh --profile jev-core
运行后可在 ~/.dsh/jev-loop.jsonl 查看每次判定记录。
适用场景与注意¶
适合希望在 DSH 工作流里统一做「请求澄清、工具风险、结果完整性、回合是否该停」四类判定、且接受调用 TypeSafe 云端 API 的团队。Pre-execute 可从 log 观察起步，再改为 ask 或 deny；对只读或可信工具可列入 preExecuteSkip。
插件与当前 dsh 进程同权限运行，判定请求会携带工具参数与输出中的实际内容。安装前应阅读 GitHub 源码 与 MIT 许可证，确认数据出境范围与组织策略一致。无 UI 场景可直接只用本包；需要图形化开关时再考虑独立的 moqi-jev-loop。
结尾¶
dsh-jev-loop 把 Jev 判定接到 DSH 智能体循环的标准关口上，配置集中在 Cordis patch 与可选的 $DSH_HOME/jev-loop.json，失败开放以免拖垮主循环。目录与文档：SkillHub、GitHub、npm。
