# https://github.com/grainulation/grainulation 项目说明书
生成时间：2026-05-13 12:30:20 UTC
## 目录
- [项目概述](#page-overview)
- [安装指南](#page-installation)
- [快速开始](#page-quickstart)
- [系统架构](#page-architecture)
- [CLI命令参考](#page-cli-commands)
- [生态系统概览](#page-ecosystem)
- [工具集成与协作](#page-tools-integration)
- [健康检查与诊断](#page-doctor)
- [开发环境配置](#page-setup)
- [故障排除](#page-troubleshooting)
## 项目概述
### 相关页面
相关主题：[系统架构](#page-architecture), [生态系统概览](#page-ecosystem), [快速开始](#page-quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/grainulation/grainulation/blob/main/README.md)
- [site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)
# 项目概述
## 项目简介
**grainulation** 是一个结构化技术决策研究生态系统，旨在将技术问题转化为带类型的、有证据等级支撑的声明（claims）。该项目并非传统的文档生成工具或 RFC/ADR 模板系统，而是一套完整的**研究-质疑-编译**工作流工具。
核心定位：帮助团队从"凭直觉做决策"转变为"基于可验证证据做决策"。
资料来源：[README.md:1-10]()
## 核心概念
### 声明（Claims）
grainulation 的所有工作都围绕**声明（claims）**展开。每个声明具有以下属性：
| 属性 | 说明 | 示例 |
|------|------|------|
| 类型 | 声明的语义类别 | factual（事实）、risk（风险）、estimate（估算）、constraint（约束）、recommendation（建议） |
| 证据等级 | 证据的可靠程度 | 从"有人说"到"生产环境测量" |
| 引用来源 | 证据的出处 | 文档、测试、生产数据等 |
> "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 工具组成，每个工具专注于单一职责。
| 工具 | 功能定位 | 安装命令 | 文档链接 |
|------|----------|----------|----------|
| **wheat** | 研究引擎，生成结构化证据 | `npx @grainulation/wheat init` | [wheat](https://github.com/grainulation/wheat) |
| **farmer** | 权限仪表盘，审批 AI 代理的工具调用 | `npx @grainulation/farmer start` | [farmer](https://github.com/grainulation/farmer) |
| **mill** | 导出与发布，生成 PDF、CSV、静态站点 | `npx @grainulation/mill export --format pdf` | [mill](https://github.com/grainulation/mill) |
| **barn** | 共享工具库，Sprint 检测、清单生成、HTML 模板 | `npx @grainulation/barn detect-sprints` | [barn](https://github.com/grainulation/barn) |
| **orchard** | 编排工具，路由到正确工具、检查生态健康 | `npx grainulation` | [orchard](https://github.com/grainulation/orchard) |
| **harvest** | 分析工具，跨 Sprint 学习、追踪预测准确性 | `npx @grainulation/harvest analyze ./sprints/` | [harvest](https://github.com/grainulation/harvest) |
| **silo** | 存储工具，结构化数据持久化 | `npx @grainulation/silo store` | [silo](https://github.com/grainulation/silo) |
| **grainulation** | 统一 CLI入口 | `npx grainulation` | 主仓库 |
资料来源：[README.md:36-44]()
## 工作流程
grainulation 采用 **研究-质疑-编译** 的三阶段工作流：
```mermaid
graph TD
A["❓ 提出问题
例：是否应将微服务迁移回模块化单体？"] --> B["1️⃣ 初始化 Sprint
wheat init"]
B --> C["claims.json 创建
wheat.config.json 就绪"]
C --> D["2️⃣ 研究与质疑"]
D --> E["wheat research 收集证据"]
E --> F["生成 typed claims
r001 [factual|documented]"]
F --> G["wheat challenge 压力测试"]
G --> H["生成风险声明
x001 [risk|documented]"]
H --> I["3️⃣ 编译与交付"]
I --> J["wheat brief 编译决策简报"]
J --> K["冲突已解决
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 依赖**：
| 特性 | 说明 |
|------|------|
| 仅使用 Node.js 内置模块 | 无外部依赖包 |
| 无供应链风险 | 不依赖第三方包的安全性 |
| 无 API 密钥需求 | 核心工具无需配置认证信息 |
| 纯本地运行 | 所有数据处理在本地完成 |
| 纯 JSON + HTML 输出 | 易于集成到现有工作流 |
> "Zero npm dependencies across all eight packages. No supply chain anxiety. No left-pad."
> 资料来源：[site/index.html:1]()
### 四大设计原则
| 原则 | 说明 | 相关特性 |
|------|------|----------|
| **声明优于观点** | 每个发现都是有类型、有等级、可追溯的声明 ID | "I think" → 声明 ID + 证据等级 |
| **对抗性压力** | 系统强制用户质疑、见证、压力测试每个声明 | 舒适的一致性是良好决策的大敌 |
| **零依赖** | 仅使用 Node.js 内置模块 | 纯本地运行，无外部依赖 |
| **确定性编译** | 编译器是 JavaScript 代码，非 LLM | 相同输入，相同输出 |
> "Comfortable agreement is the enemy of good decisions. The system forces you to challenge, witness, and stress-test every claim."
> 资料来源：[site/index.html:1]()
## 系统架构
```mermaid
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
冲突检测
证据验证
门控机制"]
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
```
## 安装与快速开始
### 环境要求
| 依赖 | 版本要求 |
|------|----------|
| Node.js | 20+ |
| npx | 最新版本 |
| Claude Code（可选） | 用于 AI 辅助研究 |
| Git | 用于审计轨迹追踪 |
### 安装方式
```bash
# 全局安装
npm install -g @grainulation/grainulation
# 或直接使用 npx（无需安装）
npx @grainulation/wheat init
```
### 快速命令
```bash
grainulation # 生态系统概览
grainulation doctor # 健康检查：工具列表、版本
grainulation setup # 为当前角色安装合适的工具
grainulation wheat init # 委托给 wheat 工具
grainulation farmer start # 启动权限仪表盘
```
资料来源：[README.md:21-29]()
## 与传统方法的区别
| 维度 | RFC/ADR | grainulation |
|------|---------|--------------|
| 文档性质 | 决策后记录 | 研究过程捕获 |
| 证据管理 | 手动整理 | 结构化声明 + 证据等级 |
| 对抗性测试 | 可选 | 内置强制机制 |
| 冲突处理 | 人工发现 | 编译器自动检测 |
| 审计轨迹 | 依赖 git 历史 | 内置完整证据链 |
> "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 审计轨迹**：完整的数据收集和质疑历史
---
## 安装指南
### 相关页面
相关主题：[快速开始](#page-quickstart), [开发环境配置](#page-setup)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/grainulation/grainulation/blob/main/README.md)
- [site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)
- [RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)
# 安装指南
## 概述
Grainulation 是一个由八个独立 CLI 工具组成的生态系统，旨在将技术问题转化为带有类型和证据等级的声明（claims），最终生成可审计的决策简报。整个项目遵循**零 npm 依赖**原则，全部基于 Node.js 原生内置模块构建，所有工具均在本地运行，无需云服务或 API 密钥。
本安装指南涵盖完整的环境准备、各工具的安装方式以及不同使用场景下的推荐配置。
## 系统要求
| 组件 | 最低版本 | 说明 |
|------|----------|------|
| Node.js | 20+ | 核心运行时环境 |
| npm | 内置 | 用于全局安装或本地依赖管理 |
| npx | 内置 | 用于直接执行远程包 |
| Claude Code | 最新版 | 用于执行研究任务的 AI 代理 |
资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)
> **重要提示**：核心工具（如 wheat）的编译器部分**不需要 API 密钥**。所有数据处理均在本地完成，不涉及任何云服务调用。
## 安装模式
Grainulation 提供两种主要安装模式，用户可根据实际需求选择。
### 模式一：全局安装（推荐长期使用）
全局安装适合需要频繁使用工具链的场景，一次安装后可在任意目录下直接调用：
```bash
npm install -g @grainulation/grainulation
```
安装完成后，可以通过统一的入口工具 `grainulation` 调用所有子命令：
```bash
grainulation # 查看生态系统概览
grainulation doctor # 健康检查：已安装工具列表及版本
grainulation setup # 根据角色安装所需工具
grainulation wheat init # 委托给 wheat 工具初始化研究 sprint
grainulation farmer start # 启动权限仪表板
```
资料来源：[README.md](https://github.com/grainulation/grainulation/blob/main/README.md)
### 模式二：按需执行（零安装）
对于偶尔使用或临时探索的场景，可以直接使用 `npx` 跳过安装步骤，按需下载并执行：
```bash
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](https://github.com/grainulation/grainulation/blob/main/site/index.html)
## 工具生态概览
Grainulation 包含八个独立工具，每个工具专注于特定功能领域：
| 工具 | 功能域 | 核心用途 | 安装命令 |
|------|--------|----------|----------|
| wheat | 研究引擎 | 增长结构化证据，管理声明 | `npx @grainulation/wheat init` |
| farmer | 权限仪表板 | 审批 AI 代理的工具调用请求 | `npx @grainulation/farmer start` |
| barn | 共享基础库 | Sprint 检测、清单生成、HTML 模板 | `npx @grainulation/barn detect-sprints` |
| mill | 导出与发布 | 生成 PDF、CSV、静态站点等格式 | `npx @grainulation/mill export --format pdf` |
| silo | 沙箱隔离 | 为 AI 代理提供安全的代码执行环境 | `npx @grainulation/silo sandbox` |
| harvest | 分析与洞察 | 跨 sprint 学习，追踪预测准确率 | `npx @grainulation/harvest analyze ./sprints/` |
| orchard | 编排层 | 工作流编排，跨工具协调 | `npx @grainulation/orchard status` |
| grainulation | 统一 CLI | 生态系统总入口，配置管理 | `npm install -g @grainulation/grainulation` |
资料来源：[README.md](https://github.com/grainulation/grainulation/blob/main/README.md)
## 快速开始工作流
对于新用户，建议按照以下三步流程完成首次研究 sprint：
```mermaid
graph TD
A[初始化 Sprint
npx @grainulation/wheat init] --> B[研究与质疑
收集证据, 挑战声明]
B --> C[编译与交付
生成决策简报]
C --> D[输出 brief.html
可导出为 PDF/CSV]
```
### 步骤一：初始化 Sprint
```bash
npx @grainulation/wheat init
```
执行后将创建两个核心文件：
- `claims.json` — 存储所有声明的清单文件
- `wheat.config.json` — 工具配置文件
```bash
$ npx @grainulation/wheat init
Sprint initialized.
claims.json created (0 claims)
wheat.config.json ready
```
资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)
### 步骤二：研究与质疑
在 wheat 交互式环境中使用以下命令：
```bash
wheat> /research "topic" # 收集关于指定主题的研究证据
wheat> /challenge r001 # 质疑指定声明，触发对抗性测试
```
声明将以统一格式输出：
```
r001 [factual|documented] ...
x001 [risk|documented] ...
```
### 步骤三：编译与交付
```bash
wheat> /brief
```
编译器将执行以下验证：
1. 解析所有声明及关联证据
2. 检测声明间的矛盾冲突
3. 标记证据等级不足的声明
4. 阻止输出直至所有问题解决
5. 生成包含完整 git 审计轨迹的决策简报
```bash
Compiled 12 claims (2 conflicts resolved)
Written: output/brief.html
```
资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)
## 环境健康检查
安装完成后，可使用以下命令验证工具链状态：
```bash
grainulation doctor
```
该命令将检测：
- 已安装的工具列表及版本号
- Node.js 版本兼容性
- 各工具间的依赖关系状态
## 权限仪表板安装
Farmer 是用于审批 AI 代理工具调用的实时仪表板，特别适合团队协作场景：
```bash
npx @grainulation/farmer start
```
启动后支持以下功能：
- 通过手机、另一浏览器标签页或会议期间审批请求
- 实时 SSE（Server-Sent Events）推送
- **零依赖**设计，不引入额外包
资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)
## 离线与私有部署
由于 Grainulation 整个生态系统的设计原则是**零 npm 依赖**（仅使用 Node.js 内置模块），部署到私有环境或离线场景非常直接：
1. 将整个仓库克隆至目标机器
2. 确保 Node.js 20+ 已安装
3. 通过 `npx` 或本地 `node` 直接运行各工具入口脚本
```bash
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：可以安装单个工具而不安装整个生态吗？
可以。八个工具相互独立，按需安装即可：
```bash
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
---
## 快速开始
### 相关页面
相关主题：[CLI命令参考](#page-cli-commands), [生态系统概览](#page-ecosystem)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/grainulation/grainulation/blob/main/README.md)
- [site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)
- [CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
- [bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)
- [lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)
# 快速开始
## 概述
快速开始是 Grainulation 生态系统的入口点，旨在帮助用户在 60 秒内启动一个技术决策研究冲刺（Sprint）。整个流程设计遵循"三条命令，一个决策"的原则，无需安装、无需注册、无需配置 API Key，只需 `npx` 和一个问题即可开始。
资料来源：[site/index.html:1]()
## 前置要求
在开始使用 Grainulation 之前，请确保满足以下环境要求：
| 要求 | 版本 | 说明 |
|------|------|------|
| Node.js | 20+ | 仅使用 Node.js 内置模块 |
| npx | 最新版 | 用于直接运行包 |
| Claude Code | 可选 | 用于 AI 辅助研究 |
| npm | 最新版 | 用于全局安装 |
Grainulation 的核心理念是**零依赖**——所有八个包均不使用任何 npm 依赖项，完全基于 Node.js 内置模块构建，不存在供应链安全风险。
资料来源：[README.md:1]()
## 安装方式
Grainulation 提供两种安装方式，用户可根据使用场景选择：
### 全局安装
适合经常使用 Grainulation 的用户：
```bash
npm install -g @grainulation/grainulation
```
全局安装后，可以直接使用 `grainulation` 命令：
```bash
grainulation # 生态系统概览
grainulation doctor # 健康检查：工具列表和版本
grainulation setup # 安装适合角色的工具
grainulation farmer start # 启动权限仪表板
```
### 直接运行（推荐）
适合临时使用或首次体验的用户：
```bash
npx @grainulation/wheat init
```
这种方式无需安装任何内容，直接通过 npx 拉取并执行包。
资料来源：[README.md:1]()
## 三步工作流程
Grainulation 的快速开始流程分为三个阶段：初始化、研究与挑战、编译发布。
### 步骤一：初始化冲刺
使用 `wheat` 工具初始化一个新的研究冲刺。系统会提示你输入问题、受众和约束条件：
```bash
npx @grainulation/wheat init
```
执行后将创建两个文件：
| 文件 | 用途 |
|------|------|
| `claims.json` | 存储所有声明（Claims）的文件 |
| `wheat.config.json` | 配置文件 |
初始化输出示例：
```
Sprint initialized.
claims.json created (0 claims)
wheat.config.json ready
```
资料来源：[site/index.html:1]()
### 步骤二：研究与挑战
在研究阶段，你需要收集证据并对每个发现进行压力测试。所有发现都会成为带有类型和等级的声明（Claims）。
wheat 命令行工具提供两个核心命令：
```bash
wheat> /research "topic" # 收集关于某个主题的证据
wheat> /challenge r001 # 挑战已有的声明
```
声明具有以下属性：
| 属性 | 可选值 | 说明 |
|------|--------|------|
| 类型 | factual, risk, estimate, constraint, recommendation | 声明的语义类型 |
| 等级 | documented, measured, peer-reviewed 等 | 证据强度等级 |
| 状态 | active, challenged, resolved | 当前状态 |
挑战声明后，系统会生成新的风险声明（以 `x` 前缀标识）：
```
r001 [factual|documented] ... # 原始声明
x001 [risk|documented] ... # 由挑战产生的风险声明
```
资料来源：[site/index.html:1]()
### 步骤三：编译并发布
当研究完成且冲突已解决后，使用编译命令生成决策简报：
```bash
wheat> /brief
```
编译器的工作流程：
```mermaid
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 生态系统的工作流程如下：
```mermaid
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 由八个独立的工具组成，每个工具负责特定功能：
| 工具 | 用途 | 安装命令 |
|------|------|----------|
| [wheat](https://github.com/grainulation/wheat) | 研究引擎，构建结构化证据 | `npx @grainulation/wheat init` |
| [farmer](https://github.com/grainulation/farmer) | 权限仪表板，审批 AI 代理工具调用 | `npx @grainulation/farmer start` |
| [barn](https://github.com/grainulation/barn) | 共享工具库，冲刺检测和清单生成 | `npx @grainulation/barn detect-sprints` |
| [mill](https://github.com/grainulation/mill) | 导出工具，生成 PDF、CSV、静态站点 | `npx @grainulation/mill export --format pdf` |
| [silo](https://github.com/grainulation/silo) | 文档存储，可搜索的结构化声明存档 | `npx @grainulation/silo search` |
| [orchard](https://github.com/grainulation/orchard) | 编排工具，路由和生态系统健康检查 | `npx @grainulation/orchard status` |
| [harvest](https://github.com/grainulation/harvest) | 分析工具，预测准确性和系统盲点追踪 | `npx @grainulation/harvest analyze ./sprints/` |
| grainulation | 统一 CLI，元工具路由 | `npx @grainulation/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 文件，可部署到任何静态托管服务。
---
## 系统架构
### 相关页面
相关主题：[项目概述](#page-overview), [CLI命令参考](#page-cli-commands), [工具集成与协作](#page-tools-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)
- [lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)
- [lib/server.mjs](https://github.com/grainulation/grainulation/blob/main/lib/server.mjs)
- [lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/lib/ecosystem.js)
- [lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/lib/doctor.js)
- [lib/setup.js](https://github.com/grainulation/grainulation/blob/main/lib/setup.js)
- [lib/pm.js](https://github.com/grainulation/grainulation/blob/main/lib/pm.js)
# 系统架构
## 概述
Grainulation 是一个元包（meta-package）和生态系统路由器，它编排所有 Grainulation 工具并提供统一的 CLI 入口点。该项目的核心理念是**零依赖**——整个生态系统完全基于 Node.js 内置模块构建，不使用任何 npm 依赖项。
资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
## 架构设计原则
Grainulation 遵循以下核心架构原则：
| 原则 | 描述 | 实现方式 |
|------|------|----------|
| 零依赖 | 整个生态系统无 npm 依赖 | 仅使用 Node.js 内置模块 |
| 统一入口 | 所有工具通过单一 CLI 路由 | `bin/grainulation.js` 作为主入口 |
| 本地优先 | 所有数据和处理在本地运行 | 无需 API 密钥或云服务 |
| 生态系统协调 | 统一的健康检查和工具发现 | `lib/ecosystem.js` 负责 |
资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)
## 核心组件架构
### 组件层次结构
```mermaid
graph TD
subgraph 入口层
CLI[bin/grainulation.js
CLI 入口点]
end
subgraph 核心库
Router[lib/router.js
命令路由]
Ecosystem[lib/ecosystem.js
生态系统健康检查]
Doctor[lib/doctor.js
诊断工具]
Setup[lib/setup.js
首次运行配置]
PM[lib/pm.js
包管理]
end
subgraph 服务层
Server[lib/server.mjs
本地服务器]
end
subgraph 前端层
Public[public/
Web UI]
Site[site/
公共网站]
end
CLI --> Router
Router --> Ecosystem
Router --> Doctor
Router --> Setup
Router --> PM
Server --> Public
Server --> Ecosystem
```
### 各组件职责
| 组件文件 | 职责 | 模块类型 |
|----------|------|----------|
| `bin/grainulation.js` | CLI 入口点，路由到各个独立工具包 | CommonJS |
| `lib/router.js` | 命令路由，将请求分发到正确的工具包 | CommonJS |
| `lib/ecosystem.js` | 生态系统健康检查和工具发现 | CommonJS |
| `lib/doctor.js` | 诊断工具，验证工具安装状态 | CommonJS |
| `lib/setup.js` | 首次运行设置和配置 | CommonJS |
| `lib/pm.js` | Grainulation 工具的包管理功能 | CommonJS |
| `lib/server.mjs` | 本地服务器，提供统一生态系统仪表板 | ESM |
资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
## 命令路由机制
### 路由流程
```mermaid
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 由八个独立工具组成，每个工具专注于特定功能：
| 工具名称 | 颜色标识 | 功能领域 | 用途 |
|----------|----------|----------|------|
| **wheat** | 金色 (#fbbf24) | 研究引擎 | 初始化 sprint、研究、挑战、编译决策 |
| **farmer** | 蓝色 (#3b82f6) | 权限仪表板 | 审批 AI 代理的工具调用请求 |
| **barn** | 红色 (#f43f5e) | 知识存储 | 持久化存储和管理研究数据 |
| **mill** | 紫色 (#a78bfa) | 导出发布 | 将研究编译为 PDF、CSV、静态站点 |
| **silo** | 青色 (#22d3ee) | 共享存储 | 团队间共享和协作研究 |
| **harvest** | 橙色 (#fb923c) | 分析统计 | 跨 sprint 学习，追踪预测准确性 |
| **orchard** | 棕色 (#d4a574) | 编排协调 | 跨工具协调和工作流管理 |
| **grainulation** | 灰色 (#9ca3af) | 统一 CLI | 元工具，路由到各工具并管理配置 |
资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)
## 生态系统健康检查
`lib/ecosystem.js` 负责维护整个工具生态系统的健康状态：
### 健康检查流程
```mermaid
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](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
## 本地服务器架构
`lib/server.mjs` 是使用 ESM 模块格式的本地服务器：
### 服务器特性
| 特性 | 描述 |
|------|------|
| 模块格式 | ESM (ECMAScript Modules) |
| 功能 | 提供统一的生态系统仪表板 |
| 前端资源 | `public/` 目录下的 Web UI |
| 实时更新 | 支持 SSE (Server-Sent Events) 实时通信 |
### 服务架构
```mermaid
graph TD
subgraph 服务层
Server[lib/server.mjs
ESM 服务器]
end
subgraph 前端资源
UI[public/
静态资源]
Dashboard[生态系统仪表板]
end
Server --> UI
Server --> Dashboard
Server --> SSE[SSE 实时更新]
subgraph 数据流
API[内部 API]
Health[健康检查数据]
end
Server --> API
API --> Health
```
资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
## 测试架构
### 测试框架
Grainulation 使用 Node.js 内置测试运行器：
| 测试文件 | 描述 |
|----------|------|
| `test/basic.test.js` | 基本功能测试 |
### 测试执行
```bash
node test/basic.test.js
```
测试覆盖以下核心功能：
- CLI 命令解析
- 路由功能验证
- 生态系统健康检查
资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
## 发布工作流架构
### 发布流程
```mermaid
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]
```
### 发布配置
| 配置项 | 值 |
|--------|-----|
| 工作流文件 | `.github/workflows/publish.yml` |
| 认证方式 | OIDC 信任发布 (无需 NPM_TOKEN) |
| 平台 | npmjs.com |
| 徽章 | "Built + Signed" 链接回工作流运行 |
### 协调发布流程
当消费者依赖新的内部功能时：
1. **首先发布依赖包**（如 `barn`）
2. **等待 npm 发布完成**（约 60 秒）
3. **在消费者仓库执行 `npm install`** 更新 package-lock.json
4. **提交锁文件更新**
5. **按顺序发布各消费者包**
资料来源：[RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)
## 数据流总览
```mermaid
graph TD
subgraph 用户交互层
CLI[CLI 命令行]
WebUI[Web 界面]
end
subgraph 入口处理
Entry[bin/grainulation.js]
end
subgraph 核心处理
Router[路由层
lib/router.js]
Ecosystem[生态层
lib/ecosystem.js]
Doctor[诊断层
lib/doctor.js]
Setup[配置层
lib/setup.js]
PM[包管理层
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
```
## 技术栈总结
| 层面 | 技术选择 | 理由 |
|------|----------|------|
| 运行时 | Node.js 20+ | 核心运行要求 |
| CLI 框架 | 原生参数解析 | 零依赖原则 |
| 模块系统 | CommonJS + ESM 混合 | 兼容性考虑 |
| 测试框架 | Node.js 内置测试 | 无外部依赖 |
| 发布平台 | npm (OIDC) | 现代化 CI/CD |
| 包管理 | npx | 即开即用 |
资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)
---
## CLI命令参考
### 相关页面
相关主题：[系统架构](#page-architecture), [健康检查与诊断](#page-doctor), [开发环境配置](#page-setup)
相关源码文件
以下源码文件用于生成本页说明：
- [bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)
- [lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)
- [lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/lib/ecosystem.js)
- [lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/lib/doctor.js)
- [lib/pm.js](https://github.com/grainulation/grainulation/blob/main/lib/pm.js)
- [lib/setup.js](https://github.com/grainulation/grainulation/blob/main/lib/setup.js)
- [lib/server.mjs](https://github.com/grainulation/grainulation/blob/main/lib/server.mjs)
# CLI命令参考
本文档详细介绍 grainulation 生态系统中统一 CLI 的所有命令、功能和使用方式。
## 概述
grainulation 是 grainulation 工具生态系统的元包和统一入口点，负责协调所有 grainulation 工具并提供统一的 CLI 入口。CLI 架构遵循简单路由模式，将命令分发到各个独立工具包执行。资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
## 架构设计
grainulation CLI 采用模块化架构，核心组件协同工作以提供统一的命令行体验。
```mermaid
graph TD
A[bin/grainulation.js
CLI入口点] --> B[lib/router.js
命令路由]
A --> C[lib/ecosystem.js
生态系统健康检查]
A --> D[lib/doctor.js
诊断工具]
B --> E[@grainulation/wheat
研究工具]
B --> F[@grainulation/farmer
权限仪表盘]
B --> G[@grainulation/barn
共享工具]
B --> H[其他工具包...]
C --> I[npm registry
工具发现]
D --> J[本地安装验证]
F --> K[server.mjs
本地服务器]
```
### 核心文件职责
| 文件路径 | 职责 | 功能描述 |
|---------|------|---------|
| `bin/grainulation.js` | CLI入口点 | 解析命令行参数，路由到正确工具 |
| `lib/router.js` | 命令路由 | 将命令分发到独立工具包执行 |
| `lib/ecosystem.js` | 生态系统管理 | 健康检查和工具发现 |
| `lib/doctor.js` | 诊断工具 | 验证工具安装状态 |
| `lib/pm.js` | 包管理 | grainulation 工具的包管理 |
| `lib/setup.js` | 首次设置 | 首次运行配置和初始化 |
| `lib/server.mjs` | 本地服务器 | 统一的生态系统仪表盘（ESM） |
## 命令行接口
### 基本用法
```bash
npx grainulation [command] [options]
```
### 全局选项
| 选项 | 描述 | 默认值 |
|------|------|--------|
| `--help, -h` | 显示帮助信息 | - |
| `--version, -v` | 显示版本号 | - |
| `--json` | 以JSON格式输出 | false |
### 帮助命令
```bash
grainulation --help
```
显示所有可用命令和选项的完整帮助信息。
## 子命令详解
### 1. doctor - 诊断命令
doctor 命令用于验证 grainulation 工具的本地安装状态，检查每个工具包的健康状况。
```bash
grainulation doctor [options]
```
**功能说明**
- 验证各工具包的安装完整性
- 检查 Node.js 版本兼容性
- 报告缺失或损坏的工具包
- 提供修复建议
**可用选项**
| 选项 | 描述 |
|------|------|
| `--fix` | 自动修复发现的问题 |
| `--json` | 输出JSON格式诊断结果 |
### 2. doctor 命令工作流程
```mermaid
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 工具生态系统的包管理功能。
```bash
grainulation pm [subcommand] [options]
```
**子命令**
| 子命令 | 描述 |
|--------|------|
| `install` | 安装指定工具包 |
| `uninstall` | 卸载指定工具包 |
| `update` | 更新工具包到最新版本 |
| `list` | 列出已安装的工具包 |
| `search` | 在npm registry中搜索工具 |
**install 子命令选项**
| 选项 | 描述 | 示例 |
|------|------|------|
| `--save` | 保存到package.json依赖 | `pm install wheat --save` |
| `--global` | 全局安装 | `pm install --global farmer` |
| `--version` | 指定版本安装 | `pm install barn@1.3.0` |
### 4. ecosystem - 生态系统命令
ecosystem 命令用于检查整个 grainulation 工具生态系统的健康状态和可用性。
```bash
grainulation ecosystem [options]
```
**功能说明**
- 检查所有工具包的最新版本
- 验证工具包在npm上的可用性
- 生成生态系统健康报告
- 检测过时工具包
**输出示例**
```
生态系统健康检查
✓ wheat@1.2.0 - 最新
✓ farmer@0.9.5 - 最新
⚠ barn@1.2.0 - 可用更新: 1.3.0
✓ mill@2.1.0 - 最新
```
### 5. setup - 初始设置命令
setup 命令处理 grainulation CLI 的首次运行配置。
```bash
grainulation setup [options]
```
**功能说明**
- 创建必要的配置文件
- 初始化本地工具缓存
- 配置默认工具路径
- 验证环境依赖
**自动执行流程**
```mermaid
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界面。
```bash
grainulation server [options]
```
**功能说明**
- 启动本地HTTP服务器
- 提供Web UI界面查看所有工具状态
- 支持实时工具健康监控
- 提供SSE（Server-Sent Events）实时更新
**服务器选项**
| 选项 | 描述 | 默认值 |
|------|------|--------|
| `--port, -p` | 指定服务器端口 | 3000 |
| `--host` | 指定服务器主机 | localhost |
| `--open` | 启动后自动打开浏览器 | false |
**使用示例**
```bash
# 启动服务器
grainulation server
# 指定端口并自动打开浏览器
grainulation server --port 8080 --open
```
## 工具包路由机制
grainulation CLI 的核心功能是将命令路由到正确的工具包。路由机制通过 `lib/router.js` 实现。
```mermaid
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[返回结果]
```
### 路由配置
路由系统支持以下工具包前缀：
| 前缀 | 工具包 | 用途 |
|------|--------|------|
| `wheat` | @grainulation/wheat | 研究和挑战工具 |
| `farmer` | @grainulation/farmer | 权限仪表盘 |
| `barn` | @grainulation/barn | 共享工具库 |
| `mill` | @grainulation/mill | 导出和发布工具 |
| `silo` | @grainulation/silo | 存储管理 |
| `harvest` | @grainulation/harvest | 分析工具 |
| `orchard` | @grainulation/orchard | 状态管理 |
## 环境要求
### Node.js版本要求
grainulation CLI 要求 **Node.js 20.0.0** 或更高版本。
```bash
# 检查Node.js版本
node --version
# 要求版本
node >= 20.0.0
```
### 零依赖设计
grainulation 核心CLI包采用零npm依赖设计，完全基于Node.js内置模块构建。资料来源：[package.json](https://github.com/grainulation/grainulation/blob/main/package.json)
**内置依赖使用情况**
| 模块 | 用途 |
|------|------|
| `fs` | 文件系统操作 |
| `path` | 路径处理 |
| `child_process` | 子进程执行 |
| `http`/`https` | 网络请求 |
| `url` | URL解析 |
| `os` | 操作系统信息 |
## 配置文件
### 配置文件位置
grainulation 使用以下配置文件：
| 文件名 | 位置 | 用途 |
|--------|------|------|
| `grainulation.config.json` | 用户主目录 | 全局配置 |
| `.grainulationrc` | 当前目录 | 项目级配置 |
### 配置文件结构
```json
{
"version": "1.0.0",
"tools": {
"installed": ["wheat", "farmer", "barn"],
"path": "~/.grainulation/tools"
},
"server": {
"port": 3000,
"host": "localhost"
},
"registry": "https://registry.npmjs.org/"
}
```
## 常见用法示例
### 完整工作流程
```bash
# 1. 首次使用：检查环境健康
grainulation doctor
# 2. 查看生态系统状态
grainulation ecosystem
# 3. 安装所需工具
grainulation pm install wheat
grainulation pm install farmer
# 4. 启动本地仪表盘
grainulation server --open
# 5. 在另一终端使用wheat进行研究
wheat init "我们的系统应该使用微服务吗?"
```
### 诊断和修复
```bash
# 诊断问题
grainulation doctor
# 自动修复
grainulation doctor --fix
# 查看JSON格式诊断结果
grainulation doctor --json
```
### 包管理操作
```bash
# 列出已安装的工具
grainulation pm list
# 搜索可用工具
grainulation pm search auth
# 安装特定版本
grainulation pm install barn@1.3.0
# 更新所有工具
grainulation pm update
```
## 错误处理
### 常见错误及解决方案
| 错误代码 | 描述 | 解决方案 |
|---------|------|---------|
| `E_NODE_VERSION` | Node.js版本过低 | 升级到Node.js 20+ |
| `E_TOOL_NOT_FOUND` | 工具包未安装 | 运行 `grainulation pm install ` |
| `E_TOOL_BROKEN` | 工具包损坏 | 运行 `grainulation doctor --fix` |
| `E_REGISTRY_UNREACHABLE` | npm registry不可达 | 检查网络连接和代理设置 |
| `E_PERMISSION_DENIED` | 权限不足 | 使用sudo或检查文件权限 |
### 调试模式
启用调试模式以获取详细日志：
```bash
DEBUG=grainulation:* grainulation
```
## 与wheat工具的集成
grainulation CLI 与 `@grainulation/wheat` 工具深度集成，提供完整的研究决策流程支持。
```mermaid
graph LR
A[grainulation wheat] --> B[wheat init
初始化研究项目]
B --> C[wheat /research
收集证据]
C --> D[wheat /challenge
挑战Claims]
D --> E[wheat /brief
编译决策简报]
E --> F[grainulation mill
导出报告]
```
资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
## 相关资源
- [官方文档](https://grainulation.com)
- [wheat工具文档](https://wheat.grainulation.com)
- [farmer工具文档](https://farmer.grainulation.com)
- [GitHub仓库](https://github.com/grainulation/grainulation)
---
## 生态系统概览
### 相关页面
相关主题：[工具集成与协作](#page-tools-integration), [项目概述](#page-overview)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/grainulation/grainulation/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
- [RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)
- [site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)
# 生态系统概览
Grainulation 是一个由八个零依赖 CLI 工具组成的生态系统，旨在将技术问题转化为结构化的、带类型标注的、可审计的决策声明。整个系统基于 Node.js 原生模块构建，不依赖任何外部 npm 包，实现本地化运行和可复现的决策流程。
## 核心设计理念
Grainulation 的核心理念源于一个观察：**大多数决策失败不是因为团队缺乏数据，而是缺乏将数据转化为证据、将证据转化为决策的过程**。系统围绕四个基本原则构建：
| 原则 | 说明 |
|------|------|
| 证据驱动 | 每个声明都是带类型、置信度和证据等级的声明 |
| 编译器验证 | 编译器是确定性 JavaScript 代码，而非 LLM 调用，确保相同输入产生相同输出 |
| 对抗性挑战 | 系统强制团队挑战、见证和压力测试每个声明 |
| 零依赖 | 全部八个包仅使用 Node.js 内置模块 |
资料来源：[README.md:1-15]()
## 八工具架构
整个生态系统包含八个独立工具，每个工具专注于一个特定功能。以下是完整工具矩阵：
| 工具名称 | 功能角色 | 核心用途 |
|----------|----------|----------|
| **wheat** | 研究引擎 | 增长结构化证据，创建声明文件 |
| **farmer** | 权限仪表板 | 从手机、另一标签页或会议审批 AI 代理工具调用 |
| **barn** | 证据存储 | 结构化存储所有研究和声明 |
| **mill** | 导出发布 | 将编译后的研究转换为 PDF、CSV 和静态站点 |
| **silo** | 证据验证 | 独立验证声明，检测不一致 |
| **harvest** | 分析统计 | 跨 Sprint 学习，追踪预测准确性 |
| **orchard** | 配置管理 | 状态面板，管理所有工具配置 |
| **grainulation** | 统一 CLI | 元工具，路由到正确工具，检查生态系统健康状态 |
资料来源：[site/index.html:140-180]()
## 工具协作流程
```mermaid
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 采用分层架构设计：
```mermaid
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
```
### 核心组件说明
| 组件 | 文件路径 | 职责 |
|------|----------|------|
| CLI 入口点 | `bin/grainulation.js` | 路由到各个工具包 |
| 命令路由 | `lib/router.js` | 将命令分发到正确的工具包 |
| 生态系统 | `lib/ecosystem.js` | 健康检查和工具发现 |
| 诊断工具 | `lib/doctor.js` | 验证工具安装状态 |
| 首次设置 | `lib/setup.js` | 首次运行设置和配置 |
| 包管理 | `lib/pm.js` | grainulation 工具的包管理 |
资料来源：[CONTRIBUTING.md:20-45]()
## 声明类型系统
Grainulation 的核心抽象是**声明（Claim）**——一个带有类型和证据等级的单个声明语句。声明具有以下属性：
| 属性 | 可选值 | 说明 |
|------|--------|------|
| 类型 | factual, risk, estimate, constraint, recommendation | 声明的语义类别 |
| 证据等级 | 从"有人说"到"生产环境测量" | 证据强度 |
| ID | r001, x001 等 | 全局唯一标识 |
系统通过编译器验证声明的一致性，检测矛盾，并标记弱证据。
资料来源：[site/index.html:200-220]()
## 快速上手路径
```mermaid
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
```
### 基础命令
```bash
# 生态系统概览
grainulation
# 健康检查
grainulation doctor
# 安装适合角色的工具
grainulation setup
# 初始化研究 Sprint
grainulation wheat init
# 或直接
npx @grainulation/wheat init
```
资料来源：[README.md:30-50]()
## 发布与版本管理
生态系统采用协调发布机制，确保包之间的依赖关系正确：
```mermaid
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]()
## 技术约束
| 约束项 | 要求 |
|--------|------|
| Node.js 版本 | 20+ |
| 依赖策略 | 零 npm 依赖，仅 Node.js 内置模块 |
| API 密钥 | 核心工具无需 API 密钥 |
| 云服务 | 无需云服务 |
| 运行方式 | 全部本地运行 |
| 数据格式 | 纯 JSON 和 HTML |
资料来源：[site/index.html:225-235]()
## 相关文档
- [wheat 工具文档](https://wheat.grainulation.com/) — 研究引擎
- [farmer 工具文档](https://farmer.grainulation.com/) — 权限仪表板
- [barn 工具文档](https://barn.grainulation.com/) — 证据存储
- [mill 工具文档](https://mill.grainulation.com/) — 导出发布
---
## 工具集成与协作
### 相关页面
相关主题：[生态系统概览](#page-ecosystem), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)
- [lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)
- [lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/lib/ecosystem.js)
- [lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/lib/doctor.js)
- [lib/setup.js](https://github.com/grainulation/grainulation/blob/main/lib/setup.js)
- [lib/pm.js](https://github.com/grainulation/grainulation/blob/main/lib/pm.js)
- [CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
- [RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)
# 工具集成与协作
## 概述
Grainulation 是一个元包（meta-package），通过统一的 CLI 入口点协调整个工具生态系统。它本身不提供核心研究功能，而是作为八个独立工具包的路由层和编排层存在。这种设计遵循单一职责原则，使每个工具（Wheat、Farmer、Barn、Mill、Silo、Harvest、Orchard）能够独立发布和演进，同时通过统一的入口点提供一致的用户体验。
工具集成架构的核心目标是实现**零依赖**生态——所有工具都基于 Node.js 内置模块构建，不依赖外部 npm 包。Grainulation 作为中央协调器，负责命令路由、健康检查、工具发现和包管理等职责，使各个工具能够无缝协作。
## 核心架构
Grainulation 的架构采用分层设计，从上到下依次为：CLI 入口层、路由层、生态系统层和工具层。这种分层确保了各组件之间的松耦合，便于独立扩展和维护。
```mermaid
graph TB
subgraph "CLI 入口层"
CLI["bin/grainulation.js
统一命令行入口"]
end
subgraph "路由层"
ROUTER["lib/router.js
命令路由"]
end
subgraph "生态系统层"
ECO["lib/ecosystem.js
健康检查与工具发现"]
DOCTOR["lib/doctor.js
诊断工具"]
PM["lib/pm.js
包管理"]
SETUP["lib/setup.js
首次配置"]
end
subgraph "工具层"
WHEAT["@grainulation/wheat
核心研究引擎"]
FARMER["@grainulation/farmer
权限仪表板"]
BARN["@grainulation/barn
SSE 通信"]
MILL["@grainulation/mill
导出与发布"]
SILO["@grainulation/silo
统一 CLI"]
HARVEST["@grainulation/harvest
分析工具"]
ORCHARD["@grainulation/orchard
编排工具"]
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](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
## CLI 入口点
### bin/grainulation.js
`bin/grainulation.js` 是整个生态系统的统一命令行入口点。它负责接收用户输入并将其路由到相应的工具包。该入口点支持 `--help` 参数来显示帮助信息，用户无需安装任何依赖即可通过 `npx grainulation` 直接运行。
入口脚本的设计理念是**零安装依赖**——用户只需拥有 Node.js 20+ 和 npx 即可使用所有功能。这种设计降低了入门门槛，使用户能够快速开始技术决策研究工作。
CLI 入口点采用命令路由模式，根据输入的命令参数将请求转发到具体的工具包。例如，当用户执行 `npx grainulation orchard status` 时，入口点会识别 `orchard` 子命令并将其路由到对应的工具包。
### 快速启动流程
用户可以通过以下命令快速启动 Grainulation 生态系统：
```bash
node bin/grainulation.js --help
```
无需执行 `npm install` 命令，因为 grainulation 本身没有 npm 依赖。这一特性确保了工具的即开即用性。
资料来源：[bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)
资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
## 命令路由机制
### lib/router.js
`lib/router.js` 是 Grainulation 的核心路由模块，负责将命令分发到正确的工具包。它解析用户输入的命令参数，识别目标工具，并将控制权传递给相应的工具模块。
路由机制支持以下功能：
| 功能 | 说明 |
|------|------|
| 子命令识别 | 解析如 `orchard status`、`wheat init` 等子命令 |
| 参数传递 | 将用户参数原样传递给目标工具 |
| 错误处理 | 识别无效命令并提供友好的错误提示 |
| 帮助路由 | 将 `--help` 请求路由到对应工具的帮助系统 |
路由层的设计遵循**无状态原则**——每个路由请求都是独立的，不依赖前一个请求的状态。这使得路由层能够高效处理并发请求，同时简化了测试和调试过程。
当用户执行子命令时，路由器会验证目标工具是否已安装。如果工具未安装，路由器会提示用户通过包管理器安装相应工具，或提供直接使用 npx 运行工具的备选方案。
资料来源：[lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)
资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/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](https://github.com/grainulation/grainulation/blob/main/lib/ecosystem.js)
资料来源：[lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/lib/doctor.js)
## 包管理集成
### lib/pm.js
`lib/pm.js` 实现了 Grainulation 工具的包管理功能。它封装了 npm 的核心操作，提供统一的接口用于安装、更新和卸载 grainulation 工具包。
包管理功能支持以下操作：
| 操作 | 命令 | 说明 |
|------|------|------|
| 安装 | `pm install ` | 安装指定工具包 |
| 卸载 | `pm uninstall ` | 移除已安装工具包 |
| 更新 | `pm update ` | 更新到最新版本 |
| 列表 | `pm list` | 显示已安装工具包 |
包管理器与生态系统层紧密集成，当安装新工具时会自动触发生态系统健康检查，确保新工具与现有工具版本兼容。
### lib/setup.js
`lib/setup.js` 负责首次运行设置和配置初始化。它检测用户环境，生成必要的配置文件，并引导用户完成初始配置流程。
首次设置流程包括以下步骤：
1. **环境检测**：验证 Node.js 版本和必需工具
2. **目录创建**：初始化配置目录和数据存储位置
3. **配置生成**：创建默认配置文件
4. **欢迎引导**：展示快速开始指南和下一步建议
设置模块会检查 `~/.grainulation/` 目录是否存在，如果不存在则自动创建。该目录用于存储用户级别的配置和跨项目共享的数据。
资料来源：[lib/pm.js](https://github.com/grainulation/grainulation/blob/main/lib/pm.js)
资料来源：[lib/setup.js](https://github.com/grainulation/grainulation/blob/main/lib/setup.js)
## 发布流程与工具协调
### 统一发布机制
Grainulation 生态系统采用集中式发布策略，所有工具包通过统一的 GitHub Actions 工作流发布。每个包在其自己的仓库中维护，但发布流程由 grainulation 的发布规范协调。
发布架构遵循以下原则：
- **独立版本控制**：每个工具包维护自己的语义化版本号
- **自动化发布**：通过标签推送触发 CI/CD 流程
- **可信发布**：使用 npm OIDC 信任发布，无需 API token
资料来源：[RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)
### 单包发布流程
对于单包补丁发布，流程如下：
```mermaid
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](https://github.com/grainulation/grainulation/blob/main/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 数据结构。这种设计确保了工具间协作的无缝性。
```mermaid
graph LR
WHEAT[Wheat
收集声明] --> CLAIMS[claims.json
统一声明存储]
FARMER[Farmer
权限管理] --> CLAIMS
CLAIMS --> MILL[Mill
导出格式转换]
CLAIMS --> HARVEST[Harvest
跨冲刺分析]
CLAIMS --> SILO[Silo
统一查询]
CLAIMS --> ORCHARD[Orchard
状态汇总]
BARN[Barn
SSE通信] -.->|实时更新| FARMER
BARN -.->|事件通知| WHEAT
```
声明（Claim）是 Grainulation 系统的核心数据单元，每个声明包含：
| 字段 | 说明 |
|------|------|
| id | 声明唯一标识符（如 r001、x001） |
| type | 类型：factual、risk、estimate、constraint、recommendation |
| tier | 证据等级：从"有人说过"到"生产环境测量" |
| content | 声明内容文本 |
| evidence | 支持证据列表 |
| challenges | 挑战记录列表 |
| timestamp | 创建时间戳 |
资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)
## 测试与验证
### 基本测试框架
Grainulation 使用 Node.js 内置测试运行器进行基本功能验证。测试文件位于 `test/basic.test.js`，通过以下命令执行：
```bash
node test/basic.test.js
```
测试覆盖范围包括：
- CLI 入口点参数解析
- 命令路由正确性
- 工具发现机制
- 配置文件生成
- 健康检查流程
### CI/CD 集成
每个工具包都配置了 GitHub Actions 工作流进行持续集成。CI 流程自动运行测试套件，确保代码变更不会破坏现有功能。
发布前的工作流检查项目：
1. 单元测试通过
2. 集成测试通过
3. 代码覆盖率达标
4. 版本号一致性验证
5. npm 发布签名验证
资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
## 配置与自定义
### 全局配置
Grainulation 在 `~/.grainulation/` 目录中存储用户级配置。配置采用 JSON 格式，支持以下自定义项：
```json
{
"registry": "https://registry.npmjs.org/",
"telemetry": false,
"theme": "default",
"editor": "vim"
}
```
### 项目级配置
每个 Wheat 冲刺包含独立的配置文件 `wheat.config.json`，存储冲刺特定的设置，如约束条件、参与者信息和决策标准。
### 环境变量
Grainulation 支持通过环境变量进行高级配置：
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `GRAINULATION_HOME` | 配置目录路径 | `~/.grainulation/` |
| `GRAINULATION_REGISTRY` | npm 注册表地址 | npmjs.org |
| `GRAINULATION_DEBUG` | 启用调试模式 | false |
## 故障排除
### 常见问题
| 问题 | 原因 | 解决方案 |
|------|------|----------|
| 命令未找到 | 工具包未安装 | 运行 `npx @grainulation/ help` |
| Node 版本过低 | Node.js < 20 | 升级到 Node.js 20+ |
| 权限错误 | 配置目录不可写 | 检查目录权限或重新创建 |
| 发布失败 | 标签版本不匹配 | 确保 package.json 版本与标签一致 |
### 诊断命令
使用 doctor 工具进行系统诊断：
```bash
node bin/grainulation.js doctor
```
诊断工具会逐步检查环境并提供修复建议。
## 扩展与贡献
### 添加新工具
要将新工具集成到 Grainulation 生态系统，需要：
1. 创建独立的 npm 包 `@grainulation/`
2. 在 grainulation 的路由配置中注册新工具
3. 更新生态系统健康检查以包含新工具
4. 添加相应的文档和测试
### 贡献流程
贡献代码的标准流程：
1. Fork 仓库并创建功能分支
2. 进行代码修改并编写测试
3. 运行 `node test/basic.test.js` 验证
4. 提交并推送变更
5. 创建 Pull Request 供审查
所有贡献者应遵循项目的行为准则，确保社区健康持续发展。
资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
---
## 健康检查与诊断
### 相关页面
相关主题：[CLI命令参考](#page-cli-commands), [故障排除](#page-troubleshooting)
相关源码文件
以下源码文件用于生成本页说明：
- [lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/lib/doctor.js)
- [bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)
- [lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/lib/ecosystem.js)
- [lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)
- [lib/setup.js](https://github.com/grainulation/grainulation/blob/main/lib/setup.js)
# 健康检查与诊断
Grainulation 生态系统的健康检查与诊断功能是确保工具链可靠运行的核心模块。该模块负责验证工具安装状态、检测生态系统完整性，并提供统一的诊断入口。
## 概述
Grainulation 采用零依赖架构设计，所有健康检查功能均基于 Node.js 内置模块实现。诊断系统由多个组件协同工作，包括 `doctor.js` 诊断工具、生态系统健康检查模块以及统一的 CLI 路由层。资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
### 核心职责
健康检查与诊断模块承担以下核心职责：
| 模块 | 职责描述 |
|------|----------|
| 诊断工具 | 验证各工具包的安装状态，检测配置完整性 |
| 健康检查 | 监控生态系统整体健康状态，发现工具缺失 |
| 路由分发 | 将诊断命令正确路由至对应工具 |
| 配置验证 | 检查 wheat.config.json 等配置文件有效性 |
资料来源：[CONTRIBUTING.md:lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
## 系统架构
健康检查与诊断系统采用分层架构设计，从 CLI 入口到具体诊断模块逐层传递。
```mermaid
graph TD
A[bin/grainulation.js
CLI 入口] --> B[lib/router.js
命令路由]
B --> C[lib/doctor.js
诊断工具]
B --> D[lib/ecosystem.js
生态系统]
C --> E[工具安装验证]
C --> F[配置文件检查]
D --> G[健康状态检查]
D --> H[工具发现]
```
### 各层组件说明
**CLI 入口层**
`bin/grainulation.js` 是整个生态系统的统一 CLI 入口点，负责接收用户命令并路由至正确的工具。该文件不依赖任何外部包，直接使用 Node.js 内置模块实现基础功能。资料来源：[CONTRIBUTING.md:bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
**命令路由层**
`lib/router.js` 负责将诊断相关命令分发至对应的处理模块。路由层会根据命令类型判断是执行诊断检查还是其他工具操作。资料来源：[CONTRIBUTING.md:lib/router.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
**诊断执行层**
`lib/doctor.js` 是核心诊断工具，执行以下验证操作：
- 验证 grainulation 工具链中各包的安装状态
- 检查 Node.js 版本兼容性
- 检测 wheat.config.json 配置文件是否存在且有效
- 扫描所有八个工具包的健康状态
资料来源：[CONTRIBUTING.md:lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
**生态系统层**
`lib/ecosystem.js` 负责整个生态系统的健康检查和工具发现功能。该模块会枚举已安装的工具包，并生成生态系统状态报告。资料来源：[CONTRIBUTING.md:lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
## 诊断工具详解
### doctor.js 核心功能
诊断工具提供三类核心检查能力：
| 检查类型 | 检查内容 | 输出格式 |
|----------|----------|----------|
| 安装验证 | 验证 @grainulation/* 包是否正确安装 | 状态列表 |
| 版本检查 | 确认 Node.js 版本是否满足要求 | 版本兼容性报告 |
| 配置校验 | 检查项目级配置文件完整性 | 配置文件状态 |
### 检查流程
```mermaid
graph TD
A[启动诊断] --> B{Node.js 版本检查}
B -->|版本过低| C[输出警告]
B -->|版本兼容| D[检查工具安装]
D --> E{工具包是否存在}
E -->|缺失| F[标记待安装]
E -->|完整| G[验证配置文件]
G --> H[生成诊断报告]
```
### 错误处理机制
诊断工具采用渐进式错误报告策略。当检测到问题时，系统不会立即终止，而是收集所有问题后统一输出，确保用户能一次性了解所有待修复项。资料来源：[CONTRIBUTING.md:lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
## 生态系统健康检查
### 健康检查范围
`lib/ecosystem.js` 提供的健康检查覆盖以下维度：
1. **工具发现** - 自动检测系统中已安装的 grainulation 工具
2. **状态监控** - 实时追踪各工具的运行状态
3. **依赖关系** - 验证工具间的依赖完整性
4. **版本一致性** - 确保生态系统内版本同步
资料来源：[CONTRIBUTING.md:lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
### 工具清单
Grainulation 生态系统包含以下八个工具：
| 工具名称 | 用途 | 包名 |
|----------|------|------|
| wheat | 研究与决策工作流主工具 | @grainulation/wheat |
| farmer | AI 代理权限管理 | @grainulation/farmer |
| mill | 导出与发布工具 | @grainulation/mill |
| silo | 知识库管理 | @grainulation/silo |
| orchard | 统一 CLI 协调 | @grainulation/orchard |
| barn | 共享基础工具 | @grainulation/barn |
| harvest | 分析与学习 | @grainulation/harvest |
| grainulation | 元工具与路由 | grainulation |
资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)
## 配置与设置
### 首次运行设置
`lib/setup.js` 负责首次运行时的初始化配置，包括：
- 创建必要的目录结构
- 初始化默认配置文件
- 验证 Node.js 环境
- 设置本地诊断基准
资料来源：[CONTRIBUTING.md:lib/setup.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
### 配置文件结构
诊断系统依赖以下配置文件：
```json
{
"wheat.config.json": "项目级工具配置",
"claims.json": "研究声明存储",
".grainulation/": "本地生态系统配置目录"
}
```
## 使用方式
### 快速诊断
用户可通过以下命令启动诊断检查：
```bash
npx grainulation doctor
```
### 生态系统状态
查看完整生态系统健康状态：
```bash
npx grainulation status
```
### 详细诊断报告
生成包含所有工具包的详细诊断报告：
```bash
npx grainulation doctor --verbose
```
## 诊断结果解读
### 状态代码
| 状态码 | 含义 | 后续操作 |
|--------|------|----------|
| OK | 工具正常安装，配置有效 | 无需操作 |
| WARN | 发现潜在问题 | 建议检查警告内容 |
| ERROR | 关键组件缺失 | 需要安装缺失组件 |
| PENDING | 配置待完成 | 完成初始化设置 |
### 常见问题处理
**工具包缺失**
当诊断报告指示工具包未安装时，可使用 `lib/pm.js` 包管理模块进行安装。资料来源：[CONTRIBUTING.md:lib/pm.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
**Node.js 版本不兼容**
Grainulation 要求 Node.js 20 或更高版本。检查当前版本：
```bash
node --version
```
**配置文件损坏**
删除现有配置并重新初始化：
```bash
npx grainulation setup --reset
```
## 技术实现细节
### 零依赖原则
健康检查与诊断模块严格遵循零依赖原则，所有功能基于 Node.js 内置模块实现：
- `fs` 模块 - 文件系统操作
- `path` 模块 - 路径处理
- `child_process` - 子进程管理
- `crypto` - 哈希校验
资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)
### 本地服务器
诊断结果可通过 `lib/server.mjs` 提供的本地 Web 界面展示。该服务器使用 ESM 模块格式，提供统一的生态系统仪表板视图。资料来源：[CONTRIBUTING.md:lib/server.mjs](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
## 相关链接
- 官方文档：https://grainulation.com
- 工具状态页：https://orchard.grainulation.com/
- 仓库地址：https://github.com/grainulation/grainulation
---
## 开发环境配置
### 相关页面
相关主题：[安装指南](#page-installation), [健康检查与诊断](#page-doctor)
相关源码文件
以下源码文件用于生成本页说明：
- [bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)
- [lib/setup.js](https://github.com/grainulation/grainulation/blob/main/lib/setup.js)
- [lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/lib/doctor.js)
- [lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/lib/ecosystem.js)
- [lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)
- [lib/pm.js](https://github.com/grainulation/grainulation/blob/main/lib/pm.js)
- [CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
- [README.md](https://github.com/grainulation/grainulation/blob/main/README.md)
# 开发环境配置
## 概述
Grainulation 是一个基于 Node.js 的技术决策研究工具生态系统，其开发环境配置采用零依赖设计理念，仅使用 Node.js 内置模块完成所有功能。整个开发环境围绕 CLI 工具链构建，核心目标是提供一套轻量、可审计的本地化研究流程，帮助团队将技术问题转化为带有类型和置信度评级的结构化声明（claims）。
开发环境配置模块主要负责以下几个核心功能：工具链初始化、环境健康检查、依赖管理、以及命令路由分发。资料来源：[CONTRIBUTING.md]()
## 核心组件架构
### 组件职责矩阵
| 组件文件 | 核心职责 | 依赖关系 |
|---------|---------|---------|
| `bin/grainulation.js` | CLI 入口点，命令路由分发 | router.js |
| `lib/router.js` | 命令路由到具体工具包 | ecosystem.js |
| `lib/ecosystem.js` | 生态系统健康检查与工具发现 | doctor.js |
| `lib/doctor.js` | 诊断工具，验证工具安装状态 | 无外部依赖 |
| `lib/setup.js` | 首次运行配置与初始化 | pm.js |
| `lib/pm.js` | 工具包管理 | 无外部依赖 |
### 系统架构图
```mermaid
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]()
### 基础安装
```bash
# 全局安装主工具
npm install -g @grainulation/grainulation
# 或直接使用 npx 运行
npx @grainulation/grainulation
```
### 初始化配置流程
```mermaid
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]()
### 可用命令列表
| 命令 | 功能描述 | 入口文件 |
|-----|---------|---------|
| `grainulation` | 生态系统概览 | bin/grainulation.js |
| `grainulation doctor` | 健康检查 | lib/doctor.js |
| `grainulation setup` | 首次配置 | lib/setup.js |
| `grainulation wheat init` | 初始化研究冲刺 | wheat 包 |
| `grainulation farmer start` | 启动权限仪表板 | farmer 包 |
| `grainulation orchard status` | 编排状态 | orchard 包 |
资料来源：[README.md]()
## 环境健康检查
### doctor.js 诊断功能
`lib/doctor.js` 是 Grainulation 的诊断工具，用于验证本地开发环境的完整性和工具安装状态。该模块执行以下检查：
1. **Node.js 版本验证**：确认当前版本是否满足 20.x+ 要求
2. **工具包检测**：扫描已安装的 grainulation 工具包
3. **配置完整性检查**：验证配置文件是否存在且格式正确
4. **路径环境检查**：确认 `npx` 可访问
### doctor 输出示例
```bash
$ 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 支持根据用户角色进行差异化配置：
| 角色 | 推荐工具组合 | 使用场景 |
|-----|------------|---------|
| 研究员 | wheat, barn | 独立研究、快速验证 |
| 团队负责人 | wheat, barn, mill, harvest | 团队协作、决策汇报 |
| 全栈 | wheat, farmer, orchard | AI 辅助开发、权限管理 |
资料来源：[lib/setup.js]()
## 包管理机制
### pm.js 工具包管理
`lib/pm.js` 是 Grainulation 的内部包管理器，负责：
1. **工具发现**：扫描 `~/.grainulation/tools/` 目录下的已安装工具
2. **版本检查**：比较本地版本与 npm 注册表版本
3. **按需安装**：使用 `npx` 懒加载未安装的工具
4. **依赖隔离**：每个工具包完全独立，无共享依赖
### 工具包安装流程
```mermaid
graph LR
A[用户请求工具] --> B{pm.js 检测}
B -->|已安装| C[直接调用]
B -->|未安装| D[npx 懒加载]
D --> E[临时安装到缓存]
E --> F[执行工具]
F --> G[缓存保留供后续使用]
```
资料来源：[lib/pm.js]()
## 测试环境配置
### 基本测试
Grainulation 使用 Node.js 内置的测试运行器，无需额外安装测试框架。测试文件位于 `test/` 目录。
```bash
# 运行基础测试
node test/basic.test.js
```
### 测试覆盖范围
| 测试模块 | 测试内容 | 源码映射 |
|---------|---------|---------|
| CLI 入口测试 | 命令行参数解析 | bin/grainulation.js |
| 路由测试 | 命令分发逻辑 | lib/router.js |
| 诊断测试 | 健康检查准确性 | lib/doctor.js |
| 配置测试 | 配置文件生成 | lib/setup.js |
资料来源：[CONTRIBUTING.md]()
## 开发调试
### 本地调试模式
```bash
# 直接运行本地源码
node bin/grainulation.js --help
# 带调试输出运行
DEBUG=grainulation:* node bin/grainulation.js doctor
```
### 源码修改工作流
1. **克隆仓库**：
```bash
git clone https://github.com/grainulation/grainulation.git
cd grainulation
```
2. **创建功能分支**：
```bash
git checkout -b feature/description
```
3. **修改代码**
4. **运行测试**：
```bash
node test/basic.test.js
```
5. **提交并推送**
资料来源：[CONTRIBUTING.md]()
## 配置文件
### 配置文件位置
Grainulation 使用以下配置文件位置：
| 文件类型 | 位置 | 用途 |
|---------|-----|-----|
| 用户配置 | `~/.grainulation/config.json` | 全局用户偏好设置 |
| 工具配置 | `~/.grainulation/tools/` | 各工具的独立配置 |
| 缓存 | `~/.grainulation/cache/` | 临时数据和下载缓存 |
| 冲刺数据 | `./sprints/` | 研究冲刺的工作目录 |
### 配置示例
```json
{
"version": "1.0.0",
"role": "researcher",
"tools": ["wheat", "barn"],
"preferences": {
"editor": "code",
"gitAutoCommit": true
}
}
```
## 常见问题排查
### 环境问题诊断表
| 问题现象 | 可能原因 | 解决方案 |
|---------|---------|---------|
| 命令未找到 | Node.js PATH 配置错误 | 重新安装 Node.js 或检查 PATH |
| 工具加载失败 | npx 缓存损坏 | 运行 `npx clear-npx-cache` |
| 配置文件错误 | JSON 格式错误 | 检查 `~/.grainulation/config.json` |
| 权限错误 | 目录不可写 | 检查 `~/.grainulation/` 权限 |
### 诊断命令
```bash
# 完整环境诊断
grainulation doctor
# 检查 Node 版本
node --version
# 检查 npx 可用性
npx --version
```
## 技术实现细节
### 零依赖设计原则
Grainulation 的所有模块均使用 Node.js 内置模块实现，不依赖任何外部 npm 包。这一设计带来以下优势：
- **安全性**：无第三方依赖意味着无供应链攻击风险
- **可移植性**：任何装有 Node.js 20+ 的环境可直接运行
- **稳定性**：不受上游包版本变更影响
- **轻量化**：安装包体积最小化
### 内置模块使用情况
| 模块 | 用途 |
|-----|-----|
| `fs` | 文件读写、目录扫描 |
| `path` | 路径处理、跨平台兼容 |
| `url` | URL 解析、npx 命令构造 |
| `child_process` | 子进程管理、命令执行 |
| `os` | 操作系统信息、临时目录 |
资料来源：[lib/ecosystem.js]()
## 总结
Grainulation 的开发环境配置以简洁和零依赖为核心设计原则，通过模块化的架构实现了工具发现、健康检查、按需加载等关键功能。开发者只需确保 Node.js 20+ 环境即可开始使用，无需复杂的安装流程或依赖管理。这种设计使 Grainulation 成为技术决策研究中可靠、可审计且易于部署的工具选择。
---
## 故障排除
### 相关页面
相关主题：[健康检查与诊断](#page-doctor), [开发环境配置](#page-setup)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/grainulation/grainulation/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)
- [RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)
- [site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)
# 故障排除
Grainulation 生态系统提供了内置的诊断和排查机制，帮助用户快速定位并解决工具安装、配置和环境相关的问题。由于整个项目采用零依赖设计（仅使用 Node.js 内置模块），故障排查主要依赖于 `doctor` 命令和 `setup` 命令提供的诊断信息。
## 诊断工具概述
Grainulation 的故障排查体系由以下核心组件构成：
| 组件 | 文件路径 | 功能 |
|------|----------|------|
| `doctor.js` | `lib/doctor.js` | 诊断工具，验证各工具的安装状态 |
| `ecosystem.js` | `lib/ecosystem.js` | 生态系统健康检查和工具发现 |
| `setup.js` | `lib/setup.js` | 首次运行设置和配置管理 |
| `router.js` | `lib/router.js` | 命令路由，将请求分发至正确工具 |
资料来源：[CONTRIBUTING.md:28-34]()
## 诊断命令详解
### grainulation doctor
`doctor` 命令是 Grainulation 生态系统的健康检查工具，用于验证已安装工具的状态和版本信息。
**使用方式：**
```bash
grainulation doctor
```
**功能说明：**
- 检查哪些工具已安装
- 验证各工具的版本号
- 报告缺失或过时的工具
- 提供生态系统整体健康状态报告
资料来源：[README.md:48](), [site/index.html]()
### grainulation setup
`setup` 命令用于首次运行时的工具配置和安装引导。
**使用方式：**
```bash
grainulation setup
```
**功能说明：**
- 根据用户角色安装对应工具
- 配置必要的环境参数
- 初始化配置文件（如 `wheat.config.json`）
资料来源：[README.md:47](), [CONTRIBUTING.md:35]()
## 诊断流程图
```mermaid
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 对运行环境有明确要求，在排查问题时首先应确认以下条件：
| 要求 | 最低版本 | 检查命令 |
|------|----------|----------|
| Node.js | 20+ | `node --version` |
| npx | 最新版 | `npx --version` |
| Claude Code | 需安装 | 需单独配置 |
资料来源：[site/index.html]()
### 常见环境问题
1. **Node.js 版本过低**
- 症状：运行时报语法错误或模块未找到
- 解决：升级至 Node.js 20 或更高版本
2. **缺少 Claude Code**
- 部分高级功能需要 Claude Code 支持
- 详情参阅 [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code)
## 工具安装问题排查
### 通过 npm 全局安装
```bash
npm install -g @grainulation/grainulation
```
### 通过 npx 直接运行
```bash
npx @grainulation/wheat init
npx @grainulation/farmer start
npx @grainulation/harvest analyze ./sprints/
```
资料来源：[README.md:37-41]()
### 常见安装问题
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 找不到命令 | 未正确安装 | 重新运行 `npm install -g` |
| 版本不匹配 | npm 缓存问题 | 清除缓存 `npm cache clean --force` |
| 权限错误 | 全局安装需要权限 | 使用 `sudo` 或配置 npm prefix |
## 生态系统健康诊断
Grainulation 的生态系统包含八个独立工具，每个工具都可能需要单独诊断：
| 工具 | 命令 | 功能 |
|------|------|------|
| wheat | `wheat init` | 研究引擎，生成结构化证据 |
| farmer | `farmer start` | 权限仪表板 |
| mill | `mill export` | 导出工具 |
| silo | `silo` | 知识管理 |
| harvest | `harvest analyze` | 跨迭代学习分析 |
| orchard | `orchard status` | 状态管理 |
| barn | `barn` | 本地服务器 |
| grainulation | `grainulation` | 统一 CLI |
资料来源：[README.md:55-62]()
## 发布与测试相关问题
RELEASE.md 描述了完整的发布流程，当构建失败时可参考以下步骤：
### CI/CD 故障排查
发布工作流位于 `.github/workflows/publish.yml`，测试脚本位于 `test/basic.test.js`。
```bash
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
---
---
## Doramagic 踩坑日志
项目：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