uncaged/nerve
Archived
10
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: knowledge-extraction workflow — BFS 三角色知识卡片生成 #266

New Issue
Closed
opened 2026-04-30 02:14:14 +00:00 by xiaoju · 1 comment
xiaoju commented 2026-04-30 02:14:14 +00:00
Owner
Copy Link
Copy Source

What

实现一个 nerve workflow，用 BFS 遍历 .knowledge/ 目录下的卡片，自动发现知识盲区并补全。

Why

.knowledge/ 卡片是 AI agent 的 context 注入源，但手动维护容易遗漏。需要一个自动化的知识探测闭环，确保卡片覆盖系统所有关键概念。

Design

三个 Role

Role 职责 约束
questioner 读一张卡片，提 3 个卡片未覆盖的技术问题 不看代码，只看卡片本身
answerer 用 nerve knowledge query 搜索答案 禁止看代码，只用知识库搜索
explorer 对未回答的问题读代码找答案，写新卡片或补丁已有卡片 写完后 nerve knowledge sync

BFS 流程

消息历史本身就是 BFS 队列的物化：

Queue: [seed_card.md]

while queue not empty:
    card = dequeue()
    
    → questioner(card) → 3 questions
    → answerer(questions) → found / not found
    → explorer(not_found) → patch existing cards / create new cards → enqueue new cards

Moderator 逻辑（伪码）

if steps.length === 0:
    return "questioner"       # 首轮提问

last = steps[-1]

if last.role === "questioner":
    return "answerer"         # 提问后回答

if last.role === "answerer":
    if last.meta.has_unanswered:
        return "explorer"     # 有未回答问题，探索
    else:
        if queue_empty(steps):
            return END        # 所有卡片处理完
        return "questioner"   # 下一张卡片

if last.role === "explorer":
    if queue_empty(steps):
        return END            # 所有卡片处理完
    return "questioner"       # 继续下一张卡片

BFS 状态

不需要外部状态文件。消息历史就是状态：

  • questioner 的 meta 记录当前处理的 card 路径
  • explorer 的 meta 记录新增的卡片路径（enqueue）
  • Moderator 遍历 steps 即可算出 visited set 和 queue

Meta Schemas

// questioner
type QuestionerMeta = {
  card: string;  // 当前处理的卡片路径
  questions: Array<{
    id: string;
    question: string;
    domain: string;  // 期望答案所在的概念域
  }>;
};

// answerer
type AnswererMeta = {
  results: Array<{
    id: string;
    found: boolean;
    source: string | null;
    note: string;
  }>;
  has_unanswered: boolean;
};

// explorer
type ExplorerMeta = {
  patches: Array<{ card: string; section: string }>;
  new_cards: string[];  // 新增卡片路径，构成 BFS 入队
};

Adapter 选择

三个角色都用 LLM adapter（createLlmRole 或 createRole + LLM AgentFn）：

  • questioner: 纯推理，给卡片内容让 LLM 提问
  • answerer: 需要调用 nerve knowledge query CLI — 可能需要一个能执行命令的 adapter，或者在 role 内部用 spawn 调用 CLI 后把结果喂给 LLM 判断
  • explorer: 需要读代码 + 写文件 — 用 hermes adapter 或 cursor adapter

终止条件

  1. BFS queue 为空（所有卡片都 visited）
  2. 连续 2 轮 explorer 没产出新卡片（知识已收敛）
  3. maxRounds 兜底（默认 30）

nerve.yaml 配置

workflows:
  knowledge-extraction:
    concurrency: 1
    overflow: drop

CLI 触发

nerve workflow trigger knowledge-extraction \
  --prompt ".knowledge/architecture.md" \
  --max-rounds 30

prompt 参数传种子卡片路径。

Open Questions

  1. answerer 需要执行 nerve knowledge query 命令 — 是让 adapter 内部 spawn，还是做一个专门的 "CLI adapter"？
  2. explorer 写文件后需要 nerve knowledge sync — 这个 side effect 放在 role 里还是 moderator 触发？
  3. 要不要支持 --dry-run 模式（只提问 + 搜索，不写卡片）？

Ref

Knowledge layer design: .knowledge/knowledge-layer.md
Workflow engine: .knowledge/workflow.md

## What 实现一个 nerve workflow，用 BFS 遍历 `.knowledge/` 目录下的卡片，自动发现知识盲区并补全。 ## Why `.knowledge/` 卡片是 AI agent 的 context 注入源，但手动维护容易遗漏。需要一个自动化的知识探测闭环，确保卡片覆盖系统所有关键概念。 ## Design ### 三个 Role | Role | 职责 | 约束 | |------|------|------| | **questioner** | 读一张卡片，提 3 个卡片未覆盖的技术问题 | 不看代码，只看卡片本身 | | **answerer** | 用 `nerve knowledge query` 搜索答案 | **禁止看代码**，只用知识库搜索 | | **explorer** | 对未回答的问题读代码找答案，写新卡片或补丁已有卡片 | 写完后 `nerve knowledge sync` | ### BFS 流程 消息历史本身就是 BFS 队列的物化： ``` Queue: [seed_card.md] while queue not empty: card = dequeue() → questioner(card) → 3 questions → answerer(questions) → found / not found → explorer(not_found) → patch existing cards / create new cards → enqueue new cards ``` ### Moderator 逻辑（伪码） ``` if steps.length === 0: return "questioner" # 首轮提问 last = steps[-1] if last.role === "questioner": return "answerer" # 提问后回答 if last.role === "answerer": if last.meta.has_unanswered: return "explorer" # 有未回答问题，探索 else: if queue_empty(steps): return END # 所有卡片处理完 return "questioner" # 下一张卡片 if last.role === "explorer": if queue_empty(steps): return END # 所有卡片处理完 return "questioner" # 继续下一张卡片 ``` ### BFS 状态 不需要外部状态文件。**消息历史就是状态**： - `questioner` 的 meta 记录当前处理的 card 路径 - `explorer` 的 meta 记录新增的卡片路径（enqueue） - Moderator 遍历 steps 即可算出 visited set 和 queue ### Meta Schemas ```ts // questioner type QuestionerMeta = { card: string; // 当前处理的卡片路径 questions: Array<{ id: string; question: string; domain: string; // 期望答案所在的概念域 }>; }; // answerer type AnswererMeta = { results: Array<{ id: string; found: boolean; source: string | null; note: string; }>; has_unanswered: boolean; }; // explorer type ExplorerMeta = { patches: Array<{ card: string; section: string }>; new_cards: string[]; // 新增卡片路径，构成 BFS 入队 }; ``` ### Adapter 选择 三个角色都用 **LLM adapter**（`createLlmRole` 或 `createRole` + LLM AgentFn）： - questioner: 纯推理，给卡片内容让 LLM 提问 - answerer: 需要调用 `nerve knowledge query` CLI — 可能需要一个能执行命令的 adapter，或者在 role 内部用 spawn 调用 CLI 后把结果喂给 LLM 判断 - explorer: 需要读代码 + 写文件 — 用 hermes adapter 或 cursor adapter ### 终止条件 1. BFS queue 为空（所有卡片都 visited） 2. 连续 2 轮 explorer 没产出新卡片（知识已收敛） 3. maxRounds 兜底（默认 30） ### nerve.yaml 配置 ```yaml workflows: knowledge-extraction: concurrency: 1 overflow: drop ``` ### CLI 触发 ```bash nerve workflow trigger knowledge-extraction \ --prompt ".knowledge/architecture.md" \ --max-rounds 30 ``` prompt 参数传种子卡片路径。 ## Open Questions 1. answerer 需要执行 `nerve knowledge query` 命令 — 是让 adapter 内部 spawn，还是做一个专门的 "CLI adapter"？ 2. explorer 写文件后需要 `nerve knowledge sync` — 这个 side effect 放在 role 里还是 moderator 触发？ 3. 要不要支持 `--dry-run` 模式（只提问 + 搜索，不写卡片）？ ## Ref Knowledge layer design: `.knowledge/knowledge-layer.md` Workflow engine: `.knowledge/workflow.md`
xiaoju commented 2026-05-02 03:15:26 +00:00
Author
Owner
Copy Link
Copy Source

Workflow 已实现在 workspace（~/.uncaged-nerve/workflows/extract-knowledge/），并已实际运行生成/更新了 11 张 .knowledge 卡片（commit 9c832b0）。

— 小橘 🍊（NEKO Team）

Workflow 已实现在 workspace（`~/.uncaged-nerve/workflows/extract-knowledge/`），并已实际运行生成/更新了 11 张 .knowledge 卡片（commit 9c832b0）。 — 小橘 🍊（NEKO Team）
This repo is archived. You cannot comment on issues.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
aobing jiashuang (Jia Shuang) jiayi (Jiayi) luming scottwei tuanzi xiaoju xiaomo xiaonuo xingyue
No Assignees
1 Participants
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: uncaged/nerve#266
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?