projector

name	projector
description	Use when the user types "/projector" to initialize or update project knowledge base. Creates CLAUDE.md, agent.md, and PROJECTOR/ folder with structured project documentation. Solves the problem of AI losing context between conversations by maintaining persistent project knowledge.
version	1.0.0
argument-hint	[init|update|scan]
allowed-tools	["Read","Write","Edit","Glob","Grep","Bash"]
disable-model-invocation	true

Projector - 项目知识库生成器

概述

Projector 是一个项目知识管理工具，通过创建结构化的知识库文件，让 AI 在每次对话中都能快速、准确地理解项目上下文。

解决的问题:

• 代码分裂：不同组件代码没有复用，各自为政
• 重复编码：相同逻辑在不同组件中重复实现
• 遗忘参考：已解决的 bug 在其他组件中重复出现
• 重回起点：每次新对话都要重新理解项目
• 幻觉反复：注入或依赖未实现的组件

触发条件

用户输入 /projector 或 /projector <参数> 时触发。

参数说明

• init - 初始化项目知识库（首次使用）
• update - 更新现有知识库（增量更新）
• scan - 扫描项目结构，输出分析报告（不创建文件）

如果未提供参数，默认执行 init。

执行流程

Step 0: 检测项目语言

1. 检查项目根目录是否存在 README.md
2. 分析 README.md 中的中文字符比例
3. 如果中文占比 > 30%，使用中文生成文档；否则使用英文
4. 将检测结果保存到变量 $LANGUAGE (zh/en)

Step 1: 项目分析

1. 扫描项目根目录结构（排除 node_modules, .git, dist 等目录）
2. 识别技术栈：
   • 检查 package.json, pyproject.toml, Cargo.toml, go.mod 等配置文件
   • 识别语言 (TypeScript, Python, Rust, Go 等)
   • 识别框架 (React, Vue, Django, Flask 等)
   • 识别构建工具 (webpack, vite, cargo 等)
3. 分析模块和组件关系：
   • 扫描 src/, lib/, app/ 等源码目录
   • 识别模块边界（目录结构、index 文件）
   • 分析 import/require 依赖关系
4. 检测代码复用机会：
   • 查找相似的工具函数
   • 识别重复的业务逻辑
   • 发现可抽象的通用模式
5. 识别已知问题和解决方案：
   • 扫描注释中的 TODO, FIXME, HACK, XXX
   • 检查 git log 中的 bug 修复记录
   • 识别常见的错误模式

Step 2: 生成 CLAUDE.md

在项目根目录创建 CLAUDE.md，内容包含：

# [项目名称]

[项目一句话描述]

## 项目知识库

**重要**: 本项目使用 projector 管理项目知识。在开始任何工作前，请先阅读：

1. `PROJECTOR/README.md` - 项目总览和使用指南
2. `PROJECTOR/architecture/overview.md` - 系统架构
3. `PROJECTOR/modules/` - 相关模块文档
4. `PROJECTOR/patterns/` - 代码约定和复用清单
5. `PROJECTOR/issues/` - 已知问题和解决方案

## Commands

| Command | Description |
|---------|-------------|
| [从 package.json 等提取] | [自动生成] |

## Architecture

[简要概述，详见 PROJECTOR/architecture/overview.md]

## Code Style

[从代码分析中提取关键约定]

## Gotchas

[从 PROJECTOR/issues/ 提取关键注意事项]

Step 3: 生成 agent.md

在项目根目录创建 agent.md，定义项目专用代理：

---
name: project-expert
description: 项目专家代理，负责维护和查询项目知识库
tools: [Read, Write, Edit, Glob, Grep]
model: inherit
---

# Project Expert Agent

你是项目专家代理，负责：

1. 维护 PROJECTOR/ 文件夹中的知识文档
2. 回答关于项目架构和实现的问题
3. 识别代码复用机会
4. 记录已解决的问题和解决方案

## 工作流程

1. 查询问题时，首先检查 PROJECTOR/ 中的相关文档
2. 发现新的模式或解决方案时，更新相应文档
3. 遇到重复代码时，建议复用现有实现
4. 定期扫描项目，更新知识库

Step 4: 创建 PROJECTOR/ 文件夹

创建以下目录结构和文件：

PROJECTOR/
├── README.md              # 项目总览和使用指南
├── architecture/          # 架构文档
│   ├── overview.md        # 系统架构概述
│   ├── modules.md         # 模块依赖关系
│   └── data-flow.md       # 数据流图
├── modules/               # 模块详细文档
│   ├── <module-name>.md   # 每个模块的文档
│   └── ...
├── patterns/              # 代码模式和复用
│   ├── reusable.md        # 可复用代码清单
│   ├── conventions.md     # 编码约定
│   └── anti-patterns.md   # 需要避免的模式
├── issues/                # 问题和解决方案
│   ├── resolved.md        # 已解决的问题
│   ├── known-issues.md    # 已知问题
│   └── workarounds.md     # 临时解决方案
└── context/               # 上下文信息
    ├── decisions.md       # 技术决策记录
    ├── dependencies.md    # 依赖关系
    └── environment.md     # 环境配置

文件生成规则:

1. README.md - 根据语言选择生成中文或英文版本
2. architecture/overview.md - 从项目分析结果中提取架构信息
3. architecture/modules.md - 生成模块依赖关系图（Mermaid 格式）
4. modules/*.md - 为每个主要模块生成详细文档
5. patterns/reusable.md - 从代码分析中提取可复用代码
6. patterns/conventions.md - 从代码风格中提取约定
7. issues/resolved.md - 从 git log 中提取已解决的问题
8. issues/known-issues.md - 从 TODO/FIXME 中提取已知问题
9. context/dependencies.md - 从配置文件中提取依赖关系
10. context/environment.md - 从配置文件中提取环境要求

Step 5: 设置 Git Hook（可选）

如果项目是 git 仓库，询问用户是否安装 Git hook：

1. 显示 hook 的作用说明
2. 如果用户同意，运行 setup-hooks.sh 安装 hook
3. hook 会在每次提交后自动检测变更并提示更新

Step 6: 验证和报告

1. 验证所有文件已创建
2. 输出创建摘要：
   • 创建的文件数量
   • 检测到的技术栈
   • 识别的模块数量
   • 发现的可复用代码数量
3. 提供使用指南：
   • 如何使用知识库
   • 如何更新知识库
   • 如何手动触发更新

注意事项

1. 不要覆盖现有文件: 如果 CLAUDE.md 或 PROJECTOR/ 已存在，询问用户是否覆盖
2. 排除无关目录: 排除 node_modules, .git, dist, build, pycache 等目录
3. 增量更新: 使用 update 参数时，只更新变更的部分，保留手动编辑的内容
4. 语言一致性: 所有生成的文档使用相同的语言（中文或英文）
5. Mermaid 图表: 使用 Mermaid 语法生成依赖关系图，便于可视化

模板位置

所有模板文件位于 templates/ 目录：

• templates/README-zh.md - 中文版项目总览
• templates/README-en.md - 英文版项目总览
• templates/CLAUDE.md - CLAUDE.md 模板
• templates/agent.md - agent.md 模板
• templates/modules/ - 模块文档模板

相关文件

• scripts/detect-language.py - 语言检测脚本
• scripts/analyze-project.sh - 项目分析脚本
• scripts/generate-docs.sh - 文档生成脚本
• scripts/setup-hooks.sh - Git hook 安装脚本
• hooks/post-commit - 提交后 hook
• hooks/pre-commit - 提交前 hook（可选）
• agents/project-expert.md - 项目专家代理定义