From 9e2de87d794b900c412be1dbb1497cc465c0ae70 Mon Sep 17 00:00:00 2001
From: anchenqlw <200550784+anchenqlw@users.noreply.github.com>
Date: Fri, 24 Jul 2026 11:58:53 +0800
Subject: [PATCH] Reframe README as a QCA best-practice reference

---
 README.md | 194 ++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 121 insertions(+), 73 deletions(-)

diff --git a/README.md b/README.md
index d5e65ac..ed1e3fc 100644
--- a/README.md
+++ b/README.md
@@ -1,54 +1,82 @@
 # Operra
 
-**The QCA-powered workspace for one-person companies.**<br>
-**基于 Qoder Cloud Agents（QCA）、面向一人公司（OPC）的 AI 工作台。**
+**A best-practice reference for building useful products with Qoder Cloud Agents (QCA).**<br>
+**一个展示如何基于 Qoder Cloud Agents（QCA）快速搭建可用产品的最佳实践项目。**
 
 [English](#english) · [中文](#中文)
 
-Operra turns a goal into a durable task, lets QCA work in your GitHub repository, and brings plans, approvals, progress, and artifacts back into one calm workspace.
-
-> This is the best time to build a one-person company: cloud agents can keep working, repositories can preserve business context, and a founder can operate with the leverage of a team.
+Operra is the reference application in this repository: an OPC workspace built as a thin product layer on top of QCA. The point of this project is not to introduce another agent runtime. It is to show how QCA's sessions, cloud execution, GitHub collaboration, event stream, and deployments can be assembled into a complete product experience.
 
 ---
 
 ## English
 
-### Why Operra
+### What this project demonstrates
 
-Most agent demos end at a chat transcript. A real business needs work that is inspectable, resumable, and reusable.
+[Qoder Cloud Agents](https://qoder.com/) already provides the difficult execution layer:
 
-Operra is a task-first control plane built on [Qoder Cloud Agents](https://qoder.com/). You work with **Oopz**, the operating partner in the workspace. Operra translates intent into tasks, starts QCA sessions or deployments, keeps human approval in the loop for consequential actions, and treats the resulting files and deliverables as first-class artifacts.
+- persistent agent sessions;
+- managed cloud sandboxes;
+- native collaboration with GitHub repositories;
+- streaming execution events and human-in-the-loop interactions;
+- deployments for work that should run in the cloud without keeping a local process alive.
 
-Operra does not replace QCA. It gives QCA a product surface designed for everyday company operations.
+Operra demonstrates the product layer that can be built around those capabilities:
 
-### What you get
+- turn a user's goal into a durable Task;
+- translate QCA events into readable plans, activity, review requests, and outcomes;
+- make files and artifacts the primary deliverables;
+- reconnect to an existing QCA session after a restart or network interruption;
+- use a second QCA agent as a conversational workspace operator through custom tools;
+- keep credentials, local state, and approval boundaries explicit.
 
-- **Task-first workspace** — projects, tasks, plans, activity, outcomes, and artifacts in one place.
-- **QCA-native execution** — session creation, streaming events, follow-ups, interruption, deployment runs, and reconnect support.
-- **Repository as business memory** — agents work against GitHub repositories so context and deliverables survive individual chats.
-- **Human-in-the-loop controls** — review gates for actions that need judgment or approval.
-- **Oopz operating partner** — a conversational front door that helps turn goals into executable work.
-- **Recurring outcomes** — schedules and reusable task patterns for work that should keep happening.
-- **Local control plane** — Operra runs on your machine; QCA and GitHub are contacted only for the capabilities you configure.
+The result is a working OPC workspace, but the patterns are reusable for research tools, content workflows, internal operations, customer-support workbenches, and other agent products.
 
-### How it fits together
+### Two QCA patterns in one application
 
 ```mermaid
 flowchart LR
-    U["Founder / Operator"] --> O["Operra · Oopz + Task Workspace"]
-    O --> T["Task, Plan, Review & Activity"]
-    T --> Q["Qoder Cloud Agents"]
-    Q <--> G["Your GitHub Repository"]
-    Q --> A["Artifacts & Outcomes"]
-    A --> O
+    U["User"] --> UI["Operra product UI"]
+    UI --> O["Oopz · QCA workspace operator"]
+    O --> CT["Operra custom tools"]
+    CT --> T["Projects, Tasks & Schedules"]
+    T --> A["Task QCA session / deployment"]
+    A <--> G["User GitHub repository"]
+    A --> E["Streamed events & artifacts"]
+    E --> UI
 ```
 
-### Quick start
+#### 1. QCA as the task execution runtime
+
+Each Task is backed by a QCA session or deployment. QCA works in the connected GitHub repository, streams its progress, requests input when needed, and leaves deliverables in a durable, versioned workspace.
+
+#### 2. QCA as the product's conversational operator
+
+Oopz is another QCA-powered agent. Instead of directly doing project work, it calls a small set of Operra custom tools to create projects, start Tasks, inspect status, and manage resources. This keeps the product conversation natural without putting business state inside a prompt.
+
+### What remains deliberately thin
+
+Operra does not build its own agent loop, sandbox, model router, or local coding runtime. The QCA adapter stays narrow; the rest of the code focuses on product concerns:
+
+| Concern | Reference implementation |
+|---|---|
+| QCA session, SSE, follow-up, interruption | `app/engine/qca.py` |
+| QCA endpoint and region handling | `app/engine/qca_endpoint.py` |
+| QCA deployments and provisioning | `app/engine/qca_provision.py` |
+| Task state and normalized events | `app/domain/`, `app/services/task_service.py` |
+| Dispatch, reconnect, repository sync | `app/dispatch/`, `app/engine/resilience.py` |
+| QCA-powered workspace operator | `app/operator/cloud_xiaoO.py` |
+| Custom-tool registry | `app/api/server.py` |
+| Product UI and streamed experience | `app/api/static/` |
+
+See [QCA runtime](docs/qca-runtime.md) and [Architecture](docs/architecture.md) for the complete boundary.
+
+### Run the reference application
 
 Requirements:
 
 - Python 3.11 or newer
-- A Qoder Cloud Agents run token from [Qoder integrations](https://qoder.com/account/integrations)
+- A QCA run token from [Qoder integrations](https://qoder.com/account/integrations)
 - A GitHub account; use a fine-grained personal access token in Settings, or configure your own OAuth app
 
 macOS / Linux:
@@ -67,22 +95,26 @@ cd oder-cloud-agents-opc
 .\start.ps1
 ```
 
-Open <http://127.0.0.1:8848>. The launcher creates an isolated `.venv`, installs pinned dependencies, and stores workspace data outside the repository in `~/Operra` or `%USERPROFILE%\Operra`.
+Open <http://127.0.0.1:8848>, add your QCA token and GitHub connection, create a project, and start a Task. The launcher creates an isolated `.venv`; workspace data is stored outside the repository in `~/Operra` or `%USERPROFILE%\Operra`.
 
-Optional environment variables:
+Optional:
 
 ```bash
 OPERRA_HOME=/path/to/workspace PORT=9000 ./start.sh
 ```
 
-Set `OPERRA_GITHUB_CLIENT_ID` only when you operate your own GitHub OAuth App. You can always use a fine-grained GitHub token from Settings instead.
+Set `OPERRA_GITHUB_CLIENT_ID` only if you operate your own GitHub OAuth App. A fine-grained GitHub token can always be entered in Settings.
 
-To update:
+### Use these patterns in your own QCA product
 
-```bash
-git pull --ff-only
-./start.sh
-```
+1. **Let QCA own execution.** Keep your adapter focused on authentication, sessions, event streaming, follow-ups, and deployments.
+2. **Define a product-level Task.** Do not expose transport payloads or agent internals as the user's primary mental model.
+3. **Use a repository as durable context.** Let QCA work with real files, version history, and artifacts.
+4. **Normalize events before rendering them.** Translate the QCA stream into product concepts such as plan, activity, review, failure, and outcome.
+5. **Design for reconnect and replay.** A local process restart should reconnect to the same cloud work instead of starting it again.
+6. **Keep consequential actions reviewable.** Human approval belongs in the product workflow.
+7. **Make artifacts first-class.** A useful product delivers files and outcomes, not only a transcript.
+8. **Use QCA custom tools for the control plane.** A conversational operator can manage real application state without hiding that state in model context.
 
 ### Development
 
@@ -91,52 +123,68 @@ python3.11 -m venv .venv
 source .venv/bin/activate          # Windows: .venv\Scripts\Activate.ps1
 python -m pip install -r requirements-dev.txt
 python -m pytest -q
-python scripts/e2e_ui.py           # installs/uses Playwright Chromium
+python scripts/e2e_ui.py
 ```
 
-The default test suite uses fixtures and does not require a live QCA token. See [Architecture](docs/architecture.md), [QCA runtime](docs/qca-runtime.md), and the [User guide](docs/user-guide.md).
+The default suite uses fixtures and does not require a live QCA token.
 
-### Security and data boundary
+Operra is a reference implementation rather than an official QCA SDK. QCA API behavior and authentication should follow the current Qoder documentation. Contributions that make the QCA integration patterns clearer, safer, or easier to reuse are especially welcome. See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [PRIVACY.md](PRIVACY.md).
 
-Never commit QCA or GitHub credentials. Operra prefers the operating-system credential vault and keeps project/task data in `OPERRA_HOME`, not in this source tree. Configured actions may send task context to QCA and repository content to GitHub. Read [SECURITY.md](SECURITY.md) and [PRIVACY.md](PRIVACY.md) before using sensitive data.
+Apache License 2.0. See [LICENSE](LICENSE).
 
-### Project status
+---
 
-Operra is an early open-source product, ready for source-based local use and contribution. The core QCA task lifecycle works; packaging, broader platform polish, and a plugin ecosystem are still evolving. Honest feedback and focused pull requests are welcome.
+## 中文
 
-### Contributing
+### 这个项目要展示什么
 
-Start with [CONTRIBUTING.md](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md). If you are building for an OPC workflow, describe the user outcome first—then the agent mechanics.
+[Qoder Cloud Agents](https://qoder.com/) 已经提供了搭建 Agent 产品最困难的执行层：
 
-Apache License 2.0. See [LICENSE](LICENSE).
+- 可持续的 Agent Session；
+- 托管的云端沙箱；
+- 与 GitHub 仓库的原生协作；
+- 流式执行事件与 Human-in-the-loop 交互；
+- 无需本地进程常驻的云端 Deployment。
 
----
+Operra 是这套能力之上的一个参考应用。它用很薄的产品层展示如何：
 
-## 中文
+- 把用户目标组织成可持续的 Task；
+- 将 QCA 事件翻译为人能理解的计划、活动、审核请求和结果；
+- 把文件与 Artifact 作为首要交付物；
+- 在应用重启或网络中断后接回原有 QCA Session；
+- 让另一个 QCA Agent 通过 custom tools 成为工作台的对话式运营入口；
+- 明确处理凭证、本地状态与人工审批边界。
+
+最终得到的是一个面向 OPC 的可用工作台，但这些模式同样适用于研究工具、内容工作流、内部运营、客户支持工作台和其他 Agent 产品。
 
-### 为什么做 Operra
+### 一个应用里的两种 QCA 用法
 
-多数 Agent 演示止步于一段聊天记录，但真实经营需要的是可检查、可恢复、可复用的工作。
+#### 1. QCA 作为任务执行运行时
 
-Operra 是一个以 Task 为核心、构建在 [Qoder Cloud Agents](https://qoder.com/) 之上的控制面。你通过工作台里的运营搭档 **Oopz** 发起目标；Operra 将意图组织成任务，启动 QCA session 或 deployment，把计划、审批、进度和最终产物带回同一个工作空间。
+每个 Task 对应一个 QCA Session 或 Deployment。QCA 在用户连接的 GitHub 仓库中工作，持续回传进展，在需要时请求输入，并把交付物留在可版本化、可持续使用的真实工作空间里。
 
-Operra 不替代 QCA。它为 QCA 提供了一套面向日常经营的产品界面。
+#### 2. QCA 作为产品的对话式运营入口
 
-### 为什么现在是最佳时机
+Oopz 本身也是一个由 QCA 驱动的 Agent。它不直接完成项目任务，而是调用一组小而明确的 Operra custom tools，负责创建项目、启动 Task、查询状态和管理资源。这样既能保持自然对话，又不会把业务状态藏进 prompt。
 
-云端 Agent 已经能够持续工作，GitHub 仓库可以成为长期业务记忆，而一个创始人第一次有机会用接近团队的杠杆经营公司。**现在正是构建一人公司（OPC）的最佳时间。**
+### Operra 没有重复建设什么
 
-### 核心能力
+Operra 不自研 Agent loop、沙箱、模型路由或本地 Coding Runtime。QCA adapter 保持狭窄，其余代码集中解决产品层问题：
 
-- **Task-first 工作台**：在一个地方管理项目、任务、计划、活动、结果与产物。
-- **QCA 原生执行**：支持 session 创建、事件流、追问、中断、deployment 运行与断线恢复。
-- **仓库即业务记忆**：Agent 在 GitHub 仓库中工作，业务上下文与交付物不再困在单次对话里。
-- **Human-in-the-loop**：对需要判断或授权的关键动作保留人工审核卡点。
-- **Oopz 运营搭档**：用自然语言把经营目标逐步变成可执行工作。
-- **持续性结果**：通过日程与可复用任务模式承接周期性工作。
-- **本地控制面**：Operra 在你的电脑上运行；只有你配置并使用相应能力时才会连接 QCA 与 GitHub。
+| 关注点 | 参考实现 |
+|---|---|
+| QCA Session、SSE、追问与中断 | `app/engine/qca.py` |
+| QCA Endpoint 与区域处理 | `app/engine/qca_endpoint.py` |
+| QCA Deployment 与资源准备 | `app/engine/qca_provision.py` |
+| Task 状态与事件归一化 | `app/domain/`、`app/services/task_service.py` |
+| 派发、断线恢复与仓库同步 | `app/dispatch/`、`app/engine/resilience.py` |
+| QCA 驱动的工作台运营入口 | `app/operator/cloud_xiaoO.py` |
+| Custom-tool 注册表 | `app/api/server.py` |
+| 产品界面与流式体验 | `app/api/static/` |
 
-### 快速开始
+完整边界见 [QCA 运行时](docs/qca-runtime.md)与[架构说明](docs/architecture.md)。
+
+### 运行参考应用
 
 你需要：
 
@@ -160,7 +208,7 @@ cd oder-cloud-agents-opc
 .\start.ps1
 ```
 
-打开 <http://127.0.0.1:8848>。启动脚本会创建隔离的 `.venv`、安装锁定版本的依赖，并将工作区数据放在源码仓库之外的 `~/Operra` 或 `%USERPROFILE%\Operra`。
+打开 <http://127.0.0.1:8848>，填写 QCA token、连接 GitHub、创建项目并启动一个 Task。启动脚本会创建隔离的 `.venv`；工作区数据位于源码仓库之外的 `~/Operra` 或 `%USERPROFILE%\Operra`。
 
 需要自定义工作区或端口时：
 
@@ -170,14 +218,18 @@ OPERRA_HOME=/path/to/workspace PORT=9000 ./start.sh
 
 只有在你运营自己的 GitHub OAuth App 时才需要设置 `OPERRA_GITHUB_CLIENT_ID`；也可以直接在设置页使用 fine-grained GitHub token。
 
-更新源码：
+### 用这些模式构建自己的 QCA 产品
 
-```bash
-git pull --ff-only
-./start.sh
-```
+1. **让 QCA 负责执行。** Adapter 只处理认证、Session、事件流、追问、中断与 Deployment。
+2. **定义产品级 Task。** 不要把传输 payload 或 Agent 内部机制当成用户的第一心智。
+3. **把仓库作为持久上下文。** 让 QCA 面向真实文件、版本历史与 Artifact 工作。
+4. **先归一化事件，再渲染界面。** 把 QCA 事件流翻译为计划、活动、审核、失败与结果。
+5. **把断线恢复作为默认路径。** 本地应用重启后应接回同一份云端工作，而不是重新执行。
+6. **关键动作保留人工审核。** Human-in-the-loop 应进入产品工作流。
+7. **让 Artifact 成为一等公民。** 好用的产品交付文件与结果，而不只是一段对话。
+8. **用 QCA custom tools 构建控制面。** 对话式运营 Agent 可以管理真实应用状态，不需要把状态隐藏在模型上下文中。
 
-### 开发与贡献
+### 开发
 
 ```bash
 python3.11 -m venv .venv
@@ -187,12 +239,8 @@ python -m pytest -q
 python scripts/e2e_ui.py
 ```
 
-默认测试使用 fixture，不要求真实 QCA token。更多信息见[架构说明](docs/architecture.md)、[QCA 运行时](docs/qca-runtime.md)与[用户指南](docs/user-guide.md)。
-
-Operra 目前是一个可从源码本地运行、欢迎共同建设的早期开源产品。核心 QCA 任务生命周期已经可用；安装体验、跨平台细节和插件生态仍在演进。
-
-提交贡献前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 与 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。描述新能力时，请先说明它为 OPC 用户交付什么结果，再说明 Agent 如何实现。
+默认测试使用 fixture，不要求真实 QCA token。
 
-安全与数据边界见 [SECURITY.md](SECURITY.md) 和 [PRIVACY.md](PRIVACY.md)。
+Operra 是 QCA 的参考实现，而不是官方 QCA SDK。QCA API 行为和认证方式应以 Qoder 最新文档为准。我们尤其欢迎能够让 QCA 集成模式更清晰、更安全、更容易复用的贡献。详见 [CONTRIBUTING.md](CONTRIBUTING.md)、[SECURITY.md](SECURITY.md) 和 [PRIVACY.md](PRIVACY.md)。
 
 本项目采用 Apache License 2.0，详见 [LICENSE](LICENSE)。