创建 PiscesOS Website / Desktop 工具，处理独立后台、两种账户与权限、数据库、动态 Server 地址及 ZIP 更新；包含新版 Skill 库后台规则。
Instructions
---
name: piscesos-tool-builder
description: Build and update PiscesOS tools using shared web/Desktop HTML packages or independent Windows applications, with the appropriate update source, file handling and optional Server backend.
metadata:
version: "1.0.37"
---
# PiscesOS Tool Builder
Choose the runtime from the requested behavior, then deliver a verified application package. Use English for new UI, comments and release documentation unless the user requests another language. Preserve existing localization, package IDs, accounts, backend data and migration hashes.
## Choose the delivery
| Required behavior | Delivery |
| --- | --- |
| The same tool UI on Website and Desktop, using existing host capabilities | Shared HTML/CSS/JS in a `piscesos-tool` ZIP. Desktop runs it in its Windows executable host. |
| An application that must run with Desktop closed or own its native file/NAS/Shell functions | A portable Windows application with `runtime=windows-native`, executable entry and its own updater. HTML/CSS can still be its renderer. |
| A Windows application with an existing Server backend and web UI | One combined application/backend ZIP, retaining the existing package and database identities. |
| A BIOS-owned built-in tool module | `piscesos-native-tool` with `app.mjs`; only the trusted BIOS publisher releases it. |
An HTML package hosted by Desktop is not a standalone EXE. An EXE wrapper alone does not implement native functions, file receivers or automatic updates. Do not convert an existing tool merely to satisfy a label; select the simplest delivery that meets the user's requirements.
Read [references/update-authority.md](references/update-authority.md) before implementing updates or default-file handling. Official PiscesOS applications check BIOS directly for program updates. Company-uploaded packages use their company Server. User-added installed Windows programs are excluded from managed updates. The program's update source is separate from the user's business database and authentication source.
## Implement the selected mode
- For shared HTML, read [references/runtime.md](references/runtime.md) and [references/hosted-workflow.md](references/hosted-workflow.md). Use `assets/starter/` and `scripts/package_tool.py`. The starter is an example, not a finished business backend.
- For an independent application, read [references/windows-applications.md](references/windows-applications.md). Build its portable runtime, native functions, file receiver and startup updater before using `scripts/package_application.py`.
- For a native application with Server authentication/backend, read [references/combined-applications.md](references/combined-applications.md). Minimum integration: Desktop 0.5.66 / Server 0.4.50 / Website 1.24.88. Server derives the client-only archive; ordinary clients never receive PHP, SQL or private state.
- For a full Server-hosted backend, read [references/server-hosted-package.md](references/server-hosted-package.md) and [references/app-backend-and-packages.md](references/app-backend-and-packages.md). Deliver frontend, backend, administration and migrations in one supported ZIP. Do not replace this with a connector plus manual deployment unless the user requests that arrangement.
Use the actual target repository's `tool-manager.php`, `fleet.php`, `api/fleet.php`, `tool-database.php`, `native/tool-preload.cjs` and tool IPC in `native/main.cjs` as the contract. Do not invent SDK methods or manifest fields. Preserve original icon artwork and names; Windows titles omit internal IDs. Platform and category assignments determine availability, while users arrange their authorized workspace.
## Conditional capabilities
Read only the references needed for the requested tool:
- Persistence and databases: [data-ownership.md](references/data-ownership.md), [database.md](references/database.md). Host window state and tool business data have different owners.
- Login, users and permissions: [accounts-backend.md](references/accounts-backend.md), [groups-and-delegation.md](references/groups-and-delegation.md). Reuse current Server/Enterprise identity where supported; verify issuer, scope and subject on the backend. Frontend roles and usernames are not authorization.
- Scheduled jobs, imports and scanning: [background-work.md](references/background-work.md). Do not add a service to a simple file/library tool without a concrete need.
- Languages and Windows integration: [languages.md](references/languages.md), [host-compatibility.md](references/host-compatibility.md).
- Hosted original UNC files: [native-files.md](references/native-files.md). Use the authorized current-user resolver, not arbitrary-path IPC.
- Hosted offline assets and account index snapshots: [hosted-offline.md](references/hosted-offline.md).
- Hosted NAS tags, previews and native Shell menus: [desktop-nas.md](references/desktop-nas.md). This host contract requires tool integration; an independent application implements its own native engine.
- Shared fonts, PDF text editing and typography: [fonts.md](references/fonts.md). Basic fonts sync gently after Desktop installation; Extra fonts are fetched on demand. Reuse the shared local cache and let BIOS discover approved missing families. Never run font-package installers.
Do not abandon an authorized backend, administrator UI or shared database when later requests concern the frontend. Keep configured protocol, port and subdirectory; do not scan for another server. Offline operation must retain account boundaries and distinguish connection failure from explicit authorization denial.
## Design: Apple-directed UI and application artwork
For substantive UI or icon design, remind the user that Figma is the preferred editable workspace and follow [Figma access and fallback](references/design-access.md): connected Figma tools first, then an authorized Chrome Figma session, then independent local design if neither is usable. Respect code-only/no-computer-control instructions. Missing Figma access must not prevent the requested implementation and package delivery.
Use the user's selected [Apple iOS 27 community design system](references/apple-ios27-community.md) and current Apple HIG as the primary visual direction for PiscesOS interfaces and app artwork. Retain [Material Design 3](https://m3.material.io/) as a supplementary adaptive-layout, interaction and accessibility reference. Read [references/design-language.md](references/design-language.md) and relevant [Material references](references/material-design.md). Support exactly computer, tablet and phone with appropriate input and layout. Preserve native Windows behavior.
For application icons, preserve the user's accepted simple identities with restrained glass material on both their selected shell and primary content. Read [references/apple-hig.md](references/apple-hig.md) and relevant official Apple chapters and learning sessions before proposing artwork. Read [references/icons.md](references/icons.md) for concept, optical balance, glass materials, rendering and coordinated appearances. Recognition takes priority over extra mechanisms, micro-detail or layers.
Start Apple design study at [Apple Design](https://developer.apple.com/design/), including HIG, Design Resources, Icon Composer and relevant learning videos. For Figma-assisted app design or a supplied Figma Design/Make link, read [references/figma-app-workflow.md](references/figma-app-workflow.md). It routes to available official Figma skills for editable screens, components, themes and design-to-code, with a portable fallback when those skills or the connector are unavailable. Figma assists design and implementation; the selected PiscesOS runtime, backend and packaging contracts still apply.
Keep application artwork separate from interface symbols. Existing licensed Material Symbols can remain a coherent interface family where suitable; they do not select the whole visual system. A Windows/web icon does not universally require an enclosing tile; preserve the user's selected glass shell for accepted artwork. Native Apple app icons follow actual platform templates. Retain editable clean layers and a separate host-specific compositor; the Windows/web static adaptation is not Apple's dynamic Liquid Glass. Technical PNG/ICO dimensions remain transport constraints. Do not revive retired PiscesOS safe grids, gradient or palette recipes.
This is design only. Preserve runtime selection, package formats, updates, authentication, databases, font services and functions. The explicit UI request changes the visual reference, not the implementation framework. Use [references/piscesos-suite.md](references/piscesos-suite.md) across BIOS, company web, main web, Desktop and Server. Verify renderer capabilities and label approximations instead of assuming native Apple behavior from a kit's appearance.
For shell work, read [Desktop shell and Settings behavior](references/piscesos-desktop-shell.md); these launcher-specific rules do not prescribe every tool's layout. For existing tool artwork, read [Current artwork decisions](references/piscesos-current-artwork.md). Preserve effective scale, scroll position, current workspace and user data during UI updates and asynchronous checks.
## Verify and deliver
Read [references/icon-updates.md](references/icon-updates.md) when packaging artwork or implementing updates. Set `icon: "icon.png"`; the package scripts generate checksum-protected `icon_update` metadata. Include the same master in web, Desktop and Windows icon resources. Desktop 0.5.84 / Server 0.4.57 / Website 1.24.112 support the explicit declaration and visible managed-tool update checks.
Read [references/release.md](references/release.md). Keep the stable package ID, increment numeric versions for changed code, and verify archive paths, CRC and SHA-256 against the real importer. Verify upgrades preserve user data and settings; failed or corrupt downloads retain the last verified release. Download and verify before closing a running managed tool; restart with the same data profile. User-added Windows programs are never terminated for managed updates.
For shared HTML default-file handling, verify the supported Desktop receiver with a real file argument. For standalone delivery, launch the EXE with Desktop closed and test its own updater. A working web preview does not prove Desktop updated, and a packaged updater library does not prove its callbacks or restart work. Report actual checks and untested integration honestly.
Provide package, version, SHA-256, update source, required host versions and release notes. Do not imply permission to publish or install merely because packaging is complete. Skill library content ZIPs contain this skill folder and are distinct from application installation ZIPs; they do not install themselves into a Codex profile.
