大象金鱼设计评审 dryw/dsh-egm

dsh-egm

用大象做设计，用金鱼做评审。

安装 · 快速上手 · 工作原理 · 示例运行 · 许可

Google 的 Elephant-Goldfish Model 的独立社区移植版。与 Google 无隶属关系，也未获其背书。

dsh-egm 把 Elephant-Goldfish Model （EGM）作为原生插件带进 DeepSeek Harness。
上下文丰富的大象会话会访谈你，并起草设计文档；随后，全新的、零上下文的、只读的金鱼评审者会攻击这份文档，挑出歧义、隐藏假设和实现缺口；你来做取舍，并在写任何代码之前批准规格说明。

当一项改动需要先做设计决策时，就用它。如果只是小而清晰的 bug 修复，走你平常的编码工作流即可。

工作原理

| 角色 | 上下文 | 职责 |
| 大象 | 你的项目、需求和早先的决策 | 探索问题、辩论取舍、起草规格说明。 |
| 金鱼 | 文档及其引用的源材料，不含早先的对话 | 找出缺失的假设、含糊的需求和实现风险。 |
| 你 | 真正重要的目标与约束 | 解决取舍、批准设计、决定要构建什么。 |

上游的技能、人格和标准逐字照搬自固定版本的上游提交（见 ADAPTATIONS.md）；DeepSeek Harness 的机制放在一层很小的集成层里，宿主插件在注册每个技能时会把它前置到技能前面。评审者用插件的 egm_reviewer 工具启动，该工具让它们在随附的只读 egm-reviewer 智能体预设：能读文件、搜文件，没有写入、编辑、命令、用户提问、会话读取、委派这几类工具。在同一上下文里做评审，不算 Goldfish 评审。

环境要求

- DeepSeek Harness 0.2.1-rc.5 或更新，且属于 0.2.x 系列（engines.dsh）；记录的端到端运行用的是 0.2.1-rc.5。DSH 评估该范围时开启了 SemVer 预发布匹配。
- Node.js 22 或 24（CI 已测；engines.node 为 >=22 <25）。DSH 0.2.2 alpha 系列自带 node >=24.9 要求，跑那条 harness 线时请用 Node 24.9+。
- 一套 Harness 组合，包含技能注册表、工具注册表、子代理服务、智能体预设服务，以及进程内 spawn 子代理服务商。插件会安装 egm-reviewer 预设，以及选中该预设的 egm_reviewer 工具。
- 评审请用 egm_reviewer，不要用普通 subagent：普通子代理会继承父级的工具带，因此不是只读的，绝不能跑 Goldfish 评审。

安装

装进某个配置档——把 default 换成你启动时用的配置档：

from npm: shortest install, and the form the DSH Plugin Hub lists
dsh plugin --profile web add dsh-egm

from GitHub (before npm, or to pin a revision)
dsh plugin --profile web add github:dryw/dsh-egm#<sha>

from a local checkout
dsh plugin --profile web add /path/to/dsh-egm

from a packed tarball
pnpm pack
dsh plugin --profile web add ./dsh-egm-0.2.1.tgz

把 web 换成你启动时用的配置档。首次安装后重启 Harness，然后在 Settings → Plugins 下检查插件条目和它的图标。

快速上手

挑一个需要做设计决策的功能，比如 webhook 投递：投递失败时该怎么办？同一个事件到达两次又该怎么办？

1. 探索想法 —— 输入 /egm-brainstorm Add webhook delivery to this project.，讨论需求与取舍。全新的评审者会质疑方案，达成一致的方向会存成 concepts_brief.md。
2. 起草规格 —— /egm-draft 把 brief 变成一份分节的设计文档，放在 docs/designs/ 下，每写完一节就暂停，等你在聊天里反馈。
3. 评审草稿 —— /egm-review docs/designs/webhook-delivery/DESIGN.md 跑 Goldfish 协议：拉远视角、朴素读者理解、设计批评、中间拉远、实现就绪度，最后做一轮综合。用 /egm-resolve 选择要处理哪些发现。
4. 人工评审，然后实现 —— 把设计送人工评审，再让智能体按批准的计划开工。

每个技能都能单独用，不必走完整套流程。

看一次完整运行

仓库里的 examples/e2e-verification/ 是一次针对小型示例项目的记录运行：从概念 brief 开始 /egm-brainstorm、/egm-draft 产出的设计，以及 /egm-review 的全部五份 Goldfish 阶段报告，连同 harness 环境和 reviewer 激活 id，都记录在 E2E-VERIFICATION.md 里。这些内容只存在于仓库中，不在 npm tarball 内。

技能

| 技能 | 调用方式 | 用途 |
| Brainstorm | /egm-brainstorm | 检验想法，写出概念简报。 |
| Draft | /egm-draft | 把简报或已有笔记整理成设计文档。 |
| Review | /egm-review | 用全新的只读 Goldfish 智能体分五个阶段评审设计。 |
| Review loop | /egm-review-loop | 针对特定评审任务，运行一组配置好的评审者。 |
| Resolve | /egm-resolve | 逐条处理评审发现的问题，就改动达成一致。 |
| Bootstrap | /egm-bootstrap | 为已有代码库创建或更新 README 和代码库上下文。 |
| Drift report | /egm-drift-report | 对比已提交的设计文档与当前源代码。 |

七个技能全部由用户主动调用，与上游 EGM 完全一致：智能体不会自行决定开启设计会话或昂贵的评审。输入技能的 /egm-… 名称即可启动；上游指令和 DeepSeek Harness 集成说明会在该轮注入。

项目结构

设计产物放在仓库里时，EGM 效果最好：

path/to/project
├── .agents/skills/<project>-elephant/SKILL.md # optional: project context loader
└── docs/
└── designs/
├── SITEMAP.md # index of design artifacts
└── <feature>/DESIGN.md # design specification

设计文档、概念简报和评审报告都是纯 Markdown，写进你的工作目录，因此可以像其他改动一样在 pull request 里评审。项目上下文技能由 DeepSeek Harness 在 <repo>/.agents/skills/ 下发现。

如果想让 EGM 的工作产物不落在仓库根目录、同时设计仍放在 docs/designs/，在项目的 AGENTS.md 里加上这一行，并把该文件夹加入 gitignore：

EGM artifact directory: .dev/docs

包结构

dsh-egm/
├── index.js # package entry; re-exports the integration layer
├── skills-host.js # DSH integration layer: registers skills + injects the preamble
├── reviewer-host.js # egm_reviewer tool: fresh child in the read-only preset
├── reviewer-tools.js # preset tool guard: read/search allowlist, deny everything else
├── cordis.patch.yml # bundle patch: host rows + the egm-reviewer agent preset
├── ADAPTER-NOTES.md # adapter notes for direct SKILL.md reads
├── E2E-VERIFICATION.md # recorded brainstorm -> draft -> review verification run
├── examples/ # repository-only: the recorded end-to-end run
├── skills/ # seven upstream SKILL.md files, verbatim
├── agents/ # nine upstream reviewer/orchestrator personas, verbatim
├── resources/ # 上游标准、执行说明和 README，逐字保留 ├── locale/ # 插件显示元数据（en、zh） └── icon.svg

适配器模块是本包唯一新增的代码。随包附带的目录树与上游在锁定提交处逐字节一致；upstream.lock.json 记录该提交和每个文件的哈希。

开发

node --test # 52 checks: manifest, engines, vendored content, adapter, reviewer isolation, upstream parity
node scripts/check-upstream.mjs # reports whether upstream EGM moved since the pinned commit

上游支持标准的端到端验证记录见 E2E-VERIFICATION.md。

改动随包内容后（仅在你适配新的上游提交时），用 node scripts/check-upstream.mjs --update-lock 刷新锁文件。安装插件后若要继续迭代，重启 Harness（或切换插件行），让宿主插件重新读取随包文件。

与上游保持同步

dsh-egm 逐字附带上游 EGM，只增加一层 DeepSeek Harness 集成。upstream.lock.json 锁定上游提交（403d8881d62022490637d740657b33f01e321ea8）和每个随包文件的 SHA-256。

scripts/check-upstream.mjs 把该锁定与上游默认分支比对，报告哪些随包文件有变动：

node scripts/check-upstream.mjs # clean = exit 0, drift = exit 1
node scripts/check-upstream.mjs --json # machine-readable drift report
node scripts/check-upstream.mjs --update-lock # after refreshing the vendored files

每周运行的 GitHub Actions 工作流（.github/workflows/upstream-sync.yml）会执行这项检查，并新建或刷新一个标题为 "Upstream EGM changed: re-vendor bundled skills" 的 issue。test/upstream-parity.test.js 把上游自己的行为场景套件当作内容一致性测试，所以刷新时若丢掉上游可见的需求，node --test 就会失败。scripts/README.md 有完整流程。

许可与署名

本项目按 Apache License, Version 2.0 授权。技能、评审人设、标准和模板附带自 google/elephant-goldfish-model，Copyright Google LLC，按 Apache License, Version 2.0 授权；见 NOTICE 和 ADAPTATIONS.md。DeepSeek Harness 适配器、打包和评审预设是本包的原创工作。

本项目不是 Google 官方支持的产品。