From 7a0c928a4ac85435614b27365b2cdefbd5e730b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E5=A2=A8?= Date: Tue, 2 Jun 2026 02:55:42 +0000 Subject: [PATCH] docs: update all docs to reference @ocas/core and ocas_ref MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md, docs/architecture.md, docs/wf-stateless-design.md - docs/builtin-agent-research.md - All package README.md files - cas_ref → ocas_ref, @uncaged/json-cas → @ocas/core, json-cas-fs → @ocas/fs --- README.md | 2 +- docs/architecture.md | 30 +++++------ docs/builtin-agent-research.md | 2 +- docs/wf-stateless-design.md | 50 +++++++++---------- packages/cli-workflow/README.md | 4 +- packages/workflow-agent-builtin/README.md | 2 +- packages/workflow-agent-claude-code/README.md | 2 +- packages/workflow-agent-hermes/README.md | 2 +- packages/workflow-protocol/README.md | 4 +- packages/workflow-util-agent/README.md | 2 +- 10 files changed, 50 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 27d11fe..ef2f8d3 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ App (uses protocol; not in the runtime engine stack) workflow-dashboard Web UI for visual workflow editing ``` -External CAS: [`@uncaged/json-cas`](https://www.npmjs.com/package/@uncaged/json-cas) (store API, hashing, schema validation) + `@uncaged/json-cas-fs` (filesystem backend). +External CAS: [`@ocas/core`](https://www.npmjs.com/package/@ocas/core) (store API, hashing, schema validation) + `@ocas/fs` (filesystem backend). See [docs/architecture.md](docs/architecture.md) for the full design — three-phase engine loop, CAS node types, storage layout, agent CLI protocol, and design decisions. diff --git a/docs/architecture.md b/docs/architecture.md index b4f9a38..6745b60 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -8,13 +8,13 @@ A stateless workflow engine driven by a single-step CLI. Workflows are YAML definitions stored as CAS nodes; threads are immutable chains of CAS-linked step nodes. No daemon — each `uwf thread step` invocation runs one moderator→agent→extract cycle and exits. -The implementation lives in **5** active packages under `packages/`, plus two external CAS packages (`@uncaged/json-cas`, `@uncaged/json-cas-fs`). Legacy packages reside in `legacy-packages/` and are not part of the active stack. +The implementation lives in **5** active packages under `packages/`, plus two external CAS packages (`@ocas/core`, `@ocas/fs`). Legacy packages reside in `legacy-packages/` and are not part of the active stack. ## Package map | Layer | Package | One-line role | |-------|---------|---------------| -| Contract | `@uncaged/workflow-protocol` → `workflow-protocol` | Shared TypeScript types (`WorkflowPayload`, `StepNodePayload`, `ModeratorContext`, `WorkflowConfig`, etc.). No runtime deps beyond `@uncaged/json-cas-fs`. | +| Contract | `@uncaged/workflow-protocol` → `workflow-protocol` | Shared TypeScript types (`WorkflowPayload`, `StepNodePayload`, `ModeratorContext`, `WorkflowConfig`, etc.). No runtime deps beyond `@ocas/fs`. | | Shared infra | `@uncaged/workflow-util` → `workflow-util` | Crockford Base32, ULID generation, `createLogger`, frontmatter parsing/validation. | | Agent framework | `@uncaged/workflow-util-agent` → `workflow-util-agent` | `createAgent` entrypoint factory, context builder, frontmatter fast-path extractor, LLM extract fallback, output format instruction builder. | | Agent: Hermes | `@uncaged/workflow-agent-hermes` → `workflow-agent-hermes` | `uwf-hermes` CLI binary — spawns `hermes chat`, pipes prompt, captures session detail. | @@ -24,8 +24,8 @@ The implementation lives in **5** active packages under `packages/`, plus two ex | Package | Role | |---------|------| -| `@uncaged/json-cas` | Content-addressed store API, XXH64 hashing, JSON Schema registration and validation. | -| `@uncaged/json-cas-fs` | Filesystem backend for `json-cas`. | +| `@ocas/core` | Content-addressed store API, XXH64 hashing, JSON Schema registration and validation. | +| `@ocas/fs` | Filesystem backend for `ocas`. | | `mustache` | Template renderer for edge prompts (used by `cli-workflow` moderator). | | `commander` | CLI argument parsing (used by `cli-workflow`). | | `dotenv` | Loads `.env` files for API keys. | @@ -36,8 +36,8 @@ The implementation lives in **5** active packages under `packages/`, plus two ex ```mermaid flowchart BT subgraph External - jcas["@uncaged/json-cas"] - jcasfs["@uncaged/json-cas-fs"] + jcas["@ocas/core"] + jcasfs["@ocas/fs"] end subgraph L0["Layer 0 — contract"] protocol["@uncaged/workflow-protocol"] @@ -146,7 +146,7 @@ Key properties: - **`roles`** — inline role definitions; each `meta` is a JSON Schema (stored as its own CAS node on registration) - **`graph`** — `Record>` — status-based routing; each role maps statuses to targets - **No agent binding** — agent selection is a deployment concern, configured in `config.yaml` -- **No Zod** — all schemas are JSON Schema, validated through `@uncaged/json-cas` +- **No Zod** — all schemas are JSON Schema, validated through `@ocas/core` ## Three-phase engine loop @@ -263,7 +263,7 @@ Structured output extraction uses a two-layer strategy (`workflow-util-agent`): 2. Validate required fields (`validateFrontmatter`) 3. Build a candidate object from frontmatter fields (`status`, `next`, `confidence`, `artifacts`, `scope`) 4. `store.put()` the candidate against the role's `meta` schema -5. Validate with `json-cas` schema validation +5. Validate with `ocas` schema validation 6. If valid → return `outputHash` (zero LLM cost) ### Layer 2: LLM extract fallback (`extract.ts`) @@ -302,7 +302,7 @@ payload: capabilities: [planning, issue-analysis] procedure: "Analyze the issue and create a plan." output: "Output the plan summary." - meta: "5GWKR8TN1V3JA" # cas_ref → JSON Schema node + meta: "5GWKR8TN1V3JA" # ocas_ref → JSON Schema node conditions: notApproved: description: "Reviewer rejected" @@ -318,7 +318,7 @@ payload: ```yaml type: payload: - workflow: "4KNM2PXR3B1QW" # cas_ref → Workflow + workflow: "4KNM2PXR3B1QW" # ocas_ref → Workflow prompt: "Fix the login bug..." ``` @@ -327,11 +327,11 @@ payload: ```yaml type: payload: - start: "4TNVW8KR2B3MA" # cas_ref → StartNode - prev: "2MXBG6PN4A8JR" # cas_ref → previous StepNode (null for first step) + start: "4TNVW8KR2B3MA" # ocas_ref → StartNode + prev: "2MXBG6PN4A8JR" # ocas_ref → previous StepNode (null for first step) role: "developer" - output: "9KRVW3TN5F1QA" # cas_ref → structured output (validated against meta schema) - detail: "7BQST3VW9F2MA" # cas_ref → execution detail (raw turns, session data) + output: "9KRVW3TN5F1QA" # ocas_ref → structured output (validated against meta schema) + detail: "7BQST3VW9F2MA" # ocas_ref → execution detail (raw turns, session data) agent: "uwf-hermes" # agent command used (plain string) ``` @@ -484,7 +484,7 @@ Binary: `uwf` | **Frontmatter markdown output** | Agents produce structured meta (YAML frontmatter) alongside free-form content (markdown body). Enables zero-cost extraction when frontmatter is well-formed. | | **Two-layer extract** | Fast path avoids LLM calls when agents follow the format; LLM fallback handles messy output gracefully. | | **Prompt injection for format** | Output format instruction prepended to system prompt ensures agents produce parseable output without per-agent configuration. | -| **JSON Schema (not Zod)** | Schemas are CAS-native data — storable, hashable, validatable through `json-cas`. No code generation, no runtime library dependency. | +| **JSON Schema (not Zod)** | Schemas are CAS-native data — storable, hashable, validatable through `ocas`. No code generation, no runtime library dependency. | | **Agent as external command** | Agents are independent CLI binaries (`uwf-hermes`, `uwf-cursor`). Swappable per workflow/role via config. No tight coupling to the engine. | | **No daemon** | Process starts, does one step, exits. Simpler failure model, no connection management. | | **Crockford Base32** | Filesystem-safe, case-insensitive, readable, compact. | diff --git a/docs/builtin-agent-research.md b/docs/builtin-agent-research.md index a76ae7b..96c6f1a 100644 --- a/docs/builtin-agent-research.md +++ b/docs/builtin-agent-research.md @@ -630,7 +630,7 @@ flowchart TB Spawn -->|"stdout: step hash"| Step ``` -**新包**：`packages/workflow-agent-builtin`，bin `uwf-builtin`，仅依赖 `workflow-util-agent`、`workflow-protocol`、`workflow-util`（可选 `@uncaged/json-cas` 写 detail schema）。 +**新包**：`packages/workflow-agent-builtin`，bin `uwf-builtin`，仅依赖 `workflow-util-agent`、`workflow-protocol`、`workflow-util`（可选 `@ocas/core` 写 detail schema）。 **分层**： diff --git a/docs/wf-stateless-design.md b/docs/wf-stateless-design.md index 6a0b527..b6b05ee 100644 --- a/docs/wf-stateless-design.md +++ b/docs/wf-stateless-design.md @@ -22,7 +22,7 @@ uwf workflow show # 查看 workflow 定义 uwf workflow list # 列出已注册 workflows ``` -两组对称，各 3-4 个子命令。CAS 操作交给 `json-cas` CLI，不在 `uwf` 中重复。 +两组对称，各 3-4 个子命令。CAS 操作交给 `ocas` CLI，不在 `uwf` 中重复。 ### 1.2 `uwf thread start` @@ -136,14 +136,14 @@ uwf-hermes 沿用 json-cas 的三层：bootstrap meta-schema → JSON Schema nodes → data nodes。 -下面所有 CAS 节点都遵循 `{ type: cas_ref, payload: T, timestamp: number }` 的标准格式。 -`cas_ref` 类型的字符串字段在 json-cas 中已内置支持，不需要额外的 `$ref` 包装。 +下面所有 CAS 节点都遵循 `{ type: ocas_ref, payload: T, timestamp: number }` 的标准格式。 +`ocas_ref` 类型的字符串字段在 ocas 中已内置支持，不需要额外的 `$ref` 包装。 ### 2.2 数据节点 #### `Workflow` -Roles 和 moderator 内联在 Workflow 中，只有 meta 独立为 CAS 节点（方便 json-cas 校验）。 +Roles 和 moderator 内联在 Workflow 中，只有 meta 独立为 CAS 节点（方便 ocas 校验）。 ```yaml type: @@ -157,21 +157,21 @@ payload: capabilities: [planning, issue-analysis] procedure: "Analyze the issue and create a plan." output: "Output the plan summary." - meta: "5GWKR8TN1V3JA" # cas_ref → JSON Schema 节点（json-cas 内置） + meta: "5GWKR8TN1V3JA" # ocas_ref → JSON Schema 节点（ocas 内置） developer: description: "Implements code changes" goal: "You are a developer agent..." capabilities: [file-edit, shell] procedure: "Implement the plan." output: "List all files changed." - meta: "8CNWT4KR6D1HV" # cas_ref → JSON Schema 节点 + meta: "8CNWT4KR6D1HV" # ocas_ref → JSON Schema 节点 reviewer: description: "Reviews code changes" goal: "You are a code reviewer..." capabilities: [code-review] procedure: "Review the implementation." output: "Approve or reject with comments." - meta: "1VPBG9SM5E7WK" # cas_ref → JSON Schema 节点 + meta: "1VPBG9SM5E7WK" # ocas_ref → JSON Schema 节点 conditions: needsClarification: description: "Planner requests clarification from user" @@ -198,7 +198,7 @@ payload: condition: null ``` -- `roles` — 内联定义，每个 role 的 `meta` 是独立的 cas_ref（指向 json-cas 内置 JSON Schema 节点） +- `roles` — 内联定义，每个 role 的 `meta` 是独立的 ocas_ref（指向 ocas 内置 JSON Schema 节点） - `graph` — `Record>`，每个 Target = `{ role, prompt }` - Status 来自上一个 role 输出的 `status` 字段，`$START` 用 `_` 作为初始 status - Prompt 模板使用 Mustache 渲染，变量来自 lastOutput @@ -220,7 +220,7 @@ evaluate(graph, lastRole, lastOutput) → { role, prompt } ```yaml type: payload: - workflow: "4KNM2PXR3B1QW" # cas_ref → Workflow + workflow: "4KNM2PXR3B1QW" # ocas_ref → Workflow prompt: "Fix the login bug..." ``` @@ -232,18 +232,18 @@ payload: ```yaml type: payload: - start: "4TNVW8KR2B3MA" # cas_ref → StartNode（每个 step 都引用） - prev: "2MXBG6PN4A8JR" # cas_ref → 前一个 StepNode，第一步为 null + start: "4TNVW8KR2B3MA" # ocas_ref → StartNode（每个 step 都引用） + prev: "2MXBG6PN4A8JR" # ocas_ref → 前一个 StepNode，第一步为 null role: "developer" - output: "9KRVW3TN5F1QA" # cas_ref → 结构化输出节点（符合 role 的 meta schema） - detail: "7BQST3VW9F2MA" # cas_ref → 执行详情（content node / 子 workflow terminal StepNode / ...） + output: "9KRVW3TN5F1QA" # ocas_ref → 结构化输出节点（符合 role 的 meta schema） + detail: "7BQST3VW9F2MA" # ocas_ref → 执行详情（content node / 子 workflow terminal StepNode / ...） agent: "uwf-cursor" # 实际使用的 agent 命令（纯字符串） ``` - `start` — 每个 StepNode 都直接引用 StartNode，方便随机访问 -- `prev` — 前一个 StepNode 的 cas_ref，第一步为 `null`（不指向 StartNode） -- `output` — cas_ref，指向符合 role meta schema 的 CAS 节点，可用 json-cas 校验 -- `detail` — cas_ref，指向执行详情。可以是原始 agent 输出（content node），也可以是子 workflow thread 的 terminal StepNode（workflowAsAgent 场景） +- `prev` — 前一个 StepNode 的 ocas_ref，第一步为 `null`（不指向 StartNode） +- `output` — ocas_ref，指向符合 role meta schema 的 CAS 节点，可用 ocas 校验 +- `detail` — ocas_ref，指向执行详情。可以是原始 agent 输出（content node），也可以是子 workflow thread 的 terminal StepNode（workflowAsAgent 场景） - `agent` — 纯字符串，不是 CAS 节点 ### 2.3 链式结构 @@ -337,7 +337,7 @@ OPENROUTER_API_KEY=sk-or-... ## 3. 包结构 -全新包，不复用现有 packages，避免命名冲突。CAS 直接依赖 `@uncaged/json-cas`。 +全新包，不复用现有 packages，避免命名冲突。CAS 直接依赖 `@ocas/core`。 ``` packages/ @@ -349,8 +349,8 @@ packages/ ``` **外部依赖：** -- `@uncaged/json-cas` — CAS 存储、hash、schema 校验 -- `@uncaged/json-cas-fs` — 文件系统 CAS 后端 +- `@ocas/core` — CAS 存储、hash、schema 校验 +- `@ocas/fs` — 文件系统 CAS 后端 **现有包全部保留不动**，新旧并存，逐步迁移。 @@ -372,8 +372,8 @@ type ThreadId = string; /** 一个 step 的核心数据，被 StepNode payload 和 moderator 上下文共享 */ type StepRecord = { role: string; - output: CasRef; // cas_ref → 结构化输出节点（符合 role meta schema） - detail: CasRef; // cas_ref → 执行详情（content node / 子 workflow terminal StepNode） + output: CasRef; // ocas_ref → 结构化输出节点（符合 role meta schema） + detail: CasRef; // ocas_ref → 执行详情（content node / 子 workflow terminal StepNode） agent: string; // 实际使用的 agent 命令（纯字符串） }; ``` @@ -387,7 +387,7 @@ type RoleDefinition = { capabilities: string[]; procedure: string; output: string; - meta: CasRef; // cas_ref → json-cas 内置 JSON Schema 节点 + meta: CasRef; // ocas_ref → ocas 内置 JSON Schema 节点 }; type Target = { @@ -407,13 +407,13 @@ type WorkflowPayload = { ```typescript type StartNodePayload = { - workflow: CasRef; // cas_ref → Workflow + workflow: CasRef; // ocas_ref → Workflow prompt: string; }; type StepNodePayload = StepRecord & { - start: CasRef; // cas_ref → StartNode（每个 step 都引用） - prev: CasRef | null; // cas_ref → 前一个 StepNode，第一步为 null + start: CasRef; // ocas_ref → StartNode（每个 step 都引用） + prev: CasRef | null; // ocas_ref → 前一个 StepNode，第一步为 null }; ``` diff --git a/packages/cli-workflow/README.md b/packages/cli-workflow/README.md index 2f9dc92..48763dc 100644 --- a/packages/cli-workflow/README.md +++ b/packages/cli-workflow/README.md @@ -20,7 +20,7 @@ workflow → thread → step → turn This package has no library `src/index.ts` — it is consumed as a CLI binary only. -**Dependencies:** `@uncaged/json-cas`, `@uncaged/json-cas-fs`, `@uncaged/workflow-util-agent`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`, `commander`, `dotenv`, `mustache`, `yaml` +**Dependencies:** `@ocas/core`, `@ocas/fs`, `@uncaged/workflow-util-agent`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`, `commander`, `dotenv`, `mustache`, `yaml` ## Installation @@ -209,7 +209,7 @@ src/ | `~/.uncaged/workflow/.env` | API keys (referenced by `apiKeyEnv` in config) | | `~/.uncaged/workflow/registry.yaml` | Workflow name → CAS hash | | `~/.uncaged/workflow/threads.yaml` | Active thread head pointers | -| `~/.uncaged/json-cas/` | Content-addressed node storage (unified CAS store, shared with `json-cas` CLI) | +| `~/.uncaged/json-cas/` | Content-addressed node storage (unified CAS store, shared with `ocas` CLI) | ### Environment Variables diff --git a/packages/workflow-agent-builtin/README.md b/packages/workflow-agent-builtin/README.md index 4855310..52efdf6 100644 --- a/packages/workflow-agent-builtin/README.md +++ b/packages/workflow-agent-builtin/README.md @@ -8,7 +8,7 @@ Layer 3 agent implementation. Runs an OpenAI-compatible chat completion loop wit Useful when you want a self-contained agent without an external CLI like Hermes or Claude Code. -**Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-util-agent`, `@uncaged/workflow-util` +**Dependencies:** `@ocas/core`, `@uncaged/workflow-util-agent`, `@uncaged/workflow-util` ## Installation diff --git a/packages/workflow-agent-claude-code/README.md b/packages/workflow-agent-claude-code/README.md index 09f84b9..4e6860f 100644 --- a/packages/workflow-agent-claude-code/README.md +++ b/packages/workflow-agent-claude-code/README.md @@ -6,7 +6,7 @@ Layer 3 agent implementation. Spawns the `claude` CLI with a composed system prompt (role definition, task, prior steps, edge prompt). Parses stream or JSON stdout, caches session IDs for multi-turn continuation, and stores raw output plus structured detail in CAS. -**Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-util-agent` +**Dependencies:** `@ocas/core`, `@uncaged/workflow-util-agent` ## Installation diff --git a/packages/workflow-agent-hermes/README.md b/packages/workflow-agent-hermes/README.md index 3c6d445..61f0f57 100644 --- a/packages/workflow-agent-hermes/README.md +++ b/packages/workflow-agent-hermes/README.md @@ -8,7 +8,7 @@ On first visit to a role it sends a composed prompt (role definition, task, history, edge prompt); on continuation it resumes the cached session. Session transcripts and raw output are stored as CAS detail nodes. -**Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-util-agent`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util` +**Dependencies:** `@ocas/core`, `@uncaged/workflow-util-agent`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util` ## Installation diff --git a/packages/workflow-protocol/README.md b/packages/workflow-protocol/README.md index 3f0644f..627da27 100644 --- a/packages/workflow-protocol/README.md +++ b/packages/workflow-protocol/README.md @@ -4,9 +4,9 @@ Shared TypeScript types and JSON Schema constants for the workflow engine. ## Overview -This is the contract layer (Layer 0). It defines `WorkflowPayload`, thread node payloads, moderator context, CLI output shapes, and configuration types used across every other package. It has no runtime logic beyond exporting schema objects from `@uncaged/json-cas`. +This is the contract layer (Layer 0). It defines `WorkflowPayload`, thread node payloads, moderator context, CLI output shapes, and configuration types used across every other package. It has no runtime logic beyond exporting schema objects from `@ocas/core`. -**Dependencies:** `@uncaged/json-cas`, `@uncaged/json-cas-fs` +**Dependencies:** `@ocas/core`, `@ocas/fs` ## Installation diff --git a/packages/workflow-util-agent/README.md b/packages/workflow-util-agent/README.md index a1b75f1..47eeefd 100644 --- a/packages/workflow-util-agent/README.md +++ b/packages/workflow-util-agent/README.md @@ -8,7 +8,7 @@ Layer 2 agent framework. Provides the standard entrypoint for all agent CLIs: pa Also exports prompt builders, config/storage helpers, and session ID caching for multi-turn agents. -**Dependencies:** `@uncaged/json-cas`, `@uncaged/json-cas-fs`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`, `dotenv`, `yaml` +**Dependencies:** `@ocas/core`, `@ocas/fs`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`, `dotenv`, `yaml` ## Installation