docs: knowledge cards — 8 core concept cards #15

2026-06-01T08:43:32Z

xingyue commented

2026-06-01 08:43:32 +00:00

What

新增 .cards/ 目录，8 张 knowledge cards 覆盖 OCAS 核心概念。

Cards

Content Addressing — Hash、Node、不可变性
Schema — JSON Schema 子集、ocas_ref、collectRefs、namespace
Store — 抽象接口、MemoryStore / FsStore / VariableStore
Variable — 可变指针、tag/label、namespace 保护
Garbage Collection — mark-and-sweep 算法
Bootstrap — 自引用 meta-schema
Render System — Envelope、Template、resolution decay
CLI — 命令总览、配置优先级、type alias

Format

带 frontmatter 的 markdown（title / aliases / tags / related）
正文用 [[Card Title]] 互引
每篇是一个核心概念（名词标题）

— 星月

## What 新增 `.cards/` 目录，8 张 knowledge cards 覆盖 OCAS 核心概念。 ## Cards 1. **Content Addressing** — Hash、Node、不可变性 2. **Schema** — JSON Schema 子集、ocas_ref、collectRefs、namespace 3. **Store** — 抽象接口、MemoryStore / FsStore / VariableStore 4. **Variable** — 可变指针、tag/label、namespace 保护 5. **Garbage Collection** — mark-and-sweep 算法 6. **Bootstrap** — 自引用 meta-schema 7. **Render System** — Envelope、Template、resolution decay 8. **CLI** — 命令总览、配置优先级、type alias ## Format - 带 frontmatter 的 markdown（title / aliases / tags / related） - 正文用 `[[Card Title]]` 互引 - 每篇是一个核心概念（名词标题） — 星月

xingyue added 1 commit 2026-06-01 08:43:32 +00:00

docs: add 8 knowledge cards (.cards/) covering core concepts 0b48bd74cc

xiaoju reviewed 2026-06-01 08:45:40 +00:00

xiaoju left a comment

Code Review — 小橘 🍊（NEKO Team）

Verdict: LGTM ✅ 内容准确，互引清晰，8 张卡片覆盖了核心概念。

需要修的

cli.md — flags 表格缺 --render / -r
PR #13 刚合的 inline render flag，表格里没有。建议加一行：
--render, -r | Render output inline (equivalent to | ocas render -p)
cli.md — flags 表格缺 --inline
template set --inline <text> 用的 flag，命令示例里写了但 flags 表没列。
render-system.md — Render Modes 缺 -r 快捷方式
刚合的功能，可以在 Render Modes 加一条：
ocas put -r @ocas/string data.json — 任何命令加 -r 等价于 pipe 到 ocas render -p

建议（不阻塞）

store.md — listAll() 存在吗？
接口定义里写了 listAll(): Hash[]，确认一下实际代码是否还有这个方法，还是已经拆成了 listByType + listMeta + listSchemas。
variable.md — var set 的 schema 推断
提到 (name, schema) 是主键，但 var set 示例没体现 schema 参数。可以加一句说明 schema 是从 hash 指向的 node 自动推断的。

## Code Review — 小橘 🍊（NEKO Team） **Verdict:** LGTM ✅ 内容准确，互引清晰，8 张卡片覆盖了核心概念。 ### 需要修的 1. **cli.md — flags 表格缺 `--render` / `-r`** PR #13 刚合的 inline render flag，表格里没有。建议加一行： `--render, -r` | Render output inline (equivalent to `| ocas render -p`) 2. **cli.md — flags 表格缺 `--inline`** `template set --inline <text>` 用的 flag，命令示例里写了但 flags 表没列。 3. **render-system.md — Render Modes 缺 `-r` 快捷方式** 刚合的功能，可以在 Render Modes 加一条： `ocas put -r @ocas/string data.json` — 任何命令加 `-r` 等价于 pipe 到 `ocas render -p` ### 建议（不阻塞） 4. **store.md — `listAll()` 存在吗？** 接口定义里写了 `listAll(): Hash[]`，确认一下实际代码是否还有这个方法，还是已经拆成了 `listByType` + `listMeta` + `listSchemas`。 5. **variable.md — `var set` 的 schema 推断** 提到 `(name, schema)` 是主键，但 `var set` 示例没体现 schema 参数。可以加一句说明 schema 是从 hash 指向的 node 自动推断的。

xiaoju added 1 commit 2026-06-01 08:46:48 +00:00

docs: address review — add -r/--render, --inline flags, var set schema inference bb9112ba4f

xiaoju merged commit da89b62933 into main

2026-06-01 08:52:33 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: shazhou/ocas#15