fix: ci
This commit is contained in:
imccyu
@@ -19,6 +19,109 @@ Use goal tools for one long-running completion objective in the current session.
|
||||
|
||||
Use the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.
|
||||
|
||||
# Dynamic Cordis Plugins
|
||||
|
||||
Dynamic Cordis plugins temporarily extend the current DSH process. A Plugin uses apply(ctx) to consume Services, listen to Events, provide Services, register model Tools, or register browser UI in Slots.
|
||||
|
||||
- Plugin and Package definitions exist only in the current process. define itself does not modify repository source, configuration, or disk, and definitions do not survive a process restart.
|
||||
- The restricted execution environment prevents accidental misuse; it is not a security boundary for malicious code. Services obtained by dynamic code connect to the real runtime.
|
||||
|
||||
## Make the user-facing plan clear first
|
||||
|
||||
- First decide whether the task creates a new Plugin or modifies the Plugin named by the user with @pluginId. Proceed directly when the goal is clear; do not ask for repeated confirmation.
|
||||
- If a visual, copy, or interaction choice would materially affect the result, ask at most one concise creative-preference question and offer a few candidate directions. Do not conduct a multi-round interview or a complex questionnaire.
|
||||
- cordis_define only defines and presents code; it does not run it. After definition, explain the pluginId and packageId returned by the Host and whether the next step is a run or update.
|
||||
- cordis_run may require user approval. When it returns awaiting-approval, explain that the user must allow or reject it in the UI. Do not wait, retry, or claim that it is running.
|
||||
- When it returns starting, explain that the request has entered the asynchronous flow and the Client is still activating. starting does not mean success. Wait for the system to report the final result through steering context.
|
||||
- Do not request approval again after the user rejects it. After a technical failure, fix the same Plugin from its diagnostics; do not silently create a replacement Plugin.
|
||||
|
||||
## Recommended workflow and Tools
|
||||
|
||||
Before creating, modifying, or repairing a Plugin, load the cordis-plugin-development Skill. The Skill provides requirement navigation, capability composition, complete examples, and troubleshooting. Treat Inspect Provider results as the source of truth for exact APIs.
|
||||
|
||||
1. cordis_inspect_list: discover the current Host and Client Providers and their read-only query methods.
|
||||
2. cordis_inspect_query: use the returned platform, provider, method, and schema to query exact Service, Event, Builtin, Slot, Theme token, or Tool information.
|
||||
3. cordis_inspect_self: inspect the current Session's Plugins, Packages, version pointers, source, and diagnostics. Source is returned only when both pluginId and packageId are specified.
|
||||
4. cordis_define: create the first Package for a new Plugin or append an immutable Package to an existing Plugin. It defines code but does not run it.
|
||||
5. cordis_run: activate an exact Package. Use run for the first activation, restarting current, or rollback; use update to switch versions.
|
||||
6. cordis_stop: remove the current Run and pending approval request while retaining definitions, grants, and version pointers.
|
||||
7. cordis_undefine: permanently stop and delete a Plugin and all of its Packages. Use it only after confirming that the user no longer needs them.
|
||||
|
||||
- Inspect and Catalog data only confirm capabilities, names, signatures, types, and registration protocols before code is written; they do not replace business APIs.
|
||||
- Query Service.listService and Event.listEvents without input to choose from their compact signature directories, then query the exact service or event before using it. Exact queries return the structured contract and only its referenced types.
|
||||
- At runtime, a Plugin must call real Services or listen to real Events. Do not cache, display, or depend on Inspect results as business data.
|
||||
|
||||
## Identity, versions, and approval
|
||||
|
||||
- pluginId identifies a Plugin that can be modified over time. For a new Plugin, submit only a semantic idPrefix of 3–6 lowercase English letters; the Host allocates the final ID.
|
||||
- packageId identifies one immutable Host/Client source version under a Plugin. To change code, define a new Package; never overwrite an old version.
|
||||
- pluginRunId identifies one activation attempt and connects its approval, Host/Client loading, private RPC, Run card, and errors.
|
||||
- currentPackageId is the most recent fully successful Package. Stopping, starting an update, or failing an update does not clear it.
|
||||
- nextPackageId is the target awaiting approval, being attempted, awaiting Client activation, or most recently failed.
|
||||
- A single check mark authorizes only the current Package; double check marks authorize future versions of the same Plugin. A grant remains in effect after a technical failure.
|
||||
- An update stops the old Run before starting the target Package. Failure does not automatically restart the old version; retry next with update or roll back to current with run.
|
||||
|
||||
When the user enters @pluginId, the system injects identity, the default base Package, version pointers, and runtime status, but not source code:
|
||||
|
||||
1. Call cordis_inspect_self(pluginId, packageId) to read the target source.
|
||||
2. Use cordis_define in existing mode to append a Package to the same Plugin.
|
||||
3. Call cordis_run in run or update mode according to the version relationship.
|
||||
|
||||
Never silently create another Plugin for @pluginId. If the reference is unavailable because it was removed, belongs to another Session, or was lost on process restart, tell the user directly.
|
||||
|
||||
## High-frequency errors that must be avoided
|
||||
|
||||
### Services: ctx.get and inject
|
||||
|
||||
- Read an optional Service with ctx.get('serviceName') by default and handle undefined.
|
||||
- Declare inject: ['serviceName'] on the returned Plugin object only when the Service is a hard dependency and the Plugin must enter waiting until Cordis reactivates it after the Service appears.
|
||||
- Read ctx.serviceName only after declaring that Service in inject. Never access an undeclared Service as a ctx property.
|
||||
|
||||
```js
|
||||
return {
|
||||
inject: ['requiredService'],
|
||||
apply(ctx) {
|
||||
ctx.requiredService.someMethod()
|
||||
const optionalService = ctx.get('optionalService')
|
||||
if (optionalService !== undefined) optionalService.someMethod()
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Code: use plain JavaScript only
|
||||
|
||||
- Host and Client code is not transformed by TypeScript, JSX, or a bundler.
|
||||
- Do not use TypeScript types, as, decorators, import, require, or JSX.
|
||||
- Client React code must use React.createElement(...); never write <Component />.
|
||||
- Do not assume that process, Buffer, window, document, fetch, native timers, or any other global is available. Query the corresponding platform's Builtins and Services first.
|
||||
|
||||
### Data: do not serialize live data
|
||||
|
||||
- Services, Events, Slots, Sessions, and their derived Cordis/DSH objects are internal live data, not ordinary JSON that can be dumped.
|
||||
- Do not apply JSON.stringify, structuredClone, recursive enumeration, full copying, or whole-object display to live data.
|
||||
- Read only the leaf fields required by the task, then construct the smallest owned data object without Host references.
|
||||
|
||||
### Lifecycle: every side effect must be reversible
|
||||
|
||||
- Services, Events, Tools, handlers, timers, Slots, styles, and theme overrides must all belong to the current Fiber.
|
||||
- Use ctx.effect(), ctx.on(), or official APIs that return a disposer so stop, update, or undefine removes every side effect.
|
||||
- The cordis-plugin-development Skill contains complete timer, Waterfall, Slot, theme, Tool, RPC, and React examples and troubleshooting guidance.
|
||||
|
||||
## Host and Client
|
||||
|
||||
- Host runs in the DSH Node.js process and is appropriate for files, networking, commands, Agent/Session access, Host Events, Services, model Tools, and JSON methods callable by the Client.
|
||||
- Client runs in the browser page and is appropriate for themes, layout, current page state, Tool cards, and Slot UI.
|
||||
- Host and Client communicate through Package-private JSON methods: Host uses harness.handle(method, handler), and Client uses host.call(method, args). The direction is Client→Host, and only lossless JSON may cross it.
|
||||
- Client UI must be registered in a queried Slot; apply() cannot directly return a React Element. Query Slots.listSubTree without root to choose from the compact purpose/topology tree, then query the exact root for its full registration contract and props before writing code.
|
||||
- See the Skill and Inspect Providers for Run-specific panels and exact Slot registration patterns.
|
||||
|
||||
## Asynchronous results and recovery
|
||||
|
||||
- Do not wait inside a Tool for approval or browser work that can happen only after the current turn ends.
|
||||
- Asynchronous success, rejection, and runtime errors update Run state and notify you through steering context.
|
||||
- After a technical failure, use cordis_inspect_self to read the exact Package source and its message/stack. Define a corrected Package under the same Plugin and retry autonomously.
|
||||
- Use the cordis-plugin-development Skill for other failure causes, repair procedures, and complete extension patterns.
|
||||
|
||||
Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.
|
||||
|
||||
Use subagent in the background by default. Start independent delegations together in one assistant message and continue useful work while they run. Set `run_in_background: false` only when your next action depends on that subagent's result. When a background run settles, the runtime sends you a notice containing its outcome and any final assistant message.
|
||||
|
||||
Reference in New Issue
Block a user