soia-cwork-processon-diagrams

ProcessOn diagram browsing and export

Read team spaces, folders, diagram titles, and visible content through the skill's own ProcessOn browser profile; export diagrams within the user-specified scope, safely archive downloads to the delivery directory, and generate a verifiable manifest for local POS, image, SVG, PDF, and XMind files. Read-only by default; do not modify, share, move, or delete remote files; formal batch tasks must not take over the customer's Chrome in use.

Customer-readable description

What this skill can do

Customer wants	Skill will do	Customer can see
Inventory team space	Recurse from the specified node to every subdirectory and leaf file, save in small batches, and audit recovery status	Markdown/JSON tree, progress snapshots, omission diff set, permission gaps, and completion receipt
See what is in the diagram	Enter the "Browse" view to read accessible text, and use screenshots to verify the visual layout	Content summary, key text, and screenshots
Export diagrams	Select VSDX, POS, PNG, SVG, PDF, XMind, or Office formats according to customer authorization	Downloaded files, format/size/SHA-256 acceptance
Archive browser downloads	Parse paths from CLI, environment variables, and private YAML, and have Playwright write directly to managed staging by run/artifact; after verification, archive without copying on the same file system	staging/final path, transfer mode, SHA-256, and audit manifest
Batch resume archiving	Initialize the download queue from the archive plan, claim items one by one, record success/failure/blocked, and replay the audit	`download-progress.json`, next batch list, and mechanical acceptance results
Close out abnormal tail orders	Retry failed/blocked items using an exact artifact whitelist; for same-name items within the plan, generate sequential confirmation bound to the plan SHA; for unknown types, only observe the fixed provider icon	Targeted batch receipt, collision confirmation file, unknown-type observation list; ambiguous and safety items will not be forcibly counted as successful
Controlled concurrent archiving	Within one skill-dedicated context, fix and reuse 1–2 headless worker pages; downloads may be concurrent, while archiving and progress remain single-writer	Concurrency proof, per-batch receipt, popup/worker closure reconciliation, and progress mirror
Long-task resume supervision	Run proven small batches sequentially; continue only after each batch is audited, and host interruptions can be recovered from private supervision state	`archive-supervisor-state.json`, per-batch status, and stop reason
Control the browser without interference	Invoke the local Playwright runner from any AI/terminal, executing headless in the skill-dedicated profile	Independent login state, page closure count, download receipt; the customer's main Chrome is not taken over
Parse existing exports	Read local POS/XMind/SVG/images; VSDX can be handed off to an optional draw.io/Visio skill	Title, diagram type, node text, dimensions, and checksum

How customers use it

The customer provides the minimum necessary portion of the following information:

ProcessOn team, folder, or diagram URL; a space name and file name may also be provided.
Target action: initial inventory, incremental inventory, download archive, or parse/convert an existing exported file.
When exporting, specify the file scope, format, and delivery directory; if no format is specified, flowcharts default to the Visio option currently available in the menu .vsdx, and mind maps default to .xmind. For both types, it is recommended to also keep POS as a native ProcessOn structure backup. When the type cannot be confirmed from icons, browse view, or menu, only write it to the "pending manual confirmation" list; do not guess the format or download automatically. Prioritize SVG/high-resolution PNG for visual reuse, and PDF for review delivery.
On first use, the client only needs to manually enter the username, password, SMS code, or verification code in thestandalone ProcessOn windowthat pops up from the runner; after success, the window closes automatically, and subsequent batches default to headless. The skill does not read, record, or output Cookies, Local Storage, password files, or credentials.
Optionally copy the path configuration template to a private configuration directory, fixing the temporary download, final delivery, audit manifest, and retention days.

Example:

初始化盘点这个 ProcessOn 团队空间，只读，不下载：<team-url>
对上次盘点和今天重新审计后的快照做增量盘点，不猜测删除项
按已审计计划下载已确认流程图为 VSDX、思维导图为 XMind，归档到 <output-dir>
解析 <export-dir> 里的 POS，或把 VSDX 转成 draw.io 真源后升级

Dependencies and Installation

First-time use requires installing Playwright, preparing a ProcessOn login profile, and configuring the output directory; see the full steps at setup.md。

Install the entire domain (Claude Code and Codex share the same domain plugin):

claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-cwork-office@soia

Install only this one skill:

npx skills add soia-team/soia-open-cwork-office-skills -g -a '*' -s soia-cwork-processon-diagrams -y

WorkBuddy 's loading unit is a role-based expert rather than a plugin,npx skills add -a '*' cannot cover it, and it needs to be installed separately; see docs/install/workbuddy.md。

Logs and Completion Receipt

Each run must report at least:

The space/folder scope read, as well as the number of folders, diagrams, and restricted items found.
During preview, what is actually seen may be DOM text, thumbnails, browse view, or exported POS; do not treat thumbnail OCR as structured source text.
When exporting, report the requested format, actual format, success/failure counts, file sizes, and verification results by category.
When archiving, report the browser's actual download path, final delivery path, copy/move mode, duplicate-name handling, manifest path, and SHA-256.
When cleaning up, first report the number of dry-run candidates; actual cleanup only handles temporary directories marked with the skill, and generates a deletion audit manifest.
Security verification, membership format restrictions, insufficient permissions, or page structure changes must be listed separately and must not be disguised as success.
Each batch must report the browser mode, dedicated profile,pages_seen_at_start、stale_pages_closed、scoped_pages_opened/closed and pages_closed_at_exit; if the close count is abnormal, the batch must not claim completion.
If the editor export entry is delayed or missing, the receipt must include the restricted editor_export_controls_unavailable diagnostic; if the VSDX package structure is valid but content provenance binding cannot be completed, it may only enter private blocked evidence, and must not be written to the final knowledge base directory or counted as completed.
Both normal completion and abnormal exit must return a close receipt; if the error JSON lacks receipt , only "cleanup unverified" may be reported, and the next item must not be processed. The same ProcessOn title may have multiple DOM nodes, andwait_text must use an explicit nth to eliminate strict ambiguity.
In addition to native button/link/role, the snapshot must also read title、aria-label、data-title、data-tooltip -annotated non-button icons; do not fall back to fixed coordinates just because the toolbar is implemented with span/div.
The current ProcessOn flowchart row simultaneously has the old version .icon-a-444_huaban1 and the new red UI .icon-a-222_huaban1 markers; both must pass asynchronous-safe fixed allowlist detection, and synchronous generator expressions cannot be used.
For semantically meaningless icons, only the fixed read-only inspect_text can first be used to inspect the title row ancestors and direct child nodes; the action file must not pass in JavaScript, and the inspection results may only be used to implement constrained provider actions, and must not open arbitrary CSS clicks.
The ProcessOn file row's "More" may only use provider-scoped row_menu: locate the nearest file_list_itemby visible title, then click the same-row menu trigger verified by the real DOM; generic action files still cannot pass CSS. Text actions by default filter out hidden duplicate nodes before applying nth。
status、snapshot and run After initial navigation, you must wait for a bounded SPA settle (default 2000ms); an empty snapshot may only report "page not rendered/needs review" and must not be used to generate click actions.
Full inventory must report "the set of subdirectories declared by the parent directory − the set actually visited"; if the difference set is nonempty, only "partially complete" may be written.
The completion receipt must come from audit the mechanical result after replaying all immutable batches; it cannot rely solely on checkpoint statistics or a browser page claiming completion.
Directory inventory and source file archiving must be reported in stages:inventory_completed_asset_archive_pending is not "knowledge base archiving complete".
Before asset archiving, an archiving plan must be generated from the final checkpoint;ready_for_known_artifacts controls downloads of confirmed types,ready_for_archive only after unknown types are also cleared is true。
Formal downloads must first initialize download-progress.json, and immediately after each artifact is completed or blocked, record/mark; the sole progress must not be maintained only in the conversation, the browser download list, or the knowledge base Markdown.
Each download, in download.save_as() after, before final archiving, must first write a private artifact-level staging receipt; after an abnormal process exit, the next batch run will only recover files that simultaneously have that receipt, source URL/remote ID, file path isolation, byte count, and structural validation. Old staging files without a receipt are never automatically archived.
For long tasks, processon_archive_supervisor.py can be used to launch bounded small batches sequentially; each batch replays audit and writes a private archive-supervisor-state.json. It will only mark artifacts explicitly recorded item by item in the batch JSON as BatchError: no visible ProcessOn download menu matched: Xmind文件 as failed with the same immutable receipt; all other pending, collision, structural error, or non-JSON exits stop immediately for diagnosis, and are never silently skipped.
Incremental inventory must report the SHA-256 of two complete snapshots, added, changed, and removed candidates; it is not a ProcessOn event/API increment. Without stable remote_id/id you must not claim a file "moved"; only report added/removed candidates.
The final reply gives the delivery directory, verification method, and unfinished items; do not output accounts, cookies, tokens, or browser internal state.

Runtime boundaries

Default is read-only. Browsing, searching, screenshots, and downloads are allowed actions; editing, renaming, copying, moving, deleting, locking, inviting collaboration, and public sharing must be explicitly authorized by the customer in the current request.
Formal batches may only use a skill-dedicated profile; attaching the customer's default Chrome profile is prohibited, and using Codex/Claude's browser, computer-use, or extensions to repeatedly open and close tabs in the customer's main Chrome is prohibited. The dedicated runner defaults to headless; use headed only for the first login, a real visible CAPTCHA, or when the customer explicitly asks to observe.
When the dedicated context starts, keep only one parent page; at most one temporary popup is allowed, and it must be closed within the nested action finally ; on success, failure, timeout, Ctrl-C, and SIGTERM, all dedicated pages and the context must be closed. After a soft interrupt, verify the closure receipt before resuming.
Before downloading, confirm the target file, format, and delivery location. If the customer has already explicitly requested the export in the current request, there is no need to reconfirm the same scope.
Only process files the customer has the right to access. Do not expand the visible scope by guessing URLs, internal interfaces, cookies, or undisclosed endpoints.
Prefer ProcessOn's official UI and official documentation. When ordinary accounts do not have a public REST API for team files, do not package reverse-engineered interfaces as a stable API.
Stop automated interaction only when a CAPTCHA/slider control actually appears in the current viewport and blocks or obstructs the target operation, and preserve the page for the customer to take over; the presence in the DOM of display:none, a zero-size preloaded iframe, or one moved outside the viewport does not mean “the CAPTCHA has popped up.” Do not simulate dragging, call CAPTCHA interfaces, or bypass verification.
Do not ask the customer to send passwords into the conversation; do not write usernames, passwords, cookies, tokens, login state, or browser profiles into configuration, command parameters, logs, or manifests.
Single file finalize is copied by default and automatically renamed when the name is the same; formal processon_archive_batch.py must be archived from skill-tagged staging using no-copy move, and fail closed when the temporary root and delivery root are not on the same file system. Overwriting must simultaneously use --collision overwrite --allow-overwrite, and the customer must explicitly authorize it in the current request.
Temporary cleanup must explicitly execute cleanup; if there is no skill tag, the delivery directory is inside the temporary directory, or it is a symbolic link file, always refuse.

Private information and intermediate data

ProcessOn diagrams, directory names, authors, and exported files may all contain internal company information; by default, inventory appears only in stdout/customer-specified reports and is not written to the public skill repository.
Usernames, passwords, SMS codes, cookies, tokens, Local Storage, and browser profiles are left to the browser/provider itself to store; this skill does not read, copy, or record them.
The skill-dedicated profile is by default located under the user's private config root; it is local login state held by ProcessOn/the browser and does not enter the public repository, run package, or knowledge base. The runner rejects the default Chrome/Chromium profile and non-empty directories without a skill tag.
Temporary downloads use the skill-managed staging specified in the configuration; for formal batches, it is recommended to place staging in a controlled subdirectory of the delivery root so that after download.save_as() it can be archived without copying on the same file system. The secure default still uses the operating system temporary directory; a formal move across file systems will stop and require customer configuration. Deliverables go in the customer-specified directory, and the audit manifest goes in the user state directory. For retention period and path resolution, see Download archiving workflow。
Long browser tasks are batched by system/top-level directory, and by default a run package is created in ${XDG_STATE_HOME:-~/.local/state}/soia-cwork-processon-diagrams/runs/<run-id>/ ; each batch immediately persists the raw batch and checkpoint. After a session interruption, resume from pending_paths , without relying on volatile memory to store the sole inventory results.
Asset archive progress is fixed-written into the run package's artifacts/download-progress.json; the state script uses an exclusive lock to guarantee a single writer, records the completed, failed, blocked, and pending-confirmation queues, and recovers from the same plan fingerprint.
The run package is an intermediate control plane, not the knowledge base body; the knowledge base only receives the frozen inventory, the final artifact manifest, and validated delivery files.

Failure gates solidified by this execution

Before executing a complex team space, first read Failure mode reference. The following rules are hard gates:

"Full" must recurse to leaf directories; first-level pages, old browsing sessions, or model memory cannot replace a checkpoint.
Multiple Agents only perform read-only page analysis in parallel; the same run package's record、audit and state files can only be executed serially by a single writer.
Only CAPTCHAs that are truly visible in the current viewport and block the operation cause a pause; hidden/zero-size/out-of-viewport iframes do not count as popups, and verification must not be bypassed.
The user logs in manually; the Agent does not receive passwords, does not read Cookies/Tokens/profiles, and does not inject credentials through CDP or extensions.
When the chart type cannot be proven by cards, the browse view, or menus, retain unknown, and enter the manual confirmation queue.
Passing the directory audit only means the inventory stage is complete; download, format validation, SHA-256, manifest, draw.io conversion, and preview belong to the independent artifact_archive stage.
Host browser capability is not the main executor; batch tasks must be started from a dedicated runner. Every popup and the entire context must have a close receipt; a missing receipt is treated as an interruption pending recovery.

Workflow (strictly in three stages)

1. `inventory`: initial inventory or incremental inventory

1.1 Access and initial inventory (`inventory.init`）

First look for the ProcessOn official connector, public API, or CLI; when there is no dedicated capability that satisfies the current task, use processon_browser_runner.py and the skill-specific profile. The first login is completed manually by the customer only in a separate runner window; input values, Cookies, Tokens, or profiles are not read, and no Chrome extension is needed. The host browser/computer-use can only perform one-time diagnosis after explicit customer authorization and cannot take on the batch main flow.
Use the runner status/snapshot to open the customer URL (if not provided, enter from "My Files/Team Space"), and confirm the target space is visible. If login or a security verification truly visible in the current viewport blocks it, use a separate headed session to wait for the customer to take over; hidden iframes do not count as popups. Read ProcessOn capabilities and formats before operating.
init must first create a new run package; use BFS/DFS to recurse from the specified root to leaves. Every 3–6 directories visited, writeComplete directory snapshotas an immutable batch, then record; do not keep the only inventory solely in the browser session. For format, recovery, and audit, see Recursive inventory intermediate state。
At each level, record the logical full path, subdirectories, chart title, type, author, update time, visible thumbnail/access restrictions. Folders are entered by clicking; when deep-level breadcrumbs are collapsed, the logical path still prevails. The virtual list stops only when two consecutive scrolls add no new entries.
Run audit to replay batches. Only when discovered_paths - visited_paths - blocked_paths = 0 and blocked=0 do you obtain a usable complete snapshot and receipt.md; otherwise you can only report a partial inventory.

python3 scripts/processon_inventory_state.py init \
  --run-id '<run-id>' --root-path '<logical-root>' --source-url '<team-url>'
python3 scripts/processon_inventory_state.py audit --run-dir <run-dir>

1.2 Incremental inventory (`inventory.incremental`）

ProcessOn ordinary team space has no public file event API it can rely on; "incremental" islocal diff of two complete, audited snapshots, not scanning only one directory level, and certainly not guessing remote changes.
First re-run a inventory.init complete inventory with the same scope and pass audit, then compare the before and after checkpoints:

python3 scripts/diff_processon_inventory.py \
  --previous <previous-run>/inventory/checkpoint.json \
  --current <current-run>/inventory/checkpoint.json \
  --output <current-run>/analysis/inventory-delta.json

The diff script rejects pending or blocked snapshots, cross-root/cross-URL comparisons, symbolic links, and duplicate stable IDs; output added、changed、removed_candidates and the SHA-256 of both checkpoints. Only entries with a stable remote_id/id may report moved/renamed; entries without IDs do not fabricate move relationships. Duplicate ID-less identities are isolated into ambiguous_entriesand do not participate in any change conclusion.removed_candidates are candidates pending review and will not automatically delete local archives.

2. `archive`: download and archive confirmed source files

Only after stage 1 produceslatest, complete, and audit-passedcheckpoint does it begin. For complete steps (asset plan generation and validation, resumable transfer queue, download and archive, failure gates), see archive-stage.md。

3. `analyze`: parse, convert, or upgrade only after being asked

After stage 2 completes an artifact, first ask the user whether they want to "archive only, extract structure, convert, or upgrade the diagram". Without instructions, do not automatically parse, modify diagrams, or open the editor.

User goal / file	Invocation route	Output and boundaries
Content inventory of POS, XMind, SVG, images, and PDF	This skill `inspect_processon_export.py`	Reads only titles, node text, dimensions, and checksums; thumbnail-level evidence cannot impersonate structured source text
Reading VSDX, converting to draw.io, editable upgrade	`soia-dev-drawio-visio-diagrams`	First verify VSDX before converting `.drawio` true source; any graphic upgrade must have a specific user goal
Only need to view the diagram	ProcessOn "Browse" view or export preview	Record DOM text, visual screenshots, or thumbnail evidence, and distinguish explicit text from layout inference

When the browser is unavailable, the account is not logged in, or a genuine visible security verification has not been completed, have the customer manually export VSDX/POS/PNG/PDF/XMind, then continue from the local archive entry point in stage 2.

Verification

Static:python3 -m py_compile scripts/inspect_processon_export.py scripts/finalize_processon_download.py scripts/processon_inventory_state.py scripts/build_processon_archive_plan.py scripts/processon_archive_state.py scripts/diff_processon_inventory.py scripts/processon_browser_runner.py scripts/processon_archive_batch.py scripts/processon_archive_supervisor.py scripts/prepare_processon_collision_confirmation.py scripts/inspect_processon_unknown_types.py
Unit tests:python3 -m unittest tests.test_processon_downloads tests.test_processon_inventory_state tests.test_processon_archive_plan tests.test_processon_archive_state tests.test_processon_inventory_delta tests.test_processon_browser_runner tests.test_processon_archive_batch tests.test_processon_archive_supervisor -v, covering configuration priority, safe default paths, atomic copy, same-name rename, no-copy move/cross-disk rejection/failure rollback, reopen isolation and re-claiming, directory and asset intermediate states, plan drift rejection, failure/blocked resume, complete snapshot incremental gating, as well as primary Chrome profile rejection, sensitive action rejection, concurrent proof, collision isolation, in-file title signals, the supervisor's precise failure gating, and normal/abnormal page closure.
POS: Run with one flowchart POS and one mind map POS --format json, confirm title, category, node text, and element count.
Images: Run the script with PNG/JPEG, confirm width, height, and SHA-256.
Archiving: With real export files, run finalize --dry-run and finalizein sequence, verify the delivered file SHA-256 and manifest; do not write fixture paths into public documents.
Remote: verify at least once “open the team space → read the file list → right-click to see browse/download”; if security verification blocks export, the conclusion must be written as “remote read verified, full export pending manual verification to continue”.
Non-interfering browser: run with a temporary dedicated profile status/snapshot smoke; verify that the customer's default Chrome is not in the process arguments, that stale pages started are cleaned up, and that after an abnormal action the context is fully closed. Real-account E2E must have the customer first complete a login in a separate window, and must not copy the main Chrome profile.
Recursion: use at least three levels of directories to verify that the discovered/visited difference set is 0; simulate session interruption and then continue from the persisted recovery point.
Plan: run with a real checkpoint build and verify; after manually modifying the checkpoint or plan entry,verify must fail; when it contains unknown the plan must be marked as pending confirmation, allowing confirmed types to be downloaded in stages but must not claim that full archiving is ready.
Download queue: run against a real plan init and next; after recording a real archive file, run record and audit, and confirm that after restart it will not be claimed repeatedly, that counts can be recalculated, and that audit fails after modifying the file or plan.
Incremental: run the diff using two complete audit checkpoints; modifications, moves, renames, additions, and removals of candidates must be reproducible. After changing one of them to pending/blocked or injecting duplicate stable IDs, the command must fail; duplicate identities without IDs must be isolated and must not produce fake changes.
VSDX: real downloads or public samples pass ZIP/OOXML checks; when the optional draw.io skill is installed, run VSDX → .drawio → PNG forward verification again.
Structure: run repository scripts/audit_skills.py --strict, the skill validator supporting this repository's version field, and git diff --check。

reference material index

read on demand, no need to read through.

File	When to read
setup.md	First use, install dependencies and configure login profile
processon-capabilities.md	Need to confirm which formats and operations ProcessOn supports
archive-stage.md	Execute stage 2 `archive`, download and archive
download-workflow.md	Single-file download details and browser interaction
inventory-checkpoint.md	Take stock of the checkpoint structure and audit criteria
known-failure-modes.md	When encountering a failure, first check whether it is a known pattern
local-check-scripts.md	Locally verify artifact integrity