pi-cli – 统一项目分析 CLI

统一的项目分析和维护工具，支持静态分析和 LLM 驱动的智能分析。与 project-index 功能完全一致。

⛔ 严禁操作 (CRITICAL – 必读)

2026-01-22 事故记录：执行 git checkout HEAD -- tests/ 和 git checkout HEAD -- js/，导致用户一整天的手动工作（100+ 文件）永久丢失，无法恢复。

以下操作必须先询问用户确认，否则绝对禁止执行：

1. git checkout HEAD -- / git checkout -- <path> — 会永久丢弃未提交修改
2. git reset --hard — 会永久丢弃所有未提交修改
3. git clean -fd — 会永久删除未跟踪文件
4. git stash drop / git stash clear — 会永久删除 stash
5. 任何批量删除文件的操作 (rm -rf, find -delete 等)

批量任务进度保护：每完成一批任务后，必须提交或提醒用户提交。

核心能力

命令对照

快速开始

# 初始化配置
pi init

# 构建依赖图
pi deps build

# LLM 驱动的模块分析（生成 CLAUDE.md + AUDIT.md）
pi module analyze --llm --concurrency=20

# 测试分析和修复
pi test map
pi test fix --llm --concurrency=10

# 启动 Dashboard
pi ui --port=3008

命令

AI 交互指引

主动询问

完成批量任务后，应主动询问用户：

任务完成。是否打开 Dashboard 查看详细状态？
→ 运行: pi ui
→ 访问: http://localhost:3008

任务前检查

执行文档/测试任务前，先检查状态：

pi doc check --stale-only --json

根据输出决定处理范围。

触发场景

1. 新项目入驻 — 用户说”帮我分析这个项目”、”生成文档”
2. 遗留项目理解 — 用户说”这个代码库怎么组织的”
3. 代码修改后 — 检测到核心模块变更，提醒更新文档
4. 测试维护 — 用户说”生成测试”、”修复测试”
5. 审计需求 — 用户说”检查安全问题”、”代码审计”

核心概念

三层架构

project/CLAUDE.md           # Layer 1: 概览 + 模块索引
    ↓
src/modules/auth/CLAUDE.md  # Layer 2: 模块详情 + 子模块索引
    ↓
src/modules/auth/jwt/CLAUDE.md  # Layer 3: 实现细节

智能覆盖策略

不是每个目录都需要独立 CLAUDE.md：

• 大目录 (≥5 文件或 ≥200 行) → 必须有独立 CLAUDE.md
• 小目录 + 父目录有 CLAUDE.md → 由父目录覆盖
• 小目录 + 父目录无 CLAUDE.md → 孤儿，需关注

层级依赖排序 (DAG)

批量生成时按目录深度从深到浅处理：

js/agents/core/sandbox/system  → 先生成
js/agents/core/sandbox         → 后生成
js/agents/core                 → 再后
js/agents                      → 最后

确保父目录生成时可引用子目录的 CLAUDE.md。

LLM 模式

通过 --llm 启用 LLM 驱动的智能分析：

# 模块分析（含 Kanban 集成）
KANBAN_URL=http://localhost:3007/api/v1 pi module analyze --llm

# 测试修复（安全约束：只改测试，不改实现）
pi test fix --llm --concurrency=20

DAG 调度

任务带 dependencies 字段时自动启用 DAG 调度：

const tasks = [
  { id: 'parent', dependencies: ['child1', 'child2'], prompt: '...' },
  { id: 'child1', prompt: '...' },
  { id: 'child2', prompt: '...' }
];
// child1, child2 并发执行，完成后 parent 才开始

依赖分析系统

构建文件级依赖图，支持影响分析和 stale 传播。

依赖图构建

# 构建依赖图
pi deps build

# 查询单文件依赖
pi deps query shared/index.js

输出文件：.dep-graph.json

影响分析

分析变更文件的下游影响范围：

# 分析指定文件
pi deps impact shared/utils/logger.js core/event-bus.js

# 分析 git 变更
pi deps impact --since HEAD~5
pi deps impact --staged

Stale 传播

将 stale 状态沿依赖图向下游传播：

# 自动检测 + 传播
pi deps propagate

# 指定变更文件
pi deps propagate --changed core/event-bus.js

# 包含测试重跑列表
pi deps propagate --changed core/event-bus.js --tests

# 调整传播深度（默认 2）
pi deps propagate --depth 3

典型工作流

# 1. 构建/更新依赖图
pi deps build

# 2. 代码修改后，分析影响
pi deps impact --staged

# 3. 检查 stale 传播
pi deps propagate --tests

# 4. 运行受影响的测试
pi test affected --staged

智能测试修复（100+ 错误场景）

当有大量测试失败时，智能排序修复顺序：

# 分析失败测试的优先级
pi test prioritize --from-file test-results.json

修复策略：

1. 先修 root cause — 被依赖最多的文件，一个修复解决多个错误
2. 并行修独立集 — 无依赖关系的文件可以 60 开并发
3. 最后修叶子节点 — 依赖链末端的文件

工作流

新项目

1. pi init – 初始化配置
2. pi deps build – 构建依赖图
3. pi doc generate – 生成文档
4. 开始开发

遗留项目

1. pi init – 初始化配置
2. pi deps build – 构建依赖图
3. pi doc generate – 生成文档
4. pi module analyze --llm – 初始审计
5. 按需调整

代码修改后

修改模块代码后，必须检查并更新对应的 CLAUDE.md 和 AUDIT.md：

1. 检查 CLAUDE.md

   • 内容需要更新 → 修改文档内容
   • 内容仍然准确 → touch CLAUDE.md 更新时间戳

2. 检查 AUDIT.md

   • 新增安全问题 → 补充到 Issues 列表
   • 问题已修复 → 使用 pi audit archive 归档
   • 内容仍然准确 → touch AUDIT.md 更新时间戳

3. 验证状态

   pi doc check <module-path> --stale-only
   pi audit status <module-path>
   

重要：即使没有实质性改动，也必须 touch 文件以更新时间戳，否则 stale 检测会持续报告该模块过期。

配置文件

.pi-config.json

{
  "name": "my-project",
  "language": "javascript",
  "src": {
    "dirs": ["src"],
    "pattern": "**/*.js",
    "ignore": ["node_modules", "dist"]
  },
  "test": {
    "dirs": ["tests"],
    "pattern": "**/*.test.js",
    "cmd": "npm test",
    "framework": "vitest"
  },
  "cache": ".project-index",
  "llm": {
    "provider": "codex",
    "timeout": 600000
  }
}

.stale-config.json

{
  "include": ["js/agents/**"],
  "ignore": ["tests/**", "docs/**"],
  "features": { "doc": true, "audit": true, "kanban": true, "testAnalysis": true },
  "concurrency": 6
}

Dashboard

访问 http://localhost:3008，功能包括：

• 总览：过期状态、缓存来源
• 模块：模块列表、过滤、状态筛选
• 任务：启动/取消/删除/重试任务
• 依赖图：D3 可视化
• 配置：编辑 .stale-config.json
• 启动：任务类型选择、参数配置

目录结构

pi-cli/
├── cli.js              # 统一入口
├── lib/
│   ├── shared.js       # 工具函数
│   ├── context.js      # 配置加载
│   ├── types.js        # 类型定义
│   ├── deps/           # 依赖图分析
│   │   └── graph.js    # 依赖图 + 影响分析
│   ├── test/           # 测试操作
│   │   ├── mapper.js   # 源码↔测试映射
│   │   ├── runner.js   # 测试运行
│   │   ├── prioritize.js # 优先级排序
│   │   ├── fix.js      # LLM 测试修复
│   │   └── generator.js # 测试生成
│   ├── doc/            # 文档生成
│   │   └── generate.js # CLAUDE.md 生成 + stale 检测
│   ├── audit/          # 代码审计
│   │   └── scan.js     # AUDIT.md 生成
│   ├── module/         # LLM 模块分析
│   │   └── analyzer.js # 批量文档/审计生成
│   ├── llm/            # LLM 批量执行
│   │   └── batch.js    # DAG 调度 + codeagent-wrapper
│   ├── task/           # 任务管理
│   │   └── manager.js  # PID 跟踪 + 状态管理
│   ├── stale/          # Stale 通知
│   └── update/         # 增量更新
└── ui/
    └── server.js       # Dashboard (SSE + API)

Kanban 集成

审计任务自动创建到 Kanban：

export KANBAN_URL=http://127.0.0.1:3007/api/v1

未运行 Kanban 服务时静默跳过。

安全约束

LLM 任务自动注入安全前缀，禁止：

• 执行 git checkout / reset / clean
• 删除文件
• 修改实现代码（仅测试修复时）

⚠️ 禁止的错误模式

测试修复和代码生成时必须避免的反模式：

1. 不要跳过测试 — 每次修复后必须运行测试验证
2. 不要批量删除 — 单个文件逐一处理
3. 不要硬编码 — 使用配置文件
4. 不要忽略错误 — 记录并上报

经验教训

参见 LESSONS.md