Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions MANIFEST.in
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ recursive-include src *
recursive-include packages/core/src *.py
recursive-include apps/api/src *.py
recursive-include packages/agent/skills *
include plugins/catalog.json
prune packages/core/src/opendirector/_bundled
prune node_modules
prune dist
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,7 @@ Use Chrome or Edge for MP4 export, and keep the page and editor open while rende
- [Troubleshooting](docs/guides/user-guide.md#troubleshooting): Installation, generation, saving, and export issues.
- [Business CLI (Chinese)](docs/guides/cli.md): Work with projects through a terminal or Agent Shell.
- [DeepSeek Harness plugin](plugins/deepseek-harness/README.md): Generate media from DSH, track jobs, and continue editing in OpenDirector.
- [Optional creative plugins](docs/guides/plugins.md): Install, enable per harness, and create portable Skill packages.
- [Documentation index (Chinese)](docs/README.md): Architecture, development, and validation documents.

## Community
Expand Down
1 change: 1 addition & 0 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,7 @@ opendirector serve
- [故障排查](docs/guides/user-guide.zh-CN.md#故障排查):安装、生成、保存与导出问题。
- [业务 CLI](docs/guides/cli.md):通过终端或 Agent Shell 操作工程。
- [DeepSeek Harness 插件](plugins/deepseek-harness/README.zh-CN.md):从 DSH 生成素材、跟踪任务,再回到 OpenDirector 继续编辑。
- [可选创作插件](docs/guides/plugins.zh-CN.md):安装插件、按引擎启用,以及制作可移植的技能包。
- [文档索引](docs/README.md):架构、开发与验证文档。

## 社区交流
Expand Down
11 changes: 6 additions & 5 deletions apps/api/src/opendirector_api/agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -315,10 +315,11 @@ async def runtime_models(project_id: UUID, runtime: Literal['opencode', 'codex',
return await model_choices(runtime)

@router.get('/skills')
async def catalog(project_id: UUID):
async def catalog(project_id: UUID, runtime: Runtime = 'default'):
directory = await asyncio.to_thread(conversations.path, project_id)
found = await skills(projects.local.repository, directory)
return [{key: item[key] for key in ('name', 'description', 'source')} for item in found]
found = await skills(projects.local.repository, directory, runtime)
return [{key: item[key] for key in ('name', 'description', 'source', 'pluginId', 'displayName', 'localizedDescription')
if key in item} for item in found]

@router.post('/turns/{turn_id}/stop')
async def stop(project_id: UUID, turn_id: UUID, x_opendirector_session: UUID = Header()):
Expand Down Expand Up @@ -356,9 +357,9 @@ async def turn(project_id: UUID, value: Turn, x_opendirector_session: UUID = Hea
if value.runtime == 'jiuwenswarm' and value.thinking != 'auto':
raise ProjectError('JiuwenSwarm 当前使用原生默认推理强度。', 409)
config = await asyncio.to_thread(configs.resolve, str(value.modelId), 'agent') if spec.modelSource == 'settings' else None
available = await skills(projects.local.repository, directory) if spec.supportsSkills else []
available = await skills(projects.local.repository, directory, value.runtime) if spec.supportsSkills else []
if set(value.skills) - {item['name'] for item in available}:
raise ProjectError('技能已失效,请重新选择。', 409)
raise ProjectError('所选技能对当前引擎已不可用,请从消息中移除并重新选择。', 409, code='agent_skill_unavailable')
snapshot = await asyncio.to_thread(projects.snapshot, project_id)
assets = {str(asset.id): asset for asset in snapshot.assets}
for asset_id in value.assets:
Expand Down
3 changes: 3 additions & 0 deletions apps/api/src/opendirector_api/localization.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,11 @@
from opendirector.domain.timeline_errors import timeline_error_message

from opendirector.domain.creation.commands import CommandReceipt
from opendirector.domain.plugins import PLUGIN_ERRORS

ENGLISH_BY_CODE = {
**{code: messages[1] for code, messages in PLUGIN_ERRORS.items()},
'agent_skill_unavailable': 'A selected skill is unavailable for this harness. Remove it from the message and select an available skill.',
'bigmodel_video_model': 'The BigModel video protocol supports CogVideoX-3 only.',
'bigmodel_video_output': 'Choose a supported CogVideoX-3 pixel size and a 5- or 10-second duration. The size determines the aspect ratio.',
'bigmodel_video_image': 'CogVideoX-3 frame images must be valid PNG or JPEG files, up to 5 MB each.',
Expand Down
2 changes: 2 additions & 0 deletions apps/api/src/opendirector_api/main.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
from opendirector_api.agent import agent_routes
from opendirector_api.library import library_routes
from opendirector_api.voices import voice_routes
from opendirector_api.plugins import plugin_routes
from opendirector_api.localization import localized_error
from opendirector_api.models import (ModelConfigInput, ModelConfigPublic, AgentModelTest,
ModelCapabilityRequest, ModelDiscoveryRequest, ModelBatchInput,
Expand Down Expand Up @@ -70,6 +71,7 @@ async def lifespan(app):
app.include_router(agent_routes(creation_projects, creation_generation, model_configs, chat_provider))
app.include_router(library_routes(creation_projects))
app.include_router(voice_routes(creation_generation.voices))
app.include_router(plugin_routes(store.repository))

@app.exception_handler(RequestValidationError)
async def invalid_request(request, error):
Expand Down
56 changes: 56 additions & 0 deletions apps/api/src/opendirector_api/plugins.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
"""Local plugin management; native harnesses retain execution permissions."""
import asyncio
from typing import Annotated

from fastapi import APIRouter, Path, Request
from pydantic import BaseModel, ConfigDict, Field

from opendirector.agent.context import RuntimeId
from opendirector.agent.plugins import MAX_ARCHIVE_BYTES, PluginRegistry, failure
from opendirector.domain.plugins import Digest, PluginId


class PluginSource(BaseModel):
model_config = ConfigDict(extra='forbid', strict=True)
source: str = Field(min_length=1, max_length=4096)


class PluginChange(BaseModel):
model_config = ConfigDict(extra='forbid', strict=True)
digest: Digest


class PluginEnabled(PluginChange):
enabled: bool


def plugin_routes(repository):
router = APIRouter(prefix='/api/plugins')
registry = PluginRegistry(repository)

@router.get('')
def catalog():
return registry.catalog()

@router.post('')
def install(value: PluginSource):
return registry.install(value.source)

@router.post('/upload')
async def upload(request: Request):
content = bytearray()
async for chunk in request.stream():
content.extend(chunk)
if len(content) > MAX_ARCHIVE_BYTES:
raise failure('plugin_too_large', 413)
return await asyncio.to_thread(registry.install_archive, bytes(content))

@router.put('/{plugin_id}/runtimes/{runtime}')
def enable(plugin_id: Annotated[PluginId, Path()], runtime: RuntimeId, value: PluginEnabled):
return registry.change(plugin_id, value.digest, runtime=runtime, enabled=value.enabled)

@router.delete('/{plugin_id}')
def remove(plugin_id: Annotated[PluginId, Path()], value: PluginChange):
return registry.change(plugin_id, value.digest)

return router
1 change: 1 addition & 0 deletions build_backend.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ def prepare_resources():
shutil.rmtree(bundled)
shutil.copytree(ROOT / 'dist', bundled / 'web')
shutil.copytree(ROOT / 'packages/agent/skills', bundled / 'skills')
shutil.copy2(ROOT / 'plugins/catalog.json', bundled / 'plugin-catalog.json')
npm_package = ROOT / 'node_modules/opencode-ai'
metadata = json.loads((npm_package / 'package.json').read_text())
executable = npm_package / metadata['bin']['opencode']
Expand Down
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ This directory is the entry point for the repository's shared documentation. The
| [Python installation and packaging](development/packaging.md) | Installation, platform wheel builds, and isolated verification | Packaging, resource paths, or build process changes |
| [Business CLI](guides/cli.md) | Querying, editing, and generating through a terminal or Agent Shell | Commands, authorization, or receipt semantics change |
| [DeepSeek Harness plugin](../plugins/deepseek-harness/README.md) | Installing the DSH bundle and editing an OpenDirector project from DSH | Plugin setup, tools, or creation workflows change |
| [Optional creative plugins](guides/plugins.md) / [可选创作插件](guides/plugins.zh-CN.md) | Installing, enabling and authoring portable Skill packages | Package format, activation or examples change |
| [Video model capabilities](guides/video-model-capabilities.md) | Declaring output specifications supported by a service | Configuration fields or capability integration changes |
| [OpenAI Images](guides/openai-images.md) | Wiring gpt-image as an optional image service, request shape and failures | Integration fields, capability scope, or the OpenAI interface change |
| [Kling video](guides/kling-video.md) ([中文](guides/kling-video.zh-CN.md)) | Optional Kling 4.0 and Flash setup, model-specific inputs, and recovery limits | Kling inputs, model declarations, or recovery behavior change |
Expand Down
1 change: 1 addition & 0 deletions docs/development/i18n.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,7 @@ npm run check:i18n
| --- | --- | --- |
| 通用、错误 | [common.ts](../../src/i18n/messages/zh-CN/common.ts) | [common.ts](../../src/i18n/messages/en-US/common.ts) |
| 设置、主题 | [settings.ts](../../src/i18n/messages/zh-CN/settings.ts) | [settings.ts](../../src/i18n/messages/en-US/settings.ts) |
| 可选插件 | [plugins.ts](../../src/i18n/messages/zh-CN/plugins.ts) | [plugins.ts](../../src/i18n/messages/en-US/plugins.ts) |
| 画布与项目 | [canvas.ts](../../src/i18n/messages/zh-CN/canvas.ts) | [canvas.ts](../../src/i18n/messages/en-US/canvas.ts) |
| 模型与服务 | [models.ts](../../src/i18n/messages/zh-CN/models.ts) | [models.ts](../../src/i18n/messages/en-US/models.ts) |
| 画布外壳 | [canvasShell.ts](../../src/i18n/messages/zh-CN/canvasShell.ts) | [canvasShell.ts](../../src/i18n/messages/en-US/canvasShell.ts) |
Expand Down
14 changes: 14 additions & 0 deletions docs/development/lessons.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,3 +99,17 @@ When work exposes a consequential risk or a recurring problem, add a lesson or u
- **Lesson:** [Issue #302](https://github.com/ThinkFlowLab/OpenDirector/issues/302) identified four citation groups whose Unicode private-use delimiters and internal source IDs were displayed as text. The native and persisted replies agreed byte for byte; intact text transport did not establish usable presentation.
- **Check:** Verify the source metadata as well as reply text, multiple citations, split streaming markers, history reopening, copying and missing-source fallback. Preserve raw execution evidence and tool offsets; leave literal code examples unchanged and inspect both interface languages in the browser.
- **Presentation follow-up:** The source-link UI in #302 initially inherited a library modal's utility classes without the corresponding CSS. Text and click checks passed while the border and close-button positioning failed. Use the supported custom renderer with repository-owned styles, and check computed styles, element geometry, long URLs, keyboard close and focus restoration as well as translated text.

## Validate every entry returned by native discovery

- **Trigger:** A package declares one Skill while the native loader scans resource directories recursively.
- **Evidence:** [Issue #114](https://github.com/ThinkFlowLab/OpenDirector/issues/114)'s independent review reproduced nested `SKILL.md` entries being classified as workspace skills, bypassing plugin metadata and colliding during snapshot copying. The regressions in [test_plugins.py](../../tests/test_plugins.py) cover both package rejection and unexpected native discovery results.
- **Check:** Validate all discoverable entry filenames, including case variants. Require the native catalog's exact paths and identities to match registered entries, reject duplicate names before copying, and test the discovery boundary independently of installer validation.

## Local HTTP requests still need filesystem scope

- **Trigger:** Accepting a local plugin path from an HTTP request.
- **Evidence:** [PR #371](https://github.com/ThinkFlowLab/OpenDirector/pull/371)'s CodeQL gate flagged unrestricted source paths. An isolated API probe read a valid package outside the backend workspace using only the public local-request header. This demonstrated missing source scope; it did not test a separate OS user or establish a remote-network exploit.
- **Follow-up:** Independent review reproduced replacing a checked resource with an outside symlink during installation, and a hard link bypassed the pathname check without a race. A normalized path check alone does not authorize the object eventually opened.
- **Entry-point follow-up:** Full CodeQL traces exposed a mixed string/bytes installer that skipped source authorization for other types; a direct `Path` call reproduced installation from outside the workspace. Separate source strings from uploaded bytes, reject unexpected types before parsing, and test the shared service boundary as well as HTTP validation.
- **Check:** Authorize the complete normalized candidate against the backend workspace and exclude project/internal storage. Use the existing descriptor/handle reader to pin every path component and reject hard links; do not resolve the package entry after checking it. Test absolute/relative traversal, sibling prefixes, control characters, replacements at the file/directory/ZIP boundaries and bilingual errors. Preserve empty package resources without relaxing execution-artifact defaults, and keep ZIP upload for packages elsewhere.
102 changes: 102 additions & 0 deletions docs/guides/plugins.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
# Optional creative plugins

[中文](plugins.zh-CN.md)

Plugins add optional creative Skills to the existing assistant harnesses. Open
**Settings → Plugins**, install a package, then enable the harnesses that may
use it. Every installation starts disabled. The same package can support Default,
OpenCode, Codex, Claude Code, JiuwenSwarm and DeepSeek Harness; switching harnesses
shows only the Skills enabled for that harness.

This format is an OpenDirector Skill package, with one native Skill entry and
supporting templates or scripts. It is distinct from the [DSH integration
bundle](../../plugins/deepseek-harness/README.md), which lets external DSH call
OpenDirector. Other harnesses' native plugin formats are not accepted as packages.

## Install and use

1. In **Settings → Plugins**, choose **Install Creative brief**, select a ZIP,
or enter a local directory/ZIP path or public HTTPS ZIP URL. Paths refer to the
computer running the backend and must stay inside its workspace. Relative paths
start at that workspace; absolute paths inside it also work. Use a package
folder such as `plugins/my-plugin`; the workspace root, `projects/` and
`.opendirector/` are excluded. For packages in other locations, use
**Choose ZIP file**. Only install packages you trust.
2. Enable the desired harness under **Enabled harnesses**. Dependencies must be
installed at their declared versions and enabled for that same harness first.
3. Choose that harness in the assistant and open **Skills**. Select the plugin
and describe your goal in Chinese or English. Existing model configuration and
harness authentication still apply.
4. Inspect the resulting project assets. The official Creative brief example
reads project context, prepares a brief and shot outline, and publishes an
editable Markdown text asset. It does not itself request image/video generation.

The application includes only the official discovery catalog. Example payloads
are downloaded on explicit installation; source checkouts can use the matching
local example. No optional plugin is activated or added to the default Skill
catalog automatically. Installation validates files and never runs package hooks.
Once enabled, Skill instructions and scripts use the harness's existing tools,
permissions and project business commands; installation does not grant new access.

## Disable, remove and update

Changes apply to subsequent turns. Already accepted turns keep their Skill
snapshot. When the enabled package set changes, a new native session starts with
the saved conversation history instead of resuming the old plugin context.
Remove a disabled Skill from any unfinished message before sending it; the server
rejects selected Skills that are no longer available.

Disable dependent plugins first. To change a package version, disable and uninstall
the old package, install the new one, then enable its harnesses. Installing identical
contents again preserves activation; different contents with the same ID are
rejected until the previous package is removed. Dependencies use exact versions,
not ranges, and there is no automatic dependency download or update.

The registry and immutable package cache live under the backend workspace's
`.opendirector/plugins/`. They survive restarts and apply across its projects.
Uninstall removes registration and future discovery. Cached package files remain
for in-flight turns; there is no automatic cache deletion. Project assets,
generation configuration, conversation history and execution receipts remain in
the unified project and can still be edited after disabling or removing a plugin.
If a cached package is damaged, uninstall and reinstall from a valid source.
Reinstallation preserves the damaged cache under `.opendirector/plugins/.damaged-*`
before publishing the validated replacement; it does not delete the old files.

## Make a custom package

Copy [plugins/template](../../plugins/template) and change the ID, bilingual name,
description, supported runtimes and Skill instructions. Keep these identities equal:

```text
opendirector-plugin.json → id: my-creative-tool
skills/my-creative-tool/SKILL.md → name: my-creative-tool
```

The manifest requires `schemaVersion: 1`, a lowercase hyphenated ID (up to 64
characters), a `major.minor.patch` version (optional prerelease), `zh-CN` and `en-US`
names/descriptions, and one or more runtime IDs. Runtime IDs are `default`,
`opencode`, `codex`, `claude`, `jiuwenswarm`, `deepseek`. Optional `dependencies`
maps plugin IDs to exact versions, for example `{"studio-brief": "1.0.0"}`.

The Skill needs YAML frontmatter with matching `name` and a nonempty `description`.
Additional or nested `SKILL.md` files are rejected, regardless of filename case.
Keep templates and scripts under its directory: those resources are copied into
the turn's native Skill directory. Other package files are retained but are not
exposed as Skill resources. Publish outputs through the existing `opendirector`
CLI or business tools, preserving command IDs, version checks, locks and receipts.
Do not maintain a separate editable project or write the project JSON directly.

Install a directory inside the backend workspace while developing. Parent path
aliases are resolved before checking the workspace boundary. File reads pin every
path component without following links, and reject hard links. Empty resource
files are allowed. To share it, ZIP its **contents**, with
the manifest at the archive root, and use **Choose ZIP file** or a public HTTPS
download URL. A package permits up to 256 files/archive entries, 2 MiB per file,
20 MiB unpacked and 10 MiB compressed. Skill text is limited to 64 KiB. Links,
special files, encrypted archives, ambiguous or escaping paths, private network
URLs and credentials in URLs are rejected. Redirect destinations are also checked.

Official maintainers edit `packages/agent/plugin-examples/` and run
`python scripts/package-plugin-examples.py` with the project's Python dependencies
installed. Commit the resulting `plugins/catalog.json` and `plugins/examples/`
ZIP together; the catalog pins the expected package content digest.
Loading
Loading