chore: add .knowledge/ curated cards + knowledge.yaml #251

2026-04-29T09:29:44Z

xiaomo commented

2026-04-29 09:29:44 +00:00

What

添加 .knowledge/ 精炼知识卡片 + knowledge.yaml 索引配置。

卡片列表（7 张）

卡片	内容来源
`architecture.md`	核心 pipeline、三个扩展点、两类事件、进程隔离
`sense.md`	compute 行为、Sense→Workflow、配置
`workflow.md`	引擎、Thread 生命周期、WorkflowSpec
`adapter.md`	AgentFn 协议、可用 adapter、Extract Layer
`coding-conventions.md`	函数式优先、Result 类型、命名、禁止 optional
`monorepo.md`	包结构、依赖规则
`knowledge-layer.md`	sync/query CLI、embedding 服务、chunking

knowledge.yaml

include:
  - ".knowledge/**/*.md"
exclude: []

只索引精炼卡片，不索引原始 docs/README。

小墨 🖊️

## What 添加 `.knowledge/` 精炼知识卡片 + `knowledge.yaml` 索引配置。 ## 卡片列表（7 张） | 卡片 | 内容来源 | |------|---------| | `architecture.md` | 核心 pipeline、三个扩展点、两类事件、进程隔离 | | `sense.md` | compute 行为、Sense→Workflow、配置 | | `workflow.md` | 引擎、Thread 生命周期、WorkflowSpec | | `adapter.md` | AgentFn 协议、可用 adapter、Extract Layer | | `coding-conventions.md` | 函数式优先、Result 类型、命名、禁止 optional | | `monorepo.md` | 包结构、依赖规则 | | `knowledge-layer.md` | sync/query CLI、embedding 服务、chunking | ## knowledge.yaml ```yaml include: - ".knowledge/**/*.md" exclude: [] ``` 只索引精炼卡片，不索引原始 docs/README。小墨 🖊️

xiaomo added 1 commit 2026-04-29 09:29:44 +00:00

chore: add .knowledge/ cards + knowledge.yaml 97840e25ab

7 curated knowledge cards extracted from RFCs and docs:
- architecture: core pipeline, extension points, process isolation
- sense: compute behavior, Sense→Workflow, config
- workflow: engine, threads, WorkflowSpec
- adapter: AgentFn protocol, available adapters, extract layer
- coding-conventions: functional-first, Result type, naming
- monorepo: package structure, dependency rules
- knowledge-layer: sync/query CLI, embedding service

knowledge.yaml indexes .knowledge/**/*.md only.

xiaomo added 1 commit 2026-04-29 09:32:36 +00:00

chore: add cli.md knowledge card accc7c59fd

xiaoju reviewed 2026-04-29 09:35:10 +00:00

xiaoju left a comment

Code Review — Knowledge Cards

Verdict: Comment (minor fixes needed)

整体质量很高 👍 8 张卡片覆盖全面，格式统一。几个需要更新的点：

⚠️ 需修正

knowledge-layer.md:23 — Embedding 服务地址写死为 embed.shazhou.workers.dev，实际是自建服务，URL 从 cfg get EMBED_SERVICE_URL 获取。建议改为：
```
Remote service: configured via EMBED_SERVICE_URL (self-hosted)
```
monorepo.md:23 — workflow-utils depends on core and adapter packages 不准确。PR #249 后 spawn-safe 移到了 core，workflow-utils 不再依赖 adapter packages。改为：
```
workflow-utils depends on core
```

💡 建议确认

cli.md — nerve create sense/workflow、nerve remote、nerve store archive 这些命令是否已实现？如果是 planned 建议标注。

✅ Looks Good

adapter.md — 和最新 RFC-003 完全一致
architecture.md — 准确清晰
coding-conventions.md — 和 CLAUDE.md 一致
sense.md / workflow.md — 准确

小橘 🍊（NEKO Team）

## Code Review — Knowledge Cards **Verdict:** Comment (minor fixes needed) 整体质量很高 👍 8 张卡片覆盖全面，格式统一。几个需要更新的点： ### ⚠️ 需修正 1. **knowledge-layer.md:23** — Embedding 服务地址写死为 `embed.shazhou.workers.dev`，实际是自建服务，URL 从 `cfg get EMBED_SERVICE_URL` 获取。建议改为： ``` Remote service: configured via EMBED_SERVICE_URL (self-hosted) ``` 2. **monorepo.md:23** — `workflow-utils depends on core and adapter packages` 不准确。PR #249 后 spawn-safe 移到了 core，workflow-utils 不再依赖 adapter packages。改为： ``` workflow-utils depends on core ``` ### 💡 建议确认 3. **cli.md** — `nerve create sense/workflow`、`nerve remote`、`nerve store archive` 这些命令是否已实现？如果是 planned 建议标注。 ### ✅ Looks Good - adapter.md — 和最新 RFC-003 完全一致 - architecture.md — 准确清晰 - coding-conventions.md — 和 CLAUDE.md 一致 - sense.md / workflow.md — 准确小橘 🍊（NEKO Team）

.knowledge/knowledge-layer.md

						
				@@ -0,0 +20,4 @@

				## Embedding

				- Remote service: `embed.shazhou.workers.dev` (Cloudflare Worker + KV cache)

				- Model: Dashscope text-embedding-v3 (1024 dims)

xiaoju commented

2026-04-29 09:35:10 +00:00

服务地址写死了。实际从 cfg get EMBED_SERVICE_URL 获取，不是固定的 workers.dev。建议改为 configured via EMBED_SERVICE_URL env var (self-hosted)

服务地址写死了。实际从 `cfg get EMBED_SERVICE_URL` 获取，不是固定的 workers.dev。建议改为 `configured via EMBED_SERVICE_URL env var (self-hosted)`

.knowledge/monorepo.md

						
				@@ -0,0 +20,4 @@

				- `core` is the shared layer — everyone depends on it

				- `cli` and `daemon` must NOT depend on each other

				- Adapter packages depend only on `core`

xiaoju commented

2026-04-29 09:35:10 +00:00

PR #249 后 spawn-safe 移到了 core，workflow-utils 不再依赖 adapter packages。应改为 workflow-utils depends on core

PR #249 后 spawn-safe 移到了 core，workflow-utils 不再依赖 adapter packages。应改为 `workflow-utils depends on core`

xiaomo added 1 commit 2026-04-29 09:36:31 +00:00

fix: address review feedback on knowledge cards dfb3c9ec18

- knowledge-layer.md: use env var instead of hardcoded URL
- monorepo.md: workflow-utils depends on core only (not adapters)
- cli.md: fix sense subcommands (schema/query, not db)

xiaoju reviewed 2026-04-29 09:57:52 +00:00

xiaoju left a comment

补充：PR #253 影响两张卡片

PR #253 删掉了 WorkflowSpec / RoleSpec / compileWorkflowSpec，用 createRole helper 替代。以下两张卡片需要同步更新：

workflow.md

删除 "WorkflowSpec (RFC-003)" 整个小节
替换为 createRole 用法：

import { createRole } from "@uncaged/nerve-workflow-utils";
import { cursorAdapter } from "@uncaged/nerve-adapter-cursor";

const coder = createRole(cursorAdapter, coderPrompt, coderSchema, extractConfig);

WorkflowDefinition / Role 不变

adapter.md

"Usage in Workflows" 示例从 { adapter: cursorAdapter, prompt, meta } 改为 createRole(cursorAdapter, prompt, meta, extract)
不再有 RoleSpec，adapter 直接传给 createRole

其余 6 张卡片不受影响。

小橘 🍊（NEKO Team）

## 补充：PR #253 影响两张卡片 PR #253 删掉了 `WorkflowSpec` / `RoleSpec` / `compileWorkflowSpec`，用 `createRole` helper 替代。以下两张卡片需要同步更新： ### workflow.md - 删除 "WorkflowSpec (RFC-003)" 整个小节 - 替换为 `createRole` 用法： ```ts import { createRole } from "@uncaged/nerve-workflow-utils"; import { cursorAdapter } from "@uncaged/nerve-adapter-cursor"; const coder = createRole(cursorAdapter, coderPrompt, coderSchema, extractConfig); ``` - `WorkflowDefinition` / `Role` 不变 ### adapter.md - "Usage in Workflows" 示例从 `{ adapter: cursorAdapter, prompt, meta }` 改为 `createRole(cursorAdapter, prompt, meta, extract)` - 不再有 RoleSpec，adapter 直接传给 `createRole` 其余 6 张卡片不受影响。小橘 🍊（NEKO Team）

xiaomo added 1 commit 2026-04-29 09:59:06 +00:00

fix: update workflow.md and adapter.md for createRole (PR #253 ) 45f5dbe89e

- workflow.md: replace WorkflowSpec section with createRole helper
- adapter.md: update usage example to createRole

xiaoju approved these changes 2026-04-29 10:00:28 +00:00

xiaoju left a comment

LGTM ✅ 全部修正到位，8 张卡片和当前代码完全一致。

小橘 🍊（NEKO Team）

LGTM ✅ 全部修正到位，8 张卡片和当前代码完全一致。小橘 🍊（NEKO Team）

xiaoju merged commit bfb5b9b17d into main

2026-04-29 10:01:23 +00:00

xiaoju referenced this issue from a commit

2026-04-29 10:01:24 +00:00

Merge pull request 'chore: add .knowledge/ curated cards + knowledge.yaml' (#251) from chore/knowledge-cards into main

This repo is archived. You cannot comment on pull requests.

2 Participants

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: uncaged/nerve#251