claw/docs/superpowers/specs/2026-04-06-zhihu-hotlist-post-export-auto-open-design.md

Zhihu Hotlist Post-Export Auto-Open Design

Background

The current Zhihu hotlist workflows already support two separate artifact outputs:

• openxml_office generates a local .xlsx file for hotlist export
• screen_html_export generates a local .html dashboard for presentation

Today, the workflow stops after artifact generation and returns a summary string such as:

• 已导出知乎热榜 Excel <path>
• 已生成知乎热榜大屏 <path>

That means the user still has to manually open the generated file.

The user wants one additional post-export action, but only one at a time:

1. for Excel-oriented tasks, automatically open the generated .xlsx with the system default spreadsheet application
2. for dashboard-oriented tasks, automatically open the generated local dashboard HTML inside the running sgBrowser session

This is an exclusive choice, not a combined mode.

Current Runtime Facts

The implementation must match the current browser/runtime boundary that already exists in the repo:

• the active service submit path in src/service/server.rs constructs BrowserCallbackBackend
• BrowserCallbackBackend::invoke(Action::Navigate, ...) currently emits sgBrowerserOpenPage, which opens a new visible browser tab and keeps the helper page alive
• WsBrowserBackend::invoke(Action::Navigate, ...) has different semantics and a different transport path from the callback-host service path
• MacPolicy::validate(...) currently rejects empty or non-domain values, so a raw file://... navigation cannot pass through the normal domain validation path today
• screen_html_export already returns presentation.url, which is the existing file:// presentation URL contract for the generated dashboard

Those facts mean the design must not promise "replace the helper page" or "reuse identical tab behavior across all backends". The required success path for this slice is narrower: open the generated dashboard automatically in the current callback-host-backed sgBrowser service session without adding a new user-facing surface.

Problem Statement

The existing workflow logic in src/compat/workflow_executor.rs already separates hotlist export from dashboard generation, but it treats both routes as artifact-only flows. The last mile is missing:

• the Excel route does not auto-open the generated file
• the dashboard route does not consume the generated dashboard presentation URL and open it automatically in the browser runtime

The risk is scope drift. This change must not:

• turn Excel-open and dashboard-open into a combined workflow
• add new help/help-like user-visible surfaces
• move orchestration into frontend/service-console/
• modify the websocket protocol
• modify browser-helper.html
• modify callback-host HTTP endpoints or their contracts
• change the artifact-generation contract of openxml_office or screen_html_export

Goal

Extend the existing Zhihu hotlist post-export behavior so that:

• Excel tasks generate .xlsx and then auto-open it with the local system default spreadsheet application
• dashboard tasks generate .html and then auto-open that generated dashboard inside sgBrowser

On the current callback-host service path, "inside sgBrowser" means opening the generated dashboard in a new visible browser tab while the helper page stays alive. The user does not need to open the file manually.

Non-goals

This slice does not include:

• opening Excel and dashboard in the same run
• adding a new combined route that auto-opens both artifacts
• adding any new help, helper, or user-visible assistance surface
• modifying frontend/service-console/sg_claw_service_console.html
• modifying src/service/protocol.rs
• modifying browser-helper.html
• modifying /sgclaw/callback/* contracts
• turning the browser backend into a general-purpose local filesystem browser
• changing the artifact-generation JSON contract of openxml_office or screen_html_export

Chosen Approach

Keep the current two workflow routes, but add one route-specific post-export action to each:

• ZhihuHotlistExportXlsx -> generate .xlsx, then open it locally with the OS default app
• ZhihuHotlistScreen -> generate .html, then open the generated dashboard presentation URL in the browser runtime

For the dashboard route, use the existing presentation.url returned by screen_html_export as the authoritative browser-open URL. Do not invent a separate normal-path URL conversion layer when the tool already returns the presentation contract.

The compat opener must emit one exact navigate request shape for this case.

• action: Action::Navigate
• expected_domain: the exact literal __sgclaw_local_dashboard__
• params.url: the exact presentation.url returned by screen_html_export
• params.sgclaw_local_dashboard_open.source: the exact literal compat.workflow_executor
• params.sgclaw_local_dashboard_open.kind: the exact literal zhihu_hotlist_screen
• params.sgclaw_local_dashboard_open.output_path: the generated local dashboard artifact path
• params.sgclaw_local_dashboard_open.presentation_url: the same file:// URL stored in params.url

On the current callback-host-backed service path, only that exact request shape is approved for the local-dashboard special case. A plain Action::Navigate with an arbitrary file://... URL, or a request missing any one of the required marker fields above, must continue to be rejected.

Because normal MacPolicy domain validation cannot accept file://..., add a narrow local-dashboard presentation allowance in the browser backend/security boundary. That allowance must be limited to this one case:

• only for Action::Navigate
• only for generated local dashboard presentation URLs
• only for local HTML presentation, not arbitrary local paths or generic file browsing

Why this approach:

• it preserves the existing mutual exclusivity between Excel export and dashboard presentation
• it keeps artifact generation in the existing tools
• it keeps browser opening inside the existing browser backend boundary
• it uses the existing screen_html_export presentation contract instead of duplicating it
• it avoids pushing orchestration into the service console or protocol layer
• it stays compatible with the current callback-host runtime, where visible navigation is new-tab based
• it limits the guaranteed browser-open behavior in this slice to the callback-host-backed service path that the user is using today

Rejected alternatives:

• add a combined "Excel + dashboard" route: explicitly rejected by user behavior
• let frontend/service-console/ decide when to open generated files: wrong layer; the console is only a submit/view surface
• add help UI to expose output choices: explicitly unwanted by the user
• change browser-helper.html so the helper page itself becomes the dashboard: this would break the current helper-page persistence model
• promise a backend-agnostic "replace the current page" behavior: inaccurate because callback-host and websocket backends do not share identical navigate semantics
• require the websocket backend to gain matching local-dashboard visible-open behavior in this slice: outside the narrow current-service-path goal

File Responsibilities

src/compat/workflow_executor.rs

Continue to own:

• route detection for Zhihu hotlist workflows
• artifact generation orchestration
• post-export summary construction

New responsibilities in this slice:

• parse the successful artifact payloads after openxml_office and screen_html_export
• call the route-specific post-export opener only after artifact creation succeeds
• for the dashboard route, consume presentation.url from the screen_html_export result payload
• keep generation success and post-export open success/failure distinct in the returned summary

src/compat/artifact_open.rs

New helper module to keep side effects out of workflow_executor.rs.

Responsibilities:

• open a generated local .xlsx with the system default application
• open a generated local dashboard presentation URL through the existing BrowserBackend
• construct the exact approved dashboard navigate request shape used by this slice
• define the narrow local-dashboard presentation token/constants used by the compat layer and backend compatibility path
• return narrow success/failure results so workflow_executor.rs can produce accurate summaries

This module must stay small and focused. It is not a general launcher framework.

src/browser/callback_backend.rs

New narrow responsibility in this slice:

• at the BrowserCallbackBackend::invoke(Action::Navigate, params, expected_domain) entrypoint, recognize only the exact approved local-dashboard presentation request shape
• preserve the current callback-host behavior of using sgBrowerserOpenPage, which opens a new visible tab and keeps the helper page alive
• reject local-file navigate attempts that do not include the exact post-export marker payload from the compat layer

This slice must not change callback-host polling, helper bootstrap, or callback endpoint behavior.

src/browser/ws_backend.rs

No required behavior change in this slice.

Notes:

• websocket transport semantics differ from the callback-host service path
• this spec does not require websocket backend local-dashboard visible-open support
• websocket-specific parity can be designed later as a separate slice if needed

src/security/mac_policy.rs

New narrow responsibility in this slice:

• expose a small validation helper for the approved local-dashboard presentation case
• validate the real local presentation URL and artifact path for that case rather than treating file:// as a normal allowed domain
• keep the normal domain-based validation path unchanged for ordinary remote navigation

The policy layer must not turn file:// into a generally allowed "domain". This is an explicit special case for generated local dashboard presentation only.

src/compat/mod.rs

Expose the new helper module.

Route Semantics

Excel export route

Trigger examples:

• 读取知乎热榜数据，并导出 excel 文件
• 导出知乎热榜 xlsx

Expected behavior:

1. collect hotlist rows
2. call openxml_office
3. obtain output_path
4. open the generated .xlsx using the local OS default spreadsheet application
5. return a success summary reflecting both generation and open state

Summary rules:

• open succeeded -> 已导出并打开知乎热榜 Excel <path>
• open failed but file exists -> 已导出知乎热榜 Excel <path>，但自动打开失败：<reason>

The workflow still counts artifact generation as successful even if the post-export open step fails.

Dashboard route

Trigger examples:

• 读取知乎热榜数据并生成领导演示大屏
• 生成知乎热榜 dashboard
• 展示知乎热榜大屏

Expected behavior:

1. collect hotlist rows
2. call screen_html_export
3. obtain output_path
4. obtain presentation.url from the tool result payload
5. invoke the browser opener through the existing BrowserBackend
6. return a success summary reflecting both generation and browser-open state

Summary rules:

• browser open succeeded -> 已在浏览器中打开知乎热榜大屏 <path>
• browser open failed but file exists -> 已生成知乎热榜大屏 <path>，但浏览器自动打开失败：<reason>

The workflow still counts artifact generation as successful even if the browser-open step fails.

Browser Boundary

This slice must preserve the current browser/runtime boundary.

Allowed:

• use the existing BrowserBackend
• use the existing Action::Navigate
• use the existing screen_html_export presentation.url
• add a narrow compatibility path so local generated dashboard presentation can pass backend validation

Not allowed:

• change browser-helper.html
• introduce a new callback-host endpoint
• move file-opening responsibility into the frontend service console
• add a new browser-side bootstrap flow
• require websocket protocol changes

Important semantic note:

• on the current service callback-host path, dashboard open is expected to use sgBrowerserOpenPage, so the generated dashboard appears in a new visible browser tab while the helper page remains available for later tasks
• websocket-backed browser execution may continue to differ; this slice does not require matching visible-open semantics there

Local Dashboard Presentation Allowance

The local dashboard browser-open path needs an explicit narrow validation rule because file://... cannot pass the normal domain allowlist.

Requirements for the narrow allowance:

• only approved for Action::Navigate
• only approved for the exact compat marker payload described above
• only approved for generated local dashboard presentation URLs
• only approved when the validated local artifact path points to the generated dashboard HTML artifact returned by the same screen_html_export success payload
• only approved for local HTML presentation, not arbitrary executables or unrelated local files
• ordinary remote navigation must continue using the existing MacPolicy::validate(...) domain rules unchanged

This keeps the behavior small and auditable while still satisfying the user-visible dashboard auto-open requirement.

Local File Opening Boundary

The Excel auto-open action is a local runtime side effect, not a browser action.

Requirements:

• use the system default application for .xlsx
• support the current Windows environment first
• keep the implementation minimal and focused on the generated artifact path

Not required in this slice:

• a cross-platform abstraction beyond the minimal shape needed for the current repo environment
• opening arbitrary user-selected files
• exposing local file opening to the service websocket protocol

Error Handling

Excel route

If .xlsx generation fails:

• return the existing export failure

If .xlsx generation succeeds but auto-open fails:

• keep the artifact path in the summary
• mark only the auto-open step as failed
• do not delete the generated file

Dashboard route

If .html generation fails:

• return the existing screen export failure

If .html generation succeeds but browser open fails:

• keep the artifact path in the summary
• mark only the browser-open step as failed
• do not delete the generated file

If the tool result is missing presentation.url:

• treat that as a protocol error in the post-export open step for this route
• keep the generated artifact path in the summary if it is available
• do not silently invent a different contract in the normal path

Test Strategy

Workflow tests

Update or add focused workflow coverage so that:

• Excel workflow still calls openxml_office
• dashboard workflow still calls screen_html_export
• the two routes remain mutually exclusive
• dashboard workflow consumes the tool's existing presentation.url

New Excel post-export test

Add a focused regression proving:

• an Excel-oriented hotlist request triggers export
• the generated .xlsx path is passed into the local default-app opener
• no browser dashboard navigate is triggered for that route

New dashboard post-export test

Add a focused regression proving:

• a dashboard-oriented hotlist request triggers HTML generation
• the generated tool payload presentation.url is used for browser open
• the browser backend receives a local-dashboard navigate request through the approved compat path
• no local spreadsheet opener is triggered for that route

Backend/security compatibility tests

Add focused regressions proving:

• callback backend accepts the approved local-dashboard navigate case and still emits sgBrowerserOpenPage
• the narrow local-dashboard allowance rejects non-local or malformed URLs
• ordinary domain validation behavior remains unchanged for normal remote navigation

Existing boundary tests remain unchanged

Do not change the service-console boundary guard. This slice is runtime behavior only.

Acceptance Criteria

The slice is complete when all of the following are true:

1. Excel hotlist export still generates a local .xlsx artifact.
2. Excel hotlist export auto-opens that .xlsx with the system default spreadsheet application.
3. Dashboard hotlist export still generates a local .html artifact.
4. Dashboard hotlist export consumes the existing screen_html_export presentation.url and auto-opens it in the current callback-host-backed sgBrowser service session.
5. On the current callback-host service path, the dashboard opens automatically in a visible browser tab without breaking the helper-page runtime.
6. Excel-open and dashboard-open remain separate user-chosen flows, not a combined mode.
7. No new help/help-like user-visible surface is added.
8. The service console, websocket protocol, browser-helper.html, and callback-host endpoint surface remain untouched.