← Back to home@FranklinZaneDurant

agent-discipline

给 AI 编码 Agent 的仓库工作纪律插件（DeepSeek Harness bundle）：方法论提示段 + 工件脚手架（AGENTS.md/特性清单/验证门）+ 合规审计。

Stars
1
Language
TypeScript
Created
Aug 27, 2026
Updated
Aug 27, 2026
Coding
GitHub repo

Introduction

agent-discipline

把《Harness Engineering Methodology》（HARNESS-METHODOLOGY-SPEC v1.0，本仓库随附副本见根目录）实现为 DeepSeek Harness 的 out-of-tree bundle：方法论 persona 提示段 + 工件脚手架工具（agent_discipline_init）+ 合规审计工具（agent_discipline_audit）。本仓库自身也按该方法论约束开发（dogfooding：见 AGENTS.md / feature_list.json / PROGRESS.md）。

安装

本地开发（相对路径 spec 锚定调用目录；本地文件夹名仍为 dsh-methodology）：

cd <deepseek-harness 检出>
pnpm dsh --profile web plugin add ../dsh-methodology

发布后：

dsh plugin --profile web add agent-discipline

使用

  • 提示段：安装后自动注入（system-prompt section agent-discipline，order -90），模型按 §1.3 会话生命周期与核心不变式工作。
  • agent_discipline_init：在目标仓库生成 §8 工件模板（入口指令/特性清单/进度/验证入口/命名注册/清洁清单/评估准则/架构规则），跳过已存在文件。
  • agent_discipline_audit：对照 §10 审计（CRITICAL 6 + 推荐抽样、五子系统 1-5 评分、最弱子系统、判定），只读。

Model Experience

模型可见内容：agent-discipline 提示段（约 1.2KB 文本）+ 两个工具的参数 schema 与结果。agent_discipline_audit 结果含 report 字段（文本报告）与结构化字段（verdict/totalScore/scores/weakest/failedCritical）。

方法论映射

插件元素规范章节
agent-discipline 提示段§1.3 生命周期、§1.4 不变式、§3.3 状态机、§13 反模式
agent_discipline_init§8 工件契约、§11.1 最小采纳
agent_discipline_audit§10 审计与度量
src/constants.ts + naming-registry.md§14.1 命名单点注册
scripts/check.sh + verify-feature.sh§4 验证子系统、§4.5 通过门
（形态 C 规划）ctx.features§3.3 状态机、§4.5 通过门、OBS-04

致谢与来源声明（开源致谢）

本插件实现的方法论（HARNESS-METHODOLOGY-SPEC.md，本仓库随附副本）提炼自开源课程 《Learn Harness Engineering》（Harness engineering beginner tutorial, from 0 to 1）：

按规范头部的来源声明（附录 A 亦逐条标注条款出处）：本规范仅从该课程逆向抽离逻辑骨架，不依赖该课程仓库的任何具体代码；本插件仓库同样只实现方法论（提示段 / 脚手架 / 审计），未复制该课程仓库的模板、脚本或文本。

上游许可证：该课程仓库以 MIT License 发布，派生与再分发在保留署名（版权声明 + 许可声明）的前提下被允许。本仓库基于"仅借鉴方法论思想、不复制其代码"的方式派生，已在本文与规范头部完成署名；若后续需要直接复用该课程的素材（模板/脚本/文本），除署名外还需在分发物中附带上游版权与许可声明（MIT 的必备条款），并请以仓库当时的 LICENSE 为准。

当前状态与演进路径（形态 B → 形态 C）

形态 B —— 当前已落地（文件 + 工具）

特性清单状态机为「仓库文件 + 工具/脚本纪律」实现：

  • 状态载体：feature_list.json（状态词表单点定义于 src/constants.ts；WIP=1，blocked 附解除条件）
  • 生成：agent_discipline_init 在目标仓库铺 12 个 §8 工件（入口指令/特性清单/进度/交接/命名注册/清洁清单/评估准则/架构规则/check.sh/verify-feature.sh/.gitignore）；已存在文件默认跳过
  • 审计：agent_discipline_audit 对照 §10 只读检查（CRITICAL 6 + 推荐抽样、五子系统 1-5 评分、最弱子系统、判定 pass/fail）
  • 通过门：scripts/verify-feature.sh <id> 跑全量验证后提示记录证据；status=passing 由流程置位
  • 强制方式：WIP=1、通过门、证据落盘是纪律约束（提示段 + 脚本），理论上可被绕过，靠审计抽查兜底

本仓库自证状态：F-001..F-006 全部 passing；node scripts/acceptance.mjs self 审计 100/100（CRITICAL 6/6、五子系统全 5/5、无缺项）。

形态 C —— 规划中（ctx.features 事件溯源服务）

把状态机服务化为 harness 能力缝，纪律变机器强制：

  • 服务：ctx.features（仿 goal/goal 模式）：create / update / transition / verify 操作 + CAS 修订号防并发覆盖
  • 折叠：feature/change 会话事件（声明 ignorable: true 以兼容 harness 生成的 known-event-types 读路径）+ 严格 fold——WIP=1 违约、passing 无证据、非法状态跳转即判 corrupt（AP-09/AP-10 结构性堵死，不再依赖自觉）
  • 工具：get_feature / update_feature / verify_feature（替代手改 JSON；verify 先跑该特性的 verification 步骤，成功才提交 complete）
  • 伴生：真实 invariant（每会话增量折叠 + internal/dispatch 预提交拦截）
  • 可选：featureStatus 投影单元 + GUI 特性看板
  • 待拍板：状态真源——推荐「会话日志为真源 + feature_list.json 作导出投影」（贴合 OBS-04 与 harness「模型可见⟺可日志化」语系）；若选「仓库文件为真源」，服务只做 CAS/锁包装、日志仅镜像
  • 触发条件：先用形态 B 完成 §11.2 的 S1-S3 对比实验（before/after 完成率），数据验证方法论有效后再上 C，避免在方法论未验证前先背服务复杂度

Known Limitations and Deferred Work

  • 特性清单状态机当前为形态 B（文件 + 工具纪律）；形态 C（ctx.features 事件溯源服务）为规划项，详见「当前状态与演进路径」一节。
  • agent_discipline_audit 的 CRITICAL/RECOMMENDED 检查为启发式文本/结构检查，不执行目标仓库的验证命令本身；锁文件候选未覆盖 go.sum/Maven/Gradle，C6 只认本地 check 脚本（CI-only 仓库会误报）。
  • invariant 伴生（agent-discipline/invariant）为可选装配：它 inject invariants 服务，而产品 bundle（dsh-base）不装载该服务；bundle 默认不插入该行，只有同时装载 @deepseek-ai/dsh-invariants 的组合（开发/测试树）才挂它。
  • 依赖版本范围 >=0.1.0-0 为预发布期宽松声明，harness 版本稳定后应收紧（D-006）。

开发

pnpm install
npm run check    # 静态 → 测试 → 构建（= scripts/check.sh）
node scripts/acceptance.mjs self   # 用 agent_discipline_audit 审计本仓库（F-004 自证）

链接本地 harness 检出（REAL-composition 测试与 dsh plugin add 需要）。注意用 link: 协议（file: 会触发 pnpm 解析被链接包的 workspace: 依赖而报 ERR_PNPM_WORKSPACE_PKG_NOT_FOUND，见 DECISIONS D-008）：

pnpm add -D link:../deepseek-harness/vendor/cordis `
          link:../deepseek-harness/packages/core/tools `
          link:../deepseek-harness/packages/core/system-prompt `
          link:../deepseek-harness/packages/runtime-diagnostics/invariants