Knowledge 工坊:构建 Wiki 与 CodeGraph

Knowledge 工坊:构建 Wiki 与 CodeGraph

本节摘要:前三节的资产大多是「对话产生」的(Chat Memory、Skill),本节看另一类资产——知识资产(Wiki、CodeGraph)如何在工坊里被「构建」出来。Knowledge 工坊是控制台里发起 Wiki 与 CodeGraph 构建的入口,你把文档或代码库喂进去,知识引擎在后台异步处理,生成结构化的知识地图。本节讲清工坊的操作流程、为什么是异步构建、如何判断 ready,以及它与第 7 章知识引擎的分工。

一、Knowledge 工坊:构建知识资产的入口

工坊里你能做两件事:构建 Wiki(从文档)、构建 CodeGraph(从代码库)。两者都是「喂源材料 → 引擎处理 → 产出知识资产」:

工坊的两条构建线
  Wiki 构建:
    喂文档(产品文档/设计/运维手册)
      → Wiki 引擎 ingest
      → 产出:结构化页面 + 链接图谱
    
  CodeGraph 构建:
    喂代码库(HTTPS 仓库)
      → CodeGraph 引擎 index
      → 产出:符号/文件/调用关系/影响路径
​

关键概念:工坊是「人发起构建」的入口,但实际处理在知识引擎(第 7 章)。工坊负责「提交源材料、查看状态、管理产物」,知识引擎负责「ingest/index」。理解这个分工,你就知道为什么「点了构建不会立刻有结果」——工坊只是发起,引擎在后台慢慢跑。

二、为什么是异步构建:量大、需 LLM 处理

Wiki 与 CodeGraph 不是「点了立刻好」,而是异步构建,需要等 ready。原因是它们处理量大、且要动用 LLM:

为什么异步
  Wiki:文档可能几十上百页,每页要 LLM 抽结构、建链接 → 耗时
  CodeGraph:代码库可能上万文件,要索引符号/调用关系 → 耗时
  
  → 若同步,用户在工坊点一下要等几十分钟 → 体验极差
  → 异步:点了立刻返回「构建中」,后台跑,好了标 ready
​

这就解释了第 1 章验收时提到的「发起构建后要等 ready,不是故障」。判断一个知识资产是否健康,看的是「能否发起构建」而非「是否立刻 ready」。

⚠️ 注意:CodeGraph 当前首先支持公开 HTTPS 仓库;私有仓库和 SSH 凭证接入仍在完善。如果你用私有仓库构建失败,大概率是这个限制,不是配置错。

三、构建流程与状态跟踪

一次完整构建的状态流转:

构建状态流转
  提交源材料
    → 状态:构建中(processing)
    → 后台:Wiki ingest / CodeGraph index
    → 状态:ready(构建完成,可被检索/配装)
    
  若失败:
    → 状态:failed(可重试)
​

在工坊里你能看到每条知识资产的处理状态,ready 后它就变成一条正常的 Memory Asset,可以配装给 Agent、可以被 /v3/tools/call 检索。

四、构建完成后:成为可调用的知识资产

知识资产 ready 后,它的用法与对话类资产不同——它不直接「注入上下文」,而是作为「工具」被 Agent 按需调用:

知识资产的用法(对比对话类资产)
  对话类(Chat Memory/Skill):
    → 召回后注入 system prompt(inject)
  
  知识类(Wiki/CodeGraph):
    → 作为工具暴露给 Agent(toolize)
    → Agent 用 /v3/tools/list 发现
    → 用 /v3/tools/call 读取所需页面/符号
    → 平时只是可用工具,用到才进上下文
​

这就是第 2 章那条命题——「知识不整库注入,而是按需调用」——的操作面。Wiki 和 CodeGraph 即使有几千个页面,也不会撑爆上下文,因为 Agent 只在需要时调取一小块。第 7 章会详解这个「按需调用」机制。

💡 技巧:构建 Wiki/CodeGraph 时,源材料要「干净」——文档结构清晰、代码有基本注释,构建质量会高很多。垃圾进、垃圾出在知识构建里特别明显:混乱的文档会产出混乱的 Wiki,LLM 抽不出好结构。投入整理源材料,是提升知识资产质量的最有效手段。

五、Auto-Sync:让知识「一直新鲜」

文档和代码会变,知识资产也要跟着更新。工坊支持 Auto-Sync——源仓库变化时,知识资产自动增量更新:

Auto-Sync 的效果
  源代码库 push 了新提交
    → 触发 CodeGraph 增量 index
    → 更新影响到的符号/调用关系
    → 知识资产保持「新鲜」
  
  → 不用人工每次重建,自动跟随源变化
​

Auto-Sync 的内部机制(FIFO 队列 + worker pool)是第 7 章的内容。从工坊视角,你只需知道「开了 Auto-Sync,知识会自动跟随源更新」,不必每次手动重建。

本节要点回顾

1. 工坊是入口:人发起构建,知识引擎在后台处理——分工明确。
2. 异步构建:量大需 LLM,同步会卡死;点了立刻返回「构建中」,好了标 ready。
3. 状态跟踪:构建中→ready(可用)/failed(重试),ready 后成为正常资产。
4. 用法不同:知识资产作为「工具」被按需调用(toolize),不直接 inject——这是「按需调用」命题的操作面。
5. Auto-Sync:源变化自动增量更新,知识保持新鲜,第 7 章详解机制。
6. 源材料要干净:垃圾进垃圾出,整理源材料是提升知识质量的最有效手段。

第 5 章到此完成——团队角色、资产管理、Loadout 装配、知识构建,控制台的核心操作都覆盖了。下一章进入硬核区——第 6 章 MemoryCore 抽取 Pipeline 源码精读。