Repository navigation
docs(rfc): propose source plugin framework - #2012
Conversation
| | Instance connection | plugin instance Runtime proves its own identity to management | | ||
| | External system | Stored and interpreted by plugins, optionally referenced in Config | | ||
|
|
||
| Before business execution, deployment verifies actual identities, registers Definitions, grants Scope permissions, records instance scope and connection identities, and checks access using execution credentials. Existing identity and Access interfaces are reused. Instances may be registered without Scope authorization but cannot accept work for that Scope. write has no separate execution credentials and does not borrow deployment authority for daily saves. Credentials are excluded from command arguments, catalogs, and ordinary logs; cross-machine connections use TLS or equivalent security. |
There was a problem hiding this comment.
[P2] RFC 缺少模板要求的收尾章节，而它们恰好承载这个提案最需要的论证
对照 docs/en/rfcs/0000_example.md，本 RFC 只有 Summary / Motivation / Guide-level / Reference-level，缺 Drawbacks、Rationale and alternatives、Prior art、Unresolved questions、Future possibilities 五个章节。双语结构完全对齐（这点做得好），但两边同时缺。
这些不是格式仪式——对本提案恰好是最需要的部分：
- Drawbacks / 安全边界：框架要在 Server 侧加载并执行第三方插件代码（插件实例 Runtime 甚至跨机连接），这引入了任意外部代码执行面。文末「Permission responsibilities / Credentials」两节覆盖了授权与凭据，但没有一处集中讨论信任边界：插件代码以什么身份运行、崩溃/恶意行为的爆炸半径、是否需要进程隔离或 capability 降级。这是评审人必然会追问的问题。
- Rationale and alternatives：为什么不沿用 feat(sources): add Source Definition and Connector contracts #1400 已有的 Source Definition 注册表 + MCP 提交管线、只把「发现/加载第三方实现」做成一个薄扩展，而要引入独立的插件管理服务 + 实例 Runtime + 目标管理这三层？现有文中的论证散落在各节，缺少一个集中的方案对比表。
- Unresolved questions：插件签名/供应链校验、插件 API 的版本兼容承诺、collect 插件对 Server 稳定性的影响上限等，都还没交代由谁在何时决定。
作为 draft 这些可以后补；建议在转 Ready 之前补齐，尤其第 1 点。语言与结构质量本身没有问题。
There was a problem hiding this comment.
-
第一版只运行部署者信任的插件代码，不提供安全沙箱。write 使用 Server 进程的系统权限，阻塞、资源耗尽或进程级故障可能影响整个 Server；collect 使用独立 Runtime 进程及受 Scope 限制的 PC 执行身份，但进程分离不等于完整资源隔离。随仓库提供的插件及依赖纳入项目的审查、测试和发布流程；用户自行提供的插件由部署者审核，需要更强隔离时由部署环境提供。这些执行身份和影响范围已补充到 RFC 的“缺点”章节。
-
我之前考虑过另一版设计：不引入管理服务，一份目录配置启动一个后台进程，pc-source run / stop 负责启动和停止。插件复用 feat(sources): add Source Definition and Connector contracts #1400 的 Worker、提交和 checkpoint 管道，以独立进程采集并向 PowerContext Server 写入自定义 Source。框架只提供加载、后台启停和数据管道，目标管理由插件自行实现。
这种方式足够灵活，也可以支持动态新增采集目标。但目标格式、更新入口和处理方式由各插件约定，宿主没有统一的能力发现、添加目标、查询提交和启停入口。如果需求只是自定义数据类型和采集逻辑，管理由用户自行负责，这个方案已经足够。
考虑到 PowerContext 后续可以随仓库提供不同场景下开箱即用的插件，希望不同宿主能通过公共 MCP 统一使用内置与自定义 Source 能力，因此把目标管理和实例生命周期纳入框架。采集节奏、分页和重试仍由插件决定。
独立管理服务不是统一入口的必要条件，将管理模块放进 Server 同样可行。选择独立服务主要是为了分离管理模块与 Server 的进程生命周期，代价是额外部署和通信成本。RFC 已补充这两种方案与最初方案的对比。另外，write 选择在 Server 内执行，是为了减少保存已有内容所需的执行组件和执行链路，外部执行同样可以同步返回。 -
第一版暂不提供插件分发体系或自动签名与供应链验证。项目只对随 PowerContext 仓库提供的插件负责；用户自行提供的插件仍可加载，其来源和依赖由用户负责审核。
插件 API 先采用明确的版本检查：加载时检查 plugin_api_version，不支持则拒绝，不建设多版本兼容层，也不承诺旧版本支持周期。随仓库提供的插件随框架同步维护，具体支持版本与拒绝行为会在实现 PR 中列明并验证。
collect 插件在独立 Runtime 中执行，减少执行故障直接传播到 Server 的风险，但不能限制提交负载，也不隔离同机资源竞争。collect 复用 Server 的提交入口，实现 PR 中会核实已有保护，并补齐必要的请求大小、并发及过载处理，首次发布前由维护者确认。更强隔离暂不纳入本次范围。上述边界和待验证事项已补充到 RFC。
There was a problem hiding this comment.
感谢回复。我按当前 head 1c7ed6fa1347e1fdad1f2c50f407a78da4aaa58e 逐条核对，这五个章节现在仍然不存在。
docs/en/rfcs/2012-source-plugin-system.md 与 docs/zh/rfcs/2012-source-plugin-system.md 各 423 行，双语结构一致，章节顺序为：Summary / Motivation / 1. Overview / 2. Architecture / 3. Public MCP / 4. Plugin interfaces / 5. Lifecycle, restarts, and permissions，最后一个标题是 ## Permission responsibilities and operation conditions 与 ## Credentials and initial authorization，文件到此结束。
逐项核对结果：
# Drawbacks（中文「缺点」）：不存在。全文没有任何 Drawbacks 或「缺点」标题。# Rationale and alternatives：不存在（您评论里写出的那版「不引入管理服务、一份目录配置启动一个后台进程」的备选设计只在评论中，没有进文档）。# Prior art：不存在。# Unresolved questions：不存在。# Future possibilities：不存在。
您回复中描述的执行身份与影响范围（write 使用 Server 进程权限、collect 使用独立 Runtime 进程与 Scope 受限身份、进程分离不等于完整资源隔离、随仓库插件纳入项目流程而用户插件由部署者审核）确实已经写进 RFC，但它落在 §5 的 ## Permission responsibilities and operation conditions 与 ## Credentials and initial authorization 之下，并没有形成独立的 Drawbacks 章节；也就是说「信任边界」这块论证已经具备，只是没有出现在模板要求的位置，另外四节则完全没有。
这不是格式仪式：对照 docs/en/rfcs/0000_example.md，并统计仓库现状（用 grep -c "^# Drawbacks" / Rationale / Prior art / Unresolved / Future possibilities 逐文件核对），1400、1417、1435、1510、1515、1557、1652、1708、1783、1803、1809、1858 等近期 RFC 五个章节全部齐备；缺章节的是 1429、1549 等较早的文件。因此这是本仓既有惯例。
建议：把已经写好的信任边界内容提升为独立的 # Drawbacks，补上 # Rationale and alternatives（含被否掉的进程式方案）、# Prior art、# Unresolved questions、# Future possibilities，中英同步。
There was a problem hiding this comment.
抱歉，是我漏了 push，现在已经同步了。
There was a problem hiding this comment.
至于我前面回复中提到的旧的设计方案，我并不打算完整描述在本 pr 中，设计其实很简单，会更贴近于您提出的“在 #1400 已有能力上增加插件发现和加载”：保留 SourceDefinition、Projection、Worker、提交与 checkpoint 契约，由框架补充本地插件发现、配置校验、独立进程启停及资源清理，使用户无需修改 Server 就能接入自定义数据类型和采集逻辑。框架不引入共享管理服务或统一目标管理，插件自行维护采集范围和运行节奏。它的优势是组件少、对 Server 的扩展小，自定义代码在外部进程执行；代价是不同插件各自定义新增目标、查询和控制方式，宿主需要逐插件对接。新方案增加管理服务、实例 Runtime 和目标管理，主要是为了提供跨插件、跨宿主的统一管理入口，而不是因为原方案无法完成自定义采集。
|
现在的表数量比较多，新加表比较慎重，优先考虑复用表，可新加字段。确实无法复用的再考虑新建，同时综合考虑新表未来的扩展性。 |
Which issue or RFC does this PR close?
Proposes a new Source plugin framework RFC; no issue is closed.
Rationale for this change
Users need to develop custom Source plugins or use existing ones to support different data types, Projections, and collection logic without modifying PowerContext core. Applications and hosts need a common way to discover and use built-in and custom Source capabilities.
What changes are included in this PR?
Adds matching English and Chinese RFCs covering:
write: Server loads custom Definition and Projection implementations and synchronously saves complete content supplied by the caller.collect: plugins control collection timing and reuse the existing Worker, submission, and checkpoint pipeline.The RFC includes architecture and flow diagrams. Deployment guides and runnable plugin examples will accompany implementation.
Are there any user-facing changes?
Documentation only; no changes to runtime behavior or persisted data formats.
How was this change tested?
uv run prek run -a: all hooks, including type checking, passed.git diff --cached --check: passed before committing.Validation covers documentation only; the proposed functionality was not tested at runtime.
AI usage statement
Codex assisted with drafting, editing, and reviewing the bilingual RFCs based on the contributor's design decisions and feedback.