前言¶
在 DeepSeek Harness（DSH）里跑本地 Agent 时，常见现象是同一条命令反复失败、同一文件被多次读取、单次工具输出过大，或用户多次纠偏后 Agent 仍沿原路走。这些模式往往散在已保存会话里，事后很难系统复盘，也不容易沉淀成可审核的项目规则。
Waymark（dsh-waymark）是面向 DSH 的工作流类插件：从本地已保存会话中定位上述模式，给出带轮次与 seq 证据的报告，并产出 AGENTS.md 候选规则。当前为 0.2.0-alpha.1 开发者预览，支持会话复盘与显式开启的实时提醒；自动拦截尚未实现。维护者为 ZhSM27，源码与说明见 GitHub 仓库，社区目录页为 skillhub.cn/plugins/ZhSM27/dsh-waymark。DSH 生态强调「一切皆插件」；社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
这是什么¶
Waymark 的定位是：本地、有证据依据的 Agent 工作流诊断。它不调用模型做复盘，不把报告再塞回模型上下文；也不重写被分析的日志，不自动编辑 AGENTS.md 或宿主配置。真实会话经宿主只读查询处理，插件侧不上传网络、不调用 LLM、无遥测。插件以当前 dsh 进程权限运行，安装前应自行查看源码与 MIT 许可证。
README 写明仅适配并验证 dsh 0.2.1-rc.5；dsh 升级可能破坏接口，使用前建议阅读仓库内 已知限制。
核心功能¶
会话复盘（/waymark retro）¶
对已保存会话做离线分析，输出人类可读报告，或 --json / --markdown / --export 等形式。命令直接返回结果；dsh 会保存 command/run、command/done 及结果文本，这不等于宿主运行时磁盘零写入。
分析规则与边界如下（摘自 README）：
| 规则 | 判定要点 |
|---|---|
| R1 重复失败 | 同工具、相同/近似参数、相同错误的连续失败，默认三次起报 |
| R2 重复读取 | 同文件、相同范围的成功读取默认三次；成功 write/edit 后计数重置 |
| R3 巨型输出 | 结果体积严格大于 4000 token（可配置），并列出 Top 5 |
| R4 用户纠偏 | 用户消息命中词表且其后仍有工具活动；低置信度，只展示前 80 个 Unicode 字符 |
报告含轮次证据、工具成败、有限形式的验证命令观察（仅识别简单 npm/pnpm/yarn/bun 的 test/build/lint/typecheck），以及最多三条去重的项目级规则提案。内容 token 缺失时用 Unicode 字符数 / 4 粗估；重复体积只计第一次之后的调用及输出，不能当作账单节省或当前窗口占比。
生产命令已接入宿主 workspaceRegistry 归档准入：当前会话、显式 id、last 与导出均排除归档或未登记会话；last 仅选择与当前会话 cwd 完全匹配 的最近顶层已保存会话，排除当前会话与 subagent。
实时观察与提醒（实验性，/waymark guard）¶
默认 off，需按当前会话显式开启。observe 只计数；warn 对 R1/R3 提供提示，不拒绝或自动重试工具。默认 delivery=model，提示随宿主下一次模型请求发送；delivery=user 则提示留在本地 status，不进入模型上下文。状态与反馈仅在内存，重启不保留。PTC 子调用和继承会话暂不覆盖。
安装与启用¶
需要 Node.js 24.11+（README 实测 24.22.2）及匹配版本的 dsh。安装须选择实际运行的 profile；官方验收使用隔离 web profile，未验证 Desktop/TUI 的 UI 呈现。
Alpha 预发布包安装示例（README）：
dsh plugin --profile web add -w ./dsh-waymark-0.2.0-alpha.1.tgz
npm 发布待维护者完成账号 2FA；发布完成后可用 registry 安装：
dsh plugin --profile web add -w dsh-waymark@alpha
安装后重启对应 profile。卸载：
dsh plugin --profile web remove -w dsh-waymark
随后重启。-w 为当前 pnpm 9.15.0 在 dsh 生成的 profile workspace 中所需的显式根标志；若 CLI 版本不同，按实际行为核实。
典型用法¶
复盘命令¶
/waymark retro
/waymark retro last
/waymark retro <session-id>
/waymark retro <session-id> --json
/waymark retro <session-id> --markdown
/waymark retro <session-id> --export review.md
省略 id 时分析当前会话。--export 将报告写入接收命令的工作目录下 .waymark/reports/<filename>；三种输出模式互斥。导出只接受简单 .md 文件名，拒绝覆盖与路径穿越。完整报告可能含本地路径及用户纠偏片段，分享前需自行脱敏。
Guard 命令（实验性）¶
/waymark guard status
/waymark guard mode observe
/waymark guard mode warn
/waymark guard delivery user
/waymark guard delivery model
/waymark guard feedback 1 helpful
/waymark guard mode off
配置¶
在 profile 的 cordis.patch.yml 中覆盖 waymark 行的 config，重启生效。dsh patch 会替换整行 config，修改时需保留需要的全部选项：
- id: waymark
config:
failLoopMin: 3
rereadMin: 3
similarityThreshold: 0.8
bigOutputTokens: 4000
topN: 5
volatileArgumentKeys: []
temporaryPathPrefixes: []
correctionKeywords: ['不对', '停', '重来', '撤销', '搞错', 'revert', 'undo', 'stop', 'wrong']
实时提醒可在同一 config 下增加 live 块，例如 failWarnMin、bigOutputTokens、maxPerSession、maxChars；未知键会报错。字段含义与约束见 README 配置表。
适用场景与注意¶
适合：希望在本地复盘 Agent 会话、把重复失败/重复读/大输出/纠偏模式整理成可审核规则提案的 DSH 用户；需要在同一会话内可选开启 R1/R3 轻量提醒（且不替代人工判断）时，可试用 guard。
务必注意：
- Alpha 阶段，接口与 dsh 版本绑定；自动拦截、暂停/恢复、上下文压缩等不在此版本。
- 插件不捆绑执行其他第三方插件；宿主及其他插件的网络行为不属于 Waymark。
- R3 大输出不自动等同于浪费；R4 可能是正常改需求。
- 误报、漏报与兼容性建议通过 GitHub Issues 反馈，注明版本与脱敏复现，勿上传原始会话或密钥。
仓库提供 pnpm demo 运行合成失败循环演示，便于理解 R1 等行为，无需真实会话。
结尾¶
Waymark 把「事后复盘」和「可选实时提醒」放在同一插件里，强调证据与本地处理，适合作为 DSH 工作流调优的起点。目录页：https://www.skillhub.cn/plugins/ZhSM27/dsh-waymark；源码与文档：https://github.com/ZhSM27/dsh-waymark。
