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 等)

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

---

核心能力

能力	说明
DAG 调度	依赖感知的并发执行，子目录先于父目录
LLM 批量	codeagent-wrapper 集成，并发 + 重试 + checkpoint
依赖图	文件级依赖分析、影响范围、stale 传播
测试分析	映射、优先级排序、受影响测试、LLM 修复
文档生成	CLAUDE.md 生成（静态 + LLM 模式）
代码审计	AUDIT.md 生成、安全/质量问题检测
Dashboard	Web UI，SSE 实时更新，任务管理，配置编辑

命令对照

pi-cli 命令	project-index 脚本	说明
pi init	hook.js init	初始化配置
pi deps build	dependency-graph.js	构建依赖图
pi deps impact	impact-analyzer.js	影响分析
pi deps propagate	stale-propagate.js	Stale 传播
pi test map	test-mapper.js	测试映射
pi test fix --llm	test-fix.js	测试修复
pi test prioritize	test-prioritize.js	优先级排序
pi test affected	test-affected.js	受影响测试
pi test generate	test-generator.js	生成测试
pi doc generate	generate.js	生成 CLAUDE.md
pi doc check	check-stale.js	过期检测
pi audit scan	code-audit.js	代码审计
pi audit fix	audit-fix.js	审计修复
pi module analyze --llm	module-analyzer.js	LLM 模块分析
pi ui	dashboard.js	Web Dashboard

快速开始

# 初始化配置
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

命令

命令	子命令	说明
init	-	初始化 .pi-config.json
deps	build, impact, propagate, query	依赖图分析
test	map, run, plan, fix, affected, prioritize, generate	测试操作
doc	generate, check, scan	文档生成
audit	scan, fix, status, archive	代码审计
module	analyze	LLM 模块分析
task	list, start, cancel, types	任务管理
stale	notify, status	Stale 通知
update	-	增量更新
hook	init, install, uninstall	Claude Code hooks
ui	-	Web Dashboard

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