Kraionix/deepseek-web-chat-harness

deepseek-web-chat-harness

一个用于在网页聊天会话中开发软件的最小化 agent harness，其中模型没有读取权限、没有写入权限、没有执行能力，也无法进行迭代。用户是唯一的 I/O 通道：他们从聊天中复制消息、运行命令，并将结果粘贴回去。

dwch（CLI）通过十六条命令弥合了这一差距，覆盖整个会话生命周期：引导上下文、应用任务的文件、验证结果、提交、按需读取文件、回滚、开启新阶段、关闭会话。它还能精确统计 token 数量（使用 DeepSeek 真实的 BPE 分词器），以便模型知道引导内容是否能放得下。

0.4.0 是什么

0.4.0 将 harness 从一份协议描述转变为一个 agent 工作区。

- state.toml 是唯一的事实来源。 没有 handoff.md，也没有单独的锁文件。冻结计划的哈希存放在 state 中。
- 引导内容分为六个有序层。 L0 元信息、L1 契约、L2 工具、L3 会话状态、L4 上下文、L5 当前任务、L6 笔记。L1 永远不会被截断。
- 计划是按 id 键控的任务列表，而不是编号步骤。AI 决定任务的粒度；契约解释了规则。
- 验证失败是一种工作状态。 verify 写入报告，递增 state.failure.count，并将一条简短提示放到剪贴板。dwch fix 为一个新的聊天生成修复引导。在连续三次失败后，两者中都会加入一条警告。
- 一份契约文档。 contract.md 承载块语法、计划/任务/偏差 schema、行为规则、工具类别，以及笔记与契约的规则。它永远不会被截断。

要求

- Python 3.11 或更新版本（使用 tomllib 和 StrEnum）。
- PATH 上有 git，用于 done、start、abandon、rollback、log，以及任何读取 HEAD 的命令。
- 可选：如果在 .harness/config.toml 中启用了默认 lint 检查，则需要 ruff。
- 在 dwch init 期间需要网络访问，以从 HuggingFace 下载分词器（约 8 MB）。之后，harness 可离线工作。

安装

pip install -e .

唯一的运行时依赖是 tokenizers（HuggingFace）。

对于开发，安装 dev 附加项：

pip install -e ".[dev]"

这会添加 ruff、pytest 和 pytest-cov。使用以下命令运行检查：

ruff check .
ruff format --check .
pytest -q

测试套件在临时目录中使用真实的文件系统和 git 适配器，并且从不接触网络。

快速开始

cd /path/to/your/project
dwch init
dwch health
dwch start "design the API"
dwch next

dwch next 会将引导内容复制到剪贴板。打开一个新的网页聊天，粘贴它，然后让模型生成设计产物和计划。对于每个任务：

dwch apply          # reads the message from the clipboard
dwch verify         # runs checks; hints to clipboard on failure
dwch done           # commits task {id}: applied and verified

当规划阶段中的最后一个任务完成时，计划就
自动哈希并冻结；当它在开发阶段完成时，计划位置会前进。

init 创建的内容

- .harness/config.toml — 用户可编辑的配置。
- .harness/state.toml — 阶段、计划位置、验证结果。
- .harness/contract.md — 契约，作为 L1 包含在每次引导中。
- .harness/data/deepseek_tokenizer.json — 下载的分词器。
- .harness/.gitignore — 仅忽略 data/。
- steps/.gitignore — 使 steps/ 自我忽略。

.harness/（除 data/ 外）和 steps/ 应与项目一起提交：它们是会话的可移植状态及其产物。分词器文件是本地缓存。

dwch init --force 会重新生成 harness 拥有且可以安全重建的文件：config.toml、contract.md 和分词器缓存。它不会触碰 state.toml 或 .harness/.gitignore。

十六个命令

| 命令 | 用途 |
|---|---|
| dwch init | 将 harness 安装到当前项目。 |
| dwch start "goal" | 开始一个阶段。除非指定 --kind，否则自动推断类型。 |
| dwch next | 组装当前任务的引导；复制到剪贴板。 |
| dwch apply | 解析块消息并执行其操作。 |
| dwch verify | 运行检查，写入报告，失败时给出提示。 |
| dwch done | 提交当前任务；在最后一个任务时关闭阶段。 |
| dwch fix | 为上次失败组装修复引导。 |
| dwch abandon | 将阶段标记为已放弃；保留文件。 |
| dwch status | 打印当前状态。 |
| dwch log [N] | 来自 git 的最近生命周期事件。 |
| dwch health | 环境和项目健全性检查。 |
| dwch read PATH | 将文件包裹在块标记中以便聊天使用。 |
| dwch map [ROOT] | 模块接口映射。 |
| dwch tree [ROOT] | 目录树。 |
| dwch count PATH | 统计文件或树中的 token 数。 |
| dwch rollback | 撤销上一次 task ... 提交。 |

生命周期

1. init 将 harness 写入 .harness/ 和 steps/。
2. start "goal" 开启一个规划阶段。
3. 每个任务：apply 写入文件，verify 检查。
4. done 提交。当计划在磁盘上且有效时，阶段关闭，计划被冻结。
5. start "goal"（现在推断为开发）开启开发阶段。
6. 每个任务：apply、verify、done。在最后一个任务时，阶段关闭。
7. start "goal" 为下一个版本开启一个新的规划阶段。

块消息格式

一条消息包含一个或多个块。存在三种块类型：file、delete 和 move。

file 块以 >> 开头，文件内容原样呈现，并以仅包含 >> 的一行结束。

delete 块以 >> 开头，主体为空（仅空白），并以结束标记结束。

move 块以 >> 开头，主体为空，并以结束标记结束。MOVE 恰好接受两个路径，以单个冒号分隔。
每条路径在写入前都会检查：相对路径、不含 ..、不含符号链接组件、不含保留名称。如果任务触及带有未提交更改的已跟踪文件，则会被拒绝。

引导层

L0  元信息        约 50 个 token      永不截断
L1  契约          约 1200 个 token    永不截断
L2  工具          约 200 个 token     永不截断
L3  会话状态      事实                永不截断
L4  上下文        可变                最先截断
L5  当前任务      可变                永不截断
L6  笔记          可变                第二个截断

截断顺序：先 L6，再 L4（笔记、要点、module_map、提交、报告）。L1 永不截断：契约始终能容纳。