weiqingy commented on code in PR #918:
URL: https://github.com/apache/flink-agents/pull/918#discussion_r3609348272
##########
dev/agent-skills/flink-agents-dev/references/local-development.md:
##########
@@ -0,0 +1,506 @@
+# Project Generation and MiniCluster Validation
+
+## Contents
+
+- [Delivery Contract](#delivery-contract)
+- [Resolve and Confirm a Compatible Version
Set](#resolve-and-confirm-a-compatible-version-set)
+- [Generate a Java Maven Project](#generate-a-java-maven-project)
+- [Generate a Python Project and Select an
Environment](#generate-a-python-project-and-select-an-environment)
+- [Handle Local Plaintext Credentials](#handle-local-plaintext-credentials)
+- [Scaffold Runtime Skill Configuration](#scaffold-runtime-skill-configuration)
+- [Connect the Agent through
RemoteExecutionEnvironment](#connect-the-agent-through-remoteexecutionenvironment)
+- [Submit to a Local MiniCluster](#submit-to-a-local-minicluster)
+
+## Delivery Contract
+
+Do not stop after generating an Agent class or YAML definition. For a new
+application, also generate and verify its executable project:
+
+- Java: a complete Maven project with `pom.xml`, sources, Resources, a Flink
job
+ entry point, and a configured local run command;
+- Python: source files, pinned dependency input, `.gitignore`, a user-selected
+ existing Python environment or project-local `.venv`, installed
dependencies, and
+ a Flink job entry point;
+- both: a `StreamExecutionEnvironment`, the public Agents factory backed by
+ `RemoteExecutionEnvironment`, a keyed DataStream/Table, a sink, and an
+ `AgentsExecutionEnvironment.execute(...)` call.
+
+For existing applications, preserve their package manager and layout, but
provide
+the same runnable path. "Local" changes only the Flink deployment target: the
job
+is still built through `RemoteExecutionEnvironment` and submitted to a
MiniCluster.
+Never substitute the removed local Agents APIs.
+
+## Resolve and Confirm a Compatible Version Set
+
+For an existing application, resolve versions from its lockfile, Maven
metadata,
+installed package, or `FLINK_HOME`, preserve them, and report what was
detected. For
+a new application, do not create dependency files, a virtual environment, or
source
+files until all sequential gates are complete. Versions are the first gate; do
not
+choose or mention the implementation language before it.
+
+Offer choices rather than asking an open-ended version question. The
publication
+snapshot, mirrored from `tools/install.sh`, is:
+
+| Component | Installer-supported versions | New-project choices | Recommended
choice |
+|---|---|---|---|
+| Flink Agents | `0.3.0`, `0.2.1`, `0.2.0`, `0.1.1`, `0.1.0` | `0.3.0`,
`0.2.1`, `0.1.1` | `0.3.0` |
+| Flink | `2.2.1`, `2.1.3`, `2.0.2`, `1.20.5` | `2.2.1`, `2.1.3`, `2.0.2`,
`1.20.5` | `2.2.1` |
+
+For a new project, offer only the highest supported patch in each Flink Agents
+minor line. Older patches such as `0.2.0` and `0.1.0` remain valid when an
existing
+project pins them or the user explicitly requests one, but they add no useful
+choice to the default new-project menu.
+
+Render the Flink Agents row through the interaction adapter selected by
`SKILL.md`.
+If the native tool limits the number of options, use the adapter's hierarchy or
+paging rule so every version remains selectable. First satisfy any mode
prerequisite
+defined by that adapter. If the native tool remains unavailable afterward, use
a
+numbered fallback instead of asking the user to type a version string:
+
+```text
+Select the Flink Agents version:
+1. 0.3.0 (Recommended)
+2. 0.2.1
+3. 0.1.1
+
+Reply with 1, 2, or 3.
+```
+
+After that answer, present the compatible Flink versions through a separate
native
+selector or numbered list. Never put both version decisions into one
multi-select
+control: they are ordered single-choice gates because the first filters the
second.
+
+Flink Agents `0.1.x` supports Flink `1.20` only in this snapshot. Flink Agents
+`0.2.x` and `0.3.x` publish artifacts for all listed Flink minors. Use a
+target-version installer, release metadata, or compatibility matrix when
available
+because it overrides this bundled snapshot.
+
+Present the recommended choice first, but do not select it because the user is
+silent. Ask only for the Flink Agents version and wait. Then show only the
Flink
+versions compatible with that answer and wait again. These questions must not
also
+propose YAML/Python/Java APIs, Python/JDK versions, model providers, Resource
+configuration, Skill loading, business backends, or mocks. Summarize only the
+confirmed Flink Agents/Flink pair before moving to the API gate.
+
+Do not describe a bundled recommendation as "latest", "preview", or preferable
to
+an unlisted Flink release unless target-version release metadata was actually
+checked and that comparison is needed for the user's request. The installer
choices
+are a compatibility menu, not permission to make broader release claims.
+
+After the API and implementation language are confirmed, resolve the language
+runtime separately. When the design first requires Python, inspect available
+interpreters and environments and keep only versions compatible with the
already
+selected Flink pair; do not assume Python 3.12. In this snapshot, Python 3.12
+requires Flink Agents `0.3+` and Flink `2.1+`; older combinations require
Python
Review Comment:
The version table just above (lines 44–47) mirrors `tools/install.sh`, which
makes it lovely and easy for a coding agent to confirm. This 3.12 → Flink
Agents `0.3+` / Flink `2.1+` pairing is the one concrete version constraint
here I couldn't trace back to an in-tree source — `pyproject.toml` pins
`requires-python = ">=3.10,<3.13"` but doesn't seem to gate 3.12 on those
component versions. Is it coming from the per-release wheel matrix? If so,
might it be worth either pointing a coding agent at where it can confirm this,
or leaning on the same escape hatch the snapshot note at 73–76 already uses
("use a target-version installer, release metadata, or compatibility matrix ...
because it overrides this bundled snapshot")? You'd know the release matrix far
better than I can reconstruct from the tree — mostly curious whether there's a
source a coding agent could check.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
