完成接口
This commit is contained in:
parent
2b2ba006b3
commit
02ec00d256
|
|
@ -0,0 +1,25 @@
|
|||
# CCPE External Interface
|
||||
|
||||
This is the single external entrypoint for business systems, workbench projects, and local product repositories that need to invoke CCPE Agents, Lite prompts, Skills, Runtime nodes, or other canonical CCPE participants.
|
||||
|
||||
Consumer projects should record this file path as their default CCPE interface:
|
||||
|
||||
```text
|
||||
C:\Users\wangq\Documents\Codex\ccpe-system\Interface.md
|
||||
```
|
||||
|
||||
Before invoking any CCPE participant, read the consumer setup contract:
|
||||
|
||||
```text
|
||||
C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\ccpe-agent-consumer-setup.md
|
||||
```
|
||||
|
||||
Do not memorize or hardcode other CCPE paths as default interfaces. Read protocol, Runtime, Agent, Lite, or Skill files only when the consumer setup contract tells you to.
|
||||
|
||||
Minimum rule:
|
||||
|
||||
```text
|
||||
Interface.md
|
||||
-> ccpe-agent-consumer-setup.md
|
||||
-> only then read the required protocol / Runtime / Agent / Lite / Skill files for the current task
|
||||
```
|
||||
|
|
@ -128,6 +128,14 @@ review-committee.runtime.md
|
|||
= process that invokes several reviewers and synthesizes outputs
|
||||
```
|
||||
|
||||
For projects and business systems that call CCPE Agents or Lite prompts, record this single CCPE external interface:
|
||||
|
||||
```text
|
||||
Interface.md
|
||||
```
|
||||
|
||||
`Interface.md` routes consumers to the setup contract. The setup contract defines which additional CCPE files should be read for environment checks, invocation packets, specific Runtimes, and participant artifacts. Consumer projects should not memorize multiple CCPE paths as their default interface.
|
||||
|
||||
## 6. Runtime vs Skill
|
||||
|
||||
A Skill is a reusable capability.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,528 @@
|
|||
---
|
||||
artifact_type: ccpe-runtime-consumer-setup
|
||||
name: ccpe-agent-consumer-setup
|
||||
protocol_id: ccpe-agent-consumer-setup
|
||||
author: CCPE System
|
||||
version: 0.1.0
|
||||
created: 2026-06-20
|
||||
updated: 2026-06-20
|
||||
status: draft
|
||||
runtime_type: hybrid
|
||||
target_platform: Codex / Claude Code / OpenClaw / GPT / Gemini / Claude / local business systems
|
||||
depends_on:
|
||||
- runtimes/hybrid/agent-invocation-packet.protocol.md
|
||||
based_on: CCPE System
|
||||
---
|
||||
|
||||
# CCPE Agent Consumer Setup
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document is the single consumer entrypoint for any project or business system that needs to invoke CCPE Agents, Lite prompts, Skills, Runtime nodes, or native participants as formal participants.
|
||||
|
||||
It answers one practical question:
|
||||
|
||||
```text
|
||||
What must a consumer project create before it can safely call a CCPE Agent?
|
||||
```
|
||||
|
||||
Consumer projects should record the root interface file as their stable CCPE interface:
|
||||
|
||||
```text
|
||||
C:\Users\wangq\Documents\Codex\ccpe-system\Interface.md
|
||||
```
|
||||
|
||||
`Interface.md` routes consumer projects to this setup contract. Do not require consumer projects to memorize multiple CCPE protocol, Runtime, Agent, or Skill paths. This setup tells them which additional files to read only when the current task requires them.
|
||||
|
||||
This setup does not replace the Agent Invocation Packet Protocol, specific Runtime specs, or canonical Agent artifacts. It routes the consumer project to them at the right time. Its first job is to make the project install a small project-local contract that forces every invocation to bind an agent name to its canonical CCPE artifact before any child thread, subagent, external platform, or local Skill execution is launched.
|
||||
|
||||
## 2. Classification
|
||||
|
||||
```yaml
|
||||
primary_classification: ccpe-runtime-consumer-setup
|
||||
secondary_components:
|
||||
- cross-project invocation contract
|
||||
- project-local registry template
|
||||
- invocation preflight checklist
|
||||
- no-simulation guard
|
||||
operating_mode: hybrid
|
||||
depth_vs_automation: hybrid
|
||||
owner: ccpe-system
|
||||
consumer_owner: target project repository
|
||||
```
|
||||
|
||||
CCPE owns this setup contract because it defines a reusable cross-project invocation boundary.
|
||||
|
||||
Consumer projects own their own registry files, run directories, prompt-to-send files, returned outputs, decision logs, and project-specific runbooks.
|
||||
|
||||
## 3. Single Entry Point Rule
|
||||
|
||||
A consumer project must store exactly one default CCPE startup reference:
|
||||
|
||||
```text
|
||||
C:\Users\wangq\Documents\Codex\ccpe-system\Interface.md
|
||||
```
|
||||
|
||||
When a project starts, repairs its CCPE integration, or prepares to call a CCPE participant, it reads `Interface.md` first, then follows it to this setup file.
|
||||
|
||||
After reading this file, it must decide which narrower read set applies:
|
||||
|
||||
```text
|
||||
Environment check only:
|
||||
Read Interface.md and this setup file.
|
||||
Verify the CCPE root exists.
|
||||
Verify the project-local registry exists or can be created.
|
||||
|
||||
Prepare or validate invocation packets:
|
||||
Read Interface.md and this setup file.
|
||||
Then read runtimes/hybrid/agent-invocation-packet.protocol.md.
|
||||
|
||||
Invoke a specific participant:
|
||||
Read Interface.md and this setup file.
|
||||
Read the project-local registry.
|
||||
Resolve participant_id to canonical_artifact_path.
|
||||
Read or paste that canonical artifact.
|
||||
Read runtimes/hybrid/agent-invocation-packet.protocol.md when writing the packet.
|
||||
|
||||
Run a specific CCPE Runtime:
|
||||
Read Interface.md and this setup file.
|
||||
Read the project-local registry or workflow manifest.
|
||||
Read the named Runtime spec only if the project is actually running that workflow.
|
||||
Read runtimes/hybrid/agent-invocation-packet.protocol.md when the Runtime invokes participants.
|
||||
```
|
||||
|
||||
Do not read a specific Runtime just because the project might use CCPE. Read a Runtime only when the active workflow names it.
|
||||
|
||||
## 4. Interface Layers
|
||||
|
||||
Consumer projects should treat CCPE files as four layers:
|
||||
|
||||
```text
|
||||
Layer 0. Consumer entrypoint:
|
||||
Interface.md
|
||||
Always read first.
|
||||
|
||||
Layer 1. Consumer setup contract:
|
||||
runtimes/hybrid/ccpe-agent-consumer-setup.md
|
||||
Read after Interface.md.
|
||||
|
||||
Layer 2. Invocation evidence protocol:
|
||||
runtimes/hybrid/agent-invocation-packet.protocol.md
|
||||
Read when preparing, validating, or auditing participant invocation.
|
||||
|
||||
Layer 3. Workflow Runtime:
|
||||
runtimes/{interactive|automation|hybrid}/{runtime_id}.runtime.md
|
||||
Read only when the project is running that specific workflow.
|
||||
|
||||
Layer 4. Participant artifact:
|
||||
agents/lite/*.prompt.md
|
||||
agents/agent-specs/*.agent.md
|
||||
skills/**/*.skill.md
|
||||
Read or paste only for the participant being invoked.
|
||||
```
|
||||
|
||||
The exact canonical artifact path must come from the project-local registry, not from memory, fuzzy search, or the display name alone.
|
||||
|
||||
## 5. Consumer Project File Contract
|
||||
|
||||
Every consumer project that invokes CCPE participants should create these project-local files.
|
||||
|
||||
Recommended default for software or business repositories:
|
||||
|
||||
```text
|
||||
ccpe/
|
||||
agent-registry.yaml
|
||||
invocation-policy.md
|
||||
invocations/
|
||||
{participant_id}/
|
||||
{run_id}/
|
||||
agent-invocation-packet.md
|
||||
prompt-to-send.md # when needed
|
||||
returned-output.md # after real return
|
||||
run-metadata.json
|
||||
skill-execution-record.md # only for local_skill_execution
|
||||
```
|
||||
|
||||
Recommended default for workbench projects that already have an audit or review folder:
|
||||
|
||||
```text
|
||||
audit/
|
||||
ccpe-agent-registry.yaml
|
||||
{participant_id}/
|
||||
{run_id}/
|
||||
agent-invocation-packet.md
|
||||
prompt-to-send.md
|
||||
returned-output.md
|
||||
run-metadata.json
|
||||
skill-execution-record.md
|
||||
```
|
||||
|
||||
The path may vary by project, but the file roles must not vary.
|
||||
|
||||
## 6. Project-Local Registry Template
|
||||
|
||||
Create one registry per consumer project or per concrete workbench project.
|
||||
|
||||
```yaml
|
||||
schema: ccpe.agent.consumer.registry.v1
|
||||
project_id:
|
||||
project_root:
|
||||
ccpe_system_root: C:\Users\wangq\Documents\Codex\ccpe-system
|
||||
invocation_protocol_path: C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\agent-invocation-packet.protocol.md
|
||||
default_run_root: ccpe\invocations
|
||||
strict_invocation_required: true
|
||||
no_simulation_requirement: true
|
||||
|
||||
defaults:
|
||||
invocation_mode: prompt_path_reference
|
||||
carrier_type: codex_thread_participant
|
||||
role_integrity_requirement: must_load_canonical_artifact_before_task
|
||||
missing_canonical_behavior: blocked_missing_canonical_artifact
|
||||
task_prompt_authority: task_context_only
|
||||
output_structure_authority: canonical_artifact
|
||||
packet_only_is_execution: false
|
||||
prompt_to_send_only_is_execution: false
|
||||
|
||||
participants:
|
||||
example-participant-id:
|
||||
display_name:
|
||||
canonical_artifact_path:
|
||||
canonical_artifact_type: ccpe_lite | ccpe_agent | ccpe_skill | ccpe_runtime_node | native_agent | external_agent | human
|
||||
canonical_artifact_version:
|
||||
default_invocation_mode: prompt_path_reference
|
||||
default_carrier_type: codex_thread_participant
|
||||
role_integrity_requirement: must_load_canonical_artifact_before_task
|
||||
missing_canonical_behavior: blocked_missing_canonical_artifact
|
||||
output_structure_authority: canonical_artifact
|
||||
allowed_wrapper_instructions:
|
||||
- project_id
|
||||
- workflow
|
||||
- stage
|
||||
- run_id
|
||||
- input_files
|
||||
- context_files
|
||||
- output_path
|
||||
- output_language_policy
|
||||
forbidden_role_changes:
|
||||
- replacing the canonical role
|
||||
- replacing the canonical tone
|
||||
- replacing the canonical output structure
|
||||
- weakening the canonical evaluation method
|
||||
- treating the task prompt as the role definition
|
||||
```
|
||||
|
||||
## 7. Environment Check
|
||||
|
||||
Before creating the registry or launching participants, a consumer project may run an environment check. It should verify:
|
||||
|
||||
```text
|
||||
1. The CCPE entrypoint exists:
|
||||
C:\Users\wangq\Documents\Codex\ccpe-system\Interface.md
|
||||
|
||||
2. The CCPE consumer setup exists:
|
||||
C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\ccpe-agent-consumer-setup.md
|
||||
|
||||
3. The CCPE invocation protocol exists:
|
||||
C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\agent-invocation-packet.protocol.md
|
||||
|
||||
4. The project can create or update its project-local registry.
|
||||
|
||||
5. Every participant it plans to invoke has a registry entry.
|
||||
|
||||
6. Every referenced canonical_artifact_path exists and is readable, or the invocation mode is full_prompt_paste.
|
||||
|
||||
7. The project has a run root for invocation records.
|
||||
```
|
||||
|
||||
Environment check is not execution. It may produce or repair registry files, but it must not claim any participant has returned output.
|
||||
|
||||
## 8. Standard Participants Example
|
||||
|
||||
For article outline review projects that use the current CCPE reviewer trio, the registry entries should look like this:
|
||||
|
||||
```yaml
|
||||
participants:
|
||||
zhang-liao:
|
||||
display_name: 张辽
|
||||
canonical_artifact_path: C:\Users\wangq\Documents\Codex\ccpe-system\agents\lite\zhang-liao.prompt.md
|
||||
canonical_artifact_type: ccpe_lite
|
||||
canonical_artifact_version: current
|
||||
default_invocation_mode: prompt_path_reference
|
||||
default_carrier_type: codex_thread_participant
|
||||
role_integrity_requirement: must_load_canonical_artifact_before_task
|
||||
missing_canonical_behavior: blocked_missing_canonical_artifact
|
||||
output_structure_authority: canonical_artifact
|
||||
|
||||
giant-cognition:
|
||||
display_name: 巨人
|
||||
canonical_artifact_path: C:\Users\wangq\Documents\Codex\ccpe-system\agents\lite\giant-cognition.prompt.md
|
||||
canonical_artifact_type: ccpe_lite
|
||||
canonical_artifact_version: current
|
||||
default_invocation_mode: prompt_path_reference
|
||||
default_carrier_type: codex_thread_participant
|
||||
role_integrity_requirement: must_load_canonical_artifact_before_task
|
||||
missing_canonical_behavior: blocked_missing_canonical_artifact
|
||||
output_structure_authority: canonical_artifact
|
||||
|
||||
cognitive-imaging:
|
||||
display_name: 认知显影
|
||||
canonical_artifact_path: C:\Users\wangq\Documents\Codex\ccpe-system\agents\lite\cognitive-imaging-practitioner.prompt.md
|
||||
canonical_artifact_type: ccpe_lite
|
||||
canonical_artifact_version: current
|
||||
default_invocation_mode: prompt_path_reference
|
||||
default_carrier_type: codex_thread_participant
|
||||
role_integrity_requirement: must_load_canonical_artifact_before_task
|
||||
missing_canonical_behavior: blocked_missing_canonical_artifact
|
||||
output_structure_authority: canonical_artifact
|
||||
```
|
||||
|
||||
## 9. Invocation Preflight
|
||||
|
||||
Before launching any CCPE participant, the consumer project must complete this preflight:
|
||||
|
||||
```text
|
||||
1. Locate the project-local registry.
|
||||
2. Resolve participant_id to canonical_artifact_path.
|
||||
3. Verify the canonical artifact exists and is readable, or prepare full_prompt_paste.
|
||||
4. Create a run directory.
|
||||
5. Write agent-invocation-packet.md.
|
||||
6. Write prompt-to-send.md when the participant carrier needs a startup prompt.
|
||||
7. Separate canonical role from task context.
|
||||
8. Include output contract and return path.
|
||||
9. Launch a real participant carrier.
|
||||
10. Save returned-output.md only after the real participant returns.
|
||||
```
|
||||
|
||||
If any required canonical artifact is missing or unreadable, stop with:
|
||||
|
||||
```text
|
||||
blocked_missing_canonical_artifact
|
||||
```
|
||||
|
||||
If the participant cannot be truly invoked, stop with:
|
||||
|
||||
```text
|
||||
blocked_waiting_for_participant_output
|
||||
```
|
||||
|
||||
Do not produce a role-played report in the main session.
|
||||
|
||||
## 10. Prompt-To-Send Startup Block
|
||||
|
||||
When `invocation_mode = prompt_path_reference`, the startup prompt may reference local paths, but it must still force the participant to load the canonical artifact before reading the task prompt.
|
||||
|
||||
```md
|
||||
# Prompt To Send: {participant_id}
|
||||
|
||||
You are being invoked as a formal CCPE participant.
|
||||
|
||||
First read your canonical CCPE artifact:
|
||||
{canonical_artifact_path}
|
||||
|
||||
This canonical artifact defines your role, tone, judgment method, and output structure.
|
||||
|
||||
The task prompt and project files below are task context only. They must not replace your canonical role.
|
||||
|
||||
If the canonical artifact is unavailable or unreadable, stop and return:
|
||||
blocked_missing_canonical_artifact
|
||||
|
||||
After loading the canonical artifact, read:
|
||||
{task_prompt_path_or_embedded_task}
|
||||
|
||||
Write the formal output to:
|
||||
{returned_output_path}
|
||||
|
||||
Return metadata:
|
||||
- participant_id:
|
||||
- canonical_artifact_path:
|
||||
- invocation_mode:
|
||||
- carrier_type:
|
||||
- thread_id:
|
||||
- execution_status: returned
|
||||
- simulation_only: false
|
||||
```
|
||||
|
||||
When `invocation_mode = full_prompt_paste`, paste the full canonical artifact into the prompt-to-send before the task context.
|
||||
|
||||
## 11. Agent Invocation Packet Minimum
|
||||
|
||||
Every run must include at least:
|
||||
|
||||
```yaml
|
||||
project_id:
|
||||
workflow:
|
||||
stage:
|
||||
run_id:
|
||||
participant_id:
|
||||
display_name:
|
||||
canonical_artifact_path:
|
||||
canonical_artifact_type:
|
||||
canonical_artifact_version:
|
||||
invocation_mode:
|
||||
carrier_type:
|
||||
thread_id:
|
||||
strict_invocation_required: true
|
||||
simulation_only: false
|
||||
task_prompt_authority: task_context_only
|
||||
output_structure_authority: canonical_artifact
|
||||
path_readability_evidence:
|
||||
input_files:
|
||||
context_files:
|
||||
output_contract:
|
||||
returned_output_path:
|
||||
no_simulation_requirement: true
|
||||
runtime_acceptance_rule:
|
||||
```
|
||||
|
||||
The full field set is defined in:
|
||||
|
||||
```text
|
||||
runtimes/hybrid/agent-invocation-packet.protocol.md
|
||||
```
|
||||
|
||||
## 12. Runtime Selection Rule
|
||||
|
||||
A business system does not read all CCPE Runtimes by default.
|
||||
|
||||
It reads a specific Runtime only when one of these is true:
|
||||
|
||||
```text
|
||||
- the user explicitly asks for that workflow
|
||||
- the project-local registry names workflow_runtime_path
|
||||
- the project-local run manifest names runtime_id
|
||||
- a previous accepted project decision says this project uses that Runtime
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
```text
|
||||
Article outline development:
|
||||
Read the article outline development Runtime only when the project is actually running the article outline workflow.
|
||||
|
||||
Local CCRA review:
|
||||
Read runtimes/hybrid/ccra-local-review.runtime.md only when the project is running a Local CCRA review.
|
||||
|
||||
Viewpoint discussion distillation:
|
||||
Read runtimes/hybrid/viewpoint-discussion-distillation.runtime.md only when the project is distilling a long discussion into topic documents or related outputs.
|
||||
```
|
||||
|
||||
If no specific Runtime is named, the consumer project should use this setup file plus the invocation packet protocol only.
|
||||
|
||||
## 13. Runtime Acceptance Rule
|
||||
|
||||
A consumer project may treat a CCPE participant output as formal only when:
|
||||
|
||||
```text
|
||||
- the project-local registry binds participant_id to canonical_artifact_path
|
||||
- an agent-invocation-packet.md exists for the run
|
||||
- a real participant carrier was launched
|
||||
- the participant loaded or received the canonical artifact
|
||||
- returned-output.md exists
|
||||
- returned metadata says simulation_only: false
|
||||
- packet-only and prompt-to-send-only states are rejected as execution
|
||||
```
|
||||
|
||||
If these are not true, the output is not a formal CCPE participant result.
|
||||
|
||||
## 14. Business-System Startup Instruction
|
||||
|
||||
Use this instruction when initializing or repairing a business project that will call CCPE Agents:
|
||||
|
||||
```md
|
||||
Before invoking any CCPE Agent, read the single CCPE external interface:
|
||||
|
||||
C:\Users\wangq\Documents\Codex\ccpe-system\Interface.md
|
||||
|
||||
Then follow Interface.md to the consumer setup contract and create or repair the project-local CCPE agent registry and invocation policy.
|
||||
|
||||
Do not invoke a CCPE participant until:
|
||||
|
||||
- every participant name is bound to a canonical_artifact_path
|
||||
- the canonical artifact path is readable or pasted into prompt-to-send.md
|
||||
- agent-invocation-packet.md will be written for the run
|
||||
- returned-output.md will be saved only after a real participant returns
|
||||
- the main session will not simulate formal participant output
|
||||
|
||||
Read additional CCPE files only when Interface.md and the consumer setup contract tell you to:
|
||||
|
||||
- read agent-invocation-packet.protocol.md when preparing invocation packets
|
||||
- read a specific Runtime only when the active workflow names it
|
||||
- read a specific Agent / Lite / Skill artifact only when invoking that participant
|
||||
```
|
||||
|
||||
## 15. Failure Modes This Setup Prevents
|
||||
|
||||
```text
|
||||
Display-name invocation:
|
||||
The project says "call Zhang Liao" but never binds Zhang Liao to zhang-liao.prompt.md.
|
||||
|
||||
Task-prompt role replacement:
|
||||
The task prompt says "CCPE Zhang Liao" but does not include or reference the canonical prompt.
|
||||
|
||||
Generic review drift:
|
||||
A child thread behaves like a normal reviewer because no canonical artifact was loaded.
|
||||
|
||||
Packet-only false positive:
|
||||
The project creates prompt-to-send.md but treats it as completed execution.
|
||||
|
||||
Main-session simulation:
|
||||
The orchestrator writes what a participant would have said and records it as formal output.
|
||||
|
||||
Interface sprawl:
|
||||
A project is told to read several CCPE paths without a single stable entrypoint or routing rule.
|
||||
```
|
||||
|
||||
## 16. Validation Checklist
|
||||
|
||||
```text
|
||||
Single CCPE entrypoint recorded?
|
||||
Interface.md exists?
|
||||
Consumer setup contract exists?
|
||||
Project-local registry exists?
|
||||
Registry schema version present?
|
||||
CCPE system root present?
|
||||
Invocation protocol path present?
|
||||
Participant ID present?
|
||||
Display name present?
|
||||
Canonical artifact path present?
|
||||
Canonical artifact readable or fully pasted?
|
||||
Task prompt marked as task_context_only?
|
||||
Output structure authority set to canonical_artifact?
|
||||
Forbidden role changes listed?
|
||||
Run directory created?
|
||||
Agent invocation packet written?
|
||||
Prompt-to-send written when needed?
|
||||
Real participant carrier recorded?
|
||||
Returned output saved only after return?
|
||||
Simulation-only false for formal output?
|
||||
Packet-only rejected as execution?
|
||||
Prompt-to-send-only rejected as execution?
|
||||
```
|
||||
|
||||
## 17. Boundary
|
||||
|
||||
CCPE supplies:
|
||||
|
||||
```text
|
||||
- this consumer setup contract
|
||||
- canonical participant artifacts
|
||||
- Agent Invocation Packet Protocol
|
||||
- reusable Runtime specs
|
||||
- reusable Skill specs
|
||||
- model and evaluation assets when needed
|
||||
```
|
||||
|
||||
The consumer project supplies:
|
||||
|
||||
```text
|
||||
- project-local registry
|
||||
- project-specific invocation policy
|
||||
- run directories
|
||||
- task prompts
|
||||
- context packs
|
||||
- returned outputs
|
||||
- decision logs
|
||||
- implementation adapters
|
||||
```
|
||||
|
||||
Do not copy project run history into CCPE. Do not copy CCPE canonical prompts into project repositories unless `full_prompt_paste` is required for an external/manual participant.
|
||||
Loading…
Reference in New Issue