前言¶

在 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 目录页。