showcase-demo-debugging

展示 Demo 工作

从这里开始

在更改代码或 fixture 之前，请先阅读当前的本地指南：

• showcase/README.md
• showcase/RUNBOOK.md
• showcase/DEBUGGING.md
• 在添加或更改 demo 时，阅读 showcase/INTEGRATION-CHECKLIST.md

使用 showcase/bin/showcase 进行展示相关操作。除非 CLI 缺少所需操作，并且你解释了原因，否则不要使用原始的 docker compose、原始的 docker build 或直接运行 harness 命令。

当其他会话可能正在使用 showcase 时，优先使用隔离运行：

showcase/bin/showcase test <slug> --d5 --verbose --cycle --isolate

基线规则

• 将 showcase demo 代码保持在 CopilotKit v2 API 上。
• 将 showcase/integrations/langgraph-python 视为 D5 行为的黄金标准。对于相同的 demo 行为、提示词、pill、工具流、UI 断言和 D5 覆盖，其他每个 showcase demo 都必须与 langgraph-python 一一对应，除非用户明确批准已记录的差异。
• 对于新增或迁移的 demo，在实现前将依赖版本与 showcase/integrations/langgraph-python 进行比较，并保持相同或更新的版本，除非用户明确批准已记录的差异。
• 仅在相关时，将 Google ADK 作为额外上下文使用。
• 对于任何 D5 单元格或迁移，先让每个 pill 都能对真实 Agent 工作，然后实现 fixture，再运行本地 D5 验证直到通过。
• 迁移 demo 的 E2E 测试应与 langgraph-python 的行为和断言匹配，除非用户明确批准差异。
• 在 demo 完成之前，demo 中的每个 pill 都必须通过由 aimock 支持的 D5 回放进行演练和覆盖。
• 在实现新功能时，点击 demo 中的每个建议 pill 并验证其可用，然后再宣布该功能完成。
• 在 aimock 回放中，当 pill 被点击一次、连续点击五次、在另一个 pill 之后点击，以及在中间插入其他 pill 之后再次点击时，fixture 行为都必须稳定。对于同一个由 fixture 支持的提示词，无论之前的 pill 顺序如何，同一个 pill 都应产生相同的预期输出。
• 在说修复或 demo 已完成之前，先在本地验证。
• 不要为了满足测试而削弱 demo。demo 行为就是产品。

新增 Showcase 项

在创建新的 showcase 项、添加新的 demo 单元格、添加建议 pill 或实现新的 showcase 功能时，使用此工作流。适用与调试相同的规则：

1. 阅读上面列出的当前 showcase 指南。
2. 找到匹配的 langgraph-python demo，或先定义新的 langgraph-python 行为。
3. 将依赖与 showcase/integrations/langgraph-python 进行比较；对于共享的 demo/运行时/测试依赖，使用相同或更新的版本，除非有已记录的不兼容性要求另行处理。
4. 使用 CopilotKit v2 API 实现 demo 行为，并让每个建议 pill 都能对真实 Agent 工作。
5. 如果任何本地步骤要与真实大模型通信，请通过 aimock 记录模式运行，以便捕获 fixture。
6. 将记录转换为确定性的源 D5 fixture。
7. 在 aimock 回放下验证每个 pill 单次、重复和交错点击的情况。
8. 为每个 pill 添加或更新 D5 E2E 覆盖。
9. 在标记新 showcase 项完成之前，运行本地验证。

不要在 UI 看起来工作一次后就把新的 showcase 工作视为完成。新 demo 需要与 bug 修复相同的 fixture 一致性、回放稳定性和回归覆盖。

Bug 排查循环

1. 复现之前，先阅读相关 demo、D5 脚本和现有 fixtures。
2. 判断该流程使用的是 aimock 还是真实大模型：
   • 检查 showcase/docker-compose.local.yml、provider base URL 和 showcase/harness/fixtures/d5/*.json。
   • 检查匹配的 fixture 是否存在于 showcase/aimock/d5-all.json 或 showcase/harness/fixtures/d5/ 下的源 fixtures 中。
   • 运行后使用 showcase/bin/showcase logs aimock --grep "fixture|match|NO match|404"。
3. 如果该流程应该使用 aimock，用以下命令复现：

   showcase/bin/showcase up aimock <slug>
   showcase/bin/showcase test <slug> --d5 --verbose --cycle
   

4. 如果 fixtures 看起来可疑，先在本地运行 aimock 并检查 fixture 匹配，再编辑应用代码。
5. 如果该流程绕过 aimock 直接与真实大模型通信，则始终在本地为该步骤以 record 模式运行 aimock。不要运行未录制的真实大模型本地流程。使用录制得到的 fixture 输出，让后续 replay 具备确定性，并达到由 aimock 支撑的 D5 覆盖率。
6. 一旦定位到根因并实现了修复，请用户点击走完确切的流程并确认其正常工作，然后再锁定回归覆盖。
7. 用户确认后，添加或更新 D5 fixtures 和回归 E2E 覆盖，确保该问题不会悄无声息地回归。
8. 对于用户点击过程中报告的每一个额外问题，重复同样的循环：复现、根因、用户验证、fixture、回归测试。

环境设置

如果需要真实大模型 provider，检查 showcase/.env，但不要打印密钥值。如果所需的 key 缺失或为空：

1. 确保 showcase/.env 存在，必要时从 showcase/.env.example 复制。
2. 为用户打开它：

   code --new-window "F:\projects\cpk\CopilotKit\showcase\.env"
   

3. 请用户粘贴所需的 key，通常是 OPENAI_API_KEY；仅当目标 provider 需要时才使用 ANTHROPIC_API_KEY 或 GOOGLE_API_KEY。
4. 请用户在文件保存后告知你。不要让他们把密钥粘贴到聊天中。

如果 env/config 更改会影响容器，使用：

showcase/bin/showcase recreate <slug>

仅在依赖、Dockerfile 或非挂载源码发生更改时才使用 rebuild。

交互式复现

如果用户说他们会手动复现，启动所需的本地服务，并请他们点击走完流程，完成后告知你，以便你检查日志和录制下的 fixtures。

如果用户要求你按说明复现，在 headed Playwright 或 Browser MCP 中运行 showcase demo，交互直到 bug 复现，并保留确切的步骤、提示词文本、选中的 pill、URL 和观察到的失败。

在有用时使用 headed D5：

showcase/bin/showcase test <slug> --d5 --headed --verbose --cycle

录制 Fixtures

对于新 demo 或任何与真实大模型通信的本地步骤，以 record 模式运行 aimock，使该交互变为由 fixture 支撑。这是强制要求：真实 provider 流量应当产生可稍后 replay 的 fixtures。

docker compose -f showcase/docker-compose.local.yml -f showcase/docker-compose.record.yml --profile infra up -d aimock <slug>

这个 record 模式的 compose override 是对常规"使用 showcase/bin/showcase"规则的公认例外，直到 showcase CLI 拥有一个一等公民的 record 命令。

然后手动或使用 D5 harness 驱动 demo 中的每个 pill。录制的调用会落在 showcase/aimock/d5-recorded/ 下。

录制之后：

1. 将录制的输出转换或移动到 showcase/harness/fixtures/d5/ 下的源 D5 fixtures。
2. 确保 showcase/aimock/d5-all.json 包含当前文档/脚本所需的 replay fixture 路径。
3. 运行 fixture 校验。
4. 仅使用 aimock replay 重新运行 demo。
5. 为每个 pill 添加或更新 D5 E2E 覆盖。

使用现有的 D5 recorder helper 时，先阅读 showcase/scripts/record-d5-fixtures.mjs。它记录了当前针对多轮 fixtures 的 recorder 补丁要求。如果 aimock 无法录制所需的响应形态，不要在 demo 中伪造该行为；与用户讨论最小的上游 aimock 变更。

Pill 重放稳定性

在添加功能、更改 fixture 或调试任何由 fixture 支持的演示时，请在 aimock 重放下验证建议 pill 的稳定性：

1. 在全新会话中分别点击每个建议 pill 一次，确认 UI 和助手输出符合预期。
2. 反复点击每个建议 pill，对于会触发 LLM/工具行为的 pill，至少连续点击五次。
3. 依次点击多个不同的 pill，然后返回此前点击过的某个 pill，确认它仍能产生相同的预期输出。
4. 检查 aimock 日志，查找 fixture 未命中、错误匹配、重复命中陈旧匹配或依赖顺序的匹配。
5. 如果输出依赖于点击顺序、先前的 pill，或同一 pill 被点击的次数，请修复 fixture 匹配。

Fixture 必须保持一致且可重放。当稳定的 userMessage、toolCallId、hasToolResult 或更具体的 fixture 键能够让重放在重复和交错的 pill 点击中保持确定性时，不要依赖 turnIndex 或对话历史。

Fixture 规则

• 源 fixture 位于 showcase/harness/fixtures/d5/*.json。
• 打包的运行时 fixture 位于 showcase/aimock/d5-all.json。
• 当存在稳定的工具 id 时，使用 toolCallId 进行多轮消歧；仅当确切的工具 id 不可用或有意在运行时变化时，才使用 hasToolResult。
• 除非没有任何稳定的请求属性能够区分轮次，并且已记录这种差异，否则不要在新 fixture 中引入 turnIndex。
• 优先使用稳定、具体的 userMessage、systemMessage、toolCallId 和工具面匹配。避免使用可能抢占另一个 pill 的 fixture 的宽泛兜底匹配。
• 编辑 fixture 后，验证并重新创建 aimock：

  showcase/bin/showcase fixtures validate
  showcase/bin/showcase recreate aimock
  showcase/bin/showcase test <slug> --d5 --verbose --cycle
  

• 如果添加新的 fixture 文件，请在当前文档要求的情况下更新 compose 挂载和 aimock Dockerfile 复制规则。

回归测试

在用户确认修复后的流程可正常工作后，添加回归覆盖：

• 为确切的提示词/pill/工具流程添加或更新 D5 fixture。
• 添加一个在原始 bug 上失败、在修复后通过的 E2E 回归测试。
• 覆盖演示中的每个 pill，包括仅为暴露边缘情况而存在的 pill。
• 当涉及 fixture 时，加入重复和交错的 pill 点击覆盖，使 fixture 不能仅在首次点击时通过。
• 对于等效的演示，与 langgraph-python D5 的断言风格和行为保持 1:1 一致。
• 将用户报告的每个独立演示问题都作为单独覆盖的行为，除非单个测试自然覆盖了共同的根因。
• 先运行范围较窄的相关 D5 测试，当更改涉及共享 fixture、harness 逻辑、运行时行为或多个演示时，再运行更广泛的 showcase 验证。

Aimock 上游缺口

如果 aimock 缺少准确重放 LLM 提供商响应所需的功能：

1. 通过录制的提供商响应或日志确认该缺口。
2. 避免添加掩盖不匹配的演示变通方案。
3. 询问用户，对于你来说，提交上游 PR 的最简便方式是什么。
4. 如果获得批准，进行最小的 aimock 更改，并使用以下命令重新构建：

   showcase/bin/showcase aimock-rebuild --from <aimock-source-path>
   

5. 使用重新构建的 aimock 重新运行 showcase D5 流程。

完成标准

在最终状态之前：

• 已具体说明根本原因。
• 受影响的本地 showcase 演示正在运行，并且其本地 URL 已在概览中提供，以便用户手动测试修复后的流程。
• 当要求手动验证时，用户已确认修复后的 UI 流程。
• Fixtures 是确定性的并且已验证。
• 任何真实的 LLM 本地运行都通过 aimock record 模式路由，并生成了可回放的 fixtures。
• 受影响演示中的每个 pill 都具有 aimock 支持的 D5 覆盖。
• Aimock fixture 回放在单次、重复和交错的 suggestion-pill 点击下均稳定。
• 非 langgraph-python 演示的行为与 langgraph-python 1:1 匹配，或者具有明确记录且经用户批准的差异。
• 相关的 D5/e2e 回归已存在并在本地通过。
• 任何 aimock 限制要么已在上游修复，要么已链接到上游 PR/计划，要么被明确标记为阻塞项。