FSQ 0.1.x growth plan — discussion draft

[mijun (houlianpi)]

中文 · English

中文

Important

状态：讨论稿。 本文不是公开 Roadmap、发布承诺或已确认的版本计划。维护者完成评审后，确认的工作将通过 GitHub Issues 和 Milestones 单独跟踪。

目标

对于 FSQ 0.1.x 系列，我们希望开发者能够快速理解 FSQ、在五分钟内完成一次成功体验、自然地将 FSQ 与 Coding Agent 配合使用，并愿意 Star、分享和再次使用。

建议的北极星结果是：提升用户认可度，并实现 GitHub Star 的持续快速增长。Star 是结果指标；首次使用成功率、重复使用和 Coding Agent 工作流完成率，才是指导具体工作的可操作信号。

希望大家重点评审的问题

1. 以用户采用和认可作为 0.1.x 的首要目标是否正确？
2. P0/P1/P2 的排序是否合理？
3. Provider 覆盖、Coding Agent 工作流和 Runs 可用性是否应该是最高优先级？
4. 哪些内容应明确排除在 0.1.x 之外？
5. 应使用哪些可量化目标来定义成功？
6. 每个优先事项以及每周复盘应由谁负责？

成功指标

结果指标

• 每周新增 GitHub Stars
• 每周新增 Forks
• Unique cloners 和 Clone 趋势
• PyPI 下载趋势
• 在能够安全衡量的前提下，记录 FSQ 的重复使用情况

漏斗与产品指标

• README 访问者
• 安装尝试
• 首次 Run 尝试
• 首次成功的无 Provider 重放
• 首次成功创建 AI Case
• Coding Agent 工作流完成率
• 每周前三项首次使用流失原因

这些指标仍需确定基线、0.1.x 目标、负责人和复盘节奏。GitHub Traffic 和 PyPI 下载量只应作为趋势信号，不等同于准确用户数。

建议 P0：必须完成

1. 建立增长基线

• 每周记录 Stars、Forks、Clones、Unique cloners 和 PyPI 下载量。
• 在可行范围内衡量从 README 访问到安装、首次 Run 和首次成功的路径。
• 按安装、Provider、Driver、Run、Case 和其他采用阻塞因素分类 Issues。
• 每周复盘前三项用户流失原因。
• 确定 0.1.x 目标值和固定复盘节奏。

2. 扩大 Provider 和模型覆盖

• 支持 OpenAI。
• 支持 Anthropic。
• 在能够带来有效覆盖时，提供 OpenAI-compatible endpoint。
• 建立 Provider conformance tests。
• 定义 Supported、Compatible 和 Experimental 支持等级。
• 改进认证失败、模型不支持、限流和超时错误。
• 在 README 中清楚展示支持的 Provider 和模型边界。

OpenRouter、Ollama 和其他 Provider 应根据明确需求提升优先级，而不是仅为了增加集成数量而加入。

3. 建立标准 Coding Agent 工作流

• 提供简洁、稳定的 FSQ Agent skill 或 AGENTS.md 模板。
• 说明 Coding Agent 应如何创建、检查、审查和重放 Case。
• 为 Codex、Claude Code 和 GitHub Copilot 提供最小示例。
• 确保核心命令具有稳定的 JSON 或 JSONL 输出。
• 定义可靠的退出码和错误类别。
• 让 Agent 无需解析面向人的终端文本，就能定位最新 Run、报告、证据和生成的 Case。
• 发布一个端到端示例：修改代码、启动应用、使用 FSQ 验证真实 UI、检查 Run，并重放审查后的 Case。

第一阶段目标是建立一套可供多个 Coding Agent 使用的稳定 CLI 契约，而不是分别构建三个深度集成。

4. 完善 Runs 核心体验

• 每个 Run 完成后都应报告状态、Run ID、失败位置和建议的下一条命令。
• 保持 runs list 可按 mode、platform、status 和 Case/Goal 轻松导航。
• 让 runs show 成为权威的人类可读 Run 摘要。
• 清楚表达 Goal、Run、Evidence、Candidate Case、Published Case 和 Replay Run 之间的关系。
• 区分环境、Provider、Driver、Case assertion 和内部错误。
• 失败后直接链接相关截图、UI snapshots、日志和报告。
• 为 Coding Agent 提供稳定的机器可读 Run 摘要。

复杂 Dashboard、跨 Run 对比和长期历史分析不属于本阶段 P0 范围。

5. 确保首次使用成功

• 验证从干净环境到首次 Web replay 的完整路径。
• 保持 provider-free 示例可以直接运行。
• 在 AI Case creation 之前明确说明 Provider 要求。
• 确保 fsq doctor 能说明哪些功能已就绪、哪些被阻塞以及如何修复。
• 邀请至少 5–10 位核心实现团队之外的人员测试首次使用。
• 修复这些测试中反复出现的阻塞问题。
• 保持 README、Getting Started 和 CLI help 一致。
• 为 Windows、macOS 和 Android 前置条件提供最短成功路径。

6. 制作可传播的 Demo

• 制作一个围绕单一故事的 Coding Agent + FSQ 主 Demo。
• 在 30–60 秒内展示：Coding Agent 修改功能、FSQ 操作真实 UI、Run 捕获证据、审查 Case，以及不使用 LLM 重放 Case。
• 发布对应的可运行示例仓库或项目。
• 准备适合 README、社交媒体和发布公告的不同版本。
• 清楚解释 FSQ 与 Agent 仅仅自我报告“修改有效”之间的差异。
• 发布围绕“AI 探索一次；审查后的自动化确定性重放”的配套内容。

建议 P1：根据用户证据推进

7. 修复高频可靠性问题

• 建立最小的面向用户错误分类。
• 始终保存有用的失败证据。
• 为短暂的 UI 未就绪问题提供安全、有限的重试。
• 明确 timeout 和 cancellation 行为。
• 将底层 Driver 错误转换为可操作的信息。
• 不允许 Strict replay 隐式改变 Case 中编写的动作。
• 根据观察到的失败频率选择下一项修复。

0.1.x 不要求完成完整的 exception 和 recovery 系统，但任何反复阻碍首次成功的问题都应被视为近期工作。

8. 建立社区反馈闭环

• 保持 Bug、Provider request 和 New platform/Driver 模板简洁。
• 维护适合首次贡献者的 good first issues。
• 清楚说明社区可以贡献什么。
• 快速响应安装和首次运行问题。
• 为每个有意义的 0.1.x 版本发布简短说明和聚焦 Demo。
• 展示真实的社区 Case、集成和使用示例。
• 询问停止使用 FSQ 的用户：什么阻碍了继续采用。

建议 P2：仅在有明确需求时推进

• OpenRouter、Ollama 和其他 Provider
• 官方 GitHub Action
• 更多 Coding Agent 示例
• VS Code extension 原型
• 实验性 Driver plugin contract
• 新平台 Drivers
• 更丰富的 Run timeline
• 基础 replay reliability benchmark

0.1.x 明确暂不投入

除非用户证据表明以下某项已经成为直接的采用阻塞：

• 完整 Harness SDK
• 公共 Driver registry
• 大规模 Case marketplace
• Multi-agent execution
• Remote device farm
• 完整 self-healing
• 高级 Evidence graph
• 跨 Run 分析平台
• Cloud Control Plane
• 仅为了内部整洁而进行的大型架构重构

建议版本节奏

以下内容仅用于辅助讨论，不是版本承诺。

0.1.1 — 首次使用成功

• 解决发布后的安装和文档问题。
• 改进 doctor 和高频错误指导。
• 验证 provider-free Web 示例。
• 改进 Run 完成摘要。

0.1.2 — Provider 覆盖

• 添加 OpenAI。
• 根据评审结果添加 Anthropic 或 OpenAI-compatible endpoint。
• 添加 Provider conformance 和支持等级。
• 改进 Provider 配置和失败处理。

0.1.3 — Coding Agent 工作流

• 稳定机器可读输出。
• 发布 Agent skill 或模板。
• 发布端到端示例。
• 发布 Coding Agent + FSQ 主 Demo。

后续 0.1.x — 数据驱动

根据观察到的流失原因、Provider 请求、首次运行失败、Coding Agent 反馈和 Star/下载转化来选择工作，而不是提前填满所有 patch release。

每周决策标准

在把一个事项加入当前 0.1.x 计划之前，询问：

1. 它是否能让更多开发者尝试 FSQ？
2. 它是否提高首次成功或重复使用的概率？
3. 它是否让 FSQ 更容易理解和传播？
4. 是否有用户或指标证据支持它？
5. 它的维护成本和兼容风险对于 0.1.x 是否可接受？

开放决策

• 确认或修订 0.1.x 的首要目标。
• 定义增长基线和目标值。
• 指定每周指标复盘的负责人和节奏。
• 选择第一个新增 Provider。
• 决定下一步优先支持 Anthropic，还是 OpenAI-compatible endpoint。
• 定义 Coding Agent 的最小稳定契约。
• 确认 Runs 的 P0 范围。
• 定义一次成功的首次使用体验。
• 确认或修订建议的 0.1.1–0.1.3 节奏。
• 确认明确暂不投入的事项。

决策记录

日期	决策	理由	负责人	后续行动
—	—	—	—	—

请针对各项优先级发表评论、提供具体证据，并指出哪些内容应该在 P0、P1、P2 或暂不投入之间调整。

---

English

Important

Status: Discussion draft. This is not the public roadmap, a release commitment, or a confirmed version plan. Confirmed work will be tracked separately through GitHub Issues and milestones after maintainer review.

Objective

For the FSQ 0.1.x line, help developers understand FSQ quickly, complete a successful first experience within five minutes, use FSQ naturally with Coding Agents, and be willing to star, share, and use it again.

The proposed north-star outcome is faster user recognition and sustained GitHub Star growth. Stars are an outcome metric; first-use success, repeat usage, and Coding Agent workflow completion are the actionable signals that should guide the work.

Questions for review

1. Is adoption and user recognition the right primary objective for 0.1.x?
2. Is the proposed P0/P1/P2 ordering correct?
3. Are Provider coverage, Coding Agent workflow, and Runs usability the right top priorities?
4. What should explicitly remain outside 0.1.x?
5. What measurable targets should define success?
6. Who should own each priority and the weekly review?

Success metrics

Outcome metrics

• Weekly new GitHub Stars
• Weekly new Forks
• Unique cloners and clone trend
• PyPI download trend
• Repeat FSQ usage where it can be measured safely

Funnel and product metrics

• README visitors
• Installation attempts
• First Run attempts
• First successful provider-free replay
• First successful AI Case creation
• Coding Agent workflow completion
• Top three first-use abandonment reasons each week

Metrics still need baselines, 0.1.x targets, owners, and a review cadence. GitHub traffic and PyPI downloads are directional signals rather than exact user counts.

Proposed P0: must complete

1. Establish the growth baseline

• Record weekly Stars, Forks, Clones, unique cloners, and PyPI downloads.
• Measure the path from README visit to installation, first Run, and first success where practical.
• Classify Issues by installation, Provider, Driver, Run, Case, and other adoption blockers.
• Review the top three user abandonment causes each week.
• Define 0.1.x target values and a regular review cadence.

2. Expand Provider and model coverage

• Support OpenAI.
• Support Anthropic.
• Provide an OpenAI-compatible endpoint where it offers meaningful coverage.
• Establish Provider conformance tests.
• Define Supported, Compatible, and Experimental support levels.
• Improve authentication, unsupported-model, rate-limit, and timeout errors.
• Show supported Providers and model boundaries clearly in the README.

OpenRouter, Ollama, and other Providers should be promoted based on demonstrated demand rather than added only to increase the integration count.

3. Establish a standard Coding Agent workflow

• Provide a concise and stable FSQ Agent skill or AGENTS.md template.
• Explain how a Coding Agent should create, inspect, review, and replay a Case.
• Provide minimal examples for Codex, Claude Code, and GitHub Copilot.
• Ensure core commands have stable JSON or JSONL output.
• Define reliable exit codes and error categories.
• Let an Agent locate the latest Run, report, evidence, and generated Case without parsing human terminal text.
• Publish one end-to-end example: modify code, start the app, verify the real UI with FSQ, inspect the Run, and replay the reviewed Case.

The first goal is one stable CLI contract usable by multiple Coding Agents, not three separate deep integrations.

4. Complete the core Runs experience

• Make every completed Run report its status, Run ID, failure location, and recommended next command.
• Keep runs list easy to navigate by mode, platform, status, and Case or Goal.
• Make runs show the authoritative human-readable Run summary.
• Clearly connect Goal, Run, Evidence, Candidate Case, Published Case, and Replay Run.
• Distinguish environment, Provider, Driver, Case assertion, and internal failures.
• Link directly to relevant screenshots, UI snapshots, logs, and reports after failure.
• Provide a stable machine-readable Run summary for Coding Agents.

Complex dashboards, cross-Run comparisons, and long-term history analytics are not part of this P0 scope.

5. Ensure first-use success

• Verify the complete path from a clean environment to the first Web replay.
• Keep the provider-free example directly runnable.
• Make Provider requirements explicit before AI Case creation.
• Ensure fsq doctor explains what is ready, what is blocked, and how to fix it.
• Test first use with at least 5–10 people outside the core implementation group.
• Fix repeated blockers found in those sessions.
• Keep README, Getting Started, and CLI help consistent.
• Provide the shortest successful setup path for Windows, macOS, and Android prerequisites.

6. Produce a shareable Demo

• Create one primary Coding Agent + FSQ Demo with a single focused story.
• Show within 30–60 seconds: a Coding Agent changes a feature, FSQ operates the real UI, the Run captures evidence, a Case is reviewed, and the Case replays without an LLM.
• Publish the corresponding runnable example repository or project.
• Prepare suitable versions for the README, social posts, and release announcements.
• Explain clearly how FSQ differs from an Agent merely reporting that its own change works.
• Publish supporting material around “AI explores once; reviewed automation replays deterministically.”

Proposed P1: advance from user evidence

7. Fix high-frequency reliability problems

• Establish a minimal user-facing error taxonomy.
• Always preserve useful failure evidence.
• Add safe, bounded retries for transient UI readiness problems.
• Clarify timeout and cancellation behavior.
• Translate backend Driver errors into actionable messages.
• Do not allow Strict replay to change authored Case actions implicitly.
• Select the next fix from observed failure frequency.

A complete exception and recovery system is not required for 0.1.x, but any issue that repeatedly prevents first success should be treated as near-term work.

8. Establish a community feedback loop

• Keep Bug, Provider request, and New platform or Driver templates concise.
• Maintain useful good first issues.
• Explain clearly what the community can contribute.
• Respond quickly to installation and first-run problems.
• Publish short release notes and a focused Demo for each meaningful 0.1.x release.
• Highlight real community Cases, integrations, and usage examples.
• Ask users who stop using FSQ what prevented continued adoption.

Proposed P2: only with demonstrated demand

• OpenRouter, Ollama, and additional Providers
• Official GitHub Action
• Additional Coding Agent examples
• VS Code extension prototype
• Experimental Driver plugin contract
• New platform Drivers
• Richer Run timeline
• Basic replay reliability benchmark

Explicitly out of scope for 0.1.x

Unless user evidence shows that one of these is a direct adoption blocker:

• Full Harness SDK
• Public Driver registry
• Large Case marketplace
• Multi-agent execution
• Remote device farm
• Full self-healing
• Advanced Evidence graph
• Cross-Run analytics platform
• Cloud Control Plane
• Large architecture refactors performed only for internal cleanliness

Proposed release sequence

This sequence is a discussion aid, not a commitment.

0.1.1 — First-use success

• Address post-release installation and documentation issues.
• Improve doctor and frequent error guidance.
• Validate the provider-free Web example.
• Improve the Run completion summary.

0.1.2 — Provider coverage

• Add OpenAI.
• Add Anthropic or an OpenAI-compatible endpoint based on review.
• Add Provider conformance and support levels.
• Improve Provider configuration and failure handling.

0.1.3 — Coding Agent workflow

• Stabilize machine-readable output.
• Publish the Agent skill or template.
• Publish an end-to-end example.
• Publish the primary Coding Agent + FSQ Demo.

Later 0.1.x — Data-driven

Select work from observed abandonment reasons, Provider requests, first-run failures, Coding Agent feedback, and Star/download conversion rather than pre-filling every patch release.

Weekly decision criteria

Before adding an item to the active 0.1.x plan, ask:

1. Does it let more developers try FSQ?
2. Does it improve the probability of first success or repeat usage?
3. Does it make FSQ easier to understand and share?
4. Is there user or metric evidence supporting it?
5. Is its maintenance cost and compatibility risk acceptable for 0.1.x?

Open decisions

• Confirm or revise the primary 0.1.x objective.
• Define growth baselines and target values.
• Assign an owner and cadence for weekly metric review.
• Choose the first new Provider.
• Decide whether Anthropic direct support or an OpenAI-compatible endpoint comes next.
• Define the minimum stable Coding Agent contract.
• Confirm the P0 Runs scope.
• Define a successful first-use session.
• Confirm or revise the proposed 0.1.1–0.1.3 sequence.
• Confirm the explicit out-of-scope list.

Decision log

Date	Decision	Rationale	Owner	Follow-up
—	—	—	—	—

Please comment on individual priorities, propose concrete evidence, and call out anything that should move between P0, P1, P2, or out of scope.