OpenDCAI · Huangdingcheng · Apr 21, 2026 · Apr 30, 2026
diff --git a/docs/editable_ppt_presentagent.md b/docs/editable_ppt_presentagent.md
@@ -0,0 +1,42 @@
+# Editable PPT PresentAgent Options
+
+ThinkFlow exposes a small PresentAgent option surface for editable PPT generation.
+
+For optional online PPTX editing through ONLYOFFICE, see `docs/onlyoffice-editable-ppt.md`.
+
+## User-Facing Options
+
+- `model_profile`: `general`, `claude`, or `qwen`.
+- `coder_mode`: `library` or `direct`. If omitted, ThinkFlow defaults to `library`.
+- `language`: `chinese` or `english`.
+- `complexity`: `simple`, `balanced`, or `complex`.
+- `target_slides`: positive integer page target.
+
+## Qwen Behavior
+
+- `model_profile=qwen` uses the local LLM backend.
+- `model_profile=qwen` with omitted `coder_mode` defaults to `library`.
+- `model_profile=qwen,coder_mode=library` is mapped inside the vendored PresentAgent CLI to the Qwen recipe library pipeline: `QwenRecipeCoder`, `QwenRecipeRenderer`, harness, audit, and `QwenRecipeRefiner`.
+- `model_profile=qwen,coder_mode=direct` remains available and uses the direct generation path with the local Qwen backend.
+
+## Local Qwen Model Files
+
+Model weights are not committed. For the built-in local Qwen server, download:
+
+`Qwen3.5-27B-Claude-4.6-Opus-Reasoning-Distilled`
+
+to:
+
+`vendor/presentagent/models/Qwen3.5-27B-Claude-4.6-Opus-Reasoning-Distilled/`
+
+The directory must contain `config.json`, tokenizer files, and model weight files. Then start the local server from `vendor/presentagent`:
+
+```bash
+./run_local_qwen35_c500_server.sh
+```
+
+The script defaults to `http://127.0.0.1:18081/v1`, matching ThinkFlow's default `PRESENT_AGENT_LOCAL_LLM_API_BASE`. To use another local model directory, set `LOCAL_QWEN35_C500_MODEL_DIR`. To use an already running OpenAI-compatible Qwen service, set `PRESENT_AGENT_LOCAL_LLM_API_BASE` and `PRESENT_AGENT_LOCAL_LLM_MODEL`.
+
+## Option Boundary
+
+Qwen mode selection is represented only by the public pair `model_profile=qwen` and `coder_mode=library|direct`.
diff --git a/docs/onlyoffice-editable-ppt.md b/docs/onlyoffice-editable-ppt.md
@@ -0,0 +1,79 @@
+# ONLYOFFICE Editable PPT Deployment
+
+ThinkFlow editable PPT can optionally embed ONLYOFFICE Document Server for manual PPTX editing. If ONLYOFFICE is not configured, users can still download the generated PPTX.
+
+## Required Settings
+
+Configure these in `fastapi_app/.env` or the deployment environment:
+
+```bash
+ONLYOFFICE_DOCUMENT_SERVER_URL=/onlyoffice
+ONLYOFFICE_THINKFLOW_PUBLIC_URL=http://host.docker.internal:8213
+ONLYOFFICE_DOCUMENT_DOWNLOAD_BASE_URL=http://172.18.0.1:3003
+ONLYOFFICE_JWT_SECRET=
+```
+
+- `ONLYOFFICE_DOCUMENT_SERVER_URL`: browser-side Document Server entry. For local Vite development, use `/onlyoffice` so browser requests go through the frontend proxy.
+- `ONLYOFFICE_THINKFLOW_PUBLIC_URL`: ThinkFlow backend URL reachable from the Document Server container. It is used for save callbacks.
+- `ONLYOFFICE_DOCUMENT_DOWNLOAD_BASE_URL`: browser-facing URL used by ONLYOFFICE to download the PPTX. In local Vite development this should point at the frontend origin so cache and document URLs stay same-origin.
+- `ONLYOFFICE_JWT_SECRET`: set this only when Document Server JWT is enabled, and keep it identical to the Document Server secret.
+
+## Local Docker Deployment
+
+Start Document Server:
+
+```bash
+docker run -d --name thinkflow-onlyoffice \
+  -p 8082:80 \
+  --add-host=host.docker.internal:host-gateway \
+  -e JWT_ENABLED=false \
+  -e ALLOW_PRIVATE_IP_ADDRESS=true \
+  onlyoffice/documentserver:latest
+```
+
+For local Vite development, `frontend_zh/vite.config.ts` proxies `/onlyoffice` to `http://localhost:8082`. Configure Document Server cache URLs to stay on the frontend origin:
+
+```bash
+docker cp thinkflow-onlyoffice:/etc/onlyoffice/documentserver/local.json /tmp/thinkflow-onlyoffice-local.json
+python - <<'PY'
+import json
+from pathlib import Path
+
+path = Path("/tmp/thinkflow-onlyoffice-local.json")
+data = json.loads(path.read_text())
+storage = data.setdefault("storage", {})
+storage["externalHost"] = "http://localhost:3003/onlyoffice"
+storage["useDirectStorageUrls"] = False
+path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+PY
+docker cp /tmp/thinkflow-onlyoffice-local.json thinkflow-onlyoffice:/etc/onlyoffice/documentserver/local.json
+docker exec thinkflow-onlyoffice supervisorctl restart ds:docservice ds:converter
+```
+
+This avoids browser-side failures where ONLYOFFICE returns cache URLs such as `localhost:8082/cache/.../Editor.bin` while the editor is embedded from the frontend origin.
+
+## ThinkFlow Endpoints
+
+Editable PPT uses these backend endpoints:
+
+- `GET /api/v1/kb/outputs/{output_id}/onlyoffice/config`
+- `GET|HEAD /api/v1/kb/outputs/{output_id}/onlyoffice/download/{document_key}.pptx`
+- `POST /api/v1/kb/outputs/{output_id}/onlyoffice/callback`
+
+The callback downloads ONLYOFFICE's saved PPTX and writes it back to the output storage. PPTX edits are not reverse-synced into PresentAgent IR in this version.
+
+## Production Notes
+
+- Put Document Server behind the same HTTPS domain or a trusted internal URL.
+- Enable Document Server JWT in production and set `ONLYOFFICE_JWT_SECRET` to the same secret in ThinkFlow.
+- Ensure Document Server can reach `ONLYOFFICE_THINKFLOW_PUBLIC_URL` and the browser can reach `ONLYOFFICE_DOCUMENT_SERVER_URL`.
+- Do not commit local container dumps such as `.onlyoffice_*.json`, `.oo_*`, or runtime logs. They are debugging artifacts, not deployable config.
+
+## Quick Check
+
+1. Create or generate an `editable_ppt` output.
+2. Open the output workspace.
+3. Click `在线编辑 PPTX`.
+4. Confirm the editor loads and saves back through the callback.
+
+If the editor reports download error `-4`, re-check `storage.externalHost`, `ONLYOFFICE_DOCUMENT_DOWNLOAD_BASE_URL`, and the `/onlyoffice` proxy.
diff --git a/docs/superpowers/plans/2026-04-20-thinkflow-flashcard-upgrade.md b/docs/superpowers/plans/2026-04-20-thinkflow-flashcard-upgrade.md
@@ -0,0 +1,81 @@
+# ThinkFlow Flashcard Upgrade Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Implement flashcard generation controls, structured citations, persisted generation settings, and synced CN/EN flashcard UX.
+
+**Architecture:** Extend the backend flashcard schema and persistence first so both direct API generation and outputs-v2 generation emit the same `generation_config` and card-level `citations`. Then update the Chinese workspace flow and English flashcard modal to consume the same structure and reuse existing source preview logic.
+
+**Tech Stack:** FastAPI, Pydantic, React, TypeScript, CSS, Framer Motion
+
+---
+
+### Task 1: Backend flashcard schema and generation metadata
+
+**Files:**
+- Modify: `fastapi_app/schemas.py`
+- Modify: `fastapi_app/services/flashcard_service.py`
+- Modify: `fastapi_app/routers/kb.py`
+
+- [x] **Step 1: Extend flashcard models with citation and generation config fields**
+
+- [x] **Step 2: Update LLM prompt and response parser to preserve `[1][2]` answers plus structured `citations`**
+
+- [x] **Step 3: Persist `generation_config` in `flashcards.json` and API response payload**
+
+### Task 2: outputs-v2 flashcard config threading
+
+**Files:**
+- Modify: `fastapi_app/routers/kb_outputs_v2.py`
+- Modify: `fastapi_app/services/output_v2_service.py`
+
+- [x] **Step 1: Let outputs-v2 outline requests accept `flashcard_config`**
+
+- [x] **Step 2: Save `flashcard_config` in output items and forward it into flashcard generation**
+
+- [x] **Step 3: Preserve legacy flashcard `generation_config` when scanning old outputs**
+
+### Task 3: Chinese flashcard study UX
+
+**Files:**
+- Modify: `frontend_zh/src/components/ThinkFlowFlashcardStudy.tsx`
+- Modify: `frontend_zh/src/components/ThinkFlowWorkspace.tsx`
+- Modify: `frontend_zh/src/components/ThinkFlowWorkspace.css`
+- Modify: `frontend_zh/src/components/thinkflow-types.ts`
+
+- [x] **Step 1: Parse flashcard citations and generation config from output results**
+
+- [x] **Step 2: Add generation controls to the flashcard direct-output confirmation flow**
+
+- [x] **Step 3: Render interactive citations, citation preview panel, open-full-source action, and upgraded card visuals**
+
+### Task 4: English flashcard sync
+
+**Files:**
+- Modify: `frontend_en/src/pages/NotebookView.tsx`
+- Modify: `frontend_en/src/components/flashcards/FlashcardViewer.tsx`
+
+- [x] **Step 1: Extend flashcard settings panel with difficulty, card count, topic, and test focus**
+
+- [x] **Step 2: Forward new settings to `/generate-flashcards` and load persisted `generation_config`**
+
+- [x] **Step 3: Render interactive citations and generation settings in the English flashcard viewer**
+
+### Task 5: Verification
+
+**Files:**
+- Verify: `fastapi_app/schemas.py`
+- Verify: `fastapi_app/services/flashcard_service.py`
+- Verify: `fastapi_app/routers/kb.py`
+- Verify: `fastapi_app/routers/kb_outputs_v2.py`
+- Verify: `fastapi_app/services/output_v2_service.py`
+- Verify: `frontend_zh/src/components/ThinkFlowFlashcardStudy.tsx`
+- Verify: `frontend_zh/src/components/ThinkFlowWorkspace.tsx`
+- Verify: `frontend_en/src/pages/NotebookView.tsx`
+- Verify: `frontend_en/src/components/flashcards/FlashcardViewer.tsx`
+
+- [ ] **Step 1: Run focused Python compile checks**
+
+- [ ] **Step 2: Run frontend TypeScript/build checks where available**
+
+- [ ] **Step 3: Review diff for CN/EN parity and remaining compatibility risks**
diff --git a/docs/superpowers/plans/2026-04-27-thinkflow-editable-ppt.md b/docs/superpowers/plans/2026-04-27-thinkflow-editable-ppt.md
@@ -0,0 +1,98 @@
+# ThinkFlow Editable PPT Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build the first usable `可编辑PPT` output path by vendoring the stable PresentAgent CLI/runtime into ThinkFlow and exposing its editable PPTX plus IR artifacts in the Chinese frontend.
+
+**Architecture:** Add a backend service that prepares ThinkFlow context, invokes the vendored PresentAgent CLI, discovers artifacts, and stores them in outputs-v2. Extend the existing output manifest model with `editable_ppt` and add a frontend workspace that is independent from the old image-based PPT stage rail.
+
+**Tech Stack:** FastAPI, Python subprocess/pathlib/json, pytest, React 18, TypeScript, Vite, lucide-react.
+
+---
+
+### Task 0: Vendor PresentAgent Runtime
+
+**Files:**
+- Create: `vendor/presentagent/`
+- Modify: `fastapi_app/config/settings.py`
+- Modify: `fastapi_app/services/editable_ppt_service.py`
+- Test: `tests/test_editable_ppt_service.py`
+
+- [x] Vendor PresentAgent CLI/runtime files needed by Step1-Step5 for `general`/`claude` direct/library and `qwen` direct/library.
+- [x] Exclude generated outputs, caches, sample PDFs/PPTX, and model weights; include qwen recipe library/harness source.
+- [x] Remove the internal `qwen_lib` CLI entry from the vendored runtime; expose Qwen library through `model_profile=qwen,coder_mode=library`.
+- [x] Default `EditablePPTService` to `<project_root>/vendor/presentagent`; keep `PRESENT_AGENT_ROOT` as explicit override.
+- [x] Move PresentAgent runtime defaults into `fastapi_app/config/settings.py`.
+
+### Task 1: Backend PresentAgent Wrapper
+
+**Files:**
+- Create: `fastapi_app/services/editable_ppt_service.py`
+- Test: `tests/test_editable_ppt_service.py`
+
+- [x] Write tests for command construction, Qwen library/direct mode selection, artifact URL payloads, and local Qwen defaults.
+- [x] Run `pytest -q tests/test_editable_ppt_service.py` and verify failures are about missing service.
+- [x] Implement `EditablePPTService` with `build_context_markdown`, `normalize_request`, `run_presentagent`, and `discover_artifacts`.
+- [x] Run `pytest -q tests/test_editable_ppt_service.py` and verify it passes.
+
+### Task 2: OutputV2 Integration
+
+**Files:**
+- Modify: `fastapi_app/services/output_v2_service.py`
+- Test: `tests/test_output_v2_editable_ppt.py`
+
+- [x] Write tests proving `editable_ppt` is supported, creates a lightweight output record, and dispatches generation to `EditablePPTService`.
+- [x] Run `pytest -q tests/test_output_v2_editable_ppt.py` and verify failures are about unsupported output type or missing dispatch.
+- [x] Extend `SUPPORTED_TYPES`, `create_outline`, and `generate_output` for `editable_ppt`.
+- [x] Run `pytest -q tests/test_output_v2_editable_ppt.py` and verify it passes.
+
+### Task 3: Frontend Type And Entry
+
+**Files:**
+- Modify: `frontend_zh/src/components/thinkflow-types.ts`
+- Modify: `frontend_zh/src/components/ThinkFlowWorkspace.tsx`
+
+- [x] Add `editable_ppt` to local and shared output types.
+- [x] Add a `可编辑PPT` output button and icon.
+- [x] Ensure `resolveOutputCreationInputs` treats `editable_ppt` like `ppt` for source/document requirements.
+- [x] Ensure `createOutline` routes `editable_ppt` into the output workspace and can auto-generate.
+
+### Task 4: Frontend Editable PPT Workspace
+
+**Files:**
+- Modify: `frontend_zh/src/components/ThinkFlowWorkspace.tsx`
+- Modify: `frontend_zh/src/components/ThinkFlowWorkspace.css`
+
+- [x] Add state for editable PPT options: model profile, coder mode, language, complexity, and target slide count.
+- [x] Render a separate workspace for `editable_ppt`.
+- [x] Render generation controls before result exists.
+- [x] Render PPTX download links and IR JSON links after generation.
+- [x] Render editable deck/slide IR fields and persist edits in component state.
+
+### Task 5: Verification
+
+**Files:**
+- Verify: backend tests
+- Verify: frontend build
+
+- [x] Run `pytest -q tests/test_editable_ppt_service.py tests/test_output_v2_editable_ppt.py`.
+- [x] Run `npm run build` from `frontend_zh`.
+- [x] Check `git status --short` and confirm only intended files were changed, aside from pre-existing unrelated files.
+
+### Task 6: ONLYOFFICE PPTX Editor
+
+**Files:**
+- Modify: `fastapi_app/config/settings.py`
+- Modify: `fastapi_app/services/output_v2_service.py`
+- Modify: `fastapi_app/routers/kb_outputs_v2.py`
+- Modify: `frontend_zh/src/components/ThinkFlowWorkspace.tsx`
+- Modify: `frontend_zh/src/components/ThinkFlowWorkspace.css`
+- Test: `tests/test_output_v2_editable_ppt.py`
+
+- [x] Add ONLYOFFICE settings for Document Server URL, ThinkFlow public URL, and optional JWT secret.
+- [x] Add backend config endpoint for editable PPTX ONLYOFFICE editor config.
+- [x] Add backend callback endpoint that saves ONLYOFFICE-returned PPTX back to output storage.
+- [x] Add frontend `在线编辑 PPTX` action and embedded editor panel.
+- [x] Keep PPTX download fallback when ONLYOFFICE is not configured.
+- [x] Route Document Server browser assets through the Vite `/onlyoffice` proxy and configure `storage.externalHost` so editor cache files stay on the frontend origin.
+- [x] Use a real same-origin `/online-editor-frame.html` iframe, per-open `editor_session_id`, and PPTX LibreOffice normalization to avoid stale sessions and ONLYOFFICE PPTX parser failures.