项目简介

grainulation 是一个结构化技术决策研究生态系统，旨在将技术问题转化为带类型的、有证据等级支撑的声明（claims）。该项目并非传统的文档生成工具或 RFC/ADR 模板系统，而是一套完整的研究-质疑-编译工作流工具。

核心定位：帮助团队从"凭直觉做决策"转变为"基于可验证证据做决策"。

资料来源：README.md:1-10

核心概念

声明（Claims）

grainulation 的所有工作都围绕声明（claims）展开。每个声明具有以下属性：

"Everything in grainulation starts with a claim — a single typed statement with an evidence grade."

资料来源：site/index.html:1

编译器（Compiler）

编译器是 grainulation 的核心验证引擎：

• 确定性：基于 JavaScript 代码实现（非 LLM 调用），相同输入产生相同输出
• 冲突检测：识别并标记相互矛盾的声明
• 证据验证：检查证据等级是否满足要求
• 门控机制：在问题未解决前阻止输出

"The compiler is JavaScript code, not an LLM call. Same claims in, same result out, every time."

资料来源：site/index.html:1

工具生态概览

grainulation 由 8 个独立的 CLI 工具组成，每个工具专注于单一职责。

资料来源：README.md:36-44

工作流程

grainulation 采用 研究-质疑-编译 的三阶段工作流：

graph TD
    A["❓ 提出问题<br/>例：是否应将微服务迁移回模块化单体？"] --> B["1️⃣ 初始化 Sprint<br/>wheat init"]
    B --> C["claims.json 创建<br/>wheat.config.json 就绪"]
    C --> D["2️⃣ 研究与质疑"]
    D --> E["wheat research 收集证据"]
    E --> F["生成 typed claims<br/>r001 [factual|documented]"]
    F --> G["wheat challenge 压力测试"]
    G --> H["生成风险声明<br/>x001 [risk|documented]"]
    H --> I["3️⃣ 编译与交付"]
    I --> J["wheat brief 编译决策简报"]
    J --> K["冲突已解决<br/>output/brief.html 生成"]
    K --> L["✅ 决策简报包含完整 git 审计轨迹"]

各阶段说明

阶段 1：初始化

• 使用 wheat init 命令创建研究 Sprint
• 自动生成 claims.json（声明存储）和 wheat.config.json（配置）

阶段 2：研究与质疑

• /research 命令用于收集特定主题的证据
• /challenge 命令用于对已有声明进行对抗性测试
• 所有发现都转化为带类型和证据等级的声明

阶段 3：编译与交付

• /brief 命令触发编译器
• 编译器检测冲突、验证证据等级
• 输出结构化决策简报（HTML 格式）

"Research that compiles."

资料来源：site/index.html:1

技术特性

零依赖设计

grainulation 生态系统的核心原则之一是零 npm 依赖：

"Zero npm dependencies across all eight packages. No supply chain anxiety. No left-pad."

资料来源：site/index.html:1

四大设计原则

"Comfortable agreement is the enemy of good decisions. The system forces you to challenge, witness, and stress-test every claim."

资料来源：site/index.html:1

系统架构

graph TD
    subgraph "用户层"
        A["用户/团队"]
    end
    
    subgraph "工具层 (CLI)"
        B["wheat - 研究"]
        C["farmer - 权限"]
        D["mill - 导出"]
        E["barn - 共享库"]
        F["harvest - 分析"]
    end
    
    subgraph "编排层"
        G["orchard - 统一入口"]
    end
    
    subgraph "数据层"
        H["claims.json"]
        I["wheat.config.json"]
        J["sprints/ 目录"]
    end
    
    subgraph "编译器层"
        K["Compiler<br/>冲突检测<br/>证据验证<br/>门控机制"]
    end
    
    A --> G
    G --> B
    G --> C
    G --> D
    G --> E
    G --> F
    
    B --> H
    B --> I
    H --> K
    I --> K
    K --> L["output/brief.html"]
    
    style G fill:#9ca3af,color:#000
    style K fill:#fbbf24,color:#000
    style H fill:#6ee7b7,color:#000

安装与快速开始

环境要求

安装方式

# 全局安装
npm install -g @grainulation/grainulation

# 或直接使用 npx（无需安装）
npx @grainulation/wheat init

快速命令

grainulation              # 生态系统概览
grainulation doctor       # 健康检查：工具列表、版本
grainulation setup        # 为当前角色安装合适的工具
grainulation wheat init   # 委托给 wheat 工具
grainulation farmer start # 启动权限仪表盘

资料来源：README.md:21-29

与传统方法的区别

"RFCs and ADRs document a decision after it is made. Grainulation captures the research process — evidence gathering, adversarial testing, and conflict resolution."

资料来源：site/index.html:1

输出产物

执行 wheat brief 后的输出包含：

• 决策简报：结构化 HTML 文档
• 声明清单：所有收集的声明及其状态
• 冲突报告：未解决的矛盾说明
• 证据摘要：每条声明的来源和等级
• Git 审计轨迹：完整的数据收集和质疑历史

概述

Grainulation 是一个由八个独立 CLI 工具组成的生态系统，旨在将技术问题转化为带有类型和证据等级的声明（claims），最终生成可审计的决策简报。整个项目遵循零 npm 依赖原则，全部基于 Node.js 原生内置模块构建，所有工具均在本地运行，无需云服务或 API 密钥。

本安装指南涵盖完整的环境准备、各工具的安装方式以及不同使用场景下的推荐配置。

系统要求

资料来源：site/index.html

重要提示：核心工具（如 wheat）的编译器部分不需要 API 密钥。所有数据处理均在本地完成，不涉及任何云服务调用。

安装模式

Grainulation 提供两种主要安装模式，用户可根据实际需求选择。

模式一：全局安装（推荐长期使用）

全局安装适合需要频繁使用工具链的场景，一次安装后可在任意目录下直接调用：

npm install -g @grainulation/grainulation

安装完成后，可以通过统一的入口工具 grainulation 调用所有子命令：

grainulation              # 查看生态系统概览
grainulation doctor       # 健康检查：已安装工具列表及版本
grainulation setup        # 根据角色安装所需工具
grainulation wheat init   # 委托给 wheat 工具初始化研究 sprint
grainulation farmer start # 启动权限仪表板

资料来源：README.md

模式二：按需执行（零安装）

对于偶尔使用或临时探索的场景，可以直接使用 npx 跳过安装步骤，按需下载并执行：

npx @grainulation/wheat init   # 直接初始化研究 sprint
npx @grainulation/farmer start # 启动权限仪表板
npx @grainulation/mill export --format pdf  # 导出决策简报为 PDF
npx @grainulation/harvest analyze ./sprints/  # 分析历史 sprint 数据

这种模式的优势在于无需预先安装任何依赖，每次执行都会获取最新版本。

资料来源：site/index.html

工具生态概览

Grainulation 包含八个独立工具，每个工具专注于特定功能领域：

资料来源：README.md

快速开始工作流

对于新用户，建议按照以下三步流程完成首次研究 sprint：

graph TD
    A[初始化 Sprint<br/>npx @grainulation/wheat init] --> B[研究与质疑<br/>收集证据, 挑战声明]
    B --> C[编译与交付<br/>生成决策简报]
    C --> D[输出 brief.html<br/>可导出为 PDF/CSV]

步骤一：初始化 Sprint

npx @grainulation/wheat init

执行后将创建两个核心文件：

• claims.json — 存储所有声明的清单文件
• wheat.config.json — 工具配置文件

$ npx @grainulation/wheat init

Sprint initialized.
claims.json created (0 claims)
wheat.config.json ready

资料来源：site/index.html

步骤二：研究与质疑

在 wheat 交互式环境中使用以下命令：

wheat> /research "topic"     # 收集关于指定主题的研究证据
wheat> /challenge r001       # 质疑指定声明，触发对抗性测试

声明将以统一格式输出：

r001 [factual|documented] ...
x001 [risk|documented] ...

步骤三：编译与交付

wheat> /brief

编译器将执行以下验证：

1. 解析所有声明及关联证据
2. 检测声明间的矛盾冲突
3. 标记证据等级不足的声明
4. 阻止输出直至所有问题解决
5. 生成包含完整 git 审计轨迹的决策简报

Compiled 12 claims (2 conflicts resolved)
Written: output/brief.html

资料来源：site/index.html

环境健康检查

安装完成后，可使用以下命令验证工具链状态：

grainulation doctor

该命令将检测：

• 已安装的工具列表及版本号
• Node.js 版本兼容性
• 各工具间的依赖关系状态

权限仪表板安装

Farmer 是用于审批 AI 代理工具调用的实时仪表板，特别适合团队协作场景：

npx @grainulation/farmer start

启动后支持以下功能：

• 通过手机、另一浏览器标签页或会议期间审批请求
• 实时 SSE（Server-Sent Events）推送
• 零依赖设计，不引入额外包

资料来源：site/index.html

离线与私有部署

由于 Grainulation 整个生态系统的设计原则是零 npm 依赖（仅使用 Node.js 内置模块），部署到私有环境或离线场景非常直接：

1. 将整个仓库克隆至目标机器
2. 确保 Node.js 20+ 已安装
3. 通过 npx 或本地 node 直接运行各工具入口脚本

git clone https://github.com/grainulation/grainulation.git
cd grainulation
node wheat/bin/index.js init  # 直接执行，跳过 npm 查找

常见问题

Q：是否需要注册账户或获取 API 密钥？

不需要。核心工具（wheat、barn、mill 等）完全本地运行，不连接任何外部服务。唯一需要 API 密钥的是与 AI 代理（Claude Code）的交互，由用户自行管理。

Q：是否支持 Yarn、pnpm 等其他包管理器？

Grainulation 主包 @grainulation/grainulation 支持通过 npm 全局安装。对于子工具，推荐使用 npx 方式执行以确保版本一致性。

Q：可以安装单个工具而不安装整个生态吗？

可以。八个工具相互独立，按需安装即可：

npm install -g @grainulation/wheat
npm install -g @grainulation/mill
# 等等...

Q：安装后如何获取更新？

• 全局安装：npm update -g @grainulation/grainulation
• npx 方式：每次执行自动获取最新版本

相关资源

• 项目官网：https://grainulation.com
• 官方文档：各工具独立维护的文档站点
• GitHub 仓库：https://github.com/grainulation/grainulation
• npm 包页面：https://www.npmjs.com/package/@grainulation/grainulation

概述

快速开始是 Grainulation 生态系统的入口点，旨在帮助用户在 60 秒内启动一个技术决策研究冲刺（Sprint）。整个流程设计遵循"三条命令，一个决策"的原则，无需安装、无需注册、无需配置 API Key，只需 npx 和一个问题即可开始。

资料来源：site/index.html:1

前置要求

在开始使用 Grainulation 之前，请确保满足以下环境要求：

Grainulation 的核心理念是零依赖——所有八个包均不使用任何 npm 依赖项，完全基于 Node.js 内置模块构建，不存在供应链安全风险。

资料来源：README.md:1

安装方式

Grainulation 提供两种安装方式，用户可根据使用场景选择：

全局安装

适合经常使用 Grainulation 的用户：

npm install -g @grainulation/grainulation

全局安装后，可以直接使用 grainulation 命令：

grainulation              # 生态系统概览
grainulation doctor       # 健康检查：工具列表和版本
grainulation setup        # 安装适合角色的工具
grainulation farmer start # 启动权限仪表板

直接运行（推荐）

适合临时使用或首次体验的用户：

npx @grainulation/wheat init

这种方式无需安装任何内容，直接通过 npx 拉取并执行包。

资料来源：README.md:1

三步工作流程

Grainulation 的快速开始流程分为三个阶段：初始化、研究与挑战、编译发布。

步骤一：初始化冲刺

使用 wheat 工具初始化一个新的研究冲刺。系统会提示你输入问题、受众和约束条件：

npx @grainulation/wheat init

执行后将创建两个文件：

初始化输出示例：

Sprint initialized.
claims.json created (0 claims)
wheat.config.json ready

资料来源：site/index.html:1

步骤二：研究与挑战

在研究阶段，你需要收集证据并对每个发现进行压力测试。所有发现都会成为带有类型和等级的声明（Claims）。

wheat 命令行工具提供两个核心命令：

wheat> /research "topic"     # 收集关于某个主题的证据
wheat> /challenge r001       # 挑战已有的声明

声明具有以下属性：

挑战声明后，系统会生成新的风险声明（以 x 前缀标识）：

r001 [factual|documented] ...  # 原始声明
x001 [risk|documented] ...      # 由挑战产生的风险声明

资料来源：site/index.html:1

步骤三：编译并发布

当研究完成且冲突已解决后，使用编译命令生成决策简报：

wheat> /brief

编译器的工作流程：

graph TD
    A[输入 Claims] --> B{检查冲突}
    B -->|存在冲突| C[阻止输出]
    B -->|无冲突| D{检查证据强度}
    D -->|证据不足| E[标记弱证据]
    D -->|证据充分| F[生成决策简报]
    E --> C
    F --> G[output/brief.html]

编译器输出示例：

Compiled 12 claims (2 conflicts resolved)
Written: output/brief.html

决策简报具有完整的 Git 审计跟踪功能，记录每个声明的收集方式和挑战过程。

资料来源：site/index.html:1

工作流程图

整个 Grainulation 生态系统的工作流程如下：

graph LR
    A[问题] --> B[w:heat 初始化]
    B --> C[w:heat 研究]
    C --> D[w:heat 挑战]
    D --> E{编译器检查}
    E -->|通过| F[o:rchard 状态]
    E -->|失败| C
    F --> G[m:ill 导出]
    G --> H[决策简报]
    
    H --> I[h:arvest 分析]
    I --> J[跨冲刺学习]

生态工具概览

Grainulation 由八个独立的工具组成，每个工具负责特定功能：

资料来源：README.md:1

项目架构

Grainulation 作为元包和生态系统路由器，其架构如下：

bin/grainulation.js       # CLI 入口点 - 路由到各工具包
lib/router.js             # 命令路由，将请求分发到正确工具
lib/ecosystem.js          # 生态系统健康检查和工具发现
lib/doctor.js             # 诊断工具 - 验证工具安装状态
lib/setup.js              # 首次运行设置和配置
lib/pm.js                 # grainulation 工具的包管理
lib/server.mjs            # 本地服务器 - 统一生态系统仪表板
public/                   # Web UI - 生态系统概览和状态
site/                     # 公开网站
test/                     # Node 内置测试运行器

关键架构原则：所有工具均通过统一的 CLI 接口路由，用户只需记住 grainulation 一个入口点即可访问整个生态系统。

资料来源：CONTRIBUTING.md:1

常见问题

需要 Node.js 吗？

是的，Grainulation 是一个 Node.js 工具，需要 Node.js 20 或更高版本。它不使用任何外部依赖，仅使用 Node.js 内置模块。

与 RFC/ADR 有何不同？

RFC 和 ADR 在决策完成后记录决策。Grainulation 捕获研究过程——证据收集、对抗性测试和冲突解决——并通过编译器进行验证。输出的简报可作为 ADR 使用，具有完整的 Git 审计跟踪，显示每个声明是如何收集、挑战和解决的。

数据存储在哪里？

所有数据都存储在本地 JSON 文件中。没有云服务、没有账户、没有 API 密钥。决策简报是静态 HTML 文件，可部署到任何静态托管服务。

概述

Grainulation 是一个元包（meta-package）和生态系统路由器，它编排所有 Grainulation 工具并提供统一的 CLI 入口点。该项目的核心理念是零依赖——整个生态系统完全基于 Node.js 内置模块构建，不使用任何 npm 依赖项。

资料来源：CONTRIBUTING.md

架构设计原则

Grainulation 遵循以下核心架构原则：

资料来源：site/index.html

核心组件架构

组件层次结构

graph TD
    subgraph 入口层
        CLI[bin/grainulation.js<br/>CLI 入口点]
    end
    
    subgraph 核心库
        Router[lib/router.js<br/>命令路由]
        Ecosystem[lib/ecosystem.js<br/>生态系统健康检查]
        Doctor[lib/doctor.js<br/>诊断工具]
        Setup[lib/setup.js<br/>首次运行配置]
        PM[lib/pm.js<br/>包管理]
    end
    
    subgraph 服务层
        Server[lib/server.mjs<br/>本地服务器]
    end
    
    subgraph 前端层
        Public[public/<br/>Web UI]
        Site[site/<br/>公共网站]
    end
    
    CLI --> Router
    Router --> Ecosystem
    Router --> Doctor
    Router --> Setup
    Router --> PM
    Server --> Public
    Server --> Ecosystem

各组件职责

资料来源：CONTRIBUTING.md

命令路由机制

路由流程

sequenceDiagram
    participant User as 用户
    participant CLI as bin/grainulation.js
    participant Router as lib/router.js
    participant Tool as 目标工具包
    
    User->>CLI: node bin/grainulation.js [command]
    CLI->>Router: 解析命令参数
    Router->>Router: 识别工具类型
    Router->>Tool: 路由到对应工具
    Tool-->>User: 返回执行结果

工具生态系统

Grainulation 由八个独立工具组成，每个工具专注于特定功能：

资料来源：site/index.html

生态系统健康检查

lib/ecosystem.js 负责维护整个工具生态系统的健康状态：

健康检查流程

graph LR
    A[启动检查] --> B{工具已安装?}
    B -->|是| C[检查版本]
    C --> D{版本匹配?}
    D -->|是| E[工具可用]
    D -->|否| F[提示更新]
    B -->|否| G[安装工具]
    G --> E
    E --> H[生态系统就绪]

工具发现机制

生态系统通过以下方式发现和验证工具：

1. 本地注册表检查：扫描已安装的 @grainulation/* 包
2. 版本兼容性验证：确保工具版本与 grainulation 主包兼容
3. 依赖链验证：检查工具间的依赖关系是否满足

资料来源：CONTRIBUTING.md

本地服务器架构

lib/server.mjs 是使用 ESM 模块格式的本地服务器：

服务器特性

服务架构

graph TD
    subgraph 服务层
        Server[lib/server.mjs<br/>ESM 服务器]
    end
    
    subgraph 前端资源
        UI[public/<br/>静态资源]
        Dashboard[生态系统仪表板]
    end
    
    Server --> UI
    Server --> Dashboard
    Server --> SSE[SSE 实时更新]
    
    subgraph 数据流
        API[内部 API]
        Health[健康检查数据]
    end
    
    Server --> API
    API --> Health

资料来源：CONTRIBUTING.md

测试架构

测试框架

Grainulation 使用 Node.js 内置测试运行器：

测试执行

node test/basic.test.js

测试覆盖以下核心功能：

• CLI 命令解析
• 路由功能验证
• 生态系统健康检查

资料来源：CONTRIBUTING.md

发布工作流架构

发布流程

graph LR
    A[代码变更] --> B[版本升级]
    B --> C[npm version patch]
    C --> D[提交 + 标签]
    D --> E[git push --follow-tags]
    E --> F[触发 Actions]
    F --> G{测试通过?}
    G -->|是| H[验证 package.json]
    G -->|否| I[发布失败]
    H --> J[发布到 npm]
    J --> K[OIDC 信任发布]
    K --> L[生成 Provenance]

发布配置

协调发布流程

当消费者依赖新的内部功能时：

1. 首先发布依赖包（如 barn）
2. 等待 npm 发布完成（约 60 秒）
3. 在消费者仓库执行 npm install 更新 package-lock.json
4. 提交锁文件更新
5. 按顺序发布各消费者包

资料来源：RELEASE.md

数据流总览

graph TD
    subgraph 用户交互层
        CLI[CLI 命令行]
        WebUI[Web 界面]
    end
    
    subgraph 入口处理
        Entry[bin/grainulation.js]
    end
    
    subgraph 核心处理
        Router[路由层<br/>lib/router.js]
        Ecosystem[生态层<br/>lib/ecosystem.js]
        Doctor[诊断层<br/>lib/doctor.js]
        Setup[配置层<br/>lib/setup.js]
        PM[包管理层<br/>lib/pm.js]
    end
    
    subgraph 工具层
        Wheat[wheat]
        Farmer[farmer]
        Barn[barn]
        Mill[mill]
        Silo[silo]
        Harvest[harvest]
        Orchard[orchard]
    end
    
    subgraph 存储层
        LocalData[本地数据]
        CloudData[云存储]
    end
    
    CLI --> Entry
    WebUI --> Entry
    Entry --> Router
    Router --> Ecosystem
    Router --> Doctor
    Router --> Setup
    Router --> PM
    Ecosystem --> Wheat
    Ecosystem --> Farmer
    Ecosystem --> Barn
    Ecosystem --> Mill
    Ecosystem --> Silo
    Ecosystem --> Harvest
    Ecosystem --> Orchard
    Barn --> LocalData
    Silo --> CloudData

技术栈总结

资料来源：site/index.html

概述

grainulation 是 grainulation 工具生态系统的元包和统一入口点，负责协调所有 grainulation 工具并提供统一的 CLI 入口。CLI 架构遵循简单路由模式，将命令分发到各个独立工具包执行。资料来源：CONTRIBUTING.md

架构设计

grainulation CLI 采用模块化架构，核心组件协同工作以提供统一的命令行体验。

graph TD
    A[bin/grainulation.js<br>CLI入口点] --> B[lib/router.js<br>命令路由]
    A --> C[lib/ecosystem.js<br>生态系统健康检查]
    A --> D[lib/doctor.js<br>诊断工具]
    B --> E[@grainulation/wheat<br>研究工具]
    B --> F[@grainulation/farmer<br>权限仪表盘]
    B --> G[@grainulation/barn<br>共享工具]
    B --> H[其他工具包...]
    C --> I[npm registry<br>工具发现]
    D --> J[本地安装验证]
    F --> K[server.mjs<br>本地服务器]

核心文件职责

命令行接口

基本用法

npx grainulation [command] [options]

全局选项

帮助命令

grainulation --help

显示所有可用命令和选项的完整帮助信息。

子命令详解

1. doctor - 诊断命令

doctor 命令用于验证 grainulation 工具的本地安装状态，检查每个工具包的健康状况。

grainulation doctor [options]

功能说明

• 验证各工具包的安装完整性
• 检查 Node.js 版本兼容性
• 报告缺失或损坏的工具包
• 提供修复建议

可用选项

2. doctor 命令工作流程

graph TD
    A[grainulation doctor] --> B{检查Node.js版本}
    B -->|版本过低| C[警告: 需要Node.js 20+]
    B -->|版本符合| D[检查工具包目录]
    D --> E{扫描@scope/@grainulation/*}
    E -->|发现包| F[验证package.json]
    E -->|无包| G[提示安装工具]
    F --> H{package.json完整?}
    H -->|是| I[工具状态: 健康]
    H -->|否| J[工具状态: 损坏]
    I --> K[生成诊断报告]
    J --> K

3. pm - 包管理命令

pm 命令提供 grainulation 工具生态系统的包管理功能。

grainulation pm [subcommand] [options]

子命令

install 子命令选项

4. ecosystem - 生态系统命令

ecosystem 命令用于检查整个 grainulation 工具生态系统的健康状态和可用性。

grainulation ecosystem [options]

功能说明

• 检查所有工具包的最新版本
• 验证工具包在npm上的可用性
• 生成生态系统健康报告
• 检测过时工具包

输出示例

生态系统健康检查
✓ [email protected] - 最新
✓ [email protected] - 最新
⚠ [email protected] - 可用更新: 1.3.0
✓ [email protected] - 最新

5. setup - 初始设置命令

setup 命令处理 grainulation CLI 的首次运行配置。

grainulation setup [options]

功能说明

• 创建必要的配置文件
• 初始化本地工具缓存
• 配置默认工具路径
• 验证环境依赖

自动执行流程

graph LR
    A[首次运行grainulation] --> B{检测配置文件}
    B -->|不存在| C[运行setup]
    B -->|已存在| D[跳过setup]
    C --> E[创建配置目录]
    E --> F[生成grainulation.config.json]
    F --> G[验证Node.js环境]
    G --> H[完成初始化]

6. server - 本地服务器命令

server 命令启动统一的生态系统仪表盘Web界面。

grainulation server [options]

功能说明

• 启动本地HTTP服务器
• 提供Web UI界面查看所有工具状态
• 支持实时工具健康监控
• 提供SSE（Server-Sent Events）实时更新

服务器选项

使用示例

# 启动服务器
grainulation server

# 指定端口并自动打开浏览器
grainulation server --port 8080 --open

工具包路由机制

grainulation CLI 的核心功能是将命令路由到正确的工具包。路由机制通过 lib/router.js 实现。

graph TD
    A[用户输入命令] --> B[bin/grainulation.js]
    B --> C[解析命令类型]
    C --> D{是否为内置命令?}
    D -->|doctor| E[执行lib/doctor.js]
    D -->|pm| F[执行lib/pm.js]
    D -->|ecosystem| G[执行lib/ecosystem.js]
    D -->|setup| H[执行lib/setup.js]
    D -->|server| I[执行lib/server.mjs]
    D -->|其他| J[lib/router.js路由]
    J --> K[定位工具包]
    K --> L[执行工具包命令]
    L --> M[返回结果]

路由配置

路由系统支持以下工具包前缀：

环境要求

Node.js版本要求

grainulation CLI 要求 Node.js 20.0.0 或更高版本。

# 检查Node.js版本
node --version

# 要求版本
node >= 20.0.0

零依赖设计

grainulation 核心CLI包采用零npm依赖设计，完全基于Node.js内置模块构建。资料来源：package.json

内置依赖使用情况

配置文件

配置文件位置

grainulation 使用以下配置文件：

配置文件结构

{
  "version": "1.0.0",
  "tools": {
    "installed": ["wheat", "farmer", "barn"],
    "path": "~/.grainulation/tools"
  },
  "server": {
    "port": 3000,
    "host": "localhost"
  },
  "registry": "https://registry.npmjs.org/"
}

常见用法示例

完整工作流程

# 1. 首次使用：检查环境健康
grainulation doctor

# 2. 查看生态系统状态
grainulation ecosystem

# 3. 安装所需工具
grainulation pm install wheat
grainulation pm install farmer

# 4. 启动本地仪表盘
grainulation server --open

# 5. 在另一终端使用wheat进行研究
wheat init "我们的系统应该使用微服务吗?"

诊断和修复

# 诊断问题
grainulation doctor

# 自动修复
grainulation doctor --fix

# 查看JSON格式诊断结果
grainulation doctor --json

包管理操作

# 列出已安装的工具
grainulation pm list

# 搜索可用工具
grainulation pm search auth

# 安装特定版本
grainulation pm install [email protected]

# 更新所有工具
grainulation pm update

错误处理

常见错误及解决方案

调试模式

启用调试模式以获取详细日志：

DEBUG=grainulation:* grainulation <command>

与wheat工具的集成

grainulation CLI 与 @grainulation/wheat 工具深度集成，提供完整的研究决策流程支持。

graph LR
    A[grainulation wheat] --> B[wheat init<br>初始化研究项目]
    B --> C[wheat /research<br>收集证据]
    C --> D[wheat /challenge<br>挑战Claims]
    D --> E[wheat /brief<br>编译决策简报]
    E --> F[grainulation mill<br>导出报告]

资料来源：CONTRIBUTING.md

相关资源

• 官方文档
• wheat工具文档
• farmer工具文档
• GitHub仓库

核心设计理念

Grainulation 的核心理念源于一个观察：大多数决策失败不是因为团队缺乏数据，而是缺乏将数据转化为证据、将证据转化为决策的过程。系统围绕四个基本原则构建：

资料来源：README.md:1-15

八工具架构

整个生态系统包含八个独立工具，每个工具专注于一个特定功能。以下是完整工具矩阵：

资料来源：site/index.html:140-180

工具协作流程

graph TD
    subgraph 研究阶段
        A[wheat init] --> B[Research & Challenge]
        B --> C[创建声明]
        C --> D[收集证据]
    end
    
    subgraph 验证阶段
        D --> E[silo 验证]
        E --> F{验证通过?}
        F -->|否| G[修复问题]
        G --> D
    end
    
    subgraph 编译阶段
        F -->|是| H[barn 存储]
        H --> I[harvest 分析]
        I --> J[mill 导出]
    end
    
    subgraph 协作阶段
        J --> K[farmer 审批]
        K --> L[orchard 管理]
    end
    
    J --> M[决策简报]

工具之间的依赖关系遵循特定顺序：当需要发布新版本时（如 barn），需要先发布被依赖的包，等待其出现在 npm 上，然后更新消费者仓库的依赖。

资料来源：RELEASE.md:1-30

架构层次

Grainulation 采用分层架构设计：

graph TB
    subgraph 用户交互层
        A[统一 CLI: grainulation]
        B[wheat REPL]
        C[farmer Web 界面]
    end
    
    subgraph 核心库
        D[lib/router.js 路由]
        E[lib/ecosystem.js 生态系统]
        F[lib/doctor.js 诊断]
        G[lib/setup.js 配置]
        H[lib/pm.js 包管理]
    end
    
    subgraph 数据层
        I[claims.json]
        J[wheat.config.json]
        K[barn 存储]
    end
    
    A --> D
    B --> D
    C --> H
    D --> E
    D --> F
    D --> G
    E --> H
    H --> K
    F --> J
    G --> J

核心组件说明

资料来源：CONTRIBUTING.md:20-45

声明类型系统

Grainulation 的核心抽象是声明（Claim）——一个带有类型和证据等级的单个声明语句。声明具有以下属性：

系统通过编译器验证声明的一致性，检测矛盾，并标记弱证据。

资料来源：site/index.html:200-220

快速上手路径

graph LR
    A["npx @grainulation/wheat init"] --> B[初始化 Sprint]
    B --> C[Research & Challenge]
    C --> D[/brief 编译]
    D --> E[决策简报]
    
    A -.->|或者| F["npm install -g @grainulation/grainulation"]
    F --> G["grainulation setup"]
    G --> A

基础命令

# 生态系统概览
grainulation

# 健康检查
grainulation doctor

# 安装适合角色的工具
grainulation setup

# 初始化研究 Sprint
grainulation wheat init
# 或直接
npx @grainulation/wheat init

资料来源：README.md:30-50

发布与版本管理

生态系统采用协调发布机制，确保包之间的依赖关系正确：

sequenceDiagram
    participant Dev as 开发者
    participant Barn as barn 包
    participant Consumer as 消费者包
    participant NPM as npm registry
    
    Dev->>Barn: npm version patch
    Dev->>Barn: git push --follow-tags
    Barn->>NPM: 发布 v1.2.3
    NPM-->>Dev: 发布成功
    
    Dev->>Consumer: 修改依赖版本
    Consumer->>NPM: npm install
    NPM-->>Consumer: 获取新版本 barn
    Consumer->>Consumer: 更新 package-lock.json

每个包通过 .github/workflows/publish.yml 在标签推送时自动发布，使用 npm provenance 通过 OIDC 可信发布（无需 NPM_TOKEN）。

资料来源：RELEASE.md:10-25

技术约束

资料来源：site/index.html:225-235

相关文档

• wheat 工具文档 — 研究引擎
• farmer 工具文档 — 权限仪表板
• barn 工具文档 — 证据存储
• mill 工具文档 — 导出发布

概述

Grainulation 是一个元包（meta-package），通过统一的 CLI 入口点协调整个工具生态系统。它本身不提供核心研究功能，而是作为八个独立工具包的路由层和编排层存在。这种设计遵循单一职责原则，使每个工具（Wheat、Farmer、Barn、Mill、Silo、Harvest、Orchard）能够独立发布和演进，同时通过统一的入口点提供一致的用户体验。

工具集成架构的核心目标是实现零依赖生态——所有工具都基于 Node.js 内置模块构建，不依赖外部 npm 包。Grainulation 作为中央协调器，负责命令路由、健康检查、工具发现和包管理等职责，使各个工具能够无缝协作。

核心架构

Grainulation 的架构采用分层设计，从上到下依次为：CLI 入口层、路由层、生态系统层和工具层。这种分层确保了各组件之间的松耦合，便于独立扩展和维护。

graph TB
    subgraph "CLI 入口层"
        CLI["bin/grainulation.js<br/>统一命令行入口"]
    end
    
    subgraph "路由层"
        ROUTER["lib/router.js<br/>命令路由"]
    end
    
    subgraph "生态系统层"
        ECO["lib/ecosystem.js<br/>健康检查与工具发现"]
        DOCTOR["lib/doctor.js<br/>诊断工具"]
        PM["lib/pm.js<br/>包管理"]
        SETUP["lib/setup.js<br/>首次配置"]
    end
    
    subgraph "工具层"
        WHEAT["@grainulation/wheat<br/>核心研究引擎"]
        FARMER["@grainulation/farmer<br/>权限仪表板"]
        BARN["@grainulation/barn<br/>SSE 通信"]
        MILL["@grainulation/mill<br/>导出与发布"]
        SILO["@grainulation/silo<br/>统一 CLI"]
        HARVEST["@grainulation/harvest<br/>分析工具"]
        ORCHARD["@grainulation/orchard<br/>编排工具"]
    end
    
    CLI --> ROUTER
    ROUTER --> ECO
    ROUTER --> WHEAT
    ROUTER --> FARMER
    ROUTER --> BARN
    ROUTER --> MILL
    ROUTER --> SILO
    ROUTER --> HARVEST
    ROUTER --> ORCHARD
    ECO --> DOCTOR
    ECO --> PM
    ECO --> SETUP

资料来源：CONTRIBUTING.md

CLI 入口点

bin/grainulation.js

bin/grainulation.js 是整个生态系统的统一命令行入口点。它负责接收用户输入并将其路由到相应的工具包。该入口点支持 --help 参数来显示帮助信息，用户无需安装任何依赖即可通过 npx grainulation 直接运行。

入口脚本的设计理念是零安装依赖——用户只需拥有 Node.js 20+ 和 npx 即可使用所有功能。这种设计降低了入门门槛，使用户能够快速开始技术决策研究工作。

CLI 入口点采用命令路由模式，根据输入的命令参数将请求转发到具体的工具包。例如，当用户执行 npx grainulation orchard status 时，入口点会识别 orchard 子命令并将其路由到对应的工具包。

快速启动流程

用户可以通过以下命令快速启动 Grainulation 生态系统：

node bin/grainulation.js --help

无需执行 npm install 命令，因为 grainulation 本身没有 npm 依赖。这一特性确保了工具的即开即用性。

资料来源：bin/grainulation.js 资料来源：CONTRIBUTING.md

命令路由机制

lib/router.js

lib/router.js 是 Grainulation 的核心路由模块，负责将命令分发到正确的工具包。它解析用户输入的命令参数，识别目标工具，并将控制权传递给相应的工具模块。

路由机制支持以下功能：

路由层的设计遵循无状态原则——每个路由请求都是独立的，不依赖前一个请求的状态。这使得路由层能够高效处理并发请求，同时简化了测试和调试过程。

当用户执行子命令时，路由器会验证目标工具是否已安装。如果工具未安装，路由器会提示用户通过包管理器安装相应工具，或提供直接使用 npx 运行工具的备选方案。

资料来源：lib/router.js 资料来源：CONTRIBUTING.md

生态系统管理

lib/ecosystem.js

lib/ecosystem.js 负责整个生态系统的健康检查和工具发现功能。它维护已安装工具的注册表，并提供接口用于检查工具的可用性和版本状态。

生态系统管理器的核心职责包括：

• 工具发现：扫描已安装的 @grainulation/* 包并注册其功能
• 健康检查：验证每个工具包的安装完整性和版本兼容性
• 状态报告：汇总所有工具的运行状态并生成统一报告

健康检查流程会验证每个工具的以下条件：package.json 配置完整性、入口脚本可执行性、以及必需的依赖项是否满足。通过这种主动检查机制，系统能够在用户执行命令前发现并报告潜在问题。

lib/doctor.js

lib/doctor.js 是一个诊断工具，用于验证工具安装和问题排查。它提供交互式诊断流程，帮助用户识别和解决常见的配置问题。

诊断工具会执行以下检查项目：

1. Node.js 版本验证（需要 20+）
2. npm/npx 可用性检查
3. Grainulation 包安装状态验证
4. 子工具包完整性检查
5. 配置文件权限验证

当检测到问题时，doctor 会提供具体的修复建议，包括需要执行的命令和配置修改步骤。

资料来源：lib/ecosystem.js 资料来源：lib/doctor.js

包管理集成

lib/pm.js

lib/pm.js 实现了 Grainulation 工具的包管理功能。它封装了 npm 的核心操作，提供统一的接口用于安装、更新和卸载 grainulation 工具包。

包管理功能支持以下操作：

包管理器与生态系统层紧密集成，当安装新工具时会自动触发生态系统健康检查，确保新工具与现有工具版本兼容。

lib/setup.js

lib/setup.js 负责首次运行设置和配置初始化。它检测用户环境，生成必要的配置文件，并引导用户完成初始配置流程。

首次设置流程包括以下步骤：

1. 环境检测：验证 Node.js 版本和必需工具
2. 目录创建：初始化配置目录和数据存储位置
3. 配置生成：创建默认配置文件
4. 欢迎引导：展示快速开始指南和下一步建议

设置模块会检查 ~/.grainulation/ 目录是否存在，如果不存在则自动创建。该目录用于存储用户级别的配置和跨项目共享的数据。

资料来源：lib/pm.js 资料来源：lib/setup.js

发布流程与工具协调

统一发布机制

Grainulation 生态系统采用集中式发布策略，所有工具包通过统一的 GitHub Actions 工作流发布。每个包在其自己的仓库中维护，但发布流程由 grainulation 的发布规范协调。

发布架构遵循以下原则：

• 独立版本控制：每个工具包维护自己的语义化版本号
• 自动化发布：通过标签推送触发 CI/CD 流程
• 可信发布：使用 npm OIDC 信任发布，无需 API token

资料来源：RELEASE.md

单包发布流程

对于单包补丁发布，流程如下：

graph LR
    A[进入包目录] --> B[执行 npm version patch]
    B --> C[更新 package.json 和标签]
    C --> D[推送提交和标签]
    D --> E[GitHub Actions 运行测试]
    E --> F{测试通过?}
    F -->|是| G[发布到 npm]
    F -->|否| H[终止发布]
    G --> I[验证 npm 注册表]

发布工作流会自动验证标签与 package.json 版本号匹配，确保发布的一致性。

协调发布流程

当工具包之间存在依赖关系时（如 barn 新版本被其他工具依赖），需要执行协调发布流程：

1. 按依赖顺序发布：先发布被依赖的包
2. 等待 npm 同步：等待约 60 秒让新版本同步到 npm
3. 更新依赖包：在消费包中执行 npm install 更新依赖
4. 提交锁定文件：将更新后的 package-lock.json 提交到仓库

这种协调机制确保了生态系统内部版本的一致性，避免了依赖缺失问题。

资料来源：RELEASE.md

工具协作模式

核心工具：Wheat

Wheat 是 Grainulation 生态系统的核心研究引擎，负责启动和管理整个研究冲刺（sprint）生命周期。它是用户首先接触的工具，也是协调其他工具协作的起点。

Wheat 的核心命令流程：

1. 初始化冲刺：npx @grainulation/wheat init - 创建 claims.json 和配置文件
2. 添加证据：/research "topic" - 收集研究证据并生成声明
3. 挑战证据：/challenge r001 - 对已有证据进行对抗性测试
4. 生成简报：/brief - 编译所有声明并生成决策文档

权限管理：Farmer

Farmer 提供实时权限仪表板功能，允许用户从手机、另一浏览器标签页或会议中批准 AI 代理的工具调用。它通过 SSE（Server-Sent Events）与 Barn 组件通信，实现实时状态同步。

通信中枢：Barn

Barn 是 SSE 通信层的实现，为 Farmer 和其他需要实时通信的工具提供基础设施。它处理事件流分发、连接管理和消息路由，确保实时交互的可靠性。

导出工具：Mill

Mill 负责将编译后的研究成果导出为多种格式（PDF、CSV、静态站点），满足不同场景的分享需求。

分析工具：Harvest

Harvest 提供跨冲刺的学习分析功能，追踪预测准确性、发现系统性盲点、检测过时声明，帮助团队持续改进研究质量。

编排工具：Orchard

Orchard 是元工具（meta-tool），负责路由到正确工具、检查生态系统健康状况、管理所有八个包的配置。

统一入口：Silo

Silo 提供统一的 CLI 界面，整合所有工具的访问入口，简化多工具使用场景下的命令行操作。

工具间数据流

Grainulation 生态系统中的数据流动遵循声明式设计模式，所有工具共享统一的 claims 数据结构。这种设计确保了工具间协作的无缝性。

graph LR
    WHEAT[Wheat<br/>收集声明] --> CLAIMS[claims.json<br/>统一声明存储]
    FARMER[Farmer<br/>权限管理] --> CLAIMS
    CLAIMS --> MILL[Mill<br/>导出格式转换]
    CLAIMS --> HARVEST[Harvest<br/>跨冲刺分析]
    CLAIMS --> SILO[Silo<br/>统一查询]
    CLAIMS --> ORCHARD[Orchard<br/>状态汇总]
    
    BARN[Barn<br/>SSE通信] -.->|实时更新| FARMER
    BARN -.->|事件通知| WHEAT

声明（Claim）是 Grainulation 系统的核心数据单元，每个声明包含：

资料来源：site/index.html

测试与验证

基本测试框架

Grainulation 使用 Node.js 内置测试运行器进行基本功能验证。测试文件位于 test/basic.test.js，通过以下命令执行：

node test/basic.test.js

测试覆盖范围包括：

• CLI 入口点参数解析
• 命令路由正确性
• 工具发现机制
• 配置文件生成
• 健康检查流程

CI/CD 集成

每个工具包都配置了 GitHub Actions 工作流进行持续集成。CI 流程自动运行测试套件，确保代码变更不会破坏现有功能。

发布前的工作流检查项目：

1. 单元测试通过
2. 集成测试通过
3. 代码覆盖率达标
4. 版本号一致性验证
5. npm 发布签名验证

资料来源：CONTRIBUTING.md

配置与自定义

全局配置

Grainulation 在 ~/.grainulation/ 目录中存储用户级配置。配置采用 JSON 格式，支持以下自定义项：

{
  "registry": "https://registry.npmjs.org/",
  "telemetry": false,
  "theme": "default",
  "editor": "vim"
}

项目级配置

每个 Wheat 冲刺包含独立的配置文件 wheat.config.json，存储冲刺特定的设置，如约束条件、参与者信息和决策标准。

环境变量

Grainulation 支持通过环境变量进行高级配置：

故障排除

常见问题

诊断命令

使用 doctor 工具进行系统诊断：

node bin/grainulation.js doctor

诊断工具会逐步检查环境并提供修复建议。

扩展与贡献

添加新工具

要将新工具集成到 Grainulation 生态系统，需要：

1. 创建独立的 npm 包 @grainulation/<tool-name>
2. 在 grainulation 的路由配置中注册新工具
3. 更新生态系统健康检查以包含新工具
4. 添加相应的文档和测试

贡献流程

贡献代码的标准流程：

1. Fork 仓库并创建功能分支
2. 进行代码修改并编写测试
3. 运行 node test/basic.test.js 验证
4. 提交并推送变更
5. 创建 Pull Request 供审查

所有贡献者应遵循项目的行为准则，确保社区健康持续发展。

资料来源：CONTRIBUTING.md

概述

Grainulation 采用零依赖架构设计，所有健康检查功能均基于 Node.js 内置模块实现。诊断系统由多个组件协同工作，包括 doctor.js 诊断工具、生态系统健康检查模块以及统一的 CLI 路由层。资料来源：CONTRIBUTING.md

核心职责

健康检查与诊断模块承担以下核心职责：

资料来源：CONTRIBUTING.md:lib/doctor.js

系统架构

健康检查与诊断系统采用分层架构设计，从 CLI 入口到具体诊断模块逐层传递。

graph TD
    A[bin/grainulation.js<br/>CLI 入口] --> B[lib/router.js<br/>命令路由]
    B --> C[lib/doctor.js<br/>诊断工具]
    B --> D[lib/ecosystem.js<br/>生态系统]
    C --> E[工具安装验证]
    C --> F[配置文件检查]
    D --> G[健康状态检查]
    D --> H[工具发现]

各层组件说明

CLI 入口层

bin/grainulation.js 是整个生态系统的统一 CLI 入口点，负责接收用户命令并路由至正确的工具。该文件不依赖任何外部包，直接使用 Node.js 内置模块实现基础功能。资料来源：CONTRIBUTING.md:bin/grainulation.js

命令路由层

lib/router.js 负责将诊断相关命令分发至对应的处理模块。路由层会根据命令类型判断是执行诊断检查还是其他工具操作。资料来源：CONTRIBUTING.md:lib/router.js

诊断执行层

lib/doctor.js 是核心诊断工具，执行以下验证操作：

• 验证 grainulation 工具链中各包的安装状态
• 检查 Node.js 版本兼容性
• 检测 wheat.config.json 配置文件是否存在且有效
• 扫描所有八个工具包的健康状态

资料来源：CONTRIBUTING.md:lib/doctor.js

生态系统层

lib/ecosystem.js 负责整个生态系统的健康检查和工具发现功能。该模块会枚举已安装的工具包，并生成生态系统状态报告。资料来源：CONTRIBUTING.md:lib/ecosystem.js

诊断工具详解

doctor.js 核心功能

诊断工具提供三类核心检查能力：

检查流程

graph TD
    A[启动诊断] --> B{Node.js 版本检查}
    B -->|版本过低| C[输出警告]
    B -->|版本兼容| D[检查工具安装]
    D --> E{工具包是否存在}
    E -->|缺失| F[标记待安装]
    E -->|完整| G[验证配置文件]
    G --> H[生成诊断报告]

错误处理机制

诊断工具采用渐进式错误报告策略。当检测到问题时，系统不会立即终止，而是收集所有问题后统一输出，确保用户能一次性了解所有待修复项。资料来源：CONTRIBUTING.md:lib/doctor.js

生态系统健康检查

健康检查范围

lib/ecosystem.js 提供的健康检查覆盖以下维度：

1. 工具发现 - 自动检测系统中已安装的 grainulation 工具
2. 状态监控 - 实时追踪各工具的运行状态
3. 依赖关系 - 验证工具间的依赖完整性
4. 版本一致性 - 确保生态系统内版本同步

资料来源：CONTRIBUTING.md:lib/ecosystem.js

工具清单

Grainulation 生态系统包含以下八个工具：

资料来源：site/index.html

配置与设置

首次运行设置

lib/setup.js 负责首次运行时的初始化配置，包括：

• 创建必要的目录结构
• 初始化默认配置文件
• 验证 Node.js 环境
• 设置本地诊断基准

资料来源：CONTRIBUTING.md:lib/setup.js

配置文件结构

诊断系统依赖以下配置文件：

{
  "wheat.config.json": "项目级工具配置",
  "claims.json": "研究声明存储",
  ".grainulation/": "本地生态系统配置目录"
}

使用方式

快速诊断

用户可通过以下命令启动诊断检查：

npx grainulation doctor

生态系统状态

查看完整生态系统健康状态：

npx grainulation status

详细诊断报告

生成包含所有工具包的详细诊断报告：

npx grainulation doctor --verbose

诊断结果解读

状态代码

常见问题处理

工具包缺失

当诊断报告指示工具包未安装时，可使用 lib/pm.js 包管理模块进行安装。资料来源：CONTRIBUTING.md:lib/pm.js

Node.js 版本不兼容

Grainulation 要求 Node.js 20 或更高版本。检查当前版本：

node --version

配置文件损坏

删除现有配置并重新初始化：

npx grainulation setup --reset

技术实现细节

零依赖原则

健康检查与诊断模块严格遵循零依赖原则，所有功能基于 Node.js 内置模块实现：

• fs 模块 - 文件系统操作
• path 模块 - 路径处理
• child_process - 子进程管理
• crypto - 哈希校验

资料来源：site/index.html

本地服务器

诊断结果可通过 lib/server.mjs 提供的本地 Web 界面展示。该服务器使用 ESM 模块格式，提供统一的生态系统仪表板视图。资料来源：CONTRIBUTING.md:lib/server.mjs

相关链接

• 官方文档：https://grainulation.com
• 工具状态页：https://orchard.grainulation.com/
• 仓库地址：https://github.com/grainulation/grainulation

概述

Grainulation 是一个基于 Node.js 的技术决策研究工具生态系统，其开发环境配置采用零依赖设计理念，仅使用 Node.js 内置模块完成所有功能。整个开发环境围绕 CLI 工具链构建，核心目标是提供一套轻量、可审计的本地化研究流程，帮助团队将技术问题转化为带有类型和置信度评级的结构化声明（claims）。

开发环境配置模块主要负责以下几个核心功能：工具链初始化、环境健康检查、依赖管理、以及命令路由分发。资料来源：CONTRIBUTING.md

核心组件架构

组件职责矩阵

系统架构图

graph TD
    A[用户终端] --> B[bin/grainulation.js]
    B --> C[lib/router.js]
    C --> D[lib/ecosystem.js]
    C --> E[lib/setup.js]
    C --> F[lib/doctor.js]
    D --> E
    D --> F
    E --> G[lib/pm.js]
    F --> H[本地工具包检测]
    G --> I[工具包安装/更新]
    H --> J[wheat]
    H --> K[farmer]
    H --> L[barn]
    H --> M[mill]

资料来源：CONTRIBUTING.md

快速开始

环境要求

• Node.js: 20.x 或更高版本
• 包管理器: npx（随 Node.js 内置）
• 操作系统: 跨平台支持（Linux、macOS、Windows）

Grainulation 强调零依赖设计，整个生态系统不依赖任何 npm 包，全部使用 Node.js 内置模块实现。资料来源：README.md

基础安装

# 全局安装主工具
npm install -g @grainulation/grainulation

# 或直接使用 npx 运行
npx @grainulation/grainulation

初始化配置流程

sequenceDiagram
    用户->>CLI: grainulation setup
    CLI->>setup.js: 执行初始化
    setup.js->>pm.js: 检查工具包状态
    pm.js->>生态系统: 列出可用工具
    生态系统-->>setup.js: 工具列表
    setup.js-->>用户: 显示配置向导
    用户->>setup.js: 选择角色/工具
    setup.js->>本地配置: 写入配置文件

命令路由机制

router.js 工作原理

lib/router.js 是整个 CLI 的核心路由模块，负责将用户输入的命令分发到对应的工具包。该模块不依赖任何外部库，仅使用 Node.js 内置的 fs、path、url 等模块读取和解析文件系统结构。

路由匹配规则：

1. 解析命令行参数（process.argv）
2. 识别主命令（如 wheat、farmer、barn）
3. 查找对应的工具包目录
4. 将控制权传递给目标工具的入口文件

资料来源：lib/router.js

可用命令列表

资料来源：README.md

环境健康检查

doctor.js 诊断功能

lib/doctor.js 是 Grainulation 的诊断工具，用于验证本地开发环境的完整性和工具安装状态。该模块执行以下检查：

1. Node.js 版本验证：确认当前版本是否满足 20.x+ 要求
2. 工具包检测：扫描已安装的 grainulation 工具包
3. 配置完整性检查：验证配置文件是否存在且格式正确
4. 路径环境检查：确认 npx 可访问

doctor 输出示例

$ grainulation doctor

✓ Node.js v20.11.0 (要求: 20.x+)
✓ npx 可用
✓ wheat 已安装
✓ farmer 已安装
✓ barn 已安装
⚠ mill 未安装
✗ orchard 未安装

检查完成: 2 个工具缺失
运行 'grainulation setup' 安装缺失工具

资料来源：lib/doctor.js

首次运行配置

setup.js 配置流程

lib/setup.js 负责首次运行时的初始化工作。该模块会：

1. 检测当前环境的工具包安装状态
2. 根据用户角色推荐需要安装的工具
3. 生成用户级配置文件
4. 设置默认的研究工作目录结构

角色化配置

Grainulation 支持根据用户角色进行差异化配置：

资料来源：lib/setup.js

包管理机制

pm.js 工具包管理

lib/pm.js 是 Grainulation 的内部包管理器，负责：

1. 工具发现：扫描 ~/.grainulation/tools/ 目录下的已安装工具
2. 版本检查：比较本地版本与 npm 注册表版本
3. 按需安装：使用 npx 懒加载未安装的工具
4. 依赖隔离：每个工具包完全独立，无共享依赖

工具包安装流程

graph LR
    A[用户请求工具] --> B{pm.js 检测}
    B -->|已安装| C[直接调用]
    B -->|未安装| D[npx 懒加载]
    D --> E[临时安装到缓存]
    E --> F[执行工具]
    F --> G[缓存保留供后续使用]

资料来源：lib/pm.js

测试环境配置

基本测试

Grainulation 使用 Node.js 内置的测试运行器，无需额外安装测试框架。测试文件位于 test/ 目录。

# 运行基础测试
node test/basic.test.js

测试覆盖范围

资料来源：CONTRIBUTING.md

开发调试

本地调试模式

# 直接运行本地源码
node bin/grainulation.js --help

# 带调试输出运行
DEBUG=grainulation:* node bin/grainulation.js doctor

源码修改工作流

``bash git clone https://github.com/grainulation/grainulation.git cd grainulation ``

1. 克隆仓库：

``bash git checkout -b feature/description ``

1. 创建功能分支：

1. 修改代码

``bash node test/basic.test.js ``

1. 运行测试：

1. 提交并推送

资料来源：CONTRIBUTING.md

配置文件

配置文件位置

Grainulation 使用以下配置文件位置：

配置示例

{
  "version": "1.0.0",
  "role": "researcher",
  "tools": ["wheat", "barn"],
  "preferences": {
    "editor": "code",
    "gitAutoCommit": true
  }
}

常见问题排查

环境问题诊断表

诊断命令

# 完整环境诊断
grainulation doctor

# 检查 Node 版本
node --version

# 检查 npx 可用性
npx --version

技术实现细节

零依赖设计原则

Grainulation 的所有模块均使用 Node.js 内置模块实现，不依赖任何外部 npm 包。这一设计带来以下优势：

• 安全性：无第三方依赖意味着无供应链攻击风险
• 可移植性：任何装有 Node.js 20+ 的环境可直接运行
• 稳定性：不受上游包版本变更影响
• 轻量化：安装包体积最小化

内置模块使用情况

资料来源：lib/ecosystem.js

总结

Grainulation 的开发环境配置以简洁和零依赖为核心设计原则，通过模块化的架构实现了工具发现、健康检查、按需加载等关键功能。开发者只需确保 Node.js 20+ 环境即可开始使用，无需复杂的安装流程或依赖管理。这种设计使 Grainulation 成为技术决策研究中可靠、可审计且易于部署的工具选择。

诊断工具概述

Grainulation 的故障排查体系由以下核心组件构成：

资料来源：CONTRIBUTING.md:28-34

诊断命令详解

grainulation doctor

doctor 命令是 Grainulation 生态系统的健康检查工具，用于验证已安装工具的状态和版本信息。

使用方式：

grainulation doctor

功能说明：

• 检查哪些工具已安装
• 验证各工具的版本号
• 报告缺失或过时的工具
• 提供生态系统整体健康状态报告

资料来源：README.md:48, site/index.html

grainulation setup

setup 命令用于首次运行时的工具配置和安装引导。

使用方式：

grainulation setup

功能说明：

• 根据用户角色安装对应工具
• 配置必要的环境参数
• 初始化配置文件（如 wheat.config.json）

资料来源：README.md:47, CONTRIBUTING.md:35

诊断流程图

graph TD
    A[用户运行命令] --> B{命令类型}
    B -->|doctor| C[doctor.js 健康检查]
    B -->|setup| D[setup.js 首次配置]
    B -->|其他| E[router.js 命令路由]
    C --> F{工具状态}
    F -->|全部正常| G[输出健康报告]
    F -->|存在问题| H[输出问题列表]
    D --> I[ecosystem.js 工具发现]
    I --> J{工具缺失}
    J -->|是| K[提示安装命令]
    J -->|否| L[配置完成]
    E --> M[路由至对应工具包]

环境要求检查

Grainulation 对运行环境有明确要求，在排查问题时首先应确认以下条件：

资料来源：site/index.html

常见环境问题

1. Node.js 版本过低

• 症状：运行时报语法错误或模块未找到
• 解决：升级至 Node.js 20 或更高版本

1. 缺少 Claude Code

• 部分高级功能需要 Claude Code 支持
• 详情参阅 Claude Code 官方文档

工具安装问题排查

通过 npm 全局安装

npm install -g @grainulation/grainulation

通过 npx 直接运行

npx @grainulation/wheat init
npx @grainulation/farmer start
npx @grainulation/harvest analyze ./sprints/

资料来源：README.md:37-41

常见安装问题

生态系统健康诊断

Grainulation 的生态系统包含八个独立工具，每个工具都可能需要单独诊断：

资料来源：README.md:55-62

发布与测试相关问题

RELEASE.md 描述了完整的发布流程，当构建失败时可参考以下步骤：

CI/CD 故障排查

发布工作流位于 .github/workflows/publish.yml，测试脚本位于 test/basic.test.js。

node test/basic.test.js

资料来源：CONTRIBUTING.md:27, RELEASE.md

发布前检查清单

1. 本地运行测试确保通过
2. 确认 package.json 版本号正确
3. 验证标签与版本一致
4. 等待 npm 发布完成后再更新依赖方

资料来源：RELEASE.md:15-30

常见问题速查

Q: 工具命令找不到

排查步骤：

1. 确认已安装：npm list -g @grainulation/grainulation
2. 检查 PATH 配置
3. 使用完整命令路径测试

Q: 工具运行报错

排查步骤：

1. 检查 Node.js 版本：node --version（需 ≥20）
2. 清除 npm 缓存：npm cache clean --force
3. 重新安装工具

Q: 生态系统状态异常

排查步骤：

1. 运行健康检查：grainulation doctor
2. 检查各子工具版本
3. 使用 grainulation setup 重新配置

Q: wheat.config.json 相关问题

wheat 工具会创建配置文件如 wheat.config.json 和 claims.json，确保这些文件存在且格式正确。

资料来源：site/index.html

架构级诊断信息

Grainulation 的核心架构如下：

bin/grainulation.js       CLI 入口 - 路由至各工具
lib/router.js             命令路由
lib/ecosystem.js          生态系统健康检查
lib/doctor.js             诊断工具
lib/setup.js              首次运行设置
lib/pm.js                 包管理
lib/server.mjs            本地服务器
public/                   Web UI
site/                     公共网站
test/                     测试文件

资料来源：CONTRIBUTING.md:22-30

获取更多帮助

• 查看官方文档：https://grainulation.com
• 工具特定文档：
• wheat: https://wheat.grainulation.com
• farmer: https://farmer.grainulation.com
• mill: https://mill.grainulation.com
• silo: https://silo.grainulation.com
• GitHub Issues: https://github.com/grainulation/grainulation/issues

Pitfall Log / 踩坑日志

项目：grainulation/grainulation

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1184031176 | https://github.com/grainulation/grainulation | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1184031176 | https://github.com/grainulation/grainulation | last_activity_observed missing

3. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1184031176 | https://github.com/grainulation/grainulation | no_demo; severity=medium

4. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：risks.safety_notes | github_repo:1184031176 | https://github.com/grainulation/grainulation | No sandbox install has been executed yet; downstream must verify before user use.

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1184031176 | https://github.com/grainulation/grainulation | no_demo; severity=medium

6. 安全/权限坑 · 来源证据：v1.1.0 — Security Hardening

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 — Security Hardening
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_5e8c2578dd024d369fd769a7c23df98a | https://github.com/grainulation/grainulation/releases/tag/v1.1.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1184031176 | https://github.com/grainulation/grainulation | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1184031176 | https://github.com/grainulation/grainulation | release_recency=unknown