⚡

Navigator初始化 nav-init

创建新项目中的 Navigator 文档结构，复制模板，并设置初始配置，以便于项目文档管理和监控。

DevOps 0 次安装 0 次浏览 更新于 3/4/2026

Navigator 初始化技能

目的

在新项目中创建 Navigator 文档结构（.agent/），复制模板，并设置初始配置。

何时自动调用此技能

  • “在此项目中初始化 Navigator”
  • “设置 Navigator 文档结构”
  • “为 Navigator 创建 .agent 文件夹”
  • “为我的项目启动 Navigator”

此技能的作用

  1. 检查是否已初始化：防止覆盖现有结构
  2. 创建 .agent/ 目录结构：
    .agent/
├── DEVELOPMENT-README.md
├── .nav-config.json
├── tasks/
├── system/
├── sops/
│   ├── integrations/
│   ├── debugging/
│   ├── development/
│   └── deployment/
└── grafana/
    ├── docker-compose.yml
    ├── prometheus.yml
    ├── grafana-datasource.yml
    ├── grafana-dashboards.yml
    ├── navigator-dashboard.json
    └── README.md
  3. 创建 .claude/ 目录与钩子：
    .claude/
└── settings.json    # 令牌监控钩子配置
  4. 复制模板：DEVELOPMENT-README.md，配置，Grafana 设置
  5. 自动检测项目信息：名称，技术栈（如果可用，从 package.json）
  6. 更新 CLAUDE.md：添加 Navigator 特定指令到项目
  7. 创建 .gitignore 条目：排除临时 Navigator 文件

执行步骤

1. 检查是否已初始化

if [ -d ".agent" ]; then
    echo "✅ Navigator 已在此项目中初始化"
    echo ""
    echo "要开始会话：'开始我的 Navigator 会话'"
    echo "要查看文档：阅读 .agent/DEVELOPMENT-README.md"
    exit 0
fi

2. 检测项目信息

读取 package.json，pyproject.toml，go.mod，Cargo.toml 或类似文件以提取：

  • 项目名称
  • 技术栈
  • 依赖项

回退：如果没有找到配置，则使用当前目录名称。

3. 创建目录结构

使用 Write 工具创建：

.agent/
.agent/tasks/
.agent/system/
.agent/sops/integrations/
.agent/sops/debugging/
.agent/sops/development/
.agent/sops/deployment/
.agent/grafana/

4. 复制模板

从插件的 templates/ 目录复制到 .agent/：

DEVELOPMENT-README.md：

  • 将 ${PROJECT_NAME} 替换为检测到的项目名称
  • 将 ${TECH_STACK} 替换为检测到的栈
  • 将 ${DATE} 替换为当前日期

.nav-config.json：

{
  "version": "5.5.0",
  "project_name": "${PROJECT_NAME}",
  "tech_stack": "${TECH_STACK}",
  "project_management": "none",
  "task_prefix": "TASK",
  "team_chat": "none",
  "auto_load_navigator": true,
  "compact_strategy": "conservative",
  "auto_update": {
    "enabled": true,
    "check_interval_hours": 1
  }
}

Grafana 设置： 复制所有 Grafana 仪表板文件以启用指标可视化：

# 查找插件安装目录
PLUGIN_DIR="${HOME}/.claude/plugins/marketplaces/jitd-marketplace"

# 如果插件有 Grafana 文件，则复制 Grafana 文件
if [ -d "${PLUGIN_DIR}/.agent/grafana" ]; then
  cp -r "${PLUGIN_DIR}/.agent/grafana/"* .agent/grafana/
  echo "✓ Grafana 仪表板已安装"
else
  echo "⚠️ 插件中未找到 Grafana 文件"
fi

复制的文件：

  • docker-compose.yml（Grafana + Prometheus 堆栈）
  • prometheus.yml（Claude Code 指标的抓取配置）
  • grafana-datasource.yml（Prometheus 数据源配置）
  • grafana-dashboards.yml（仪表板提供者配置）
  • navigator-dashboard.json（10 面板 Navigator 指标仪表板）
  • README.md（设置说明）

5. 更新项目 CLAUDE.md

如果存在 CLAUDE.md：

  • 追加 Navigator 特定部分
  • 保留现有项目定制

如果 CLAUDE.md 不存在：

  • 将 templates/CLAUDE.md 复制到项目根目录
  • 使用项目信息进行定制

6. 设置令牌监控钩子

创建 .claude/settings.json 用于令牌预算监控：

mkdir -p .claude

cat > .claude/settings.json << 'EOF'
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|Bash|Task",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"${CLAUDE_PLUGIN_DIR}/hooks/monitor-tokens.py\"",
            "timeout": 5
          }
        ]
      }
    ]
  }
}
EOF

echo "✓ 令牌监控钩子已配置"

这的作用：

  • 在每次工具调用后监控上下文使用情况
  • 在使用量达到 70% 时警告，85% 时发出严重警报
  • 当接近限制时建议使用 /nav:compact

7. 创建 .gitignore 条目

如果尚未出现，则添加到 .gitignore：

# Navigator 上下文标记
.context-markers/

# Navigator 临时文件
.agent/.nav-temp/

8. 成功消息

✅ Navigator 初始化成功！

创建的结构：
  📁 .agent/                    Navigator 文档
  📁 .agent/tasks/              实现计划
  📁 .agent/system/             架构文档
  📁 .agent/sops/               标准程序
  📁 .agent/grafana/            指标仪表板
  📄 .agent/.nav-config.json    配置
  📁 .claude/                   Claude Code 钩子
  📄 .claude/settings.json      令牌监控配置
  📄 CLAUDE.md                  更新为 Navigator 工作流

后续步骤：
  1. 开始会话："开始我的 Navigator 会话"
  2. 可选：启用指标 - 见 .agent/sops/integrations/opentelemetry-setup.md
  3. 可选：启动 Grafana - cd .agent/grafana && docker compose up -d

令牌监控已激活 - 当接近上下文限制时您将收到警告。

文档：阅读 .agent/DEVELOPMENT-README.md

错误处理

如果 .agent/ 存在：

  • 不要覆盖
  • 显示消息：“已初始化”

如果模板未找到：

  • 错误：“Navigator 插件模板缺失。请重新安装插件。”

如果没有写权限：

  • 错误：“无法创建 .agent/ 目录。检查权限。”

预定义函数

project_detector.py

def detect_project_info(cwd: str) -> dict:
    """
    从配置文件中检测项目名称和技术栈。

    检查顺序：
    1. package.json (Node.js)
    2. pyproject.toml (Python)
    3. go.mod (Go)
    4. Cargo.toml (Rust)
    5. composer.json (PHP)
    6. Gemfile (Ruby)

    返回：
        {
            "name": "project-name",
            "tech_stack": "Next.js, TypeScript, Prisma",
            "detected_from": "package.json"
        }
    """

template_customizer.py

def customize_template(template_content: str, project_info: dict) -> str:
    """
    用项目特定的值替换模板中的占位符。

    占位符：
    - ${PROJECT_NAME}
    - ${TECH_STACK}
    - ${DATE}
    - ${YEAR}

    返回定制化的模板内容。
    """

示例

示例 1：新的 Next.js 项目

用户说：“在此项目中初始化 Navigator”

技能检测：

  • 存在 package.json
  • 名称：“my-saas-app”
  • 依赖项：next, typescript, prisma

结果：

示例 2：Python 项目

用户说：“设置 Navigator”

技能检测：

  • 存在 pyproject.toml
  • 名称：“ml-pipeline”
  • 依赖项：fastapi, pydantic, sqlalchemy

结果：

  • 创建了 .agent/
  • 技术栈：“FastAPI, Pydantic, SQLAlchemy”

示例 3：已初始化

用户说：“初始化 Navigator”

技能检查：

  • .agent/ 目录存在

结果：

✅ Navigator 已在此项目中初始化

要开始会话：'开始我的 Navigator 会话'

与其他技能的集成

nav-start 技能：

  • 检查 .agent/DEVELOPMENT-README.md
  • 如果缺失，建议：“首先初始化 Navigator”

nav-task 技能：

  • 在 .agent/tasks/ 中创建任务
  • 需要初始化

nav-sop 技能：

  • 在 .agent/sops/ 中创建 SOP
  • 需要初始化

版本历史

  • 1.0.0 (2025-01-20)：初始实现
    • 自动检测项目信息
    • 模板定制
    • 包括 Grafana 设置
    • 现有安装的错误处理

注释

  • 此技能替换了 v2.x 中已删除的 /nav:init 命令
  • 模板从插件安装目录复制
  • 项目信息检测是尽力而为的（如果失败则回退到目录名称）
  • 可以安全地多次运行（不会覆盖现有结构）