jiayiyan
55 lines
3.1 KiB
Markdown
55 lines
3.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Commands
|
|
|
|
```sh
|
|
bun install # install dependencies
|
|
bun run check # Biome lint + format (run before committing)
|
|
bun test # run all tests
|
|
bun test <path> # run a single test file
|
|
bun run bundle # bundle all *-entry.ts files → dist/*.esm.js
|
|
uncaged-workflow add <name> <bundle.esm.js> # register a workflow bundle
|
|
uncaged-workflow run <name> # run a registered workflow
|
|
```
|
|
|
|
### One-time setup for docx-diff binary
|
|
|
|
```sh
|
|
cd /Users/yanjiayi/workspace/docx-diff && npm install && npm run build && npm link
|
|
```
|
|
|
|
The `@uncaged` scoped packages resolve from a private registry configured in `bunfig.toml` (`https://git.shazhou.work/api/packages/shazhou/npm/`).
|
|
|
|
## Architecture
|
|
|
|
This is a Bun monorepo (`workspaces: ["templates/*", "workflows"]`) for developing `@uncaged/workflow-runtime` workflows.
|
|
|
|
**Two layers:**
|
|
|
|
- `templates/<name>/` — pure data packages: `WorkflowDefinition` (roles + `ModeratorTable`), no agent binding. Exported from `src/index.ts`.
|
|
- `workflows/` — binds a template's `WorkflowDefinition` to an `AdapterFn` and `ExtractFn`; each workflow instance is a `*-entry.ts` file that the bundle script turns into a single `dist/*.esm.js`.
|
|
|
|
**Bundle script** (`scripts/bundle.ts`): scans `workflows/` for `*-entry.ts` files, bundles each with Bun into `dist/<stem>.esm.js` (ESM, Node target, no splitting). All `@uncaged/workflow-*` packages are kept external. Also emits a `.d.ts` shim per bundle.
|
|
|
|
**Engine loop**: `ModeratorTable` routes from `START` → role → … → `END`. Each step: Adapter produces typed meta via the role's Zod schema; engine appends the step and selects the next role.
|
|
|
|
**Core types** (from `@uncaged/workflow-runtime`):
|
|
- `RoleMeta` — `Record<string, Record<string, unknown>>`: role name → meta shape
|
|
- `RoleDefinition<Meta>` — `description`, `systemPrompt`, `schema` (Zod v4)
|
|
- `WorkflowDefinition<M>` — `description` + `roles` + `ModeratorTable`
|
|
- `ModeratorTable` — declarative, serializable routing table; maps `START`/role names to ordered transition lists (`check` + next role or `END`)
|
|
- `AdapterFn` — receives system prompt + Zod schema, returns a `RoleFn`
|
|
- `ExtractFn` — resolves structured data from a CAS content hash
|
|
|
|
## Coding Conventions
|
|
|
|
- **`type` not `interface`** — use type aliases everywhere.
|
|
- **`T | null` not `?:`** — write nullable fields as `field: T | null`, not `field?: T`.
|
|
- **`function` not `class`** — no classes except third-party requirements or `Error` subclasses.
|
|
- **Named exports only** — no default exports. Workflow bundles must export `run` and `descriptor` by name.
|
|
- **No `console.log`** — use structured logger in library code.
|
|
- **No dynamic `import()`** — bundles must be statically analyzable; dynamic imports break hash and loading constraints.
|
|
- **No `import()` in business code** — the only exception is the engine's own bundle loader.
|