[jasper-yl]

Which issue or RFC does this PR close?

This PR proposes a new RFC that replaces the plugin contracts and management mechanisms of RFC #2175 (Artifact plugins, implemented in #2246). It is implemented in #2616. Standalone Source plugins and collection, which replace RFC #2012, are proposed separately in #2617.

Rationale for this change

The managed Artifact plugin framework makes PC Server carry plugin lifecycle on behalf of third-party code: persisted enable/disable/reload/unload state machines, registration-generation fencing, and frozen content schemas with framework-built declarative indexes. As discussed with maintainers, plugins should instead implement a few interfaces that PC Server calls when needed, similar to Dify's plugin model, and own their content structure and indexes.

What changes are included in this PR?

New RFC docs/{en,zh}/rfcs/2549-plugin-interfaces.md (Chinese first, English translation in sync):

• Plugin shape: a directory with plugin.py, which assigns an ArtifactPlugin declaration to plugin; no manifest file. setup(ctx) returns the plugin object.
• Methods: render_artifact (required), generate (required with a schedule or on_sources), and optional search_artifacts and user-change methods (create_artifact, update_artifact, merge_artifacts, forget_artifact, restore_artifact). A methods-at-a-glance table lists when each is called and where it runs. Reads, history, governance, and tags call no plugin method.
• Presentation and search belong to the plugin: core builds no index for plugin families. GET .../{artifact_id}/rendering returns the plugin's default presentation. Generic search passes the complete request to search_artifacts, and core keeps only current, active revisions the caller may read. Prepared Context sections may list plugin families, with an optional search passed through.
• Generation and user changes: generate writes in async with writer.transaction(), committed with the consumption cursor; user changes go through the plugin, with core handling authorization, version checks, and provenance. Plugins may declare their own Source types to record what users asked for.
• Execution: background calls run in Supervisor Workers; synchronous calls run in a per-plugin host process that core manages. ctx.storage and ctx.models give plugins dedicated storage and the Server's models without credentials.
• Persistence: one new migration revision removes the old framework's storage only when it holds no data (otherwise the upgrade is refused), adds pc_artifacts.metadata with the writing plugin's name and version, accepts plugin: bindings without registration, and keeps frozen revision resources unchanged; portable revision records gain metadata.
• Lifecycle: plugins load at startup with no persisted plugin state. Hot reload, data upgrades, plugin APIs, and pages are in RFC #2579.

Are there any user-facing changes?

This PR changes documentation only. The proposed design, implemented in #2616, removes /v1/admin/artifact-plugins, powercontext.artifact_plugins, and POWERCONTEXT_SERVER_ARTIFACT_PLUGINS_DIR, and refuses to upgrade while plugins of the old framework still hold data. Typed clients see CreateArtifactRequest become a choice between built-in and plugin branches, and several family fields (ArtifactCreated.family, TaggableArtifactFamily, ContextAssemblySection.family, receipt families) and CreateSourceRequest.source_type become strings; wire formats of existing requests are unchanged.

How was this change tested?

• uv run prek run --files docs/en/rfcs/2549-plugin-interfaces.md docs/zh/rfcs/2549-plugin-interfaces.md
• Checked that both locales have matching sections, tables, and code blocks.
• The implementation in feat(plugins): load directory plugins that generate, present, search, and change their own Artifacts #2616 was tested as described there.

AI usage statement

Drafted with Claude Code (Claude Opus 5.5) under the author's direction and review.

🤖 Generated with Claude Code

[hidb4ai]

The simplification is reasonable, but the retry/storage and no-op/provenance contracts need to be consistent before this RFC is accepted. The two inline findings apply to both translations.

[hidb4ai]

The content-digest storage guidance and the explicit distinction between generation no-ops and user-edit provenance address my earlier RFC findings. One new contract gap remains: plugins cannot detect a same-dimension embedding-model change.

[hidb4ai]

[P2] Preserve an embedding-space identity for plugin indexes

Replacing embedding_profile with availability flags and a dimension leaves plugins unable to implement the rebuild-on-configuration-change rule below. If an index was built with model A and Server restarts with a different model B of the same dimension, all exposed metadata stays unchanged, but embed() now returns vectors from a different space. The plugin can silently compare them with A's persisted vectors or mix both spaces in the same index. The existing core distinguishes same-dimension profiles for precisely this reason. Expose a non-secret embedding-space/profile fingerprint that changes with the model or relevant encoding configuration, and require it to match the persisted index before reuse. Please align both language versions.

[hidb4ai]

LGTM