agent-discipline

Readme

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

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

发布后：

```sh
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](https://github.com/9bow/learn-harness-engineering)（另见同课程副本 [walkinglabs/learn-harness-engineering](https://github.com/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 <id>` 跑全量验证后提示记录证据；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）

## Known Limitations and Deferred Work

- 特性清单状态机为形态 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）。

## 开发

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

```sh
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
```