创建 PiscesOS Website / Desktop 工具，处理独立后台、两种账户与权限、数据库、动态 Server 地址及 ZIP 更新；包含新版 Skill 库后台规则。
Instructions
---
name: piscesos-tool-builder
description: Build and package independent Windows applications for PiscesOS, with tool-owned native functions, application updates and optional Server authentication. Includes legacy web/Server package integration when explicitly requested.
metadata:
version: "1.0.21"
---
# PiscesOS 工具开发
本 Skill 修订 1.0.18，基线 Website 1.24.34、Desktop 0.5.35、Server 0.4.38。接口以目标仓库为准；Desktop 窗口资料与工具业务数据分别上传。Server 托管工具核心库可单独选择本地或线上主库、备库和备份频率；外部自管后台必须自行实现相应接口，不能仅添加无效开关。
## Independent Windows application default (1.0.20)
For new PiscesOS computer tools, deliver an independently runnable Windows application, not a Desktop-hosted HTML package. Read [references/windows-applications.md](references/windows-applications.md) before choosing the runtime, implementing native operations or packaging releases. Use `scripts/package_application.py` on the application's portable Windows build output. Desktop manages discovery, authorized download and launch; the tool owns its native functions and can update using its own bundled updater with Desktop closed.
The HTML/PHP workflows below document legacy compatibility and explicitly requested web/Server products. They are not the default for new computer tools. Preserve an existing application's backend/data while migrating its frontend/native process; do not rewrite it merely because this skill now prefers standalone delivery. Do not promise that old HTML tools have been converted or silently discard their data.
Use Desktop 0.5.64 / Server 0.4.48 / Website 1.24.86 or newer for the Windows application package integration. User-added Windows programs are outside PiscesOS's managed update catalogue.
## 开始工作
先确定工具名称、稳定 package ID、界面能力、是否需要后台和业务数据库、是否多人共享、两种登录的适用场景及目标宿主。只补问真正缺少的产品决定。
用户已要求后台、管理员维护资料、共享业务数据库或账户权限时，将前端、后台界面、业务 API、数据迁移及后台入口一起列入交付范围。不能因用户后续补充 UI 要求而丢弃后台。只有用户明确要求原型时，才以样例数据或未连接数据库的预览作为最终成果。
如果已有 PiscesOS 仓库，先看 `tool-manager.php`、`fleet.php`、`api/fleet.php`、`tool-database.php`、`native/tool-preload.cjs` 与 `native/main.cjs` 的工具 IPC。没有仓库时采用本 Skill 的基线接口，不猜测不存在的 SDK。
选择交付形式：
| 需求 | 形式 |
| --- | --- |
| HTML/CSS/JS 本地工具 | `piscesos-tool` ZIP，可上传 BIOS 或本地 Server |
| Server 上有后台、共享数据库、角色权限的工具 | 一个完整 `piscesos-tool` ZIP：前端 + `backend/` PHP + database 迁移；读下方完整后台包规范 |
| 替换 PiscesOS 内置模块 | `piscesos-native-tool`，仅受信 BIOS 管理员发布 |
| Windows 原生 EXE / installer / portable ZIP | 按 Desktop 本机软件安装包类型登记，不冒充 HTML 工具 ZIP |
## 完整后台包：默认交付方式
用户要求在 PiscesOS Server 上传安装时，默认交付一个 ZIP，不拆成连接器与手工部署包，不要求另装 Apache、PHP、MySQL、运行 PowerShell 或覆盖程序文件。Server 0.4.26 的完整后台包协议见 [references/server-hosted-package.md](references/server-hosted-package.md)。复制 `assets/backend-starter/` 起步；用同一个打包脚本生成前端、PHP 后台和迁移清单。
静态 ZIP 未声明 backend 时仍不能执行 PHP。后台 PHP 只能放 `backend/`，由管理员上传的可信代码在 Server 执行，不能宣称是操作系统沙箱；不允许前端下载后台源码或凭据。Server 负责专用 MySQL、主库路由、备份和版本入口切换；工具负责业务 API、细粒度角色/行级权限及业务界面。
仅当用户明确要求独立部署或既有外部服务时，才使用独立业务 API；外部服务不能冒称已由 Server 安装。目标 Server 不支持新协议时，说明所需 Server 更新，保留单 ZIP 目标，不静默退回“连接器 + 手动部署”作为完成。
静态应用、Skill 内容包和旧网站后台入口区别见 [references/app-backend-and-packages.md](references/app-backend-and-packages.md)。完整后台包使用 `backend.admin`，不是旧 `admin.path`。PK Catalogue 等旧独立服务需开发者按本协议迁移，不能仅把两个旧 ZIP 套进一个 ZIP。
## 创建流程
1. 读 [references/runtime.md](references/runtime.md)，确认 Website 与 Desktop 可用接口。保留原工具图标和名称，使用原图色彩；Windows 标题不附内部 ID。
2. 复制 `assets/starter/` 到独立工具目录，修改 `tool.json` 的 package/name/version/notes。起步模板是可运行的个人偏好记事示例，不是已经接好业务账户的生产应用。
3. 涉及保存、同步、更新或备份时先读 [references/data-ownership.md](references/data-ownership.md)：宿主管窗口，工具后台管业务数据，备份由 Server 执行。有数据库时读 [references/database.md](references/database.md)。普通共享资料可用受限数据库桥接；涉及密码、个人业务数据或角色隔离时必须走有服务端鉴权的 API。
4. 有账户/权限时读 [references/accounts-backend.md](references/accounts-backend.md) 和 [references/groups-and-delegation.md](references/groups-and-delegation.md)。实现默认 user / admin 组、自建组、用户入组及个人额外权限；子用户继承与委派不能超出主账户权限。Server 托管工具默认沿用当前 Server / Enterprise 身份；不要再次要求用户输入宿主密码。只有用户明确需要独立账户时才增加软件账户，并明确与宿主身份的关联。先校验身份，再按 issuer + scope + user 建立软件身份和授权，禁止仅凭前端角色或用户名授权。没有权限设置的应用保留原行为。
5. Server/后台地址来自运行环境或用户配置；保留协议、端口和子目录。局域网默认端口 8089，但允许自定义。缺端口时提示用户确认，不自动探测或悄悄连接别的服务。
6. 编写业务界面、权限校验和参数化数据访问；保存失败保留表单，显示可重试的具体错误。
7. 在工具管理里设置可用平台（Desktop、Website 或两者）和一个或多个分类；这决定工具中心的展示，不限制用户把获授权工具加入个人工作空间。新增分类由工具中心管理，不靠硬编码到 ZIP。
8. 执行打包脚本，得到稳定 package + 新版本 + 完整 SHA-256 清单的 ZIP。
9. 按 [references/release.md](references/release.md) 验证新装、升级、账户隔离和动态地址，提供 ZIP、版本、SHA-256、更新说明与实际测试结果。
## 语言与窗口
实现可用语言后才声明 `languages`，详见 [references/languages.md](references/languages.md)。默认英文；Desktop 用户可给每个工具选择跟随系统、English、中文或 Malay，不支持时优先英文，再中文。不要翻译用户数据；切换不能丢失正在编辑的内容。
Desktop 打开工具默认显示在 Windows 任务栏，由用户在宿主设置中关闭。沿用同一个工具窗口，不额外生成替代工具。灰条与开始按钮、浮动桌面及后台入口由宿主管理，不要在工具里复制它们。网页工具由 PiscesOS Browser 打开，个人网页/程序由“我的工具”编辑和移除。
## 打包命令
```text
python scripts/package_tool.py <工具目录> <输出.zip>
```
目录必须包含 `tool.json` 和 `index.html`。`tool.json` 是打包配置，不进入运行 ZIP；脚本生成根目录 manifest.json 并逐文件计算哈希。不要把输出 ZIP 放到工具目录中。
可选数据库演示：将 `references/database.md` 的 database 段加入 tool.json；仅在已配置本地 MySQL 的 PiscesOS Server 上上传并使用。先在隔离数据库测试，不碰现有用户数据库。
## 交付标准
- URL 和业务数据不写死 IP、8089 或数据库实际库名；配置变更后可重新连接，错误不能清空全部输入。
- Server / Enterprise 账户停用、退出和工具取消分配会阻止后续后台调用；角色权限在后端重新验证。
- 前端无主库密码、Server controller key、root 凭据；日志无 token/password/PIN。
- 更新不重置用户设置、不更改已执行迁移；冲突库名由用户确认替代名，删工具默认保留数据。
- 下载/安装耗时有进度和状态，已知字节显示已传/总 MB、MB/s、百分比，未知总量用不定进度，不伪造进度。
- 不引入每秒网络检查或付费授权轮询。离线跨账户/跨数据库同步是独立设计项，不能把无连接等同于认证成功。
- 清楚区分“已实现/测试”和“待接入”。不可把现有 raw SQL 桥接说成通用安全 SSO、行级权限或自动后台部署。
- 有后台的工具交付时提供后台源文件位置、管理员实际进入路径、业务数据落库位置、完整工具 ZIP 与所需最低 Server 版本，以及“后台保存一条记录→用户前台读到→重启后仍存在→普通用户后台写入被拒绝”的实测结果。只通过前端 ZIP 校验不等于整个工具完成。
安装本 Skill：将解压后的 `piscesos-tool-builder` 文件夹放到目标 Codex 的用户 skills 目录，或在已安装的 PiscesOS Skill / Agent 工具库后台上传 Skill 内容 ZIP。新版后台只需选 ZIP，从 SKILL.md 自动读取元数据并递增版本；旧版后台仍需填写编号、名称和版本。本包不会自动安装或执行；内容 ZIP 不是 BIOS 的工具安装 ZIP。
## Current host compatibility
For business APIs, administration, scanning, imports or scheduled work, read [references/background-work.md](references/background-work.md). Server 0.4.35 is the first release with the API 1 scheduler and bounded worker. Use `$context->jobs()`, the validated `background` manifest and `assets/background-demo/`; the reference defines actual service grants, checkpoints, calendar rules and lifecycle behavior. Simple library/file tools do not need an independent service. Skill downloads use one stable ZIP directly inside the source-scoped Skills folder.
Read [references/host-compatibility.md](references/host-compatibility.md) for localized Windows names, icon editor overrides, offline account behavior and the background-jobs compatibility boundary. These are actual host capabilities, not permission to deploy or install software.
For authorized original UNC files, read [references/native-files.md](references/native-files.md). Desktop 0.5.40 / Server 0.4.39 add the hosted-tool native files API. Tools must implement a current-user resolver; do not invent arbitrary-path IPC or treat the old file receiver as a native opener.
For opt-in hosted offline assets, account-bound index snapshots and shared thumbnail APIs, read [references/hosted-offline.md](references/hosted-offline.md). Catalogue must implement its own exporter and offline UI adapter; this does not retrofit an unchanged tool ZIP.
## Icon standard
For every new or revised tool icon, read [references/icons.md](references/icons.md) and use [assets/icon-template.svg](assets/icon-template.svg). Keep the 256 px master canvas, 224 px tile with a 50 px corner radius, and 182 px artwork safe area consistent across tools. Export transparent-corner PNG/ICO assets from the same artwork and verify them at actual host sizes.
## Desktop-first NAS tools
For Desktop-local Catalogue browsing, signed cached source grants, daily/manual sync, shared NAS tags/previews, and real folder/background shell menus, read [references/desktop-nas.md](references/desktop-nas.md). Version 2 adds the compiled NAS helper, source-generation Reset, bounded tag batches, index correlations and explicit reconciliation. This contract extends the existing offline bridge. It requires explicit tool integration and declares the current runtime-validation and migration limitations.
## Combined native applications with Server backends (1.0.21)
Read [references/combined-applications.md](references/combined-applications.md). One uploaded ZIP contains the Windows application and its existing Server backend under one stable package ID and one numeric version. Minimum host: Desktop 0.5.66 / Server 0.4.50 / Website 1.24.88. Preserve existing tool/database/source identities and migration hashes. Server derives the client-only archive; never distribute PHP or private state to ordinary clients.
Managed running tools are now downloaded and verified first, then closed (with bounded forced termination if necessary), switched to the immutable new release and restarted. Keep application data separate. User-added installed Windows programs remain excluded. Application-owned startup updaters must stage verified files in a writable profile directory and restart using that same data profile; offline or corrupt downloads leave the current application usable. Do not promise silent writes to Program Files: protected Desktop installations need Windows elevation during file replacement.
