x7687315-gif/dsh-policy

dsh-policy

面向 DeepSeek Harness 的用户可控策略与个性化运行时。

一个策略驱动的运行时扩展，让用户能够定义项目级硬约束（MUST / MUST NOT / BLOCK）、管理行为指引与编码偏好，并逐步构建一个用户可控的个性化系统——而不将长期用户规则的自主权交给 AI。

系统不仅仅是在告诉 Agent 该做什么。它是在强制约束 Agent 被允许完成什么。

该插件实际做了什么

dsh-policy 挂接到四个经过验证的 DeepSeek Harness 接缝，并将你的策略文件转化为运行时强制执行：

Agent 编辑代码            ──► tools/post-execute ──► 规范化证据（真实工具结果）
Agent 调用 MUST NOT 工具  ─► tools/pre-execute ───► 在工具主体运行前被拒绝
Agent 说“完成”            ──► agent/turn-stopping ──► 评估硬规则
违规，仍有预算剩余                            ► BLOCK：补救措施作为用户消息注入
（循环重新开启该轮次——模型必须采取行动）
预算耗尽                                     ► 该轮次只能以 ERROR 结束（绝不允许虚假完成）
所有规则通过                                 ► 该轮次正常完成

该流水线背后的子系统：

| 子系统 | 功能 | 挂接位置 |
|---|---|---|
| 策略加载器与验证器 | 读取 .dsh-policy/policy.json，对任何格式错误（包括错误的正则表达式）大声报错 | 激活时 |
| 作用域解析器 | 合并全局 / 项目 / 任务规则；强制执行约束单调性（更具体的作用域可以添加规则，但绝不能削弱更强的规则） | 激活时 |
| 约束引擎 | 纯函数 evaluate(rules, evidence) → PASS \| BLOCK + remediation；故障关闭 | agent/turn-stopping |
| MUST NOT 门禁 | 禁止的工具在其主体执行前被拒绝 | tools/pre-execute |
| 证据存储 | 每个会话的 JSONL 格式真实工具结果；在重启后仍然保留（未补救的违规会持续阻断） | tools/post-execute |
| 行为观察 | 检测重复出现的模式（重复的补救措施、被拒绝工具的重复尝试、用户纠正）——零额外 LLM 调用；候选规则在未经用户审核前绝不会成为规则 | session/event + 执行动作 |
| 行为守卫 | 经用户确认的、上下文相关的、绝不阻断的提醒（与硬规则类型隔离） | 提示层 910 + post-execute 上下文 |
| 用户模型 + 🧋 审核 | 持久的个性化，具有单一写入路径（ConfirmRequest）、完整审计追踪、交互式审核 CLI | CLI（唯一的写入者） |
| 上下文解析器 | 在严格的 800 token 预算下仅注入与任务相关的偏好/目标；硬规则绝不会被驱逐 | 提示层 920/925 |
| 项目生命周期 | 已暂停/已完成/已归档的项目停止贡献规则 | 激活（注册表） |

验证基线：跨 25 个文件的 166/166 测试，端到端基准测试（见 docs/benchmarks.md），本地 Web 管理界面（pnpm ui），以及针对构建后的 dist/ 包运行的打包测试。

截图

内置的 Web 管理界面（pnpm ui / dsh-policy ui）——仅限 localhost，用点击操作代替编辑配置文件：

仪表盘——一目了然

行为审核——确认/编辑/拒绝观察到的模式（显示证据 + 置信度）

为什么

大多数“记忆插件”只是把更多用户信息放进提示词中。本项目不同：Agent 运行在一个由用户控制的策略边界内，该边界分为三层：

| 层级 | 语义 | 能否阻断 Agent |
|---|---|---|
| 1. 项目策略（硬约束） | MUST / MUST NOT / BLOCK，可机器验证 | 能 |
| 2. 行为守卫（重复出现的错误） | WARNING / GUIDE | 否 |
| 3. 编码偏好（风格/习惯） | PREFER / SOFT | 否 |

优先级：硬性项目策略 > 行为指导 > 编码偏好。

核心不变量：

- AI 建议不等于用户授权。 AI 可以观察和建议，但绝不会静默创建/修改/删除持久规则。
- 运行时事实胜过模型声明。 硬规则通过可观察的工具/会话事件验证，而不是根据 LLM 说“我做了”。
- 约束单调性。 具体规则可以增加要求，但绝不会静默削弱更强的硬规则。

它实现为一个原生 DeepSeek Harness 插件（Cordis），而不是另一个 agent 框架。

安装

注意： 该包尚未发布到 npm。在此之前，请从 GitHub 或本地检出安装（见下文）；发布后将是 pnpm add dsh-policy。

1. 添加依赖并搭建脚手架

从 GitHub 安装（固定 commit/tag 以保证可复现性）
pnpm add github:x7687315-gif/dsh-policy
或者从本地检出安装
pnpm add ./path/to/dsh-policy

然后使用捆绑的 CLI 搭建你的第一条策略（绝不覆盖已存在的文件）：
bash
npx dsh-policy init            # 创建 .dsh-policy/policy.json，内含一条可用的起始规则

要求：Node ≥ 20、pnpm（或 npm/yarn），以及带有 Cordis 加载器的 DeepSeek Harness 运行时。

2a. 通过 cordis.yml 将其接入你的 Harness（推荐）
yaml
plugins:
你的 LLM 适配器 —— API 密钥来自环境变量，绝不来自文件
- name: '@deepseek-ai/dsh-llm-deepseek'
options:
apiKey: ${DEEPSEEK_API_KEY}
model: deepseek-chat
baseURL: https://api.deepseek.com

- name: dsh-policy
options:
policyPath: .dsh-policy/policy.json   # 你项目的硬性规则
userModelPath: ~/.dsh-policy/user-model.json
behavior:
enabled: true                       # 选择启用模式观察
context:
tokenBudget: 800                    # 指导/偏好的提示预算
projectId: my-project                 # 启用生命周期注册表

完整的生产示例位于 examples/cordis.yml。

2b. 或者以编程方式挂载
ts
import { dshPolicy } from 'dsh-policy'

await ctx.plugin(dshPolicy, {
policyPath: '.dsh-policy/policy.json',
behavior: { enabled: true },
})

3. 编写你的第一条策略

在你的项目中创建 .dsh-policy/policy.json：
json
{
"project": "my-api",
"policy": {
"hard": [
{ "id": "test-after-code-change", "trigger": "code_change", "require": "tests_pass", "enforcement": "hard" },
{ "id": "no-dangerous-commands", "trigger": "always", "denyTools": ["drop_database"], "enforcement": "hard" }
]
}
}

完整模式（工具通过规则、拒绝规则、证据匹配器、作用域、补救文本）记录在 docs/policy.md 中。

插件选项

| 选项 | 默认值 | 用途 |
|---|---|---|
| policy / policyPath | /.dsh-policy/policy.json | 项目硬性规则（内联优先于路径） |
| globalPolicy / globalPolicyPath | ~/.dsh-policy/policy.json | 跨项目硬性规则 |
| taskRules | — | 仅追加的任务作用域规则 |
| projectId / projectRegistryPath | ~/.dsh-policy/project-registry.json | 生命周期：已暂停/已归档的项目停止强制执行 |
| maxRemediations | 2 | 在硬性拒绝之前每轮注入的补救措施数 |
| evidenceRoot | 内存中 | 用于持久化每会话 JSONL 证据的目录 |
| behavior | 禁用 | 模式观察（写入候选供审查，绝不写入规则） |
| userModelPath | — | 对已确认的守卫/偏好的只读消费 |
| guards / preferences / goals | — | 用户模型投影的内联覆盖 |
| context.tokenBudget | 800 | 指导/偏好的提示预算（硬性规则绝不被驱逐） |

运行事项
统一 CLI（通过 bin 条目安装为 dsh-policy，或从仓库安装）：
bash
dsh-policy init      # 搭建 .dsh-policy/policy.json 脚手架（从不覆盖）
dsh-policy review    # 交互式/管道式候选审查
dsh-policy project   # 生命周期：pause | resume | complete | archive
dsh-policy ui        # 本地 Web 管理 UI -> http://127.0.0.1:5178

从仓库检出后，相同的命令可通过 pnpm 脚本运行（pnpm ui、pnpm review、pnpm project、pnpm init），此外还有：
bash
pnpm install
pnpm test        # 166 个测试 / 25 个文件 — 真实 Harness 技术栈，脚本化 LLM（无需 API 密钥）
pnpm bench       # 完整基准测试扫描 -> bench/report.json（约束/个性化/成本）
pnpm demo        # 端到端：BLOCK -> 注入修复 -> 运行测试 -> PASS
pnpm typecheck   # 严格 TS，零错误
pnpm build       # tsdown -> dist/（可发布到 npm 的打包产物，由打包测试验证）

🖥️ Web 管理 UI — 点击式管理
bash
pnpm ui --policy .dsh-policy/policy.json --candidates  --model ~/.dsh-policy/user-model.json
打开 http://127.0.0.1:5178  （仅限 localhost）

六个标签页，无需编辑配置文件：

- Dashboard — 规则、待处理候选、活跃守卫/偏好、项目、证据会话的计数
- Hard rules — 跨项目与全局作用域添加/编辑/启用/禁用工具通过规则和 MUST-NOT 规则；每次保存都经过服务端验证（无效规则——包括错误的正则表达式——绝不会写入磁盘）
- Candidates — 审查观察到的模式及其证据与置信度：确认 / 编辑消息 / 拒绝（永久墓碑化）/ 跳过
- Guards & preferences — 管理持久化的用户模型记录，支持启用/禁用/删除（全部审计），通过 appliesTo 条件添加偏好
- Project lifecycle — 暂停/恢复/完成项目
- Evidence — 只读的按会话 JSONL 查看器

UI 中保持写入路径纪律：它是第二个合法写入者（仅次于 Review CLI），每次变更都是显式的用户操作，经由 ConfirmRequest{via:'review-ui'} + 审计流转；插件保持只读，并在下次激活时获取变更。

🧋 Review CLI — 确认或拒绝行为候选

观察会产生候选；只有你才能让它们持久化：
bash
pnpm tsx src/review/cli.ts --candidates  --model ~/.dsh-policy/user-model.json

对于每个候选，它会显示证据、出现次数和置信度，然后询问：
[y] confirm / [e ] edit / [n] reject / [s] skip。已确认的候选会在下次激活时成为
Behavior Guards；被拒绝的候选会被墓碑化，永不再出现。
CLI 是用户模型的唯一写入者，每次变更都会被审计。

项目生命周期 CLI
bash
pnpm project pause      # 规则停止对新会话产生作用
pnpm project resume
pnpm project complete
pnpm project archive    # .dsh-policy 移动到 archive/，历史记录保留

生产运行

1. export DEEPSEEK_API_KEY=...（切勿提交密钥），
2. 使用 examples/cordis.yml 启动你的 Harness，
3. 插件加载你的策略，在提示词中告知模型相关规则，并在回合边界强制执行这些规则——无本地推理，所有 LLM 调用均发往 DeepSeek 云 API。

强制执行行为一览

Agent 编辑代码                       → tools/post-execute 记录 code_change（真实工具结果）
Agent 未运行测试就说“完成”           → agent/turn-stopping 评估策略
→ BLOCK：补救措施以用户消息形式注入
Agent 运行测试，测试再次失败         → 再次 BLOCK（在补救预算内）
预算耗尽但仍存在违规                 → 该回合只能以错误结束（绝不伪造完成）
Agent 运行测试，测试通过             → PASS：该回合可以完成
Agent 调用 MUST NOT 工具             → tools/pre-execute 在主体运行前拒绝该调用
每一步                               → 模型在提示词中看到生效规则（解释 ≠ 强制执行）

状态

阶段 0–18 已完成——完整的项目计划（阶段 0–18）以及 Web 管理 UI 和真实环境加固。 验证基线：pnpm test 在 25 个文件中 166/166 通过，pnpm typecheck 无错误，pnpm build 通过，pnpm bench 全量扫描基准测试通过（报告，解读）。

- [x] 阶段 0 — 仓库基础
- [x] 阶段 1 — Harness 集成验证（回合停止阻断机制已确认）
- [x] 阶段 2 — 策略与约束引擎核心
- [x] 阶段 3 — 硬约束概念验证（code_change → tests_pass）
- [x] 阶段 4 — 文档与收尾
- [x] 阶段 5 — 泛化规则模型 + 约束单调性
- [x] 阶段 6 — MUST NOT 门禁（tools/pre-execute 拒绝）+ 提示词中的规则可见性
- [x] 阶段 7 — CI（GitHub Actions）与文档同步
- [x] 阶段 8 — 持久会话证据、HMR 安全性、可发布构建
- [x] 阶段 9 — 缺陷审查（每回合预算、根目录清理、严格拒绝触发）
- [x] 阶段 10 — 行为观察引擎（零额外 LLM 调用）
- [x] 阶段 11 — 行为守卫（上下文相关、永不阻断的引导）
- [x] 阶段 12 — 用户模型 + 🧋 审查流水线与 CLI（单一写入路径 + 审计）
- [x] 审计 — L1/L2 安全审计：软层无法获得 BLOCK 或绕过授权
- [x] 加固 — R1 正则快速失败 + R2 失败关闭式回合门禁
- [x] 阶段 13 — 偏好层与上下文解析器（token 预算、相关性、顺序 920）
- [x] 阶段 14 — 作用域（全局/项目/任务）+ 生命周期注册表与 CLI
- [x] 阶段 15 — 完整组合：目标模型、cordis.yml、场景 A–E 端到端
- [x] 阶段 16 — 基准测试：约束有效性 / 个性化有效性 / 成本
- [x] 阶段 17 — Web 管理界面（计划外增强）：对规则、候选、守卫、偏好、生命周期进行点击式管理
- [x] 阶段 18 — 真实环境验证（dist 包、发现语义、真实浏览器 UI 测试）+ 安装简化（dsh-policy init / 统一 CLI / bin 入口）

下一步：加固与部署 — npm 发布、云端冒烟测试（DeepSeek key）、已登记的工程债务（见 docs/PROGRESS.md）。

工程报告 — 我们做过的一切，按阶段逐一呈现

下面每个阶段都有一份完整报告（做了什么、如何做的，以及之后项目处于什么状态）。请先阅读项目计划（原始规格说明）和阶段表（当前状态），然后再深入任一阶段：

基础

- 阶段 0 — 仓库奠基 — 脚手架、文档系统、GitHub 仓库
- 阶段 1 — Harness 接入验证 — 真实扩展 API 已验证，回合停止机制已确认
- 阶段 2 — 策略与引擎核心 — schema / validator / loader / evidence / 纯引擎
- 阶段 3 — POC 集成测试 — 四个用例证明 agent 在违反策略时无法结束
- 阶段 4 — 收尾同步

泛化

- 阶段 5 — 规则模型泛化 — 两种规则类型、作用域解析、约束单调性
- 阶段 6 — MUST NOT 门禁与规则可见性 — 执行前拒绝门禁、提示词分层、根作用域发现
- 阶段 7 — CI — GitHub Actions（push/PR 时执行 typecheck + tests）
- 阶段 8 — 持久化与 HMR 安全 — 按会话的 JSONL 证据、重启后存活、策略编写指南
- 阶段 9 — 缺陷审查与修复 — 按回合预算、根注册清理、严格拒绝触发

个性化

- 阶段 10 — 行为观察引擎 — 确定性模式、置信度公式、拒绝墓碑
- 阶段 11 — Behavior Guard — 上下文相关且永不阻塞的引导、类型隔离不变量
- 阶段 12 — User Model 与 Review — 单一写入路径 + 审计 + 🧋 CLI（交互式/管道式）
- 安全审计 — L1/L2 架构安全审计 — 软层无法获得 BLOCK 或绕过授权
- 加固 — R1/R2 — 正则快速失败 + 失败关闭式回合门禁

组合与验证

- 阶段 13 — 偏好层与 Context Resolver — 相关性匹配、800 token 预算、顺序 920
- 阶段 14 — 作用域与生命周期 — 全局/项目/任务作用域、生命周期注册表与 CLI
- 阶段 15 — 全量集成与端到端验收 — 目标模型、cordis.yml、场景 A–E
- Stage 16 — 基准测试 — 三维基准测试 + 它捕获的 P1 缺陷
- 审查轮次 — 一致性/全局性/安全性审查 — 横切缺陷审查
- Stage 17 — Web 管理界面 — 计划外增强：点击式管理界面（计划外附加项）
- Stage 18 — 真实环境验证与安装简化 — dist 打包测试、发现语义、真实浏览器 UI 验证、dsh-policy init

参考文档

- docs/architecture.md — 经验证的 Harness 扩展接缝与发现
- docs/policy.md — 如何编写策略文件
- docs/benchmarks.md — 基准测试解读
- docs/roadmap.md — 每个阶段的技术计划
- docs/PROGRESS.md — 实时阶段表与提交日志

社区

dsh-policy 是 DeepSeek Harness 插件生态系统（“一切皆插件”）的一部分——可通过 GitHub 主题 dsh 和 dsh-plugin 找到它（及其同类项目）。

- 🐛 发现了 bug 或想要新功能？提交 issue
- 🔀 欢迎 PR——小而可测试、可解释的改动（参见计划中的贡献理念）
- 🧋 测试版反馈尤为宝贵：三层模型是否符合你约束 agent 的方式？

许可证

MIT