Skip to content

jaytonkogeru/huandeng

v0.24.0MIT

Create and refine Story-driven scientific slides in the open HUANDENG project, with reviewable proposals and one shared editor writer.

HUANDENG Plugin

A shared Story workflow for Codex, Claude Code, official DeepSeek Harness and ChatGPT through an authorized workstation connection. Agents read the open PPTD, construct reviewable changes, and save through the same writer as the editor. The package contains no model executor or separate document store.

Start from the open project

Open the intended .pptd in HUANDENG. The desktop Agent setup toolbar action generates a client-specific connection fragment. Copy it into the intended client's configuration without replacing unrelated settings. The generator does not install, enable or connect a client.

For a checkout or copied plugin, the equivalent is:

node /absolute/plugin/scripts/configure.mjs --client codex --entry /absolute/project/deck.pptd
node /absolute/plugin/scripts/doctor.mjs --entry /absolute/project/deck.pptd

Use codex, claude, deepseek-native, chatgpt, or generic mcp. The legacy deepseek option remains a compatibility patch. Output is native TOML for Codex, JSON for Claude/generic MCP, a JSON-formatted YAML configuration patch for DeepSeek, and a CLI parameter template for ChatGPT. Commands accept --cli, --install-dir, --url, and --runtime-dir when explicit routing is needed. Diagnostics go to stderr; stdout contains only the requested configuration or result.

The runtime resolver supports both a source checkout and resources/app/plugins/huandeng beside the installed node_modules/@open-slide/core. A copied plugin now discovers the local running Editor, a registered installation, or a standard installation directory. Use --install-dir / HUANDENG_INSTALL_DIR or --cli / HUANDENG_CLI to choose explicitly. Invalid explicit paths never fall back. HUANDENG_ENTRY pins an absolute Project path; if omitted, the launcher can bind exactly one verified active Project. Multiple Projects or installations require a choice. Each connection remains pinned until it is restarted. When configuration is generated by HUANDENG's executable, it uses that executable with ELECTRON_RUN_AS_NODE=1; a separate Node installation is not required for that generated connection. Generic portable manifests use node and require Node compatible with the core package.

doctor starts the real stdio bridge, reads its tool/resource list and Story guide, and confirms the deck identity. It reports protocolVerified: true and modelTaskVerified: false: a successful connection is distinct from a successful task in a particular agent client. Reconnect the client with the verified updated CLI to refresh its MCP tool set. Restart the Editor only when an authorized update changes the writer or interface itself; a client-side tool addition can use an existing compatible writer.

Client adapters

ClientPackaged connectionWhat must be checked in the actual client
CodexPortable plugin.json / mcp.json, .codex-plugin compatibility manifest, or generated TOMLLoad the Story skill and call huandeng_context against the intended project
Claude Code.claude-plugin/plugin.json, .mcp.json, shared skills/Local plugin loading or generated MCP fragment, then a real tool call
DeepSeek HarnessNative huandeng bundle, with a compatibility Cordis patch for explicit headless routingActual host loading, Project routes, skill reads and a real native task
ChatGPT with DC-WALTPrivate account package with the existing app binding and shared skillVerify account component discovery, then call the installed CLI through the selected workstation

The editor's loopback /__pptd service is a document API, not a Streamable HTTP MCP endpoint. No public endpoint or new tunnel is needed for these local connections. A portable manifest does not make private workstation executables available to ChatGPT Web by itself.

Independent image acquisition

When present in the advertised tool list, huandeng_asset_import imports an original public HTTPS image or supplied base64 bytes into the bound Project. It returns the actual asset path, dimensions, revision and acquisition source. Downloads reject credentials and local/private/reserved destinations, validate redirects and pin DNS resolution; type, size and time limits apply. The existing writer validates image bytes, including SVG safety, and performs the import. No slide is inserted.

huandeng_editor_capture captures the actual complete web Editor in an isolated browser, using existing page/object IDs and enumerated view, sidebar, Inspector, language and viewport choices. It blocks writes and global human-selection broadcasts, then imports the PNG through that same writer. It accepts no JavaScript, arbitrary URL, file destination or click script. Native Electron dialogs such as Agent setup are outside this capture interface. Management views retain their real Inspector visibility. Each author chooses the source and state; no prepared image collection is supplied.

Editor and plugin 0.23 use local protocol 2. Upgrade the matching Editor, CLI and plugin together, then reconnect the intended Project. Old discovery records are rejected explicitly; there is no fallback to an anonymous session. A failed network or browser action remains an explicit capability failure; it does not authorize changes to permissions or a different workstation.

Codex

The generated fragment supplies [mcp_servers.huandeng] with explicit executable, arguments and environment. Merge that one server into the existing configuration. Load this repository-owned plugin through the client's supported local plugin mechanism, or make skills/huandeng-story available in a supported skill root. The skill and the runtime resources teach the same workflow; an MCP-only connection still receives server instructions and can read the guides.

The portable layout follows OpenAI's plugin packaging documentation. Its root mcp.json declares type: stdio and runs the relative launcher with the plugin root as its working directory. The compatibility manifest points at .codex.mcp.json, which names the environment variables to forward; the Claude manifest uses its supported ${CLAUDE_PLUGIN_ROOT} path. Portable hosts may sanitize ambient environment variables, so supply the explicit entry/runtime values through that host's settings or use the generated client-native fragment. Neither manifest creates client configuration automatically.

Claude Code

With the intended Editor open (or explicit HUANDENG_ENTRY and runtime selection):

claude --plugin-dir /absolute/path/to/huandeng/plugin
claude plugin validate /absolute/path/to/huandeng/plugin

The plugin contains the discoverable huandeng-story skill. Alternatively, merge the generated mcpServers.huandeng fragment into the intended scope and load the same skill. Avoid registering both connections under conflicting names. Client-specific tool permissions remain under the client's normal controls. See Claude's plugin reference.

Official DeepSeek Harness

Use the native huandeng bundle for official DeepSeek Harness. The current adapter targets the actual DSH 0.2.2-rc.1 host. It incorporates the user's native prototype, carries the shared skill and scripts, and reconciles open Projects without starting another writer.

Build with node plugins/huandeng/scripts/build-deepseek.mjs --output <new-absolute-directory>, then use the running profile's official Plugin Manager to install the resulting huandeng package. For an existing installation, inspect its exact identity and manager result before replacement. Do not hand-edit the profile or infer live success from a saved package. The detailed lifecycle, configuration, locale/icon packaging and verification contract is in the native adapter guide.

Once installed, configure.mjs --client deepseek-native --entry <absolute.pptd> generates an override for the existing huandeng row. Default bundle discovery exposes verified open Projects under stable, entry-derived namespaces. Explicit entries narrow a task to its intended Projects. A changed origin/epoch rebuilds only that Project's bridge; a transient failed scan retains routes.

For a profile that does not load the native bundle, configure.mjs --client deepseek --entry <absolute.pptd> still generates the earlier raw MCP/skill --patch. It is a compatibility route, not a native bundle installation. Do not combine it with this bundle in the same registration scope. Keep the existing account, permissions and model route; a separate DSH_HOME is not required for ordinary use.

A successful skill catalog, MCP transport or Project context call does not prove that a model followed guidance or visually reviewed slides. Verify the actual skill/resource reads, Project identity, tool results and authored output separately. Text-only routes cannot claim image inspection.

ChatGPT through the existing workstation

Read skills/huandeng-story/SKILL.md and run the generated command/argument arrays through the authorized DC-WALT connection. guide story and guide operations do not require an open project; inspect, brief, preview, apply, and render attach to the explicitly selected open project. Preserve the generated environment when the executable is HUANDENG/Electron. Do not treat the configuration output as a shell string: pass argument arrays or quote for the host shell correctly.

The private ChatGPT package binds the existing authorized workstation app and the shared Story skill. It creates no server, reverse proxy, public endpoint or new tunnel. The account package deliberately omits local stdio MCP configuration, since a web host cannot start the workstation executable directly. The portable local package has no account app binding. In a local Codex session, prefer the local Editor even when the account also has a THUG connection. Account creation, host installation, and a successful authoring task are separate validation outcomes.

Story-driven manufacturing

The discoverable skill is skills/huandeng-story/SKILL.md. The runtime's current canonical guides are:

  • huandeng://guide/story — audience, question, supplied evidence, takeaway, preservation constraints, revision-aware authoring and verification.
  • huandeng://guide/operations — the actual transaction language, Story/project structures, Main/presentation identity, click build effects and limits.

Read context, the author's complete supplied account, scoped Story, pages and actual presentation occurrences. Establish the presentation's job before selecting its sequence: interpret the author's reasoning, reorganize weak transitions and add verified details the audience needs. A product introduction must explain what the tool is, how to use it and why its design helps; a coherent retelling alone is insufficient. Keep a preservation inventory of useful evidence, visuals, icons and acknowledgments. When bilingual correspondence is requested, map substantive claims, demonstrations and user steps before separate layout work. When independent editions are requested, let each argument determine its sequence and page boundaries instead of imposing a translated page map. Keep facts and necessary attribution accurate in both. Use Main/Presentation Story for purpose and constraints and Notes for the spoken explanation. Distinguish personal observations from verified facts. Use focused dotted patches and the revisions required for touched resources. Preview the exact payload, inspect its impact and apply when editing is authorized. Read/render the result, inspect editable prose/table structures, and test interactive builds in the real show when present.

A page UUID identifies reusable content. An occurrence identifies one appearance, while position can change. A live Main edit affects live references; usedBy entries with versionId identify pinned artwork unaffected by that live edit. Presentation-local notes belong to the occurrence. Use explicit independent pages or named-version pins when different artwork is needed; no additional visual-variant feature is implied.

Use native table objects for genuine row/column relationships. Do not build fake tables out of aligned text boxes, lines or cell shapes; use one rich-text object for ordinary paragraphs or lists where practical. Purposeful scientific multi-panel compositions and explanatory diagrams remain available. Structured PPTD inspection does not remove actual visual review.

Agent Story metadata records an interpretation, not human approval. Review-only requests stop at a proposal. An already authorized edit does not require a second invented permission gate.

Proposal contract

huandeng_preview accepts {transaction} and runs the same validation/planning logic as the writer. It returns previewHash, baseline revisions, actual field/file/page changes, reuse impact, creation count and diagnostics. It does not save pages or metadata, capture external versions, create a receipt/history/checkpoint, emit a commit event, or consume an operation ID. Creation identities in a preview are provisional; use the real apply response's createdPages for future transactions.

The output includes at most 200 changes/files/diagnostics, 100 page impacts and 50 uses per page. Serialized values above 2000 characters are marked clipped. Totals and truncation are explicit. The original transaction is never clipped. Narrow a large proposal or inspect its complete JSON before applying. This preview is structural, not a rendered before/after picture.

huandeng_apply accepts {transaction, previewHash?}. When provided, the hash must match every transaction field exactly. The existing writer then rechecks CAS, supports identical request retries, and retains its recovery/Undo/history behavior. A matching hash identifies the payload; it is not approval. Legacy apply calls without a hash remain supported. After a conflict, re-read and form a fresh proposal that preserves intervening work.

CLI equivalents:

huandeng guide story
huandeng guide operations
huandeng --entry /path/deck.pptd inspect
huandeng --entry /path/deck.pptd brief
huandeng --entry /path/deck.pptd brief PAGE_UUID --presentation talk --occurrence OCCURRENCE_ID
huandeng --entry /path/deck.pptd preview /path/proposal.json
huandeng --entry /path/deck.pptd apply /path/proposal.json --preview-hash sha256:RETURNED_HASH
huandeng --entry /path/deck.pptd review RETURNED_OPERATION_ID --page PAGE_UUID
huandeng --entry /path/deck.pptd render PAGE_UUID

Optional review in the Editor

For a user-requested review before saving, use huandeng --entry /path/deck.pptd propose /path/transaction.json --title "Review title". This saves a pending proposal and leaves project documents unchanged. proposals lists records; proposals PROPOSAL_ID reads one without receiving approval authority.

The user opens Activity → Review proposals to compare actual before/after slides, Notes, fields and live/pinned uses. Accepting runs the same shared writer with the reviewed page and asset baseline. Rejecting leaves the document unchanged. Independent page patches or Notes may be selected as whole page groups, producing a new preview that must be reviewed separately. Structural changes stay together. Split proposals whose affected pages exceed the complete review limit.

A changed Project, writer session or referenced resource requires a fresh proposal with a new requestId. The Editor binds its one-use acceptance record to the selected proposal and writer; an Agent cannot manufacture that record by supplying an actor or approvedBy string. Ordinary authorized preview/apply remains available. See review and conflict guidance.

Tool surface

The v0.18 bridge advertises 22 tools. Legacy huanding_* names and huandeng_frame_record still dispatch without being advertised twice.

ToolPurpose
huandeng_contextDeck identity, Main pages, revisions, organization and diagnostics
huandeng_activity_readRecent task reports and actual writer records for this Project
huandeng_activity_reportExplicit client progress tied to a Project, conversation and task
huandeng_story_briefingFour Story layers, exact occurrence, neighbors, used-by, assets and revisions
huandeng_presentation_readComplete resolved sequence, repeated pages, notes and pins
huandeng_assets_listSearch project assets, source names, usages and missing references
huandeng_design_auditRead advisory type sizes, backgrounds, requested dividers and image sampling; never edits or approves
huandeng_page_readCurrent Main content, object IDs and revision
huandeng_selection_readHuman selection and presentation/occurrence context
huandeng_story_recordCompatibility tool for a separate agent intent record
huandeng_previewNon-writing exact transaction preview and payload hash
huandeng_applyShared writer, optional preview hash, CAS and idempotence
huandeng_renderCommitted Main or exact occurrence PNG
huandeng_historyNamed versions and granular operations
huandeng_reviewExact saved-operation before/after data and bounded changes; read-only
huandeng_version_recordNamed milestone with archived local assets
huandeng_version_restoreRestore through a new transaction
huandeng_revertConflict-checked operation undo
huandeng_projectFile tree with explicit truncation
huandeng_exportStatic PDF/PPTX or optional asynchronous MP4
huandeng_export_statusExport progress and result
huandeng_export_cancelCancel active video delivery

Asset search is paginated (hasMore) and may report a directory-scan truncated flag. unused means unreferenced by current Main pages, not safe to delete: versions or other projects may still use it. The tools never infer deletion safety.

Click-driven builds are the presentation workflow. Static PNG/PDF/PPTX retain the base pose and do not preserve interactive animation. The retained MP4 compatibility path is a timed silent H.264 export, not live click delivery. Protocol presence does not prove any particular model client loaded the plugin or completed a task; consult the milestone validation report for actual evidence.

First-Slide Sections and private Projects

The editor and CLI share the same authoring service. Read the running guide operations before replacing Project organization. In editor 0.11, startPageId binds a Section to an existing first Slide and resolves its members through the next Section start. Preserve legacy range / pageIds definitions unless the task explicitly converts them. The existing preview/apply workflow works with this model; no additional plugin service is required.

Treat research files, figures, rendered slides, file manifests, and client paths as private Project data. Keep them in the user's Project or an explicitly chosen local working directory. Editor release evidence uses synthetic fixtures; do not copy private Project content into this repository.

Portable discovery and package delivery (0.12)

Run node scripts/discover.mjs to list this computer's verified active Projects and discovered installed runtime. This reads only local discovery records and loopback session identity; it never prints session tokens. To remember an installation outside standard directories, run node scripts/register-runtime.mjs --install-dir <absolute Editor directory>. The resulting machine-local pointer is outside the plugin and contains no Project path or credentials. Opening the Windows Editor is sufficient for running-process discovery. macOS/Linux use standard locations or an explicit installation pointer.

build-package.mjs --target local --output <new absolute directory> copies an explicit allowlist into a self-contained huandeng directory. The private account variant is --target chatgpt --app-id <verified existing app ID>. It contains the same skill and current logo, an existing-workstation binding, and no local MCP server. Archive only that generated directory, with the archive outside it. Do not upload the repository or a Project directory. The builder excludes test fixtures, generated proposals, client configuration, local registration and private source data.

For native local installation, put the generated local package in a dedicated local marketplace and register it with each client's supported CLI. The Codex catalog uses .agents/plugins/marketplace.json; Claude uses .claude-plugin/marketplace.json. Entries reference the package by a relative path. Install with codex plugin marketplace add <marketplace-directory> followed by codex plugin add huandeng@huandeng-local --json, or claude plugin install huandeng --marketplace <marketplace-directory> --scope user --json. Installing that catalog does not change other marketplaces or permissions. For DeepSeek Harness, build and install the native bundle through the current profile Plugin Manager; preserve existing account/model settings. The generated raw Cordis --patch is a compatibility alternative for profiles without that bundle.

Source formats and native installation are documented by OpenAI and Claude Code. Inspect the installed client help before an install or upgrade, since host configuration formats can change.

Project activity and visual review

The runtime exposes huandeng_activity_read and huandeng_activity_report for explicit per-Project task stages. Each conversation keeps its own session ID and explicit PPTD entry; a visible tab switch does not reroute it. Shared-writer save receipts are distinct from client reports.

The authoring skill now requires inspection of approved reference pages, concrete typography and spacing, evidence-preserving composition, actual rendered review, and meaningful versions only for changed pages. See skills/huandeng-story/references/scientific-design.md.

Editor v0.14 connects Layout preview → shared-writer save → Activity receipt → visual Before/After review → current-page/object navigation. The Layout task uses project image thumbnails and a full composed preview. The review dialog uses the actual page renderer and distinguishes live and pinned usage. Current-asset and fallback-theme limitations remain visible; unavailable history is never replaced with the current page.

Clients can include up to 20 exact operationIds in a progress report. These are explicit claims resolved against this Project's journal, not timestamp associations. See skills/huandeng-story/references/connected-review.md for the complete workflow and the separate levels of setup, protocol, save, structure, rendering, export and human approval.

Canonical Editorial Standard and quality gate (0.24)

Global positive/negative design rules live in one registry: packages/core/src/pptd/editorial-standard.json. Run pnpm sync:editorial, or pnpm check:editorial to detect drift. The build produces both the Skill's references/editorial-standard.md and the MCP huandeng://guide/editorial content from that exact registry; neither file is an independent policy source. The running writer's huandeng_design_audit now reports gentle, rule-ID-linked anti-pattern signals, including repeated three-card layouts and footer disclaimer furniture. Use huandeng_authoring_gate for prototype/release validation against saved render revisions and explicit per-page visual observations; it never claims to prove visual inspection or author acceptance. Do not treat advisory signal counts as an AI-feel score. Project root AGENTS.md adds its own approved style and exceptions only.

Deliberate design workflow (plugin 0.18.2)

Start a new empty Project with huandeng init /absolute/new-directory --title 'Project title', then open its returned entry in HUANDENG. Existing targets are refused. Desktop and CLI initialization share the same folder layout and AGENTS.md source.

Use Audit → Spec → Implement → Validate → Release, proportionate to the task. Read the author's actual requirements and Project policy, audit references and assets, then specify the argument, preservation inventory and visual direction. Frame representative compositions within Spec and inspect their first renders before expanding through preview/apply. Integrate teaching within a story-driven brief rather than replacing the story with a tutorial. Never rewrite the author's policy to fit an agent plan. Use the production-design and asset-evidence references for language-specific typography, a coherent background system, purposeful imagery/icons/diagrams and real UI captures. A white or sparse page is not a quality criterion. Include actual title-only divider slides when the Project requests them, with no watermark, footer or ornament. Locate teaching crops within the real whole interface and use comparable frames for visual comparisons. Generate scientific plots with professional tools from verified data. When author trials require independent acquisition, each author collects and captures its own active assets; shared preloads do not satisfy that requirement.

Use huandeng --entry /project/deck.pptd quality --language zh-CN for a collection-wide measured review. Add --background or --require-section-dividers only when the Project explicitly requests those policies. Add --presentation ID for the exact presentation, including repeated/pinned appearances. --max-title and --max-body override 960-normalized advisory thresholds. A quality report neither edits slides nor establishes visual quality or author acceptance. Keep structural checks, agent visual review, Office verification and the author's actual response distinct. For batch visual review, render each affected stable page or exact occurrence and inspect a contact sheet plus full-size pages; retain the saved operation IDs.

Packages include content-manifest.json with SHA-256 hashes. Doctor reports the loaded plugin version, Story skill hash, package correspondence, runtime Story-guide hash and design-audit availability. Native and account transports differ; their shared Story/design reference bytes must agree at release. Installed-cache edits are not a release workflow.