# 1. 全局安装（仅需一次）
git clone -b main https://github.com/kingkongshot/Pensieve.git ~/.claude/skills/pensieve

# 2. 安装钩子（推荐；编辑后自动同步知识图谱，在会话开始时自动检查状态）
bash ~/.claude/skills/pensieve/.src/scripts/install-hooks.sh

# 3. 在您的项目中初始化
cd <your-project>
bash ~/.claude/skills/pensieve/.src/scripts/init-project-data.sh

将 <skill-path> 替换为您客户端的技能目录（例如 ~/.cursor/skills/pensieve）。

# 1. 全局安装（仅需一次）
git clone -b main https://github.com/kingkongshot/Pensieve.git <skill-path>

# 2. 在您的项目中初始化
cd <your-project>
bash <skill-path>/.src/scripts/init-project-data.sh

当用户请求 AI 代理安装 Pensieve 时，代理应遵循以下决策流程。其中，SKILL_PATH 指的是客户端特定的安装路径（例如 ~/.claude/skills/pensieve）。

步骤 1：检查全局安装状态

SKILL_PATH="$HOME/.claude/skills/pensieve"  # 根据客户端调整

if [[ -d "$SKILL_PATH/.src" ]]; then
    echo "Pensieve 已经全局安装，跳过克隆"
else
    SKILL_PARENT="$(dirname "$SKILL_PATH")"
    # 检查父目录是否为 Git 仓库（有些用户会用 Git 同步配置）
    if git -C "$SKILL_PARENT/.." rev-parse --is-inside-work-tree >/dev/null 2>&1; then
        git -C "$SKILL_PARENT/.." submodule add -b main https://github.com/kingkongshot/Pensieve.git "skills/pensieve"
    else
        git clone -b main https://github.com/kingkongshot/Pensieve.git "$SKILL_PATH"
    fi
    # 钩子是 Claude Code 特有的功能；其他客户端可跳过此步骤
    # bash "$SKILL_PATH/.src/scripts/install-hooks.sh"
fi

步骤 2：判断是否需要运行项目初始化

# 如果当前目录是技能的父级配置目录，则不自动初始化项目数据
CURRENT_DIR="$(pwd)"
CONFIG_DIR="$(cd "$(dirname "$SKILL_PATH")/.." 2>/dev/null && pwd)"
if [[ "$CURRENT_DIR" == "$CONFIG_DIR" ]]; then
    echo "当前目录是配置目录，跳过项目初始化。如果您需要在此处使用 Pensieve，请明确指定。"
    exit 0
fi

步骤 3：检查旧版数据并进行初始化

HAS_LEGACY=0
for legacy_dir in .claude/skills/pensieve .agents/skills/pensieve skills/pensieve .claude/pensieve; do
    if [[ -d "$legacy_dir" ]] && [[ -d "$legacy_dir/maxims" || -d "$legacy_dir/decisions" || -d "$legacy_dir/knowledge" || -d "$legacy_dir/pipelines" ]]; then
        HAS_LEGACY=1
        break
    fi
done

if [[ "$HAS_LEGACY" -eq 1 ]]; then
    echo "检测到旧版 Pensieve 用户数据。是否迁移到 v2？"
    bash "$SKILL_PATH/.src/scripts/init-project-data.sh"
    bash "$SKILL_PATH/.src/scripts/run-migrate.sh"
    bash "$SKILL_PATH/.src/scripts/run-doctor.sh" --strict
elif [[ -d .pensieve ]]; then
    echo "当前项目已初始化 Pensieve"
else
    bash "$SKILL_PATH/.src/scripts/init-project-data.sh"
fi

关键要点：先检查全局安装情况 -> 判断父目录是否为 Git 仓库以决定是克隆还是添加子模块 -> 对于配置目录跳过项目初始化 -> 检查旧版数据以决定是否初始化或迁移。

# 更新系统代码（一次操作，所有项目同步生效）
cd <skill-path>
git pull --ff-only || { git fetch origin && git reset --hard "origin/$(git rev-parse --abbrev-ref HEAD)"; }

# 在您的项目中进行健康检查（可选但建议）
cd <your-project>
bash <skill-path>/.src/scripts/run-doctor.sh --strict

git pull --ff-only 适用于常规更新。如果远程分支被强制推送（例如在压缩提交后重新发布），ff-only 将失败，此时需执行 fetch + reset 来将本地同步到最新的远程状态。这是安全的操作——技能目录仅包含受版本控制的系统文件；用户数据位于 <project>/.pensieve/，不会被覆盖。

完整的安装、更新、重新安装和卸载说明：skill-lifecycle.md。

如果您之前的 Pensieve 是在项目级别安装的（代码位于 <project>/.claude/skills/pensieve/），或者通过 claude plugin install 安装的，您需要迁移到 v2 架构：

# 1. 全局安装系统代码（如果尚未安装）
if [[ ! -d <skill-path> ]]; then
    git clone -b main https://github.com/kingkongshot/Pensieve.git <skill-path>
fi

# 2. 安装钩子（仅限 Claude Code；其他客户端可跳过）
# bash <skill-path>/.src/scripts/install-hooks.sh

# 3. 在每个项目中运行迁移
cd <your-project>
bash <skill-path>/.src/scripts/init-project-data.sh
bash <skill-path>/.src/scripts/run-migrate.sh
bash <skill-path>/.src/scripts/run-doctor.sh --strict

# 4. 卸载旧插件（如适用，仅限 Claude Code）
# claude plugin uninstall pensieve 2>/dev/null || true

run-migrate.sh 会自动将用户数据（maxims/、decisions/、knowledge/、pipelines/）从旧路径移动到 <project>/.pensieve/，运行时状态从 <project>/.state/ 移动到 <project>/.pensieve/.state/，清理旧图文件和 README 副本，然后删除旧目录。

目录结构

~/.claude/skills/pensieve/          # 用户级别（单次全局安装）
├── SKILL.md                        #   静态路由文件（受版本控制）
├── .src/                           #   系统代码、模板、参考文档、核心引擎
│   ├── core/
│   ├── scripts/
│   ├── templates/
│   ├── references/
│   └── tools/
└── agents/                         #   代理配置

<project>/.pensieve/                # 项目级别（每个项目独立，可版本控制）
├── maxims/                         #   工程原则
├── decisions/                      #   架构决策
├── knowledge/                      #   缓存的探索结果
├── pipelines/                      #   可重用的工作流
├── state.md                        #   动态：生命周期状态 + 知识图
└── .state/                         #   运行时产物（被 .gitignore 忽略）

.src/manifest.json 是技能根目录的锚点——脚本通过它来定位所有路径。

设计原则

• 系统代码与用户数据物理隔离 —— 系统代码位于 ~/.claude/skills/pensieve/，用户数据位于 <project>/.pensieve/；通过 git pull 更新系统代码绝不会触及项目数据。
• 规则的单一可信来源 —— 目录、关键文件和迁移路径均在 .src/core/schema.json 中定义。
• 执行前确认 —— 当范围不明确时，先询问再行动；不要自动启动长时间运行的工作流。
• 读取规范再写入数据 —— 在创建任何用户数据之前，务必阅读 .src/references/ 中的格式规范。