Applied AI Field Guide 部署与使用教程

The Applied AI Field Guide 是一个开源的设计与验证工具包，专为那些致力于将 AI 应用于实际工作场景的人士（如 AI 工程师、产品负责人、服务运营者、现场工程师）打造。它提供了一套系统化的方法论、模板和可运行的教学示例，帮助确保 AI 解决方案不仅仅停留在演示层面，而是能真正融入业务流程并产生可衡量的价值。本教程将指导你如何获取、安装并开始使用这套工具包。

核心概念与结构

在开始操作前，理解其结构有助于你按需取用。

  • 三层设计：
    1. The Guide (指南)：提供核心思维模型和标准交付流程，适合快速建立认知。
    2. Handbook (手册)：包含生命周期各阶段的详细操作手册，用于指导实际客户项目的执行。
    3. Engineering Kit (工程套件)：提供合同模板、控制项、架构蓝图、评估与运维的实践指引，以及可执行的证据模板。
  • 核心流程：项目遵循一个从“继承简报”到“运营/学习/退役”的标准化生命周期，每个阶段都需要通过证据和明确的决策来推进。
  • 教学示例：项目中包含 examples/ 目录，提供了如“发票处理”、“货运风险评估”等教学系统，用于演示方法论的应用。

第一步：环境准备与安装

该项目主要基于 Node.js，但它的核心产出是文档、方法论和示例代码。

  1. 前提条件：

    • 安装 Node.js (推荐最新 LTS 版本) 和 npm (Node.js 自带)。
    • 一个代码编辑器 (如 VS Code) 用于查看和编辑文件。

  2. 克隆与安装依赖：

    1
    2
    3
    4
    5
    6
    # 1. 克隆项目仓库
    git clone https://github.com/davidahmann/applied-ai-field-guide.git
    cd applied-ai-field-guide

    # 2. 安装项目依赖 (主要用于运行教学示例和验证工具)
    npm ci --ignore-scripts

    npm ci 命令会根据 package-lock.json 安装确切版本的依赖包，确保环境一致性。

第二步：探索与运行教学示例 (可选但强烈推荐)

项目包含一些可运行的教学示例，通过实际操作可以最快地理解其方法论。

  1. 运行参考测试和评估：
    在项目根目录下，运行以下命令来执行内置的教学案例。

    1
    2
    3
    4
    5
    6
    7
    8
    # 运行参考测试 (验证核心逻辑)
    npm run test:reference

    # 运行评估测试 (验证评估体系)
    npm run test:evals

    # 运行混合模式测试
    npm run test:hybrid

    这些命令会运行 examples/ 目录下的模拟系统（如发票异常处理、货运风险分析）。终端输出会显示测试结果，帮助你理解如何验证一个 AI 辅助工作流的正确性。

    重要提示：这些测试仅在内存中运行，用于教学。通过测试仅证明声明的本地行为正确，并不代表能为客户创造价值，也不意味着已达到生产就绪状态。

  2. 查看示例工件 (Artifacts)：
    浏览 examples/ 目录下的子文件夹，查看如 invoice-exception (发票异常) 等案例。阅读其中的 README.md 文件和代码，观察其如何应用“简报-观察-重构-价值-构建-验证-交接”的流程。

第三步：使用验证工具 (Artifact Validation)

项目提供了一个命令行工具，用于验证你创建的工作流定义文件是否符合其规范。

1
2
3
4
5
# 验证一个初创阶段的工作流包 (starter profile)
npm run validate:artifact -- ./path/to/your/workflow-start.json --profile starter --type workflow-charter

# 验证一个完整的工作流包 (complete profile)
npm run validate:artifact -- ./path/to/your/workflow-charter.json --profile complete
  • --profile starter 检查当前阶段决策所需的关键字段，而 complete 则检查完整定义。
  • 此工具可以帮助你确保项目文档的格式和关键信息点符合方法论的规范。你可以在 templates/ 目录下找到工件模板。

第四步：(可选) 与 AI 编程代理集成

该项目提供可选的技能包，方便 AI 编程代理 (如 Claude Code) 调用其方法论。

  1. 安装技能：

    1
    npx skills add davidahmann/applied-ai-field-guide

  2. 使用方式：安装后，在与 AI 代理的对话中，你可以用自然语言描述你的处境，代理会加载相应的技能来引导你。

    • 例如，当你说 “Keep this engagement coherent and tell me the next defensible move.” 时，代理可能会调用 $run-ai-engagement 技能。
    • 具体技能和路由逻辑可以查看项目中的 AGENTS.md 文件和 .agents/skills/ 目录。

第五步：下一步：应用指南到实际项目

完成上述探索后，你可以开始将方法论应用于实际工作。

  1. 从“五个核心问题”入手：参考 README.md 中的表格，根据你当前遇到的困境（如“简报与实际工作流不符”、“无法识别真正的流程负责人”），找到对应的起始点和期望产出。
  2. 研读核心指南：深入阅读 guide/ 目录下的核心指南文档，理解“12 Factors of AI Value Engineering”等关键概念。
  3. 使用模板和检查清单：在 templates/ 和 controls/ 目录下，你可以找到各种工作模板（如工作流章程、评估计划）和检查清单，用于规范化你的项目文档和决策。

故障排查与常见问题

  • npm ci 命令失败：检查网络连接，或尝试删除 node_modules 目录和 package-lock.json 文件后，改用 npm install。
  • 运行测试时出现错误：确保 Node.js 版本符合要求。部分测试可能依赖特定的文件路径，请确保在项目根目录下运行命令。
  • 验证工具报错：仔细检查你的 JSON 工件文件格式，确保其结构与 schemas/ 目录下的 JSON Schema 定义一致。starter profile 只要求最核心的字段，请确认你至少提供了这些字段。

总的来说，The Applied AI Field Guide 不是一个需要复杂部署的应用程序，而是一套可直接应用于工作的方法论、模板和工具集合。它的核心价值在于提供了一套严谨的工程化思路，帮助团队系统地论证、构建和运营 AI 解决方案，避免常见的“演示很酷，落地困难”陷阱。建议你从运行教学示例和阅读核心指南开始，逐步将其融入到你的日常项目中。