dsh-powershell-patterns

DeepSeek Harness 个人适配声明（Personal Adaptation Notice）

本项目是 DeepSeek Harness 的个人适配产物（personal adaptation），并非 DeepSeek Harness 官方文件（not an official DeepSeek Harness file），随附功能、使用说明与个人产物（bundled with features, documentation, and personal artifacts），可与 DeepSeek Harness 搭配使用，也可独立使用。

This project is a personal adaptation for DeepSeek Harness, and is NOT an official DeepSeek Harness file, bundled with features, documentation, and personal artifacts. It can be used alongside DeepSeek Harness or standalone.

作者 / Author: h565656445

合作 / Collaboration: 如有项目可以一起合作，欢迎联系。微信：wohaishihenshuaide。If you have projects, let's collaborate. WeChat: wohaishihenshuaide.

---

用途 / What this is for

PowerShell 模块工程最佳实践：模块封装、Schema 校验、哈希链 Ledger、幂等与确定性测试。

PowerShell module engineering best practices: encapsulation, schema validation, hash-chained ledger, idempotency and deterministic tests.

---

Hermes PowerShell Module Engineering Best Practices / Hermes PowerShell 模块工程最佳实践

本项目是从 Hermes Harness 源架构 src/*.psm1 中提炼的 PowerShell 模块工程最佳实践（纯文档仓库）。内容覆盖：模块封装（StrictMode 与显式导出）、严格参数校验、JSON Schema 校验与身份协商、哈希链 Ledger 与恢复、基于 token 的幂等写入（CAS）与命名互斥、稳定读取与路径安全（reparse point 拒绝）、以及确定性测试策略。所有示例均为通用模式，不包含任何源码。

This repository distills PowerShell module engineering best practices from the Hermes Harness source src/*.psm1 (pure documentation). It covers: module encapsulation (StrictMode and explicit exports), strict parameter validation, JSON Schema validation and identity negotiation, hash-chain ledgers and recovery, token-based idempotent writes (CAS) with named mutexes, stable reads and path safety (reparse-point rejection), and deterministic testing. Examples are generic patterns; no source code is included.

Features / 功能

• 模块封装：Set-StrictMode Latest + 显式 Export-ModuleMember，模块间用 PSScriptRoot 相对导入 Module encapsulation: Set-StrictMode Latest plus explicit Export-ModuleMember; relative imports via PSScriptRoot
• 严格参数校验：CmdletBinding、Mandatory 与 ValidatePattern（如 SHA-256 格式）、业务规则校验 Strict parameters: CmdletBinding, Mandatory, ValidatePattern (e.g. SHA-256 shape) and business-rule checks
• Schema 校验：同一份字节完成解析、校验与哈希，schema 身份以 id|version|sha256 协商 Schema validation: parse, validate and hash from the same bytes; identities negotiated as id|version|sha256
• 哈希链 Ledger：追加式 JSONL，序号 + 前向哈希 + 事件哈希；损坏时只暴露可信前缀 Hash-chain ledger: append-only JSONL with sequence, previous-hash and event-hash; corruption exposes only the trusted prefix
• 幂等与并发：token 比较写入（CAS）、CreateNew 不覆盖、命名 Mutex、单次使用审批 Idempotency and concurrency: token compare-and-swap writes, CreateNew without overwrite, named mutex, single-use approvals
• 稳定读取与路径安全：句柄最终路径核验、拒绝 reparse point 穿越、16 MiB 上限 Stable reads and path safety: final-path handle verification, reparse-point traversal rejection, 16 MiB limit

What's inside / 目录结构

dsh-powershell-patterns/
├── README.md                     # 双语说明 + DSH 衍生声明
├── LICENSE                       # MIT
├── docs/
│   └── powershell-patterns.md    # 双语 PowerShell 模块工程最佳实践（核心文档）
└── .dsh/                         # DeepSeek Harness 衍生包
    ├── preset.yml
    ├── agent.cordis.yml
    ├── README.md
    └── skills/dsh-powershell-patterns/SKILL.md

Quick start / 快速开始

# 1. 阅读模块工程最佳实践
$repo = "E:\path\to\dsh-powershell-patterns"
Get-Content (Join-Path $repo "docs\powershell-patterns.md")

# 2. 快速核对清单（检查你自己的模块）
#    - 开头是否有 Set-StrictMode Latest 与 $ErrorActionPreference = 'Stop'
#    - 是否显式 Export-ModuleMember
#    - 写文件是否先读旧字节再比较 token（CAS）
Get-Content (Join-Path $repo "docs\powershell-patterns.md") | Select-String "清单"

# 3. 安装 DSH 预设（可选）
$dst = Join-Path $env:DSH_HOME ".agent-presets\hermes-powershell-patterns"
Copy-Item -Recurse -Force (Join-Path $repo ".dsh") $dst

DeepSeek Harness 衍生 / DSH Derivative

本项目附带 DeepSeek Harness 衍生包，位于 .dsh/ 目录：

• preset.yml — Agent 预设元数据
• agent.cordis.yml — Cordis 组装（基于 standard 预设，persona 已定制）
• skills/dsh-powershell-patterns/SKILL.md — 项目专属技能（skill）

安装与接入方式见 .dsh/README.md（双语）。

License / 许可证

MIT

---

---

相关项目 / Related Projects

这是 DeepSeek Harness 个人适配系列（共 31 个仓库）的完整导航。 / This is the complete navigation for the DeepSeek Harness personal-adaptation series (31 repos).

Agent OS 内核 / Kernel

dsh-agent-os-runtime · dsh-agent-os-planning · dsh-agent-os-scheduler · dsh-agent-os-worker-protocol · dsh-agent-os-observability · dsh-agent-os-specs

Harness 基础设施 / Infrastructure

dsh-harness-core · dsh-graph-entry · dsh-async-job · dsh-file-identity · dsh-json-projection · dsh-manual-approval · dsh-observation-writer · dsh-provider-control · dsh-schema-negotiator · dsh-upgrade-governance

规格与文档 / Specs & Docs

dsh-harness-specs · dsh-novel-specs · dsh-architecture-guide · dsh-powershell-patterns（本仓库 / this repo） · dsh-json-schema-driven-dev · dsh-llm-agent-harness-guide

适配器 / Adapters

dsh-short-story-engine · dsh-tutorial-video-state-machine · dsh-governance-kernel · dsh-sports-pipeline · dsh-motion-grammar

DSH 总集成 / Integration

dsh-integration · dsh-presets-pack · dsh-skills-pack · dsh-starter-kit