OpenFDE 是一个专为 AI 现场工程师 (FDE) 设计的本地优先工作空间。它将客户访谈、聊天记录、文档等素材，转化为一个基于本体论 (Ontology) 的可操作记忆系统，并通过任务看板与 AI 编程代理（如 Claude Code）形成闭环，从而加速 AI 解决方案的交付。本教程将指导你在本地完成 OpenFDE 的部署与基本使用。

核心概念与工作流程

理解 OpenFDE 的设计哲学是有效使用它的基础：

  • 本地优先 (Local-First)：所有客户数据以 SQLite 数据库和 Markdown 文件的形式，存储在 ~/.openfde/engagements/<客户代号>/ 目录下，数据完全在你自己的机器上，不会上传到任何外部服务。交接客户项目，本质上就是移交这个目录。
  • 强制溯源 (Enforced Provenance)：系统中的每一条事实信息都必须附带来源 URI（统一资源标识符），否则无法写入。在召回信息时，每条事实都会附带其原始引用，确保可追溯。
  • 双时态记忆 (Bi-temporal Memory)：当新的事实与旧事实冲突时，旧事实不会被删除，而是被标记为“被取代”。recall --mode handoff 命令可以回放完整的时间线，包括你之前相信什么以及被什么取代了。
  • 混合检索与排序 (Hybrid Retrieval)：召回记忆时，融合了 BM25 关键词检索和实体图谱检索等多种方法，并应用衰减和取代惩罚，确保最相关、最新的信息优先呈现。
  • 代理原生 (Agent-Native)：所有 CLI 命令都支持 --json 输出，方便 AI 代理解析和调用。通过安装提供的技能 (Skill)，AI 代理可以自主查询记忆、认领任务、执行并回写结果。

核心工作流：访谈 → 注入 (ingest) → 提取 (extract) → 召回 (recall) → 任务 (task) → 代理执行 → 回写与评估 (eval)。

第一步：环境准备与安装

OpenFDE 基于 Node.js，使用 pnpm 作为包管理器。

前提条件：

  • 安装 Node.js (版本 >= 18) 和 pnpm。可通过 node --version 和 pnpm --version 检查。如果未安装 pnpm，可通过 npm install -g pnpm 安装。

安装步骤：

  1. 克隆项目仓库：

    1
    2
    git clone https://github.com/memovai/openfde.git
    cd openfde

  2. 安装依赖：
    在项目根目录下运行：

    1
    pnpm install

    这会安装所有必要的依赖包。

  3. 构建 CLI 工具：

    1
    pnpm -C apps/cli build

    此命令会构建 OpenFDE 的核心命令行工具 openfde。

  4. (可选) 全局链接命令：
    为了在终端任意位置都能使用 openfde 命令，可以将它全局链接：

    1
    2
    # 在项目根目录下执行
    pnpm link --global

    或者，你也可以在 apps/cli 目录下使用 pnpm openfde 来运行命令。

第二步：初始化并开始一个客户项目

  1. 创建客户项目 (Engagement)：

    1
    openfde engagement create "acme corp"

    将 acme corp 替换为你的客户名称。此命令会在 ~/.openfde/engagements/acme-corp/ 创建项目目录并初始化数据库。

  2. 切换到该项目：

    1
    openfde engagement use acme-corp

    后续所有命令都将在这个客户上下文中执行。

第三步：注入知识与提取记忆

这是将非结构化信息（会议记录、文档等）转化为结构化记忆的核心步骤。

  1. 注入 (Ingest) 素材：
    将你的访谈记录、会议笔记、PDF 文档或图片放入 ./notes/ 目录（或任意目录），然后注入到系统中。

    1
    2
    3
    4
    5
    6
    7
    8
    # 注入一个 Markdown 文件，并指明这是某人的发言
    openfde ingest ./notes/interview.md --kind message --speaker "Wang"

    # 注入一个 PDF 文件
    openfde ingest ./docs/requirements.pdf

    # 注入一个图片 (需 OCR 或 Claude 原生视觉能力)
    openfde ingest ./diagrams/architecture.png

    关键：内容必须附带来源，--source 参数可以指定来源 URI。如果不指定，ingest 命令会要求你提供。

  2. 提取 (Extract) 结构化事实：
    注入完成后，运行提取命令，系统会根据定义好的领域本体 (Ontology)（包括目标、工作流、决策、约束、数据源、痛点等），从注入的素材中提取出结构化的事实，并存放到记忆库中。

    1
    2
    3
    4
    5
    6
    # 需要设置 ANTHROPIC_API_KEY 环境变量，因为提取过程使用了 Claude 模型
    export ANTHROPIC_API_KEY="你的API密钥"
    openfde extract

    # 如果只想测试流程，可以使用模拟数据 (离线模式)
    openfde extract --mock

第四步：查询记忆与创建任务

  1. 查询 (Recall) 记忆：
    使用自然语言查询已提取的结构化信息。

    1
    2
    3
    4
    5
    6
    7
    8
    # 基础查询
    openfde recall "数据源"

    # 以交接模式查看完整时间线 (包含被取代的事实)
    openfde recall "数据源" --mode handoff

    # 输出 JSON 格式，方便代理读取
    openfde recall "数据源" --json

  2. 创建任务 (Task)：
    基于记忆中的痛点或机会，创建一个任务卡片。

    1
    2
    3
    openfde task create "自动化CSV文件清理流程" \
      --criteria "能够无人值守运行" \
      --source "interview://onsite#pain-csv"

    任务创建后，会有一个状态机（如 backlog → claimed → started → done → accepted）来追踪其生命周期。

  3. 为代理准备上下文 (Context)：
    当 AI 代理准备开始工作时，可以拉取该任务所需的所有上下文信息。

    1
    openfde context <任务ID>

    这会生成一个“弹药包”，包含该任务相关的约束、决策、数据源等信息，所有信息都附有引用。

第五步：与 AI 代理集成 (Agent Integration)

OpenFDE 为 AI 代理（如 Claude Code）提供了一个技能包，使其能通过 CLI 与系统交互。

  1. 安装技能到你的代理：

    1
    2
    3
    4
    5
    # 以 Claude Code 为例，安装到用户级技能目录
    cp -r skills/openfde ~/.claude/skills/openfde

    # 或者安装到项目级目录
    # cp -r skills/openfde .claude/skills/openfde

  2. 代理工作循环：
    安装后，你可以在对话中指示代理（例如使用 @openfde 调用技能）执行以下操作：

    • 查找任务：使用 openfde task list 查找 ready 状态的任务。
    • 认领任务：使用 openfde task claim <ID>。
    • 获取上下文：使用 openfde context <ID> 获取所有必要背景。
    • 执行工作：代理根据上下文和任务标准，在客户代码库中工作。
    • 回写发现：在工作过程中发现的新知识，使用 openfde remember "新事实" --source "task://<ID>" 写回记忆库。
    • 提交任务：完成后，使用 openfde task done <ID> 标记任务完成，并可由人类审查和接受 (openfde task accept <ID>)。

第六步：启动 Web 工作空间与共享报告

OpenFDE 提供了一个本地的 Web 界面，方便人类查看和管理整个项目。

  1. 启动本地 Web 服务：

    1
    openfde serve

    服务默认启动在 http://localhost:4517。界面包含四个主要标签页：

    • Note (笔记)：以 Obsidian 风格查看所有实体、事件和任务，支持 [[wiki-links]] 和内联引用。
    • Ontology (本体)：可视化显示实体之间的关系图。
    • Todo (待办)：任务看板，支持拖拽卡片来改变任务状态。
    • Canvas (画布)：自由形式的卡片空间，用于承载结构化的前期思考。

  2. 生成并共享实时报告：
    为向客户领导展示进展，可以生成一份动态报告。

    1
    2
    3
    4
    5
    # 在终端生成 Markdown 格式报告
    openfde report

    # 通过 Web 服务生成并共享一个只读的实时报告链接 (LAN)
    openfde share

    openfde share 会生成一个局域网内的只读链接，客户可以通过该链接实时查看项目进度、价值分析等关键信息，且所有数据均带引用。

故障排查与注意事项

  • ANTHROPIC_API_KEY 未设置：运行 extract 命令需要 Anthropic API Key。请确保在执行提取前已正确设置环境变量。如仅想体验流程，可使用 --mock 参数。
  • openfde 命令未找到：可能未全局链接。你可以使用 pnpm openfde (在项目根目录) 或 node apps/cli/dist/index.js 来运行。
  • 数据隐私：所有数据仅存储在本地 ~/.openfde/ 目录下。请确保此目录未同步至任何云服务。openfde share 命令虽然会生成一个 HTTP 链接，但仅在你的局域网内可访问，并且是只读的。
  • 任务状态流转：任务状态机有严格的流转规则（如 claimed 才能 started）。非法拖拽或命令操作会被拒绝，并给出提示。建议通过 Web UI 的 Todo 看板直观管理。

总而言之，OpenFDE 是一个为现代 AI 现场工程师设计的、高度结构化的知识工作系统。它通过“强制溯源”和“本体论约束”将模糊的客户沟通转化为可操作的、可追溯的集体记忆，并通过任务系统与 AI 代理形成高效的自动化闭环。它的部署和使用有一定门槛，建议从创建第一个客户项目和注入一份访谈记录开始，逐步体验其强大功能。