From e0552262244e50a8eecedd80b7d876ed86e40270 Mon Sep 17 00:00:00 2001 From: Qunmi Date: Wed, 2 Sep 2026 22:27:42 +0800 Subject: [PATCH] Remove unused documentation files --- docs/README.md | 16 - ...ough_overflow_menu_on_ntp.example.fsq.yaml | 151 ------ docs/launch/introducing-fsq.md | 32 -- docs/launch/introducing-fsq.zh-CN.md | 32 -- .../2026-08-13-next-generation-cli-design.md | 504 ------------------ ...t-generation-cli-team-discussion-design.md | 305 ----------- pyproject.toml | 2 - tests/test_distribution_contract.py | 2 - 8 files changed, 1044 deletions(-) delete mode 100644 docs/README.md delete mode 100644 docs/examples/complete_all_menu_workflow_through_overflow_menu_on_ntp.example.fsq.yaml delete mode 100644 docs/launch/introducing-fsq.md delete mode 100644 docs/launch/introducing-fsq.zh-CN.md delete mode 100644 docs/superpowers/specs/2026-08-13-next-generation-cli-design.md delete mode 100644 docs/superpowers/specs/2026-08-13-next-generation-cli-team-discussion-design.md diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 82b179b..0000000 --- a/docs/README.md +++ /dev/null @@ -1,16 +0,0 @@ -# FSQ Documentation - -- [Getting started](getting-started.md) -- [中文快速开始](getting-started.zh-CN.md) -- [CLI reference](cli-reference.md) -- [Case format](case-format.md) -- [Platform prerequisites](platform-prerequisites.md) -- [Support and stability](support-and-stability.md) -- [v0.1.0 release notes](releases/v0.1.0.md) -- [v0.1.0 GitHub Release copy](releases/v0.1.0-github-release.md) -- [Autoplay demo page](demo.html) -- [English launch article](launch/introducing-fsq.md) -- [中文发布文章](launch/introducing-fsq.zh-CN.md) -- [Release media plan](media/README.md) - -Current product behavior and implementation architecture are defined by the repository's root and module `SPEC.md` files. diff --git a/docs/examples/complete_all_menu_workflow_through_overflow_menu_on_ntp.example.fsq.yaml b/docs/examples/complete_all_menu_workflow_through_overflow_menu_on_ntp.example.fsq.yaml deleted file mode 100644 index 36f9056..0000000 --- a/docs/examples/complete_all_menu_workflow_through_overflow_menu_on_ntp.example.fsq.yaml +++ /dev/null @@ -1,151 +0,0 @@ -schemaVersion: fsq.ai-test/v1 -name: "Example: Complete all menu workflow through overflow menu on NTP" -description: Example strict FSQ case based on a successful dynamic recording. Observation tools such as ui_tree are intentionally not emitted as commands. -platform: android -appId: com.microsoft.emmx -tags: -- example -- android -- overflow-menu -- strict-replay -properties: - example: - based_on: complete_all_menu_workflow_through_overflow_menu_on_ntp - source: dynamic-recording - notes: - - Observation snapshots are evidence/audit artifacts, not replay commands. - - Locators are trimmed to stable fields instead of preserving null recording fields. -onCaseStart: -- runCase: cases/fsq-testcases/android/bottom_bar/access_downloads_through_overflow_menu.fsq.yaml -onCaseComplete: -- runShell: echo case complete ---- -- launchApp: - app_id: com.microsoft.emmx -- tapOn: - target: Add New tab - locator: - resourceId: com.microsoft.emmx:id/edge_bottom_bar_plus_button -- assertVisible: - target: New Tab Page account menu - locator: - accessibilityId: Account menu - optional: false -- tapOn: - target: Browser menu - locator: - resourceId: com.microsoft.emmx:id/overflow_button_bottom -- swipe: - start: - x: 800 - y: 2350 - end: - x: 200 - y: 2350 - reference_screen_size: - width: 1264 - height: 2744 - duration: 1000 -- tapOn: - target: All Menu - locator: - text: All menu - className: android.widget.TextView - xpath: //android.widget.TextView[@text='All menu'] -- assertVisible: - target: the All Menu panel should open - locator: - xpath: //android.widget.TextView[@text='All Menu'] - optional: false -- tapOn: - target: Edit - locator: - resourceId: com.microsoft.emmx:id/toolbar_button_edit_done -- assertVisible: - target: The All menu edit mode should be opened - locator: - xpath: //android.widget.TextView[@text='Edit Menu'] - optional: false -- assert: - element: - xpath: //android.widget.FrameLayout[@resource-id='com.microsoft.emmx:id/grid_item_view'][1] - enabled: false - optional: false -- tapOn: - target: Drop - locator: - xpath: //android.widget.TextView[@text='Drop']/.. -- tapOn: - target: Done - locator: - text: Done - className: android.widget.Button - xpath: //android.widget.Button[@text='Done'] -- tapOn: - target: Back button on All menu panel - locator: - resourceId: com.microsoft.emmx:id/back_button -- tapOn: - target: Browser menu - locator: - resourceId: com.microsoft.emmx:id/overflow_button_bottom -- swipe: - start: - x: 800 - y: 2350 - end: - x: 200 - y: 2350 - reference_screen_size: - width: 1264 - height: 2744 - duration: 1000 -- assertNotVisible: - target: Drop menu item - locator: - xpath: //android.widget.TextView[@text='Drop'] - optional: false -- tapOn: - target: All Menu - locator: - text: All menu - className: android.widget.TextView - xpath: //android.widget.TextView[@text='All menu'] -- tapOn: - target: Edit - locator: - resourceId: com.microsoft.emmx:id/toolbar_button_edit_done -- tapOn: - target: Drop - locator: - xpath: //android.widget.TextView[@text='Drop']/.. -- tapOn: - target: Done - locator: - resourceId: com.microsoft.emmx:id/toolbar_button_edit_done -- tapOn: - target: Back button on All menu panel - locator: - resourceId: com.microsoft.emmx:id/back_button -- tapOn: - target: Browser menu - locator: - resourceId: com.microsoft.emmx:id/overflow_button_bottom -- swipe: - start: - x: 800 - y: 2350 - end: - x: 200 - y: 2350 - reference_screen_size: - width: 1264 - height: 2744 - duration: 1000 -- assertVisible: - target: Drop menu item - locator: - xpath: //android.widget.TextView[@text='Drop'] - optional: false -- killApp: - app_id: com.microsoft.emmx diff --git a/docs/launch/introducing-fsq.md b/docs/launch/introducing-fsq.md deleted file mode 100644 index 94c423c..0000000 --- a/docs/launch/introducing-fsq.md +++ /dev/null @@ -1,32 +0,0 @@ -# Introducing FSQ: Evidence-First AI UI Automation You Can Replay - -AI can operate a user interface, but “the agent said it finished” is not enough for a trustworthy test. Teams need to inspect what happened and repeat successful behavior without asking a model to rediscover every step. - -FSQ is an open-source, evidence-first agent harness built for that workflow. - -## From a goal to inspectable facts - -Give FSQ a user-visible goal. During execution it records screenshots, normalized UI snapshots, ordered events, metadata, and a report in one local Run. Verification consumes evidence rather than relying only on the agent's narrative. - -When exploration succeeds, FSQ can produce a reviewable YAML Case from the actual actions. That Case can be replayed through the same platform Harness to produce fresh regression evidence. - -## One model across four platforms - -FSQ uses Playwright for Web, uiautomator2 for Android, pywinauto for Windows, and Appium Mac2 for macOS. These libraries perform platform interaction. FSQ adds a shared Case format, lifecycle, evidence model, verification, Run history, readiness diagnostics, and local Control Plane. - -## Local-first operation - -Workspace files and Run evidence stay local. Provider configuration is stored under the user's FSQ configuration directory and shared by the CLI and Control Plane. Model-backed operations use the configured GitHub Copilot or Azure OpenAI Provider. - -## Try the alpha - -```bash -python -m pip install fsq-agent -mkdir fsq-web-demo && cd fsq-web-demo -fsq init --platform web --browser-channel chrome -fsq doctor -``` - -The v0.1.0 release is alpha software. It is an invitation to evaluate the model, inspect the architecture, report gaps, and help define a dependable path to 1.0. - -Read the [getting-started guide](../getting-started.md), use the root and module `SPEC.md` files for implementation contracts, and join through the [contribution guide](../../CONTRIBUTING.md). diff --git a/docs/launch/introducing-fsq.zh-CN.md b/docs/launch/introducing-fsq.zh-CN.md deleted file mode 100644 index c1056c8..0000000 --- a/docs/launch/introducing-fsq.zh-CN.md +++ /dev/null @@ -1,32 +0,0 @@ -# 介绍 FSQ：可检查、可重放的证据优先 AI UI 自动化 - -AI 可以操作用户界面，但“Agent 说任务完成了”并不足以构成可信的测试。团队需要看见实际发生的过程，检查判断结果所依据的事实，并在不让模型重新探索的情况下重复成功路径。 - -FSQ 是为这一工作流打造的开源、证据优先 UI 自动化 Agent Harness。 - -## 从自然语言目标到可检查事实 - -向 FSQ 提供一个用户可见的目标。执行过程中，FSQ 会把截图、标准化 UI Snapshot、有序事件、元数据和报告保存在同一个本地 Run 中。验证基于已有证据，而不仅仅依赖 Agent 的文字结论。 - -探索成功后，FSQ 可以根据真实操作生成一份供人工审查的 YAML Case。审查后的 Case 可以通过同一个平台 Harness 确定性重放，并生成新的回归证据。 - -## 四个平台，共享一套模型 - -FSQ 使用成熟的平台后端：Web 使用 Playwright，Android 使用 uiautomator2，Windows 使用 pywinauto，macOS 使用 Appium Mac2。FSQ 在其上提供统一的 Case、执行生命周期、证据、验证、Run 历史、就绪诊断和本地 Control Plane。 - -## 本地优先 - -Workspace 文件和 Run 证据保存在本地。Provider 配置存储在用户级 FSQ 配置目录，并由 CLI 与 Control Plane 共享。需要模型的操作会使用已配置的 GitHub Copilot 或 Azure OpenAI Provider。 - -## 体验 Alpha 版本 - -```bash -python -m pip install fsq-agent -mkdir fsq-web-demo && cd fsq-web-demo -fsq init --platform web --browser-channel chrome -fsq doctor -``` - -v0.1.0 是 Alpha 版本，适合评估、实验和早期贡献，但不是 1.0 兼容性承诺。 - -请从[入门指南](../getting-started.md)开始，以根目录和各模块的 `SPEC.md` 文件为实现契约，并通过[贡献指南](../../CONTRIBUTING.md)参与项目。 diff --git a/docs/superpowers/specs/2026-08-13-next-generation-cli-design.md b/docs/superpowers/specs/2026-08-13-next-generation-cli-design.md deleted file mode 100644 index 877260b..0000000 --- a/docs/superpowers/specs/2026-08-13-next-generation-cli-design.md +++ /dev/null @@ -1,504 +0,0 @@ -# FSQ Next-Generation CLI Design - -**Status:** Confirmed revision for internal review -**Date:** 2026-08-14 - -## Goal - -Design FSQ's next-generation command-line interface as a stable entry point for people, CI, and Coding Agents, while establishing a transport-neutral Python Application API shared by the CLI, Control Plane, and future Agent-facing adapters. - -This revision defines the public CLI interface and the shared application boundary. It deliberately does not design the internal workflow of each command. - -## Scope - -This design covers: - -- The first-phase public `fsq` command tree. -- Goal-driven Case creation and existing Case testing. -- The single public Case asset suffix `*.fsq.yaml`. -- Optional AI suggestions after testing an existing Case. -- Workspace preconditions for public commands. -- Human, JSON, and JSONL interfaces for people and Coding Agents. -- A real Python Application package shared by CLI, Control Plane, and future Coding Agent APIs. -- Transport-neutral Application Operations, Request, Result, Event, and Error contracts. -- Ownership boundaries between Application and the existing Agent, FSQ, Core, Report, and Driver modules. -- The first-phase Provider, Run, and Environment command surfaces. -- Breaking command and Case-file migration. - -## Non-goals - -This design does not decide: - -- The detailed internal workflow of `init`. -- Whether `case create`, `case test`, and `--suggest` are implemented as separate internal use-case classes. -- The detailed execution timing, persistence model, or failure semantics of suggestions. -- Concrete Python class names or the final file layout inside the Application package. -- Internal Run, Environment, Provider, or resource lifecycle algorithms. -- A public Extension protocol or installation mechanism. -- Public Action, Capability, or Operation discovery. -- A daemon, background queue, remote control plane, or detached execution. -- Parallel workers, sharding, test matrices, or cross-Case shared sessions. -- Environment creation, deletion, inspection, or cleanup commands. -- Run cancellation or deletion commands. -- Automatic modification of source Case files. - -## Design Principles - -1. **Organize commands around the Case resource.** Users create Cases from Goals and test existing Cases. -2. **Use one public Case format.** `*.fsq.yaml` is the only new Case asset type; no separate Intent format is introduced. -3. **Humans and Coding Agents share one CLI.** Machine consumers select a versioned output protocol rather than a separate command tree. -4. **CLI and UI share application semantics.** Entry adapters must not independently orchestrate FSQ workflows. -5. **Application is a real boundary, not a diagram label.** A Python Application package exposes transport-neutral operations and contracts. -6. **Application composes existing authorities.** It does not duplicate AI planning, Case parsing, step execution, report interpretation, or platform automation rules. -7. **Current directory is explicit context.** Commands do not search parent directories for a Workspace. -8. **Platform remains explicit.** Relevant commands require `--platform`; omitted Environment continues to mean `local`. -9. **Source Cases remain immutable.** AI output is written as suggestions or Run-local candidates, never silently over source files. -10. **First-phase contracts stay intentionally small.** Extension and discovery APIs remain future work. - -## Public Command Tree - -```text -fsq [GLOBAL OPTIONS] -├── init -├── doctor -├── case -│ ├── create -│ └── test -├── ui -├── providers -│ ├── list -│ ├── configure NAME -│ └── status [NAME] -├── runs -│ ├── list -│ ├── show RUN_ID -│ └── logs RUN_ID -└── environments - ├── list - └── doctor NAME -``` - -The first phase does not expose `extensions`, operation discovery, Environment mutation, or Run mutation commands. - -## Core Case Interfaces - -### Create a Case from a Goal - -```bash -fsq case create --platform web --goal "Verify product search" -``` - -Public meaning: - -- The user supplies a natural-language Goal. -- AI participates in testing the real target. -- Successful execution may produce a Run-local candidate `*.fsq.yaml`. -- The command does not overwrite an existing Case. - -Important public options expected in the first phase include: - -- `--platform PLATFORM`: required. -- `--goal TEXT`: required Goal input. -- `--environment NAME`: defaults to `local`. -- `--record/--no-record`: controls candidate Case generation; success records by default. -- `--stream/--no-stream`: controls live event presentation. -- `--timeout DURATION`: accepts forms such as `30s`, `5m`, and `1h`. -- `--max-steps N`: bounds external Agent operations. -- `--dry-run`: validates public preconditions without operating a target. - -The exact internal stages, internal use-case decomposition, and candidate-generation algorithm are deferred. - -### Test an Existing Case - -```bash -fsq case test --platform web tests/search.fsq.yaml -``` - -Public meaning: - -- The input is an existing `*.fsq.yaml` Case or a directory of Cases. -- The Case is executed as the regression-test authority. -- The source Case is not modified. -- An explicitly authored AI assertion remains part of the Case contract where supported. - -Important public options expected in the first phase include: - -- `CASE`: required `*.fsq.yaml`, migration-period `*.codex.yaml`, or directory. -- `--platform PLATFORM`: required and must agree with the Case. -- `--environment NAME`: defaults to `local`. -- `--suggest`: requests AI analysis and optional candidate improvements without overwriting the source Case. -- `--timeout DURATION`: bounds one Case test. -- `--fail-fast`: stops directory testing after the first unsuccessful child. -- `--dry-run`: validates discovery and public preconditions without operating a target. - -The detailed relationship between the original Case result and the suggestion result is deferred. The eventual implementation must preserve the original test facts and must not silently turn a failed Case into a pass. - -### Suggestion Boundary - -The public contract for `--suggest` is intentionally limited: - -- it is available only while testing an existing Case; -- it may emit structured suggestions and a Run-local candidate Case; -- it never overwrites the source `*.fsq.yaml`; -- it must preserve the original Case test facts; -- its internal timing, status model, and use-case decomposition are future design items. - -## Case Assets - -New Case assets use: - -```text -*.fsq.yaml -``` - -No `*.intent.yaml` or `fsq.test-intent/v1` format is introduced. Natural-language intent enters through `case create --goal`. Existing Cases enter through `case test`. - -For one deprecation cycle, Case testing and lifecycle references may accept `*.codex.yaml`. New candidates, examples, and documentation use `*.fsq.yaml`. The system does not automatically rename old files. The exact removal release remains a release-policy decision. - -Directory Case discovery is recursive, contained below the requested root, does not follow directory symlinks, and uses stable relative-path ordering. Empty discovery is an input error. Duplicate new/legacy Case identification requires a precise rule during the later SPEC phase. - -## Workspace Preconditions - -With the exception of `fsq init`, public commands require the current directory to contain a valid initialized Workspace at: - -```text -.fsq-agent-workspace -``` - -When the Workspace is missing or invalid, the command must: - -- fail before creating Runs, output directories, external sessions, VMs, or device actions; -- not search parent directories; -- not initialize automatically; -- tell the user to run `fsq init` or change to the intended initialized Workspace directory; -- expose stable structured error code `workspace.not_initialized`; -- map the condition consistently in Human, JSON, JSONL, CLI exit status, and UI responses. - -**TODO — Init design:** This revision intentionally does not redesign `fsq init`. Its responsibilities, parameters, Workspace creation flow, idempotency, and migration behavior require a separate design discussion. - -## Global CLI Contracts - -| Option | Behavior | -|---|---| -| `--output human\|json\|jsonl` | Selects the output protocol; default is `human`. | -| `--non-interactive` | Prohibits prompts, confirmations, and interactive authentication. | -| `--quiet` | Reduces Human output without removing required errors. | -| `--verbose`, `-v` | Increases safe diagnostics and may be repeated. | -| `--color auto\|always\|never` | Controls Human terminal color. | -| `--version` | Reports FSQ and protocol versions. | -| `--help` | Provides help at every command level. | - -`json` emits one final result. `jsonl` emits versioned events and ends with a terminal command event carrying an equivalent final result. Structured stdout contains protocol records only; safe diagnostics go to stderr. Commands without meaningful progress emit one terminal JSONL record. - -The shared result envelope includes a schema version, operation/command identity, status, timestamp, safe data, warnings, and a structured error with stable code, category, message, next action, and bounded redacted details. - -## Supporting Public Interfaces - -### `fsq doctor` - -Diagnoses the selected platform and Environment without provisioning paid or remote resources. Its detailed checks remain a later command-level design topic. - -### `fsq ui` - -Starts the official Control Plane adapter. It must consume the same Application API as the CLI rather than reimplement Case, Run, Provider, or Environment semantics. Non-loopback security and detailed UI startup options remain governed by the later public-interface specification. - -### `fsq providers` - -First-phase interfaces remain: - -```text -providers list -providers configure NAME -providers status [NAME] -``` - -Provider configuration remains current-directory-oriented and must never expose Secret values. Detailed authentication flows remain command-level design work after the shared framework is confirmed. - -### `fsq runs` - -First-phase interfaces remain: - -```text -runs list -runs show RUN_ID -runs logs RUN_ID -``` - -They expose the same application-level Run facts to CLI and UI. Detailed persistence layout, filtering, and lifecycle behavior are deferred. - -### `fsq environments` - -First-phase interfaces remain: - -```text -environments list --platform PLATFORM -environments doctor --platform PLATFORM NAME -``` - -The public CLI selects Environment Profiles without exposing Provider-specific switches. Detailed Local/Tart lifecycle implementation remains outside this revision. - -## Shared Application Architecture - -### Decision - -`Shared Application Services` is both an architecture layer and a real Python package in the repository. The package is the shared, transport-neutral application boundary used by the CLI, Control Plane, and future Coding Agent adapters. - -The package exposes Application Operations grouped by resource domain: - -- Workspace Operations -- Case Operations -- Run Operations -- Provider Operations -- Environment Operations - -It also exposes or consistently consumes shared application contracts: - -- Request -- Result -- Event -- Error -- Operation status and safe artifact references where applicable - -This design does not require one class per operation and does not decide the final package-internal file layout. - -```mermaid -flowchart TD - subgraph Adapters["Entry Adapters"] - CLI["fsq CLI"] - UI["Control Plane / fsq ui"] - AgentAPI["Future Coding Agent API"] - end - - subgraph Application["Python Application Package"] - Contracts["Shared Contracts
Request · Result · Event · Error"] - Workspace["Workspace Operations"] - Cases["Case Operations"] - Runs["Run Operations"] - Providers["Provider Operations"] - Environments["Environment Operations"] - end - - subgraph Authorities["Existing FSQ Authorities"] - Agent["Agent
AI planning and verification"] - FSQ["FSQ
Case language and normalization"] - Core["Core
step execution and evidence policy"] - Report["Report
persisted facts to reports"] - Driver["Driver
platform automation"] - end - - CLI --> Contracts - UI --> Contracts - AgentAPI --> Contracts - Contracts --> Workspace - Contracts --> Cases - Contracts --> Runs - Contracts --> Providers - Contracts --> Environments - Cases --> Agent - Cases --> FSQ - Cases --> Core - Runs --> Report - Environments --> Core - Core --> Driver - Core --> Report -``` - -The arrows show permitted application composition, not mandatory direct calls for every operation and not one class per box. - -### Why a Real Package - -If Application exists only as a diagram label, the CLI and Control Plane can each continue to load configuration, validate inputs, start execution, map states, and find artifacts independently. Their behavior will eventually diverge even if both call the same low-level modules. - -A real package makes the dependency boundary enforceable: - -```text -CLI adapter ─────────┐ -Control Plane adapter├──> Application API ──> existing FSQ authorities -Future Agent adapter ┘ -``` - -CLI and UI should share application semantics, not transport objects. - -### Shared vs Adapter-specific Concerns - -| Shared Application contract | CLI adapter | Control Plane adapter | -|---|---|---| -| Request | Click argument mapping | HTTP request mapping | -| Result | Human/JSON/JSONL rendering | HTTP response/UI projection | -| Event | stdout/stderr stream | SSE or equivalent transport | -| Error | Exit-code mapping | HTTP status mapping | -| Operation status | Process/SIGINT behavior | Browser task state | - -Application contracts must not import or expose Click contexts, HTTP request/response types, SSE payload types, terminal formatting objects, or frontend view models. - -## Ownership Boundaries - -### What Application Owns - -Application owns cross-module application semantics that must be identical for all adapters: - -- the public operation boundary and request validation at that boundary; -- current-Workspace context enforcement; -- composition of existing module APIs into one user operation; -- unified application results, events, statuses, and errors; -- safe artifact references and adapter-independent next actions; -- consistent behavior across CLI, Control Plane, and future adapters. - -### What Application Does Not Re-own - -Application may call the existing modules, but it does not copy, reinterpret, or replace their authoritative rules: - -- **Agent** continues to own AI planning, model tool-use orchestration, dynamic execution guidance, and evidence-based dynamic verification. -- **FSQ** continues to own Case-file recognition, YAML/DSL parsing, validation, capability alias resolution, and conversion into canonical executable steps. -- **Core** continues to own capability lookup, parameter and runtime-secret validation, deterministic step/sequence execution, evidence capture policy, Harness routing, and normalized step results. -- **Report** continues to own transformation of persisted execution facts into standard reports and failure analysis. -- **Driver** continues to own concrete platform automation and backend error normalization. - -Application owns the statement "compose the appropriate authorities for this user operation." It does not own alternative implementations of YAML parsing, tool execution, screenshot policy, report semantics, or device automation. - -### No Giant Facade - -The Application package must not collapse into a single catch-all interface such as: - -```python -application.execute(command) -``` - -or a giant service object containing every command. Operations are grouped by resource domain so adapters depend only on the capabilities they use. The exact internal use-case granularity remains deferred. - -### Adapter Dependency Rule - -New CLI and Control Plane business operations must go through the Application API. Adapters must not bypass Application to recreate shared validation, orchestration, state mapping, or artifact discovery. Narrow transport-only concerns remain in the adapter. - -Existing low-level authorities must not import the Application package. Dependency direction is from adapters to Application to existing modules. - -## Extension Boundary - -This revision does not define a public Extension API. It records only an architectural constraint for future work: - -- extensions will most naturally appear below the Application layer, including Model Providers, Environment Providers, Drivers, Report exporters, and carefully governed capabilities; -- extensions must not require CLI-only business orchestration that has no equivalent Application Operation for UI and Agent adapters; -- extending public Application Operations is a separate future design because it requires transport-neutral schemas, compatibility, permissions, discovery, and security rules. - -No Extension installation or discovery command is committed by this design. - -## Existing Module Locations and Roles - -| Authority | Current location | Role retained beneath Application | -|---|---|---| -| Agent | `fsq_agent/agent/` | Goal planning, SDK tool orchestration, dynamic execution, verification | -| FSQ | `fsq_agent/fsq/` | Case DSL parsing, validation, and canonical step adaptation | -| Core | `fsq_agent/core/` | Capability registry, deterministic execution, evidence, Harness/Driver routing | -| Report | `fsq_agent/report/` | Persisted facts to Markdown/JSON reports and failure analysis | -| Drivers | `fsq_agent/core/harness/` | Concrete Playwright, UIAutomator2, Appium Mac2, and pywinauto automation | - -The later SPEC phase must define the Application module's public imports and verify that existing authorities remain the single rule owners. - -## Machine Protocol and Exit Categories - -The previously agreed direction remains: - -- `--output human|json|jsonl` is global. -- JSON emits one final application Result. -- JSONL emits versioned Events and one terminal Result event. -- stdout contains structured protocol data only in machine modes. -- Secrets and hidden reasoning never appear in outputs. - -Top-level CLI exit categories remain: - -| Code | Meaning | -|---:|---| -| `0` | Operation succeeded; tested behavior passed where applicable. | -| `1` | Case test completed but failed or was inconclusive. | -| `2` | CLI usage, Case input, discovery, or schema error. | -| `3` | Workspace, configuration, authentication, Provider, or Environment not ready. | -| `4` | Driver, device, network, VM, or remote infrastructure failure. | -| `5` | FSQ internal error. | -| `130` | User interruption. | - -Application Error is the shared semantic fact. CLI maps it to an exit code; Control Plane maps it to an HTTP/status response. - -## Compatibility and Migration - -The primary executable becomes `fsq`; `fsq-agent` may temporarily point to the same new command tree. New documentation uses `fsq`. - -Old command forms are not silently forwarded: - -| Removed form | New interface | -|---|---| -| `fsq-agent run --goal ...` | `fsq case create --goal ...` | -| `fsq-agent run --case-yaml ...` | `fsq case test CASE` or create a Case from a Goal | -| `fsq-agent run --strict --case-yaml ...` | `fsq case test CASE` | -| `fsq-agent report --run-id ...` | `fsq runs show RUN_ID` | -| `fsq-agent control-plane` | `fsq ui` | -| `fsq-agent playground` | No first-phase public replacement | - -Removed commands return a usage error and a migration action rather than guessing intent. Existing `.fsq-agent-workspace` and configured output roots remain migration concerns. The exact removal release for `fsq-agent` and `*.codex.yaml` remains open. - -## Verification Expectations - -The later implementation must verify: - -- the complete command/help hierarchy and public option mapping; -- current-directory Workspace enforcement on every command except `init`; -- no parent-directory Workspace discovery or automatic initialization; -- Goal-to-Case and existing-Case public input separation; -- `--suggest` never overwrites the source Case and preserves original test facts; -- `*.fsq.yaml` discovery and migration-period legacy behavior; -- identical Application Result, Event, and Error semantics across CLI and Control Plane adapters; -- clean mapping from shared Application errors to CLI exit codes and UI/HTTP status; -- no Click/HTTP/frontend types in the Application API; -- no Application logic duplicated in CLI or Control Plane; -- no duplicate Agent, FSQ, Core, Report, or Driver rule implementation in Application; -- Human, JSON, and JSONL output consistency and redaction; -- source-checkout and isolated-wheel behavior. - -Expected repository checks remain: - -```bash -pytest -ruff check . -ruff format --check . -npm test -npm run build -``` - -## Affected Specifications - -The later `/spec-driven` phase is expected to evaluate at least: - -- `SPEC.md` for public command, module-map, dependency, and file-naming changes. -- A new Application module `SPEC.md` if the confirmed module does not yet exist. -- `fsq_agent/cli/SPEC.md` for the public CLI and adapter boundary. -- `fsq_agent/models/SPEC.md` for shared serializable application boundary models where appropriate. -- `fsq_agent/control_plane/SPEC.md` and `frontend/control-plane/SPEC.md` for Application API consumption and renamed Case operations. -- `fsq_agent/agent/SPEC.md`, `fsq_agent/fsq/SPEC.md`, `fsq_agent/core/SPEC.md`, and `fsq_agent/report/SPEC.md` for dependency direction and retained ownership. -- `fsq_agent/config/SPEC.md`, Provider, and Environment specifications where the public interfaces require change. - -## Resolved Decisions - -- Public Case operations are `fsq case create` and `fsq case test`. -- `fsq case test --suggest` requests optional AI suggestions without source overwrite. -- No `test`, `replay`, or `*.intent.yaml` public model remains. -- `*.fsq.yaml` is the single new Case asset suffix. -- Except for `init`, commands require an initialized Workspace in the current directory. -- Parent-directory Workspace search and automatic initialization are prohibited. -- `init` details are deferred as a separate TODO. -- Shared Application Services is a real Python package and an architecture layer. -- Application Operations are grouped by Workspace, Case, Run, Provider, and Environment. -- CLI, Control Plane, and future Agent adapters share transport-neutral Request, Result, Event, and Error contracts. -- Application composes but does not duplicate Agent, FSQ, Core, Report, or Driver rules. -- Application is not a giant catch-all Facade. -- Detailed internal use-case decomposition is deferred. - -## Open Review Questions - -1. What exact Python package name and public import surface should carry the Application API? -2. Which contract types belong in Application versus the neutral `models` module? -3. What precise request/result/event/error compatibility policy applies across releases? -4. Which existing CLI and Control Plane composition helpers migrate into Application, and which remain adapter-local? -5. What is the exact public option set for each command after the framework is approved? -6. How is `--suggest` represented in results without changing the original Case test facts? -7. What exact rule identifies duplicate `*.fsq.yaml` and `*.codex.yaml` files? -8. Which release removes the `fsq-agent` executable and legacy Case suffix? -9. What detailed behavior should `fsq init` eventually own? diff --git a/docs/superpowers/specs/2026-08-13-next-generation-cli-team-discussion-design.md b/docs/superpowers/specs/2026-08-13-next-generation-cli-team-discussion-design.md deleted file mode 100644 index 9380650..0000000 --- a/docs/superpowers/specs/2026-08-13-next-generation-cli-team-discussion-design.md +++ /dev/null @@ -1,305 +0,0 @@ -# FSQ 下一代 CLI：团队内部讨论稿 - -**用途：** 团队讨论与决策同步 -**日期：** 2026-08-14 -**状态：** 修订后内部 Review - -> 本文不是 SPEC、实现依据或最终 API 承诺。完整技术设计见 [FSQ Next-Generation CLI Design](./2026-08-13-next-generation-cli-design.md)。 - -## 1. 本轮讨论收敛到什么范围 - -本轮只讨论两件事： - -1. FSQ CLI 应该公开哪些接口。 -2. CLI、Control Plane 和未来 Coding Agent API 如何共享同一套应用接口。 - -暂不讨论： - -- 每个命令内部的详细流程； -- `case create`、`case test`、`--suggest` 是否对应三个内部 Use Case； -- Run、Environment、Provider 的内部生命周期； -- Application 包内的具体类和文件； -- Extension、Driver、Reporter 的具体插件机制； -- `init` 的具体职责和参数。 - -## 2. 第一阶段 CLI 接口 - -```text -fsq -├── init -├── doctor -├── case -│ ├── create -│ └── test -├── ui -├── providers -│ ├── list -│ ├── configure NAME -│ └── status [NAME] -├── runs -│ ├── list -│ ├── show RUN_ID -│ └── logs RUN_ID -└── environments - ├── list - └── doctor NAME -``` - -核心调用： - -```bash -fsq case create --platform web --goal "验证搜索功能" - -fsq case test --platform web tests/search.fsq.yaml - -fsq case test \ - --platform web \ - tests/search.fsq.yaml \ - --suggest -``` - -## 3. Case 模型 - -### `case create` - -- 输入自然语言 Goal。 -- AI 参与真实测试。 -- 成功后可以生成 Run-local 的候选 `*.fsq.yaml`。 -- 不覆盖已有 Case。 - -### `case test` - -- 输入已有 `*.fsq.yaml` 或 Case 目录。 -- Case 是回归测试的执行依据。 -- 不修改源 Case。 - -### `case test --suggest` - -- 在测试已有 Case 时请求 AI 建议。 -- 可以产生结构化建议和候选 Case。 -- 不覆盖源文件。 -- 必须保留原始 Case Test 的执行事实，不能把失败静默变成通过。 -- 建议阶段的内部时机、状态和拆分暂不讨论。 - -本轮不再引入： - -```text -fsq test -fsq replay -*.intent.yaml -fsq.test-intent/v1 -``` - -新的正式 Case 统一使用： - -```text -*.fsq.yaml -``` - -旧 `*.codex.yaml` 可以保留一个迁移周期，具体期限后续决定。 - -## 4. Workspace 前置规则 - -除 `fsq init` 外，所有命令必须在已经初始化的 Workspace 当前目录中运行： - -```text -/.fsq-agent-workspace -``` - -如果不存在或无效： - -- 不向父目录查找； -- 不自动初始化； -- 不创建 Run 或外部资源； -- 提示执行 `fsq init`，或者切换到正确目录； -- 结构化错误使用 `workspace.not_initialized`。 - -> **TODO — Init 单独设计：** 本轮不修改 `init` 的详细职责、参数和 Workspace 创建流程。 - -## 5. Shared Application Services 到底是什么 - -确认方向： - -> Shared Application Services 既是架构层，也是仓库中的真实 Python Application 包。 - -它不是一个巨型 `ApplicationService`，也不是只有一张架构图。它向以下入口提供同一套应用接口： - -- `fsq` CLI -- Control Plane / `fsq ui` -- 未来 Coding Agent API - -接口按资源域组织： - -```text -Workspace Operations -Case Operations -Run Operations -Provider Operations -Environment Operations -``` - -入口共享传输无关的： - -```text -Request -Result -Event -Error -``` - -## 6. CLI 和 UI 如何共用 90% - -```mermaid -flowchart LR - CLIInput["CLI arguments"] --> CLI["CLI Adapter"] - HTTPInput["HTTP requests"] --> UI["Control Plane Adapter"] - AgentInput["Future Agent calls"] --> AgentAdapter["Agent Adapter"] - - CLI --> API["Shared Application API"] - UI --> API - AgentAdapter --> API - - API --> Contracts["Request · Result · Event · Error"] - Contracts --> Existing["Existing FSQ Authorities"] - - Contracts --> CLIOutput["Human · JSON · JSONL · Exit code"] - Contracts --> UIOutput["HTTP · SSE · UI projection"] -``` - -共同部分是业务语义： - -- Workspace 上下文； -- 请求验证； -- Case、Run、Provider、Environment 操作； -- 状态、结果、事件、错误； -- Artifact 引用和安全的下一步建议。 - -不共同的是传输细节： - -| CLI 独有 | UI 独有 | -|---|---| -| Click 参数 | HTTP 请求 | -| stdout/stderr | HTTP Response | -| Human/JSON/JSONL | SSE/UI 投影 | -| 退出码 | HTTP 状态码 | -| SIGINT | 浏览器任务状态 | - -Application API 不暴露 Click、HTTP、SSE 或前端类型。 - -## 7. Application 不重新拥有底层行为 - -Application 负责“为了完成用户操作，需要组合哪些现有能力”。它不复制这些模块的领域规则： - -| 模块 | 继续拥有的规则 | -|---|---| -| Agent | AI 规划、工具编排、动态执行和 Evidence-based verification | -| FSQ | Case YAML/DSL 解析、验证和 canonical step 转换 | -| Core | Capability、参数/Secret 验证、步骤执行、Evidence 策略和 Harness 路由 | -| Report | 从持久化事实生成标准报告和失败分析 | -| Driver | Playwright、UIAutomator2、Appium、pywinauto 等平台操作 | - -Application 可以做： - -```text -接收 Case Operation → 调用正确模块 → 返回统一 Result/Event/Error -``` - -Application 不可以做： - -```text -再写一套 YAML Parser -直接循环调用 Driver -自己决定截图策略 -自己重新解释 pass/fail 报告 -自己实现 Agent tool loop -``` - -## 8. 为什么必须是真实 Python 包 - -如果 Shared Application Services 只是一层概念，CLI 和 UI 仍可能分别： - -- 加载和验证配置； -- 启动 Case； -- 映射状态和错误； -- 查找 Report 与 Evidence； -- 处理 Provider 和 Environment readiness。 - -行为最终会分叉。真实的 Application 包可以建立强制依赖方向： - -```text -CLI ───────────┐ -Control Plane ─├──> Application API ──> Existing FSQ modules -Future Agent ──┘ -``` - -底层 Agent、FSQ、Core、Report 和 Driver 不反向依赖 Application。 - -## 9. 不做巨型 Facade - -不建议： - -```python -application.execute(command) -``` - -也不建议一个类包含全部命令。Application Operations 按 Workspace、Case、Run、Provider、Environment 分组。 - -本轮不决定这些分组内部最终拆成多少 Use Case 或文件。 - -## 10. Extension 的暂定位置 - -本轮不设计 Extension API，只记录方向： - -- Extension 更可能出现在 Application 下面，例如 Model Provider、Environment Provider、Driver、Report exporter 和受治理的 Capability。 -- Extension 不应只增加 CLI 私有业务流程，否则 UI 和 Agent API 无法共用。 -- 扩展公开 Application Operation 需要单独设计版本、Schema、权限、发现和安全模型。 - -第一阶段不公开 Extension 安装或发现命令。 - -## 11. 机器接口方向 - -继续保留全局： - -```text ---output human|json|jsonl ---non-interactive -``` - -- JSON 输出最终 Application Result。 -- JSONL 输出 Application Events，并以终态 Result 结束。 -- Application Error 由 CLI 映射成退出码，由 UI 映射成 HTTP/状态响应。 -- Secret 和隐藏推理不得进入任何输出。 - -## 12. Breaking Changes - -| 旧方式 | 新接口 | -|---|---| -| `fsq-agent run --goal ...` | `fsq case create --goal ...` | -| `fsq-agent run --case-yaml ...` | `fsq case test CASE` 或从 Goal 创建 Case | -| `fsq-agent run --strict --case-yaml ...` | `fsq case test CASE` | -| `fsq-agent report --run-id ...` | `fsq runs show RUN_ID` | -| `fsq-agent control-plane` | `fsq ui` | - -旧命令不应静默转发。`fsq-agent` 程序名和 `*.codex.yaml` 的具体移除版本后续决定。 - -## 13. 下一轮需要逐项讨论 - -框架确认后，再分别讨论： - -1. `init` 的职责和 Workspace 创建流程。 -2. 每个 CLI 命令的完整参数和行为。 -3. `case create` 的内部阶段和候选 Case 规则。 -4. `case test --suggest` 的时机、结果状态和 Artifact。 -5. Run、Environment 和 Provider 的内部生命周期。 -6. Application 包的具体模块、类型和公开 import。 -7. Extension、Driver 和 Reporter 的扩展协议。 - -## 14. 本轮希望团队确认 - -- 是否接受 `case create` / `case test` 的公共模型； -- 是否确认只保留 `*.fsq.yaml` 新 Case 格式； -- 是否确认 Workspace 当前目录前置规则； -- 是否确认建立真实 Python Application 包； -- 是否确认 CLI、UI、未来 Agent API 共享传输无关契约； -- 是否确认 Application 只编排、不复制现有模块的领域规则； -- 是否确认先定框架，再逐命令讨论内部实现。 diff --git a/pyproject.toml b/pyproject.toml index 8485d51..75325a8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -71,7 +71,6 @@ include = [ "/README.md", "/README.zh-CN.md", "/CHANGELOG.md", - "/docs/README.md", "/docs/assets/fsq-workflow.svg", "/docs/assets/social-preview.png", "/docs/assets/social-preview.svg", @@ -80,7 +79,6 @@ include = [ "/docs/demo.html", "/docs/getting-started.md", "/docs/getting-started.zh-CN.md", - "/docs/launch", "/docs/media", "/docs/platform-prerequisites.md", "/docs/releases", diff --git a/tests/test_distribution_contract.py b/tests/test_distribution_contract.py index 284dca0..9cf6146 100644 --- a/tests/test_distribution_contract.py +++ b/tests/test_distribution_contract.py @@ -65,7 +65,6 @@ def test_sdist_includes_public_release_documentation_and_example() -> None: assert { "/CHANGELOG.md", "/README.zh-CN.md", - "/docs/README.md", "/docs/assets/fsq-workflow.svg", "/docs/assets/social-preview.png", "/docs/assets/social-preview.svg", @@ -73,7 +72,6 @@ def test_sdist_includes_public_release_documentation_and_example() -> None: "/docs/cli-reference.md", "/docs/getting-started.md", "/docs/getting-started.zh-CN.md", - "/docs/launch", "/docs/media", "/docs/platform-prerequisites.md", "/docs/releases",