Repository navigation
RFC: DSH plugin integration and the domain capability authoring contract - #9011
huangruiteng wants to merge 1 commit into
Conversation
Signed-off-by: huangruiteng <huangrt01@163.com>
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent | self_reported | Gemini (Google)
基于精确 head f180192083f3d1015b73e6a7d12b3ac2d2fca0a8 对 PR #9011 完成全量 diff 阅读、跨仓源码核对、链接锚点校验与本地门禁验证,未发现阻塞性问题,结论为 APPROVE。
动机 / Motivation
希望接入 LoopX 领域能力、复用既有领域判断或设计新能力的 DSH 插件作者与能力维护者,在阅读 Goal-scoped Capability Portfolio RFC 时会遇到接入选型与边界不明确的问题。
此前 DSH 插件作者面对已有领域能力与新能力时缺乏统一决策路径,容易混淆单向事件观测、扩展实现与独立能力注册三种模式,甚至在未验证跨宿主契约测试前误建生成器;本次双语 RFC 修订明确给出以领域结果与判断为单位的三层接入对照表、原生操作失联对账约束及先做只读参考原型再评估骨架标准化的准则,使作者无需猜测宿主入口与 schema 归属。 若维持现状不修订,新接入的 DSH 插件作者可能自行维护平行 schema、错误重试已生效的外部操作,或在缺乏多入口复用证据时过早引入复杂脚手架。英文与中文两份 RFC 镜像文档同步落地 DSH 接入决策路径、三类作者交付模式对照表、跨会话与多消费者验收行以及第 12 节未决问题第 5 项,所有相对链接、锚点与双语校验均在工作树精确 head 验证通过,未触及任何运行时或 UI 代码。 本次改动不实现 DSH 能力代码生成器或通用 SDK,不修改运行时控制面代码、扩展清单或 CLI 行为,也不声称已完成跨宿主一致性测试或真实现场评估。
改动思路 / Approach
本次修订以“领域能力由它负责的结果与判断定义”为主线,复用既有 catalog、Goal binding、agent_context 三个生命周期 hook 以及扩展清单边界,而不是为 DSH 单独设计第二套注册或状态模型:
| 接入目标 | 既有复用边界 | 责任与恢复归属 |
|---|---|---|
| 向已有能力提供 DSH 事件观察 | reliability-diagnostics 目录声明 dsh-session-events(npm 插件),Cordis 订阅映射为 reliability_observer_envelope_v0 |
只读旁路观察,关闭即停,不持有发送或调度权限 |
| 通过 LoopX 扩展实现已有能力 | [[implements]] 指向既有 capability ID 与协议(如 packages/loopx-media/extension.toml) |
由原能力解析 provider、校权并消费结果 |
| 提供可独立验收的新领域结果 | [[provides]] 声明能力并引用 loopx_external_domain_capability_profile_v0 |
领域作者拥有验收标准、权限映射与执行回执解释;失联后先对账再决定是否重试 |
在规划与演进策略上,修订稿补充了“以观察到的错误或具体验收缺口触发发现、按工作性质选择 Turn-start / post-writeback / direct 入口、多消费者复用同一领域结果投影并独立恢复失败交付”的闭环原则,同时把 DSH 能力生成器本身保持为开放设计议题,要求先用单个只读参考实现完成等价输入跨入口验证,再提取标准骨架。
具体改动 / Changes
- 规范依据:
docs/architecture/rfcs/goal-scoped-capability-portfolio-v0.md(基线 commit1083771794744d663eb8c025788bd6c116f8c113)及docs/reference/extensions.md。 - 准则映射:
RFC-SEC-1-4-5-BOUNDARY(implemented):保持配置、provider 状态、权限与回执的单一 owner 边界,不引入第二份真相源或隐式授权。RFC-BILINGUAL-MIRROR(implemented):中英文 RFC 镜像(goal-scoped-capability-portfolio-v0.md+100/-6 行、goal-scoped-capability-portfolio-v0.zh-CN.md+68/-4 行)同步更新,语义逐段对齐。RFC-OPEN-DECISION-5(deferred):将 DSH 接入标准化层级(文档化示例、共享契约测试、生成器)保留至第 12 节第 5 项,待只读参考实现对比完成后决策。
关键内容讲解
- 领域能力单元与 DSH 单一观察边界(第 1、4 节)
修订稿以 Issue Fix 为例界定“领域能力对结果与判断负责、Kernel 负责接纳后继与等待/恢复”,并说明 DSH 插件可仅提供只读会话事件观察(dsh-session-events->reliability-diagnostics)。经核对packages/dsh-loopx-plugin/src/observer.ts与loopx/capabilities/reliability_diagnostics/catalog_entry.py,dsh-session-events确以origin=extension、status=declared_default_off声明在能力目录中,采用严格 allowlist 字段(reliability_observer_envelope_v0)且与控制面隔离。 - 发现触发、调用时机与多消费者独立恢复(第 5 节前段)
用具体的 PR 反复修改案例说明应先排查 Issue Fix 既有判断、Goal enablement 与宿主是否真实带证据调用入口;梳理 Explore Turn-start 入口(loopx/capabilities/explore/catalog_entry.py)、Periodic Report 写回后触发(loopx/capabilities/periodic_report/post_writeback_hook.py)与 Deep Research 直接发起(loopx/capabilities/deep_research/README.md)的分工,并以 Issue Fix 同时投影至explore_projection.py与periodic_report.py说明报告投递失败时可单独恢复报告而保留已完成修复。 - DSH 插件接入与能力作者骨架(第 5 节新增小节 & 第 12 节第 5 项)
明确映射session/event到reliability_observer_envelope_v0时须保留来源、会话、序号与时钟,并对照packages/dsh-loopx-plugin/src/native-operation.ts确认原生操作适配器在响应丢失后禁止直接重试、要求对账(// No retries: a lost reply may follow a committed canonical consumption)。同时准确界定loopx extension init当前仅生成standalonePython 扩展骨架(经核对loopx/extensions/scaffold.py为starter_kind="standalone"、capability_id=None),提出“单一 versioned schema 留归领域 owner + 先建只读参考实现并验证未知 schema 拒绝、停用停止采集、宿主重载不重复结算与有副作用撤权/对账”的收敛路线。 - 演进归属与跨会话/多消费者验收行(第 5 节末 & 第 9 节)
对接loopx/control_plane/capabilities/goal_capability_organization.ts说明 Goal 采用策略调整、能力 owner 可逆规则修复与注册新能力的分工,并在第 9 节验收表新增“跨会话的领域判断”(引用tests/capabilities/test_issue_fix_pr_lifecycle_review_response.py作为预期决策基线)和“一个结果由多个能力消费”两条可检验目标。
对主干的风险 / Risks
- 无阻塞性回归风险:本 PR 仅修改两份公开架构 RFC 文档,不改动生产代码、数据库 schema、CLI 入口或 UI 表面;公共边界扫描与双语一致性脚本均通过。
- 非阻塞说明 1(参考与实施边界):第 9 节新增的跨会话留出 PR 对比、多消费者重试及第 12 节第 5 项参考原型实验属于未来待执行验收项(文档已诚实标注预期来自现有分支单测与未来独立测量),当前尚不构成运行时覆盖保证。
- 非阻塞说明 2(文档细节微瑕):RFC 顶部元信息
Last normative revision仍保留2026-10-10且附录 B 未追加新条目,不过scripts/generate_rfc_status_index.py --check验证通过;另observer.ts实际同时订阅session/created、session/disposed与session/event(正文以session/event为例,表格已写明订阅与清理入口),均不造成契约误导。 - 验证观察(worktree 依赖差异):在缺少
node_modules的全新 detached worktree 中直接运行examples/semantic-vocabulary-drift-smoke.py会因缺少typescriptnpm 依赖报错(经验证origin/main基线存在完全相同的报错);在 worktree 挂载主仓同版node_modules后复跑loopx canary premerge --from-git-diff --git-diff-base origin/main,全部 11 项门禁检查通过。
我的整体评价 / Verdict
- 长程与用户体验影响:
long_horizon=preserved、user_experience=preserved。未新增控制面复杂度或交互负担,反而为跨插件生态作者提供了清晰、可回滚的领域契约选型指导。 - 视觉检查边界:本 PR 仅修改 docs/architecture/rfcs/goal-scoped-capability-portfolio-v0.md 与 docs/architecture/rfcs/goal-scoped-capability-portfolio-v0.zh-CN.md 两份公共 RFC 文档,无任何渲染界面、前端组件或 CLI 展示变更。(
unverified_scope:none)。 - 改动体量与兼容性:两份 RFC 镜像共 +158/-10 行(
code_volume=necessary),无兼容性面变化(compatibility_assessment=not_applicable)。 - 本地验证矩阵(精确 head
f180192083f3d1015b73e6a7d12b3ac2d2fca0a8):PASS:scripts/check_rfc_bilingual.py --base origin/main --head HEAD(双语同步门禁通过)。PASS:scripts/generate_rfc_status_index.py --check(RFC 状态索引校验通过)。PASS:loopx check --scan-path ...(2 份文件公共边界扫描 0 error / 0 warning)。PASS:中英文共 32+ 处相对文件路径与标题锚点静态解析全部命中且正文描述与源码实况一致。PASS:loopx canary premerge --from-git-diff --git-diff-base origin/main(带node_modules下 11/11 全通过:4 项 diff/双语直接检查、2 项 catalog canary 含semantic-vocabulary-drift-smoke.py、8 项 risk-profile smoke、1 项公共边界检查)。PASS:pytest141 项issue_fix/reliability_diagnostics测试 + 10 项extensions测试 +examples/reliability_diagnostics/dsh-shadow-observer-fixture-smoke.py。UNVERIFIED:远端 GitHub CI 状态汇总未提供;依据personal-loopx-maintenanceGoal 的wait_for_ci=false策略,未轮询或等待远端 CI。
English Verdict: APPROVE
Goal and delivered outcome
How much should a DSH plugin author need to know about LoopX to contribute a useful domain capability? This bilingual RFC revision takes the existing DSH session observer and Issue Fix review decisions as working examples. It covers how a Goal discovers an existing capability, when the host invokes it, how multiple capabilities consume one outcome, and how to evaluate a change to domain judgment across sessions.
Design questions for review
[[implements]], or publish a new caller outcome through[[provides]]. The RFC gives each path a concrete entry point. For operations that can change external state, please review where binding and permission are checked, and how a lost response is reconciled.loopx extension initgenerates a standalone provider. This PR leaves a capability SDK or generator open for review.Read the English authoring proposal or the Chinese section.
Author declaration
mainas the intended base.Scope and validation
Tested revision
f180192083f3d1015b73e6a7d12b3ac2d2fca0a8. Run statefinished. Inputs were synthetic and public fixtures.examples/reliability_diagnostics/dsh-shadow-observer-fixture-smoke.pyexercised a synthetic DSH-shaped event streamScope is two public RFC files. Runtime and UI impact: none. The next design decision belongs to the DSH adapter, capability and extension maintainers.