前言¶

在 DeepSeek Harness（DSH）裏開一個會話，一下午裏可能換好幾個倉庫、分支和環境。每個地方往往各有 Git 身份、分支命名、受保護分支、提交格式和評審約定；這些內容多半散落在 CONTRIBUTING.md、commitlint 配置、羣聊或同事記憶裏，模型看不到，深夜改代碼時也容易被違反。

下面介紹 dsh-visualrules（維護者 Mephisto1056，社區分類 admin-security）：它不改動倉庫裏的 agents.md、不寫回 Git 配置、不保存密碼或私鑰，而是把「工作區畫像、團隊規則、提交校驗、會話級規則注入」做成 DSH 裏可查看、可執行、可追蹤的一等公民。

這是什麼¶

dsh-visualrules 是面向 DSH 的插件，npm 包名爲 dsh-visualrules，當前資料中的版本爲 0.2.0，許可證 MIT。它需要 Node.js >= 20，並面向 DSH 0.2.2-rc.1+ 構建與測試。

一句話概括 README 中的定位：Workspace profiles, team rules, commit validation, and session-scoped rule injection for DeepSeek Harness —— 會話頭可見環境信息，規則可注入系統提示，AI 發起的 git commit 與建分支會先過規則引擎，可選 Git 鉤子覆蓋終端與 IDE 裏的人工提交。

目錄頁：SkillHub - DSH-visualrules
源碼與文檔：GitHub - Mephisto1056/DSH-visualrules

核心能力¶

工作區畫像與團隊配置¶

會話頭展示當前環境；一點即可在右側邊欄查看身份、分支、遠程、環境色階與規則摘要。插件會讀取 Git user.name / user.email 的實際作用域、分支與 upstream、ahead-behind、受保護分支與命名告警、團隊負責人與聯繫人、工具鏈與 CI 預期等（README 功能表 F1.x）。

團隊側使用倉庫內只讀的 .dsh/profile.yaml：YAML 語法錯誤會報告行號與字段路徑；未知字段忽略並提示；團隊層拒絕信任個人字段（F4.x）。

規則包與會話注入¶

可創建、導入 Markdown、編輯規則包，全局或按工作區啓用，同一包可跨倉庫複用。團隊包可用 file: 指向倉庫內文件，或用 content: 內聯，插件側只讀（F0.1、F0.4、F0.6）。

啓用後的規則按 個人 → 團隊 → 工作區補充 疊合，後者優先。注入前可在界面預覽完整文本、字符數、上下文預算及截斷情況，再進入下一步模型調用（F0.2、F0.3、F0.5）。默認安裝後不會自動啓用任何規則包。

提交校驗與模型可讀反饋¶

校驗維度包括：身份、受保護分支、分支命名、Conventional Commits、允許的類型與 scope、標題長度、關聯 Issue、merge 信息不一致、以及 --no-verify 是否可見等；每條規則在工作區內可設爲 off / info / warn / block（F2.1–F2.4、F2.6）。

AI 發起的 git commit 或建分支在真正執行前先過規則引擎。若被 block，工具調用會返回違反的規則、來源與具體修復建議，模型在下一步可讀並重試；另提供 visualrules_check 供預檢提交信息或分支名（F2.8）。

可選託管 pre-commit、commit-msg 鉤子覆蓋人工提交：已有鉤子會先備份並仍優先執行；卸載可恢復。若 core.hooksPath 指向倉庫外路徑，插件會拒絕（F2.9）。被攔截的提交僅能通過 UI 申請一次性放行（須寫明理由，TTL 5–30 分鐘），智能體不能自行創建 bypass（F2.7）。

索引與既有規則源¶

成功由 AI 發起的提交會在本地按會話、倉庫、分支、作者與完整 hash 建索引，不寫進 commit 或 Git notes（F3.8）。插件只讀發現 commitlint（JSON/YAML/靜態 JS）、.editorconfig、eslint 配置、CONTRIBUTING.md、PR 模板等，用已有配置補全缺口而非再抄一本規則書（F4.7）。攔截、警告、一次性放行與 AI 提交 hash 均在本地可追溯。

界面支持明/暗主題，會話頭入口、右側快速預覽、完整畫像頁與 Settings 分區；中英文字典（F1.8、F4.6）。

安裝與啓用¶

插件以當前 DSH 進程權限運行，安裝前請自行查看源碼與 MIT 許可證。生態上 DSH 強調「一切皆插件」；SkillHub 爲社區目錄，與 DeepSeek / 幻方無官方從屬關係。

從本地包目錄安裝（README 當前寫明的方式）¶

在插件源碼目錄執行依賴安裝後，把絕對路徑裝進你實際使用的 DSH profile（如 desktop、web）：

npm install

dsh plugin --profile desktop add /absolute/path/to/DSH-visualrules

也可在 DSH 會話內讓智能體通過 plugin_manager 用上述絕對路徑安裝。安裝後應對瀏覽器做硬刷新（Cmd/Ctrl + Shift + R）：宿主側會立即激活，客戶端 bundle 由頁面加載。

從 npm 安裝（發佈後）¶

dsh plugin --profile desktop add dsh-visualrules@latest

兼容性與 DSH 版本線見倉庫內 docs/compatibility.md。

首次運行建議¶

1. 在 Git 倉庫中打開 DSH 會話。
2. 點擊會話頭工具區左緣的盾牌圖標（或側邊欄盾牌進入完整頁）。
3. 打開 Validation，查看生效規則；在團隊規則或個人期望配置前，默認不會因規則而 block。
4. 向倉庫添加 .dsh/profile.yaml 並提交，供團隊共享規則源。
5. 可選啓用規則包，在 Injection preview 中確認模型將收到的文本。

典型用法：提交團隊 profile¶

在倉庫中維護只讀團隊配置，示例結構如下（字段含義見 README Quick start，可按團隊裁剪）：

# .dsh/profile.yaml — committed, read-only to the plugin
version: 1
team: 支付平臺組
environment: staging
environments:
  - { name: dev, host: dev.example.com, level: dev }
  - { name: staging, host: stg.example.com, level: warn }
  - { name: prod, host: prod.example.com, level: danger }
git:
  branch_pattern: "^(feature|fix|hotfix)/[a-z0-9-]+$"
  commit_format: conventional
  allowed_commit_types: [feat, fix, docs, refactor, test, chore]
  header_max_length: 72
  require_issue: true
  merge_strategy: squash
  protected_branches: [main, "release/*"]
  review:
    min_approvals: 2
dev:
  toolchain: { node: "20.x", python: "3.11" }
  lint: eslint
  test: [unit-test]
  ci_required: [lint, unit-test]
docs:
  wiki: https://example.com/wiki
  issues: https://example.com/board
team_info:
  owner: 張三
  contacts: [張三 · 負責人 · zhang@example.com]
  release_window: 每週四 20:00
packs:
  - id: team/git-rules
    title: 團隊提交規範
    file: .dsh/rules/git-rules.md

packs 中的 file: 可指向倉庫內 Markdown 規則文件，由插件只讀加載並參與注入與校驗上下文。

適用場景與注意¶

適合誰：需要在 DSH 會話裏統一看見「當前是誰、在哪個環境、分支與遠程是否合規」，並希望 AI 代發 git commit 時與團隊 Conventional Commits、受保護分支等策略一致的多人協作倉庫；同時想把團隊規範注入模型系統提示、又不願改動倉庫既有文檔結構的團隊。

使用時注意：

• 禁用校驗或卸載插件時，README 寫明不會破壞 Git 與 DSH 既有狀態；Server 類信息默認關閉，需顯式開啓。
• 一次性 bypass 僅用戶可在 UI 操作，適合有明確理由的例外，並會進入本地審計索引。
• 依賴 DSH 宿主 API（engines.dsh: >=0.2.2-rc.1），升級 DSH 主版本時請對照倉庫兼容說明。

結尾¶

經過上面的步驟，dsh-visualrules 把散落在文檔與配置裏的約束接到會話頭、校驗引擎與規則注入上，讓「看見規則、攔截錯誤提交、把規範教給模型」落在 DSH 工作流內，而不必爲了用插件去改倉庫核心文件。

進一步瞭解安裝細節與完整字段說明，見 GitHub 倉庫 README（含 README_ZH.md）與 SkillHub 目錄頁。