{
"canonical_name": "grainulation/grainulation",
"compilation_id": "pack_e627af9f48524540a5f3e8accb598f46",
"created_at": "2026-05-13T14:18:22.492326+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npm install -g @grainulation/grainulation` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npm install -g @grainulation/grainulation",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_20a563c146634081b10eed5cbc634b42"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_573c88ef6562c2ba86d3e602a59f25f3",
"canonical_name": "grainulation/grainulation",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/grainulation/grainulation",
"slug": "grainulation",
"source_packet_id": "phit_40ba55d02e974661a35ff776715452aa",
"source_validation_id": "dval_5c0769632ff947e08b65a16f9a24f853"
},
"merchandising": {
"best_for": "需要信息检索与知识管理能力，并使用 mcp_host的用户",
"github_forks": 1,
"github_stars": 6,
"one_liner_en": "The grainulation ecosystem. Structured research, decision-making, and knowledge management for AI agents.",
"one_liner_zh": "The grainulation ecosystem. Structured research, decision-making, and knowledge management for AI agents.",
"primary_category": {
"category_id": "research-knowledge",
"confidence": "high",
"name_en": "Research & Knowledge",
"name_zh": "信息检索与知识管理",
"reason": "matched_keywords:research, knowledge, search"
},
"target_user": "使用 mcp_host 等宿主 AI 的用户",
"title_en": "grainulation",
"title_zh": "grainulation 能力包",
"visible_tags": [
{
"label_en": "Knowledge Retrieval",
"label_zh": "知识检索",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-knowledge-retrieval",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_40ba55d02e974661a35ff776715452aa",
"page_model": {
"artifacts": {
"artifact_slug": "grainulation",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npm install -g @grainulation/grainulation",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/grainulation/grainulation#readme",
"verified": true
}
],
"display_tags": [
"知识检索",
"知识库问答",
"流程自动化",
"节点式流程编排",
"本地优先"
],
"eyebrow": "信息检索与知识管理",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要信息检索与知识管理能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "The grainulation ecosystem. Structured research, decision-making, and knowledge management for AI agents."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1184031176 | https://github.com/grainulation/grainulation | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1184031176 | https://github.com/grainulation/grainulation | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1184031176 | https://github.com/grainulation/grainulation | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:1184031176 | https://github.com/grainulation/grainulation | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1184031176 | https://github.com/grainulation/grainulation | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 — Security Hardening",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_5e8c2578dd024d369fd769a7c23df98a | https://github.com/grainulation/grainulation/releases/tag/v1.1.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.1.0 — Security Hardening",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1184031176 | https://github.com/grainulation/grainulation | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1184031176 | https://github.com/grainulation/grainulation | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 1,
"forks": 1,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 6
},
"source_url": "https://github.com/grainulation/grainulation",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "The grainulation ecosystem. Structured research, decision-making, and knowledge management for AI agents.",
"title": "grainulation 能力包",
"trial_prompt": "# grainulation - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 grainulation 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: The grainulation ecosystem. Structured research, decision-making, and knowledge management for AI agents. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-quickstart：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n4. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-cli-commands：CLI命令参考。围绕“CLI命令参考”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-quickstart\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-cli-commands\n输入：用户提供的“CLI命令参考”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-quickstart：Step 3 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-architecture：Step 4 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-cli-commands：Step 5 必须围绕“CLI命令参考”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/grainulation/grainulation\n- https://github.com/grainulation/grainulation#readme\n- README.md\n- docs/ecosystem.md\n- package.json\n- lib/setup.js\n- bin/grainulation.js\n- lib/router.js\n- lib/server.mjs\n- lib/ecosystem.js\n- lib/doctor.js\n- lib/pm.js\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 grainulation 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_release: v1.1.0 — Security Hardening（https://github.com/grainulation/grainulation/releases/tag/v1.1.0）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_release",
"source": "github",
"title": "v1.1.0 — Security Hardening",
"url": "https://github.com/grainulation/grainulation/releases/tag/v1.1.0"
}
],
"status": "已收录 1 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "信息检索与知识管理",
"desc": "The grainulation ecosystem. Structured research, decision-making, and knowledge management for AI agents.",
"effort": "安装已验证",
"forks": 1,
"icon": "search",
"name": "grainulation 能力包",
"risk": "需复核",
"slug": "grainulation",
"stars": 6,
"tags": [
"知识检索",
"知识库问答",
"流程自动化",
"节点式流程编排",
"本地优先"
],
"thumb": "blue",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/grainulation/grainulation 项目说明书\n\n生成时间：2026-05-13 12:30:20 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [安装指南](#page-installation)\n- [快速开始](#page-quickstart)\n- [系统架构](#page-architecture)\n- [CLI命令参考](#page-cli-commands)\n- [生态系统概览](#page-ecosystem)\n- [工具集成与协作](#page-tools-integration)\n- [健康检查与诊断](#page-doctor)\n- [开发环境配置](#page-setup)\n- [故障排除](#page-troubleshooting)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [生态系统概览](#page-ecosystem), [快速开始](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/grainulation/grainulation/blob/main/README.md)\n- [site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n \n\n# 项目概述\n\n## 项目简介\n\n**grainulation** 是一个结构化技术决策研究生态系统，旨在将技术问题转化为带类型的、有证据等级支撑的声明（claims）。该项目并非传统的文档生成工具或 RFC/ADR 模板系统，而是一套完整的**研究-质疑-编译**工作流工具。\n\n核心定位：帮助团队从\"凭直觉做决策\"转变为\"基于可验证证据做决策\"。\n\n资料来源：[README.md:1-10]()\n\n## 核心概念\n\n### 声明（Claims）\n\ngrainulation 的所有工作都围绕**声明（claims）**展开。每个声明具有以下属性：\n\n| 属性 | 说明 | 示例 |\n|------|------|------|\n| 类型 | 声明的语义类别 | factual（事实）、risk（风险）、estimate（估算）、constraint（约束）、recommendation（建议） |\n| 证据等级 | 证据的可靠程度 | 从\"有人说\"到\"生产环境测量\" |\n| 引用来源 | 证据的出处 | 文档、测试、生产数据等 |\n\n> \"Everything in grainulation starts with a claim — a single typed statement with an evidence grade.\"\n> 资料来源：[site/index.html:1]()\n\n### 编译器（Compiler）\n\n编译器是 grainulation 的核心验证引擎：\n\n- **确定性**：基于 JavaScript 代码实现（非 LLM 调用），相同输入产生相同输出\n- **冲突检测**：识别并标记相互矛盾的声明\n- **证据验证**：检查证据等级是否满足要求\n- **门控机制**：在问题未解决前阻止输出\n\n> \"The compiler is JavaScript code, not an LLM call. Same claims in, same result out, every time.\"\n> 资料来源：[site/index.html:1]()\n\n## 工具生态概览\n\ngrainulation 由 8 个独立的 CLI 工具组成，每个工具专注于单一职责。\n\n| 工具 | 功能定位 | 安装命令 | 文档链接 |\n|------|----------|----------|----------|\n| **wheat** | 研究引擎，生成结构化证据 | `npx @grainulation/wheat init` | [wheat](https://github.com/grainulation/wheat) |\n| **farmer** | 权限仪表盘，审批 AI 代理的工具调用 | `npx @grainulation/farmer start` | [farmer](https://github.com/grainulation/farmer) |\n| **mill** | 导出与发布，生成 PDF、CSV、静态站点 | `npx @grainulation/mill export --format pdf` | [mill](https://github.com/grainulation/mill) |\n| **barn** | 共享工具库，Sprint 检测、清单生成、HTML 模板 | `npx @grainulation/barn detect-sprints` | [barn](https://github.com/grainulation/barn) |\n| **orchard** | 编排工具，路由到正确工具、检查生态健康 | `npx grainulation` | [orchard](https://github.com/grainulation/orchard) |\n| **harvest** | 分析工具，跨 Sprint 学习、追踪预测准确性 | `npx @grainulation/harvest analyze ./sprints/` | [harvest](https://github.com/grainulation/harvest) |\n| **silo** | 存储工具，结构化数据持久化 | `npx @grainulation/silo store` | [silo](https://github.com/grainulation/silo) |\n| **grainulation** | 统一 CLI入口 | `npx grainulation` | 主仓库 |\n\n资料来源：[README.md:36-44]()\n\n## 工作流程\n\ngrainulation 采用 **研究-质疑-编译** 的三阶段工作流：\n\n```mermaid\ngraph TD\n A[\"❓ 提出问题
例：是否应将微服务迁移回模块化单体？\"] --> B[\"1️⃣ 初始化 Sprint
wheat init\"]\n B --> C[\"claims.json 创建
wheat.config.json 就绪\"]\n C --> D[\"2️⃣ 研究与质疑\"]\n D --> E[\"wheat research 收集证据\"]\n E --> F[\"生成 typed claims
r001 [factual|documented]\"]\n F --> G[\"wheat challenge 压力测试\"]\n G --> H[\"生成风险声明
x001 [risk|documented]\"]\n H --> I[\"3️⃣ 编译与交付\"]\n I --> J[\"wheat brief 编译决策简报\"]\n J --> K[\"冲突已解决
output/brief.html 生成\"]\n K --> L[\"✅ 决策简报包含完整 git 审计轨迹\"]\n```\n\n### 各阶段说明\n\n**阶段 1：初始化**\n- 使用 `wheat init` 命令创建研究 Sprint\n- 自动生成 `claims.json`（声明存储）和 `wheat.config.json`（配置）\n\n**阶段 2：研究与质疑**\n- `/research` 命令用于收集特定主题的证据\n- `/challenge` 命令用于对已有声明进行对抗性测试\n- 所有发现都转化为带类型和证据等级的声明\n\n**阶段 3：编译与交付**\n- `/brief` 命令触发编译器\n- 编译器检测冲突、验证证据等级\n- 输出结构化决策简报（HTML 格式）\n\n> \"Research that compiles.\"\n> 资料来源：[site/index.html:1]()\n\n## 技术特性\n\n### 零依赖设计\n\ngrainulation 生态系统的核心原则之一是**零 npm 依赖**：\n\n| 特性 | 说明 |\n|------|------|\n| 仅使用 Node.js 内置模块 | 无外部依赖包 |\n| 无供应链风险 | 不依赖第三方包的安全性 |\n| 无 API 密钥需求 | 核心工具无需配置认证信息 |\n| 纯本地运行 | 所有数据处理在本地完成 |\n| 纯 JSON + HTML 输出 | 易于集成到现有工作流 |\n\n> \"Zero npm dependencies across all eight packages. No supply chain anxiety. No left-pad.\"\n> 资料来源：[site/index.html:1]()\n\n### 四大设计原则\n\n| 原则 | 说明 | 相关特性 |\n|------|------|----------|\n| **声明优于观点** | 每个发现都是有类型、有等级、可追溯的声明 ID | \"I think\" → 声明 ID + 证据等级 |\n| **对抗性压力** | 系统强制用户质疑、见证、压力测试每个声明 | 舒适的一致性是良好决策的大敌 |\n| **零依赖** | 仅使用 Node.js 内置模块 | 纯本地运行，无外部依赖 |\n| **确定性编译** | 编译器是 JavaScript 代码，非 LLM | 相同输入，相同输出 |\n\n> \"Comfortable agreement is the enemy of good decisions. The system forces you to challenge, witness, and stress-test every claim.\"\n> 资料来源：[site/index.html:1]()\n\n## 系统架构\n\n```mermaid\ngraph TD\n subgraph \"用户层\"\n A[\"用户/团队\"]\n end\n \n subgraph \"工具层 (CLI)\"\n B[\"wheat - 研究\"]\n C[\"farmer - 权限\"]\n D[\"mill - 导出\"]\n E[\"barn - 共享库\"]\n F[\"harvest - 分析\"]\n end\n \n subgraph \"编排层\"\n G[\"orchard - 统一入口\"]\n end\n \n subgraph \"数据层\"\n H[\"claims.json\"]\n I[\"wheat.config.json\"]\n J[\"sprints/ 目录\"]\n end\n \n subgraph \"编译器层\"\n K[\"Compiler
冲突检测
证据验证
门控机制\"]\n end\n \n A --> G\n G --> B\n G --> C\n G --> D\n G --> E\n G --> F\n \n B --> H\n B --> I\n H --> K\n I --> K\n K --> L[\"output/brief.html\"]\n \n style G fill:#9ca3af,color:#000\n style K fill:#fbbf24,color:#000\n style H fill:#6ee7b7,color:#000\n```\n\n## 安装与快速开始\n\n### 环境要求\n\n| 依赖 | 版本要求 |\n|------|----------|\n| Node.js | 20+ |\n| npx | 最新版本 |\n| Claude Code（可选） | 用于 AI 辅助研究 |\n| Git | 用于审计轨迹追踪 |\n\n### 安装方式\n\n```bash\n# 全局安装\nnpm install -g @grainulation/grainulation\n\n# 或直接使用 npx（无需安装）\nnpx @grainulation/wheat init\n```\n\n### 快速命令\n\n```bash\ngrainulation # 生态系统概览\ngrainulation doctor # 健康检查：工具列表、版本\ngrainulation setup # 为当前角色安装合适的工具\ngrainulation wheat init # 委托给 wheat 工具\ngrainulation farmer start # 启动权限仪表盘\n```\n\n资料来源：[README.md:21-29]()\n\n## 与传统方法的区别\n\n| 维度 | RFC/ADR | grainulation |\n|------|---------|--------------|\n| 文档性质 | 决策后记录 | 研究过程捕获 |\n| 证据管理 | 手动整理 | 结构化声明 + 证据等级 |\n| 对抗性测试 | 可选 | 内置强制机制 |\n| 冲突处理 | 人工发现 | 编译器自动检测 |\n| 审计轨迹 | 依赖 git 历史 | 内置完整证据链 |\n\n> \"RFCs and ADRs document a decision after it is made. Grainulation captures the research process — evidence gathering, adversarial testing, and conflict resolution.\"\n> 资料来源：[site/index.html:1]()\n\n## 输出产物\n\n执行 `wheat brief` 后的输出包含：\n\n- **决策简报**：结构化 HTML 文档\n- **声明清单**：所有收集的声明及其状态\n- **冲突报告**：未解决的矛盾说明\n- **证据摘要**：每条声明的来源和等级\n- **Git 审计轨迹**：完整的数据收集和质疑历史\n\n---\n\n\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart), [开发环境配置](#page-setup)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/grainulation/grainulation/blob/main/README.md)\n- [site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n- [RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)\n \n\n# 安装指南\n\n## 概述\n\nGrainulation 是一个由八个独立 CLI 工具组成的生态系统，旨在将技术问题转化为带有类型和证据等级的声明（claims），最终生成可审计的决策简报。整个项目遵循**零 npm 依赖**原则，全部基于 Node.js 原生内置模块构建，所有工具均在本地运行，无需云服务或 API 密钥。\n\n本安装指南涵盖完整的环境准备、各工具的安装方式以及不同使用场景下的推荐配置。\n\n## 系统要求\n\n| 组件 | 最低版本 | 说明 |\n|------|----------|------|\n| Node.js | 20+ | 核心运行时环境 |\n| npm | 内置 | 用于全局安装或本地依赖管理 |\n| npx | 内置 | 用于直接执行远程包 |\n| Claude Code | 最新版 | 用于执行研究任务的 AI 代理 |\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n> **重要提示**：核心工具（如 wheat）的编译器部分**不需要 API 密钥**。所有数据处理均在本地完成，不涉及任何云服务调用。\n\n## 安装模式\n\nGrainulation 提供两种主要安装模式，用户可根据实际需求选择。\n\n### 模式一：全局安装（推荐长期使用）\n\n全局安装适合需要频繁使用工具链的场景，一次安装后可在任意目录下直接调用：\n\n```bash\nnpm install -g @grainulation/grainulation\n```\n\n安装完成后，可以通过统一的入口工具 `grainulation` 调用所有子命令：\n\n```bash\ngrainulation # 查看生态系统概览\ngrainulation doctor # 健康检查：已安装工具列表及版本\ngrainulation setup # 根据角色安装所需工具\ngrainulation wheat init # 委托给 wheat 工具初始化研究 sprint\ngrainulation farmer start # 启动权限仪表板\n```\n\n资料来源：[README.md](https://github.com/grainulation/grainulation/blob/main/README.md)\n\n### 模式二：按需执行（零安装）\n\n对于偶尔使用或临时探索的场景，可以直接使用 `npx` 跳过安装步骤，按需下载并执行：\n\n```bash\nnpx @grainulation/wheat init # 直接初始化研究 sprint\nnpx @grainulation/farmer start # 启动权限仪表板\nnpx @grainulation/mill export --format pdf # 导出决策简报为 PDF\nnpx @grainulation/harvest analyze ./sprints/ # 分析历史 sprint 数据\n```\n\n这种模式的优势在于**无需预先安装任何依赖**，每次执行都会获取最新版本。\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n## 工具生态概览\n\nGrainulation 包含八个独立工具，每个工具专注于特定功能领域：\n\n| 工具 | 功能域 | 核心用途 | 安装命令 |\n|------|--------|----------|----------|\n| wheat | 研究引擎 | 增长结构化证据，管理声明 | `npx @grainulation/wheat init` |\n| farmer | 权限仪表板 | 审批 AI 代理的工具调用请求 | `npx @grainulation/farmer start` |\n| barn | 共享基础库 | Sprint 检测、清单生成、HTML 模板 | `npx @grainulation/barn detect-sprints` |\n| mill | 导出与发布 | 生成 PDF、CSV、静态站点等格式 | `npx @grainulation/mill export --format pdf` |\n| silo | 沙箱隔离 | 为 AI 代理提供安全的代码执行环境 | `npx @grainulation/silo sandbox` |\n| harvest | 分析与洞察 | 跨 sprint 学习，追踪预测准确率 | `npx @grainulation/harvest analyze ./sprints/` |\n| orchard | 编排层 | 工作流编排，跨工具协调 | `npx @grainulation/orchard status` |\n| grainulation | 统一 CLI | 生态系统总入口，配置管理 | `npm install -g @grainulation/grainulation` |\n\n资料来源：[README.md](https://github.com/grainulation/grainulation/blob/main/README.md)\n\n## 快速开始工作流\n\n对于新用户，建议按照以下三步流程完成首次研究 sprint：\n\n```mermaid\ngraph TD\n A[初始化 Sprint
npx @grainulation/wheat init] --> B[研究与质疑
收集证据, 挑战声明]\n B --> C[编译与交付
生成决策简报]\n C --> D[输出 brief.html
可导出为 PDF/CSV]\n```\n\n### 步骤一：初始化 Sprint\n\n```bash\nnpx @grainulation/wheat init\n```\n\n执行后将创建两个核心文件：\n\n- `claims.json` — 存储所有声明的清单文件\n- `wheat.config.json` — 工具配置文件\n\n```bash\n$ npx @grainulation/wheat init\n\nSprint initialized.\nclaims.json created (0 claims)\nwheat.config.json ready\n```\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n### 步骤二：研究与质疑\n\n在 wheat 交互式环境中使用以下命令：\n\n```bash\nwheat> /research \"topic\" # 收集关于指定主题的研究证据\nwheat> /challenge r001 # 质疑指定声明，触发对抗性测试\n```\n\n声明将以统一格式输出：\n\n```\nr001 [factual|documented] ...\nx001 [risk|documented] ...\n```\n\n### 步骤三：编译与交付\n\n```bash\nwheat> /brief\n```\n\n编译器将执行以下验证：\n\n1. 解析所有声明及关联证据\n2. 检测声明间的矛盾冲突\n3. 标记证据等级不足的声明\n4. 阻止输出直至所有问题解决\n5. 生成包含完整 git 审计轨迹的决策简报\n\n```bash\nCompiled 12 claims (2 conflicts resolved)\nWritten: output/brief.html\n```\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n## 环境健康检查\n\n安装完成后，可使用以下命令验证工具链状态：\n\n```bash\ngrainulation doctor\n```\n\n该命令将检测：\n\n- 已安装的工具列表及版本号\n- Node.js 版本兼容性\n- 各工具间的依赖关系状态\n\n## 权限仪表板安装\n\nFarmer 是用于审批 AI 代理工具调用的实时仪表板，特别适合团队协作场景：\n\n```bash\nnpx @grainulation/farmer start\n```\n\n启动后支持以下功能：\n\n- 通过手机、另一浏览器标签页或会议期间审批请求\n- 实时 SSE（Server-Sent Events）推送\n- **零依赖**设计，不引入额外包\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n## 离线与私有部署\n\n由于 Grainulation 整个生态系统的设计原则是**零 npm 依赖**（仅使用 Node.js 内置模块），部署到私有环境或离线场景非常直接：\n\n1. 将整个仓库克隆至目标机器\n2. 确保 Node.js 20+ 已安装\n3. 通过 `npx` 或本地 `node` 直接运行各工具入口脚本\n\n```bash\ngit clone https://github.com/grainulation/grainulation.git\ncd grainulation\nnode wheat/bin/index.js init # 直接执行，跳过 npm 查找\n```\n\n## 常见问题\n\n### Q：是否需要注册账户或获取 API 密钥？\n\n不需要。核心工具（wheat、barn、mill 等）**完全本地运行**，不连接任何外部服务。唯一需要 API 密钥的是与 AI 代理（Claude Code）的交互，由用户自行管理。\n\n### Q：是否支持 Yarn、pnpm 等其他包管理器？\n\nGrainulation 主包 `@grainulation/grainulation` 支持通过 npm 全局安装。对于子工具，推荐使用 `npx` 方式执行以确保版本一致性。\n\n### Q：可以安装单个工具而不安装整个生态吗？\n\n可以。八个工具相互独立，按需安装即可：\n\n```bash\nnpm install -g @grainulation/wheat\nnpm install -g @grainulation/mill\n# 等等...\n```\n\n### Q：安装后如何获取更新？\n\n- 全局安装：`npm update -g @grainulation/grainulation`\n- npx 方式：每次执行自动获取最新版本\n\n## 相关资源\n\n- 项目官网：https://grainulation.com\n- 官方文档：各工具独立维护的文档站点\n- GitHub 仓库：https://github.com/grainulation/grainulation\n- npm 包页面：https://www.npmjs.com/package/@grainulation/grainulation\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[CLI命令参考](#page-cli-commands), [生态系统概览](#page-ecosystem)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/grainulation/grainulation/blob/main/README.md)\n- [site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n- [CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n- [bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)\n- [lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)\n \n\n# 快速开始\n\n## 概述\n\n快速开始是 Grainulation 生态系统的入口点，旨在帮助用户在 60 秒内启动一个技术决策研究冲刺（Sprint）。整个流程设计遵循\"三条命令，一个决策\"的原则，无需安装、无需注册、无需配置 API Key，只需 `npx` 和一个问题即可开始。\n\n资料来源：[site/index.html:1]()\n\n## 前置要求\n\n在开始使用 Grainulation 之前，请确保满足以下环境要求：\n\n| 要求 | 版本 | 说明 |\n|------|------|------|\n| Node.js | 20+ | 仅使用 Node.js 内置模块 |\n| npx | 最新版 | 用于直接运行包 |\n| Claude Code | 可选 | 用于 AI 辅助研究 |\n| npm | 最新版 | 用于全局安装 |\n\nGrainulation 的核心理念是**零依赖**——所有八个包均不使用任何 npm 依赖项，完全基于 Node.js 内置模块构建，不存在供应链安全风险。\n\n资料来源：[README.md:1]()\n\n## 安装方式\n\nGrainulation 提供两种安装方式，用户可根据使用场景选择：\n\n### 全局安装\n\n适合经常使用 Grainulation 的用户：\n\n```bash\nnpm install -g @grainulation/grainulation\n```\n\n全局安装后，可以直接使用 `grainulation` 命令：\n\n```bash\ngrainulation # 生态系统概览\ngrainulation doctor # 健康检查：工具列表和版本\ngrainulation setup # 安装适合角色的工具\ngrainulation farmer start # 启动权限仪表板\n```\n\n### 直接运行（推荐）\n\n适合临时使用或首次体验的用户：\n\n```bash\nnpx @grainulation/wheat init\n```\n\n这种方式无需安装任何内容，直接通过 npx 拉取并执行包。\n\n资料来源：[README.md:1]()\n\n## 三步工作流程\n\nGrainulation 的快速开始流程分为三个阶段：初始化、研究与挑战、编译发布。\n\n### 步骤一：初始化冲刺\n\n使用 `wheat` 工具初始化一个新的研究冲刺。系统会提示你输入问题、受众和约束条件：\n\n```bash\nnpx @grainulation/wheat init\n```\n\n执行后将创建两个文件：\n\n| 文件 | 用途 |\n|------|------|\n| `claims.json` | 存储所有声明（Claims）的文件 |\n| `wheat.config.json` | 配置文件 |\n\n初始化输出示例：\n\n```\nSprint initialized.\nclaims.json created (0 claims)\nwheat.config.json ready\n```\n\n资料来源：[site/index.html:1]()\n\n### 步骤二：研究与挑战\n\n在研究阶段，你需要收集证据并对每个发现进行压力测试。所有发现都会成为带有类型和等级的声明（Claims）。\n\nwheat 命令行工具提供两个核心命令：\n\n```bash\nwheat> /research \"topic\" # 收集关于某个主题的证据\nwheat> /challenge r001 # 挑战已有的声明\n```\n\n声明具有以下属性：\n\n| 属性 | 可选值 | 说明 |\n|------|--------|------|\n| 类型 | factual, risk, estimate, constraint, recommendation | 声明的语义类型 |\n| 等级 | documented, measured, peer-reviewed 等 | 证据强度等级 |\n| 状态 | active, challenged, resolved | 当前状态 |\n\n挑战声明后，系统会生成新的风险声明（以 `x` 前缀标识）：\n\n```\nr001 [factual|documented] ... # 原始声明\nx001 [risk|documented] ... # 由挑战产生的风险声明\n```\n\n资料来源：[site/index.html:1]()\n\n### 步骤三：编译并发布\n\n当研究完成且冲突已解决后，使用编译命令生成决策简报：\n\n```bash\nwheat> /brief\n```\n\n编译器的工作流程：\n\n```mermaid\ngraph TD\n A[输入 Claims] --> B{检查冲突}\n B -->|存在冲突| C[阻止输出]\n B -->|无冲突| D{检查证据强度}\n D -->|证据不足| E[标记弱证据]\n D -->|证据充分| F[生成决策简报]\n E --> C\n F --> G[output/brief.html]\n```\n\n编译器输出示例：\n\n```\nCompiled 12 claims (2 conflicts resolved)\nWritten: output/brief.html\n```\n\n决策简报具有完整的 Git 审计跟踪功能，记录每个声明的收集方式和挑战过程。\n\n资料来源：[site/index.html:1]()\n\n## 工作流程图\n\n整个 Grainulation 生态系统的工作流程如下：\n\n```mermaid\ngraph LR\n A[问题] --> B[w:heat 初始化]\n B --> C[w:heat 研究]\n C --> D[w:heat 挑战]\n D --> E{编译器检查}\n E -->|通过| F[o:rchard 状态]\n E -->|失败| C\n F --> G[m:ill 导出]\n G --> H[决策简报]\n \n H --> I[h:arvest 分析]\n I --> J[跨冲刺学习]\n```\n\n## 生态工具概览\n\nGrainulation 由八个独立的工具组成，每个工具负责特定功能：\n\n| 工具 | 用途 | 安装命令 |\n|------|------|----------|\n| [wheat](https://github.com/grainulation/wheat) | 研究引擎，构建结构化证据 | `npx @grainulation/wheat init` |\n| [farmer](https://github.com/grainulation/farmer) | 权限仪表板，审批 AI 代理工具调用 | `npx @grainulation/farmer start` |\n| [barn](https://github.com/grainulation/barn) | 共享工具库，冲刺检测和清单生成 | `npx @grainulation/barn detect-sprints` |\n| [mill](https://github.com/grainulation/mill) | 导出工具，生成 PDF、CSV、静态站点 | `npx @grainulation/mill export --format pdf` |\n| [silo](https://github.com/grainulation/silo) | 文档存储，可搜索的结构化声明存档 | `npx @grainulation/silo search` |\n| [orchard](https://github.com/grainulation/orchard) | 编排工具，路由和生态系统健康检查 | `npx @grainulation/orchard status` |\n| [harvest](https://github.com/grainulation/harvest) | 分析工具，预测准确性和系统盲点追踪 | `npx @grainulation/harvest analyze ./sprints/` |\n| grainulation | 统一 CLI，元工具路由 | `npx @grainulation/grainulation` |\n\n资料来源：[README.md:1]()\n\n## 项目架构\n\nGrainulation 作为元包和生态系统路由器，其架构如下：\n\n```\nbin/grainulation.js # CLI 入口点 - 路由到各工具包\nlib/router.js # 命令路由，将请求分发到正确工具\nlib/ecosystem.js # 生态系统健康检查和工具发现\nlib/doctor.js # 诊断工具 - 验证工具安装状态\nlib/setup.js # 首次运行设置和配置\nlib/pm.js # grainulation 工具的包管理\nlib/server.mjs # 本地服务器 - 统一生态系统仪表板\npublic/ # Web UI - 生态系统概览和状态\nsite/ # 公开网站\ntest/ # Node 内置测试运行器\n```\n\n关键架构原则：所有工具均通过统一的 CLI 接口路由，用户只需记住 `grainulation` 一个入口点即可访问整个生态系统。\n\n资料来源：[CONTRIBUTING.md:1]()\n\n## 常见问题\n\n### 需要 Node.js 吗？\n\n是的，Grainulation 是一个 Node.js 工具，需要 Node.js 20 或更高版本。它不使用任何外部依赖，仅使用 Node.js 内置模块。\n\n### 与 RFC/ADR 有何不同？\n\nRFC 和 ADR 在决策完成后记录决策。Grainulation 捕获研究过程——证据收集、对抗性测试和冲突解决——并通过编译器进行验证。输出的简报可作为 ADR 使用，具有完整的 Git 审计跟踪，显示每个声明是如何收集、挑战和解决的。\n\n### 数据存储在哪里？\n\n所有数据都存储在本地 JSON 文件中。没有云服务、没有账户、没有 API 密钥。决策简报是静态 HTML 文件，可部署到任何静态托管服务。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [CLI命令参考](#page-cli-commands), [工具集成与协作](#page-tools-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)\n- [lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)\n- [lib/server.mjs](https://github.com/grainulation/grainulation/blob/main/lib/server.mjs)\n- [lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/lib/ecosystem.js)\n- [lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/lib/doctor.js)\n- [lib/setup.js](https://github.com/grainulation/grainulation/blob/main/lib/setup.js)\n- [lib/pm.js](https://github.com/grainulation/grainulation/blob/main/lib/pm.js)\n \n\n# 系统架构\n\n## 概述\n\nGrainulation 是一个元包（meta-package）和生态系统路由器，它编排所有 Grainulation 工具并提供统一的 CLI 入口点。该项目的核心理念是**零依赖**——整个生态系统完全基于 Node.js 内置模块构建，不使用任何 npm 依赖项。\n\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 架构设计原则\n\nGrainulation 遵循以下核心架构原则：\n\n| 原则 | 描述 | 实现方式 |\n|------|------|----------|\n| 零依赖 | 整个生态系统无 npm 依赖 | 仅使用 Node.js 内置模块 |\n| 统一入口 | 所有工具通过单一 CLI 路由 | `bin/grainulation.js` 作为主入口 |\n| 本地优先 | 所有数据和处理在本地运行 | 无需 API 密钥或云服务 |\n| 生态系统协调 | 统一的健康检查和工具发现 | `lib/ecosystem.js` 负责 |\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n## 核心组件架构\n\n### 组件层次结构\n\n```mermaid\ngraph TD\n subgraph 入口层\n CLI[bin/grainulation.js
CLI 入口点]\n end\n \n subgraph 核心库\n Router[lib/router.js
命令路由]\n Ecosystem[lib/ecosystem.js
生态系统健康检查]\n Doctor[lib/doctor.js
诊断工具]\n Setup[lib/setup.js
首次运行配置]\n PM[lib/pm.js
包管理]\n end\n \n subgraph 服务层\n Server[lib/server.mjs
本地服务器]\n end\n \n subgraph 前端层\n Public[public/
Web UI]\n Site[site/
公共网站]\n end\n \n CLI --> Router\n Router --> Ecosystem\n Router --> Doctor\n Router --> Setup\n Router --> PM\n Server --> Public\n Server --> Ecosystem\n```\n\n### 各组件职责\n\n| 组件文件 | 职责 | 模块类型 |\n|----------|------|----------|\n| `bin/grainulation.js` | CLI 入口点，路由到各个独立工具包 | CommonJS |\n| `lib/router.js` | 命令路由，将请求分发到正确的工具包 | CommonJS |\n| `lib/ecosystem.js` | 生态系统健康检查和工具发现 | CommonJS |\n| `lib/doctor.js` | 诊断工具，验证工具安装状态 | CommonJS |\n| `lib/setup.js` | 首次运行设置和配置 | CommonJS |\n| `lib/pm.js` | Grainulation 工具的包管理功能 | CommonJS |\n| `lib/server.mjs` | 本地服务器，提供统一生态系统仪表板 | ESM |\n\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 命令路由机制\n\n### 路由流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant CLI as bin/grainulation.js\n participant Router as lib/router.js\n participant Tool as 目标工具包\n \n User->>CLI: node bin/grainulation.js [command]\n CLI->>Router: 解析命令参数\n Router->>Router: 识别工具类型\n Router->>Tool: 路由到对应工具\n Tool-->>User: 返回执行结果\n```\n\n### 工具生态系统\n\nGrainulation 由八个独立工具组成，每个工具专注于特定功能：\n\n| 工具名称 | 颜色标识 | 功能领域 | 用途 |\n|----------|----------|----------|------|\n| **wheat** | 金色 (#fbbf24) | 研究引擎 | 初始化 sprint、研究、挑战、编译决策 |\n| **farmer** | 蓝色 (#3b82f6) | 权限仪表板 | 审批 AI 代理的工具调用请求 |\n| **barn** | 红色 (#f43f5e) | 知识存储 | 持久化存储和管理研究数据 |\n| **mill** | 紫色 (#a78bfa) | 导出发布 | 将研究编译为 PDF、CSV、静态站点 |\n| **silo** | 青色 (#22d3ee) | 共享存储 | 团队间共享和协作研究 |\n| **harvest** | 橙色 (#fb923c) | 分析统计 | 跨 sprint 学习，追踪预测准确性 |\n| **orchard** | 棕色 (#d4a574) | 编排协调 | 跨工具协调和工作流管理 |\n| **grainulation** | 灰色 (#9ca3af) | 统一 CLI | 元工具，路由到各工具并管理配置 |\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n## 生态系统健康检查\n\n`lib/ecosystem.js` 负责维护整个工具生态系统的健康状态：\n\n### 健康检查流程\n\n```mermaid\ngraph LR\n A[启动检查] --> B{工具已安装?}\n B -->|是| C[检查版本]\n C --> D{版本匹配?}\n D -->|是| E[工具可用]\n D -->|否| F[提示更新]\n B -->|否| G[安装工具]\n G --> E\n E --> H[生态系统就绪]\n```\n\n### 工具发现机制\n\n生态系统通过以下方式发现和验证工具：\n\n1. **本地注册表检查**：扫描已安装的 `@grainulation/*` 包\n2. **版本兼容性验证**：确保工具版本与 grainulation 主包兼容\n3. **依赖链验证**：检查工具间的依赖关系是否满足\n\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 本地服务器架构\n\n`lib/server.mjs` 是使用 ESM 模块格式的本地服务器：\n\n### 服务器特性\n\n| 特性 | 描述 |\n|------|------|\n| 模块格式 | ESM (ECMAScript Modules) |\n| 功能 | 提供统一的生态系统仪表板 |\n| 前端资源 | `public/` 目录下的 Web UI |\n| 实时更新 | 支持 SSE (Server-Sent Events) 实时通信 |\n\n### 服务架构\n\n```mermaid\ngraph TD\n subgraph 服务层\n Server[lib/server.mjs
ESM 服务器]\n end\n \n subgraph 前端资源\n UI[public/
静态资源]\n Dashboard[生态系统仪表板]\n end\n \n Server --> UI\n Server --> Dashboard\n Server --> SSE[SSE 实时更新]\n \n subgraph 数据流\n API[内部 API]\n Health[健康检查数据]\n end\n \n Server --> API\n API --> Health\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 测试架构\n\n### 测试框架\n\nGrainulation 使用 Node.js 内置测试运行器：\n\n| 测试文件 | 描述 |\n|----------|------|\n| `test/basic.test.js` | 基本功能测试 |\n\n### 测试执行\n\n```bash\nnode test/basic.test.js\n```\n\n测试覆盖以下核心功能：\n- CLI 命令解析\n- 路由功能验证\n- 生态系统健康检查\n\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 发布工作流架构\n\n### 发布流程\n\n```mermaid\ngraph LR\n A[代码变更] --> B[版本升级]\n B --> C[npm version patch]\n C --> D[提交 + 标签]\n D --> E[git push --follow-tags]\n E --> F[触发 Actions]\n F --> G{测试通过?}\n G -->|是| H[验证 package.json]\n G -->|否| I[发布失败]\n H --> J[发布到 npm]\n J --> K[OIDC 信任发布]\n K --> L[生成 Provenance]\n```\n\n### 发布配置\n\n| 配置项 | 值 |\n|--------|-----|\n| 工作流文件 | `.github/workflows/publish.yml` |\n| 认证方式 | OIDC 信任发布 (无需 NPM_TOKEN) |\n| 平台 | npmjs.com |\n| 徽章 | \"Built + Signed\" 链接回工作流运行 |\n\n### 协调发布流程\n\n当消费者依赖新的内部功能时：\n\n1. **首先发布依赖包**（如 `barn`）\n2. **等待 npm 发布完成**（约 60 秒）\n3. **在消费者仓库执行 `npm install`** 更新 package-lock.json\n4. **提交锁文件更新**\n5. **按顺序发布各消费者包**\n\n资料来源：[RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)\n\n## 数据流总览\n\n```mermaid\ngraph TD\n subgraph 用户交互层\n CLI[CLI 命令行]\n WebUI[Web 界面]\n end\n \n subgraph 入口处理\n Entry[bin/grainulation.js]\n end\n \n subgraph 核心处理\n Router[路由层
lib/router.js]\n Ecosystem[生态层
lib/ecosystem.js]\n Doctor[诊断层
lib/doctor.js]\n Setup[配置层
lib/setup.js]\n PM[包管理层
lib/pm.js]\n end\n \n subgraph 工具层\n Wheat[wheat]\n Farmer[farmer]\n Barn[barn]\n Mill[mill]\n Silo[silo]\n Harvest[harvest]\n Orchard[orchard]\n end\n \n subgraph 存储层\n LocalData[本地数据]\n CloudData[云存储]\n end\n \n CLI --> Entry\n WebUI --> Entry\n Entry --> Router\n Router --> Ecosystem\n Router --> Doctor\n Router --> Setup\n Router --> PM\n Ecosystem --> Wheat\n Ecosystem --> Farmer\n Ecosystem --> Barn\n Ecosystem --> Mill\n Ecosystem --> Silo\n Ecosystem --> Harvest\n Ecosystem --> Orchard\n Barn --> LocalData\n Silo --> CloudData\n```\n\n## 技术栈总结\n\n| 层面 | 技术选择 | 理由 |\n|------|----------|------|\n| 运行时 | Node.js 20+ | 核心运行要求 |\n| CLI 框架 | 原生参数解析 | 零依赖原则 |\n| 模块系统 | CommonJS + ESM 混合 | 兼容性考虑 |\n| 测试框架 | Node.js 内置测试 | 无外部依赖 |\n| 发布平台 | npm (OIDC) | 现代化 CI/CD |\n| 包管理 | npx | 即开即用 |\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n---\n\n\n\n## CLI命令参考\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [健康检查与诊断](#page-doctor), [开发环境配置](#page-setup)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)\n- [lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)\n- [lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/lib/ecosystem.js)\n- [lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/lib/doctor.js)\n- [lib/pm.js](https://github.com/grainulation/grainulation/blob/main/lib/pm.js)\n- [lib/setup.js](https://github.com/grainulation/grainulation/blob/main/lib/setup.js)\n- [lib/server.mjs](https://github.com/grainulation/grainulation/blob/main/lib/server.mjs)\n \n\n# CLI命令参考\n\n本文档详细介绍 grainulation 生态系统中统一 CLI 的所有命令、功能和使用方式。\n\n## 概述\n\ngrainulation 是 grainulation 工具生态系统的元包和统一入口点，负责协调所有 grainulation 工具并提供统一的 CLI 入口。CLI 架构遵循简单路由模式，将命令分发到各个独立工具包执行。资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 架构设计\n\ngrainulation CLI 采用模块化架构，核心组件协同工作以提供统一的命令行体验。\n\n```mermaid\ngraph TD\n A[bin/grainulation.js
CLI入口点] --> B[lib/router.js
命令路由]\n A --> C[lib/ecosystem.js
生态系统健康检查]\n A --> D[lib/doctor.js
诊断工具]\n B --> E[@grainulation/wheat
研究工具]\n B --> F[@grainulation/farmer
权限仪表盘]\n B --> G[@grainulation/barn
共享工具]\n B --> H[其他工具包...]\n C --> I[npm registry
工具发现]\n D --> J[本地安装验证]\n F --> K[server.mjs
本地服务器]\n```\n\n### 核心文件职责\n\n| 文件路径 | 职责 | 功能描述 |\n|---------|------|---------|\n| `bin/grainulation.js` | CLI入口点 | 解析命令行参数，路由到正确工具 |\n| `lib/router.js` | 命令路由 | 将命令分发到独立工具包执行 |\n| `lib/ecosystem.js` | 生态系统管理 | 健康检查和工具发现 |\n| `lib/doctor.js` | 诊断工具 | 验证工具安装状态 |\n| `lib/pm.js` | 包管理 | grainulation 工具的包管理 |\n| `lib/setup.js` | 首次设置 | 首次运行配置和初始化 |\n| `lib/server.mjs` | 本地服务器 | 统一的生态系统仪表盘（ESM） |\n\n## 命令行接口\n\n### 基本用法\n\n```bash\nnpx grainulation [command] [options]\n```\n\n### 全局选项\n\n| 选项 | 描述 | 默认值 |\n|------|------|--------|\n| `--help, -h` | 显示帮助信息 | - |\n| `--version, -v` | 显示版本号 | - |\n| `--json` | 以JSON格式输出 | false |\n\n### 帮助命令\n\n```bash\ngrainulation --help\n```\n\n显示所有可用命令和选项的完整帮助信息。\n\n## 子命令详解\n\n### 1. doctor - 诊断命令\n\ndoctor 命令用于验证 grainulation 工具的本地安装状态，检查每个工具包的健康状况。\n\n```bash\ngrainulation doctor [options]\n```\n\n**功能说明**\n\n- 验证各工具包的安装完整性\n- 检查 Node.js 版本兼容性\n- 报告缺失或损坏的工具包\n- 提供修复建议\n\n**可用选项**\n\n| 选项 | 描述 |\n|------|------|\n| `--fix` | 自动修复发现的问题 |\n| `--json` | 输出JSON格式诊断结果 |\n\n### 2. doctor 命令工作流程\n\n```mermaid\ngraph TD\n A[grainulation doctor] --> B{检查Node.js版本}\n B -->|版本过低| C[警告: 需要Node.js 20+]\n B -->|版本符合| D[检查工具包目录]\n D --> E{扫描@scope/@grainulation/*}\n E -->|发现包| F[验证package.json]\n E -->|无包| G[提示安装工具]\n F --> H{package.json完整?}\n H -->|是| I[工具状态: 健康]\n H -->|否| J[工具状态: 损坏]\n I --> K[生成诊断报告]\n J --> K\n```\n\n### 3. pm - 包管理命令\n\npm 命令提供 grainulation 工具生态系统的包管理功能。\n\n```bash\ngrainulation pm [subcommand] [options]\n```\n\n**子命令**\n\n| 子命令 | 描述 |\n|--------|------|\n| `install` | 安装指定工具包 |\n| `uninstall` | 卸载指定工具包 |\n| `update` | 更新工具包到最新版本 |\n| `list` | 列出已安装的工具包 |\n| `search` | 在npm registry中搜索工具 |\n\n**install 子命令选项**\n\n| 选项 | 描述 | 示例 |\n|------|------|------|\n| `--save` | 保存到package.json依赖 | `pm install wheat --save` |\n| `--global` | 全局安装 | `pm install --global farmer` |\n| `--version` | 指定版本安装 | `pm install barn@1.3.0` |\n\n### 4. ecosystem - 生态系统命令\n\necosystem 命令用于检查整个 grainulation 工具生态系统的健康状态和可用性。\n\n```bash\ngrainulation ecosystem [options]\n```\n\n**功能说明**\n\n- 检查所有工具包的最新版本\n- 验证工具包在npm上的可用性\n- 生成生态系统健康报告\n- 检测过时工具包\n\n**输出示例**\n\n```\n生态系统健康检查\n✓ wheat@1.2.0 - 最新\n✓ farmer@0.9.5 - 最新\n⚠ barn@1.2.0 - 可用更新: 1.3.0\n✓ mill@2.1.0 - 最新\n```\n\n### 5. setup - 初始设置命令\n\nsetup 命令处理 grainulation CLI 的首次运行配置。\n\n```bash\ngrainulation setup [options]\n```\n\n**功能说明**\n\n- 创建必要的配置文件\n- 初始化本地工具缓存\n- 配置默认工具路径\n- 验证环境依赖\n\n**自动执行流程**\n\n```mermaid\ngraph LR\n A[首次运行grainulation] --> B{检测配置文件}\n B -->|不存在| C[运行setup]\n B -->|已存在| D[跳过setup]\n C --> E[创建配置目录]\n E --> F[生成grainulation.config.json]\n F --> G[验证Node.js环境]\n G --> H[完成初始化]\n```\n\n### 6. server - 本地服务器命令\n\nserver 命令启动统一的生态系统仪表盘Web界面。\n\n```bash\ngrainulation server [options]\n```\n\n**功能说明**\n\n- 启动本地HTTP服务器\n- 提供Web UI界面查看所有工具状态\n- 支持实时工具健康监控\n- 提供SSE（Server-Sent Events）实时更新\n\n**服务器选项**\n\n| 选项 | 描述 | 默认值 |\n|------|------|--------|\n| `--port, -p` | 指定服务器端口 | 3000 |\n| `--host` | 指定服务器主机 | localhost |\n| `--open` | 启动后自动打开浏览器 | false |\n\n**使用示例**\n\n```bash\n# 启动服务器\ngrainulation server\n\n# 指定端口并自动打开浏览器\ngrainulation server --port 8080 --open\n```\n\n## 工具包路由机制\n\ngrainulation CLI 的核心功能是将命令路由到正确的工具包。路由机制通过 `lib/router.js` 实现。\n\n```mermaid\ngraph TD\n A[用户输入命令] --> B[bin/grainulation.js]\n B --> C[解析命令类型]\n C --> D{是否为内置命令?}\n D -->|doctor| E[执行lib/doctor.js]\n D -->|pm| F[执行lib/pm.js]\n D -->|ecosystem| G[执行lib/ecosystem.js]\n D -->|setup| H[执行lib/setup.js]\n D -->|server| I[执行lib/server.mjs]\n D -->|其他| J[lib/router.js路由]\n J --> K[定位工具包]\n K --> L[执行工具包命令]\n L --> M[返回结果]\n```\n\n### 路由配置\n\n路由系统支持以下工具包前缀：\n\n| 前缀 | 工具包 | 用途 |\n|------|--------|------|\n| `wheat` | @grainulation/wheat | 研究和挑战工具 |\n| `farmer` | @grainulation/farmer | 权限仪表盘 |\n| `barn` | @grainulation/barn | 共享工具库 |\n| `mill` | @grainulation/mill | 导出和发布工具 |\n| `silo` | @grainulation/silo | 存储管理 |\n| `harvest` | @grainulation/harvest | 分析工具 |\n| `orchard` | @grainulation/orchard | 状态管理 |\n\n## 环境要求\n\n### Node.js版本要求\n\ngrainulation CLI 要求 **Node.js 20.0.0** 或更高版本。\n\n```bash\n# 检查Node.js版本\nnode --version\n\n# 要求版本\nnode >= 20.0.0\n```\n\n### 零依赖设计\n\ngrainulation 核心CLI包采用零npm依赖设计，完全基于Node.js内置模块构建。资料来源：[package.json](https://github.com/grainulation/grainulation/blob/main/package.json)\n\n**内置依赖使用情况**\n\n| 模块 | 用途 |\n|------|------|\n| `fs` | 文件系统操作 |\n| `path` | 路径处理 |\n| `child_process` | 子进程执行 |\n| `http`/`https` | 网络请求 |\n| `url` | URL解析 |\n| `os` | 操作系统信息 |\n\n## 配置文件\n\n### 配置文件位置\n\ngrainulation 使用以下配置文件：\n\n| 文件名 | 位置 | 用途 |\n|--------|------|------|\n| `grainulation.config.json` | 用户主目录 | 全局配置 |\n| `.grainulationrc` | 当前目录 | 项目级配置 |\n\n### 配置文件结构\n\n```json\n{\n \"version\": \"1.0.0\",\n \"tools\": {\n \"installed\": [\"wheat\", \"farmer\", \"barn\"],\n \"path\": \"~/.grainulation/tools\"\n },\n \"server\": {\n \"port\": 3000,\n \"host\": \"localhost\"\n },\n \"registry\": \"https://registry.npmjs.org/\"\n}\n```\n\n## 常见用法示例\n\n### 完整工作流程\n\n```bash\n# 1. 首次使用：检查环境健康\ngrainulation doctor\n\n# 2. 查看生态系统状态\ngrainulation ecosystem\n\n# 3. 安装所需工具\ngrainulation pm install wheat\ngrainulation pm install farmer\n\n# 4. 启动本地仪表盘\ngrainulation server --open\n\n# 5. 在另一终端使用wheat进行研究\nwheat init \"我们的系统应该使用微服务吗?\"\n```\n\n### 诊断和修复\n\n```bash\n# 诊断问题\ngrainulation doctor\n\n# 自动修复\ngrainulation doctor --fix\n\n# 查看JSON格式诊断结果\ngrainulation doctor --json\n```\n\n### 包管理操作\n\n```bash\n# 列出已安装的工具\ngrainulation pm list\n\n# 搜索可用工具\ngrainulation pm search auth\n\n# 安装特定版本\ngrainulation pm install barn@1.3.0\n\n# 更新所有工具\ngrainulation pm update\n```\n\n## 错误处理\n\n### 常见错误及解决方案\n\n| 错误代码 | 描述 | 解决方案 |\n|---------|------|---------|\n| `E_NODE_VERSION` | Node.js版本过低 | 升级到Node.js 20+ |\n| `E_TOOL_NOT_FOUND` | 工具包未安装 | 运行 `grainulation pm install ` |\n| `E_TOOL_BROKEN` | 工具包损坏 | 运行 `grainulation doctor --fix` |\n| `E_REGISTRY_UNREACHABLE` | npm registry不可达 | 检查网络连接和代理设置 |\n| `E_PERMISSION_DENIED` | 权限不足 | 使用sudo或检查文件权限 |\n\n### 调试模式\n\n启用调试模式以获取详细日志：\n\n```bash\nDEBUG=grainulation:* grainulation \n```\n\n## 与wheat工具的集成\n\ngrainulation CLI 与 `@grainulation/wheat` 工具深度集成，提供完整的研究决策流程支持。\n\n```mermaid\ngraph LR\n A[grainulation wheat] --> B[wheat init
初始化研究项目]\n B --> C[wheat /research
收集证据]\n C --> D[wheat /challenge
挑战Claims]\n D --> E[wheat /brief
编译决策简报]\n E --> F[grainulation mill
导出报告]\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 相关资源\n\n- [官方文档](https://grainulation.com)\n- [wheat工具文档](https://wheat.grainulation.com)\n- [farmer工具文档](https://farmer.grainulation.com)\n- [GitHub仓库](https://github.com/grainulation/grainulation)\n\n---\n\n\n\n## 生态系统概览\n\n### 相关页面\n\n相关主题：[工具集成与协作](#page-tools-integration), [项目概述](#page-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/grainulation/grainulation/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n- [RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)\n- [site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n \n\n# 生态系统概览\n\nGrainulation 是一个由八个零依赖 CLI 工具组成的生态系统，旨在将技术问题转化为结构化的、带类型标注的、可审计的决策声明。整个系统基于 Node.js 原生模块构建，不依赖任何外部 npm 包，实现本地化运行和可复现的决策流程。\n\n## 核心设计理念\n\nGrainulation 的核心理念源于一个观察：**大多数决策失败不是因为团队缺乏数据，而是缺乏将数据转化为证据、将证据转化为决策的过程**。系统围绕四个基本原则构建：\n\n| 原则 | 说明 |\n|------|------|\n| 证据驱动 | 每个声明都是带类型、置信度和证据等级的声明 |\n| 编译器验证 | 编译器是确定性 JavaScript 代码，而非 LLM 调用，确保相同输入产生相同输出 |\n| 对抗性挑战 | 系统强制团队挑战、见证和压力测试每个声明 |\n| 零依赖 | 全部八个包仅使用 Node.js 内置模块 |\n\n资料来源：[README.md:1-15]()\n\n## 八工具架构\n\n整个生态系统包含八个独立工具，每个工具专注于一个特定功能。以下是完整工具矩阵：\n\n| 工具名称 | 功能角色 | 核心用途 |\n|----------|----------|----------|\n| **wheat** | 研究引擎 | 增长结构化证据，创建声明文件 |\n| **farmer** | 权限仪表板 | 从手机、另一标签页或会议审批 AI 代理工具调用 |\n| **barn** | 证据存储 | 结构化存储所有研究和声明 |\n| **mill** | 导出发布 | 将编译后的研究转换为 PDF、CSV 和静态站点 |\n| **silo** | 证据验证 | 独立验证声明，检测不一致 |\n| **harvest** | 分析统计 | 跨 Sprint 学习，追踪预测准确性 |\n| **orchard** | 配置管理 | 状态面板，管理所有工具配置 |\n| **grainulation** | 统一 CLI | 元工具，路由到正确工具，检查生态系统健康状态 |\n\n资料来源：[site/index.html:140-180]()\n\n## 工具协作流程\n\n```mermaid\ngraph TD\n subgraph 研究阶段\n A[wheat init] --> B[Research & Challenge]\n B --> C[创建声明]\n C --> D[收集证据]\n end\n \n subgraph 验证阶段\n D --> E[silo 验证]\n E --> F{验证通过?}\n F -->|否| G[修复问题]\n G --> D\n end\n \n subgraph 编译阶段\n F -->|是| H[barn 存储]\n H --> I[harvest 分析]\n I --> J[mill 导出]\n end\n \n subgraph 协作阶段\n J --> K[farmer 审批]\n K --> L[orchard 管理]\n end\n \n J --> M[决策简报]\n```\n\n工具之间的依赖关系遵循特定顺序：当需要发布新版本时（如 `barn`），需要先发布被依赖的包，等待其出现在 npm 上，然后更新消费者仓库的依赖。\n\n资料来源：[RELEASE.md:1-30]()\n\n## 架构层次\n\nGrainulation 采用分层架构设计：\n\n```mermaid\ngraph TB\n subgraph 用户交互层\n A[统一 CLI: grainulation]\n B[wheat REPL]\n C[farmer Web 界面]\n end\n \n subgraph 核心库\n D[lib/router.js 路由]\n E[lib/ecosystem.js 生态系统]\n F[lib/doctor.js 诊断]\n G[lib/setup.js 配置]\n H[lib/pm.js 包管理]\n end\n \n subgraph 数据层\n I[claims.json]\n J[wheat.config.json]\n K[barn 存储]\n end\n \n A --> D\n B --> D\n C --> H\n D --> E\n D --> F\n D --> G\n E --> H\n H --> K\n F --> J\n G --> J\n```\n\n### 核心组件说明\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| CLI 入口点 | `bin/grainulation.js` | 路由到各个工具包 |\n| 命令路由 | `lib/router.js` | 将命令分发到正确的工具包 |\n| 生态系统 | `lib/ecosystem.js` | 健康检查和工具发现 |\n| 诊断工具 | `lib/doctor.js` | 验证工具安装状态 |\n| 首次设置 | `lib/setup.js` | 首次运行设置和配置 |\n| 包管理 | `lib/pm.js` | grainulation 工具的包管理 |\n\n资料来源：[CONTRIBUTING.md:20-45]()\n\n## 声明类型系统\n\nGrainulation 的核心抽象是**声明（Claim）**——一个带有类型和证据等级的单个声明语句。声明具有以下属性：\n\n| 属性 | 可选值 | 说明 |\n|------|--------|------|\n| 类型 | factual, risk, estimate, constraint, recommendation | 声明的语义类别 |\n| 证据等级 | 从\"有人说\"到\"生产环境测量\" | 证据强度 |\n| ID | r001, x001 等 | 全局唯一标识 |\n\n系统通过编译器验证声明的一致性，检测矛盾，并标记弱证据。\n\n资料来源：[site/index.html:200-220]()\n\n## 快速上手路径\n\n```mermaid\ngraph LR\n A[\"npx @grainulation/wheat init\"] --> B[初始化 Sprint]\n B --> C[Research & Challenge]\n C --> D[/brief 编译]\n D --> E[决策简报]\n \n A -.->|或者| F[\"npm install -g @grainulation/grainulation\"]\n F --> G[\"grainulation setup\"]\n G --> A\n```\n\n### 基础命令\n\n```bash\n# 生态系统概览\ngrainulation\n\n# 健康检查\ngrainulation doctor\n\n# 安装适合角色的工具\ngrainulation setup\n\n# 初始化研究 Sprint\ngrainulation wheat init\n# 或直接\nnpx @grainulation/wheat init\n```\n\n资料来源：[README.md:30-50]()\n\n## 发布与版本管理\n\n生态系统采用协调发布机制，确保包之间的依赖关系正确：\n\n```mermaid\nsequenceDiagram\n participant Dev as 开发者\n participant Barn as barn 包\n participant Consumer as 消费者包\n participant NPM as npm registry\n \n Dev->>Barn: npm version patch\n Dev->>Barn: git push --follow-tags\n Barn->>NPM: 发布 v1.2.3\n NPM-->>Dev: 发布成功\n \n Dev->>Consumer: 修改依赖版本\n Consumer->>NPM: npm install\n NPM-->>Consumer: 获取新版本 barn\n Consumer->>Consumer: 更新 package-lock.json\n```\n\n每个包通过 `.github/workflows/publish.yml` 在标签推送时自动发布，使用 npm provenance 通过 OIDC 可信发布（无需 NPM_TOKEN）。\n\n资料来源：[RELEASE.md:10-25]()\n\n## 技术约束\n\n| 约束项 | 要求 |\n|--------|------|\n| Node.js 版本 | 20+ |\n| 依赖策略 | 零 npm 依赖，仅 Node.js 内置模块 |\n| API 密钥 | 核心工具无需 API 密钥 |\n| 云服务 | 无需云服务 |\n| 运行方式 | 全部本地运行 |\n| 数据格式 | 纯 JSON 和 HTML |\n\n资料来源：[site/index.html:225-235]()\n\n## 相关文档\n\n- [wheat 工具文档](https://wheat.grainulation.com/) — 研究引擎\n- [farmer 工具文档](https://farmer.grainulation.com/) — 权限仪表板\n- [barn 工具文档](https://barn.grainulation.com/) — 证据存储\n- [mill 工具文档](https://mill.grainulation.com/) — 导出发布\n\n---\n\n\n\n## 工具集成与协作\n\n### 相关页面\n\n相关主题：[生态系统概览](#page-ecosystem), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)\n- [lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)\n- [lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/lib/ecosystem.js)\n- [lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/lib/doctor.js)\n- [lib/setup.js](https://github.com/grainulation/grainulation/blob/main/lib/setup.js)\n- [lib/pm.js](https://github.com/grainulation/grainulation/blob/main/lib/pm.js)\n- [CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n- [RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)\n \n\n# 工具集成与协作\n\n## 概述\n\nGrainulation 是一个元包（meta-package），通过统一的 CLI 入口点协调整个工具生态系统。它本身不提供核心研究功能，而是作为八个独立工具包的路由层和编排层存在。这种设计遵循单一职责原则，使每个工具（Wheat、Farmer、Barn、Mill、Silo、Harvest、Orchard）能够独立发布和演进，同时通过统一的入口点提供一致的用户体验。\n\n工具集成架构的核心目标是实现**零依赖**生态——所有工具都基于 Node.js 内置模块构建，不依赖外部 npm 包。Grainulation 作为中央协调器，负责命令路由、健康检查、工具发现和包管理等职责，使各个工具能够无缝协作。\n\n## 核心架构\n\nGrainulation 的架构采用分层设计，从上到下依次为：CLI 入口层、路由层、生态系统层和工具层。这种分层确保了各组件之间的松耦合，便于独立扩展和维护。\n\n```mermaid\ngraph TB\n subgraph \"CLI 入口层\"\n CLI[\"bin/grainulation.js
统一命令行入口\"]\n end\n \n subgraph \"路由层\"\n ROUTER[\"lib/router.js
命令路由\"]\n end\n \n subgraph \"生态系统层\"\n ECO[\"lib/ecosystem.js
健康检查与工具发现\"]\n DOCTOR[\"lib/doctor.js
诊断工具\"]\n PM[\"lib/pm.js
包管理\"]\n SETUP[\"lib/setup.js
首次配置\"]\n end\n \n subgraph \"工具层\"\n WHEAT[\"@grainulation/wheat
核心研究引擎\"]\n FARMER[\"@grainulation/farmer
权限仪表板\"]\n BARN[\"@grainulation/barn
SSE 通信\"]\n MILL[\"@grainulation/mill
导出与发布\"]\n SILO[\"@grainulation/silo
统一 CLI\"]\n HARVEST[\"@grainulation/harvest
分析工具\"]\n ORCHARD[\"@grainulation/orchard
编排工具\"]\n end\n \n CLI --> ROUTER\n ROUTER --> ECO\n ROUTER --> WHEAT\n ROUTER --> FARMER\n ROUTER --> BARN\n ROUTER --> MILL\n ROUTER --> SILO\n ROUTER --> HARVEST\n ROUTER --> ORCHARD\n ECO --> DOCTOR\n ECO --> PM\n ECO --> SETUP\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## CLI 入口点\n\n### bin/grainulation.js\n\n`bin/grainulation.js` 是整个生态系统的统一命令行入口点。它负责接收用户输入并将其路由到相应的工具包。该入口点支持 `--help` 参数来显示帮助信息，用户无需安装任何依赖即可通过 `npx grainulation` 直接运行。\n\n入口脚本的设计理念是**零安装依赖**——用户只需拥有 Node.js 20+ 和 npx 即可使用所有功能。这种设计降低了入门门槛，使用户能够快速开始技术决策研究工作。\n\nCLI 入口点采用命令路由模式，根据输入的命令参数将请求转发到具体的工具包。例如，当用户执行 `npx grainulation orchard status` 时，入口点会识别 `orchard` 子命令并将其路由到对应的工具包。\n\n### 快速启动流程\n\n用户可以通过以下命令快速启动 Grainulation 生态系统：\n\n```bash\nnode bin/grainulation.js --help\n```\n\n无需执行 `npm install` 命令，因为 grainulation 本身没有 npm 依赖。这一特性确保了工具的即开即用性。\n\n资料来源：[bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 命令路由机制\n\n### lib/router.js\n\n`lib/router.js` 是 Grainulation 的核心路由模块，负责将命令分发到正确的工具包。它解析用户输入的命令参数，识别目标工具，并将控制权传递给相应的工具模块。\n\n路由机制支持以下功能：\n\n| 功能 | 说明 |\n|------|------|\n| 子命令识别 | 解析如 `orchard status`、`wheat init` 等子命令 |\n| 参数传递 | 将用户参数原样传递给目标工具 |\n| 错误处理 | 识别无效命令并提供友好的错误提示 |\n| 帮助路由 | 将 `--help` 请求路由到对应工具的帮助系统 |\n\n路由层的设计遵循**无状态原则**——每个路由请求都是独立的，不依赖前一个请求的状态。这使得路由层能够高效处理并发请求，同时简化了测试和调试过程。\n\n当用户执行子命令时，路由器会验证目标工具是否已安装。如果工具未安装，路由器会提示用户通过包管理器安装相应工具，或提供直接使用 npx 运行工具的备选方案。\n\n资料来源：[lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 生态系统管理\n\n### lib/ecosystem.js\n\n`lib/ecosystem.js` 负责整个生态系统的健康检查和工具发现功能。它维护已安装工具的注册表，并提供接口用于检查工具的可用性和版本状态。\n\n生态系统管理器的核心职责包括：\n\n- **工具发现**：扫描已安装的 @grainulation/* 包并注册其功能\n- **健康检查**：验证每个工具包的安装完整性和版本兼容性\n- **状态报告**：汇总所有工具的运行状态并生成统一报告\n\n健康检查流程会验证每个工具的以下条件：package.json 配置完整性、入口脚本可执行性、以及必需的依赖项是否满足。通过这种主动检查机制，系统能够在用户执行命令前发现并报告潜在问题。\n\n### lib/doctor.js\n\n`lib/doctor.js` 是一个诊断工具，用于验证工具安装和问题排查。它提供交互式诊断流程，帮助用户识别和解决常见的配置问题。\n\n诊断工具会执行以下检查项目：\n\n1. Node.js 版本验证（需要 20+）\n2. npm/npx 可用性检查\n3. Grainulation 包安装状态验证\n4. 子工具包完整性检查\n5. 配置文件权限验证\n\n当检测到问题时，doctor 会提供具体的修复建议，包括需要执行的命令和配置修改步骤。\n\n资料来源：[lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/lib/ecosystem.js)\n资料来源：[lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/lib/doctor.js)\n\n## 包管理集成\n\n### lib/pm.js\n\n`lib/pm.js` 实现了 Grainulation 工具的包管理功能。它封装了 npm 的核心操作，提供统一的接口用于安装、更新和卸载 grainulation 工具包。\n\n包管理功能支持以下操作：\n\n| 操作 | 命令 | 说明 |\n|------|------|------|\n| 安装 | `pm install ` | 安装指定工具包 |\n| 卸载 | `pm uninstall ` | 移除已安装工具包 |\n| 更新 | `pm update ` | 更新到最新版本 |\n| 列表 | `pm list` | 显示已安装工具包 |\n\n包管理器与生态系统层紧密集成，当安装新工具时会自动触发生态系统健康检查，确保新工具与现有工具版本兼容。\n\n### lib/setup.js\n\n`lib/setup.js` 负责首次运行设置和配置初始化。它检测用户环境，生成必要的配置文件，并引导用户完成初始配置流程。\n\n首次设置流程包括以下步骤：\n\n1. **环境检测**：验证 Node.js 版本和必需工具\n2. **目录创建**：初始化配置目录和数据存储位置\n3. **配置生成**：创建默认配置文件\n4. **欢迎引导**：展示快速开始指南和下一步建议\n\n设置模块会检查 `~/.grainulation/` 目录是否存在，如果不存在则自动创建。该目录用于存储用户级别的配置和跨项目共享的数据。\n\n资料来源：[lib/pm.js](https://github.com/grainulation/grainulation/blob/main/lib/pm.js)\n资料来源：[lib/setup.js](https://github.com/grainulation/grainulation/blob/main/lib/setup.js)\n\n## 发布流程与工具协调\n\n### 统一发布机制\n\nGrainulation 生态系统采用集中式发布策略，所有工具包通过统一的 GitHub Actions 工作流发布。每个包在其自己的仓库中维护，但发布流程由 grainulation 的发布规范协调。\n\n发布架构遵循以下原则：\n\n- **独立版本控制**：每个工具包维护自己的语义化版本号\n- **自动化发布**：通过标签推送触发 CI/CD 流程\n- **可信发布**：使用 npm OIDC 信任发布，无需 API token\n\n资料来源：[RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)\n\n### 单包发布流程\n\n对于单包补丁发布，流程如下：\n\n```mermaid\ngraph LR\n A[进入包目录] --> B[执行 npm version patch]\n B --> C[更新 package.json 和标签]\n C --> D[推送提交和标签]\n D --> E[GitHub Actions 运行测试]\n E --> F{测试通过?}\n F -->|是| G[发布到 npm]\n F -->|否| H[终止发布]\n G --> I[验证 npm 注册表]\n```\n\n发布工作流会自动验证标签与 package.json 版本号匹配，确保发布的一致性。\n\n### 协调发布流程\n\n当工具包之间存在依赖关系时（如 barn 新版本被其他工具依赖），需要执行协调发布流程：\n\n1. **按依赖顺序发布**：先发布被依赖的包\n2. **等待 npm 同步**：等待约 60 秒让新版本同步到 npm\n3. **更新依赖包**：在消费包中执行 `npm install` 更新依赖\n4. **提交锁定文件**：将更新后的 package-lock.json 提交到仓库\n\n这种协调机制确保了生态系统内部版本的一致性，避免了依赖缺失问题。\n\n资料来源：[RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)\n\n## 工具协作模式\n\n### 核心工具：Wheat\n\nWheat 是 Grainulation 生态系统的核心研究引擎，负责启动和管理整个研究冲刺（sprint）生命周期。它是用户首先接触的工具，也是协调其他工具协作的起点。\n\nWheat 的核心命令流程：\n\n1. **初始化冲刺**：`npx @grainulation/wheat init` - 创建 claims.json 和配置文件\n2. **添加证据**：`/research \"topic\"` - 收集研究证据并生成声明\n3. **挑战证据**：`/challenge r001` - 对已有证据进行对抗性测试\n4. **生成简报**：`/brief` - 编译所有声明并生成决策文档\n\n### 权限管理：Farmer\n\nFarmer 提供实时权限仪表板功能，允许用户从手机、另一浏览器标签页或会议中批准 AI 代理的工具调用。它通过 SSE（Server-Sent Events）与 Barn 组件通信，实现实时状态同步。\n\n### 通信中枢：Barn\n\nBarn 是 SSE 通信层的实现，为 Farmer 和其他需要实时通信的工具提供基础设施。它处理事件流分发、连接管理和消息路由，确保实时交互的可靠性。\n\n### 导出工具：Mill\n\nMill 负责将编译后的研究成果导出为多种格式（PDF、CSV、静态站点），满足不同场景的分享需求。\n\n### 分析工具：Harvest\n\nHarvest 提供跨冲刺的学习分析功能，追踪预测准确性、发现系统性盲点、检测过时声明，帮助团队持续改进研究质量。\n\n### 编排工具：Orchard\n\nOrchard 是元工具（meta-tool），负责路由到正确工具、检查生态系统健康状况、管理所有八个包的配置。\n\n### 统一入口：Silo\n\nSilo 提供统一的 CLI 界面，整合所有工具的访问入口，简化多工具使用场景下的命令行操作。\n\n## 工具间数据流\n\nGrainulation 生态系统中的数据流动遵循声明式设计模式，所有工具共享统一的 claims 数据结构。这种设计确保了工具间协作的无缝性。\n\n```mermaid\ngraph LR\n WHEAT[Wheat
收集声明] --> CLAIMS[claims.json
统一声明存储]\n FARMER[Farmer
权限管理] --> CLAIMS\n CLAIMS --> MILL[Mill
导出格式转换]\n CLAIMS --> HARVEST[Harvest
跨冲刺分析]\n CLAIMS --> SILO[Silo
统一查询]\n CLAIMS --> ORCHARD[Orchard
状态汇总]\n \n BARN[Barn
SSE通信] -.->|实时更新| FARMER\n BARN -.->|事件通知| WHEAT\n```\n\n声明（Claim）是 Grainulation 系统的核心数据单元，每个声明包含：\n\n| 字段 | 说明 |\n|------|------|\n| id | 声明唯一标识符（如 r001、x001） |\n| type | 类型：factual、risk、estimate、constraint、recommendation |\n| tier | 证据等级：从\"有人说过\"到\"生产环境测量\" |\n| content | 声明内容文本 |\n| evidence | 支持证据列表 |\n| challenges | 挑战记录列表 |\n| timestamp | 创建时间戳 |\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n## 测试与验证\n\n### 基本测试框架\n\nGrainulation 使用 Node.js 内置测试运行器进行基本功能验证。测试文件位于 `test/basic.test.js`，通过以下命令执行：\n\n```bash\nnode test/basic.test.js\n```\n\n测试覆盖范围包括：\n\n- CLI 入口点参数解析\n- 命令路由正确性\n- 工具发现机制\n- 配置文件生成\n- 健康检查流程\n\n### CI/CD 集成\n\n每个工具包都配置了 GitHub Actions 工作流进行持续集成。CI 流程自动运行测试套件，确保代码变更不会破坏现有功能。\n\n发布前的工作流检查项目：\n\n1. 单元测试通过\n2. 集成测试通过\n3. 代码覆盖率达标\n4. 版本号一致性验证\n5. npm 发布签名验证\n\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 配置与自定义\n\n### 全局配置\n\nGrainulation 在 `~/.grainulation/` 目录中存储用户级配置。配置采用 JSON 格式，支持以下自定义项：\n\n```json\n{\n \"registry\": \"https://registry.npmjs.org/\",\n \"telemetry\": false,\n \"theme\": \"default\",\n \"editor\": \"vim\"\n}\n```\n\n### 项目级配置\n\n每个 Wheat 冲刺包含独立的配置文件 `wheat.config.json`，存储冲刺特定的设置，如约束条件、参与者信息和决策标准。\n\n### 环境变量\n\nGrainulation 支持通过环境变量进行高级配置：\n\n| 变量 | 说明 | 默认值 |\n|------|------|--------|\n| `GRAINULATION_HOME` | 配置目录路径 | `~/.grainulation/` |\n| `GRAINULATION_REGISTRY` | npm 注册表地址 | npmjs.org |\n| `GRAINULATION_DEBUG` | 启用调试模式 | false |\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 原因 | 解决方案 |\n|------|------|----------|\n| 命令未找到 | 工具包未安装 | 运行 `npx @grainulation/ help` |\n| Node 版本过低 | Node.js < 20 | 升级到 Node.js 20+ |\n| 权限错误 | 配置目录不可写 | 检查目录权限或重新创建 |\n| 发布失败 | 标签版本不匹配 | 确保 package.json 版本与标签一致 |\n\n### 诊断命令\n\n使用 doctor 工具进行系统诊断：\n\n```bash\nnode bin/grainulation.js doctor\n```\n\n诊断工具会逐步检查环境并提供修复建议。\n\n## 扩展与贡献\n\n### 添加新工具\n\n要将新工具集成到 Grainulation 生态系统，需要：\n\n1. 创建独立的 npm 包 `@grainulation/`\n2. 在 grainulation 的路由配置中注册新工具\n3. 更新生态系统健康检查以包含新工具\n4. 添加相应的文档和测试\n\n### 贡献流程\n\n贡献代码的标准流程：\n\n1. Fork 仓库并创建功能分支\n2. 进行代码修改并编写测试\n3. 运行 `node test/basic.test.js` 验证\n4. 提交并推送变更\n5. 创建 Pull Request 供审查\n\n所有贡献者应遵循项目的行为准则，确保社区健康持续发展。\n\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n---\n\n\n\n## 健康检查与诊断\n\n### 相关页面\n\n相关主题：[CLI命令参考](#page-cli-commands), [故障排除](#page-troubleshooting)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/lib/doctor.js)\n- [bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)\n- [lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/lib/ecosystem.js)\n- [lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)\n- [lib/setup.js](https://github.com/grainulation/grainulation/blob/main/lib/setup.js)\n \n\n# 健康检查与诊断\n\nGrainulation 生态系统的健康检查与诊断功能是确保工具链可靠运行的核心模块。该模块负责验证工具安装状态、检测生态系统完整性，并提供统一的诊断入口。\n\n## 概述\n\nGrainulation 采用零依赖架构设计，所有健康检查功能均基于 Node.js 内置模块实现。诊断系统由多个组件协同工作，包括 `doctor.js` 诊断工具、生态系统健康检查模块以及统一的 CLI 路由层。资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n### 核心职责\n\n健康检查与诊断模块承担以下核心职责：\n\n| 模块 | 职责描述 |\n|------|----------|\n| 诊断工具 | 验证各工具包的安装状态，检测配置完整性 |\n| 健康检查 | 监控生态系统整体健康状态，发现工具缺失 |\n| 路由分发 | 将诊断命令正确路由至对应工具 |\n| 配置验证 | 检查 wheat.config.json 等配置文件有效性 |\n\n资料来源：[CONTRIBUTING.md:lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 系统架构\n\n健康检查与诊断系统采用分层架构设计，从 CLI 入口到具体诊断模块逐层传递。\n\n```mermaid\ngraph TD\n A[bin/grainulation.js
CLI 入口] --> B[lib/router.js
命令路由]\n B --> C[lib/doctor.js
诊断工具]\n B --> D[lib/ecosystem.js
生态系统]\n C --> E[工具安装验证]\n C --> F[配置文件检查]\n D --> G[健康状态检查]\n D --> H[工具发现]\n```\n\n### 各层组件说明\n\n**CLI 入口层**\n\n`bin/grainulation.js` 是整个生态系统的统一 CLI 入口点，负责接收用户命令并路由至正确的工具。该文件不依赖任何外部包，直接使用 Node.js 内置模块实现基础功能。资料来源：[CONTRIBUTING.md:bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n**命令路由层**\n\n`lib/router.js` 负责将诊断相关命令分发至对应的处理模块。路由层会根据命令类型判断是执行诊断检查还是其他工具操作。资料来源：[CONTRIBUTING.md:lib/router.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n**诊断执行层**\n\n`lib/doctor.js` 是核心诊断工具，执行以下验证操作：\n\n- 验证 grainulation 工具链中各包的安装状态\n- 检查 Node.js 版本兼容性\n- 检测 wheat.config.json 配置文件是否存在且有效\n- 扫描所有八个工具包的健康状态\n\n资料来源：[CONTRIBUTING.md:lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n**生态系统层**\n\n`lib/ecosystem.js` 负责整个生态系统的健康检查和工具发现功能。该模块会枚举已安装的工具包，并生成生态系统状态报告。资料来源：[CONTRIBUTING.md:lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 诊断工具详解\n\n### doctor.js 核心功能\n\n诊断工具提供三类核心检查能力：\n\n| 检查类型 | 检查内容 | 输出格式 |\n|----------|----------|----------|\n| 安装验证 | 验证 @grainulation/* 包是否正确安装 | 状态列表 |\n| 版本检查 | 确认 Node.js 版本是否满足要求 | 版本兼容性报告 |\n| 配置校验 | 检查项目级配置文件完整性 | 配置文件状态 |\n\n### 检查流程\n\n```mermaid\ngraph TD\n A[启动诊断] --> B{Node.js 版本检查}\n B -->|版本过低| C[输出警告]\n B -->|版本兼容| D[检查工具安装]\n D --> E{工具包是否存在}\n E -->|缺失| F[标记待安装]\n E -->|完整| G[验证配置文件]\n G --> H[生成诊断报告]\n```\n\n### 错误处理机制\n\n诊断工具采用渐进式错误报告策略。当检测到问题时，系统不会立即终止，而是收集所有问题后统一输出，确保用户能一次性了解所有待修复项。资料来源：[CONTRIBUTING.md:lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 生态系统健康检查\n\n### 健康检查范围\n\n`lib/ecosystem.js` 提供的健康检查覆盖以下维度：\n\n1. **工具发现** - 自动检测系统中已安装的 grainulation 工具\n2. **状态监控** - 实时追踪各工具的运行状态\n3. **依赖关系** - 验证工具间的依赖完整性\n4. **版本一致性** - 确保生态系统内版本同步\n\n资料来源：[CONTRIBUTING.md:lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n### 工具清单\n\nGrainulation 生态系统包含以下八个工具：\n\n| 工具名称 | 用途 | 包名 |\n|----------|------|------|\n| wheat | 研究与决策工作流主工具 | @grainulation/wheat |\n| farmer | AI 代理权限管理 | @grainulation/farmer |\n| mill | 导出与发布工具 | @grainulation/mill |\n| silo | 知识库管理 | @grainulation/silo |\n| orchard | 统一 CLI 协调 | @grainulation/orchard |\n| barn | 共享基础工具 | @grainulation/barn |\n| harvest | 分析与学习 | @grainulation/harvest |\n| grainulation | 元工具与路由 | grainulation |\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n## 配置与设置\n\n### 首次运行设置\n\n`lib/setup.js` 负责首次运行时的初始化配置，包括：\n\n- 创建必要的目录结构\n- 初始化默认配置文件\n- 验证 Node.js 环境\n- 设置本地诊断基准\n\n资料来源：[CONTRIBUTING.md:lib/setup.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n### 配置文件结构\n\n诊断系统依赖以下配置文件：\n\n```json\n{\n \"wheat.config.json\": \"项目级工具配置\",\n \"claims.json\": \"研究声明存储\",\n \".grainulation/\": \"本地生态系统配置目录\"\n}\n```\n\n## 使用方式\n\n### 快速诊断\n\n用户可通过以下命令启动诊断检查：\n\n```bash\nnpx grainulation doctor\n```\n\n### 生态系统状态\n\n查看完整生态系统健康状态：\n\n```bash\nnpx grainulation status\n```\n\n### 详细诊断报告\n\n生成包含所有工具包的详细诊断报告：\n\n```bash\nnpx grainulation doctor --verbose\n```\n\n## 诊断结果解读\n\n### 状态代码\n\n| 状态码 | 含义 | 后续操作 |\n|--------|------|----------|\n| OK | 工具正常安装，配置有效 | 无需操作 |\n| WARN | 发现潜在问题 | 建议检查警告内容 |\n| ERROR | 关键组件缺失 | 需要安装缺失组件 |\n| PENDING | 配置待完成 | 完成初始化设置 |\n\n### 常见问题处理\n\n**工具包缺失**\n\n当诊断报告指示工具包未安装时，可使用 `lib/pm.js` 包管理模块进行安装。资料来源：[CONTRIBUTING.md:lib/pm.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n**Node.js 版本不兼容**\n\nGrainulation 要求 Node.js 20 或更高版本。检查当前版本：\n\n```bash\nnode --version\n```\n\n**配置文件损坏**\n\n删除现有配置并重新初始化：\n\n```bash\nnpx grainulation setup --reset\n```\n\n## 技术实现细节\n\n### 零依赖原则\n\n健康检查与诊断模块严格遵循零依赖原则，所有功能基于 Node.js 内置模块实现：\n\n- `fs` 模块 - 文件系统操作\n- `path` 模块 - 路径处理\n- `child_process` - 子进程管理\n- `crypto` - 哈希校验\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n### 本地服务器\n\n诊断结果可通过 `lib/server.mjs` 提供的本地 Web 界面展示。该服务器使用 ESM 模块格式，提供统一的生态系统仪表板视图。资料来源：[CONTRIBUTING.md:lib/server.mjs](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 相关链接\n\n- 官方文档：https://grainulation.com\n- 工具状态页：https://orchard.grainulation.com/\n- 仓库地址：https://github.com/grainulation/grainulation\n\n---\n\n\n\n## 开发环境配置\n\n### 相关页面\n\n相关主题：[安装指南](#page-installation), [健康检查与诊断](#page-doctor)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)\n- [lib/setup.js](https://github.com/grainulation/grainulation/blob/main/lib/setup.js)\n- [lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/lib/doctor.js)\n- [lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/lib/ecosystem.js)\n- [lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)\n- [lib/pm.js](https://github.com/grainulation/grainulation/blob/main/lib/pm.js)\n- [CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/grainulation/grainulation/blob/main/README.md)\n \n\n# 开发环境配置\n\n## 概述\n\nGrainulation 是一个基于 Node.js 的技术决策研究工具生态系统，其开发环境配置采用零依赖设计理念，仅使用 Node.js 内置模块完成所有功能。整个开发环境围绕 CLI 工具链构建，核心目标是提供一套轻量、可审计的本地化研究流程，帮助团队将技术问题转化为带有类型和置信度评级的结构化声明（claims）。\n\n开发环境配置模块主要负责以下几个核心功能：工具链初始化、环境健康检查、依赖管理、以及命令路由分发。资料来源：[CONTRIBUTING.md]()\n\n## 核心组件架构\n\n### 组件职责矩阵\n\n| 组件文件 | 核心职责 | 依赖关系 |\n|---------|---------|---------|\n| `bin/grainulation.js` | CLI 入口点，命令路由分发 | router.js |\n| `lib/router.js` | 命令路由到具体工具包 | ecosystem.js |\n| `lib/ecosystem.js` | 生态系统健康检查与工具发现 | doctor.js |\n| `lib/doctor.js` | 诊断工具，验证工具安装状态 | 无外部依赖 |\n| `lib/setup.js` | 首次运行配置与初始化 | pm.js |\n| `lib/pm.js` | 工具包管理 | 无外部依赖 |\n\n### 系统架构图\n\n```mermaid\ngraph TD\n A[用户终端] --> B[bin/grainulation.js]\n B --> C[lib/router.js]\n C --> D[lib/ecosystem.js]\n C --> E[lib/setup.js]\n C --> F[lib/doctor.js]\n D --> E\n D --> F\n E --> G[lib/pm.js]\n F --> H[本地工具包检测]\n G --> I[工具包安装/更新]\n H --> J[wheat]\n H --> K[farmer]\n H --> L[barn]\n H --> M[mill]\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 快速开始\n\n### 环境要求\n\n- **Node.js**: 20.x 或更高版本\n- **包管理器**: npx（随 Node.js 内置）\n- **操作系统**: 跨平台支持（Linux、macOS、Windows）\n\nGrainulation 强调零依赖设计，整个生态系统不依赖任何 npm 包，全部使用 Node.js 内置模块实现。资料来源：[README.md]()\n\n### 基础安装\n\n```bash\n# 全局安装主工具\nnpm install -g @grainulation/grainulation\n\n# 或直接使用 npx 运行\nnpx @grainulation/grainulation\n```\n\n### 初始化配置流程\n\n```mermaid\nsequenceDiagram\n 用户->>CLI: grainulation setup\n CLI->>setup.js: 执行初始化\n setup.js->>pm.js: 检查工具包状态\n pm.js->>生态系统: 列出可用工具\n 生态系统-->>setup.js: 工具列表\n setup.js-->>用户: 显示配置向导\n 用户->>setup.js: 选择角色/工具\n setup.js->>本地配置: 写入配置文件\n```\n\n## 命令路由机制\n\n### router.js 工作原理\n\n`lib/router.js` 是整个 CLI 的核心路由模块，负责将用户输入的命令分发到对应的工具包。该模块不依赖任何外部库，仅使用 Node.js 内置的 `fs`、`path`、`url` 等模块读取和解析文件系统结构。\n\n**路由匹配规则**：\n\n1. 解析命令行参数（`process.argv`）\n2. 识别主命令（如 `wheat`、`farmer`、`barn`）\n3. 查找对应的工具包目录\n4. 将控制权传递给目标工具的入口文件\n\n资料来源：[lib/router.js]()\n\n### 可用命令列表\n\n| 命令 | 功能描述 | 入口文件 |\n|-----|---------|---------|\n| `grainulation` | 生态系统概览 | bin/grainulation.js |\n| `grainulation doctor` | 健康检查 | lib/doctor.js |\n| `grainulation setup` | 首次配置 | lib/setup.js |\n| `grainulation wheat init` | 初始化研究冲刺 | wheat 包 |\n| `grainulation farmer start` | 启动权限仪表板 | farmer 包 |\n| `grainulation orchard status` | 编排状态 | orchard 包 |\n\n资料来源：[README.md]()\n\n## 环境健康检查\n\n### doctor.js 诊断功能\n\n`lib/doctor.js` 是 Grainulation 的诊断工具，用于验证本地开发环境的完整性和工具安装状态。该模块执行以下检查：\n\n1. **Node.js 版本验证**：确认当前版本是否满足 20.x+ 要求\n2. **工具包检测**：扫描已安装的 grainulation 工具包\n3. **配置完整性检查**：验证配置文件是否存在且格式正确\n4. **路径环境检查**：确认 `npx` 可访问\n\n### doctor 输出示例\n\n```bash\n$ grainulation doctor\n\n✓ Node.js v20.11.0 (要求: 20.x+)\n✓ npx 可用\n✓ wheat 已安装\n✓ farmer 已安装\n✓ barn 已安装\n⚠ mill 未安装\n✗ orchard 未安装\n\n检查完成: 2 个工具缺失\n运行 'grainulation setup' 安装缺失工具\n```\n\n资料来源：[lib/doctor.js]()\n\n## 首次运行配置\n\n### setup.js 配置流程\n\n`lib/setup.js` 负责首次运行时的初始化工作。该模块会：\n\n1. 检测当前环境的工具包安装状态\n2. 根据用户角色推荐需要安装的工具\n3. 生成用户级配置文件\n4. 设置默认的研究工作目录结构\n\n### 角色化配置\n\nGrainulation 支持根据用户角色进行差异化配置：\n\n| 角色 | 推荐工具组合 | 使用场景 |\n|-----|------------|---------|\n| 研究员 | wheat, barn | 独立研究、快速验证 |\n| 团队负责人 | wheat, barn, mill, harvest | 团队协作、决策汇报 |\n| 全栈 | wheat, farmer, orchard | AI 辅助开发、权限管理 |\n\n资料来源：[lib/setup.js]()\n\n## 包管理机制\n\n### pm.js 工具包管理\n\n`lib/pm.js` 是 Grainulation 的内部包管理器，负责：\n\n1. **工具发现**：扫描 `~/.grainulation/tools/` 目录下的已安装工具\n2. **版本检查**：比较本地版本与 npm 注册表版本\n3. **按需安装**：使用 `npx` 懒加载未安装的工具\n4. **依赖隔离**：每个工具包完全独立，无共享依赖\n\n### 工具包安装流程\n\n```mermaid\ngraph LR\n A[用户请求工具] --> B{pm.js 检测}\n B -->|已安装| C[直接调用]\n B -->|未安装| D[npx 懒加载]\n D --> E[临时安装到缓存]\n E --> F[执行工具]\n F --> G[缓存保留供后续使用]\n```\n\n资料来源：[lib/pm.js]()\n\n## 测试环境配置\n\n### 基本测试\n\nGrainulation 使用 Node.js 内置的测试运行器，无需额外安装测试框架。测试文件位于 `test/` 目录。\n\n```bash\n# 运行基础测试\nnode test/basic.test.js\n```\n\n### 测试覆盖范围\n\n| 测试模块 | 测试内容 | 源码映射 |\n|---------|---------|---------|\n| CLI 入口测试 | 命令行参数解析 | bin/grainulation.js |\n| 路由测试 | 命令分发逻辑 | lib/router.js |\n| 诊断测试 | 健康检查准确性 | lib/doctor.js |\n| 配置测试 | 配置文件生成 | lib/setup.js |\n\n资料来源：[CONTRIBUTING.md]()\n\n## 开发调试\n\n### 本地调试模式\n\n```bash\n# 直接运行本地源码\nnode bin/grainulation.js --help\n\n# 带调试输出运行\nDEBUG=grainulation:* node bin/grainulation.js doctor\n```\n\n### 源码修改工作流\n\n1. **克隆仓库**：\n ```bash\n git clone https://github.com/grainulation/grainulation.git\n cd grainulation\n ```\n\n2. **创建功能分支**：\n ```bash\n git checkout -b feature/description\n ```\n\n3. **修改代码**\n\n4. **运行测试**：\n ```bash\n node test/basic.test.js\n ```\n\n5. **提交并推送**\n\n资料来源：[CONTRIBUTING.md]()\n\n## 配置文件\n\n### 配置文件位置\n\nGrainulation 使用以下配置文件位置：\n\n| 文件类型 | 位置 | 用途 |\n|---------|-----|-----|\n| 用户配置 | `~/.grainulation/config.json` | 全局用户偏好设置 |\n| 工具配置 | `~/.grainulation/tools/` | 各工具的独立配置 |\n| 缓存 | `~/.grainulation/cache/` | 临时数据和下载缓存 |\n| 冲刺数据 | `./sprints/` | 研究冲刺的工作目录 |\n\n### 配置示例\n\n```json\n{\n \"version\": \"1.0.0\",\n \"role\": \"researcher\",\n \"tools\": [\"wheat\", \"barn\"],\n \"preferences\": {\n \"editor\": \"code\",\n \"gitAutoCommit\": true\n }\n}\n```\n\n## 常见问题排查\n\n### 环境问题诊断表\n\n| 问题现象 | 可能原因 | 解决方案 |\n|---------|---------|---------|\n| 命令未找到 | Node.js PATH 配置错误 | 重新安装 Node.js 或检查 PATH |\n| 工具加载失败 | npx 缓存损坏 | 运行 `npx clear-npx-cache` |\n| 配置文件错误 | JSON 格式错误 | 检查 `~/.grainulation/config.json` |\n| 权限错误 | 目录不可写 | 检查 `~/.grainulation/` 权限 |\n\n### 诊断命令\n\n```bash\n# 完整环境诊断\ngrainulation doctor\n\n# 检查 Node 版本\nnode --version\n\n# 检查 npx 可用性\nnpx --version\n```\n\n## 技术实现细节\n\n### 零依赖设计原则\n\nGrainulation 的所有模块均使用 Node.js 内置模块实现，不依赖任何外部 npm 包。这一设计带来以下优势：\n\n- **安全性**：无第三方依赖意味着无供应链攻击风险\n- **可移植性**：任何装有 Node.js 20+ 的环境可直接运行\n- **稳定性**：不受上游包版本变更影响\n- **轻量化**：安装包体积最小化\n\n### 内置模块使用情况\n\n| 模块 | 用途 |\n|-----|-----|\n| `fs` | 文件读写、目录扫描 |\n| `path` | 路径处理、跨平台兼容 |\n| `url` | URL 解析、npx 命令构造 |\n| `child_process` | 子进程管理、命令执行 |\n| `os` | 操作系统信息、临时目录 |\n\n资料来源：[lib/ecosystem.js]()\n\n## 总结\n\nGrainulation 的开发环境配置以简洁和零依赖为核心设计原则，通过模块化的架构实现了工具发现、健康检查、按需加载等关键功能。开发者只需确保 Node.js 20+ 环境即可开始使用，无需复杂的安装流程或依赖管理。这种设计使 Grainulation 成为技术决策研究中可靠、可审计且易于部署的工具选择。\n\n---\n\n\n\n## 故障排除\n\n### 相关页面\n\n相关主题：[健康检查与诊断](#page-doctor), [开发环境配置](#page-setup)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/grainulation/grainulation/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n- [RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)\n- [site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n \n\n# 故障排除\n\nGrainulation 生态系统提供了内置的诊断和排查机制，帮助用户快速定位并解决工具安装、配置和环境相关的问题。由于整个项目采用零依赖设计（仅使用 Node.js 内置模块），故障排查主要依赖于 `doctor` 命令和 `setup` 命令提供的诊断信息。\n\n## 诊断工具概述\n\nGrainulation 的故障排查体系由以下核心组件构成：\n\n| 组件 | 文件路径 | 功能 |\n|------|----------|------|\n| `doctor.js` | `lib/doctor.js` | 诊断工具，验证各工具的安装状态 |\n| `ecosystem.js` | `lib/ecosystem.js` | 生态系统健康检查和工具发现 |\n| `setup.js` | `lib/setup.js` | 首次运行设置和配置管理 |\n| `router.js` | `lib/router.js` | 命令路由，将请求分发至正确工具 |\n\n资料来源：[CONTRIBUTING.md:28-34]()\n\n## 诊断命令详解\n\n### grainulation doctor\n\n`doctor` 命令是 Grainulation 生态系统的健康检查工具，用于验证已安装工具的状态和版本信息。\n\n**使用方式：**\n\n```bash\ngrainulation doctor\n```\n\n**功能说明：**\n\n- 检查哪些工具已安装\n- 验证各工具的版本号\n- 报告缺失或过时的工具\n- 提供生态系统整体健康状态报告\n\n资料来源：[README.md:48](), [site/index.html]()\n\n### grainulation setup\n\n`setup` 命令用于首次运行时的工具配置和安装引导。\n\n**使用方式：**\n\n```bash\ngrainulation setup\n```\n\n**功能说明：**\n\n- 根据用户角色安装对应工具\n- 配置必要的环境参数\n- 初始化配置文件（如 `wheat.config.json`）\n\n资料来源：[README.md:47](), [CONTRIBUTING.md:35]()\n\n## 诊断流程图\n\n```mermaid\ngraph TD\n A[用户运行命令] --> B{命令类型}\n B -->|doctor| C[doctor.js 健康检查]\n B -->|setup| D[setup.js 首次配置]\n B -->|其他| E[router.js 命令路由]\n C --> F{工具状态}\n F -->|全部正常| G[输出健康报告]\n F -->|存在问题| H[输出问题列表]\n D --> I[ecosystem.js 工具发现]\n I --> J{工具缺失}\n J -->|是| K[提示安装命令]\n J -->|否| L[配置完成]\n E --> M[路由至对应工具包]\n```\n\n## 环境要求检查\n\nGrainulation 对运行环境有明确要求，在排查问题时首先应确认以下条件：\n\n| 要求 | 最低版本 | 检查命令 |\n|------|----------|----------|\n| Node.js | 20+ | `node --version` |\n| npx | 最新版 | `npx --version` |\n| Claude Code | 需安装 | 需单独配置 |\n\n资料来源：[site/index.html]()\n\n### 常见环境问题\n\n1. **Node.js 版本过低**\n - 症状：运行时报语法错误或模块未找到\n - 解决：升级至 Node.js 20 或更高版本\n\n2. **缺少 Claude Code**\n - 部分高级功能需要 Claude Code 支持\n - 详情参阅 [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code)\n\n## 工具安装问题排查\n\n### 通过 npm 全局安装\n\n```bash\nnpm install -g @grainulation/grainulation\n```\n\n### 通过 npx 直接运行\n\n```bash\nnpx @grainulation/wheat init\nnpx @grainulation/farmer start\nnpx @grainulation/harvest analyze ./sprints/\n```\n\n资料来源：[README.md:37-41]()\n\n### 常见安装问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 找不到命令 | 未正确安装 | 重新运行 `npm install -g` |\n| 版本不匹配 | npm 缓存问题 | 清除缓存 `npm cache clean --force` |\n| 权限错误 | 全局安装需要权限 | 使用 `sudo` 或配置 npm prefix |\n\n## 生态系统健康诊断\n\nGrainulation 的生态系统包含八个独立工具，每个工具都可能需要单独诊断：\n\n| 工具 | 命令 | 功能 |\n|------|------|------|\n| wheat | `wheat init` | 研究引擎，生成结构化证据 |\n| farmer | `farmer start` | 权限仪表板 |\n| mill | `mill export` | 导出工具 |\n| silo | `silo` | 知识管理 |\n| harvest | `harvest analyze` | 跨迭代学习分析 |\n| orchard | `orchard status` | 状态管理 |\n| barn | `barn` | 本地服务器 |\n| grainulation | `grainulation` | 统一 CLI |\n\n资料来源：[README.md:55-62]()\n\n## 发布与测试相关问题\n\nRELEASE.md 描述了完整的发布流程，当构建失败时可参考以下步骤：\n\n### CI/CD 故障排查\n\n发布工作流位于 `.github/workflows/publish.yml`，测试脚本位于 `test/basic.test.js`。\n\n```bash\nnode test/basic.test.js\n```\n\n资料来源：[CONTRIBUTING.md:27](), [RELEASE.md]()\n\n### 发布前检查清单\n\n1. 本地运行测试确保通过\n2. 确认 package.json 版本号正确\n3. 验证标签与版本一致\n4. 等待 npm 发布完成后再更新依赖方\n\n资料来源：[RELEASE.md:15-30]()\n\n## 常见问题速查\n\n### Q: 工具命令找不到\n\n**排查步骤：**\n\n1. 确认已安装：`npm list -g @grainulation/grainulation`\n2. 检查 PATH 配置\n3. 使用完整命令路径测试\n\n### Q: 工具运行报错\n\n**排查步骤：**\n\n1. 检查 Node.js 版本：`node --version`（需 ≥20）\n2. 清除 npm 缓存：`npm cache clean --force`\n3. 重新安装工具\n\n### Q: 生态系统状态异常\n\n**排查步骤：**\n\n1. 运行健康检查：`grainulation doctor`\n2. 检查各子工具版本\n3. 使用 `grainulation setup` 重新配置\n\n### Q: wheat.config.json 相关问题\n\nwheat 工具会创建配置文件如 `wheat.config.json` 和 `claims.json`，确保这些文件存在且格式正确。\n\n资料来源：[site/index.html]()\n\n## 架构级诊断信息\n\nGrainulation 的核心架构如下：\n\n```\nbin/grainulation.js CLI 入口 - 路由至各工具\nlib/router.js 命令路由\nlib/ecosystem.js 生态系统健康检查\nlib/doctor.js 诊断工具\nlib/setup.js 首次运行设置\nlib/pm.js 包管理\nlib/server.mjs 本地服务器\npublic/ Web UI\nsite/ 公共网站\ntest/ 测试文件\n```\n\n资料来源：[CONTRIBUTING.md:22-30]()\n\n## 获取更多帮助\n\n- 查看官方文档：https://grainulation.com\n- 工具特定文档：\n - wheat: https://wheat.grainulation.com\n - farmer: https://farmer.grainulation.com\n - mill: https://mill.grainulation.com\n - silo: https://silo.grainulation.com\n- GitHub Issues: https://github.com/grainulation/grainulation/issues\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：grainulation/grainulation\n\n摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1184031176 | https://github.com/grainulation/grainulation | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1184031176 | https://github.com/grainulation/grainulation | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1184031176 | https://github.com/grainulation/grainulation | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1184031176 | https://github.com/grainulation/grainulation | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1184031176 | https://github.com/grainulation/grainulation | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 来源证据：v1.1.0 — Security Hardening\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 — Security Hardening\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5e8c2578dd024d369fd769a7c23df98a | https://github.com/grainulation/grainulation/releases/tag/v1.1.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 7. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1184031176 | https://github.com/grainulation/grainulation | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1184031176 | https://github.com/grainulation/grainulation | release_recency=unknown\n\n\n",
"markdown_key": "grainulation",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1184031176",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/grainulation/grainulation"
},
{
"evidence_id": "art_9e0ca4ebbac3479db86c749ef6b030c7",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/grainulation/grainulation#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "grainulation 说明书",
"toc": [
"https://github.com/grainulation/grainulation 项目说明书",
"目录",
"项目概述",
"项目简介",
"核心概念",
"工具生态概览",
"工作流程",
"技术特性",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": false,
"repo_commit": null,
"repo_inspection_error": null,
"repo_inspection_files": [],
"repo_inspection_verified": false,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @grainulation/grainulation - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @grainulation/grainulation 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npm install -g @grainulation/grainulation` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `npx @grainulation/wheat init` 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做研究框架试用\n- **为什么**：这个项目面向研究工作流，核心风险是资料可信度和输出质量；先用 Prompt Preview 验证研究框架，再在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做研究框架试用\n- **最小安全下一步**：先用 Prompt Preview 验证研究框架；满意后再隔离试装\n- **先别相信**：研究结论、引用和实验结果不能在安装前相信。\n- **继续会触碰**：研究判断、命令执行、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：想在安装前理解开源项目价值和边界的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **研究结论、引用和实验结果不能在安装前相信。**（unverified）：研究 Skill 可以组织问题和路径，但不能替代真实资料检索、论文核验和实验复现。\n- **是否适合你的具体研究领域不能直接相信。**（unverified）：Skill 覆盖很多研究主题，不代表对你的领域、资料要求和可信度标准足够。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **研究判断**：问题拆解、资料路径、实验路径、结论结构和可信度判断。 原因：研究型 Skill 可能让输出看起来更专业，但不能替代真实证据核验。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先验证它能否正确界定研究问题和证据边界，不要先相信研究输出。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **保留资料和结论核验清单**：如果后续发现引用或实验路径不可靠，可以回到证据边界阶段重新校验。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0005` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0006` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：41\n- 重要文件覆盖：38/41\n- 证据索引条目：37\n- 角色 / Skill 条目：7\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @grainulation/grainulation 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @grainulation/grainulation 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @grainulation/grainulation 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 7 个角色 / Skill / 项目文档条目。\n\n- **Install**（project_doc）：Structured research for decisions that satisfice. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Contributing to Grainulation**（project_doc）：Thanks for considering contributing. Grainulation is the meta-package and ecosystem router -- it orchestrates all grainulation tools and provides the unified CLI entry point. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Grainulation Ecosystem Reference**（project_doc）：The grainulation CLI is the unified entry point for all eight tools in the ecosystem. Each tool has its own npm package and can be used standalone, but the grainulation package connects them into an integrated workflow. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/ecosystem.md`\n- **Changelog**（project_doc）：- Added SECURITY.md and CODE OF CONDUCT.md - Production polish: publishConfig , .env and .idea ignored 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n- **Code of Conduct**（project_doc）：We are committed to providing a welcoming and productive environment for everyone. We expect participants to: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CODE_OF_CONDUCT.md`\n- **Release playbook**（project_doc）：This file lives in the grainulation umbrella repo but covers the whole 8-package ecosystem wheat , farmer , barn , mill , silo , harvest , orchard , grainulation plus the grainulator plugin. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`RELEASE.md`\n- **Security Policy**（project_doc）：Only the latest published minor version of each package receives security fixes. Older versions may be patched at maintainer discretion. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`\n\n## 证据索引\n\n- 共索引 37 条证据。\n\n- **Install**（documentation）：Structured research for decisions that satisfice. 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"@grainulation/grainulation\", \"version\": \"1.1.3\", \"description\": \"Structured research for decisions that satisfice\", \"license\": \"MIT\", \"bin\": { \"grainulation\": \"bin/grainulation.js\" }, \"main\": \"./lib/ecosystem.js\", \"exports\": { \".\": \"./lib/ecosystem.js\", \"./pm\": \"./lib/pm.js\", \"./doctor\": \"./lib/doctor.js\", \"./router\": \"./lib/router.js\" }, \"files\": \"bin/\", \"lib/\", \"public/\", \"site/\", \"CHANGELOG.md\", \"LICENSE\", \"CODE OF CONDUCT.md\", \"CONTRIBUTING.md\", \"SECURITY.md\", \"README.md\" , \"type\": \"commonjs\", \"scripts\": { \"test\": \"node test/basic.test.js && node --test test/tarball.test.mjs\", \"lint\": \"npx @biomejs/biome@2.4.8 ci .\", \"format\": \"npx @biomejs/biome@2.4.8 check --write .\", \"star… 证据：`package.json`\n- **Contributing to Grainulation**（documentation）：Thanks for considering contributing. Grainulation is the meta-package and ecosystem router -- it orchestrates all grainulation tools and provides the unified CLI entry point. 证据：`CONTRIBUTING.md`\n- **License**（source_file）：Copyright c 2026 grainulation contributors 证据：`LICENSE`\n- **Grainulation Ecosystem Reference**（documentation）：The grainulation CLI is the unified entry point for all eight tools in the ecosystem. Each tool has its own npm package and can be used standalone, but the grainulation package connects them into an integrated workflow. 证据：`docs/ecosystem.md`\n- **Changelog**（documentation）：- Added SECURITY.md and CODE OF CONDUCT.md - Production polish: publishConfig , .env and .idea ignored 证据：`CHANGELOG.md`\n- **Code of Conduct**（documentation）：We are committed to providing a welcoming and productive environment for everyone. We expect participants to: 证据：`CODE_OF_CONDUCT.md`\n- **Release playbook**（documentation）：This file lives in the grainulation umbrella repo but covers the whole 8-package ecosystem wheat , farmer , barn , mill , silo , harvest , orchard , grainulation plus the grainulator plugin. 证据：`RELEASE.md`\n- **Security Policy**（documentation）：Only the latest published minor version of each package receives security fixes. Older versions may be patched at maintainer discretion. 证据：`SECURITY.md`\n- **Wiki**（structured_config）：{ \"repo notes\": { \"content\": \"grainulation is the umbrella repository and marketing site for the grainulation ecosystem. It is NOT a standalone tool — it is the landing page grainulation.app , the meta-package that lets users discover the individual packages barn, wheat, farmer, mill, silo, harvest, orchard , and the place where cross-cutting docs and demos live. The actual functionality lives in the individual packages.\", \"author\": \"grainulation-core\" }, { \"content\": \"When documenting grainulation, emphasize: 1 it is the ENTRY POINT — start here if you're new, 2 it hosts the interactive demo sprint-mode demo at grainulation.app , 3 each ecosystem package has its own wiki — link out, do not… 证据：`.devin/wiki.json`\n- **Biome**（structured_config）：{ \"$schema\": \"https://biomejs.dev/schemas/2.4.8/schema.json\", \"vcs\": { \"enabled\": true, \"clientKind\": \"git\", \"useIgnoreFile\": true }, \"formatter\": { \"enabled\": true, \"indentStyle\": \"space\", \"indentWidth\": 2, \"lineWidth\": 120 }, \"linter\": { \"enabled\": true, \"rules\": { \"recommended\": true, \"correctness\": { \"noUnusedVariables\": \"warn\", \"noUnusedImports\": \"warn\" } } }, \"javascript\": { \"formatter\": { \"quoteStyle\": \"single\", \"trailingCommas\": \"all\" } }, \"files\": { \"includes\": \" / .js\", \" / .mjs\", \" / .css\", \"!site/grainulation-print.css\", \"!site/grainulation-tokens.css\" } } 证据：`biome.json`\n- **!/bin/sh**（source_file）：Lint with Biome skip if npx is not available, but fail on lint errors if command -v npx /dev/null 2 &1; then npx --no biome check --staged --no-errors-on-unmatched fi 证据：`.githooks/pre-commit`\n- **Claude Code**（source_file）：.farmer-token .farmer-state.json .farmer.pid .farmer-audit .jsonl .farmer-config.json node modules/ coverage/ 证据：`.gitignore`\n- **!/usr/bin/env node**（source_file）：/ grainulation The unified entry point for the grainulation ecosystem. Routes to the right tool based on what you need. Usage: grainulation Show ecosystem overview grainulation doctor Check which tools are installed grainulation setup Interactive setup wizard grainulation serve Start the ecosystem control center grainulation args Delegate to a grainulation tool / 证据：`bin/grainulation.js`\n- **Doctor**（source_file）：const { execFileSync } = require 'node:child process' ; const { existsSync, readFileSync, readdirSync } = require 'node:fs' ; const path = require 'node:path' ; const { getInstallable } = require './ecosystem' ; 证据：`lib/doctor.js`\n- **Ecosystem**（source_file）：/ The grainulation ecosystem registry. Eight tools. Each grows from the same soil: question - evidence - decision. / 证据：`lib/ecosystem.js`\n- **Pm**（source_file）：/ Process Manager — start, stop, and monitor grainulation tools. Each tool runs its own HTTP server on a known port. This module spawns/kills them and probes ports for health. / 证据：`lib/pm.js`\n- **Router**（source_file）：const { execFileSync, spawn } = require 'node:child process' ; const { existsSync, readFileSync } = require 'node:fs' ; const path = require 'node:path' ; const { getByName, getInstallable } = require './ecosystem' ; 证据：`lib/router.js`\n- **!/usr/bin/env node**（source_file）：/ grainulation serve — local HTTP server for the ecosystem control center Tool catalog, doctor health checks, scaffold actions, and cross-tool navigation. SSE for live updates. Zero npm dependencies node:http only . Usage: grainulation serve --port 9098 / 证据：`lib/server.mjs`\n- **Setup**（source_file）：const readline = require 'node:readline' ; const { execFileSync } = require 'node:child process' ; const { getInstallable } = require './ecosystem' ; const { getVersion } = require './doctor' ; 证据：`lib/setup.js`\n- **0a0e1a is universal across all four UIs.**（source_file）：/ grainulation-tokens.css v1.0.0 Shared design tokens for the grainulation ecosystem. Home: barn the design-system tool Usage: Token architecture three layers : 1. Base layer -- backgrounds, foregrounds, borders, spacing, type, radii 2. Semantic layer -- accent maps to tool , status colors, feedback colors 3. Tool scales -- per-tool 5-weight accent ramp 50/200/400/600/800 Reset layer: Box model, scrollbar, font smoothing, shared components Accent activation: Set data-tool=\" \" on to load that tool's accent scale. Default accent no data-tool = barn rose-red. Extracted from working UIs: - barn/public/index.html accent: f43f5e rose — lightened from e11d48 for WCAG AA - wheat/public/index.html a… 证据：`public/grainulation-tokens.css`\n- **Index**（source_file）：Grainulation G \" / ── Tokens inline, zero deps ── / :root { --bg: 0a0e1a; --bg2: 111827; --bg3: 1e293b; --bg4: 334155; --fg: e2e8f0; --fg2: 94a3b8; --fg3: 64748b; --border: 1e293b; --border-subtle: rgba 255,255,255,0.08 ; --green: 34d399; --red: f87171; --blue: 60a5fa; --orange: fb923c; --purple: a78bfa; --cyan: 22d3ee; --accent: 9ca3af; --accent-light: d1d5db; --accent-dim: rgba 156,163,175,0.10 ; --accent-border: rgba 156,163,175,0.25 ; --radius: 8px; --radius-sm: 4px; --radius-lg: 12px; --font-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Inter', sans-serif; --font-mono: 'SF Mono', 'Cascadia Code', 'JetBrains Mono', monospace; --transition-fast: 0.1s ease; --transition-base: 0.15… 证据：`public/index.html`\n- **!/usr/bin/env bash**（source_file）：!/usr/bin/env bash seo-check.sh grainulation variant — Layer 1 regression guard for SEO/AI-visibility site assets. grainulation's site intentionally uses PNG favicons favicon-16.png, favicon-32.png, apple-touch-icon.png rather than the single SVG favicon used by the other 7 grainulation packages. Zero deps Bash + standard Unix . Runs in well under 30s. 证据：`scripts/seo-check.sh`\n- **7100366149211580Be04515B58B6E6D0**（source_file）：7100366149211580be04515b58b6e6d0 证据：`site/7100366149211580be04515b58b6e6d0.txt`\n- **Cname**（source_file）：grainulation.com 证据：`site/CNAME`\n- **Favicon**（source_file）：G 证据：`site/favicon.svg`\n- **Grainulation Print**（source_file）：/ grainulation-print.css v1.0.0 Shared print stylesheet for grainulation ecosystem sites. Home: barn. Vendored into each site via barn sync-assets . Usage in each site's , before : Sites that need local overrides ship a site-specific print-local.css AFTER this one; higher specificity wins. Do NOT fork this file -- contribute upstream to barn instead. Scope: applied only at print-time media=\"print\" . Has no effect on on-screen rendering; safe to ship everywhere. / 证据：`site/grainulation-print.css`\n- **0a0e1a is universal across all four UIs.**（source_file）：/ grainulation-tokens.css v0.1.0 Shared design tokens for the grainulation ecosystem. Home: barn the design-system tool Usage: Token architecture three layers : 1. Base layer -- backgrounds, foregrounds, borders, spacing, type, radii 2. Semantic layer -- accent maps to tool , status colors, feedback colors 3. Tool scales -- per-tool 5-weight accent ramp 50/200/400/600/800 Reset layer: Box model, scrollbar, font smoothing, shared components Accent activation: Set data-tool=\" \" on to load that tool's accent scale. Default accent no data-tool = barn rose-red. Extracted from working UIs: - barn/public/index.html accent: f43f5e rose — lightened from e11d48 for WCAG AA - wheat/public/index.html a… 证据：`site/grainulation-tokens.css`\n- **Index**（source_file）：Grainulation — Evidence-Based Technical Decision Tools :root { --bg: 0a0e1a; --bg-2: 111827; --surface: rgba 255,255,255,0.03 ; --surface-hover: rgba 255,255,255,0.06 ; --border: rgba 255,255,255,0.07 ; --border-light: rgba 255,255,255,0.12 ; --accent: 9ca3af; --accent-dim: rgba 156,163,175,0.12 ; --accent-glow: rgba 156,163,175,0.06 ; --green: 34d399; --green-dim: rgba 52,211,153,0.1 ; --red: f87171; --silver: 9ca3af; --blue: 60a5fa; --blue-dim: rgba 96,165,250,0.1 ; --orange: f59e0b; --pink: ec4899; --text: e8ecf1; --text-2: 9ba5b7; --text-3: 8b95a5; --mono: 'SF Mono','Fira Code','Cascadia Code','Consolas',monospace; --sans: -apple-system,BlinkMacSystemFont,'Segoe UI',system-ui,sans-serif… 证据：`site/index.html`\n- **Grainulation umbrella**（source_file）：Umbrella site for the grainulation ecosystem — research sprints, claim compilation, evidence-graded decisions. 证据：`site/llms.txt`\n- **Og Image**（source_file）：G rainulation Structured research for decisions that matter grainulation 证据：`site/og-image.svg`\n- **Robots**（source_file）：Sitemap: https://grainulation.com/sitemap.xml 证据：`site/robots.txt`\n- **Sitemap**（source_file）：https://grainulation.com/ 2026-04-19 weekly 1.0 证据：`site/sitemap.xml`\n- **Status Icons**（source_file）： B[\"1️⃣ 初始化 Sprint
wheat init\"]\n B --> C[\"claims.json 创建
wheat.config.json 就绪\"]\n C --> D[\"2️⃣ 研究与质疑\"]\n D --> E[\"wheat research 收集证据\"]\n E --> F[\"生成 typed claims
r001 [factual|documented]\"]\n F --> G[\"wheat challenge 压力测试\"]\n G --> H[\"生成风险声明
x001 [risk|documented]\"]\n H --> I[\"3️⃣ 编译与交付\"]\n I --> J[\"wheat brief 编译决策简报\"]\n J --> K[\"冲突已解决
output/brief.html 生成\"]\n K --> L[\"✅ 决策简报包含完整 git 审计轨迹\"]\n```\n\n### 各阶段说明\n\n**阶段 1：初始化**\n- 使用 `wheat init` 命令创建研究 Sprint\n- 自动生成 `claims.json`（声明存储）和 `wheat.config.json`（配置）\n\n**阶段 2：研究与质疑**\n- `/research` 命令用于收集特定主题的证据\n- `/challenge` 命令用于对已有声明进行对抗性测试\n- 所有发现都转化为带类型和证据等级的声明\n\n**阶段 3：编译与交付**\n- `/brief` 命令触发编译器\n- 编译器检测冲突、验证证据等级\n- 输出结构化决策简报（HTML 格式）\n\n> \"Research that compiles.\"\n> 资料来源：[site/index.html:1]()\n\n## 技术特性\n\n### 零依赖设计\n\ngrainulation 生态系统的核心原则之一是**零 npm 依赖**：\n\n| 特性 | 说明 |\n|------|------|\n| 仅使用 Node.js 内置模块 | 无外部依赖包 |\n| 无供应链风险 | 不依赖第三方包的安全性 |\n| 无 API 密钥需求 | 核心工具无需配置认证信息 |\n| 纯本地运行 | 所有数据处理在本地完成 |\n| 纯 JSON + HTML 输出 | 易于集成到现有工作流 |\n\n> \"Zero npm dependencies across all eight packages. No supply chain anxiety. No left-pad.\"\n> 资料来源：[site/index.html:1]()\n\n### 四大设计原则\n\n| 原则 | 说明 | 相关特性 |\n|------|------|----------|\n| **声明优于观点** | 每个发现都是有类型、有等级、可追溯的声明 ID | \"I think\" → 声明 ID + 证据等级 |\n| **对抗性压力** | 系统强制用户质疑、见证、压力测试每个声明 | 舒适的一致性是良好决策的大敌 |\n| **零依赖** | 仅使用 Node.js 内置模块 | 纯本地运行，无外部依赖 |\n| **确定性编译** | 编译器是 JavaScript 代码，非 LLM | 相同输入，相同输出 |\n\n> \"Comfortable agreement is the enemy of good decisions. The system forces you to challenge, witness, and stress-test every claim.\"\n> 资料来源：[site/index.html:1]()\n\n## 系统架构\n\n```mermaid\ngraph TD\n subgraph \"用户层\"\n A[\"用户/团队\"]\n end\n \n subgraph \"工具层 (CLI)\"\n B[\"wheat - 研究\"]\n C[\"farmer - 权限\"]\n D[\"mill - 导出\"]\n E[\"barn - 共享库\"]\n F[\"harvest - 分析\"]\n end\n \n subgraph \"编排层\"\n G[\"orchard - 统一入口\"]\n end\n \n subgraph \"数据层\"\n H[\"claims.json\"]\n I[\"wheat.config.json\"]\n J[\"sprints/ 目录\"]\n end\n \n subgraph \"编译器层\"\n K[\"Compiler
冲突检测
证据验证
门控机制\"]\n end\n \n A --> G\n G --> B\n G --> C\n G --> D\n G --> E\n G --> F\n \n B --> H\n B --> I\n H --> K\n I --> K\n K --> L[\"output/brief.html\"]\n \n style G fill:#9ca3af,color:#000\n style K fill:#fbbf24,color:#000\n style H fill:#6ee7b7,color:#000\n```\n\n## 安装与快速开始\n\n### 环境要求\n\n| 依赖 | 版本要求 |\n|------|----------|\n| Node.js | 20+ |\n| npx | 最新版本 |\n| Claude Code（可选） | 用于 AI 辅助研究 |\n| Git | 用于审计轨迹追踪 |\n\n### 安装方式\n\n```bash\n# 全局安装\nnpm install -g @grainulation/grainulation\n\n# 或直接使用 npx（无需安装）\nnpx @grainulation/wheat init\n```\n\n### 快速命令\n\n```bash\ngrainulation # 生态系统概览\ngrainulation doctor # 健康检查：工具列表、版本\ngrainulation setup # 为当前角色安装合适的工具\ngrainulation wheat init # 委托给 wheat 工具\ngrainulation farmer start # 启动权限仪表盘\n```\n\n资料来源：[README.md:21-29]()\n\n## 与传统方法的区别\n\n| 维度 | RFC/ADR | grainulation |\n|------|---------|--------------|\n| 文档性质 | 决策后记录 | 研究过程捕获 |\n| 证据管理 | 手动整理 | 结构化声明 + 证据等级 |\n| 对抗性测试 | 可选 | 内置强制机制 |\n| 冲突处理 | 人工发现 | 编译器自动检测 |\n| 审计轨迹 | 依赖 git 历史 | 内置完整证据链 |\n\n> \"RFCs and ADRs document a decision after it is made. Grainulation captures the research process — evidence gathering, adversarial testing, and conflict resolution.\"\n> 资料来源：[site/index.html:1]()\n\n## 输出产物\n\n执行 `wheat brief` 后的输出包含：\n\n- **决策简报**：结构化 HTML 文档\n- **声明清单**：所有收集的声明及其状态\n- **冲突报告**：未解决的矛盾说明\n- **证据摘要**：每条声明的来源和等级\n- **Git 审计轨迹**：完整的数据收集和质疑历史\n\n---\n\n\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart), [开发环境配置](#page-setup)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/grainulation/grainulation/blob/main/README.md)\n- [site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n- [RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)\n \n\n# 安装指南\n\n## 概述\n\nGrainulation 是一个由八个独立 CLI 工具组成的生态系统，旨在将技术问题转化为带有类型和证据等级的声明（claims），最终生成可审计的决策简报。整个项目遵循**零 npm 依赖**原则，全部基于 Node.js 原生内置模块构建，所有工具均在本地运行，无需云服务或 API 密钥。\n\n本安装指南涵盖完整的环境准备、各工具的安装方式以及不同使用场景下的推荐配置。\n\n## 系统要求\n\n| 组件 | 最低版本 | 说明 |\n|------|----------|------|\n| Node.js | 20+ | 核心运行时环境 |\n| npm | 内置 | 用于全局安装或本地依赖管理 |\n| npx | 内置 | 用于直接执行远程包 |\n| Claude Code | 最新版 | 用于执行研究任务的 AI 代理 |\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n> **重要提示**：核心工具（如 wheat）的编译器部分**不需要 API 密钥**。所有数据处理均在本地完成，不涉及任何云服务调用。\n\n## 安装模式\n\nGrainulation 提供两种主要安装模式，用户可根据实际需求选择。\n\n### 模式一：全局安装（推荐长期使用）\n\n全局安装适合需要频繁使用工具链的场景，一次安装后可在任意目录下直接调用：\n\n```bash\nnpm install -g @grainulation/grainulation\n```\n\n安装完成后，可以通过统一的入口工具 `grainulation` 调用所有子命令：\n\n```bash\ngrainulation # 查看生态系统概览\ngrainulation doctor # 健康检查：已安装工具列表及版本\ngrainulation setup # 根据角色安装所需工具\ngrainulation wheat init # 委托给 wheat 工具初始化研究 sprint\ngrainulation farmer start # 启动权限仪表板\n```\n\n资料来源：[README.md](https://github.com/grainulation/grainulation/blob/main/README.md)\n\n### 模式二：按需执行（零安装）\n\n对于偶尔使用或临时探索的场景，可以直接使用 `npx` 跳过安装步骤，按需下载并执行：\n\n```bash\nnpx @grainulation/wheat init # 直接初始化研究 sprint\nnpx @grainulation/farmer start # 启动权限仪表板\nnpx @grainulation/mill export --format pdf # 导出决策简报为 PDF\nnpx @grainulation/harvest analyze ./sprints/ # 分析历史 sprint 数据\n```\n\n这种模式的优势在于**无需预先安装任何依赖**，每次执行都会获取最新版本。\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n## 工具生态概览\n\nGrainulation 包含八个独立工具，每个工具专注于特定功能领域：\n\n| 工具 | 功能域 | 核心用途 | 安装命令 |\n|------|--------|----------|----------|\n| wheat | 研究引擎 | 增长结构化证据，管理声明 | `npx @grainulation/wheat init` |\n| farmer | 权限仪表板 | 审批 AI 代理的工具调用请求 | `npx @grainulation/farmer start` |\n| barn | 共享基础库 | Sprint 检测、清单生成、HTML 模板 | `npx @grainulation/barn detect-sprints` |\n| mill | 导出与发布 | 生成 PDF、CSV、静态站点等格式 | `npx @grainulation/mill export --format pdf` |\n| silo | 沙箱隔离 | 为 AI 代理提供安全的代码执行环境 | `npx @grainulation/silo sandbox` |\n| harvest | 分析与洞察 | 跨 sprint 学习，追踪预测准确率 | `npx @grainulation/harvest analyze ./sprints/` |\n| orchard | 编排层 | 工作流编排，跨工具协调 | `npx @grainulation/orchard status` |\n| grainulation | 统一 CLI | 生态系统总入口，配置管理 | `npm install -g @grainulation/grainulation` |\n\n资料来源：[README.md](https://github.com/grainulation/grainulation/blob/main/README.md)\n\n## 快速开始工作流\n\n对于新用户，建议按照以下三步流程完成首次研究 sprint：\n\n```mermaid\ngraph TD\n A[初始化 Sprint
npx @grainulation/wheat init] --> B[研究与质疑
收集证据, 挑战声明]\n B --> C[编译与交付
生成决策简报]\n C --> D[输出 brief.html
可导出为 PDF/CSV]\n```\n\n### 步骤一：初始化 Sprint\n\n```bash\nnpx @grainulation/wheat init\n```\n\n执行后将创建两个核心文件：\n\n- `claims.json` — 存储所有声明的清单文件\n- `wheat.config.json` — 工具配置文件\n\n```bash\n$ npx @grainulation/wheat init\n\nSprint initialized.\nclaims.json created (0 claims)\nwheat.config.json ready\n```\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n### 步骤二：研究与质疑\n\n在 wheat 交互式环境中使用以下命令：\n\n```bash\nwheat> /research \"topic\" # 收集关于指定主题的研究证据\nwheat> /challenge r001 # 质疑指定声明，触发对抗性测试\n```\n\n声明将以统一格式输出：\n\n```\nr001 [factual|documented] ...\nx001 [risk|documented] ...\n```\n\n### 步骤三：编译与交付\n\n```bash\nwheat> /brief\n```\n\n编译器将执行以下验证：\n\n1. 解析所有声明及关联证据\n2. 检测声明间的矛盾冲突\n3. 标记证据等级不足的声明\n4. 阻止输出直至所有问题解决\n5. 生成包含完整 git 审计轨迹的决策简报\n\n```bash\nCompiled 12 claims (2 conflicts resolved)\nWritten: output/brief.html\n```\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n## 环境健康检查\n\n安装完成后，可使用以下命令验证工具链状态：\n\n```bash\ngrainulation doctor\n```\n\n该命令将检测：\n\n- 已安装的工具列表及版本号\n- Node.js 版本兼容性\n- 各工具间的依赖关系状态\n\n## 权限仪表板安装\n\nFarmer 是用于审批 AI 代理工具调用的实时仪表板，特别适合团队协作场景：\n\n```bash\nnpx @grainulation/farmer start\n```\n\n启动后支持以下功能：\n\n- 通过手机、另一浏览器标签页或会议期间审批请求\n- 实时 SSE（Server-Sent Events）推送\n- **零依赖**设计，不引入额外包\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n## 离线与私有部署\n\n由于 Grainulation 整个生态系统的设计原则是**零 npm 依赖**（仅使用 Node.js 内置模块），部署到私有环境或离线场景非常直接：\n\n1. 将整个仓库克隆至目标机器\n2. 确保 Node.js 20+ 已安装\n3. 通过 `npx` 或本地 `node` 直接运行各工具入口脚本\n\n```bash\ngit clone https://github.com/grainulation/grainulation.git\ncd grainulation\nnode wheat/bin/index.js init # 直接执行，跳过 npm 查找\n```\n\n## 常见问题\n\n### Q：是否需要注册账户或获取 API 密钥？\n\n不需要。核心工具（wheat、barn、mill 等）**完全本地运行**，不连接任何外部服务。唯一需要 API 密钥的是与 AI 代理（Claude Code）的交互，由用户自行管理。\n\n### Q：是否支持 Yarn、pnpm 等其他包管理器？\n\nGrainulation 主包 `@grainulation/grainulation` 支持通过 npm 全局安装。对于子工具，推荐使用 `npx` 方式执行以确保版本一致性。\n\n### Q：可以安装单个工具而不安装整个生态吗？\n\n可以。八个工具相互独立，按需安装即可：\n\n```bash\nnpm install -g @grainulation/wheat\nnpm install -g @grainulation/mill\n# 等等...\n```\n\n### Q：安装后如何获取更新？\n\n- 全局安装：`npm update -g @grainulation/grainulation`\n- npx 方式：每次执行自动获取最新版本\n\n## 相关资源\n\n- 项目官网：https://grainulation.com\n- 官方文档：各工具独立维护的文档站点\n- GitHub 仓库：https://github.com/grainulation/grainulation\n- npm 包页面：https://www.npmjs.com/package/@grainulation/grainulation\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[CLI命令参考](#page-cli-commands), [生态系统概览](#page-ecosystem)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/grainulation/grainulation/blob/main/README.md)\n- [site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n- [CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n- [bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)\n- [lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)\n \n\n# 快速开始\n\n## 概述\n\n快速开始是 Grainulation 生态系统的入口点，旨在帮助用户在 60 秒内启动一个技术决策研究冲刺（Sprint）。整个流程设计遵循\"三条命令，一个决策\"的原则，无需安装、无需注册、无需配置 API Key，只需 `npx` 和一个问题即可开始。\n\n资料来源：[site/index.html:1]()\n\n## 前置要求\n\n在开始使用 Grainulation 之前，请确保满足以下环境要求：\n\n| 要求 | 版本 | 说明 |\n|------|------|------|\n| Node.js | 20+ | 仅使用 Node.js 内置模块 |\n| npx | 最新版 | 用于直接运行包 |\n| Claude Code | 可选 | 用于 AI 辅助研究 |\n| npm | 最新版 | 用于全局安装 |\n\nGrainulation 的核心理念是**零依赖**——所有八个包均不使用任何 npm 依赖项，完全基于 Node.js 内置模块构建，不存在供应链安全风险。\n\n资料来源：[README.md:1]()\n\n## 安装方式\n\nGrainulation 提供两种安装方式，用户可根据使用场景选择：\n\n### 全局安装\n\n适合经常使用 Grainulation 的用户：\n\n```bash\nnpm install -g @grainulation/grainulation\n```\n\n全局安装后，可以直接使用 `grainulation` 命令：\n\n```bash\ngrainulation # 生态系统概览\ngrainulation doctor # 健康检查：工具列表和版本\ngrainulation setup # 安装适合角色的工具\ngrainulation farmer start # 启动权限仪表板\n```\n\n### 直接运行（推荐）\n\n适合临时使用或首次体验的用户：\n\n```bash\nnpx @grainulation/wheat init\n```\n\n这种方式无需安装任何内容，直接通过 npx 拉取并执行包。\n\n资料来源：[README.md:1]()\n\n## 三步工作流程\n\nGrainulation 的快速开始流程分为三个阶段：初始化、研究与挑战、编译发布。\n\n### 步骤一：初始化冲刺\n\n使用 `wheat` 工具初始化一个新的研究冲刺。系统会提示你输入问题、受众和约束条件：\n\n```bash\nnpx @grainulation/wheat init\n```\n\n执行后将创建两个文件：\n\n| 文件 | 用途 |\n|------|------|\n| `claims.json` | 存储所有声明（Claims）的文件 |\n| `wheat.config.json` | 配置文件 |\n\n初始化输出示例：\n\n```\nSprint initialized.\nclaims.json created (0 claims)\nwheat.config.json ready\n```\n\n资料来源：[site/index.html:1]()\n\n### 步骤二：研究与挑战\n\n在研究阶段，你需要收集证据并对每个发现进行压力测试。所有发现都会成为带有类型和等级的声明（Claims）。\n\nwheat 命令行工具提供两个核心命令：\n\n```bash\nwheat> /research \"topic\" # 收集关于某个主题的证据\nwheat> /challenge r001 # 挑战已有的声明\n```\n\n声明具有以下属性：\n\n| 属性 | 可选值 | 说明 |\n|------|--------|------|\n| 类型 | factual, risk, estimate, constraint, recommendation | 声明的语义类型 |\n| 等级 | documented, measured, peer-reviewed 等 | 证据强度等级 |\n| 状态 | active, challenged, resolved | 当前状态 |\n\n挑战声明后，系统会生成新的风险声明（以 `x` 前缀标识）：\n\n```\nr001 [factual|documented] ... # 原始声明\nx001 [risk|documented] ... # 由挑战产生的风险声明\n```\n\n资料来源：[site/index.html:1]()\n\n### 步骤三：编译并发布\n\n当研究完成且冲突已解决后，使用编译命令生成决策简报：\n\n```bash\nwheat> /brief\n```\n\n编译器的工作流程：\n\n```mermaid\ngraph TD\n A[输入 Claims] --> B{检查冲突}\n B -->|存在冲突| C[阻止输出]\n B -->|无冲突| D{检查证据强度}\n D -->|证据不足| E[标记弱证据]\n D -->|证据充分| F[生成决策简报]\n E --> C\n F --> G[output/brief.html]\n```\n\n编译器输出示例：\n\n```\nCompiled 12 claims (2 conflicts resolved)\nWritten: output/brief.html\n```\n\n决策简报具有完整的 Git 审计跟踪功能，记录每个声明的收集方式和挑战过程。\n\n资料来源：[site/index.html:1]()\n\n## 工作流程图\n\n整个 Grainulation 生态系统的工作流程如下：\n\n```mermaid\ngraph LR\n A[问题] --> B[w:heat 初始化]\n B --> C[w:heat 研究]\n C --> D[w:heat 挑战]\n D --> E{编译器检查}\n E -->|通过| F[o:rchard 状态]\n E -->|失败| C\n F --> G[m:ill 导出]\n G --> H[决策简报]\n \n H --> I[h:arvest 分析]\n I --> J[跨冲刺学习]\n```\n\n## 生态工具概览\n\nGrainulation 由八个独立的工具组成，每个工具负责特定功能：\n\n| 工具 | 用途 | 安装命令 |\n|------|------|----------|\n| [wheat](https://github.com/grainulation/wheat) | 研究引擎，构建结构化证据 | `npx @grainulation/wheat init` |\n| [farmer](https://github.com/grainulation/farmer) | 权限仪表板，审批 AI 代理工具调用 | `npx @grainulation/farmer start` |\n| [barn](https://github.com/grainulation/barn) | 共享工具库，冲刺检测和清单生成 | `npx @grainulation/barn detect-sprints` |\n| [mill](https://github.com/grainulation/mill) | 导出工具，生成 PDF、CSV、静态站点 | `npx @grainulation/mill export --format pdf` |\n| [silo](https://github.com/grainulation/silo) | 文档存储，可搜索的结构化声明存档 | `npx @grainulation/silo search` |\n| [orchard](https://github.com/grainulation/orchard) | 编排工具，路由和生态系统健康检查 | `npx @grainulation/orchard status` |\n| [harvest](https://github.com/grainulation/harvest) | 分析工具，预测准确性和系统盲点追踪 | `npx @grainulation/harvest analyze ./sprints/` |\n| grainulation | 统一 CLI，元工具路由 | `npx @grainulation/grainulation` |\n\n资料来源：[README.md:1]()\n\n## 项目架构\n\nGrainulation 作为元包和生态系统路由器，其架构如下：\n\n```\nbin/grainulation.js # CLI 入口点 - 路由到各工具包\nlib/router.js # 命令路由，将请求分发到正确工具\nlib/ecosystem.js # 生态系统健康检查和工具发现\nlib/doctor.js # 诊断工具 - 验证工具安装状态\nlib/setup.js # 首次运行设置和配置\nlib/pm.js # grainulation 工具的包管理\nlib/server.mjs # 本地服务器 - 统一生态系统仪表板\npublic/ # Web UI - 生态系统概览和状态\nsite/ # 公开网站\ntest/ # Node 内置测试运行器\n```\n\n关键架构原则：所有工具均通过统一的 CLI 接口路由，用户只需记住 `grainulation` 一个入口点即可访问整个生态系统。\n\n资料来源：[CONTRIBUTING.md:1]()\n\n## 常见问题\n\n### 需要 Node.js 吗？\n\n是的，Grainulation 是一个 Node.js 工具，需要 Node.js 20 或更高版本。它不使用任何外部依赖，仅使用 Node.js 内置模块。\n\n### 与 RFC/ADR 有何不同？\n\nRFC 和 ADR 在决策完成后记录决策。Grainulation 捕获研究过程——证据收集、对抗性测试和冲突解决——并通过编译器进行验证。输出的简报可作为 ADR 使用，具有完整的 Git 审计跟踪，显示每个声明是如何收集、挑战和解决的。\n\n### 数据存储在哪里？\n\n所有数据都存储在本地 JSON 文件中。没有云服务、没有账户、没有 API 密钥。决策简报是静态 HTML 文件，可部署到任何静态托管服务。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [CLI命令参考](#page-cli-commands), [工具集成与协作](#page-tools-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)\n- [lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)\n- [lib/server.mjs](https://github.com/grainulation/grainulation/blob/main/lib/server.mjs)\n- [lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/lib/ecosystem.js)\n- [lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/lib/doctor.js)\n- [lib/setup.js](https://github.com/grainulation/grainulation/blob/main/lib/setup.js)\n- [lib/pm.js](https://github.com/grainulation/grainulation/blob/main/lib/pm.js)\n \n\n# 系统架构\n\n## 概述\n\nGrainulation 是一个元包（meta-package）和生态系统路由器，它编排所有 Grainulation 工具并提供统一的 CLI 入口点。该项目的核心理念是**零依赖**——整个生态系统完全基于 Node.js 内置模块构建，不使用任何 npm 依赖项。\n\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 架构设计原则\n\nGrainulation 遵循以下核心架构原则：\n\n| 原则 | 描述 | 实现方式 |\n|------|------|----------|\n| 零依赖 | 整个生态系统无 npm 依赖 | 仅使用 Node.js 内置模块 |\n| 统一入口 | 所有工具通过单一 CLI 路由 | `bin/grainulation.js` 作为主入口 |\n| 本地优先 | 所有数据和处理在本地运行 | 无需 API 密钥或云服务 |\n| 生态系统协调 | 统一的健康检查和工具发现 | `lib/ecosystem.js` 负责 |\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n## 核心组件架构\n\n### 组件层次结构\n\n```mermaid\ngraph TD\n subgraph 入口层\n CLI[bin/grainulation.js
CLI 入口点]\n end\n \n subgraph 核心库\n Router[lib/router.js
命令路由]\n Ecosystem[lib/ecosystem.js
生态系统健康检查]\n Doctor[lib/doctor.js
诊断工具]\n Setup[lib/setup.js
首次运行配置]\n PM[lib/pm.js
包管理]\n end\n \n subgraph 服务层\n Server[lib/server.mjs
本地服务器]\n end\n \n subgraph 前端层\n Public[public/
Web UI]\n Site[site/
公共网站]\n end\n \n CLI --> Router\n Router --> Ecosystem\n Router --> Doctor\n Router --> Setup\n Router --> PM\n Server --> Public\n Server --> Ecosystem\n```\n\n### 各组件职责\n\n| 组件文件 | 职责 | 模块类型 |\n|----------|------|----------|\n| `bin/grainulation.js` | CLI 入口点，路由到各个独立工具包 | CommonJS |\n| `lib/router.js` | 命令路由，将请求分发到正确的工具包 | CommonJS |\n| `lib/ecosystem.js` | 生态系统健康检查和工具发现 | CommonJS |\n| `lib/doctor.js` | 诊断工具，验证工具安装状态 | CommonJS |\n| `lib/setup.js` | 首次运行设置和配置 | CommonJS |\n| `lib/pm.js` | Grainulation 工具的包管理功能 | CommonJS |\n| `lib/server.mjs` | 本地服务器，提供统一生态系统仪表板 | ESM |\n\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 命令路由机制\n\n### 路由流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant CLI as bin/grainulation.js\n participant Router as lib/router.js\n participant Tool as 目标工具包\n \n User->>CLI: node bin/grainulation.js [command]\n CLI->>Router: 解析命令参数\n Router->>Router: 识别工具类型\n Router->>Tool: 路由到对应工具\n Tool-->>User: 返回执行结果\n```\n\n### 工具生态系统\n\nGrainulation 由八个独立工具组成，每个工具专注于特定功能：\n\n| 工具名称 | 颜色标识 | 功能领域 | 用途 |\n|----------|----------|----------|------|\n| **wheat** | 金色 (#fbbf24) | 研究引擎 | 初始化 sprint、研究、挑战、编译决策 |\n| **farmer** | 蓝色 (#3b82f6) | 权限仪表板 | 审批 AI 代理的工具调用请求 |\n| **barn** | 红色 (#f43f5e) | 知识存储 | 持久化存储和管理研究数据 |\n| **mill** | 紫色 (#a78bfa) | 导出发布 | 将研究编译为 PDF、CSV、静态站点 |\n| **silo** | 青色 (#22d3ee) | 共享存储 | 团队间共享和协作研究 |\n| **harvest** | 橙色 (#fb923c) | 分析统计 | 跨 sprint 学习，追踪预测准确性 |\n| **orchard** | 棕色 (#d4a574) | 编排协调 | 跨工具协调和工作流管理 |\n| **grainulation** | 灰色 (#9ca3af) | 统一 CLI | 元工具，路由到各工具并管理配置 |\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n## 生态系统健康检查\n\n`lib/ecosystem.js` 负责维护整个工具生态系统的健康状态：\n\n### 健康检查流程\n\n```mermaid\ngraph LR\n A[启动检查] --> B{工具已安装?}\n B -->|是| C[检查版本]\n C --> D{版本匹配?}\n D -->|是| E[工具可用]\n D -->|否| F[提示更新]\n B -->|否| G[安装工具]\n G --> E\n E --> H[生态系统就绪]\n```\n\n### 工具发现机制\n\n生态系统通过以下方式发现和验证工具：\n\n1. **本地注册表检查**：扫描已安装的 `@grainulation/*` 包\n2. **版本兼容性验证**：确保工具版本与 grainulation 主包兼容\n3. **依赖链验证**：检查工具间的依赖关系是否满足\n\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 本地服务器架构\n\n`lib/server.mjs` 是使用 ESM 模块格式的本地服务器：\n\n### 服务器特性\n\n| 特性 | 描述 |\n|------|------|\n| 模块格式 | ESM (ECMAScript Modules) |\n| 功能 | 提供统一的生态系统仪表板 |\n| 前端资源 | `public/` 目录下的 Web UI |\n| 实时更新 | 支持 SSE (Server-Sent Events) 实时通信 |\n\n### 服务架构\n\n```mermaid\ngraph TD\n subgraph 服务层\n Server[lib/server.mjs
ESM 服务器]\n end\n \n subgraph 前端资源\n UI[public/
静态资源]\n Dashboard[生态系统仪表板]\n end\n \n Server --> UI\n Server --> Dashboard\n Server --> SSE[SSE 实时更新]\n \n subgraph 数据流\n API[内部 API]\n Health[健康检查数据]\n end\n \n Server --> API\n API --> Health\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 测试架构\n\n### 测试框架\n\nGrainulation 使用 Node.js 内置测试运行器：\n\n| 测试文件 | 描述 |\n|----------|------|\n| `test/basic.test.js` | 基本功能测试 |\n\n### 测试执行\n\n```bash\nnode test/basic.test.js\n```\n\n测试覆盖以下核心功能：\n- CLI 命令解析\n- 路由功能验证\n- 生态系统健康检查\n\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 发布工作流架构\n\n### 发布流程\n\n```mermaid\ngraph LR\n A[代码变更] --> B[版本升级]\n B --> C[npm version patch]\n C --> D[提交 + 标签]\n D --> E[git push --follow-tags]\n E --> F[触发 Actions]\n F --> G{测试通过?}\n G -->|是| H[验证 package.json]\n G -->|否| I[发布失败]\n H --> J[发布到 npm]\n J --> K[OIDC 信任发布]\n K --> L[生成 Provenance]\n```\n\n### 发布配置\n\n| 配置项 | 值 |\n|--------|-----|\n| 工作流文件 | `.github/workflows/publish.yml` |\n| 认证方式 | OIDC 信任发布 (无需 NPM_TOKEN) |\n| 平台 | npmjs.com |\n| 徽章 | \"Built + Signed\" 链接回工作流运行 |\n\n### 协调发布流程\n\n当消费者依赖新的内部功能时：\n\n1. **首先发布依赖包**（如 `barn`）\n2. **等待 npm 发布完成**（约 60 秒）\n3. **在消费者仓库执行 `npm install`** 更新 package-lock.json\n4. **提交锁文件更新**\n5. **按顺序发布各消费者包**\n\n资料来源：[RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)\n\n## 数据流总览\n\n```mermaid\ngraph TD\n subgraph 用户交互层\n CLI[CLI 命令行]\n WebUI[Web 界面]\n end\n \n subgraph 入口处理\n Entry[bin/grainulation.js]\n end\n \n subgraph 核心处理\n Router[路由层
lib/router.js]\n Ecosystem[生态层
lib/ecosystem.js]\n Doctor[诊断层
lib/doctor.js]\n Setup[配置层
lib/setup.js]\n PM[包管理层
lib/pm.js]\n end\n \n subgraph 工具层\n Wheat[wheat]\n Farmer[farmer]\n Barn[barn]\n Mill[mill]\n Silo[silo]\n Harvest[harvest]\n Orchard[orchard]\n end\n \n subgraph 存储层\n LocalData[本地数据]\n CloudData[云存储]\n end\n \n CLI --> Entry\n WebUI --> Entry\n Entry --> Router\n Router --> Ecosystem\n Router --> Doctor\n Router --> Setup\n Router --> PM\n Ecosystem --> Wheat\n Ecosystem --> Farmer\n Ecosystem --> Barn\n Ecosystem --> Mill\n Ecosystem --> Silo\n Ecosystem --> Harvest\n Ecosystem --> Orchard\n Barn --> LocalData\n Silo --> CloudData\n```\n\n## 技术栈总结\n\n| 层面 | 技术选择 | 理由 |\n|------|----------|------|\n| 运行时 | Node.js 20+ | 核心运行要求 |\n| CLI 框架 | 原生参数解析 | 零依赖原则 |\n| 模块系统 | CommonJS + ESM 混合 | 兼容性考虑 |\n| 测试框架 | Node.js 内置测试 | 无外部依赖 |\n| 发布平台 | npm (OIDC) | 现代化 CI/CD |\n| 包管理 | npx | 即开即用 |\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n---\n\n\n\n## CLI命令参考\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [健康检查与诊断](#page-doctor), [开发环境配置](#page-setup)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)\n- [lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)\n- [lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/lib/ecosystem.js)\n- [lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/lib/doctor.js)\n- [lib/pm.js](https://github.com/grainulation/grainulation/blob/main/lib/pm.js)\n- [lib/setup.js](https://github.com/grainulation/grainulation/blob/main/lib/setup.js)\n- [lib/server.mjs](https://github.com/grainulation/grainulation/blob/main/lib/server.mjs)\n \n\n# CLI命令参考\n\n本文档详细介绍 grainulation 生态系统中统一 CLI 的所有命令、功能和使用方式。\n\n## 概述\n\ngrainulation 是 grainulation 工具生态系统的元包和统一入口点，负责协调所有 grainulation 工具并提供统一的 CLI 入口。CLI 架构遵循简单路由模式，将命令分发到各个独立工具包执行。资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 架构设计\n\ngrainulation CLI 采用模块化架构，核心组件协同工作以提供统一的命令行体验。\n\n```mermaid\ngraph TD\n A[bin/grainulation.js
CLI入口点] --> B[lib/router.js
命令路由]\n A --> C[lib/ecosystem.js
生态系统健康检查]\n A --> D[lib/doctor.js
诊断工具]\n B --> E[@grainulation/wheat
研究工具]\n B --> F[@grainulation/farmer
权限仪表盘]\n B --> G[@grainulation/barn
共享工具]\n B --> H[其他工具包...]\n C --> I[npm registry
工具发现]\n D --> J[本地安装验证]\n F --> K[server.mjs
本地服务器]\n```\n\n### 核心文件职责\n\n| 文件路径 | 职责 | 功能描述 |\n|---------|------|---------|\n| `bin/grainulation.js` | CLI入口点 | 解析命令行参数，路由到正确工具 |\n| `lib/router.js` | 命令路由 | 将命令分发到独立工具包执行 |\n| `lib/ecosystem.js` | 生态系统管理 | 健康检查和工具发现 |\n| `lib/doctor.js` | 诊断工具 | 验证工具安装状态 |\n| `lib/pm.js` | 包管理 | grainulation 工具的包管理 |\n| `lib/setup.js` | 首次设置 | 首次运行配置和初始化 |\n| `lib/server.mjs` | 本地服务器 | 统一的生态系统仪表盘（ESM） |\n\n## 命令行接口\n\n### 基本用法\n\n```bash\nnpx grainulation [command] [options]\n```\n\n### 全局选项\n\n| 选项 | 描述 | 默认值 |\n|------|------|--------|\n| `--help, -h` | 显示帮助信息 | - |\n| `--version, -v` | 显示版本号 | - |\n| `--json` | 以JSON格式输出 | false |\n\n### 帮助命令\n\n```bash\ngrainulation --help\n```\n\n显示所有可用命令和选项的完整帮助信息。\n\n## 子命令详解\n\n### 1. doctor - 诊断命令\n\ndoctor 命令用于验证 grainulation 工具的本地安装状态，检查每个工具包的健康状况。\n\n```bash\ngrainulation doctor [options]\n```\n\n**功能说明**\n\n- 验证各工具包的安装完整性\n- 检查 Node.js 版本兼容性\n- 报告缺失或损坏的工具包\n- 提供修复建议\n\n**可用选项**\n\n| 选项 | 描述 |\n|------|------|\n| `--fix` | 自动修复发现的问题 |\n| `--json` | 输出JSON格式诊断结果 |\n\n### 2. doctor 命令工作流程\n\n```mermaid\ngraph TD\n A[grainulation doctor] --> B{检查Node.js版本}\n B -->|版本过低| C[警告: 需要Node.js 20+]\n B -->|版本符合| D[检查工具包目录]\n D --> E{扫描@scope/@grainulation/*}\n E -->|发现包| F[验证package.json]\n E -->|无包| G[提示安装工具]\n F --> H{package.json完整?}\n H -->|是| I[工具状态: 健康]\n H -->|否| J[工具状态: 损坏]\n I --> K[生成诊断报告]\n J --> K\n```\n\n### 3. pm - 包管理命令\n\npm 命令提供 grainulation 工具生态系统的包管理功能。\n\n```bash\ngrainulation pm [subcommand] [options]\n```\n\n**子命令**\n\n| 子命令 | 描述 |\n|--------|------|\n| `install` | 安装指定工具包 |\n| `uninstall` | 卸载指定工具包 |\n| `update` | 更新工具包到最新版本 |\n| `list` | 列出已安装的工具包 |\n| `search` | 在npm registry中搜索工具 |\n\n**install 子命令选项**\n\n| 选项 | 描述 | 示例 |\n|------|------|------|\n| `--save` | 保存到package.json依赖 | `pm install wheat --save` |\n| `--global` | 全局安装 | `pm install --global farmer` |\n| `--version` | 指定版本安装 | `pm install barn@1.3.0` |\n\n### 4. ecosystem - 生态系统命令\n\necosystem 命令用于检查整个 grainulation 工具生态系统的健康状态和可用性。\n\n```bash\ngrainulation ecosystem [options]\n```\n\n**功能说明**\n\n- 检查所有工具包的最新版本\n- 验证工具包在npm上的可用性\n- 生成生态系统健康报告\n- 检测过时工具包\n\n**输出示例**\n\n```\n生态系统健康检查\n✓ wheat@1.2.0 - 最新\n✓ farmer@0.9.5 - 最新\n⚠ barn@1.2.0 - 可用更新: 1.3.0\n✓ mill@2.1.0 - 最新\n```\n\n### 5. setup - 初始设置命令\n\nsetup 命令处理 grainulation CLI 的首次运行配置。\n\n```bash\ngrainulation setup [options]\n```\n\n**功能说明**\n\n- 创建必要的配置文件\n- 初始化本地工具缓存\n- 配置默认工具路径\n- 验证环境依赖\n\n**自动执行流程**\n\n```mermaid\ngraph LR\n A[首次运行grainulation] --> B{检测配置文件}\n B -->|不存在| C[运行setup]\n B -->|已存在| D[跳过setup]\n C --> E[创建配置目录]\n E --> F[生成grainulation.config.json]\n F --> G[验证Node.js环境]\n G --> H[完成初始化]\n```\n\n### 6. server - 本地服务器命令\n\nserver 命令启动统一的生态系统仪表盘Web界面。\n\n```bash\ngrainulation server [options]\n```\n\n**功能说明**\n\n- 启动本地HTTP服务器\n- 提供Web UI界面查看所有工具状态\n- 支持实时工具健康监控\n- 提供SSE（Server-Sent Events）实时更新\n\n**服务器选项**\n\n| 选项 | 描述 | 默认值 |\n|------|------|--------|\n| `--port, -p` | 指定服务器端口 | 3000 |\n| `--host` | 指定服务器主机 | localhost |\n| `--open` | 启动后自动打开浏览器 | false |\n\n**使用示例**\n\n```bash\n# 启动服务器\ngrainulation server\n\n# 指定端口并自动打开浏览器\ngrainulation server --port 8080 --open\n```\n\n## 工具包路由机制\n\ngrainulation CLI 的核心功能是将命令路由到正确的工具包。路由机制通过 `lib/router.js` 实现。\n\n```mermaid\ngraph TD\n A[用户输入命令] --> B[bin/grainulation.js]\n B --> C[解析命令类型]\n C --> D{是否为内置命令?}\n D -->|doctor| E[执行lib/doctor.js]\n D -->|pm| F[执行lib/pm.js]\n D -->|ecosystem| G[执行lib/ecosystem.js]\n D -->|setup| H[执行lib/setup.js]\n D -->|server| I[执行lib/server.mjs]\n D -->|其他| J[lib/router.js路由]\n J --> K[定位工具包]\n K --> L[执行工具包命令]\n L --> M[返回结果]\n```\n\n### 路由配置\n\n路由系统支持以下工具包前缀：\n\n| 前缀 | 工具包 | 用途 |\n|------|--------|------|\n| `wheat` | @grainulation/wheat | 研究和挑战工具 |\n| `farmer` | @grainulation/farmer | 权限仪表盘 |\n| `barn` | @grainulation/barn | 共享工具库 |\n| `mill` | @grainulation/mill | 导出和发布工具 |\n| `silo` | @grainulation/silo | 存储管理 |\n| `harvest` | @grainulation/harvest | 分析工具 |\n| `orchard` | @grainulation/orchard | 状态管理 |\n\n## 环境要求\n\n### Node.js版本要求\n\ngrainulation CLI 要求 **Node.js 20.0.0** 或更高版本。\n\n```bash\n# 检查Node.js版本\nnode --version\n\n# 要求版本\nnode >= 20.0.0\n```\n\n### 零依赖设计\n\ngrainulation 核心CLI包采用零npm依赖设计，完全基于Node.js内置模块构建。资料来源：[package.json](https://github.com/grainulation/grainulation/blob/main/package.json)\n\n**内置依赖使用情况**\n\n| 模块 | 用途 |\n|------|------|\n| `fs` | 文件系统操作 |\n| `path` | 路径处理 |\n| `child_process` | 子进程执行 |\n| `http`/`https` | 网络请求 |\n| `url` | URL解析 |\n| `os` | 操作系统信息 |\n\n## 配置文件\n\n### 配置文件位置\n\ngrainulation 使用以下配置文件：\n\n| 文件名 | 位置 | 用途 |\n|--------|------|------|\n| `grainulation.config.json` | 用户主目录 | 全局配置 |\n| `.grainulationrc` | 当前目录 | 项目级配置 |\n\n### 配置文件结构\n\n```json\n{\n \"version\": \"1.0.0\",\n \"tools\": {\n \"installed\": [\"wheat\", \"farmer\", \"barn\"],\n \"path\": \"~/.grainulation/tools\"\n },\n \"server\": {\n \"port\": 3000,\n \"host\": \"localhost\"\n },\n \"registry\": \"https://registry.npmjs.org/\"\n}\n```\n\n## 常见用法示例\n\n### 完整工作流程\n\n```bash\n# 1. 首次使用：检查环境健康\ngrainulation doctor\n\n# 2. 查看生态系统状态\ngrainulation ecosystem\n\n# 3. 安装所需工具\ngrainulation pm install wheat\ngrainulation pm install farmer\n\n# 4. 启动本地仪表盘\ngrainulation server --open\n\n# 5. 在另一终端使用wheat进行研究\nwheat init \"我们的系统应该使用微服务吗?\"\n```\n\n### 诊断和修复\n\n```bash\n# 诊断问题\ngrainulation doctor\n\n# 自动修复\ngrainulation doctor --fix\n\n# 查看JSON格式诊断结果\ngrainulation doctor --json\n```\n\n### 包管理操作\n\n```bash\n# 列出已安装的工具\ngrainulation pm list\n\n# 搜索可用工具\ngrainulation pm search auth\n\n# 安装特定版本\ngrainulation pm install barn@1.3.0\n\n# 更新所有工具\ngrainulation pm update\n```\n\n## 错误处理\n\n### 常见错误及解决方案\n\n| 错误代码 | 描述 | 解决方案 |\n|---------|------|---------|\n| `E_NODE_VERSION` | Node.js版本过低 | 升级到Node.js 20+ |\n| `E_TOOL_NOT_FOUND` | 工具包未安装 | 运行 `grainulation pm install ` |\n| `E_TOOL_BROKEN` | 工具包损坏 | 运行 `grainulation doctor --fix` |\n| `E_REGISTRY_UNREACHABLE` | npm registry不可达 | 检查网络连接和代理设置 |\n| `E_PERMISSION_DENIED` | 权限不足 | 使用sudo或检查文件权限 |\n\n### 调试模式\n\n启用调试模式以获取详细日志：\n\n```bash\nDEBUG=grainulation:* grainulation \n```\n\n## 与wheat工具的集成\n\ngrainulation CLI 与 `@grainulation/wheat` 工具深度集成，提供完整的研究决策流程支持。\n\n```mermaid\ngraph LR\n A[grainulation wheat] --> B[wheat init
初始化研究项目]\n B --> C[wheat /research
收集证据]\n C --> D[wheat /challenge
挑战Claims]\n D --> E[wheat /brief
编译决策简报]\n E --> F[grainulation mill
导出报告]\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 相关资源\n\n- [官方文档](https://grainulation.com)\n- [wheat工具文档](https://wheat.grainulation.com)\n- [farmer工具文档](https://farmer.grainulation.com)\n- [GitHub仓库](https://github.com/grainulation/grainulation)\n\n---\n\n\n\n## 生态系统概览\n\n### 相关页面\n\n相关主题：[工具集成与协作](#page-tools-integration), [项目概述](#page-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/grainulation/grainulation/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n- [RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)\n- [site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n \n\n# 生态系统概览\n\nGrainulation 是一个由八个零依赖 CLI 工具组成的生态系统，旨在将技术问题转化为结构化的、带类型标注的、可审计的决策声明。整个系统基于 Node.js 原生模块构建，不依赖任何外部 npm 包，实现本地化运行和可复现的决策流程。\n\n## 核心设计理念\n\nGrainulation 的核心理念源于一个观察：**大多数决策失败不是因为团队缺乏数据，而是缺乏将数据转化为证据、将证据转化为决策的过程**。系统围绕四个基本原则构建：\n\n| 原则 | 说明 |\n|------|------|\n| 证据驱动 | 每个声明都是带类型、置信度和证据等级的声明 |\n| 编译器验证 | 编译器是确定性 JavaScript 代码，而非 LLM 调用，确保相同输入产生相同输出 |\n| 对抗性挑战 | 系统强制团队挑战、见证和压力测试每个声明 |\n| 零依赖 | 全部八个包仅使用 Node.js 内置模块 |\n\n资料来源：[README.md:1-15]()\n\n## 八工具架构\n\n整个生态系统包含八个独立工具，每个工具专注于一个特定功能。以下是完整工具矩阵：\n\n| 工具名称 | 功能角色 | 核心用途 |\n|----------|----------|----------|\n| **wheat** | 研究引擎 | 增长结构化证据，创建声明文件 |\n| **farmer** | 权限仪表板 | 从手机、另一标签页或会议审批 AI 代理工具调用 |\n| **barn** | 证据存储 | 结构化存储所有研究和声明 |\n| **mill** | 导出发布 | 将编译后的研究转换为 PDF、CSV 和静态站点 |\n| **silo** | 证据验证 | 独立验证声明，检测不一致 |\n| **harvest** | 分析统计 | 跨 Sprint 学习，追踪预测准确性 |\n| **orchard** | 配置管理 | 状态面板，管理所有工具配置 |\n| **grainulation** | 统一 CLI | 元工具，路由到正确工具，检查生态系统健康状态 |\n\n资料来源：[site/index.html:140-180]()\n\n## 工具协作流程\n\n```mermaid\ngraph TD\n subgraph 研究阶段\n A[wheat init] --> B[Research & Challenge]\n B --> C[创建声明]\n C --> D[收集证据]\n end\n \n subgraph 验证阶段\n D --> E[silo 验证]\n E --> F{验证通过?}\n F -->|否| G[修复问题]\n G --> D\n end\n \n subgraph 编译阶段\n F -->|是| H[barn 存储]\n H --> I[harvest 分析]\n I --> J[mill 导出]\n end\n \n subgraph 协作阶段\n J --> K[farmer 审批]\n K --> L[orchard 管理]\n end\n \n J --> M[决策简报]\n```\n\n工具之间的依赖关系遵循特定顺序：当需要发布新版本时（如 `barn`），需要先发布被依赖的包，等待其出现在 npm 上，然后更新消费者仓库的依赖。\n\n资料来源：[RELEASE.md:1-30]()\n\n## 架构层次\n\nGrainulation 采用分层架构设计：\n\n```mermaid\ngraph TB\n subgraph 用户交互层\n A[统一 CLI: grainulation]\n B[wheat REPL]\n C[farmer Web 界面]\n end\n \n subgraph 核心库\n D[lib/router.js 路由]\n E[lib/ecosystem.js 生态系统]\n F[lib/doctor.js 诊断]\n G[lib/setup.js 配置]\n H[lib/pm.js 包管理]\n end\n \n subgraph 数据层\n I[claims.json]\n J[wheat.config.json]\n K[barn 存储]\n end\n \n A --> D\n B --> D\n C --> H\n D --> E\n D --> F\n D --> G\n E --> H\n H --> K\n F --> J\n G --> J\n```\n\n### 核心组件说明\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| CLI 入口点 | `bin/grainulation.js` | 路由到各个工具包 |\n| 命令路由 | `lib/router.js` | 将命令分发到正确的工具包 |\n| 生态系统 | `lib/ecosystem.js` | 健康检查和工具发现 |\n| 诊断工具 | `lib/doctor.js` | 验证工具安装状态 |\n| 首次设置 | `lib/setup.js` | 首次运行设置和配置 |\n| 包管理 | `lib/pm.js` | grainulation 工具的包管理 |\n\n资料来源：[CONTRIBUTING.md:20-45]()\n\n## 声明类型系统\n\nGrainulation 的核心抽象是**声明（Claim）**——一个带有类型和证据等级的单个声明语句。声明具有以下属性：\n\n| 属性 | 可选值 | 说明 |\n|------|--------|------|\n| 类型 | factual, risk, estimate, constraint, recommendation | 声明的语义类别 |\n| 证据等级 | 从\"有人说\"到\"生产环境测量\" | 证据强度 |\n| ID | r001, x001 等 | 全局唯一标识 |\n\n系统通过编译器验证声明的一致性，检测矛盾，并标记弱证据。\n\n资料来源：[site/index.html:200-220]()\n\n## 快速上手路径\n\n```mermaid\ngraph LR\n A[\"npx @grainulation/wheat init\"] --> B[初始化 Sprint]\n B --> C[Research & Challenge]\n C --> D[/brief 编译]\n D --> E[决策简报]\n \n A -.->|或者| F[\"npm install -g @grainulation/grainulation\"]\n F --> G[\"grainulation setup\"]\n G --> A\n```\n\n### 基础命令\n\n```bash\n# 生态系统概览\ngrainulation\n\n# 健康检查\ngrainulation doctor\n\n# 安装适合角色的工具\ngrainulation setup\n\n# 初始化研究 Sprint\ngrainulation wheat init\n# 或直接\nnpx @grainulation/wheat init\n```\n\n资料来源：[README.md:30-50]()\n\n## 发布与版本管理\n\n生态系统采用协调发布机制，确保包之间的依赖关系正确：\n\n```mermaid\nsequenceDiagram\n participant Dev as 开发者\n participant Barn as barn 包\n participant Consumer as 消费者包\n participant NPM as npm registry\n \n Dev->>Barn: npm version patch\n Dev->>Barn: git push --follow-tags\n Barn->>NPM: 发布 v1.2.3\n NPM-->>Dev: 发布成功\n \n Dev->>Consumer: 修改依赖版本\n Consumer->>NPM: npm install\n NPM-->>Consumer: 获取新版本 barn\n Consumer->>Consumer: 更新 package-lock.json\n```\n\n每个包通过 `.github/workflows/publish.yml` 在标签推送时自动发布，使用 npm provenance 通过 OIDC 可信发布（无需 NPM_TOKEN）。\n\n资料来源：[RELEASE.md:10-25]()\n\n## 技术约束\n\n| 约束项 | 要求 |\n|--------|------|\n| Node.js 版本 | 20+ |\n| 依赖策略 | 零 npm 依赖，仅 Node.js 内置模块 |\n| API 密钥 | 核心工具无需 API 密钥 |\n| 云服务 | 无需云服务 |\n| 运行方式 | 全部本地运行 |\n| 数据格式 | 纯 JSON 和 HTML |\n\n资料来源：[site/index.html:225-235]()\n\n## 相关文档\n\n- [wheat 工具文档](https://wheat.grainulation.com/) — 研究引擎\n- [farmer 工具文档](https://farmer.grainulation.com/) — 权限仪表板\n- [barn 工具文档](https://barn.grainulation.com/) — 证据存储\n- [mill 工具文档](https://mill.grainulation.com/) — 导出发布\n\n---\n\n\n\n## 工具集成与协作\n\n### 相关页面\n\n相关主题：[生态系统概览](#page-ecosystem), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)\n- [lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)\n- [lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/lib/ecosystem.js)\n- [lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/lib/doctor.js)\n- [lib/setup.js](https://github.com/grainulation/grainulation/blob/main/lib/setup.js)\n- [lib/pm.js](https://github.com/grainulation/grainulation/blob/main/lib/pm.js)\n- [CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n- [RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)\n \n\n# 工具集成与协作\n\n## 概述\n\nGrainulation 是一个元包（meta-package），通过统一的 CLI 入口点协调整个工具生态系统。它本身不提供核心研究功能，而是作为八个独立工具包的路由层和编排层存在。这种设计遵循单一职责原则，使每个工具（Wheat、Farmer、Barn、Mill、Silo、Harvest、Orchard）能够独立发布和演进，同时通过统一的入口点提供一致的用户体验。\n\n工具集成架构的核心目标是实现**零依赖**生态——所有工具都基于 Node.js 内置模块构建，不依赖外部 npm 包。Grainulation 作为中央协调器，负责命令路由、健康检查、工具发现和包管理等职责，使各个工具能够无缝协作。\n\n## 核心架构\n\nGrainulation 的架构采用分层设计，从上到下依次为：CLI 入口层、路由层、生态系统层和工具层。这种分层确保了各组件之间的松耦合，便于独立扩展和维护。\n\n```mermaid\ngraph TB\n subgraph \"CLI 入口层\"\n CLI[\"bin/grainulation.js
统一命令行入口\"]\n end\n \n subgraph \"路由层\"\n ROUTER[\"lib/router.js
命令路由\"]\n end\n \n subgraph \"生态系统层\"\n ECO[\"lib/ecosystem.js
健康检查与工具发现\"]\n DOCTOR[\"lib/doctor.js
诊断工具\"]\n PM[\"lib/pm.js
包管理\"]\n SETUP[\"lib/setup.js
首次配置\"]\n end\n \n subgraph \"工具层\"\n WHEAT[\"@grainulation/wheat
核心研究引擎\"]\n FARMER[\"@grainulation/farmer
权限仪表板\"]\n BARN[\"@grainulation/barn
SSE 通信\"]\n MILL[\"@grainulation/mill
导出与发布\"]\n SILO[\"@grainulation/silo
统一 CLI\"]\n HARVEST[\"@grainulation/harvest
分析工具\"]\n ORCHARD[\"@grainulation/orchard
编排工具\"]\n end\n \n CLI --> ROUTER\n ROUTER --> ECO\n ROUTER --> WHEAT\n ROUTER --> FARMER\n ROUTER --> BARN\n ROUTER --> MILL\n ROUTER --> SILO\n ROUTER --> HARVEST\n ROUTER --> ORCHARD\n ECO --> DOCTOR\n ECO --> PM\n ECO --> SETUP\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## CLI 入口点\n\n### bin/grainulation.js\n\n`bin/grainulation.js` 是整个生态系统的统一命令行入口点。它负责接收用户输入并将其路由到相应的工具包。该入口点支持 `--help` 参数来显示帮助信息，用户无需安装任何依赖即可通过 `npx grainulation` 直接运行。\n\n入口脚本的设计理念是**零安装依赖**——用户只需拥有 Node.js 20+ 和 npx 即可使用所有功能。这种设计降低了入门门槛，使用户能够快速开始技术决策研究工作。\n\nCLI 入口点采用命令路由模式，根据输入的命令参数将请求转发到具体的工具包。例如，当用户执行 `npx grainulation orchard status` 时，入口点会识别 `orchard` 子命令并将其路由到对应的工具包。\n\n### 快速启动流程\n\n用户可以通过以下命令快速启动 Grainulation 生态系统：\n\n```bash\nnode bin/grainulation.js --help\n```\n\n无需执行 `npm install` 命令，因为 grainulation 本身没有 npm 依赖。这一特性确保了工具的即开即用性。\n\n资料来源：[bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 命令路由机制\n\n### lib/router.js\n\n`lib/router.js` 是 Grainulation 的核心路由模块，负责将命令分发到正确的工具包。它解析用户输入的命令参数，识别目标工具，并将控制权传递给相应的工具模块。\n\n路由机制支持以下功能：\n\n| 功能 | 说明 |\n|------|------|\n| 子命令识别 | 解析如 `orchard status`、`wheat init` 等子命令 |\n| 参数传递 | 将用户参数原样传递给目标工具 |\n| 错误处理 | 识别无效命令并提供友好的错误提示 |\n| 帮助路由 | 将 `--help` 请求路由到对应工具的帮助系统 |\n\n路由层的设计遵循**无状态原则**——每个路由请求都是独立的，不依赖前一个请求的状态。这使得路由层能够高效处理并发请求，同时简化了测试和调试过程。\n\n当用户执行子命令时，路由器会验证目标工具是否已安装。如果工具未安装，路由器会提示用户通过包管理器安装相应工具，或提供直接使用 npx 运行工具的备选方案。\n\n资料来源：[lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 生态系统管理\n\n### lib/ecosystem.js\n\n`lib/ecosystem.js` 负责整个生态系统的健康检查和工具发现功能。它维护已安装工具的注册表，并提供接口用于检查工具的可用性和版本状态。\n\n生态系统管理器的核心职责包括：\n\n- **工具发现**：扫描已安装的 @grainulation/* 包并注册其功能\n- **健康检查**：验证每个工具包的安装完整性和版本兼容性\n- **状态报告**：汇总所有工具的运行状态并生成统一报告\n\n健康检查流程会验证每个工具的以下条件：package.json 配置完整性、入口脚本可执行性、以及必需的依赖项是否满足。通过这种主动检查机制，系统能够在用户执行命令前发现并报告潜在问题。\n\n### lib/doctor.js\n\n`lib/doctor.js` 是一个诊断工具，用于验证工具安装和问题排查。它提供交互式诊断流程，帮助用户识别和解决常见的配置问题。\n\n诊断工具会执行以下检查项目：\n\n1. Node.js 版本验证（需要 20+）\n2. npm/npx 可用性检查\n3. Grainulation 包安装状态验证\n4. 子工具包完整性检查\n5. 配置文件权限验证\n\n当检测到问题时，doctor 会提供具体的修复建议，包括需要执行的命令和配置修改步骤。\n\n资料来源：[lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/lib/ecosystem.js)\n资料来源：[lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/lib/doctor.js)\n\n## 包管理集成\n\n### lib/pm.js\n\n`lib/pm.js` 实现了 Grainulation 工具的包管理功能。它封装了 npm 的核心操作，提供统一的接口用于安装、更新和卸载 grainulation 工具包。\n\n包管理功能支持以下操作：\n\n| 操作 | 命令 | 说明 |\n|------|------|------|\n| 安装 | `pm install ` | 安装指定工具包 |\n| 卸载 | `pm uninstall ` | 移除已安装工具包 |\n| 更新 | `pm update ` | 更新到最新版本 |\n| 列表 | `pm list` | 显示已安装工具包 |\n\n包管理器与生态系统层紧密集成，当安装新工具时会自动触发生态系统健康检查，确保新工具与现有工具版本兼容。\n\n### lib/setup.js\n\n`lib/setup.js` 负责首次运行设置和配置初始化。它检测用户环境，生成必要的配置文件，并引导用户完成初始配置流程。\n\n首次设置流程包括以下步骤：\n\n1. **环境检测**：验证 Node.js 版本和必需工具\n2. **目录创建**：初始化配置目录和数据存储位置\n3. **配置生成**：创建默认配置文件\n4. **欢迎引导**：展示快速开始指南和下一步建议\n\n设置模块会检查 `~/.grainulation/` 目录是否存在，如果不存在则自动创建。该目录用于存储用户级别的配置和跨项目共享的数据。\n\n资料来源：[lib/pm.js](https://github.com/grainulation/grainulation/blob/main/lib/pm.js)\n资料来源：[lib/setup.js](https://github.com/grainulation/grainulation/blob/main/lib/setup.js)\n\n## 发布流程与工具协调\n\n### 统一发布机制\n\nGrainulation 生态系统采用集中式发布策略，所有工具包通过统一的 GitHub Actions 工作流发布。每个包在其自己的仓库中维护，但发布流程由 grainulation 的发布规范协调。\n\n发布架构遵循以下原则：\n\n- **独立版本控制**：每个工具包维护自己的语义化版本号\n- **自动化发布**：通过标签推送触发 CI/CD 流程\n- **可信发布**：使用 npm OIDC 信任发布，无需 API token\n\n资料来源：[RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)\n\n### 单包发布流程\n\n对于单包补丁发布，流程如下：\n\n```mermaid\ngraph LR\n A[进入包目录] --> B[执行 npm version patch]\n B --> C[更新 package.json 和标签]\n C --> D[推送提交和标签]\n D --> E[GitHub Actions 运行测试]\n E --> F{测试通过?}\n F -->|是| G[发布到 npm]\n F -->|否| H[终止发布]\n G --> I[验证 npm 注册表]\n```\n\n发布工作流会自动验证标签与 package.json 版本号匹配，确保发布的一致性。\n\n### 协调发布流程\n\n当工具包之间存在依赖关系时（如 barn 新版本被其他工具依赖），需要执行协调发布流程：\n\n1. **按依赖顺序发布**：先发布被依赖的包\n2. **等待 npm 同步**：等待约 60 秒让新版本同步到 npm\n3. **更新依赖包**：在消费包中执行 `npm install` 更新依赖\n4. **提交锁定文件**：将更新后的 package-lock.json 提交到仓库\n\n这种协调机制确保了生态系统内部版本的一致性，避免了依赖缺失问题。\n\n资料来源：[RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)\n\n## 工具协作模式\n\n### 核心工具：Wheat\n\nWheat 是 Grainulation 生态系统的核心研究引擎，负责启动和管理整个研究冲刺（sprint）生命周期。它是用户首先接触的工具，也是协调其他工具协作的起点。\n\nWheat 的核心命令流程：\n\n1. **初始化冲刺**：`npx @grainulation/wheat init` - 创建 claims.json 和配置文件\n2. **添加证据**：`/research \"topic\"` - 收集研究证据并生成声明\n3. **挑战证据**：`/challenge r001` - 对已有证据进行对抗性测试\n4. **生成简报**：`/brief` - 编译所有声明并生成决策文档\n\n### 权限管理：Farmer\n\nFarmer 提供实时权限仪表板功能，允许用户从手机、另一浏览器标签页或会议中批准 AI 代理的工具调用。它通过 SSE（Server-Sent Events）与 Barn 组件通信，实现实时状态同步。\n\n### 通信中枢：Barn\n\nBarn 是 SSE 通信层的实现，为 Farmer 和其他需要实时通信的工具提供基础设施。它处理事件流分发、连接管理和消息路由，确保实时交互的可靠性。\n\n### 导出工具：Mill\n\nMill 负责将编译后的研究成果导出为多种格式（PDF、CSV、静态站点），满足不同场景的分享需求。\n\n### 分析工具：Harvest\n\nHarvest 提供跨冲刺的学习分析功能，追踪预测准确性、发现系统性盲点、检测过时声明，帮助团队持续改进研究质量。\n\n### 编排工具：Orchard\n\nOrchard 是元工具（meta-tool），负责路由到正确工具、检查生态系统健康状况、管理所有八个包的配置。\n\n### 统一入口：Silo\n\nSilo 提供统一的 CLI 界面，整合所有工具的访问入口，简化多工具使用场景下的命令行操作。\n\n## 工具间数据流\n\nGrainulation 生态系统中的数据流动遵循声明式设计模式，所有工具共享统一的 claims 数据结构。这种设计确保了工具间协作的无缝性。\n\n```mermaid\ngraph LR\n WHEAT[Wheat
收集声明] --> CLAIMS[claims.json
统一声明存储]\n FARMER[Farmer
权限管理] --> CLAIMS\n CLAIMS --> MILL[Mill
导出格式转换]\n CLAIMS --> HARVEST[Harvest
跨冲刺分析]\n CLAIMS --> SILO[Silo
统一查询]\n CLAIMS --> ORCHARD[Orchard
状态汇总]\n \n BARN[Barn
SSE通信] -.->|实时更新| FARMER\n BARN -.->|事件通知| WHEAT\n```\n\n声明（Claim）是 Grainulation 系统的核心数据单元，每个声明包含：\n\n| 字段 | 说明 |\n|------|------|\n| id | 声明唯一标识符（如 r001、x001） |\n| type | 类型：factual、risk、estimate、constraint、recommendation |\n| tier | 证据等级：从\"有人说过\"到\"生产环境测量\" |\n| content | 声明内容文本 |\n| evidence | 支持证据列表 |\n| challenges | 挑战记录列表 |\n| timestamp | 创建时间戳 |\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n## 测试与验证\n\n### 基本测试框架\n\nGrainulation 使用 Node.js 内置测试运行器进行基本功能验证。测试文件位于 `test/basic.test.js`，通过以下命令执行：\n\n```bash\nnode test/basic.test.js\n```\n\n测试覆盖范围包括：\n\n- CLI 入口点参数解析\n- 命令路由正确性\n- 工具发现机制\n- 配置文件生成\n- 健康检查流程\n\n### CI/CD 集成\n\n每个工具包都配置了 GitHub Actions 工作流进行持续集成。CI 流程自动运行测试套件，确保代码变更不会破坏现有功能。\n\n发布前的工作流检查项目：\n\n1. 单元测试通过\n2. 集成测试通过\n3. 代码覆盖率达标\n4. 版本号一致性验证\n5. npm 发布签名验证\n\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 配置与自定义\n\n### 全局配置\n\nGrainulation 在 `~/.grainulation/` 目录中存储用户级配置。配置采用 JSON 格式，支持以下自定义项：\n\n```json\n{\n \"registry\": \"https://registry.npmjs.org/\",\n \"telemetry\": false,\n \"theme\": \"default\",\n \"editor\": \"vim\"\n}\n```\n\n### 项目级配置\n\n每个 Wheat 冲刺包含独立的配置文件 `wheat.config.json`，存储冲刺特定的设置，如约束条件、参与者信息和决策标准。\n\n### 环境变量\n\nGrainulation 支持通过环境变量进行高级配置：\n\n| 变量 | 说明 | 默认值 |\n|------|------|--------|\n| `GRAINULATION_HOME` | 配置目录路径 | `~/.grainulation/` |\n| `GRAINULATION_REGISTRY` | npm 注册表地址 | npmjs.org |\n| `GRAINULATION_DEBUG` | 启用调试模式 | false |\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 原因 | 解决方案 |\n|------|------|----------|\n| 命令未找到 | 工具包未安装 | 运行 `npx @grainulation/ help` |\n| Node 版本过低 | Node.js < 20 | 升级到 Node.js 20+ |\n| 权限错误 | 配置目录不可写 | 检查目录权限或重新创建 |\n| 发布失败 | 标签版本不匹配 | 确保 package.json 版本与标签一致 |\n\n### 诊断命令\n\n使用 doctor 工具进行系统诊断：\n\n```bash\nnode bin/grainulation.js doctor\n```\n\n诊断工具会逐步检查环境并提供修复建议。\n\n## 扩展与贡献\n\n### 添加新工具\n\n要将新工具集成到 Grainulation 生态系统，需要：\n\n1. 创建独立的 npm 包 `@grainulation/`\n2. 在 grainulation 的路由配置中注册新工具\n3. 更新生态系统健康检查以包含新工具\n4. 添加相应的文档和测试\n\n### 贡献流程\n\n贡献代码的标准流程：\n\n1. Fork 仓库并创建功能分支\n2. 进行代码修改并编写测试\n3. 运行 `node test/basic.test.js` 验证\n4. 提交并推送变更\n5. 创建 Pull Request 供审查\n\n所有贡献者应遵循项目的行为准则，确保社区健康持续发展。\n\n资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n---\n\n\n\n## 健康检查与诊断\n\n### 相关页面\n\n相关主题：[CLI命令参考](#page-cli-commands), [故障排除](#page-troubleshooting)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/lib/doctor.js)\n- [bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)\n- [lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/lib/ecosystem.js)\n- [lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)\n- [lib/setup.js](https://github.com/grainulation/grainulation/blob/main/lib/setup.js)\n \n\n# 健康检查与诊断\n\nGrainulation 生态系统的健康检查与诊断功能是确保工具链可靠运行的核心模块。该模块负责验证工具安装状态、检测生态系统完整性，并提供统一的诊断入口。\n\n## 概述\n\nGrainulation 采用零依赖架构设计，所有健康检查功能均基于 Node.js 内置模块实现。诊断系统由多个组件协同工作，包括 `doctor.js` 诊断工具、生态系统健康检查模块以及统一的 CLI 路由层。资料来源：[CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n### 核心职责\n\n健康检查与诊断模块承担以下核心职责：\n\n| 模块 | 职责描述 |\n|------|----------|\n| 诊断工具 | 验证各工具包的安装状态，检测配置完整性 |\n| 健康检查 | 监控生态系统整体健康状态，发现工具缺失 |\n| 路由分发 | 将诊断命令正确路由至对应工具 |\n| 配置验证 | 检查 wheat.config.json 等配置文件有效性 |\n\n资料来源：[CONTRIBUTING.md:lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 系统架构\n\n健康检查与诊断系统采用分层架构设计，从 CLI 入口到具体诊断模块逐层传递。\n\n```mermaid\ngraph TD\n A[bin/grainulation.js
CLI 入口] --> B[lib/router.js
命令路由]\n B --> C[lib/doctor.js
诊断工具]\n B --> D[lib/ecosystem.js
生态系统]\n C --> E[工具安装验证]\n C --> F[配置文件检查]\n D --> G[健康状态检查]\n D --> H[工具发现]\n```\n\n### 各层组件说明\n\n**CLI 入口层**\n\n`bin/grainulation.js` 是整个生态系统的统一 CLI 入口点，负责接收用户命令并路由至正确的工具。该文件不依赖任何外部包，直接使用 Node.js 内置模块实现基础功能。资料来源：[CONTRIBUTING.md:bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n**命令路由层**\n\n`lib/router.js` 负责将诊断相关命令分发至对应的处理模块。路由层会根据命令类型判断是执行诊断检查还是其他工具操作。资料来源：[CONTRIBUTING.md:lib/router.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n**诊断执行层**\n\n`lib/doctor.js` 是核心诊断工具，执行以下验证操作：\n\n- 验证 grainulation 工具链中各包的安装状态\n- 检查 Node.js 版本兼容性\n- 检测 wheat.config.json 配置文件是否存在且有效\n- 扫描所有八个工具包的健康状态\n\n资料来源：[CONTRIBUTING.md:lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n**生态系统层**\n\n`lib/ecosystem.js` 负责整个生态系统的健康检查和工具发现功能。该模块会枚举已安装的工具包，并生成生态系统状态报告。资料来源：[CONTRIBUTING.md:lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 诊断工具详解\n\n### doctor.js 核心功能\n\n诊断工具提供三类核心检查能力：\n\n| 检查类型 | 检查内容 | 输出格式 |\n|----------|----------|----------|\n| 安装验证 | 验证 @grainulation/* 包是否正确安装 | 状态列表 |\n| 版本检查 | 确认 Node.js 版本是否满足要求 | 版本兼容性报告 |\n| 配置校验 | 检查项目级配置文件完整性 | 配置文件状态 |\n\n### 检查流程\n\n```mermaid\ngraph TD\n A[启动诊断] --> B{Node.js 版本检查}\n B -->|版本过低| C[输出警告]\n B -->|版本兼容| D[检查工具安装]\n D --> E{工具包是否存在}\n E -->|缺失| F[标记待安装]\n E -->|完整| G[验证配置文件]\n G --> H[生成诊断报告]\n```\n\n### 错误处理机制\n\n诊断工具采用渐进式错误报告策略。当检测到问题时，系统不会立即终止，而是收集所有问题后统一输出，确保用户能一次性了解所有待修复项。资料来源：[CONTRIBUTING.md:lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 生态系统健康检查\n\n### 健康检查范围\n\n`lib/ecosystem.js` 提供的健康检查覆盖以下维度：\n\n1. **工具发现** - 自动检测系统中已安装的 grainulation 工具\n2. **状态监控** - 实时追踪各工具的运行状态\n3. **依赖关系** - 验证工具间的依赖完整性\n4. **版本一致性** - 确保生态系统内版本同步\n\n资料来源：[CONTRIBUTING.md:lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n### 工具清单\n\nGrainulation 生态系统包含以下八个工具：\n\n| 工具名称 | 用途 | 包名 |\n|----------|------|------|\n| wheat | 研究与决策工作流主工具 | @grainulation/wheat |\n| farmer | AI 代理权限管理 | @grainulation/farmer |\n| mill | 导出与发布工具 | @grainulation/mill |\n| silo | 知识库管理 | @grainulation/silo |\n| orchard | 统一 CLI 协调 | @grainulation/orchard |\n| barn | 共享基础工具 | @grainulation/barn |\n| harvest | 分析与学习 | @grainulation/harvest |\n| grainulation | 元工具与路由 | grainulation |\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n## 配置与设置\n\n### 首次运行设置\n\n`lib/setup.js` 负责首次运行时的初始化配置，包括：\n\n- 创建必要的目录结构\n- 初始化默认配置文件\n- 验证 Node.js 环境\n- 设置本地诊断基准\n\n资料来源：[CONTRIBUTING.md:lib/setup.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n### 配置文件结构\n\n诊断系统依赖以下配置文件：\n\n```json\n{\n \"wheat.config.json\": \"项目级工具配置\",\n \"claims.json\": \"研究声明存储\",\n \".grainulation/\": \"本地生态系统配置目录\"\n}\n```\n\n## 使用方式\n\n### 快速诊断\n\n用户可通过以下命令启动诊断检查：\n\n```bash\nnpx grainulation doctor\n```\n\n### 生态系统状态\n\n查看完整生态系统健康状态：\n\n```bash\nnpx grainulation status\n```\n\n### 详细诊断报告\n\n生成包含所有工具包的详细诊断报告：\n\n```bash\nnpx grainulation doctor --verbose\n```\n\n## 诊断结果解读\n\n### 状态代码\n\n| 状态码 | 含义 | 后续操作 |\n|--------|------|----------|\n| OK | 工具正常安装，配置有效 | 无需操作 |\n| WARN | 发现潜在问题 | 建议检查警告内容 |\n| ERROR | 关键组件缺失 | 需要安装缺失组件 |\n| PENDING | 配置待完成 | 完成初始化设置 |\n\n### 常见问题处理\n\n**工具包缺失**\n\n当诊断报告指示工具包未安装时，可使用 `lib/pm.js` 包管理模块进行安装。资料来源：[CONTRIBUTING.md:lib/pm.js](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n**Node.js 版本不兼容**\n\nGrainulation 要求 Node.js 20 或更高版本。检查当前版本：\n\n```bash\nnode --version\n```\n\n**配置文件损坏**\n\n删除现有配置并重新初始化：\n\n```bash\nnpx grainulation setup --reset\n```\n\n## 技术实现细节\n\n### 零依赖原则\n\n健康检查与诊断模块严格遵循零依赖原则，所有功能基于 Node.js 内置模块实现：\n\n- `fs` 模块 - 文件系统操作\n- `path` 模块 - 路径处理\n- `child_process` - 子进程管理\n- `crypto` - 哈希校验\n\n资料来源：[site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n\n### 本地服务器\n\n诊断结果可通过 `lib/server.mjs` 提供的本地 Web 界面展示。该服务器使用 ESM 模块格式，提供统一的生态系统仪表板视图。资料来源：[CONTRIBUTING.md:lib/server.mjs](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n\n## 相关链接\n\n- 官方文档：https://grainulation.com\n- 工具状态页：https://orchard.grainulation.com/\n- 仓库地址：https://github.com/grainulation/grainulation\n\n---\n\n\n\n## 开发环境配置\n\n### 相关页面\n\n相关主题：[安装指南](#page-installation), [健康检查与诊断](#page-doctor)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [bin/grainulation.js](https://github.com/grainulation/grainulation/blob/main/bin/grainulation.js)\n- [lib/setup.js](https://github.com/grainulation/grainulation/blob/main/lib/setup.js)\n- [lib/doctor.js](https://github.com/grainulation/grainulation/blob/main/lib/doctor.js)\n- [lib/ecosystem.js](https://github.com/grainulation/grainulation/blob/main/lib/ecosystem.js)\n- [lib/router.js](https://github.com/grainulation/grainulation/blob/main/lib/router.js)\n- [lib/pm.js](https://github.com/grainulation/grainulation/blob/main/lib/pm.js)\n- [CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/grainulation/grainulation/blob/main/README.md)\n \n\n# 开发环境配置\n\n## 概述\n\nGrainulation 是一个基于 Node.js 的技术决策研究工具生态系统，其开发环境配置采用零依赖设计理念，仅使用 Node.js 内置模块完成所有功能。整个开发环境围绕 CLI 工具链构建，核心目标是提供一套轻量、可审计的本地化研究流程，帮助团队将技术问题转化为带有类型和置信度评级的结构化声明（claims）。\n\n开发环境配置模块主要负责以下几个核心功能：工具链初始化、环境健康检查、依赖管理、以及命令路由分发。资料来源：[CONTRIBUTING.md]()\n\n## 核心组件架构\n\n### 组件职责矩阵\n\n| 组件文件 | 核心职责 | 依赖关系 |\n|---------|---------|---------|\n| `bin/grainulation.js` | CLI 入口点，命令路由分发 | router.js |\n| `lib/router.js` | 命令路由到具体工具包 | ecosystem.js |\n| `lib/ecosystem.js` | 生态系统健康检查与工具发现 | doctor.js |\n| `lib/doctor.js` | 诊断工具，验证工具安装状态 | 无外部依赖 |\n| `lib/setup.js` | 首次运行配置与初始化 | pm.js |\n| `lib/pm.js` | 工具包管理 | 无外部依赖 |\n\n### 系统架构图\n\n```mermaid\ngraph TD\n A[用户终端] --> B[bin/grainulation.js]\n B --> C[lib/router.js]\n C --> D[lib/ecosystem.js]\n C --> E[lib/setup.js]\n C --> F[lib/doctor.js]\n D --> E\n D --> F\n E --> G[lib/pm.js]\n F --> H[本地工具包检测]\n G --> I[工具包安装/更新]\n H --> J[wheat]\n H --> K[farmer]\n H --> L[barn]\n H --> M[mill]\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 快速开始\n\n### 环境要求\n\n- **Node.js**: 20.x 或更高版本\n- **包管理器**: npx（随 Node.js 内置）\n- **操作系统**: 跨平台支持（Linux、macOS、Windows）\n\nGrainulation 强调零依赖设计，整个生态系统不依赖任何 npm 包，全部使用 Node.js 内置模块实现。资料来源：[README.md]()\n\n### 基础安装\n\n```bash\n# 全局安装主工具\nnpm install -g @grainulation/grainulation\n\n# 或直接使用 npx 运行\nnpx @grainulation/grainulation\n```\n\n### 初始化配置流程\n\n```mermaid\nsequenceDiagram\n 用户->>CLI: grainulation setup\n CLI->>setup.js: 执行初始化\n setup.js->>pm.js: 检查工具包状态\n pm.js->>生态系统: 列出可用工具\n 生态系统-->>setup.js: 工具列表\n setup.js-->>用户: 显示配置向导\n 用户->>setup.js: 选择角色/工具\n setup.js->>本地配置: 写入配置文件\n```\n\n## 命令路由机制\n\n### router.js 工作原理\n\n`lib/router.js` 是整个 CLI 的核心路由模块，负责将用户输入的命令分发到对应的工具包。该模块不依赖任何外部库，仅使用 Node.js 内置的 `fs`、`path`、`url` 等模块读取和解析文件系统结构。\n\n**路由匹配规则**：\n\n1. 解析命令行参数（`process.argv`）\n2. 识别主命令（如 `wheat`、`farmer`、`barn`）\n3. 查找对应的工具包目录\n4. 将控制权传递给目标工具的入口文件\n\n资料来源：[lib/router.js]()\n\n### 可用命令列表\n\n| 命令 | 功能描述 | 入口文件 |\n|-----|---------|---------|\n| `grainulation` | 生态系统概览 | bin/grainulation.js |\n| `grainulation doctor` | 健康检查 | lib/doctor.js |\n| `grainulation setup` | 首次配置 | lib/setup.js |\n| `grainulation wheat init` | 初始化研究冲刺 | wheat 包 |\n| `grainulation farmer start` | 启动权限仪表板 | farmer 包 |\n| `grainulation orchard status` | 编排状态 | orchard 包 |\n\n资料来源：[README.md]()\n\n## 环境健康检查\n\n### doctor.js 诊断功能\n\n`lib/doctor.js` 是 Grainulation 的诊断工具，用于验证本地开发环境的完整性和工具安装状态。该模块执行以下检查：\n\n1. **Node.js 版本验证**：确认当前版本是否满足 20.x+ 要求\n2. **工具包检测**：扫描已安装的 grainulation 工具包\n3. **配置完整性检查**：验证配置文件是否存在且格式正确\n4. **路径环境检查**：确认 `npx` 可访问\n\n### doctor 输出示例\n\n```bash\n$ grainulation doctor\n\n✓ Node.js v20.11.0 (要求: 20.x+)\n✓ npx 可用\n✓ wheat 已安装\n✓ farmer 已安装\n✓ barn 已安装\n⚠ mill 未安装\n✗ orchard 未安装\n\n检查完成: 2 个工具缺失\n运行 'grainulation setup' 安装缺失工具\n```\n\n资料来源：[lib/doctor.js]()\n\n## 首次运行配置\n\n### setup.js 配置流程\n\n`lib/setup.js` 负责首次运行时的初始化工作。该模块会：\n\n1. 检测当前环境的工具包安装状态\n2. 根据用户角色推荐需要安装的工具\n3. 生成用户级配置文件\n4. 设置默认的研究工作目录结构\n\n### 角色化配置\n\nGrainulation 支持根据用户角色进行差异化配置：\n\n| 角色 | 推荐工具组合 | 使用场景 |\n|-----|------------|---------|\n| 研究员 | wheat, barn | 独立研究、快速验证 |\n| 团队负责人 | wheat, barn, mill, harvest | 团队协作、决策汇报 |\n| 全栈 | wheat, farmer, orchard | AI 辅助开发、权限管理 |\n\n资料来源：[lib/setup.js]()\n\n## 包管理机制\n\n### pm.js 工具包管理\n\n`lib/pm.js` 是 Grainulation 的内部包管理器，负责：\n\n1. **工具发现**：扫描 `~/.grainulation/tools/` 目录下的已安装工具\n2. **版本检查**：比较本地版本与 npm 注册表版本\n3. **按需安装**：使用 `npx` 懒加载未安装的工具\n4. **依赖隔离**：每个工具包完全独立，无共享依赖\n\n### 工具包安装流程\n\n```mermaid\ngraph LR\n A[用户请求工具] --> B{pm.js 检测}\n B -->|已安装| C[直接调用]\n B -->|未安装| D[npx 懒加载]\n D --> E[临时安装到缓存]\n E --> F[执行工具]\n F --> G[缓存保留供后续使用]\n```\n\n资料来源：[lib/pm.js]()\n\n## 测试环境配置\n\n### 基本测试\n\nGrainulation 使用 Node.js 内置的测试运行器，无需额外安装测试框架。测试文件位于 `test/` 目录。\n\n```bash\n# 运行基础测试\nnode test/basic.test.js\n```\n\n### 测试覆盖范围\n\n| 测试模块 | 测试内容 | 源码映射 |\n|---------|---------|---------|\n| CLI 入口测试 | 命令行参数解析 | bin/grainulation.js |\n| 路由测试 | 命令分发逻辑 | lib/router.js |\n| 诊断测试 | 健康检查准确性 | lib/doctor.js |\n| 配置测试 | 配置文件生成 | lib/setup.js |\n\n资料来源：[CONTRIBUTING.md]()\n\n## 开发调试\n\n### 本地调试模式\n\n```bash\n# 直接运行本地源码\nnode bin/grainulation.js --help\n\n# 带调试输出运行\nDEBUG=grainulation:* node bin/grainulation.js doctor\n```\n\n### 源码修改工作流\n\n1. **克隆仓库**：\n ```bash\n git clone https://github.com/grainulation/grainulation.git\n cd grainulation\n ```\n\n2. **创建功能分支**：\n ```bash\n git checkout -b feature/description\n ```\n\n3. **修改代码**\n\n4. **运行测试**：\n ```bash\n node test/basic.test.js\n ```\n\n5. **提交并推送**\n\n资料来源：[CONTRIBUTING.md]()\n\n## 配置文件\n\n### 配置文件位置\n\nGrainulation 使用以下配置文件位置：\n\n| 文件类型 | 位置 | 用途 |\n|---------|-----|-----|\n| 用户配置 | `~/.grainulation/config.json` | 全局用户偏好设置 |\n| 工具配置 | `~/.grainulation/tools/` | 各工具的独立配置 |\n| 缓存 | `~/.grainulation/cache/` | 临时数据和下载缓存 |\n| 冲刺数据 | `./sprints/` | 研究冲刺的工作目录 |\n\n### 配置示例\n\n```json\n{\n \"version\": \"1.0.0\",\n \"role\": \"researcher\",\n \"tools\": [\"wheat\", \"barn\"],\n \"preferences\": {\n \"editor\": \"code\",\n \"gitAutoCommit\": true\n }\n}\n```\n\n## 常见问题排查\n\n### 环境问题诊断表\n\n| 问题现象 | 可能原因 | 解决方案 |\n|---------|---------|---------|\n| 命令未找到 | Node.js PATH 配置错误 | 重新安装 Node.js 或检查 PATH |\n| 工具加载失败 | npx 缓存损坏 | 运行 `npx clear-npx-cache` |\n| 配置文件错误 | JSON 格式错误 | 检查 `~/.grainulation/config.json` |\n| 权限错误 | 目录不可写 | 检查 `~/.grainulation/` 权限 |\n\n### 诊断命令\n\n```bash\n# 完整环境诊断\ngrainulation doctor\n\n# 检查 Node 版本\nnode --version\n\n# 检查 npx 可用性\nnpx --version\n```\n\n## 技术实现细节\n\n### 零依赖设计原则\n\nGrainulation 的所有模块均使用 Node.js 内置模块实现，不依赖任何外部 npm 包。这一设计带来以下优势：\n\n- **安全性**：无第三方依赖意味着无供应链攻击风险\n- **可移植性**：任何装有 Node.js 20+ 的环境可直接运行\n- **稳定性**：不受上游包版本变更影响\n- **轻量化**：安装包体积最小化\n\n### 内置模块使用情况\n\n| 模块 | 用途 |\n|-----|-----|\n| `fs` | 文件读写、目录扫描 |\n| `path` | 路径处理、跨平台兼容 |\n| `url` | URL 解析、npx 命令构造 |\n| `child_process` | 子进程管理、命令执行 |\n| `os` | 操作系统信息、临时目录 |\n\n资料来源：[lib/ecosystem.js]()\n\n## 总结\n\nGrainulation 的开发环境配置以简洁和零依赖为核心设计原则，通过模块化的架构实现了工具发现、健康检查、按需加载等关键功能。开发者只需确保 Node.js 20+ 环境即可开始使用，无需复杂的安装流程或依赖管理。这种设计使 Grainulation 成为技术决策研究中可靠、可审计且易于部署的工具选择。\n\n---\n\n\n\n## 故障排除\n\n### 相关页面\n\n相关主题：[健康检查与诊断](#page-doctor), [开发环境配置](#page-setup)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/grainulation/grainulation/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/grainulation/grainulation/blob/main/CONTRIBUTING.md)\n- [RELEASE.md](https://github.com/grainulation/grainulation/blob/main/RELEASE.md)\n- [site/index.html](https://github.com/grainulation/grainulation/blob/main/site/index.html)\n \n\n# 故障排除\n\nGrainulation 生态系统提供了内置的诊断和排查机制，帮助用户快速定位并解决工具安装、配置和环境相关的问题。由于整个项目采用零依赖设计（仅使用 Node.js 内置模块），故障排查主要依赖于 `doctor` 命令和 `setup` 命令提供的诊断信息。\n\n## 诊断工具概述\n\nGrainulation 的故障排查体系由以下核心组件构成：\n\n| 组件 | 文件路径 | 功能 |\n|------|----------|------|\n| `doctor.js` | `lib/doctor.js` | 诊断工具，验证各工具的安装状态 |\n| `ecosystem.js` | `lib/ecosystem.js` | 生态系统健康检查和工具发现 |\n| `setup.js` | `lib/setup.js` | 首次运行设置和配置管理 |\n| `router.js` | `lib/router.js` | 命令路由，将请求分发至正确工具 |\n\n资料来源：[CONTRIBUTING.md:28-34]()\n\n## 诊断命令详解\n\n### grainulation doctor\n\n`doctor` 命令是 Grainulation 生态系统的健康检查工具，用于验证已安装工具的状态和版本信息。\n\n**使用方式：**\n\n```bash\ngrainulation doctor\n```\n\n**功能说明：**\n\n- 检查哪些工具已安装\n- 验证各工具的版本号\n- 报告缺失或过时的工具\n- 提供生态系统整体健康状态报告\n\n资料来源：[README.md:48](), [site/index.html]()\n\n### grainulation setup\n\n`setup` 命令用于首次运行时的工具配置和安装引导。\n\n**使用方式：**\n\n```bash\ngrainulation setup\n```\n\n**功能说明：**\n\n- 根据用户角色安装对应工具\n- 配置必要的环境参数\n- 初始化配置文件（如 `wheat.config.json`）\n\n资料来源：[README.md:47](), [CONTRIBUTING.md:35]()\n\n## 诊断流程图\n\n```mermaid\ngraph TD\n A[用户运行命令] --> B{命令类型}\n B -->|doctor| C[doctor.js 健康检查]\n B -->|setup| D[setup.js 首次配置]\n B -->|其他| E[router.js 命令路由]\n C --> F{工具状态}\n F -->|全部正常| G[输出健康报告]\n F -->|存在问题| H[输出问题列表]\n D --> I[ecosystem.js 工具发现]\n I --> J{工具缺失}\n J -->|是| K[提示安装命令]\n J -->|否| L[配置完成]\n E --> M[路由至对应工具包]\n```\n\n## 环境要求检查\n\nGrainulation 对运行环境有明确要求，在排查问题时首先应确认以下条件：\n\n| 要求 | 最低版本 | 检查命令 |\n|------|----------|----------|\n| Node.js | 20+ | `node --version` |\n| npx | 最新版 | `npx --version` |\n| Claude Code | 需安装 | 需单独配置 |\n\n资料来源：[site/index.html]()\n\n### 常见环境问题\n\n1. **Node.js 版本过低**\n - 症状：运行时报语法错误或模块未找到\n - 解决：升级至 Node.js 20 或更高版本\n\n2. **缺少 Claude Code**\n - 部分高级功能需要 Claude Code 支持\n - 详情参阅 [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code)\n\n## 工具安装问题排查\n\n### 通过 npm 全局安装\n\n```bash\nnpm install -g @grainulation/grainulation\n```\n\n### 通过 npx 直接运行\n\n```bash\nnpx @grainulation/wheat init\nnpx @grainulation/farmer start\nnpx @grainulation/harvest analyze ./sprints/\n```\n\n资料来源：[README.md:37-41]()\n\n### 常见安装问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 找不到命令 | 未正确安装 | 重新运行 `npm install -g` |\n| 版本不匹配 | npm 缓存问题 | 清除缓存 `npm cache clean --force` |\n| 权限错误 | 全局安装需要权限 | 使用 `sudo` 或配置 npm prefix |\n\n## 生态系统健康诊断\n\nGrainulation 的生态系统包含八个独立工具，每个工具都可能需要单独诊断：\n\n| 工具 | 命令 | 功能 |\n|------|------|------|\n| wheat | `wheat init` | 研究引擎，生成结构化证据 |\n| farmer | `farmer start` | 权限仪表板 |\n| mill | `mill export` | 导出工具 |\n| silo | `silo` | 知识管理 |\n| harvest | `harvest analyze` | 跨迭代学习分析 |\n| orchard | `orchard status` | 状态管理 |\n| barn | `barn` | 本地服务器 |\n| grainulation | `grainulation` | 统一 CLI |\n\n资料来源：[README.md:55-62]()\n\n## 发布与测试相关问题\n\nRELEASE.md 描述了完整的发布流程，当构建失败时可参考以下步骤：\n\n### CI/CD 故障排查\n\n发布工作流位于 `.github/workflows/publish.yml`，测试脚本位于 `test/basic.test.js`。\n\n```bash\nnode test/basic.test.js\n```\n\n资料来源：[CONTRIBUTING.md:27](), [RELEASE.md]()\n\n### 发布前检查清单\n\n1. 本地运行测试确保通过\n2. 确认 package.json 版本号正确\n3. 验证标签与版本一致\n4. 等待 npm 发布完成后再更新依赖方\n\n资料来源：[RELEASE.md:15-30]()\n\n## 常见问题速查\n\n### Q: 工具命令找不到\n\n**排查步骤：**\n\n1. 确认已安装：`npm list -g @grainulation/grainulation`\n2. 检查 PATH 配置\n3. 使用完整命令路径测试\n\n### Q: 工具运行报错\n\n**排查步骤：**\n\n1. 检查 Node.js 版本：`node --version`（需 ≥20）\n2. 清除 npm 缓存：`npm cache clean --force`\n3. 重新安装工具\n\n### Q: 生态系统状态异常\n\n**排查步骤：**\n\n1. 运行健康检查：`grainulation doctor`\n2. 检查各子工具版本\n3. 使用 `grainulation setup` 重新配置\n\n### Q: wheat.config.json 相关问题\n\nwheat 工具会创建配置文件如 `wheat.config.json` 和 `claims.json`，确保这些文件存在且格式正确。\n\n资料来源：[site/index.html]()\n\n## 架构级诊断信息\n\nGrainulation 的核心架构如下：\n\n```\nbin/grainulation.js CLI 入口 - 路由至各工具\nlib/router.js 命令路由\nlib/ecosystem.js 生态系统健康检查\nlib/doctor.js 诊断工具\nlib/setup.js 首次运行设置\nlib/pm.js 包管理\nlib/server.mjs 本地服务器\npublic/ Web UI\nsite/ 公共网站\ntest/ 测试文件\n```\n\n资料来源：[CONTRIBUTING.md:22-30]()\n\n## 获取更多帮助\n\n- 查看官方文档：https://grainulation.com\n- 工具特定文档：\n - wheat: https://wheat.grainulation.com\n - farmer: https://farmer.grainulation.com\n - mill: https://mill.grainulation.com\n - silo: https://silo.grainulation.com\n- GitHub Issues: https://github.com/grainulation/grainulation/issues\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：grainulation/grainulation\n\n摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1184031176 | https://github.com/grainulation/grainulation | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1184031176 | https://github.com/grainulation/grainulation | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1184031176 | https://github.com/grainulation/grainulation | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1184031176 | https://github.com/grainulation/grainulation | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1184031176 | https://github.com/grainulation/grainulation | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 来源证据：v1.1.0 — Security Hardening\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 — Security Hardening\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5e8c2578dd024d369fd769a7c23df98a | https://github.com/grainulation/grainulation/releases/tag/v1.1.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 7. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1184031176 | https://github.com/grainulation/grainulation | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1184031176 | https://github.com/grainulation/grainulation | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：grainulation/grainulation\n\n摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1184031176 | https://github.com/grainulation/grainulation | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1184031176 | https://github.com/grainulation/grainulation | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1184031176 | https://github.com/grainulation/grainulation | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1184031176 | https://github.com/grainulation/grainulation | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1184031176 | https://github.com/grainulation/grainulation | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 来源证据：v1.1.0 — Security Hardening\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 — Security Hardening\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5e8c2578dd024d369fd769a7c23df98a | https://github.com/grainulation/grainulation/releases/tag/v1.1.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 7. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1184031176 | https://github.com/grainulation/grainulation | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1184031176 | https://github.com/grainulation/grainulation | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# grainulation - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 grainulation 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: The grainulation ecosystem. Structured research, decision-making, and knowledge management for AI agents. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-quickstart：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n4. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-cli-commands：CLI命令参考。围绕“CLI命令参考”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-quickstart\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-cli-commands\n输入：用户提供的“CLI命令参考”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-quickstart：Step 3 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-architecture：Step 4 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-cli-commands：Step 5 必须围绕“CLI命令参考”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/grainulation/grainulation\n- https://github.com/grainulation/grainulation#readme\n- README.md\n- docs/ecosystem.md\n- package.json\n- lib/setup.js\n- bin/grainulation.js\n- lib/router.js\n- lib/server.mjs\n- lib/ecosystem.js\n- lib/doctor.js\n- lib/pm.js\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 grainulation 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：grainulation/grainulation\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -g @grainulation/grainulation\n```\n\n来源：https://github.com/grainulation/grainulation#readme\n\n## 来源\n\n- repo: https://github.com/grainulation/grainulation\n- docs: https://github.com/grainulation/grainulation#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_5c0769632ff947e08b65a16f9a24f853"
}