{"record":{"id":"90a690a275916d2e","repo":"siyuan-note/siyuan","slug":"agent-capability-name-and-description-are-required","errorCode":null,"errorMessage":"Agent capability name and description are required","messagePattern":"Agent capability name and description are required","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"app/src/plugin/index.ts","lineNumber":455,"sourceCode":"    }\n\n    public addAgentCapability(options: {\n        name: string,\n        title?: string,\n        description: string,\n        inputSchema: Record<string, unknown>,\n        outputSchema?: Record<string, unknown>,\n        effects?: IAgentCapabilityEffects,\n        actionEffects?: Record<string, IAgentCapabilityEffects>,\n        handler: (args: Record<string, unknown>, app: App) => Promise<{\n            result?: string;\n            structuredContent?: unknown;\n            error?: string;\n        }>\n    }): string {\n        const name = options.name.trim();\n        if (!name || !options.description.trim()) {\n            throw new Error(\"Agent capability name and description are required\");\n        }\n        const id = \"plugin/frontend/\" + encodeURIComponent(this.name) + \"/\" + encodeURIComponent(name);\n        if (!this.agentCapabilities.some((capability) => capability.id === id)) {\n            const generation = registerCapability({\n                id,\n                title: options.title,\n                description: options.description,\n                inputSchema: options.inputSchema,\n                outputSchema: options.outputSchema,\n                effects: options.effects,\n                actionEffects: options.actionEffects,\n                source: \"plugin\",\n                ownerId: this.name,\n                ownerName: this.displayName || this.name,\n                handler: options.handler,\n            });\n            this.agentCapabilities.push({id, generation});\n        }","sourceCodeStart":437,"sourceCodeEnd":473,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/251596fc0de2f9528c00c224252fd073a99973f4/app/src/plugin/index.ts#L437-L473","documentation":"Plugin.addAgentCapability() throws 'Agent capability name and description are required' when options.name.trim() or options.description.trim() is empty. The name becomes part of the registered capability id ('plugin/frontend/<plugin>/<name>'), so empty values would produce an invalid id; the description is shown to the model and must not be blank.","triggerScenarios":"A plugin calls this.addAgentCapability({...}) with name=' ', description='', or omits the field; user input used as the name/description without trimming; template literal that evaluated to empty.","commonSituations":"Plugin author forgot to localize the description; dynamically generated name from user input that was blank; refactor renamed the field but left a default empty string; plugin loaded before its i18n bundle resolved.","solutions":["Validate name and description before calling addAgentCapability and skip registration if blank.","Provide non-empty defaults for name and description from the plugin manifest or i18n bundle.","Trim and assert length > 0 on both fields at the call site.","Surface the error to the plugin author during development via the plugin console."],"exampleFix":"// before\nthis.addAgentCapability({name, description, inputSchema, handler});\n// after\nif (!name?.trim() || !description?.trim()) {\n    console.warn('[plugin] skipping capability registration: empty name or description');\n    return;\n}\nthis.addAgentCapability({name: name.trim(), description: description.trim(), inputSchema, handler});","handlingStrategy":"validation","validationCode":"const name = options.name?.trim();\nconst description = options.description?.trim();\nif (!name || !description) { console.warn('capability registration skipped: empty name/description'); return; }","typeGuard":"function isValidCapabilityOptions(o: {name?: unknown; description?: unknown}): boolean {\n    return typeof o.name === 'string' && o.name.trim().length > 0 &&\n        typeof o.description === 'string' && o.description.trim().length > 0;\n}","tryCatchPattern":"try { this.addAgentCapability(opts); }\ncatch (e) { if (/name and description are required/i.test(e.message)) return; throw e; }","preventionTips":["Validate name and description at the call site before registering.","Provide non-empty defaults from the plugin manifest or i18n bundle.","Trim user-supplied values used for name/description.","Log a warning during plugin development when registration is skipped."],"tags":["plugin","agent-capability","validation","typescript"],"backgroundTag":null,"analyzedSha":"251596fc0de2f9528c00c224252fd073a99973f4","analyzedAt":"2026-08-12T21:18:37.123Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}