yp-agent

一个基于 Anthropic Claude Code 的项目分析代理。它在本地以“读取/检索/写入”权限扫描你的代码库，输出问题清单、影响分析与可执行建议，并在仓库根目录生成形如 <包名>项目优化点分析报告.md 的完整报告

特性

• 自动扫描：遍历代码与配置，定位性能、可维护性、安全与 DX 问题
• 可执行建议：问题描述、影响评估、改进步骤与示例代码一应俱全
• 流式执行：控制台显示进度与耗时统计，结束后打印摘要
• 灵活鉴权：直连 Anthropic 或通过代理解密鉴权信息
• 范围控制：通过 include/exclude glob 规则精确指定分析范围
• 飞书同步：将分析报告自动创建并更新到飞书知识库文档

安装

• 全局安装：

npm i -g yp-agent   # 或 pnpm add -g yp-agent / yarn global add yp-agent

• 临时执行：

npx yp-agent

快速开始

在需要分析的项目根目录执行：

ypa

完成后将在当前目录生成（或覆盖）以项目名命名的 项目优化点分析报告.md 报告文件，同时在控制台打印摘要与用时统计。

CLI 选项

• -t, --auth-token <token>：Anthropic 鉴权令牌（设置后将跳过代理）
• -u, --base-url <url>：Anthropic API 基础地址（默认使用内置的代理中转地址）
• -p, --auth-proxy <url>：鉴权代理地址（返回加密密钥，需解密）
• --auth-proxy-secret-key <key>：解密代理响应的密钥（支持 Base64/Hex/32 字节 UTF-8）
• --dir <dir>：指定分析目录（默认当前工作目录）
• --include <pattern>：仅分析匹配 glob 模式的路径（可多次使用）
• --exclude <pattern>：排除匹配 glob 模式的路径（可多次使用）
• --verbose：显示详细的 Claude Code 流式输出日志
• --app-id <id>：飞书应用 ID，用于自动同步报告
• --app-secret <secret>：飞书应用密钥，用于自动同步报告

示例：

# 直接使用令牌
ypa -t "$ANTHROPIC_AUTH_TOKEN"

# 通过代理获取令牌（推荐在 CI 中使用环境变量）
YPA_AUTH_PROXY_SECRET_KEY=base64-or-hex-key \
ypa -p https://api.yourdomain.com

# 指定分析目录
ypa --dir ./packages/app

配置

支持以下任一配置来源（后者覆盖前者；CLI 选项优先级最高）：

1. ypa.config.(js|ts|mjs|cjs|json)：

   // ypa.config.ts
   import { defineConfig } from 'yp-agent'
   export default defineConfig({
     // 任选其一：直连 or 代理
     // authToken: 'YOUR_ANTHROPIC_API_KEY',
     authProxy: 'https://api.yourdomain.com',
     authProxySecretKey: 'base64-or-hex-or-32bytes',
     // 可选：覆盖基础地址
     // baseUrl: 'https://api.anthropic.com',
     // 可选：指定要分析的目录
     // dir: '.',
     // 可选：控制分析范围
     // include: ['src/**/*.ts'],
     // exclude: ['**/*.spec.ts'],
     // 可选：打印详细日志
     // verbose: true,
     // 可选：飞书集成
     // appId: 'cli_xxxxxxxx',
     // appSecret: 'xxxxxxxx',
   })

2. package.json：

   {
     "ypa": {
      "authProxy": "https://api.yourdomain.com",
       "authProxySecretKey": "base64-or-hex-or-32bytes"
     }
   }

3. .yparc（JSON）：

   {
     "authToken": "YOUR_ANTHROPIC_API_KEY",
     "dir": "."
   }

环境变量

• ANTHROPIC_AUTH_TOKEN：直连模式下的鉴权令牌
• ANTHROPIC_BASE_URL：自定义 API 基础地址
• YPA_AUTH_PROXY_SECRET_KEY：代理模式下用于解密的密钥（可替代 --auth-proxy-secret-key）

运行时会根据最终配置为进程设置 ANTHROPIC_AUTH_TOKEN 与 ANTHROPIC_BASE_URL。

编程接口（API）

import { analyse, defineConfig } from 'yp-agent'

// 直接调用
await analyse({ authToken: 'xxx', baseUrl: 'https://api.anthropic.com', dir: process.cwd() })

// 配置文件辅助（仅做类型与直传）
export default defineConfig({ authToken: 'xxx' })

工作原理（简述）

• CLI 解析参数并合并配置（ypa.config.*/package.json/.yparc/CLI）
• 选择鉴权方式：
  • 直连：使用 authToken
  • 代理：向 authProxy 请求密文，使用 authProxySecretKey 解密得到令牌
• 使用 Claude Code 的工具能力在指定目录执行只读扫描，并要求代理将完整报告写入动态命名的 项目优化点分析报告.md
• 控制台输出摘要、用时、token 用量（若可用）
• （可选）若配置飞书凭证，将报告同步至云文档

常见问题（FAQ）

• 无网络或代理不可达时 CLI 退出码为 1。
  • 解决：提供 --auth-token 直连，或在联网环境下配置 --auth-proxy 与 YPA_AUTH_PROXY_SECRET_KEY。
• 报告未生成？
  • 检查仓库根目录是否有写权限；确保运行目录与 --dir 指向的目录一致。

许可协议

MIT © iridescent