FranklinZaneDurant/agent-discipline

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
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）：

- 课程仓库：9bow/learn-harness-engineering（另见同课程副本 walkinglabs/learn-harness-engineering）

按规范头部的来源声明（附录 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  跑全量验证后提示记录证据；status=passing 由流程置位
- 强制方式：WIP=1、通过门、证据落盘是纪律约束（提示段 + 脚本），理论上可被绕过，靠审计抽查兜底

本仓库自证状态：F-001..F-013 中 11 条 passing（F-007/F-008 not_started 挂起）；本仓库已完成形态 B→C 迁移（事件日志真源 .harness/features/events.jsonl + feature_list.json 投影）；node scripts/acceptance.mjs self 审计 100/100（CRITICAL 6/6、五子系统全 5/5、无缺项）。

形态 C —— 已落地（F-009..F-013，决策见 D-016/D-020）

把状态机服务化为 harness 能力缝，纪律变机器强制（四轮实验实证形态 B 验证门可被绕过，见 docs/experiments/s1-s3.md R3 结论）：

- 服务：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 特性看板
- 已拍板（D-016）：状态真源 = 会话日志为真源 + feature_list.json 作导出投影（OBS-04「模型可见⟺可日志化」）；状态词表不变（§3.3）
- web 多会话（D-020）：root 解析改为 per-call——resolveRoot(session?)（显式 config.root → 会话 cwd → 静态 workspaceRoot → process.cwd()）；工具 execute 携带 exec.agent?.session；audit/init 无 target 时按会话 root；get_feature 未找到返回 feature: null
- 分期：C-1 ctx.features 服务 + 严格 fold + 三工具（F-009）→ C-2 真实 invariant（F-010）→ C-3 看板/投影（F-011）→ 迁移+lossless 修复（F-012）→ web 会话 root 解析（F-013）

已知限制与待办工作

- 特性清单状态机为形态 C（ctx.features 事件溯源服务，F-009..F-013 已落地）；本仓库自身已完成 B→C 迁移，feature_list.json 为导出投影（手改会被真源折叠覆盖——用工具改）。
- agent_discipline_audit 的检查为启发式文本/结构检查（C5 覆盖多生态锁文件，C6 认本地脚本 / CI 工作流 / 常见命令别名），不执行目标仓库的验证命令本身。
- 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