From 74ffd3ba18cc95e87def12b49cce55c47c3cb705 Mon Sep 17 00:00:00 2001 From: wantsong Date: Mon, 22 Jun 2026 13:45:46 +0800 Subject: [PATCH] docs: align video workbench rules with CCPE interface --- AGENTS.md | 32 +++++++++++++++++++++++ PROJECTS.md | 6 ++--- README.md | 4 ++- VIDEO_WORKBENCH.md | 29 +++++++++++++++++---- ccpe-consumption/README.md | 41 ++++++++++++++++++++++++++++++ ccpe-consumption/runtime-links.md | 42 ------------------------------- docs/ccpe-system-handoff.md | 26 +++++++++++++------ docs/context-handoff.md | 21 +++++++++++++++- requirements/ccpe/README.md | 7 ++++++ 9 files changed, 148 insertions(+), 60 deletions(-) create mode 100644 AGENTS.md create mode 100644 ccpe-consumption/README.md delete mode 100644 ccpe-consumption/runtime-links.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..fea5d86 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,32 @@ +# Video Workbench Agent Rules + +## Text Encoding + +All local project documents are UTF-8 unless a file explicitly declares another encoding. + +When reading Markdown, JSON, YAML, text, handoff, prompt, or discussion files from PowerShell, use explicit UTF-8 by default: + +```powershell +Get-Content -LiteralPath -Encoding UTF8 +Select-String -Path -Pattern -Encoding UTF8 +``` + +When writing text files, preserve UTF-8. Do not rely on PowerShell encoding defaults for Chinese Markdown. + +## CCPE Interface + +The default external CCPE entrypoint is: + +```text +C:\Users\wangq\Documents\Codex\ccpe-system\Interface.md +``` + +For CCPE setup or invocation work, read that file first, then follow it to: + +```text +C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\ccpe-agent-consumer-setup.md +``` + +Do not hardcode old Agent, Lite, Skill, Runtime, or protocol paths as default CCPE entrypoints. Read narrower CCPE artifacts only when the consumer setup contract, a project-local registry, or the active task requires them. + +Formal CCPE participant output requires a project-local registry, an invocation packet, a real participant carrier, and returned output saved only after the participant returns. Main-session roleplay is not formal CCPE output. diff --git a/PROJECTS.md b/PROJECTS.md index 058f8ef..779432f 100644 --- a/PROJECTS.md +++ b/PROJECTS.md @@ -29,7 +29,7 @@ It does not own upstream deep creation, canonical agents, reusable automation so | --- | --- | --- | --- | | `knowledge-vault` | Upstream knowledge, source archive, formal essays, human-readable model documents, and discussion memory | stable essays, model documents, selected source notes, source paths, discussion records with formed conclusions | optional pointers from video packages back to source materials | | `writing-workbench` | Sibling workspace for deep article production | completed or sufficiently stable article projects when the user chooses to make video content | no default output | -| `ccpe-system` | Supplier of local work agents, runtime rules, model cards, and governed cognitive assets | CCPE-Lite actors, agent specs, runtime rules, invocation contracts, model usage rules | capability requests under `requirements/ccpe/` | +| `ccpe-system` | Supplier of local work agents, runtime rules, model cards, and governed cognitive assets | the external `Interface.md`, the consumer setup contract, and task-specific canonical artifacts only when routed by the setup/registry | capability requests under `requirements/ccpe/` | | `skills-vault` | Supplier of deterministic automation tools | file processors, batch utilities, asset tools, export tools, installable automation skills | capability requests under `requirements/skills-vault/` | | `work-projects` | Separate software/customer project workspace | no default input | production system requirements if this video workflow is later packaged as deployable software | @@ -38,7 +38,7 @@ It does not own upstream deep creation, canonical agents, reusable automation so - Video Workbench is a sibling of Writing Workbench, not a child project. - Deep article creation belongs in `writing-workbench`. - Long-term sources, finished essays, model documents, and open-ended discussion memory belong in `knowledge-vault`. -- Canonical local-work agents, prompts, runtimes, model cards, and invocation protocols belong in `ccpe-system`. +- Canonical local-work agents, prompts, runtimes, model cards, and invocation protocols belong in `ccpe-system`; Video Workbench starts from `ccpe-system\Interface.md`, not from hardcoded internal CCPE artifact paths. - Deterministic reusable automation implementation source belongs in `skills-vault`. - If the video workflow is later packaged as a deployable system, production/business agent implementation belongs in the relevant `work-projects` repository, not in this local workbench. - Missing capabilities are requested through `requirements/`, not implemented ad hoc inside this repository. @@ -50,7 +50,7 @@ Video Workbench is a client and production room: ```text knowledge-vault provides sources and long-term knowledge. writing-workbench may provide stable article projects. -ccpe-system provides local work agents, protocols, and model assets. +ccpe-system provides local work agents, protocols, and model assets through `Interface.md`. skills-vault provides deterministic automation tools. video-workbench runs local projects under `projects/` and keeps lightweight execution records. ``` diff --git a/README.md b/README.md index f34afa3..610e076 100644 --- a/README.md +++ b/README.md @@ -51,11 +51,13 @@ Series indexes can be added later under `projects/_series/` when a real series n - Video Workbench does not default to full video editing, image-to-video generation, or platform publishing. - Missing CCPE assets should be requested under `requirements/ccpe/`. - Missing reusable automation should be requested under `requirements/skills-vault/`. +- All local Markdown, JSON, YAML, text, prompt, discussion, and handoff files are UTF-8 by default. PowerShell reads should use explicit `-Encoding UTF8`. +- The default CCPE external interface is `C:\Users\wangq\Documents\Codex\ccpe-system\Interface.md`; follow it to the consumer setup contract before reading narrower CCPE artifacts. ## Starting A New Session In a new Codex session opened on this project, use: ```md -Please read README.md, VIDEO_WORKBENCH.md, docs/context-handoff.md, and docs/ccpe-system-handoff.md first, then continue work on Video Workbench according to those conventions. +Please read AGENTS.md, README.md, VIDEO_WORKBENCH.md, docs/context-handoff.md, and docs/ccpe-system-handoff.md first, then continue work on Video Workbench according to those conventions. ``` diff --git a/VIDEO_WORKBENCH.md b/VIDEO_WORKBENCH.md index 60c6e25..3bf2501 100644 --- a/VIDEO_WORKBENCH.md +++ b/VIDEO_WORKBENCH.md @@ -119,14 +119,33 @@ Use `requirements/ccpe/` for local work agents, CCPE-Lite artifacts, agent specs Use `requirements/skills-vault/` for deterministic automation tools, scripts, exporters, batch processors, and installable automation skills. -## 10. CCPE Consumption +## 10. Text Encoding -Video Workbench consumes CCPE assets from: +All local project documents are UTF-8 unless a file explicitly declares another encoding. -```text -C:\Users\wangq\Documents\Codex\ccpe-system +When using PowerShell to read Markdown, JSON, YAML, text, handoff, prompt, or discussion files, use explicit UTF-8: + +```powershell +Get-Content -LiteralPath -Encoding UTF8 +Select-String -Path -Pattern -Encoding UTF8 ``` -Do not duplicate canonical CCPE definitions here. Use `ccpe-consumption/` for links, usage notes, planned dependencies, and future interface records. +Do not wait for mojibake or a failed first read before applying UTF-8. + +## 11. CCPE Consumption + +Video Workbench consumes CCPE through the single external interface: + +```text +C:\Users\wangq\Documents\Codex\ccpe-system\Interface.md +``` + +When preparing CCPE integration or invocation work, read `Interface.md` first and follow it to: + +```text +C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\ccpe-agent-consumer-setup.md +``` + +Do not duplicate canonical CCPE definitions here. Do not hardcode Agent, Lite, Skill, Runtime, or protocol paths as default entrypoints. Use `ccpe-consumption/` for interface notes and future project-local invocation setup records. Local work prompts and agents belong in CCPE. If this workflow is later packaged as deployable software, production/business agent implementation belongs in the target software project, not in Video Workbench. diff --git a/ccpe-consumption/README.md b/ccpe-consumption/README.md new file mode 100644 index 0000000..f30a616 --- /dev/null +++ b/ccpe-consumption/README.md @@ -0,0 +1,41 @@ +# CCPE Consumption + +This directory records how Video Workbench consumes CCPE from the outside. + +The single default CCPE interface is: + +```text +C:\Users\wangq\Documents\Codex\ccpe-system\Interface.md +``` + +Before preparing any CCPE setup or invocation, read that file first. It routes consumers to: + +```text +C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\ccpe-agent-consumer-setup.md +``` + +## Rules + +- Do not copy canonical CCPE prompts, agents, runtimes, model cards, protocols, or skills into this repository. +- Do not hardcode old Agent, Lite, Skill, Runtime, or protocol paths as default entrypoints. +- Read narrower CCPE artifacts only when `Interface.md`, the consumer setup contract, a project-local registry, or an active task requires them. +- Planned participants are not available until they have a real registry entry, readable `canonical_artifact_path`, invocation packet, real participant carrier, and returned output. + +## Future Project-Local Invocation Shape + +When a concrete Video Workbench project needs formal CCPE participant invocation, create the invocation contract inside that project, for example: + +```text +projects//ccpe/ + agent-registry.yaml + invocation-policy.md + invocations/ + / + / + agent-invocation-packet.md + prompt-to-send.md + returned-output.md + run-metadata.json +``` + +This path may be adjusted for the first real project, but the file roles must follow the CCPE consumer setup contract. diff --git a/ccpe-consumption/runtime-links.md b/ccpe-consumption/runtime-links.md deleted file mode 100644 index 140566e..0000000 --- a/ccpe-consumption/runtime-links.md +++ /dev/null @@ -1,42 +0,0 @@ -# CCPE Runtime Links - -This file records how Video Workbench consumes CCPE System assets. - -Canonical CCPE workspace: - -```text -C:\Users\wangq\Documents\Codex\ccpe-system -``` - -## Planned Assets - -| Asset | Type | Status | Notes | -| --- | --- | --- | --- | -| Qiangge's Apprentice | Lite / Agent Spec | planned | Primary dimensional output actor | -| Short Video Production Runtime | Runtime | planned | Full video package workflow | -| Source-To-Episode Splitter | Skill | planned | Split deep source into episodes | -| Angle Proposal Generator | Skill | planned | Generate three entry angles | -| Tone And Outline Builder | Skill | planned | Build video outline and global visual style | -| Storyboard Logic Builder | Skill | planned | Build timed storyboard logic | -| Shot Deep Production | Skill | planned | Build shot visual plan, prompt, voiceover, notes | -| Image Prompt Generator | Skill | planned | Produce consistent image prompts | -| Voiceover Script Generator | Skill | planned | Fit narration to duration budget | -| Publish Copy Generator | Skill | planned | Prepare platform copy | - -## Policy - -Do not copy canonical CCPE artifacts here. Record links, usage notes, and future interface records only. - -Video Workbench does not store canonical prompts, agent specs, model cards, or runtime specs. Missing CCPE capabilities should be requested through: - -```text -requirements/ccpe/ -``` - -Deterministic automation tools should be requested through: - -```text -requirements/skills-vault/ -``` - -Do not mark planned assets as executed or available until they have a real source path and validation record. diff --git a/docs/ccpe-system-handoff.md b/docs/ccpe-system-handoff.md index dd93b05..d0a375c 100644 --- a/docs/ccpe-system-handoff.md +++ b/docs/ccpe-system-handoff.md @@ -1,12 +1,26 @@ # CCPE System Handoff For Video Workbench -This document is the handoff for future work in: +This document is the handoff for future supplier work in: ```text C:\Users\wangq\Documents\Codex\ccpe-system ``` -It records the CCPE assets needed to support Video Workbench. +It records candidate CCPE assets needed to support Video Workbench. It is not the CCPE consumer interface and must not be used as a formal invocation startup path. + +The external CCPE interface is: + +```text +C:\Users\wangq\Documents\Codex\ccpe-system\Interface.md +``` + +For any CCPE setup or invocation, read `Interface.md` first, then follow it to: + +```text +C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\ccpe-agent-consumer-setup.md +``` + +Do not treat the candidate paths below as canonical invocation paths until a project-local registry resolves a participant to a real `canonical_artifact_path`. ## Core Principle @@ -22,11 +36,7 @@ Previous single-agent actor: 强哥的徒弟 ``` -Likely first target: - -```text -agents/lite/qiangge-apprentice.prompt.md -``` +Likely first supplier target: a CCPE-owned Lite artifact or Agent Spec for the dimensional-output actor. Do not record a concrete `canonical_artifact_path` here; that belongs in the project-local registry when a real invocation is prepared. Purpose: @@ -34,7 +44,7 @@ Purpose: Transform deep essays and models into public-facing short video plans, scripts, visual prompts, and production packages. ``` -This actor should remain a CCPE-owned local work asset. Video Workbench may request, consume, and validate it, but should not store its canonical prompt or agent definition. +This actor should remain a CCPE-owned local work asset. Video Workbench may request, consume, and validate it, but should not store its canonical prompt or agent definition. Formal use must go through the CCPE interface and project-local registry rules. ## Recommended CCPE Build Sequence diff --git a/docs/context-handoff.md b/docs/context-handoff.md index b0b339f..b791638 100644 --- a/docs/context-handoff.md +++ b/docs/context-handoff.md @@ -62,6 +62,17 @@ Use root `handoff/` for repo-level, cross-project, series-level, or context-wind `slides/sNN/` keeps all files for one slide, page, or shot together: prompts, narration, generated images, generated audio, and local notes. +## Text Encoding + +All local Markdown, JSON, YAML, text, prompt, discussion, and handoff files are UTF-8 unless a file explicitly declares another encoding. + +Use explicit UTF-8 when reading these files from PowerShell: + +```powershell +Get-Content -LiteralPath -Encoding UTF8 +Select-String -Path -Pattern -Encoding UTF8 +``` + ## Dimensional Output Rule The user's method: @@ -88,6 +99,14 @@ requirements/skills-vault/ CCPE supplies local work agents, runtime rules, model cards, invocation contracts, governed cognitive assets, and external capability registrations. +The single CCPE external interface is: + +```text +C:\Users\wangq\Documents\Codex\ccpe-system\Interface.md +``` + +Read that file first, then follow it to the consumer setup contract. Do not use older Agent, Lite, Skill, Runtime, or protocol paths as default startup paths. + Skills-vault supplies deterministic automation tools, scripts, batch utilities, exporters, and installable automation skills. ## New Session Instruction @@ -95,5 +114,5 @@ Skills-vault supplies deterministic automation tools, scripts, batch utilities, Use this in a new Video Workbench session: ```md -Please read README.md, VIDEO_WORKBENCH.md, docs/context-handoff.md, and docs/ccpe-system-handoff.md first, then continue work on Video Workbench according to those conventions. +Please read AGENTS.md, README.md, VIDEO_WORKBENCH.md, docs/context-handoff.md, and docs/ccpe-system-handoff.md first, then continue work on Video Workbench according to those conventions. ``` diff --git a/requirements/ccpe/README.md b/requirements/ccpe/README.md index cb8808c..0349a31 100644 --- a/requirements/ccpe/README.md +++ b/requirements/ccpe/README.md @@ -10,3 +10,10 @@ Use this directory when Video Workbench needs a local work agent, CCPE-Lite prom Do not place canonical prompts, agent specs, model cards, or runtime specs in this repository. This directory records the request from Video Workbench as the client project. +For actual CCPE setup or invocation, the default entrypoint is: + +```text +C:\Users\wangq\Documents\Codex\ccpe-system\Interface.md +``` + +Read `Interface.md` first and follow it to the consumer setup contract. Do not hardcode internal CCPE artifact paths in supplier tickets as default invocation entrypoints.