{
"canonical_name": "Inferensys/contextful",
"compilation_id": "pack_235cb6e69712474abca1541ca98c9956",
"created_at": "2026-05-16T04:52:53.224695+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, 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 `npx @inferensys/contextful` 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": "npx @inferensys/contextful",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_81c822c974f54856a37fab77c6cb7ef9"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_6d1d87fdbc61f0de69507804647868c0",
"canonical_name": "Inferensys/contextful",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/Inferensys/contextful",
"slug": "contextful",
"source_packet_id": "phit_c356bced3c75459ebd1856c19e32d434",
"source_validation_id": "dval_a57d47da1eb34bfc9406efeb91587234"
},
"merchandising": {
"best_for": "需要信息检索与知识管理能力，并使用 claude的用户",
"github_forks": 0,
"github_stars": 0,
"one_liner_en": "Most-efficient Context Management Layer for Agentic AI. Graph-based knowledge context, SQLite index, advanced FTS5 lexical/BM25 search and cross-session live memory.",
"one_liner_zh": "Most-efficient Context Management Layer for Agentic AI. Graph-based knowledge context, SQLite index, advanced FTS5 lexical/BM25 search and cross-session live memory.",
"primary_category": {
"category_id": "research-knowledge",
"confidence": "high",
"name_en": "Research & Knowledge",
"name_zh": "信息检索与知识管理",
"reason": "matched_keywords:knowledge, graph, search"
},
"target_user": "使用 claude, claude_code 等宿主 AI 的用户",
"title_en": "contextful",
"title_zh": "contextful 能力包",
"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": "Plugin Ecosystem",
"label_zh": "插件生态",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-plugin-ecosystem",
"type": "selection_signal"
}
]
},
"packet_id": "phit_c356bced3c75459ebd1856c19e32d434",
"page_model": {
"artifacts": {
"artifact_slug": "contextful",
"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": "npx @inferensys/contextful",
"label": "Node.js / npx · 官方安装入口",
"source": "https://github.com/Inferensys/contextful#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"插件生态"
],
"eyebrow": "信息检索与知识管理",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要信息检索与知识管理能力，并使用 claude的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Most-efficient Context Management Layer for Agentic AI. Graph-based knowledge context, SQLite index, advanced FTS5 lexical/BM25 search and cross-session live memory."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "claude, claude_code",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:1240001007 | https://github.com/Inferensys/contextful | host_targets=claude, claude_code"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1240001007 | https://github.com/Inferensys/contextful | 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:1240001007 | https://github.com/Inferensys/contextful | 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:1240001007 | https://github.com/Inferensys/contextful | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1240001007 | https://github.com/Inferensys/contextful | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1240001007 | https://github.com/Inferensys/contextful | 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:1240001007 | https://github.com/Inferensys/contextful | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 1,
"forks": 0,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 0
},
"source_url": "https://github.com/Inferensys/contextful",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Most-efficient Context Management Layer for Agentic AI. Graph-based knowledge context, SQLite index, advanced FTS5 lexical/BM25 search and cross-session live memory.",
"title": "contextful 能力包",
"trial_prompt": "# contextful - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 contextful 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：claude / Claude Code\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Most-efficient Context Management Layer for Agentic AI. Graph-based knowledge context, SQLite index, advanced FTS5 lexical/BM25 search and cross-session live memory. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-1：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-2：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-3：搜索系统。围绕“搜索系统”模拟一次用户任务，不展示安装或运行结果。\n4. page-4：上下文包系统。围绕“上下文包系统”模拟一次用户任务，不展示安装或运行结果。\n5. page-7：MCP 服务器集成。围绕“MCP 服务器集成”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-1\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-2\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-3\n输入：用户提供的“搜索系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-4\n输入：用户提供的“上下文包系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-7\n输入：用户提供的“MCP 服务器集成”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-1：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-2：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-3：Step 3 必须围绕“搜索系统”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-4：Step 4 必须围绕“上下文包系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-7：Step 5 必须围绕“MCP 服务器集成”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/Inferensys/contextful\n- https://github.com/Inferensys/contextful#readme\n- README.md\n- package.json\n- src/types.ts\n- src/mcp-server.ts\n- src/indexer.ts\n- src/cli.ts\n- src/index.ts\n- src/search.ts\n- src/db.ts\n- src/extract.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 contextful 的核心服务。\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": "Most-efficient Context Management Layer for Agentic AI. Graph-based knowledge context, SQLite index, advanced FTS5 lexical/BM25 search and cross-session live memory.",
"effort": "安装已验证",
"forks": 0,
"icon": "search",
"name": "contextful 能力包",
"risk": "需复核",
"slug": "contextful",
"stars": 0,
"tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"插件生态"
],
"thumb": "blue",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/Inferensys/contextful 项目说明书\n\n生成时间：2026-05-16 04:01:04 UTC\n\n## 目录\n\n- [项目概述](#page-1)\n- [系统架构](#page-2)\n- [搜索系统](#page-3)\n- [上下文包系统](#page-4)\n- [内存分类账](#page-5)\n- [数据存储与索引](#page-6)\n- [MCP 服务器集成](#page-7)\n- [解析与代码提取](#page-8)\n- [CLI 命令行工具](#page-9)\n- [部署与配置](#page-10)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-2), [数据存储与索引](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Inferensys/contextful/blob/main/README.md)\n- [package.json](https://github.com/Inferensys/contextful/blob/main/package.json)\n- [src/cli.ts](https://github.com/Inferensys/contextful/blob/main/src/cli.ts)\n- [src/search.ts](https://github.com/Inferensys/contextful/blob/main/src/search.ts)\n- [src/mcp-server.ts](https://github.com/Inferensys/contextful/blob/main/src/mcp-server.ts)\n- [src/report.ts](https://github.com/Inferensys/contextful/blob/main/src/report.ts)\n \n\n# 项目概述\n\n## 项目简介\n\n**Contextful**（也称 `cxf` 或 `contextful`）是一个本地代码索引与上下文检索系统，专为 AI 编程助手设计。该项目由 Inferensys 团队开发，旨在解决大型代码库中上下文信息过载的问题，帮助 AI Agent 在代码审查、重构、依赖分析等场景中高效获取精确的证据支撑[资料来源：README.md:1]()\n\nContextful 的核心价值在于将传统的\"暴力读取文件\"模式转变为\"证据驱动的紧凑上下文打包\"模式。传统方式下，AI Agent 可能需要读取数十个文件才能理解一个问题，而 Contextful 能够根据查询意图返回一个经过排序、标注来源、符合 token 预算的紧凑证据包[资料来源：README.md:1-5]()。\n\n### 核心设计理念\n\nContextful 遵循以下设计原则：\n\n1. **证据优先**：每个返回的上下文都附带文件引用和行号，AI 可以直接溯源\n2. **意图感知**：系统能够分类用户查询（如精确搜索、影响分析、架构追踪等）\n3. **预算可控**：返回结果严格遵守 token 预算限制，避免信息过载\n4. **记忆持久化**：支持将 AI 学习到的经验持久化存储，供后续会话复用\n\n## 技术架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph 输入层\n Q[用户查询]\n W[工作区文件]\n M[记忆数据]\n end\n \n subgraph 处理层\n C[CLI命令解析]\n S[搜索引擎]\n G[图数据库]\n I[索引引擎]\n end\n \n subgraph MCP层\n MCP[MCP Server]\n TOOLS[7大工具集]\n end\n \n subgraph 输出层\n P[Evidence Pack]\n R[Context Report]\n end\n \n Q --> C\n W --> I\n I --> G\n C --> S\n S --> G\n M --> S\n C --> MCP\n MCP --> TOOLS\n TOOLS --> P\n TOOLS --> R\n S --> P\n G --> P\n```\n\n### 核心模块\n\n| 模块名称 | 文件路径 | 职责说明 |\n|---------|---------|---------|\n| CLI 解析器 | `src/cli.ts` | 命令行参数解析与路由 |\n| 搜索引擎 | `src/search.ts` | 全文检索、意图分类、结果排序 |\n| 索引引擎 | `src/extract.ts` | 符号提取、依赖关系图构建 |\n| MCP 服务 | `src/mcp-server.ts` | MCP 协议实现与工具暴露 |\n| 报告生成 | `src/report.ts` | 上下文报告与证据包渲染 |\n\n## 功能特性\n\n### CLI 命令行工具\n\nContextful 提供完整的命令行界面，支持以下操作[资料来源：src/cli.ts:1-100]()：\n\n| 命令 | 功能描述 | 核心参数 |\n|------|---------|---------|\n| `cxf index` | 建立或更新工作区索引 | `--workspace`, `--watch` |\n| `cxf daemon` | 启动本地索引守护进程 | `--workspace` |\n| `cxf query` | 创建证据包 | `--workspace`, `--budget`, `--json` |\n| `cxf search` | 搜索上下文 | `--workspace`, `--limit`, `--kind` |\n| `cxf report` | 生成上下文报告 | `--workspace`, `--format` |\n| `cxf memory add` | 存储经验教训 | `--claim`, `--evidence`, `--scope` |\n| `cxf server` | 启动 MCP 服务 | 无 |\n\n### MCP 工具集\n\nContextful 作为 MCP（Model Context Protocol）服务器，暴露了 7 个核心工具[资料来源：src/mcp-server.ts:1-50]()：\n\n| 工具名称 | 功能说明 |\n|---------|---------|\n| `context_pack` | 返回排序、标注来源、符合预算的证据包 |\n| `search_code` | 强大的代码、文档、符号和记忆搜索 |\n| `trace_path` | 跨文件、符号、模块、配置的图遍历 |\n| `impact_analysis` | 逆向依赖分析与影响范围识别 |\n| `why_changed` | 结合 Git 历史的变更原因分析 |\n| `recall_memory` | 搜索持久化的经验教训 |\n| `write_lesson` | 写入带证据的经验教训 |\n\n### 搜索意图分类\n\n系统能够将用户查询自动分类为以下意图类型[资料来源：src/search.ts:1-30]()：\n\n| 意图类型 | 触发关键词 | 典型使用场景 |\n|---------|-----------|-------------|\n| `exact` | 文件路径、符号名、正则表达式 | 精确查找定义或文件 |\n| `code` | 函数、变量、参数、实现 | 代码实现分析 |\n| `memory` | 记忆、经验、教训、会话 | 经验检索 |\n| `impact` | 影响、依赖、影响范围 | 变更影响分析 |\n| `historical` | 为什么、变更、历史、提交 | 变更原因追溯 |\n| `architectural` | 架构、流程、路径、依赖 | 系统架构分析 |\n| `docs` | 文档、指南、README、配置 | 文档查找 |\n| `vague` | 通用查询 | 模糊匹配 |\n\n### 索引能力\n\n系统支持多种编程语言的代码索引[资料来源：src/extract.ts:1-80]()：\n\n| 语言 | 支持类型 | 提取内容 |\n|------|---------|---------|\n| TypeScript/JavaScript | 函数、类、接口、类型 | 函数声明、导出状态、签名 |\n| Python | 函数、类 | 函数定义、类定义 |\n| Go | 函数、结构体、接口 | 函数声明、包级导出 |\n| Rust | 函数、结构体、枚举、特征、impl | 函数、结构体、特征实现 |\n| Markdown | 标题 | 层级标题结构 |\n| JSON | 配置键 | 顶层键名 |\n| Go | import 路径 | 包引用 |\n| Rust | use/mod 语句 | 模块引用 |\n\n## 工作流程\n\n### 索引构建流程\n\n```mermaid\ngraph LR\n A[文件扫描] --> B[语言检测]\n B --> C[符号提取]\n C --> D[依赖关系提取]\n D --> E[全文分块]\n E --> F[SQLite存储]\n \n F --> G[FTS全文索引]\n G --> H[图数据库索引]\n```\n\n### 证据包生成流程\n\n```mermaid\ngraph TD\n Q[query查询] --> C{意图分类}\n C -->|code| F1[FTS全文搜索]\n C -->|impact| F2[图遍历分析]\n C -->|memory| F3[记忆库搜索]\n C -->|historical| F4[Git历史查询]\n \n F1 --> R[结果合并]\n F2 --> R\n F3 --> R\n F4 --> R\n \n R --> D[相关性评分]\n D --> S[Token预算分配]\n S --> P[Evidence Pack]\n \n P --> CITE[引用标注]\n P --> GRAPH[图路径连接]\n P --> CONF[置信度计算]\n \n CITE --> OUTPUT[最终输出]\n GRAPH --> OUTPUT\n CONF --> OUTPUT\n```\n\n## 依赖关系\n\n### 核心依赖\n\n| 依赖包 | 版本 | 用途 |\n|--------|------|------|\n| `@modelcontextprotocol/sdk` | ^1.29.0 | MCP 协议实现 |\n| `better-sqlite3` | ^12.10.0 | SQLite 数据库引擎 |\n| `commander` | ^14.0.3 | CLI 命令解析 |\n| `fast-glob` | ^3.3.3 | 文件模式匹配 |\n| `web-tree-sitter` | ^0.20.8 | 语法树解析 |\n| `zod` | ^4.4.3 | 数据验证 |\n\n### 开发依赖\n\n| 依赖包 | 版本 | 用途 |\n|--------|------|------|\n| `typescript` | ^6.0.3 | 类型检查与编译 |\n| `vitest` | ^4.1.6 | 单元测试框架 |\n\n### 环境要求\n\n- **Node.js 版本**: >= 20[资料来源：package.json:45]()\n\n### 支持的 IDE\n\n项目已针对以下 IDE 和编辑器进行测试[资料来源：package.json:10-18]()：\n\n- Windsurf\n- GitHub Copilot\n- VS Code\n- Cline\n- Roo Code\n- Continue\n- Zed\n\n## 项目元数据\n\n| 属性 | 值 |\n|------|-----|\n| 项目名称 | contextful |\n| CLI 别名 | `cxf` |\n| MCP 名称 | `io.github.Inferensys/contextful` |\n| 许可证 | MIT |\n| 仓库地址 | `git+https://github.com/Inferensys/contextful.git` |\n| 官网 | https://inferensys.github.io/contextful/ |\n| 问题追踪 | https://github.com/Inferensys/contextful/issues |\n\n## 使用示例\n\n### 安装与索引\n\n```bash\n# 全局安装\nnpx @inferensys/contextful index --workspace .\n\n# 持续监听文件变化\nnpx @inferensys/contextful index --workspace . --watch\n```\n\n### 查询上下文\n\n```bash\n# 基本查询\ncxf query \"where is user auth handled\" --workspace . --budget 2000\n\n# 输出 JSON 格式\ncxf query \"memory ledger implementation\" --workspace . --json\n```\n\n### MCP 服务模式\n\n```bash\n# 启动 MCP 服务器\nnpx @inferensys/contextful server\n```\n\n## 数据模型\n\n### 证据包结构\n\n```mermaid\nclassDiagram\n class EvidencePack {\n +string id\n +string query\n +string scope\n +SearchIntent intent\n +string summary\n +SearchHit[] citations\n +FileContext[] files\n +SymbolRecord[] symbols\n +GraphPath[] graphPaths\n +SearchHit[] memoryHits\n +number confidence\n +number tokenEstimate\n +number budget\n +string createdAt\n }\n \n class SearchHit {\n +string ref\n +string path\n +string title\n +string kind\n +string excerpt\n +number rank\n }\n \n class GraphPath {\n +string from\n +string to\n +string edgeType\n +string filePath\n +number line\n }\n \n EvidencePack --> SearchHit\n EvidencePack --> GraphPath\n```\n\n### 记忆条目结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 唯一标识符 |\n| `claim` | string | 经验主张 |\n| `evidenceRefs` | string[] | 证据引用列表 |\n| `scope` | string | 作用范围（repo/global） |\n| `confidence` | number | 置信度（0-1） |\n| `createdAt` | string | 创建时间 |\n\n## 报告功能\n\n系统支持生成多格式的上下文报告[资料来源：src/report.ts:1-60]()：\n\n| 格式 | 说明 |\n|------|------|\n| `markdown` | 默认格式，Markdown 渲染 |\n| `json` | 结构化 JSON 输出 |\n| `html` | 独立 HTML 页面，可直接在浏览器打开 |\n\n### 报告包含内容\n\n- **索引状态**：已索引文件数、符号数、块数\n- **统计摘要**：Token 使用情况、节省比例估算\n- **警告信息**：潜在问题提示（如未索引文件、依赖缺失）\n- **Token 节省估算**：相对于未使用系统的平均节省比例\n\n---\n\n**相关链接**：\n\n- 官方文档：https://inferensys.github.io/contextful/\n- 问题反馈：https://github.com/Inferensys/contextful/issues\n- 源码仓库：https://github.com/Inferensys/contextful\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#page-1), [数据存储与索引](#page-6), [MCP 服务器集成](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp-server.ts](https://github.com/Inferensys/contextful/blob/main/src/mcp-server.ts)\n- [src/indexer.ts](https://github.com/Inferensys/contextful/blob/main/src/indexer.ts)\n- [src/cli.ts](https://github.com/Inferensys/contextful/blob/main/src/cli.ts)\n- [src/search.ts](https://github.com/Inferensys/contextful/blob/main/src/search.ts)\n- [src/extract.ts](https://github.com/Inferensys/contextful/blob/main/src/extract.ts)\n- [src/report.ts](https://github.com/Inferensys/contextful/blob/main/src/report.ts)\n \n\n# 系统架构\n\n## 1. 概述\n\nContextful 是一个基于语义索引的上下文检索系统，旨在为 AI 代理提供精准、紧凑且有据可查的证据包。系统通过解析、索引代码仓库中的符号、导入关系和文档片段，使代理能够在执行任务时快速获取相关上下文，避免随机文件读取带来的效率低下问题。资料来源：[README.md]()\n\n## 2. 整体架构\n\nContextful 采用分层架构设计，主要包含以下层次：\n\n| 层次 | 职责 | 核心模块 |\n|------|------|----------|\n| CLI 层 | 用户交互接口 | `src/cli.ts` |\n| MCP 服务层 | 与 AI 代理的标准通信协议 | `src/mcp-server.ts` |\n| 搜索/查询层 | 语义检索和证据包生成 | `src/search.ts` |\n| 索引层 | 代码解析和数据库写入 | `src/indexer.ts` |\n| 提取层 | 符号和依赖关系解析 | `src/extract.ts` |\n| 工具层 | 通用工具函数 | `src/util.ts` |\n\n```mermaid\ngraph TD\n A[CLI 客户端] --> B[MCP Server]\n C[AI 代理] --> B\n B --> D[Search Module]\n D --> E[Index Layer]\n E --> F[SQLite Kernel DB]\n G[File System] --> E\n D --> G\n```\n\n资料来源：[src/cli.ts:40-65]()，[src/search.ts:1-50]()\n\n## 3. 核心组件详解\n\n### 3.1 索引子系统 (Indexer)\n\n索引子系统负责扫描工作区文件并将其内容转换为可检索的数据库记录。索引过程包括文件发现、语言检测、符号提取和依赖关系分析四个阶段。\n\n```mermaid\ngraph LR\n A[文件扫描] --> B[语言检测]\n B --> C[符号提取]\n C --> D[依赖分析]\n D --> E[分块存储]\n```\n\n#### 索引流程\n\n| 阶段 | 功能 | 关键函数 |\n|------|------|----------|\n| 文件发现 | 递归扫描目录，忽略隐藏文件和测试文件 | `scanWorkspace()` |\n| 语言检测 | 根据扩展名识别 TypeScript/JavaScript、Python、Go、Rust 等语言 | `detectLanguage()` |\n| 符号提取 | 解析函数、类、接口、类型定义 | `extractSymbols()` |\n| 依赖分析 | 提取 import/require/use 语句 | `extractEdges()` |\n| 内容分块 | 将文件内容切分为可管理的片段 | `textChunks()` |\n\n资料来源：[src/extract.ts:1-50]()，[src/indexer.ts]()\n\n#### 支持的编程语言\n\n系统支持多种编程语言的符号提取和依赖分析：\n\n| 语言 | 符号类型 | 依赖检测 |\n|------|----------|----------|\n| TypeScript/JavaScript | function, class, interface, type, const | `import from`、`require()` |\n| Python | function, class | `from ... import`、`import` |\n| Go | function, struct, interface | 字符串字面量导入 |\n| Rust | function, struct, enum, trait, impl | `use`、`mod` |\n| Markdown | heading | 无依赖 |\n| JSON | config-key | 键值对配置 |\n\n资料来源：[src/extract.ts:10-45]()\n\n### 3.2 搜索与查询子系统 (Search)\n\n搜索子系统是系统的核心大脑，负责理解用户查询意图并返回最相关的上下文片段。\n\n```mermaid\ngraph TD\n A[用户查询] --> B{意图分类}\n B -->|code| C[代码搜索]\n B -->|symbol| D[符号搜索]\n B -->|impact| E[影响分析]\n B -->|historical| F[历史追溯]\n B -->|architectural| G[架构路径]\n B -->|docs| H[文档检索]\n C --> I[全文索引查询]\n D --> J[符号表查询]\n E --> K[依赖图遍历]\n F --> L[Git 历史读取]\n I --> M[BM25 排序]\n J --> M\n K --> M\n M --> N[证据包组装]\n```\n\n#### 意图分类器\n\n查询意图自动分类为以下类型：\n\n| 意图 | 检测关键词 | 搜索模式 |\n|------|------------|----------|\n| `code` | how, implement, code, function | 全文搜索 |\n| `symbol` | class, interface, function name | 精确符号匹配 |\n| `impact` | impact, affected, depends, blast radius | 逆向依赖分析 |\n| `historical` | why, changed, commit, history | Git 历史 + 当前代码 |\n| `architectural` | architecture, flow, path, trace | 图遍历 |\n| `docs` | resource, docs, documentation, guide | 文档优先 |\n| `vague` | 通用模糊查询 | 扩展术语 + 全文搜索 |\n\n资料来源：[src/search.ts:1-20]()\n\n### 3.3 证据包系统 (Evidence Pack)\n\n证据包是系统返回给 AI 代理的核心数据结构，包含查询答案的所有支持证据。\n\n```mermaid\ngraph TD\n A[createContextPack] --> B[searchContext]\n B --> C{选择命中}\n C -->|hits| D[topKByScore]\n C -->|graphPaths| E[loadGraphPaths]\n C -->|memoryHits| F[内存记忆]\n D --> G[组装证据包]\n E --> G\n F --> G\n G --> H[EvidencePack]\n H --> I[summary 摘要]\n H --> J[citations 引用]\n H --> K[symbols 符号]\n H --> L[graphPaths 路径]\n```\n\n#### 证据包数据结构\n\n```typescript\ninterface EvidencePack {\n id: string; // 唯一标识符\n query: string; // 原始查询\n scope: string; // 作用域 (repo|file|session)\n intent: SearchIntent; // 识别的查询意图\n summary: string; // 自然语言摘要\n citations: SearchHit[]; // 命中的上下文片段\n files: FileReference[]; // 相关文件列表\n symbols: SymbolRecord[]; // 匹配的符号\n graphPaths: GraphPath[]; // 图路径连接\n memoryHits: SearchHit[]; // 记忆系统命中\n confidence: number; // 置信度 (0.1-0.92)\n tokenEstimate: number; // 估算的 token 数量\n budget: number; // token 预算上限\n createdAt: string; // 创建时间戳\n}\n```\n\n资料来源：[src/search.ts:150-200]()，[src/types.ts]()\n\n### 3.4 MCP 服务层\n\nMCP (Model Context Protocol) 服务层提供了与 AI 代理通信的标准接口，使 Contextful 可作为工具被集成到任何兼容 MCP 的代理中。\n\n```mermaid\ngraph LR\n A[AI Agent] -->|stdio| B[MCP Server]\n B -->|context_pack| C[createContextPack]\n B -->|search_code| D[searchContext]\n B -->|trace_path| E[traceGraph]\n B -->|impact_analysis| F[impactAnalysis]\n B -->|why_changed| G[whyChanged]\n B -->|recall_memory| H[recallMemory]\n B -->|write_lesson| I[writeLesson]\n```\n\n#### MCP 工具列表\n\n| 工具名 | 功能 | 参数 |\n|--------|------|------|\n| `context_pack` | 生成带证据的上下文包 | query, budget, scope |\n| `search_code` | 搜索代码、文档、符号、记忆 | query, mode, filters |\n| `trace_path` | 图遍历追踪符号/模块依赖 | from, to, edge_types |\n| `impact_analysis` | 分析符号/文件的逆向依赖 | symbol_or_file |\n| `why_changed` | 追溯变更历史 | symbol_or_file |\n| `recall_memory` | 搜索记忆系统 | query, scope |\n| `write_lesson` | 写入学习记忆 | claim, evidence_refs |\n\n资料来源：[src/mcp-server.ts]()，[README.md]()\n\n### 3.5 CLI 命令行接口\n\nCLI 模块提供了独立的命令行工具 `cxf` (contextful) 供开发者直接使用。\n\n#### 命令概览\n\n| 命令 | 描述 | 核心选项 |\n|------|------|----------|\n| `index` | 索引工作区文件 | `--workspace`, `--watch` |\n| `daemon` | 启动本地索引守护进程 | `--workspace` |\n| `query` | 创建证据包 | `--workspace`, `--budget`, `--json` |\n| `search` | 搜索索引内容 | `--workspace`, `--limit`, `--kind` |\n| `report` | 生成上下文报告 | `--workspace`, `--format` |\n| `memory add` | 添加学习记忆 | `--claim`, `--evidence`, `--confidence` |\n| `server` | 启动 MCP 服务 | 无 |\n\n资料来源：[src/cli.ts:1-80]()\n\n#### 使用示例\n\n```bash\n# 索引当前目录\ncxf index --workspace .\n\n# 启动守护进程监听变更\ncxf daemon --workspace .\n\n# 查询上下文\ncxf query \"用户认证在哪里处理\" --workspace . --budget 2000\n\n# 生成报告\ncxf report --workspace . --format markdown\n```\n\n## 4. 数据模型\n\n### 4.1 内核数据库 (SQLite)\n\n系统使用 SQLite 作为内核数据库，存储以下核心表结构：\n\n| 表名 | 用途 | 核心字段 |\n|------|------|----------|\n| `files` | 已索引文件元数据 | path, language, hash, indexed_at |\n| `chunks` | 文件分块内容 | file_id, path, title, text, kind |\n| `chunks_fts` | 全文搜索索引 | BM25 排序的 FTS5 表 |\n| `symbols` | 代码符号表 | name, kind, file_path, line, signature |\n| `edges` | 依赖关系图 | source_path, target_name, edge_type |\n| `memory` | 学习记忆存储 | id, claim, evidence, confidence, scope |\n| `queries` | 查询历史 | query, intent, timestamp |\n\n资料来源：[src/indexer.ts]()，[src/search.ts:50-100]()\n\n### 4.2 符号提取数据模型\n\n```typescript\ninterface SymbolRecord {\n ref: string; // 文件引用，如 \"file:src/auth.ts:1-20\"\n name: string; // 符号名称\n kind: string; // 类型：function, class, interface, struct, enum\n filePath: string; // 文件路径\n line: number; // 定义行号\n signature?: string; // 函数签名摘要\n exported?: boolean; // 是否导出\n}\n\ninterface RawEdge {\n targetName: string; // 目标名称\n targetType: string; // 目标类型：module, config\n edgeType: string; // 边类型：IMPORTS, CONFIGURES\n filePath: string; // 源文件路径\n line: number; // 行号\n}\n```\n\n资料来源：[src/extract.ts:1-30]()\n\n## 5. 工作流程\n\n### 5.1 索引完整流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI as CLI/Server\n participant Indexer\n participant Extractor\n participant DB as Kernel DB\n \n User->>CLI: cxf index --workspace .\n CLI->>Indexer: scanWorkspace(workspace)\n Indexer->>Indexer: 遍历所有文件\n loop 每个文件\n Indexer->>Extractor: extractSymbols(content, language)\n Extractor-->>Indexer: symbols[]\n Indexer->>Extractor: extractEdges(content, language)\n Extractor-->>Indexer: edges[]\n Indexer->>Extractor: textChunks(content)\n Extractor-->>Indexer: chunks[]\n Indexer->>DB: insert records\n end\n DB-->>CLI: indexing complete\n CLI-->>User: status report\n```\n\n### 5.2 查询证据包生成流程\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant MCP as MCP Server\n participant Search\n participant DB as Kernel DB\n \n Agent->>MCP: context_pack(\"用户认证\", budget=2000)\n MCP->>Search: createContextPack({query, budget})\n Search->>Search: classifyQuery(query) -> intent\n Search->>Search: searchContext({query, intent})\n Search->>DB: FTS query + BM25\n DB-->>Search: ranked hits\n Search->>Search: selectTopK(hits, budget)\n Search->>DB: loadSymbolsForPaths()\n Search->>DB: loadGraphPaths()\n Search-->>MCP: EvidencePack\n MCP-->>Agent: EvidencePack (JSON/Markdown)\n```\n\n## 6. 记忆系统\n\nContextful 内置了一个证据支持的学习记忆系统，允许 AI 代理保存从查询中获得的经验教训。\n\n### 6.1 记忆数据结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 唯一标识符 |\n| `claim` | string | 经验断言/教训 |\n| `evidence` | SearchHit[] | 支持证据引用 |\n| `confidence` | number | 置信度 (0-1) |\n| `scope` | string | 作用域 (repo/file/session) |\n| `createdAt` | string | 创建时间 |\n\n### 6.2 记忆查询\n\n记忆系统支持通过自然语言查询检索相关经验，与常规代码搜索并行执行，结果合并到证据包中。\n\n资料来源：[src/search.ts:200-250]()\n\n## 7. 报告系统\n\n报告模块提供工作区的整体上下文分析视图。\n\n```mermaid\ngraph TD\n A[generateReport] --> B[getIndexStatus]\n A --> C[getQueryStats]\n A --> D[getStaleMemories]\n B --> E[renderReport]\n C --> E\n D --> E\n E -->|markdown| F[Markdown 格式]\n E -->|json| G[JSON 格式]\n E -->|html| H[HTML 格式]\n```\n\n### 7.1 报告内容\n\n| 部分 | 内容 |\n|------|------|\n| 状态概览 | 文件数、符号数、索引状态 |\n| 语言覆盖 | 各编程语言的文件数量统计 |\n| 热门查询 | 最常使用的查询及意图分布 |\n| 陈旧记忆 | 需要更新的学习记忆 |\n| 代理指导 | 最佳实践建议 |\n| 警告 | 索引过程中的潜在问题 |\n\n资料来源：[src/report.ts:1-100]()\n\n## 8. 扩展机制\n\n### 8.1 自定义文件类型支持\n\n系统通过 `extract.ts` 中的语言检测器支持扩展新的编程语言。需要实现：\n\n1. **符号提取**：匹配函数/类/类型定义的正则表达式\n2. **依赖分析**：匹配导入语句的模式\n3. **分块策略**：适用于该语言内容的分块算法\n\n### 8.2 MCP 工具扩展\n\nMCP 服务层支持注册新的工具函数，遵循以下签名：\n\n```typescript\ninterface MCPTool {\n name: string;\n description: string;\n inputSchema: object;\n handler: (params: object) => Promise