@nocobase/app-skills 0.1.0-beta.46 → 0.1.0-beta.48
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +2 -2
- package/skills/nocobase-app-development/SKILL.md +10 -0
- package/skills/nocobase-app-development/references/frontend/frontend-dev.md +14 -0
- package/skills/nocobase-app-development/references/frontend/references/ui-library.md +4 -4
- package/skills/nocobase-app-development/references/frontend/ui-workflow.md +2 -0
- package/skills/nocobase-app-development/references/lifecycle.md +1 -1
- package/skills/nocobase-app-development/references/migrations.md +7 -1
- package/skills/nocobase-deployment/SKILL.md +4 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nocobase/app-skills",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
3
|
+
"version": "0.1.0-beta.48",
|
|
4
4
|
"description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
"devDependencies": {
|
|
19
19
|
"@playwright/test": "^1.62.1",
|
|
20
20
|
"prettier": "^3.9.6",
|
|
21
|
-
"@nocobase/dev-config": "0.1.0-beta.
|
|
21
|
+
"@nocobase/dev-config": "0.1.0-beta.25"
|
|
22
22
|
},
|
|
23
23
|
"peerDependencies": {
|
|
24
24
|
"@playwright/test": "^1.62.1",
|
|
@@ -17,6 +17,8 @@ Do not use it to develop a published plugin package. Plugin development has its
|
|
|
17
17
|
|
|
18
18
|
Do not use it to upgrade the template this application was generated from, which is also how the application moves to a newer NocoBase version when the user asks to upgrade NocoBase or its core. That is `.agents/skills/nocobase-app-upgrade/`, which reconciles a newer template release against the application without reverting the user's work.
|
|
19
19
|
|
|
20
|
+
Check [browser API compatibility](references/frontend/frontend-dev.md#browser-api-compatibility) for direct calls and third-party integrations. HTTPS-only APIs require capability detection and a clear user-facing explanation when unavailable. UUID generation and copying text must support HTTP; use `createUuid()` and `copyText()` from `@nocobase/app-client`.
|
|
21
|
+
|
|
20
22
|
## Before you start
|
|
21
23
|
|
|
22
24
|
Read the application's `AGENTS.md` first for the rules that apply everywhere, and the `.agents/rules/` files its index points to for your task. This Skill's references are the detail behind it. Before running any `pnpm nocobase` command, read [the command line](references/cli.md): it maps tasks to commands and states the flags an agent must not add on its own.
|
|
@@ -66,6 +68,14 @@ Install, update and customize plugins, and remove a direct NocoBase package, as
|
|
|
66
68
|
|
|
67
69
|
Business role assignments must be visible and editable through administration. Default to explicit users; do not assign application roles to every authenticated identity or broaden the inherited member role merely to enable a feature. Follow [permission assignment safety](references/authorization.md#visible-and-manageable-assignments) and run the template's initialized-assignment guard before delivery.
|
|
68
70
|
|
|
71
|
+
## Choose sample data or a demo system
|
|
72
|
+
|
|
73
|
+
A request to add example customers, orders or tasks normally means sample data in the existing application. Use `sample: true` seeds or `sampleDataToken`; see [sample data and demo systems](references/migrations.md#sample-data-and-demo-systems). Keep required initialization data in ordinary seeds. Do not infer an isolated demo deployment from the words "demo data" alone.
|
|
74
|
+
|
|
75
|
+
A dedicated demo system has its own database and storage, repeatable business-data generation/clear/reset, visitor write policies and optional simulated external or Agent execution. For that requirement, follow the `nocobase-app-plugin-demo-mode` Skill. If `@nocobase/app-plugin-demo-mode` is not yet a dependency, register it with `pnpm nocobase plugin register demo-mode`, which also synchronizes its Skill; the Skill exists in the application only after synchronization. The plugin supplies the environment mechanisms; the application supplies its dataset, cleanup, management UI and any simulation adapters. Sample data alone supplies none of those operating policies. Use the user's stated deployment and lifecycle requirements to choose; if the intended scope remains ambiguous, clarify it before adding full-business cleanup or changing the environment mode. A trial, staging or customer environment where users keep their data, a provider's sandbox credentials and an in-app presentation mode are not demo systems.
|
|
76
|
+
|
|
77
|
+
When the application already depends on `@nocobase/app-plugin-demo-mode`, a change that adds business collections, outbound integrations or background jobs also updates the demo dataset's cleanup and adapters; follow that Skill's maintenance section.
|
|
78
|
+
|
|
69
79
|
## Deliver system administration by default
|
|
70
80
|
|
|
71
81
|
When a user asks you to build a complete application, deliver a usable System management navigation section and administration pages alongside the business features, unless the user explicitly excludes them or requests a narrower deliverable such as an API-only service or a prototype explicitly limited to business screens. Users do not need to request administration pages individually. Include user management and role and permission management by default. Place workflow management, background tasks and other applicable administration entries directly under System management as siblings; show execution status, failures and supported recovery actions within each capability's pages, without an additional Operational monitoring group. Reuse existing pages and installed plugins, and implement missing application-owned pages. Read [system administration](references/system-administration.md) for the baseline, capability-specific pages and acceptance criteria. For a focused feature change, extend existing administration where that feature requires it.
|
|
@@ -34,6 +34,20 @@ Conventions every page follows, each explained in its home:
|
|
|
34
34
|
- Toasts with `useToaster()` from `@nocobase/app-client`, never a second `Toaster` (["Toasts" in `references/api.md`](references/api.md#toasts)).
|
|
35
35
|
- Every user-visible string through a translation key ([`references/i18n.md`](references/i18n.md)).
|
|
36
36
|
|
|
37
|
+
## Browser API compatibility
|
|
38
|
+
|
|
39
|
+
Check browser support and secure-context requirements before choosing a browser API, including APIs called by third-party libraries. HTTPS-only APIs are allowed when a feature needs them: detect availability and permission failures, and show a localized explanation of the requirement and how the user can proceed. Keep unrelated actions working. Do not silently do nothing or show a success message when an API is unavailable. A LAN IP served over HTTP is not a secure context, while localhost is treated as trustworthy, so test the unavailable state instead of relying on localhost alone.
|
|
40
|
+
|
|
41
|
+
UUID generation and copying text must work on ordinary HTTP, including LAN IP access. Use the public `createUuid()` and `copyText()` utilities from `@nocobase/app-client` rather than duplicating browser-specific implementations in pages. `createUuid()` returns a cryptographically random UUID v4 using `crypto.getRandomValues`, with the standard version, variant and encoding; it does not require `crypto.randomUUID`. Server-side `node:crypto` is unaffected.
|
|
42
|
+
|
|
43
|
+
### Copy and clipboard actions
|
|
44
|
+
|
|
45
|
+
Call `copyText(text)` directly from the user's click handler and await its boolean result. It uses the [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/writeText) when available and falls back to selection-based copying on HTTP or after a rejected write. It returns `false` when programmatic copying is refused or unsupported. Only show a copied confirmation when it returns `true`; on `false`, present the exact text in a selectable field with localized manual-copy instructions. Do not use optional chaining on `navigator.clipboard` that silently skips copying.
|
|
46
|
+
|
|
47
|
+
For a dialog or other focus trap, pass `copyText(text, { container: dialogElement })` when the trigger does not take focus. Otherwise the helper selects the nearest dialog containing the active element, or the document body. Its temporary field is removed and the previous focus and selection are restored. The HTTP fallback uses the [deprecated `document.execCommand('copy')` compatibility mechanism](https://developer.mozilla.org/en-US/docs/Web/API/Document/execCommand); browser policy can still reject it, so keep the manual-copy path.
|
|
48
|
+
|
|
49
|
+
Verify UUID generation and copy actions on a non-secure HTTP origin where `window.isSecureContext` is `false`, including missing clipboard APIs, permission denial and copying from a dialog. Verify copied content by pasting into a normal input, including multiline and non-ASCII text; do not rely only on another secure-context-only API such as `navigator.clipboard.readText()`. For other HTTPS-only features, test the unavailable/denied state and its user-facing explanation as well as the supported path. Report browser checks that could not be performed.
|
|
50
|
+
|
|
37
51
|
## Look up by task
|
|
38
52
|
|
|
39
53
|
| Task | Read |
|
|
@@ -30,14 +30,14 @@ An agent's runs on one subject: a compact side-column log with a live timer, an
|
|
|
30
30
|
|
|
31
31
|
### agent-composer
|
|
32
32
|
|
|
33
|
-
The message box for talking to an agent: page-context chips inside it, files to send (attach, paste, drop, uploaded before sending), Enter to send, Stop while the agent works, and a toolbar slot for a picker such as the agent's. Use it wherever a person writes to an agent. Presentational: context chips, drafts and focus come from the agents plugin's chat hooks (@nocobase/app-plugin-agents/client/chat) through optional props.
|
|
33
|
+
The message box for talking to an agent: page-context chips inside it (each can open a preview of what it carries), files to send (attach, paste, drop, uploaded before sending), Enter to send, Stop while the agent works, and a toolbar slot for a picker such as the agent's. Use it wherever a person writes to an agent. Presentational: context chips, drafts and focus come from the agents plugin's chat hooks (@nocobase/app-plugin-agents/client/chat) through optional props.
|
|
34
34
|
|
|
35
35
|
- Kind: component
|
|
36
36
|
- Install: `yes n | pnpm exec shadcn add @nocobase/agent-composer`
|
|
37
37
|
- Installs to: `client/components/agent-composer.tsx`
|
|
38
38
|
- Plugin dependencies: `@nocobase/app-plugin-agents`
|
|
39
39
|
- Example: `@nocobase/agent-composer-demo` (`pnpm exec shadcn view @nocobase/agent-composer-demo`)
|
|
40
|
-
- After installing: Pass onSend (return true, or a promise of true, once the message is taken), and optionally running, onStop, toolbar and notice; pass attachments (upload, and optionally discard and registerAdd; useChatAttachments of @nocobase/app-plugin-agents/client/chat uploads to the plugin) to send files; wire context (chips from contextChips and buildPageContext of @nocobase/app-plugin-agents/client/chat), draft and registerFocus from the chat panel when it sits in one. Every word comes from the labels prop, English by default.
|
|
40
|
+
- After installing: Pass onSend (return true, or a promise of true, once the message is taken), and optionally running, onStop, toolbar and notice; pass attachments (upload, and optionally discard and registerAdd; useChatAttachments of @nocobase/app-plugin-agents/client/chat uploads to the plugin) to send files; wire context (chips from contextChips and buildPageContext of @nocobase/app-plugin-agents/client/chat, and optionally inspect, which makes each chip open a preview of what it carries), draft and registerFocus from the chat panel when it sits in one. Every word comes from the labels prop, English by default.
|
|
41
41
|
|
|
42
42
|
### agent-picker
|
|
43
43
|
|
|
@@ -52,7 +52,7 @@ The one way to pick an agent: a trigger with the agent's avatar (availability do
|
|
|
52
52
|
|
|
53
53
|
### agent-chat
|
|
54
54
|
|
|
55
|
-
The agents' chat: a side panel beside the content area with the conversation, live steps, a composer with page-context chips and files to send (attach, paste, drop), the agent picker, the history, a full-page conversation view, and header, floating and Ask agent launchers. Use it to let people talk to agents from any page. Wired to the headless hooks of @nocobase/app-plugin-agents/client/chat.
|
|
55
|
+
The agents' chat: a side panel beside the content area, switching between the online agent and runner agents when both are configured, with the conversation, live steps, a composer with page-context chips and files to send (attach, paste, drop), the agent picker, the history, a full-page conversation view, and header, floating and Ask agent launchers. Use it to let people talk to agents from any page. Wired to the headless hooks of @nocobase/app-plugin-agents/client/chat.
|
|
56
56
|
|
|
57
57
|
- Kind: block
|
|
58
58
|
- Install: `yes n | pnpm exec shadcn add @nocobase/agent-chat`
|
|
@@ -60,7 +60,7 @@ The agents' chat: a side panel beside the content area with the conversation, li
|
|
|
60
60
|
- Plugin dependencies: `@nocobase/app-plugin-agents`
|
|
61
61
|
- Also installs: `@nocobase/markdown-view`, `@nocobase/agent-run-history`, `@nocobase/agent-composer`, `@nocobase/agent-picker`, `@nocobase/attachment-list`
|
|
62
62
|
- Example: `@nocobase/agent-chat-demo` (`pnpm exec shadcn view @nocobase/agent-chat-demo`)
|
|
63
|
-
- After installing: Requires the agents plugin (and the file plugin on the server for files sent in chat): wrap the routes in ChatProvider from @nocobase/app-plugin-agents/client/chat (pass conversationPath when ChatConversationPage has a route such as /chat/:conversationId), optionally with ChatExtensionsContext for cards among the messages. Render ChatPanel as a sibling of <main> inside a `relative flex` row, ChatHeaderButton in the header and ChatFloatingButton anywhere; add the plugin's chatLinkRoutes(base) for links that open the panel; spread locales/ into client/locales/.
|
|
63
|
+
- After installing: Requires the agents plugin (and the file plugin on the server for files sent in chat): wrap the routes in ChatProvider from @nocobase/app-plugin-agents/client/chat (pass memoryScope, the signed-in person's id, so a new conversation starts with the agent they used last; pass conversationPath when ChatConversationPage has a route such as /chat/:conversationId), optionally with ChatExtensionsContext for cards among the messages. Render ChatPanel as a sibling of <main> inside a `relative flex` row, ChatHeaderButton in the header and ChatFloatingButton anywhere; add the plugin's chatLinkRoutes(base) for links that open the panel; spread locales/ into client/locales/.
|
|
64
64
|
|
|
65
65
|
## Approval
|
|
66
66
|
|
|
@@ -8,6 +8,8 @@ This is the entry point for the application's frontend work: read it before writ
|
|
|
8
8
|
|
|
9
9
|
What the interface should look like is in [`ui-guidelines.md`](ui-guidelines.md); how to write the code is in [`frontend-dev.md`](frontend-dev.md). Paths in this document are relative to its own directory: [`ui-guidelines.md`](ui-guidelines.md) and [`frontend-dev.md`](frontend-dev.md) sit beside it, the topic references are under `references/`, the record templates and reviewer prompts are under `templates/`, and the screenshot tool is under `scripts/`.
|
|
10
10
|
|
|
11
|
+
Every workflow follows [browser API compatibility](frontend-dev.md#browser-api-compatibility): explain unavailable HTTPS-only capabilities to users, and verify that UUID generation and copy actions work on ordinary HTTP through the shared `@nocobase/app-client` utilities.
|
|
12
|
+
|
|
11
13
|
## Choosing a workflow
|
|
12
14
|
|
|
13
15
|
Decide before you start, and say in one sentence in your reply which workflow you are following and why.
|
|
@@ -399,7 +399,7 @@ return view.available.map((transition) => (
|
|
|
399
399
|
|
|
400
400
|
Render the buttons from `view.available`, never from a hard-coded state check, so the page and the server use the same judgement. Translate titles and blocker messages by their stable `name` and `code`, as every user-visible string goes through a translation key. `fire` sends a fresh `requestId` and the version on screen; on `CONFLICT` tell the person the record changed and reload rather than retrying. On `INVALID_INPUT`, mark the fields in `error.problems`. The hook refreshes every 4 seconds by default; `refreshMs` changes it. Follow [the frontend workflow](frontend/ui-workflow.md) for the page itself.
|
|
401
401
|
|
|
402
|
-
For browser request IDs, prefer the built-in lifecycle client, which already handles environments without `crypto.randomUUID()`. Custom submissions and parameter saves
|
|
402
|
+
For browser request IDs, prefer the built-in lifecycle client, which already handles environments without `crypto.randomUUID()`. Custom submissions and parameter saves follow [browser API compatibility](frontend/frontend-dev.md#browser-api-compatibility), including regression coverage with `randomUUID` unavailable. Generate one key per logical operation and reuse it with the same payload for transport retries; changed input or a new decision needs a new key.
|
|
403
403
|
|
|
404
404
|
## 6. Tests
|
|
405
405
|
|
|
@@ -18,7 +18,13 @@ This applies pending migrations and then pending seeds for `database.default`, i
|
|
|
18
18
|
|
|
19
19
|
Seeds are the second half of that run, so the structure a seed writes into must already exist from an earlier migration. Keep seed data fixed and reproducible — no current timestamps or random values in identifying fields — and never let a repeat run silently overwrite data a user has edited.
|
|
20
20
|
|
|
21
|
-
Sample data
|
|
21
|
+
## Sample data and demo systems
|
|
22
|
+
|
|
23
|
+
Sample data is optional example content for exploring or developing an application, such as fictional customers and related orders. It does not enable read-only protection, recurring resets, demo-account management or external-call simulation. Required system records still belong in ordinary seeds.
|
|
24
|
+
|
|
25
|
+
Use `@nocobase/app-plugin-demo-mode` when the requirement is a dedicated demo system with a separate database and storage, repeatable data lifecycle, visitor write policies and optional Agent or external-call simulation. Follow that installed plugin's Skill for its application-owned dataset and full-business cleanup contract. A request for a few example records does not require this plugin. Both mechanisms can use the same fictional story or application fixture helpers, but keep their execution and cleanup lifecycles separate; do not register the same data-generation routine in both paths and run it twice.
|
|
26
|
+
|
|
27
|
+
Put sample data in the same `seeds` directory as `defineSeed({ name, sample: true, run })`, or, when it has to go through plugins' services, register it on `sampleDataToken` from `@nocobase/app-server/sample-data` in a service provider's `boot()`; `.agents/skills/nocobase-db/SKILL.md` section 2 has the details. Both load only while the run installs the connection — it held no migration or seed history, or `db reset` rebuilt it — with `app.sampleData` set (`APP_SAMPLE_DATA=true`); otherwise they are recorded as skipped. The seeds entry of a run reports `freshInstall` and, when it skipped any, `skippedSamples`. `pnpm nocobase db sample` runs what was skipped, in development only: a built `dist/` refuses it.
|
|
22
28
|
|
|
23
29
|
## Multiple connections
|
|
24
30
|
|
|
@@ -119,6 +119,10 @@ Bind-mount the complete runtime configuration read-only at `/app/config.yml` and
|
|
|
119
119
|
|
|
120
120
|
## Verify the deployed application
|
|
121
121
|
|
|
122
|
+
Use the intended public origin for browser checks, including its scheme, host and base path. Follow [browser API compatibility](../nocobase-app-development/references/frontend/frontend-dev.md#browser-api-compatibility): UUID generation and copying text must work on ordinary HTTP, while other HTTPS-only capabilities must explain their requirements to users when unavailable. Verify those HTTP-compatible actions and unavailable-feature messages on an origin where `window.isSecureContext` is `false`; localhost and HTTPS can mask incompatibilities. Exercise actions through completion and inspect browser errors; a loaded page or healthy server is insufficient.
|
|
123
|
+
|
|
124
|
+
When the application offers copy buttons, include [copy and clipboard verification](../nocobase-app-development/references/frontend/frontend-dev.md#copy-and-clipboard-actions): copy from a representative page or dialog and paste into a normal input on HTTP. A success toast alone is not evidence that the clipboard changed.
|
|
125
|
+
|
|
122
126
|
Collect evidence for each item:
|
|
123
127
|
|
|
124
128
|
1. The process or container reports ready. The application answers `GET <APP_BASE_PATH>/api/healthz` with a JSON object whose `ok` is `true` (alongside the app name and base path).
|