Polish Lynx Agent open-source presentation

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,41 +1,45 @@
 ---
 name: Bug report
-about: Report a runtime, benchmark, or build problem
-title: "[Bug] "
+about: Report a runtime, benchmark, or Android automation failure
+title: "[Bug]: "
 labels: bug
 assignees: ""
 ---
 
-## Summary
+## What happened?
 
-Describe the problem in one or two sentences.
+Describe the task, expected result, and actual result.
 
-## Environment
+## Device and environment
 
 - Device:
 - Android version:
-- Build variant:
-- Model provider:
+- Lynx Agent commit:
+- Text model:
+- Vision model:
 
-## Reproduction
+## Task instruction
 
-1. 
-2. 
-3. 
+```text
 
-## Expected
-
-What should have happened?
-
-## Actual
-
-What actually happened?
+```
 
 ## Evidence
 
-Include logs, traces, screenshots, or benchmark output if you can share them
-without leaking sensitive data.
+Attach a sanitized benchmark report, trace excerpt, screenshot, or screen
+recording if possible.
+
+## Failure category
 
-## Notes
+Choose the closest category:
 
-Anything else that may help narrow the failure mode.
+- app launch or app resolution
+- wrong click or wrong coordinate
+- typing/input grounding
+- repeated no-progress action
+- false completion
+- verifier false reject
+- safety confirmation
+- model provider/API failure
+- benchmark or trace parsing
+- other

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,29 +1,24 @@
 ---
 name: Feature request
-about: Suggest a runtime, benchmark, or developer-experience improvement
-title: "[Feature] "
+about: Suggest a general Lynx Agent capability improvement
+title: "[Feature]: "
 labels: enhancement
 assignees: ""
 ---
 
-## Problem
+## Capability
 
-What limitation are you hitting today?
+What should Lynx Agent become better at?
 
-## Proposal
+## Why it matters
 
-What would you like to change?
+Explain the real Android task or benchmark failure this would improve.
 
-## Why This Helps
+## Suggested approach
 
-Explain how this would improve completion, recovery, verification, benchmark
-coverage, or developer ergonomics.
+Describe the smallest useful change, if you have one.
 
-## Risks
+## Validation
 
-Could this introduce app-specific hardcoding, false-success risk, or prompt
-noise?
-
-## Extra Context
-
-Add examples, screenshots, or related references if useful.
+How should we know this improved real task completion rather than one app or one
+benchmark case?

.github/pull_request_template.md

@@ -1,19 +1,18 @@
-## Summary
+## What changed
 
-Describe the change briefly.
 
 ## Why
 
-Explain which problem this addresses and how it relates to completion,
-verification, recovery, or observability.
 
 ## Validation
 
-- [ ] `./gradlew test`
+- [ ] `./gradlew test --continue`
 - [ ] `./gradlew assembleDebug`
-- [ ] benchmark or trace check when relevant
+- [ ] Device benchmark or trace review, if runtime behavior changed
 
-## Risks
+## Risk check
 
-Call out anything not yet proven, especially around false success, app-specific
-behavior, or benchmark-only gains.
+- [ ] Does not add app-specific runtime hardcoding
+- [ ] Does not weaken completion verification
+- [ ] Does not bypass safety confirmation
+- [ ] Does not expose sensitive benchmark artifacts

.github/workflows/android-ci.yml

@@ -0,0 +1,27 @@
+name: Android CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+
+      - name: Set up Android SDK
+        uses: android-actions/setup-android@v3
+
+      - name: Run unit tests
+        run: ./gradlew test --continue

.gitignore

@@ -23,9 +23,6 @@ bin/
 gen/
 out/
 
-# Gradle wrapper
-!gradle/wrapper/gradle-wrapper.jar
-
 # Maven
 target/
 pom.xml.tag
@@ -66,3 +63,6 @@ Thumbs.db
 *.tar.gz
 *.rar
 artifacts/benchmarks/
+
+# Keep Gradle wrapper executable for clean clones
+!gradle/wrapper/gradle-wrapper.jar

CONTRIBUTING.md

@@ -1,75 +1,67 @@
-# Contributing to Lynx Agent
+# Contributing
 
-Thanks for taking an interest in Lynx Agent.
+Thanks for your interest in Lynx Agent.
 
-This project is still an engineering preview, so the goal is not to merge every
-idea quickly. The goal is to keep the runtime moving toward higher real task
-completion rate without drifting into app-specific patches or benchmark tricks.
+This project is focused on improving general Android agent capability: task
+completion, recovery, verification, safety, observation quality, traceability,
+and benchmark reliability.
 
-## Before You Start
+## Good Contributions
 
-Please read these first:
+- Improve screenshot, OCR, UI tree, or screen-state observation.
+- Improve executor prompts, action validation, tool results, or recovery.
+- Reduce false completion or repeated no-progress actions.
+- Add benchmark scenarios that expose general agent weaknesses.
+- Add tests for verifier, completion gate, safety, coordinate handling, or
+  world-state transitions.
+- Improve documentation, setup, demo scripts, or failure reports.
 
-1. [README.md](README.md)
-2. [docs/architecture-design.md](docs/architecture-design.md)
-3. [docs/agent-validation-platform.md](docs/agent-validation-platform.md)
-4. [AGENTS.md](AGENTS.md)
+## Contributions To Avoid
 
-These documents explain the main contracts of the project:
+- Hardcoded click scripts for one app or one page.
+- Special cases for a specific button label, contact, product, setting, or
+  benchmark scenario inside runtime code.
+- Fixed coordinates tuned to one device.
+- Runtime shortcuts that jump directly to an app subpage.
+- Large UI tree or OCR dumps in the default model prompt without benchmark
+  evidence that they improve completion rate.
 
-1. completion-first over demo-first
-2. evidence-based completion over model self-report
-3. vision-first minimal context over XML-heavy default prompts
-4. generic Android capability over app-specific runtime hardcoding
+Scenario knowledge belongs in benchmark definitions, fixtures, oracle logic, or
+manual review notes.
 
-## Good First Contributions
+## Development
 
-Early contributions are most helpful in these areas:
+Build the debug APK:
 
-1. documentation clarity
-2. benchmark coverage and benchmark hygiene
-3. trace readability and debugging ergonomics
-4. primitive tool result structure
-5. verifier and recovery tests
-6. provider integration that keeps runtime behavior generic
-
-## What We Usually Do Not Want
-
-These changes are usually out of scope for the main runtime:
-
-1. app-specific fixed click paths
-2. hardcoded page labels, package-specific shortcuts, or benchmark-only prompts
-3. direct success shortcuts that bypass `VerifierAgent + CompletionGate`
-4. large context additions without benchmark evidence
-5. changes that improve one scenario by making the runtime less general
-
-If a benchmark reveals a real generic weakness, fix the generic weakness and
-leave scenario knowledge in benchmarks, fixtures, or oracle logic.
+```bash
+./gradlew assembleDebug
+```
 
-## Development Flow
+Run unit tests:
 
-1. Open an issue first for large changes.
-2. Keep patches small and focused.
-3. Explain which architecture goal the change improves.
-4. Mention what you tested.
-5. Call out risks or unverified assumptions.
+```bash
+./gradlew test --continue
+```
 
-Useful local commands:
+Run a single benchmark scenario:
 
 ```bash
-./gradlew test
-./gradlew assembleDebug
-tools/run_device_benchmark.sh --scenario-id smoke --instruction "open settings" --launch
-tools/run_benchmark_suite.sh benchmarks/suites/completion_smoke.tsv
+tools/run_device_benchmark.sh \
+  --scenario-id settings_wlan \
+  --instruction "打开设置并进入 WLAN 页面" \
+  --duration 150 \
+  --launch
 ```
 
-## Pull Request Notes
+## Pull Requests
 
-Please include:
+Please keep pull requests focused. Include:
 
-1. what changed
-2. why it helps completion, recovery, verification, or observability
-3. what tests or benchmark checks you ran
-4. what is still not proven
+- the problem being fixed
+- the runtime area changed
+- tests or benchmark evidence
+- any risk to completion verification, safety, or user confirmation
 
-Small, well-explained PRs are much easier to review than broad rewrites.
+If a change touches `VerifierAgent`, `CompletionGate`, `HumanAssistanceGate`,
+`WorldState`, safety checks, recovery budgets, or benchmark acceptance logic,
+call that out clearly in the PR description.