{
  "canonical_name": "engincankaya/blueprint",
  "compilation_id": "pack_1d14a8a7befe4441865eabd5761e8814",
  "created_at": "2026-05-15T06:36:26.908220+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 blueprint-mcp-server` 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 blueprint-mcp-server",
      "sandbox_container_image": "node:22-slim",
      "sandbox_execution_backend": "docker",
      "sandbox_planner_decision": "deterministic_isolated_install",
      "sandbox_validation_id": "sbx_2094a717bc024f129c8c73748dfd8205"
    },
    "feedback_event_type": "project_pack_compilation_feedback",
    "learning_candidate_reasons": [],
    "template_gaps": []
  },
  "identity": {
    "canonical_id": "project_bf3898a54057c34e20ae6cfd178fe6ea",
    "canonical_name": "engincankaya/blueprint",
    "homepage_url": null,
    "license": "unknown",
    "repo_url": "https://github.com/engincankaya/blueprint",
    "slug": "blueprint",
    "source_packet_id": "phit_d73202cfc25047898b838b67a189843c",
    "source_validation_id": "dval_b24e4e869d9c46e0b432673d5547fcbd"
  },
  "merchandising": {
    "best_for": "需要软件开发与交付能力，并使用 mcp_host的用户",
    "github_forks": 0,
    "github_stars": 0,
    "one_liner_en": "Architecture-aware MCP server that analyzes codebases with Tree-sitter and generates Blueprint memory for  LLM coding agents.",
    "one_liner_zh": "Architecture-aware MCP server that analyzes codebases with Tree-sitter and generates Blueprint memory for  LLM coding agents.",
    "primary_category": {
      "category_id": "software-development",
      "confidence": "high",
      "name_en": "Software Development",
      "name_zh": "软件开发与交付",
      "reason": "matched_keywords:code, coding, git"
    },
    "target_user": "使用 mcp_host 等宿主 AI 的用户",
    "title_en": "blueprint",
    "title_zh": "blueprint 能力包",
    "visible_tags": [
      {
        "label_en": "MCP Tools",
        "label_zh": "MCP 工具",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "product_domain-mcp-tools",
        "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_d73202cfc25047898b838b67a189843c",
  "page_model": {
    "artifacts": {
      "artifact_slug": "blueprint",
      "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 blueprint-mcp-server",
          "label": "Node.js / npm · 官方安装入口",
          "source": "https://github.com/engincankaya/blueprint#readme",
          "verified": true
        }
      ],
      "display_tags": [
        "MCP 工具",
        "知识库问答",
        "流程自动化",
        "节点式流程编排",
        "本地优先"
      ],
      "eyebrow": "软件开发与交付",
      "glance": [
        {
          "body": "判断自己是不是目标用户。",
          "label": "最适合谁",
          "value": "需要软件开发与交付能力，并使用 mcp_host的用户"
        },
        {
          "body": "先理解能力边界，再决定是否继续。",
          "label": "核心价值",
          "value": "Architecture-aware MCP server that analyzes codebases with Tree-sitter and generates Blueprint memory for  LLM coding 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:1230090802 | https://github.com/engincankaya/blueprint | 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:1230090802 | https://github.com/engincankaya/blueprint | 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:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "进入安全/权限治理复核队列。",
            "title": "下游验证发现风险项",
            "user_impact": "下游已经要求复核，不能在页面中弱化。"
          },
          {
            "body": "no_demo",
            "category": "安全/权限坑",
            "evidence": [
              "risks.scoring_risks | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
            "title": "存在评分风险",
            "user_impact": "风险会影响是否适合普通用户安装。"
          },
          {
            "body": "issue_or_pr_quality=unknown。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | 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:1230090802 | https://github.com/engincankaya/blueprint | release_recency=unknown"
            ],
            "severity": "low",
            "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
            "title": "发布节奏不明确",
            "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
          }
        ],
        "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
        "summary": "发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。",
        "title": "踩坑日志"
      },
      "snapshot": {
        "contributors": 1,
        "forks": 0,
        "license": "unknown",
        "note": "站点快照，非实时质量证明；用于开工前背景判断。",
        "stars": 0
      },
      "source_url": "https://github.com/engincankaya/blueprint",
      "steps": [
        {
          "body": "不安装项目，先体验能力节奏。",
          "code": "preview",
          "title": "先试 Prompt"
        },
        {
          "body": "理解输入、输出、失败模式和边界。",
          "code": "manual",
          "title": "读说明书"
        },
        {
          "body": "把上下文交给宿主 AI 继续工作。",
          "code": "context",
          "title": "带给 AI"
        },
        {
          "body": "进入主力环境前先完成安装入口与风险边界验证。",
          "code": "verify",
          "title": "沙箱验证"
        }
      ],
      "subtitle": "Architecture-aware MCP server that analyzes codebases with Tree-sitter and generates Blueprint memory for  LLM coding agents.",
      "title": "blueprint 能力包",
      "trial_prompt": "# blueprint - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 blueprint 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Architecture-aware MCP server that analyzes codebases with Tree-sitter and generates Blueprint memory for  LLM coding agents. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-tool-system：工具系统概览。围绕“工具系统概览”模拟一次用户任务，不展示安装或运行结果。\n4. page-scan-pipeline：Scan管道 - 文件清单与分析。围绕“Scan管道 - 文件清单与分析”模拟一次用户任务，不展示安装或运行结果。\n5. page-group-pipeline：Group管道 - 语义分组。围绕“Group管道 - 语义分组”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-tool-system\n输入：用户提供的“工具系统概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-scan-pipeline\n输入：用户提供的“Scan管道 - 文件清单与分析”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-group-pipeline\n输入：用户提供的“Group管道 - 语义分组”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-tool-system：Step 3 必须围绕“工具系统概览”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-scan-pipeline：Step 4 必须围绕“Scan管道 - 文件清单与分析”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-group-pipeline：Step 5 必须围绕“Group管道 - 语义分组”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/engincankaya/blueprint\n- https://github.com/engincankaya/blueprint#readme\n- README.md\n- AGENTS.md\n- src/index.ts\n- src/tools/init-tools.ts\n- src/types.ts\n- src/lib/artifact-store.ts\n- src/tools/scan/index.ts\n- src/tools/scan/scan-file-inventory-builder.ts\n- src/tools/scan/scan-code-analysis-engine.ts\n- src/tools/group/index.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 blueprint 的核心服务。\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": "当前没有项目级社区来源；不会把未抓取讨论包装成社会证明。",
          "items": [],
          "status": "待发现 Agent 补证",
          "title": "社区讨论"
        }
      ]
    },
    "homepage_card": {
      "category": "软件开发与交付",
      "desc": "Architecture-aware MCP server that analyzes codebases with Tree-sitter and generates Blueprint memory for  LLM coding agents.",
      "effort": "安装已验证",
      "forks": 0,
      "icon": "code",
      "name": "blueprint 能力包",
      "risk": "需复核",
      "slug": "blueprint",
      "stars": 0,
      "tags": [
        "MCP 工具",
        "知识库问答",
        "流程自动化",
        "节点式流程编排",
        "本地优先"
      ],
      "thumb": "gray",
      "type": "MCP 配置"
    },
    "manual": {
      "markdown": "# https://github.com/engincankaya/blueprint 项目说明书\n\n生成时间：2026-05-14 18:16:08 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [系统架构](#page-architecture)\n- [工具系统概览](#page-tool-system)\n- [Scan管道 - 文件清单与分析](#page-scan-pipeline)\n- [Group管道 - 语义分组](#page-group-pipeline)\n- [Compose管道 - 最终输出生成](#page-compose-pipeline)\n- [Refresh系统 - 状态刷新与维护](#page-refresh-system)\n- [Task Context - 任务上下文构建](#page-task-context)\n- [语言支持与Tree-sitter集成](#page-language-support)\n- [数据存储与路径管理](#page-data-storage)\n\n<a id='page-overview'></a>\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [工具系统概览](#page-tool-system)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)\n- [AGENTS.md](https://github.com/engincankaya/blueprint/blob/main/AGENTS.md)\n- [frontend/src/components/BlueprintApp.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/BlueprintApp.tsx)\n- [frontend/src/components/blueprint/GroupDetailPanel.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/blueprint/GroupDetailPanel.tsx)\n- [frontend/index.html](https://github.com/engincankaya/blueprint/blob/main/frontend/index.html)\n- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n- [src/viewer/render-html.ts](https://github.com/engincankaya/blueprint/blob/main/src/viewer/render-html.ts)\n- [src/tools/group/grouping-assignment-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping-assignment-engine.ts)\n- [todos_120526.md](https://github.com/engincankaya/blueprint/blob/main/todos_120526.md)\n</details>\n\n# 项目概述\n\n## 项目简介\n\nBlueprint 是一个面向开发者的项目结构分析和可视化工具，旨在帮助开发者快速理解代码库架构、文件关系和项目组织结构。该工具通过自动扫描源代码、构建文件清单、生成语义化分组和渲染可视化界面，为代码审查、架构重构和团队知识传递提供支持。\n\nBlueprint 的核心设计理念是 **\"Blueprint 是辅助层，源码是真相\"**。文档和蓝图文件仅用于方向指引，如果文档与源码存在冲突，应以源码为准。资料来源：[AGENTS.md]()\n\n## 核心功能\n\nBlueprint 提供以下核心功能：\n\n| 功能 | 说明 |\n|------|------|\n| 文件扫描 | 构建项目的完整文件清单，包含文件类型、语言、路径等元数据 |\n| 代码分析 | 基于 Tree-sitter 的深度符号分析，支持 TypeScript、Python、Go、Rust、Java |\n| 语义分组 | 根据文件角色和重要性自动将文件组织成逻辑分组 |\n| 可视化查看器 | 轻量级 React/Vite 静态 HTML 查看器，支持浏览器直接打开 |\n| Markdown 文档 | 生成架构组文档模板，包含核心流程、契约、不变量等 |\n\n资料来源：[README.md]()\n\n## 架构设计\n\n### 整体架构\n\nBlueprint 采用模块化设计，主要由扫描工具、分析引擎、分组引擎和可视化渲染器四大组件构成。\n\n```mermaid\ngraph TD\n    A[文件系统] --> B[文件扫描器<br/>scan-file-inventory-builder]\n    B --> C[文件清单<br/>FileInventory]\n    C --> D[代码分析引擎<br/>scan-code-analysis-engine]\n    D --> E[分析结果<br/>AnalysisFacts]\n    E --> F[分组引擎<br/>grouping-assignment-engine]\n    F --> G[蓝图输出<br/>blueprint-output.json]\n    G --> H[静态 HTML 渲染器<br/>render-html]\n    H --> I[viewer/index.html]\n    G --> J[.blueprint/groups/*.md]\n    J --> K[架构组文档]\n```\n\n### 工具集\n\nBlueprint 通过 MCP（Model Context Protocol）提供以下命令行工具：\n\n| 工具 | 用途 |\n|------|------|\n| `blueprint.scan` | 构建文件清单和代码分析产物 |\n| `blueprint.group` | 准备或应用语义化文件分组 |\n| `blueprint.compose` | 写入最终蓝图输出和 Markdown 笔记 |\n| `blueprint.refresh` | 从当前文件系统快照刷新蓝图状态 |\n| `blueprint.group.update` | 分配未分配的文件或管理空分组 |\n| `blueprint open` | 打开可视化查看器 |\n\n资料来源：[README.md]()\n\n## 数据模型\n\n### 文件清单结构\n\n文件扫描器生成的 `FileInventory` 包含以下核心字段：\n\n```typescript\ninterface FileInventory {\n  files: FileRecord[];        // 文件记录数组\n  summary: {\n    totalFiles: number;       // 总文件数\n    parseableFiles: number;   // 可解析文件数\n    metadataOnlyFiles: number; // 仅元数据文件数\n  };\n  rootPath: string;           // 项目根路径\n}\n```\n\n每个文件记录 `FileRecord` 包含路径、语言、分类、分析级别等属性。资料来源：[src/tools/scan/scan-file-inventory-builder.ts]()\n\n### 文件分类\n\nBlueprint 支持以下文件分类类型：\n\n| 分类 | 判断条件 |\n|------|----------|\n| `source` | 源代码文件（.ts, .tsx, .py, .go, .rs, .java 等） |\n| `test` | 测试文件（.spec.ts, .test.js, test/ 目录等） |\n| `config` | 配置文件（package.json, tsconfig.json, .config.js 等） |\n| `documentation` | 文档文件（.md, docs/ 目录） |\n| `script` | 脚本文件（.sh, scripts/ 目录） |\n| `asset` | 资源文件（.css, .svg, assets/, public/ 目录） |\n| `lockfile` | 锁文件（package-lock.json, yarn.lock 等） |\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts]()\n\n### 分析结果结构\n\n代码分析引擎输出的 `AnalysisFacts` 包含：\n\n```typescript\ninterface AnalysisFacts {\n  inventoryArtifactId: string;\n  rootPath: string;\n  files: {};                  // 按 fileId 索引的解析结果\n  symbols: {};                // 符号表\n  imports: Import[];          // 导入关系\n  exports: Export[];          // 导出关系\n  dependencies: Dependency[]; // 依赖关系\n  summary: {\n    totalFiles: number;\n    parseableFiles: number;\n    symbols: number;\n    imports: number;\n    exports: number;\n    dependencies: number;\n    parseErrors: number;\n  };\n  validation: AnalysisValidation; // 分析验证状态\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts]()\n\n## 工作流程\n\n### 初始工作流\n\n首次使用 Blueprint 时，按以下顺序执行工具：\n\n```mermaid\ngraph LR\n    A[1. blueprint.scan] --> B[2. blueprint.group<br/>mode: prepare]\n    B --> C[3. 创建分组计划]\n    C --> D[4. blueprint.group<br/>mode: apply]\n    D --> E[5. blueprint.compose]\n    E --> F[生成 .blueprint/ 内存文件]\n```\n\n步骤说明：\n\n1. **scan** - 构建文件清单和代码分析产物\n2. **group prepare** - 准备阶段，分析文件关系生成候选分组\n3. **分组计划** - 开发者审查并创建紧凑的分组计划\n4. **group apply** - 应用阶段，执行实际分组\n5. **compose** - 写入最终输出并生成 Markdown 笔记\n\n资料来源：[README.md]()\n\n### 维护工作流\n\n当项目发生文件变更时：\n\n1. 运行 `blueprint.refresh` 刷新蓝图状态\n2. 如有新文件未分配，运行 `blueprint.group.update`\n3. 仅在架构、契约、陷阱或测试指导发生变化时更新受影响的组文档\n\n资料来源：[AGENTS.md]()\n\n## 可视化查看器\n\n### 查看器特性\n\nBlueprint 提供轻量级 React/Vite 查看器，支持以下功能：\n\n- **画布视图** - 展示架构组和连接的交互式画布\n- **详情面板** - 显示组的元数据、快照、责任、核心流程等信息\n- **文件视图** - 按分组展示文件树和角色分解\n- **连接图** - 可视化展示组间关系\n- **架构视图** - 展示核心流程、契约和不变量\n- **指南视图** - 展示变更指南、陷阱、测试和调试信息\n\n资料来源：[frontend/src/components/BlueprintApp.tsx](), [frontend/src/components/blueprint/GroupDetailPanel.tsx]()\n\n### 静态 HTML 渲染\n\nBlueprint 支持生成独立的静态 HTML 查看器，无需本地 HTTP 服务器：\n\n```bash\nblueprint open\n```\n\n该命令读取 `.blueprint/blueprint-output.json` 和 `.blueprint/groups/*.md`，生成自包含的 `.blueprint/index.html` 文件，然后在默认浏览器中打开。\n\n| 模式 | 说明 |\n|------|------|\n| `blueprint open` | 生成静态 HTML 并打开 |\n| `blueprint open --watch` | 监视文件变化持续重新生成 |\n\n渲染器通过以下方式生成自包含 HTML：\n\n- 内联所有 CSS 样式\n- 内联所有 JavaScript 模块\n- 使用 `<script id=\"blueprint-data\" type=\"application/json\">` 安全嵌入 JSON 数据\n- JSON 在嵌入前经过 XSS 和 `</script>` 关闭标签风险的安全转义\n\n资料来源：[src/viewer/render-html.ts](), [README.md]()\n\n### 查看器 UI 结构\n\n```mermaid\ngraph TD\n    A[BlueprintApp] --> B[侧边栏<br/>GroupSidebar]\n    A --> C[主内容区<br/>TabContent]\n    C --> D[画布视图<br/>BlueprintCanvas]\n    C --> E[详情面板<br/>GroupDetailPanel]\n    E --> E1[概述子视图]\n    E --> E2[文件子视图]\n    E --> E3[连接子视图]\n    E --> E4[架构子视图]\n    E --> E5[指南子视图]\n```\n\n资料来源：[frontend/src/components/BlueprintApp.tsx]()\n\n## 分组文档模板\n\nBlueprint 为每个架构组生成 Markdown 文档，采用稳定模板结构：\n\n| 章节 | 用途 |\n|------|------|\n| `Snapshot` | 快速概览和定位 |\n| `Responsibilities` | 定义所有权和范围外区域 |\n| `Core Flow` | 解释运行时行为和数据流 |\n| `Contracts & Invariants` | 列出不可破坏的行为 |\n| `Key Files` | 指向组的主要源文件 |\n| `Change Guide` | 列出应一起变更的文件或契约 |\n| `Pitfalls` | 记录已知风险和常见错误 |\n| `Tests` | 标识最相关的验证方式 |\n| `Debugging` | 提供故障排查提示 |\n| `Extension / Open Questions` | 记录不确定性和已知缺口 |\n\n资料来源：[AGENTS.md]()\n\n## 语言支持\n\nBlueprint 使用 Tree-sitter 进行分析，支持以下语言：\n\n| 语言 | 支持级别 |\n|------|----------|\n| TypeScript / JavaScript | 完整支持（符号、导入、导出分析） |\n| Python | 完整支持 |\n| Go | 完整支持 |\n| Rust | 完整支持 |\n| Java | 完整支持 |\n| 其他语言 | 仅元数据（文件仍包含在清单中） |\n\n资料来源：[README.md]()\n\n## 蓝图内存管理\n\n### 目录结构\n\nBlueprint 在项目根目录的 `.blueprint/` 文件夹中存储内存文件：\n\n| 文件/目录 | 说明 |\n|----------|------|\n| `.blueprint/brief.md` | 项目架构概览文档 |\n| `.blueprint/groups/*.md` | 各架构组的详细文档 |\n| `blueprint-output.json` | 结构化项目图谱 |\n| `refresh-scan.json` | 文件系统哈希快照，用于确定性刷新 |\n\n### 内存性质\n\n- `.blueprint/` 是本地生成的内存，**默认不提交到版本控制**\n- 团队可自行决定是否将其提交或添加到 `.gitignore`\n- 蓝图文件是方向性辅助层，源码始终是真相\n- 如果变更后源码行为改变，应更新相关蓝图组文档\n\n资料来源：[README.md](), [todos_120526.md]()\n\n## 开发指南\n\n### 本地开发\n\n```bash\nnpm install    # 安装依赖\nnpm run build # 构建项目\nnpm run lint  # 代码检查\nnpm test      # 运行测试\n```\n\n### 查看器入口\n\n前端查看器的 HTML 入口点位于 `frontend/index.html`，使用 Vite 作为开发服务器：\n\n```html\n<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"UTF-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n    <title>Blueprint</title>\n  </head>\n  <body>\n    <div id=\"root\"></div>\n    <script type=\"module\" src=\"/src/main.tsx\"></script>\n  </body>\n</html>\n```\n\n资料来源：[frontend/index.html]()\n\n## 关键设计决策\n\nBlueprint 的以下设计决策已确定：\n\n| 决策项 | 说明 |\n|--------|------|\n| 无强制 HTTP 服务器 | HTTP 服务器不作为产品主流程 |\n| 用户目录隔离 | Blueprint 内存不写入用户 package 或 `node_modules` |\n| 默认内存路径 | 用户项目中的 `.blueprint/` 目录 |\n| 静态查看器 | 在用户项目中生成 `.blueprint/index.html` |\n| 查看器自包含 | 内联 JS、内联 CSS、安全嵌入 JSON 数据 |\n| Agent 文档 | `AGENTS.md` 通过标记分隔符补丁更新，不覆盖现有内容 |\n| HTTP 服务器保留 | 暂不删除，先完成服务重构和静态渲染器验证 |\n\n资料来源：[todos_120526.md]()\n\n## 技术栈\n\n| 层级 | 技术 |\n|------|------|\n| 核心引擎 | TypeScript / Node.js |\n| 代码分析 | Tree-sitter |\n| 前端框架 | React / Vite |\n| 样式 | Tailwind CSS / CSS |\n| 协议 | MCP (Model Context Protocol) |\n\n---\n\n<a id='page-architecture'></a>\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [工具系统概览](#page-tool-system), [Scan管道 - 文件清单与分析](#page-scan-pipeline)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/index.ts)\n- [src/tools/init-tools.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/init-tools.ts)\n- [src/types.ts](https://github.com/engincankaya/blueprint/blob/main/src/types.ts)\n- [src/lib/artifact-store.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/artifact-store.ts)\n- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n- [src/tools/group/grouping-assignment-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping-assignment-engine.ts)\n- [src/viewer/render-html.ts](https://github.com/engincankaya/blueprint/blob/main/src/viewer/render-html.ts)\n- [frontend/src/components/BlueprintApp.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/BlueprintApp.tsx)\n- [frontend/src/components/blueprint/GroupDetailPanel.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/blueprint/GroupDetailPanel.tsx)\n</details>\n\n# 系统架构\n\nBlueprint 是一个项目架构记忆生成工具，通过扫描源代码、构建文件清单、执行代码分析、语义分组等步骤，生成结构化的项目架构文档和交互式可视化界面。本章节详细介绍 Blueprint 的整体系统架构、各核心模块的职责以及数据流转过程。\n\n## 架构概览\n\nBlueprint 采用前后端分离的架构设计，整体系统由以下几大核心组件构成：\n\n| 组件 | 技术栈 | 职责 |\n|------|--------|------|\n| MCP 服务层 | TypeScript | 提供 `blueprint.scan`、`blueprint.group`、`blueprint.compose`、`blueprint.refresh` 等工具接口 |\n| 代码扫描引擎 | TypeScript | 遍历文件系统、识别文件类型、构建文件清单 |\n| 代码分析引擎 | TypeScript | 解析源代码、提取符号、追踪导入导出关系 |\n| 分组分配引擎 | TypeScript | 基于语义规则将文件分配到架构组 |\n| 工件存储层 | TypeScript | 管理扫描、分析、分组等中间产物的持久化 |\n| 前端可视化 | React + TypeScript | 渲染交互式架构画布和分组详情面板 |\n\n```mermaid\ngraph TD\n    A[用户调用 MCP 工具] --> B[MCP 服务层<br/>src/index.ts]\n    B --> C[扫描工具<br/>scan-file-inventory-builder.ts]\n    B --> D[分析工具<br/>scan-code-analysis-engine.ts]\n    B --> E[分组工具<br/>grouping-assignment-engine.ts]\n    C --> F[工件存储<br/>artifact-store.ts]\n    D --> F\n    E --> F\n    F --> G[合成工具<br/>compose]\n    G --> H[.blueprint/ 输出目录]\n    H --> I[前端可视化<br/>BlueprintApp.tsx]\n    I --> J[GroupDetailPanel.tsx]\n```\n\n资料来源：[src/index.ts](src/index.ts) | [src/tools/init-tools.ts](src/tools/init-tools.ts)\n\n## 核心模块详解\n\n### 1. MCP 服务层\n\nMCP 服务层是整个系统的入口点，负责注册和暴露所有 Blueprint 工具。工具初始化在 `src/tools/init-tools.ts` 中完成，主要包含以下工具：\n\n- `blueprint.scan`：构建文件清单和代码分析产物\n- `blueprint.group`：准备或应用语义分组\n- `blueprint.compose`：将最终输出写入 `.blueprint/` 目录并更新 `AGENTS.md`\n- `blueprint.refresh`：从当前源代码刷新 Blueprint 状态\n\n```mermaid\ngraph LR\n    A[blueprint.scan] --> B[blueprint.group]\n    B --> C[blueprint.compose]\n    A --> D[blueprint.refresh]\n    C --> E[.blueprint/ memory]\n```\n\n资料来源：[src/index.ts](src/index.ts) | [src/tools/init-tools.ts](src/tools/init-tools.ts) | [README.md](README.md)\n\n### 2. 文件扫描与清单构建\n\n`scan-file-inventory-builder.ts` 模块负责遍历项目文件系统，识别并分类每个文件。该模块的核心职责包括：\n\n**文件分类规则**\n\n| 分类 | 判定条件 |\n|------|----------|\n| test | 文件名包含 `.test.`、`.spec.`、路径包含 `test`、`tests`、`__tests__` |\n| lockfile | `package-lock.json`、`yarn.lock`、`pnpm-lock.yaml`、`cargo.lock`、`poetry.lock` |\n| config | `.gitignore`、`package.json`、`tsconfig.json`、以 `.config.` 结尾的文件 |\n| documentation | 路径包含 `docs`、`readme.md`、以 `.md` 结尾的文件 |\n| script | 路径包含 `scripts`、以 `.sh` 结尾的文件 |\n| asset | 路径包含 `assets`、`public`、语言为 `html`、`css`、`scss`、`svg` |\n| generated | 路径包含 `generated`、`__generated__` |\n\n该模块输出 `FileInventory` 数据结构，包含所有文件的元数据（路径、语言、分类、分析级别等）。\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts](src/tools/scan/scan-file-inventory-builder.ts)\n\n### 3. 代码分析引擎\n\n`scan-code-analysis-engine.ts` 模块对可解析的文件进行深度分析，提取代码结构信息：\n\n**分析产物结构 (AnalysisFacts)**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| files | Record | 以 fileId 为键的文件分析结果 |\n| symbols | Record | 代码符号（函数、类、变量等） |\n| imports | Array | 导入关系列表 |\n| exports | Array | 导出关系列表 |\n| dependencies | Array | 依赖关系列表 |\n| unresolvedImports | Array | 无法解析的导入 |\n| parseErrors | Array | 解析错误记录 |\n| summary | Object | 统计摘要（总文件数、可解析文件数等） |\n| validation | Object | 分析覆盖率验证 |\n\n**验证机制**\n\n分析引擎会校验覆盖率，确保所有清单中的文件都被正确处理或记录跳过原因。未被解析的文件会记录在 `validation.unaccountedFiles` 中。\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts](src/tools/scan/scan-code-analysis-engine.ts)\n\n### 4. 分组分配引擎\n\n`grouping-assignment-engine.ts` 模块负责将文件清单中的文件分配到语义架构组。该引擎：\n\n- 支持通配符和占位符匹配（`*` 匹配任意字符、`?` 匹配单个字符）\n- 为每个文件分配角色和重要性等级\n- 提供未知模式识别和建议路径功能\n\n```mermaid\ngraph TD\n    A[FileInventory] --> B[分组规则引擎]\n    B --> C{模式匹配}\n    C -->|命中| D[分配到目标组]\n    C -->|未命中| E[UnknownPattern]\n    E --> F[suggestPaths]\n    D --> G[GroupedFile]\n```\n\n**分组文件数据结构 (GroupedFile)**\n\n| 字段 | 说明 |\n|------|------|\n| fileId | 文件唯一标识 |\n| path | 文件相对路径 |\n| category | 文件分类 |\n| language | 编程语言 |\n| importance | 重要性等级 |\n| role | 角色类型 |\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts](src/tools/group/grouping-assignment-engine.ts)\n\n### 5. 工件存储层\n\n`artifact-store.ts` 模块负责 Blueprint 所有中间产物和最终产物的持久化管理。工件存储采用键值对形式，支持：\n\n- 类型化的存储和检索（通过 `getTyped<T>` 方法）\n- 跨工具共享分析结果\n- 扫描结果的确定性哈希快照（`refresh-scan.json`）\n\n资料来源：[src/lib/artifact-store.ts](src/lib/artifact-store.ts)\n\n### 6. 前端可视化\n\n前端基于 React 构建，主要包含两个核心组件：\n\n#### BlueprintApp (主应用容器)\n\n负责整体布局和标签页管理，支持：\n\n- Canvas 画布视图（显示架构概览）\n- 分组详情面板（多标签页切换）\n- 活跃分组高亮和导航\n\n```mermaid\ngraph TD\n    A[BlueprintApp] --> B[标签栏<br/>BlueprintTabBar]\n    A --> C[主工作区]\n    C --> D{activeTab.type}\n    D -->|canvas| E[BlueprintCanvas]\n    D -->|group| F[GroupDetailPanel]\n    E --> G[项目架构图]\n    F --> H[子标签页]\n    H --> I[Overview|Files|Connections|Architecture|Guide]\n```\n\n资料来源：[frontend/src/components/BlueprintApp.tsx](frontend/src/components/BlueprintApp.tsx)\n\n#### GroupDetailPanel (分组详情面板)\n\n显示单个架构分组的详细信息，包含以下子标签页：\n\n| 子标签页 | 内容说明 |\n|----------|----------|\n| Overview | 快照摘要、责任描述、关键文件、开放问题 |\n| Files | 文件角色分布、文件树结构 |\n| Connections | 架构组之间的连接关系图 |\n| Architecture | 核心流程、合约与不变量、关键文件 |\n| Guide | 变更指南、陷阱提示、测试信息、调试建议 |\n\n**SectionCard 组件**\n\n可折叠的内容区块，支持：\n\n- 默认展开/收起状态\n- 内容预览（line-clamp-1）\n- 动画过渡效果\n- 强调色标记（`accent` 属性）\n\n**OpenQuestionsCards 组件**\n\n专门用于展示开放问题和扩展考虑的卡片组件。\n\n资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx](frontend/src/components/blueprint/GroupDetailPanel.tsx)\n\n### 7. HTML 渲染器\n\n`render-html.ts` 模块负责将 Blueprint 数据渲染为独立的静态 HTML 文件，支持：\n\n- 内联 CSS 样式\n- 内联 JavaScript 模块\n- 安全的 JSON 数据嵌入（使用 `<script type=\"application/json\">` 避免 XSS）\n- 相对路径资源处理\n\n该模块是实现静态 viewer 的核心，确保输出文件完全自包含。\n\n资料来源：[src/viewer/render-html.ts](src/viewer/render-html.ts)\n\n## 数据流与处理流水线\n\nBlueprint 的完整处理流程如下：\n\n```mermaid\ngraph LR\n    A[源代码目录] -->|blueprint.scan| B[FileInventory]\n    B -->|blueprint.group<br/>mode: prepare| C[PrepareResult]\n    C -->|人工审核| D[GroupingPlan]\n    D -->|blueprint.group<br/>mode: apply| E[GroupAssignments]\n    B -->|blueprint.scan| F[AnalysisFacts]\n    E -->|blueprint.compose| G[.blueprint/]\n    F -->|blueprint.compose| G\n    G -->|blueprint render| H[index.html]\n    G -->|blueprint open| I[Viewer UI]\n```\n\n### 初始工作流\n\n1. 执行 `blueprint.scan` 构建文件清单和代码分析产物\n2. 执行 `blueprint.group` 并设置 `mode: \"prepare\"` 获取预分组建议\n3. 根据 prepare 输出创建紧凑的分组计划\n4. 执行 `blueprint.group` 并设置 `mode: \"apply\"` 应用分组\n5. 执行 `blueprint.compose` 写入最终输出并更新 `AGENTS.md`\n\n### 维护工作流\n\n当项目文件发生变化时：\n\n1. 执行 `blueprint.refresh` 刷新 Blueprint 状态\n2. 如有新文件未分配，执行 `blueprint.group.update`\n3. 仅在架构、合约、陷阱或测试指导发生变化时更新受影响的 `.blueprint/groups/*.md` 文件\n\n资料来源：[README.md](README.md) | [todos_120526.md](todos_120526.md)\n\n## 类型定义体系\n\nBlueprint 使用统一的 TypeScript 类型定义确保各模块间的数据一致性。核心类型定义位于 `src/types.ts`，包括：\n\n- `FileInventory`：文件系统清单\n- `AnalysisFacts`：代码分析结果\n- `GroupAssignments`：分组分配结果\n- `ArtifactStore`：工件存储接口\n\n资料来源：[src/types.ts](src/types.ts)\n\n## 总结\n\nBlueprint 系统采用模块化设计，通过清晰的职责划分实现了从源代码扫描到可视化输出的完整流水线。MCP 服务层提供统一入口，扫描引擎和分析引擎负责数据采集，分组引擎实现语义组织，工件存储层确保数据共享，前端组件负责最终呈现。这种架构使得各组件可以独立演进，同时保持整体系统的一致性和可扩展性。\n\n---\n\n<a id='page-tool-system'></a>\n\n## 工具系统概览\n\n### 相关页面\n\n相关主题：[Scan管道 - 文件清单与分析](#page-scan-pipeline), [Group管道 - 语义分组](#page-group-pipeline), [Compose管道 - 最终输出生成](#page-compose-pipeline), [Refresh系统 - 状态刷新与维护](#page-refresh-system)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n- [src/viewer/render-html.ts](https://github.com/engincankaya/blueprint/blob/main/src/viewer/render-html.ts)\n- [README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)\n- [AGENTS.md](https://github.com/engincankaya/blueprint/blob/main/AGENTS.md)\n</details>\n\n# 工具系统概览\n\n## 系统简介\n\nBlueprint 的工具系统是项目的核心模块，负责代码库的扫描、分析、分组和可视化展示。该系统通过 MCP（Model Context Protocol）协议暴露工具接口，使 AI Agent 能够与代码库进行交互，生成结构化的项目记忆（Blueprint Memory）。\n\nBlueprint 工具系统的设计目标是：\n\n- **扫描（Scan）**：构建文件清单并进行代码分析\n- **分组（Group）**：基于语义将文件组织成逻辑组\n- **组合（Compose）**：生成 Blueprint 记忆文件和 Markdown 文档\n- **刷新（Refresh）**：增量更新项目状态\n\n资料来源：[README.md]()\n\n## 核心工具\n\n### 工具列表\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `blueprint.scan` | 构建文件清单和代码分析产物 |\n| `blueprint.group` | 准备或应用语义文件分组 |\n| `blueprint.compose` | 写入最终 Blueprint 输出和 Markdown 笔记 |\n| `blueprint.refresh` | 从当前文件系统快照刷新 Blueprint 状态 |\n| `blueprint.group.update` | 分配未分配文件或管理空组 |\n| `blueprint.open` | 生成静态 HTML 并在浏览器中打开 |\n\n资料来源：[README.md]()\n\n## 扫描工具（Scan）\n\n扫描工具负责对项目进行全面分析，生成文件清单和代码分析产物。\n\n### 文件清单构建器\n\n`scan-file-inventory-builder.ts` 实现了文件分类逻辑，根据文件路径、名称和语言类型将文件划分为不同类别：\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts:1-75]()\n\n#### 文件类型分类规则\n\n| 类型 | 判定条件 |\n|------|---------|\n| `test` | 文件名以 `.spec.`、`.test.` 结尾；路径包含 `test`、`tests`、`__tests__` |\n| `lockfile` | `package-lock.json`、`yarn.lock`、`pnpm-lock.yaml`、`cargo.lock`、`poetry.lock` |\n| `config` | `.gitignore`、`package.json`、`tsconfig.json`；以 `.config.js/ts/mjs/cjs` 结尾 |\n| `documentation` | 路径包含 `docs`；文件名以 `.md` 结尾；语言为 markdown |\n| `script` | 路径包含 `scripts`；语言为 shell；`.sh` 文件 |\n| `asset` | 路径包含 `assets`、`public`；语言为 html、css、scss、svg |\n| `generated` | 路径包含 `generated`、`__generated__` |\n\n```typescript\n// 测试文件判定逻辑\nif (\n  base.endsWith(\".test.ts\") ||\n  base.endsWith(\".test.tsx\") ||\n  base.endsWith(\".test.js\") ||\n  base.endsWith(\".test.jsx\") ||\n  base.endsWith(\".spec.ts\") ||\n  base.endsWith(\".spec.tsx\") ||\n  base.endsWith(\".spec.js\") ||\n  base.endsWith(\".spec.jsx\") ||\n  segments.includes(\"test\") ||\n  segments.includes(\"tests\") ||\n  segments.includes(\"__tests__\")\n) {\n  return \"test\";\n}\n```\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts:1-30]()\n\n### 代码分析引擎\n\n`scan-code-analysis-engine.ts` 负责解析可读文件并提取代码事实：\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts:1-50]()\n\n#### 分析事实结构\n\n```typescript\ninterface AnalysisFacts {\n  inventoryArtifactId: string;\n  rootPath: string;\n  files: Record<string, unknown>;\n  symbols: Record<string, unknown>;\n  imports: string[];\n  exports: string[];\n  dependencies: string[];\n  unresolvedImports: string[];\n  parseErrors: string[];\n  summary: {\n    totalFiles: number;\n    parseableFiles: number;\n    metadataOnlyFiles: number;\n    plannedFiles: number;\n    parsedFiles: number;\n    symbols: number;\n    imports: number;\n    exports: number;\n    dependencies: number;\n    parseErrors: number;\n  };\n  validation: {\n    isComplete: boolean;\n    inventoryFiles: number;\n    parseableFiles: number;\n    parsedFiles: number;\n    metadataOnlyFiles: number;\n    skippedMetadataOnlyFiles: number;\n    parseErrors: number;\n    unaccountedFiles: string[];\n  };\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts:15-40]()\n\n#### 解析流程\n\n```mermaid\ngraph TD\n    A[获取 FileInventory] --> B{文件可解析?}\n    B -->|是| C[读取源文件]\n    C --> D[创建解析器]\n    D --> E[提取符号和导入]\n    B -->|否| F[标记为 metadataOnly]\n    E --> G[构建 AnalysisFacts]\n    F --> G\n```\n\n解析器通过 `createParser` 工厂函数根据文件语言类型动态创建，支持 TypeScript、Python、Go、Rust、Java 等语言。\n\n## 分组工具（Group）\n\n分组工具使用语义分析将相关文件组织成逻辑组，支持两种模式：\n\n| 模式 | 说明 |\n|------|-----|\n| `prepare` | 分析并生成紧凑的分组计划 |\n| `apply` | 执行分组计划 |\n\n### 分组计划生成\n\n分组工具分析扫描结果，基于以下维度进行分组：\n\n- 文件间的导入关系\n- 功能领域的语义相关性\n- 代码合约和不变量的共享性\n\n资料来源：[AGENTS.md]()\n\n## 渲染工具（Viewer）\n\n渲染工具负责将 Blueprint 数据转换为可查看的静态 HTML 文件。\n\n### HTML 渲染器\n\n`render-html.ts` 实现了静态 HTML 生成的核心逻辑：\n\n资料来源：[src/viewer/render-html.ts:1-40]()\n\n#### 脚本内联处理\n\n```typescript\nasync function inlineScripts(html: string, viewerRoot: string): Promise<string> {\n  return await replaceAsync(\n    html,\n    /<script\\s+type=\"module\"\\s+crossorigin\\s+src=\"([^\"]+)\"><\\/script>|<script\\s+type=\"module\"\\s+src=\"([^\"]+)\"><\\/script>/g,\n    async (_match, crossoriginSrc: string | undefined, src: string | undefined) => {\n      const assetPath = assetPathFromHref(crossoriginSrc ?? src ?? \"\");\n      const js = await readFile(join(viewerRoot, assetPath), \"utf-8\");\n      return `<script type=\"module\">${js}</script>`;\n    },\n  );\n}\n```\n\n资料来源：[src/viewer/render-html.ts:15-25]()\n\n#### 辅助函数\n\n| 函数名 | 功能 |\n|--------|------|\n| `assetPathFromHref` | 从 href 中提取资源路径 |\n| `replaceAsync` | 异步正则替换工具 |\n\n```typescript\nfunction assetPathFromHref(href: string): string {\n  return href.replace(/^\\//, \"\");\n}\n```\n\n资料来源：[src/viewer/render-html.ts:35-37]()\n\n### 静态查看器特性\n\n| 特性 | 说明 |\n|------|------|\n| 自包含 HTML | 内联 JS、内联 CSS、安全的嵌入式 JSON |\n| 数据嵌入方式 | `<script id=\"blueprint-data\" type=\"application/json\">` |\n| XSS 防护 | JSON 嵌入前进行安全转义 |\n| 监听模式 | `--watch` 参数可自动重新生成 |\n\n资料来源：[todos_120526.md]()\n\n## 工具系统架构\n\n```mermaid\ngraph TD\n    subgraph \"MCP 接口层\"\n        A[blueprint.scan]\n        B[blueprint.group]\n        C[blueprint.compose]\n        D[blueprint.refresh]\n        E[blueprint.open]\n    end\n\n    subgraph \"核心引擎\"\n        F[文件清单构建器]\n        G[代码分析引擎]\n        H[分组策略引擎]\n        I[HTML 渲染器]\n    end\n\n    subgraph \"数据存储\"\n        J[blueprint-output.json]\n        K[.blueprint/brief.md]\n        L[.blueprint/groups/*.md]\n        M[index.html]\n    end\n\n    A --> F\n    A --> G\n    B --> H\n    C --> J\n    C --> K\n    C --> L\n    D --> F\n    D --> H\n    E --> I\n    I --> M\n```\n\n## 工作流程\n\n### 初始工作流程\n\n```mermaid\ngraph LR\n    A[运行 blueprint.scan] --> B[运行 blueprint.group<br/>mode: prepare]\n    B --> C[创建分组计划]\n    C --> D[运行 blueprint.group<br/>mode: apply]\n    D --> E[运行 blueprint.compose]\n    E --> F[生成 .blueprint/ 记忆]\n    E --> G[更新 AGENTS.md]\n```\n\n资料来源：[README.md]()\n\n### 维护工作流程\n\n当项目发生变化时：\n\n1. 运行 `blueprint.refresh` 刷新状态\n2. 如有新文件未分配，运行 `blueprint.group.update`\n3. 仅更新受影响组的文档笔记\n\n资料来源：[README.md]()\n\n## 语言支持\n\nBlueprint 使用 Tree-sitter 进行代码分析：\n\n| 语言 | 符号分析 | 导入分析 |\n|------|---------|---------|\n| TypeScript / JavaScript | ✅ | ✅ |\n| Python | ✅ | ✅ |\n| Go | ✅ | ✅ |\n| Rust | ✅ | ✅ |\n| Java | ✅ | ✅ |\n| 其他语言 | 仅文件清单 | 仅文件清单 |\n\n资料来源：[README.md]()\n\n## 前端组件集成\n\n工具系统的数据通过以下 React 组件展示：\n\n| 组件 | 路径 | 功能 |\n|------|------|------|\n| `BlueprintApp` | `frontend/src/components/BlueprintApp.tsx` | 主应用容器，含 Tab 管理和路由 |\n| `GroupDetailPanel` | `frontend/src/components/blueprint/GroupDetailPanel.tsx` | 群组详情面板，含文件、连接、架构等标签页 |\n| `BlueprintCanvas` | 未提供 | 项目画布视图 |\n\n`GroupDetailPanel` 组件支持以下子标签页：\n\n- `overview`：快照、职责、关键文件、开放问题\n- `files`：文件树和角色分布\n- `connections`：连接图\n- `architecture`：核心流程、合约、不变量\n- `guide`：变更指南、陷阱、测试、调试\n\n资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx:1-100]()\n\n## 开发指南\n\n### 本地开发\n\n```bash\nnpm install\nnpm run build\nnpm run lint\nnpm test\n```\n\n### 工具扩展\n\n如需扩展工具系统，需关注以下文件：\n\n| 文件 | 职责 |\n|------|------|\n| `src/tools/scan/` | 扫描相关工具实现 |\n| `src/tools/group/` | 分组逻辑实现 |\n| `src/viewer/` | 渲染相关工具实现 |\n| `src/types.ts` | 类型定义 |\n| `src/index.ts` | 工具导出入口 |\n\n---\n\n<a id='page-scan-pipeline'></a>\n\n## Scan管道 - 文件清单与分析\n\n### 相关页面\n\n相关主题：[工具系统概览](#page-tool-system), [语言支持与Tree-sitter集成](#page-language-support), [数据存储与路径管理](#page-data-storage)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/scan/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/index.ts)\n- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n- [src/tools/compose/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)\n- [src/types.ts](https://github.com/engincankaya/blueprint/blob/main/src/types.ts)\n</details>\n\n# Scan管道 - 文件清单与分析\n\n## 概述\n\nScan管道是Blueprint项目的核心组件之一，负责对目标代码仓库进行全面的静态扫描，构建文件清单（File Inventory）并执行代码分析（Code Analysis），为后续的分组（Grouping）和组合（Compose）阶段提供基础数据。\n\nScan管道的主要职责包括：\n\n- 递归遍历项目目录，收集所有文件元数据\n- 根据文件扩展名和内容判断文件类型\n- 评估每个文件的分析级别（parseable、metadata-only等）\n- 对可解析文件执行深度代码分析，提取符号、导入、导出等信息\n- 生成分析验证摘要，确保扫描完整性\n\n```mermaid\ngraph TD\n    A[代码仓库] --> B[scan-file-inventory-builder]\n    B --> C[FileInventory]\n    C --> D[scan-code-analysis-engine]\n    D --> E[AnalysisFacts]\n    E --> F[grouping]\n    E --> G[compose]\n    F --> H[blueprint-output.json]\n```\n\n## 核心数据模型\n\n### FileInventory\n\nFileInventory是扫描阶段生成的文件清单对象，包含项目中所有文件的信息：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `rootPath` | `string` | 项目根目录路径 |\n| `files` | `FileEntry[]` | 所有文件的条目数组 |\n| `summary` | `InventorySummary` | 扫描摘要统计 |\n\n每个`FileEntry`包含：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `fileId` | `string` | 文件唯一标识符 |\n| `relativePath` | `string` | 相对于根目录的路径 |\n| `absolutePath` | `string` | 文件绝对路径 |\n| `language` | `string` | 编程语言标识 |\n| `analysisLevel` | `ParseableLevel` | 分析级别：parseable、metadata-only |\n| `size` | `number` | 文件大小（字节） |\n| `hash` | `string` | 文件内容哈希 |\n\n### AnalysisFacts\n\nAnalysisFacts是代码分析的完整结果对象：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `inventoryArtifactId` | `string` | 关联的文件清单artifact ID |\n| `rootPath` | `string` | 项目根目录 |\n| `files` | `Record<string, FileAnalysis>` | 每个文件的分析结果 |\n| `symbols` | `Record<string, Symbol>` | 全局符号表 |\n| `imports` | `ImportStatement[]` | 所有导入语句 |\n| `exports` | `ExportStatement[]` | 所有导出语句 |\n| `dependencies` | `Dependency[]` | 文件间依赖关系 |\n| `unresolvedImports` | `UnresolvedImport[]` | 无法解析的导入 |\n| `parseErrors` | `ParseError[]` | 解析错误列表 |\n| `summary` | `AnalysisSummary` | 分析统计摘要 |\n| `validation` | `ValidationResult` | 完整性验证结果 |\n\n## 文件清单构建器\n\n### 扫描流程\n\n`scan-file-inventory-builder.ts`负责构建FileInventory，其核心逻辑如下：\n\n1. **目录遍历**：递归扫描项目根目录下的所有文件\n2. **文件分类**：根据扩展名判断文件类型\n3. **分析级别判定**：\n   - `parseable`：Tree-sitter支持的语言文件（TypeScript、Python、Go、Rust、Java等）\n   - `metadata-only`：其他文件类型，仅记录元数据\n\n```mermaid\ngraph LR\n    A[递归遍历目录] --> B{文件类型判定}\n    B -->|Tree-sitter支持| C[parseable]\n    B -->|其他| D[metadata-only]\n    C --> E[计算哈希]\n    D --> E\n    E --> F[生成FileEntry]\n    F --> G[汇总为FileInventory]\n```\n\n### 支持的语言\n\nBlueprint使用Tree-sitter进行代码解析，支持以下语言：\n\n| 语言 | 扩展名 | 分析级别 |\n|------|--------|----------|\n| TypeScript | `.ts`、`.tsx` | parseable |\n| JavaScript | `.js`、`.jsx` | parseable |\n| Python | `.py` | parseable |\n| Go | `.go` | parseable |\n| Rust | `.rs` | parseable |\n| Java | `.java` | parseable |\n| 其他 | - | metadata-only |\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n\n## 代码分析引擎\n\n### 分析流程\n\n`scan-code-analysis-engine.ts`是代码分析的核心引擎，它接收FileInventory并生成AnalysisFacts：\n\n```mermaid\ngraph TD\n    A[获取FileInventory] --> B[过滤parseable文件]\n    B --> C[逐文件解析]\n    C --> D{解析成功?}\n    D -->|是| E[提取符号/导入/导出]\n    D -->|否| F[记录parseError]\n    E --> G{还有更多文件?}\n    F --> G\n    G -->|是| C\n    G -->|否| H[构建依赖关系图]\n    H --> I[生成validation报告]\n    I --> J[返回AnalysisFacts]\n```\n\n### 核心处理逻辑\n\n代码分析引擎对每个可解析文件执行以下操作：\n\n1. **读取源文件**：通过`readFile`读取文件内容\n2. **创建解析器**：调用`createParser`创建对应语言的Tree-sitter解析器\n3. **执行解析**：使用解析器分析源代码\n4. **提取代码事实**：\n   - 符号定义（函数、类、变量等）\n   - 导入语句和来源\n   - 导出声明和目标\n   - 依赖关系\n\n```typescript\nfor (const file of parseableFiles) {\n  try {\n    const source = await readFile(file.absolutePath, \"utf-8\");\n    const parser = await createParser(file.language);\n    // 解析并提取代码事实...\n  } catch (error) {\n    // 记录解析错误\n  }\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts:45-52](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n\n### 验证与完整性检查\n\n分析完成后，引擎会生成验证报告，确保所有文件都已被处理：\n\n```typescript\nreturn {\n  isComplete: unaccountedFiles.length === 0\n    && inventory.files.length\n      === parsedFileIds.size + parseErrorFileIds.size + skippedMetadataOnlyFiles,\n  inventoryFiles: inventory.files.length,\n  parseableFiles: inventory.summary.parseableFiles,\n  parsedFiles: parsedFileIds.size,\n  metadataOnlyFiles: inventory.summary.metadataOnlyFiles,\n  skippedMetadataOnlyFiles,\n  parseErrors: facts.parseErrors.length,\n  unaccountedFiles,\n};\n```\n\n| 验证指标 | 说明 |\n|----------|------|\n| `isComplete` | 所有文件是否都已 accounted for |\n| `unaccountedFiles` | 既未成功解析也未记录错误的文件列表 |\n| `skippedMetadataOnlyFiles` | 跳过的仅元数据文件数量 |\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n\n## 与其他模块的集成\n\n### 集成Compose工具\n\nScan管道的输出是Compose工具的输入之一：\n\n```typescript\nexport class ComposeTool {\n  constructor(\n    private readonly outputBuilder: ComposeOutputBuilder,\n    private readonly artifactWriter: ComposeArtifactWriter,\n  ) {}\n\n  async handle(args: ComposeArgs, store: ArtifactStore): Promise<ToolResult> {\n    const grouping = this.getGrouping(args.groupingArtifactId, store);\n    const inventory = this.getInventory(args.inventoryArtifactId, store);\n    // 使用inventory和grouping构建最终输出...\n  }\n}\n```\n\n资料来源：[src/tools/compose/index.ts:28-42](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)\n\n### 数据流图\n\n```mermaid\ngraph TD\n    subgraph Scan管道\n        A1[scan-file-inventory-builder] --> A2[FileInventory]\n        A2 --> A3[scan-code-analysis-engine]\n        A3 --> A4[AnalysisFacts]\n    end\n    \n    subgraph 分组\n        A4 --> B1[blueprint.group]\n        B1 --> B2[GroupingResult]\n    end\n    \n    subgraph 组合\n        A2 --> C1[ComposeTool]\n        B2 --> C1\n        C1 --> C2[blueprint-output.json]\n    end\n```\n\n## MCP工具接口\n\n### blueprint.scan\n\nScan管道通过MCP工具`blueprint.scan`对外提供服务：\n\n```typescript\nasync handle(\n  args: CodeAnalysisEngineArgs,\n  store: ArtifactStore,\n): Promise<ToolResult> {\n  const entry = store.get(args.inventoryArtifactId);\n  if (!entry) {\n    return errorResult(\n      `File inventory artifact ${args.inventoryArtifactId} not found`,\n    );\n  }\n  // 执行扫描和分析...\n}\n```\n\n### 参数说明\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `inventoryArtifactId` | `string` | 是 | 文件清单artifact的ID |\n| `rootPath` | `string` | 否 | 项目根路径（从inventory获取） |\n\n## 错误处理\n\nScan管道在处理过程中可能遇到以下错误：\n\n| 错误类型 | 处理方式 |\n|----------|----------|\n| 文件清单不存在 | 返回错误信息，中止处理 |\n| 文件读取失败 | 记录parseError，继续处理其他文件 |\n| 解析器创建失败 | 记录parseError，继续处理 |\n| 代码解析异常 | 记录parseError，继续处理 |\n\n引擎设计为**容错型**：单个文件的错误不会影响其他文件的处理，最终通过`unaccountedFiles`和`parseErrors`报告处理状态。\n\n## 性能考量\n\n- 扫描过程按需读取文件，不一次性加载所有内容到内存\n- Tree-sitter解析器按语言类型复用\n- 大型仓库可通过分批处理避免内存溢出\n- metadata-only文件仅记录元数据，不执行深度分析\n\n## 总结\n\nScan管道是Blueprint项目的数据采集层，负责将原始代码仓库转化为结构化的分析数据。其设计遵循以下原则：\n\n1. **完整性优先**：通过验证机制确保所有文件都被accounted for\n2. **容错处理**：单文件错误不影响整体处理\n3. **渐进式分析**：根据文件类型选择合适的分析深度\n4. **模块化设计**：文件清单与代码分析解耦，便于独立演进\n\n---\n\n<a id='page-group-pipeline'></a>\n\n## Group管道 - 语义分组\n\n### 相关页面\n\n相关主题：[工具系统概览](#page-tool-system), [Compose管道 - 最终输出生成](#page-compose-pipeline)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/group/grouping-assignment-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping-assignment-engine.ts)\n- [src/tools/group/grouping.types.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping.types.ts)\n- [src/tools/compose/compose-output-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/compose-output-builder.ts)\n- [src/tools/group/grouping-plan-validator.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping-plan-validator.ts)\n- [src/tools/group-update/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group-update/index.ts)\n</details>\n\n# Group管道 - 语义分组\n\n## 概述\n\nGroup管道是Blueprint项目架构中的核心组件之一，负责将扫描阶段的文件清单（File Inventory）按照语义相关性进行智能分组。该管道通过分析文件的路径模式、角色分类、导入依赖关系等多维度特征，将大量源文件组织成具有明确职责边界的逻辑组（Group），为后续的架构文档生成和可视化展示提供基础数据结构。\n\n语义分组的目标是帮助开发者和架构师快速理解代码库的结构层次，识别核心模块、边界模块和支持模块的分布情况，从而更好地把握系统的整体架构设计。\n\n## 核心数据类型\n\n### GroupingResult\n\n分组管道的主要输出结果类型，包含以下关键字段：\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `groups` | `BlueprintGroup[]` | 分组后的所有组列表 |\n| `crossGroupEdges` | `CrossGroupEdge[]` | 跨组依赖关系边 |\n| `unassignedFiles` | `UnassignedFile[]` | 未能分配到任何组的文件 |\n| `duplicateAssignments` | `DuplicateAssignment[]` | 重复分配记录 |\n| `unknownPatterns` | `UnknownPattern[]` | 无法识别的路径模式 |\n| `isAssignedCompletely` | `boolean` | 是否完全分配 |\n| `blockingIssues` | `string[]` | 阻塞性问题列表 |\n| `warningIssues` | `string[]` | 警告级别问题列表 |\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:1-50]()\n\n### BlueprintGroup\n\n单个分组的数据结构定义：\n\n```typescript\ninterface BlueprintGroup {\n  id: string;           // 组唯一标识符\n  name: string;         // 组名称\n  description: string; // 组描述\n  kind: GroupKind;      // 组类型（core/boundary/support等）\n  confidence: number;   // 分组置信度\n  files: GroupedFile[]; // 包含的文件列表\n}\n```\n\n资料来源：[src/tools/group/grouping.types.ts]()\n\n### GroupedFile\n\n分组内文件的数据结构：\n\n```typescript\ninterface GroupedFile {\n  fileId: string;      // 文件唯一标识\n  path: string;        // 文件相对路径\n  category: string;    // 文件类别\n  language: string;    // 编程语言\n  importance: string;  // 重要程度\n  role: string;        // 文件角色\n}\n```\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:180-190]()\n\n## 架构设计\n\n### 组件关系图\n\n```mermaid\ngraph TD\n    A[FileInventory<br/>文件清单] --> B[GroupingPlanValidator<br/>分组计划验证器]\n    A --> C[GroupingAssignmentEngine<br/>分组分配引擎]\n    B --> D{验证结果}\n    D -->|通过| C\n    D -->|失败| E[ValidationError<br/>验证错误]\n    C --> F[GroupingResult<br/>分组结果]\n    F --> G[BlueprintGroup[]<br/>组列表]\n    F --> H[CrossGroupEdge[]<br/>跨组边]\n    F --> I[Issue Lists<br/>问题列表]\n```\n\n### 核心流程\n\n语义分组管道的工作流程分为两个主要阶段：\n\n1. **准备阶段（Prepare Mode）**：分析文件清单，生成候选分组方案\n2. **应用阶段（Apply Mode）**：根据用户确认的分组方案执行实际分配\n\n```mermaid\nsequenceDiagram\n    participant User as 用户\n    participant Engine as GroupingAssignmentEngine\n    participant Validator as GroupingPlanValidator\n    participant Inventory as FileInventory\n    \n    User->>Engine: blueprint.group(mode: \"prepare\")\n    Engine->>Inventory: 获取文件清单\n    Inventory-->>Engine: 文件列表及分析数据\n    Engine->>Engine: 分析文件特征与依赖关系\n    Engine->>Validator: 验证分组计划\n    Validator-->>Engine: 验证结果\n    Engine-->>User: 分组候选方案\n    \n    User->>Engine: blueprint.group(mode: \"apply\")\n    Engine->>Engine: 执行文件分配\n    Engine->>Engine: 聚合跨组依赖边\n    Engine-->>User: 最终分组结果\n```\n\n## GroupingAssignmentEngine 实现细节\n\n### 主要职责\n\n`GroupingAssignmentEngine` 是分组管道的核心执行引擎，承担以下职责：\n\n| 职责 | 描述 |\n|------|------|\n| 模式切换 | 支持 prepare 和 apply 两种执行模式 |\n| 计划验证 | 调用验证器确保分组计划的合法性 |\n| 文件分配 | 将清单中的文件映射到对应分组 |\n| 边聚合 | 收集并聚合跨组依赖关系 |\n| 问题收集 | 识别未分配文件、重复分配、未知模式等问题 |\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:1-100]()\n\n### 分组执行逻辑\n\n```mermaid\ngraph LR\n    A[遍历计划中的组] --> B{文件属于哪个组?}\n    B -->|文件已唯一分配| C[加入该组]\n    B -->|文件未分配| D[加入未分配列表]\n    B -->|文件重复分配| E[记录重复分配]\n    C --> F[排序文件列表]\n    D --> G[统计阻塞问题]\n    E --> G\n    F --> H[聚合跨组边]\n    G --> I[生成最终结果]\n    H --> I\n```\n\n### 关键方法\n\n#### groupedFile 方法\n\n将 `FileInventory` 中的文件转换为 `GroupedFile` 结构：\n\n```typescript\nprivate groupedFile(file: FileInventory[\"files\"][number]): GroupedFile {\n  return {\n    fileId: file.fileId,\n    path: file.path,\n    category: file.category,\n    language: file.language,\n    importance: \"unknown\",\n    role: \"unknown\",\n  };\n}\n```\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:180-190]()\n\n#### aggregateEdges 方法\n\n聚合跨组依赖边，识别不同分组之间的关联关系：\n\n```mermaid\ngraph TD\n    A[遍历所有文件] --> B[提取导入关系]\n    B --> C{导入文件属于哪个组?}\n    C -->|同组| D[忽略（组内依赖）]\n    C -->|不同组| E[创建跨组边]\n    E --> F{边是否已存在?}\n    F -->|是| G[更新边属性]\n    F -->|否| H[新增边记录]\n    G --> I[返回边集合]\n    H --> I\n```\n\n### 未知模式处理\n\n当分组计划中包含无法匹配文件的路径模式时，系统会生成 `UnknownPattern` 报告：\n\n```typescript\nprivate unknownPattern(inventory: FileInventory, pattern: string): UnknownPattern {\n  return {\n    pattern,\n    reason: \"matched no inventory files; the path may be ignored or not inventoried\",\n    suggestions: this.suggestPaths(inventory, pattern),\n  };\n}\n```\n\n`suggestPaths` 方法会尝试找到与模式相似的实际文件路径，为用户提供修正建议：\n\n```typescript\nprivate suggestPaths(inventory: FileInventory, pattern: string): string[] {\n  const suffix = pattern\n    .replaceAll(\"*\", \"\")\n    .replaceAll(\"?\", \"\")\n    .split(\"/\")\n    .filter(Boolean)\n    .at(-1);\n  if (!suffix) return [];\n  return inventory.files\n    .map((file) => file.path)\n    .filter((path) => path.includes(suffix))\n    .slice(0, 5);\n}\n```\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:195-220]()\n\n## 分组计划验证\n\n### 验证规则\n\n`GroupingPlanValidator` 负责在执行分组前验证计划的合法性：\n\n| 验证规则 | 描述 |\n|----------|------|\n| 完整性检查 | 确保所有文件都能被分配 |\n| 唯一性检查 | 确保文件不会被重复分配到多个组 |\n| 模式有效性 | 确保路径模式能够匹配到实际文件 |\n| 组定义检查 | 确保组定义完整（id、name、kind） |\n\n### 验证结果处理\n\n```mermaid\ngraph TD\n    A[执行验证] --> B{验证通过?}\n    B -->|是| C[返回有效状态]\n    B -->|否| D{错误类型}\n    D -->|阻塞性错误| E[阻止分组执行]\n    D -->|警告级别| F[记录警告但继续执行]\n    E --> G[返回详细错误信息]\n    F --> H[包含警告的分组结果]\n```\n\n## 输出结构\n\n### BlueprintOutput 转换\n\n`GroupingAssignmentEngine` 的结果会被 `compose-output-builder.ts` 转换为标准化的 `BlueprintOutput` 格式：\n\n```typescript\ngroups: grouping.groups\n  .map((group) => ({\n    id: group.id,\n    name: group.name,\n    kind: group.kind,\n    summary: group.description,\n    docsPath: this.groupDocsPath(group.id),\n    fileIds: group.files.map((file) => file.fileId).sort(),\n  }))\n  .sort((a, b) => a.id.localeCompare(b.id)),\n```\n\n资料来源：[src/tools/compose/compose-output-builder.ts:1-30]()\n\n### 文件输出格式\n\n```typescript\nfiles: grouping.groups\n  .flatMap((group) =>\n    group.files.map((file) => ({\n      id: file.fileId,\n      path: file.path,\n      groupId: group.id,\n      category: file.category,\n      language: file.language,\n      notesStatus: \"not-required\" as const,\n      role: file.role && file.role !== \"unknown\" ? file.role : undefined,\n    })),\n  )\n  .sort((a, b) => a.path.localeCompare(b.path)),\n```\n\n### 边输出格式\n\n跨组依赖边按组ID和类型排序输出：\n\n```typescript\nedges: [...grouping.crossGroupEdges]\n  .sort((a, b) =>\n    a.fromGroupId.localeCompare(b.fromGroupId)\n    || a.toGroupId.localeCompare(b.toGroupId)\n    || a.type.localeCompare(b.type),\n  ),\n```\n\n## 动态分组更新\n\n### 增量更新机制\n\n当代码库发生变化（文件增删改）时，`GroupUpdateArgs` 提供了增量更新能力：\n\n```typescript\ninterface GroupUpdateArgs {\n  decision: {\n    assignments: Array<{ fileId: string; groupId: string }>;\n    newGroups: Array<{ id: string; name: string; fileIds: string[] }>;\n    deletedGroups: string[];\n  };\n  unassignedGroupId: string;\n}\n```\n\n资料来源：[src/tools/group-update/index.ts:1-50]()\n\n### 空组候选检测\n\n系统会自动识别没有文件分配的组作为删除候选：\n\n```typescript\nconst emptyGroupCandidates = output.groups\n  .filter((group) => group.fileIds.length === 0)\n  .map((group) => ({\n    groupId: group.id,\n    name: group.name,\n    docsPath: group.docsPath,\n    deletedFileIds: [],\n  }));\n```\n\n## 路径模式匹配\n\n### 模式语法\n\n分组计划支持类 glob 的路径模式匹配：\n\n| 模式字符 | 含义 | 示例 |\n|----------|------|------|\n| `*` | 匹配任意字符（不含路径分隔符） | `src/*.ts` 匹配 `src/a.ts` 但不匹配 `src/utils/b.ts` |\n| `**` | 匹配任意字符（含路径分隔符） | `src/**/*.ts` 匹配 `src/utils/b.ts` |\n| `?` | 匹配单个字符 | `src/??.ts` 匹配 `src/ab.ts` |\n| `[abc]` | 匹配字符集合 | `src/[ab]c.ts` 匹配 `src/ac.ts` 和 `src/bc.ts` |\n\n### 正则转换实现\n\n```typescript\nprivate patternToRegex(pattern: string): RegExp {\n  let source = \"\";\n  for (const char of pattern) {\n    if (char === \"*\") {\n      if (source.endsWith(\"[^/]*\")) {\n        source += \"[^/]*\";\n      } else {\n        source += \"[^/]*\";\n      }\n      continue;\n    }\n    if (char === \"?\") {\n      source += \"[^/]\";\n      continue;\n    }\n    source += this.escapeRegex(char);\n  }\n  return new RegExp(`^${source}$`);\n}\n```\n\n## 最佳实践\n\n### 分组命名规范\n\n| 规范 | 说明 |\n|------|------|\n| 使用 kebab-case | 组ID推荐使用小写连字符格式 |\n| 包含功能描述 | 组名称应清晰表达功能职责 |\n| 避免过于通用 | 避免使用 \"other\"、\"misc\" 等模糊命名 |\n\n### 模式编写建议\n\n1. **优先级顺序**：更具体的模式应放在前面\n2. **互斥性检查**：确保模式之间不会产生重叠匹配\n3. **边界情况**：考虑测试文件、配置文件等的归属\n\n### 性能考量\n\n| 场景 | 建议 |\n|------|------|\n| 大型代码库 | 使用 `**` 模式进行批量匹配 |\n| 频繁更新 | 利用增量更新而非全量重新分组 |\n| 调试阶段 | 启用详细日志观察匹配过程 |\n\n## 相关命令\n\n| 命令 | 用途 |\n|------|------|\n| `blueprint.scan` | 扫描文件并生成清单 |\n| `blueprint.group` | 执行语义分组（prepare/apply模式） |\n| `blueprint.refresh` | 增量刷新分组状态 |\n| `blueprint.compose` | 生成最终输出和文档 |\n\n## 扩展与定制\n\n### 自定义分组规则\n\n开发者可以通过扩展 `GroupingAssignmentEngine` 类来实现自定义分组逻辑：\n\n```typescript\nclass CustomGroupingEngine extends GroupingAssignmentEngine {\n  protected override classifyFile(file: FileInfo): string {\n    // 自定义分类逻辑\n  }\n}\n```\n\n### 集成CI/CD\n\n建议在持续集成流程中集成分组更新检查：\n\n```yaml\n# .github/workflows/blueprint-check.yml\n- name: Check Blueprint consistency\n  run: npx blueprint group --mode prepare --dry-run\n```\n\n## 参考资料\n\n- 分组引擎实现：[src/tools/group/grouping-assignment-engine.ts]()\n- 类型定义：[src/tools/group/grouping.types.ts]()\n- 计划验证器：[src/tools/group/grouping-plan-validator.ts]()\n- 输出构建器：[src/tools/compose/compose-output-builder.ts]()\n- 更新机制：[src/tools/group-update/index.ts]()\n\n---\n\n<a id='page-compose-pipeline'></a>\n\n## Compose管道 - 最终输出生成\n\n### 相关页面\n\n相关主题：[Group管道 - 语义分组](#page-group-pipeline), [数据存储与路径管理](#page-data-storage)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/compose/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)\n- [src/tools/compose/compose-output-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/compose-output-builder.ts)\n- [src/tools/compose/compose-artifact-writer.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/compose-artifact-writer.ts)\n- [src/tools/compose/compose.types.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/compose.types.ts)\n\n</details>\n\n# Compose管道 - 最终输出生成\n\n## 概述\n\nCompose管道是Blueprint系统工作流的最终阶段，负责将扫描、分组和编排的结果整合为可读的最终输出。`blueprint.compose`工具执行此管道，将Blueprint的内存数据转换为结构化的JSON工件和Markdown文档。 资料来源：[README.md - Tools章节]()\n\nCompose管道的核心职责包括：\n\n- 将分组引擎生成的文件组与代码分析结果合并\n- 生成`.blueprint/blueprint-output.json`主工件文件\n- 创建`.blueprint/groups/*.md`组文档集合\n- 生成`.blueprint/brief.md`项目概要文档\n- 支持静态HTML查看器的数据输出 资料来源：[todos_120526.md - 项目Root/.blueprint/index.html]()\n\n## 架构设计\n\n### 管道入口结构\n\nCompose管道采用分层架构设计，从入口到输出形成清晰的单向数据流：\n\n```mermaid\ngraph TD\n    A[compose输入参数] --> B[ComposeInput验证]\n    B --> C[ComposeOutputBuilder]\n    C --> D[ArtifactWriter]\n    D --> E[blueprint-output.json]\n    D --> F[groups/*.md]\n    D --> G[brief.md]\n    \n    H[scan-code-analysis-engine] --> I[AnalysisFacts]\n    G --> J[GroupingEngine]\n    J --> K[GroupedFiles]\n    I --> C\n    K --> C\n```\n\n### 核心组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| ComposeInput | compose.types.ts | 定义输入参数类型和验证规则 |\n| ComposeOutputBuilder | compose-output-builder.ts | 编排输出数据结构 |\n| ArtifactWriter | compose-artifact-writer.ts | 将数据写入文件系统 |\n| SectionContent | GroupDetailPanel.tsx | 渲染Markdown内容块 |\n\n## 数据模型\n\n### ComposeInput类型定义\n\n```typescript\ninterface ComposeInput {\n  projectRoot: string;           // 项目根目录路径\n  inventoryArtifactId?: string; // 文件清单工件ID\n  analysisArtifactId?: string;   // 代码分析工件ID\n  groupAssignmentId?: string;    // 分组分配工件ID\n  briefMd?: string;              // 概要文档内容\n}\n```\n\n### 输出工件结构\n\nCompose管道生成的JSON工件包含以下主要字段：\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| version | string | Blueprint版本标识 |\n| generatedAt | string | 生成时间戳 |\n| projectRoot | string | 项目根路径 |\n| brief | Brief | 项目概要信息 |\n| groups | Group[] | 所有文件组列表 |\n| metadata | Metadata | 工件元数据 |\n\n## 工作流程\n\n### 完整执行流程\n\n```mermaid\nsequenceDiagram\n    participant CLI as blueprint compose\n    participant Engine as ComposeEngine\n    participant Builder as OutputBuilder\n    participant Writer as ArtifactWriter\n    participant FS as FileSystem\n    \n    CLI->>Engine: execute(args)\n    Engine->>Engine: 验证输入参数\n    Engine->>Builder: 构建输出结构\n    Builder->>Builder: 合并分析结果与分组\n    Builder->>Writer: 写入blueprint-output.json\n    Writer->>FS: 创建.groups目录\n    Builder->>Writer: 写入groups/*.md\n    Writer->>FS: 创建各组文档\n    Builder->>Writer: 写入brief.md\n    Writer->>FS: 生成项目概要\n    FS-->>Engine: 返回写入结果\n    Engine-->>CLI: 返回执行结果\n```\n\n### 各阶段详解\n\n#### 1. 输入验证阶段\n\nCompose管道首先验证输入参数的有效性：\n\n- 检查`projectRoot`路径是否存在且可访问\n- 验证工件ID引用的数据是否存在于存储中\n- 确保必要的依赖数据已生成 资料来源：[compose.types.ts - ComposeInput]()\n\n#### 2. 数据编排阶段\n\n输出构建器执行数据整合操作：\n\n```typescript\n// 伪代码示例\nfunction buildOutput(input: ComposeInput): ComposeOutput {\n  const analysis = getAnalysisFacts(input.analysisArtifactId);\n  const groups = getGroupedFiles(input.groupAssignmentId);\n  \n  return {\n    summary: aggregateSummary(analysis),\n    groups: enrichGroups(groups, analysis),\n    brief: input.briefMd ?? generateDefaultBrief()\n  };\n}\n```\n\n#### 3. 工件写入阶段\n\n文件写入器负责持久化输出：\n\n- 创建`.blueprint/`目录结构\n- 序列化JSON数据为`blueprint-output.json`\n- 生成每个组的Markdown文档\n- 写入项目级`brief.md`文件 资料来源：[compose-artifact-writer.ts - 目录结构]()\n\n## 组文档生成\n\n### 文档模板结构\n\nBlueprint组文档遵循统一的模板格式，便于AI代理和开发人员快速定位信息：\n\n| 章节 | 用途 | 重要性 |\n|------|------|--------|\n| Snapshot | 快速了解代码组的核心功能 | 默认展开 |\n| Responsibilities | 定义职责范围和边界 | 默认展开 |\n| Core Flow | 运行时行为和数据流 | 关键 |\n| Contracts & Invariants | 不可破坏的行为约束 | 重要 |\n| Key Files | 指向主要源文件 | 参考 |\n| Change Guide | 变更时的协同修改建议 | 指导 |\n| Pitfalls | 已知风险和常见错误 | 警示 |\n| Tests | 测试相关说明 | 参考 |\n| Extension Open Questions | 扩展和待解决问题 | 探索 |\n\n资料来源：[AGENTS.md - Group Doc Template]()\n\n### SectionCard组件\n\n`SectionCard`组件负责渲染可折叠的文档章节：\n\n```typescript\ninterface SectionCardProps {\n  title: string;\n  content: string;\n  accent?: 'amber' | 'red' | 'green' | 'blue' | 'zinc';\n  defaultOpen?: boolean;\n  index?: number;\n}\n```\n\n颜色语义定义：\n\n| 颜色 | 语义 | 使用场景 |\n|------|------|----------|\n| amber | 警告 | Pitfalls章节 |\n| red | 危险 | Contracts & Invariants章节 |\n| green | 提示 | Extension Open Questions章节 |\n| blue | 信息 | Open Questions章节 |\n| zinc | 默认 | 标准章节 |\n\n资料来源：[GroupDetailPanel.tsx - SectionCard组件]()\n\n## Markdown内容渲染\n\n### 内容块解析\n\n`SectionContent`组件负责解析和渲染Markdown内容，支持以下块类型：\n\n| 块类型 | 识别规则 | 渲染方式 |\n|--------|----------|----------|\n| 代码块 | ` ``` ` | 语法高亮容器 |\n| 标题 | `^#{1,4}\\s+` | 对应级别的标题样式 |\n| 无序列表 | `^\\s*[-*]\\s+` | 项目符号列表 |\n| 有序列表 | `^\\s*\\d+\\.\\s+` | 数字编号列表 |\n| 引用 | `^>\\s?` | 左侧边框引用块 |\n| 段落 | 其他文本 | 标准段落样式 |\n\n### 行内Markdown渲染\n\n行内元素通过`renderInlineMarkdown`函数处理：\n\n- **加粗文本**: `**text**` → `<strong>`\n- *斜体文本*: `*text*` → `<em>`\n- `行内代码`: `` `code` `` → `<code>`\n- [链接文本](url): `[text](url)` → `<a>`\n\n资料来源：[markdown.tsx - renderInlineMarkdown函数]()\n\n## 与其他管道的交互\n\n### 前置依赖\n\nCompose管道依赖以下上游管道的结果：\n\n```mermaid\ngraph LR\n    A[scan管道] -->|FileInventory| B[compose管道]\n    C[scan管道] -->|AnalysisFacts| B\n    D[group管道] -->|GroupedFiles| B\n    \n    B -->|Blueprint Memory| E[viewer UI]\n    B -->|Markdown Docs| F[开发者阅读]\n```\n\n| 管道 | 输出工件 | Compose使用方式 |\n|------|----------|-----------------|\n| `blueprint.scan` | fileInventory | 文件路径和元数据 |\n| `blueprint.scan` | codeAnalysis | 符号和导入依赖 |\n| `blueprint.group` | groupAssignment | 文件分组结构 |\n\n资料来源：[scan-code-analysis-engine.ts - 工件结构]()\n\n### 查看器数据源\n\nCompose输出支持两种查看器数据源模式：\n\n| 模式 | 数据源 | 用途 |\n|------|--------|------|\n| Static/Embedded | `.blueprint/index.html`内嵌JSON | 分发和离线查看 |\n| HTTP | 实时API响应 | 开发调试模式 |\n\n静态模式下，查看器数据通过`<script id=\"blueprint-data\" type=\"application/json\">`嵌入HTML，需进行XSS安全转义。 资料来源：[todos_120526.md - Embedded data模型]()\n\n## 配置与参数\n\n### 命令行参数\n\n```bash\nblueprint compose [options]\n```\n\n| 参数 | 必填 | 默认值 | 描述 |\n|------|------|--------|------|\n| `--project-root` | 是 | - | 项目根目录路径 |\n| `--inventory-id` | 否 | 自动推断 | 文件清单工件ID |\n| `--analysis-id` | 否 | 自动推断 | 代码分析工件ID |\n| `--group-id` | 否 | 自动推断 | 分组分配工件ID |\n| `--brief` | 否 | 自动生成 | 自定义概要内容 |\n\n### 输出路径配置\n\n所有输出文件默认写入项目根目录下的`.blueprint/`文件夹：\n\n| 文件/目录 | 说明 |\n|-----------|------|\n| `.blueprint/blueprint-output.json` | 主工件文件 |\n| `.blueprint/brief.md` | 项目概要文档 |\n| `.blueprint/groups/` | 各组详细文档目录 |\n| `.blueprint/index.html` | 静态查看器HTML |\n\n资料来源：[README.md - Viewer UI章节]()\n\n## 错误处理与验证\n\n### 验证检查点\n\nCompose管道在执行过程中设置多个验证点：\n\n1. **输入验证**: 检查参数完整性和路径有效性\n2. **依赖验证**: 确保上游工件存在且类型正确\n3. **写入验证**: 确认文件成功创建且内容完整\n4. **完整性检查**: 验证所有分组都有对应文档\n\n### 失败场景处理\n\n| 错误类型 | 表现 | 恢复方式 |\n|----------|------|----------|\n| 工件缺失 | \"Artifact not found\" | 重新运行上游管道 |\n| 路径无效 | \"Invalid project root\" | 检查并修复路径 |\n| 写入失败 | \"Failed to write file\" | 检查目录权限 |\n| 数据损坏 | \"Parse error in artifact\" | 清理后重新扫描 |\n\n## 扩展点\n\n### 自定义内容处理器\n\n开发者可以通过扩展`SectionContent`组件来支持更多Markdown语法变体：\n\n```typescript\n// 扩展示例\nconst customBlocks: BlockType[] = ['callout', 'warning', 'note'];\nfunction renderCustomBlock(block: CustomBlock): ReactNode {\n  // 自定义渲染逻辑\n}\n```\n\n### 替代输出格式\n\n当前架构支持扩展不同的输出格式：\n\n- JSON格式（默认）\n- YAML格式（需插件）\n- Protocol Buffer格式（用于RPC场景）\n\n## 最佳实践\n\n1. **确保上游管道完成**: 在运行compose前验证scan和group管道已成功执行\n2. **定期刷新**: 使用`blueprint.refresh`同步最新文件系统状态\n3. **版本控制**: 将`.blueprint/`目录纳入版本控制以保持团队一致性\n4. **查看器更新**: 修改源文件后运行`blueprint open --watch`保持查看器同步\n\n---\n\n*本文档基于Blueprint v1.x版本编写，涵盖Compose管道的核心功能和数据流。*\n\n---\n\n<a id='page-refresh-system'></a>\n\n## Refresh系统 - 状态刷新与维护\n\n### 相关页面\n\n相关主题：[工具系统概览](#page-tool-system), [数据存储与路径管理](#page-data-storage)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/refresh/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/refresh/index.ts)\n- [src/tools/refresh/refresh.types.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/refresh/refresh.types.ts)\n- [src/tools/group-update/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group-update/index.ts)\n</details>\n\n# Refresh系统 - 状态刷新与维护\n\n## 概述\n\n> **注意**：当前提供的源码上下文**不包含** `src/tools/refresh/` 目录下的文件内容。本页面基于 TODO 文档中记录的 Refresh 系统设计目标和 CLI 命令规范进行推断性描述，实际实现细节需以源码为准。\n\n根据 `todos_120526.md` 中的规划，Refresh 系统旨在实现 Blueprint 状态与当前文件系统快照的同步维护。\n\n## 核心设计目标\n\n根据项目规划文档，Refresh 系统需满足以下核心目标：\n\n| 目标 | 描述 |\n|------|------|\n| 文件系统快照同步 | 从当前文件系统状态刷新 Blueprint 内存 |\n| 组状态维护 | 管理 `.blueprint/groups/*.md` 中的组信息 |\n| 增量更新 | 支持增量刷新而非全量重建 |\n| 状态一致性 | 确保 Blueprint 输出与实际代码结构同步 |\n\n资料来源：[todos_120526.md:任务规划]()\n\n## 架构组件\n\n### Refresh 模块 (src/tools/refresh/)\n\n根据项目结构推测，Refresh 模块位于 `src/tools/refresh/` 目录，包含以下核心文件：\n\n- `index.ts` - Refresh 入口和主逻辑\n- `refresh.types.ts` - Refresh 相关类型定义\n\n### Group Update 模块 (src/tools/group-update/)\n\nGroup Update 模块负责组级别的状态更新：\n\n- `index.ts` - 组更新入口\n\n资料来源：[todos_120526.md:任务规划]()\n\n## 工作流程\n\n```mermaid\ngraph TD\n    A[blueprint refresh 命令] --> B[扫描文件系统变更]\n    B --> C{检测到变更?}\n    C -->|是| D[增量更新 Inventory]\n    C -->|否| E[保持现有状态]\n    D --> F[同步 groups 目录]\n    F --> G[更新 brief.md]\n    G --> H[生成增量输出]\n    H --> I[写入 .blueprint/]\n    I --> J[输出摘要报告]\n```\n\n### 刷新触发条件\n\nRefresh 系统可在以下场景触发：\n\n1. **手动触发**：用户执行 `blueprint refresh` 命令\n2. **扫描后触发**：在 `blueprint scan` 完成后自动执行\n3. **组更新触发**：在 `blueprint group.update` 执行后同步状态\n\n资料来源：[README.md:Tools表格](README.md)\n\n## CLI 接口\n\n### blueprint refresh 命令\n\n| 参数/选项 | 类型 | 描述 |\n|-----------|------|------|\n| `--project-root` | 路径 | 项目根目录，默认为当前工作目录 |\n| `--force` | 标志 | 强制全量刷新 |\n| `--dry-run` | 标志 | 模拟刷新，不写入文件 |\n\n### blueprint group.update 命令\n\n该命令是 Refresh 系统的重要组成部分，负责：\n\n- 分配未分配的文件到相应组\n- 管理刷新后的空组\n- 维护组与文件的映射关系\n\n资料来源：[README.md:Tools表格](README.md)\n\n## 与其他模块的集成\n\n```mermaid\ngraph LR\n    A[Scan 模块] -->|生成 FileInventory| R[Refresh 系统]\n    B[Group 模块] -->|分组策略| R\n    R -->|同步状态| G[Groups 目录]\n    R -->|更新索引| B[brief.md]\n    G --> V[Viewer UI]\n```\n\n### 依赖关系\n\n| 模块 | 依赖关系 |\n|------|----------|\n| Scan | Refresh 的上游，提供文件清单 |\n| Group | 与 Refresh 并行，维护语义分组 |\n| Compose | Refresh 的下游，消费刷新后的状态 |\n| Viewer | 消费 Refresh 生成的静态资源 |\n\n资料来源：[todos_120526.md:任务规划]()\n\n## 实现要点\n\n### 1. 状态持久化\n\nRefresh 系统维护的状态存储在 `.blueprint/` 目录：\n\n```\n.blueprint/\n├── blueprint-output.json    # 主输出文件\n├── brief.md                  # 项目概览\n├── groups/\n│   ├── group-a.md\n│   ├── group-b.md\n│   └── ...\n└── inventory/                # 可选的扫描缓存\n```\n\n### 2. 增量刷新策略\n\n根据项目规划，Refresh 系统应支持增量刷新：\n\n- 检测文件新增、删除、修改\n- 仅更新受影响组的内容\n- 保留未变更组的现有文档\n\n### 3. Group 文档同步\n\n刷新过程中需要同步维护组文档：\n\n- 更新 `Snapshot` 部分反映新文件\n- 重新计算 `Key Files` 列表\n- 检查 `Contracts & Invariants` 是否仍有效\n\n资料来源：[AGENTS.md:Group Doc Template]()\n\n## 已知限制\n\n根据项目 TODO 文档中的记录：\n\n| 限制项 | 描述 |\n|--------|------|\n| 首次刷新 | 需要完整扫描，不支持跳过 |\n| 实时更新 | 初始版本不包含 SSE/live update |\n| 文件锁定 | 刷新期间目标文件需可写 |\n\n资料来源：[todos_120526.md:已知限制]()\n\n## 相关命令速查\n\n```bash\n# 刷新 Blueprint 状态\nblueprint refresh\n\n# 组级别更新\nblueprint group.update\n\n# 扫描代码库\nblueprint scan\n\n# 查看当前 Blueprint\nblueprint open\n```\n\n资料来源：[README.md:CLI Commands]()\n\n## 待确认的实现细节\n\n以下信息需要通过查阅实际源码确认：\n\n1. **刷新算法**：增量刷新的具体检测逻辑\n2. **并发控制**：多进程/线程下的状态一致性\n3. **错误处理**：文件系统变更异常的处理策略\n4. **缓存策略**：Inventory 缓存的有效期和失效机制\n\n---\n\n<a id='page-task-context'></a>\n\n## Task Context - 任务上下文构建\n\n### 相关页面\n\n相关主题：[工具系统概览](#page-tool-system), [Compose管道 - 最终输出生成](#page-compose-pipeline)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/lib/agent-instructions.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/agent-instructions.ts)\n- [AGENTS.md](https://github.com/engincankaya/blueprint/blob/main/AGENTS.md)\n- [frontend/src/components/blueprint/GroupDetailPanel.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/blueprint/GroupDetailPanel.tsx)\n- [frontend/src/components/BlueprintApp.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/BlueprintApp.tsx)\n- [src/viewer/render-html.ts](https://github.com/engincankaya/blueprint/blob/main/src/viewer/render-html.ts)\n</details>\n\n# Task Context - 任务上下文构建\n\n## 概述\n\nTask Context（任务上下文）是 Blueprint 项目中用于为 AI Agent 提供结构化架构记忆的核心机制。它通过构建和呈现项目架构信息，帮助 AI Agent 在执行代码探索和修改任务时获得必要的上下文理解，避免盲目搜索代码库。\n\nBlueprint 的任务上下文构建系统包含两个核心组成部分：\n\n1. **Brief 机制** - 通过 `.blueprint/brief.md` 提供项目级架构概览\n2. **Group Docs 机制** - 通过 `.blueprint/groups/*.md` 提供分组级的详细文档\n\n资料来源：[AGENTS.md]()()\n\n## 核心架构\n\n### 任务上下文构建流程\n\n```mermaid\ngraph TD\n    A[开始代码探索] --> B{Blueprint 记忆存在?}\n    B -->|是| C[读取 brief.md]\n    B -->|否| D[构建默认上下文]\n    C --> E[使用稳定章节标题定位]\n    E --> F[读取相关 Group Doc]\n    F --> G[切换到源码检查]\n    G --> H[执行开发任务]\n    D --> H\n```\n\n资料来源：[AGENTS.md:4-7]()\n\n### 上下文信息来源层级\n\nBlueprint 采用分层的信息组织方式，Agent 应遵循以下优先级：\n\n| 优先级 | 信息源 | 用途 | 读取策略 |\n|--------|--------|------|----------|\n| 1 | `.blueprint/brief.md` | 项目整体架构概览 | 始终读取 |\n| 2 | `.blueprint/groups/*.md` | 分组级架构文档 | 按需读取 |\n| 3 | 源码文件 | 实际实现细节 | 确定文件后切换 |\n\n资料来源：[AGENTS.md:1-7]()\n\n## Brief 机制\n\n### brief.md 的作用\n\n`brief.md` 是 Blueprint 项目架构记忆的入口点，它提供了项目的整体架构概述。根据 `agent-instructions.ts` 中的实现：\n\n```typescript\nexport function renderBlueprintAgentsSnippet(): string {\n  return [\n    beginMarker,\n    \"\",\n    \"## Blueprint MCP\",\n    \"\",\n    \"This project uses Blueprint MCP for local architecture memory.\",\n    \"\",\n    \"Before broad codebase exploration, read:\",\n    \"\",\n    \"`node_modules/blueprint-mcp-server/docs/agents.md`\",\n    \"\",\n    \"If Blueprint memory exists, start with:\",\n    \"\",\n    \"`.blueprint/brief.md`\",\n    \"\",\n    endMarker,\n  ].join(\"\\n\");\n}\n```\n\n资料来源：[src/lib/agent-instructions.ts:37-56]()\n\n该函数生成了一个 Blueprint Agent 片段，当 `AGENTS.md` 文件不存在时，会自动插入带有标记的 Blueprint 片段，引导 Agent 首先读取 `brief.md`。\n\n### Agent 指令snippet写入\n\nBlueprint 通过 `appendBlueprintAgentsSnippet` 函数在 `AGENTS.md` 文件中添加 Agent 指令：\n\n```typescript\nexport async function appendBlueprintAgentsSnippet(\n  path: string,\n  snippet: string,\n): Promise<{ path: string; changed: boolean }> {\n  const exists = await fileExists(path);\n  if (!exists) {\n    await writeFile(path, snippet + \"\\n\", \"utf-8\");\n    return { path, changed: false };\n  }\n  // ... 处理已存在文件的情况\n  await writeFile(path, `${current}${separator}${snippet}\\n`, \"utf-8\");\n  return { path, changed: true };\n}\n```\n\n资料来源：[src/lib/agent-instructions.ts:18-34]()\n\n## Group Docs 机制\n\n### 分组文档结构\n\nGroup Docs 位于 `.blueprint/groups/*.md`，遵循稳定的模板结构。在 `GroupDetailPanel.tsx` 中可以看到这些文档在 UI 中的呈现方式：\n\n```typescript\n// Overview 标签页\n{s.snapshot && (\n  <SectionCard title=\"Snapshot\" content={s.snapshot} defaultOpen index={0} />\n)}\n{s.responsibilities && (\n  <SectionCard title=\"Responsibilities\" content={s.responsibilities} defaultOpen index={1} />\n)}\n{s.keyFiles && (\n  <SectionCard title=\"Key Files\" content={s.keyFiles} index={2} />\n)}\n```\n\n资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx]()\n\n### 稳定章节标题\n\nGroup Doc 模板定义了以下稳定章节，Agent 可以直接跳转：\n\n| 章节名称 | 用途 | 优先级 |\n|----------|------|--------|\n| Snapshot | 快速定位和理解 | 默认展开 |\n| Responsibilities | 定义所有权和范围外区域 | 默认展开 |\n| Core Flow | 运行时行为和数据流 | 按需 |\n| Contracts & Invariants | 必须遵守的行为约束 | 重要 |\n| Key Files | 指向主要源文件 | 参考 |\n| Change Guide | 应该一起变更的文件或合约 | 实现检查清单 |\n| Pitfalls | 已知风险和常见错误 | 重要 |\n| Tests | 测试相关信息 | 参考 |\n\n资料来源：[AGENTS.md:6](), [GroupDetailPanel.tsx]()\n\n### UI 标签页结构\n\n在 `GroupDetailPanel.tsx` 中，任务上下文通过以下标签页呈现给用户：\n\n```typescript\nconst SUB_TABS = [\n  { id: \"overview\", label: \"Overview\" },\n  { id: \"files\", label: \"Files\" },\n  { id: \"connections\", label: \"Connections\" },\n  { id: \"architecture\", label: \"Architecture\" },\n  { id: \"guide\", label: \"Guide\" },\n];\n```\n\n资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx]()\n\n## 任务上下文构建的最佳实践\n\n### 推荐的阅读策略\n\n根据 Blueprint 的设计原则，Agent 应遵循以下策略：\n\n1. **优先读取 narrow 范围** - 使用搜索命中的前后 20-60 行窗口\n2. **使用稳定标题跳转** - 直接定位到 `Core Flow`、`Contracts & Invariants` 等章节\n3. **避免过早读取完整文档** - 仅在以下情况才阅读完整 Group Doc：\n   - 搜索结果不明确\n   - 任务涉及更改该分组的架构合约\n   - 需要章节结构作为实现检查清单\n   - 源码上下文在目标读取后仍不清晰\n\n4. **确定文件后切换到源码** - 识别相关源文件后，停止继续阅读 Blueprint，转向目标源码检查\n\n资料来源：[AGENTS.md:2-8]()\n\n### 上下文构建的默认预算\n\n| 类型 | 预算策略 |\n|------|----------|\n| `.blueprint/brief.md` | 始终读取 |\n| Blueprint Markdown 搜索 | 始终优先 |\n| Group Docs | 先读取目标摘录 |\n| 完整 Group Docs | 例外，非默认 |\n\n资料来源：[AGENTS.md:11-15]()\n\n## 渲染与呈现\n\n### 前端组件架构\n\nBlueprint 的前端通过 `BlueprintApp.tsx` 管理任务上下文的呈现：\n\n```typescript\n{activeTab.type === \"canvas\" ? (\n  <BlueprintCanvas overview={overview} activeGroupId={activeGroupId} onGroupClick={openGroup} />\n) : details[activeTab.group.id] ? (\n  <GroupDetailPanel detail={details[activeTab.group.id]} />\n) : (\n  <div className=\"flex h-full items-center justify-center bg-zinc-950 text-sm text-zinc-500\">\n    {detailErrors[activeTab.group.id]\n      ?? (detailLoading[activeTab.group.id] ? \"Loading group...\" : \"Waiting for group data...\")}\n  </div>\n)}\n```\n\n资料来源：[frontend/src/components/BlueprintApp.tsx]()\n\n### SectionCard 组件\n\n`SectionCard` 是展示任务上下文内容的核心 UI 组件，支持：\n\n- **可折叠展开** - 通过 `defaultOpen` 属性控制默认状态\n- **强调色支持** - 通过 `accent` 属性设置颜色主题\n- **预览模式** - 收起状态显示一行预览文本\n- **动画过渡** - 使用 Framer Motion 实现平滑展开/收起动画\n\n```typescript\nfunction SectionCard({\n  title,\n  content,\n  accent,\n  defaultOpen = false,\n  index = 0,\n}: {\n  title: string\n  content: string\n  accent?: 'amber' | 'red' | 'green' | 'blue' | 'zinc'\n  defaultOpen?: boolean\n  index?: number\n})\n```\n\n资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx]()\n\n## 嵌入式 Viewer 渲染\n\n### HTML 内联渲染\n\nBlueprint 的 viewer 功能支持将 HTML 页面中的 CSS 和 JavaScript 内联化：\n\n```typescript\nasync function inlineStyles(html: string, viewerRoot: string): Promise<string> {\n  return await replaceAsync(\n    html,\n    /<link\\s+rel=\"stylesheet\"\\s+crossorigin\\s+href=\"([^\"]+)\">|<link\\s+rel=\"stylesheet\"\\s+href=\"([^\"]+)\">/g,\n    async (_match, crossoriginHref: string | undefined, href: string | undefined) => {\n      const assetPath = assetPathFromHref(crossoriginHref ?? href ?? \"\");\n      const css = await readFile(join(viewerRoot, assetPath), \"utf-8\");\n      return `<style>${css}</style>`;\n    },\n  );\n}\n```\n\n资料来源：[src/viewer/render-html.ts]()\n\n这确保了任务上下文的 HTML 导出可以在没有外部依赖的情况下正常工作。\n\n## 总结\n\nTask Context 系统是 Blueprint 项目架构的核心，它通过分层的信息组织（Brief + Group Docs）和稳定的文档模板，为 AI Agent 提供了可预测、可导航的架构记忆。Agent 应遵循\"先概览后深入\"的原则，优先使用搜索和章节跳转，而非盲目遍历整个代码库。\n\n---\n\n<a id='page-language-support'></a>\n\n## 语言支持与Tree-sitter集成\n\n### 相关页面\n\n相关主题：[Scan管道 - 文件清单与分析](#page-scan-pipeline)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/languages/registry.ts](https://github.com/engincankaya/blueprint/blob/main/src/languages/registry.ts)\n- [src/languages/types.ts](https://github.com/engincankaya/blueprint/blob/main/src/languages/types.ts)\n- [src/languages/typescript/normalizer.ts](https://github.com/engincankaya/blueprint/blob/main/src/languages/typescript/normalizer.ts)\n- [src/languages/python/normalizer.ts](https://github.com/engincankaya/blueprint/blob/main/src/languages/python/normalizer.ts)\n- [src/lib/tree-sitter-loader.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/tree-sitter-loader.ts)\n</details>\n\n# 语言支持与Tree-sitter集成\n\n## 概述\n\nBlueprint项目的语言支持系统基于Tree-sitter构建，为多种编程语言提供统一的代码解析、符号提取、导入/导出分析能力。该系统采用插件化架构，通过语言注册表（Language Registry）管理不同语言的分析器，并使用标准化的类型定义确保各语言模块之间的互操作性。\n\n## 核心架构\n\n### 系统组件关系\n\n```mermaid\ngraph TD\n    subgraph \"语言支持层\"\n        Registry[语言注册表<br/>registry.ts]\n        Types[类型定义<br/>types.ts]\n    end\n    \n    subgraph \"语言分析器\"\n        TSNormalizer[TypeScript Normalizer<br/>normalizer.ts]\n        PyNormalizer[Python Normalizer<br/>normalizer.ts]\n    end\n    \n    subgraph \"基础设施\"\n        Loader[Tree-sitter加载器<br/>tree-sitter-loader.ts]\n        Scanner[文件扫描器<br/>scan-file-inventory-builder.ts]\n        Analyzer[代码分析引擎<br/>scan-code-analysis-engine.ts]\n    end\n    \n    Registry --> TSNormalizer\n    Registry --> PyNormalizer\n    Loader --> Registry\n    Scanner --> Registry\n    Analyzer --> Registry\n    Analyzer --> Loader\n```\n\n### 语言注册表机制\n\n语言注册表（`src/languages/registry.ts`）是整个语言支持系统的核心枢纽，负责：\n\n- 注册各语言对应的Tree-sitter语法分析器实例\n- 管理语言与文件扩展名的映射关系\n- 提供语言特定配置的查询接口\n- 支持运行时语言模块的动态加载\n\n```mermaid\ngraph LR\n    A[文件扫描] --> B{识别扩展名}\n    B --> C[查询注册表]\n    C --> D{语言已注册?}\n    D -->|是| E[返回分析器]\n    D -->|否| F[加载对应语言模块]\n    F --> E\n```\n\n## 类型系统\n\n类型定义文件（`src/languages/types.ts`）为整个语言分析管道提供统一的数据模型：\n\n### 关键类型\n\n| 类型名称 | 用途 | 包含字段 |\n|---------|------|---------|\n| `FileInventory` | 文件清单元数据 | `rootPath`, `files[]`, `summary` |\n| `AnalysisFacts` | 代码分析结果 | `symbols{}`, `imports[]`, `exports[]` |\n| `ImportInfo` | 导入信息 | `rawSpecifier`, `kind`, `importedSymbols[]` |\n| `ExportInfo` | 导出信息 | 依赖具体语言语义 |\n| `SymbolInfo` | 符号信息 | `name`, `type`, `location` |\n\n### FileInventory结构\n\n```typescript\ninterface FileInventory {\n  rootPath: string;           // 项目根路径\n  files: FileEntry[];         // 所有文件条目\n  summary: {\n    totalFiles: number;       // 总文件数\n    parseableFiles: number;   // 可解析文件数\n    metadataOnlyFiles: number; // 仅元数据文件数\n  };\n}\n```\n\n## Tree-sitter集成\n\n### 加载器机制\n\nTree-sitter加载器（`src/lib/tree-sitter-loader.ts`）负责：\n\n- 初始化Tree-sitter语言包\n- 管理语法树缓存\n- 处理跨语言的解析错误\n- 提供异步解析接口\n\n### 解析流程\n\n```mermaid\nsequenceDiagram\n    participant 调用方\n    participant Loader as Tree-sitter加载器\n    participant Parser as Tree-sitter解析器\n    participant Normalizer as 语言标准化器\n    \n    调用方->>Loader: 请求解析文件\n    Loader->>Parser: 创建解析实例\n    Parser->>Parser: 执行语法解析\n    Parser-->>Loader: 返回SyntaxNode树\n    Loader-->>调用方: 提供解析结果\n    调用方->>Normalizer: 提取语义信息\n    Normalizer-->>调用方: 返回ImportInfo/ExportInfo\n```\n\n## Python语言分析\n\nPython语言标准化器（`src/languages/python/normalizer.ts`）处理Python特有的代码结构：\n\n### 导入分析\n\nPython的`import`语句解析需要处理多种语法变体：\n\n```mermaid\ngraph TD\n    A[import语句] --> B{import类型}\n    B -->|import x| C[单模块导入]\n    B -->|import x as y| D[别名导入]\n    B -->|from x import y| E[从模块导入]\n    B -->|from x import *| F[通配符导入]\n    \n    C --> G[符号: x]\n    D --> H[符号: y]\n    E --> I[符号: y]\n    F --> J[符号: *]\n```\n\n### 导出分析\n\nPython没有显式的`export`关键字，系统通过以下规则推断导出：\n\n1. 模块级公共名称（不以`_`开头）\n2. `__all__`列表中定义的名称\n3. 装饰器标记的公共函数和类\n\n资料来源：[src/languages/python/normalizer.ts:70-90]()\n\n```typescript\n// 公共名称判断逻辑\nif (name && !name.startsWith(\"_\")) {\n  publicNames.push(name);\n}\n```\n\n### AST节点处理\n\n标准化器遍历语法树时处理以下节点类型：\n\n| 节点类型 | 处理方式 |\n|---------|---------|\n| `import_statement` | 提取所有导入符号 |\n| `import_from_statement` | 解析`from ... import`结构 |\n| `dotted_name` | 收集点分名称组件 |\n| `aliased_import` | 记录别名映射 |\n| `wildcard_import` | 记录通配符导入 |\n| `decorated_definition` | 处理带装饰器的定义 |\n\n## TypeScript语言分析\n\nTypeScript标准化器（`src/languages/typescript/normalizer.ts`）处理TypeScript/JavaScript的代码结构：\n\n### 符号提取\n\n- 解析函数定义、类定义、接口定义\n- 提取类型参数和访问修饰符\n- 处理命名空间和模块声明\n\n### 导入/导出处理\n\n- `import`声明的标准解析\n- `export`声明的类型区分\n- `export =`和`export default`的兼容性处理\n- 命名空间导入的别名处理\n\n## 文件分类系统\n\nBlueprint通过文件扫描器（`src/tools/scan/scan-file-inventory-builder.ts`）对项目文件进行分类：\n\n### 分类规则\n\n| 分类 | 判断条件 |\n|-----|---------|\n| `test` | 文件名包含`.test.`, `.spec.`, `__tests__`目录, `test/`目录 |\n| `lockfile` | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Cargo.lock` |\n| `config` | `.gitignore`, `package.json`, `tsconfig.json`, `.config.ts/.js` |\n| `documentation` | `docs/`目录, `README.md`, `.md`文件 |\n| `script` | `scripts/`目录, `.sh`文件, shell语言 |\n| `asset` | `assets/`, `public/`目录, html/css/svg文件 |\n| `generated` | `generated/`, `__generated__/`目录 |\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts:20-70]()\n\n### 文件角色标注\n\n根据文件在项目中的位置和用途，系统为每个文件分配角色标签：\n\n- `core`: 核心业务逻辑\n- `interface`: 接口定义\n- `implementation`: 具体实现\n- `test`: 测试代码\n- `config`: 配置文件\n- `utility`: 工具函数\n- `unknown`: 未能识别的角色\n\n## 分析结果验证\n\n代码分析引擎（`src/tools/scan/scan-code-analysis-engine.ts`）生成的分析结果包含验证信息：\n\n```typescript\ninterface Validation {\n  isComplete: boolean;           // 分析是否完整\n  inventoryFiles: number;       // 清单文件数\n  parseableFiles: number;        // 可解析文件数\n  parsedFiles: number;           // 实际解析文件数\n  metadataOnlyFiles: number;    // 仅元数据文件数\n  skippedMetadataOnlyFiles: number; // 跳过的元数据文件\n  parseErrors: number;           // 解析错误数\n  unaccountedFiles: string[];    // 未纳入分析的文件\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts:30-45]()\n\n## 扩展语言支持\n\n### 添加新语言步骤\n\n1. 在`src/languages/`下创建`<language>/normalizer.ts`\n2. 实现`extractImports`和`extractExports`函数\n3. 在注册表中注册新的语言模块\n4. 添加对应的文件扩展名映射\n5. 编写测试用例验证解析正确性\n\n### 语言配置接口\n\n```typescript\ninterface LanguageConfig {\n  id: string;              // 语言标识符\n  name: string;           // 显示名称\n  extensions: string[];   // 文件扩展名\n  treeSitterLanguage: string;  // Tree-sitter语言包名\n  normalizer: Normalizer;  // 标准化器实例\n}\n```\n\n## 技术限制与注意事项\n\n### 当前限制\n\n- Tree-sitter解析依赖于预编译的语言包，加载大型项目时可能有内存压力\n- Python的动态特性（如`exec`、`__getattr__`）无法静态分析\n- TypeScript的类型系统部分特性（如条件类型）在编译时可能无法完全解析\n\n### 最佳实践\n\n1. 保持Tree-sitter语言包版本与主包一致\n2. 对于不支持的文件类型，系统会自动降级为仅元数据模式\n3. 定期更新语言解析器以支持新的语法特性\n\n## 相关文件索引\n\n| 文件路径 | 功能描述 |\n|---------|---------|\n| `src/languages/registry.ts` | 语言注册与管理中心 |\n| `src/languages/types.ts` | 统一类型定义 |\n| `src/languages/python/normalizer.ts` | Python代码标准化 |\n| `src/languages/typescript/normalizer.ts` | TypeScript代码标准化 |\n| `src/lib/tree-sitter-loader.ts` | Tree-sitter运行时加载 |\n| `src/tools/scan/scan-file-inventory-builder.ts` | 文件扫描与分类 |\n| `src/tools/scan/scan-code-analysis-engine.ts` | 代码分析引擎 |\n\n---\n\n<a id='page-data-storage'></a>\n\n## 数据存储与路径管理\n\n### 相关页面\n\n相关主题：[Scan管道 - 文件清单与分析](#page-scan-pipeline), [Compose管道 - 最终输出生成](#page-compose-pipeline)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/lib/blueprint-paths.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/blueprint-paths.ts)\n- [src/lib/artifact-store.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/artifact-store.ts)\n- [src/lib/group-docs.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/group-docs.ts)\n- [src/lib/brief-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/brief-builder.ts)\n- [src/tools/compose/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)\n- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n</details>\n\n# 数据存储与路径管理\n\n## 概述\n\nBlueprint 项目的数据存储与路径管理系统是整个架构的核心基础设施，负责管理项目内存文件的生成、存储、读取和维护。该系统采用本地文件系统作为默认存储后端，将架构记忆以结构化 JSON 和 Markdown 文件的形式持久化到用户项目的 `.blueprint/` 目录中。\n\nBlueprint 的存储架构遵循以下核心原则：\n\n- **本地优先**：所有数据默认存储在用户项目的 `.blueprint/` 目录中\n- **确定性维护**：使用 Tree-sitter 分析和文件系统哈希快照确保增量更新的准确性\n- **源码头信任**：源码是最终事实依据，Blueprint 文档仅为方向性参考\n- **工具驱动**：不直接编辑生成的 JSON 文件，通过 MCP 工具进行确定性维护\n\n资料来源：[README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)\n\n## 核心组件\n\n### BlueprintPaths 路径管理模块\n\n`BlueprintPaths` 模块负责定义和管理 Blueprint 相关的所有文件系统路径。该模块封装了路径解析逻辑，为其他模块提供统一的路径访问接口。\n\n| 属性 | 说明 | 默认值 |\n|------|------|--------|\n| `projectRoot` | 用户项目根目录 | 当前工作目录 |\n| `blueprintDir` | Blueprint 内存目录 | `.blueprint/` |\n| `briefPath` | 项目概述文档路径 | `.blueprint/brief.md` |\n| `groupsDir` | 分组文档目录 | `.blueprint/groups/` |\n| `outputJsonPath` | 结构化输出 JSON 路径 | `.blueprint/blueprint-output.json` |\n| `indexHtmlPath` | 静态查看器 HTML 路径 | `.blueprint/index.html` |\n| `refreshScanJsonPath` | 刷新扫描哈希快照路径 | `.blueprint/refresh-scan.json` |\n\n路径模块还负责生成 Agent 说明文件路径，该文件包含 Blueprint MCP 的使用指引。\n\n资料来源：[src/lib/blueprint-paths.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/blueprint-paths.ts)\n\n### ArtifactStore 工件存储\n\n`ArtifactStore` 是 Blueprint 的核心数据存储抽象层，提供类型安全的工件存取接口。每个工件（Artifact）都具有唯一的标识符，支持版本追踪和类型验证。\n\n```typescript\ninterface Artifact {\n  id: string;\n  type: string;\n  data: unknown;\n  metadata: {\n    createdAt: number;\n    updatedAt: number;\n    version: number;\n  };\n}\n```\n\n#### 存储操作接口\n\n| 方法 | 功能 | 返回类型 |\n|------|------|----------|\n| `store(artifact)` | 存储新工件 | `string` (工件ID) |\n| `get(id)` | 根据ID获取工件 | `Artifact \\| undefined` |\n| `getTyped(id, type, expectedType)` | 类型安全获取 | `T \\| undefined` |\n| `update(id, data)` | 更新现有工件 | `boolean` |\n| `delete(id)` | 删除工件 | `boolean` |\n| `list()` | 列出所有工件 | `Artifact[]` |\n| `clear()` | 清空存储 | `void` |\n\n`getTyped` 方法是类型安全访问的核心，它在返回数据前验证工件类型是否符合预期。如果类型不匹配，返回 `undefined` 并记录警告。\n\n资料来源：[src/lib/artifact-store.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/artifact-store.ts)\n\n### FileInventory 文件清单\n\n`FileInventory` 是扫描阶段生成的文件清单数据结构，包含项目的完整文件列表和元数据。\n\n```typescript\ninterface FileInventory {\n  rootPath: string;\n  files: FileEntry[];\n  summary: {\n    totalFiles: number;\n    parseableFiles: number;\n    metadataOnlyFiles: number;\n  };\n}\n\ninterface FileEntry {\n  absolutePath: string;\n  relativePath: string;\n  language: string;\n  analysisLevel: 'parseable' | 'metadata-only';\n  size: number;\n  category?: FileCategory;\n}\n```\n\n文件分类通过 `FileCategory` 枚举区分：\n\n| 分类 | 说明 | 判定规则 |\n|------|------|----------|\n| `source` | 源代码文件 | `.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.go`, `.rs`, `.java` |\n| `test` | 测试文件 | `.test.ts`, `.spec.ts`, `test/`, `tests/` 目录 |\n| `config` | 配置文件 | `package.json`, `tsconfig.json`, `.config.js` |\n| `documentation` | 文档文件 | `readme.md`, `.md`, `docs/` 目录 |\n| `script` | 脚本文件 | `.sh`, `scripts/` 目录 |\n| `asset` | 静态资源 | `.svg`, `.css`, `assets/`, `public/` 目录 |\n| `lockfile` | 锁文件 | `package-lock.json`, `yarn.lock`, `Cargo.lock` |\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n\n### GroupDocs 分组文档管理\n\n`GroupDocs` 模块负责管理 `.blueprint/groups/*.md` 中的分组文档。这些 Markdown 文件记录了每个架构分组的详细信息，包括核心流程、契约、不变式和测试指南等。\n\n分组文档模板结构：\n\n| 章节 | 说明 | 必填 |\n|------|------|------|\n| `Snapshot` | 快速概览和摘要 | 建议 |\n| `Responsibilities` | 所有权和范围定义 | 建议 |\n| `Core Flow` | 运行时行为和数据流 | 建议 |\n| `Contracts & Invariants` | 必须保持的行为契约 | 建议 |\n| `Key Files` | 指向主要源文件 | 建议 |\n| `Change Guide` | 变更协同文件列表 | 可选 |\n| `Pitfalls` | 已知风险和常见错误 | 可选 |\n| `Tests` | 相关验证测试 | 可选 |\n| `Debugging` | 故障排查提示 | 可选 |\n| `Extension / Open Questions` | 不确定性和已知缺口 | 可选 |\n\n资料来源：[src/lib/group-docs.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/group-docs.ts)\n\n### BriefBuilder 概述文档构建\n\n`BriefBuilder` 负责生成 `.blueprint/brief.md` 项目概述文档。该文档提供项目的全局架构视图，包括：\n\n- 项目概述和架构分组成员\n- 路由提示和入口点\n- 关键文件列表\n- 分组文档路径引用\n\nBrief 文档是 Agent 开始探索代码库时的首要参考资源，应当保持简洁且与当前 Blueprint 输出同步。\n\n资料来源：[src/lib/brief-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/brief-builder.ts)\n\n## 数据流架构\n\n### 整体工作流\n\n```mermaid\ngraph TD\n    A[用户项目] --> B[blueprint.scan]\n    B --> C[FileInventory]\n    C --> D[blueprint.group]\n    D --> E[GroupingResult]\n    E --> F[blueprint.compose]\n    F --> G[BlueprintOutput]\n    G --> H[.blueprint/brief.md]\n    G --> I[.blueprint/groups/*.md]\n    G --> J[blueprint-output.json]\n    J --> K[blueprint open]\n    K --> L[.blueprint/index.html]\n    \n    M[源码变更] --> N[blueprint.refresh]\n    N --> O[refresh-scan.json]\n    O --> P{哈希对比}\n    P -->|检测到变更| Q[更新受影响分组]\n    P -->|无变更| R[跳过]\n```\n\n### 扫描与代码分析流程\n\n```mermaid\ngraph LR\n    A[文件系统] -->|readFile| B[scan-code-analysis-engine]\n    B --> C{语言类型}\n    C -->|TypeScript/JS| D[Tree-sitter Parser]\n    C -->|Python| E[Tree-sitter Parser]\n    C -->|Go| F[Tree-sitter Parser]\n    C -->|Rust| G[Tree-sitter Parser]\n    C -->|Java| H[Tree-sitter Parser]\n    C -->|其他| I[元数据仅存]\n    \n    D --> J[AnalysisFacts]\n    E --> J\n    F --> J\n    G --> J\n    H --> J\n    I --> J\n    \n    J --> K[符号表]\n    J --> L[导入关系]\n    J --> M[依赖图]\n    J --> N[解析错误]\n```\n\n### Compose 阶段数据转换\n\n```mermaid\ngraph TD\n    A[GroupingResult] --> B[ComposeTool]\n    C[FileInventory] --> B\n    D[AnalysisFacts] --> B\n    \n    B --> E[ComposeOutputBuilder]\n    E --> F[ComposeArtifactWriter]\n    F --> G[blueprint.v1 结构]\n    \n    G --> H[brief.md]\n    G --> I[groups/*.md]\n    G --> J[blueprint-output.json]\n    G --> K[AGENTS.md 补丁]\n```\n\n`ComposeTool` 协调多个构建器完成最终输出：\n\n1. **ComposeOutputBuilder**：构建前端可用的 Blueprint JSON 结构\n2. **ComposeArtifactWriter**：将构建结果写入文件系统\n3. **ComposeEntrypointDetector**：检测项目入口点并关联\n\n资料来源：[src/tools/compose/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)\n\n## AnalysisFacts 数据结构\n\n`AnalysisFacts` 是代码分析阶段生成的核心数据结构，汇总了所有代码解析结果。\n\n```typescript\ninterface AnalysisFacts {\n  inventoryArtifactId: string;\n  rootPath: string;\n  files: Record<string, FileAnalysis>;\n  symbols: Record<string, SymbolInfo>;\n  imports: ImportEntry[];\n  exports: ExportEntry[];\n  dependencies: DependencyEdge[];\n  unresolvedImports: UnresolvedImport[];\n  parseErrors: ParseError[];\n  summary: AnalysisSummary;\n  validation: ValidationState;\n}\n```\n\n#### ValidationState 验证状态\n\n| 字段 | 说明 | 用途 |\n|------|------|------|\n| `isComplete` | 分析是否完成 | 状态标志 |\n| `inventoryFiles` | 清单文件总数 | 完整性检查 |\n| `parseableFiles` | 可解析文件数 | 解析覆盖率 |\n| `parsedFiles` | 实际解析文件数 | 进度追踪 |\n| `metadataOnlyFiles` | 元数据文件数 | 未分析文件 |\n| `skippedMetadataOnlyFiles` | 跳过的元数据文件 | 分析决策记录 |\n| `parseErrors` | 解析错误数 | 质量指标 |\n| `unaccountedFiles` | 未归属文件列表 | 完整性审计 |\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n\n## 存储路径配置\n\n### 目录结构\n\n```\nproject-root/\n├── .blueprint/\n│   ├── brief.md                    # 项目概述文档\n│   ├── blueprint-output.json       # 结构化输出数据\n│   ├── refresh-scan.json           # 文件系统哈希快照\n│   ├── index.html                  # 静态查看器\n│   └── groups/\n│       ├── frontend.md             # 前端分组文档\n│       ├── backend.md              # 后端分组文档\n│       └── shared.md               # 共享模块文档\n└── src/                            # 用户源代码\n```\n\n### 路径解析优先级\n\n```mermaid\ngraph TD\n    A[路径请求] --> B{存在自定义配置?}\n    B -->|是| C[使用配置的路径]\n    B -->|否| D{环境变量 BLUEPRINT_DIR?}\n    D -->|是| E[使用环境变量值]\n    D -->|否| F{命令行参数 --dir?}\n    F -->|是| G[使用命令行值]\n    F -->|否| H[使用默认 .blueprint/]\n    \n    C --> Z[解析完成]\n    E --> Z\n    G --> Z\n    H --> Z\n```\n\n## MCP 工具集成\n\nBlueprint MCP 提供四个主要工具用于存储和路径管理：\n\n| 工具 | 用途 | 影响文件 |\n|------|------|----------|\n| `blueprint.scan` | 构建文件清单和代码分析 | 生成扫描缓存 |\n| `blueprint.group` | 准备或应用语义分组 | 更新分组状态 |\n| `blueprint.compose` | 写入最终 Blueprint 输出 | `brief.md`, `groups/*.md`, `blueprint-output.json` |\n| `blueprint.refresh` | 从当前文件系统快照刷新 | 更新哈希快照 |\n| `blueprint.group.update` | 分配未分配文件 | 更新分组配置 |\n\n### 工具调用流程\n\n```mermaid\nsequenceDiagram\n    participant U as 用户/Agent\n    participant M as MCP Server\n    participant A as ArtifactStore\n    participant F as 文件系统\n\n    U->>M: blueprint.scan\n    M->>F: 扫描项目文件\n    F-->>M: FileInventory\n    M->>A: store(FileInventory)\n    A-->>M: artifactId\n    \n    U->>M: blueprint.group with mode: prepare\n    M->>A: get(inventoryArtifactId)\n    A-->>M: FileInventory\n    M->>F: 分析分组建议\n    F-->>M: GroupingResult\n    M->>A: store(GroupingResult)\n    \n    U->>M: blueprint.compose\n    M->>A: get(groupingArtifactId)\n    A-->>M: GroupingResult\n    M->>F: 写入 .blueprint/ 目录\n    F-->>M: 写入完成\n```\n\n## 静态查看器渲染\n\nBlueprint 的静态查看器使用嵌入式数据渲染模式：\n\n```mermaid\ngraph TD\n    A[blueprint-output.json] --> B[Renderer]\n    C[brief.md] --> B\n    D[groups/*.md] --> B\n    B --> E[index.html]\n    E --> F[浏览器]\n    F --> G[显示架构视图]\n```\n\n查看器特点：\n\n- **独立 HTML**：无需 HTTP 服务器即可查看\n- **嵌入式数据**：JSON 数据直接嵌入 HTML 文件\n- **自包含**：所有样式和脚本内联\n- **无外部依赖**：不依赖网络资源\n\n资料来源：[README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)\n\n## 维护与更新策略\n\n### 确定性刷新机制\n\nBlueprint 使用文件系统哈希快照进行确定性刷新：\n\n1. 扫描阶段计算所有源文件的哈希值\n2. 将哈希快照存储在 `refresh-scan.json`\n3. 刷新时重新计算哈希并对比\n4. 仅更新发生变化的文件关联\n\n```mermaid\ngraph TD\n    A[refresh-scan.json] --> B[当前哈希计算]\n    B --> C{与快照对比}\n    C -->|有变更| D[识别受影响分组]\n    C -->|无变更| E[跳过更新]\n    D --> F[blueprint.group.update]\n    F --> G[更新分组关联]\n    G --> H[写入新快照]\n```\n\n### 文件分类变更处理\n\n当文件移动、删除或新增时：\n\n| 变更类型 | 处理方式 | 触发操作 |\n|----------|----------|----------|\n| 新增文件 | 检查分组归属 | `blueprint.group.update` |\n| 删除文件 | 从分组移除 | 自动清理 |\n| 移动文件 | 更新相对路径 | 重新分析关联 |\n| 重命名文件 | 视为删除+新增 | 完整重新关联 |\n\n### 分组文档同步\n\n分组文档应随源码变更同步更新：\n\n- 仅在架构契约、契约、不变式、陷阱或测试指导变更时更新\n- 保持 `.blueprint/brief.md` 与当前 Blueprint 输出同步\n- 不要将完整源码详情复制到 Markdown 文档\n- 记录稳定的架构事实、契约和测试指导\n\n## 最佳实践\n\n### 路径使用规范\n\n1. **始终使用 BlueprintPaths 模块**：不要硬编码路径字符串\n2. **类型安全访问**：优先使用 `getTyped()` 方法\n3. **验证工件存在**：在访问前检查 `undefined` 情况\n\n### 数据一致性维护\n\n```mermaid\ngraph LR\n    A[源码变更] -->|blueprint.refresh| B{检测变更}\n    B -->|分组结构变更| C[更新 groups/*.md]\n    B -->|文档结构变更| D[更新 brief.md]\n    B -->|两者都变| E[更新两者]\n    B -->|无变更| F[无需操作]\n```\n\n### 避免的操作\n\n- 手动编辑 `blueprint-output.json`\n- 跳过 `blueprint.refresh` 直接修改源码\n- 将大量源码细节复制到分组文档\n- 在分组文档与源码冲突时信任文档\n\n## 总结\n\nBlueprint 的数据存储与路径管理系统通过模块化设计和确定性工具链，实现了架构记忆的可靠管理和自动同步。核心组件包括：\n\n- **BlueprintPaths**：提供统一的路径解析接口\n- **ArtifactStore**：实现类型安全的工件存储抽象\n- **FileInventory**：维护项目的完整文件清单\n- **GroupDocs**：管理分组 Markdown 文档\n- **BriefBuilder**：构建项目概述文档\n\n整个系统以源码为最终事实依据，通过 MCP 工具驱动进行确定性维护，确保架构文档始终反映当前代码库的真实状态。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：engincankaya/blueprint\n\n摘要：发现 6 个潜在踩坑项，其中 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:1230090802 | https://github.com/engincankaya/blueprint | 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:1230090802 | https://github.com/engincankaya/blueprint | 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:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium\n\n## 5. 维护坑 · 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:1230090802 | https://github.com/engincankaya/blueprint | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | release_recency=unknown\n\n<!-- canonical_name: engincankaya/blueprint; human_manual_source: deepwiki_human_wiki -->\n",
      "markdown_key": "blueprint",
      "pages": "draft",
      "source_refs": [
        {
          "evidence_id": "github_repo:1230090802",
          "kind": "repo",
          "supports_claim_ids": [
            "claim_identity",
            "claim_distribution",
            "claim_capability"
          ],
          "url": "https://github.com/engincankaya/blueprint"
        },
        {
          "evidence_id": "art_647f8d5f3c174aef82a7cb067ad098a7",
          "kind": "docs",
          "supports_claim_ids": [
            "claim_identity",
            "claim_distribution",
            "claim_capability"
          ],
          "url": "https://github.com/engincankaya/blueprint#readme"
        }
      ],
      "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
      "title": "blueprint 说明书",
      "toc": [
        "https://github.com/engincankaya/blueprint 项目说明书",
        "目录",
        "项目概述",
        "项目简介",
        "核心功能",
        "架构设计",
        "数据模型",
        "工作流程",
        "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": true,
    "repo_commit": "0a360b93c955d8ddb9769ad173aaf642603e9196",
    "repo_inspection_error": null,
    "repo_inspection_files": [
      "package.json",
      "README.md",
      "docs/agents.md",
      "src/index.ts",
      "src/types.ts",
      "src/cli/index.ts",
      "src/services/blueprint-group-service.ts",
      "src/services/blueprint-viewer-service.ts",
      "src/languages/registry.ts",
      "src/languages/types.ts",
      "src/tools/task-context.ts",
      "src/tools/init-tools.ts",
      "src/lib/brief-builder.ts",
      "src/lib/agent-instructions.ts",
      "src/lib/blueprint-paths.ts",
      "src/lib/hashing.ts",
      "src/lib/group-note-template.ts",
      "src/lib/tree-sitter-loader.ts",
      "src/lib/group-docs.ts",
      "src/lib/artifact-store.ts",
      "src/viewer/render-html.ts",
      "src/languages/rust/normalizer.ts",
      "src/languages/typescript/normalizer.ts",
      "src/languages/python/normalizer.ts",
      "src/languages/java/normalizer.ts",
      "src/languages/go/normalizer.ts",
      "src/tools/group-update/group-update.types.ts",
      "src/tools/group-update/group-update-applier.ts",
      "src/tools/group-update/index.ts",
      "src/tools/group-update/group-update-validator.ts",
      "src/tools/refresh/refresh.types.ts",
      "src/tools/refresh/index.ts",
      "src/tools/group/grouping-plan-validator.ts",
      "src/tools/group/grouping.types.ts",
      "src/tools/group/grouping-assignment-engine.ts",
      "src/tools/group/index.ts",
      "src/tools/scan/scan-file-inventory-builder.ts",
      "src/tools/scan/scan-code-analysis-engine.ts",
      "src/tools/scan/index.ts",
      "src/tools/compose/compose-entrypoint-detector.ts"
    ],
    "repo_inspection_verified": true,
    "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": "# blueprint-mcp-server - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 blueprint-mcp-server 编译的 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 blueprint-mcp-server` 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\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）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`AGENTS.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\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_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0005` 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- 文件总数：82\n- 重要文件覆盖：17/82\n- 证据索引条目：17\n- 角色 / Skill 条目：5\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请基于 blueprint-mcp-server 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 blueprint-mcp-server 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 blueprint-mcp-server 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 5 个角色 / Skill / 项目文档条目。\n\n- **Blueprint MCP Agent Rules**（project_doc）：Blueprint MCP stores local architecture memory in .blueprint/ . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/agents.md`\n- **AGENTS.md**（project_doc）：This project uses Blueprint memory. Blueprint files are the first orientation layer for every task, but they are not the source of truth. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`AGENTS.md`\n- **Blueprint MCP Server**（project_doc）：Blueprint is an MCP server that gives coding agents a durable project memory layer. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **1- Frontend Integration Todo**（project_doc）：Bu projeye Next.js kullanmadan hafif bir frontend eklemek. Frontend, mevcut MCP/HTTP server icinden statik dosya olarak servis edilecek ve Blueprint mimarisini gorsel olarak incelemek icin kullanilacak. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`todos.md`\n- **1- MCP Native Static Viewer Refactor**（project_doc）：1- MCP Native Static Viewer Refactor 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`todos_120526.md`\n\n## 证据索引\n\n- 共索引 17 条证据。\n\n- **Blueprint MCP Agent Rules**（documentation）：Blueprint MCP stores local architecture memory in .blueprint/ . 证据：`docs/agents.md`\n- **AGENTS.md**（documentation）：This project uses Blueprint memory. Blueprint files are the first orientation layer for every task, but they are not the source of truth. 证据：`AGENTS.md`\n- **Blueprint MCP Server**（documentation）：Blueprint is an MCP server that gives coding agents a durable project memory layer. 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"blueprint-mcp-server\", \"version\": \"0.1.0\", \"description\": \"MCP server for architecture-aware Blueprint memory using Tree-sitter\", \"type\": \"module\", \"main\": \"dist/index.js\", \"bin\": { \"blueprint-mcp-server\": \"dist/index.js\", \"blueprint\": \"dist/cli/index.js\" }, \"files\": \"dist\", \"docs\", \"README.md\", \"LICENSE\" , \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/engincankaya/blueprint.git\" }, \"bugs\": { \"url\": \"https://github.com/engincankaya/blueprint/issues\" }, \"homepage\": \"https://github.com/engincankaya/blueprint readme\", \"keywords\": \"mcp\", \"model-context-protocol\", \"blueprint\", \"llm\", \"coding-agent\", \"tree-sitter\" , \"license\": \"MIT\", \"scripts\": { \"build\": \"npm run clean… 证据：`package.json`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **1- Frontend Integration Todo**（documentation）：Bu projeye Next.js kullanmadan hafif bir frontend eklemek. Frontend, mevcut MCP/HTTP server icinden statik dosya olarak servis edilecek ve Blueprint mimarisini gorsel olarak incelemek icin kullanilacak. 证据：`todos.md`\n- **1- MCP Native Static Viewer Refactor**（documentation）：1- MCP Native Static Viewer Refactor 证据：`todos_120526.md`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"useDefineForClassFields\": true, \"lib\": \"DOM\", \"DOM.Iterable\", \"ES2022\" , \"allowJs\": false, \"skipLibCheck\": true, \"esModuleInterop\": true, \"allowSyntheticDefaultImports\": true, \"strict\": true, \"forceConsistentCasingInFileNames\": true, \"module\": \"ESNext\", \"moduleResolution\": \"Bundler\", \"baseUrl\": \".\", \"paths\": { \"@/ \": \"src/ \" }, \"resolveJsonModule\": true, \"isolatedModules\": true, \"noEmit\": true, \"jsx\": \"react-jsx\", \"types\": \"vite/client\" }, \"include\": \"src\" } 证据：`frontend/tsconfig.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"Node16\", \"moduleResolution\": \"Node16\", \"outDir\": \"./dist\", \"rootDir\": \"./src\", \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"forceConsistentCasingInFileNames\": true, \"resolveJsonModule\": true, \"declaration\": true, \"sourceMap\": true, \"isolatedModules\": true }, \"include\": \"src/ / \" , \"exclude\": \"node modules\", \"dist\", \" / .test.ts\", \" / .spec.ts\" } 证据：`tsconfig.json`\n- **Index**（source_file）：Blueprint 证据：`frontend/index.html`\n- **Postcss.Config**（source_file）：module.exports = { plugins: { tailwindcss: { config: \"./frontend/tailwind.config.cjs\" }, autoprefixer: {}, }, }; 证据：`frontend/postcss.config.cjs`\n- **Tailwind.Config**（source_file）：module.exports = { darkMode: \"class\", content: { relative: true, files: \"./index.html\", \"./src/ / .{ts,tsx}\" , }, safelist: \"border-emerald-800/60\", \"bg-emerald-950/40\", \"text-emerald-200\", \"border-amber-500\", \"bg-amber-900/70\", \"text-amber-100\", \"ring-amber-500/50\", \"shadow-amber-900/40\", \"border-blue-800/60\", \"bg-blue-950/40\", \"text-blue-200\", , theme: { extend: { fontFamily: { mono: \"var --font-mono \", \"monospace\" , }, }, }, plugins: , }; 证据：`frontend/tailwind.config.cjs`\n- **Vite.Config**（source_file）：import { defineConfig } from \"vite\"; import react from \"@vitejs/plugin-react\"; import { resolve } from \"node:path\"; 证据：`frontend/vite.config.ts`\n- **!/usr/bin/env node**（source_file）：import { readFileSync, writeFileSync } from \"node:fs\"; import { join, dirname } from \"node:path\"; import { fileURLToPath } from \"node:url\"; 证据：`scripts/add-shebang.js`\n- **!/usr/bin/env node**（source_file）：/ Copies only the needed Tree-sitter WASM grammars from tree-sitter-wasms into dist/grammars/ for inclusion in the npm package. / 证据：`scripts/copy-grammars.js`\n- **Index**（source_file）：import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\"; import { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\"; import { z } from \"zod\"; import { ArtifactStore } from \"./lib/artifact-store.js\"; import { initTools } from \"./tools/init-tools.js\"; import { handleTaskContext } from \"./tools/task-context.js\"; 证据：`src/index.ts`\n- **Types**（source_file）：/ MCP tool handler return type. Must include index signature for compatibility with CallToolResult. / export interface ToolResult { key: string : unknown; content: Array ; structuredContent?: Record ; } 证据：`src/types.ts`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/agents.md`, `AGENTS.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/agents.md`, `AGENTS.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n  - source_paths: README.md, AGENTS.md, src/index.ts\n- **系统架构**：importance `high`\n  - source_paths: src/index.ts, src/tools/init-tools.ts, src/types.ts, src/lib/artifact-store.ts\n- **工具系统概览**：importance `high`\n  - source_paths: src/index.ts, src/tools/init-tools.ts, src/types.ts\n- **Scan管道 - 文件清单与分析**：importance `high`\n  - source_paths: src/tools/scan/index.ts, src/tools/scan/scan-file-inventory-builder.ts, src/tools/scan/scan-code-analysis-engine.ts\n- **Group管道 - 语义分组**：importance `high`\n  - source_paths: src/tools/group/index.ts, src/tools/group/grouping-assignment-engine.ts, src/tools/group/grouping-plan-validator.ts, src/tools/group/grouping.types.ts\n- **Compose管道 - 最终输出生成**：importance `high`\n  - source_paths: src/tools/compose/index.ts, src/tools/compose/compose-output-builder.ts, src/tools/compose/compose-artifact-writer.ts, src/tools/compose/compose.types.ts\n- **Refresh系统 - 状态刷新与维护**：importance `high`\n  - source_paths: src/tools/refresh/index.ts, src/tools/refresh/refresh.types.ts, src/tools/group-update/index.ts\n- **Task Context - 任务上下文构建**：importance `medium`\n  - source_paths: src/tools/task-context.ts, src/lib/brief-builder.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `0a360b93c955d8ddb9769ad173aaf642603e9196`\n- inspected_files: `package.json`, `README.md`, `docs/agents.md`, `src/index.ts`, `src/types.ts`, `src/cli/index.ts`, `src/services/blueprint-group-service.ts`, `src/services/blueprint-viewer-service.ts`, `src/languages/registry.ts`, `src/languages/types.ts`, `src/tools/task-context.ts`, `src/tools/init-tools.ts`, `src/lib/brief-builder.ts`, `src/lib/agent-instructions.ts`, `src/lib/blueprint-paths.ts`, `src/lib/hashing.ts`, `src/lib/group-note-template.ts`, `src/lib/tree-sitter-loader.ts`, `src/lib/group-docs.ts`, `src/lib/artifact-store.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1230090802 | https://github.com/engincankaya/blueprint | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
      "summary": "给宿主 AI 的上下文和工作边界。",
      "title": "AI Context Pack / 带给我的 AI"
    },
    "boundary_risk_card": {
      "asset_id": "boundary_risk_card",
      "filename": "BOUNDARY_RISK_CARD.md",
      "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：engincankaya/blueprint\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- issue/PR 响应质量未知（low）：用户无法判断遇到问题后是否有人维护。 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
      "summary": "安装、权限、验证和推荐前风险。",
      "title": "Boundary & Risk Card / 边界与风险卡"
    },
    "human_manual": {
      "asset_id": "human_manual",
      "filename": "HUMAN_MANUAL.md",
      "markdown": "# https://github.com/engincankaya/blueprint 项目说明书\n\n生成时间：2026-05-14 18:16:08 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [系统架构](#page-architecture)\n- [工具系统概览](#page-tool-system)\n- [Scan管道 - 文件清单与分析](#page-scan-pipeline)\n- [Group管道 - 语义分组](#page-group-pipeline)\n- [Compose管道 - 最终输出生成](#page-compose-pipeline)\n- [Refresh系统 - 状态刷新与维护](#page-refresh-system)\n- [Task Context - 任务上下文构建](#page-task-context)\n- [语言支持与Tree-sitter集成](#page-language-support)\n- [数据存储与路径管理](#page-data-storage)\n\n<a id='page-overview'></a>\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [工具系统概览](#page-tool-system)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)\n- [AGENTS.md](https://github.com/engincankaya/blueprint/blob/main/AGENTS.md)\n- [frontend/src/components/BlueprintApp.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/BlueprintApp.tsx)\n- [frontend/src/components/blueprint/GroupDetailPanel.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/blueprint/GroupDetailPanel.tsx)\n- [frontend/index.html](https://github.com/engincankaya/blueprint/blob/main/frontend/index.html)\n- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n- [src/viewer/render-html.ts](https://github.com/engincankaya/blueprint/blob/main/src/viewer/render-html.ts)\n- [src/tools/group/grouping-assignment-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping-assignment-engine.ts)\n- [todos_120526.md](https://github.com/engincankaya/blueprint/blob/main/todos_120526.md)\n</details>\n\n# 项目概述\n\n## 项目简介\n\nBlueprint 是一个面向开发者的项目结构分析和可视化工具，旨在帮助开发者快速理解代码库架构、文件关系和项目组织结构。该工具通过自动扫描源代码、构建文件清单、生成语义化分组和渲染可视化界面，为代码审查、架构重构和团队知识传递提供支持。\n\nBlueprint 的核心设计理念是 **\"Blueprint 是辅助层，源码是真相\"**。文档和蓝图文件仅用于方向指引，如果文档与源码存在冲突，应以源码为准。资料来源：[AGENTS.md]()\n\n## 核心功能\n\nBlueprint 提供以下核心功能：\n\n| 功能 | 说明 |\n|------|------|\n| 文件扫描 | 构建项目的完整文件清单，包含文件类型、语言、路径等元数据 |\n| 代码分析 | 基于 Tree-sitter 的深度符号分析，支持 TypeScript、Python、Go、Rust、Java |\n| 语义分组 | 根据文件角色和重要性自动将文件组织成逻辑分组 |\n| 可视化查看器 | 轻量级 React/Vite 静态 HTML 查看器，支持浏览器直接打开 |\n| Markdown 文档 | 生成架构组文档模板，包含核心流程、契约、不变量等 |\n\n资料来源：[README.md]()\n\n## 架构设计\n\n### 整体架构\n\nBlueprint 采用模块化设计，主要由扫描工具、分析引擎、分组引擎和可视化渲染器四大组件构成。\n\n```mermaid\ngraph TD\n    A[文件系统] --> B[文件扫描器<br/>scan-file-inventory-builder]\n    B --> C[文件清单<br/>FileInventory]\n    C --> D[代码分析引擎<br/>scan-code-analysis-engine]\n    D --> E[分析结果<br/>AnalysisFacts]\n    E --> F[分组引擎<br/>grouping-assignment-engine]\n    F --> G[蓝图输出<br/>blueprint-output.json]\n    G --> H[静态 HTML 渲染器<br/>render-html]\n    H --> I[viewer/index.html]\n    G --> J[.blueprint/groups/*.md]\n    J --> K[架构组文档]\n```\n\n### 工具集\n\nBlueprint 通过 MCP（Model Context Protocol）提供以下命令行工具：\n\n| 工具 | 用途 |\n|------|------|\n| `blueprint.scan` | 构建文件清单和代码分析产物 |\n| `blueprint.group` | 准备或应用语义化文件分组 |\n| `blueprint.compose` | 写入最终蓝图输出和 Markdown 笔记 |\n| `blueprint.refresh` | 从当前文件系统快照刷新蓝图状态 |\n| `blueprint.group.update` | 分配未分配的文件或管理空分组 |\n| `blueprint open` | 打开可视化查看器 |\n\n资料来源：[README.md]()\n\n## 数据模型\n\n### 文件清单结构\n\n文件扫描器生成的 `FileInventory` 包含以下核心字段：\n\n```typescript\ninterface FileInventory {\n  files: FileRecord[];        // 文件记录数组\n  summary: {\n    totalFiles: number;       // 总文件数\n    parseableFiles: number;   // 可解析文件数\n    metadataOnlyFiles: number; // 仅元数据文件数\n  };\n  rootPath: string;           // 项目根路径\n}\n```\n\n每个文件记录 `FileRecord` 包含路径、语言、分类、分析级别等属性。资料来源：[src/tools/scan/scan-file-inventory-builder.ts]()\n\n### 文件分类\n\nBlueprint 支持以下文件分类类型：\n\n| 分类 | 判断条件 |\n|------|----------|\n| `source` | 源代码文件（.ts, .tsx, .py, .go, .rs, .java 等） |\n| `test` | 测试文件（.spec.ts, .test.js, test/ 目录等） |\n| `config` | 配置文件（package.json, tsconfig.json, .config.js 等） |\n| `documentation` | 文档文件（.md, docs/ 目录） |\n| `script` | 脚本文件（.sh, scripts/ 目录） |\n| `asset` | 资源文件（.css, .svg, assets/, public/ 目录） |\n| `lockfile` | 锁文件（package-lock.json, yarn.lock 等） |\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts]()\n\n### 分析结果结构\n\n代码分析引擎输出的 `AnalysisFacts` 包含：\n\n```typescript\ninterface AnalysisFacts {\n  inventoryArtifactId: string;\n  rootPath: string;\n  files: {};                  // 按 fileId 索引的解析结果\n  symbols: {};                // 符号表\n  imports: Import[];          // 导入关系\n  exports: Export[];          // 导出关系\n  dependencies: Dependency[]; // 依赖关系\n  summary: {\n    totalFiles: number;\n    parseableFiles: number;\n    symbols: number;\n    imports: number;\n    exports: number;\n    dependencies: number;\n    parseErrors: number;\n  };\n  validation: AnalysisValidation; // 分析验证状态\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts]()\n\n## 工作流程\n\n### 初始工作流\n\n首次使用 Blueprint 时，按以下顺序执行工具：\n\n```mermaid\ngraph LR\n    A[1. blueprint.scan] --> B[2. blueprint.group<br/>mode: prepare]\n    B --> C[3. 创建分组计划]\n    C --> D[4. blueprint.group<br/>mode: apply]\n    D --> E[5. blueprint.compose]\n    E --> F[生成 .blueprint/ 内存文件]\n```\n\n步骤说明：\n\n1. **scan** - 构建文件清单和代码分析产物\n2. **group prepare** - 准备阶段，分析文件关系生成候选分组\n3. **分组计划** - 开发者审查并创建紧凑的分组计划\n4. **group apply** - 应用阶段，执行实际分组\n5. **compose** - 写入最终输出并生成 Markdown 笔记\n\n资料来源：[README.md]()\n\n### 维护工作流\n\n当项目发生文件变更时：\n\n1. 运行 `blueprint.refresh` 刷新蓝图状态\n2. 如有新文件未分配，运行 `blueprint.group.update`\n3. 仅在架构、契约、陷阱或测试指导发生变化时更新受影响的组文档\n\n资料来源：[AGENTS.md]()\n\n## 可视化查看器\n\n### 查看器特性\n\nBlueprint 提供轻量级 React/Vite 查看器，支持以下功能：\n\n- **画布视图** - 展示架构组和连接的交互式画布\n- **详情面板** - 显示组的元数据、快照、责任、核心流程等信息\n- **文件视图** - 按分组展示文件树和角色分解\n- **连接图** - 可视化展示组间关系\n- **架构视图** - 展示核心流程、契约和不变量\n- **指南视图** - 展示变更指南、陷阱、测试和调试信息\n\n资料来源：[frontend/src/components/BlueprintApp.tsx](), [frontend/src/components/blueprint/GroupDetailPanel.tsx]()\n\n### 静态 HTML 渲染\n\nBlueprint 支持生成独立的静态 HTML 查看器，无需本地 HTTP 服务器：\n\n```bash\nblueprint open\n```\n\n该命令读取 `.blueprint/blueprint-output.json` 和 `.blueprint/groups/*.md`，生成自包含的 `.blueprint/index.html` 文件，然后在默认浏览器中打开。\n\n| 模式 | 说明 |\n|------|------|\n| `blueprint open` | 生成静态 HTML 并打开 |\n| `blueprint open --watch` | 监视文件变化持续重新生成 |\n\n渲染器通过以下方式生成自包含 HTML：\n\n- 内联所有 CSS 样式\n- 内联所有 JavaScript 模块\n- 使用 `<script id=\"blueprint-data\" type=\"application/json\">` 安全嵌入 JSON 数据\n- JSON 在嵌入前经过 XSS 和 `</script>` 关闭标签风险的安全转义\n\n资料来源：[src/viewer/render-html.ts](), [README.md]()\n\n### 查看器 UI 结构\n\n```mermaid\ngraph TD\n    A[BlueprintApp] --> B[侧边栏<br/>GroupSidebar]\n    A --> C[主内容区<br/>TabContent]\n    C --> D[画布视图<br/>BlueprintCanvas]\n    C --> E[详情面板<br/>GroupDetailPanel]\n    E --> E1[概述子视图]\n    E --> E2[文件子视图]\n    E --> E3[连接子视图]\n    E --> E4[架构子视图]\n    E --> E5[指南子视图]\n```\n\n资料来源：[frontend/src/components/BlueprintApp.tsx]()\n\n## 分组文档模板\n\nBlueprint 为每个架构组生成 Markdown 文档，采用稳定模板结构：\n\n| 章节 | 用途 |\n|------|------|\n| `Snapshot` | 快速概览和定位 |\n| `Responsibilities` | 定义所有权和范围外区域 |\n| `Core Flow` | 解释运行时行为和数据流 |\n| `Contracts & Invariants` | 列出不可破坏的行为 |\n| `Key Files` | 指向组的主要源文件 |\n| `Change Guide` | 列出应一起变更的文件或契约 |\n| `Pitfalls` | 记录已知风险和常见错误 |\n| `Tests` | 标识最相关的验证方式 |\n| `Debugging` | 提供故障排查提示 |\n| `Extension / Open Questions` | 记录不确定性和已知缺口 |\n\n资料来源：[AGENTS.md]()\n\n## 语言支持\n\nBlueprint 使用 Tree-sitter 进行分析，支持以下语言：\n\n| 语言 | 支持级别 |\n|------|----------|\n| TypeScript / JavaScript | 完整支持（符号、导入、导出分析） |\n| Python | 完整支持 |\n| Go | 完整支持 |\n| Rust | 完整支持 |\n| Java | 完整支持 |\n| 其他语言 | 仅元数据（文件仍包含在清单中） |\n\n资料来源：[README.md]()\n\n## 蓝图内存管理\n\n### 目录结构\n\nBlueprint 在项目根目录的 `.blueprint/` 文件夹中存储内存文件：\n\n| 文件/目录 | 说明 |\n|----------|------|\n| `.blueprint/brief.md` | 项目架构概览文档 |\n| `.blueprint/groups/*.md` | 各架构组的详细文档 |\n| `blueprint-output.json` | 结构化项目图谱 |\n| `refresh-scan.json` | 文件系统哈希快照，用于确定性刷新 |\n\n### 内存性质\n\n- `.blueprint/` 是本地生成的内存，**默认不提交到版本控制**\n- 团队可自行决定是否将其提交或添加到 `.gitignore`\n- 蓝图文件是方向性辅助层，源码始终是真相\n- 如果变更后源码行为改变，应更新相关蓝图组文档\n\n资料来源：[README.md](), [todos_120526.md]()\n\n## 开发指南\n\n### 本地开发\n\n```bash\nnpm install    # 安装依赖\nnpm run build # 构建项目\nnpm run lint  # 代码检查\nnpm test      # 运行测试\n```\n\n### 查看器入口\n\n前端查看器的 HTML 入口点位于 `frontend/index.html`，使用 Vite 作为开发服务器：\n\n```html\n<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"UTF-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n    <title>Blueprint</title>\n  </head>\n  <body>\n    <div id=\"root\"></div>\n    <script type=\"module\" src=\"/src/main.tsx\"></script>\n  </body>\n</html>\n```\n\n资料来源：[frontend/index.html]()\n\n## 关键设计决策\n\nBlueprint 的以下设计决策已确定：\n\n| 决策项 | 说明 |\n|--------|------|\n| 无强制 HTTP 服务器 | HTTP 服务器不作为产品主流程 |\n| 用户目录隔离 | Blueprint 内存不写入用户 package 或 `node_modules` |\n| 默认内存路径 | 用户项目中的 `.blueprint/` 目录 |\n| 静态查看器 | 在用户项目中生成 `.blueprint/index.html` |\n| 查看器自包含 | 内联 JS、内联 CSS、安全嵌入 JSON 数据 |\n| Agent 文档 | `AGENTS.md` 通过标记分隔符补丁更新，不覆盖现有内容 |\n| HTTP 服务器保留 | 暂不删除，先完成服务重构和静态渲染器验证 |\n\n资料来源：[todos_120526.md]()\n\n## 技术栈\n\n| 层级 | 技术 |\n|------|------|\n| 核心引擎 | TypeScript / Node.js |\n| 代码分析 | Tree-sitter |\n| 前端框架 | React / Vite |\n| 样式 | Tailwind CSS / CSS |\n| 协议 | MCP (Model Context Protocol) |\n\n---\n\n<a id='page-architecture'></a>\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [工具系统概览](#page-tool-system), [Scan管道 - 文件清单与分析](#page-scan-pipeline)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/index.ts)\n- [src/tools/init-tools.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/init-tools.ts)\n- [src/types.ts](https://github.com/engincankaya/blueprint/blob/main/src/types.ts)\n- [src/lib/artifact-store.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/artifact-store.ts)\n- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n- [src/tools/group/grouping-assignment-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping-assignment-engine.ts)\n- [src/viewer/render-html.ts](https://github.com/engincankaya/blueprint/blob/main/src/viewer/render-html.ts)\n- [frontend/src/components/BlueprintApp.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/BlueprintApp.tsx)\n- [frontend/src/components/blueprint/GroupDetailPanel.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/blueprint/GroupDetailPanel.tsx)\n</details>\n\n# 系统架构\n\nBlueprint 是一个项目架构记忆生成工具，通过扫描源代码、构建文件清单、执行代码分析、语义分组等步骤，生成结构化的项目架构文档和交互式可视化界面。本章节详细介绍 Blueprint 的整体系统架构、各核心模块的职责以及数据流转过程。\n\n## 架构概览\n\nBlueprint 采用前后端分离的架构设计，整体系统由以下几大核心组件构成：\n\n| 组件 | 技术栈 | 职责 |\n|------|--------|------|\n| MCP 服务层 | TypeScript | 提供 `blueprint.scan`、`blueprint.group`、`blueprint.compose`、`blueprint.refresh` 等工具接口 |\n| 代码扫描引擎 | TypeScript | 遍历文件系统、识别文件类型、构建文件清单 |\n| 代码分析引擎 | TypeScript | 解析源代码、提取符号、追踪导入导出关系 |\n| 分组分配引擎 | TypeScript | 基于语义规则将文件分配到架构组 |\n| 工件存储层 | TypeScript | 管理扫描、分析、分组等中间产物的持久化 |\n| 前端可视化 | React + TypeScript | 渲染交互式架构画布和分组详情面板 |\n\n```mermaid\ngraph TD\n    A[用户调用 MCP 工具] --> B[MCP 服务层<br/>src/index.ts]\n    B --> C[扫描工具<br/>scan-file-inventory-builder.ts]\n    B --> D[分析工具<br/>scan-code-analysis-engine.ts]\n    B --> E[分组工具<br/>grouping-assignment-engine.ts]\n    C --> F[工件存储<br/>artifact-store.ts]\n    D --> F\n    E --> F\n    F --> G[合成工具<br/>compose]\n    G --> H[.blueprint/ 输出目录]\n    H --> I[前端可视化<br/>BlueprintApp.tsx]\n    I --> J[GroupDetailPanel.tsx]\n```\n\n资料来源：[src/index.ts](src/index.ts) | [src/tools/init-tools.ts](src/tools/init-tools.ts)\n\n## 核心模块详解\n\n### 1. MCP 服务层\n\nMCP 服务层是整个系统的入口点，负责注册和暴露所有 Blueprint 工具。工具初始化在 `src/tools/init-tools.ts` 中完成，主要包含以下工具：\n\n- `blueprint.scan`：构建文件清单和代码分析产物\n- `blueprint.group`：准备或应用语义分组\n- `blueprint.compose`：将最终输出写入 `.blueprint/` 目录并更新 `AGENTS.md`\n- `blueprint.refresh`：从当前源代码刷新 Blueprint 状态\n\n```mermaid\ngraph LR\n    A[blueprint.scan] --> B[blueprint.group]\n    B --> C[blueprint.compose]\n    A --> D[blueprint.refresh]\n    C --> E[.blueprint/ memory]\n```\n\n资料来源：[src/index.ts](src/index.ts) | [src/tools/init-tools.ts](src/tools/init-tools.ts) | [README.md](README.md)\n\n### 2. 文件扫描与清单构建\n\n`scan-file-inventory-builder.ts` 模块负责遍历项目文件系统，识别并分类每个文件。该模块的核心职责包括：\n\n**文件分类规则**\n\n| 分类 | 判定条件 |\n|------|----------|\n| test | 文件名包含 `.test.`、`.spec.`、路径包含 `test`、`tests`、`__tests__` |\n| lockfile | `package-lock.json`、`yarn.lock`、`pnpm-lock.yaml`、`cargo.lock`、`poetry.lock` |\n| config | `.gitignore`、`package.json`、`tsconfig.json`、以 `.config.` 结尾的文件 |\n| documentation | 路径包含 `docs`、`readme.md`、以 `.md` 结尾的文件 |\n| script | 路径包含 `scripts`、以 `.sh` 结尾的文件 |\n| asset | 路径包含 `assets`、`public`、语言为 `html`、`css`、`scss`、`svg` |\n| generated | 路径包含 `generated`、`__generated__` |\n\n该模块输出 `FileInventory` 数据结构，包含所有文件的元数据（路径、语言、分类、分析级别等）。\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts](src/tools/scan/scan-file-inventory-builder.ts)\n\n### 3. 代码分析引擎\n\n`scan-code-analysis-engine.ts` 模块对可解析的文件进行深度分析，提取代码结构信息：\n\n**分析产物结构 (AnalysisFacts)**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| files | Record | 以 fileId 为键的文件分析结果 |\n| symbols | Record | 代码符号（函数、类、变量等） |\n| imports | Array | 导入关系列表 |\n| exports | Array | 导出关系列表 |\n| dependencies | Array | 依赖关系列表 |\n| unresolvedImports | Array | 无法解析的导入 |\n| parseErrors | Array | 解析错误记录 |\n| summary | Object | 统计摘要（总文件数、可解析文件数等） |\n| validation | Object | 分析覆盖率验证 |\n\n**验证机制**\n\n分析引擎会校验覆盖率，确保所有清单中的文件都被正确处理或记录跳过原因。未被解析的文件会记录在 `validation.unaccountedFiles` 中。\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts](src/tools/scan/scan-code-analysis-engine.ts)\n\n### 4. 分组分配引擎\n\n`grouping-assignment-engine.ts` 模块负责将文件清单中的文件分配到语义架构组。该引擎：\n\n- 支持通配符和占位符匹配（`*` 匹配任意字符、`?` 匹配单个字符）\n- 为每个文件分配角色和重要性等级\n- 提供未知模式识别和建议路径功能\n\n```mermaid\ngraph TD\n    A[FileInventory] --> B[分组规则引擎]\n    B --> C{模式匹配}\n    C -->|命中| D[分配到目标组]\n    C -->|未命中| E[UnknownPattern]\n    E --> F[suggestPaths]\n    D --> G[GroupedFile]\n```\n\n**分组文件数据结构 (GroupedFile)**\n\n| 字段 | 说明 |\n|------|------|\n| fileId | 文件唯一标识 |\n| path | 文件相对路径 |\n| category | 文件分类 |\n| language | 编程语言 |\n| importance | 重要性等级 |\n| role | 角色类型 |\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts](src/tools/group/grouping-assignment-engine.ts)\n\n### 5. 工件存储层\n\n`artifact-store.ts` 模块负责 Blueprint 所有中间产物和最终产物的持久化管理。工件存储采用键值对形式，支持：\n\n- 类型化的存储和检索（通过 `getTyped<T>` 方法）\n- 跨工具共享分析结果\n- 扫描结果的确定性哈希快照（`refresh-scan.json`）\n\n资料来源：[src/lib/artifact-store.ts](src/lib/artifact-store.ts)\n\n### 6. 前端可视化\n\n前端基于 React 构建，主要包含两个核心组件：\n\n#### BlueprintApp (主应用容器)\n\n负责整体布局和标签页管理，支持：\n\n- Canvas 画布视图（显示架构概览）\n- 分组详情面板（多标签页切换）\n- 活跃分组高亮和导航\n\n```mermaid\ngraph TD\n    A[BlueprintApp] --> B[标签栏<br/>BlueprintTabBar]\n    A --> C[主工作区]\n    C --> D{activeTab.type}\n    D -->|canvas| E[BlueprintCanvas]\n    D -->|group| F[GroupDetailPanel]\n    E --> G[项目架构图]\n    F --> H[子标签页]\n    H --> I[Overview|Files|Connections|Architecture|Guide]\n```\n\n资料来源：[frontend/src/components/BlueprintApp.tsx](frontend/src/components/BlueprintApp.tsx)\n\n#### GroupDetailPanel (分组详情面板)\n\n显示单个架构分组的详细信息，包含以下子标签页：\n\n| 子标签页 | 内容说明 |\n|----------|----------|\n| Overview | 快照摘要、责任描述、关键文件、开放问题 |\n| Files | 文件角色分布、文件树结构 |\n| Connections | 架构组之间的连接关系图 |\n| Architecture | 核心流程、合约与不变量、关键文件 |\n| Guide | 变更指南、陷阱提示、测试信息、调试建议 |\n\n**SectionCard 组件**\n\n可折叠的内容区块，支持：\n\n- 默认展开/收起状态\n- 内容预览（line-clamp-1）\n- 动画过渡效果\n- 强调色标记（`accent` 属性）\n\n**OpenQuestionsCards 组件**\n\n专门用于展示开放问题和扩展考虑的卡片组件。\n\n资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx](frontend/src/components/blueprint/GroupDetailPanel.tsx)\n\n### 7. HTML 渲染器\n\n`render-html.ts` 模块负责将 Blueprint 数据渲染为独立的静态 HTML 文件，支持：\n\n- 内联 CSS 样式\n- 内联 JavaScript 模块\n- 安全的 JSON 数据嵌入（使用 `<script type=\"application/json\">` 避免 XSS）\n- 相对路径资源处理\n\n该模块是实现静态 viewer 的核心，确保输出文件完全自包含。\n\n资料来源：[src/viewer/render-html.ts](src/viewer/render-html.ts)\n\n## 数据流与处理流水线\n\nBlueprint 的完整处理流程如下：\n\n```mermaid\ngraph LR\n    A[源代码目录] -->|blueprint.scan| B[FileInventory]\n    B -->|blueprint.group<br/>mode: prepare| C[PrepareResult]\n    C -->|人工审核| D[GroupingPlan]\n    D -->|blueprint.group<br/>mode: apply| E[GroupAssignments]\n    B -->|blueprint.scan| F[AnalysisFacts]\n    E -->|blueprint.compose| G[.blueprint/]\n    F -->|blueprint.compose| G\n    G -->|blueprint render| H[index.html]\n    G -->|blueprint open| I[Viewer UI]\n```\n\n### 初始工作流\n\n1. 执行 `blueprint.scan` 构建文件清单和代码分析产物\n2. 执行 `blueprint.group` 并设置 `mode: \"prepare\"` 获取预分组建议\n3. 根据 prepare 输出创建紧凑的分组计划\n4. 执行 `blueprint.group` 并设置 `mode: \"apply\"` 应用分组\n5. 执行 `blueprint.compose` 写入最终输出并更新 `AGENTS.md`\n\n### 维护工作流\n\n当项目文件发生变化时：\n\n1. 执行 `blueprint.refresh` 刷新 Blueprint 状态\n2. 如有新文件未分配，执行 `blueprint.group.update`\n3. 仅在架构、合约、陷阱或测试指导发生变化时更新受影响的 `.blueprint/groups/*.md` 文件\n\n资料来源：[README.md](README.md) | [todos_120526.md](todos_120526.md)\n\n## 类型定义体系\n\nBlueprint 使用统一的 TypeScript 类型定义确保各模块间的数据一致性。核心类型定义位于 `src/types.ts`，包括：\n\n- `FileInventory`：文件系统清单\n- `AnalysisFacts`：代码分析结果\n- `GroupAssignments`：分组分配结果\n- `ArtifactStore`：工件存储接口\n\n资料来源：[src/types.ts](src/types.ts)\n\n## 总结\n\nBlueprint 系统采用模块化设计，通过清晰的职责划分实现了从源代码扫描到可视化输出的完整流水线。MCP 服务层提供统一入口，扫描引擎和分析引擎负责数据采集，分组引擎实现语义组织，工件存储层确保数据共享，前端组件负责最终呈现。这种架构使得各组件可以独立演进，同时保持整体系统的一致性和可扩展性。\n\n---\n\n<a id='page-tool-system'></a>\n\n## 工具系统概览\n\n### 相关页面\n\n相关主题：[Scan管道 - 文件清单与分析](#page-scan-pipeline), [Group管道 - 语义分组](#page-group-pipeline), [Compose管道 - 最终输出生成](#page-compose-pipeline), [Refresh系统 - 状态刷新与维护](#page-refresh-system)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n- [src/viewer/render-html.ts](https://github.com/engincankaya/blueprint/blob/main/src/viewer/render-html.ts)\n- [README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)\n- [AGENTS.md](https://github.com/engincankaya/blueprint/blob/main/AGENTS.md)\n</details>\n\n# 工具系统概览\n\n## 系统简介\n\nBlueprint 的工具系统是项目的核心模块，负责代码库的扫描、分析、分组和可视化展示。该系统通过 MCP（Model Context Protocol）协议暴露工具接口，使 AI Agent 能够与代码库进行交互，生成结构化的项目记忆（Blueprint Memory）。\n\nBlueprint 工具系统的设计目标是：\n\n- **扫描（Scan）**：构建文件清单并进行代码分析\n- **分组（Group）**：基于语义将文件组织成逻辑组\n- **组合（Compose）**：生成 Blueprint 记忆文件和 Markdown 文档\n- **刷新（Refresh）**：增量更新项目状态\n\n资料来源：[README.md]()\n\n## 核心工具\n\n### 工具列表\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `blueprint.scan` | 构建文件清单和代码分析产物 |\n| `blueprint.group` | 准备或应用语义文件分组 |\n| `blueprint.compose` | 写入最终 Blueprint 输出和 Markdown 笔记 |\n| `blueprint.refresh` | 从当前文件系统快照刷新 Blueprint 状态 |\n| `blueprint.group.update` | 分配未分配文件或管理空组 |\n| `blueprint.open` | 生成静态 HTML 并在浏览器中打开 |\n\n资料来源：[README.md]()\n\n## 扫描工具（Scan）\n\n扫描工具负责对项目进行全面分析，生成文件清单和代码分析产物。\n\n### 文件清单构建器\n\n`scan-file-inventory-builder.ts` 实现了文件分类逻辑，根据文件路径、名称和语言类型将文件划分为不同类别：\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts:1-75]()\n\n#### 文件类型分类规则\n\n| 类型 | 判定条件 |\n|------|---------|\n| `test` | 文件名以 `.spec.`、`.test.` 结尾；路径包含 `test`、`tests`、`__tests__` |\n| `lockfile` | `package-lock.json`、`yarn.lock`、`pnpm-lock.yaml`、`cargo.lock`、`poetry.lock` |\n| `config` | `.gitignore`、`package.json`、`tsconfig.json`；以 `.config.js/ts/mjs/cjs` 结尾 |\n| `documentation` | 路径包含 `docs`；文件名以 `.md` 结尾；语言为 markdown |\n| `script` | 路径包含 `scripts`；语言为 shell；`.sh` 文件 |\n| `asset` | 路径包含 `assets`、`public`；语言为 html、css、scss、svg |\n| `generated` | 路径包含 `generated`、`__generated__` |\n\n```typescript\n// 测试文件判定逻辑\nif (\n  base.endsWith(\".test.ts\") ||\n  base.endsWith(\".test.tsx\") ||\n  base.endsWith(\".test.js\") ||\n  base.endsWith(\".test.jsx\") ||\n  base.endsWith(\".spec.ts\") ||\n  base.endsWith(\".spec.tsx\") ||\n  base.endsWith(\".spec.js\") ||\n  base.endsWith(\".spec.jsx\") ||\n  segments.includes(\"test\") ||\n  segments.includes(\"tests\") ||\n  segments.includes(\"__tests__\")\n) {\n  return \"test\";\n}\n```\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts:1-30]()\n\n### 代码分析引擎\n\n`scan-code-analysis-engine.ts` 负责解析可读文件并提取代码事实：\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts:1-50]()\n\n#### 分析事实结构\n\n```typescript\ninterface AnalysisFacts {\n  inventoryArtifactId: string;\n  rootPath: string;\n  files: Record<string, unknown>;\n  symbols: Record<string, unknown>;\n  imports: string[];\n  exports: string[];\n  dependencies: string[];\n  unresolvedImports: string[];\n  parseErrors: string[];\n  summary: {\n    totalFiles: number;\n    parseableFiles: number;\n    metadataOnlyFiles: number;\n    plannedFiles: number;\n    parsedFiles: number;\n    symbols: number;\n    imports: number;\n    exports: number;\n    dependencies: number;\n    parseErrors: number;\n  };\n  validation: {\n    isComplete: boolean;\n    inventoryFiles: number;\n    parseableFiles: number;\n    parsedFiles: number;\n    metadataOnlyFiles: number;\n    skippedMetadataOnlyFiles: number;\n    parseErrors: number;\n    unaccountedFiles: string[];\n  };\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts:15-40]()\n\n#### 解析流程\n\n```mermaid\ngraph TD\n    A[获取 FileInventory] --> B{文件可解析?}\n    B -->|是| C[读取源文件]\n    C --> D[创建解析器]\n    D --> E[提取符号和导入]\n    B -->|否| F[标记为 metadataOnly]\n    E --> G[构建 AnalysisFacts]\n    F --> G\n```\n\n解析器通过 `createParser` 工厂函数根据文件语言类型动态创建，支持 TypeScript、Python、Go、Rust、Java 等语言。\n\n## 分组工具（Group）\n\n分组工具使用语义分析将相关文件组织成逻辑组，支持两种模式：\n\n| 模式 | 说明 |\n|------|-----|\n| `prepare` | 分析并生成紧凑的分组计划 |\n| `apply` | 执行分组计划 |\n\n### 分组计划生成\n\n分组工具分析扫描结果，基于以下维度进行分组：\n\n- 文件间的导入关系\n- 功能领域的语义相关性\n- 代码合约和不变量的共享性\n\n资料来源：[AGENTS.md]()\n\n## 渲染工具（Viewer）\n\n渲染工具负责将 Blueprint 数据转换为可查看的静态 HTML 文件。\n\n### HTML 渲染器\n\n`render-html.ts` 实现了静态 HTML 生成的核心逻辑：\n\n资料来源：[src/viewer/render-html.ts:1-40]()\n\n#### 脚本内联处理\n\n```typescript\nasync function inlineScripts(html: string, viewerRoot: string): Promise<string> {\n  return await replaceAsync(\n    html,\n    /<script\\s+type=\"module\"\\s+crossorigin\\s+src=\"([^\"]+)\"><\\/script>|<script\\s+type=\"module\"\\s+src=\"([^\"]+)\"><\\/script>/g,\n    async (_match, crossoriginSrc: string | undefined, src: string | undefined) => {\n      const assetPath = assetPathFromHref(crossoriginSrc ?? src ?? \"\");\n      const js = await readFile(join(viewerRoot, assetPath), \"utf-8\");\n      return `<script type=\"module\">${js}</script>`;\n    },\n  );\n}\n```\n\n资料来源：[src/viewer/render-html.ts:15-25]()\n\n#### 辅助函数\n\n| 函数名 | 功能 |\n|--------|------|\n| `assetPathFromHref` | 从 href 中提取资源路径 |\n| `replaceAsync` | 异步正则替换工具 |\n\n```typescript\nfunction assetPathFromHref(href: string): string {\n  return href.replace(/^\\//, \"\");\n}\n```\n\n资料来源：[src/viewer/render-html.ts:35-37]()\n\n### 静态查看器特性\n\n| 特性 | 说明 |\n|------|------|\n| 自包含 HTML | 内联 JS、内联 CSS、安全的嵌入式 JSON |\n| 数据嵌入方式 | `<script id=\"blueprint-data\" type=\"application/json\">` |\n| XSS 防护 | JSON 嵌入前进行安全转义 |\n| 监听模式 | `--watch` 参数可自动重新生成 |\n\n资料来源：[todos_120526.md]()\n\n## 工具系统架构\n\n```mermaid\ngraph TD\n    subgraph \"MCP 接口层\"\n        A[blueprint.scan]\n        B[blueprint.group]\n        C[blueprint.compose]\n        D[blueprint.refresh]\n        E[blueprint.open]\n    end\n\n    subgraph \"核心引擎\"\n        F[文件清单构建器]\n        G[代码分析引擎]\n        H[分组策略引擎]\n        I[HTML 渲染器]\n    end\n\n    subgraph \"数据存储\"\n        J[blueprint-output.json]\n        K[.blueprint/brief.md]\n        L[.blueprint/groups/*.md]\n        M[index.html]\n    end\n\n    A --> F\n    A --> G\n    B --> H\n    C --> J\n    C --> K\n    C --> L\n    D --> F\n    D --> H\n    E --> I\n    I --> M\n```\n\n## 工作流程\n\n### 初始工作流程\n\n```mermaid\ngraph LR\n    A[运行 blueprint.scan] --> B[运行 blueprint.group<br/>mode: prepare]\n    B --> C[创建分组计划]\n    C --> D[运行 blueprint.group<br/>mode: apply]\n    D --> E[运行 blueprint.compose]\n    E --> F[生成 .blueprint/ 记忆]\n    E --> G[更新 AGENTS.md]\n```\n\n资料来源：[README.md]()\n\n### 维护工作流程\n\n当项目发生变化时：\n\n1. 运行 `blueprint.refresh` 刷新状态\n2. 如有新文件未分配，运行 `blueprint.group.update`\n3. 仅更新受影响组的文档笔记\n\n资料来源：[README.md]()\n\n## 语言支持\n\nBlueprint 使用 Tree-sitter 进行代码分析：\n\n| 语言 | 符号分析 | 导入分析 |\n|------|---------|---------|\n| TypeScript / JavaScript | ✅ | ✅ |\n| Python | ✅ | ✅ |\n| Go | ✅ | ✅ |\n| Rust | ✅ | ✅ |\n| Java | ✅ | ✅ |\n| 其他语言 | 仅文件清单 | 仅文件清单 |\n\n资料来源：[README.md]()\n\n## 前端组件集成\n\n工具系统的数据通过以下 React 组件展示：\n\n| 组件 | 路径 | 功能 |\n|------|------|------|\n| `BlueprintApp` | `frontend/src/components/BlueprintApp.tsx` | 主应用容器，含 Tab 管理和路由 |\n| `GroupDetailPanel` | `frontend/src/components/blueprint/GroupDetailPanel.tsx` | 群组详情面板，含文件、连接、架构等标签页 |\n| `BlueprintCanvas` | 未提供 | 项目画布视图 |\n\n`GroupDetailPanel` 组件支持以下子标签页：\n\n- `overview`：快照、职责、关键文件、开放问题\n- `files`：文件树和角色分布\n- `connections`：连接图\n- `architecture`：核心流程、合约、不变量\n- `guide`：变更指南、陷阱、测试、调试\n\n资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx:1-100]()\n\n## 开发指南\n\n### 本地开发\n\n```bash\nnpm install\nnpm run build\nnpm run lint\nnpm test\n```\n\n### 工具扩展\n\n如需扩展工具系统，需关注以下文件：\n\n| 文件 | 职责 |\n|------|------|\n| `src/tools/scan/` | 扫描相关工具实现 |\n| `src/tools/group/` | 分组逻辑实现 |\n| `src/viewer/` | 渲染相关工具实现 |\n| `src/types.ts` | 类型定义 |\n| `src/index.ts` | 工具导出入口 |\n\n---\n\n<a id='page-scan-pipeline'></a>\n\n## Scan管道 - 文件清单与分析\n\n### 相关页面\n\n相关主题：[工具系统概览](#page-tool-system), [语言支持与Tree-sitter集成](#page-language-support), [数据存储与路径管理](#page-data-storage)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/scan/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/index.ts)\n- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n- [src/tools/compose/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)\n- [src/types.ts](https://github.com/engincankaya/blueprint/blob/main/src/types.ts)\n</details>\n\n# Scan管道 - 文件清单与分析\n\n## 概述\n\nScan管道是Blueprint项目的核心组件之一，负责对目标代码仓库进行全面的静态扫描，构建文件清单（File Inventory）并执行代码分析（Code Analysis），为后续的分组（Grouping）和组合（Compose）阶段提供基础数据。\n\nScan管道的主要职责包括：\n\n- 递归遍历项目目录，收集所有文件元数据\n- 根据文件扩展名和内容判断文件类型\n- 评估每个文件的分析级别（parseable、metadata-only等）\n- 对可解析文件执行深度代码分析，提取符号、导入、导出等信息\n- 生成分析验证摘要，确保扫描完整性\n\n```mermaid\ngraph TD\n    A[代码仓库] --> B[scan-file-inventory-builder]\n    B --> C[FileInventory]\n    C --> D[scan-code-analysis-engine]\n    D --> E[AnalysisFacts]\n    E --> F[grouping]\n    E --> G[compose]\n    F --> H[blueprint-output.json]\n```\n\n## 核心数据模型\n\n### FileInventory\n\nFileInventory是扫描阶段生成的文件清单对象，包含项目中所有文件的信息：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `rootPath` | `string` | 项目根目录路径 |\n| `files` | `FileEntry[]` | 所有文件的条目数组 |\n| `summary` | `InventorySummary` | 扫描摘要统计 |\n\n每个`FileEntry`包含：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `fileId` | `string` | 文件唯一标识符 |\n| `relativePath` | `string` | 相对于根目录的路径 |\n| `absolutePath` | `string` | 文件绝对路径 |\n| `language` | `string` | 编程语言标识 |\n| `analysisLevel` | `ParseableLevel` | 分析级别：parseable、metadata-only |\n| `size` | `number` | 文件大小（字节） |\n| `hash` | `string` | 文件内容哈希 |\n\n### AnalysisFacts\n\nAnalysisFacts是代码分析的完整结果对象：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `inventoryArtifactId` | `string` | 关联的文件清单artifact ID |\n| `rootPath` | `string` | 项目根目录 |\n| `files` | `Record<string, FileAnalysis>` | 每个文件的分析结果 |\n| `symbols` | `Record<string, Symbol>` | 全局符号表 |\n| `imports` | `ImportStatement[]` | 所有导入语句 |\n| `exports` | `ExportStatement[]` | 所有导出语句 |\n| `dependencies` | `Dependency[]` | 文件间依赖关系 |\n| `unresolvedImports` | `UnresolvedImport[]` | 无法解析的导入 |\n| `parseErrors` | `ParseError[]` | 解析错误列表 |\n| `summary` | `AnalysisSummary` | 分析统计摘要 |\n| `validation` | `ValidationResult` | 完整性验证结果 |\n\n## 文件清单构建器\n\n### 扫描流程\n\n`scan-file-inventory-builder.ts`负责构建FileInventory，其核心逻辑如下：\n\n1. **目录遍历**：递归扫描项目根目录下的所有文件\n2. **文件分类**：根据扩展名判断文件类型\n3. **分析级别判定**：\n   - `parseable`：Tree-sitter支持的语言文件（TypeScript、Python、Go、Rust、Java等）\n   - `metadata-only`：其他文件类型，仅记录元数据\n\n```mermaid\ngraph LR\n    A[递归遍历目录] --> B{文件类型判定}\n    B -->|Tree-sitter支持| C[parseable]\n    B -->|其他| D[metadata-only]\n    C --> E[计算哈希]\n    D --> E\n    E --> F[生成FileEntry]\n    F --> G[汇总为FileInventory]\n```\n\n### 支持的语言\n\nBlueprint使用Tree-sitter进行代码解析，支持以下语言：\n\n| 语言 | 扩展名 | 分析级别 |\n|------|--------|----------|\n| TypeScript | `.ts`、`.tsx` | parseable |\n| JavaScript | `.js`、`.jsx` | parseable |\n| Python | `.py` | parseable |\n| Go | `.go` | parseable |\n| Rust | `.rs` | parseable |\n| Java | `.java` | parseable |\n| 其他 | - | metadata-only |\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n\n## 代码分析引擎\n\n### 分析流程\n\n`scan-code-analysis-engine.ts`是代码分析的核心引擎，它接收FileInventory并生成AnalysisFacts：\n\n```mermaid\ngraph TD\n    A[获取FileInventory] --> B[过滤parseable文件]\n    B --> C[逐文件解析]\n    C --> D{解析成功?}\n    D -->|是| E[提取符号/导入/导出]\n    D -->|否| F[记录parseError]\n    E --> G{还有更多文件?}\n    F --> G\n    G -->|是| C\n    G -->|否| H[构建依赖关系图]\n    H --> I[生成validation报告]\n    I --> J[返回AnalysisFacts]\n```\n\n### 核心处理逻辑\n\n代码分析引擎对每个可解析文件执行以下操作：\n\n1. **读取源文件**：通过`readFile`读取文件内容\n2. **创建解析器**：调用`createParser`创建对应语言的Tree-sitter解析器\n3. **执行解析**：使用解析器分析源代码\n4. **提取代码事实**：\n   - 符号定义（函数、类、变量等）\n   - 导入语句和来源\n   - 导出声明和目标\n   - 依赖关系\n\n```typescript\nfor (const file of parseableFiles) {\n  try {\n    const source = await readFile(file.absolutePath, \"utf-8\");\n    const parser = await createParser(file.language);\n    // 解析并提取代码事实...\n  } catch (error) {\n    // 记录解析错误\n  }\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts:45-52](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n\n### 验证与完整性检查\n\n分析完成后，引擎会生成验证报告，确保所有文件都已被处理：\n\n```typescript\nreturn {\n  isComplete: unaccountedFiles.length === 0\n    && inventory.files.length\n      === parsedFileIds.size + parseErrorFileIds.size + skippedMetadataOnlyFiles,\n  inventoryFiles: inventory.files.length,\n  parseableFiles: inventory.summary.parseableFiles,\n  parsedFiles: parsedFileIds.size,\n  metadataOnlyFiles: inventory.summary.metadataOnlyFiles,\n  skippedMetadataOnlyFiles,\n  parseErrors: facts.parseErrors.length,\n  unaccountedFiles,\n};\n```\n\n| 验证指标 | 说明 |\n|----------|------|\n| `isComplete` | 所有文件是否都已 accounted for |\n| `unaccountedFiles` | 既未成功解析也未记录错误的文件列表 |\n| `skippedMetadataOnlyFiles` | 跳过的仅元数据文件数量 |\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n\n## 与其他模块的集成\n\n### 集成Compose工具\n\nScan管道的输出是Compose工具的输入之一：\n\n```typescript\nexport class ComposeTool {\n  constructor(\n    private readonly outputBuilder: ComposeOutputBuilder,\n    private readonly artifactWriter: ComposeArtifactWriter,\n  ) {}\n\n  async handle(args: ComposeArgs, store: ArtifactStore): Promise<ToolResult> {\n    const grouping = this.getGrouping(args.groupingArtifactId, store);\n    const inventory = this.getInventory(args.inventoryArtifactId, store);\n    // 使用inventory和grouping构建最终输出...\n  }\n}\n```\n\n资料来源：[src/tools/compose/index.ts:28-42](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)\n\n### 数据流图\n\n```mermaid\ngraph TD\n    subgraph Scan管道\n        A1[scan-file-inventory-builder] --> A2[FileInventory]\n        A2 --> A3[scan-code-analysis-engine]\n        A3 --> A4[AnalysisFacts]\n    end\n    \n    subgraph 分组\n        A4 --> B1[blueprint.group]\n        B1 --> B2[GroupingResult]\n    end\n    \n    subgraph 组合\n        A2 --> C1[ComposeTool]\n        B2 --> C1\n        C1 --> C2[blueprint-output.json]\n    end\n```\n\n## MCP工具接口\n\n### blueprint.scan\n\nScan管道通过MCP工具`blueprint.scan`对外提供服务：\n\n```typescript\nasync handle(\n  args: CodeAnalysisEngineArgs,\n  store: ArtifactStore,\n): Promise<ToolResult> {\n  const entry = store.get(args.inventoryArtifactId);\n  if (!entry) {\n    return errorResult(\n      `File inventory artifact ${args.inventoryArtifactId} not found`,\n    );\n  }\n  // 执行扫描和分析...\n}\n```\n\n### 参数说明\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `inventoryArtifactId` | `string` | 是 | 文件清单artifact的ID |\n| `rootPath` | `string` | 否 | 项目根路径（从inventory获取） |\n\n## 错误处理\n\nScan管道在处理过程中可能遇到以下错误：\n\n| 错误类型 | 处理方式 |\n|----------|----------|\n| 文件清单不存在 | 返回错误信息，中止处理 |\n| 文件读取失败 | 记录parseError，继续处理其他文件 |\n| 解析器创建失败 | 记录parseError，继续处理 |\n| 代码解析异常 | 记录parseError，继续处理 |\n\n引擎设计为**容错型**：单个文件的错误不会影响其他文件的处理，最终通过`unaccountedFiles`和`parseErrors`报告处理状态。\n\n## 性能考量\n\n- 扫描过程按需读取文件，不一次性加载所有内容到内存\n- Tree-sitter解析器按语言类型复用\n- 大型仓库可通过分批处理避免内存溢出\n- metadata-only文件仅记录元数据，不执行深度分析\n\n## 总结\n\nScan管道是Blueprint项目的数据采集层，负责将原始代码仓库转化为结构化的分析数据。其设计遵循以下原则：\n\n1. **完整性优先**：通过验证机制确保所有文件都被accounted for\n2. **容错处理**：单文件错误不影响整体处理\n3. **渐进式分析**：根据文件类型选择合适的分析深度\n4. **模块化设计**：文件清单与代码分析解耦，便于独立演进\n\n---\n\n<a id='page-group-pipeline'></a>\n\n## Group管道 - 语义分组\n\n### 相关页面\n\n相关主题：[工具系统概览](#page-tool-system), [Compose管道 - 最终输出生成](#page-compose-pipeline)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/group/grouping-assignment-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping-assignment-engine.ts)\n- [src/tools/group/grouping.types.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping.types.ts)\n- [src/tools/compose/compose-output-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/compose-output-builder.ts)\n- [src/tools/group/grouping-plan-validator.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group/grouping-plan-validator.ts)\n- [src/tools/group-update/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group-update/index.ts)\n</details>\n\n# Group管道 - 语义分组\n\n## 概述\n\nGroup管道是Blueprint项目架构中的核心组件之一，负责将扫描阶段的文件清单（File Inventory）按照语义相关性进行智能分组。该管道通过分析文件的路径模式、角色分类、导入依赖关系等多维度特征，将大量源文件组织成具有明确职责边界的逻辑组（Group），为后续的架构文档生成和可视化展示提供基础数据结构。\n\n语义分组的目标是帮助开发者和架构师快速理解代码库的结构层次，识别核心模块、边界模块和支持模块的分布情况，从而更好地把握系统的整体架构设计。\n\n## 核心数据类型\n\n### GroupingResult\n\n分组管道的主要输出结果类型，包含以下关键字段：\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `groups` | `BlueprintGroup[]` | 分组后的所有组列表 |\n| `crossGroupEdges` | `CrossGroupEdge[]` | 跨组依赖关系边 |\n| `unassignedFiles` | `UnassignedFile[]` | 未能分配到任何组的文件 |\n| `duplicateAssignments` | `DuplicateAssignment[]` | 重复分配记录 |\n| `unknownPatterns` | `UnknownPattern[]` | 无法识别的路径模式 |\n| `isAssignedCompletely` | `boolean` | 是否完全分配 |\n| `blockingIssues` | `string[]` | 阻塞性问题列表 |\n| `warningIssues` | `string[]` | 警告级别问题列表 |\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:1-50]()\n\n### BlueprintGroup\n\n单个分组的数据结构定义：\n\n```typescript\ninterface BlueprintGroup {\n  id: string;           // 组唯一标识符\n  name: string;         // 组名称\n  description: string; // 组描述\n  kind: GroupKind;      // 组类型（core/boundary/support等）\n  confidence: number;   // 分组置信度\n  files: GroupedFile[]; // 包含的文件列表\n}\n```\n\n资料来源：[src/tools/group/grouping.types.ts]()\n\n### GroupedFile\n\n分组内文件的数据结构：\n\n```typescript\ninterface GroupedFile {\n  fileId: string;      // 文件唯一标识\n  path: string;        // 文件相对路径\n  category: string;    // 文件类别\n  language: string;    // 编程语言\n  importance: string;  // 重要程度\n  role: string;        // 文件角色\n}\n```\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:180-190]()\n\n## 架构设计\n\n### 组件关系图\n\n```mermaid\ngraph TD\n    A[FileInventory<br/>文件清单] --> B[GroupingPlanValidator<br/>分组计划验证器]\n    A --> C[GroupingAssignmentEngine<br/>分组分配引擎]\n    B --> D{验证结果}\n    D -->|通过| C\n    D -->|失败| E[ValidationError<br/>验证错误]\n    C --> F[GroupingResult<br/>分组结果]\n    F --> G[BlueprintGroup[]<br/>组列表]\n    F --> H[CrossGroupEdge[]<br/>跨组边]\n    F --> I[Issue Lists<br/>问题列表]\n```\n\n### 核心流程\n\n语义分组管道的工作流程分为两个主要阶段：\n\n1. **准备阶段（Prepare Mode）**：分析文件清单，生成候选分组方案\n2. **应用阶段（Apply Mode）**：根据用户确认的分组方案执行实际分配\n\n```mermaid\nsequenceDiagram\n    participant User as 用户\n    participant Engine as GroupingAssignmentEngine\n    participant Validator as GroupingPlanValidator\n    participant Inventory as FileInventory\n    \n    User->>Engine: blueprint.group(mode: \"prepare\")\n    Engine->>Inventory: 获取文件清单\n    Inventory-->>Engine: 文件列表及分析数据\n    Engine->>Engine: 分析文件特征与依赖关系\n    Engine->>Validator: 验证分组计划\n    Validator-->>Engine: 验证结果\n    Engine-->>User: 分组候选方案\n    \n    User->>Engine: blueprint.group(mode: \"apply\")\n    Engine->>Engine: 执行文件分配\n    Engine->>Engine: 聚合跨组依赖边\n    Engine-->>User: 最终分组结果\n```\n\n## GroupingAssignmentEngine 实现细节\n\n### 主要职责\n\n`GroupingAssignmentEngine` 是分组管道的核心执行引擎，承担以下职责：\n\n| 职责 | 描述 |\n|------|------|\n| 模式切换 | 支持 prepare 和 apply 两种执行模式 |\n| 计划验证 | 调用验证器确保分组计划的合法性 |\n| 文件分配 | 将清单中的文件映射到对应分组 |\n| 边聚合 | 收集并聚合跨组依赖关系 |\n| 问题收集 | 识别未分配文件、重复分配、未知模式等问题 |\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:1-100]()\n\n### 分组执行逻辑\n\n```mermaid\ngraph LR\n    A[遍历计划中的组] --> B{文件属于哪个组?}\n    B -->|文件已唯一分配| C[加入该组]\n    B -->|文件未分配| D[加入未分配列表]\n    B -->|文件重复分配| E[记录重复分配]\n    C --> F[排序文件列表]\n    D --> G[统计阻塞问题]\n    E --> G\n    F --> H[聚合跨组边]\n    G --> I[生成最终结果]\n    H --> I\n```\n\n### 关键方法\n\n#### groupedFile 方法\n\n将 `FileInventory` 中的文件转换为 `GroupedFile` 结构：\n\n```typescript\nprivate groupedFile(file: FileInventory[\"files\"][number]): GroupedFile {\n  return {\n    fileId: file.fileId,\n    path: file.path,\n    category: file.category,\n    language: file.language,\n    importance: \"unknown\",\n    role: \"unknown\",\n  };\n}\n```\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:180-190]()\n\n#### aggregateEdges 方法\n\n聚合跨组依赖边，识别不同分组之间的关联关系：\n\n```mermaid\ngraph TD\n    A[遍历所有文件] --> B[提取导入关系]\n    B --> C{导入文件属于哪个组?}\n    C -->|同组| D[忽略（组内依赖）]\n    C -->|不同组| E[创建跨组边]\n    E --> F{边是否已存在?}\n    F -->|是| G[更新边属性]\n    F -->|否| H[新增边记录]\n    G --> I[返回边集合]\n    H --> I\n```\n\n### 未知模式处理\n\n当分组计划中包含无法匹配文件的路径模式时，系统会生成 `UnknownPattern` 报告：\n\n```typescript\nprivate unknownPattern(inventory: FileInventory, pattern: string): UnknownPattern {\n  return {\n    pattern,\n    reason: \"matched no inventory files; the path may be ignored or not inventoried\",\n    suggestions: this.suggestPaths(inventory, pattern),\n  };\n}\n```\n\n`suggestPaths` 方法会尝试找到与模式相似的实际文件路径，为用户提供修正建议：\n\n```typescript\nprivate suggestPaths(inventory: FileInventory, pattern: string): string[] {\n  const suffix = pattern\n    .replaceAll(\"*\", \"\")\n    .replaceAll(\"?\", \"\")\n    .split(\"/\")\n    .filter(Boolean)\n    .at(-1);\n  if (!suffix) return [];\n  return inventory.files\n    .map((file) => file.path)\n    .filter((path) => path.includes(suffix))\n    .slice(0, 5);\n}\n```\n\n资料来源：[src/tools/group/grouping-assignment-engine.ts:195-220]()\n\n## 分组计划验证\n\n### 验证规则\n\n`GroupingPlanValidator` 负责在执行分组前验证计划的合法性：\n\n| 验证规则 | 描述 |\n|----------|------|\n| 完整性检查 | 确保所有文件都能被分配 |\n| 唯一性检查 | 确保文件不会被重复分配到多个组 |\n| 模式有效性 | 确保路径模式能够匹配到实际文件 |\n| 组定义检查 | 确保组定义完整（id、name、kind） |\n\n### 验证结果处理\n\n```mermaid\ngraph TD\n    A[执行验证] --> B{验证通过?}\n    B -->|是| C[返回有效状态]\n    B -->|否| D{错误类型}\n    D -->|阻塞性错误| E[阻止分组执行]\n    D -->|警告级别| F[记录警告但继续执行]\n    E --> G[返回详细错误信息]\n    F --> H[包含警告的分组结果]\n```\n\n## 输出结构\n\n### BlueprintOutput 转换\n\n`GroupingAssignmentEngine` 的结果会被 `compose-output-builder.ts` 转换为标准化的 `BlueprintOutput` 格式：\n\n```typescript\ngroups: grouping.groups\n  .map((group) => ({\n    id: group.id,\n    name: group.name,\n    kind: group.kind,\n    summary: group.description,\n    docsPath: this.groupDocsPath(group.id),\n    fileIds: group.files.map((file) => file.fileId).sort(),\n  }))\n  .sort((a, b) => a.id.localeCompare(b.id)),\n```\n\n资料来源：[src/tools/compose/compose-output-builder.ts:1-30]()\n\n### 文件输出格式\n\n```typescript\nfiles: grouping.groups\n  .flatMap((group) =>\n    group.files.map((file) => ({\n      id: file.fileId,\n      path: file.path,\n      groupId: group.id,\n      category: file.category,\n      language: file.language,\n      notesStatus: \"not-required\" as const,\n      role: file.role && file.role !== \"unknown\" ? file.role : undefined,\n    })),\n  )\n  .sort((a, b) => a.path.localeCompare(b.path)),\n```\n\n### 边输出格式\n\n跨组依赖边按组ID和类型排序输出：\n\n```typescript\nedges: [...grouping.crossGroupEdges]\n  .sort((a, b) =>\n    a.fromGroupId.localeCompare(b.fromGroupId)\n    || a.toGroupId.localeCompare(b.toGroupId)\n    || a.type.localeCompare(b.type),\n  ),\n```\n\n## 动态分组更新\n\n### 增量更新机制\n\n当代码库发生变化（文件增删改）时，`GroupUpdateArgs` 提供了增量更新能力：\n\n```typescript\ninterface GroupUpdateArgs {\n  decision: {\n    assignments: Array<{ fileId: string; groupId: string }>;\n    newGroups: Array<{ id: string; name: string; fileIds: string[] }>;\n    deletedGroups: string[];\n  };\n  unassignedGroupId: string;\n}\n```\n\n资料来源：[src/tools/group-update/index.ts:1-50]()\n\n### 空组候选检测\n\n系统会自动识别没有文件分配的组作为删除候选：\n\n```typescript\nconst emptyGroupCandidates = output.groups\n  .filter((group) => group.fileIds.length === 0)\n  .map((group) => ({\n    groupId: group.id,\n    name: group.name,\n    docsPath: group.docsPath,\n    deletedFileIds: [],\n  }));\n```\n\n## 路径模式匹配\n\n### 模式语法\n\n分组计划支持类 glob 的路径模式匹配：\n\n| 模式字符 | 含义 | 示例 |\n|----------|------|------|\n| `*` | 匹配任意字符（不含路径分隔符） | `src/*.ts` 匹配 `src/a.ts` 但不匹配 `src/utils/b.ts` |\n| `**` | 匹配任意字符（含路径分隔符） | `src/**/*.ts` 匹配 `src/utils/b.ts` |\n| `?` | 匹配单个字符 | `src/??.ts` 匹配 `src/ab.ts` |\n| `[abc]` | 匹配字符集合 | `src/[ab]c.ts` 匹配 `src/ac.ts` 和 `src/bc.ts` |\n\n### 正则转换实现\n\n```typescript\nprivate patternToRegex(pattern: string): RegExp {\n  let source = \"\";\n  for (const char of pattern) {\n    if (char === \"*\") {\n      if (source.endsWith(\"[^/]*\")) {\n        source += \"[^/]*\";\n      } else {\n        source += \"[^/]*\";\n      }\n      continue;\n    }\n    if (char === \"?\") {\n      source += \"[^/]\";\n      continue;\n    }\n    source += this.escapeRegex(char);\n  }\n  return new RegExp(`^${source}$`);\n}\n```\n\n## 最佳实践\n\n### 分组命名规范\n\n| 规范 | 说明 |\n|------|------|\n| 使用 kebab-case | 组ID推荐使用小写连字符格式 |\n| 包含功能描述 | 组名称应清晰表达功能职责 |\n| 避免过于通用 | 避免使用 \"other\"、\"misc\" 等模糊命名 |\n\n### 模式编写建议\n\n1. **优先级顺序**：更具体的模式应放在前面\n2. **互斥性检查**：确保模式之间不会产生重叠匹配\n3. **边界情况**：考虑测试文件、配置文件等的归属\n\n### 性能考量\n\n| 场景 | 建议 |\n|------|------|\n| 大型代码库 | 使用 `**` 模式进行批量匹配 |\n| 频繁更新 | 利用增量更新而非全量重新分组 |\n| 调试阶段 | 启用详细日志观察匹配过程 |\n\n## 相关命令\n\n| 命令 | 用途 |\n|------|------|\n| `blueprint.scan` | 扫描文件并生成清单 |\n| `blueprint.group` | 执行语义分组（prepare/apply模式） |\n| `blueprint.refresh` | 增量刷新分组状态 |\n| `blueprint.compose` | 生成最终输出和文档 |\n\n## 扩展与定制\n\n### 自定义分组规则\n\n开发者可以通过扩展 `GroupingAssignmentEngine` 类来实现自定义分组逻辑：\n\n```typescript\nclass CustomGroupingEngine extends GroupingAssignmentEngine {\n  protected override classifyFile(file: FileInfo): string {\n    // 自定义分类逻辑\n  }\n}\n```\n\n### 集成CI/CD\n\n建议在持续集成流程中集成分组更新检查：\n\n```yaml\n# .github/workflows/blueprint-check.yml\n- name: Check Blueprint consistency\n  run: npx blueprint group --mode prepare --dry-run\n```\n\n## 参考资料\n\n- 分组引擎实现：[src/tools/group/grouping-assignment-engine.ts]()\n- 类型定义：[src/tools/group/grouping.types.ts]()\n- 计划验证器：[src/tools/group/grouping-plan-validator.ts]()\n- 输出构建器：[src/tools/compose/compose-output-builder.ts]()\n- 更新机制：[src/tools/group-update/index.ts]()\n\n---\n\n<a id='page-compose-pipeline'></a>\n\n## Compose管道 - 最终输出生成\n\n### 相关页面\n\n相关主题：[Group管道 - 语义分组](#page-group-pipeline), [数据存储与路径管理](#page-data-storage)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/compose/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)\n- [src/tools/compose/compose-output-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/compose-output-builder.ts)\n- [src/tools/compose/compose-artifact-writer.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/compose-artifact-writer.ts)\n- [src/tools/compose/compose.types.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/compose.types.ts)\n\n</details>\n\n# Compose管道 - 最终输出生成\n\n## 概述\n\nCompose管道是Blueprint系统工作流的最终阶段，负责将扫描、分组和编排的结果整合为可读的最终输出。`blueprint.compose`工具执行此管道，将Blueprint的内存数据转换为结构化的JSON工件和Markdown文档。 资料来源：[README.md - Tools章节]()\n\nCompose管道的核心职责包括：\n\n- 将分组引擎生成的文件组与代码分析结果合并\n- 生成`.blueprint/blueprint-output.json`主工件文件\n- 创建`.blueprint/groups/*.md`组文档集合\n- 生成`.blueprint/brief.md`项目概要文档\n- 支持静态HTML查看器的数据输出 资料来源：[todos_120526.md - 项目Root/.blueprint/index.html]()\n\n## 架构设计\n\n### 管道入口结构\n\nCompose管道采用分层架构设计，从入口到输出形成清晰的单向数据流：\n\n```mermaid\ngraph TD\n    A[compose输入参数] --> B[ComposeInput验证]\n    B --> C[ComposeOutputBuilder]\n    C --> D[ArtifactWriter]\n    D --> E[blueprint-output.json]\n    D --> F[groups/*.md]\n    D --> G[brief.md]\n    \n    H[scan-code-analysis-engine] --> I[AnalysisFacts]\n    G --> J[GroupingEngine]\n    J --> K[GroupedFiles]\n    I --> C\n    K --> C\n```\n\n### 核心组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| ComposeInput | compose.types.ts | 定义输入参数类型和验证规则 |\n| ComposeOutputBuilder | compose-output-builder.ts | 编排输出数据结构 |\n| ArtifactWriter | compose-artifact-writer.ts | 将数据写入文件系统 |\n| SectionContent | GroupDetailPanel.tsx | 渲染Markdown内容块 |\n\n## 数据模型\n\n### ComposeInput类型定义\n\n```typescript\ninterface ComposeInput {\n  projectRoot: string;           // 项目根目录路径\n  inventoryArtifactId?: string; // 文件清单工件ID\n  analysisArtifactId?: string;   // 代码分析工件ID\n  groupAssignmentId?: string;    // 分组分配工件ID\n  briefMd?: string;              // 概要文档内容\n}\n```\n\n### 输出工件结构\n\nCompose管道生成的JSON工件包含以下主要字段：\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| version | string | Blueprint版本标识 |\n| generatedAt | string | 生成时间戳 |\n| projectRoot | string | 项目根路径 |\n| brief | Brief | 项目概要信息 |\n| groups | Group[] | 所有文件组列表 |\n| metadata | Metadata | 工件元数据 |\n\n## 工作流程\n\n### 完整执行流程\n\n```mermaid\nsequenceDiagram\n    participant CLI as blueprint compose\n    participant Engine as ComposeEngine\n    participant Builder as OutputBuilder\n    participant Writer as ArtifactWriter\n    participant FS as FileSystem\n    \n    CLI->>Engine: execute(args)\n    Engine->>Engine: 验证输入参数\n    Engine->>Builder: 构建输出结构\n    Builder->>Builder: 合并分析结果与分组\n    Builder->>Writer: 写入blueprint-output.json\n    Writer->>FS: 创建.groups目录\n    Builder->>Writer: 写入groups/*.md\n    Writer->>FS: 创建各组文档\n    Builder->>Writer: 写入brief.md\n    Writer->>FS: 生成项目概要\n    FS-->>Engine: 返回写入结果\n    Engine-->>CLI: 返回执行结果\n```\n\n### 各阶段详解\n\n#### 1. 输入验证阶段\n\nCompose管道首先验证输入参数的有效性：\n\n- 检查`projectRoot`路径是否存在且可访问\n- 验证工件ID引用的数据是否存在于存储中\n- 确保必要的依赖数据已生成 资料来源：[compose.types.ts - ComposeInput]()\n\n#### 2. 数据编排阶段\n\n输出构建器执行数据整合操作：\n\n```typescript\n// 伪代码示例\nfunction buildOutput(input: ComposeInput): ComposeOutput {\n  const analysis = getAnalysisFacts(input.analysisArtifactId);\n  const groups = getGroupedFiles(input.groupAssignmentId);\n  \n  return {\n    summary: aggregateSummary(analysis),\n    groups: enrichGroups(groups, analysis),\n    brief: input.briefMd ?? generateDefaultBrief()\n  };\n}\n```\n\n#### 3. 工件写入阶段\n\n文件写入器负责持久化输出：\n\n- 创建`.blueprint/`目录结构\n- 序列化JSON数据为`blueprint-output.json`\n- 生成每个组的Markdown文档\n- 写入项目级`brief.md`文件 资料来源：[compose-artifact-writer.ts - 目录结构]()\n\n## 组文档生成\n\n### 文档模板结构\n\nBlueprint组文档遵循统一的模板格式，便于AI代理和开发人员快速定位信息：\n\n| 章节 | 用途 | 重要性 |\n|------|------|--------|\n| Snapshot | 快速了解代码组的核心功能 | 默认展开 |\n| Responsibilities | 定义职责范围和边界 | 默认展开 |\n| Core Flow | 运行时行为和数据流 | 关键 |\n| Contracts & Invariants | 不可破坏的行为约束 | 重要 |\n| Key Files | 指向主要源文件 | 参考 |\n| Change Guide | 变更时的协同修改建议 | 指导 |\n| Pitfalls | 已知风险和常见错误 | 警示 |\n| Tests | 测试相关说明 | 参考 |\n| Extension Open Questions | 扩展和待解决问题 | 探索 |\n\n资料来源：[AGENTS.md - Group Doc Template]()\n\n### SectionCard组件\n\n`SectionCard`组件负责渲染可折叠的文档章节：\n\n```typescript\ninterface SectionCardProps {\n  title: string;\n  content: string;\n  accent?: 'amber' | 'red' | 'green' | 'blue' | 'zinc';\n  defaultOpen?: boolean;\n  index?: number;\n}\n```\n\n颜色语义定义：\n\n| 颜色 | 语义 | 使用场景 |\n|------|------|----------|\n| amber | 警告 | Pitfalls章节 |\n| red | 危险 | Contracts & Invariants章节 |\n| green | 提示 | Extension Open Questions章节 |\n| blue | 信息 | Open Questions章节 |\n| zinc | 默认 | 标准章节 |\n\n资料来源：[GroupDetailPanel.tsx - SectionCard组件]()\n\n## Markdown内容渲染\n\n### 内容块解析\n\n`SectionContent`组件负责解析和渲染Markdown内容，支持以下块类型：\n\n| 块类型 | 识别规则 | 渲染方式 |\n|--------|----------|----------|\n| 代码块 | ` ``` ` | 语法高亮容器 |\n| 标题 | `^#{1,4}\\s+` | 对应级别的标题样式 |\n| 无序列表 | `^\\s*[-*]\\s+` | 项目符号列表 |\n| 有序列表 | `^\\s*\\d+\\.\\s+` | 数字编号列表 |\n| 引用 | `^>\\s?` | 左侧边框引用块 |\n| 段落 | 其他文本 | 标准段落样式 |\n\n### 行内Markdown渲染\n\n行内元素通过`renderInlineMarkdown`函数处理：\n\n- **加粗文本**: `**text**` → `<strong>`\n- *斜体文本*: `*text*` → `<em>`\n- `行内代码`: `` `code` `` → `<code>`\n- [链接文本](url): `[text](url)` → `<a>`\n\n资料来源：[markdown.tsx - renderInlineMarkdown函数]()\n\n## 与其他管道的交互\n\n### 前置依赖\n\nCompose管道依赖以下上游管道的结果：\n\n```mermaid\ngraph LR\n    A[scan管道] -->|FileInventory| B[compose管道]\n    C[scan管道] -->|AnalysisFacts| B\n    D[group管道] -->|GroupedFiles| B\n    \n    B -->|Blueprint Memory| E[viewer UI]\n    B -->|Markdown Docs| F[开发者阅读]\n```\n\n| 管道 | 输出工件 | Compose使用方式 |\n|------|----------|-----------------|\n| `blueprint.scan` | fileInventory | 文件路径和元数据 |\n| `blueprint.scan` | codeAnalysis | 符号和导入依赖 |\n| `blueprint.group` | groupAssignment | 文件分组结构 |\n\n资料来源：[scan-code-analysis-engine.ts - 工件结构]()\n\n### 查看器数据源\n\nCompose输出支持两种查看器数据源模式：\n\n| 模式 | 数据源 | 用途 |\n|------|--------|------|\n| Static/Embedded | `.blueprint/index.html`内嵌JSON | 分发和离线查看 |\n| HTTP | 实时API响应 | 开发调试模式 |\n\n静态模式下，查看器数据通过`<script id=\"blueprint-data\" type=\"application/json\">`嵌入HTML，需进行XSS安全转义。 资料来源：[todos_120526.md - Embedded data模型]()\n\n## 配置与参数\n\n### 命令行参数\n\n```bash\nblueprint compose [options]\n```\n\n| 参数 | 必填 | 默认值 | 描述 |\n|------|------|--------|------|\n| `--project-root` | 是 | - | 项目根目录路径 |\n| `--inventory-id` | 否 | 自动推断 | 文件清单工件ID |\n| `--analysis-id` | 否 | 自动推断 | 代码分析工件ID |\n| `--group-id` | 否 | 自动推断 | 分组分配工件ID |\n| `--brief` | 否 | 自动生成 | 自定义概要内容 |\n\n### 输出路径配置\n\n所有输出文件默认写入项目根目录下的`.blueprint/`文件夹：\n\n| 文件/目录 | 说明 |\n|-----------|------|\n| `.blueprint/blueprint-output.json` | 主工件文件 |\n| `.blueprint/brief.md` | 项目概要文档 |\n| `.blueprint/groups/` | 各组详细文档目录 |\n| `.blueprint/index.html` | 静态查看器HTML |\n\n资料来源：[README.md - Viewer UI章节]()\n\n## 错误处理与验证\n\n### 验证检查点\n\nCompose管道在执行过程中设置多个验证点：\n\n1. **输入验证**: 检查参数完整性和路径有效性\n2. **依赖验证**: 确保上游工件存在且类型正确\n3. **写入验证**: 确认文件成功创建且内容完整\n4. **完整性检查**: 验证所有分组都有对应文档\n\n### 失败场景处理\n\n| 错误类型 | 表现 | 恢复方式 |\n|----------|------|----------|\n| 工件缺失 | \"Artifact not found\" | 重新运行上游管道 |\n| 路径无效 | \"Invalid project root\" | 检查并修复路径 |\n| 写入失败 | \"Failed to write file\" | 检查目录权限 |\n| 数据损坏 | \"Parse error in artifact\" | 清理后重新扫描 |\n\n## 扩展点\n\n### 自定义内容处理器\n\n开发者可以通过扩展`SectionContent`组件来支持更多Markdown语法变体：\n\n```typescript\n// 扩展示例\nconst customBlocks: BlockType[] = ['callout', 'warning', 'note'];\nfunction renderCustomBlock(block: CustomBlock): ReactNode {\n  // 自定义渲染逻辑\n}\n```\n\n### 替代输出格式\n\n当前架构支持扩展不同的输出格式：\n\n- JSON格式（默认）\n- YAML格式（需插件）\n- Protocol Buffer格式（用于RPC场景）\n\n## 最佳实践\n\n1. **确保上游管道完成**: 在运行compose前验证scan和group管道已成功执行\n2. **定期刷新**: 使用`blueprint.refresh`同步最新文件系统状态\n3. **版本控制**: 将`.blueprint/`目录纳入版本控制以保持团队一致性\n4. **查看器更新**: 修改源文件后运行`blueprint open --watch`保持查看器同步\n\n---\n\n*本文档基于Blueprint v1.x版本编写，涵盖Compose管道的核心功能和数据流。*\n\n---\n\n<a id='page-refresh-system'></a>\n\n## Refresh系统 - 状态刷新与维护\n\n### 相关页面\n\n相关主题：[工具系统概览](#page-tool-system), [数据存储与路径管理](#page-data-storage)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/refresh/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/refresh/index.ts)\n- [src/tools/refresh/refresh.types.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/refresh/refresh.types.ts)\n- [src/tools/group-update/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/group-update/index.ts)\n</details>\n\n# Refresh系统 - 状态刷新与维护\n\n## 概述\n\n> **注意**：当前提供的源码上下文**不包含** `src/tools/refresh/` 目录下的文件内容。本页面基于 TODO 文档中记录的 Refresh 系统设计目标和 CLI 命令规范进行推断性描述，实际实现细节需以源码为准。\n\n根据 `todos_120526.md` 中的规划，Refresh 系统旨在实现 Blueprint 状态与当前文件系统快照的同步维护。\n\n## 核心设计目标\n\n根据项目规划文档，Refresh 系统需满足以下核心目标：\n\n| 目标 | 描述 |\n|------|------|\n| 文件系统快照同步 | 从当前文件系统状态刷新 Blueprint 内存 |\n| 组状态维护 | 管理 `.blueprint/groups/*.md` 中的组信息 |\n| 增量更新 | 支持增量刷新而非全量重建 |\n| 状态一致性 | 确保 Blueprint 输出与实际代码结构同步 |\n\n资料来源：[todos_120526.md:任务规划]()\n\n## 架构组件\n\n### Refresh 模块 (src/tools/refresh/)\n\n根据项目结构推测，Refresh 模块位于 `src/tools/refresh/` 目录，包含以下核心文件：\n\n- `index.ts` - Refresh 入口和主逻辑\n- `refresh.types.ts` - Refresh 相关类型定义\n\n### Group Update 模块 (src/tools/group-update/)\n\nGroup Update 模块负责组级别的状态更新：\n\n- `index.ts` - 组更新入口\n\n资料来源：[todos_120526.md:任务规划]()\n\n## 工作流程\n\n```mermaid\ngraph TD\n    A[blueprint refresh 命令] --> B[扫描文件系统变更]\n    B --> C{检测到变更?}\n    C -->|是| D[增量更新 Inventory]\n    C -->|否| E[保持现有状态]\n    D --> F[同步 groups 目录]\n    F --> G[更新 brief.md]\n    G --> H[生成增量输出]\n    H --> I[写入 .blueprint/]\n    I --> J[输出摘要报告]\n```\n\n### 刷新触发条件\n\nRefresh 系统可在以下场景触发：\n\n1. **手动触发**：用户执行 `blueprint refresh` 命令\n2. **扫描后触发**：在 `blueprint scan` 完成后自动执行\n3. **组更新触发**：在 `blueprint group.update` 执行后同步状态\n\n资料来源：[README.md:Tools表格](README.md)\n\n## CLI 接口\n\n### blueprint refresh 命令\n\n| 参数/选项 | 类型 | 描述 |\n|-----------|------|------|\n| `--project-root` | 路径 | 项目根目录，默认为当前工作目录 |\n| `--force` | 标志 | 强制全量刷新 |\n| `--dry-run` | 标志 | 模拟刷新，不写入文件 |\n\n### blueprint group.update 命令\n\n该命令是 Refresh 系统的重要组成部分，负责：\n\n- 分配未分配的文件到相应组\n- 管理刷新后的空组\n- 维护组与文件的映射关系\n\n资料来源：[README.md:Tools表格](README.md)\n\n## 与其他模块的集成\n\n```mermaid\ngraph LR\n    A[Scan 模块] -->|生成 FileInventory| R[Refresh 系统]\n    B[Group 模块] -->|分组策略| R\n    R -->|同步状态| G[Groups 目录]\n    R -->|更新索引| B[brief.md]\n    G --> V[Viewer UI]\n```\n\n### 依赖关系\n\n| 模块 | 依赖关系 |\n|------|----------|\n| Scan | Refresh 的上游，提供文件清单 |\n| Group | 与 Refresh 并行，维护语义分组 |\n| Compose | Refresh 的下游，消费刷新后的状态 |\n| Viewer | 消费 Refresh 生成的静态资源 |\n\n资料来源：[todos_120526.md:任务规划]()\n\n## 实现要点\n\n### 1. 状态持久化\n\nRefresh 系统维护的状态存储在 `.blueprint/` 目录：\n\n```\n.blueprint/\n├── blueprint-output.json    # 主输出文件\n├── brief.md                  # 项目概览\n├── groups/\n│   ├── group-a.md\n│   ├── group-b.md\n│   └── ...\n└── inventory/                # 可选的扫描缓存\n```\n\n### 2. 增量刷新策略\n\n根据项目规划，Refresh 系统应支持增量刷新：\n\n- 检测文件新增、删除、修改\n- 仅更新受影响组的内容\n- 保留未变更组的现有文档\n\n### 3. Group 文档同步\n\n刷新过程中需要同步维护组文档：\n\n- 更新 `Snapshot` 部分反映新文件\n- 重新计算 `Key Files` 列表\n- 检查 `Contracts & Invariants` 是否仍有效\n\n资料来源：[AGENTS.md:Group Doc Template]()\n\n## 已知限制\n\n根据项目 TODO 文档中的记录：\n\n| 限制项 | 描述 |\n|--------|------|\n| 首次刷新 | 需要完整扫描，不支持跳过 |\n| 实时更新 | 初始版本不包含 SSE/live update |\n| 文件锁定 | 刷新期间目标文件需可写 |\n\n资料来源：[todos_120526.md:已知限制]()\n\n## 相关命令速查\n\n```bash\n# 刷新 Blueprint 状态\nblueprint refresh\n\n# 组级别更新\nblueprint group.update\n\n# 扫描代码库\nblueprint scan\n\n# 查看当前 Blueprint\nblueprint open\n```\n\n资料来源：[README.md:CLI Commands]()\n\n## 待确认的实现细节\n\n以下信息需要通过查阅实际源码确认：\n\n1. **刷新算法**：增量刷新的具体检测逻辑\n2. **并发控制**：多进程/线程下的状态一致性\n3. **错误处理**：文件系统变更异常的处理策略\n4. **缓存策略**：Inventory 缓存的有效期和失效机制\n\n---\n\n<a id='page-task-context'></a>\n\n## Task Context - 任务上下文构建\n\n### 相关页面\n\n相关主题：[工具系统概览](#page-tool-system), [Compose管道 - 最终输出生成](#page-compose-pipeline)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/lib/agent-instructions.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/agent-instructions.ts)\n- [AGENTS.md](https://github.com/engincankaya/blueprint/blob/main/AGENTS.md)\n- [frontend/src/components/blueprint/GroupDetailPanel.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/blueprint/GroupDetailPanel.tsx)\n- [frontend/src/components/BlueprintApp.tsx](https://github.com/engincankaya/blueprint/blob/main/frontend/src/components/BlueprintApp.tsx)\n- [src/viewer/render-html.ts](https://github.com/engincankaya/blueprint/blob/main/src/viewer/render-html.ts)\n</details>\n\n# Task Context - 任务上下文构建\n\n## 概述\n\nTask Context（任务上下文）是 Blueprint 项目中用于为 AI Agent 提供结构化架构记忆的核心机制。它通过构建和呈现项目架构信息，帮助 AI Agent 在执行代码探索和修改任务时获得必要的上下文理解，避免盲目搜索代码库。\n\nBlueprint 的任务上下文构建系统包含两个核心组成部分：\n\n1. **Brief 机制** - 通过 `.blueprint/brief.md` 提供项目级架构概览\n2. **Group Docs 机制** - 通过 `.blueprint/groups/*.md` 提供分组级的详细文档\n\n资料来源：[AGENTS.md]()()\n\n## 核心架构\n\n### 任务上下文构建流程\n\n```mermaid\ngraph TD\n    A[开始代码探索] --> B{Blueprint 记忆存在?}\n    B -->|是| C[读取 brief.md]\n    B -->|否| D[构建默认上下文]\n    C --> E[使用稳定章节标题定位]\n    E --> F[读取相关 Group Doc]\n    F --> G[切换到源码检查]\n    G --> H[执行开发任务]\n    D --> H\n```\n\n资料来源：[AGENTS.md:4-7]()\n\n### 上下文信息来源层级\n\nBlueprint 采用分层的信息组织方式，Agent 应遵循以下优先级：\n\n| 优先级 | 信息源 | 用途 | 读取策略 |\n|--------|--------|------|----------|\n| 1 | `.blueprint/brief.md` | 项目整体架构概览 | 始终读取 |\n| 2 | `.blueprint/groups/*.md` | 分组级架构文档 | 按需读取 |\n| 3 | 源码文件 | 实际实现细节 | 确定文件后切换 |\n\n资料来源：[AGENTS.md:1-7]()\n\n## Brief 机制\n\n### brief.md 的作用\n\n`brief.md` 是 Blueprint 项目架构记忆的入口点，它提供了项目的整体架构概述。根据 `agent-instructions.ts` 中的实现：\n\n```typescript\nexport function renderBlueprintAgentsSnippet(): string {\n  return [\n    beginMarker,\n    \"\",\n    \"## Blueprint MCP\",\n    \"\",\n    \"This project uses Blueprint MCP for local architecture memory.\",\n    \"\",\n    \"Before broad codebase exploration, read:\",\n    \"\",\n    \"`node_modules/blueprint-mcp-server/docs/agents.md`\",\n    \"\",\n    \"If Blueprint memory exists, start with:\",\n    \"\",\n    \"`.blueprint/brief.md`\",\n    \"\",\n    endMarker,\n  ].join(\"\\n\");\n}\n```\n\n资料来源：[src/lib/agent-instructions.ts:37-56]()\n\n该函数生成了一个 Blueprint Agent 片段，当 `AGENTS.md` 文件不存在时，会自动插入带有标记的 Blueprint 片段，引导 Agent 首先读取 `brief.md`。\n\n### Agent 指令snippet写入\n\nBlueprint 通过 `appendBlueprintAgentsSnippet` 函数在 `AGENTS.md` 文件中添加 Agent 指令：\n\n```typescript\nexport async function appendBlueprintAgentsSnippet(\n  path: string,\n  snippet: string,\n): Promise<{ path: string; changed: boolean }> {\n  const exists = await fileExists(path);\n  if (!exists) {\n    await writeFile(path, snippet + \"\\n\", \"utf-8\");\n    return { path, changed: false };\n  }\n  // ... 处理已存在文件的情况\n  await writeFile(path, `${current}${separator}${snippet}\\n`, \"utf-8\");\n  return { path, changed: true };\n}\n```\n\n资料来源：[src/lib/agent-instructions.ts:18-34]()\n\n## Group Docs 机制\n\n### 分组文档结构\n\nGroup Docs 位于 `.blueprint/groups/*.md`，遵循稳定的模板结构。在 `GroupDetailPanel.tsx` 中可以看到这些文档在 UI 中的呈现方式：\n\n```typescript\n// Overview 标签页\n{s.snapshot && (\n  <SectionCard title=\"Snapshot\" content={s.snapshot} defaultOpen index={0} />\n)}\n{s.responsibilities && (\n  <SectionCard title=\"Responsibilities\" content={s.responsibilities} defaultOpen index={1} />\n)}\n{s.keyFiles && (\n  <SectionCard title=\"Key Files\" content={s.keyFiles} index={2} />\n)}\n```\n\n资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx]()\n\n### 稳定章节标题\n\nGroup Doc 模板定义了以下稳定章节，Agent 可以直接跳转：\n\n| 章节名称 | 用途 | 优先级 |\n|----------|------|--------|\n| Snapshot | 快速定位和理解 | 默认展开 |\n| Responsibilities | 定义所有权和范围外区域 | 默认展开 |\n| Core Flow | 运行时行为和数据流 | 按需 |\n| Contracts & Invariants | 必须遵守的行为约束 | 重要 |\n| Key Files | 指向主要源文件 | 参考 |\n| Change Guide | 应该一起变更的文件或合约 | 实现检查清单 |\n| Pitfalls | 已知风险和常见错误 | 重要 |\n| Tests | 测试相关信息 | 参考 |\n\n资料来源：[AGENTS.md:6](), [GroupDetailPanel.tsx]()\n\n### UI 标签页结构\n\n在 `GroupDetailPanel.tsx` 中，任务上下文通过以下标签页呈现给用户：\n\n```typescript\nconst SUB_TABS = [\n  { id: \"overview\", label: \"Overview\" },\n  { id: \"files\", label: \"Files\" },\n  { id: \"connections\", label: \"Connections\" },\n  { id: \"architecture\", label: \"Architecture\" },\n  { id: \"guide\", label: \"Guide\" },\n];\n```\n\n资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx]()\n\n## 任务上下文构建的最佳实践\n\n### 推荐的阅读策略\n\n根据 Blueprint 的设计原则，Agent 应遵循以下策略：\n\n1. **优先读取 narrow 范围** - 使用搜索命中的前后 20-60 行窗口\n2. **使用稳定标题跳转** - 直接定位到 `Core Flow`、`Contracts & Invariants` 等章节\n3. **避免过早读取完整文档** - 仅在以下情况才阅读完整 Group Doc：\n   - 搜索结果不明确\n   - 任务涉及更改该分组的架构合约\n   - 需要章节结构作为实现检查清单\n   - 源码上下文在目标读取后仍不清晰\n\n4. **确定文件后切换到源码** - 识别相关源文件后，停止继续阅读 Blueprint，转向目标源码检查\n\n资料来源：[AGENTS.md:2-8]()\n\n### 上下文构建的默认预算\n\n| 类型 | 预算策略 |\n|------|----------|\n| `.blueprint/brief.md` | 始终读取 |\n| Blueprint Markdown 搜索 | 始终优先 |\n| Group Docs | 先读取目标摘录 |\n| 完整 Group Docs | 例外，非默认 |\n\n资料来源：[AGENTS.md:11-15]()\n\n## 渲染与呈现\n\n### 前端组件架构\n\nBlueprint 的前端通过 `BlueprintApp.tsx` 管理任务上下文的呈现：\n\n```typescript\n{activeTab.type === \"canvas\" ? (\n  <BlueprintCanvas overview={overview} activeGroupId={activeGroupId} onGroupClick={openGroup} />\n) : details[activeTab.group.id] ? (\n  <GroupDetailPanel detail={details[activeTab.group.id]} />\n) : (\n  <div className=\"flex h-full items-center justify-center bg-zinc-950 text-sm text-zinc-500\">\n    {detailErrors[activeTab.group.id]\n      ?? (detailLoading[activeTab.group.id] ? \"Loading group...\" : \"Waiting for group data...\")}\n  </div>\n)}\n```\n\n资料来源：[frontend/src/components/BlueprintApp.tsx]()\n\n### SectionCard 组件\n\n`SectionCard` 是展示任务上下文内容的核心 UI 组件，支持：\n\n- **可折叠展开** - 通过 `defaultOpen` 属性控制默认状态\n- **强调色支持** - 通过 `accent` 属性设置颜色主题\n- **预览模式** - 收起状态显示一行预览文本\n- **动画过渡** - 使用 Framer Motion 实现平滑展开/收起动画\n\n```typescript\nfunction SectionCard({\n  title,\n  content,\n  accent,\n  defaultOpen = false,\n  index = 0,\n}: {\n  title: string\n  content: string\n  accent?: 'amber' | 'red' | 'green' | 'blue' | 'zinc'\n  defaultOpen?: boolean\n  index?: number\n})\n```\n\n资料来源：[frontend/src/components/blueprint/GroupDetailPanel.tsx]()\n\n## 嵌入式 Viewer 渲染\n\n### HTML 内联渲染\n\nBlueprint 的 viewer 功能支持将 HTML 页面中的 CSS 和 JavaScript 内联化：\n\n```typescript\nasync function inlineStyles(html: string, viewerRoot: string): Promise<string> {\n  return await replaceAsync(\n    html,\n    /<link\\s+rel=\"stylesheet\"\\s+crossorigin\\s+href=\"([^\"]+)\">|<link\\s+rel=\"stylesheet\"\\s+href=\"([^\"]+)\">/g,\n    async (_match, crossoriginHref: string | undefined, href: string | undefined) => {\n      const assetPath = assetPathFromHref(crossoriginHref ?? href ?? \"\");\n      const css = await readFile(join(viewerRoot, assetPath), \"utf-8\");\n      return `<style>${css}</style>`;\n    },\n  );\n}\n```\n\n资料来源：[src/viewer/render-html.ts]()\n\n这确保了任务上下文的 HTML 导出可以在没有外部依赖的情况下正常工作。\n\n## 总结\n\nTask Context 系统是 Blueprint 项目架构的核心，它通过分层的信息组织（Brief + Group Docs）和稳定的文档模板，为 AI Agent 提供了可预测、可导航的架构记忆。Agent 应遵循\"先概览后深入\"的原则，优先使用搜索和章节跳转，而非盲目遍历整个代码库。\n\n---\n\n<a id='page-language-support'></a>\n\n## 语言支持与Tree-sitter集成\n\n### 相关页面\n\n相关主题：[Scan管道 - 文件清单与分析](#page-scan-pipeline)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/languages/registry.ts](https://github.com/engincankaya/blueprint/blob/main/src/languages/registry.ts)\n- [src/languages/types.ts](https://github.com/engincankaya/blueprint/blob/main/src/languages/types.ts)\n- [src/languages/typescript/normalizer.ts](https://github.com/engincankaya/blueprint/blob/main/src/languages/typescript/normalizer.ts)\n- [src/languages/python/normalizer.ts](https://github.com/engincankaya/blueprint/blob/main/src/languages/python/normalizer.ts)\n- [src/lib/tree-sitter-loader.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/tree-sitter-loader.ts)\n</details>\n\n# 语言支持与Tree-sitter集成\n\n## 概述\n\nBlueprint项目的语言支持系统基于Tree-sitter构建，为多种编程语言提供统一的代码解析、符号提取、导入/导出分析能力。该系统采用插件化架构，通过语言注册表（Language Registry）管理不同语言的分析器，并使用标准化的类型定义确保各语言模块之间的互操作性。\n\n## 核心架构\n\n### 系统组件关系\n\n```mermaid\ngraph TD\n    subgraph \"语言支持层\"\n        Registry[语言注册表<br/>registry.ts]\n        Types[类型定义<br/>types.ts]\n    end\n    \n    subgraph \"语言分析器\"\n        TSNormalizer[TypeScript Normalizer<br/>normalizer.ts]\n        PyNormalizer[Python Normalizer<br/>normalizer.ts]\n    end\n    \n    subgraph \"基础设施\"\n        Loader[Tree-sitter加载器<br/>tree-sitter-loader.ts]\n        Scanner[文件扫描器<br/>scan-file-inventory-builder.ts]\n        Analyzer[代码分析引擎<br/>scan-code-analysis-engine.ts]\n    end\n    \n    Registry --> TSNormalizer\n    Registry --> PyNormalizer\n    Loader --> Registry\n    Scanner --> Registry\n    Analyzer --> Registry\n    Analyzer --> Loader\n```\n\n### 语言注册表机制\n\n语言注册表（`src/languages/registry.ts`）是整个语言支持系统的核心枢纽，负责：\n\n- 注册各语言对应的Tree-sitter语法分析器实例\n- 管理语言与文件扩展名的映射关系\n- 提供语言特定配置的查询接口\n- 支持运行时语言模块的动态加载\n\n```mermaid\ngraph LR\n    A[文件扫描] --> B{识别扩展名}\n    B --> C[查询注册表]\n    C --> D{语言已注册?}\n    D -->|是| E[返回分析器]\n    D -->|否| F[加载对应语言模块]\n    F --> E\n```\n\n## 类型系统\n\n类型定义文件（`src/languages/types.ts`）为整个语言分析管道提供统一的数据模型：\n\n### 关键类型\n\n| 类型名称 | 用途 | 包含字段 |\n|---------|------|---------|\n| `FileInventory` | 文件清单元数据 | `rootPath`, `files[]`, `summary` |\n| `AnalysisFacts` | 代码分析结果 | `symbols{}`, `imports[]`, `exports[]` |\n| `ImportInfo` | 导入信息 | `rawSpecifier`, `kind`, `importedSymbols[]` |\n| `ExportInfo` | 导出信息 | 依赖具体语言语义 |\n| `SymbolInfo` | 符号信息 | `name`, `type`, `location` |\n\n### FileInventory结构\n\n```typescript\ninterface FileInventory {\n  rootPath: string;           // 项目根路径\n  files: FileEntry[];         // 所有文件条目\n  summary: {\n    totalFiles: number;       // 总文件数\n    parseableFiles: number;   // 可解析文件数\n    metadataOnlyFiles: number; // 仅元数据文件数\n  };\n}\n```\n\n## Tree-sitter集成\n\n### 加载器机制\n\nTree-sitter加载器（`src/lib/tree-sitter-loader.ts`）负责：\n\n- 初始化Tree-sitter语言包\n- 管理语法树缓存\n- 处理跨语言的解析错误\n- 提供异步解析接口\n\n### 解析流程\n\n```mermaid\nsequenceDiagram\n    participant 调用方\n    participant Loader as Tree-sitter加载器\n    participant Parser as Tree-sitter解析器\n    participant Normalizer as 语言标准化器\n    \n    调用方->>Loader: 请求解析文件\n    Loader->>Parser: 创建解析实例\n    Parser->>Parser: 执行语法解析\n    Parser-->>Loader: 返回SyntaxNode树\n    Loader-->>调用方: 提供解析结果\n    调用方->>Normalizer: 提取语义信息\n    Normalizer-->>调用方: 返回ImportInfo/ExportInfo\n```\n\n## Python语言分析\n\nPython语言标准化器（`src/languages/python/normalizer.ts`）处理Python特有的代码结构：\n\n### 导入分析\n\nPython的`import`语句解析需要处理多种语法变体：\n\n```mermaid\ngraph TD\n    A[import语句] --> B{import类型}\n    B -->|import x| C[单模块导入]\n    B -->|import x as y| D[别名导入]\n    B -->|from x import y| E[从模块导入]\n    B -->|from x import *| F[通配符导入]\n    \n    C --> G[符号: x]\n    D --> H[符号: y]\n    E --> I[符号: y]\n    F --> J[符号: *]\n```\n\n### 导出分析\n\nPython没有显式的`export`关键字，系统通过以下规则推断导出：\n\n1. 模块级公共名称（不以`_`开头）\n2. `__all__`列表中定义的名称\n3. 装饰器标记的公共函数和类\n\n资料来源：[src/languages/python/normalizer.ts:70-90]()\n\n```typescript\n// 公共名称判断逻辑\nif (name && !name.startsWith(\"_\")) {\n  publicNames.push(name);\n}\n```\n\n### AST节点处理\n\n标准化器遍历语法树时处理以下节点类型：\n\n| 节点类型 | 处理方式 |\n|---------|---------|\n| `import_statement` | 提取所有导入符号 |\n| `import_from_statement` | 解析`from ... import`结构 |\n| `dotted_name` | 收集点分名称组件 |\n| `aliased_import` | 记录别名映射 |\n| `wildcard_import` | 记录通配符导入 |\n| `decorated_definition` | 处理带装饰器的定义 |\n\n## TypeScript语言分析\n\nTypeScript标准化器（`src/languages/typescript/normalizer.ts`）处理TypeScript/JavaScript的代码结构：\n\n### 符号提取\n\n- 解析函数定义、类定义、接口定义\n- 提取类型参数和访问修饰符\n- 处理命名空间和模块声明\n\n### 导入/导出处理\n\n- `import`声明的标准解析\n- `export`声明的类型区分\n- `export =`和`export default`的兼容性处理\n- 命名空间导入的别名处理\n\n## 文件分类系统\n\nBlueprint通过文件扫描器（`src/tools/scan/scan-file-inventory-builder.ts`）对项目文件进行分类：\n\n### 分类规则\n\n| 分类 | 判断条件 |\n|-----|---------|\n| `test` | 文件名包含`.test.`, `.spec.`, `__tests__`目录, `test/`目录 |\n| `lockfile` | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Cargo.lock` |\n| `config` | `.gitignore`, `package.json`, `tsconfig.json`, `.config.ts/.js` |\n| `documentation` | `docs/`目录, `README.md`, `.md`文件 |\n| `script` | `scripts/`目录, `.sh`文件, shell语言 |\n| `asset` | `assets/`, `public/`目录, html/css/svg文件 |\n| `generated` | `generated/`, `__generated__/`目录 |\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts:20-70]()\n\n### 文件角色标注\n\n根据文件在项目中的位置和用途，系统为每个文件分配角色标签：\n\n- `core`: 核心业务逻辑\n- `interface`: 接口定义\n- `implementation`: 具体实现\n- `test`: 测试代码\n- `config`: 配置文件\n- `utility`: 工具函数\n- `unknown`: 未能识别的角色\n\n## 分析结果验证\n\n代码分析引擎（`src/tools/scan/scan-code-analysis-engine.ts`）生成的分析结果包含验证信息：\n\n```typescript\ninterface Validation {\n  isComplete: boolean;           // 分析是否完整\n  inventoryFiles: number;       // 清单文件数\n  parseableFiles: number;        // 可解析文件数\n  parsedFiles: number;           // 实际解析文件数\n  metadataOnlyFiles: number;    // 仅元数据文件数\n  skippedMetadataOnlyFiles: number; // 跳过的元数据文件\n  parseErrors: number;           // 解析错误数\n  unaccountedFiles: string[];    // 未纳入分析的文件\n}\n```\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts:30-45]()\n\n## 扩展语言支持\n\n### 添加新语言步骤\n\n1. 在`src/languages/`下创建`<language>/normalizer.ts`\n2. 实现`extractImports`和`extractExports`函数\n3. 在注册表中注册新的语言模块\n4. 添加对应的文件扩展名映射\n5. 编写测试用例验证解析正确性\n\n### 语言配置接口\n\n```typescript\ninterface LanguageConfig {\n  id: string;              // 语言标识符\n  name: string;           // 显示名称\n  extensions: string[];   // 文件扩展名\n  treeSitterLanguage: string;  // Tree-sitter语言包名\n  normalizer: Normalizer;  // 标准化器实例\n}\n```\n\n## 技术限制与注意事项\n\n### 当前限制\n\n- Tree-sitter解析依赖于预编译的语言包，加载大型项目时可能有内存压力\n- Python的动态特性（如`exec`、`__getattr__`）无法静态分析\n- TypeScript的类型系统部分特性（如条件类型）在编译时可能无法完全解析\n\n### 最佳实践\n\n1. 保持Tree-sitter语言包版本与主包一致\n2. 对于不支持的文件类型，系统会自动降级为仅元数据模式\n3. 定期更新语言解析器以支持新的语法特性\n\n## 相关文件索引\n\n| 文件路径 | 功能描述 |\n|---------|---------|\n| `src/languages/registry.ts` | 语言注册与管理中心 |\n| `src/languages/types.ts` | 统一类型定义 |\n| `src/languages/python/normalizer.ts` | Python代码标准化 |\n| `src/languages/typescript/normalizer.ts` | TypeScript代码标准化 |\n| `src/lib/tree-sitter-loader.ts` | Tree-sitter运行时加载 |\n| `src/tools/scan/scan-file-inventory-builder.ts` | 文件扫描与分类 |\n| `src/tools/scan/scan-code-analysis-engine.ts` | 代码分析引擎 |\n\n---\n\n<a id='page-data-storage'></a>\n\n## 数据存储与路径管理\n\n### 相关页面\n\n相关主题：[Scan管道 - 文件清单与分析](#page-scan-pipeline), [Compose管道 - 最终输出生成](#page-compose-pipeline)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/lib/blueprint-paths.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/blueprint-paths.ts)\n- [src/lib/artifact-store.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/artifact-store.ts)\n- [src/lib/group-docs.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/group-docs.ts)\n- [src/lib/brief-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/brief-builder.ts)\n- [src/tools/compose/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)\n- [src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n- [src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n</details>\n\n# 数据存储与路径管理\n\n## 概述\n\nBlueprint 项目的数据存储与路径管理系统是整个架构的核心基础设施，负责管理项目内存文件的生成、存储、读取和维护。该系统采用本地文件系统作为默认存储后端，将架构记忆以结构化 JSON 和 Markdown 文件的形式持久化到用户项目的 `.blueprint/` 目录中。\n\nBlueprint 的存储架构遵循以下核心原则：\n\n- **本地优先**：所有数据默认存储在用户项目的 `.blueprint/` 目录中\n- **确定性维护**：使用 Tree-sitter 分析和文件系统哈希快照确保增量更新的准确性\n- **源码头信任**：源码是最终事实依据，Blueprint 文档仅为方向性参考\n- **工具驱动**：不直接编辑生成的 JSON 文件，通过 MCP 工具进行确定性维护\n\n资料来源：[README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)\n\n## 核心组件\n\n### BlueprintPaths 路径管理模块\n\n`BlueprintPaths` 模块负责定义和管理 Blueprint 相关的所有文件系统路径。该模块封装了路径解析逻辑，为其他模块提供统一的路径访问接口。\n\n| 属性 | 说明 | 默认值 |\n|------|------|--------|\n| `projectRoot` | 用户项目根目录 | 当前工作目录 |\n| `blueprintDir` | Blueprint 内存目录 | `.blueprint/` |\n| `briefPath` | 项目概述文档路径 | `.blueprint/brief.md` |\n| `groupsDir` | 分组文档目录 | `.blueprint/groups/` |\n| `outputJsonPath` | 结构化输出 JSON 路径 | `.blueprint/blueprint-output.json` |\n| `indexHtmlPath` | 静态查看器 HTML 路径 | `.blueprint/index.html` |\n| `refreshScanJsonPath` | 刷新扫描哈希快照路径 | `.blueprint/refresh-scan.json` |\n\n路径模块还负责生成 Agent 说明文件路径，该文件包含 Blueprint MCP 的使用指引。\n\n资料来源：[src/lib/blueprint-paths.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/blueprint-paths.ts)\n\n### ArtifactStore 工件存储\n\n`ArtifactStore` 是 Blueprint 的核心数据存储抽象层，提供类型安全的工件存取接口。每个工件（Artifact）都具有唯一的标识符，支持版本追踪和类型验证。\n\n```typescript\ninterface Artifact {\n  id: string;\n  type: string;\n  data: unknown;\n  metadata: {\n    createdAt: number;\n    updatedAt: number;\n    version: number;\n  };\n}\n```\n\n#### 存储操作接口\n\n| 方法 | 功能 | 返回类型 |\n|------|------|----------|\n| `store(artifact)` | 存储新工件 | `string` (工件ID) |\n| `get(id)` | 根据ID获取工件 | `Artifact \\| undefined` |\n| `getTyped(id, type, expectedType)` | 类型安全获取 | `T \\| undefined` |\n| `update(id, data)` | 更新现有工件 | `boolean` |\n| `delete(id)` | 删除工件 | `boolean` |\n| `list()` | 列出所有工件 | `Artifact[]` |\n| `clear()` | 清空存储 | `void` |\n\n`getTyped` 方法是类型安全访问的核心，它在返回数据前验证工件类型是否符合预期。如果类型不匹配，返回 `undefined` 并记录警告。\n\n资料来源：[src/lib/artifact-store.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/artifact-store.ts)\n\n### FileInventory 文件清单\n\n`FileInventory` 是扫描阶段生成的文件清单数据结构，包含项目的完整文件列表和元数据。\n\n```typescript\ninterface FileInventory {\n  rootPath: string;\n  files: FileEntry[];\n  summary: {\n    totalFiles: number;\n    parseableFiles: number;\n    metadataOnlyFiles: number;\n  };\n}\n\ninterface FileEntry {\n  absolutePath: string;\n  relativePath: string;\n  language: string;\n  analysisLevel: 'parseable' | 'metadata-only';\n  size: number;\n  category?: FileCategory;\n}\n```\n\n文件分类通过 `FileCategory` 枚举区分：\n\n| 分类 | 说明 | 判定规则 |\n|------|------|----------|\n| `source` | 源代码文件 | `.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.go`, `.rs`, `.java` |\n| `test` | 测试文件 | `.test.ts`, `.spec.ts`, `test/`, `tests/` 目录 |\n| `config` | 配置文件 | `package.json`, `tsconfig.json`, `.config.js` |\n| `documentation` | 文档文件 | `readme.md`, `.md`, `docs/` 目录 |\n| `script` | 脚本文件 | `.sh`, `scripts/` 目录 |\n| `asset` | 静态资源 | `.svg`, `.css`, `assets/`, `public/` 目录 |\n| `lockfile` | 锁文件 | `package-lock.json`, `yarn.lock`, `Cargo.lock` |\n\n资料来源：[src/tools/scan/scan-file-inventory-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-file-inventory-builder.ts)\n\n### GroupDocs 分组文档管理\n\n`GroupDocs` 模块负责管理 `.blueprint/groups/*.md` 中的分组文档。这些 Markdown 文件记录了每个架构分组的详细信息，包括核心流程、契约、不变式和测试指南等。\n\n分组文档模板结构：\n\n| 章节 | 说明 | 必填 |\n|------|------|------|\n| `Snapshot` | 快速概览和摘要 | 建议 |\n| `Responsibilities` | 所有权和范围定义 | 建议 |\n| `Core Flow` | 运行时行为和数据流 | 建议 |\n| `Contracts & Invariants` | 必须保持的行为契约 | 建议 |\n| `Key Files` | 指向主要源文件 | 建议 |\n| `Change Guide` | 变更协同文件列表 | 可选 |\n| `Pitfalls` | 已知风险和常见错误 | 可选 |\n| `Tests` | 相关验证测试 | 可选 |\n| `Debugging` | 故障排查提示 | 可选 |\n| `Extension / Open Questions` | 不确定性和已知缺口 | 可选 |\n\n资料来源：[src/lib/group-docs.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/group-docs.ts)\n\n### BriefBuilder 概述文档构建\n\n`BriefBuilder` 负责生成 `.blueprint/brief.md` 项目概述文档。该文档提供项目的全局架构视图，包括：\n\n- 项目概述和架构分组成员\n- 路由提示和入口点\n- 关键文件列表\n- 分组文档路径引用\n\nBrief 文档是 Agent 开始探索代码库时的首要参考资源，应当保持简洁且与当前 Blueprint 输出同步。\n\n资料来源：[src/lib/brief-builder.ts](https://github.com/engincankaya/blueprint/blob/main/src/lib/brief-builder.ts)\n\n## 数据流架构\n\n### 整体工作流\n\n```mermaid\ngraph TD\n    A[用户项目] --> B[blueprint.scan]\n    B --> C[FileInventory]\n    C --> D[blueprint.group]\n    D --> E[GroupingResult]\n    E --> F[blueprint.compose]\n    F --> G[BlueprintOutput]\n    G --> H[.blueprint/brief.md]\n    G --> I[.blueprint/groups/*.md]\n    G --> J[blueprint-output.json]\n    J --> K[blueprint open]\n    K --> L[.blueprint/index.html]\n    \n    M[源码变更] --> N[blueprint.refresh]\n    N --> O[refresh-scan.json]\n    O --> P{哈希对比}\n    P -->|检测到变更| Q[更新受影响分组]\n    P -->|无变更| R[跳过]\n```\n\n### 扫描与代码分析流程\n\n```mermaid\ngraph LR\n    A[文件系统] -->|readFile| B[scan-code-analysis-engine]\n    B --> C{语言类型}\n    C -->|TypeScript/JS| D[Tree-sitter Parser]\n    C -->|Python| E[Tree-sitter Parser]\n    C -->|Go| F[Tree-sitter Parser]\n    C -->|Rust| G[Tree-sitter Parser]\n    C -->|Java| H[Tree-sitter Parser]\n    C -->|其他| I[元数据仅存]\n    \n    D --> J[AnalysisFacts]\n    E --> J\n    F --> J\n    G --> J\n    H --> J\n    I --> J\n    \n    J --> K[符号表]\n    J --> L[导入关系]\n    J --> M[依赖图]\n    J --> N[解析错误]\n```\n\n### Compose 阶段数据转换\n\n```mermaid\ngraph TD\n    A[GroupingResult] --> B[ComposeTool]\n    C[FileInventory] --> B\n    D[AnalysisFacts] --> B\n    \n    B --> E[ComposeOutputBuilder]\n    E --> F[ComposeArtifactWriter]\n    F --> G[blueprint.v1 结构]\n    \n    G --> H[brief.md]\n    G --> I[groups/*.md]\n    G --> J[blueprint-output.json]\n    G --> K[AGENTS.md 补丁]\n```\n\n`ComposeTool` 协调多个构建器完成最终输出：\n\n1. **ComposeOutputBuilder**：构建前端可用的 Blueprint JSON 结构\n2. **ComposeArtifactWriter**：将构建结果写入文件系统\n3. **ComposeEntrypointDetector**：检测项目入口点并关联\n\n资料来源：[src/tools/compose/index.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/compose/index.ts)\n\n## AnalysisFacts 数据结构\n\n`AnalysisFacts` 是代码分析阶段生成的核心数据结构，汇总了所有代码解析结果。\n\n```typescript\ninterface AnalysisFacts {\n  inventoryArtifactId: string;\n  rootPath: string;\n  files: Record<string, FileAnalysis>;\n  symbols: Record<string, SymbolInfo>;\n  imports: ImportEntry[];\n  exports: ExportEntry[];\n  dependencies: DependencyEdge[];\n  unresolvedImports: UnresolvedImport[];\n  parseErrors: ParseError[];\n  summary: AnalysisSummary;\n  validation: ValidationState;\n}\n```\n\n#### ValidationState 验证状态\n\n| 字段 | 说明 | 用途 |\n|------|------|------|\n| `isComplete` | 分析是否完成 | 状态标志 |\n| `inventoryFiles` | 清单文件总数 | 完整性检查 |\n| `parseableFiles` | 可解析文件数 | 解析覆盖率 |\n| `parsedFiles` | 实际解析文件数 | 进度追踪 |\n| `metadataOnlyFiles` | 元数据文件数 | 未分析文件 |\n| `skippedMetadataOnlyFiles` | 跳过的元数据文件 | 分析决策记录 |\n| `parseErrors` | 解析错误数 | 质量指标 |\n| `unaccountedFiles` | 未归属文件列表 | 完整性审计 |\n\n资料来源：[src/tools/scan/scan-code-analysis-engine.ts](https://github.com/engincankaya/blueprint/blob/main/src/tools/scan/scan-code-analysis-engine.ts)\n\n## 存储路径配置\n\n### 目录结构\n\n```\nproject-root/\n├── .blueprint/\n│   ├── brief.md                    # 项目概述文档\n│   ├── blueprint-output.json       # 结构化输出数据\n│   ├── refresh-scan.json           # 文件系统哈希快照\n│   ├── index.html                  # 静态查看器\n│   └── groups/\n│       ├── frontend.md             # 前端分组文档\n│       ├── backend.md              # 后端分组文档\n│       └── shared.md               # 共享模块文档\n└── src/                            # 用户源代码\n```\n\n### 路径解析优先级\n\n```mermaid\ngraph TD\n    A[路径请求] --> B{存在自定义配置?}\n    B -->|是| C[使用配置的路径]\n    B -->|否| D{环境变量 BLUEPRINT_DIR?}\n    D -->|是| E[使用环境变量值]\n    D -->|否| F{命令行参数 --dir?}\n    F -->|是| G[使用命令行值]\n    F -->|否| H[使用默认 .blueprint/]\n    \n    C --> Z[解析完成]\n    E --> Z\n    G --> Z\n    H --> Z\n```\n\n## MCP 工具集成\n\nBlueprint MCP 提供四个主要工具用于存储和路径管理：\n\n| 工具 | 用途 | 影响文件 |\n|------|------|----------|\n| `blueprint.scan` | 构建文件清单和代码分析 | 生成扫描缓存 |\n| `blueprint.group` | 准备或应用语义分组 | 更新分组状态 |\n| `blueprint.compose` | 写入最终 Blueprint 输出 | `brief.md`, `groups/*.md`, `blueprint-output.json` |\n| `blueprint.refresh` | 从当前文件系统快照刷新 | 更新哈希快照 |\n| `blueprint.group.update` | 分配未分配文件 | 更新分组配置 |\n\n### 工具调用流程\n\n```mermaid\nsequenceDiagram\n    participant U as 用户/Agent\n    participant M as MCP Server\n    participant A as ArtifactStore\n    participant F as 文件系统\n\n    U->>M: blueprint.scan\n    M->>F: 扫描项目文件\n    F-->>M: FileInventory\n    M->>A: store(FileInventory)\n    A-->>M: artifactId\n    \n    U->>M: blueprint.group with mode: prepare\n    M->>A: get(inventoryArtifactId)\n    A-->>M: FileInventory\n    M->>F: 分析分组建议\n    F-->>M: GroupingResult\n    M->>A: store(GroupingResult)\n    \n    U->>M: blueprint.compose\n    M->>A: get(groupingArtifactId)\n    A-->>M: GroupingResult\n    M->>F: 写入 .blueprint/ 目录\n    F-->>M: 写入完成\n```\n\n## 静态查看器渲染\n\nBlueprint 的静态查看器使用嵌入式数据渲染模式：\n\n```mermaid\ngraph TD\n    A[blueprint-output.json] --> B[Renderer]\n    C[brief.md] --> B\n    D[groups/*.md] --> B\n    B --> E[index.html]\n    E --> F[浏览器]\n    F --> G[显示架构视图]\n```\n\n查看器特点：\n\n- **独立 HTML**：无需 HTTP 服务器即可查看\n- **嵌入式数据**：JSON 数据直接嵌入 HTML 文件\n- **自包含**：所有样式和脚本内联\n- **无外部依赖**：不依赖网络资源\n\n资料来源：[README.md](https://github.com/engincankaya/blueprint/blob/main/README.md)\n\n## 维护与更新策略\n\n### 确定性刷新机制\n\nBlueprint 使用文件系统哈希快照进行确定性刷新：\n\n1. 扫描阶段计算所有源文件的哈希值\n2. 将哈希快照存储在 `refresh-scan.json`\n3. 刷新时重新计算哈希并对比\n4. 仅更新发生变化的文件关联\n\n```mermaid\ngraph TD\n    A[refresh-scan.json] --> B[当前哈希计算]\n    B --> C{与快照对比}\n    C -->|有变更| D[识别受影响分组]\n    C -->|无变更| E[跳过更新]\n    D --> F[blueprint.group.update]\n    F --> G[更新分组关联]\n    G --> H[写入新快照]\n```\n\n### 文件分类变更处理\n\n当文件移动、删除或新增时：\n\n| 变更类型 | 处理方式 | 触发操作 |\n|----------|----------|----------|\n| 新增文件 | 检查分组归属 | `blueprint.group.update` |\n| 删除文件 | 从分组移除 | 自动清理 |\n| 移动文件 | 更新相对路径 | 重新分析关联 |\n| 重命名文件 | 视为删除+新增 | 完整重新关联 |\n\n### 分组文档同步\n\n分组文档应随源码变更同步更新：\n\n- 仅在架构契约、契约、不变式、陷阱或测试指导变更时更新\n- 保持 `.blueprint/brief.md` 与当前 Blueprint 输出同步\n- 不要将完整源码详情复制到 Markdown 文档\n- 记录稳定的架构事实、契约和测试指导\n\n## 最佳实践\n\n### 路径使用规范\n\n1. **始终使用 BlueprintPaths 模块**：不要硬编码路径字符串\n2. **类型安全访问**：优先使用 `getTyped()` 方法\n3. **验证工件存在**：在访问前检查 `undefined` 情况\n\n### 数据一致性维护\n\n```mermaid\ngraph LR\n    A[源码变更] -->|blueprint.refresh| B{检测变更}\n    B -->|分组结构变更| C[更新 groups/*.md]\n    B -->|文档结构变更| D[更新 brief.md]\n    B -->|两者都变| E[更新两者]\n    B -->|无变更| F[无需操作]\n```\n\n### 避免的操作\n\n- 手动编辑 `blueprint-output.json`\n- 跳过 `blueprint.refresh` 直接修改源码\n- 将大量源码细节复制到分组文档\n- 在分组文档与源码冲突时信任文档\n\n## 总结\n\nBlueprint 的数据存储与路径管理系统通过模块化设计和确定性工具链，实现了架构记忆的可靠管理和自动同步。核心组件包括：\n\n- **BlueprintPaths**：提供统一的路径解析接口\n- **ArtifactStore**：实现类型安全的工件存储抽象\n- **FileInventory**：维护项目的完整文件清单\n- **GroupDocs**：管理分组 Markdown 文档\n- **BriefBuilder**：构建项目概述文档\n\n整个系统以源码为最终事实依据，通过 MCP 工具驱动进行确定性维护，确保架构文档始终反映当前代码库的真实状态。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：engincankaya/blueprint\n\n摘要：发现 6 个潜在踩坑项，其中 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:1230090802 | https://github.com/engincankaya/blueprint | 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:1230090802 | https://github.com/engincankaya/blueprint | 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:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium\n\n## 5. 维护坑 · 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:1230090802 | https://github.com/engincankaya/blueprint | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | release_recency=unknown\n\n<!-- canonical_name: engincankaya/blueprint; human_manual_source: deepwiki_human_wiki -->\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项目：engincankaya/blueprint\n\n摘要：发现 6 个潜在踩坑项，其中 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:1230090802 | https://github.com/engincankaya/blueprint | 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:1230090802 | https://github.com/engincankaya/blueprint | 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:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1230090802 | https://github.com/engincankaya/blueprint | no_demo; severity=medium\n\n## 5. 维护坑 · 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:1230090802 | https://github.com/engincankaya/blueprint | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1230090802 | https://github.com/engincankaya/blueprint | release_recency=unknown\n",
      "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
      "title": "Pitfall Log / 踩坑日志"
    },
    "prompt_preview": {
      "asset_id": "prompt_preview",
      "filename": "PROMPT_PREVIEW.md",
      "markdown": "# blueprint - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 blueprint 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Architecture-aware MCP server that analyzes codebases with Tree-sitter and generates Blueprint memory for  LLM coding agents. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-tool-system：工具系统概览。围绕“工具系统概览”模拟一次用户任务，不展示安装或运行结果。\n4. page-scan-pipeline：Scan管道 - 文件清单与分析。围绕“Scan管道 - 文件清单与分析”模拟一次用户任务，不展示安装或运行结果。\n5. page-group-pipeline：Group管道 - 语义分组。围绕“Group管道 - 语义分组”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-tool-system\n输入：用户提供的“工具系统概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-scan-pipeline\n输入：用户提供的“Scan管道 - 文件清单与分析”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-group-pipeline\n输入：用户提供的“Group管道 - 语义分组”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-tool-system：Step 3 必须围绕“工具系统概览”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-scan-pipeline：Step 4 必须围绕“Scan管道 - 文件清单与分析”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-group-pipeline：Step 5 必须围绕“Group管道 - 语义分组”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/engincankaya/blueprint\n- https://github.com/engincankaya/blueprint#readme\n- README.md\n- AGENTS.md\n- src/index.ts\n- src/tools/init-tools.ts\n- src/types.ts\n- src/lib/artifact-store.ts\n- src/tools/scan/index.ts\n- src/tools/scan/scan-file-inventory-builder.ts\n- src/tools/scan/scan-code-analysis-engine.ts\n- src/tools/group/index.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 blueprint 的核心服务。\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项目：engincankaya/blueprint\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -g blueprint-mcp-server\n```\n\n来源：https://github.com/engincankaya/blueprint#readme\n\n## 来源\n\n- repo: https://github.com/engincankaya/blueprint\n- docs: https://github.com/engincankaya/blueprint#readme\n",
      "summary": "从项目官方 README 或安装文档提取的开工入口。",
      "title": "Quick Start / 官方入口"
    }
  },
  "validation_id": "dval_b24e4e869d9c46e0b432673d5547fcbd"
}