Comparison

A · AGENTS.md · langgenius/dify B · AGENTS.md · langgenius/dify

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	10	2	0%
Commands	0	0	0	—
Section tags	2	3	2	29%

What each file covers

Sections

0 shared · 10 only in A · 2 only in B

− Agent V2 E2E
− Scope
− Execution tags
− Step organization
− World state
− Setup boundary
− Seed and fixture contract
− Runtime contract
− Build and Preview
− API contracts
+ Frontend Workflow
+ Package Contracts

Commands

neither file has any

Section tags

2 shared · 3 only in A · 2 only in B

− setup
− build
− api
+ test
+ code-style
testing-strategy
agent-behaviour

Line diff

+11 added−76 removed4 unchanged5.0% identical

langgenius/dify · e2e/features/agent-v2/AGENTS.md

@@ −1 @@

1# Agent V2 E2E

3This file scopes Agent v2 conventions under `features/agent-v2/` and its step definitions. Package-wide runner, locator, assertion, lifecycle, and cleanup rules live in `e2e/AGENTS.md`.

5## Scope

7Agent v2 scenarios use the `@agent-v2` capability tag. The E2E web environment enables Agent v2 through `NEXT_PUBLIC_ENABLE_AGENT_V2=true`.

9Cover user-observable Configure, Build draft, saved configuration, publish, Access Point, files, advanced settings, and runtime behavior. Do not keep readiness-only, unavailable, or permanently skipped scenarios. Use API setup for prerequisites, then assert visible behavior or a persisted public contract.

11## Execution tags

13- `@core` — stable, non-runtime user behavior.

14- `@prepared` — deterministic user behavior that requires the checked-in post-merge seed.

15- `@external-model` — execution can call a real model provider.

16- `@external-tool` — execution can call a real third-party tool provider.

17- `@agent-backend-runtime` — execution requires the standalone `dify-agent` server and shellctl sandbox.

18- `@web-app-runtime` — published Web app chat behavior.

19- `@service-api-runtime` — Backend service API chat behavior.

20- `@microphone` — isolated Chromium context with the fake audio fixture.

22Fixture tags such as `@stable-model`, `@tool-fixture`, `@knowledge-fixture`, `@full-config-agent`, `@tool-states-agent`, `@dual-retrieval-fixture`, and `@workflow-reference` describe the concrete seeded dependency. They do not change execution by themselves.

24Use `@external-model` and `@external-tool` only for runtime calls. A scenario that merely selects or persists an active model or tool is `@prepared`, not external.

26## Step organization

28Keep steps grouped by Agent product capability, such as configuration, Build draft, resource configuration, lifecycle, Access Point, and runtime behavior. Group by the domain action that owns the wording instead of mechanically pairing a step file with each feature file. Fixture-resolution steps should remain separate from behavior steps because they validate environment readiness rather than perform a user journey.

30Cucumber step definitions are globally registered. Do not duplicate step text across files.

32## World state

34Agent v2 state belongs under `world.agentBuilder`:

36- `fixtures` stores resolved models and seeded resources.

37- `accessPoint`, `configure`, `speechToText`, and `workflow` store per-scenario state.

39Do not add Agent v2 fields to the top level of `DifyWorld`. Store created Agent IDs, drive files, and tool credentials in the existing typed cleanup fields.

41## Setup boundary

43Use `a basic configured Agent v2 test agent has been created via API` for model-free, scenario-owned state. Use `a runnable Agent v2 test agent has been created via API` only after resolving the stable model fixture. Use the agent-decision variant only for autonomous planning or resource-selection behavior.

45API setup may create scenario-owned Agents, workflows, drafts, access toggles, and files. Register every created resource for cleanup. Do not mutate a fixed seeded fixture to make a scenario pass.

47Use `the Agent v2 configuration should be saved automatically` for Configure autosave. It waits for the visible publish-bar saved state; do not replace it with network-idle waits or internal store assertions.

49## Seed and fixture contract

51Seed tasks create or update environment-owned models, plugins, datasets, Agents, and workflows. `fixtures.steps.ts` resolves and validates those resources before a dependent behavior runs. Missing, inactive, unindexed, or drifted fixtures must throw and fail the scenario; never return `skipped`.

53`@prepared` scenarios are excluded from deterministic PR core. Post-merge runs:

55```bash

56E2E_START_AGENT_BACKEND=1 pnpm -C e2e e2e:post-merge

57```

59The command owns runtime setup, strict seed, Cucumber, and teardown. The strict seed must finish without blocked tasks. The concrete resource inventory and defaults belong to the seed profile and environment configuration rather than this guidance.

61Organize fixture helpers by the product resource or infrastructure capability they own, not by the feature file that happens to consume them. Keep runtime readiness adapters separate from Console resource fixtures, and keep all fixture state in the current `SeedContext` or scenario `DifyWorld` rather than module globals.

63Provider credentials belong to seed/admin setup, never to Cucumber steps.

65## Runtime contract

67Scenarios tagged `@agent-backend-runtime` must include `the Agent v2 runtime backend is available`. Run with `E2E_START_AGENT_BACKEND=1` to start `dify-agent` and shellctl, or point `E2E_AGENT_BACKEND_URL` / `AGENT_BACKEND_BASE_URL` to an existing server.

69Use the stable model for generic runtime behavior and the decision model only where model reasoning quality is part of the contract. Do not broaden external runtime tags to cover configuration-only scenarios.

71## Build and Preview

73Build mode covers Configure and Build draft persistence. Preview/Test Run covers real generation, runtime failure recovery, and tool or knowledge hits proven through replies. Do not add Preview scenarios until they are executable in the selected CI lane.

75## API contracts

77Import generated Console/Web/Service API types directly from `@dify/contracts/.../types.gen`. Keep local types only for E2E-owned state, fixture registry entries, helper inputs, and intentionally narrowed views. If the generated contract is incomplete, fix the backend schema and regenerate it instead of duplicating the response shape.

79Agent detail is the state owner for Agent scenarios. An Agent's backing app identifier may be used to route a shared app command, but it is not a substitute query model and must not become the final assertion source. Derive Agent Web app URLs and persisted Agent state from the generated Agent detail contract, then assert the user-visible Access Point or runtime result in the browser.

langgenius/dify · web/AGENTS.md

@@ +1 @@

1## Frontend Workflow

3- Read `docs/test.md` only for frontend test work and `docs/lint.md` only when running or changing static checks.

4- Use the repo-local `how-to-write-component` skill when implementation requires component ownership, state, data-flow, effect, or interaction-boundary decisions. Do not load it for test-only, copy-only, or styling-only changes.

5- Use `frontend-code-review` only for explicit frontend review or audit requests, including test reviews. Use `frontend-testing` when writing or changing Vitest or React Testing Library tests.

7## Package Contracts

9- User-facing strings must use `web/i18n/en-US/` keys. When adding or renaming a key, update every supported locale with the correct localized value.

10- For new backend calls and migrated surfaces, use generated `consoleQuery` / `consoleClient` APIs from `@/service/client`. Do not add handwritten REST helpers or DTO mirrors, mock-backed app state, or direct edits to generated contracts.

11- Prefer `@langgenius/dify-ui/*` primitives, data attributes, and design tokens. Preserve a visible focus indicator on the final focusable element.

12- Follow `docs/overlay.md` for overlay selection and migration. Migrate a legacy overlay only when the current behavior change actually involves that overlay boundary.

13- For custom SVG icons, follow `../packages/iconify-collections/README.md`; do not add generated React icons under `app/components/base/icons/src/`.

14- `docs/test.md` is the single source of truth for frontend automated-test policy. Skills may route and execute that policy but must not redefine it.

@@ −1 +1 @@

1−# Agent V2 E2E

1+## Frontend Workflow

3−This file scopes Agent v2 conventions under `features/agent-v2/` and its step definitions. Package-wide runner, locator, assertion, lifecycle, and cleanup rules live in `e2e/AGENTS.md`.

3+- Read `docs/test.md` only for frontend test work and `docs/lint.md` only when running or changing static checks.

4+- Use the repo-local `how-to-write-component` skill when implementation requires component ownership, state, data-flow, effect, or interaction-boundary decisions. Do not load it for test-only, copy-only, or styling-only changes.

5+- Use `frontend-code-review` only for explicit frontend review or audit requests, including test reviews. Use `frontend-testing` when writing or changing Vitest or React Testing Library tests.

5−## Scope

7+## Package Contracts

7−Agent v2 scenarios use the `@agent-v2` capability tag. The E2E web environment enables Agent v2 through `NEXT_PUBLIC_ENABLE_AGENT_V2=true`.

8−

9−Cover user-observable Configure, Build draft, saved configuration, publish, Access Point, files, advanced settings, and runtime behavior. Do not keep readiness-only, unavailable, or permanently skipped scenarios. Use API setup for prerequisites, then assert visible behavior or a persisted public contract.

10−

11−## Execution tags

12−

13−- `@core` — stable, non-runtime user behavior.

14−- `@prepared` — deterministic user behavior that requires the checked-in post-merge seed.

15−- `@external-model` — execution can call a real model provider.

16−- `@external-tool` — execution can call a real third-party tool provider.

17−- `@agent-backend-runtime` — execution requires the standalone `dify-agent` server and shellctl sandbox.

18−- `@web-app-runtime` — published Web app chat behavior.

19−- `@service-api-runtime` — Backend service API chat behavior.

20−- `@microphone` — isolated Chromium context with the fake audio fixture.

21−

22−Fixture tags such as `@stable-model`, `@tool-fixture`, `@knowledge-fixture`, `@full-config-agent`, `@tool-states-agent`, `@dual-retrieval-fixture`, and `@workflow-reference` describe the concrete seeded dependency. They do not change execution by themselves.

23−

24−Use `@external-model` and `@external-tool` only for runtime calls. A scenario that merely selects or persists an active model or tool is `@prepared`, not external.

25−

26−## Step organization

27−

28−Keep steps grouped by Agent product capability, such as configuration, Build draft, resource configuration, lifecycle, Access Point, and runtime behavior. Group by the domain action that owns the wording instead of mechanically pairing a step file with each feature file. Fixture-resolution steps should remain separate from behavior steps because they validate environment readiness rather than perform a user journey.

29−

30−Cucumber step definitions are globally registered. Do not duplicate step text across files.

31−

32−## World state

33−

34−Agent v2 state belongs under `world.agentBuilder`:

35−

36−- `fixtures` stores resolved models and seeded resources.

37−- `accessPoint`, `configure`, `speechToText`, and `workflow` store per-scenario state.

38−

39−Do not add Agent v2 fields to the top level of `DifyWorld`. Store created Agent IDs, drive files, and tool credentials in the existing typed cleanup fields.

40−

41−## Setup boundary

42−

43−Use `a basic configured Agent v2 test agent has been created via API` for model-free, scenario-owned state. Use `a runnable Agent v2 test agent has been created via API` only after resolving the stable model fixture. Use the agent-decision variant only for autonomous planning or resource-selection behavior.

44−

45−API setup may create scenario-owned Agents, workflows, drafts, access toggles, and files. Register every created resource for cleanup. Do not mutate a fixed seeded fixture to make a scenario pass.

46−

47−Use `the Agent v2 configuration should be saved automatically` for Configure autosave. It waits for the visible publish-bar saved state; do not replace it with network-idle waits or internal store assertions.

48−

49−## Seed and fixture contract

50−

51−Seed tasks create or update environment-owned models, plugins, datasets, Agents, and workflows. `fixtures.steps.ts` resolves and validates those resources before a dependent behavior runs. Missing, inactive, unindexed, or drifted fixtures must throw and fail the scenario; never return `skipped`.

52−

53−`@prepared` scenarios are excluded from deterministic PR core. Post-merge runs:

54−

55−```bash

56−E2E_START_AGENT_BACKEND=1 pnpm -C e2e e2e:post-merge

57−```

58−

59−The command owns runtime setup, strict seed, Cucumber, and teardown. The strict seed must finish without blocked tasks. The concrete resource inventory and defaults belong to the seed profile and environment configuration rather than this guidance.

60−

61−Organize fixture helpers by the product resource or infrastructure capability they own, not by the feature file that happens to consume them. Keep runtime readiness adapters separate from Console resource fixtures, and keep all fixture state in the current `SeedContext` or scenario `DifyWorld` rather than module globals.

62−

63−Provider credentials belong to seed/admin setup, never to Cucumber steps.

64−

65−## Runtime contract

66−

67−Scenarios tagged `@agent-backend-runtime` must include `the Agent v2 runtime backend is available`. Run with `E2E_START_AGENT_BACKEND=1` to start `dify-agent` and shellctl, or point `E2E_AGENT_BACKEND_URL` / `AGENT_BACKEND_BASE_URL` to an existing server.

68−

69−Use the stable model for generic runtime behavior and the decision model only where model reasoning quality is part of the contract. Do not broaden external runtime tags to cover configuration-only scenarios.

70−

71−## Build and Preview

72−

73−Build mode covers Configure and Build draft persistence. Preview/Test Run covers real generation, runtime failure recovery, and tool or knowledge hits proven through replies. Do not add Preview scenarios until they are executable in the selected CI lane.

74−

75−## API contracts

76−

77−Import generated Console/Web/Service API types directly from `@dify/contracts/.../types.gen`. Keep local types only for E2E-owned state, fixture registry entries, helper inputs, and intentionally narrowed views. If the generated contract is incomplete, fix the backend schema and regenerate it instead of duplicating the response shape.

78−

79−Agent detail is the state owner for Agent scenarios. An Agent's backing app identifier may be used to route a shared app command, but it is not a substitute query model and must not become the final assertion source. Derive Agent Web app URLs and persisted Agent state from the generated Agent detail contract, then assert the user-visible Access Point or runtime result in the browser.

9+- User-facing strings must use `web/i18n/en-US/` keys. When adding or renaming a key, update every supported locale with the correct localized value.

10+- For new backend calls and migrated surfaces, use generated `consoleQuery` / `consoleClient` APIs from `@/service/client`. Do not add handwritten REST helpers or DTO mirrors, mock-backed app state, or direct edits to generated contracts.

11+- Prefer `@langgenius/dify-ui/*` primitives, data attributes, and design tokens. Preserve a visible focus indicator on the final focusable element.

12+- Follow `docs/overlay.md` for overlay selection and migration. Migrate a legacy overlay only when the current behavior change actually involves that overlay boundary.

13+- For custom SVG icons, follow `../packages/iconify-collections/README.md`; do not add generated React icons under `app/components/base/icons/src/`.

14+- `docs/test.md` is the single source of truth for frontend automated-test policy. Skills may route and execute that policy but must not redefine it.

8015