pi-okf

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# pi-okf

CLI for creating and validating [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) bundles.

OKF is Google’s open, Markdown-first format for portable knowledge — a directory of `.md` files with YAML frontmatter. No required manifest. This tool implements create/validate/index/pack against the **v0.1 Draft** spec (SHA pinned in `package.json`).

## Official OKF documentation (Google)

| Resource | Link |
|---|---|
| **Specification (canonical)** | [okf/SPEC.md](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) |
| **Spec (raw)** | [raw SPEC.md](https://raw.githubusercontent.com/GoogleCloudPlatform/knowledge-catalog/main/okf/SPEC.md) |
| **OKF directory & overview** | [GoogleCloudPlatform/knowledge-catalog → okf/](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) |
| **Sample bundles** | [samples/](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/samples) |
| **Launch announcement** | [How the Open Knowledge Format can improve data sharing](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) (Google Cloud blog, June 12, 2026) |
| **Product** | [Google Cloud Knowledge Catalog](https://cloud.google.com/products/knowledge-catalog) |

`pi-okf` is an independent community CLI. It is **not** an official Google product. Prefer the links above when the format itself is in question.

```bash
pi-okf --spec-info   # prints pinned OKF version + SHA used by this release
```

## Install

```bash
# from source
git clone https://github.com/kaishin/pi-okf.git
cd pi-okf
npm install
npm run build
npm link                 # optional: put `pi-okf` on PATH

# or run without linking
npx tsx src/cli.ts <command>
```

Requires **Node.js ≥ 18**.

## Commands

```bash
pi-okf validate <bundle-path> [--strict] [--json] [--fail-on-warnings]
pi-okf init <bundle-name> [--dir <path>]
pi-okf index <bundle-path> [--write]
pi-okf pack <bundle-path> [--out <path>] [--no-okf]
pi-okf inspect <file.md> [--json]
pi-okf capture <bundle-path> --summary <text> [--title <text>] [--decision <text>...] [--change <text>...] [--question <text>...]
pi-okf --spec-info [--json]
pi-okf --help | --version
```

### `validate`

Walks the bundle tree and checks normative OKF rules from the [official spec](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md):

| Severity | Rule | Behavior |
|---|---|---|
| **Hard** | §2.2 item 1 — frontmatter must be parseable YAML when present | error → exit 1 |
| **Hard** | §2.2 item 2 — non-empty `type` when frontmatter present | error → exit 1 |
| **Hard** | §6 — `index.md` must not have frontmatter | error → exit 1 |
| **Soft** | Missing frontmatter on plain docs | warn (use `--strict` to fail) |
| **Soft** | §9 — unknown `type`, unknown keys, broken links, missing `index.md` | warn only |

**§9 Conformance (normative for consumers):** consumers MUST NOT reject a bundle solely because of missing optional fields, unknown `type` values, unknown extra frontmatter keys, broken cross-links, or missing `index.md`. This CLI treats those as warnings (exit 2), never hard failures.

Exit codes:

| Code | Meaning |
|---|---|
| `0` | Clean — no errors or warnings |
| `1` | Hard error |
| `2` | Soft warnings only |

### `init`

Scaffolds `index.md`, `log.md`, and an example `concept.md` with full frontmatter.

### `index`

Generates `index.md` content grouped by frontmatter `type`. Pass `--write` to overwrite files.

### `pack`

Zips the bundle to `<name>.okf` (or `.zip` with `--no-okf`). Uses system `zip` when available, otherwise `adm-zip`.

### `inspect`

Dumps frontmatter and structure for a single `.md` file.

### `capture`

Appends a dated entry to the bundle's `log.md` summarising the current session: a title, a one-line summary, and optional bulleted lists for decisions, changes, and open questions. When called, the command also runs `okf validate` and prints the result so you can spot any conformance errors introduced by the new entry.

```bash
pi-okf capture okf/ \
  --summary "Migrated the subscription model docs to the new schema" \
  --title "Subscription model migration" \
  --decision "Treat the application schema as the source of truth." \
  --decision "Keep payments staging in the ledger tables, not the app." \
  --change "Rewrote tables/subscriptions.md to reference the new entities." \
  --question "Confirm the retention policy with the data team."
```

Repeated `--decision`, `--change`, and `--question` flags accumulate into bulleted lists. Entries for the same day are grouped under a single `## YYYY-MM-DD` heading; the most recent capture sits at the top of that group, and newer days sit above older ones in the log.

Exit codes:

| Code | Meaning |
|---|---|
| `0` | Capture succeeded; no hard validation errors |
| `1` | Hard validation error in the bundle (e.g. broken `log.md` structure) |

Soft validation warnings (such as a missing root `index.md`) are reported but never block capture.

## Examples

```bash
pi-okf validate examples/minimal-bundle/          # exit 0, prints OK
pi-okf validate examples/broken-bundle/           # exit 1, cites §2.2
pi-okf validate examples/soft-violation-bundle/   # exit 2, warnings only
pi-okf init my-bundle && pi-okf validate my-bundle/
pi-okf pack examples/minimal-bundle/ --out /tmp/minimal.okf
pi-okf capture my-bundle/ --summary "Shipped the capture command" --decision "Keep /okf-capture args unstructured"
```

## Spec pin

| Field | Value |
|---|---|
| Version | 0.1 Draft |
| Canonical URL | https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md |
| SHA | `ee67a5ca27044ebe7c38385f5b6cffc2305a9c1a` (`package.json` → `okf.specSha`) |

## Development

```bash
npm install
npm test          # vitest
npm run check     # tsc --noEmit
npm run build     # emit dist/
```

## Pi package (optional)

This repo also ships a [Pi](https://pi.dev) extension (`extensions/okf.ts`) and skill for agent workflows. The CLI is the primary interface and does not require Pi.

```bash
pi install npm:pi-okf
# or develop locally
pi -e /absolute/path/to/pi-okf
```

For an ongoing authoring session, use the Pi `okf_diff` tool (or `/okf-diff [path]`) before `okf_inspect`. It lists staged, unstaged, and untracked files relative to `HEAD`, so the agent can read the changed sources before updating `/okf`. The tool accepts `base` (for example, `origin/main`), `path`, and `includeUntracked` when a broader or narrower change window is needed.

At the end of a meaningful session, call the `okf_capture` tool (or `/okf-capture [bundle-path] [summary...]`) to append a dated entry with decisions, changes, and open questions to `/okf/log.md`. Pass structured args to the tool when bullets are needed; the slash command stays light and treats everything after the bundle path as the summary.

## Contributing

Issues and PRs: [github.com/kaishin/pi-okf](https://github.com/kaishin/pi-okf).

When changing validation behavior, keep §9 soft-constraint rules as warnings unless the official [SPEC.md](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) hardens them.

## License

[MIT](https://github.com/kaishin/pi-okf/tree/HEAD/LICENSE) © 2026 Kaishin.

OKF itself is an open specification published by Google Cloud; see the [knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog) repository for Google’s terms on the format, samples, and reference tooling. This CLI is a separate project and is not affiliated with or endorsed by Google.

pi-okf

CLI for creating and validating Open Knowledge Format (OKF) bundles.

OKF is Google’s open, Markdown-first format for portable knowledge — a directory of .md files with YAML frontmatter. No required manifest. This tool implements create/validate/index/pack against the v0.1 Draft spec (SHA pinned in package.json).

Official OKF documentation (Google)

Resource	Link
Specification (canonical)	okf/SPEC.md
Spec (raw)	raw SPEC.md
OKF directory & overview	GoogleCloudPlatform/knowledge-catalog → okf/
Sample bundles	samples/
Launch announcement	How the Open Knowledge Format can improve data sharing (Google Cloud blog, June 12, 2026)
Product	Google Cloud Knowledge Catalog

pi-okf is an independent community CLI. It is not an official Google product. Prefer the links above when the format itself is in question.

pi-okf --spec-info   # prints pinned OKF version + SHA used by this release

Install

# from source
git clone https://github.com/kaishin/pi-okf.git
cd pi-okf
npm install
npm run build
npm link                 # optional: put `pi-okf` on PATH

# or run without linking
npx tsx src/cli.ts <command>

Requires Node.js ≥ 18.

Commands

pi-okf validate <bundle-path> [--strict] [--json] [--fail-on-warnings]
pi-okf init <bundle-name> [--dir <path>]
pi-okf index <bundle-path> [--write]
pi-okf pack <bundle-path> [--out <path>] [--no-okf]
pi-okf inspect <file.md> [--json]
pi-okf capture <bundle-path> --summary <text> [--title <text>] [--decision <text>...] [--change <text>...] [--question <text>...]
pi-okf --spec-info [--json]
pi-okf --help | --version

`validate`

Walks the bundle tree and checks normative OKF rules from the official spec:

Severity	Rule	Behavior
Hard	§2.2 item 1 — frontmatter must be parseable YAML when present	error → exit 1
Hard	§2.2 item 2 — non-empty `type` when frontmatter present	error → exit 1
Hard	§6 — `index.md` must not have frontmatter	error → exit 1
Soft	Missing frontmatter on plain docs	warn (use `--strict` to fail)
Soft	§9 — unknown `type`, unknown keys, broken links, missing `index.md`	warn only

§9 Conformance (normative for consumers): consumers MUST NOT reject a bundle solely because of missing optional fields, unknown type values, unknown extra frontmatter keys, broken cross-links, or missing index.md. This CLI treats those as warnings (exit 2), never hard failures.

Exit codes:

Code	Meaning
`0`	Clean — no errors or warnings
`1`	Hard error
`2`	Soft warnings only

`init`

Scaffolds index.md, log.md, and an example concept.md with full frontmatter.

`index`

Generates index.md content grouped by frontmatter type. Pass --write to overwrite files.

`pack`

Zips the bundle to <name>.okf (or .zip with --no-okf). Uses system zip when available, otherwise adm-zip.

`inspect`

Dumps frontmatter and structure for a single .md file.

`capture`

Appends a dated entry to the bundle's log.md summarising the current session: a title, a one-line summary, and optional bulleted lists for decisions, changes, and open questions. When called, the command also runs okf validate and prints the result so you can spot any conformance errors introduced by the new entry.

pi-okf capture okf/ \
  --summary "Migrated the subscription model docs to the new schema" \
  --title "Subscription model migration" \
  --decision "Treat the application schema as the source of truth." \
  --decision "Keep payments staging in the ledger tables, not the app." \
  --change "Rewrote tables/subscriptions.md to reference the new entities." \
  --question "Confirm the retention policy with the data team."

Repeated --decision, --change, and --question flags accumulate into bulleted lists. Entries for the same day are grouped under a single ## YYYY-MM-DD heading; the most recent capture sits at the top of that group, and newer days sit above older ones in the log.

Exit codes:

Code	Meaning
`0`	Capture succeeded; no hard validation errors
`1`	Hard validation error in the bundle (e.g. broken `log.md` structure)

Soft validation warnings (such as a missing root index.md) are reported but never block capture.

Examples

pi-okf validate examples/minimal-bundle/          # exit 0, prints OK
pi-okf validate examples/broken-bundle/           # exit 1, cites §2.2
pi-okf validate examples/soft-violation-bundle/   # exit 2, warnings only
pi-okf init my-bundle && pi-okf validate my-bundle/
pi-okf pack examples/minimal-bundle/ --out /tmp/minimal.okf
pi-okf capture my-bundle/ --summary "Shipped the capture command" --decision "Keep /okf-capture args unstructured"

Spec pin

Field	Value
Version	0.1 Draft
Canonical URL	https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
SHA	`ee67a5ca27044ebe7c38385f5b6cffc2305a9c1a` (`package.json` → `okf.specSha`)

Development

npm install
npm test          # vitest
npm run check     # tsc --noEmit
npm run build     # emit dist/

Pi package (optional)

This repo also ships a Pi extension (extensions/okf.ts) and skill for agent workflows. The CLI is the primary interface and does not require Pi.

pi install npm:pi-okf
# or develop locally
pi -e /absolute/path/to/pi-okf

For an ongoing authoring session, use the Pi okf_diff tool (or /okf-diff [path]) before okf_inspect. It lists staged, unstaged, and untracked files relative to HEAD, so the agent can read the changed sources before updating /okf. The tool accepts base (for example, origin/main), path, and includeUntracked when a broader or narrower change window is needed.

At the end of a meaningful session, call the okf_capture tool (or /okf-capture [bundle-path] [summary...]) to append a dated entry with decisions, changes, and open questions to /okf/log.md. Pass structured args to the tool when bullets are needed; the slash command stays light and treats everything after the bundle path as the summary.

Contributing

Issues and PRs: github.com/kaishin/pi-okf.

When changing validation behavior, keep §9 soft-constraint rules as warnings unless the official SPEC.md hardens them.

License

OKF itself is an open specification published by Google Cloud; see the knowledge-catalog repository for Google’s terms on the format, samples, and reference tooling. This CLI is a separate project and is not affiliated with or endorsed by Google.