# 1. 克隆或下载项目
cd project-analysis-mcp

# 2. 安装依赖
npm install

{
  "mcpServers": {
    "project-analysis": {
      "command": "npx",
      "args": [
        "tsx",
        "/path/to/project-analysis-mcp/src/index.ts"
      ]
    }
  }
}

# 启动开发服务器
npm run dev

# 启动 Web 查看界面
npm run web

# 运行测试
npm test

# 自定义端口
PORT=8080 npm run web

AI 决策流程：
├── search_insights("单位权限")
├── 找到历史知识
├── checkFreshness: true（启用新鲜度检查）
├── 🟢 fresh → 直接复用历史结论
└── 🔴 stale → 告诉用户"历史知识存在，但关联代码已变化，需要重新验证"
     └── 重新分析代码 → record_insight 更新知识

AI 决策流程：
├── analyze_impact("src/store/unit.js")
├── 得到：直接引用 12 个文件、间接影响 27 个文件
├── 关联知识 6 条
├── 风险评分 HIGH (62/100)
└── 建议：修改前请重点关注这些模块和页面

AI 决策流程：
├── get_full_context({
│     projectName: "分级管控",
│     question: "单位逻辑",
│     targetFile: "src/store/unit.js"
│   })
├── Part 1: 搜索知识 + 检查每条知识的新鲜度
├── Part 2: 影响范围分析（含关联知识的新鲜度）
└── Part 3: 建议后续操作

用户提问
  │
  ├── search_insights（搜索历史知识）
  │     │
  │     ├── 找到知识 + checkFreshness
  │     │     │
  │     │     ├── 🟢 fresh → 直接复用，回答问题
  │     │     │
  │     │     └── 🔴 stale → 警告用户
  │     │           │
  │     │           ├── analyze_project / search_code（重新分析）
  │     │           │
  │     │           └── record_insight（更新知识，重置 fresh 状态）
  │     │
  │     └── ⚪ unknown（旧知识无快照）→ 可选更新以补充快照
  │
  └── 未找到知识
        │
        ├── search_code / analyze_project（分析代码）
        │
        └── record_insight（记录新知识，附带 relatedFiles）

用户问"修改 X 会影响什么？"
  │
  ├── analyze_impact(X)
  │     │
  │     ├── 直接引用文件列表
  │     ├── 间接影响文件列表
  │     ├── 关联模块 / API
  │     ├── 关联历史知识（含新鲜度）
  │     └── 风险评分（可解释）
  │
  └── AI 综合判断
        │
        ├── 低风险 → 可以安全修改
        ├── 中风险 → 建议重点测试相关模块
        └── 高风险 → 建议分步修改，逐步验证

第一层（快速）：比较 mtime + size
  └── 没有变化 → ✅ fresh
  └── 有变化 → 进入第二层

第二层（精确）：计算 SHA-256 hash
  └── hash 相同 → ✅ fresh（mtime 变化但内容没变，如 touch）
  └── hash 不同 → 🔴 stale（代码确实变了）

帮我检查一下"单位权限逻辑"这条知识的代码有没有变

帮我看看这个项目的所有知识，有哪些需要更新

搜索认证相关的知识，顺便检查一下代码有没有变

帮我分析一下修改 store/unit.js 会影响什么

🎯 影响分析: unit.js
📁 文件: src/store/unit.js

🟠 风险等级: HIGH (62/100)
   原因:
   - 12 个文件直接引用
   - 8 个文件间接依赖
   - 6 条项目知识相关（其中 2 条已过期）
   - 2 个 API 端点相关

📍 直接影响 (12 个文件):
   - ../views/unit/list.vue
   - ../views/unit/detail.vue
   ...

💡 相关知识 (6 条):
   🟢 [feature] 责任田模块的派工策略 (v2, fresh)
   🔴 [data_flow] 工单数据流 (v1, stale)
   ...

📊 知识新鲜度: 🟢 有效 4 | 🔴 需验证 2 | ⚪ 无快照 0

~/.project-analysis-mcp/knowledge/

{
  "name": "项目名称",
  "projectPath": "/absolute/path/to/project",
  "businessSummary": "AI 生成的业务总结",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "lastUpdated": "2026-01-01T00:00:00.000Z",
  "schemaVersion": 2,
  "insights": [
    {
      "id": "unique-id",
      "question": "用户提出的问题",
      "answer": "AI 分析的结果",
      "category": "architecture",
      "tags": ["认证", "JWT"],
      "relatedFiles": ["src/auth/index.ts"],
      "relatedSymbols": ["AuthService", "JwtToken"],
      "relatedModules": ["auth"],
      "relatedApis": ["POST /api/auth/login"],
      "fileSnapshots": [
        {
          "path": "/absolute/path/src/auth/index.ts",
          "size": 1234,
          "mtime": "2026-01-01T00:00:00.000Z",
          "hash": "a1b2c3d4e5f6..."
        }
      ],
      "status": "active",
      "lastVerifiedAt": "2026-01-01T00:00:00.000Z",
      "version": 1,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

project-analysis-mcp/
├── src/
│   ├── index.ts                  # MCP 服务器入口，注册所有工具（10个 Tool）
│   ├── tools/
│   │   └── searchCode.ts         # 代码搜索工具（实验性）
│   └── utils/
│       ├── knowledge-store.ts    # 知识存储核心逻辑 + 数据迁移
│       ├── scanner.ts            # 文件扫描 + 快照生成
│       ├── freshness.ts          # 知识新鲜度检查（P0-2）
│       ├── dependency-graph.ts   # 依赖图构建与分析（P0-3）
│       └── impact-analyzer.ts    # 影响范围分析器（P0-3，含知识新鲜度集成）
├── tests/
│   ├── test-p0-1.ts              # P0-1 单元测试：知识模型（16 项）
│   ├── test-p0-2.ts              # P0-2 单元测试：新鲜度检查（13 项）
│   ├── test-p0-3.ts              # P0-3 单元测试：影响分析（18 项）
│   ├── test-integration.ts       # 集成测试：完整闭环场景（10 项）
│   └── test-review-fixes.ts      # 回归测试（15 项）
├── examples/
│   ├── usage-examples.md         # 基本用法和配置示例
│   └── real-usage-records.md     # 真实项目使用记录
├── web/
│   ├── index.html                # Web 页面入口
│   ├── app.js                    # Web 交互逻辑
│   └── styles.css                # Web 界面样式
├── docs/
│   └── screenshots/              # Web 界面截图
├── CHANGELOG.md                  # 更新日志
├── package.json
├── tsconfig.json
└── README.md

# 运行全部测试（72 项）
npm test

# TypeScript 类型检查
npx tsc --noEmit

npm test