diff --git a/docs/architecture/rfcs/README.md b/docs/architecture/rfcs/README.md index 4932f56ab..9cb78e57c 100644 --- a/docs/architecture/rfcs/README.md +++ b/docs/architecture/rfcs/README.md @@ -139,6 +139,18 @@ changes. ## Planning, Research, And Adaptive Intelligence +- [Goal-scoped Capability Portfolio and Connector Lifecycle v0](goal-scoped-capability-portfolio-v0.md) + ([中文版](goal-scoped-capability-portfolio-v0.zh-CN.md)) + - **RFC status:** Draft, under maintainer review. + - **Delivery on `main`:** Proposal; catalog, Agent-context hooks and connector + inventory are prerequisites rather than a shipped portfolio. + - **Current boundary:** Existing Goal enablement activates supported capability + behavior without a second Portfolio opt-in. Direct work needs no DAG or + adoption record; material dependencies use bounded composition. Policy stays + capability-owned and existing config/effect/admission owners remain authoritative. + M0 includes affected product entry points; merged #4813 supplies evidence + infrastructure, not connector or Portfolio qualification. No new authority. + - [Agent Judgment and Optional Independent Assessment v0](optional-semantic-assistance-jev-v0.md) ([中文版](optional-semantic-assistance-jev-v0.zh-CN.md)) - **RFC status:** Draft; M0 [accepted-for-discussion](https://github.com/loopx-project/loopx/pull/4749#pullrequestreview-5259253204) only; Q1–Q7 remain pending. diff --git a/docs/architecture/rfcs/external-evidence-research-capability-v0.md b/docs/architecture/rfcs/external-evidence-research-capability-v0.md index bc3027d23..ae9101239 100644 --- a/docs/architecture/rfcs/external-evidence-research-capability-v0.md +++ b/docs/architecture/rfcs/external-evidence-research-capability-v0.md @@ -4,7 +4,7 @@ - Scope: provider-neutral research planning, provenance admission, projection, and retirement - Roadmap: S8 capabilities and domain integration -- Language note: the Chinese version is a semantic mirror; drift is a defect. +- Language note: [中文版](external-evidence-research-capability-v0.zh-CN.md) is a semantic mirror; drift is a defect. ## Problem diff --git a/docs/architecture/rfcs/external-evidence-research-capability-v0.zh-CN.md b/docs/architecture/rfcs/external-evidence-research-capability-v0.zh-CN.md index e925ccff0..7af8a1e95 100644 --- a/docs/architecture/rfcs/external-evidence-research-capability-v0.zh-CN.md +++ b/docs/architecture/rfcs/external-evidence-research-capability-v0.zh-CN.md @@ -3,7 +3,7 @@ - 状态:Draft implementation slice - 范围:provider-neutral 的研究规划、provenance 准入、投影与退休 - 路线图:S8 能力与领域集成 -- 语言说明:本文件与英文版语义镜像;语义漂移属于缺陷。 +- 语言说明:本文件与 [English](external-evidence-research-capability-v0.md) 语义镜像;语义漂移属于缺陷。 ## 问题 diff --git a/docs/architecture/rfcs/goal-scoped-capability-portfolio-v0.md b/docs/architecture/rfcs/goal-scoped-capability-portfolio-v0.md new file mode 100644 index 000000000..4db16f872 --- /dev/null +++ b/docs/architecture/rfcs/goal-scoped-capability-portfolio-v0.md @@ -0,0 +1,656 @@ +# RFC: Goal-scoped Capability Portfolio and Connector Lifecycle (v0) + +- **RFC status:** Draft +- **Delivery maturity:** Proposal; existing catalog, hooks and external-evidence slices are partial prerequisites +- **Authors / owners:** LoopX capability and control-plane maintainers +- **Created:** 2026-09-21 +- **Last normative revision:** 2026-09-21 +- **Implementation baseline:** `65afc4872db67d36f74625a9e53ae63da2bc619c` +- **Related contracts:** [overall roadmap](loopx-overall-roadmap-v0.md), + [research exploration](research-exploration-control-plane-v0.md), + [agent loop effects](agent-loop-effect-interpreter-v0.md), + [post-outcome memory utility](post-outcome-memory-utility-attribution-v0.md), + [extension reference](../../reference/extensions.md), and + [external-evidence lifecycle PR #4813](https://github.com/loopx-project/loopx/pull/4813) +- **Language mirror:** [中文版](goal-scoped-capability-portfolio-v0.zh-CN.md) + +## Document map and maintenance contract + +Sections 1–10 are the durable design and acceptance contract. Section 11 is +the normative delivery plan. Section 12 contains unresolved decisions. +Appendices are non-normative evidence and history. RFC maturity and delivery +maturity are independent. The English and Chinese documents are a semantic mirror +and must change together. + +--- + +## 1. Decision summary + +LoopX will add a **Goal-scoped Capability Portfolio** that lets an Agent reason +about, select, compose, evaluate, degrade and retire capabilities against the +Goal's outcome and acceptance gaps. It owns adoption, composition and lifecycle +transition decisions. It indexes immutable receipts from their existing owners; +it does not own or restate their effects. It does not copy capability +configuration, provider state, evidence, Todo state, authority grants or memory +into another source of truth. + +The portfolio composes existing owners: + +1. the capability catalog describes what can be considered; +2. existing Goal configuration and external-capability bindings select an exact + operation, provider revision and profile digest; +3. `agent_context` projects a bounded plan at `before_plan`, freezes a selected + route at `before_delegate`, and returns typed outcomes at + `after_delegate_result`; +4. the external-evidence lifecycle qualifies repeatable source methods and + connectors; +5. Decision Context, Explore and reward memory remain downstream consumers + with their own admission rules. + +**Goal enablement is sufficient to activate the capability's supported behavior.** +Once the existing configuration owner resolves a capability as enabled for a +Goal's current Agent/surface scope, its applicable hooks and normal execution +route participate automatically; +there is no second Portfolio switch, manual adoption step or per-Turn reminder. +Activation follows the capability's trigger, budget and authority contract. It +does not mean invoking every enabled capability on every Turn. + +Use the least machinery that satisfies the work: no enabled capability adds no +Portfolio work; one capability or several independent capabilities use their +existing direct routes; a material dependency or selection tradeoff introduces +a bounded composition. Durable portfolio state is created only for an explicit +cross-Turn adoption/lifecycle decision that existing configuration cannot express. + +Composition advice is fail-open; existing capability obligations are not. +An unavailable portfolio must not suppress enabled direct routes or bypass +Todo admission. Discovery cannot install software, enable a provider, enlarge +scope, change model authorization or approve a protected effect. + +This RFC does not approve automatic capability installation, a connector +marketplace, domain-specific ranking in Core, or finance execution authority. + +## 2. Problem and motivation + +LoopX already has a catalog, extensions, readiness checks, Goal/Todo capability +requirements, three Agent-context hooks, external-evidence planning, Explore, +Decision Context and reward memory. A fresh Agent still has to infer how these +pieces fit together. A domain prompt or local strategy document often supplies +the missing organization, so adoption reasoning disappears across sessions and +another Agent may repeat the same discovery, select redundant sources or treat +provider readiness as evidence quality. + +Connectors expose the same gap. The current connector registry is useful +inventory and usage telemetry. Registration, readiness and call counts do not +prove source coverage, freshness, rights, execution, parent admission or +decision value. A stable source should be promoted only after discovery and a +bounded trial, and should later degrade or retire when it becomes stale, +unreliable, costly or unused. + +Concrete example: a research Goal needs current primary evidence, independent +counterevidence and a read-heavy worker. The Agent should discover an existing +external-research method, one qualified source connector and an eligible worker +route; explain why each was selected; freeze revisions and budget; record +partial coverage and failures; and tell whether the result changed the +decision. Today those facts live in separate projections and prose. + +### Invariants + +- Portfolio adoption never creates or enlarges authority. +- Configuration stays with its original owner; the portfolio stores only + exact references, digests and bounded readback. +- `ready`, `executed`, `read`, `admitted`, `decision-changing` and + `domain-eligible` remain distinct states. +- One source observed through multiple connectors or workers is not independent + evidence. +- Unknown, stale, partial and unavailable are explicit; an empty result is not + complete coverage. +- A model response, tool call, commit or connector invocation is not effect + evidence by itself. +- Replays are idempotent and revision drift cannot silently reuse an old plan. +- CLI, managed Turn, frontend and Lark read the same public projection. +- Enablement, adoption policy and owner qualification are separate typed facts. +- No Portfolio record is required to use an already enabled capability. +- Feature-off and portfolio-failure paths preserve existing capability routes + and their obligations, including explicit automation settings. + +## 3. Scope and non-goals + +### In scope + +- a provider-neutral capability descriptor reference and Goal adoption record; +- direct activation first, with a bounded composition DAG only when needed; +- trial, adoption, degradation and retirement decisions, plus typed references + to owner receipts; +- a connector qualification profile built on the external-evidence lifecycle; +- injection through `before_plan`, `before_delegate` and + `after_delegate_result`; +- exact effective-configuration and provider-revision readback; +- shared CLI/frontend/Lark inspection and feedback; +- finance and one non-finance journey as qualification consumers. + +### Non-goals + +- replacing Goal, Todo, quota, claim, lease or shared-authority state; +- copying provider credentials, raw source bodies or private configuration; +- moving Decision Context, Explore or reward-memory state into the portfolio; +- inventing a universal score across unrelated capabilities; +- automatic installation, permission grant, payment, publishing, signing or + trading; +- treating a portfolio recommendation as a runtime or domain authorization; +- requiring every Turn to scan every installed capability. + +## 4. Current-system contract + +At the implementation baseline: + +- the capability catalog and extension manifests describe installed and enabled + implementations, declared providers, hooks, permissions and readiness; +- `goal.external_capability_bindings` already owns durable Goal-scoped enablement + for exact operations, provider revisions and profile digests; direct bound + invocation admits read-only operations without creating a Turn or spending + quota, while governed effects remain on their existing execution path; +- capability admission and capability memory expose bounded Goal/provider and + host observations but do not grant authority; +- Todo capability gates answer whether a known task can execute; they do not + discover a Goal's missing capability; +- `agent_context` supports `before_plan`, `before_delegate` and + `after_delegate_result` with bounded guidance-only projections; +- the connector registry stores inventory and simple usage telemetry, not + source qualification; +- merged PR #4813 ships `external-evidence` discovery, plan, receipt observation, + parent admission and evidence retirement, with provider execution outside Core; + it does not ship a durable connector qualification state machine; +- Decision Context owns decision evidence, Explore owns research topology, and + reward memory owns qualified reusable outcome lessons. + +The existing configuration editor and Goal capability settings already share +preview/apply/readback. Periodic-report post-writeback hooks resolve their Goal +subscription at composition; reward-memory hooks preserve owner-defined +surface/automation settings. These are reuse boundaries, not proof that every +capability is already wired into every host. General automatic participation, +Portfolio state and cross-surface readback remain proposed here. + +## 5. Proposed architecture + +### Ownership and authority + +**Placement:** proposed capability id `goal-capability-portfolio`; provider id +`builtin` (a design label, not a new registration in this PR). Its independent +caller outcome is inspecting and retaining a Goal's capability choices across +Agents. The small read model belongs with built-in capability policy because it +must understand existing Goal configuration without installing a domain package. +Catalog, configuration, Decision Context and extension lifecycle remain sufficient +for their own contracts; none owns cross-capability selection history. + +Selection, demand detection and lifecycle policy belong to that capability. +Typed normalization, identities and transitions stay in its TypeScript owning +boundary; Python only adapts transport. The generic Kernel reuses registration, +bounded dispatch, schema validation, failure isolation and existing effect/Todo +admission. It must not learn capability names, connector stages, domain ranking +or portfolio adoption states. Registration occurs at the composition root; +shared quota, scheduler and Todo reducers do not import portfolio policy. +Provider execution and independently versioned domain integrations remain in +their existing capabilities/extensions/packages. No new worker, scheduler, +workflow DSL, binding store or generic effect ledger is required. + +The portfolio owns only: + +- why a Goal considered, trialed, adopted, degraded or retired a capability; +- the selected composition and its exact revision; +- portfolio lifecycle-transition receipts and review triggers. + +Existing Goal configuration and external-capability binding remain the sole +runtime enablement owners. Their preview/apply/readback activates supported +behavior without an adoption record; the Portfolio cannot veto that direct +route. Conversely, an adoption record does not enable or invoke a capability: +`adopted` with a missing/stale required binding is visible but not runnable. +Degrade/retire changes Portfolio selection policy only; disabling a capability +still uses its existing configuration owner. + +It references, without copying: + +- catalog and extension declarations; +- effective configuration and provider readiness; +- Todo requirements and authorization decisions; +- external-evidence call/admission receipts; +- Decision Context, Explore and memory artifact identifiers. + +No chat, UI, connector, worker or domain capability may become an alternate +portfolio writer. Mutations pass through one typed reducer and the configured +Goal authority provider. + +### Activation and proportional execution + +The configuration owner resolves inheritance, explicit disable, Agent/surface +scope and supported operation/profile settings once. An Agent-scoped activation +(such as reward memory) never enables other Agents in the same Goal. Portfolio consumes that exact effective result; +it must not infer enablement from catalog presence or reinterpret each owner's +legacy defaults. Existing explicit manual-only or disabled automation settings +remain effective. New supported automatic surfaces need no Portfolio opt-in; +any change to an existing capability's defaults must be disclosed and qualified +by that owner before release. + +| Effective state and current work | Automatic behavior | Additional Portfolio work | +| --- | --- | --- | +| No enabled capability | Existing Agent path | No provider/model calls, hook contribution or durable Portfolio write | +| Enabled but trigger not applicable | Keep capability ready; do not invoke | Empty hot-path contribution; optional inspect reason | +| Enabled and applicable; direct or independent work | Run the existing supported hook/route within its own admission | No trial, DAG, adoption receipt or extra model call required | +| Enabled with a material dependency or tradeoff | Produce the smallest bounded plan; execute through existing owners | Only the selected dependency closure and necessary decision refs | +| Missing binding/readiness/authority/budget | Preserve the owner's unavailable, blocked or deferred result | No implicit repair, provider replacement or grant | + +The host must actually dispatch registered applicable hooks, not merely print +that an enabled capability exists. Commands that have no automatic hook remain +available through the normal Agent/tool route; unsupported host integration is +reported as unsupported, not as successful activation. Automatic protected-effect +execution still requires its existing exact admission. Optional ranking advice +cannot turn a machine-enforced capability obligation into a suggestion. + +Composition is justified by a typed input/output dependency, shared constrained +resource, alternative-provider choice or a named acceptance gap requiring joint +results. Capability count and keyword matches alone are insufficient. Use known +effective configuration first; broaden discovery only for an unresolved gap. +Two independent capabilities stay direct. One operation choosing between costly +providers may warrant a plan. Existing native hooks continue while planning fails. + +### State model and schema + +These are proposed contract sketches, not five mandatory new stores. Direct +activation reads existing owners and creates none of these durable records. +Materialize adoption/lifecycle state only when an explicit cross-Turn policy +cannot be derived from configuration or existing owner receipts; a plan is +needed only for the composed route. A new field must have a real consumer. + +#### `capability_catalog_entry_v1` + +This is a normalized reference to an existing capability declaration: + +```text +capability_id, capability_revision, owner_ref, declaration_ref, declaration_digest +effective_config_ref?, readiness_ref? +``` + +The portfolio does not edit or persist a second catalog. Outcome, phase, schema, +authority, privacy and cost declarations are resolved from their original owners +only when selection needs them. + +#### `goal_capability_adoption_v1` + +```text +goal_id, adoption_id, portfolio_revision +gap_ref, capability_id, capability_revision +status = candidate | trial | adopted | degraded | retired +reason, alternatives[], expected_effects[] +effective_config_ref, effective_config_revision, config_digest +binding_ref?, binding_digest? +trial_budget?, trial_window?, authority_refs[] +owner_observation_refs[], lifecycle_receipt_refs[] +review_after, degradation_conditions[], retirement_conditions[] +created_at, updated_at +``` + +`gap_ref` points to an outcome or acceptance gap; it does not create a second +Todo. A transition needs an expected current revision. Omitting a field preserves +it; explicit clear semantics are defined per optional field. `binding_ref` +resolves the existing Goal binding when execution requires one; it is not a +portfolio-owned copy of provider configuration. Binding readiness/status is a +read-time owner join. An enabled direct capability may have no adoption record; +inspection reports `adoption_status=null`, not a fabricated `adopted` transition. +The read model separates effective enablement, execution mode +(`disabled | direct | composed`) and optional adoption status, with provenance. + +#### `capability_composition_plan_v1` + +```text +goal_id, todo_id?, turn_id?, composition_id, portfolio_revision? +gap_refs[], nodes[], edges[], selected_at, expires_at +node: capability/provider/connector/worker/reducer reference, + phase, input/output schema, exact revision, budget, + required authority, required read/write scope, + disposition, reason +``` + +`composition_id` is a canonical digest of all normalized decision-relevant +fields. The graph must be acyclic. Each considered candidate receives `selected`, +`skipped`, `unavailable` or `incompatible` with a reason. A plan is guidance, +not execution authority. + +#### `capability_owner_receipt_observation_v1` + +```text +observation_id, composition_id?, node_id?, phase +goal/todo/turn identity +owner_kind, owner_revision +owner_receipt_ref, owner_receipt_digest +observed_at, owner_receipt_status +lineage_digest, review_trigger, next_lifecycle_proposal +``` + +This is a read-only index over an immutable receipt from the capability, +provider, delegation, Decision Context, external-evidence or outcome owner. It +must not copy provider/model/connector revisions, coverage, source families, +cost, failure details, parent disposition, decision effects or utility. Those +facts remain authoritative only in the referenced owner record. + +An owner correction, revocation or retirement creates or selects a new owner +receipt according to that owner's protocol. The portfolio observes the new +reference and marks the old observation superseded at read time; it never +rewrites the owner fact. If owner readback conflicts with the index, the owner +wins and a portfolio lifecycle transition cannot consume the stale observation. + +Each successful portfolio mutation returns a +`capability_lifecycle_transition_receipt_v1` containing only the adoption id, +operation id, expected and committed portfolio revisions, previous and next +adoption status, reason, optional composition id, owner-observation references and next +review trigger. `adopted` means the Goal's capability-adoption policy selected +the capability. It never means evidence was admitted, an outcome succeeded or +new authority was granted. + +Two examples preserve the boundary: + +- **External evidence.** The external-evidence owner alone records provider + execution observation, parent admission, coverage and retirement. If that + owner corrects or retires a receipt, the portfolio follows the superseding + owner reference and may propose `degraded`; it does not retain a competing + coverage or admission fact. +- **Non-evidence capability.** A delegation owner records worker route and + result receipts, while the relevant evaluation owner records outcome quality. + The portfolio references those receipts when reviewing adoption; it does not + translate them into generic `admitted`, `refuted` or `decision_effects` facts. + +### Command and event lifecycle + +```text +Existing Goal enablement read back → capability-owned applicability check + ├─ independent work → native hook/direct route + └─ material dependency/tradeoff → bounded plan → existing execution owners +Both routes → owner result/readback + → only if cross-Turn policy is needed: adoption/lifecycle transition +``` + +Discovery/trial is for a missing method or uncertain selection, not a mandatory +entry gate for already enabled work. Composed delegation freezes its route at +`before_delegate` and observes owner receipts at `after_delegate_result`; +non-delegated work keeps its native execution and result boundary. + +The mutation identity is `(goal_id, adoption_id, expected_revision, +operation_id)`. Replay with the same intent returns the original receipt; +identity drift fails closed. Provider/config revision drift invalidates the +plan. Lost responses reconcile through receipt readback before retry. + +If a portfolio cannot be read, planning continues without portfolio guidance +and reports Portfolio availability as unknown; it does not invent an evidence +coverage fact. If a Todo explicitly requires the missing capability, normal capability admission blocks that Todo; the portfolio does +not weaken it. + +### Connector qualification profile + +Connector qualification belongs to `external-evidence-research`, consuming its +existing plan/receipt/admission/retirement references. The following is a proposed +connector-owner profile, not the evidence-retirement state machine shipped by +#4813 and not Portfolio adoption vocabulary: + +```text +external-research discovery + → connector candidate + → bounded trial + → parent qualification + → active + → degraded | retired +``` + +A connector descriptor adds source family, supported operations, coverage +domain, publication/observation-time semantics, rights, cost, failure and +fallback declarations. A call receipt binds the exact plan/provider revision, +source references, coverage interval, freshness, rights snapshot, cost, +latency, failure and output digest. Registration and readiness remain +inventory facts. Parent qualification remains distinct from finance evidence +eligibility or another domain's admission. + +Portfolio `adopted` describes selection policy only. Connector `active`, if +supported by that qualification owner, is a separately labeled owner-joined fact. +For example, `adoption_status=adopted` and `connector_qualification.status=active` +can coexist with different owner refs; neither maps to the other. An adopted +entry can reference a degraded connector, and an active connector need not have +any Portfolio adoption. Until the connector owner supplies that typed fact, +qualification is unknown; registry readiness or evidence admission cannot mint it. +Installation, +enablement, doctor status, provider revision and rollback continue to come from +the extension runtime and existing Goal binding. Disable, uninstall, doctor +failure or binding revision drift makes the composition stale; the portfolio +must not silently resolve a replacement provider. + +### Runtime injection + +- **`before_plan`:** read enabled applicable capabilities; emit no Portfolio + contribution for independent direct work. For composed work, project only the + current gap, selected dependencies and stale/unavailable nodes. +- **`before_delegate`:** freeze worker/connector/provider revisions, budget, + schemas, authority references and composition digest. Domain capabilities + describe the question and acceptance criteria; the generic delegation owner + controls capacity, route and result receipts. +- **`after_delegate_result`:** index typed owner-receipt references and propose + a portfolio lifecycle review. Cost, coverage, failure, admission, decision + effect and utility remain in their owning receipts. Raw worker prose is not + an adoption or lifecycle receipt. + +These phases apply when their corresponding lifecycle event exists. They do +not force delegation or a governed Turn for a bound read-only call. Existing +turn-start/post-writeback hooks and pending-intent execution retain their owners; +Portfolio neither duplicates dispatch nor journals an effect twice. + +An optional Turn-start summary contains only a relevant composition reference, +stale/unavailable dependencies and next review trigger. Direct work adds no +Portfolio prompt section. Full catalog/history and owner joins stay behind +on-demand inspect. Cache bounded declarations by their existing revision; +configuration/provider/receipt drift invalidates only affected entries. + +## 6. Alternatives and design choices + +### Domain skills organize capabilities + +This is useful for early experiments but loses adoption history across Agents, +duplicates runtime discovery and makes each domain implement failure and +authority rules. Domain capabilities will keep domain semantics and acceptance +criteria, while the portfolio owns generic organization. + +### Connector registry becomes the quality authority + +Rejected. A registry is inventory and telemetry. Source quality and parent +admission require exact call evidence, time, coverage, rights and domain rules. + +### Decision Context owns capability planning + +Rejected. Decision Context assembles decision evidence; it must not become a +configuration, provider or authorization owner. + +### Mandatory portfolio adoption and a universal planner + +Rejected. Existing enablement already answers whether a capability participates. +Requiring another switch, trial, adoption record or graph for independent work +creates a second gate and unnecessary tokens, writes and failure dependencies. +The direct path remains primary; composition is a demand-driven capability +policy, not a Kernel prerequisite for every Goal or Turn. + +### Fully automatic self-installation + +Rejected for v0. It collapses recommendation, configuration and authority. The +portfolio may propose installation or enablement through existing governed +owners, but cannot perform it implicitly. + +## 7. Safety, privacy, and compatibility + +- Automatic activation is an integration obligation; composition ranking is + advice. Existing admission, required validation and authority remain enforced. + Portfolio stores no secrets or raw private payloads. +- Public projections redact private source, account and paid-data details. They + may join authorized, bounded coverage or failure fields from owner + projections at read time, but the portfolio does not persist another copy. +- A readiness observation cannot become a durable grant. Existing authority + scope and protected-effect confirmation remain authoritative. +- Mixed-version readers preserve unknown fields and reject unsupported semantic + narrowing. Revision mismatch is visible and blocks reuse. +- A connector with expired rights, stale revision or ambiguous execution moves + to unknown/degraded; it is never silently active. +- Source-family deduplication prevents multiple wrappers or workers from being + counted as independent evidence. +- A feature-off installation retains the existing planning, delegation and + evidence paths. + +## 8. Migration and rollback + +M0 first qualifies automatic direct participation and read-only inspection over +existing owners. Unconfigured/disabled capabilities retain their defaults; +enabled capabilities need no new Portfolio opt-in or bulk adoption migration. +Adding this integration must preserve each owner's explicit automation settings. +A connector becomes qualified only through its own exact-revision evidence. + +Rollout proceeds Goal by Goal using existing capability configuration controls. +Before any durable Portfolio mutation, preflight verifies its typed owner, +authority provider and references. M0 ships without a new storage dependency; +M2 adds state only for irreducible policy. Rollback removes Portfolio planning +and writes while retaining receipts for read-only audit and preserving enabled +native routes. To stop a capability itself, disable it through its original +configuration/binding owner. No destructive registry migration is part of v0. + +## 9. Validation and acceptance + +| Claim | Test or evidence | Required result | Boundary / exclusions | +| --- | --- | --- | --- | +| Enabled means usable automatically | enable through existing Goal editor/CLI, then a fresh supported Agent session without Portfolio command or adoption | applicable native hook/route runs and returns owner readback; no second opt-in | required authority and explicit manual-only settings remain enforced | +| Small work stays small | zero, one, two independent capabilities, then one real dependency | direct cases add zero Portfolio model/provider calls, DAGs or durable writes; dependency produces only needed plan | ordinary owner execution cost remains visible | +| Off/failure parity | compare same base/head workload on CLI, managed Turn, context and post-writeback paths; inject Portfolio failure | unchanged native decisions/effects; no duplicated dispatch or new gate | an actual required-capability failure still blocks through its owner | +| State vocabularies keep their owners | adoption `adopted` + connector `active`, then connector degradation and no-adoption cases | separately labeled refs/statuses; no automatic mapping or fabricated adoption | connector qualification profile is not yet shipped | +| Core stays generic | caller/import audit plus unrelated capability execution | policy is capability-owned; no Portfolio branches in Todo/quota/scheduler rules | existing generic admission still applies | +| Portfolio does not grant authority | mutation and adversarial fixtures | requested scope expansion rejected; no grant written | does not qualify each external provider | +| Plan binds exact semantics | mutate gap, config, provider, route, budget and graph fields | digest mismatch fails closed | does not prove live execution | +| Replay is idempotent | lost-response and concurrent retry fixtures | one transition and one receipt | provider side effects remain provider-owned | +| Failure preserves useful work | portfolio/provider unavailable fixture | native route continues with Portfolio availability unknown; hard requirement blocks only that Todo | no availability SLO | +| Connector lifecycle is auditable | discovery→trial→qualification→degrade→retire fixture | every transition has exact revision and typed reason | domain eligibility tested separately | +| Provider binding keeps one owner | existing Goal binding preview/apply/readback plus disable/upgrade/rollback fixtures | portfolio references the exact binding and becomes stale on drift; it writes no parallel binding | extension runtime still proves provider readiness | +| Self-discovery is useful | fresh finance and non-finance Agents receive the same Goal only | both select a minimal defensible composition or explain empty selection | two cases do not prove universal uplift | +| Composition improves outcomes | frozen baseline versus portfolio-assisted trials | better first useful action, coverage or decision quality within declared cost; failures retained | no automatic production promotion | +| Three hooks agree | before-plan/delegate/result contract tests | same composition identity and exact route/result lineage | raw model quality excluded | +| Owner truth is not duplicated | correct and retire one external-evidence receipt and one non-evidence outcome receipt | portfolio follows immutable superseding refs; no copied admission/effect fact survives | each owner still validates its own semantics | +| Product surfaces agree | existing Goal settings preview/apply/readback in CLI, packaged frontend and Lark; new-session, stale, reconnect and repeated-action cases | same effective enablement, direct/composed mode, optional adoption status and owner refs; no second activation control | release each enabled entry point only with its usable readback; owner facts retain provenance | +| Domain boundaries hold | finance and another domain fixtures | Core remains domain-neutral; domain admission remains independent | no trading authorization | + +Measure time to first useful action, evidence coverage, stale/duplicate-source +errors, manual intervention, token/monetary cost, decision changes and accepted +outcomes. Number of installed capabilities, calls or generated words is not a +success metric. + +## 10. Operational contract + +Operators can inspect effective enablement, direct/composed mode, optional +portfolio revision, adopted/trial/degraded +adoptions, exact config/provider revisions, owner-receipt references and next +review triggers. Authorized views may join current failures, cost and coverage +from their owners without persisting them in the portfolio. Alerts are +event-driven for revision drift, rights expiry, repeated failure, budget +exhaustion or a required capability becoming unavailable; routine successful +calls do not create noise. + +Reuse the existing capability configuration editor and Goal settings entry. +Show effective behavior and actionable failures first; composition details and +owner receipts are on demand. Do not add an empty Portfolio panel, an adoption +wizard or a second enable button. Lark uses the same configuration/read model. + +Capacity is bounded per Goal and relevant event. Candidate enumeration is +paginated on demand and prompt projection is size-limited. Measure same-workload +base/head latency, tokens, reads, writes and calls for off/direct/composed paths. +Off/direct add no Portfolio model or provider calls, durable writes or prompt +section. Any local projection overhead must fit an explicitly measured budget; +M0 records that budget using the repository budget-decision guide. No universal +SLO or performance win is claimed by this proposal. Failure classes distinguish +unavailable, incompatible, unauthorized, stale, rights-expired, budget-exhausted, +provider-failed and result-unqualified. Backup and recovery follow the selected +Goal authority provider; raw provider artifacts follow their original owners. + +## 11. Normative delivery plan + +| Milestone | Shipped behavior | Entry gate | Exit evidence | Rollback | +| --- | --- | --- | --- | --- | +| M0 · Automatic direct path and inspect | Resolve existing enablement, dispatch supported native hooks and expose shared readback; no new Portfolio store | existing config, hooks, admission and UI owners identified | zero/one/independent-capability cases; no second opt-in; off/failure parity and measured overhead; affected CLI/frontend/Lark journeys | remove integration; existing capability routes/config remain | +| M1 · External evidence and connector trial | Reuse merged #4813 evidence lifecycle; add only missing connector-owner qualification | real connector caller and exact-plan/provider boundary | one real host method and one connector trial with partial/failure receipts; no fabricated connector status | retain inventory/evidence; disable qualification writes | +| M2 · Optional durable adoption | candidate/trial/adopted/degraded/retired reducer and receipts only for irreducible cross-Turn policy | concrete caller needs policy beyond existing config/owner receipts; Goal authority provider selected | replay, concurrency, drift, recovery and no-adoption direct path | disable writer; retain read-only receipts | +| M3 · Demand-driven composition | Small dependency closure through existing planning/delegation/result hooks | M0; M2 only when durable policy needed; M1 only for connector qualification | direct→composed→direct, no-hint finance/non-finance trials, owner correction and same-workload overhead | remove planning; native hooks continue | +| M4 · Effect qualification | external-only, connector-only and hybrid trials; owner-backed review and retirement proposals | frozen metrics, budget and stop rules | retained denominators show benefit or explicit no-uplift without copied effect truth | revert Portfolio selection through its typed owner | +| M5 · Cross-surface consolidation | Common inspect/detail/recovery across CLI, packaged frontend and Lark | shared projection and preceding verticals available | cross-session, stale, reconnect and repeated-action acceptance for the combined journey | hide optional detail/mutation controls; native readback remains | + +M0 is a useful outcome on its own and does not wait for connector qualification, +a new authority store or the complete M2–M5 design. Each milestone includes the +entry points it changes; M5 cannot defer a required M0/M2/M3 settings companion. +#4813 is merged evidence infrastructure, not proof of the Portfolio or live +connector qualification. The overall-roadmap owner tracks S8 ordering; canonical +Todos track implementation. This PR delivers only the revised RFC contract. + +## 12. Open decisions + +1. **Portfolio storage profile.** Owner: shared-authority and capability + maintainers. Recommendation: use the configured Goal authority provider for + adoption records, reuse existing Goal external-capability bindings for + runtime enablement, and keep large receipts/artifacts with their owners. Do + not create a portfolio-specific provider binding. Decide only when M2 has a + concrete durable-policy caller; M0/direct use needs no new storage. +2. **Cross-capability comparison.** Owner: capability maintainers. + Recommendation: compare only within a named Goal gap and report multiple + dimensions; do not create one global score. Validate in M3/M4. +3. **Automatic degradation threshold.** Owner: capability plus domain owner. + Recommendation: automatic proposal, explicit typed policy to apply; never + infer retirement from low call count alone. Decide before M4. +4. **Installation proposal UX.** Owner: product and extension maintainers. + Recommendation: show governed repair/install proposals only after M3 proves + selection value. It is outside v0 execution authority. + +--- + +## Appendix A: Execution ledger (non-normative) + +### 2026-09-21 — research and contract synthesis + +- **Baseline:** `0ef7ebd749ec97a698a8fc7f2a29844dd368689b`; PR #4813 inspected at + `491c0bf3ccd4804091d7611bd85d73f5f466fdd9`. +- **Delivered:** RFC contract only. +- **Evidence:** repository audit of catalog, connector registry, capability + admission/memory, Agent-context hooks, Decision Context, Explore, reward + memory and external-evidence proposal; one finance connector inventory/use + dogfood informed the lifecycle but is not public qualification evidence. +- **Known gaps:** no canonical portfolio reducer, frontend/Lark projection or + two-domain effect trial. +- **Effect on normative design:** initial proposal. + +## Appendix B: Decision log + +| Date | Decision | Owner / approval | Alternatives | Normative sections changed | +| --- | --- | --- | --- | --- | +| 2026-09-21 | Initial proposal; no approval inferred | pending maintainer review | domain-only organization, registry-as-quality-owner, Decision Context owner | all | +| 2026-09-21 | Narrow generic use/effect state to owner-receipt observations and portfolio-only lifecycle receipts | maintainer review request on exact head `1a6b15c6` | duplicate generic effect/admission authority | Sections 1, 3, 5, 7, 9–11 | +| 2026-09-21 | Existing Goal enablement activates supported behavior; direct-first, composition on demand; adoption and connector qualification retain separate vocabularies | revised proposal pending exact-head review | second opt-in, mandatory DAG/adoption, Kernel-owned selection | Sections 1–12 | + +## Appendix C: Evidence registry + +| Evidence id | Claim | Baseline / environment | Artifact or command | Result | Privacy / validity boundary | +| --- | --- | --- | --- | --- | --- | +| E1 | Three generic hook phases exist | implementation baseline | `agent_context` and subagent-context tests/source | inspected | static inspection, not live uplift | +| E2 | Registry is inventory/telemetry rather than qualification | implementation baseline | connector-registry schema and CLI | inspected | no exhaustive provider audit | +| E3 | External-evidence typed lifecycle is a merged prerequisite | current implementation baseline | `external_research/README.md`, typed external-evidence owner and CLI | merged via #4813; source inspected | not connector qualification or live-provider evidence | +| E4 | Durable Goal binding already owns exact provider operation/revision/profile selection | implementation baseline | extension reference and capability-admission source | inspected | read-only binding contract; does not prove provider execution | +| E5 | Automatic participation and settings should reuse existing owners | current implementation baseline | `agent_context.ts`, `capability_hooks.ts`, periodic-report/reward-memory hooks, configuration editor and Goal settings | source inspected | general Portfolio activation and measured overhead remain unimplemented | + +## Appendix D: Rejected or superseded alternatives + +The alternatives in Section 6 remain rejected until evidence shows they can +preserve the invariants with less state and equal product clarity. + +## Appendix E: Incident and review lessons + +- A capability being installed or a worker route being projected did not prove + that a real call could execute. Exact authority/readiness readback belongs in + each composition plan. +- Successful persistence or exact memory readback did not prove that an + experience changed future behavior. Use and effect qualification remain + separate. +- A portfolio that copies coverage, admission or decision effects would create + a second truth that can outlive an owner correction. Portfolio state therefore + records only its own adoption lifecycle and immutable references to owner + receipts. diff --git a/docs/architecture/rfcs/goal-scoped-capability-portfolio-v0.zh-CN.md b/docs/architecture/rfcs/goal-scoped-capability-portfolio-v0.zh-CN.md new file mode 100644 index 000000000..c28c35ac0 --- /dev/null +++ b/docs/architecture/rfcs/goal-scoped-capability-portfolio-v0.zh-CN.md @@ -0,0 +1,551 @@ +# RFC:Goal 级能力组合与 Connector 生命周期(v0) + +- **RFC 状态:** Draft +- **交付成熟度:** Proposal;现有目录、hook 与外部证据切片只是部分前置 +- **作者 / Owner:** LoopX capability 与 control-plane 维护者 +- **创建时间:** 2026-09-21 +- **最近一次规范修订:** 2026-09-21 +- **实现基线:** `65afc4872db67d36f74625a9e53ae63da2bc619c` +- **相关契约:** [总路线图](loopx-overall-roadmap-v0.zh-CN.md)、 + [研究探索](research-exploration-control-plane-v0.zh-CN.md)、 + [Agent Loop Effect](agent-loop-effect-interpreter-v0.zh-CN.md)、 + [结果后 Memory 效果归因](post-outcome-memory-utility-attribution-v0.zh-CN.md)、 + [Extension 参考](../../reference/extensions.md)以及 + [外部证据生命周期 PR #4813](https://github.com/loopx-project/loopx/pull/4813) +- **语言镜像:** [English](goal-scoped-capability-portfolio-v0.md) + +## 文档结构与维护约定 + +第 1–10 节是长期设计和验收契约,第 11 节是规范性交付计划,第 12 +节是未决问题。附录只记录非规范性证据和历史。RFC 成熟度与交付成熟度 +相互独立。中英文是语义镜像,规范内容必须同步修改。 + +--- + +## 1. 决策摘要 + +LoopX 将新增 **Goal 级 Capability Portfolio**,让 Agent 围绕 Goal 的结果 +和验收缺口,判断、选择、组合、评估、降级和退役能力。Portfolio 拥有采用、 +组合与生命周期迁移决策;它只索引既有 owner 的不可变回执,不拥有或重述 +这些回执的效果。它不会把能力配置、provider 状态、证据、Todo、授权或 +memory 再复制成一份真相。 + +Portfolio 组合现有 owner: + +1. capability catalog 描述可考虑的能力; +2. 现有 Goal configuration 与 external-capability binding 选择 exact operation、 + provider revision 和 profile digest; +3. `agent_context` 在 `before_plan` 投影有界规划,在 `before_delegate` + 冻结选中路线,在 `after_delegate_result` 返回 typed 结果; +4. external-evidence 生命周期负责稳定研究方法和 connector 的资格认定; +5. Decision Context、Explore 与 reward memory 仍是有自己准入规则的下游。 + +**Goal 开启能力,就足以激活该能力支持的行为。** 既有配置 owner 将能力解析为 +对该 Goal 当前 Agent/surface scope enabled 后,适用的 hook 和正常执行路径自动参与, +不再要求第二个 +Portfolio 开关、手动 adoption 或每轮提示。激活仍遵守该能力自身的触发条件、 +预算和权限契约,不表示每个 Turn 都调用全部已启用能力。 + +按实际需求使用最少机制:没有启用能力时不增加 Portfolio 工作;一个能力或多个 +独立能力走原有直接路径;出现真实依赖或选择取舍时才生成有界组合。只有既有配置 +无法表达的显式跨 Turn 采用/生命周期决策,才需要持久化 Portfolio 状态。 + +组合建议 fail-open,既有能力义务仍须执行。Portfolio 不可用不能抑制已启用的 +直接路径,也不能绕过 Todo admission。自发现不能安装软件、启用 provider、 +扩大 scope、修改模型授权或批准 protected effect。 + +本 RFC 不批准自动安装能力、connector 市场、Core 内的垂域排序或金融 +执行权限。 + +## 2. 问题与动机 + +LoopX 已有 catalog、extension、readiness、Goal/Todo capability 要求、三个 +Agent-context hook、external-evidence 规划、Explore、Decision Context 和 +reward memory。但一个新 Agent 仍需自行猜测这些部件如何组合。当前缺失 +的组织逻辑常由垂域 prompt 或本地策略文档补齐,导致采用理由不能跨 +session 保留,换一个 Agent 又会重复探索、选择重复来源,或把 provider +ready 错当成证据质量。 + +Connector 存在同一问题。现有 registry 是有价值的库存和使用遥测;注册、 +ready 和调用次数不能证明来源覆盖、时效、rights、真实执行、父 Agent +准入或决策价值。稳定来源应经过发现和有界 trial 才晋升,并在失效、 +过期、成本过高或长期无效时降级或退役。 + +具体例子:一个投研 Goal 需要最新一手证据、独立反证和 read-heavy worker。 +Agent 应能发现已有 external-research 方法、一个 qualified source connector +和一条可用 worker route;解释各自的选择理由;冻结 revision 和预算;记录 +部分覆盖与失败;最后说明结果是否改变决策。目前这些事实分散在多个 +projection 与说明文字里。 + +### 不变量 + +- Portfolio 采用永远不能新增或扩大授权。 +- 配置仍归原 owner;Portfolio 只保存精确引用、digest 与有界 readback。 +- `ready`、`executed`、`read`、`admitted`、`decision-changing`、 + `domain-eligible` 必须彼此区分。 +- 同一来源被多个 connector 或 worker 读取,不能算独立证据。 +- unknown、stale、partial、unavailable 必须显式;空结果不是完整覆盖。 +- 模型回复、tool call、commit 或 connector 调用本身不是效果证据。 +- replay 幂等;revision 漂移不能静默复用旧计划。 +- CLI、managed Turn、前端和 Lark 读取同一份公开投影。 +- enablement、adoption policy 与 owner qualification 是分别拥有的 typed fact。 +- 使用已启用能力不要求存在 Portfolio record。 +- 功能关闭和 Portfolio 失败时,保留既有能力路径及其义务,包括显式 automation 设置。 + +## 3. 范围与非目标 + +### 范围内 + +- provider-neutral 的 capability descriptor 引用与 Goal adoption record; +- 优先直接激活,仅在需要时生成有界组合 DAG; +- trial、adoption、degradation、retirement 决策,以及 owner 回执的类型化引用; +- 建立在 external-evidence 生命周期之上的 connector qualification profile; +- 通过 `before_plan`、`before_delegate`、`after_delegate_result` 注入; +- exact effective-config 与 provider revision readback; +- CLI/前端/Lark 共享查看与反馈; +- 以 finance 和一个非金融旅程做资格验证。 + +### 非目标 + +- 替代 Goal、Todo、quota、claim、lease 或 shared-authority 状态; +- 复制 provider 凭据、原始来源正文或私有配置; +- 将 Decision Context、Explore 或 reward-memory 状态搬进 Portfolio; +- 发明跨不同能力的统一总分; +- 自动安装、授权、支付、发布、签名或交易; +- 把 Portfolio 推荐当成 runtime 或垂域授权; +- 要求每个 Turn 全量扫描全部已安装能力。 + +## 4. 当前系统契约 + +在实现基线上: + +- capability catalog 与 extension manifest 描述 installed/enabled 实现、 + provider、hook、权限与 readiness; +- `goal.external_capability_bindings` 已拥有持久的 Goal 级 enablement,绑定 exact + operation、provider revision 和 profile digest;直接 binding invocation 只准入 + read-only operation,不创建 Turn、不消耗 quota,governed effect 继续走原执行路径; +- capability admission 与 capability memory 提供有界 Goal/provider 和宿主 + 观察,但不授予权限; +- Todo capability gate 判断已知任务能否执行,不会从 Goal 缺口发现能力; +- `agent_context` 已支持三个 guidance-only、有界 phase; +- connector registry 保存库存和简单使用遥测,不负责来源资格; +- 已合并的 #4813 交付 `external-evidence` discovery、plan、receipt observation、 + parent admission 与 evidence retirement,provider execution 仍在 Core 外; + 它没有交付持久的 connector qualification 状态机; +- Decision Context 拥有决策证据,Explore 拥有研究拓扑,reward memory + 拥有经过资格审查的可复用结果经验。 + +既有 configuration editor 和 Goal capability settings 已共用 preview/apply/readback。 +Periodic-report post-writeback hook 在组合入口解析 Goal subscription;reward-memory +hook 保留 owner 定义的 surface/automation 设置。这些是复用边界,不证明所有能力已在 +所有 host 接通。通用自动参与、Portfolio 状态和跨入口读回仍是本 RFC 的提案。 + +## 5. 建议架构 + +### Owner 与权限 + +**放置决策:** 建议 capability id 为 `goal-capability-portfolio`,provider id 为 +`builtin`(设计标记,本 PR 不新增注册)。独立用户结果是跨 Agent 查看和保留 Goal 的 +能力选择。轻量 read model 归 built-in capability policy,读取既有 Goal 配置不应要求 +安装垂域包。Catalog、configuration、Decision Context、extension lifecycle 继续满足 +各自契约,但都不拥有跨能力选择历史。 + +选择、需求判断与生命周期策略归该 capability;typed normalization、identity 与迁移 +留在它的 TypeScript owning boundary,Python 只适配传输。通用 Kernel 复用注册、 +有界 dispatch、schema 校验、失败隔离和既有 effect/Todo admission;不理解能力名称、 +connector 阶段、垂域排序或 Portfolio adoption 状态。注册发生在 composition root, +共享 quota/scheduler/Todo reducer 不导入 Portfolio policy。Provider 执行和独立版本的 +垂域集成继续归原 capability/extension/package;不新增 worker、scheduler、workflow +DSL、binding store 或通用 effect ledger。 + +Portfolio 只拥有: + +- Goal 为什么考虑、trial、采用、降级或退役某项能力; +- 选中的组合和 exact revision; +- Portfolio 生命周期迁移回执与复评触发条件。 + +既有 Goal configuration 与 external-capability binding 仍是 runtime enablement 的 +唯一 owner,其 preview/apply/readback 无需 adoption record 就激活支持的行为; +Portfolio 不得否决该直接路径。反过来,adoption record 不启用或执行 capability: +`adopted` 所需 binding 缺失或 stale 时可展示但不可运行。Degrade/retire 只改变 +Portfolio 选择策略,停用能力仍须通过原配置 owner。 + +它仅引用而不复制:catalog/extension 声明、生效配置、provider readiness、 +Todo 要求、授权决策、external-evidence receipt,以及 Decision Context、 +Explore、memory artifact id。 + +任何 chat、UI、connector、worker 或垂域 capability 都不能成为另一个 +Portfolio writer。所有变更经过一个 typed reducer 和当前 Goal authority +provider。 + +### 激活与按需执行 + +配置 owner 统一解析继承、显式关闭、Agent/surface scope 和受支持的 operation/profile +设置。Agent 级激活(如 reward memory)不能顺带启用同 Goal 的其他 Agent。Portfolio 只 +消费 exact effective result,不从 catalog presence 推断 enablement,也不重解释各 +owner 的历史默认值。既有显式 manual-only 或已关闭的 automation 设置继续有效。 +新增受支持的自动入口不需要 Portfolio opt-in;若改变既有能力默认值,必须由该 owner +在发布前披露并完成验证。 + +| 生效状态与当前工作 | 自动行为 | 额外 Portfolio 工作 | +| --- | --- | --- | +| 没有启用能力 | 保留原 Agent 路径 | 无 provider/model 调用、hook contribution 或持久写入 | +| 已启用,触发条件不适用 | 保持能力可用,不调用 | 热路径 contribution 为空,可按需 inspect 原因 | +| 已启用且适用,直接或独立工作 | 按原 admission 运行既有 hook/route | 不要求 trial、DAG、adoption receipt 或额外模型调用 | +| 已启用且存在真实依赖或取舍 | 生成最小有界计划,通过既有 owner 执行 | 只保留选中的依赖闭包和必要决策引用 | +| binding/readiness/authority/budget 缺失 | 保留 owner 的 unavailable、blocked 或 deferred 结果 | 不隐式修复、替换 provider 或授予权限 | + +Host 必须真实 dispatch 已注册且适用的 hook,不能只打印“有这个 enabled 能力”。没有 +自动 hook 的命令仍通过正常 Agent/tool 路径使用;不支持的 host integration 显示 +unsupported,不能宣称激活成功。自动执行 protected effect 仍要求既有 exact admission。 +可选排序建议不得把机器强制的能力义务改成 suggestion。 + +组合依据是 typed input/output dependency、共享受限资源、备选 provider 选择,或需要 +联合结果的明确验收缺口。能力数量、关键词匹配本身不足以触发组合。优先读取已有 +生效配置,仅为未解决缺口扩大发现范围。两个独立能力保持直接路径;一个操作若需在 +高成本 provider 间取舍,也可能需要计划。规划失败时原生 hook 继续运行。 + +### 状态模型与 schema + +以下是建议契约草图,不是五个必建的新 store。直接激活只读取既有 owner,不创建 +这些持久记录。只有不能从配置或 owner receipt 推导的显式跨 Turn policy 才落 adoption/ +lifecycle state;仅 composed 路径需要 plan。每个新增字段必须有真实 consumer。 + +#### `capability_catalog_entry_v1` + +这是现有 capability declaration 的规范化引用: + +```text +capability_id, capability_revision, owner_ref, declaration_ref, declaration_digest +effective_config_ref?, readiness_ref? +``` + +Portfolio 不编辑或持久化第二份 catalog。仅在选择需要时,从原 owner 解析 outcome、 +phase、schema、authority、privacy 与 cost 声明。 + +#### `goal_capability_adoption_v1` + +```text +goal_id, adoption_id, portfolio_revision +gap_ref, capability_id, capability_revision +status = candidate | trial | adopted | degraded | retired +reason, alternatives[], expected_effects[] +effective_config_ref, effective_config_revision, config_digest +binding_ref?, binding_digest? +trial_budget?, trial_window?, authority_refs[] +owner_observation_refs[], lifecycle_receipt_refs[] +review_after, degradation_conditions[], retirement_conditions[] +created_at, updated_at +``` + +`gap_ref` 指向结果或验收缺口,不创建第二份 Todo。状态迁移要求 expected +current revision。字段省略表示保留;可选字段按字段定义显式 clear 语义。 +执行需要 binding 时,`binding_ref` 解析现有 Goal binding,而不是 Portfolio +复制一份 provider configuration。Binding readiness/status 只在读时联结原 owner。 +已启用的直接能力可以没有 adoption record,此时 inspect 返回 `adoption_status=null`, +不能伪造 `adopted` 迁移。Read model 分开呈现 effective enablement、execution mode +(`disabled | direct | composed`)与可选 adoption status,并保留 provenance。 + +#### `capability_composition_plan_v1` + +```text +goal_id, todo_id?, turn_id?, composition_id, portfolio_revision? +gap_refs[], nodes[], edges[], selected_at, expires_at +node: capability/provider/connector/worker/reducer 引用, + phase、输入/输出 schema、exact revision、预算、 + 所需授权、所需读写范围、disposition、reason +``` + +`composition_id` 是全部规范化决策字段的 canonical digest。图必须无环。 +每个纳入考虑的候选都有 `selected`、`skipped`、`unavailable` 或 `incompatible` 及理由。 +计划是 guidance,不是执行授权。 + +#### `capability_owner_receipt_observation_v1` + +```text +observation_id, composition_id?, node_id?, phase +goal/todo/turn identity +owner_kind, owner_revision +owner_receipt_ref, owner_receipt_digest +observed_at, owner_receipt_status +lineage_digest, review_trigger, next_lifecycle_proposal +``` + +这是一份只读索引,指向 capability、provider、delegation、Decision Context、 +external-evidence 或 outcome owner 的不可变回执。它不得复制 provider/model/ +connector revision、coverage、source family、cost、失败细节、parent disposition、 +decision effect 或 utility;这些事实只以被引用 owner record 为权威。 + +owner 的纠正、撤销或退役按该 owner 的协议产生或选择新回执。Portfolio 观察 +新引用,并在读时把旧 observation 标为 superseded;它不会改写 owner 事实。 +owner readback 与索引冲突时,以 owner 为准;Portfolio 的生命周期迁移不得消费 +过期 observation。 + +每次成功的 Portfolio mutation 返回 `capability_lifecycle_transition_receipt_v1`, +只包含 adoption id、operation id、预期/已提交 Portfolio revision、迁移前后 +adoption status、reason、可选 composition id、owner-observation refs 和下次 review +trigger。`adopted` 只表示 Goal 的 capability-adoption policy 选中了该能力, +不表示证据已准入、结果成功或获得新权限。 + +以下两个例子固定 owner 边界: + +- **外部证据:** external-evidence owner 独自记录 provider execution observation、 + parent admission、coverage 与 retirement。该 owner 纠正或退役回执后,Portfolio + 跟随 superseding owner ref,并可提出 `degraded`;它不保留另一份 coverage 或 + admission 事实。 +- **非证据能力:** delegation owner 记录 worker route/result receipt,相关评估 + owner 记录 outcome quality。Portfolio 复评 adoption 时只引用这些回执,不把它们 + 翻译成通用 `admitted`、`refuted` 或 `decision_effects` 事实。 + +### 命令与事件生命周期 + +```text +读回既有 Goal enablement → capability owner 判断适用性 + ├─ 独立工作 → 原生 hook/direct route + └─ 真实依赖/取舍 → 有界 plan → 既有 execution owner +两条路径 → owner result/readback + → 仅在需要跨 Turn policy 时:adoption/lifecycle transition +``` + +Discovery/trial 用于缺失的方法或不确定的选择,不是已启用工作必经入口。组合中的 +delegation 在 `before_delegate` 冻结路线,在 `after_delegate_result` 观察 owner receipt; +无 delegation 的工作保留原生执行和结果边界。 + +变更 identity 为 `(goal_id, adoption_id, expected_revision, operation_id)`。 +同一意图 replay 返回原 receipt;identity drift fail-closed。provider/config +revision 漂移使计划失效。丢失响应时先读回 receipt,再重试。 + +Portfolio 不可读取时,规划继续并报告 Portfolio availability unknown,不构造证据 +coverage 事实。若 Todo 明确要求 +缺失能力,由已有 capability admission 只阻断该 Todo;Portfolio 不得削弱它。 + +### Connector qualification profile + +Connector qualification 归 `external-evidence-research`,消费其已有 plan/receipt/ +admission/retirement 引用。以下是拟议的 connector-owner profile,不是 #4813 已交付的 +证据 retirement 状态机,也不是 Portfolio adoption 词汇: + +```text +external-research discovery + → connector candidate + → bounded trial + → parent qualification + → active + → degraded | retired +``` + +Connector descriptor 增加 source family、支持操作、coverage domain、发布/ +观察时间语义、rights、cost、failure、fallback。call receipt 绑定 exact plan/ +provider revision、source refs、coverage interval、freshness、rights snapshot、 +cost、latency、failure 和 output digest。注册和 ready 仍只是库存事实。parent +qualification 与 finance evidence eligibility 或其他垂域准入继续分开。 + +Portfolio 的 `adopted` 只描述选择策略。若 qualification owner 支持 connector `active`, +它必须作为单独标注的 owner-joined fact 展示。例如 `adoption_status=adopted` 与 +`connector_qualification.status=active` 可同时存在,但 owner ref 不同,互不映射。 +已 adopted entry 可引用 degraded connector;active connector 也可没有 Portfolio +adoption。Connector owner 尚未提供该 typed fact 时 qualification 为 unknown,不能 +从 registry readiness 或 evidence admission 构造它。安装、enablement、doctor +status、provider revision 与 rollback 继续来自 extension runtime 和现有 Goal +binding。disable、uninstall、doctor failure 或 binding revision drift 会令 composition +stale;Portfolio 不得静默切换 provider。 + +### Runtime 注入 + +- **`before_plan`:** 读取 enabled 且适用的能力;独立直接工作不增加 Portfolio + contribution。组合工作只投影当前 gap、选中的依赖和 stale/unavailable 节点。 +- **`before_delegate`:** 冻结 worker/connector/provider revision、预算、 + schema、authority refs 和 composition digest。垂域只描述问题和验收标准; + 通用 delegation owner 控制容量、route 和 result receipt。 +- **`after_delegate_result`:** 只索引 typed owner-receipt ref,并提出 Portfolio + 生命周期复评。成本、覆盖、失败、admission、decision effect 与 utility 留在原 + owner receipt。worker 原始回答不是 adoption 或 lifecycle receipt。 + +对应生命周期事件发生时才适用这些 phase;不为 bound read-only call 强制创建 +delegation 或 governed Turn。既有 turn-start/post-writeback hook 和 pending-intent +执行保留原 owner,Portfolio 不重复 dispatch 或对一个 effect 重复记账。 + +可选 Turn-start 摘要只包含相关 composition ref、stale/unavailable 依赖和下次复评 +条件。直接工作不增加 Portfolio prompt 段落;完整 catalog/history 与 owner join 留给 +按需 inspect。有界声明按既有 revision 缓存,配置/provider/receipt drift 仅失效相关项。 + +## 6. 替代方案与选择 + +### 由垂域 skill 组织能力 + +适合早期实验,但会丢失跨 Agent 采用历史、重复 runtime discovery,并让每个 +垂域重复实现失败与授权规则。垂域保留语义和验收,Portfolio 拥有通用组织。 + +### Connector registry 成为质量 owner + +拒绝。Registry 是库存和遥测。来源质量与 parent admission 需要 exact call +证据、时间、覆盖、rights 和垂域规则。 + +### Decision Context 拥有能力规划 + +拒绝。Decision Context 组装决策证据,不能成为配置、provider 或授权 owner。 + +### 强制 Portfolio adoption 与通用 planner + +拒绝。既有 enablement 已决定能力是否参与;对独立工作再要求开关、trial、adoption +record 或 graph,会产生第二道门槛及额外 token、写入和故障依赖。直接路径保持优先, +组合是按需 capability policy,不是每个 Goal/Turn 的 Kernel 前置条件。 + +### 完全自动安装 + +v0 拒绝。它混淆推荐、配置和授权。Portfolio 可以通过现有 governed owner +提出安装/启用建议,但不能隐式执行。 + +## 7. 安全、隐私与兼容 + +- 自动激活是集成义务;组合排序是建议。既有 admission、必需验证与权限继续强制 + 执行。Portfolio 不保存 secret 或原始私有 payload。 +- 公共投影隐藏私有来源、账户和付费数据细节。它可在读时联结 owner 投影中 + 已授权的有界 coverage/failure 字段,但 Portfolio 不持久化另一份副本。 +- readiness observation 不能变成 durable grant;已有 authority 与 protected + effect confirmation 继续有效。 +- 混合版本 reader 保留 unknown field,拒绝不支持的语义收窄;revision + mismatch 显式并阻断复用。 +- connector rights 过期、revision stale 或执行歧义时进入 unknown/degraded, + 不能静默 active。 +- source-family 去重避免多个 wrapper/worker 被算成独立证据。 +- 功能关闭时保留现有 planning、delegation、evidence 路径。 + +## 8. 迁移与回滚 + +M0 先验证自动直接参与和既有 owner 的只读 inspect。未配置/已关闭能力保留原默认值; +已启用能力无需新的 Portfolio opt-in 或批量 adoption 迁移。新增集成必须保留各 owner +显式 automation 设置;connector 只有通过自身 exact-revision 证据才能取得资格。 + +按 Goal 使用既有 capability configuration 推进 rollout。任何持久 Portfolio 变更前, +preflight 校验 typed owner、authority provider 与引用。M0 不依赖新 storage;M2 只为 +不可推导的 policy 增加状态。回滚移除 Portfolio planning/write,保留只读审计回执和 +已启用的原生路径;若要停止能力本身,通过原 configuration/binding owner disable。 +v0 不做破坏性 registry migration。 + +## 9. 验证与验收 + +| 声明 | 测试或证据 | 必须结果 | 边界 / 排除项 | +| --- | --- | --- | --- | +| 开启即自动可用 | 通过既有 Goal editor/CLI enable,随后新建受支持的 Agent session,不执行 Portfolio 命令或 adoption | 适用原生 hook/route 运行并完成 owner readback,无第二次 opt-in | 保留所需权限和显式 manual-only 设置 | +| 简单需求保持轻量 | 零个、一个、两个独立能力,再加入一个真实依赖 | 直接场景不增加 Portfolio 模型/provider 调用、DAG 或持久写入;依赖场景仅生成必要计划 | 原 owner 执行成本仍须可见 | +| 关闭/失败保持 parity | CLI、managed Turn、context、post-writeback 路径同工作负载比较 base/head,注入 Portfolio failure | 原生决策/effect 不变,不重复 dispatch 或加门槛 | 真正 required-capability failure 仍由 owner 阻断 | +| 状态词各有 owner | adoption `adopted` + connector `active`,再做 connector degradation 和无 adoption 场景 | 分别标注 refs/status,不自动映射、不伪造 adoption | connector qualification profile 尚未交付 | +| Core 保持通用 | caller/import 审计加无关能力执行 | policy 归 capability,Todo/quota/scheduler rule 无 Portfolio 分支 | 保留既有通用 admission | +| Portfolio 不授予权限 | mutation 与对抗 fixture | 扩权请求被拒绝,不写 grant | 不验证每个外部 provider | +| Plan 绑定 exact 语义 | 修改 gap/config/provider/route/budget/graph | digest mismatch fail-closed | 不证明 live execution | +| replay 幂等 | 丢响应与并发重试 fixture | 一次迁移、一份 receipt | provider side effect 仍归 provider | +| 失败保留有用工作 | Portfolio/provider unavailable fixture | 原生路径继续,Portfolio availability unknown;硬要求仅阻断该 Todo | 无 availability SLO | +| Connector 生命周期可审计 | discovery→trial→qualification→degrade→retire fixture | 每步 exact revision + typed reason | 垂域 eligibility 独立验证 | +| Provider binding 保持单一 owner | 现有 Goal binding preview/apply/readback 加 disable/upgrade/rollback fixture | Portfolio 引用 exact binding,drift 后变 stale,不写平行 binding | extension runtime 继续证明 provider readiness | +| 自发现有用 | 新 finance 与非金融 Agent 只收到同一 Goal | 选出最小合理组合或解释空选择 | 两例不证明普遍 uplift | +| 组合改善结果 | 冻结 baseline 对比 Portfolio-assisted trial | 在申明成本内改善首次有效行动、覆盖或决策质量,保留失败 | 不自动生产晋升 | +| 三个 hook 一致 | before-plan/delegate/result 契约测试 | 同一 composition identity 和 route/result lineage | 排除原始模型质量 | +| Owner truth 不重复 | 分别纠正并退役一个 external-evidence receipt 与一个非证据 outcome receipt | Portfolio 跟随不可变 superseding refs,不残留复制的 admission/effect 事实 | 各 owner 继续验证自己的语义 | +| 产品入口一致 | CLI、打包前端、Lark 的既有 Goal settings preview/apply/readback;新 session、stale、重连和重复操作 | 同 effective enablement、direct/composed mode、可选 adoption status 和 owner refs,无第二个激活控件 | 每个已开放入口发布时就有可用读回;owner fact 保留 provenance | +| 垂域边界成立 | finance 与另一垂域 fixture | Core 不理解垂域,domain admission 独立 | 不授予交易权限 | + +衡量首次有效行动、证据覆盖、stale/重复来源错误、人工介入、token/费用、 +决策变化和 accepted outcome。安装能力数、调用数和输出字数不是成功指标。 + +## 10. 运维契约 + +Operator 可查看 effective enablement、direct/composed mode、可选 Portfolio revision、 +adopted/trial/degraded adoption、exact config/ +provider revision、owner-receipt refs 和下次 review trigger。获授权视图可在读时 +从原 owner 联结当前 failure、cost 与 coverage,但不持久化到 Portfolio。只对 +revision drift、rights 过期、重复失败、预算耗尽或 required capability 不可用 +产生事件提醒;日常成功调用不制造噪声。 + +复用既有 capability configuration editor 与 Goal settings 入口,先显示生效行为和 +可操作的失败,按需展开组合细节和 owner receipt。不增加空 Portfolio panel、adoption +向导或第二个 enable 按钮。Lark 使用相同配置/read model。 + +每个 Goal 和相关事件的容量有界,按需候选分页,prompt projection 有大小限制。 +对 off/direct/composed 路径用同工作负载测量 base/head latency、token、read、write +和 call。Off/direct 不增加 Portfolio 模型/provider 调用、持久写入或 prompt 段落;本地 +projection 开销必须符合明确测量的预算,由 M0 按仓库 budget-decision guide 记录。 +本提案不宣称通用 SLO 或性能提升。Failure class 区分 unavailable、incompatible、unauthorized、stale、rights-expired、 +budget-exhausted、provider-failed、result-unqualified。备份恢复跟随所选 Goal +authority provider,原 provider artifact 跟随原 owner。 + +## 11. 规范性交付计划 + +| 里程碑 | 交付行为 | 入口条件 | 退出证据 | 回滚 | +| --- | --- | --- | --- | --- | +| M0 · 自动直接路径与 inspect | 解析既有 enablement,dispatch 受支持的原生 hook,共享 readback;无新 Portfolio store | 明确 config/hook/admission/UI owner | 零/单/独立能力、无第二次 opt-in、off/failure parity、测量开销和受影响 CLI/前端/Lark 旅程 | 移除集成,保留原 capability route/config | +| M1 · 外部证据与 connector trial | 复用已合入 #4813 的 evidence 生命周期,只补缺失的 connector-owner qualification | 真实 connector caller 和 exact-plan/provider boundary | 一个真实 host method + connector trial,含 partial/failure receipt,不伪造 connector status | 保留 inventory/evidence,关闭 qualification write | +| M2 · 可选持久 adoption | 仅为不可推导的跨 Turn policy 提供 candidate/trial/adopted/degraded/retired reducer 与 receipt | 真实 caller 需要超出 config/owner receipt 的 policy;选定 Goal authority provider | replay、并发、drift、recovery、无 adoption 直接路径 | 关闭 writer,保留只读回执 | +| M3 · 按需组合 | 通过现有 planning/delegation/result hook 传递最小依赖闭包 | M0;仅需持久 policy 时依赖 M2,仅需 connector qualification 时依赖 M1 | direct→composed→direct、无额外提示的 finance/非金融 trial、owner correction 和同工作负载开销 | 移除 planning,原生 hook 继续 | +| M4 · 效果资格 | external-only/connector-only/hybrid 实验、owner-backed review 与 retirement proposal | 冻结指标、预算、stop rule | 完整分母证明收益或明确 no-uplift,不复制 effect truth | 通过 typed owner 回退 Portfolio 选择 | +| M5 · 跨入口整合 | CLI、打包前端、Lark 共用 inspect/detail/recovery | shared projection 和前序纵向能力可用 | 组合旅程的跨 session、stale、重连、重复动作验收 | 隐藏可选 detail/mutation control,保留原生 readback | + +M0 本身就是有用结果,不等待 connector qualification、新 authority store 或完整 +M2–M5。各里程碑必须包含自己改变的入口;不能用 M5 推迟 M0/M2/M3 必需的设置 +配套。#4813 是已合并的 evidence 基础,不证明 Portfolio 或真实 connector qualification。 +Overall-roadmap owner 维护 S8 顺序,canonical Todo 维护执行状态。本 PR 只交付 +修订后的 RFC 契约。 + +## 12. 未决问题 + +1. **Portfolio storage profile。** Owner:shared-authority 与 capability + 维护者。建议 adoption record 使用当前 Goal authority provider,runtime + enablement 复用现有 Goal external-capability binding,大 receipt/artifact 留在 + 原 owner;不得新增 Portfolio 专属 provider binding。仅在 M2 有真实持久 policy + caller 时决定,M0/直接使用不需要新 storage。 +2. **跨能力比较。** Owner:capability 维护者。建议只在一个明确 Goal gap 内 + 多维比较,不产生全局总分。M3/M4 验证。 +3. **自动降级阈值。** Owner:capability + domain owner。建议自动提出 proposal, + 只有 typed policy 才应用;不能只因调用少而退役。M4 前决定。 +4. **安装建议 UX。** Owner:产品和 extension 维护者。建议 M3 证明选择价值后 + 才展示 governed repair/install proposal;它不属于 v0 执行权限。 + +--- + +## 附录 A:执行台账(非规范) + +### 2026-09-21 — 调研与契约整合 + +- **基线:** `0ef7ebd749ec97a698a8fc7f2a29844dd368689b`;检查 PR #4813 + `491c0bf3ccd4804091d7611bd85d73f5f466fdd9`。 +- **已交付:** 仅 RFC 契约。 +- **证据:** 对 catalog、connector registry、capability admission/memory、 + Agent-context hook、Decision Context、Explore、reward memory 和 external- + evidence proposal 的仓库审计;一次 finance connector inventory/use dogfood + 影响了生命周期设计,但不是公开 qualification evidence。 +- **已知缺口:** 无 canonical Portfolio reducer、前端/Lark projection 和双垂域 + 效果实验。 +- **对规范设计影响:** 初始提案。 + +## 附录 B:决策日志 + +| 日期 | 决策 | Owner / 批准 | 替代项 | 修改的规范章节 | +| --- | --- | --- | --- | --- | +| 2026-09-21 | 初始提案,不从实现或沉默推断批准 | 待维护者评审 | 垂域组织、registry 质量 owner、Decision Context owner | 全部 | +| 2026-09-21 | 将通用 use/effect 状态收窄为 owner-receipt observation 和 Portfolio 自有 lifecycle receipt | exact head `1a6b15c6` 的维护者 review request | 重复的通用 effect/admission authority | 第 1、3、5、7、9–11 节 | +| 2026-09-21 | Goal 既有 enablement 激活支持行为,直接路径优先、按需组合;adoption 与 connector qualification 使用独立状态词 | 修订提案,待 exact-head review | 第二次 opt-in、强制 DAG/adoption、Kernel 拥有选择策略 | 第 1–12 节 | + +## 附录 C:证据登记 + +| 证据 id | 声明 | 基线 / 环境 | artifact 或命令 | 结果 | 隐私 / 有效性边界 | +| --- | --- | --- | --- | --- | --- | +| E1 | 三个通用 hook phase 已存在 | 实现基线 | `agent_context`/subagent-context 源码与测试 | 已检查 | 静态检查,不证明 live uplift | +| E2 | Registry 是库存/遥测,不是 qualification | 实现基线 | connector-registry schema/CLI | 已检查 | 非穷尽 provider 审计 | +| E3 | external-evidence typed lifecycle 是已合并前置 | 当前实现基线 | `external_research/README.md`、typed external-evidence owner 与 CLI | #4813 已合并,已检查源码 | 不证明 connector qualification 或 live provider | +| E4 | 持久 Goal binding 已拥有 exact provider operation/revision/profile 选择 | 实现基线 | extension reference 与 capability-admission 源码 | 已检查 | 只读 binding 契约,不证明 provider 执行 | +| E5 | 自动参与和设置应复用既有 owner | 当前实现基线 | `agent_context.ts`、`capability_hooks.ts`、periodic-report/reward-memory hook、configuration editor 与 Goal settings | 已检查源码 | 通用 Portfolio 激活和开销测量尚未实现 | + +## 附录 D:拒绝或替代方案 + +第 6 节方案继续保持拒绝,除非新证据证明它们能用更少状态实现同等产品 +清晰度并保持所有不变量。 + +## 附录 E:事故与评审经验 + +- 能力 installed 或 worker route 被投影,不代表 real call 可以执行。每个 + composition plan 都要 exact authority/readiness readback。 +- 成功持久化或 memory exact readback 不代表经验改变未来行为。use 与 effect + qualification 必须分开。 +- Portfolio 若复制 coverage、admission 或 decision effect,会产生一份可能晚于 + owner 纠正仍存活的第二真相。因此 Portfolio 只记录自己的 adoption lifecycle + 和 owner receipt 的不可变引用。