EGM Ask:只读上下文帮助与后续步骤引导¶
- 作者: Smit Parmar(@smituparmar01)
- 状态: 草案
- 日期: 2026-10-28
- Issue: #175
概述¶
EGM Ask Skill(/egm-ask <question>)回答用户关于 EGM 以及用户在 EGM 工作流中所处位置的问题。它检查磁盘上存在哪些 EGM 工件(例如 concepts_brief.md、design_draft.md 以及评审报告),读取 EGM 技能描述和 EGM harness 文档,并在聊天中回复一个简短答案和至多三个建议的后续步骤。
该技能仅供参考。它不会写入文件、运行其他技能,或更改进行中技能的状态。
Issue #175 提议使用名称 /ask-egm。维护者在该 issue 上选择了 /egm-ask,因此该命令遵循其他所有 EGM 技能使用的 egm- 前缀。
问题¶
-
空白画布:新用户看过
/egm-brainstorm或/egm-review的演示,但不知道输入什么来开始,不知道哪个技能适合他们的任务,也不知道技能期望什么输入。 -
中断后迷失方向:这些技能可以按任意顺序使用(参见 getting_started.md)。在一个会话内,每个技能完成时都会指明下一步:egm-brainstorm 的交接提供
/egm-draft,egm-draft 推荐egm-review,而 egm-review 的阶段门槛会指明下一个阶段。但这种交接在开始新会话、或用户稍后返回某个项目时就不存在了。用户随后会看到磁盘上的工件文件,但不知道是哪个技能写入了它们,也不知道下一步应该运行哪个技能。 -
无锚点的故障排查:当某些事情失败时(评审者无法读取其 persona 文件、某个技能未出现在自动补全中、某个子代理工具不可用),文档记录的修复方法在 harnesses.md 或 harness 指南(claude.md 或 codex.md)中。EGM 技能设置了
disable-model-invocation: true,因此它们不会出现在自动技能发现中(claude.md)。因此,在普通聊天中,模型看不到 EGM 技能描述,也不知道哪份文档包含修复方法。
目标与非目标¶
范围内目标¶
- 添加用户调用的
/egm-ask <question>技能。 - 根据磁盘上的工件检测当前工作流阶段,并以用户 harness 期望的命令形式建议下一个要运行的技能。
- 根据用户陈述的意图推荐技能,使用每个已安装
skills/*/SKILL.md的实时description字段,因此新技能无需编辑egm-ask即可出现在推荐中。 - 通过引用包含修复方法的 EGM 文档来回答故障排查问题。
范围外非目标¶
- 运行技能、生成子代理、加载技能或编辑文件。该技能只读取文件并在聊天中回复。
- 取代用于任务工作的普通提示。
/egm-ask回答有关 EGM 的问题;它不进行起草、评审或修复。 - 回答、恢复或处理另一个技能待批准的步骤。
- 与 EGM 无关的通用编程帮助。对于这类问题,技能会说明自己只涵盖 EGM,然后停止。
- 在多次调用之间保留自身状态或记忆。
- 运行诸如
git status之类的 shell 命令。阶段检测仅使用工件文件。
系统架构与工作流程¶
sequenceDiagram
autonumber
actor User
participant Ask as egm-ask Skill
participant Workspace as Working Directory / EGM artifact directory
participant Plugin as Plugin root: skills/, docs/
User->>Ask: /egm-ask <question>
Ask->>Ask: Classify question (next step, skill choice, troubleshooting, out of scope)
Ask->>Workspace: List known EGM artifact names (read-only)
Ask->>Plugin: Read stage table, skill descriptions, harness docs (read-only)
Ask->>Ask: Detect workflow stage and compose answer
Ask->>User: Short answer + up to 3 next steps (harness command form)技能读取的位置¶
skills/egm-ask/SKILL.md 以与其他 EGM 技能相同的两行 harness 序言开头:在 Claude Code 或 Cowork 中,它读取 docs/claude.md;在 Codex 或 ChatGPT Work 中,它读取 docs/codex.md。该序言解决了两件事:
- 路径。 本设计中的
docs/和skills/路径相对于已安装的插件根目录解析,绝不对应于用户的项目——项目中可能有同名的文件夹。工件和docs/designs/则相对于用户的工作区解析。 - Harness 指南。 序言中提到的指南就是下文所使用的“harness 指南”。没有指南的 harness(例如 Antigravity 或 omp)只使用 harnesses.md。
第 1 步:对问题进行分类¶
技能将问题分为四种类型之一。该类型决定要读取哪些文件,因此技能不会为每个问题读取所有文档。
| 类型 | 示例 | 读取的文件 |
|---|---|---|
| 下一步 | “我现在该做什么?” | 工作区中的工件名称和阶段表(第 2 步) |
| 技能选择 | “哪个技能会根据代码检查我的 README?” 也包括 EGM 任务请求,例如“修复我的草稿”:指明做该工作的技能,但不做任何修改。 | 仅 skills/*/SKILL.md frontmatter |
| 故障排查 | “评审者说它无法读取自己的 persona。” | docs/harnesses.md 和 harness 指南 |
| 范围外 | “如何修复这个 TypeScript 错误?” | 无。回复 /egm-ask 只涵盖 EGM。 |
如果用户没有给出问题,技能会将其视为下一步问题。
第 2 步:检测工作流阶段¶
技能在与 egm-draft 的 intake(egm-draft 第 1 步)相同的位置、以相同的顺序查找 EGM 工件:工作目录、harness 的工件目录(参见 harnesses.md 中的“Artifact Directory”),然后是 scratch/。用户提示或代理指令文件中的 EGM artifact directory: <path> 行会替换工作目录,正如 claude.md 所描述的那样。
该技能按文件名检查文件。它从工作区读取的唯一文件内容是 goldfish_review_report.md 的前几行:Status: resolved 行和 **Target:** 行。只有当该目标正是用户所指的设计时,它才会建议解决后的下一步。
文件的存在只是阶段提示,并非工作流已完成的证据。审查报告可能不完整,也可能是早前运行的遗留物。如果这些文件无法确定当前目标所处的阶段,该技能会将阶段报告为未知,列出它看到的工件,并询问用户指的是哪次运行或哪个目标。
下面的阶段表列出了每个工件由哪个技能写入。其规范副本位于 getting_started.md 的“What to run next”一节中,由实现 PR 添加,/egm-ask 在运行时从那里读取。阅读文档的人会看到同一张表,重命名的工件只需在一处更新。
| 发现的工件(由谁写入) | 检测到的阶段 | 建议的下一步 |
|---|---|---|
无,且没有 docs/designs/*.md |
未开始 | 有新想法时运行 egm-brainstorm,或运行 egm-bootstrap 记录现有代码库 |
concepts_brief.md(egm-brainstorm) |
构思完成 | egm-draft,它会将 concepts_brief.md 作为其首个输入 |
design_draft.md(egm-draft),没有匹配的 docs/designs/<feature>.md |
草稿进行中 | 继续运行 egm-draft,直到它写出 docs/designs/<feature>.md |
docs/designs/<feature>.md,没有审查报告 |
可以审查 | egm-review docs/designs/<feature>.md |
zoom_out_report.md、comprehension_report.md、critic_report.md、intermediate_zoom_out_report.md、implementation_readiness_report.md 或 consolidated_review_report.md(egm-review) |
审查已开始;完成情况未知 | 询问该目标的审查是否已完成。如果已完成,对其发现运行 egm-resolve。如果未完成,继续待处理的审查 |
goldfish_review_report.md(egm-resolve),没有 Status: resolved |
解决进行中 | 返回等待回答的解决步骤,或重新运行 egm-resolve |
goldfish_review_report.md(带 Status: resolved) |
发现已解决 | 对设计进行人工审查(getting_started.md,步骤 4);只有在下述检查全部通过后才能实施 |
在建议实施之前。 已检入的设计或已解决的报告本身并不足以证明可以实施。该技能只有在以下各项全部成立时才会建议实施:
- 目标已知。 用户已指名该设计,或者已解决报告的
**Target:**行恰好指名一个docs/designs/<feature>.md,并且用户加以确认。如果多个设计可能匹配,该技能会询问用户指的是哪一个。 - 该目标没有待处理的审查。 如果存在审查报告,用户需确认审查已完成,并且最近对话中没有审查或解决步骤正在等待回答。
- 没有待处理的批准。 该技能无法看到人工对设计的批准,因此它会询问设计是否已获批准。在用户确认之前,它会建议人工审查步骤,而非实施。
如果任一项检查失败,该技能会转而建议待处理的步骤。它不会自行回答或恢复该步骤(见规则)。
各行按工作流顺序排列。当多行匹配时,该技能会指出最新匹配的阶段,并列出它看到的每个工件,以便用户纠正。如果用户的问题指名了不同的目标,则该目标优先于该表。
步骤 3:撰写回答¶
回复使用简明英语,并遵循以下形式:
**Where you are:** <one sentence, naming the artifacts seen>
**Answer:** <2-6 sentences>
**Next steps:**
1. `<command>`: <why>
2. ...
**Source:** <relative path of each doc or SKILL.md used>
- 最多三个下一步骤,总计最多 20 行。EGM 的工件优先原则(见 architecture.md)会将长输出排除在聊天之外;需要更多篇幅的帮助回答会指向已包含该内容的文档。
- 命令使用 harness 指南给出的形式,例如 Claude Code 中的
/egm:egm-draft。如果没有 harness 指南,该技能会显示裸命令,并重复 README 中关于前缀的说明。 - 展示的每个 EGM 命令都必须属于已安装的技能。宿主命令和设置(例如
claude plugin enable egm@egm)只有在引用自所引用文档时才能出现。该技能不得凭空编造命令或标志。 - 如果文档未涵盖某个故障排查问题,该技能会如实说明,并建议提交 issue,而不是猜测。
规则:待处理门禁与只读¶
待处理门禁。 用户可能在其他技能等待回答时运行 /egm-ask,例如在 egm-resolve 的解决门禁处。该门禁接受自由文本,包括自定义指令。/egm-ask 不会回答、恢复或处理该待处理的门禁。它的只读规则到其回复为止。用户直接回答该待处理的门禁。
只读。 该技能在主对话中运行,因为下一步骤和故障排查的回答依赖于用户最近的对话轮次以及他们刚刚看到的错误文本。全新上下文的 Goldfish 审查者(见 architecture.md)两者都看不到。在 Claude Code 中,EGM 技能在主上下文中运行,只有子代理适配器会获得受限的工具列表(claude.md)。因此,只读规则由该技能的说明和行为测试场景(见 Testing)来强制实施。与其他 EGM 技能一样,该技能设置了 disable-model-invocation: true,因此它只在用户请求时运行。
Alternatives Considered¶
| 备选方案 | 拒绝原因 |
|---|---|
| 在普通聊天中提问(不新增技能) | 目前可行,但 EGM 技能不在自动技能发现范围内,因此模型看不到它们的描述、工件名称或阶段顺序,除非这些内容已经在对话中。 |
| 改进现有的技能交接 | 值得作为后续工作去做:egm-brainstorm 和 egm-draft 会打印它们的下一条命令,但不带 harness 前缀。它无助于新会话、技能选择或故障排查,而这些都是本设计所针对的场景。 |
| 由只读子代理回答问题 | 用工具强制了只读,但下一步操作和故障排查的答案需要用户最近几轮对话和错误文本。只将部分问题类型路由到子代理,会增加第二条执行路径,并在每个 harness 中新增一个适配器,对于 20 行的回复来说成本过高。 |
| 仅在文档中增加“下一步运行什么”章节 | 已采纳为数据来源(步骤 2),但静态章节无法看到用户拥有哪些产物。 |
| 把答案写入产物文件 | 帮助答案很短。每个问题一个文件会增加杂乱,用户还得打开它。 |
| 模型可调用的技能 | 模型会在任何“我该怎么做”类的消息上触发它,这与常规任务提示冲突(这是一个明确列出的非目标)。 |
按 issue 中所述命名为 /ask-egm |
维护者在 #175 中选择了 /egm-ask。它与当前每个技能的 egm- 前缀相匹配。 |
风险与缓解措施¶
- 检测到错误的阶段。 文件的存在可能造成误导,例如早期运行遗留的报告。缓解措施:技能将文件视为提示,列出它看到的每个产物,并在无法确定时报告未知阶段,而不是猜测(步骤 2)。
- 阶段表与技能脱节。 缓解措施:在 getting_started.md 中维护一张唯一权威表,每一行标注对应的写作技能。
- 只读性仅靠指令强制。 缓解措施:行为场景 6、7、8 检查该技能不会进行任何编辑,也不会选择任何门禁选项。
- 工作区文件中可能被植入指令。 当存在写入工具时,审阅报告中的文本可能被当作指令读取。缓解措施:技能只从工作区读取文件名,以及一份报告中的
Status:和**Target:**行。它读取的所有散文内容均来自插件自有的文档和 frontmatter。 - 主线程中的上下文成本。 缓解措施:每种问题类型只读取其列出的文件,答案限制为 20 行。
实现文件与引用的组件¶
实现 PR 所更改的文件¶
| 路径 | 创建/修改 | 变更 |
|---|---|---|
skills/egm-ask/SKILL.md |
创建 | harness 前言、四种问题类型、阶段检测、答案格式,以及待定门禁和只读规则。正文必须保持在 tests/unit/test_skill_load_limits.py 检查的 24,000 字节限制以内。 |
skills/egm-ask/TEST.md |
创建 | 针对每种问题类型和阶段的手动验证步骤。 |
skills/egm-ask/test_scenarios.yaml |
创建 | 来自下文“测试”部分的行为场景。 |
skills/egm-ask/agents/openai.yaml |
创建 | 显示名称和图标元数据,与其他技能保持一致。 |
skills/egm-ask/assets/icon.svg |
创建 | 技能图标,遵循 skill_icons.md。 |
docs/getting_started.md |
修改 | 添加“下一步运行什么”阶段表和 /egm-ask 条目。 |
scripts/pack_plugin.py |
修改 | 将 egm-ask 添加到技能列表。 |
tests/unit/test_harnesses.py |
修改 | 将 egm-ask 添加到 EXPECTED_SKILLS。 |
tests/unit/test_packaging.py |
修改 | 将 skills/egm-ask/SKILL.md 添加到预期打包文件。 |
README.md |
修改 | 列出 /egm-ask 及其他命令。 |
docs/designs/architecture.md |
修改 | 将 egm-ask 添加到技能层列表。 |
docs/designs/skill_icons.md |
修改 | 更新技能数量。 |
site/src/components/Skills.astro, site/src/components/SkillIcon.astro |
修改 | 添加技能卡片和图标。 |
引用的文档(运行时读取)¶
- getting_started.md:“下一步运行什么”阶段表。
- harnesses.md、claude.md、codex.md:故障排查和命令形式。
skills/*/SKILL.md的 frontmatter:用于建议的技能名称和描述。
测试¶
skills/egm-ask/test_scenarios.yaml 使用与其他技能测试套件相同的场景格式,并至少覆盖:
- 空工作区且没有问题:建议
egm-brainstorm或egm-bootstrap。 - 仅存在
concepts_brief.md:建议egm-draft。 - 当前目标存在审阅报告:在建议
egm-resolve之前询问该审阅是否已完成,并且不会绕过待定门禁。 - 存在
critic_report.md且用户表示审阅未完成:建议继续egm-review,而不是重新开始。 - 同时存在
concepts_brief.md和docs/designs/x.md:指出最新阶段并列出这两个文件。 - “请替我修改草稿”:不进行任何编辑,并指出负责该工作的技能。
- 无关的编程问题:回复说它只覆盖 EGM。
- 在
egm-resolve门禁待定时被调用:回答问题,不进行任何编辑,也不选择任何门禁选项。 - “哪个技能会将我的设计与代码进行比较?”:推荐
egm-drift-report并引用其SKILL.md。 - Persona 读取失败:引用
docs/claude.md。 - 已解决的报告和两个已检入的设计,而用户没有指明哪一个:要求用户确认设计(报告中的
**Target:**,如果不明确,则确认是哪一个)以及该设计是否已获批准;不建议实施。
静态检查:pytest tests/unit(frontmatter、场景覆盖率、技能正文大小限制、打包和链接完整性)。
参考资料¶
- Issue #175:添加 /ask-egm 命令,提供上下文帮助和指导。
- Dave Rensin, Elephants, Goldfish, and the New Golden Age of Software Engineering (Medium, 2026).
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 el/elephant-goldfish-model