前言¶
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。
